Update the documentation for binascii and zlib crc32/adler32 functions
to better describe the signed vs unsigned return value behavior on
different platforms and versions of python. Mention the workaround to
make them all return the same thing by using & 0xffffffff.
Fixes issue4903.
Also needs to be merged into release26-maint, release30-maint, & py3k.
diff --git a/Doc/library/binascii.rst b/Doc/library/binascii.rst
index ffea232..ece0819 100644
--- a/Doc/library/binascii.rst
+++ b/Doc/library/binascii.rst
@@ -113,8 +113,25 @@
print binascii.crc32("hello world")
# Or, in two pieces:
crc = binascii.crc32("hello")
- crc = binascii.crc32(" world", crc)
- print crc
+ crc = binascii.crc32(" world", crc) & 0xffffffff
+ print 'crc32 = 0x%08x' % crc
+
+.. note::
+ To generate the same numeric value across all Python versions and
+ platforms use crc32(data) & 0xffffffff. If you are only using
+ the checksum in packed binary format this is not necessary as the
+ return value will have the correct 32bit binary representation
+ regardless of sign.
+
+.. versionchanged:: 2.6
+ The return value will always be in the range [-2**31, 2**31-1]
+ regardless of platform. In the past the value would be signed on
+ some platforms and unsigned on others. Use & 0xffffffff on the
+ value if you want it to match 3.0 behavior.
+
+.. versionchanged:: 3.0
+ The return value will always be unsigned and in the range [0, 2**32-1]
+ regardless of platform.
.. function:: b2a_hex(data)