From b757c83ec626442a8804b9417790443bf13b4fc8 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Fri, 5 Dec 2014 22:25:22 +0200 Subject: [PATCH] Issue #22581: Use more "bytes-like object" throughout the docs and comments. --- Doc/c-api/arg.rst | 27 ++++++++++++++------------- Doc/c-api/unicode.rst | 3 ++- Doc/library/socket.rst | 5 +++-- Doc/library/ssl.rst | 2 +- Include/unicodeobject.h | 2 +- Lib/multiprocessing/connection.py | 2 +- Modules/arraymodule.c | 4 ++-- Modules/socketmodule.c | 6 +++--- Objects/stringlib/join.h | 6 +++--- Objects/unicodeobject.c | 3 +-- Python/getargs.c | 14 +++++++------- Python/marshal.c | 2 +- 12 files changed, 39 insertions(+), 37 deletions(-) diff --git a/Doc/c-api/arg.rst b/Doc/c-api/arg.rst index 5d069b6b616..3c0f4b98cdb 100644 --- a/Doc/c-api/arg.rst +++ b/Doc/c-api/arg.rst @@ -65,19 +65,20 @@ Unless otherwise stated, buffers are not NUL-terminated. :exc:`UnicodeError` is raised. .. note:: - This format does not accept bytes-like objects. If you want to accept + This format does not accept :term:`bytes-like objects + `. If you want to accept filesystem paths and convert them to C character strings, it is preferable to use the ``O&`` format with :c:func:`PyUnicode_FSConverter` as *converter*. -``s*`` (:class:`str`, :class:`bytes`, :class:`bytearray` or buffer compatible object) [Py_buffer] - This format accepts Unicode objects as well as :term:`bytes-like object`\ s. +``s*`` (:class:`str` or :term:`bytes-like object`) [Py_buffer] + This format accepts Unicode objects as well as bytes-like objects. It fills a :c:type:`Py_buffer` structure provided by the caller. In this case the resulting C string may contain embedded NUL bytes. Unicode objects are converted to C strings using ``'utf-8'`` encoding. -``s#`` (:class:`str`, :class:`bytes` or read-only buffer compatible object) [const char \*, int or :c:type:`Py_ssize_t`] - Like ``s*``, except that it doesn't accept mutable buffer-like objects +``s#`` (:class:`str`, read-only :term:`bytes-like object`) [const char \*, int or :c:type:`Py_ssize_t`] + Like ``s*``, except that it doesn't accept mutable bytes-like objects such as :class:`bytearray`. The result is stored into two C variables, the first one a pointer to a C string, the second one its length. The string may contain embedded null bytes. Unicode objects are converted @@ -87,28 +88,28 @@ Unless otherwise stated, buffers are not NUL-terminated. Like ``s``, but the Python object may also be ``None``, in which case the C pointer is set to *NULL*. -``z*`` (:class:`str`, :class:`bytes`, :class:`bytearray`, buffer compatible object or ``None``) [Py_buffer] +``z*`` (:class:`str`, :term:`bytes-like object` or ``None``) [Py_buffer] Like ``s*``, but the Python object may also be ``None``, in which case the ``buf`` member of the :c:type:`Py_buffer` structure is set to *NULL*. -``z#`` (:class:`str`, :class:`bytes`, read-only buffer compatible object or ``None``) [const char \*, int] +``z#`` (:class:`str`, read-only :term:`bytes-like object` or ``None``) [const char \*, int] Like ``s#``, but the Python object may also be ``None``, in which case the C pointer is set to *NULL*. -``y`` (:class:`bytes`) [const char \*] +``y`` (read-only :term:`bytes-like object`) [const char \*] This format converts a bytes-like object to a C pointer to a character string; it does not accept Unicode objects. The bytes buffer must not contain embedded NUL bytes; if it does, a :exc:`TypeError` exception is raised. -``y*`` (:class:`bytes`, :class:`bytearray` or :term:`bytes-like object`) [Py_buffer] +``y*`` (:term:`bytes-like object`) [Py_buffer] This variant on ``s*`` doesn't accept Unicode objects, only - :term:`bytes-like object`\ s. **This is the recommended way to accept + bytes-like objects. **This is the recommended way to accept binary data.** -``y#`` (:class:`bytes`) [const char \*, int] - This variant on ``s#`` doesn't accept Unicode objects, only :term:`bytes-like - object`\ s. +``y#`` (read-only :term:`bytes-like object`) [const char \*, int] + This variant on ``s#`` doesn't accept Unicode objects, only bytes-like + objects. ``S`` (:class:`bytes`) [PyBytesObject \*] Requires that the Python object is a :class:`bytes` object, without diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst index 24bef8ec597..f541b1c8de8 100644 --- a/Doc/c-api/unicode.rst +++ b/Doc/c-api/unicode.rst @@ -556,7 +556,8 @@ APIs: Coerce an encoded object *obj* to an Unicode object and return a reference with incremented refcount. - :class:`bytes`, :class:`bytearray` and other char buffer compatible objects + :class:`bytes`, :class:`bytearray` and other + :term:`bytes-like objects ` are decoded according to the given *encoding* and using the error handling defined by *errors*. Both can be *NULL* to have the interface use the default values (see the next section for details). diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst index 86ae48488fa..b703e9e9a6f 100644 --- a/Doc/library/socket.rst +++ b/Doc/library/socket.rst @@ -1118,7 +1118,8 @@ to sockets. 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 + non-ancillary data as an iterable of + :term:`bytes-like objects ` (e.g. :class:`bytes` objects); the operating system may set a limit (:func:`~os.sysconf` value ``SC_IOV_MAX``) on the number of buffers that can be used. The *ancdata* argument specifies the ancillary @@ -1126,7 +1127,7 @@ to sockets. ``(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. Note that + bytes-like object holding the associated data. Note that some systems (in particular, systems without :func:`CMSG_SPACE`) might support sending only one control message per call. The *flags* argument defaults to 0 and has the same meaning as for diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst index a997a320513..1cc26be5d0d 100644 --- a/Doc/library/ssl.rst +++ b/Doc/library/ssl.rst @@ -1072,7 +1072,7 @@ to speed up repeated connections from the same clients. `_. The *cadata* object, if present, is either an ASCII string of one or more - PEM-encoded certificates or a bytes-like object of DER-encoded + PEM-encoded certificates or a :term:`bytes-like object` of DER-encoded certificates. Like with *capath* extra lines around PEM-encoded certificates are ignored but at least one certificate must be present. diff --git a/Include/unicodeobject.h b/Include/unicodeobject.h index faa53d644fd..057b195218b 100644 --- a/Include/unicodeobject.h +++ b/Include/unicodeobject.h @@ -849,7 +849,7 @@ PyAPI_FUNC(int) PyUnicode_Resize( Coercion is done in the following way: - 1. bytes, bytearray and other char buffer compatible objects are decoded + 1. bytes, bytearray and other bytes-like objects are decoded under the assumptions that they contain data using the UTF-8 encoding. Decoding is done in "strict" mode. diff --git a/Lib/multiprocessing/connection.py b/Lib/multiprocessing/connection.py index 3bc716f4d41..87117d91cb4 100644 --- a/Lib/multiprocessing/connection.py +++ b/Lib/multiprocessing/connection.py @@ -220,7 +220,7 @@ class _ConnectionBase: def recv_bytes_into(self, buf, offset=0): """ - Receive bytes data into a writeable buffer-like object. + Receive bytes data into a writeable bytes-like object. Return the number of bytes read. """ self._check_closed() diff --git a/Modules/arraymodule.c b/Modules/arraymodule.c index 24f0ea0f9f8..5ab1ab68367 100644 --- a/Modules/arraymodule.c +++ b/Modules/arraymodule.c @@ -1441,14 +1441,14 @@ frombytes(arrayobject *self, Py_buffer *buffer) Py_ssize_t n; if (buffer->itemsize != 1) { PyBuffer_Release(buffer); - PyErr_SetString(PyExc_TypeError, "string/buffer of bytes required."); + PyErr_SetString(PyExc_TypeError, "a bytes-like object is required"); return NULL; } n = buffer->len; if (n % itemsize != 0) { PyBuffer_Release(buffer); PyErr_SetString(PyExc_ValueError, - "string length not a multiple of item size"); + "bytes length not a multiple of item size"); return NULL; } n = n / itemsize; diff --git a/Modules/socketmodule.c b/Modules/socketmodule.c index b37e7935ffa..cb44d05b620 100644 --- a/Modules/socketmodule.c +++ b/Modules/socketmodule.c @@ -3493,7 +3493,7 @@ sock_sendmsg(PySocketSockObject *s, PyObject *args) for (; ndatabufs < ndataparts; ndatabufs++) { if (!PyArg_Parse(PySequence_Fast_GET_ITEM(data_fast, ndatabufs), "y*;sendmsg() argument 1 must be an iterable of " - "buffer-compatible objects", + "bytes-like objects", &databufs[ndatabufs])) goto finally; iovs[ndatabufs].iov_base = databufs[ndatabufs].buf; @@ -3650,12 +3650,12 @@ PyDoc_STRVAR(sendmsg_doc, Send normal and ancillary data to the socket, gathering the\n\ non-ancillary data from a series of buffers and concatenating it into\n\ a single message. The buffers argument specifies the non-ancillary\n\ -data as an iterable of buffer-compatible objects (e.g. bytes objects).\n\ +data as an iterable of bytes-like objects (e.g. bytes objects).\n\ The ancdata argument specifies the ancillary data (control messages)\n\ as an iterable of zero or more tuples (cmsg_level, cmsg_type,\n\ cmsg_data), where cmsg_level and cmsg_type are integers specifying the\n\ protocol level and protocol-specific type respectively, and cmsg_data\n\ -is a buffer-compatible object holding the associated data. The flags\n\ +is a bytes-like object holding the associated data. The flags\n\ argument defaults to 0 and has the same meaning as for send(). If\n\ address is supplied and not None, it sets a destination address for\n\ the message. The return value is the number of bytes of non-ancillary\n\ diff --git a/Objects/stringlib/join.h b/Objects/stringlib/join.h index 5568b31dab8..35eb9843523 100644 --- a/Objects/stringlib/join.h +++ b/Objects/stringlib/join.h @@ -53,15 +53,15 @@ STRINGLIB(bytes_join)(PyObject *sep, PyObject *iterable) /* Here is the general case. Do a pre-pass to figure out the total * amount of space we'll need (sz), and see whether all arguments are - * buffer-compatible. + * bytes-like. */ for (i = 0, nbufs = 0; i < seqlen; i++) { Py_ssize_t itemlen; item = PySequence_Fast_GET_ITEM(seq, i); if (_getbuffer(item, &buffers[i]) < 0) { PyErr_Format(PyExc_TypeError, - "sequence item %zd: expected bytes, bytearray, " - "or an object with the buffer interface, %.80s found", + "sequence item %zd: expected a bytes-like object, " + "%.80s found", i, Py_TYPE(item)->tp_name); goto error; } diff --git a/Objects/unicodeobject.c b/Objects/unicodeobject.c index 70728f840ca..8a13f2cdd74 100644 --- a/Objects/unicodeobject.c +++ b/Objects/unicodeobject.c @@ -2940,8 +2940,7 @@ PyUnicode_FromEncodedObject(PyObject *obj, /* Retrieve a bytes buffer view through the PEP 3118 buffer interface */ if (PyObject_GetBuffer(obj, &buffer, PyBUF_SIMPLE) < 0) { PyErr_Format(PyExc_TypeError, - "coercing to str: need bytes, bytearray " - "or buffer-like object, %.80s found", + "coercing to str: need a bytes-like object, %.80s found", Py_TYPE(obj)->tp_name); return NULL; } diff --git a/Python/getargs.c b/Python/getargs.c index 946faf2d7e0..3f47b21da5e 100644 --- a/Python/getargs.c +++ b/Python/getargs.c @@ -849,7 +849,7 @@ convertsimple(PyObject *arg, const char **p_format, va_list *p_va, int flags, /* XXX WAAAAH! 's', 'y', 'z', 'u', 'Z', 'e', 'w' codes all need to be cleaned up! */ - case 'y': {/* any buffer-like object, but not PyUnicode */ + case 'y': {/* any bytes-like object */ void **p = (void **)va_arg(*p_va, char **); char *buf; Py_ssize_t count; @@ -880,8 +880,8 @@ convertsimple(PyObject *arg, const char **p_format, va_list *p_va, int flags, break; } - case 's': /* text string */ - case 'z': /* text string or None */ + case 's': /* text string or bytes-like object */ + case 'z': /* text string, bytes-like object or None */ { if (*format == '*') { /* "s*" or "z*" */ @@ -897,7 +897,7 @@ convertsimple(PyObject *arg, const char **p_format, va_list *p_va, int flags, arg, msgbuf, bufsize); PyBuffer_FillInfo(p, arg, sarg, len, 1, 0); } - else { /* any buffer-like object */ + else { /* any bytes-like object */ char *buf; if (getbuffer(arg, p, &buf) < 0) return converterr(buf, arg, msgbuf, bufsize); @@ -908,7 +908,7 @@ convertsimple(PyObject *arg, const char **p_format, va_list *p_va, int flags, arg, msgbuf, bufsize); } format++; - } else if (*format == '#') { /* any buffer-like object */ + } else if (*format == '#') { /* a string or read-only bytes-like object */ /* "s#" or "z#" */ void **p = (void **)va_arg(*p_va, char **); FETCH_SIZE; @@ -926,7 +926,7 @@ convertsimple(PyObject *arg, const char **p_format, va_list *p_va, int flags, *p = sarg; STORE_SIZE(len); } - else { /* any buffer-like object */ + else { /* read-only bytes-like object */ /* XXX Really? */ char *buf; Py_ssize_t count = convertbuffer(arg, p, &buf); @@ -967,7 +967,7 @@ convertsimple(PyObject *arg, const char **p_format, va_list *p_va, int flags, { Py_UNICODE **p = va_arg(*p_va, Py_UNICODE **); - if (*format == '#') { /* any buffer-like object */ + if (*format == '#') { /* "s#" or "Z#" */ FETCH_SIZE; diff --git a/Python/marshal.c b/Python/marshal.c index dc5411c1ff7..bb5faf32975 100644 --- a/Python/marshal.c +++ b/Python/marshal.c @@ -529,7 +529,7 @@ w_complex_object(PyObject *v, char flag, WFILE *p) w_object(co->co_lnotab, p); } else if (PyObject_CheckBuffer(v)) { - /* Write unknown buffer-style objects as a string */ + /* Write unknown bytes-like objects as a byte string */ Py_buffer view; if (PyObject_GetBuffer(v, &view, PyBUF_SIMPLE) != 0) { w_byte(TYPE_UNKNOWN, p);