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 ffea2324a675cd26a082057ff663271068c16d38..ece0819843587fce778adee2040e4bccaad655d8 100644 (file)
--- a/Doc/library/binascii.rst
+++ b/Doc/library/binascii.rst
@@ -113,8 +113,25 @@ The :mod:`binascii` module defines the following functions:
       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)

diff --git a/Doc/library/zlib.rst b/Doc/library/zlib.rst
index 6ce4e661c1632a4ad8c8053f792944c4628102aa..ca55a5f19e26a3c972369cdbfab210c3b3faeadb 100644 (file)
--- a/Doc/library/zlib.rst
+++ b/Doc/library/zlib.rst
@@ -31,22 +31,34 @@ The available exception and functions in this module are:
    Exception raised on compression and decompression errors.
 
 
-.. function:: adler32(string[, value])
+.. function:: adler32(data[, value])
 
-   Computes a Adler-32 checksum of *string*.  (An Adler-32 checksum is almost as
+   Computes a Adler-32 checksum of *data*.  (An Adler-32 checksum is almost as
    reliable as a CRC32 but can be computed much more quickly.)  If *value* is
    present, it is used as the starting value of the checksum; otherwise, a fixed
    default value is used.  This allows computing a running checksum over the
-   concatenation of several input strings.  The algorithm is not cryptographically
+   concatenation of several inputs.  The algorithm is not cryptographically
    strong, and should not be used for authentication or digital signatures.  Since
    the algorithm is designed for use as a checksum algorithm, it is not suitable
    for use as a general hash algorithm.
 
    This function always returns an integer object.
 
-   .. versionchanged:: 2.6
-     For consistent cross-platform behavior we always return a signed integer.
-     ie: Results in the (2**31)...(2**32-1) range will be negative.
+.. note::
+   To generate the same numeric value across all Python versions and
+   platforms use adler32(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 older versions the value would be
+   signed on some platforms and unsigned on others.
+
+.. versionchanged:: 3.0
+   The return value will always be unsigned and in the range [0, 2**32-1]
+   regardless of platform.
 
 
 .. function:: compress(string[, level])
@@ -66,25 +78,37 @@ The available exception and functions in this module are:
    ``9`` is slowest and produces the most.  The default value is ``6``.
 
 
-.. function:: crc32(string[, value])
+.. function:: crc32(data[, value])
 
    .. index::
       single: Cyclic Redundancy Check
       single: checksum; Cyclic Redundancy Check
 
-   Computes a CRC (Cyclic Redundancy Check)  checksum of *string*. If *value* is
+   Computes a CRC (Cyclic Redundancy Check)  checksum of *data*. If *value* is
    present, it is used as the starting value of the checksum; otherwise, a fixed
    default value is used.  This allows computing a running checksum over the
-   concatenation of several input strings.  The algorithm is not cryptographically
+   concatenation of several inputs.  The algorithm is not cryptographically
    strong, and should not be used for authentication or digital signatures.  Since
    the algorithm is designed for use as a checksum algorithm, it is not suitable
    for use as a general hash algorithm.
 
    This function always returns an integer object.
 
-   .. versionchanged:: 2.6
-     For consistent cross-platform behavior we always return a signed integer.
-     ie: Results in the (2**31)...(2**32-1) range will be negative.
+.. 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 older versions the value would be
+   signed on some platforms and unsigned on others.
+
+.. versionchanged:: 3.0
+   The return value will always be unsigned and in the range [0, 2**32-1]
+   regardless of platform.
 
 
 .. function:: decompress(string[, wbits[, bufsize]])