[Python-checkins] bpo-47040: improve document of checksum functions (gh-31955)
gpshead
webhook-mailer at python.org
Sat Mar 19 17:42:23 EDT 2022
https://github.com/python/cpython/commit/b3f2d4c8bab52573605c96c809a1e2162eee9d7e
commit: b3f2d4c8bab52573605c96c809a1e2162eee9d7e
branch: main
author: Ma Lin <animalize at users.noreply.github.com>
committer: gpshead <greg at krypto.org>
date: 2022-03-19T14:42:04-07:00
summary:
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 <greg at krypto.org>
files:
A Misc/NEWS.d/next/Documentation/2022-03-17-13-35-28.bpo-47040.4Dn48U.rst
M Doc/library/binascii.rst
M Doc/library/zlib.rst
M Modules/zlibmodule.c
diff --git a/Doc/library/binascii.rst b/Doc/library/binascii.rst
index 62d7efe34ab36..19efc2df9483d 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 793c90f3c4e7a..f0c67d5ae2584 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 0000000000000..e977fb5f59fbc
--- /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 f9646568d7e01..4cf1b6eeba2f7 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);
}
More information about the Python-checkins
mailing list