classification
Title: Other mentions of the buffer protocol
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.4, Python 3.5
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: chris.jerdonek, docs@python, eric.araujo, ezio.melotti, flox, georg.brandl, pitrou, python-dev, r.david.murray, rhettinger, serhiy.storchaka, terry.reedy
Priority: normal Keywords: easy, needs review, patch

Created on 2014-10-08 16:18 by serhiy.storchaka, last changed 2014-12-05 20:36 by serhiy.storchaka. This issue is now closed.

Files
File name Uploaded Description Edit
bytes_like.patch serhiy.storchaka, 2014-11-10 20:50
bytes_like.patch serhiy.storchaka, 2014-11-25 15:32 review
Messages (10)
msg228799 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2014-10-08 16:18
In addition to issue16518. There are other non-fixed 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
non-ancillary data from a series of buffers and concatenating it into
a single message.  The buffers argument specifies the non-ancillary
data as an iterable of buffer-compatible objects (e.g. bytes objects).
The ancdata argument specifies the ancillary data (control messages)
as an iterable of zero or more tuples (cmsg_level, cmsg_type,
cmsg_data), where cmsg_level and cmsg_type are integers specifying the
protocol level and protocol-specific type respectively, and cmsg_data
is a buffer-compatible object holding the associated data.  The flags
argument defaults to 0 and has the same meaning as for send().  If
address is supplied and not None, it sets a destination address for
the message.  The return value is the number of bytes of non-ancillary
data sent.

And there are several mentions of "buffer-like" or "buffer-compatible" in the documentation.
msg230972 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2014-11-10 20:50
Here is a patch which fixes remnants. It also corrects descriptions of parsing arguments format units.
msg231644 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2014-11-25 08:59
Could anyone please look at the patch? It touches only docs and comments.
msg231663 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-11-25 15:02
There's no review link.  And no obvious reason why there isn't.  Could you try regenerating the patch and uploading it again?
msg231665 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2014-11-25 15:32
Regenerated for review. I don't know why Rietweld didn't like previous patch.
msg232193 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-12-05 15:29
Made some review comments.  The last comment change (deletion) in unicodeobject.c is not as obvious as the other changes were; I'm not familiar enough with the C API to know why it is correct.  I trust you on that, though :)
msg232197 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2014-12-05 16:25
Thank you David.

I have left enumerations of concrete bytes-like classes (bytes and bytearray) because I thought that it is good to be more verbose in the documentation. I left the decision how write it to you: ":class:`bytes`, :class:`bytearray` or :term:`bytes-like object`", ":term:`bytes-like object` such as :class:`bytes` and :class:`bytearray`", or just ":term:`bytes-like object`".

I don't understand your comment about unicodeobject.c. This change doesn't differ from others. May be you mean unicodeobject.h? Yes, "char buffer" is Python 2 term and doesn't make sense in 3.x.
msg232199 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-12-05 16:47
Yeah, just ignore the unicodeobject.c comment comment.

It seems to me that the stuff in the parens is supposed to be a precise description of what the format code handles, with elaboration in the following text.  So I'd prefer to just use the :term: in those lists.  But like I said I'm not that familiar with the C api, so I'm not sure how much weight my opinion should carry :)  

The biggest thing is consistency.  If you want to keep all of them in the list, I'd favor the "such as" formulation.
msg232207 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2014-12-05 20:30
New changeset 853e3e115db4 by Serhiy Storchaka in branch '3.4':
Issue #22581: Use more "bytes-like object" throughout the docs and comments.
https://hg.python.org/cpython/rev/853e3e115db4

New changeset 450a025b1669 by Serhiy Storchaka in branch 'default':
Issue #22581: Use more "bytes-like object" throughout the docs and comments.
https://hg.python.org/cpython/rev/450a025b1669
msg232208 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2014-12-05 20:35
Committed with just "bytes-like object". Thank you David for your review.
History
Date User Action Args
2014-12-05 20:36:17serhiy.storchakasetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2014-12-05 20:35:28serhiy.storchakasetmessages: + msg232208
2014-12-05 20:30:51python-devsetmessages: + msg232207
2014-12-05 16:47:45r.david.murraysetmessages: + msg232199
2014-12-05 16:25:02serhiy.storchakasetmessages: + msg232197
2014-12-05 15:29:30r.david.murraysetmessages: + msg232193
2014-11-25 15:32:50serhiy.storchakasetfiles: + bytes_like.patch

messages: + msg231665
2014-11-25 15:02:30r.david.murraysetmessages: + msg231663
2014-11-25 08:59:20serhiy.storchakasetmessages: + msg231644
2014-11-25 08:58:59serhiy.storchakasetmessages: - msg231643
2014-11-25 08:57:51serhiy.storchakasetkeywords: + needs review

messages: + msg231643
2014-11-10 20:50:33serhiy.storchakasetfiles: + bytes_like.patch
keywords: + patch
messages: + msg230972

stage: needs patch -> patch review
2014-11-02 15:07:52serhiy.storchakalinkissue22364 dependencies
2014-10-31 18:47:29ezio.melottisettype: enhancement
versions: + Python 3.4, Python 3.5
2014-10-14 15:22:04skrahsetnosy: - skrah
2014-10-08 16:18:20serhiy.storchakacreate