Martin Panter
2014-09-05 11:55:29 UTC
New submission from Martin Panter:
This is regarding the Python 3 documentation for binascii.crc32(), <https://docs.python.org/dev/library/binascii.html#binascii.crc32>. It repeatedly recommends correcting the sign by doing crc32() & 0xFFFFFFFF, but it is not immediately clear why. Only after reading the Python 2 documentation does one realise that the value is always unsigned for Python 3, so you only really need the workaround if you want to support earlier Pythons.
I also suggest documenting the initial CRC input value, which is zero. Suggested wording:
binascii.crc32(data[, crc])
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", 0)
crc = binascii.crc32(b" world", crc)
print('crc32 = {:#010x}'.format(crc))
I would simply drop the notice box with the workaround, because I gather that the Python 3 documentation generally omits Python 2 details. (There are no ?new in version 2.4 tags? for instance.) Otherwise, clarify if ?packed binary format? is a reference to the ?struct? module, or something else.
Similar fixes are probably appropriate for zlib.crc32() and zlib.alder32().
Also, what is the relationship between binascii.crc32() and zlib.crc32()? I vaguely remember reading that ?zlib? is not always available, so I tend to use ?binascii? instead. Is there any advantage in using the ?zlib? version? The ?hashlib? documentation points to ?zlib? without mentioning ?binascii? at all.
----------
assignee: docs at python
components: Documentation
messages: 226419
nosy: docs at python, vadmium
priority: normal
severity: normal
status: open
title: Python 3 crc32 documentation clarifications
versions: Python 3.4
_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue22341>
_______________________________________
This is regarding the Python 3 documentation for binascii.crc32(), <https://docs.python.org/dev/library/binascii.html#binascii.crc32>. It repeatedly recommends correcting the sign by doing crc32() & 0xFFFFFFFF, but it is not immediately clear why. Only after reading the Python 2 documentation does one realise that the value is always unsigned for Python 3, so you only really need the workaround if you want to support earlier Pythons.
I also suggest documenting the initial CRC input value, which is zero. Suggested wording:
binascii.crc32(data[, crc])
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", 0)
crc = binascii.crc32(b" world", crc)
print('crc32 = {:#010x}'.format(crc))
I would simply drop the notice box with the workaround, because I gather that the Python 3 documentation generally omits Python 2 details. (There are no ?new in version 2.4 tags? for instance.) Otherwise, clarify if ?packed binary format? is a reference to the ?struct? module, or something else.
Similar fixes are probably appropriate for zlib.crc32() and zlib.alder32().
Also, what is the relationship between binascii.crc32() and zlib.crc32()? I vaguely remember reading that ?zlib? is not always available, so I tend to use ?binascii? instead. Is there any advantage in using the ?zlib? version? The ?hashlib? documentation points to ?zlib? without mentioning ?binascii? at all.
----------
assignee: docs at python
components: Documentation
messages: 226419
nosy: docs at python, vadmium
priority: normal
severity: normal
status: open
title: Python 3 crc32 documentation clarifications
versions: Python 3.4
_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue22341>
_______________________________________