Commit part 1

Author: StanFromIreland

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
       <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`
+      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 <c-arg-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 <c-arg-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 <c-arg-borrowed-buffer>` 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.**