update to new C roles and directives
diff --git a/Doc/c-api/arg.rst b/Doc/c-api/arg.rst
index 4f8591b..8fbdc50 100644
--- a/Doc/c-api/arg.rst
+++ b/Doc/c-api/arg.rst
@@ -9,8 +9,8 @@
methods. Additional information and examples are available in
:ref:`extending-index`.
-The first three of these functions described, :cfunc:`PyArg_ParseTuple`,
-:cfunc:`PyArg_ParseTupleAndKeywords`, and :cfunc:`PyArg_Parse`, all use
+The first three of these functions described, :c:func:`PyArg_ParseTuple`,
+:c:func:`PyArg_ParseTupleAndKeywords`, and :c:func:`PyArg_Parse`, all use
*format strings* which are used to tell the function about the expected
arguments. The format strings use the same syntax for each of these
functions.
@@ -38,7 +38,7 @@
raised. Unicode objects are converted to C strings using the default
encoding. If this conversion fails, a :exc:`UnicodeError` is raised.
-``s#`` (string, Unicode or any read buffer compatible object) [const char \*, int (or :ctype:`Py_ssize_t`, see below)]
+``s#`` (string, Unicode or any read buffer compatible object) [const char \*, int (or :c:type:`Py_ssize_t`, see below)]
This variant on ``s`` stores into two C variables, the first one a pointer
to a character string, the second one its length. In this case the Python
string may contain embedded null bytes. Unicode objects pass back a
@@ -47,8 +47,8 @@
a reference to the raw internal data representation.
Starting with Python 2.5 the type of the length argument can be controlled
- by defining the macro :cmacro:`PY_SSIZE_T_CLEAN` before including
- :file:`Python.h`. If the macro is defined, length is a :ctype:`Py_ssize_t`
+ by defining the macro :c:macro:`PY_SSIZE_T_CLEAN` before including
+ :file:`Python.h`. If the macro is defined, length is a :c:type:`Py_ssize_t`
rather than an int.
``s*`` (string, Unicode, or any buffer compatible object) [Py_buffer]
@@ -76,14 +76,14 @@
Convert a Python Unicode object to a C pointer to a NUL-terminated buffer
of 16-bit Unicode (UTF-16) data. As with ``s``, there is no need to
provide storage for the Unicode data buffer; a pointer to the existing
- Unicode data is stored into the :ctype:`Py_UNICODE` pointer variable whose
+ Unicode data is stored into the :c:type:`Py_UNICODE` pointer variable whose
address you pass.
``u#`` (Unicode) [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.
+ :c:type:`Py_UNICODE` array.
``es`` (string, Unicode or character buffer compatible object) [const char \*encoding, char \*\*buffer]
This variant on ``s`` is used for encoding Unicode and objects convertible
@@ -91,18 +91,18 @@
embedded NUL bytes.
This format requires two arguments. The first is only used as input, and
- must be a :ctype:`const char\*` which points to the name of an encoding as
+ must be a :c:type:`const char\*` which points to the name of an encoding as
a NUL-terminated string, or *NULL*, in which case the default encoding is
used. An exception is raised if the named encoding is not known to Python.
- The second argument must be a :ctype:`char\*\*`; the value of the pointer
+ The second argument must be a :c:type:`char\*\*`; the value of the pointer
it references will be set to a buffer with the contents of the argument
text. The text will be encoded in the encoding specified by the first
argument.
- :cfunc:`PyArg_ParseTuple` will allocate a buffer of the needed size, copy
+ :c:func:`PyArg_ParseTuple` will allocate a buffer of the needed size, copy
the encoded data into this buffer and adjust *\*buffer* to reference the
newly allocated storage. The caller is responsible for calling
- :cfunc:`PyMem_Free` to free the allocated buffer after use.
+ :c:func:`PyMem_Free` to free the allocated buffer after use.
``et`` (string, Unicode or character buffer compatible object) [const char \*encoding, char \*\*buffer]
Same as ``es`` except that 8-bit string objects are passed through without
@@ -115,10 +115,10 @@
allows input data which contains NUL characters.
It requires three arguments. The first is only used as input, and must be
- a :ctype:`const char\*` which points to the name of an encoding as a
+ a :c:type:`const char\*` which points to the name of an encoding as a
NUL-terminated string, or *NULL*, in which case the default encoding is
used. An exception is raised if the named encoding is not known to Python.
- The second argument must be a :ctype:`char\*\*`; the value of the pointer
+ The second argument must be a :c:type:`char\*\*`; the value of the pointer
it references will be set to a buffer with the contents of the argument
text. The text will be encoded in the encoding specified by the first
argument. The third argument must be a pointer to an integer; the
@@ -129,11 +129,11 @@
If *\*buffer* points a *NULL* pointer, the function will allocate a buffer
of the needed size, copy the encoded data into this buffer and set
*\*buffer* to reference the newly allocated storage. The caller is
- responsible for calling :cfunc:`PyMem_Free` to free the allocated buffer
+ responsible for calling :c:func:`PyMem_Free` to free the allocated buffer
after usage.
If *\*buffer* points to a non-*NULL* pointer (an already allocated buffer),
- :cfunc:`PyArg_ParseTuple` will use this location as the buffer and
+ :c:func:`PyArg_ParseTuple` will use this location as the buffer and
interpret the initial value of *\*buffer_length* as the buffer size. It
will then copy the encoded data into the buffer and NUL-terminate it. If
the buffer is not large enough, a :exc:`ValueError` will be set.
@@ -148,71 +148,71 @@
``b`` (integer) [unsigned char]
Convert a nonnegative Python integer to an unsigned tiny int, stored in a C
- :ctype:`unsigned char`.
+ :c:type:`unsigned char`.
``B`` (integer) [unsigned char]
Convert a Python integer to a tiny int without overflow checking, stored in
- a C :ctype:`unsigned char`.
+ a C :c:type:`unsigned char`.
.. versionadded:: 2.3
``h`` (integer) [short int]
- Convert a Python integer to a C :ctype:`short int`.
+ Convert a Python integer to a C :c:type:`short int`.
``H`` (integer) [unsigned short int]
- Convert a Python integer to a C :ctype:`unsigned short int`, without
+ Convert a Python integer to a C :c:type:`unsigned short int`, without
overflow checking.
.. versionadded:: 2.3
``i`` (integer) [int]
- Convert a Python integer to a plain C :ctype:`int`.
+ Convert a Python integer to a plain C :c:type:`int`.
``I`` (integer) [unsigned int]
- Convert a Python integer to a C :ctype:`unsigned int`, without overflow
+ Convert a Python integer to a C :c:type:`unsigned int`, without overflow
checking.
.. versionadded:: 2.3
``l`` (integer) [long int]
- Convert a Python integer to a C :ctype:`long int`.
+ Convert a Python integer to a C :c:type:`long int`.
``k`` (integer) [unsigned long]
- Convert a Python integer or long integer to a C :ctype:`unsigned long`
+ Convert a Python integer or long integer to a C :c:type:`unsigned long`
without overflow checking.
.. versionadded:: 2.3
``L`` (integer) [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`
+ Convert a Python integer to a C :c:type:`long long`. This format is only
+ available on platforms that support :c:type:`long long` (or :c:type:`_int64`
on Windows).
``K`` (integer) [unsigned PY_LONG_LONG]
- Convert a Python integer or long integer to a C :ctype:`unsigned long long`
+ Convert a Python integer or long integer to a C :c:type:`unsigned long long`
without overflow checking. This format is only available on platforms that
- support :ctype:`unsigned long long` (or :ctype:`unsigned _int64` on
+ support :c:type:`unsigned long long` (or :c:type:`unsigned _int64` on
Windows).
.. versionadded:: 2.3
``n`` (integer) [Py_ssize_t]
- Convert a Python integer or long integer to a C :ctype:`Py_ssize_t`.
+ Convert a Python integer or long integer to a C :c:type:`Py_ssize_t`.
.. versionadded:: 2.5
``c`` (string of length 1) [char]
Convert a Python character, represented as a string of length 1, to a C
- :ctype:`char`.
+ :c:type:`char`.
``f`` (float) [float]
- Convert a Python floating point number to a C :ctype:`float`.
+ Convert a Python floating point number to a C :c:type:`float`.
``d`` (float) [double]
- Convert a Python floating point number to a C :ctype:`double`.
+ Convert a Python floating point number to a C :c:type:`double`.
``D`` (complex) [Py_complex]
- Convert a Python complex number to a C :ctype:`Py_complex` structure.
+ Convert a Python complex number to a C :c:type:`Py_complex` structure.
``O`` (object) [PyObject \*]
Store a Python object (without any conversion) in a C object pointer. The
@@ -222,20 +222,20 @@
``O!`` (object) [*typeobject*, PyObject \*]
Store a Python object in a C object pointer. This is similar to ``O``, but
takes two C arguments: the first is the address of a Python type object,
- the second is the address of the C variable (of type :ctype:`PyObject\*`)
+ the second is the address of the C variable (of type :c:type:`PyObject\*`)
into which the object pointer is stored. If the Python object does not
have the required type, :exc:`TypeError` is raised.
``O&`` (object) [*converter*, *anything*]
Convert a Python object to a C variable through a *converter* function.
This takes two arguments: the first is a function, the second is the
- address of a C variable (of arbitrary type), converted to :ctype:`void \*`.
+ address of a C variable (of arbitrary type), converted to :c:type:`void \*`.
The *converter* function in turn is called as follows::
status = converter(object, address);
where *object* is the Python object to be converted and *address* is the
- :ctype:`void\*` argument that was passed to the :cfunc:`PyArg_Parse\*`
+ :c:type:`void\*` argument that was passed to the :c:func:`PyArg_Parse\*`
function. The returned *status* should be ``1`` for a successful
conversion and ``0`` if the conversion has failed. When the conversion
fails, the *converter* function should raise an exception and leave the
@@ -244,17 +244,17 @@
``S`` (string) [PyStringObject \*]
Like ``O`` but requires that the Python object is a string object. Raises
:exc:`TypeError` if the object is not a string object. The C variable may
- also be declared as :ctype:`PyObject\*`.
+ also be declared as :c:type:`PyObject\*`.
``U`` (Unicode string) [PyUnicodeObject \*]
Like ``O`` but requires that the Python object is a Unicode object. Raises
:exc:`TypeError` if the object is not a Unicode object. The C variable may
- also be declared as :ctype:`PyObject\*`.
+ also be declared as :c:type:`PyObject\*`.
``t#`` (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.
+ interface. The :c:type:`char\*` variable is set to point to the first byte
+ of the buffer, and the :c:type:`int` is set to the length of the buffer.
Only single-segment buffer objects are accepted; :exc:`TypeError` is raised
for all others.
@@ -266,8 +266,8 @@
``w#`` (read-write character buffer) [char \*, Py_ssize_t]
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:`Py_ssize_t` is set to the length of the
+ interface. The :c:type:`char \*` variable is set to point to the first byte
+ of the buffer, and the :c:type:`Py_ssize_t` is set to the length of the
buffer. Only single-segment buffer objects are accepted; :exc:`TypeError`
is raised for all others.
@@ -302,13 +302,13 @@
Indicates that the remaining arguments in the Python argument list are
optional. The C variables corresponding to optional arguments should be
initialized to their default value --- when an optional argument is not
- specified, :cfunc:`PyArg_ParseTuple` does not touch the contents of the
+ specified, :c:func:`PyArg_ParseTuple` does not touch the contents of the
corresponding C variable(s).
``:``
The list of format units ends here; the string after the colon is used as
the function name in error messages (the "associated value" of the
- exception that :cfunc:`PyArg_ParseTuple` raises).
+ exception that :c:func:`PyArg_ParseTuple` raises).
``;``
The list of format units ends here; the string after the semicolon is used
@@ -325,40 +325,40 @@
should match what is specified for the corresponding format unit in that case.
For the conversion to succeed, the *arg* object must match the format and the
-format must be exhausted. On success, the :cfunc:`PyArg_Parse\*` functions
+format must be exhausted. On success, the :c:func:`PyArg_Parse\*` functions
return true, otherwise they return false and raise an appropriate exception.
-When the :cfunc:`PyArg_Parse\*` functions fail due to conversion failure in
+When the :c:func:`PyArg_Parse\*` functions fail due to conversion failure in
one of the format units, the variables at the addresses corresponding to that
and the following format units are left untouched.
-.. cfunction:: int PyArg_ParseTuple(PyObject *args, const char *format, ...)
+.. c:function:: int PyArg_ParseTuple(PyObject *args, const char *format, ...)
Parse the parameters of a function that takes only positional parameters
into local variables. Returns true on success; on failure, it returns
false and raises the appropriate exception.
-.. cfunction:: int PyArg_VaParse(PyObject *args, const char *format, va_list vargs)
+.. c:function:: int PyArg_VaParse(PyObject *args, const char *format, va_list vargs)
- Identical to :cfunc:`PyArg_ParseTuple`, except that it accepts a va_list
+ Identical to :c:func:`PyArg_ParseTuple`, except that it accepts a va_list
rather than a variable number of arguments.
-.. cfunction:: int PyArg_ParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], ...)
+.. c:function:: int PyArg_ParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], ...)
Parse the parameters of a function that takes both positional and keyword
parameters into local variables. Returns true on success; on failure, it
returns false and raises the appropriate exception.
-.. cfunction:: int PyArg_VaParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], va_list vargs)
+.. c:function:: int PyArg_VaParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], va_list vargs)
- Identical to :cfunc:`PyArg_ParseTupleAndKeywords`, except that it accepts a
+ Identical to :c:func:`PyArg_ParseTupleAndKeywords`, except that it accepts a
va_list rather than a variable number of arguments.
-.. cfunction:: int PyArg_Parse(PyObject *args, const char *format, ...)
+.. c:function:: int PyArg_Parse(PyObject *args, const char *format, ...)
Function used to deconstruct the argument lists of "old-style" functions
--- these are functions which use the :const:`METH_OLDARGS` parameter
@@ -369,7 +369,7 @@
purpose.
-.. cfunction:: int PyArg_UnpackTuple(PyObject *args, const char *name, Py_ssize_t min, Py_ssize_t max, ...)
+.. c:function:: int PyArg_UnpackTuple(PyObject *args, const char *name, Py_ssize_t min, Py_ssize_t max, ...)
A simpler form of parameter retrieval which does not use a format string to
specify the types of the arguments. Functions which use this method to
@@ -378,7 +378,7 @@
should be passed as *args*; it must actually be a tuple. The length of the
tuple must be at least *min* and no more than *max*; *min* and *max* may be
equal. Additional arguments must be passed to the function, each of which
- should be a pointer to a :ctype:`PyObject\*` variable; these will be filled
+ should be a pointer to a :c:type:`PyObject\*` variable; these will be filled
in with the values from *args*; they will contain borrowed references. The
variables which correspond to optional parameters not given by *args* will
not be filled in; these should be initialized by the caller. This function
@@ -401,26 +401,26 @@
return result;
}
- The call to :cfunc:`PyArg_UnpackTuple` in this example is entirely
- equivalent to this call to :cfunc:`PyArg_ParseTuple`::
+ The call to :c:func:`PyArg_UnpackTuple` in this example is entirely
+ equivalent to this call to :c:func:`PyArg_ParseTuple`::
PyArg_ParseTuple(args, "O|O:ref", &object, &callback)
.. versionadded:: 2.2
.. versionchanged:: 2.5
- This function used an :ctype:`int` type for *min* and *max*. This might
+ This function used an :c:type:`int` type for *min* and *max*. This might
require changes in your code for properly supporting 64-bit systems.
-.. cfunction:: PyObject* Py_BuildValue(const char *format, ...)
+.. c:function:: PyObject* Py_BuildValue(const char *format, ...)
Create a new value based on a format string similar to those accepted by
- the :cfunc:`PyArg_Parse\*` family of functions and a sequence of values.
+ the :c:func:`PyArg_Parse\*` family of functions and a sequence of values.
Returns the value or *NULL* in the case of an error; an exception will be
raised if *NULL* is returned.
- :cfunc:`Py_BuildValue` does not always build a tuple. It builds a tuple
+ :c:func:`Py_BuildValue` does not always build a tuple. It builds a tuple
only if its format string contains two or more format units. If the format
string is empty, it returns ``None``; if it contains exactly one format
unit, it returns whatever object is described by that format unit. To
@@ -430,10 +430,10 @@
When memory buffers are passed as parameters to supply data to build
objects, as for the ``s`` and ``s#`` formats, the required data is copied.
Buffers provided by the caller are never referenced by the objects created
- by :cfunc:`Py_BuildValue`. In other words, if your code invokes
- :cfunc:`malloc` and passes the allocated memory to :cfunc:`Py_BuildValue`,
- your code is responsible for calling :cfunc:`free` for that memory once
- :cfunc:`Py_BuildValue` returns.
+ by :c:func:`Py_BuildValue`. In other words, if your code invokes
+ :c:func:`malloc` and passes the allocated memory to :c:func:`Py_BuildValue`,
+ your code is responsible for calling :c:func:`free` for that memory once
+ :c:func:`Py_BuildValue` returns.
In the following description, the quoted form is the format unit; the entry
in (round) parentheses is the Python object type that the format unit will
@@ -469,62 +469,62 @@
length is ignored and ``None`` is returned.
``i`` (integer) [int]
- Convert a plain C :ctype:`int` to a Python integer object.
+ Convert a plain C :c:type:`int` to a Python integer object.
``b`` (integer) [char]
- Convert a plain C :ctype:`char` to a Python integer object.
+ Convert a plain C :c:type:`char` to a Python integer object.
``h`` (integer) [short int]
- Convert a plain C :ctype:`short int` to a Python integer object.
+ Convert a plain C :c:type:`short int` to a Python integer object.
``l`` (integer) [long int]
- Convert a C :ctype:`long int` to a Python integer object.
+ Convert a C :c:type:`long int` to a Python integer object.
``B`` (integer) [unsigned char]
- Convert a C :ctype:`unsigned char` to a Python integer object.
+ Convert a C :c:type:`unsigned char` to a Python integer object.
``H`` (integer) [unsigned short int]
- Convert a C :ctype:`unsigned short int` to a Python integer object.
+ Convert a C :c:type:`unsigned short int` to a Python integer object.
``I`` (integer/long) [unsigned int]
- Convert a C :ctype:`unsigned int` to a Python integer object or a Python
+ Convert a C :c:type:`unsigned int` to a Python integer object or a Python
long integer object, if it is larger than ``sys.maxint``.
``k`` (integer/long) [unsigned long]
- Convert a C :ctype:`unsigned long` to a Python integer object or a
+ Convert a C :c:type:`unsigned long` to a Python integer object or a
Python long integer object, if it is larger than ``sys.maxint``.
``L`` (long) [PY_LONG_LONG]
- Convert a C :ctype:`long long` to a Python long integer object. Only
- available on platforms that support :ctype:`long long`.
+ Convert a C :c:type:`long long` to a Python long integer object. Only
+ available on platforms that support :c:type:`long long`.
``K`` (long) [unsigned PY_LONG_LONG]
- Convert a C :ctype:`unsigned long long` to a Python long integer object.
- Only available on platforms that support :ctype:`unsigned long long`.
+ Convert a C :c:type:`unsigned long long` to a Python long integer object.
+ Only available on platforms that support :c:type:`unsigned long long`.
``n`` (int) [Py_ssize_t]
- Convert a C :ctype:`Py_ssize_t` to a Python integer or long integer.
+ Convert a C :c:type:`Py_ssize_t` to a Python integer or long integer.
.. versionadded:: 2.5
``c`` (string of length 1) [char]
- Convert a C :ctype:`int` representing a character to a Python string of
+ Convert a C :c:type:`int` representing a character to a Python string of
length 1.
``d`` (float) [double]
- Convert a C :ctype:`double` to a Python floating point number.
+ Convert a C :c:type:`double` to a Python floating point number.
``f`` (float) [float]
Same as ``d``.
``D`` (complex) [Py_complex \*]
- Convert a C :ctype:`Py_complex` structure to a Python complex number.
+ Convert a C :c:type:`Py_complex` structure to a Python complex number.
``O`` (object) [PyObject \*]
Pass a Python object untouched (except for its reference count, which is
incremented by one). If the object passed in is a *NULL* pointer, it is
assumed that this was caused because the call producing the argument
- found an error and set an exception. Therefore, :cfunc:`Py_BuildValue`
+ found an error and set an exception. Therefore, :c:func:`Py_BuildValue`
will return *NULL* but won't raise an exception. If no exception has
been raised yet, :exc:`SystemError` is set.
@@ -539,7 +539,7 @@
``O&`` (object) [*converter*, *anything*]
Convert *anything* to a Python object through a *converter* function.
The function is called with *anything* (which should be compatible with
- :ctype:`void \*`) as its argument and should return a "new" Python
+ :c:type:`void \*`) as its argument and should return a "new" Python
object, or *NULL* if an error occurred.
``(items)`` (tuple) [*matching-items*]
@@ -558,7 +558,7 @@
If there is an error in the format string, the :exc:`SystemError` exception
is set and *NULL* returned.
-.. cfunction:: PyObject* Py_VaBuildValue(const char *format, va_list vargs)
+.. c:function:: PyObject* Py_VaBuildValue(const char *format, va_list vargs)
- Identical to :cfunc:`Py_BuildValue`, except that it accepts a va_list
+ Identical to :c:func:`Py_BuildValue`, except that it accepts a va_list
rather than a variable number of arguments.