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@python
components: Documentation
messages: 226419
nosy: docs@python, vadmium
priority: normal
severity: normal
status: open
title: Python 3 crc32 documentation clarifications
versions: Python 3.4
_______________________________________
Python tracker <rep...@bugs.python.org>
<http://bugs.python.org/issue22341>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe:
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
