classification
Title: Define `binary data` representation in Python
Type: Stage: resolved
Components: Documentation Versions: Python 3.2, Python 3.3, Python 3.4
process
Status: closed Resolution: not a bug
Dependencies: Superseder:
Assigned To: docs@python Nosy List: amaury.forgeotdarc, asvetlov, chris.jerdonek, docs@python, r.david.murray, rhettinger, techtonik
Priority: normal Keywords:

Created on 2012-12-19 09:36 by techtonik, last changed 2012-12-20 05:12 by rhettinger. This issue is now closed.

Messages (13)
msg177727 - (view) Author: anatoly techtonik (techtonik) Date: 2012-12-19 09:36
http://docs.python.org/3/library/binascii

- binascii.hexlify(data)
+ binascii.hexlify(bytes)

tag:easy
msg177728 - (view) Author: Amaury Forgeot d'Arc (amaury.forgeotdarc) * (Python committer) Date: 2012-12-19 09:41
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 ..."
msg177749 - (view) Author: anatoly techtonik (techtonik) Date: 2012-12-19 15:51
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).
msg177752 - (view) Author: Amaury Forgeot d'Arc (amaury.forgeotdarc) * (Python committer) Date: 2012-12-19 16:03
> If hexlify is not accepting anything except bytes, it is better be explicit.

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.
msg177756 - (view) Author: Andrew Svetlov (asvetlov) * (Python committer) Date: 2012-12-19 16:21
I agree: the docs is good and don't needed to be modified.
msg177758 - (view) Author: anatoly techtonik (techtonik) Date: 2012-12-19 16:32
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.
msg177759 - (view) Author: Amaury Forgeot d'Arc (amaury.forgeotdarc) * (Python committer) Date: 2012-12-19 16:38
> When people use docs as a reference, they don't read top notes.
Maybe, but they can read some words beyond the function name, can't they?
msg177763 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2012-12-19 16:52
> If hexlify is not accepting anything except bytes, it is better be explicit.

However hexlify is accepting something except bytes. It is accepting any object which supports buffer protocol.
msg177764 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2012-12-19 16:52
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.
msg177765 - (view) Author: anatoly techtonik (techtonik) Date: 2012-12-19 17:10
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.
msg177767 - (view) Author: Amaury Forgeot d'Arc (amaury.forgeotdarc) * (Python committer) Date: 2012-12-19 17:27
Isn't such a definition already present in the top-level paragraphs?
msg177796 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-12-20 03:52
> 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.

I believe this is part of the goal of issue 16518, where "bytes-like object" is being proposed as one of the terms for addition to the glossary.
msg177798 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2012-12-20 05:12
I concur with Amaury and Andrew.  The docs are fine as-is.
History
Date User Action Args
2012-12-20 05:12:22rhettingersetstatus: open -> closed

nosy: + rhettinger
messages: + msg177798

resolution: not a bug
2012-12-20 03:52:44chris.jerdoneksetnosy: + chris.jerdonek
messages: + msg177796
2012-12-19 21:19:56serhiy.storchakasetnosy: - serhiy.storchaka

versions: - Python 3.1, Python 3.5
2012-12-19 17:27:18amaury.forgeotdarcsetmessages: + msg177767
2012-12-19 17:10:21techtoniksetstatus: closed -> open
resolution: not a bug -> (no value)
messages: + msg177765

title: Rename `data` argument names to `bytes` -> Define `binary data` representation in Python
2012-12-19 16:52:44r.david.murraysetstatus: open -> closed

nosy: + r.david.murray
messages: + msg177764

resolution: not a bug
stage: resolved
2012-12-19 16:52:05serhiy.storchakasetnosy: + serhiy.storchaka
messages: + msg177763
2012-12-19 16:38:49amaury.forgeotdarcsetmessages: + msg177759
2012-12-19 16:32:51techtoniksetmessages: + msg177758
2012-12-19 16:21:24asvetlovsetnosy: + asvetlov
messages: + msg177756
2012-12-19 16:03:26amaury.forgeotdarcsetmessages: + msg177752
2012-12-19 15:51:41techtoniksetmessages: + msg177749
2012-12-19 09:41:21amaury.forgeotdarcsetnosy: + amaury.forgeotdarc
messages: + msg177728
2012-12-19 09:36:38techtonikcreate