Issue #22581: Use more "bytes-like object" throughout the docs and comments.

serhiy-storchaka · serhiy-storchaka · commit b757c83ec626 · 2014-12-05T22:25:22.000+02:00
diff --git 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
+      <bytes-like object>`.  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
@@ -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 <bytes-like object>`
    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
@@ -1118,15 +1118,16 @@ 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 <bytes-like object>`
    (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
    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.  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
@@ -1072,7 +1072,7 @@ to speed up repeated connections from the same clients.
    <http://www.openssl.org/docs/ssl/SSL_CTX_load_verify_locations.html>`_.
 
    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
@@ -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
@@ -220,7 +220,7 @@ def recv_bytes(self, maxlength=None):
 
     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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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);
