add "buffer protocol" to glossary

[cjerdonek]

BPO	16518
Nosy	@birkenfeld, @rhettinger, @terryjreedy, @pitrou, @ezio-melotti, @merwok, @bitdancer, @skrah, @florentx, @cjerdonek, @serhiy-storchaka
Files	issue16518.diff issue16518-2.diff: Patch to use "bytes-like object" in throughout the docs issue16518-3.diff issue16518-4.diff

^{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 2014-10-05.16:15:14.491>
created_at = <Date 2012-11-21.06:03:27.806>
labels = ['type-feature', 'docs']
title = 'add "buffer protocol" to glossary'
updated_at = <Date 2014-10-31.19:08:28.740>
user = 'https://github.com/cjerdonek'

bugs.python.org fields:

activity = <Date 2014-10-31.19:08:28.740>
actor = 'ezio.melotti'
assignee = 'docs@python'
closed = True
closed_date = <Date 2014-10-05.16:15:14.491>
closer = 'r.david.murray'
components = ['Documentation']
creation = <Date 2012-11-21.06:03:27.806>
creator = 'chris.jerdonek'
dependencies = []
files = ['30065', '30089', '30124', '30138']
hgrepos = []
issue_num = 16518
keywords = ['patch']
message_count = 34.0
messages = ['176042', '176238', '176242', '176244', '176245', '176247', '176248', '176249', '176251', '176252', '176253', '176254', '176256', '176257', '176262', '176264', '177801', '188078', '188183', '188207', '188208', '188209', '188368', '188369', '188404', '188406', '188453', '188484', '188485', '228585', '228587', '228596', '228694', '230380']
nosy_count = 13.0
nosy_names = ['georg.brandl', 'rhettinger', 'terry.reedy', 'pitrou', 'ezio.melotti', 'eric.araujo', 'r.david.murray', 'skrah', 'flox', 'chris.jerdonek', 'docs@python', 'python-dev', 'serhiy.storchaka']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue16518'
versions = ['Python 2.7', 'Python 3.3', 'Python 3.4']

[cjerdonek]

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.

[terryjreedy]

I would use the term that is currently used in some error messages.

[pitrou]

"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 buffer type.

As for the error messages, they are generally very bad on this topic, so I would vote to change them :-)

[cjerdonek]

Do we have a recommended (and preferably briefer) way of saying, "any object that supports the buffer protocol"?

[cjerdonek]

s/any//

[ezio-melotti]

"Buffer object" doesn't mean anything in Python 3 and, furthermore,
it might be mixed up with the Python 2 buffer type.

Agreed.

As for the error messages, they are generally very bad on this topic,
so I would vote to change them :-)

I would say that they are verbose maybe, but not necessary bad.
Using "any object that supports the buffer protocol" without explicitly mentioning bytes (and bytearray) might end up being even more confusing (if that's what it's being proposed).

[pitrou]

Do we have a recommended (and preferably briefer) way of saying, "any
object that supports the buffer protocol"?

It depends where. There's no recommended way yet, but I would vote for
"bytes-like object" in error messages that are targetted at the average
developer.

The docs (glossary?) could explain that "bytes-like object" is the same
as "buffer-providing object" or "object implementing the buffer
protocol".

[ezio-melotti]

I would vote for "bytes-like object"

Sounds like a good compromise between brevity and clarity to me.

[skrah]

I wouldn't use "bytes-like object". One can certainly argue that *memoryview*
should be bytes-like as a matter of preference, but the buffer protocol
specifies strongly (or even statically) typed multi-dimensional arrays.

PEP-3118 Py_buffer structs are essentially how NumPy works internally.

[pitrou]

I wouldn't use "bytes-like object". One can certainly argue that *memoryview*
should be bytes-like as a matter of preference, but the buffer protocol
specifies strongly (or even statically) typed multi-dimensional arrays.

Ach :-(

PEP-3118 Py_buffer structs are essentially how NumPy works internally.

Well, we should still write a Python documentation, not a NumPy
documentation (on this tracker anyway). Outside of NumPy, there's little
use for multi-dimensional objects.

[cjerdonek]

I wouldn't use "bytes-like object".

What about "buffer-like object"?

[pitrou]

> I wouldn't use "bytes-like object".

What about "buffer-like object"?

"buffer-like" means "like a buffer" which is wrong on two points:

• "buffer" is not defined at this point, so the user doesn't understand
  what it means
• we are not talking about an object which is "like a buffer", but which
  "provides a buffer"