Issue #8925: fix types of Py_Parse*() and Py_BuildValue() functions

 * Add links to Python types
 * Replace "string" by bytes or str
 * Replace "long" by "int"
 * Specify the default encoding
 * Fix reST syntax ("..note ::")
 * etc.

1 files changed, 91 insertions, 89 deletions

diff --git a/Doc/c-api/arg.rst b/Doc/c-api/arg.rst
index 84e27c2..c8d9851 100644
--- a/Doc/c-api/arg.rst
+++ b/Doc/c-api/arg.rst
@@ -53,13 +53,13 @@ Unless otherwise stated, buffers are not NUL-terminated.
    drop int support.  It is best to always define :cmacro:`PY_SSIZE_T_CLEAN`.
 
 
-``s`` (Unicode object) [const char \*]
+``s`` (:class:`str`) [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.
    The Python string must not contain embedded NUL bytes; if it does,
    a :exc:`TypeError` exception is raised. Unicode objects are converted
-   to C strings using the default encoding.  If this conversion fails, a
+   to C strings using ``'utf-8'`` encoding. If this conversion fails, a
    :exc:`UnicodeError` is raised.
 
    .. note::
@@ -68,111 +68,112 @@ Unless otherwise stated, buffers are not NUL-terminated.
       preferrable to use the ``O&`` format with :cfunc:`PyUnicode_FSConverter`
       as *converter*.
 
-``s*`` (Unicode object or any buffer compatible object) [Py_buffer]
+``s*`` (:class:`str`, :class:`bytes`, :class:`bytearray` or buffer compatible object) [Py_buffer]
    This format accepts Unicode objects as well as objects supporting the
-   buffer protocol (such as :class:`bytes` or :class:`bytearray` objects).
+   buffer protocol.
    It fills a :ctype:`Py_buffer` structure provided by the caller.
-   Unicode objects are converted to C strings using the default encoding.
    In this case the resulting C string may contain embedded NUL bytes.
+   Unicode objects are converted to C strings using ``'utf-8'`` encoding.
 
-``s#`` (string, Unicode or any read buffer compatible object) [const char \*, int or :ctype:`Py_ssize_t`]
+``s#`` (:class:`str`, :class:`bytes` or read-only buffer compatible object) [const char \*, int or :ctype:`Py_ssize_t`]
    Like ``s*``, except that it doesn't accept mutable buffer-like objects
    such as :class:`bytearray`.  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.
+   The string may contain embedded null bytes. Unicode objects are converted
+   to C strings using ``'utf-8'`` encoding.
 
-``z`` (Unicode object or ``None``) [const char \*]
+``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*.
 
-``z*`` (Unicode object or ``None`` or any buffer compatible object) [Py_buffer]
+``z*`` (:class:`str`, :class:`bytes`, :class:`bytearray`, buffer compatible object or ``None``) [Py_buffer]
    Like ``s*``, but the Python object may also be ``None``, in which case the
    ``buf`` member of the :ctype:`Py_buffer` structure is set to *NULL*.
 
-``z#`` (Unicode object or ``None`` or any read buffer compatible object) [const char \*, int]
+``z#`` (:class:`str`, :class:`bytes`, read-only buffer compatible object or ``None``) [const char \*, int]
    Like ``s#``, but the Python object may also be ``None``, in which case the C
    pointer is set to *NULL*.
 
-``y`` (bytes object) [const char \*]
+``y`` (:class:`bytes`) [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`
    exception is raised.
 
-``y*`` (any buffer compatible object) [Py_buffer \*]
+``y*`` (:class:`bytes`, :class:`bytearray` or buffer compatible object) [Py_buffer \*]
    This variant on ``s*`` doesn't accept Unicode objects, only objects
    supporting the buffer protocol.  **This is the recommended way to accept
    binary data.**
 
-``y#`` (bytes object) [const char \*, int]
+``y#`` (:class:`bytes`) [const char \*, int]
    This variant on ``s#`` doesn't accept Unicode objects, only bytes-like
    objects.
 
-``S`` (bytes object) [PyBytesObject \*]
+``S`` (:class:`bytes`) [PyBytesObject \*]
    Requires that the Python object is a :class:`bytes` object, without
    attempting any conversion.  Raises :exc:`TypeError` if the object is not
    a bytes object.  The C variable may also be declared as :ctype:`PyObject\*`.
 
-``Y`` (bytearray object) [PyByteArrayObject \*]
+``Y`` (:class:`bytearray`) [PyByteArrayObject \*]
    Requires that the Python object is a :class:`bytearray` object, without
    attempting any conversion.  Raises :exc:`TypeError` if the object is not
-   a bytearray object.  The C variable may also be declared as :ctype:`PyObject\*`.
+   a :class:`bytearray` object. The C variable may also be declared as :ctype:`PyObject\*`.
 
-``u`` (Unicode object) [Py_UNICODE \*]
+``u`` (:class:`str`) [Py_UNICODE \*]
    Convert a Python Unicode object to a C pointer to a NUL-terminated buffer of
    Unicode characters.  You must pass the address of a :ctype:`Py_UNICODE`
    pointer variable, which will be filled with the pointer to an existing
    Unicode buffer.  Please note that the width of a :ctype:`Py_UNICODE`
    character depends on compilation options (it is either 16 or 32 bits).
 
-   ..note ::
+   .. 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.
 
-``u#`` (Unicode object) [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
    Unicode data buffer, the second one its length. Non-Unicode objects are handled
    by interpreting their read-buffer pointer as pointer to a :ctype:`Py_UNICODE`
    array.
 
-``Z`` (Unicode or ``None``) [Py_UNICODE \*]
+``Z`` (:class:`str` or ``None``) [Py_UNICODE \*]
    Like ``u``, but the Python object may also be ``None``, in which case the
    :ctype:`Py_UNICODE` pointer is set to *NULL*.
 
-``Z#`` (Unicode or ``None``) [Py_UNICODE \*, int]
+``Z#`` (:class:`str` or ``None``) [Py_UNICODE \*, int]
    Like ``u#``, but the Python object may also be ``None``, in which case the
    :ctype:`Py_UNICODE` pointer is set to *NULL*.
 
-``U`` (Unicode object) [PyUnicodeObject \*]
+``U`` (:class:`str`) [PyUnicodeObject \*]
    Requires that the Python object is a Unicode object, without attempting
    any conversion.  Raises :exc:`TypeError` if the object is not a Unicode
    object.  The C variable may also be declared as :ctype:`PyObject\*`.
 
-``t#`` (read-only character buffer) [char \*, int]
+``t#`` (:class:`bytes`, :class:`bytearray` or read-only character buffer) [char \*, int]
    Like ``s#``, but accepts any object which implements the read-only buffer
    interface.  The :ctype:`char\*` variable is set to point to the first byte of
    the buffer, and the :ctype:`int` is set to the length of the buffer.  Only
    single-segment buffer objects are accepted; :exc:`TypeError` is raised for all
    others.
 
-``w`` (read-write character buffer) [char \*]
+``w`` (:class:`bytearray` or read-write character buffer) [char \*]
    Similar to ``s``, but accepts any object which implements the read-write buffer
    interface.  The caller must determine the length of the buffer by other means,
    or use ``w#`` instead.  Only single-segment buffer objects are accepted;
    :exc:`TypeError` is raised for all others.
 
-``w*`` (read-write byte-oriented buffer) [Py_buffer]
+``w*`` (:class:`bytearray` or read-write byte-oriented buffer) [Py_buffer]
    This is to ``w`` what ``s*`` is to ``s``.
 
-``w#`` (read-write character buffer) [char \*, int]
+``w#`` (:class:`bytearray` or read-write character buffer) [char \*, int]
    Like ``s#``, but accepts any object which implements the read-write buffer
    interface.  The :ctype:`char \*` variable is set to point to the first byte
    of the buffer, and the :ctype:`int` is set to the length of the buffer.
    Only single-segment buffer objects are accepted; :exc:`TypeError` is raised
    for all others.
 
-``es`` (string, Unicode object or character buffer compatible object) [const char \*encoding, char \*\*buffer]
+``es`` (:class:`str`) [const char \*encoding, char \*\*buffer]
    This variant on ``s`` is used for encoding Unicode and objects convertible to
    Unicode into a character buffer. It only works for encoded data without embedded
    NUL bytes.
@@ -190,12 +191,12 @@ Unless otherwise stated, buffers are not NUL-terminated.
    allocated storage.  The caller is responsible for calling :cfunc:`PyMem_Free` to
    free the allocated buffer after use.
 
-``et`` (string, Unicode object or character buffer compatible object) [const char \*encoding, char \*\*buffer]
-   Same as ``es`` except that 8-bit string objects are passed through without
-   recoding them.  Instead, the implementation assumes that the string object uses
+``et`` (:class:`str`, :class:`bytes` or :class:`bytearray`) [const char \*encoding, char \*\*buffer]
+   Same as ``es`` except that byte string objects are passed through without
+   recoding them.  Instead, the implementation assumes that the byte string object uses
    the encoding passed in as parameter.
 
-``es#`` (string, Unicode object or character buffer compatible object) [const char \*encoding, char \*\*buffer, int \*buffer_length]
+``es#`` (:class:`str`) [const char \*encoding, char \*\*buffer, int \*buffer_length]
    This variant on ``s#`` is used for encoding Unicode and objects convertible to
    Unicode into a character buffer.  Unlike the ``es`` format, this variant allows
    input data which contains NUL characters.
@@ -226,71 +227,71 @@ Unless otherwise stated, buffers are not NUL-terminated.
    In both cases, *\*buffer_length* is set to the length of the encoded data
    without the trailing NUL byte.
 
-``et#`` (string, Unicode object or character buffer compatible object) [const char \*encoding, char \*\*buffer, int \*buffer_length]
-   Same as ``es#`` except that string objects are passed through without recoding
-   them. Instead, the implementation assumes that the string object uses the
+``et#`` (:class:`str`, :class:`bytes` or :class:`bytearray`) [const char \*encoding, char \*\*buffer, int \*buffer_length]
+   Same as ``es#`` except that byte string objects are passed through without recoding
+   them. Instead, the implementation assumes that the byte string object uses the
    encoding passed in as parameter.
 
 Numbers
 -------
 
-``b`` (integer) [unsigned char]
+``b`` (:class:`int`) [unsigned char]
    Convert a nonnegative Python integer to an unsigned tiny int, stored in a C
    :ctype:`unsigned char`.
 
-``B`` (integer) [unsigned char]
+``B`` (:class:`int`) [unsigned char]
    Convert a Python integer to a tiny int without overflow checking, stored in a C
    :ctype:`unsigned char`.
 
-``h`` (integer) [short int]
+``h`` (:class:`int`) [short int]
    Convert a Python integer to a C :ctype:`short int`.
 
-``H`` (integer) [unsigned short int]
+``H`` (:class:`int`) [unsigned short int]
    Convert a Python integer to a C :ctype:`unsigned short int`, without overflow
    checking.
 
-``i`` (integer) [int]
+``i`` (:class:`int`) [int]
    Convert a Python integer to a plain C :ctype:`int`.
 
-``I`` (integer) [unsigned int]
+``I`` (:class:`int`) [unsigned int]
    Convert a Python integer to a C :ctype:`unsigned int`, without overflow
    checking.
 
-``l`` (integer) [long int]
+``l`` (:class:`int`) [long int]
    Convert a Python integer to a C :ctype:`long int`.
 
-``k`` (integer) [unsigned long]
+``k`` (:class:`int`) [unsigned long]
    Convert a Python integer to a C :ctype:`unsigned long` without
    overflow checking.
 
-``L`` (integer) [PY_LONG_LONG]
+``L`` (:class:`int`) [PY_LONG_LONG]
    Convert a Python integer to a C :ctype:`long long`.  This format is only
    available on platforms that support :ctype:`long long` (or :ctype:`_int64` on
    Windows).
 
-``K`` (integer) [unsigned PY_LONG_LONG]
+``K`` (:class:`int`) [unsigned PY_LONG_LONG]
    Convert a Python integer to a C :ctype:`unsigned long long`
    without overflow checking.  This format is only available on platforms that
    support :ctype:`unsigned long long` (or :ctype:`unsigned _int64` on Windows).
 
-``n`` (integer) [Py_ssize_t]
+``n`` (:class:`int`) [Py_ssize_t]
    Convert a Python integer to a C :ctype:`Py_ssize_t`.
 
-``c`` (bytes object of length 1) [char]
+``c`` (:class:`bytes` of length 1) [char]
    Convert a Python byte, represented as a :class:`bytes` object of length 1,
    to a C :ctype:`char`.
 
-``C`` (Unicode object of length 1) [int]
-   Convert a Python character, represented as a :class:`str`: object of
+``C`` (:class:`str` of length 1) [int]
+   Convert a Python character, represented as a :class:`str` object of
    length 1, to a C :ctype:`int`.
 
-``f`` (float) [float]
+``f`` (:class:`float`) [float]
    Convert a Python floating point number to a C :ctype:`float`.
 
-``d`` (float) [double]
+``d`` (:class:`float`) [double]
    Convert a Python floating point number to a C :ctype:`double`.
 
-``D`` (complex) [Py_complex]
+``D`` (:class:`complex`) [Py_complex]
    Convert a Python complex number to a C :ctype:`Py_complex` structure.
 
 Other objects
@@ -330,7 +331,7 @@ Other objects
    .. versionchanged:: 3.1
       Py_CLEANUP_SUPPORTED was added.
 
-``(items)`` (tuple) [*matching-items*]
+``(items)`` (:class:`tuple`) [*matching-items*]
    The object must be a Python sequence whose length is the number of format units
    in *items*.  The C arguments must correspond to the individual format units in
    *items*.  Format units for sequences may be nested.
@@ -498,93 +499,94 @@ Building values
    not within format units such as ``s#``).  This can be used to make long format
    strings a tad more readable.
 
-   ``s`` (string) [char \*]
-      Convert a null-terminated C string to a Python object.  If the C string pointer
-      is *NULL*, ``None`` is used.
+   ``s`` (:class:`str` or ``None``) [char \*]
+      Convert a null-terminated C string to a Python object using ``'utf-8'``
+      encoding. If the C string pointer is *NULL*, ``None`` is used.
 
-   ``s#`` (string) [char \*, int]
-      Convert a C string and its length to a Python object.  If the C string pointer
-      is *NULL*, the length is ignored and ``None`` is returned.
+   ``s#`` (:class:`str` or ``None``) [char \*, int]
+      Convert a C string and its length to a Python object using ``'utf-8'``
+      encoding. If the C string pointer is *NULL*, the length is ignored and
+      ``None`` is returned.
 
-   ``y`` (bytes) [char \*]
+   ``y`` (:class:`bytes`) [char \*]
       This converts a C string to a Python :func:`bytes` object.  If the C
       string pointer is *NULL*, ``None`` is returned.
 
-   ``y#`` (bytes) [char \*, int]
+   ``y#`` (:class:`bytes`) [char \*, int]
       This converts a C string and its lengths to a Python object.  If the C
       string pointer is *NULL*, ``None`` is returned.
 
-   ``z`` (string or ``None``) [char \*]
+   ``z`` (:class:`str` or ``None``) [char \*]
       Same as ``s``.
 
-   ``z#`` (string or ``None``) [char \*, int]
+   ``z#`` (:class:`str` or ``None``) [char \*, int]
       Same as ``s#``.
 
-   ``u`` (Unicode string) [Py_UNICODE \*]
+   ``u`` (:class:`str`) [Py_UNICODE \*]
       Convert a null-terminated buffer of Unicode (UCS-2 or UCS-4) data to a Python
       Unicode object.  If the Unicode buffer pointer is *NULL*, ``None`` is returned.
 
-   ``u#`` (Unicode string) [Py_UNICODE \*, int]
+   ``u#`` (:class:`str`) [Py_UNICODE \*, int]
       Convert a Unicode (UCS-2 or UCS-4) data buffer and its length to a Python
       Unicode object.   If the Unicode buffer pointer is *NULL*, the length is ignored
       and ``None`` is returned.
 
-   ``U`` (string) [char \*]
+   ``U`` (:class:`str` or ``None``) [char \*]
       Same as ``s``.
 
-   ``U#`` (string) [char \*, int]
+   ``U#`` (:class:`str` or ``None``) [char \*, int]
       Same as ``s#``.
 
-   ``i`` (integer) [int]
+   ``i`` (:class:`int`) [int]
       Convert a plain C :ctype:`int` to a Python integer object.
 
-   ``b`` (integer) [char]
+   ``b`` (:class:`int`) [char]
       Convert a plain C :ctype:`char` to a Python integer object.
 
-   ``h`` (integer) [short int]
+   ``h`` (:class:`int`) [short int]
       Convert a plain C :ctype:`short int` to a Python integer object.
 
-   ``l`` (integer) [long int]
+   ``l`` (:class:`int`) [long int]
       Convert a C :ctype:`long int` to a Python integer object.
 
-   ``B`` (integer) [unsigned char]
+   ``B`` (:class:`int`) [unsigned char]
       Convert a C :ctype:`unsigned char` to a Python integer object.
 
-   ``H`` (integer) [unsigned short int]
+   ``H`` (:class:`int`) [unsigned short int]
       Convert a C :ctype:`unsigned short int` to a Python integer object.
 
-   ``I`` (integer) [unsigned int]
+   ``I`` (:class:`int`) [unsigned int]
       Convert a C :ctype:`unsigned int` to a Python integer object.
 
-   ``k`` (integer) [unsigned long]
+   ``k`` (:class:`int`) [unsigned long]
       Convert a C :ctype:`unsigned long` to a Python integer object.
 
-   ``L`` (long) [PY_LONG_LONG]
+   ``L`` (:class:`int`) [PY_LONG_LONG]
       Convert a C :ctype:`long long` to a Python integer object. Only available
       on platforms that support :ctype:`long long`.
 
-   ``K`` (long) [unsigned PY_LONG_LONG]
+   ``K`` (:class:`int`) [unsigned PY_LONG_LONG]
       Convert a C :ctype:`unsigned long long` to a Python integer object. Only
       available on platforms that support :ctype:`unsigned long long`.
 
-   ``n`` (int) [Py_ssize_t]
+   ``n`` (:class:`int`) [Py_ssize_t]
       Convert a C :ctype:`Py_ssize_t` to a Python integer.
 
-   ``c`` (string of length 1) [char]
-      Convert a C :ctype:`int` representing a byte to a Python byte string of
+   ``c`` (:class:`bytes` of length 1) [char]
+      Convert a C :ctype:`int` representing a byte to a Python :class:`bytes` object of
       length 1.
 
-   ``C`` (string of length 1) [int]
-      Convert a C :ctype:`int` representing a character to Python unicode
-      string of length 1.
+   ``C`` (:class:`str` of length 1) [int]
+      Convert a C :ctype:`int` representing a character to Python :class:`str`
+      object of length 1.
 
-   ``d`` (float) [double]
+   ``d`` (:class:`float`) [double]
       Convert a C :ctype:`double` to a Python floating point number.
 
-   ``f`` (float) [float]
-      Same as ``d``.
+   ``f`` (:class:`float`) [float]
+      Convert a C :ctype:`float` to a Python floating point number.
 
-   ``D`` (complex) [Py_complex \*]
+   ``D`` (:class:`complex`) [Py_complex \*]
       Convert a C :ctype:`Py_complex` structure to a Python complex number.
 
    ``O`` (object) [PyObject \*]
@@ -609,13 +611,13 @@ Building values
       \*`) as its argument and should return a "new" Python object, or *NULL* if an
       error occurred.
 
-   ``(items)`` (tuple) [*matching-items*]
+   ``(items)`` (:class:`tuple`) [*matching-items*]
       Convert a sequence of C values to a Python tuple with the same number of items.
 
-   ``[items]`` (list) [*matching-items*]
+   ``[items]`` (:class:`list`) [*matching-items*]
       Convert a sequence of C values to a Python list with the same number of items.
 
-   ``{items}`` (dictionary) [*matching-items*]
+   ``{items}`` (:class:`dict`) [*matching-items*]
       Convert a sequence of C values to a Python dictionary.  Each pair of consecutive
       C values adds one item to the dictionary, serving as key and value,
       respectively.