binhex documentation claims unknown bug

[df79d71a-01e4-4e4c-8e79-1911595e5e2c]

BPO	29557
Nosy	@birkenfeld, @rhettinger, @ronaldoussoren, @ned-deily, @berkerpeksag, @serhiy-storchaka, @Mariatta, @davidwilemski
PRs	python/cpython#90 python/cpython#474 python/cpython#475

^{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: ```python assignee = None closed_at = created_at = labels = ['OS-mac', 'type-bug', '3.7', 'docs'] title = 'binhex documentation claims unknown bug' updated_at = user = 'https://github.com/davidwilemski' ``` bugs.python.org fields: ```python activity = actor = 'serhiy.storchaka' assignee = 'docs@python' closed = True closed_date = closer = 'serhiy.storchaka' components = ['Documentation', 'macOS'] creation = creator = 'David Wilemski' dependencies = [] files = [] hgrepos = [] issue_num = 29557 keywords = [] message_count = 10.0 messages = ['287781', '287801', '287819', '287828', '287860', '287861', '287868', '289003', '290287', '290288'] nosy_count = 9.0 nosy_names = ['georg.brandl', 'rhettinger', 'ronaldoussoren', 'ned.deily', 'docs@python', 'berker.peksag', 'serhiy.storchaka', 'Mariatta', 'David Wilemski'] pr_nums = ['90', '474', '475'] priority = 'normal' resolution = 'fixed' stage = 'resolved' status = 'closed' superseder = None type = 'behavior' url = 'https://bugs.python.org/issue29557' versions = ['Python 3.5', 'Python 3.6', 'Python 3.7'] ```

[df79d71a-01e4-4e4c-8e79-1911595e5e2c]

The binhex documentation has a line in it that says "As of this writing, hexbin() appears to not work in all cases."

This is a bit ambiguous and there is no context for what the bug may be. It appears this line is from the first commit to the hexbin function's documentation in 1995 (https://hg.python.org/cpython/rev/3911d4a89ab0#l4.40) but the commit also has no information about what this bug may be. I also see no current open bugs for the binhex module that seem related.

In 2009, there was a patch for the hexbin function but I have no idea if this is the bug from the original documentation or if it was something else entirely: https://bugs.python.org/issue6369

Given this, I believe the line should be removed unless more details about the referenced buggy behavior can be found.

[berkerpeksag]

New changeset 6de2b7817fa9403e81dc38f13f3690f0bbf3d064 by Berker Peksag in branch 'master': bpo-29557: Remove ambiguous line in binhex docs (#90) https://github.com/python/cpython/commit/6de2b7817fa9403e81dc38f13f3690f0bbf3d064

[serhiy-storchaka]

I think this should be read in the context of previous lines:

If you code or decode textfiles on non-Macintosh platforms they will still use
the old Macintosh newline convention (carriage-return as end of line).

And may be related to the in-code comment:

# XXXX Do translation on non-mac systems

[rhettinger]

Georg, do remember why this admonition was present?

[ronaldoussoren]

I think the comment about needing translation on non-mac systems is incorrect. Binhex is (or rather was) a textual encoding for binary files used on classic MacOS. The encoded file is more likely to be binary data than a text file and replacing b'\r' by the line ending of the current platform could well corrupt that data.

[serhiy-storchaka]

File flags are saved in binhex format, therefore it is possible to distinguish text files from binary files.

[birkenfeld]

I don't remember anything specific about this, sorry.

[serhiy-storchaka]

See also bpo-29566. Perhaps hexbin() bug is related to that bug.

[Mariatta]

New changeset 6b7bc45e33ec953c542788420adc305ec026fa40 by Mariatta in branch '3.5': bpo-29557: Remove ambiguous line in binhex docs (GH-90) (GH-474) https://github.com/python/cpython/commit/6b7bc45e33ec953c542788420adc305ec026fa40

[Mariatta]

New changeset 130c4ec5fbeb0878b88ec6aa06e47c9672566c17 by Mariatta in branch '3.6': bpo-29557: Remove ambiguous line in binhex docs (GH-90) (GH-475) https://github.com/python/cpython/commit/130c4ec5fbeb0878b88ec6aa06e47c9672566c17