From b3f2d4c8bab52573605c96c809a1e2162eee9d7e Mon Sep 17 00:00:00 2001 From: Ma Lin Date: Sun, 20 Mar 2022 05:42:04 +0800 Subject: bpo-47040: improve document of checksum functions (gh-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 --- Doc/library/binascii.rst | 7 +++---- Doc/library/zlib.rst | 14 ++++++-------- .../Documentation/2022-03-17-13-35-28.bpo-47040.4Dn48U.rst | 2 ++ Modules/zlibmodule.c | 8 +++----- 4 files changed, 14 insertions(+), 17 deletions(-) create mode 100644 Misc/NEWS.d/next/Documentation/2022-03-17-13-35-28.bpo-47040.4Dn48U.rst diff --git a/Doc/library/binascii.rst b/Doc/library/binascii.rst index 62d7efe..19efc2d 100644 --- 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 index 793c90f..f0c67d5 100644 --- 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 new file mode 100644 index 0000000..e977fb5 --- /dev/null +++ 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 index f964656..4cf1b6e 100644 --- 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); } -- cgit v0.12