[issue16724] Rename `data` argument names to `bytes`
New submission from anatoly techtonik: http://docs.python.org/3/library/binascii - binascii.hexlify(data) + binascii.hexlify(bytes) tag:easy ---------- assignee: docs@python components: Documentation messages: 177727 nosy: docs@python, techtonik priority: normal severity: normal status: open title: Rename `data` argument names to `bytes` versions: Python 3.1, Python 3.2, Python 3.3, Python 3.4, Python 3.5 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16724> _______________________________________
Amaury Forgeot d'Arc added the comment: 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 ..." ---------- nosy: +amaury.forgeotdarc _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16724> _______________________________________
anatoly techtonik added the comment: 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). ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16724> _______________________________________
Amaury Forgeot d'Arc added the comment:
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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16724> _______________________________________
Andrew Svetlov added the comment: I agree: the docs is good and don't needed to be modified. ---------- nosy: +asvetlov _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16724> _______________________________________
anatoly techtonik added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16724> _______________________________________
Amaury Forgeot d'Arc added the comment:
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?
---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16724> _______________________________________
Serhiy Storchaka added the comment:
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. ---------- nosy: +serhiy.storchaka _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16724> _______________________________________
R. David Murray added the comment: 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. ---------- nosy: +r.david.murray resolution: -> invalid stage: -> committed/rejected status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16724> _______________________________________
anatoly techtonik added the comment: 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. ---------- resolution: invalid -> status: closed -> open title: Rename `data` argument names to `bytes` -> Define `binary data` representation in Python _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16724> _______________________________________
Amaury Forgeot d'Arc added the comment: Isn't such a definition already present in the top-level paragraphs? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16724> _______________________________________
Changes by Serhiy Storchaka <storchaka@gmail.com>: ---------- nosy: -serhiy.storchaka versions: -Python 3.1, Python 3.5 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16724> _______________________________________
Chris Jerdonek added the comment:
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. ---------- nosy: +chris.jerdonek _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16724> _______________________________________
Raymond Hettinger added the comment: I concur with Amaury and Andrew. The docs are fine as-is. ---------- nosy: +rhettinger resolution: -> invalid status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16724> _______________________________________
Amaury Forgeot d'Arc added the comment: 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 ..." ---------- nosy: +amaury.forgeotdarc _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16724> _______________________________________
anatoly techtonik added the comment: 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). ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16724> _______________________________________
Amaury Forgeot d'Arc added the comment:
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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16724> _______________________________________
Andrew Svetlov added the comment: I agree: the docs is good and don't needed to be modified. ---------- nosy: +asvetlov _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16724> _______________________________________
anatoly techtonik added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16724> _______________________________________
Amaury Forgeot d'Arc added the comment:
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?
---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16724> _______________________________________
Serhiy Storchaka added the comment:
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. ---------- nosy: +serhiy.storchaka _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16724> _______________________________________
R. David Murray added the comment: 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. ---------- nosy: +r.david.murray resolution: -> invalid stage: -> committed/rejected status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16724> _______________________________________
anatoly techtonik added the comment: 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. ---------- resolution: invalid -> status: closed -> open title: Rename `data` argument names to `bytes` -> Define `binary data` representation in Python _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16724> _______________________________________
Amaury Forgeot d'Arc added the comment: Isn't such a definition already present in the top-level paragraphs? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16724> _______________________________________
Changes by Serhiy Storchaka <storchaka@gmail.com>: ---------- nosy: -serhiy.storchaka versions: -Python 3.1, Python 3.5 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16724> _______________________________________
Chris Jerdonek added the comment:
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. ---------- nosy: +chris.jerdonek _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16724> _______________________________________
Raymond Hettinger added the comment: I concur with Amaury and Andrew. The docs are fine as-is. ---------- nosy: +rhettinger resolution: -> invalid status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16724> _______________________________________
participants (7)
-
Amaury Forgeot d'Arc -
anatoly techtonik
-
Andrew Svetlov
-
Chris Jerdonek
-
R. David Murray
-
Raymond Hettinger
-
Serhiy Storchaka