mirrors/cpython
0
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2024-11-23 18:04:37 +08:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Serhiy Storchaka 2014-12-05 22:26:10 +02:00
commit 92bf919ed0
12 changed files with 39 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
Doc/c-api/arg.rst
View File

@ -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

3
Doc/c-api/unicode.rst
View File

@ -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).

5
Doc/library/socket.rst
View File

@ -1123,7 +1123,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 <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
@ -1131,7 +1132,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

2
Doc/library/ssl.rst
View File

@ -1104,7 +1104,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.

2
Include/unicodeobject.h
View File

@ -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.

2
Lib/multiprocessing/connection.py
View File

@ -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()

4
Modules/arraymodule.c
View File

@ -1573,14 +1573,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;

6
Modules/socketmodule.c
View File

@ -3560,7 +3560,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;
@ -3717,12 +3717,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\

6
Objects/stringlib/join.h
View File

@ -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;
}

3
Objects/unicodeobject.c
View File

@ -2905,8 +2905,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;
}

14
Python/getargs.c
View File

@ -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);
@ -966,7 +966,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;

2
Python/marshal.c
View File

@ -527,7 +527,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);