bpo-47040: improve document of checksum functions (pythongh-31955)

Clarifies a versionchanged note on crc32 & adler32 docs that the workaround is only needed for Python 2 and earlier. Also cleans up an unnecessary intermediate variable in the implementation. Authored-By: Ma Lin / animalize Co-authored-by: Gregory P. Smith <[email protected]>
hello-adam · Mar 19, 2022 · b3f2d4c · b3f2d4c
1 parent 82e9b0b
commit b3f2d4c
Show file tree

Hide file tree

Showing 4 changed files with 14 additions and 17 deletions.
diff --git a/Doc/library/binascii.rst b/Doc/library/binascii.rst
@@ -107,7 +107,7 @@ The :mod:`binascii` module defines the following functions:
 
 .. function:: crc32(data[, value])
 
-   Compute CRC-32, the 32-bit checksum of *data*, starting with an
+   Compute CRC-32, the unsigned 32-bit checksum of *data*, starting with an
    initial CRC of *value*.  The default initial CRC 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
@@ -121,9 +121,8 @@ The :mod:`binascii` module defines the following functions:
 
    .. versionchanged:: 3.0
       The result is always unsigned.
-      To generate the same numeric value across all Python versions and
-      platforms, use ``crc32(data) & 0xffffffff``.
-
+      To generate the same numeric value when using Python 2 or earlier,
+      use ``crc32(data) & 0xffffffff``.
 
 .. function:: b2a_hex(data[, sep[, bytes_per_sep=1]])
               hexlify(data[, sep[, bytes_per_sep=1]])

diff --git a/Doc/library/zlib.rst b/Doc/library/zlib.rst
@@ -42,10 +42,9 @@ The available exception and functions in this module are:
    for use as a general hash algorithm.
 
    .. versionchanged:: 3.0
-      Always returns an unsigned value.
-      To generate the same numeric value across all Python versions and
-      platforms, use ``adler32(data) & 0xffffffff``.
-
+      The result is always unsigned.
+      To generate the same numeric value when using Python 2 or earlier,
+      use ``adler32(data) & 0xffffffff``.
 
 .. function:: compress(data, /, level=-1, wbits=MAX_WBITS)
 
@@ -137,10 +136,9 @@ The available exception and functions in this module are:
    for use as a general hash algorithm.
 
    .. versionchanged:: 3.0
-      Always returns an unsigned value.
-      To generate the same numeric value across all Python versions and
-      platforms, use ``crc32(data) & 0xffffffff``.
-
+      The result is always unsigned.
+      To generate the same numeric value when using Python 2 or earlier,
+      use ``crc32(data) & 0xffffffff``.
 
 .. function:: decompress(data, /, wbits=MAX_WBITS, bufsize=DEF_BUF_SIZE)
 

diff --git a/Misc/NEWS.d/next/Documentation/2022-03-17-13-35-28.bpo-47040.4Dn48U.rst b/Misc/NEWS.d/next/Documentation/2022-03-17-13-35-28.bpo-47040.4Dn48U.rst
@@ -0,0 +1,2 @@
+Clarified the old Python versions compatiblity note of :func:`binascii.crc32` /
+:func:`zlib.adler32` / :func:`zlib.crc32` functions.
diff --git a/Modules/zlibmodule.c b/Modules/zlibmodule.c
@@ -1436,8 +1436,6 @@ static PyObject *
 zlib_crc32_impl(PyObject *module, Py_buffer *data, unsigned int value)
 /*[clinic end generated code: output=63499fa20af7ea25 input=26c3ed430fa00b4c]*/
 {
-    int signed_val;
-
     /* Releasing the GIL for very small buffers is inefficient
        and may lower performance */
     if (data->len > 1024*5) {
@@ -1452,12 +1450,12 @@ zlib_crc32_impl(PyObject *module, Py_buffer *data, unsigned int value)
             buf += (size_t) UINT_MAX;
             len -= (size_t) UINT_MAX;
         }
-        signed_val = crc32(value, buf, (unsigned int)len);
+        value = crc32(value, buf, (unsigned int)len);
         Py_END_ALLOW_THREADS
     } else {
-        signed_val = crc32(value, data->buf, (unsigned int)data->len);
+        value = crc32(value, data->buf, (unsigned int)data->len);
     }
-    return PyLong_FromUnsignedLong(signed_val & 0xffffffffU);
+    return PyLong_FromUnsignedLong(value & 0xffffffffU);
 }