[docs] Python 3 crc32 documentation clarifications (issue 22341)

[vadmium+py at gmail.com]

Reviewers: storchaka,


https://bugs.python.org/review/22341/diff/13462/Doc/library/binascii.rst
File Doc/library/binascii.rst (right):

https://bugs.python.org/review/22341/diff/13462/Doc/library/binascii.rst#newcode125
Doc/library/binascii.rst:125: the given *crc*.  The default initial
value is zero.  The algorithm
On 2015/02/28 13:02:25, storchaka wrote:
> May be just write the signature as crc32(data, crc=0) and drop the
sentence
> about the default value?

I hesitate to do this because all these functions do not accept keyword
arguments, and writing crc32(.., crc=0) implies (at least to me) that it
may be a keyword argument. The square brackets imply positional-only
parameters in my mind. Is there any style guide or precedence on how to
do this better (e.g. devguide)? I couldn’t find anything obvious.



Please review this at https://bugs.python.org/review/22341/

Affected files:
  Doc/library/binascii.rst
  Doc/library/zlib.rst


# HG changeset patch
# Parent 3de678cd184d943f53e9bc0e74feefaa07cc7f55
Issue #22341: Drop Python 2 workaround and document CRC initial value


diff -r 3de678cd184d -r 8a48ec8372c2 Doc/library/binascii.rst
--- a/Doc/library/binascii.rst	Thu Dec 18 23:47:55 2014 +0100
+++ b/Doc/library/binascii.rst	Fri Dec 19 05:02:33 2014 +0000
@@ -121,24 +121,18 @@
 
 .. function:: crc32(data[, crc])
 
-   Compute CRC-32, the 32-bit checksum of data, starting with an initial crc.  This
+   Compute CRC-32, the 32-bit checksum of *data*, starting with
+   the given *crc*.  The default initial value is zero.  The algorithm
    is consistent with the ZIP file checksum.  Since the algorithm is designed for
    use as a checksum algorithm, it is not suitable for use as a general hash
    algorithm.  Use as follows::
 
       print(binascii.crc32(b"hello world"))
       # Or, in two pieces:
-      crc = binascii.crc32(b"hello")
-      crc = binascii.crc32(b" world", crc) & 0xffffffff
+      crc = binascii.crc32(b"hello", 0)
+      crc = binascii.crc32(b" world", crc)
       print('crc32 = {:#010x}'.format(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 is the correct 32bit binary representation
-   regardless of sign.
-
 
 .. function:: b2a_hex(data)
               hexlify(data)
diff -r 3de678cd184d -r 8a48ec8372c2 Doc/library/zlib.rst
--- a/Doc/library/zlib.rst	Thu Dec 18 23:47:55 2014 +0100
+++ b/Doc/library/zlib.rst	Fri Dec 19 05:02:33 2014 +0000
@@ -30,10 +30,11 @@
 
 .. function:: adler32(data[, value])
 
-   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
+   Computes an 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 default value of 1 is used.
+   This allows computing a running checksum over the
    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
@@ -41,13 +42,6 @@
 
    Always returns an unsigned 32-bit integer.
 
-.. 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 is the correct 32bit binary representation
-   regardless of sign.
-
 
 .. function:: compress(data[, level])
 
@@ -98,8 +92,9 @@
       single: checksum; Cyclic Redundancy Check
 
    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
+   present, it is used as the starting value of the checksum; otherwise, a
+   default value of zero is used.
+   This allows computing a running checksum over the
    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
@@ -107,14 +102,6 @@
 
    Always returns an unsigned 32-bit integer.
 
-   .. 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 is the correct 32-bit binary representation
-      regardless of sign.
-
 
 .. function:: decompress(data[, wbits[, bufsize]])