From 7d50d3e17e43487de2ed18d16aacecd8556a71e4 Mon Sep 17 00:00:00 2001 From: Ma Lin Date: Sun, 20 Mar 2022 05:42:04 +0800 Subject: [PATCH 1/3] 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 ++++++-------- .../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 2c0c1bce5d7f8f..5cd058c0b6d74f 100644 --- a/Doc/library/binascii.rst +++ b/Doc/library/binascii.rst @@ -135,7 +135,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 @@ -149,9 +149,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 ec60ea24db6627..6758c615d74db8 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) @@ -127,10 +126,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 00000000000000..e977fb5f59fbc9 --- /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 a6940f2fd43a3f..6c1ce9632d8dea 100644 --- a/Modules/zlibmodule.c +++ b/Modules/zlibmodule.c @@ -1433,8 +1433,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) { @@ -1449,12 +1447,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); } From 11fa8dcc408d34b5663ca547ba5eafee2f646cfc Mon Sep 17 00:00:00 2001 From: Ma Lin Date: Sun, 20 Mar 2022 12:32:53 +0800 Subject: [PATCH 2/3] remove code polish --- Modules/zlibmodule.c | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/Modules/zlibmodule.c b/Modules/zlibmodule.c index 6c1ce9632d8dea..a6940f2fd43a3f 100644 --- a/Modules/zlibmodule.c +++ b/Modules/zlibmodule.c @@ -1433,6 +1433,8 @@ 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) { @@ -1447,12 +1449,12 @@ zlib_crc32_impl(PyObject *module, Py_buffer *data, unsigned int value) buf += (size_t) UINT_MAX; len -= (size_t) UINT_MAX; } - value = crc32(value, buf, (unsigned int)len); + signed_val = crc32(value, buf, (unsigned int)len); Py_END_ALLOW_THREADS } else { - value = crc32(value, data->buf, (unsigned int)data->len); + signed_val = crc32(value, data->buf, (unsigned int)data->len); } - return PyLong_FromUnsignedLong(value & 0xffffffffU); + return PyLong_FromUnsignedLong(signed_val & 0xffffffffU); } From 07dd5ce6720a341a12d9a46cf70a7b68a1865efe Mon Sep 17 00:00:00 2001 From: "Gregory P. Smith" Date: Sat, 19 Mar 2022 23:33:22 -0700 Subject: [PATCH 3/3] no need for a news entry for minor documentation updates. --- .../next/Documentation/2022-03-17-13-35-28.bpo-47040.4Dn48U.rst | 2 -- 1 file changed, 2 deletions(-) delete mode 100644 Misc/NEWS.d/next/Documentation/2022-03-17-13-35-28.bpo-47040.4Dn48U.rst 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 deleted file mode 100644 index e977fb5f59fbc9..00000000000000 --- a/Misc/NEWS.d/next/Documentation/2022-03-17-13-35-28.bpo-47040.4Dn48U.rst +++ /dev/null @@ -1,2 +0,0 @@ -Clarified the old Python versions compatiblity note of :func:`binascii.crc32` / -:func:`zlib.adler32` / :func:`zlib.crc32` functions.