Repository navigation
Define binary data representation in Python #60928
Description
| BPO | 16724 |
|---|---|
| Nosy | @rhettinger, @amauryfa, @bitdancer, @asvetlov, @cjerdonek |
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 = None
closed_at = <Date 2012-12-20.05:12:22.851>
created_at = <Date 2012-12-19.09:36:38.212>
labels = ['invalid', 'docs']
title = 'Define `binary data` representation in Python'
updated_at = <Date 2012-12-20.05:12:22.838>
user = 'https://bugs.python.org/techtonik'bugs.python.org fields:
activity = <Date 2012-12-20.05:12:22.838>
actor = 'rhettinger'
assignee = 'docs@python'
closed = True
closed_date = <Date 2012-12-20.05:12:22.851>
closer = 'rhettinger'
components = ['Documentation']
creation = <Date 2012-12-19.09:36:38.212>
creator = 'techtonik'
dependencies = []
files = []
hgrepos = []
issue_num = 16724
keywords = []
message_count = 13.0
messages = ['177727', '177728', '177749', '177752', '177756', '177758', '177759', '177763', '177764', '177765', '177767', '177796', '177798']
nosy_count = 7.0
nosy_names = ['rhettinger', 'amaury.forgeotdarc', 'techtonik', 'r.david.murray', 'asvetlov', 'chris.jerdonek', 'docs@python']
pr_nums = []
priority = 'normal'
resolution = 'not a bug'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue16724'
versions = ['Python 3.2', 'Python 3.3', 'Python 3.4']
Activity
techtonik commentedon Dec 19, 2012
http://docs.python.org/3/library/binascii
+ binascii.hexlify(bytes)
tag:easy
amauryfa commentedon Dec 19, 2012
Why? The binascii module consistently uses "data" to refer to binary data. For example:
"Return the hexadecimal representation of the binary data. Every byte of data is converted ..."
techtonik commentedon Dec 19, 2012
In Python 2 there was no 'binary data' type - everything was a string. Now we have string, str, bytearray, array, list of ints. If hexlify is not accepting anything except bytes, it is better be explicit.
When porting code from Python 2 the argument was passed as a string with escapes inside, so it took some time to figure out why it didn't work in Py3k (actually it took a lot of time, because the research path turned wrong way at this point).
amauryfa commentedon Dec 19, 2012
But it is very explicit in the link you provided: both a note at the top, and the words "binary data" in the description of every function.
asvetlov commentedon Dec 19, 2012
I agree: the docs is good and don't needed to be modified.
techtonik commentedon Dec 19, 2012
Fact no.1: When people use docs as a reference, they don't read top notes.
Face no.2:
This is not explicit:
binascii.hexlify(data)
This is:
binascii.hexlify(bytes)
I understand that you like the wording in description, but can't understand why don't want to fix this stuff above.
amauryfa commentedon Dec 19, 2012
serhiy-storchaka commentedon Dec 19, 2012
However hexlify is accepting something except bytes. It is accepting any object which supports buffer protocol.
bitdancer commentedon Dec 19, 2012
We do not use data type names as formal parameter names. You will realize this is sensible if you consider that in most cases in Python the formal parameter name is something gets used in more than just the documentation, and that using a type name would shadow the type name, which is something we prefer to avoid.
techtonik commentedon Dec 19, 2012
The fact that array.array, bytearray and memoryview are also accepted is a surprise for me. It will help if Python docs contained a definition of what can be considered 'binary data' and link this term from hexlify description to this definition.
[-]Rename `data` argument names to `bytes`[/-][+]Define `binary data` representation in Python[/+]amauryfa commentedon Dec 19, 2012
Isn't such a definition already present in the top-level paragraphs?
cjerdonek commentedon Dec 20, 2012
I believe this is part of the goal of bpo-16518, where "bytes-like object" is being proposed as one of the terms for addition to the glossary.
rhettinger commentedon Dec 20, 2012
I concur with Amaury and Andrew. The docs are fine as-is.