classification
Title: struct module : processor endianness descriptions misleading
Type: Stage:
Components: Documentation Versions: Python 2.4, Python 3.1, Python 3.2, Python 2.7, Python 2.6
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: akuchling Nosy List: Asheesh.Laroia, akuchling, ash, ezio.melotti, georg.brandl, kmag, mark.dickinson, rhettinger
Priority: low Keywords: easy, patch

Created on 2009-07-04 07:46 by kmag, last changed 2010-02-22 15:17 by akuchling. This issue is now closed.

Files
File name Uploaded Description Edit
issue6414-trunk.patch Asheesh.Laroia, 2010-02-21 03:53 Patch against trunk; using Alexey Shamrin's exact wording
issue6414-py3k.patch Asheesh.Laroia, 2010-02-21 04:00 Patch against py3k; using Alexey Shamrin's exact wording
Messages (8)
msg90107 - (view) Author: Karl Magdsick (kmag) Date: 2009-07-04 07:46
In http://docs.python.org/dev/library/struct.html,

it says
"Native byte order is big-endian or little-endian, depending on the host 
system. For example, Motorola and Sun processors are big-endian; Intel 
and DEC processors are little-endian."

This is a gross over-generalization at best.  Off the top of my head, 
current Linux kernels run the Intel Itanium in big-endian mode. (Though, 
I don't recall if there's a non-privileged instruction to flip 
endianness, system headers and system calls are defined in big-endian 
order, which is what's most relevant to the struct module.)  Sun SPARC 
v9 is bi-endian. Intel Itanium and XScale processors are bi-endian.  Dec 
Alphas are bi-endian.  (Though, I'm only aware of Cray using Alphas in 
big-endian mode.)

The quoted paragraph should name specific processors which are single-
endian (Intel Core 2, Sun SPARC v8) and/or provide a Wikipedia 
reference, rather than making incorrect statements.

Intel Itanium machines running Linux are probably the most common 
systems where this statement's inaccuracy is likely to cause confusion 
among developers.
msg90224 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2009-07-07 09:52
Something like "Motorola and Sun processors are usually big-endian;
Intel and DEC processors are usually little-endian" (or "most
of"/"several") might be enough.
msg90230 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2009-07-07 11:56
Maybe it's better to avoid the platform-specific statements altogether, 
and just point out the existence of sys.byteorder for those who want to 
check the endianness of the system they're currently working on.

Or maybe just mention that the x86 and AMD64 (aka x86-64) architectures 
are little-endian;  I'd guess that this covers a good proportion of the 
processors that people are currently running Python on.  People using more 
exotic architectures probably already know their endianness.
msg90326 - (view) Author: Alexey Shamrin (ash) Date: 2009-07-09 12:21
Good suggestions, Mark! We should do both, I think. I didn't know about
sys.byteorder before your message ;-) Thanks for education!

How about this:

"Native byte order is big-endian or little-endian, depending on the host 
system. For example, Intel x86 and AMD64 (x86-64) are little-endian;
Motorola 68000 and PowerPC G5 are big-endian; some are even bi-endian
(switchable endianess) - ARM and DEC Alpha. Use sys.byteorder to check
the endianess of your system."

Sorry for any spelling and styling mistakes...
msg90327 - (view) Author: Alexey Shamrin (ash) Date: 2009-07-09 12:24
Little style:

"Native byte order is big-endian or little-endian, depending on the host 
system. For example, Intel x86 and AMD64 (x86-64) are little-endian;
Motorola 68000 and PowerPC G5 are big-endian; ARM and DEC Alpha feature
switchable endianness (bi-endian). Use sys.byteorder to check the
endianess of your system."
msg99639 - (view) Author: Asheesh Laroia (Asheesh.Laroia) * Date: 2010-02-21 03:53
Hey all,

I (a person who just wandered by) think that Alexey Shamrin's suggested text is great.

For that reason, I have turned it into a unified diff created by 'svn diff'.

I hope that would help move this bug along!

I'm attaching that patch against trunk right now.
msg99640 - (view) Author: Asheesh Laroia (Asheesh.Laroia) * Date: 2010-02-21 04:00
I'm attaching (basically) the same patch, this time against the py3k branch.

I'm open to improvements to the text. If the text is okay, please just ship these!

Sincerely,

A dude sitting in an open space at PyCon.
msg99745 - (view) Author: A.M. Kuchling (akuchling) * (Python committer) Date: 2010-02-22 15:17
Committed to trunk as rev.78308, and to 3.x as rev. 78309.

Thanks to Alexey for the text, and Asheesh for making a patch!
History
Date User Action Args
2010-02-22 15:17:38akuchlingsetstatus: open -> closed
2010-02-22 15:17:28akuchlingsetresolution: fixed
messages: + msg99745
2010-02-22 15:16:20akuchlingsetassignee: rhettinger -> akuchling

nosy: + akuchling
2010-02-21 04:00:22Asheesh.Laroiasetfiles: + issue6414-py3k.patch

messages: + msg99640
2010-02-21 03:53:35Asheesh.Laroiasetfiles: + issue6414-trunk.patch

nosy: + Asheesh.Laroia
messages: + msg99639

keywords: + patch
2009-07-09 15:50:56rhettingersetassignee: georg.brandl -> rhettinger

nosy: + rhettinger
versions: + Python 3.2, - Python 2.5, Python 3.0
2009-07-09 12:24:20ashsetmessages: + msg90327
2009-07-09 12:21:41ashsetnosy: + ash
messages: + msg90326
2009-07-07 11:56:18mark.dickinsonsetnosy: + mark.dickinson
messages: + msg90230
2009-07-07 09:52:54ezio.melottisetpriority: low

nosy: + ezio.melotti
messages: + msg90224

keywords: + easy
2009-07-04 07:46:29kmagcreate