From 6f379f48862e4707e631e23997b19646ee1f2f72 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Tue, 12 Jul 2016 09:14:15 +0300 Subject: [PATCH] Issue #27481: Docummented that ValueError is now raised instead of TypeError in case of embedded null characters/bytes. Patch by Xiang Zhang. --- Doc/c-api/arg.rst | 22 +++++++++++++++++----- Doc/c-api/bytes.rst | 6 +++++- 2 files changed, 22 insertions(+), 6 deletions(-) diff --git a/Doc/c-api/arg.rst b/Doc/c-api/arg.rst index 983d113f0a1..6d493aaf3bd 100644 --- a/Doc/c-api/arg.rst +++ b/Doc/c-api/arg.rst @@ -59,8 +59,8 @@ Unless otherwise stated, buffers are not NUL-terminated. Convert a Unicode object to a C pointer to a character string. A pointer to an existing string is stored in the character pointer variable whose address you pass. The C string is NUL-terminated. - The Python string must not contain embedded NUL bytes; if it does, - a :exc:`TypeError` exception is raised. Unicode objects are converted + The Python string must not contain embedded null characters; if it does, + a :exc:`ValueError` exception is raised. Unicode objects are converted to C strings using ``'utf-8'`` encoding. If this conversion fails, a :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` 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] This format accepts Unicode objects as well as bytes-like objects. 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 \*] 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` + contain embedded null bytes; if it does, a :exc:`ValueError` 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] This variant on ``s*`` doesn't accept Unicode objects, only 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 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). - The Python string must not contain embedded NUL characters; if it does, - a :exc:`TypeError` exception is raised. + The Python string must not contain embedded null characters; if it does, + a :exc:`ValueError` exception is raised. .. note:: 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#`` 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] This variant on ``u`` stores into two C variables, the first one a pointer to a Unicode data buffer, the second one its length. diff --git a/Doc/c-api/bytes.rst b/Doc/c-api/bytes.rst index 23b712881af..dcd70886298 100644 --- a/Doc/c-api/bytes.rst +++ b/Doc/c-api/bytes.rst @@ -158,7 +158,7 @@ called with a non-bytes parameter. If *length* is *NULL*, the bytes object 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 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` 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)