-
-
Notifications
You must be signed in to change notification settings - Fork 31.1k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
add "buffer protocol" to glossary #60722
Comments
This issue is to add "buffer protocol" (or perhaps "buffer object") to the glossary. The concept is currently described here: http://docs.python.org/dev/c-api/buffer.html#buffer-protocol Éric initially suggested doing this in the comments to bpo-13538. Such a glossary entry would be useful because the buffer protocol (or buffer object) should likely be cited, for example, wherever a function accepts a bytes object, bytearray object, or any object that supports the buffer protocol. The str() constructor is one example where this is done: http://hg.python.org/cpython/file/59acd5cac8b5/Doc/library/functions.rst#l1275 "Buffer object" might be the more useful term to add to the glossary because it would help to have a briefer way of saying "any object that supports the buffer protocol." (I'm assuming this is what "buffer object" actually means.) The patch for this issue should also do a comprehensive review of occurrences of buffer object/protocol throughout the docs and add or update links and index entries where appropriate. |
I would use the term that is currently used in some error messages. |
"Buffer protocol" is the right term. "Buffer object" doesn't mean anything in Python 3 and, furthermore, it might be mixed up with the Python 2 As for the error messages, they are generally very bad on this topic, so I would vote to change them :-) |
Do we have a recommended (and preferably briefer) way of saying, "any object that supports the buffer protocol"? |
s/any// |
Agreed.
I would say that they are verbose maybe, but not necessary bad. |
It depends where. There's no recommended way yet, but I would vote for The docs (glossary?) could explain that "bytes-like object" is the same |
Sounds like a good compromise between brevity and clarity to me. |
I wouldn't use "bytes-like object". One can certainly argue that *memoryview* PEP-3118 Py_buffer structs are essentially how NumPy works internally. |
Ach :-(
Well, we should still write a Python documentation, not a NumPy |
What about "buffer-like object"? |
"buffer-like" means "like a buffer" which is wrong on two points:
|
Antoine Pitrou <report@bugs.python.org> wrote:
Ok, but people should not be surprised if their (Python) array.array() of How about "object does not provide a byte buffer" for error messages |
Probably. My own (humble :-)) opinion is that array.array() is a
It's not too bad, I think. However, what I think is important is that |
Antoine Pitrou <report@bugs.python.org> wrote:
If it is somehow possible to establish the term as a shorthand for the real help (b''.join) for example would sound better with "bytes-like object" |
This can be established via the glossary. We can still use "buffer provider" for the general case, if we find that it is useful in certain circumstances. |
After this issue is resolved, the binascii docs can be updated as suggested in bpo-16724. |
Here's a patch that adds "bytes-like object" to the glossary, links to the buffer protocol docs0 and provides bytes and bytearray as examples. |
New changeset 474f28bf67b3 by Ezio Melotti in branch '3.3': New changeset 747cede24367 by Ezio Melotti in branch 'default': New changeset 1b92a0112f5d by Ezio Melotti in branch '2.7': |
New changeset d1aa8a9eba44 by Ezio Melotti in branch '2.7': |
The attached patch replaces things like "object that support the buffer protocol/interface/API" with "bytes-like objects" throughout the docs. I also noticed that on 2.70, the section about the buffer protocol in Doc/c-api/buffer.rst is called "Buffers and Memoryview Objects" and it's not as clear as the one on 3.x1. Should this section be backported? |
The "buffer protocol" situation is different on 2.x, please let's |
New changeset 003e4eb92683 by Ezio Melotti in branch '3.3': New changeset d4912244cce6 by Ezio Melotti in branch 'default': |
The attached patch uses "bytes-like objects" in the error messages. |
I'm surprised your patch doesn't touch Python/getargs.c. |
FWIW I was grepping for buffer protocol/interface/api, and then double-checking for "buffer" in the resulting files. Python/getargs.c doesn't seem to mention the buffer protocol/interface/api at all. |
Updated patch to include getargs.c too. |
At first-reading, it looks like matters were made more confusing with "bytes-like object" as a defined term. |
Can you elaborate? |
New changeset e7e8a218737a by R David Murray in branch 'default': |
Committed the message changes to 3.5 only, since it will probably cause tests to fail in various projects, despite messages not being a formal part of the python API. Per IRC conversation with Ezio and Antoine, I posted a note to python-dev to let people know we now have a consistent terminology in the docs and error messages, and to provide a last opportunity for objections (it is easy enough to back the patch out if there is an outcry, but I don't expect one). |
There are other unfixed messages (may be introduced after 3.3): >>> b''.join([''])
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: sequence item 0: expected bytes, bytearray, or an object with the buffer interface, str found
>>> str(42, 'utf8')
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: coercing to str: need bytes, bytearray or buffer-like object, int found
>>> import array; array.array('B').frombytes(array.array('I'))
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: string/buffer of bytes required.
>>> import socket; print(socket.socket.sendmsg.__doc__)
sendmsg(buffers[, ancdata[, flags[, address]]]) -> count Send normal and ancillary data to the socket, gathering the And there are several mentions of "buffer-like" or "buffer-compatible" in the documentation. |
Please open a new issue for those. |
See bpo-22581. |
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:
bugs.python.org fields:
The text was updated successfully, but these errors were encountered: