diff options
Diffstat (limited to 'Doc/c-api/arg.rst')
| -rw-r--r-- | Doc/c-api/arg.rst | 22 |
1 files changed, 17 insertions, 5 deletions
diff --git a/Doc/c-api/arg.rst b/Doc/c-api/arg.rst index 983d113..6d493aa 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. |