Python 3 crc32 documentation clarifications

[vadmium]

BPO	22341
Nosy	@gpshead, @vadmium, @serhiy-storchaka
Files	crc-sign.patch crc-sign.v2.patch crc-sign.v3.patch crc-sign.v4.patch crc-sign.v5.patch

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/vadmium'
closed_at = <Date 2015-12-11.06:07:02.737>
created_at = <Date 2014-09-05.11:55:29.367>
labels = ['docs']
title = 'Python 3 crc32 documentation clarifications'
updated_at = <Date 2015-12-11.06:07:02.736>
user = 'https://github.com/vadmium'

bugs.python.org fields:

activity = <Date 2015-12-11.06:07:02.736>
actor = 'martin.panter'
assignee = 'martin.panter'
closed = True
closed_date = <Date 2015-12-11.06:07:02.737>
closer = 'martin.panter'
components = ['Documentation']
creation = <Date 2014-09-05.11:55:29.367>
creator = 'martin.panter'
dependencies = []
files = ['37504', '38398', '38737', '38739', '41271']
hgrepos = []
issue_num = 22341
keywords = ['patch']
message_count = 15.0
messages = ['226419', '232927', '236881', '237589', '238715', '238716', '238723', '238735', '239599', '239602', '256107', '256138', '256140', '256198', '256200']
nosy_count = 5.0
nosy_names = ['gregory.p.smith', 'docs@python', 'python-dev', 'martin.panter', 'serhiy.storchaka']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue22341'
versions = ['Python 3.5', 'Python 3.6']

[vadmium]

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.

[vadmium]

Here is a patch that fixes the binascii, zlib.crc32() and adler32() documentation as I suggested.

I’m still interested why there are two ways to do a CRC-32, each equally non-obvious as the other.

[serhiy-storchaka]

crc & 0xffffffff is still used in gzip, zipfile and tarfile. And some comments say about signess of 32-bit checksums.

[vadmium]

Posting a new patch that also removes the masking from the gzip, zipfile, tarfile, and test_zlib modules. I removed the comment about signedness in tarfile; let me know if you saw any others.

[serhiy-storchaka]

These notes was added by Gregory in r68535. Ask him if they still are needed.

[serhiy-storchaka]

See also bpo-4903.

[gpshead]

I do not object to the removal of the & 0xfffffff from the stdlib library code if these functions have actually been fixed to always return unsigned now. (double check the behavior, and if good, just do it!)

But I think the docs should still mention that the & 0xffffffff is a good practice if code needs to be compatible with Python versions prior to X.Y (list the last release before the behavior was corrected). Possibly within a .. versionchanged: section.

People often use the latest docs when writing code in any version of Python as we continually improve docs and are pretty good about noting old behaviors and when behaviors changed.

[vadmium]

Hi Gregory, I think the three functions have been fixed since Python 3.0. It looks like you changed them in revisions 6a7fa8421902 (zlib module) and 132cf3a79126 (crc32 functions). Looking at the 3.0 branch, all three functions use PyLong_FromUnsignedLong(), but in the 2.7 branch, they use PyInt_FromLong(). This is tested in test_zlib.ChecksumTestCase.test_crc32_adler32_unsigned(). See also my changes to test_penguins() in the patch here for further testing. There is no explicit testing of binascii.crc32() unsignedness, but it is implicitly tested by test_same_as_binascii_crc32(), because the expected CRC is beyond the positive 32 bit signed limit.

I am happy to put back the suggestion of masking for backwards compatibility if you really think it is necessary. But since it only involves Python < 3.0 compatibility, I thought it would be okay to remove it; see my original post. The documentation is often pretty good about noting when Python 3 behaviours changed, but you usually have to look elsewhere to see the differences from Python 2.

[vadmium]

Patch v3:

• Reverted to original crc32(b"hello") example call with the implicit initial CRC
• Added “Changed in version 3.0” notices, restoring a brief version of the suggestion to use the bit mask, along with an explanation.

Python 2 compatibility information is generally unprecedented in the Python 3 documentation though, but hopefully this version should make more sense to people not already familiar with the Python 2 odd behaviour.

[vadmium]

V4 fixes a merge conflict with recent gzip changes.

[serhiy-storchaka]

The patch LGTM.

But while we are here, wouldn't be worth to unify the name of second parameter of binascii and zlib CRC calculation functions? And unify the description of crc_hqx() with other functions.

[vadmium]

In crc-sign.v5.patch I have changed the binascii.crc_hqx() and crc32() documentation to use “value”, matching the zlib documentation. Is that what you had in mind?

[serhiy-storchaka]

Yes, thank you Martin.