From 7a741cae94fea4aeb054db4a0b689eb3d2e62ae4 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Wed, 23 Apr 2025 12:27:17 +0100 Subject: [PATCH 1/2] Commit part 1 --- Doc/c-api/arg.rst | 53 +++++++++++++++++++++++++++-------------------- 1 file changed, 31 insertions(+), 22 deletions(-) diff --git a/Doc/c-api/arg.rst b/Doc/c-api/arg.rst index 81b093a3510914..12681934fd81e3 100644 --- a/Doc/c-api/arg.rst +++ b/Doc/c-api/arg.rst @@ -47,15 +47,15 @@ Unless otherwise stated, buffers are not NUL-terminated. There are three ways strings and buffers can be converted to C: -* Formats such as ``y*`` and ``s*`` fill a :c:type:`Py_buffer` structure. +* Formats such as ``"y*"`` and ``"s*"`` fill a :c:type:`Py_buffer` structure. This locks the underlying buffer so that the caller can subsequently use the buffer even inside a :c:type:`Py_BEGIN_ALLOW_THREADS` block without the risk of mutable data being resized or destroyed. As a result, **you have to call** :c:func:`PyBuffer_Release` after you have finished processing the data (or in any early abort case). -* The ``es``, ``es#``, ``et`` and ``et#`` formats allocate the result buffer. - **You have to call** :c:func:`PyMem_Free` after you have finished +* The ``"es"``, ``"es#"``, ``"et"`` and ``"et#"`` formats allocate the result + buffer. **You have to call** :c:func:`PyMem_Free` after you have finished processing the data (or in any early abort case). * .. _c-arg-borrowed-buffer: @@ -77,7 +77,7 @@ There are three ways strings and buffers can be converted to C: whether the input object is immutable (e.g. whether it would honor a request for a writable buffer, or whether another thread can mutate the data). -``s`` (:class:`str`) [const char \*] +``"s"`` (:ctype:`PyUnicodeObject\*`) [:ctype:`const char\*`] 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. @@ -90,43 +90,51 @@ There are three ways strings and buffers can be converted to C: This format does not accept :term:`bytes-like objects `. 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` + preferable to use the ``"O&"`` format with :c:func:`PyUnicode_FSConverter` as *converter*. .. versionchanged:: 3.5 Previously, :exc:`TypeError` was raised when embedded null code points were encountered in the Python string. -``s*`` (:class:`str` or :term:`bytes-like object`) [Py_buffer] +``"s*"`` (:ctype:`PyUnicodeObject\*`, :ctype:`PyBytesObject\*`, + :ctype:`PyByteArrayObject\*` or :term:`bytes-like object`) [:ctype:`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`, read-only :term:`bytes-like object`) [const char \*, :c:type:`Py_ssize_t`] - Like ``s*``, except that it provides a :ref:`borrowed buffer `. +``"s#"`` (:ctype:`PyUnicodeObject\*`, :ctype:`PyBytesObject\*` or read-only + :term:`bytes-like object`) [:ctype:`const char\*`, :ctype:`int` or + :ctype:`Py_ssize_t`] + Like ``"s*"``, except that it provides a :ref:`borrowed buffer `. 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 to C strings using ``'utf-8'`` encoding. -``z`` (:class:`str` or ``None``) [const char \*] - Like ``s``, but the Python object may also be ``None``, in which case the C - pointer is set to ``NULL``. - It is the same as ``s?`` with the C pointer was initialized to ``NULL``. +``"z"`` (:ctype:`PyUnicodeObject\*` or :ctype:`Py_None`) [:ctype:`const char\*`] + Like ``"s"``, but the Python object may also be :ctype:`Py_None`, + in which case the C pointer is set to ``NULL``. + It is the same as ``"s?"`` with the C pointer was initialized to ``NULL``. -``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 +``"z*"`` (:ctype:`PyUnicodeObject\*`, :ctype:`PyBytesObject\*`, + :ctype:`PyByteArrayObject\*`, :term:`bytes-like object`, or :ctype:`Py_None`) + [:ctype:`Py_buffer`] + Like ``"s*"``, but the Python object may also be :ctype:`Py_None`, in which case the ``buf`` member of the :c:type:`Py_buffer` structure is set to ``NULL``. - It is the same as ``s*?`` with the ``buf`` member of the :c:type:`Py_buffer` + It is the same as ``"s*?"`` with the ``buf`` member of the :c:type:`Py_buffer` structure was initialized to ``NULL``. -``z#`` (:class:`str`, read-only :term:`bytes-like object` or ``None``) [const char \*, :c:type:`Py_ssize_t`] - Like ``s#``, but the Python object may also be ``None``, in which case the C - pointer is set to ``NULL``. - It is the same as ``s#?`` with the C pointer was initialized to ``NULL``. +``"z#"`` (:ctype:`PyUnicodeObject\*`, :ctype:`PyBytesObject\*`, + read-only :term:`bytes-like object` or :ctype:`Py_None`) + [:ctype:`const char\*`, :ctype:`int`] + Like ``"s#"``, but the Python object may also be :ctype:`Py_None`, in which + case the C pointer is set to ``NULL``. + It is the same as ``"s#?"`` with the C pointer was initialized to ``NULL``. -``y`` (read-only :term:`bytes-like object`) [const char \*] +``"y"`` (:ctype:`PyBytesObject\*` or read-only :term:`bytes-like object`) + [:ctype:`const char\*`] This format converts a bytes-like object to a C pointer to a :ref:`borrowed ` character string; it does not accept Unicode objects. The bytes buffer must not @@ -137,8 +145,9 @@ There are three ways strings and buffers can be converted to C: 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 +``"y*"`` (:ctype:`PyBytesObject\*`, :ctype:`PyByteArrayObject\*`, or + :term:`bytes-like object`) [:ctype:`Py_buffer\*`] + This variant on ``"s*"`` doesn't accept Unicode objects, only bytes-like objects. **This is the recommended way to accept binary data.** From 43edb2516de034f49b0ba77f63d7d1ee0e583d06 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Wed, 23 Apr 2025 12:38:32 +0100 Subject: [PATCH 2/2] Lint fixup --- Doc/c-api/arg.rst | 31 +++++++++++-------------------- 1 file changed, 11 insertions(+), 20 deletions(-) diff --git a/Doc/c-api/arg.rst b/Doc/c-api/arg.rst index 12681934fd81e3..22df51392729ef 100644 --- a/Doc/c-api/arg.rst +++ b/Doc/c-api/arg.rst @@ -77,7 +77,7 @@ There are three ways strings and buffers can be converted to C: whether the input object is immutable (e.g. whether it would honor a request for a writable buffer, or whether another thread can mutate the data). -``"s"`` (:ctype:`PyUnicodeObject\*`) [:ctype:`const char\*`] +``"s"`` (:c:type:`PyUnicodeObject\*`) [:c:type:`const char\*`] 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. @@ -97,44 +97,36 @@ There are three ways strings and buffers can be converted to C: Previously, :exc:`TypeError` was raised when embedded null code points were encountered in the Python string. -``"s*"`` (:ctype:`PyUnicodeObject\*`, :ctype:`PyBytesObject\*`, - :ctype:`PyByteArrayObject\*` or :term:`bytes-like object`) [:ctype:`Py_buffer`] +``"s*"`` (:c:type:`PyUnicodeObject\*`, :c:type:`PyBytesObject\*`, :c:type:`PyByteArrayObject\*` or :term:`bytes-like object`) [:c:type:`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#"`` (:ctype:`PyUnicodeObject\*`, :ctype:`PyBytesObject\*` or read-only - :term:`bytes-like object`) [:ctype:`const char\*`, :ctype:`int` or - :ctype:`Py_ssize_t`] +``"s#"`` (:c:type:`PyUnicodeObject\*`, :c:type:`PyBytesObject\*` or read-only :term:`bytes-like object`) [:c:type:`const char\*`, :c:type:`int` or :c:type:`Py_ssize_t`] Like ``"s*"``, except that it provides a :ref:`borrowed buffer `. 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 to C strings using ``'utf-8'`` encoding. -``"z"`` (:ctype:`PyUnicodeObject\*` or :ctype:`Py_None`) [:ctype:`const char\*`] - Like ``"s"``, but the Python object may also be :ctype:`Py_None`, +``"z"`` (:c:type:`PyUnicodeObject\*` or :c:type:`Py_None`) [:c:type:`const char\*`] + Like ``"s"``, but the Python object may also be :c:type:`Py_None`, in which case the C pointer is set to ``NULL``. It is the same as ``"s?"`` with the C pointer was initialized to ``NULL``. -``"z*"`` (:ctype:`PyUnicodeObject\*`, :ctype:`PyBytesObject\*`, - :ctype:`PyByteArrayObject\*`, :term:`bytes-like object`, or :ctype:`Py_None`) - [:ctype:`Py_buffer`] - Like ``"s*"``, but the Python object may also be :ctype:`Py_None`, in which case the +``"z*"`` (:c:type:`PyUnicodeObject\*`, :c:type:`PyBytesObject\*`, :c:type:`PyByteArrayObject\*`, :term:`bytes-like object`, or :c:type:`Py_None`) [:c:type:`Py_buffer`] + Like ``"s*"``, but the Python object may also be :c:type:`Py_None`, in which case the ``buf`` member of the :c:type:`Py_buffer` structure is set to ``NULL``. It is the same as ``"s*?"`` with the ``buf`` member of the :c:type:`Py_buffer` structure was initialized to ``NULL``. -``"z#"`` (:ctype:`PyUnicodeObject\*`, :ctype:`PyBytesObject\*`, - read-only :term:`bytes-like object` or :ctype:`Py_None`) - [:ctype:`const char\*`, :ctype:`int`] - Like ``"s#"``, but the Python object may also be :ctype:`Py_None`, in which +``"z#"`` (:c:type:`PyUnicodeObject\*`, :c:type:`PyBytesObject\*`, read-only :term:`bytes-like object` or :c:type:`Py_None`) [:c:type:`const char\*`, :c:type:`int`] + Like ``"s#"``, but the Python object may also be :c:type:`Py_None`, in which case the C pointer is set to ``NULL``. It is the same as ``"s#?"`` with the C pointer was initialized to ``NULL``. -``"y"`` (:ctype:`PyBytesObject\*` or read-only :term:`bytes-like object`) - [:ctype:`const char\*`] +``"y"`` (:c:type:`PyBytesObject\*` or read-only :term:`bytes-like object`) [:c:type:`const char\*`] This format converts a bytes-like object to a C pointer to a :ref:`borrowed ` character string; it does not accept Unicode objects. The bytes buffer must not @@ -145,8 +137,7 @@ There are three ways strings and buffers can be converted to C: Previously, :exc:`TypeError` was raised when embedded null bytes were encountered in the bytes buffer. -``"y*"`` (:ctype:`PyBytesObject\*`, :ctype:`PyByteArrayObject\*`, or - :term:`bytes-like object`) [:ctype:`Py_buffer\*`] +``"y*"`` (:c:type:`PyBytesObject\*`, :c:type:`PyByteArrayObject\*`, or :term:`bytes-like object`) [:c:type:`Py_buffer\*`] This variant on ``"s*"`` doesn't accept Unicode objects, only bytes-like objects. **This is the recommended way to accept binary data.**