mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-08-02 16:13:13 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8

Issue #27481: Docummented that ValueError is now raised instead of TypeError

Browse source 
in case of embedded null characters/bytes.  Patch by Xiang Zhang.
This commit is contained in:
Serhiy Storchaka 2016-07-12 09:15:00 +03:00
commit b133bb4977
2 changed files with 22 additions and 6 deletions
Download patch file Download diff file Expand all files Collapse all files

22
Doc/c-api/arg.rst
View file

@ -59,8 +59,8 @@ Unless otherwise stated, buffers are not NUL-terminated.
Convert a Unicode object to a C pointer to a character string. Convert a Unicode object to a C pointer to a character string.
A pointer to an existing string is stored in the character pointer A pointer to an existing string is stored in the character pointer
variable whose address you pass. The C string is NUL-terminated. variable whose address you pass. The C string is NUL-terminated.
The Python string must not contain embedded NUL bytes; if it does, The Python string must not contain embedded null characters; if it does,
a :exc:`TypeError` exception is raised. Unicode objects are converted a :exc:`ValueError` exception is raised. Unicode objects are converted
to C strings using ``'utf-8'`` encoding. If this conversion fails, a to C strings using ``'utf-8'`` encoding. If this conversion fails, a
:exc:`UnicodeError` is raised. :exc:`UnicodeError` is raised.
@ -71,6 +71,10 @@ Unless otherwise stated, buffers are not NUL-terminated.
preferable to use the ``O&`` format with :c:func:`PyUnicode_FSConverter` preferable to use the ``O&`` format with :c:func:`PyUnicode_FSConverter`
as *converter*. as *converter*.
.. versionchanged:: 3.5
Previously, :exc:`TypeError` was raised when embedded null characters
were encountered in the Python string.
``s*`` (:class:`str` or :term:`bytes-like object`) [Py_buffer] ``s*`` (:class:`str` or :term:`bytes-like object`) [Py_buffer]
This format accepts Unicode objects as well as bytes-like objects. This format accepts Unicode objects as well as bytes-like objects.
It fills a :c:type:`Py_buffer` structure provided by the caller. It fills a :c:type:`Py_buffer` structure provided by the caller.
@ -99,9 +103,13 @@ Unless otherwise stated, buffers are not NUL-terminated.
``y`` (read-only :term:`bytes-like object`) [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 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 string; it does not accept Unicode objects. The bytes buffer must not
contain embedded NUL bytes; if it does, a :exc:`TypeError` contain embedded null bytes; if it does, a :exc:`ValueError`
exception is raised. exception is raised.
.. versionchanged:: 3.5
Previously, :exc:`TypeError` was raised when embedded null bytes were
encountered in the bytes buffer.
``y*`` (:term:`bytes-like object`) [Py_buffer] ``y*`` (:term:`bytes-like object`) [Py_buffer]
This variant on ``s*`` doesn't accept Unicode objects, only This variant on ``s*`` doesn't accept Unicode objects, only
bytes-like objects. **This is the recommended way to accept bytes-like objects. **This is the recommended way to accept
@ -127,14 +135,18 @@ Unless otherwise stated, buffers are not NUL-terminated.
pointer variable, which will be filled with the pointer to an existing pointer variable, which will be filled with the pointer to an existing
Unicode buffer. Please note that the width of a :c:type:`Py_UNICODE` Unicode buffer. Please note that the width of a :c:type:`Py_UNICODE`
character depends on compilation options (it is either 16 or 32 bits). character depends on compilation options (it is either 16 or 32 bits).
The Python string must not contain embedded NUL characters; if it does, The Python string must not contain embedded null characters; if it does,
a :exc:`TypeError` exception is raised. a :exc:`ValueError` exception is raised.
.. note:: .. note::
Since ``u`` doesn't give you back the length of the string, and it Since ``u`` doesn't give you back the length of the string, and it
may contain embedded NUL characters, it is recommended to use ``u#`` may contain embedded NUL characters, it is recommended to use ``u#``
or ``U`` instead. or ``U`` instead.
.. versionchanged:: 3.5
Previously, :exc:`TypeError` was raised when embedded null characters
were encountered in the Python string.
``u#`` (:class:`str`) [Py_UNICODE \*, int] ``u#`` (:class:`str`) [Py_UNICODE \*, int]
This variant on ``u`` stores into two C variables, the first one a pointer to a This variant on ``u`` stores into two C variables, the first one a pointer to a
Unicode data buffer, the second one its length. Unicode data buffer, the second one its length.

6
Doc/c-api/bytes.rst
View file

@ -158,7 +158,7 @@ called with a non-bytes parameter.
If *length* is *NULL*, the bytes object If *length* is *NULL*, the bytes object
may not contain embedded null bytes; may not contain embedded null bytes;
if it does, the function returns ``-1`` and a :exc:`TypeError` is raised. if it does, the function returns ``-1`` and a :exc:`ValueError` is raised.
The buffer refers to an internal buffer of *obj*, which includes an The buffer refers to an internal buffer of *obj*, which includes an
additional null byte at the end (not counted in *length*). The data additional null byte at the end (not counted in *length*). The data
@ -167,6 +167,10 @@ called with a non-bytes parameter.
*obj* is not a bytes object at all, :c:func:`PyBytes_AsStringAndSize` *obj* is not a bytes object at all, :c:func:`PyBytes_AsStringAndSize`
returns ``-1`` and raises :exc:`TypeError`. returns ``-1`` and raises :exc:`TypeError`.
.. versionchanged:: 3.5
Previously, :exc:`TypeError` was raised when embedded null bytes were
encountered in the bytes object.
.. c:function:: void PyBytes_Concat(PyObject **bytes, PyObject *newpart) .. c:function:: void PyBytes_Concat(PyObject **bytes, PyObject *newpart)