From c228e96726129e20519a2016075fca3dc9fdcd30 Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Sat, 4 May 2013 18:06:34 +0300 Subject: #16518: use "bytes-like object" throughout the docs. --- Doc/c-api/arg.rst | 13 ++++++------- Doc/c-api/bytearray.rst | 2 +- Doc/library/array.rst | 6 +++--- Doc/library/binascii.rst | 5 +++-- Doc/library/hashlib.rst | 6 +++--- Doc/library/hmac.rst | 3 +-- Doc/library/multiprocessing.rst | 5 ++--- Doc/library/stdtypes.rst | 12 +++++------- 8 files changed, 24 insertions(+), 28 deletions(-) diff --git a/Doc/c-api/arg.rst b/Doc/c-api/arg.rst index b28aa5f..b4efbf0 100644 --- a/Doc/c-api/arg.rst +++ b/Doc/c-api/arg.rst @@ -70,8 +70,7 @@ Unless otherwise stated, buffers are not NUL-terminated. as *converter*. ``s*`` (:class:`str`, :class:`bytes`, :class:`bytearray` or buffer compatible object) [Py_buffer] - This format accepts Unicode objects as well as objects supporting the - buffer protocol. + This format accepts Unicode objects as well as :term:`bytes-like object`\ s. 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. @@ -101,14 +100,14 @@ Unless otherwise stated, buffers are not NUL-terminated. contain embedded NUL bytes; if it does, a :exc:`TypeError` exception is raised. -``y*`` (:class:`bytes`, :class:`bytearray` or buffer compatible object) [Py_buffer] - This variant on ``s*`` doesn't accept Unicode objects, only objects - supporting the buffer protocol. **This is the recommended way to accept +``y*`` (:class:`bytes`, :class:`bytearray` or :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 binary data.** ``y#`` (:class:`bytes`) [const char \*, int] - This variant on ``s#`` doesn't accept Unicode objects, only bytes-like - objects. + This variant on ``s#`` doesn't accept Unicode objects, only :term:`bytes-like + object`\ s. ``S`` (:class:`bytes`) [PyBytesObject \*] Requires that the Python object is a :class:`bytes` object, without diff --git a/Doc/c-api/bytearray.rst b/Doc/c-api/bytearray.rst index 95ded96..8202205 100644 --- a/Doc/c-api/bytearray.rst +++ b/Doc/c-api/bytearray.rst @@ -40,7 +40,7 @@ Direct API functions .. c:function:: PyObject* PyByteArray_FromObject(PyObject *o) Return a new bytearray object from any object, *o*, that implements the - buffer protocol. + :ref:`buffer protocol `. .. XXX expand about the buffer protocol, at least somewhere diff --git a/Doc/library/array.rst b/Doc/library/array.rst index 8f6943a..752bad5 100644 --- a/Doc/library/array.rst +++ b/Doc/library/array.rst @@ -73,8 +73,8 @@ The module defines the following type: .. class:: array(typecode[, initializer]) A new array whose items are restricted by *typecode*, and initialized - from the optional *initializer* value, which must be a list, object - supporting the buffer interface, or iterable over elements of the + from the optional *initializer* value, which must be a list, a + :term:`bytes-like object`, or iterable over elements of the appropriate type. If given a list or string, the initializer is passed to the new array's @@ -91,7 +91,7 @@ Array objects support the ordinary sequence operations of indexing, slicing, concatenation, and multiplication. When using slice assignment, the assigned value must be an array object with the same type code; in all other cases, :exc:`TypeError` is raised. Array objects also implement the buffer interface, -and may be used wherever buffer objects are supported. +and may be used wherever :term:`bytes-like object`\ s are supported. The following data items and methods are also supported: diff --git a/Doc/library/binascii.rst b/Doc/library/binascii.rst index baf430d..02ec5d8 100644 --- a/Doc/library/binascii.rst +++ b/Doc/library/binascii.rst @@ -21,8 +21,9 @@ higher-level modules. .. note:: ``a2b_*`` functions accept Unicode strings containing only ASCII characters. - Other functions only accept bytes and bytes-compatible objects (such as - bytearray objects and other objects implementing the buffer API). + Other functions only accept :term:`bytes-like object`\ s (such as + :class:`bytes`, :class:`bytearray` and other objects that support the buffer + protocol). .. versionchanged:: 3.3 ASCII-only unicode strings are now accepted by the ``a2b_*`` functions. diff --git a/Doc/library/hashlib.rst b/Doc/library/hashlib.rst index 929d41b..0a1b208 100644 --- a/Doc/library/hashlib.rst +++ b/Doc/library/hashlib.rst @@ -32,9 +32,9 @@ digests. The modern term is secure hash. There is one constructor method named for each type of :dfn:`hash`. All return a hash object with the same simple interface. For example: use :func:`sha1` to -create a SHA1 hash object. You can now feed this object with objects conforming -to the buffer interface (normally :class:`bytes` objects) using the -:meth:`update` method. At any point you can ask it for the :dfn:`digest` of the +create a SHA1 hash object. You can now feed this object with :term:`bytes-like +object`\ s (normally :class:`bytes`) using the :meth:`update` method. +At any point you can ask it for the :dfn:`digest` of the concatenation of the data fed to it so far using the :meth:`digest` or :meth:`hexdigest` methods. diff --git a/Doc/library/hmac.rst b/Doc/library/hmac.rst index 0706ff4..c2066a7 100644 --- a/Doc/library/hmac.rst +++ b/Doc/library/hmac.rst @@ -74,8 +74,7 @@ This module also provides the following helper function: timing analysis by avoiding content-based short circuiting behaviour, making it appropriate for cryptography. *a* and *b* must both be of the same type: either :class:`str` (ASCII only, as e.g. returned by - :meth:`HMAC.hexdigest`), or any type that supports the buffer protocol - (e.g. :class:`bytes`). + :meth:`HMAC.hexdigest`), or a :term:`bytes-like object`. .. note:: diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst index fe38d23..1c18062 100644 --- a/Doc/library/multiprocessing.rst +++ b/Doc/library/multiprocessing.rst @@ -800,8 +800,7 @@ Connection objects are usually created using :func:`Pipe` -- see also .. method:: send_bytes(buffer[, offset[, size]]) - Send byte data from an object supporting the buffer interface as a - complete message. + Send byte data from a :term:`bytes-like object` as a complete message. If *offset* is given then data is read from that position in *buffer*. If *size* is given then that many bytes will be read from buffer. Very large @@ -832,7 +831,7 @@ Connection objects are usually created using :func:`Pipe` -- see also :exc:`EOFError` if there is nothing left to receive and the other end was closed. - *buffer* must be an object satisfying the writable buffer interface. If + *buffer* must be a writable :term:`bytes-like object`. If *offset* is given then the message will be written into the buffer from that position. Offset must be a non-negative integer less than the length of *buffer* (in bytes). diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 03ab5db..3763958 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -519,9 +519,8 @@ class`. In addition, it provides one more method: >>> int.from_bytes([255, 0, 0], byteorder='big') 16711680 - The argument *bytes* must either support the buffer protocol or be an - iterable producing bytes. :class:`bytes` and :class:`bytearray` are - examples of built-in objects that support the buffer protocol. + The argument *bytes* must either be a :term:`bytes-like object` or an + iterable producing bytes. The *byteorder* argument determines the byte order used to represent the integer. If *byteorder* is ``"big"``, the most significant byte is at the @@ -1417,10 +1416,9 @@ multiple fragments. single: bytes; str (built-in class) If at least one of *encoding* or *errors* is given, *object* should be a - :class:`bytes` or :class:`bytearray` object, or more generally any object - that supports the :ref:`buffer protocol `. In this case, if - *object* is a :class:`bytes` (or :class:`bytearray`) object, then - ``str(bytes, encoding, errors)`` is equivalent to + :term:`bytes-like object` (e.g. :class:`bytes` or :class:`bytearray`). In + this case, if *object* is a :class:`bytes` (or :class:`bytearray`) object, + then ``str(bytes, encoding, errors)`` is equivalent to :meth:`bytes.decode(encoding, errors) `. Otherwise, the bytes object underlying the buffer object is obtained before calling :meth:`bytes.decode`. See :ref:`binaryseq` and -- cgit v0.12