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 <report@bugs.python.org> <http://bugs.python.org/issue22341> _______________________________________