mirrors/cpython
0
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-01-19 06:54:52 +08:00
Code Issues Packages Projects Releases Wiki Activity

bpo-38600: Change the mark up of NULL in the C API documentation. (GH-16950)

Browse Source 
Replace all *NULL* with ``NULL``.
This commit is contained in:
Serhiy Storchaka 2019-10-30 12:03:20 +02:00 committed by GitHub
parent da6ce58dd5
commit 25fc088607
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
55 changed files with 728 additions and 728 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
Doc/c-api/arg.rst
View File

@ -50,7 +50,7 @@ Unless otherwise stated, buffers are not NUL-terminated.
Some formats require a read-only :term:`bytes-like object`, and set a Some formats require a read-only :term:`bytes-like object`, and set a
pointer instead of a buffer structure. They work by checking that pointer instead of a buffer structure. They work by checking that
the object's :c:member:`PyBufferProcs.bf_releasebuffer` field is *NULL*, the object's :c:member:`PyBufferProcs.bf_releasebuffer` field is ``NULL``,
which disallows mutable objects such as :class:`bytearray`. which disallows mutable objects such as :class:`bytearray`.
.. note:: .. note::
@ -99,15 +99,15 @@ which disallows mutable objects such as :class:`bytearray`.
``z`` (:class:`str` 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 Like ``s``, but the Python object may also be ``None``, in which case the C
pointer is set to *NULL*. pointer is set to ``NULL``.
``z*`` (:class:`str`, :term:`bytes-like object` or ``None``) [Py_buffer] ``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 Like ``s*``, but the Python object may also be ``None``, in which case the
``buf`` member of the :c:type:`Py_buffer` structure is set to *NULL*. ``buf`` member of the :c:type:`Py_buffer` structure is set to ``NULL``.
``z#`` (:class:`str`, read-only :term:`bytes-like object` or ``None``) [const char \*, int] ``z#`` (:class:`str`, read-only :term:`bytes-like object` or ``None``) [const char \*, int]
Like ``s#``, but the Python object may also be ``None``, in which case the C Like ``s#``, but the Python object may also be ``None``, in which case the C
pointer is set to *NULL*. pointer is set to ``NULL``.
``y`` (read-only :term:`bytes-like object`) [const char \*] ``y`` (read-only :term:`bytes-like object`) [const char \*]
This format converts a bytes-like object to a C pointer to a character This format converts a bytes-like object to a C pointer to a character
@ -166,7 +166,7 @@ which disallows mutable objects such as :class:`bytearray`.
``Z`` (:class:`str` or ``None``) [const Py_UNICODE \*] ``Z`` (:class:`str` or ``None``) [const Py_UNICODE \*]
Like ``u``, but the Python object may also be ``None``, in which case the Like ``u``, but the Python object may also be ``None``, in which case the
:c:type:`Py_UNICODE` pointer is set to *NULL*. :c:type:`Py_UNICODE` pointer is set to ``NULL``.
.. deprecated-removed:: 3.3 4.0 .. deprecated-removed:: 3.3 4.0
Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using
@ -174,7 +174,7 @@ which disallows mutable objects such as :class:`bytearray`.
``Z#`` (:class:`str` or ``None``) [const Py_UNICODE \*, int] ``Z#`` (:class:`str` or ``None``) [const Py_UNICODE \*, int]
Like ``u#``, but the Python object may also be ``None``, in which case the Like ``u#``, but the Python object may also be ``None``, in which case the
:c:type:`Py_UNICODE` pointer is set to *NULL*. :c:type:`Py_UNICODE` pointer is set to ``NULL``.
.. deprecated-removed:: 3.3 4.0 .. deprecated-removed:: 3.3 4.0
Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using
@ -197,7 +197,7 @@ which disallows mutable objects such as :class:`bytearray`.
This format requires two arguments. The first is only used as input, and This format requires two arguments. The first is only used as input, and
must be a :c:type:`const char\*` which points to the name of an encoding as a 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 ``'utf-8'`` encoding is used. NUL-terminated string, or ``NULL``, in which case ``'utf-8'`` encoding is used.
An exception is raised if the named encoding is not known to Python. The An exception is raised if the named encoding is not known to Python. The
second argument must be a :c:type:`char\*\*`; the value of the pointer it 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. references will be set to a buffer with the contents of the argument text.
@ -220,7 +220,7 @@ which disallows mutable objects such as :class:`bytearray`.
It requires three arguments. The first is only used as input, and must be a It requires three arguments. The first is only used as input, and must be a
:c:type:`const char\*` which points to the name of an encoding as a :c:type:`const char\*` which points to the name of an encoding as a
NUL-terminated string, or *NULL*, in which case ``'utf-8'`` encoding is used. NUL-terminated string, or ``NULL``, in which case ``'utf-8'`` encoding is used.
An exception is raised if the named encoding is not known to Python. The An exception is raised if the named encoding is not known to Python. The
second argument must be a :c:type:`char\*\*`; the value of the pointer it 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. references will be set to a buffer with the contents of the argument text.
@ -230,12 +230,12 @@ which disallows mutable objects such as :class:`bytearray`.
There are two modes of operation: There are two modes of operation:
If *\*buffer* points a *NULL* pointer, the function will allocate a buffer of 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 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 reference the newly allocated storage. The caller is responsible for calling
:c:func:`PyMem_Free` to free the allocated buffer after usage. :c:func:`PyMem_Free` to free the allocated buffer after usage.
If *\*buffer* points to a non-*NULL* pointer (an already allocated buffer), If *\*buffer* points to a non-``NULL`` pointer (an already allocated buffer),
:c:func:`PyArg_ParseTuple` will use this location as the buffer and interpret the :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 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 encoded data into the buffer and NUL-terminate it. If the buffer is not large
@ -317,7 +317,7 @@ Other objects
``O`` (object) [PyObject \*] ``O`` (object) [PyObject \*]
Store a Python object (without any conversion) in a C object pointer. The C Store a Python object (without any conversion) in a C object pointer. The C
program thus receives the actual object that was passed. The object's reference program thus receives the actual object that was passed. The object's reference
count is not increased. The pointer stored is not *NULL*. count is not increased. The pointer stored is not ``NULL``.
``O!`` (object) [*typeobject*, PyObject \*] ``O!`` (object) [*typeobject*, PyObject \*]
Store a Python object in a C object pointer. This is similar to ``O``, but Store a Python object in a C object pointer. This is similar to ``O``, but
@ -437,7 +437,7 @@ API Functions
Parse the parameters of a function that takes both positional and keyword Parse the parameters of a function that takes both positional and keyword
parameters into local variables. The *keywords* argument is a parameters into local variables. The *keywords* argument is a
*NULL*-terminated array of keyword parameter names. Empty names denote ``NULL``-terminated array of keyword parameter names. Empty names denote
:ref:`positional-only parameters <positional-only_parameter>`. :ref:`positional-only parameters <positional-only_parameter>`.
Returns true on success; on failure, it returns false and raises the Returns true on success; on failure, it returns false and raises the
appropriate exception. appropriate exception.
@ -520,8 +520,8 @@ Building values
Create a new value based on a format string similar to those accepted by the Create a new value based on a format string similar to those accepted by the
:c:func:`PyArg_Parse\*` family of functions and a sequence of values. Returns :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 the value or ``NULL`` in the case of an error; an exception will be raised if
*NULL* is returned. ``NULL`` is returned.
:c:func:`Py_BuildValue` does not always build a tuple. It builds a tuple only if :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 its format string contains two or more format units. If the format string is
@ -547,20 +547,20 @@ Building values
``s`` (:class:`str` or ``None``) [const char \*] ``s`` (:class:`str` or ``None``) [const char \*]
Convert a null-terminated C string to a Python :class:`str` object using ``'utf-8'`` Convert a null-terminated C string to a Python :class:`str` object using ``'utf-8'``
encoding. If the C string pointer is *NULL*, ``None`` is used. encoding. If the C string pointer is ``NULL``, ``None`` is used.
``s#`` (:class:`str` or ``None``) [const char \*, int] ``s#`` (:class:`str` or ``None``) [const char \*, int]
Convert a C string and its length to a Python :class:`str` object using ``'utf-8'`` Convert a C string and its length to a Python :class:`str` object using ``'utf-8'``
encoding. If the C string pointer is *NULL*, the length is ignored and encoding. If the C string pointer is ``NULL``, the length is ignored and
``None`` is returned. ``None`` is returned.
``y`` (:class:`bytes`) [const char \*] ``y`` (:class:`bytes`) [const char \*]
This converts a C string to a Python :class:`bytes` object. If the C This converts a C string to a Python :class:`bytes` object. If the C
string pointer is *NULL*, ``None`` is returned. string pointer is ``NULL``, ``None`` is returned.
``y#`` (:class:`bytes`) [const char \*, int] ``y#`` (:class:`bytes`) [const char \*, int]
This converts a C string and its lengths to a Python object. If the C This converts a C string and its lengths to a Python object. If the C
string pointer is *NULL*, ``None`` is returned. string pointer is ``NULL``, ``None`` is returned.
``z`` (:class:`str` or ``None``) [const char \*] ``z`` (:class:`str` or ``None``) [const char \*]
Same as ``s``. Same as ``s``.
@ -570,12 +570,12 @@ Building values
``u`` (:class:`str`) [const wchar_t \*] ``u`` (:class:`str`) [const wchar_t \*]
Convert a null-terminated :c:type:`wchar_t` buffer of Unicode (UTF-16 or UCS-4) Convert a null-terminated :c:type:`wchar_t` buffer of Unicode (UTF-16 or UCS-4)
data to a Python Unicode object. If the Unicode buffer pointer is *NULL*, data to a Python Unicode object. If the Unicode buffer pointer is ``NULL``,
``None`` is returned. ``None`` is returned.
``u#`` (:class:`str`) [const wchar_t \*, int] ``u#`` (:class:`str`) [const wchar_t \*, int]
Convert a Unicode (UTF-16 or UCS-4) data buffer and its length to a Python Convert a Unicode (UTF-16 or UCS-4) data buffer and its length to a Python
Unicode object. If the Unicode buffer pointer is *NULL*, the length is ignored Unicode object. If the Unicode buffer pointer is ``NULL``, the length is ignored
and ``None`` is returned. and ``None`` is returned.
``U`` (:class:`str` or ``None``) [const char \*] ``U`` (:class:`str` or ``None``) [const char \*]
@ -636,9 +636,9 @@ Building values
``O`` (object) [PyObject \*] ``O`` (object) [PyObject \*]
Pass a Python object untouched (except for its reference count, which is 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 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 that this was caused because the call producing the argument found an error and
set an exception. Therefore, :c:func:`Py_BuildValue` will return *NULL* but won't 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 raise an exception. If no exception has been raised yet, :exc:`SystemError` is
set. set.
@ -653,7 +653,7 @@ Building values
``O&`` (object) [*converter*, *anything*] ``O&`` (object) [*converter*, *anything*]
Convert *anything* to a Python object through a *converter* function. The Convert *anything* to a Python object through a *converter* function. The
function is called with *anything* (which should be compatible with :c:type:`void function is called with *anything* (which should be compatible with :c:type:`void
\*`) as its argument and should return a "new" Python object, or *NULL* if an \*`) as its argument and should return a "new" Python object, or ``NULL`` if an
error occurred. error occurred.
``(items)`` (:class:`tuple`) [*matching-items*] ``(items)`` (:class:`tuple`) [*matching-items*]
@ -668,7 +668,7 @@ Building values
respectively. respectively.
If there is an error in the format string, the :exc:`SystemError` exception is If there is an error in the format string, the :exc:`SystemError` exception is
set and *NULL* returned. set and ``NULL`` returned.
.. c:function:: PyObject* Py_VaBuildValue(const char *format, va_list vargs) .. c:function:: PyObject* Py_VaBuildValue(const char *format, va_list vargs)

22
Doc/c-api/buffer.rst
View File

@ -102,13 +102,13 @@ a buffer, see :c:func:`PyObject_GetBuffer`.
.. c:member:: void \*obj .. c:member:: void \*obj
A new reference to the exporting object. The reference is owned by A new reference to the exporting object. The reference is owned by
the consumer and automatically decremented and set to *NULL* by the consumer and automatically decremented and set to ``NULL`` by
:c:func:`PyBuffer_Release`. The field is the equivalent of the return :c:func:`PyBuffer_Release`. The field is the equivalent of the return
value of any standard C-API function. value of any standard C-API function.
As a special case, for *temporary* buffers that are wrapped by As a special case, for *temporary* buffers that are wrapped by
:c:func:`PyMemoryView_FromBuffer` or :c:func:`PyBuffer_FillInfo` :c:func:`PyMemoryView_FromBuffer` or :c:func:`PyBuffer_FillInfo`
this field is *NULL*. In general, exporting objects MUST NOT this field is ``NULL``. In general, exporting objects MUST NOT
use this scheme. use this scheme.
.. c:member:: Py_ssize_t len .. c:member:: Py_ssize_t len
@ -134,21 +134,21 @@ a buffer, see :c:func:`PyObject_GetBuffer`.
Important exception: If a consumer requests a buffer without the Important exception: If a consumer requests a buffer without the
:c:macro:`PyBUF_FORMAT` flag, :c:member:`~Py_buffer.format` will :c:macro:`PyBUF_FORMAT` flag, :c:member:`~Py_buffer.format` will
be set to *NULL*, but :c:member:`~Py_buffer.itemsize` still has be set to ``NULL``, but :c:member:`~Py_buffer.itemsize` still has
the value for the original format. the value for the original format.
If :c:member:`~Py_buffer.shape` is present, the equality If :c:member:`~Py_buffer.shape` is present, the equality
``product(shape) * itemsize == len`` still holds and the consumer ``product(shape) * itemsize == len`` still holds and the consumer
can use :c:member:`~Py_buffer.itemsize` to navigate the buffer. can use :c:member:`~Py_buffer.itemsize` to navigate the buffer.
If :c:member:`~Py_buffer.shape` is *NULL* as a result of a :c:macro:`PyBUF_SIMPLE` If :c:member:`~Py_buffer.shape` is ``NULL`` as a result of a :c:macro:`PyBUF_SIMPLE`
or a :c:macro:`PyBUF_WRITABLE` request, the consumer must disregard or a :c:macro:`PyBUF_WRITABLE` request, the consumer must disregard
:c:member:`~Py_buffer.itemsize` and assume ``itemsize == 1``. :c:member:`~Py_buffer.itemsize` and assume ``itemsize == 1``.
.. c:member:: const char \*format .. c:member:: const char \*format
A *NUL* terminated string in :mod:`struct` module style syntax describing A *NUL* terminated string in :mod:`struct` module style syntax describing
the contents of a single item. If this is *NULL*, ``"B"`` (unsigned bytes) the contents of a single item. If this is ``NULL``, ``"B"`` (unsigned bytes)
is assumed. is assumed.
This field is controlled by the :c:macro:`PyBUF_FORMAT` flag. This field is controlled by the :c:macro:`PyBUF_FORMAT` flag.
@ -158,7 +158,7 @@ a buffer, see :c:func:`PyObject_GetBuffer`.
The number of dimensions the memory represents as an n-dimensional array. The number of dimensions the memory represents as an n-dimensional array.
If it is ``0``, :c:member:`~Py_buffer.buf` points to a single item representing If it is ``0``, :c:member:`~Py_buffer.buf` points to a single item representing
a scalar. In this case, :c:member:`~Py_buffer.shape`, :c:member:`~Py_buffer.strides` a scalar. In this case, :c:member:`~Py_buffer.shape`, :c:member:`~Py_buffer.strides`
and :c:member:`~Py_buffer.suboffsets` MUST be *NULL*. and :c:member:`~Py_buffer.suboffsets` MUST be ``NULL``.
The macro :c:macro:`PyBUF_MAX_NDIM` limits the maximum number of dimensions The macro :c:macro:`PyBUF_MAX_NDIM` limits the maximum number of dimensions
to 64. Exporters MUST respect this limit, consumers of multi-dimensional to 64. Exporters MUST respect this limit, consumers of multi-dimensional
@ -248,7 +248,7 @@ readonly, format
.. c:macro:: PyBUF_FORMAT .. c:macro:: PyBUF_FORMAT
Controls the :c:member:`~Py_buffer.format` field. If set, this field MUST Controls the :c:member:`~Py_buffer.format` field. If set, this field MUST
be filled in correctly. Otherwise, this field MUST be *NULL*. be filled in correctly. Otherwise, this field MUST be ``NULL``.
:c:macro:`PyBUF_WRITABLE` can be \|'d to any of the flags in the next section. :c:macro:`PyBUF_WRITABLE` can be \|'d to any of the flags in the next section.
@ -349,9 +349,9 @@ The logical structure of NumPy-style arrays is defined by :c:member:`~Py_buffer.
If ``ndim == 0``, the memory location pointed to by :c:member:`~Py_buffer.buf` is If ``ndim == 0``, the memory location pointed to by :c:member:`~Py_buffer.buf` is
interpreted as a scalar of size :c:member:`~Py_buffer.itemsize`. In that case, interpreted as a scalar of size :c:member:`~Py_buffer.itemsize`. In that case,
both :c:member:`~Py_buffer.shape` and :c:member:`~Py_buffer.strides` are *NULL*. both :c:member:`~Py_buffer.shape` and :c:member:`~Py_buffer.strides` are ``NULL``.
If :c:member:`~Py_buffer.strides` is *NULL*, the array is interpreted as If :c:member:`~Py_buffer.strides` is ``NULL``, the array is interpreted as
a standard n-dimensional C-array. Otherwise, the consumer must access an a standard n-dimensional C-array. Otherwise, the consumer must access an
n-dimensional array as follows: n-dimensional array as follows:
@ -438,7 +438,7 @@ Buffer-related functions
Send a request to *exporter* to fill in *view* as specified by *flags*. Send a request to *exporter* to fill in *view* as specified by *flags*.
If the exporter cannot provide a buffer of the exact type, it MUST raise If the exporter cannot provide a buffer of the exact type, it MUST raise
:c:data:`PyExc_BufferError`, set :c:member:`view->obj` to *NULL* and :c:data:`PyExc_BufferError`, set :c:member:`view->obj` to ``NULL`` and
return ``-1``. return ``-1``.
On success, fill in *view*, set :c:member:`view->obj` to a new reference On success, fill in *view*, set :c:member:`view->obj` to a new reference
@ -518,7 +518,7 @@ Buffer-related functions
On success, set :c:member:`view->obj` to a new reference to *exporter* and On success, set :c:member:`view->obj` to a new reference to *exporter* and
return 0. Otherwise, raise :c:data:`PyExc_BufferError`, set return 0. Otherwise, raise :c:data:`PyExc_BufferError`, set
:c:member:`view->obj` to *NULL* and return ``-1``; :c:member:`view->obj` to ``NULL`` and return ``-1``;
If this function is used as part of a :ref:`getbufferproc <buffer-structs>`, If this function is used as part of a :ref:`getbufferproc <buffer-structs>`,
*exporter* MUST be set to the exporting object and *flags* must be passed *exporter* MUST be set to the exporting object and *flags* must be passed

6
Doc/c-api/bytearray.rst
View File

@ -48,7 +48,7 @@ Direct API functions
.. c:function:: PyObject* PyByteArray_FromStringAndSize(const char *string, Py_ssize_t len) .. c:function:: PyObject* PyByteArray_FromStringAndSize(const char *string, Py_ssize_t len)
Create a new bytearray object from *string* and its length, *len*. On Create a new bytearray object from *string* and its length, *len*. On
failure, *NULL* is returned. failure, ``NULL`` is returned.
.. c:function:: PyObject* PyByteArray_Concat(PyObject *a, PyObject *b) .. c:function:: PyObject* PyByteArray_Concat(PyObject *a, PyObject *b)
@ -58,13 +58,13 @@ Direct API functions
.. c:function:: Py_ssize_t PyByteArray_Size(PyObject *bytearray) .. c:function:: Py_ssize_t PyByteArray_Size(PyObject *bytearray)
Return the size of *bytearray* after checking for a *NULL* pointer. Return the size of *bytearray* after checking for a ``NULL`` pointer.
.. c:function:: char* PyByteArray_AsString(PyObject *bytearray) .. c:function:: char* PyByteArray_AsString(PyObject *bytearray)
Return the contents of *bytearray* as a char array after checking for a Return the contents of *bytearray* as a char array after checking for a
*NULL* pointer. The returned array always has an extra ``NULL`` pointer. The returned array always has an extra
null byte appended. null byte appended.

12
Doc/c-api/bytes.rst
View File

@ -37,14 +37,14 @@ called with a non-bytes parameter.
.. c:function:: PyObject* PyBytes_FromString(const char *v) .. c:function:: PyObject* PyBytes_FromString(const char *v)
Return a new bytes object with a copy of the string *v* as value on success, Return a new bytes object with a copy of the string *v* as value on success,
and *NULL* on failure. The parameter *v* must not be *NULL*; it will not be and ``NULL`` on failure. The parameter *v* must not be ``NULL``; it will not be
checked. checked.
.. c:function:: PyObject* PyBytes_FromStringAndSize(const char *v, Py_ssize_t len) .. c:function:: PyObject* PyBytes_FromStringAndSize(const char *v, Py_ssize_t len)
Return a new bytes object with a copy of the string *v* as value and length Return a new bytes object with a copy of the string *v* as value and length
*len* on success, and *NULL* on failure. If *v* is *NULL*, the contents of *len* on success, and ``NULL`` on failure. If *v* is ``NULL``, the contents of
the bytes object are uninitialized. the bytes object are uninitialized.
@ -145,7 +145,7 @@ called with a non-bytes parameter.
whether there are any other null bytes. The data must not be whether there are any other null bytes. The data must not be
modified in any way, unless the object was just created using modified in any way, unless the object was just created using
``PyBytes_FromStringAndSize(NULL, size)``. It must not be deallocated. If ``PyBytes_FromStringAndSize(NULL, size)``. It must not be deallocated. If
*o* is not a bytes object at all, :c:func:`PyBytes_AsString` returns *NULL* *o* is not a bytes object at all, :c:func:`PyBytes_AsString` returns ``NULL``
and raises :exc:`TypeError`. and raises :exc:`TypeError`.
@ -159,7 +159,7 @@ called with a non-bytes parameter.
Return the null-terminated contents of the object *obj* Return the null-terminated contents of the object *obj*
through the output variables *buffer* and *length*. through the output variables *buffer* and *length*.
If *length* is *NULL*, the bytes object If *length* is ``NULL``, the bytes object
may not contain embedded null bytes; may not contain embedded null bytes;
if it does, the function returns ``-1`` and a :exc:`ValueError` is raised. if it does, the function returns ``-1`` and a :exc:`ValueError` is raised.
@ -181,7 +181,7 @@ called with a non-bytes parameter.
appended to *bytes*; the caller will own the new reference. The reference to appended to *bytes*; the caller will own the new reference. The reference to
the old value of *bytes* will be stolen. If the new object cannot be the old value of *bytes* will be stolen. If the new object cannot be
created, the old reference to *bytes* will still be discarded and the value created, the old reference to *bytes* will still be discarded and the value
of *\*bytes* will be set to *NULL*; the appropriate exception will be set. of *\*bytes* will be set to ``NULL``; the appropriate exception will be set.
.. c:function:: void PyBytes_ConcatAndDel(PyObject **bytes, PyObject *newpart) .. c:function:: void PyBytes_ConcatAndDel(PyObject **bytes, PyObject *newpart)
@ -201,5 +201,5 @@ called with a non-bytes parameter.
desired. On success, *\*bytes* holds the resized bytes object and ``0`` is desired. On success, *\*bytes* holds the resized bytes object and ``0`` is
returned; the address in *\*bytes* may differ from its input value. If the returned; the address in *\*bytes* may differ from its input value. If the
reallocation fails, the original bytes object at *\*bytes* is deallocated, reallocation fails, the original bytes object at *\*bytes* is deallocated,
*\*bytes* is set to *NULL*, :exc:`MemoryError` is set, and ``-1`` is *\*bytes* is set to ``NULL``, :exc:`MemoryError` is set, and ``-1`` is
returned. returned.

38
Doc/c-api/capsule.rst
View File

@ -40,15 +40,15 @@ Refer to :ref:`using-capsules` for more information on using these objects.
.. c:function:: PyObject* PyCapsule_New(void *pointer, const char *name, PyCapsule_Destructor destructor) .. c:function:: PyObject* PyCapsule_New(void *pointer, const char *name, PyCapsule_Destructor destructor)
Create a :c:type:`PyCapsule` encapsulating the *pointer*. The *pointer* Create a :c:type:`PyCapsule` encapsulating the *pointer*. The *pointer*
argument may not be *NULL*. argument may not be ``NULL``.
On failure, set an exception and return *NULL*. On failure, set an exception and return ``NULL``.
The *name* string may either be *NULL* or a pointer to a valid C string. If The *name* string may either be ``NULL`` or a pointer to a valid C string. If
non-*NULL*, this string must outlive the capsule. (Though it is permitted to non-``NULL``, this string must outlive the capsule. (Though it is permitted to
free it inside the *destructor*.) free it inside the *destructor*.)
If the *destructor* argument is not *NULL*, it will be called with the If the *destructor* argument is not ``NULL``, it will be called with the
capsule as its argument when it is destroyed. capsule as its argument when it is destroyed.
If this capsule will be stored as an attribute of a module, the *name* should If this capsule will be stored as an attribute of a module, the *name* should
@ -59,20 +59,20 @@ Refer to :ref:`using-capsules` for more information on using these objects.
.. c:function:: void* PyCapsule_GetPointer(PyObject *capsule, const char *name) .. c:function:: void* PyCapsule_GetPointer(PyObject *capsule, const char *name)
Retrieve the *pointer* stored in the capsule. On failure, set an exception Retrieve the *pointer* stored in the capsule. On failure, set an exception
and return *NULL*. and return ``NULL``.
The *name* parameter must compare exactly to the name stored in the capsule. The *name* parameter must compare exactly to the name stored in the capsule.
If the name stored in the capsule is *NULL*, the *name* passed in must also If the name stored in the capsule is ``NULL``, the *name* passed in must also
be *NULL*. Python uses the C function :c:func:`strcmp` to compare capsule be ``NULL``. Python uses the C function :c:func:`strcmp` to compare capsule
names. names.
.. c:function:: PyCapsule_Destructor PyCapsule_GetDestructor(PyObject *capsule) .. c:function:: PyCapsule_Destructor PyCapsule_GetDestructor(PyObject *capsule)
Return the current destructor stored in the capsule. On failure, set an Return the current destructor stored in the capsule. On failure, set an
exception and return *NULL*. exception and return ``NULL``.
It is legal for a capsule to have a *NULL* destructor. This makes a *NULL* It is legal for a capsule to have a ``NULL`` destructor. This makes a ``NULL``
return code somewhat ambiguous; use :c:func:`PyCapsule_IsValid` or return code somewhat ambiguous; use :c:func:`PyCapsule_IsValid` or
:c:func:`PyErr_Occurred` to disambiguate. :c:func:`PyErr_Occurred` to disambiguate.
@ -80,9 +80,9 @@ Refer to :ref:`using-capsules` for more information on using these objects.
.. c:function:: void* PyCapsule_GetContext(PyObject *capsule) .. c:function:: void* PyCapsule_GetContext(PyObject *capsule)
Return the current context stored in the capsule. On failure, set an Return the current context stored in the capsule. On failure, set an
exception and return *NULL*. exception and return ``NULL``.
It is legal for a capsule to have a *NULL* context. This makes a *NULL* It is legal for a capsule to have a ``NULL`` context. This makes a ``NULL``
return code somewhat ambiguous; use :c:func:`PyCapsule_IsValid` or return code somewhat ambiguous; use :c:func:`PyCapsule_IsValid` or
:c:func:`PyErr_Occurred` to disambiguate. :c:func:`PyErr_Occurred` to disambiguate.
@ -90,9 +90,9 @@ Refer to :ref:`using-capsules` for more information on using these objects.
.. c:function:: const char* PyCapsule_GetName(PyObject *capsule) .. c:function:: const char* PyCapsule_GetName(PyObject *capsule)
Return the current name stored in the capsule. On failure, set an exception Return the current name stored in the capsule. On failure, set an exception
and return *NULL*. and return ``NULL``.
It is legal for a capsule to have a *NULL* name. This makes a *NULL* return It is legal for a capsule to have a ``NULL`` name. This makes a ``NULL`` return
code somewhat ambiguous; use :c:func:`PyCapsule_IsValid` or code somewhat ambiguous; use :c:func:`PyCapsule_IsValid` or
:c:func:`PyErr_Occurred` to disambiguate. :c:func:`PyErr_Occurred` to disambiguate.
@ -107,13 +107,13 @@ Refer to :ref:`using-capsules` for more information on using these objects.
import the module conventionally (using :c:func:`PyImport_ImportModule`). import the module conventionally (using :c:func:`PyImport_ImportModule`).
Return the capsule's internal *pointer* on success. On failure, set an Return the capsule's internal *pointer* on success. On failure, set an
exception and return *NULL*. exception and return ``NULL``.
.. c:function:: int PyCapsule_IsValid(PyObject *capsule, const char *name) .. c:function:: int PyCapsule_IsValid(PyObject *capsule, const char *name)
Determines whether or not *capsule* is a valid capsule. A valid capsule is Determines whether or not *capsule* is a valid capsule. A valid capsule is
non-*NULL*, passes :c:func:`PyCapsule_CheckExact`, has a non-*NULL* pointer non-``NULL``, passes :c:func:`PyCapsule_CheckExact`, has a non-``NULL`` pointer
stored in it, and its internal name matches the *name* parameter. (See stored in it, and its internal name matches the *name* parameter. (See
:c:func:`PyCapsule_GetPointer` for information on how capsule names are :c:func:`PyCapsule_GetPointer` for information on how capsule names are
compared.) compared.)
@ -142,9 +142,9 @@ Refer to :ref:`using-capsules` for more information on using these objects.
.. c:function:: int PyCapsule_SetName(PyObject *capsule, const char *name) .. c:function:: int PyCapsule_SetName(PyObject *capsule, const char *name)
Set the name inside *capsule* to *name*. If non-*NULL*, the name must Set the name inside *capsule* to *name*. If non-``NULL``, the name must
outlive the capsule. If the previous *name* stored in the capsule was not outlive the capsule. If the previous *name* stored in the capsule was not
*NULL*, no attempt is made to free it. ``NULL``, no attempt is made to free it.
Return ``0`` on success. Return nonzero and set an exception on failure. Return ``0`` on success. Return nonzero and set an exception on failure.
@ -152,6 +152,6 @@ Refer to :ref:`using-capsules` for more information on using these objects.
.. c:function:: int PyCapsule_SetPointer(PyObject *capsule, void *pointer) .. c:function:: int PyCapsule_SetPointer(PyObject *capsule, void *pointer)
Set the void pointer inside *capsule* to *pointer*. The pointer may not be Set the void pointer inside *capsule* to *pointer*. The pointer may not be
*NULL*. ``NULL``.
Return ``0`` on success. Return nonzero and set an exception on failure. Return ``0`` on success. Return nonzero and set an exception on failure.

12
Doc/c-api/cell.rst
View File

@ -27,13 +27,13 @@ Cell objects are not likely to be useful elsewhere.
.. c:function:: int PyCell_Check(ob) .. c:function:: int PyCell_Check(ob)
Return true if *ob* is a cell object; *ob* must not be *NULL*. Return true if *ob* is a cell object; *ob* must not be ``NULL``.
.. c:function:: PyObject* PyCell_New(PyObject *ob) .. c:function:: PyObject* PyCell_New(PyObject *ob)
Create and return a new cell object containing the value *ob*. The parameter may Create and return a new cell object containing the value *ob*. The parameter may
be *NULL*. be ``NULL``.
.. c:function:: PyObject* PyCell_Get(PyObject *cell) .. c:function:: PyObject* PyCell_Get(PyObject *cell)
@ -44,19 +44,19 @@ Cell objects are not likely to be useful elsewhere.
.. c:function:: PyObject* PyCell_GET(PyObject *cell) .. c:function:: PyObject* PyCell_GET(PyObject *cell)
Return the contents of the cell *cell*, but without checking that *cell* is Return the contents of the cell *cell*, but without checking that *cell* is
non-*NULL* and a cell object. non-``NULL`` and a cell object.
.. c:function:: int PyCell_Set(PyObject *cell, PyObject *value) .. c:function:: int PyCell_Set(PyObject *cell, PyObject *value)
Set the contents of the cell object *cell* to *value*. This releases the Set the contents of the cell object *cell* to *value*. This releases the
reference to any current content of the cell. *value* may be *NULL*. *cell* reference to any current content of the cell. *value* may be ``NULL``. *cell*
must be non-*NULL*; if it is not a cell object, ``-1`` will be returned. On must be non-``NULL``; if it is not a cell object, ``-1`` will be returned. On
success, ``0`` will be returned. success, ``0`` will be returned.
.. c:function:: void PyCell_SET(PyObject *cell, PyObject *value) .. c:function:: void PyCell_SET(PyObject *cell, PyObject *value)
Sets the value of the cell object *cell* to *value*. No reference counts are Sets the value of the cell object *cell* to *value*. No reference counts are
adjusted, and no checks are made for safety; *cell* must be non-*NULL* and must adjusted, and no checks are made for safety; *cell* must be non-``NULL`` and must
be a cell object. be a cell object.

8
Doc/c-api/codec.rst
View File

@ -21,7 +21,7 @@ Codec registry and support functions
*object* is passed through the encoder function found for the given *object* is passed through the encoder function found for the given
*encoding* using the error handling method defined by *errors*. *errors* may *encoding* using the error handling method defined by *errors*. *errors* may
be *NULL* to use the default method defined for the codec. Raises a be ``NULL`` to use the default method defined for the codec. Raises a
:exc:`LookupError` if no encoder can be found. :exc:`LookupError` if no encoder can be found.
.. c:function:: PyObject* PyCodec_Decode(PyObject *object, const char *encoding, const char *errors) .. c:function:: PyObject* PyCodec_Decode(PyObject *object, const char *encoding, const char *errors)
@ -30,7 +30,7 @@ Codec registry and support functions
*object* is passed through the decoder function found for the given *object* is passed through the decoder function found for the given
*encoding* using the error handling method defined by *errors*. *errors* may *encoding* using the error handling method defined by *errors*. *errors* may
be *NULL* to use the default method defined for the codec. Raises a be ``NULL`` to use the default method defined for the codec. Raises a
:exc:`LookupError` if no encoder can be found. :exc:`LookupError` if no encoder can be found.
@ -40,7 +40,7 @@ Codec lookup API
In the following functions, the *encoding* string is looked up converted to all In the following functions, the *encoding* string is looked up converted to all
lower-case characters, which makes encodings looked up through this mechanism lower-case characters, which makes encodings looked up through this mechanism
effectively case-insensitive. If no codec is found, a :exc:`KeyError` is set effectively case-insensitive. If no codec is found, a :exc:`KeyError` is set
and *NULL* returned. and ``NULL`` returned.
.. c:function:: PyObject* PyCodec_Encoder(const char *encoding) .. c:function:: PyObject* PyCodec_Encoder(const char *encoding)
@ -92,7 +92,7 @@ Registry API for Unicode encoding error handlers
.. c:function:: PyObject* PyCodec_LookupError(const char *name) .. c:function:: PyObject* PyCodec_LookupError(const char *name)
Lookup the error handling callback function registered under *name*. As a Lookup the error handling callback function registered under *name*. As a
special case *NULL* can be passed, in which case the error handling callback special case ``NULL`` can be passed, in which case the error handling callback
for "strict" will be returned. for "strict" will be returned.
.. c:function:: PyObject* PyCodec_StrictErrors(PyObject *exc) .. c:function:: PyObject* PyCodec_StrictErrors(PyObject *exc)

4
Doc/c-api/concrete.rst
View File

@ -17,8 +17,8 @@ dictionary, use :c:func:`PyDict_Check`. The chapter is structured like the
.. warning:: .. warning::
While the functions described in this chapter carefully check the type of the While the functions described in this chapter carefully check the type of the
objects which are passed in, many of them do not check for *NULL* being passed objects which are passed in, many of them do not check for ``NULL`` being passed
instead of a valid object. Allowing *NULL* to be passed in can cause memory instead of a valid object. Allowing ``NULL`` to be passed in can cause memory
access violations and immediate termination of the interpreter. access violations and immediate termination of the interpreter.

6
Doc/c-api/contextvars.rst
View File

@ -60,17 +60,17 @@ Type-check macros:
.. c:function:: int PyContext_CheckExact(PyObject *o) .. c:function:: int PyContext_CheckExact(PyObject *o)
Return true if *o* is of type :c:data:`PyContext_Type`. *o* must not be Return true if *o* is of type :c:data:`PyContext_Type`. *o* must not be
*NULL*. This function always succeeds. ``NULL``. This function always succeeds.
.. c:function:: int PyContextVar_CheckExact(PyObject *o) .. c:function:: int PyContextVar_CheckExact(PyObject *o)
Return true if *o* is of type :c:data:`PyContextVar_Type`. *o* must not be Return true if *o* is of type :c:data:`PyContextVar_Type`. *o* must not be
*NULL*. This function always succeeds. ``NULL``. This function always succeeds.
.. c:function:: int PyContextToken_CheckExact(PyObject *o) .. c:function:: int PyContextToken_CheckExact(PyObject *o)
Return true if *o* is of type :c:data:`PyContextToken_Type`. Return true if *o* is of type :c:data:`PyContextToken_Type`.
*o* must not be *NULL*. This function always succeeds. *o* must not be ``NULL``. This function always succeeds.
Context object management functions: Context object management functions:

2
Doc/c-api/conversion.rst
View File

@ -113,7 +113,7 @@ The following functions provide locale-independent string to number conversions.
*val* is a finite number, an infinite number, or not a number, respectively. *val* is a finite number, an infinite number, or not a number, respectively.
The return value is a pointer to *buffer* with the converted string or The return value is a pointer to *buffer* with the converted string or
*NULL* if the conversion failed. The caller is responsible for freeing the ``NULL`` if the conversion failed. The caller is responsible for freeing the
returned string by calling :c:func:`PyMem_Free`. returned string by calling :c:func:`PyMem_Free`.
.. versionadded:: 3.1 .. versionadded:: 3.1

4
Doc/c-api/coro.rst
View File

@ -23,7 +23,7 @@ return.
.. c:function:: int PyCoro_CheckExact(PyObject *ob) .. c:function:: int PyCoro_CheckExact(PyObject *ob)
Return true if *ob*'s type is *PyCoro_Type*; *ob* must not be *NULL*. Return true if *ob*'s type is *PyCoro_Type*; *ob* must not be ``NULL``.
.. c:function:: PyObject* PyCoro_New(PyFrameObject *frame, PyObject *name, PyObject *qualname) .. c:function:: PyObject* PyCoro_New(PyFrameObject *frame, PyObject *name, PyObject *qualname)
@ -31,4 +31,4 @@ return.
Create and return a new coroutine object based on the *frame* object, Create and return a new coroutine object based on the *frame* object,
with ``__name__`` and ``__qualname__`` set to *name* and *qualname*. with ``__name__`` and ``__qualname__`` set to *name* and *qualname*.
A reference to *frame* is stolen by this function. The *frame* argument A reference to *frame* is stolen by this function. The *frame* argument
must not be *NULL*. must not be ``NULL``.

28
Doc/c-api/datetime.rst
View File

@ -28,61 +28,61 @@ Type-check macros:
.. c:function:: int PyDate_Check(PyObject *ob) .. c:function:: int PyDate_Check(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_DateType` or a subtype of Return true if *ob* is of type :c:data:`PyDateTime_DateType` or a subtype of
:c:data:`PyDateTime_DateType`. *ob* must not be *NULL*. :c:data:`PyDateTime_DateType`. *ob* must not be ``NULL``.
.. c:function:: int PyDate_CheckExact(PyObject *ob) .. c:function:: int PyDate_CheckExact(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_DateType`. *ob* must not be Return true if *ob* is of type :c:data:`PyDateTime_DateType`. *ob* must not be
*NULL*. ``NULL``.
.. c:function:: int PyDateTime_Check(PyObject *ob) .. c:function:: int PyDateTime_Check(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_DateTimeType` or a subtype of Return true if *ob* is of type :c:data:`PyDateTime_DateTimeType` or a subtype of
:c:data:`PyDateTime_DateTimeType`. *ob* must not be *NULL*. :c:data:`PyDateTime_DateTimeType`. *ob* must not be ``NULL``.
.. c:function:: int PyDateTime_CheckExact(PyObject *ob) .. c:function:: int PyDateTime_CheckExact(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_DateTimeType`. *ob* must not Return true if *ob* is of type :c:data:`PyDateTime_DateTimeType`. *ob* must not
be *NULL*. be ``NULL``.
.. c:function:: int PyTime_Check(PyObject *ob) .. c:function:: int PyTime_Check(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_TimeType` or a subtype of Return true if *ob* is of type :c:data:`PyDateTime_TimeType` or a subtype of
:c:data:`PyDateTime_TimeType`. *ob* must not be *NULL*. :c:data:`PyDateTime_TimeType`. *ob* must not be ``NULL``.
.. c:function:: int PyTime_CheckExact(PyObject *ob) .. c:function:: int PyTime_CheckExact(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_TimeType`. *ob* must not be Return true if *ob* is of type :c:data:`PyDateTime_TimeType`. *ob* must not be
*NULL*. ``NULL``.
.. c:function:: int PyDelta_Check(PyObject *ob) .. c:function:: int PyDelta_Check(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_DeltaType` or a subtype of Return true if *ob* is of type :c:data:`PyDateTime_DeltaType` or a subtype of
:c:data:`PyDateTime_DeltaType`. *ob* must not be *NULL*. :c:data:`PyDateTime_DeltaType`. *ob* must not be ``NULL``.
.. c:function:: int PyDelta_CheckExact(PyObject *ob) .. c:function:: int PyDelta_CheckExact(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_DeltaType`. *ob* must not be Return true if *ob* is of type :c:data:`PyDateTime_DeltaType`. *ob* must not be
*NULL*. ``NULL``.
.. c:function:: int PyTZInfo_Check(PyObject *ob) .. c:function:: int PyTZInfo_Check(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_TZInfoType` or a subtype of Return true if *ob* is of type :c:data:`PyDateTime_TZInfoType` or a subtype of
:c:data:`PyDateTime_TZInfoType`. *ob* must not be *NULL*. :c:data:`PyDateTime_TZInfoType`. *ob* must not be ``NULL``.
.. c:function:: int PyTZInfo_CheckExact(PyObject *ob) .. c:function:: int PyTZInfo_CheckExact(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_TZInfoType`. *ob* must not be Return true if *ob* is of type :c:data:`PyDateTime_TZInfoType`. *ob* must not be
*NULL*. ``NULL``.
Macros to create objects: Macros to create objects:
@ -144,7 +144,7 @@ Macros to create objects:
Macros to extract fields from date objects. The argument must be an instance of Macros to extract fields from date objects. The argument must be an instance of
:c:data:`PyDateTime_Date`, including subclasses (such as :c:data:`PyDateTime_Date`, including subclasses (such as
:c:data:`PyDateTime_DateTime`). The argument must not be *NULL*, and the type is :c:data:`PyDateTime_DateTime`). The argument must not be ``NULL``, and the type is
not checked: not checked:
.. c:function:: int PyDateTime_GET_YEAR(PyDateTime_Date *o) .. c:function:: int PyDateTime_GET_YEAR(PyDateTime_Date *o)
@ -164,7 +164,7 @@ not checked:
Macros to extract fields from datetime objects. The argument must be an Macros to extract fields from datetime objects. The argument must be an
instance of :c:data:`PyDateTime_DateTime`, including subclasses. The argument instance of :c:data:`PyDateTime_DateTime`, including subclasses. The argument
must not be *NULL*, and the type is not checked: must not be ``NULL``, and the type is not checked:
.. c:function:: int PyDateTime_DATE_GET_HOUR(PyDateTime_DateTime *o) .. c:function:: int PyDateTime_DATE_GET_HOUR(PyDateTime_DateTime *o)
@ -187,7 +187,7 @@ must not be *NULL*, and the type is not checked:
Macros to extract fields from time objects. The argument must be an instance of Macros to extract fields from time objects. The argument must be an instance of
:c:data:`PyDateTime_Time`, including subclasses. The argument must not be *NULL*, :c:data:`PyDateTime_Time`, including subclasses. The argument must not be ``NULL``,
and the type is not checked: and the type is not checked:
.. c:function:: int PyDateTime_TIME_GET_HOUR(PyDateTime_Time *o) .. c:function:: int PyDateTime_TIME_GET_HOUR(PyDateTime_Time *o)
@ -212,7 +212,7 @@ and the type is not checked:
Macros to extract fields from time delta objects. The argument must be an Macros to extract fields from time delta objects. The argument must be an
instance of :c:data:`PyDateTime_Delta`, including subclasses. The argument must instance of :c:data:`PyDateTime_Delta`, including subclasses. The argument must
not be *NULL*, and the type is not checked: not be ``NULL``, and the type is not checked:
.. c:function:: int PyDateTime_DELTA_GET_DAYS(PyDateTime_Delta *o) .. c:function:: int PyDateTime_DELTA_GET_DAYS(PyDateTime_Delta *o)

10
Doc/c-api/dict.rst
View File

@ -33,7 +33,7 @@ Dictionary Objects
.. c:function:: PyObject* PyDict_New() .. c:function:: PyObject* PyDict_New()
Return a new empty dictionary, or *NULL* on failure. Return a new empty dictionary, or ``NULL`` on failure.
.. c:function:: PyObject* PyDictProxy_New(PyObject *mapping) .. c:function:: PyObject* PyDictProxy_New(PyObject *mapping)
@ -92,7 +92,7 @@ Dictionary Objects
.. c:function:: PyObject* PyDict_GetItem(PyObject *p, PyObject *key) .. c:function:: PyObject* PyDict_GetItem(PyObject *p, PyObject *key)
Return the object from dictionary *p* which has a key *key*. Return *NULL* Return the object from dictionary *p* which has a key *key*. Return ``NULL``
if the key *key* is not present, but *without* setting an exception. if the key *key* is not present, but *without* setting an exception.
Note that exceptions which occur while calling :meth:`__hash__` and Note that exceptions which occur while calling :meth:`__hash__` and
@ -103,8 +103,8 @@ Dictionary Objects
.. c:function:: PyObject* PyDict_GetItemWithError(PyObject *p, PyObject *key) .. c:function:: PyObject* PyDict_GetItemWithError(PyObject *p, PyObject *key)
Variant of :c:func:`PyDict_GetItem` that does not suppress Variant of :c:func:`PyDict_GetItem` that does not suppress
exceptions. Return *NULL* **with** an exception set if an exception exceptions. Return ``NULL`` **with** an exception set if an exception
occurred. Return *NULL* **without** an exception set if the key occurred. Return ``NULL`` **without** an exception set if the key
wasn't present. wasn't present.
@ -161,7 +161,7 @@ Dictionary Objects
function returns true for each pair in the dictionary, and false once all function returns true for each pair in the dictionary, and false once all
pairs have been reported. The parameters *pkey* and *pvalue* should either pairs have been reported. The parameters *pkey* and *pvalue* should either
point to :c:type:`PyObject\*` variables that will be filled in with each key point to :c:type:`PyObject\*` variables that will be filled in with each key
and value, respectively, or may be *NULL*. Any references returned through and value, respectively, or may be ``NULL``. Any references returned through
them are borrowed. *ppos* should not be altered during iteration. Its them are borrowed. *ppos* should not be altered during iteration. Its
value represents offsets within the internal dictionary structure, and value represents offsets within the internal dictionary structure, and
since the structure is sparse, the offsets are not consecutive. since the structure is sparse, the offsets are not consecutive.

46
Doc/c-api/exceptions.rst
View File

@ -13,7 +13,7 @@ exception handling. It works somewhat like the POSIX :c:data:`errno` variable:
there is a global indicator (per thread) of the last error that occurred. Most there is a global indicator (per thread) of the last error that occurred. Most
C API functions don't clear this on success, but will set it to indicate the C API functions don't clear this on success, but will set it to indicate the
cause of the error on failure. Most C API functions also return an error cause of the error on failure. Most C API functions also return an error
indicator, usually *NULL* if they are supposed to return a pointer, or ``-1`` indicator, usually ``NULL`` if they are supposed to return a pointer, or ``-1``
if they return an integer (exception: the :c:func:`PyArg_\*` functions if they return an integer (exception: the :c:func:`PyArg_\*` functions
return ``1`` for success and ``0`` for failure). return ``1`` for success and ``0`` for failure).
@ -111,7 +111,7 @@ NULL pointer for use in a ``return`` statement.
.. c:function:: PyObject* PyErr_Format(PyObject *exception, const char *format, ...) .. c:function:: PyObject* PyErr_Format(PyObject *exception, const char *format, ...)
This function sets the error indicator and returns *NULL*. *exception* This function sets the error indicator and returns ``NULL``. *exception*
should be a Python exception class. The *format* and subsequent should be a Python exception class. The *format* and subsequent
parameters help format the error message; they have the same meaning and parameters help format the error message; they have the same meaning and
values as in :c:func:`PyUnicode_FromFormat`. *format* is an ASCII-encoded values as in :c:func:`PyUnicode_FromFormat`. *format* is an ASCII-encoded
@ -140,7 +140,7 @@ NULL pointer for use in a ``return`` statement.
.. c:function:: PyObject* PyErr_NoMemory() .. c:function:: PyObject* PyErr_NoMemory()
This is a shorthand for ``PyErr_SetNone(PyExc_MemoryError)``; it returns *NULL* This is a shorthand for ``PyErr_SetNone(PyExc_MemoryError)``; it returns ``NULL``
so an object allocation function can write ``return PyErr_NoMemory();`` when it so an object allocation function can write ``return PyErr_NoMemory();`` when it
runs out of memory. runs out of memory.
@ -156,7 +156,7 @@ NULL pointer for use in a ``return`` statement.
and then calls ``PyErr_SetObject(type, object)``. On Unix, when the and then calls ``PyErr_SetObject(type, object)``. On Unix, when the
:c:data:`errno` value is :const:`EINTR`, indicating an interrupted system call, :c:data:`errno` value is :const:`EINTR`, indicating an interrupted system call,
this calls :c:func:`PyErr_CheckSignals`, and if that set the error indicator, this calls :c:func:`PyErr_CheckSignals`, and if that set the error indicator,
leaves it set to that. The function always returns *NULL*, so a wrapper leaves it set to that. The function always returns ``NULL``, so a wrapper
function around a system call can write ``return PyErr_SetFromErrno(type);`` function around a system call can write ``return PyErr_SetFromErrno(type);``
when the system call returns an error. when the system call returns an error.
@ -164,7 +164,7 @@ NULL pointer for use in a ``return`` statement.
.. c:function:: PyObject* PyErr_SetFromErrnoWithFilenameObject(PyObject *type, PyObject *filenameObject) .. c:function:: PyObject* PyErr_SetFromErrnoWithFilenameObject(PyObject *type, PyObject *filenameObject)
Similar to :c:func:`PyErr_SetFromErrno`, with the additional behavior that if Similar to :c:func:`PyErr_SetFromErrno`, with the additional behavior that if
*filenameObject* is not *NULL*, it is passed to the constructor of *type* as *filenameObject* is not ``NULL``, it is passed to the constructor of *type* as
a third parameter. In the case of :exc:`OSError` exception, a third parameter. In the case of :exc:`OSError` exception,
this is used to define the :attr:`filename` attribute of the this is used to define the :attr:`filename` attribute of the
exception instance. exception instance.
@ -195,7 +195,7 @@ NULL pointer for use in a ``return`` statement.
then it constructs a tuple object whose first item is the *ierr* value and whose then it constructs a tuple object whose first item is the *ierr* value and whose
second item is the corresponding error message (gotten from second item is the corresponding error message (gotten from
:c:func:`FormatMessage`), and then calls ``PyErr_SetObject(PyExc_WindowsError, :c:func:`FormatMessage`), and then calls ``PyErr_SetObject(PyExc_WindowsError,
object)``. This function always returns *NULL*. object)``. This function always returns ``NULL``.
.. availability:: Windows. .. availability:: Windows.
@ -304,7 +304,7 @@ an error value).
.. c:function:: int PyErr_WarnEx(PyObject *category, const char *message, Py_ssize_t stack_level) .. c:function:: int PyErr_WarnEx(PyObject *category, const char *message, Py_ssize_t stack_level)
Issue a warning message. The *category* argument is a warning category (see Issue a warning message. The *category* argument is a warning category (see
below) or *NULL*; the *message* argument is a UTF-8 encoded string. *stack_level* is a below) or ``NULL``; the *message* argument is a UTF-8 encoded string. *stack_level* is a
positive number giving a number of stack frames; the warning will be issued from positive number giving a number of stack frames; the warning will be issued from
the currently executing line of code in that stack frame. A *stack_level* of 1 the currently executing line of code in that stack frame. A *stack_level* of 1
is the function calling :c:func:`PyErr_WarnEx`, 2 is the function above that, is the function calling :c:func:`PyErr_WarnEx`, 2 is the function above that,
@ -333,7 +333,7 @@ an error value).
Issue a warning message with explicit control over all warning attributes. This Issue a warning message with explicit control over all warning attributes. This
is a straightforward wrapper around the Python function is a straightforward wrapper around the Python function
:func:`warnings.warn_explicit`, see there for more information. The *module* :func:`warnings.warn_explicit`, see there for more information. The *module*
and *registry* arguments may be set to *NULL* to get the default effect and *registry* arguments may be set to ``NULL`` to get the default effect
described there. described there.
.. versionadded:: 3.4 .. versionadded:: 3.4
@ -370,7 +370,7 @@ Querying the error indicator
Test whether the error indicator is set. If set, return the exception *type* Test whether the error indicator is set. If set, return the exception *type*
(the first argument to the last call to one of the :c:func:`PyErr_Set\*` (the first argument to the last call to one of the :c:func:`PyErr_Set\*`
functions or to :c:func:`PyErr_Restore`). If not set, return *NULL*. You do not functions or to :c:func:`PyErr_Restore`). If not set, return ``NULL``. You do not
own a reference to the return value, so you do not need to :c:func:`Py_DECREF` own a reference to the return value, so you do not need to :c:func:`Py_DECREF`
it. it.
@ -400,9 +400,9 @@ Querying the error indicator
.. c:function:: void PyErr_Fetch(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback) .. c:function:: void PyErr_Fetch(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)
Retrieve the error indicator into three variables whose addresses are passed. Retrieve the error indicator into three variables whose addresses are passed.
If the error indicator is not set, set all three variables to *NULL*. If it is If the error indicator is not set, set all three variables to ``NULL``. If it is
set, it will be cleared and you own a reference to each object retrieved. The set, it will be cleared and you own a reference to each object retrieved. The
value and traceback object may be *NULL* even when the type object is not. value and traceback object may be ``NULL`` even when the type object is not.
.. note:: .. note::
@ -422,8 +422,8 @@ Querying the error indicator
.. c:function:: void PyErr_Restore(PyObject *type, PyObject *value, PyObject *traceback) .. c:function:: void PyErr_Restore(PyObject *type, PyObject *value, PyObject *traceback)
Set the error indicator from the three objects. If the error indicator is Set the error indicator from the three objects. If the error indicator is
already set, it is cleared first. If the objects are *NULL*, the error already set, it is cleared first. If the objects are ``NULL``, the error
indicator is cleared. Do not pass a *NULL* type and non-*NULL* value or indicator is cleared. Do not pass a ``NULL`` type and non-``NULL`` value or
traceback. The exception type should be a class. Do not pass an invalid traceback. The exception type should be a class. Do not pass an invalid
exception type or value. (Violating these rules will cause subtle problems exception type or value. (Violating these rules will cause subtle problems
later.) This call takes away a reference to each object: you must own a later.) This call takes away a reference to each object: you must own a
@ -462,7 +462,7 @@ Querying the error indicator
Retrieve the exception info, as known from ``sys.exc_info()``. This refers Retrieve the exception info, as known from ``sys.exc_info()``. This refers
to an exception that was *already caught*, not to an exception that was to an exception that was *already caught*, not to an exception that was
freshly raised. Returns new references for the three objects, any of which freshly raised. Returns new references for the three objects, any of which
may be *NULL*. Does not modify the exception info state. may be ``NULL``. Does not modify the exception info state.
.. note:: .. note::
@ -479,7 +479,7 @@ Querying the error indicator
Set the exception info, as known from ``sys.exc_info()``. This refers Set the exception info, as known from ``sys.exc_info()``. This refers
to an exception that was *already caught*, not to an exception that was to an exception that was *already caught*, not to an exception that was
freshly raised. This function steals the references of the arguments. freshly raised. This function steals the references of the arguments.
To clear the exception state, pass *NULL* for all three arguments. To clear the exception state, pass ``NULL`` for all three arguments.
For general rules about the three arguments, see :c:func:`PyErr_Restore`. For general rules about the three arguments, see :c:func:`PyErr_Restore`.
.. note:: .. note::
@ -549,7 +549,7 @@ Exception Classes
This utility function creates and returns a new exception class. The *name* This utility function creates and returns a new exception class. The *name*
argument must be the name of the new exception, a C string of the form argument must be the name of the new exception, a C string of the form
``module.classname``. The *base* and *dict* arguments are normally *NULL*. ``module.classname``. The *base* and *dict* arguments are normally ``NULL``.
This creates a class object derived from :exc:`Exception` (accessible in C as This creates a class object derived from :exc:`Exception` (accessible in C as
:c:data:`PyExc_Exception`). :c:data:`PyExc_Exception`).
@ -563,7 +563,7 @@ Exception Classes
.. c:function:: PyObject* PyErr_NewExceptionWithDoc(const char *name, const char *doc, PyObject *base, PyObject *dict) .. c:function:: PyObject* PyErr_NewExceptionWithDoc(const char *name, const char *doc, PyObject *base, PyObject *dict)
Same as :c:func:`PyErr_NewException`, except that the new exception class can Same as :c:func:`PyErr_NewException`, except that the new exception class can
easily be given a docstring: If *doc* is non-*NULL*, it will be used as the easily be given a docstring: If *doc* is non-``NULL``, it will be used as the
docstring for the exception class. docstring for the exception class.
.. versionadded:: 3.2 .. versionadded:: 3.2
@ -576,7 +576,7 @@ Exception Objects
Return the traceback associated with the exception as a new reference, as Return the traceback associated with the exception as a new reference, as
accessible from Python through :attr:`__traceback__`. If there is no accessible from Python through :attr:`__traceback__`. If there is no
traceback associated, this returns *NULL*. traceback associated, this returns ``NULL``.
.. c:function:: int PyException_SetTraceback(PyObject *ex, PyObject *tb) .. c:function:: int PyException_SetTraceback(PyObject *ex, PyObject *tb)
@ -590,12 +590,12 @@ Exception Objects
Return the context (another exception instance during whose handling *ex* was Return the context (another exception instance during whose handling *ex* was
raised) associated with the exception as a new reference, as accessible from raised) associated with the exception as a new reference, as accessible from
Python through :attr:`__context__`. If there is no context associated, this Python through :attr:`__context__`. If there is no context associated, this
returns *NULL*. returns ``NULL``.
.. c:function:: void PyException_SetContext(PyObject *ex, PyObject *ctx) .. c:function:: void PyException_SetContext(PyObject *ex, PyObject *ctx)
Set the context associated with the exception to *ctx*. Use *NULL* to clear Set the context associated with the exception to *ctx*. Use ``NULL`` to clear
it. There is no type check to make sure that *ctx* is an exception instance. it. There is no type check to make sure that *ctx* is an exception instance.
This steals a reference to *ctx*. This steals a reference to *ctx*.
@ -609,7 +609,7 @@ Exception Objects
.. c:function:: void PyException_SetCause(PyObject *ex, PyObject *cause) .. c:function:: void PyException_SetCause(PyObject *ex, PyObject *cause)
Set the cause associated with the exception to *cause*. Use *NULL* to clear Set the cause associated with the exception to *cause*. Use ``NULL`` to clear
it. There is no type check to make sure that *cause* is either an exception it. There is no type check to make sure that *cause* is either an exception
instance or :const:`None`. This steals a reference to *cause*. instance or :const:`None`. This steals a reference to *cause*.
@ -656,7 +656,7 @@ The following functions are used to create and modify Unicode exceptions from C.
int PyUnicodeTranslateError_GetStart(PyObject *exc, Py_ssize_t *start) int PyUnicodeTranslateError_GetStart(PyObject *exc, Py_ssize_t *start)
Get the *start* attribute of the given exception object and place it into Get the *start* attribute of the given exception object and place it into
*\*start*. *start* must not be *NULL*. Return ``0`` on success, ``-1`` on *\*start*. *start* must not be ``NULL``. Return ``0`` on success, ``-1`` on
failure. failure.
.. c:function:: int PyUnicodeDecodeError_SetStart(PyObject *exc, Py_ssize_t start) .. c:function:: int PyUnicodeDecodeError_SetStart(PyObject *exc, Py_ssize_t start)
@ -671,7 +671,7 @@ The following functions are used to create and modify Unicode exceptions from C.
int PyUnicodeTranslateError_GetEnd(PyObject *exc, Py_ssize_t *end) int PyUnicodeTranslateError_GetEnd(PyObject *exc, Py_ssize_t *end)
Get the *end* attribute of the given exception object and place it into Get the *end* attribute of the given exception object and place it into
*\*end*. *end* must not be *NULL*. Return ``0`` on success, ``-1`` on *\*end*. *end* must not be ``NULL``. Return ``0`` on success, ``-1`` on
failure. failure.
.. c:function:: int PyUnicodeDecodeError_SetEnd(PyObject *exc, Py_ssize_t end) .. c:function:: int PyUnicodeDecodeError_SetEnd(PyObject *exc, Py_ssize_t end)

4
Doc/c-api/file.rst
View File

@ -21,9 +21,9 @@ the :mod:`io` APIs instead.
Create a Python file object from the file descriptor of an already Create a Python file object from the file descriptor of an already
opened file *fd*. The arguments *name*, *encoding*, *errors* and *newline* opened file *fd*. The arguments *name*, *encoding*, *errors* and *newline*
can be *NULL* to use the defaults; *buffering* can be *-1* to use the can be ``NULL`` to use the defaults; *buffering* can be *-1* to use the
default. *name* is ignored and kept for backward compatibility. Return default. *name* is ignored and kept for backward compatibility. Return
*NULL* on failure. For a more comprehensive description of the arguments, ``NULL`` on failure. For a more comprehensive description of the arguments,
please refer to the :func:`io.open` function documentation. please refer to the :func:`io.open` function documentation.
.. warning:: .. warning::

4
Doc/c-api/float.rst
View File

@ -34,12 +34,12 @@ Floating Point Objects
.. c:function:: PyObject* PyFloat_FromString(PyObject *str) .. c:function:: PyObject* PyFloat_FromString(PyObject *str)
Create a :c:type:`PyFloatObject` object based on the string value in *str*, or Create a :c:type:`PyFloatObject` object based on the string value in *str*, or
*NULL* on failure. ``NULL`` on failure.
.. c:function:: PyObject* PyFloat_FromDouble(double v) .. c:function:: PyObject* PyFloat_FromDouble(double v)
Create a :c:type:`PyFloatObject` object from *v*, or *NULL* on failure. Create a :c:type:`PyFloatObject` object from *v*, or ``NULL`` on failure.
.. c:function:: double PyFloat_AsDouble(PyObject *pyfloat) .. c:function:: double PyFloat_AsDouble(PyObject *pyfloat)

10
Doc/c-api/function.rst
View File

@ -26,7 +26,7 @@ There are a few functions specific to Python functions.
.. c:function:: int PyFunction_Check(PyObject *o) .. c:function:: int PyFunction_Check(PyObject *o)
Return true if *o* is a function object (has type :c:data:`PyFunction_Type`). Return true if *o* is a function object (has type :c:data:`PyFunction_Type`).
The parameter must not be *NULL*. The parameter must not be ``NULL``.
.. c:function:: PyObject* PyFunction_New(PyObject *code, PyObject *globals) .. c:function:: PyObject* PyFunction_New(PyObject *code, PyObject *globals)
@ -36,7 +36,7 @@ There are a few functions specific to Python functions.
The function's docstring and name are retrieved from the code object. *__module__* The function's docstring and name are retrieved from the code object. *__module__*
is retrieved from *globals*. The argument defaults, annotations and closure are is retrieved from *globals*. The argument defaults, annotations and closure are
set to *NULL*. *__qualname__* is set to the same value as the function's name. set to ``NULL``. *__qualname__* is set to the same value as the function's name.
.. c:function:: PyObject* PyFunction_NewWithQualName(PyObject *code, PyObject *globals, PyObject *qualname) .. c:function:: PyObject* PyFunction_NewWithQualName(PyObject *code, PyObject *globals, PyObject *qualname)
@ -69,7 +69,7 @@ There are a few functions specific to Python functions.
.. c:function:: PyObject* PyFunction_GetDefaults(PyObject *op) .. c:function:: PyObject* PyFunction_GetDefaults(PyObject *op)
Return the argument default values of the function object *op*. This can be a Return the argument default values of the function object *op*. This can be a
tuple of arguments or *NULL*. tuple of arguments or ``NULL``.
.. c:function:: int PyFunction_SetDefaults(PyObject *op, PyObject *defaults) .. c:function:: int PyFunction_SetDefaults(PyObject *op, PyObject *defaults)
@ -82,7 +82,7 @@ There are a few functions specific to Python functions.
.. c:function:: PyObject* PyFunction_GetClosure(PyObject *op) .. c:function:: PyObject* PyFunction_GetClosure(PyObject *op)
Return the closure associated with the function object *op*. This can be *NULL* Return the closure associated with the function object *op*. This can be ``NULL``
or a tuple of cell objects. or a tuple of cell objects.
@ -97,7 +97,7 @@ There are a few functions specific to Python functions.
.. c:function:: PyObject *PyFunction_GetAnnotations(PyObject *op) .. c:function:: PyObject *PyFunction_GetAnnotations(PyObject *op)
Return the annotations of the function object *op*. This can be a Return the annotations of the function object *op*. This can be a
mutable dictionary or *NULL*. mutable dictionary or ``NULL``.
.. c:function:: int PyFunction_SetAnnotations(PyObject *op, PyObject *annotations) .. c:function:: int PyFunction_SetAnnotations(PyObject *op, PyObject *annotations)

8
Doc/c-api/gcsupport.rst
View File

@ -49,7 +49,7 @@ Constructors for container types must conform to two rules:
.. c:function:: TYPE* PyObject_GC_Resize(TYPE, PyVarObject *op, Py_ssize_t newsize) .. c:function:: TYPE* PyObject_GC_Resize(TYPE, PyVarObject *op, Py_ssize_t newsize)
Resize an object allocated by :c:func:`PyObject_NewVar`. Returns the Resize an object allocated by :c:func:`PyObject_NewVar`. Returns the
resized object or *NULL* on failure. *op* must not be tracked by the collector yet. resized object or ``NULL`` on failure. *op* must not be tracked by the collector yet.
.. c:function:: void PyObject_GC_Track(PyObject *op) .. c:function:: void PyObject_GC_Track(PyObject *op)
@ -110,7 +110,7 @@ The :c:member:`~PyTypeObject.tp_traverse` handler must have the following type:
Traversal function for a container object. Implementations must call the Traversal function for a container object. Implementations must call the
*visit* function for each object directly contained by *self*, with the *visit* function for each object directly contained by *self*, with the
parameters to *visit* being the contained object and the *arg* value passed parameters to *visit* being the contained object and the *arg* value passed
to the handler. The *visit* function must not be called with a *NULL* to the handler. The *visit* function must not be called with a ``NULL``
object argument. If *visit* returns a non-zero value that value should be object argument. If *visit* returns a non-zero value that value should be
returned immediately. returned immediately.
@ -121,7 +121,7 @@ must name its arguments exactly *visit* and *arg*:
.. c:function:: void Py_VISIT(PyObject *o) .. c:function:: void Py_VISIT(PyObject *o)
If *o* is not *NULL*, call the *visit* callback, with arguments *o* If *o* is not ``NULL``, call the *visit* callback, with arguments *o*
and *arg*. If *visit* returns a non-zero value, then return it. and *arg*. If *visit* returns a non-zero value, then return it.
Using this macro, :c:member:`~PyTypeObject.tp_traverse` handlers Using this macro, :c:member:`~PyTypeObject.tp_traverse` handlers
look like:: look like::
@ -134,7 +134,7 @@ must name its arguments exactly *visit* and *arg*:
return 0; return 0;
} }
The :c:member:`~PyTypeObject.tp_clear` handler must be of the :c:type:`inquiry` type, or *NULL* The :c:member:`~PyTypeObject.tp_clear` handler must be of the :c:type:`inquiry` type, or ``NULL``
if the object is immutable. if the object is immutable.

8
Doc/c-api/gen.rst
View File

@ -22,23 +22,23 @@ than explicitly calling :c:func:`PyGen_New` or :c:func:`PyGen_NewWithQualName`.
.. c:function:: int PyGen_Check(PyObject *ob) .. c:function:: int PyGen_Check(PyObject *ob)
Return true if *ob* is a generator object; *ob* must not be *NULL*. Return true if *ob* is a generator object; *ob* must not be ``NULL``.
.. c:function:: int PyGen_CheckExact(PyObject *ob) .. c:function:: int PyGen_CheckExact(PyObject *ob)
Return true if *ob*'s type is *PyGen_Type*; *ob* must not be *NULL*. Return true if *ob*'s type is *PyGen_Type*; *ob* must not be ``NULL``.
.. c:function:: PyObject* PyGen_New(PyFrameObject *frame) .. c:function:: PyObject* PyGen_New(PyFrameObject *frame)
Create and return a new generator object based on the *frame* object. Create and return a new generator object based on the *frame* object.
A reference to *frame* is stolen by this function. The argument must not be A reference to *frame* is stolen by this function. The argument must not be
*NULL*. ``NULL``.
.. c:function:: PyObject* PyGen_NewWithQualName(PyFrameObject *frame, PyObject *name, PyObject *qualname) .. c:function:: PyObject* PyGen_NewWithQualName(PyFrameObject *frame, PyObject *name, PyObject *qualname)
Create and return a new generator object based on the *frame* object, Create and return a new generator object based on the *frame* object,
with ``__name__`` and ``__qualname__`` set to *name* and *qualname*. with ``__name__`` and ``__qualname__`` set to *name* and *qualname*.
A reference to *frame* is stolen by this function. The *frame* argument A reference to *frame* is stolen by this function. The *frame* argument
must not be *NULL*. must not be ``NULL``.

18
Doc/c-api/import.rst
View File

@ -14,7 +14,7 @@ Importing Modules
single: modules (in module sys) single: modules (in module sys)
This is a simplified interface to :c:func:`PyImport_ImportModuleEx` below, This is a simplified interface to :c:func:`PyImport_ImportModuleEx` below,
leaving the *globals* and *locals* arguments set to *NULL* and *level* set leaving the *globals* and *locals* arguments set to ``NULL`` and *level* set
to 0. When the *name* to 0. When the *name*
argument contains a dot (when it specifies a submodule of a package), the argument contains a dot (when it specifies a submodule of a package), the
*fromlist* argument is set to the list ``['*']`` so that the return value is the *fromlist* argument is set to the list ``['*']`` so that the return value is the
@ -22,7 +22,7 @@ Importing Modules
be the case. (Unfortunately, this has an additional side effect when *name* in be the case. (Unfortunately, this has an additional side effect when *name* in
fact specifies a subpackage instead of a submodule: the submodules specified in fact specifies a subpackage instead of a submodule: the submodules specified in
the package's ``__all__`` variable are loaded.) Return a new reference to the the package's ``__all__`` variable are loaded.) Return a new reference to the
imported module, or *NULL* with an exception set on failure. A failing imported module, or ``NULL`` with an exception set on failure. A failing
import of a module doesn't leave the module in :data:`sys.modules`. import of a module doesn't leave the module in :data:`sys.modules`.
This function always uses absolute imports. This function always uses absolute imports.
@ -47,7 +47,7 @@ Importing Modules
function :func:`__import__`. function :func:`__import__`.
The return value is a new reference to the imported module or top-level The return value is a new reference to the imported module or top-level
package, or *NULL* with an exception set on failure. Like for package, or ``NULL`` with an exception set on failure. Like for
:func:`__import__`, the return value when a submodule of a package was :func:`__import__`, the return value when a submodule of a package was
requested is normally the top-level package, unless a non-empty *fromlist* requested is normally the top-level package, unless a non-empty *fromlist*
was given. was given.
@ -63,7 +63,7 @@ Importing Modules
this function directly. this function directly.
The return value is a new reference to the imported module or top-level package, The return value is a new reference to the imported module or top-level package,
or *NULL* with an exception set on failure. Like for :func:`__import__`, or ``NULL`` with an exception set on failure. Like for :func:`__import__`,
the return value when a submodule of a package was requested is normally the the return value when a submodule of a package was requested is normally the
top-level package, unless a non-empty *fromlist* was given. top-level package, unless a non-empty *fromlist* was given.
@ -91,7 +91,7 @@ Importing Modules
.. c:function:: PyObject* PyImport_ReloadModule(PyObject *m) .. c:function:: PyObject* PyImport_ReloadModule(PyObject *m)
Reload a module. Return a new reference to the reloaded module, or *NULL* with Reload a module. Return a new reference to the reloaded module, or ``NULL`` with
an exception set on failure (the module still exists in this case). an exception set on failure (the module still exists in this case).
@ -100,7 +100,7 @@ Importing Modules
Return the module object corresponding to a module name. The *name* argument Return the module object corresponding to a module name. The *name* argument
may be of the form ``package.module``. First check the modules dictionary if may be of the form ``package.module``. First check the modules dictionary if
there's one there, and if not, create a new one and insert it in the modules there's one there, and if not, create a new one and insert it in the modules
dictionary. Return *NULL* with an exception set on failure. dictionary. Return ``NULL`` with an exception set on failure.
.. note:: .. note::
@ -125,7 +125,7 @@ Importing Modules
Given a module name (possibly of the form ``package.module``) and a code object Given a module name (possibly of the form ``package.module``) and a code object
read from a Python bytecode file or obtained from the built-in function read from a Python bytecode file or obtained from the built-in function
:func:`compile`, load the module. Return a new reference to the module object, :func:`compile`, load the module. Return a new reference to the module object,
or *NULL* with an exception set if an error occurred. *name* or ``NULL`` with an exception set if an error occurred. *name*
is removed from :attr:`sys.modules` in error cases, even if *name* was already is removed from :attr:`sys.modules` in error cases, even if *name* was already
in :attr:`sys.modules` on entry to :c:func:`PyImport_ExecCodeModule`. Leaving in :attr:`sys.modules` on entry to :c:func:`PyImport_ExecCodeModule`. Leaving
incompletely initialized modules in :attr:`sys.modules` is dangerous, as imports of incompletely initialized modules in :attr:`sys.modules` is dangerous, as imports of
@ -262,7 +262,7 @@ Importing Modules
.. c:var:: const struct _frozen* PyImport_FrozenModules .. c:var:: const struct _frozen* PyImport_FrozenModules
This pointer is initialized to point to an array of :c:type:`struct _frozen` This pointer is initialized to point to an array of :c:type:`struct _frozen`
records, terminated by one whose members are all *NULL* or zero. When a frozen records, terminated by one whose members are all ``NULL`` or zero. When a frozen
module is imported, it is searched in this table. Third-party code could play module is imported, it is searched in this table. Third-party code could play
tricks with this to provide a dynamically created collection of frozen modules. tricks with this to provide a dynamically created collection of frozen modules.
@ -295,7 +295,7 @@ Importing Modules
.. c:function:: int PyImport_ExtendInittab(struct _inittab *newtab) .. c:function:: int PyImport_ExtendInittab(struct _inittab *newtab)
Add a collection of modules to the table of built-in modules. The *newtab* Add a collection of modules to the table of built-in modules. The *newtab*
array must end with a sentinel entry which contains *NULL* for the :attr:`name` array must end with a sentinel entry which contains ``NULL`` for the :attr:`name`
field; failure to provide the sentinel value can result in a memory fault. field; failure to provide the sentinel value can result in a memory fault.
Returns ``0`` on success or ``-1`` if insufficient memory could be allocated to Returns ``0`` on success or ``-1`` if insufficient memory could be allocated to
extend the internal table. In the event of failure, no modules are added to the extend the internal table. In the event of failure, no modules are added to the

76
Doc/c-api/init.rst
View File

@ -851,15 +851,15 @@ code, or when embedding the Python interpreter:
.. c:function:: PyThreadState* PyEval_SaveThread() .. c:function:: PyThreadState* PyEval_SaveThread()
Release the global interpreter lock (if it has been created) and reset the Release the global interpreter lock (if it has been created) and reset the
thread state to *NULL*, returning the previous thread state (which is not thread state to ``NULL``, returning the previous thread state (which is not
*NULL*). If the lock has been created, the current thread must have ``NULL``). If the lock has been created, the current thread must have
acquired it. acquired it.
.. c:function:: void PyEval_RestoreThread(PyThreadState *tstate) .. c:function:: void PyEval_RestoreThread(PyThreadState *tstate)
Acquire the global interpreter lock (if it has been created) and set the Acquire the global interpreter lock (if it has been created) and set the
thread state to *tstate*, which must not be *NULL*. If the lock has been thread state to *tstate*, which must not be ``NULL``. If the lock has been
created, the current thread must not have acquired it, otherwise deadlock created, the current thread must not have acquired it, otherwise deadlock
ensues. ensues.
@ -873,14 +873,14 @@ code, or when embedding the Python interpreter:
.. c:function:: PyThreadState* PyThreadState_Get() .. c:function:: PyThreadState* PyThreadState_Get()
Return the current thread state. The global interpreter lock must be held. Return the current thread state. The global interpreter lock must be held.
When the current thread state is *NULL*, this issues a fatal error (so that When the current thread state is ``NULL``, this issues a fatal error (so that
the caller needn't check for *NULL*). the caller needn't check for ``NULL``).
.. c:function:: PyThreadState* PyThreadState_Swap(PyThreadState *tstate) .. c:function:: PyThreadState* PyThreadState_Swap(PyThreadState *tstate)
Swap the current thread state with the thread state given by the argument Swap the current thread state with the thread state given by the argument
*tstate*, which may be *NULL*. The global interpreter lock must be held *tstate*, which may be ``NULL``. The global interpreter lock must be held
and is not released. and is not released.
@ -1054,7 +1054,7 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
.. c:function:: PyObject* PyInterpreterState_GetDict(PyInterpreterState *interp) .. c:function:: PyObject* PyInterpreterState_GetDict(PyInterpreterState *interp)
Return a dictionary in which interpreter-specific data may be stored. Return a dictionary in which interpreter-specific data may be stored.
If this function returns *NULL* then no exception has been raised and If this function returns ``NULL`` then no exception has been raised and
the caller should assume no interpreter-specific dict is available. the caller should assume no interpreter-specific dict is available.
This is not a replacement for :c:func:`PyModule_GetState()`, which This is not a replacement for :c:func:`PyModule_GetState()`, which
@ -1068,7 +1068,7 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
Return a dictionary in which extensions can store thread-specific state Return a dictionary in which extensions can store thread-specific state
information. Each extension should use a unique key to use to store state in information. Each extension should use a unique key to use to store state in
the dictionary. It is okay to call this function when no current thread state the dictionary. It is okay to call this function when no current thread state
is available. If this function returns *NULL*, no exception has been raised and is available. If this function returns ``NULL``, no exception has been raised and
the caller should assume no current thread state is available. the caller should assume no current thread state is available.
@ -1089,7 +1089,7 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
.. c:function:: void PyEval_AcquireThread(PyThreadState *tstate) .. c:function:: void PyEval_AcquireThread(PyThreadState *tstate)
Acquire the global interpreter lock and set the current thread state to Acquire the global interpreter lock and set the current thread state to
*tstate*, which should not be *NULL*. The lock must have been created earlier. *tstate*, which should not be ``NULL``. The lock must have been created earlier.
If this thread already has the lock, deadlock ensues. If this thread already has the lock, deadlock ensues.
.. note:: .. note::
@ -1110,9 +1110,9 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
.. c:function:: void PyEval_ReleaseThread(PyThreadState *tstate) .. c:function:: void PyEval_ReleaseThread(PyThreadState *tstate)
Reset the current thread state to *NULL* and release the global interpreter Reset the current thread state to ``NULL`` and release the global interpreter
lock. The lock must have been created earlier and must be held by the current lock. The lock must have been created earlier and must be held by the current
thread. The *tstate* argument, which must not be *NULL*, is only used to check thread. The *tstate* argument, which must not be ``NULL``, is only used to check
that it represents the current thread state --- if it isn't, a fatal error is that it represents the current thread state --- if it isn't, a fatal error is
reported. reported.
@ -1197,7 +1197,7 @@ function. You can create and destroy them using the following functions:
The return value points to the first thread state created in the new The return value points to the first thread state created in the new
sub-interpreter. This thread state is made in the current thread state. sub-interpreter. This thread state is made in the current thread state.
Note that no actual thread is created; see the discussion of thread states Note that no actual thread is created; see the discussion of thread states
below. If creation of the new interpreter is unsuccessful, *NULL* is below. If creation of the new interpreter is unsuccessful, ``NULL`` is
returned; no exception is set since the exception state is stored in the returned; no exception is set since the exception state is stored in the
current thread state and there may not be a current thread state. (Like all current thread state and there may not be a current thread state. (Like all
other Python/C API functions, the global interpreter lock must be held before other Python/C API functions, the global interpreter lock must be held before
@ -1228,7 +1228,7 @@ function. You can create and destroy them using the following functions:
Destroy the (sub-)interpreter represented by the given thread state. The given Destroy the (sub-)interpreter represented by the given thread state. The given
thread state must be the current thread state. See the discussion of thread thread state must be the current thread state. See the discussion of thread
states below. When the call returns, the current thread state is *NULL*. All states below. When the call returns, the current thread state is ``NULL``. All
thread states associated with this interpreter are destroyed. (The global thread states associated with this interpreter are destroyed. (The global
interpreter lock must be held before calling this function and is still held interpreter lock must be held before calling this function and is still held
when it returns.) :c:func:`Py_FinalizeEx` will destroy all sub-interpreters that when it returns.) :c:func:`Py_FinalizeEx` will destroy all sub-interpreters that
@ -1335,27 +1335,27 @@ Python-level trace functions in previous versions.
:const:`PyTrace_C_CALL`, :const:`PyTrace_C_EXCEPTION`, :const:`PyTrace_C_RETURN`, :const:`PyTrace_C_CALL`, :const:`PyTrace_C_EXCEPTION`, :const:`PyTrace_C_RETURN`,
or :const:`PyTrace_OPCODE`, and *arg* depends on the value of *what*: or :const:`PyTrace_OPCODE`, and *arg* depends on the value of *what*:
+------------------------------+--------------------------------------+ +------------------------------+----------------------------------------+
| Value of *what* | Meaning of *arg* | | Value of *what* | Meaning of *arg* |
+==============================+======================================+ +==============================+========================================+
| :const:`PyTrace_CALL` | Always :c:data:`Py_None`. | | :const:`PyTrace_CALL` | Always :c:data:`Py_None`. |
+------------------------------+--------------------------------------+ +------------------------------+----------------------------------------+
| :const:`PyTrace_EXCEPTION` | Exception information as returned by | | :const:`PyTrace_EXCEPTION` | Exception information as returned by |
| | :func:`sys.exc_info`. | | | :func:`sys.exc_info`. |
+------------------------------+--------------------------------------+ +------------------------------+----------------------------------------+
| :const:`PyTrace_LINE` | Always :c:data:`Py_None`. | | :const:`PyTrace_LINE` | Always :c:data:`Py_None`. |
+------------------------------+--------------------------------------+ +------------------------------+----------------------------------------+
| :const:`PyTrace_RETURN` | Value being returned to the caller, | | :const:`PyTrace_RETURN` | Value being returned to the caller, |
| | or *NULL* if caused by an exception. | | | or ``NULL`` if caused by an exception. |
+------------------------------+--------------------------------------+ +------------------------------+----------------------------------------+
| :const:`PyTrace_C_CALL` | Function object being called. | | :const:`PyTrace_C_CALL` | Function object being called. |
+------------------------------+--------------------------------------+ +------------------------------+----------------------------------------+
| :const:`PyTrace_C_EXCEPTION` | Function object being called. | | :const:`PyTrace_C_EXCEPTION` | Function object being called. |
+------------------------------+--------------------------------------+ +------------------------------+----------------------------------------+
| :const:`PyTrace_C_RETURN` | Function object being called. | | :const:`PyTrace_C_RETURN` | Function object being called. |
+------------------------------+--------------------------------------+ +------------------------------+----------------------------------------+
| :const:`PyTrace_OPCODE` | Always :c:data:`Py_None`. | | :const:`PyTrace_OPCODE` | Always :c:data:`Py_None`. |
+------------------------------+--------------------------------------+ +------------------------------+----------------------------------------+
.. c:var:: int PyTrace_CALL .. c:var:: int PyTrace_CALL
@ -1419,7 +1419,7 @@ Python-level trace functions in previous versions.
.. c:function:: void PyEval_SetProfile(Py_tracefunc func, PyObject *obj) .. c:function:: void PyEval_SetProfile(Py_tracefunc func, PyObject *obj)
Set the profiler function to *func*. The *obj* parameter is passed to the Set the profiler function to *func*. The *obj* parameter is passed to the
function as its first parameter, and may be any Python object, or *NULL*. If function as its first parameter, and may be any Python object, or ``NULL``. If
the profile function needs to maintain state, using a different value for *obj* the profile function needs to maintain state, using a different value for *obj*
for each thread provides a convenient and thread-safe place to store it. The for each thread provides a convenient and thread-safe place to store it. The
profile function is called for all monitored events except :const:`PyTrace_LINE` profile function is called for all monitored events except :const:`PyTrace_LINE`
@ -1542,7 +1542,7 @@ is not possible due to its implementation being opaque at build time.
.. c:function:: Py_tss_t* PyThread_tss_alloc() .. c:function:: Py_tss_t* PyThread_tss_alloc()
Return a value which is the same state as a value initialized with Return a value which is the same state as a value initialized with
:c:macro:`Py_tss_NEEDS_INIT`, or *NULL* in the case of dynamic allocation :c:macro:`Py_tss_NEEDS_INIT`, or ``NULL`` in the case of dynamic allocation
failure. failure.
@ -1561,7 +1561,7 @@ is not possible due to its implementation being opaque at build time.
Methods Methods
~~~~~~~ ~~~~~~~
The parameter *key* of these functions must not be *NULL*. Moreover, the The parameter *key* of these functions must not be ``NULL``. Moreover, the
behaviors of :c:func:`PyThread_tss_set` and :c:func:`PyThread_tss_get` are behaviors of :c:func:`PyThread_tss_set` and :c:func:`PyThread_tss_get` are
undefined if the given :c:type:`Py_tss_t` has not been initialized by undefined if the given :c:type:`Py_tss_t` has not been initialized by
:c:func:`PyThread_tss_create`. :c:func:`PyThread_tss_create`.
@ -1601,7 +1601,7 @@ undefined if the given :c:type:`Py_tss_t` has not been initialized by
.. c:function:: void* PyThread_tss_get(Py_tss_t *key) .. c:function:: void* PyThread_tss_get(Py_tss_t *key)
Return the :c:type:`void\*` value associated with a TSS key in the current Return the :c:type:`void\*` value associated with a TSS key in the current
thread. This returns *NULL* if no value is associated with the key in the thread. This returns ``NULL`` if no value is associated with the key in the
current thread. current thread.

14
Doc/c-api/intro.rst
View File

@ -152,7 +152,7 @@ complete listing.
.. c:macro:: Py_GETENV(s) .. c:macro:: Py_GETENV(s)
Like ``getenv(s)``, but returns *NULL* if :option:`-E` was passed on the Like ``getenv(s)``, but returns ``NULL`` if :option:`-E` was passed on the
command line (i.e. if ``Py_IgnoreEnvironmentFlag`` is set). command line (i.e. if ``Py_IgnoreEnvironmentFlag`` is set).
.. c:macro:: Py_UNUSED(arg) .. c:macro:: Py_UNUSED(arg)
@ -475,7 +475,7 @@ functions in the Python/C API can raise exceptions, unless an explicit claim is
made otherwise in a function's documentation. In general, when a function made otherwise in a function's documentation. In general, when a function
encounters an error, it sets an exception, discards any object references that encounters an error, it sets an exception, discards any object references that
it owns, and returns an error indicator. If not documented otherwise, this it owns, and returns an error indicator. If not documented otherwise, this
indicator is either *NULL* or ``-1``, depending on the function's return type. indicator is either ``NULL`` or ``-1``, depending on the function's return type.
A few functions return a Boolean true/false result, with false indicating an A few functions return a Boolean true/false result, with false indicating an
error. Very few functions return no explicit error indicator or have an error. Very few functions return no explicit error indicator or have an
ambiguous return value, and require explicit testing for errors with ambiguous return value, and require explicit testing for errors with
@ -490,13 +490,13 @@ using global storage in an unthreaded application). A thread can be in one of
two states: an exception has occurred, or not. The function two states: an exception has occurred, or not. The function
:c:func:`PyErr_Occurred` can be used to check for this: it returns a borrowed :c:func:`PyErr_Occurred` can be used to check for this: it returns a borrowed
reference to the exception type object when an exception has occurred, and reference to the exception type object when an exception has occurred, and
*NULL* otherwise. There are a number of functions to set the exception state: ``NULL`` otherwise. There are a number of functions to set the exception state:
:c:func:`PyErr_SetString` is the most common (though not the most general) :c:func:`PyErr_SetString` is the most common (though not the most general)
function to set the exception state, and :c:func:`PyErr_Clear` clears the function to set the exception state, and :c:func:`PyErr_Clear` clears the
exception state. exception state.
The full exception state consists of three objects (all of which can be The full exception state consists of three objects (all of which can be
*NULL*): the exception type, the corresponding exception value, and the ``NULL``): the exception type, the corresponding exception value, and the
traceback. These have the same meanings as the Python result of traceback. These have the same meanings as the Python result of
``sys.exc_info()``; however, they are not the same: the Python objects represent ``sys.exc_info()``; however, they are not the same: the Python objects represent
the last exception being handled by a Python :keyword:`try` ... the last exception being handled by a Python :keyword:`try` ...
@ -597,10 +597,10 @@ Here is the corresponding C code, in all its glory::
This example represents an endorsed use of the ``goto`` statement in C! This example represents an endorsed use of the ``goto`` statement in C!
It illustrates the use of :c:func:`PyErr_ExceptionMatches` and It illustrates the use of :c:func:`PyErr_ExceptionMatches` and
:c:func:`PyErr_Clear` to handle specific exceptions, and the use of :c:func:`PyErr_Clear` to handle specific exceptions, and the use of
:c:func:`Py_XDECREF` to dispose of owned references that may be *NULL* (note the :c:func:`Py_XDECREF` to dispose of owned references that may be ``NULL`` (note the
``'X'`` in the name; :c:func:`Py_DECREF` would crash when confronted with a ``'X'`` in the name; :c:func:`Py_DECREF` would crash when confronted with a
*NULL* reference). It is important that the variables used to hold owned ``NULL`` reference). It is important that the variables used to hold owned
references are initialized to *NULL* for this to work; likewise, the proposed references are initialized to ``NULL`` for this to work; likewise, the proposed
return value is initialized to ``-1`` (failure) and only set to success after return value is initialized to ``-1`` (failure) and only set to success after
the final call made is successful. the final call made is successful.

4
Doc/c-api/iter.rst
View File

@ -16,8 +16,8 @@ There are two functions specifically for working with iterators.
Return the next value from the iteration *o*. The object must be an iterator Return the next value from the iteration *o*. The object must be an iterator
(it is up to the caller to check this). If there are no remaining values, (it is up to the caller to check this). If there are no remaining values,
returns *NULL* with no exception set. If an error occurs while retrieving returns ``NULL`` with no exception set. If an error occurs while retrieving
the item, returns *NULL* and passes along the exception. the item, returns ``NULL`` and passes along the exception.
To write a loop which iterates over an iterator, the C code should look To write a loop which iterates over an iterator, the C code should look
something like this:: something like this::

8
Doc/c-api/list.rst
View File

@ -33,7 +33,7 @@ List Objects
.. c:function:: PyObject* PyList_New(Py_ssize_t len) .. c:function:: PyObject* PyList_New(Py_ssize_t len)
Return a new list of length *len* on success, or *NULL* on failure. Return a new list of length *len* on success, or ``NULL`` on failure.
.. note:: .. note::
@ -61,7 +61,7 @@ List Objects
Return the object at position *index* in the list pointed to by *list*. The Return the object at position *index* in the list pointed to by *list*. The
position must be non-negative; indexing from the end of the list is not position must be non-negative; indexing from the end of the list is not
supported. If *index* is out of bounds (<0 or >=len(list)), supported. If *index* is out of bounds (<0 or >=len(list)),
return *NULL* and set an :exc:`IndexError` exception. return ``NULL`` and set an :exc:`IndexError` exception.
.. c:function:: PyObject* PyList_GET_ITEM(PyObject *list, Py_ssize_t i) .. c:function:: PyObject* PyList_GET_ITEM(PyObject *list, Py_ssize_t i)
@ -111,7 +111,7 @@ List Objects
.. c:function:: PyObject* PyList_GetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high) .. c:function:: PyObject* PyList_GetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high)
Return a list of the objects in *list* containing the objects *between* *low* Return a list of the objects in *list* containing the objects *between* *low*
and *high*. Return *NULL* and set an exception if unsuccessful. Analogous and *high*. Return ``NULL`` and set an exception if unsuccessful. Analogous
to ``list[low:high]``. Indexing from the end of the list is not supported. to ``list[low:high]``. Indexing from the end of the list is not supported.
@ -119,7 +119,7 @@ List Objects
Set the slice of *list* between *low* and *high* to the contents of Set the slice of *list* between *low* and *high* to the contents of
*itemlist*. Analogous to ``list[low:high] = itemlist``. The *itemlist* may *itemlist*. Analogous to ``list[low:high] = itemlist``. The *itemlist* may
be *NULL*, indicating the assignment of an empty list (slice deletion). be ``NULL``, indicating the assignment of an empty list (slice deletion).
Return ``0`` on success, ``-1`` on failure. Indexing from the end of the Return ``0`` on success, ``-1`` on failure. Indexing from the end of the
list is not supported. list is not supported.

18
Doc/c-api/long.rst
View File

@ -38,7 +38,7 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
.. c:function:: PyObject* PyLong_FromLong(long v) .. c:function:: PyObject* PyLong_FromLong(long v)
Return a new :c:type:`PyLongObject` object from *v*, or *NULL* on failure. Return a new :c:type:`PyLongObject` object from *v*, or ``NULL`` on failure.
The current implementation keeps an array of integer objects for all integers The current implementation keeps an array of integer objects for all integers
between ``-5`` and ``256``, when you create an int in that range you actually between ``-5`` and ``256``, when you create an int in that range you actually
@ -48,43 +48,43 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
.. c:function:: PyObject* PyLong_FromUnsignedLong(unsigned long v) .. c:function:: PyObject* PyLong_FromUnsignedLong(unsigned long v)
Return a new :c:type:`PyLongObject` object from a C :c:type:`unsigned long`, or Return a new :c:type:`PyLongObject` object from a C :c:type:`unsigned long`, or
*NULL* on failure. ``NULL`` on failure.
.. c:function:: PyObject* PyLong_FromSsize_t(Py_ssize_t v) .. c:function:: PyObject* PyLong_FromSsize_t(Py_ssize_t v)
Return a new :c:type:`PyLongObject` object from a C :c:type:`Py_ssize_t`, or Return a new :c:type:`PyLongObject` object from a C :c:type:`Py_ssize_t`, or
*NULL* on failure. ``NULL`` on failure.
.. c:function:: PyObject* PyLong_FromSize_t(size_t v) .. c:function:: PyObject* PyLong_FromSize_t(size_t v)
Return a new :c:type:`PyLongObject` object from a C :c:type:`size_t`, or Return a new :c:type:`PyLongObject` object from a C :c:type:`size_t`, or
*NULL* on failure. ``NULL`` on failure.
.. c:function:: PyObject* PyLong_FromLongLong(long long v) .. c:function:: PyObject* PyLong_FromLongLong(long long v)
Return a new :c:type:`PyLongObject` object from a C :c:type:`long long`, or *NULL* Return a new :c:type:`PyLongObject` object from a C :c:type:`long long`, or ``NULL``
on failure. on failure.
.. c:function:: PyObject* PyLong_FromUnsignedLongLong(unsigned long long v) .. c:function:: PyObject* PyLong_FromUnsignedLongLong(unsigned long long v)
Return a new :c:type:`PyLongObject` object from a C :c:type:`unsigned long long`, Return a new :c:type:`PyLongObject` object from a C :c:type:`unsigned long long`,
or *NULL* on failure. or ``NULL`` on failure.
.. c:function:: PyObject* PyLong_FromDouble(double v) .. c:function:: PyObject* PyLong_FromDouble(double v)
Return a new :c:type:`PyLongObject` object from the integer part of *v*, or Return a new :c:type:`PyLongObject` object from the integer part of *v*, or
*NULL* on failure. ``NULL`` on failure.
.. c:function:: PyObject* PyLong_FromString(const char *str, char **pend, int base) .. c:function:: PyObject* PyLong_FromString(const char *str, char **pend, int base)
Return a new :c:type:`PyLongObject` based on the string value in *str*, which Return a new :c:type:`PyLongObject` based on the string value in *str*, which
is interpreted according to the radix in *base*. If *pend* is non-*NULL*, is interpreted according to the radix in *base*. If *pend* is non-``NULL``,
*\*pend* will point to the first character in *str* which follows the *\*pend* will point to the first character in *str* which follows the
representation of the number. If *base* is ``0``, *str* is interpreted using representation of the number. If *base* is ``0``, *str* is interpreted using
the :ref:`integers` definition; in this case, leading zeros in a the :ref:`integers` definition; in this case, leading zeros in a
@ -334,4 +334,4 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
is only assured to produce a usable :c:type:`void` pointer for values created is only assured to produce a usable :c:type:`void` pointer for values created
with :c:func:`PyLong_FromVoidPtr`. with :c:func:`PyLong_FromVoidPtr`.
Returns *NULL* on error. Use :c:func:`PyErr_Occurred` to disambiguate. Returns ``NULL`` on error. Use :c:func:`PyErr_Occurred` to disambiguate.

8
Doc/c-api/mapping.rst
View File

@ -29,7 +29,7 @@ See also :c:func:`PyObject_GetItem`, :c:func:`PyObject_SetItem` and
.. c:function:: PyObject* PyMapping_GetItemString(PyObject *o, const char *key) .. c:function:: PyObject* PyMapping_GetItemString(PyObject *o, const char *key)
Return element of *o* corresponding to the string *key* or *NULL* on failure. Return element of *o* corresponding to the string *key* or ``NULL`` on failure.
This is the equivalent of the Python expression ``o[key]``. This is the equivalent of the Python expression ``o[key]``.
See also :c:func:`PyObject_GetItem`. See also :c:func:`PyObject_GetItem`.
@ -79,7 +79,7 @@ See also :c:func:`PyObject_GetItem`, :c:func:`PyObject_SetItem` and
.. c:function:: PyObject* PyMapping_Keys(PyObject *o) .. c:function:: PyObject* PyMapping_Keys(PyObject *o)
On success, return a list of the keys in object *o*. On failure, return On success, return a list of the keys in object *o*. On failure, return
*NULL*. ``NULL``.
.. versionchanged:: 3.7 .. versionchanged:: 3.7
Previously, the function returned a list or a tuple. Previously, the function returned a list or a tuple.
@ -88,7 +88,7 @@ See also :c:func:`PyObject_GetItem`, :c:func:`PyObject_SetItem` and
.. c:function:: PyObject* PyMapping_Values(PyObject *o) .. c:function:: PyObject* PyMapping_Values(PyObject *o)
On success, return a list of the values in object *o*. On failure, return On success, return a list of the values in object *o*. On failure, return
*NULL*. ``NULL``.
.. versionchanged:: 3.7 .. versionchanged:: 3.7
Previously, the function returned a list or a tuple. Previously, the function returned a list or a tuple.
@ -97,7 +97,7 @@ See also :c:func:`PyObject_GetItem`, :c:func:`PyObject_SetItem` and
.. c:function:: PyObject* PyMapping_Items(PyObject *o) .. c:function:: PyObject* PyMapping_Items(PyObject *o)
On success, return a list of the items in object *o*, where each item is a On success, return a list of the items in object *o*, where each item is a
tuple containing a key-value pair. On failure, return *NULL*. tuple containing a key-value pair. On failure, return ``NULL``.
.. versionchanged:: 3.7 .. versionchanged:: 3.7
Previously, the function returned a list or a tuple. Previously, the function returned a list or a tuple.

6
Doc/c-api/marshal.rst
View File

@ -67,7 +67,7 @@ The following functions allow marshalled values to be read back in.
reading. reading.
On error, sets the appropriate exception (:exc:`EOFError`, :exc:`ValueError` On error, sets the appropriate exception (:exc:`EOFError`, :exc:`ValueError`
or :exc:`TypeError`) and returns *NULL*. or :exc:`TypeError`) and returns ``NULL``.
.. c:function:: PyObject* PyMarshal_ReadLastObjectFromFile(FILE *file) .. c:function:: PyObject* PyMarshal_ReadLastObjectFromFile(FILE *file)
@ -81,7 +81,7 @@ The following functions allow marshalled values to be read back in.
anything else from the file. anything else from the file.
On error, sets the appropriate exception (:exc:`EOFError`, :exc:`ValueError` On error, sets the appropriate exception (:exc:`EOFError`, :exc:`ValueError`
or :exc:`TypeError`) and returns *NULL*. or :exc:`TypeError`) and returns ``NULL``.
.. c:function:: PyObject* PyMarshal_ReadObjectFromString(const char *data, Py_ssize_t len) .. c:function:: PyObject* PyMarshal_ReadObjectFromString(const char *data, Py_ssize_t len)
@ -90,5 +90,5 @@ The following functions allow marshalled values to be read back in.
containing *len* bytes pointed to by *data*. containing *len* bytes pointed to by *data*.
On error, sets the appropriate exception (:exc:`EOFError`, :exc:`ValueError` On error, sets the appropriate exception (:exc:`EOFError`, :exc:`ValueError`
or :exc:`TypeError`) and returns *NULL*. or :exc:`TypeError`) and returns ``NULL``.

56
Doc/c-api/memory.rst
View File

@ -110,9 +110,9 @@ zero bytes.
.. c:function:: void* PyMem_RawMalloc(size_t n) .. c:function:: void* PyMem_RawMalloc(size_t n)
Allocates *n* bytes and returns a pointer of type :c:type:`void\*` to the Allocates *n* bytes and returns a pointer of type :c:type:`void\*` to the
allocated memory, or *NULL* if the request fails. allocated memory, or ``NULL`` if the request fails.
Requesting zero bytes returns a distinct non-*NULL* pointer if possible, as Requesting zero bytes returns a distinct non-``NULL`` pointer if possible, as
if ``PyMem_RawMalloc(1)`` had been called instead. The memory will not have if ``PyMem_RawMalloc(1)`` had been called instead. The memory will not have
been initialized in any way. been initialized in any way.
@ -120,11 +120,11 @@ zero bytes.
.. c:function:: void* PyMem_RawCalloc(size_t nelem, size_t elsize) .. c:function:: void* PyMem_RawCalloc(size_t nelem, size_t elsize)
Allocates *nelem* elements each whose size in bytes is *elsize* and returns Allocates *nelem* elements each whose size in bytes is *elsize* and returns
a pointer of type :c:type:`void\*` to the allocated memory, or *NULL* if the a pointer of type :c:type:`void\*` to the allocated memory, or ``NULL`` if the
request fails. The memory is initialized to zeros. request fails. The memory is initialized to zeros.
Requesting zero elements or elements of size zero bytes returns a distinct Requesting zero elements or elements of size zero bytes returns a distinct
non-*NULL* pointer if possible, as if ``PyMem_RawCalloc(1, 1)`` had been non-``NULL`` pointer if possible, as if ``PyMem_RawCalloc(1, 1)`` had been
called instead. called instead.
.. versionadded:: 3.5 .. versionadded:: 3.5
@ -135,15 +135,15 @@ zero bytes.
Resizes the memory block pointed to by *p* to *n* bytes. The contents will Resizes the memory block pointed to by *p* to *n* bytes. The contents will
be unchanged to the minimum of the old and the new sizes. be unchanged to the minimum of the old and the new sizes.
If *p* is *NULL*, the call is equivalent to ``PyMem_RawMalloc(n)``; else if If *p* is ``NULL``, the call is equivalent to ``PyMem_RawMalloc(n)``; else if
*n* is equal to zero, the memory block is resized but is not freed, and the *n* is equal to zero, the memory block is resized but is not freed, and the
returned pointer is non-*NULL*. returned pointer is non-``NULL``.
Unless *p* is *NULL*, it must have been returned by a previous call to Unless *p* is ``NULL``, it must have been returned by a previous call to
:c:func:`PyMem_RawMalloc`, :c:func:`PyMem_RawRealloc` or :c:func:`PyMem_RawMalloc`, :c:func:`PyMem_RawRealloc` or
:c:func:`PyMem_RawCalloc`. :c:func:`PyMem_RawCalloc`.
If the request fails, :c:func:`PyMem_RawRealloc` returns *NULL* and *p* If the request fails, :c:func:`PyMem_RawRealloc` returns ``NULL`` and *p*
remains a valid pointer to the previous memory area. remains a valid pointer to the previous memory area.
@ -154,7 +154,7 @@ zero bytes.
:c:func:`PyMem_RawCalloc`. Otherwise, or if ``PyMem_RawFree(p)`` has been :c:func:`PyMem_RawCalloc`. Otherwise, or if ``PyMem_RawFree(p)`` has been
called before, undefined behavior occurs. called before, undefined behavior occurs.
If *p* is *NULL*, no operation is performed. If *p* is ``NULL``, no operation is performed.
.. _memoryinterface: .. _memoryinterface:
@ -181,9 +181,9 @@ The :ref:`default memory allocator <default-memory-allocators>` uses the
.. c:function:: void* PyMem_Malloc(size_t n) .. c:function:: void* PyMem_Malloc(size_t n)
Allocates *n* bytes and returns a pointer of type :c:type:`void\*` to the Allocates *n* bytes and returns a pointer of type :c:type:`void\*` to the
allocated memory, or *NULL* if the request fails. allocated memory, or ``NULL`` if the request fails.
Requesting zero bytes returns a distinct non-*NULL* pointer if possible, as Requesting zero bytes returns a distinct non-``NULL`` pointer if possible, as
if ``PyMem_Malloc(1)`` had been called instead. The memory will not have if ``PyMem_Malloc(1)`` had been called instead. The memory will not have
been initialized in any way. been initialized in any way.
@ -191,11 +191,11 @@ The :ref:`default memory allocator <default-memory-allocators>` uses the
.. c:function:: void* PyMem_Calloc(size_t nelem, size_t elsize) .. c:function:: void* PyMem_Calloc(size_t nelem, size_t elsize)
Allocates *nelem* elements each whose size in bytes is *elsize* and returns Allocates *nelem* elements each whose size in bytes is *elsize* and returns
a pointer of type :c:type:`void\*` to the allocated memory, or *NULL* if the a pointer of type :c:type:`void\*` to the allocated memory, or ``NULL`` if the
request fails. The memory is initialized to zeros. request fails. The memory is initialized to zeros.
Requesting zero elements or elements of size zero bytes returns a distinct Requesting zero elements or elements of size zero bytes returns a distinct
non-*NULL* pointer if possible, as if ``PyMem_Calloc(1, 1)`` had been called non-``NULL`` pointer if possible, as if ``PyMem_Calloc(1, 1)`` had been called
instead. instead.
.. versionadded:: 3.5 .. versionadded:: 3.5
@ -206,14 +206,14 @@ The :ref:`default memory allocator <default-memory-allocators>` uses the
Resizes the memory block pointed to by *p* to *n* bytes. The contents will be Resizes the memory block pointed to by *p* to *n* bytes. The contents will be
unchanged to the minimum of the old and the new sizes. unchanged to the minimum of the old and the new sizes.
If *p* is *NULL*, the call is equivalent to ``PyMem_Malloc(n)``; else if *n* If *p* is ``NULL``, the call is equivalent to ``PyMem_Malloc(n)``; else if *n*
is equal to zero, the memory block is resized but is not freed, and the is equal to zero, the memory block is resized but is not freed, and the
returned pointer is non-*NULL*. returned pointer is non-``NULL``.
Unless *p* is *NULL*, it must have been returned by a previous call to Unless *p* is ``NULL``, it must have been returned by a previous call to
:c:func:`PyMem_Malloc`, :c:func:`PyMem_Realloc` or :c:func:`PyMem_Calloc`. :c:func:`PyMem_Malloc`, :c:func:`PyMem_Realloc` or :c:func:`PyMem_Calloc`.
If the request fails, :c:func:`PyMem_Realloc` returns *NULL* and *p* remains If the request fails, :c:func:`PyMem_Realloc` returns ``NULL`` and *p* remains
a valid pointer to the previous memory area. a valid pointer to the previous memory area.
@ -224,7 +224,7 @@ The :ref:`default memory allocator <default-memory-allocators>` uses the
:c:func:`PyMem_Calloc`. Otherwise, or if ``PyMem_Free(p)`` has been called :c:func:`PyMem_Calloc`. Otherwise, or if ``PyMem_Free(p)`` has been called
before, undefined behavior occurs. before, undefined behavior occurs.
If *p* is *NULL*, no operation is performed. If *p* is ``NULL``, no operation is performed.
The following type-oriented macros are provided for convenience. Note that The following type-oriented macros are provided for convenience. Note that
*TYPE* refers to any C type. *TYPE* refers to any C type.
@ -241,7 +241,7 @@ The following type-oriented macros are provided for convenience. Note that
Same as :c:func:`PyMem_Realloc`, but the memory block is resized to ``(n * Same as :c:func:`PyMem_Realloc`, but the memory block is resized to ``(n *
sizeof(TYPE))`` bytes. Returns a pointer cast to :c:type:`TYPE\*`. On return, sizeof(TYPE))`` bytes. Returns a pointer cast to :c:type:`TYPE\*`. On return,
*p* will be a pointer to the new memory area, or *NULL* in the event of *p* will be a pointer to the new memory area, or ``NULL`` in the event of
failure. failure.
This is a C preprocessor macro; *p* is always reassigned. Save the original This is a C preprocessor macro; *p* is always reassigned. Save the original
@ -283,9 +283,9 @@ The :ref:`default object allocator <default-memory-allocators>` uses the
.. c:function:: void* PyObject_Malloc(size_t n) .. c:function:: void* PyObject_Malloc(size_t n)
Allocates *n* bytes and returns a pointer of type :c:type:`void\*` to the Allocates *n* bytes and returns a pointer of type :c:type:`void\*` to the
allocated memory, or *NULL* if the request fails. allocated memory, or ``NULL`` if the request fails.
Requesting zero bytes returns a distinct non-*NULL* pointer if possible, as Requesting zero bytes returns a distinct non-``NULL`` pointer if possible, as
if ``PyObject_Malloc(1)`` had been called instead. The memory will not have if ``PyObject_Malloc(1)`` had been called instead. The memory will not have
been initialized in any way. been initialized in any way.
@ -293,11 +293,11 @@ The :ref:`default object allocator <default-memory-allocators>` uses the
.. c:function:: void* PyObject_Calloc(size_t nelem, size_t elsize) .. c:function:: void* PyObject_Calloc(size_t nelem, size_t elsize)
Allocates *nelem* elements each whose size in bytes is *elsize* and returns Allocates *nelem* elements each whose size in bytes is *elsize* and returns
a pointer of type :c:type:`void\*` to the allocated memory, or *NULL* if the a pointer of type :c:type:`void\*` to the allocated memory, or ``NULL`` if the
request fails. The memory is initialized to zeros. request fails. The memory is initialized to zeros.
Requesting zero elements or elements of size zero bytes returns a distinct Requesting zero elements or elements of size zero bytes returns a distinct
non-*NULL* pointer if possible, as if ``PyObject_Calloc(1, 1)`` had been called non-``NULL`` pointer if possible, as if ``PyObject_Calloc(1, 1)`` had been called
instead. instead.
.. versionadded:: 3.5 .. versionadded:: 3.5
@ -308,14 +308,14 @@ The :ref:`default object allocator <default-memory-allocators>` uses the
Resizes the memory block pointed to by *p* to *n* bytes. The contents will be Resizes the memory block pointed to by *p* to *n* bytes. The contents will be
unchanged to the minimum of the old and the new sizes. unchanged to the minimum of the old and the new sizes.
If *p* is *NULL*, the call is equivalent to ``PyObject_Malloc(n)``; else if *n* If *p* is ``NULL``, the call is equivalent to ``PyObject_Malloc(n)``; else if *n*
is equal to zero, the memory block is resized but is not freed, and the is equal to zero, the memory block is resized but is not freed, and the
returned pointer is non-*NULL*. returned pointer is non-``NULL``.
Unless *p* is *NULL*, it must have been returned by a previous call to Unless *p* is ``NULL``, it must have been returned by a previous call to
:c:func:`PyObject_Malloc`, :c:func:`PyObject_Realloc` or :c:func:`PyObject_Calloc`. :c:func:`PyObject_Malloc`, :c:func:`PyObject_Realloc` or :c:func:`PyObject_Calloc`.
If the request fails, :c:func:`PyObject_Realloc` returns *NULL* and *p* remains If the request fails, :c:func:`PyObject_Realloc` returns ``NULL`` and *p* remains
a valid pointer to the previous memory area. a valid pointer to the previous memory area.
@ -326,7 +326,7 @@ The :ref:`default object allocator <default-memory-allocators>` uses the
:c:func:`PyObject_Calloc`. Otherwise, or if ``PyObject_Free(p)`` has been called :c:func:`PyObject_Calloc`. Otherwise, or if ``PyObject_Free(p)`` has been called
before, undefined behavior occurs. before, undefined behavior occurs.
If *p* is *NULL*, no operation is performed. If *p* is ``NULL``, no operation is performed.
.. _default-memory-allocators: .. _default-memory-allocators:

2
Doc/c-api/memoryview.rst
View File

@ -57,7 +57,7 @@ any other object.
.. c:function:: Py_buffer *PyMemoryView_GET_BASE(PyObject *mview) .. c:function:: Py_buffer *PyMemoryView_GET_BASE(PyObject *mview)
Return either a pointer to the exporting object that the memoryview is based Return either a pointer to the exporting object that the memoryview is based
on or *NULL* if the memoryview has been created by one of the functions on or ``NULL`` if the memoryview has been created by one of the functions
:c:func:`PyMemoryView_FromMemory` or :c:func:`PyMemoryView_FromBuffer`. :c:func:`PyMemoryView_FromMemory` or :c:func:`PyMemoryView_FromBuffer`.
*mview* **must** be a memoryview instance. *mview* **must** be a memoryview instance.

6
Doc/c-api/method.rst
View File

@ -21,7 +21,7 @@ to bind a :c:data:`PyCFunction` to a class object. It replaces the former call
.. c:function:: int PyInstanceMethod_Check(PyObject *o) .. c:function:: int PyInstanceMethod_Check(PyObject *o)
Return true if *o* is an instance method object (has type Return true if *o* is an instance method object (has type
:c:data:`PyInstanceMethod_Type`). The parameter must not be *NULL*. :c:data:`PyInstanceMethod_Type`). The parameter must not be ``NULL``.
.. c:function:: PyObject* PyInstanceMethod_New(PyObject *func) .. c:function:: PyObject* PyInstanceMethod_New(PyObject *func)
@ -64,14 +64,14 @@ no longer available.
.. c:function:: int PyMethod_Check(PyObject *o) .. c:function:: int PyMethod_Check(PyObject *o)
Return true if *o* is a method object (has type :c:data:`PyMethod_Type`). The Return true if *o* is a method object (has type :c:data:`PyMethod_Type`). The
parameter must not be *NULL*. parameter must not be ``NULL``.
.. c:function:: PyObject* PyMethod_New(PyObject *func, PyObject *self) .. c:function:: PyObject* PyMethod_New(PyObject *func, PyObject *self)
Return a new method object, with *func* being any callable object and *self* Return a new method object, with *func* being any callable object and *self*
the instance the method should be bound. *func* is the function that will the instance the method should be bound. *func* is the function that will
be called when the method is called. *self* must not be *NULL*. be called when the method is called. *self* must not be ``NULL``.
.. c:function:: PyObject* PyMethod_Function(PyObject *meth) .. c:function:: PyObject* PyMethod_Function(PyObject *meth)

34
Doc/c-api/module.rst
View File

@ -61,7 +61,7 @@ Module Objects
Return the dictionary object that implements *module*'s namespace; this object Return the dictionary object that implements *module*'s namespace; this object
is the same as the :attr:`~object.__dict__` attribute of the module object. is the same as the :attr:`~object.__dict__` attribute of the module object.
If *module* is not a module object (or a subtype of a module object), If *module* is not a module object (or a subtype of a module object),
:exc:`SystemError` is raised and *NULL* is returned. :exc:`SystemError` is raised and ``NULL`` is returned.
It is recommended extensions use other :c:func:`PyModule_\*` and It is recommended extensions use other :c:func:`PyModule_\*` and
:c:func:`PyObject_\*` functions rather than directly manipulate a module's :c:func:`PyObject_\*` functions rather than directly manipulate a module's
@ -75,7 +75,7 @@ Module Objects
single: SystemError (built-in exception) single: SystemError (built-in exception)
Return *module*'s :attr:`__name__` value. If the module does not provide one, Return *module*'s :attr:`__name__` value. If the module does not provide one,
or if it is not a string, :exc:`SystemError` is raised and *NULL* is returned. or if it is not a string, :exc:`SystemError` is raised and ``NULL`` is returned.
.. versionadded:: 3.3 .. versionadded:: 3.3
@ -88,14 +88,14 @@ Module Objects
.. c:function:: void* PyModule_GetState(PyObject *module) .. c:function:: void* PyModule_GetState(PyObject *module)
Return the "state" of the module, that is, a pointer to the block of memory Return the "state" of the module, that is, a pointer to the block of memory
allocated at module creation time, or *NULL*. See allocated at module creation time, or ``NULL``. See
:c:member:`PyModuleDef.m_size`. :c:member:`PyModuleDef.m_size`.
.. c:function:: PyModuleDef* PyModule_GetDef(PyObject *module) .. c:function:: PyModuleDef* PyModule_GetDef(PyObject *module)
Return a pointer to the :c:type:`PyModuleDef` struct from which the module was Return a pointer to the :c:type:`PyModuleDef` struct from which the module was
created, or *NULL* if the module wasn't created from a definition. created, or ``NULL`` if the module wasn't created from a definition.
.. c:function:: PyObject* PyModule_GetFilenameObject(PyObject *module) .. c:function:: PyObject* PyModule_GetFilenameObject(PyObject *module)
@ -106,7 +106,7 @@ Module Objects
Return the name of the file from which *module* was loaded using *module*'s Return the name of the file from which *module* was loaded using *module*'s
:attr:`__file__` attribute. If this is not defined, or if it is not a :attr:`__file__` attribute. If this is not defined, or if it is not a
unicode string, raise :exc:`SystemError` and return *NULL*; otherwise return unicode string, raise :exc:`SystemError` and return ``NULL``; otherwise return
a reference to a Unicode object. a reference to a Unicode object.
.. versionadded:: 3.2 .. versionadded:: 3.2
@ -178,17 +178,17 @@ or request "multi-phase initialization" by returning the definition struct itsel
.. c:member:: PyMethodDef* m_methods .. c:member:: PyMethodDef* m_methods
A pointer to a table of module-level functions, described by A pointer to a table of module-level functions, described by
:c:type:`PyMethodDef` values. Can be *NULL* if no functions are present. :c:type:`PyMethodDef` values. Can be ``NULL`` if no functions are present.
.. c:member:: PyModuleDef_Slot* m_slots .. c:member:: PyModuleDef_Slot* m_slots
An array of slot definitions for multi-phase initialization, terminated by An array of slot definitions for multi-phase initialization, terminated by
a ``{0, NULL}`` entry. a ``{0, NULL}`` entry.
When using single-phase initialization, *m_slots* must be *NULL*. When using single-phase initialization, *m_slots* must be ``NULL``.
.. versionchanged:: 3.5 .. versionchanged:: 3.5
Prior to version 3.5, this member was always set to *NULL*, Prior to version 3.5, this member was always set to ``NULL``,
and was defined as: and was defined as:
.. c:member:: inquiry m_reload .. c:member:: inquiry m_reload
@ -196,20 +196,20 @@ or request "multi-phase initialization" by returning the definition struct itsel
.. c:member:: traverseproc m_traverse .. c:member:: traverseproc m_traverse
A traversal function to call during GC traversal of the module object, or A traversal function to call during GC traversal of the module object, or
*NULL* if not needed. This function may be called before module state ``NULL`` if not needed. This function may be called before module state
is allocated (:c:func:`PyModule_GetState()` may return `NULL`), is allocated (:c:func:`PyModule_GetState()` may return `NULL`),
and before the :c:member:`Py_mod_exec` function is executed. and before the :c:member:`Py_mod_exec` function is executed.
.. c:member:: inquiry m_clear .. c:member:: inquiry m_clear
A clear function to call during GC clearing of the module object, or A clear function to call during GC clearing of the module object, or
*NULL* if not needed. This function may be called before module state ``NULL`` if not needed. This function may be called before module state
is allocated (:c:func:`PyModule_GetState()` may return `NULL`), is allocated (:c:func:`PyModule_GetState()` may return `NULL`),
and before the :c:member:`Py_mod_exec` function is executed. and before the :c:member:`Py_mod_exec` function is executed.
.. c:member:: freefunc m_free .. c:member:: freefunc m_free
A function to call during deallocation of the module object, or *NULL* if A function to call during deallocation of the module object, or ``NULL`` if
not needed. This function may be called before module state not needed. This function may be called before module state
is allocated (:c:func:`PyModule_GetState()` may return `NULL`), is allocated (:c:func:`PyModule_GetState()` may return `NULL`),
and before the :c:member:`Py_mod_exec` function is executed. and before the :c:member:`Py_mod_exec` function is executed.
@ -278,7 +278,7 @@ instance must be initialized with the following function:
Ensures a module definition is a properly initialized Python object that Ensures a module definition is a properly initialized Python object that
correctly reports its type and reference count. correctly reports its type and reference count.
Returns *def* cast to ``PyObject*``, or *NULL* if an error occurred. Returns *def* cast to ``PyObject*``, or ``NULL`` if an error occurred.
.. versionadded:: 3.5 .. versionadded:: 3.5
@ -311,7 +311,7 @@ The available slot types are:
The function receives a :py:class:`~importlib.machinery.ModuleSpec` The function receives a :py:class:`~importlib.machinery.ModuleSpec`
instance, as defined in :PEP:`451`, and the module definition. instance, as defined in :PEP:`451`, and the module definition.
It should return a new module object, or set an error It should return a new module object, or set an error
and return *NULL*. and return ``NULL``.
This function should be kept minimal. In particular, it should not This function should be kept minimal. In particular, it should not
call arbitrary Python code, as trying to import the same module again may call arbitrary Python code, as trying to import the same module again may
@ -330,7 +330,7 @@ The available slot types are:
:c:type:`PyModule_Type`. Any type can be used, as long as it supports :c:type:`PyModule_Type`. Any type can be used, as long as it supports
setting and getting import-related attributes. setting and getting import-related attributes.
However, only ``PyModule_Type`` instances may be returned if the However, only ``PyModule_Type`` instances may be returned if the
``PyModuleDef`` has non-*NULL* ``m_traverse``, ``m_clear``, ``PyModuleDef`` has non-``NULL`` ``m_traverse``, ``m_clear``,
``m_free``; non-zero ``m_size``; or slots other than ``Py_mod_create``. ``m_free``; non-zero ``m_size``; or slots other than ``Py_mod_create``.
.. c:var:: Py_mod_exec .. c:var:: Py_mod_exec
@ -394,7 +394,7 @@ objects dynamically. Note that both ``PyModule_FromDefAndSpec`` and
.. c:function:: int PyModule_AddFunctions(PyObject *module, PyMethodDef *functions) .. c:function:: int PyModule_AddFunctions(PyObject *module, PyMethodDef *functions)
Add the functions from the *NULL* terminated *functions* array to *module*. Add the functions from the ``NULL`` terminated *functions* array to *module*.
Refer to the :c:type:`PyMethodDef` documentation for details on individual Refer to the :c:type:`PyMethodDef` documentation for details on individual
entries (due to the lack of a shared module namespace, module level entries (due to the lack of a shared module namespace, module level
"functions" implemented in C typically receive the module as their first "functions" implemented in C typically receive the module as their first
@ -445,7 +445,7 @@ state:
Add a string constant to *module* as *name*. This convenience function can be Add a string constant to *module* as *name*. This convenience function can be
used from the module's initialization function. The string *value* must be used from the module's initialization function. The string *value* must be
*NULL*-terminated. Return ``-1`` on error, ``0`` on success. ``NULL``-terminated. Return ``-1`` on error, ``0`` on success.
.. c:function:: int PyModule_AddIntMacro(PyObject *module, macro) .. c:function:: int PyModule_AddIntMacro(PyObject *module, macro)
@ -476,7 +476,7 @@ since multiple such modules can be created from a single definition.
Returns the module object that was created from *def* for the current interpreter. Returns the module object that was created from *def* for the current interpreter.
This method requires that the module object has been attached to the interpreter state with This method requires that the module object has been attached to the interpreter state with
:c:func:`PyState_AddModule` beforehand. In case the corresponding module object is not :c:func:`PyState_AddModule` beforehand. In case the corresponding module object is not
found or has not been attached to the interpreter state yet, it returns *NULL*. found or has not been attached to the interpreter state yet, it returns ``NULL``.
.. c:function:: int PyState_AddModule(PyObject *module, PyModuleDef *def) .. c:function:: int PyState_AddModule(PyObject *module, PyModuleDef *def)

74
Doc/c-api/number.rst
View File

@ -17,25 +17,25 @@ Number Protocol
.. c:function:: PyObject* PyNumber_Add(PyObject *o1, PyObject *o2) .. c:function:: PyObject* PyNumber_Add(PyObject *o1, PyObject *o2)
Returns the result of adding *o1* and *o2*, or *NULL* on failure. This is the Returns the result of adding *o1* and *o2*, or ``NULL`` on failure. This is the
equivalent of the Python expression ``o1 + o2``. equivalent of the Python expression ``o1 + o2``.
.. c:function:: PyObject* PyNumber_Subtract(PyObject *o1, PyObject *o2) .. c:function:: PyObject* PyNumber_Subtract(PyObject *o1, PyObject *o2)
Returns the result of subtracting *o2* from *o1*, or *NULL* on failure. This is Returns the result of subtracting *o2* from *o1*, or ``NULL`` on failure. This is
the equivalent of the Python expression ``o1 - o2``. the equivalent of the Python expression ``o1 - o2``.
.. c:function:: PyObject* PyNumber_Multiply(PyObject *o1, PyObject *o2) .. c:function:: PyObject* PyNumber_Multiply(PyObject *o1, PyObject *o2)
Returns the result of multiplying *o1* and *o2*, or *NULL* on failure. This is Returns the result of multiplying *o1* and *o2*, or ``NULL`` on failure. This is
the equivalent of the Python expression ``o1 * o2``. the equivalent of the Python expression ``o1 * o2``.
.. c:function:: PyObject* PyNumber_MatrixMultiply(PyObject *o1, PyObject *o2) .. c:function:: PyObject* PyNumber_MatrixMultiply(PyObject *o1, PyObject *o2)
Returns the result of matrix multiplication on *o1* and *o2*, or *NULL* on Returns the result of matrix multiplication on *o1* and *o2*, or ``NULL`` on
failure. This is the equivalent of the Python expression ``o1 @ o2``. failure. This is the equivalent of the Python expression ``o1 @ o2``.
.. versionadded:: 3.5 .. versionadded:: 3.5
@ -43,14 +43,14 @@ Number Protocol
.. c:function:: PyObject* PyNumber_FloorDivide(PyObject *o1, PyObject *o2) .. c:function:: PyObject* PyNumber_FloorDivide(PyObject *o1, PyObject *o2)
Return the floor of *o1* divided by *o2*, or *NULL* on failure. This is Return the floor of *o1* divided by *o2*, or ``NULL`` on failure. This is
equivalent to the "classic" division of integers. equivalent to the "classic" division of integers.
.. c:function:: PyObject* PyNumber_TrueDivide(PyObject *o1, PyObject *o2) .. c:function:: PyObject* PyNumber_TrueDivide(PyObject *o1, PyObject *o2)
Return a reasonable approximation for the mathematical value of *o1* divided by Return a reasonable approximation for the mathematical value of *o1* divided by
*o2*, or *NULL* on failure. The return value is "approximate" because binary *o2*, or ``NULL`` on failure. The return value is "approximate" because binary
floating point numbers are approximate; it is not possible to represent all real floating point numbers are approximate; it is not possible to represent all real
numbers in base two. This function can return a floating point value when numbers in base two. This function can return a floating point value when
passed two integers. passed two integers.
@ -58,7 +58,7 @@ Number Protocol
.. c:function:: PyObject* PyNumber_Remainder(PyObject *o1, PyObject *o2) .. c:function:: PyObject* PyNumber_Remainder(PyObject *o1, PyObject *o2)
Returns the remainder of dividing *o1* by *o2*, or *NULL* on failure. This is Returns the remainder of dividing *o1* by *o2*, or ``NULL`` on failure. This is
the equivalent of the Python expression ``o1 % o2``. the equivalent of the Python expression ``o1 % o2``.
@ -66,7 +66,7 @@ Number Protocol
.. index:: builtin: divmod .. index:: builtin: divmod
See the built-in function :func:`divmod`. Returns *NULL* on failure. This is See the built-in function :func:`divmod`. Returns ``NULL`` on failure. This is
the equivalent of the Python expression ``divmod(o1, o2)``. the equivalent of the Python expression ``divmod(o1, o2)``.
@ -74,21 +74,21 @@ Number Protocol
.. index:: builtin: pow .. index:: builtin: pow
See the built-in function :func:`pow`. Returns *NULL* on failure. This is the See the built-in function :func:`pow`. Returns ``NULL`` on failure. This is the
equivalent of the Python expression ``pow(o1, o2, o3)``, where *o3* is optional. equivalent of the Python expression ``pow(o1, o2, o3)``, where *o3* is optional.
If *o3* is to be ignored, pass :c:data:`Py_None` in its place (passing *NULL* for If *o3* is to be ignored, pass :c:data:`Py_None` in its place (passing ``NULL`` for
*o3* would cause an illegal memory access). *o3* would cause an illegal memory access).
.. c:function:: PyObject* PyNumber_Negative(PyObject *o) .. c:function:: PyObject* PyNumber_Negative(PyObject *o)
Returns the negation of *o* on success, or *NULL* on failure. This is the Returns the negation of *o* on success, or ``NULL`` on failure. This is the
equivalent of the Python expression ``-o``. equivalent of the Python expression ``-o``.
.. c:function:: PyObject* PyNumber_Positive(PyObject *o) .. c:function:: PyObject* PyNumber_Positive(PyObject *o)
Returns *o* on success, or *NULL* on failure. This is the equivalent of the Returns *o* on success, or ``NULL`` on failure. This is the equivalent of the
Python expression ``+o``. Python expression ``+o``.
@ -96,70 +96,70 @@ Number Protocol
.. index:: builtin: abs .. index:: builtin: abs
Returns the absolute value of *o*, or *NULL* on failure. This is the equivalent Returns the absolute value of *o*, or ``NULL`` on failure. This is the equivalent
of the Python expression ``abs(o)``. of the Python expression ``abs(o)``.
.. c:function:: PyObject* PyNumber_Invert(PyObject *o) .. c:function:: PyObject* PyNumber_Invert(PyObject *o)
Returns the bitwise negation of *o* on success, or *NULL* on failure. This is Returns the bitwise negation of *o* on success, or ``NULL`` on failure. This is
the equivalent of the Python expression ``~o``. the equivalent of the Python expression ``~o``.
.. c:function:: PyObject* PyNumber_Lshift(PyObject *o1, PyObject *o2) .. c:function:: PyObject* PyNumber_Lshift(PyObject *o1, PyObject *o2)
Returns the result of left shifting *o1* by *o2* on success, or *NULL* on Returns the result of left shifting *o1* by *o2* on success, or ``NULL`` on
failure. This is the equivalent of the Python expression ``o1 << o2``. failure. This is the equivalent of the Python expression ``o1 << o2``.
.. c:function:: PyObject* PyNumber_Rshift(PyObject *o1, PyObject *o2) .. c:function:: PyObject* PyNumber_Rshift(PyObject *o1, PyObject *o2)
Returns the result of right shifting *o1* by *o2* on success, or *NULL* on Returns the result of right shifting *o1* by *o2* on success, or ``NULL`` on
failure. This is the equivalent of the Python expression ``o1 >> o2``. failure. This is the equivalent of the Python expression ``o1 >> o2``.
.. c:function:: PyObject* PyNumber_And(PyObject *o1, PyObject *o2) .. c:function:: PyObject* PyNumber_And(PyObject *o1, PyObject *o2)
Returns the "bitwise and" of *o1* and *o2* on success and *NULL* on failure. Returns the "bitwise and" of *o1* and *o2* on success and ``NULL`` on failure.
This is the equivalent of the Python expression ``o1 & o2``. This is the equivalent of the Python expression ``o1 & o2``.
.. c:function:: PyObject* PyNumber_Xor(PyObject *o1, PyObject *o2) .. c:function:: PyObject* PyNumber_Xor(PyObject *o1, PyObject *o2)
Returns the "bitwise exclusive or" of *o1* by *o2* on success, or *NULL* on Returns the "bitwise exclusive or" of *o1* by *o2* on success, or ``NULL`` on
failure. This is the equivalent of the Python expression ``o1 ^ o2``. failure. This is the equivalent of the Python expression ``o1 ^ o2``.
.. c:function:: PyObject* PyNumber_Or(PyObject *o1, PyObject *o2) .. c:function:: PyObject* PyNumber_Or(PyObject *o1, PyObject *o2)
Returns the "bitwise or" of *o1* and *o2* on success, or *NULL* on failure. Returns the "bitwise or" of *o1* and *o2* on success, or ``NULL`` on failure.
This is the equivalent of the Python expression ``o1 | o2``. This is the equivalent of the Python expression ``o1 | o2``.
.. c:function:: PyObject* PyNumber_InPlaceAdd(PyObject *o1, PyObject *o2) .. c:function:: PyObject* PyNumber_InPlaceAdd(PyObject *o1, PyObject *o2)
Returns the result of adding *o1* and *o2*, or *NULL* on failure. The operation Returns the result of adding *o1* and *o2*, or ``NULL`` on failure. The operation
is done *in-place* when *o1* supports it. This is the equivalent of the Python is done *in-place* when *o1* supports it. This is the equivalent of the Python
statement ``o1 += o2``. statement ``o1 += o2``.
.. c:function:: PyObject* PyNumber_InPlaceSubtract(PyObject *o1, PyObject *o2) .. c:function:: PyObject* PyNumber_InPlaceSubtract(PyObject *o1, PyObject *o2)
Returns the result of subtracting *o2* from *o1*, or *NULL* on failure. The Returns the result of subtracting *o2* from *o1*, or ``NULL`` on failure. The
operation is done *in-place* when *o1* supports it. This is the equivalent of operation is done *in-place* when *o1* supports it. This is the equivalent of
the Python statement ``o1 -= o2``. the Python statement ``o1 -= o2``.
.. c:function:: PyObject* PyNumber_InPlaceMultiply(PyObject *o1, PyObject *o2) .. c:function:: PyObject* PyNumber_InPlaceMultiply(PyObject *o1, PyObject *o2)
Returns the result of multiplying *o1* and *o2*, or *NULL* on failure. The Returns the result of multiplying *o1* and *o2*, or ``NULL`` on failure. The
operation is done *in-place* when *o1* supports it. This is the equivalent of operation is done *in-place* when *o1* supports it. This is the equivalent of
the Python statement ``o1 *= o2``. the Python statement ``o1 *= o2``.
.. c:function:: PyObject* PyNumber_InPlaceMatrixMultiply(PyObject *o1, PyObject *o2) .. c:function:: PyObject* PyNumber_InPlaceMatrixMultiply(PyObject *o1, PyObject *o2)
Returns the result of matrix multiplication on *o1* and *o2*, or *NULL* on Returns the result of matrix multiplication on *o1* and *o2*, or ``NULL`` on
failure. The operation is done *in-place* when *o1* supports it. This is failure. The operation is done *in-place* when *o1* supports it. This is
the equivalent of the Python statement ``o1 @= o2``. the equivalent of the Python statement ``o1 @= o2``.
@ -168,7 +168,7 @@ Number Protocol
.. c:function:: PyObject* PyNumber_InPlaceFloorDivide(PyObject *o1, PyObject *o2) .. c:function:: PyObject* PyNumber_InPlaceFloorDivide(PyObject *o1, PyObject *o2)
Returns the mathematical floor of dividing *o1* by *o2*, or *NULL* on failure. Returns the mathematical floor of dividing *o1* by *o2*, or ``NULL`` on failure.
The operation is done *in-place* when *o1* supports it. This is the equivalent The operation is done *in-place* when *o1* supports it. This is the equivalent
of the Python statement ``o1 //= o2``. of the Python statement ``o1 //= o2``.
@ -176,7 +176,7 @@ Number Protocol
.. c:function:: PyObject* PyNumber_InPlaceTrueDivide(PyObject *o1, PyObject *o2) .. c:function:: PyObject* PyNumber_InPlaceTrueDivide(PyObject *o1, PyObject *o2)
Return a reasonable approximation for the mathematical value of *o1* divided by Return a reasonable approximation for the mathematical value of *o1* divided by
*o2*, or *NULL* on failure. The return value is "approximate" because binary *o2*, or ``NULL`` on failure. The return value is "approximate" because binary
floating point numbers are approximate; it is not possible to represent all real floating point numbers are approximate; it is not possible to represent all real
numbers in base two. This function can return a floating point value when numbers in base two. This function can return a floating point value when
passed two integers. The operation is done *in-place* when *o1* supports it. passed two integers. The operation is done *in-place* when *o1* supports it.
@ -184,7 +184,7 @@ Number Protocol
.. c:function:: PyObject* PyNumber_InPlaceRemainder(PyObject *o1, PyObject *o2) .. c:function:: PyObject* PyNumber_InPlaceRemainder(PyObject *o1, PyObject *o2)
Returns the remainder of dividing *o1* by *o2*, or *NULL* on failure. The Returns the remainder of dividing *o1* by *o2*, or ``NULL`` on failure. The
operation is done *in-place* when *o1* supports it. This is the equivalent of operation is done *in-place* when *o1* supports it. This is the equivalent of
the Python statement ``o1 %= o2``. the Python statement ``o1 %= o2``.
@ -193,44 +193,44 @@ Number Protocol
.. index:: builtin: pow .. index:: builtin: pow
See the built-in function :func:`pow`. Returns *NULL* on failure. The operation See the built-in function :func:`pow`. Returns ``NULL`` on failure. The operation
is done *in-place* when *o1* supports it. This is the equivalent of the Python is done *in-place* when *o1* supports it. This is the equivalent of the Python
statement ``o1 **= o2`` when o3 is :c:data:`Py_None`, or an in-place variant of statement ``o1 **= o2`` when o3 is :c:data:`Py_None`, or an in-place variant of
``pow(o1, o2, o3)`` otherwise. If *o3* is to be ignored, pass :c:data:`Py_None` ``pow(o1, o2, o3)`` otherwise. If *o3* is to be ignored, pass :c:data:`Py_None`
in its place (passing *NULL* for *o3* would cause an illegal memory access). in its place (passing ``NULL`` for *o3* would cause an illegal memory access).
.. c:function:: PyObject* PyNumber_InPlaceLshift(PyObject *o1, PyObject *o2) .. c:function:: PyObject* PyNumber_InPlaceLshift(PyObject *o1, PyObject *o2)
Returns the result of left shifting *o1* by *o2* on success, or *NULL* on Returns the result of left shifting *o1* by *o2* on success, or ``NULL`` on
failure. The operation is done *in-place* when *o1* supports it. This is the failure. The operation is done *in-place* when *o1* supports it. This is the
equivalent of the Python statement ``o1 <<= o2``. equivalent of the Python statement ``o1 <<= o2``.
.. c:function:: PyObject* PyNumber_InPlaceRshift(PyObject *o1, PyObject *o2) .. c:function:: PyObject* PyNumber_InPlaceRshift(PyObject *o1, PyObject *o2)
Returns the result of right shifting *o1* by *o2* on success, or *NULL* on Returns the result of right shifting *o1* by *o2* on success, or ``NULL`` on
failure. The operation is done *in-place* when *o1* supports it. This is the failure. The operation is done *in-place* when *o1* supports it. This is the
equivalent of the Python statement ``o1 >>= o2``. equivalent of the Python statement ``o1 >>= o2``.
.. c:function:: PyObject* PyNumber_InPlaceAnd(PyObject *o1, PyObject *o2) .. c:function:: PyObject* PyNumber_InPlaceAnd(PyObject *o1, PyObject *o2)
Returns the "bitwise and" of *o1* and *o2* on success and *NULL* on failure. The Returns the "bitwise and" of *o1* and *o2* on success and ``NULL`` on failure. The
operation is done *in-place* when *o1* supports it. This is the equivalent of operation is done *in-place* when *o1* supports it. This is the equivalent of
the Python statement ``o1 &= o2``. the Python statement ``o1 &= o2``.
.. c:function:: PyObject* PyNumber_InPlaceXor(PyObject *o1, PyObject *o2) .. c:function:: PyObject* PyNumber_InPlaceXor(PyObject *o1, PyObject *o2)
Returns the "bitwise exclusive or" of *o1* by *o2* on success, or *NULL* on Returns the "bitwise exclusive or" of *o1* by *o2* on success, or ``NULL`` on
failure. The operation is done *in-place* when *o1* supports it. This is the failure. The operation is done *in-place* when *o1* supports it. This is the
equivalent of the Python statement ``o1 ^= o2``. equivalent of the Python statement ``o1 ^= o2``.
.. c:function:: PyObject* PyNumber_InPlaceOr(PyObject *o1, PyObject *o2) .. c:function:: PyObject* PyNumber_InPlaceOr(PyObject *o1, PyObject *o2)
Returns the "bitwise or" of *o1* and *o2* on success, or *NULL* on failure. The Returns the "bitwise or" of *o1* and *o2* on success, or ``NULL`` on failure. The
operation is done *in-place* when *o1* supports it. This is the equivalent of operation is done *in-place* when *o1* supports it. This is the equivalent of
the Python statement ``o1 |= o2``. the Python statement ``o1 |= o2``.
@ -239,7 +239,7 @@ Number Protocol
.. index:: builtin: int .. index:: builtin: int
Returns the *o* converted to an integer object on success, or *NULL* on Returns the *o* converted to an integer object on success, or ``NULL`` on
failure. This is the equivalent of the Python expression ``int(o)``. failure. This is the equivalent of the Python expression ``int(o)``.
@ -247,13 +247,13 @@ Number Protocol
.. index:: builtin: float .. index:: builtin: float
Returns the *o* converted to a float object on success, or *NULL* on failure. Returns the *o* converted to a float object on success, or ``NULL`` on failure.
This is the equivalent of the Python expression ``float(o)``. This is the equivalent of the Python expression ``float(o)``.
.. c:function:: PyObject* PyNumber_Index(PyObject *o) .. c:function:: PyObject* PyNumber_Index(PyObject *o)
Returns the *o* converted to a Python int on success or *NULL* with a Returns the *o* converted to a Python int on success or ``NULL`` with a
:exc:`TypeError` exception raised on failure. :exc:`TypeError` exception raised on failure.
@ -274,7 +274,7 @@ Number Protocol
If *o* can be converted to a Python int but the attempt to If *o* can be converted to a Python int but the attempt to
convert to a Py_ssize_t value would raise an :exc:`OverflowError`, then the convert to a Py_ssize_t value would raise an :exc:`OverflowError`, then the
*exc* argument is the type of exception that will be raised (usually *exc* argument is the type of exception that will be raised (usually
:exc:`IndexError` or :exc:`OverflowError`). If *exc* is *NULL*, then the :exc:`IndexError` or :exc:`OverflowError`). If *exc* is ``NULL``, then the
exception is cleared and the value is clipped to *PY_SSIZE_T_MIN* for a negative exception is cleared and the value is clipped to *PY_SSIZE_T_MIN* for a negative
integer or *PY_SSIZE_T_MAX* for a positive integer. integer or *PY_SSIZE_T_MAX* for a positive integer.

72
Doc/c-api/object.rst
View File

@ -53,14 +53,14 @@ Object Protocol
.. c:function:: PyObject* PyObject_GetAttr(PyObject *o, PyObject *attr_name) .. c:function:: PyObject* PyObject_GetAttr(PyObject *o, PyObject *attr_name)
Retrieve an attribute named *attr_name* from object *o*. Returns the attribute Retrieve an attribute named *attr_name* from object *o*. Returns the attribute
value on success, or *NULL* on failure. This is the equivalent of the Python value on success, or ``NULL`` on failure. This is the equivalent of the Python
expression ``o.attr_name``. expression ``o.attr_name``.
.. c:function:: PyObject* PyObject_GetAttrString(PyObject *o, const char *attr_name) .. c:function:: PyObject* PyObject_GetAttrString(PyObject *o, const char *attr_name)
Retrieve an attribute named *attr_name* from object *o*. Returns the attribute Retrieve an attribute named *attr_name* from object *o*. Returns the attribute
value on success, or *NULL* on failure. This is the equivalent of the Python value on success, or ``NULL`` on failure. This is the equivalent of the Python
expression ``o.attr_name``. expression ``o.attr_name``.
@ -81,7 +81,7 @@ Object Protocol
return ``0`` on success. This is the equivalent of the Python statement return ``0`` on success. This is the equivalent of the Python statement
``o.attr_name = v``. ``o.attr_name = v``.
If *v* is *NULL*, the attribute is deleted, however this feature is If *v* is ``NULL``, the attribute is deleted, however this feature is
deprecated in favour of using :c:func:`PyObject_DelAttr`. deprecated in favour of using :c:func:`PyObject_DelAttr`.
@ -92,7 +92,7 @@ Object Protocol
return ``0`` on success. This is the equivalent of the Python statement return ``0`` on success. This is the equivalent of the Python statement
``o.attr_name = v``. ``o.attr_name = v``.
If *v* is *NULL*, the attribute is deleted, however this feature is If *v* is ``NULL``, the attribute is deleted, however this feature is
deprecated in favour of using :c:func:`PyObject_DelAttrString`. deprecated in favour of using :c:func:`PyObject_DelAttrString`.
@ -143,7 +143,7 @@ Object Protocol
:const:`Py_NE`, :const:`Py_GT`, or :const:`Py_GE`, corresponding to ``<``, :const:`Py_NE`, :const:`Py_GT`, or :const:`Py_GE`, corresponding to ``<``,
``<=``, ``==``, ``!=``, ``>``, or ``>=`` respectively. This is the equivalent of ``<=``, ``==``, ``!=``, ``>``, or ``>=`` respectively. This is the equivalent of
the Python expression ``o1 op o2``, where ``op`` is the operator corresponding the Python expression ``o1 op o2``, where ``op`` is the operator corresponding
to *opid*. Returns the value of the comparison on success, or *NULL* on failure. to *opid*. Returns the value of the comparison on success, or ``NULL`` on failure.
.. c:function:: int PyObject_RichCompareBool(PyObject *o1, PyObject *o2, int opid) .. c:function:: int PyObject_RichCompareBool(PyObject *o1, PyObject *o2, int opid)
@ -165,7 +165,7 @@ Object Protocol
.. index:: builtin: repr .. index:: builtin: repr
Compute a string representation of object *o*. Returns the string Compute a string representation of object *o*. Returns the string
representation on success, *NULL* on failure. This is the equivalent of the representation on success, ``NULL`` on failure. This is the equivalent of the
Python expression ``repr(o)``. Called by the :func:`repr` built-in function. Python expression ``repr(o)``. Called by the :func:`repr` built-in function.
.. versionchanged:: 3.4 .. versionchanged:: 3.4
@ -188,7 +188,7 @@ Object Protocol
.. c:function:: PyObject* PyObject_Str(PyObject *o) .. c:function:: PyObject* PyObject_Str(PyObject *o)
Compute a string representation of object *o*. Returns the string Compute a string representation of object *o*. Returns the string
representation on success, *NULL* on failure. This is the equivalent of the representation on success, ``NULL`` on failure. This is the equivalent of the
Python expression ``str(o)``. Called by the :func:`str` built-in function Python expression ``str(o)``. Called by the :func:`str` built-in function
and, therefore, by the :func:`print` function. and, therefore, by the :func:`print` function.
@ -200,7 +200,7 @@ Object Protocol
.. index:: builtin: bytes .. index:: builtin: bytes
Compute a bytes representation of object *o*. *NULL* is returned on Compute a bytes representation of object *o*. ``NULL`` is returned on
failure and a bytes object on success. This is equivalent to the Python failure and a bytes object on success. This is equivalent to the Python
expression ``bytes(o)``, when *o* is not an integer. Unlike ``bytes(o)``, expression ``bytes(o)``, when *o* is not an integer. Unlike ``bytes(o)``,
a TypeError is raised when *o* is an integer instead of a zero-initialized a TypeError is raised when *o* is an integer instead of a zero-initialized
@ -259,7 +259,7 @@ Object Protocol
most efficient way to call a callable Python object without any argument. most efficient way to call a callable Python object without any argument.
Return the result of the call on success, or raise an exception and return Return the result of the call on success, or raise an exception and return
*NULL* on failure. ``NULL`` on failure.
.. versionadded:: 3.9 .. versionadded:: 3.9
@ -270,7 +270,7 @@ Object Protocol
*arg* and no keyword arguments. *arg* and no keyword arguments.
Return the result of the call on success, or raise an exception and return Return the result of the call on success, or raise an exception and return
*NULL* on failure. ``NULL`` on failure.
.. versionadded:: 3.9 .. versionadded:: 3.9
@ -280,11 +280,11 @@ Object Protocol
Call a callable Python object *callable*, with arguments given by the Call a callable Python object *callable*, with arguments given by the
tuple *args*, and named arguments given by the dictionary *kwargs*. tuple *args*, and named arguments given by the dictionary *kwargs*.
*args* must not be *NULL*, use an empty tuple if no arguments are needed. *args* must not be ``NULL``, use an empty tuple if no arguments are needed.
If no named arguments are needed, *kwargs* can be *NULL*. If no named arguments are needed, *kwargs* can be ``NULL``.
Return the result of the call on success, or raise an exception and return Return the result of the call on success, or raise an exception and return
*NULL* on failure. ``NULL`` on failure.
This is the equivalent of the Python expression: This is the equivalent of the Python expression:
``callable(*args, **kwargs)``. ``callable(*args, **kwargs)``.
@ -293,10 +293,10 @@ Object Protocol
.. c:function:: PyObject* PyObject_CallObject(PyObject *callable, PyObject *args) .. c:function:: PyObject* PyObject_CallObject(PyObject *callable, PyObject *args)
Call a callable Python object *callable*, with arguments given by the Call a callable Python object *callable*, with arguments given by the
tuple *args*. If no arguments are needed, then *args* can be *NULL*. tuple *args*. If no arguments are needed, then *args* can be ``NULL``.
Return the result of the call on success, or raise an exception and return Return the result of the call on success, or raise an exception and return
*NULL* on failure. ``NULL`` on failure.
This is the equivalent of the Python expression: ``callable(*args)``. This is the equivalent of the Python expression: ``callable(*args)``.
@ -305,10 +305,10 @@ Object Protocol
Call a callable Python object *callable*, with a variable number of C arguments. Call a callable Python object *callable*, with a variable number of C arguments.
The C arguments are described using a :c:func:`Py_BuildValue` style format The C arguments are described using a :c:func:`Py_BuildValue` style format
string. The format can be *NULL*, indicating that no arguments are provided. string. The format can be ``NULL``, indicating that no arguments are provided.
Return the result of the call on success, or raise an exception and return Return the result of the call on success, or raise an exception and return
*NULL* on failure. ``NULL`` on failure.
This is the equivalent of the Python expression: ``callable(*args)``. This is the equivalent of the Python expression: ``callable(*args)``.
@ -325,10 +325,10 @@ Object Protocol
arguments. The C arguments are described by a :c:func:`Py_BuildValue` format arguments. The C arguments are described by a :c:func:`Py_BuildValue` format
string that should produce a tuple. string that should produce a tuple.
The format can be *NULL*, indicating that no arguments are provided. The format can be ``NULL``, indicating that no arguments are provided.
Return the result of the call on success, or raise an exception and return Return the result of the call on success, or raise an exception and return
*NULL* on failure. ``NULL`` on failure.
This is the equivalent of the Python expression: This is the equivalent of the Python expression:
``obj.name(arg1, arg2, ...)``. ``obj.name(arg1, arg2, ...)``.
@ -344,10 +344,10 @@ Object Protocol
Call a callable Python object *callable*, with a variable number of Call a callable Python object *callable*, with a variable number of
:c:type:`PyObject\*` arguments. The arguments are provided as a variable number :c:type:`PyObject\*` arguments. The arguments are provided as a variable number
of parameters followed by *NULL*. of parameters followed by ``NULL``.
Return the result of the call on success, or raise an exception and return Return the result of the call on success, or raise an exception and return
*NULL* on failure. ``NULL`` on failure.
This is the equivalent of the Python expression: This is the equivalent of the Python expression:
``callable(arg1, arg2, ...)``. ``callable(arg1, arg2, ...)``.
@ -358,10 +358,10 @@ Object Protocol
Calls a method of the Python object *obj*, where the name of the method is given as a Calls a method of the Python object *obj*, where the name of the method is given as a
Python string object in *name*. It is called with a variable number of Python string object in *name*. It is called with a variable number of
:c:type:`PyObject\*` arguments. The arguments are provided as a variable number :c:type:`PyObject\*` arguments. The arguments are provided as a variable number
of parameters followed by *NULL*. of parameters followed by ``NULL``.
Return the result of the call on success, or raise an exception and return Return the result of the call on success, or raise an exception and return
*NULL* on failure. ``NULL`` on failure.
.. c:function:: PyObject* _PyObject_CallMethodNoArgs(PyObject *obj, PyObject *name) .. c:function:: PyObject* _PyObject_CallMethodNoArgs(PyObject *obj, PyObject *name)
@ -370,7 +370,7 @@ Object Protocol
where the name of the method is given as a Python string object in *name*. where the name of the method is given as a Python string object in *name*.
Return the result of the call on success, or raise an exception and return Return the result of the call on success, or raise an exception and return
*NULL* on failure. ``NULL`` on failure.
.. versionadded:: 3.9 .. versionadded:: 3.9
@ -382,7 +382,7 @@ Object Protocol
*name*. *name*.
Return the result of the call on success, or raise an exception and return Return the result of the call on success, or raise an exception and return
*NULL* on failure. ``NULL`` on failure.
.. versionadded:: 3.9 .. versionadded:: 3.9
@ -408,7 +408,7 @@ Object Protocol
and all keys must be unique. and all keys must be unique.
Return the result of the call on success, or raise an exception and return Return the result of the call on success, or raise an exception and return
*NULL* on failure. ``NULL`` on failure.
This uses the vectorcall protocol if the callable supports it; This uses the vectorcall protocol if the callable supports it;
otherwise, the arguments are converted to use otherwise, the arguments are converted to use
@ -450,7 +450,7 @@ Object Protocol
.. c:function:: PyObject* _PyObject_FastCallDict(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwdict) .. c:function:: PyObject* _PyObject_FastCallDict(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwdict)
Same as :c:func:`_PyObject_Vectorcall` except that the keyword arguments Same as :c:func:`_PyObject_Vectorcall` except that the keyword arguments
are passed as a dictionary in *kwdict*. This may be *NULL* if there are passed as a dictionary in *kwdict*. This may be ``NULL`` if there
are no keyword arguments. are no keyword arguments.
For callables supporting :c:data:`vectorcall <PyTypeObject.tp_vectorcall_offset>`, For callables supporting :c:data:`vectorcall <PyTypeObject.tp_vectorcall_offset>`,
@ -483,7 +483,7 @@ Object Protocol
*args* vector as arguments. *args* vector as arguments.
Return the result of the call on success, or raise an exception and return Return the result of the call on success, or raise an exception and return
*NULL* on failure. ``NULL`` on failure.
.. versionadded:: 3.9 .. versionadded:: 3.9
@ -525,8 +525,8 @@ Object Protocol
.. index:: builtin: type .. index:: builtin: type
When *o* is non-*NULL*, returns a type object corresponding to the object type When *o* is non-``NULL``, returns a type object corresponding to the object type
of object *o*. On failure, raises :exc:`SystemError` and returns *NULL*. This of object *o*. On failure, raises :exc:`SystemError` and returns ``NULL``. This
is equivalent to the Python expression ``type(o)``. This function increments the is equivalent to the Python expression ``type(o)``. This function increments the
reference count of the return value. There's really no reason to use this reference count of the return value. There's really no reason to use this
function instead of the common expression ``o->ob_type``, which returns a function instead of the common expression ``o->ob_type``, which returns a
@ -537,7 +537,7 @@ Object Protocol
.. c:function:: int PyObject_TypeCheck(PyObject *o, PyTypeObject *type) .. c:function:: int PyObject_TypeCheck(PyObject *o, PyTypeObject *type)
Return true if the object *o* is of type *type* or a subtype of *type*. Both Return true if the object *o* is of type *type* or a subtype of *type*. Both
parameters must be non-*NULL*. parameters must be non-``NULL``.
.. c:function:: Py_ssize_t PyObject_Size(PyObject *o) .. c:function:: Py_ssize_t PyObject_Size(PyObject *o)
@ -562,7 +562,7 @@ Object Protocol
.. c:function:: PyObject* PyObject_GetItem(PyObject *o, PyObject *key) .. c:function:: PyObject* PyObject_GetItem(PyObject *o, PyObject *key)
Return element of *o* corresponding to the object *key* or *NULL* on failure. Return element of *o* corresponding to the object *key* or ``NULL`` on failure.
This is the equivalent of the Python expression ``o[key]``. This is the equivalent of the Python expression ``o[key]``.
@ -582,15 +582,15 @@ Object Protocol
.. c:function:: PyObject* PyObject_Dir(PyObject *o) .. c:function:: PyObject* PyObject_Dir(PyObject *o)
This is equivalent to the Python expression ``dir(o)``, returning a (possibly This is equivalent to the Python expression ``dir(o)``, returning a (possibly
empty) list of strings appropriate for the object argument, or *NULL* if there empty) list of strings appropriate for the object argument, or ``NULL`` if there
was an error. If the argument is *NULL*, this is like the Python ``dir()``, was an error. If the argument is ``NULL``, this is like the Python ``dir()``,
returning the names of the current locals; in this case, if no execution frame returning the names of the current locals; in this case, if no execution frame
is active then *NULL* is returned but :c:func:`PyErr_Occurred` will return false. is active then ``NULL`` is returned but :c:func:`PyErr_Occurred` will return false.
.. c:function:: PyObject* PyObject_GetIter(PyObject *o) .. c:function:: PyObject* PyObject_GetIter(PyObject *o)
This is equivalent to the Python expression ``iter(o)``. It returns a new This is equivalent to the Python expression ``iter(o)``. It returns a new
iterator for the object argument, or the object itself if the object is already iterator for the object argument, or the object itself if the object is already
an iterator. Raises :exc:`TypeError` and returns *NULL* if the object cannot be an iterator. Raises :exc:`TypeError` and returns ``NULL`` if the object cannot be
iterated. iterated.

20
Doc/c-api/refcounting.rst
View File

@ -13,22 +13,22 @@ objects.
.. c:function:: void Py_INCREF(PyObject *o) .. c:function:: void Py_INCREF(PyObject *o)
Increment the reference count for object *o*. The object must not be *NULL*; if Increment the reference count for object *o*. The object must not be ``NULL``; if
you aren't sure that it isn't *NULL*, use :c:func:`Py_XINCREF`. you aren't sure that it isn't ``NULL``, use :c:func:`Py_XINCREF`.
.. c:function:: void Py_XINCREF(PyObject *o) .. c:function:: void Py_XINCREF(PyObject *o)
Increment the reference count for object *o*. The object may be *NULL*, in Increment the reference count for object *o*. The object may be ``NULL``, in
which case the macro has no effect. which case the macro has no effect.
.. c:function:: void Py_DECREF(PyObject *o) .. c:function:: void Py_DECREF(PyObject *o)
Decrement the reference count for object *o*. The object must not be *NULL*; if Decrement the reference count for object *o*. The object must not be ``NULL``; if
you aren't sure that it isn't *NULL*, use :c:func:`Py_XDECREF`. If the reference you aren't sure that it isn't ``NULL``, use :c:func:`Py_XDECREF`. If the reference
count reaches zero, the object's type's deallocation function (which must not be count reaches zero, the object's type's deallocation function (which must not be
*NULL*) is invoked. ``NULL``) is invoked.
.. warning:: .. warning::
@ -44,18 +44,18 @@ objects.
.. c:function:: void Py_XDECREF(PyObject *o) .. c:function:: void Py_XDECREF(PyObject *o)
Decrement the reference count for object *o*. The object may be *NULL*, in Decrement the reference count for object *o*. The object may be ``NULL``, in
which case the macro has no effect; otherwise the effect is the same as for which case the macro has no effect; otherwise the effect is the same as for
:c:func:`Py_DECREF`, and the same warning applies. :c:func:`Py_DECREF`, and the same warning applies.
.. c:function:: void Py_CLEAR(PyObject *o) .. c:function:: void Py_CLEAR(PyObject *o)
Decrement the reference count for object *o*. The object may be *NULL*, in Decrement the reference count for object *o*. The object may be ``NULL``, in
which case the macro has no effect; otherwise the effect is the same as for which case the macro has no effect; otherwise the effect is the same as for
:c:func:`Py_DECREF`, except that the argument is also set to *NULL*. The warning :c:func:`Py_DECREF`, except that the argument is also set to ``NULL``. The warning
for :c:func:`Py_DECREF` does not apply with respect to the object passed because for :c:func:`Py_DECREF` does not apply with respect to the object passed because
the macro carefully uses a temporary variable and sets the argument to *NULL* the macro carefully uses a temporary variable and sets the argument to ``NULL``
before decrementing its reference count. before decrementing its reference count.
It is a good idea to use this macro whenever decrementing the reference It is a good idea to use this macro whenever decrementing the reference

6
Doc/c-api/reflection.rst
View File

@ -14,18 +14,18 @@ Reflection
.. c:function:: PyObject* PyEval_GetLocals() .. c:function:: PyObject* PyEval_GetLocals()
Return a dictionary of the local variables in the current execution frame, Return a dictionary of the local variables in the current execution frame,
or *NULL* if no frame is currently executing. or ``NULL`` if no frame is currently executing.
.. c:function:: PyObject* PyEval_GetGlobals() .. c:function:: PyObject* PyEval_GetGlobals()
Return a dictionary of the global variables in the current execution frame, Return a dictionary of the global variables in the current execution frame,
or *NULL* if no frame is currently executing. or ``NULL`` if no frame is currently executing.
.. c:function:: PyFrameObject* PyEval_GetFrame() .. c:function:: PyFrameObject* PyEval_GetFrame()
Return the current thread state's frame, which is *NULL* if no frame is Return the current thread state's frame, which is ``NULL`` if no frame is
currently executing. currently executing.

28
Doc/c-api/sequence.rst
View File

@ -26,39 +26,39 @@ Sequence Protocol
.. c:function:: PyObject* PySequence_Concat(PyObject *o1, PyObject *o2) .. c:function:: PyObject* PySequence_Concat(PyObject *o1, PyObject *o2)
Return the concatenation of *o1* and *o2* on success, and *NULL* on failure. Return the concatenation of *o1* and *o2* on success, and ``NULL`` on failure.
This is the equivalent of the Python expression ``o1 + o2``. This is the equivalent of the Python expression ``o1 + o2``.
.. c:function:: PyObject* PySequence_Repeat(PyObject *o, Py_ssize_t count) .. c:function:: PyObject* PySequence_Repeat(PyObject *o, Py_ssize_t count)
Return the result of repeating sequence object *o* *count* times, or *NULL* on Return the result of repeating sequence object *o* *count* times, or ``NULL`` on
failure. This is the equivalent of the Python expression ``o * count``. failure. This is the equivalent of the Python expression ``o * count``.
.. c:function:: PyObject* PySequence_InPlaceConcat(PyObject *o1, PyObject *o2) .. c:function:: PyObject* PySequence_InPlaceConcat(PyObject *o1, PyObject *o2)
Return the concatenation of *o1* and *o2* on success, and *NULL* on failure. Return the concatenation of *o1* and *o2* on success, and ``NULL`` on failure.
The operation is done *in-place* when *o1* supports it. This is the equivalent The operation is done *in-place* when *o1* supports it. This is the equivalent
of the Python expression ``o1 += o2``. of the Python expression ``o1 += o2``.
.. c:function:: PyObject* PySequence_InPlaceRepeat(PyObject *o, Py_ssize_t count) .. c:function:: PyObject* PySequence_InPlaceRepeat(PyObject *o, Py_ssize_t count)
Return the result of repeating sequence object *o* *count* times, or *NULL* on Return the result of repeating sequence object *o* *count* times, or ``NULL`` on
failure. The operation is done *in-place* when *o* supports it. This is the failure. The operation is done *in-place* when *o* supports it. This is the
equivalent of the Python expression ``o *= count``. equivalent of the Python expression ``o *= count``.
.. c:function:: PyObject* PySequence_GetItem(PyObject *o, Py_ssize_t i) .. c:function:: PyObject* PySequence_GetItem(PyObject *o, Py_ssize_t i)
Return the *i*\ th element of *o*, or *NULL* on failure. This is the equivalent of Return the *i*\ th element of *o*, or ``NULL`` on failure. This is the equivalent of
the Python expression ``o[i]``. the Python expression ``o[i]``.
.. c:function:: PyObject* PySequence_GetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2) .. c:function:: PyObject* PySequence_GetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2)
Return the slice of sequence object *o* between *i1* and *i2*, or *NULL* on Return the slice of sequence object *o* between *i1* and *i2*, or ``NULL`` on
failure. This is the equivalent of the Python expression ``o[i1:i2]``. failure. This is the equivalent of the Python expression ``o[i1:i2]``.
@ -69,7 +69,7 @@ Sequence Protocol
is the equivalent of the Python statement ``o[i] = v``. This function *does is the equivalent of the Python statement ``o[i] = v``. This function *does
not* steal a reference to *v*. not* steal a reference to *v*.
If *v* is *NULL*, the element is deleted, however this feature is If *v* is ``NULL``, the element is deleted, however this feature is
deprecated in favour of using :c:func:`PySequence_DelItem`. deprecated in favour of using :c:func:`PySequence_DelItem`.
@ -114,7 +114,7 @@ Sequence Protocol
.. c:function:: PyObject* PySequence_List(PyObject *o) .. c:function:: PyObject* PySequence_List(PyObject *o)
Return a list object with the same contents as the sequence or iterable *o*, Return a list object with the same contents as the sequence or iterable *o*,
or *NULL* on failure. The returned list is guaranteed to be new. This is or ``NULL`` on failure. The returned list is guaranteed to be new. This is
equivalent to the Python expression ``list(o)``. equivalent to the Python expression ``list(o)``.
@ -123,7 +123,7 @@ Sequence Protocol
.. index:: builtin: tuple .. index:: builtin: tuple
Return a tuple object with the same contents as the sequence or iterable *o*, Return a tuple object with the same contents as the sequence or iterable *o*,
or *NULL* on failure. If *o* is a tuple, a new reference will be returned, or ``NULL`` on failure. If *o* is a tuple, a new reference will be returned,
otherwise a tuple will be constructed with the appropriate contents. This is otherwise a tuple will be constructed with the appropriate contents. This is
equivalent to the Python expression ``tuple(o)``. equivalent to the Python expression ``tuple(o)``.
@ -133,7 +133,7 @@ Sequence Protocol
Return the sequence or iterable *o* as an object usable by the other Return the sequence or iterable *o* as an object usable by the other
``PySequence_Fast*`` family of functions. If the object is not a sequence or ``PySequence_Fast*`` family of functions. If the object is not a sequence or
iterable, raises :exc:`TypeError` with *m* as the message text. Returns iterable, raises :exc:`TypeError` with *m* as the message text. Returns
*NULL* on failure. ``NULL`` on failure.
The ``PySequence_Fast*`` functions are thus named because they assume The ``PySequence_Fast*`` functions are thus named because they assume
*o* is a :c:type:`PyTupleObject` or a :c:type:`PyListObject` and access *o* is a :c:type:`PyTupleObject` or a :c:type:`PyListObject` and access
@ -146,7 +146,7 @@ Sequence Protocol
.. c:function:: Py_ssize_t PySequence_Fast_GET_SIZE(PyObject *o) .. c:function:: Py_ssize_t PySequence_Fast_GET_SIZE(PyObject *o)
Returns the length of *o*, assuming that *o* was returned by Returns the length of *o*, assuming that *o* was returned by
:c:func:`PySequence_Fast` and that *o* is not *NULL*. The size can also be :c:func:`PySequence_Fast` and that *o* is not ``NULL``. The size can also be
gotten by calling :c:func:`PySequence_Size` on *o*, but gotten by calling :c:func:`PySequence_Size` on *o*, but
:c:func:`PySequence_Fast_GET_SIZE` is faster because it can assume *o* is a :c:func:`PySequence_Fast_GET_SIZE` is faster because it can assume *o* is a
list or tuple. list or tuple.
@ -155,13 +155,13 @@ Sequence Protocol
.. c:function:: PyObject* PySequence_Fast_GET_ITEM(PyObject *o, Py_ssize_t i) .. c:function:: PyObject* PySequence_Fast_GET_ITEM(PyObject *o, Py_ssize_t i)
Return the *i*\ th element of *o*, assuming that *o* was returned by Return the *i*\ th element of *o*, assuming that *o* was returned by
:c:func:`PySequence_Fast`, *o* is not *NULL*, and that *i* is within bounds. :c:func:`PySequence_Fast`, *o* is not ``NULL``, and that *i* is within bounds.
.. c:function:: PyObject** PySequence_Fast_ITEMS(PyObject *o) .. c:function:: PyObject** PySequence_Fast_ITEMS(PyObject *o)
Return the underlying array of PyObject pointers. Assumes that *o* was returned Return the underlying array of PyObject pointers. Assumes that *o* was returned
by :c:func:`PySequence_Fast` and *o* is not *NULL*. by :c:func:`PySequence_Fast` and *o* is not ``NULL``.
Note, if a list gets resized, the reallocation may relocate the items array. Note, if a list gets resized, the reallocation may relocate the items array.
So, only use the underlying array pointer in contexts where the sequence So, only use the underlying array pointer in contexts where the sequence
@ -170,7 +170,7 @@ Sequence Protocol
.. c:function:: PyObject* PySequence_ITEM(PyObject *o, Py_ssize_t i) .. c:function:: PyObject* PySequence_ITEM(PyObject *o, Py_ssize_t i)
Return the *i*\ th element of *o* or *NULL* on failure. Faster form of Return the *i*\ th element of *o* or ``NULL`` on failure. Faster form of
:c:func:`PySequence_GetItem` but without checking that :c:func:`PySequence_GetItem` but without checking that
:c:func:`PySequence_Check` on *o* is true and without adjustment for negative :c:func:`PySequence_Check` on *o* is true and without adjustment for negative
indices. indices.

10
Doc/c-api/set.rst
View File

@ -80,8 +80,8 @@ the constructor functions work with any iterable Python object.
.. c:function:: PyObject* PySet_New(PyObject *iterable) .. c:function:: PyObject* PySet_New(PyObject *iterable)
Return a new :class:`set` containing objects returned by the *iterable*. The Return a new :class:`set` containing objects returned by the *iterable*. The
*iterable* may be *NULL* to create a new empty set. Return the new set on *iterable* may be ``NULL`` to create a new empty set. Return the new set on
success or *NULL* on failure. Raise :exc:`TypeError` if *iterable* is not success or ``NULL`` on failure. Raise :exc:`TypeError` if *iterable* is not
actually iterable. The constructor is also useful for copying a set actually iterable. The constructor is also useful for copying a set
(``c=set(s)``). (``c=set(s)``).
@ -89,8 +89,8 @@ the constructor functions work with any iterable Python object.
.. c:function:: PyObject* PyFrozenSet_New(PyObject *iterable) .. c:function:: PyObject* PyFrozenSet_New(PyObject *iterable)
Return a new :class:`frozenset` containing objects returned by the *iterable*. Return a new :class:`frozenset` containing objects returned by the *iterable*.
The *iterable* may be *NULL* to create a new empty frozenset. Return the new The *iterable* may be ``NULL`` to create a new empty frozenset. Return the new
set on success or *NULL* on failure. Raise :exc:`TypeError` if *iterable* is set on success or ``NULL`` on failure. Raise :exc:`TypeError` if *iterable* is
not actually iterable. not actually iterable.
@ -149,7 +149,7 @@ subtypes but not for instances of :class:`frozenset` or its subtypes.
.. c:function:: PyObject* PySet_Pop(PyObject *set) .. c:function:: PyObject* PySet_Pop(PyObject *set)
Return a new reference to an arbitrary object in the *set*, and removes the Return a new reference to an arbitrary object in the *set*, and removes the
object from the *set*. Return *NULL* on failure. Raise :exc:`KeyError` if the object from the *set*. Return ``NULL`` on failure. Raise :exc:`KeyError` if the
set is empty. Raise a :exc:`SystemError` if *set* is not an instance of set is empty. Raise a :exc:`SystemError` if *set* is not an instance of
:class:`set` or its subtype. :class:`set` or its subtype.

6
Doc/c-api/slice.rst
View File

@ -14,15 +14,15 @@ Slice Objects
.. c:function:: int PySlice_Check(PyObject *ob) .. c:function:: int PySlice_Check(PyObject *ob)
Return true if *ob* is a slice object; *ob* must not be *NULL*. Return true if *ob* is a slice object; *ob* must not be ``NULL``.
.. c:function:: PyObject* PySlice_New(PyObject *start, PyObject *stop, PyObject *step) .. c:function:: PyObject* PySlice_New(PyObject *start, PyObject *stop, PyObject *step)
Return a new slice object with the given values. The *start*, *stop*, and Return a new slice object with the given values. The *start*, *stop*, and
*step* parameters are used as the values of the slice object attributes of *step* parameters are used as the values of the slice object attributes of
the same names. Any of the values may be *NULL*, in which case the the same names. Any of the values may be ``NULL``, in which case the
``None`` will be used for the corresponding attribute. Return *NULL* if ``None`` will be used for the corresponding attribute. Return ``NULL`` if
the new object could not be allocated. the new object could not be allocated.

20
Doc/c-api/structures.rst
View File

@ -113,8 +113,8 @@ Implementing functions and methods
Type of the functions used to implement most Python callables in C. Type of the functions used to implement most Python callables in C.
Functions of this type take two :c:type:`PyObject\*` parameters and return Functions of this type take two :c:type:`PyObject\*` parameters and return
one such value. If the return value is *NULL*, an exception shall have one such value. If the return value is ``NULL``, an exception shall have
been set. If not *NULL*, the return value is interpreted as the return been set. If not ``NULL``, the return value is interpreted as the return
value of the function as exposed in Python. The function must return a new value of the function as exposed in Python. The function must return a new
reference. reference.
@ -186,7 +186,7 @@ also keyword arguments. So there are a total of 6 calling conventions:
Methods with these flags must be of type :c:type:`PyCFunctionWithKeywords`. Methods with these flags must be of type :c:type:`PyCFunctionWithKeywords`.
The function expects three parameters: *self*, *args*, *kwargs* where The function expects three parameters: *self*, *args*, *kwargs* where
*kwargs* is a dictionary of all the keyword arguments or possibly *NULL* *kwargs* is a dictionary of all the keyword arguments or possibly ``NULL``
if there are no keyword arguments. The parameters are typically processed if there are no keyword arguments. The parameters are typically processed
using :c:func:`PyArg_ParseTupleAndKeywords`. using :c:func:`PyArg_ParseTupleAndKeywords`.
@ -212,7 +212,7 @@ also keyword arguments. So there are a total of 6 calling conventions:
there is an additional fourth :c:type:`PyObject\*` parameter there is an additional fourth :c:type:`PyObject\*` parameter
which is a tuple representing the names of the keyword arguments which is a tuple representing the names of the keyword arguments
(which are guaranteed to be strings) (which are guaranteed to be strings)
or possibly *NULL* if there are no keywords. The values of the keyword or possibly ``NULL`` if there are no keywords. The values of the keyword
arguments are stored in the *args* array, after the positional arguments. arguments are stored in the *args* array, after the positional arguments.
This is not part of the :ref:`limited API <stable>`. This is not part of the :ref:`limited API <stable>`.
@ -226,7 +226,7 @@ also keyword arguments. So there are a total of 6 calling conventions:
they are listed with the :const:`METH_NOARGS` flag. They need to be of type they are listed with the :const:`METH_NOARGS` flag. They need to be of type
:c:type:`PyCFunction`. The first parameter is typically named *self* and will :c:type:`PyCFunction`. The first parameter is typically named *self* and will
hold a reference to the module or object instance. In all cases the second hold a reference to the module or object instance. In all cases the second
parameter will be *NULL*. parameter will be ``NULL``.
.. data:: METH_O .. data:: METH_O
@ -257,7 +257,7 @@ method.
.. index:: builtin: staticmethod .. index:: builtin: staticmethod
The method will be passed *NULL* as the first parameter rather than an The method will be passed ``NULL`` as the first parameter rather than an
instance of the type. This is used to create *static methods*, similar to instance of the type. This is used to create *static methods*, similar to
what is created when using the :func:`staticmethod` built-in function. what is created when using the :func:`staticmethod` built-in function.
@ -334,7 +334,7 @@ Accessing attributes of extension types
=============== ================== =============== ==================
:c:macro:`T_OBJECT` and :c:macro:`T_OBJECT_EX` differ in that :c:macro:`T_OBJECT` and :c:macro:`T_OBJECT_EX` differ in that
:c:macro:`T_OBJECT` returns ``None`` if the member is *NULL* and :c:macro:`T_OBJECT` returns ``None`` if the member is ``NULL`` and
:c:macro:`T_OBJECT_EX` raises an :exc:`AttributeError`. Try to use :c:macro:`T_OBJECT_EX` raises an :exc:`AttributeError`. Try to use
:c:macro:`T_OBJECT_EX` over :c:macro:`T_OBJECT` because :c:macro:`T_OBJECT_EX` :c:macro:`T_OBJECT_EX` over :c:macro:`T_OBJECT` because :c:macro:`T_OBJECT_EX`
handles use of the :keyword:`del` statement on that attribute more correctly handles use of the :keyword:`del` statement on that attribute more correctly
@ -344,7 +344,7 @@ Accessing attributes of extension types
read-only access. Using :c:macro:`T_STRING` for :attr:`type` implies read-only access. Using :c:macro:`T_STRING` for :attr:`type` implies
:c:macro:`READONLY`. :c:macro:`T_STRING` data is interpreted as UTF-8. :c:macro:`READONLY`. :c:macro:`T_STRING` data is interpreted as UTF-8.
Only :c:macro:`T_OBJECT` and :c:macro:`T_OBJECT_EX` Only :c:macro:`T_OBJECT` and :c:macro:`T_OBJECT_EX`
members can be deleted. (They are set to *NULL*). members can be deleted. (They are set to ``NULL``).
.. _pymemberdef-offsets: .. _pymemberdef-offsets:
@ -388,7 +388,7 @@ Accessing attributes of extension types
typedef PyObject *(*getter)(PyObject *, void *); typedef PyObject *(*getter)(PyObject *, void *);
It should return a new reference on success or *NULL* with a set exception It should return a new reference on success or ``NULL`` with a set exception
on failure. on failure.
``set`` functions take two :c:type:`PyObject\*` parameters (the instance and ``set`` functions take two :c:type:`PyObject\*` parameters (the instance and
@ -396,5 +396,5 @@ Accessing attributes of extension types
typedef int (*setter)(PyObject *, PyObject *, void *); typedef int (*setter)(PyObject *, PyObject *, void *);
In case the attribute should be deleted the second parameter is *NULL*. In case the attribute should be deleted the second parameter is ``NULL``.
Should return ``0`` on success or ``-1`` with a set exception on failure. Should return ``0`` on success or ``-1`` with a set exception on failure.

8
Doc/c-api/sys.rst
View File

@ -22,7 +22,7 @@ Operating System Utilities
Return true (nonzero) if the standard I/O file *fp* with name *filename* is Return true (nonzero) if the standard I/O file *fp* with name *filename* is
deemed interactive. This is the case for files for which ``isatty(fileno(fp))`` deemed interactive. This is the case for files for which ``isatty(fileno(fp))``
is true. If the global flag :c:data:`Py_InteractiveFlag` is true, this function is true. If the global flag :c:data:`Py_InteractiveFlag` is true, this function
also returns true if the *filename* pointer is *NULL* or if the name is equal to also returns true if the *filename* pointer is ``NULL`` or if the name is equal to
one of the strings ``'<stdin>'`` or ``'???'``. one of the strings ``'<stdin>'`` or ``'???'``.
@ -201,12 +201,12 @@ accessible to C code. They all work with the current interpreter thread's
.. c:function:: PyObject *PySys_GetObject(const char *name) .. c:function:: PyObject *PySys_GetObject(const char *name)
Return the object *name* from the :mod:`sys` module or *NULL* if it does Return the object *name* from the :mod:`sys` module or ``NULL`` if it does
not exist, without setting an exception. not exist, without setting an exception.
.. c:function:: int PySys_SetObject(const char *name, PyObject *v) .. c:function:: int PySys_SetObject(const char *name, PyObject *v)
Set *name* in the :mod:`sys` module to *v* unless *v* is *NULL*, in which Set *name* in the :mod:`sys` module to *v* unless *v* is ``NULL``, in which
case *name* is deleted from the sys module. Returns ``0`` on success, ``-1`` case *name* is deleted from the sys module. Returns ``0`` on success, ``-1``
on error. on error.
@ -283,7 +283,7 @@ accessible to C code. They all work with the current interpreter thread's
.. c:function:: PyObject *PySys_GetXOptions() .. c:function:: PyObject *PySys_GetXOptions()
Return the current dictionary of :option:`-X` options, similarly to Return the current dictionary of :option:`-X` options, similarly to
:data:`sys._xoptions`. On error, *NULL* is returned and an exception is :data:`sys._xoptions`. On error, ``NULL`` is returned and an exception is
set. set.
.. versionadded:: 3.2 .. versionadded:: 3.2

60
Doc/c-api/tuple.rst
View File

@ -33,12 +33,12 @@ Tuple Objects
.. c:function:: PyObject* PyTuple_New(Py_ssize_t len) .. c:function:: PyObject* PyTuple_New(Py_ssize_t len)
Return a new tuple object of size *len*, or *NULL* on failure. Return a new tuple object of size *len*, or ``NULL`` on failure.
.. c:function:: PyObject* PyTuple_Pack(Py_ssize_t n, ...) .. c:function:: PyObject* PyTuple_Pack(Py_ssize_t n, ...)
Return a new tuple object of size *n*, or *NULL* on failure. The tuple values Return a new tuple object of size *n*, or ``NULL`` on failure. The tuple values
are initialized to the subsequent *n* C arguments pointing to Python objects. are initialized to the subsequent *n* C arguments pointing to Python objects.
``PyTuple_Pack(2, a, b)`` is equivalent to ``Py_BuildValue("(OO)", a, b)``. ``PyTuple_Pack(2, a, b)`` is equivalent to ``Py_BuildValue("(OO)", a, b)``.
@ -50,14 +50,14 @@ Tuple Objects
.. c:function:: Py_ssize_t PyTuple_GET_SIZE(PyObject *p) .. c:function:: Py_ssize_t PyTuple_GET_SIZE(PyObject *p)
Return the size of the tuple *p*, which must be non-*NULL* and point to a tuple; Return the size of the tuple *p*, which must be non-``NULL`` and point to a tuple;
no error checking is performed. no error checking is performed.
.. c:function:: PyObject* PyTuple_GetItem(PyObject *p, Py_ssize_t pos) .. c:function:: PyObject* PyTuple_GetItem(PyObject *p, Py_ssize_t pos)
Return the object at position *pos* in the tuple pointed to by *p*. If *pos* is Return the object at position *pos* in the tuple pointed to by *p*. If *pos* is
out of bounds, return *NULL* and set an :exc:`IndexError` exception. out of bounds, return ``NULL`` and set an :exc:`IndexError` exception.
.. c:function:: PyObject* PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos) .. c:function:: PyObject* PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos)
@ -68,7 +68,7 @@ Tuple Objects
.. c:function:: PyObject* PyTuple_GetSlice(PyObject *p, Py_ssize_t low, Py_ssize_t high) .. c:function:: PyObject* PyTuple_GetSlice(PyObject *p, Py_ssize_t low, Py_ssize_t high)
Return the slice of the tuple pointed to by *p* between *low* and *high*, Return the slice of the tuple pointed to by *p* between *low* and *high*,
or *NULL* on failure. This is the equivalent of the Python expression or ``NULL`` on failure. This is the equivalent of the Python expression
``p[low:high]``. Indexing from the end of the list is not supported. ``p[low:high]``. Indexing from the end of the list is not supported.
@ -107,7 +107,7 @@ Tuple Objects
only more efficiently. Returns ``0`` on success. Client code should never only more efficiently. Returns ``0`` on success. Client code should never
assume that the resulting value of ``*p`` will be the same as before calling assume that the resulting value of ``*p`` will be the same as before calling
this function. If the object referenced by ``*p`` is replaced, the original this function. If the object referenced by ``*p`` is replaced, the original
``*p`` is destroyed. On failure, returns ``-1`` and sets ``*p`` to *NULL*, and ``*p`` is destroyed. On failure, returns ``-1`` and sets ``*p`` to ``NULL``, and
raises :exc:`MemoryError` or :exc:`SystemError`. raises :exc:`MemoryError` or :exc:`SystemError`.
@ -147,20 +147,20 @@ type.
Contains the meta information of a struct sequence type to create. Contains the meta information of a struct sequence type to create.
+-------------------+------------------------------+------------------------------------+ +-------------------+------------------------------+--------------------------------------+
| Field | C Type | Meaning | | Field | C Type | Meaning |
+===================+==============================+====================================+ +===================+==============================+======================================+
| ``name`` | ``const char *`` | name of the struct sequence type | | ``name`` | ``const char *`` | name of the struct sequence type |
+-------------------+------------------------------+------------------------------------+ +-------------------+------------------------------+--------------------------------------+
| ``doc`` | ``const char *`` | pointer to docstring for the type | | ``doc`` | ``const char *`` | pointer to docstring for the type |
| | | or NULL to omit | | | | or NULL to omit |
+-------------------+------------------------------+------------------------------------+ +-------------------+------------------------------+--------------------------------------+
| ``fields`` | ``PyStructSequence_Field *`` | pointer to *NULL*-terminated array | | ``fields`` | ``PyStructSequence_Field *`` | pointer to ``NULL``-terminated array |
| | | with field names of the new type | | | | with field names of the new type |
+-------------------+------------------------------+------------------------------------+ +-------------------+------------------------------+--------------------------------------+
| ``n_in_sequence`` | ``int`` | number of fields visible to the | | ``n_in_sequence`` | ``int`` | number of fields visible to the |
| | | Python side (if used as tuple) | | | | Python side (if used as tuple) |
+-------------------+------------------------------+------------------------------------+ +-------------------+------------------------------+--------------------------------------+
.. c:type:: PyStructSequence_Field .. c:type:: PyStructSequence_Field
@ -170,16 +170,16 @@ type.
:attr:`fields` array of the :c:type:`PyStructSequence_Desc` determines which :attr:`fields` array of the :c:type:`PyStructSequence_Desc` determines which
field of the struct sequence is described. field of the struct sequence is described.
+-----------+------------------+--------------------------------------+ +-----------+------------------+----------------------------------------+
| Field | C Type | Meaning | | Field | C Type | Meaning |
+===========+==================+======================================+ +===========+==================+========================================+
| ``name`` | ``const char *`` | name for the field or *NULL* to end | | ``name`` | ``const char *`` | name for the field or ``NULL`` to end |
| | | the list of named fields, set to | | | | the list of named fields, set to |
| | | PyStructSequence_UnnamedField to | | | | PyStructSequence_UnnamedField to |
| | | leave unnamed | | | | leave unnamed |
+-----------+------------------+--------------------------------------+ +-----------+------------------+----------------------------------------+
| ``doc`` | ``const char *`` | field docstring or *NULL* to omit | | ``doc`` | ``const char *`` | field docstring or ``NULL`` to omit |
+-----------+------------------+--------------------------------------+ +-----------+------------------+----------------------------------------+
.. c:var:: char* PyStructSequence_UnnamedField .. c:var:: char* PyStructSequence_UnnamedField

10
Doc/c-api/type.rst
View File

@ -81,7 +81,7 @@ Type Objects
Generic handler for the :c:member:`~PyTypeObject.tp_alloc` slot of a type object. Use Generic handler for the :c:member:`~PyTypeObject.tp_alloc` slot of a type object. Use
Python's default memory allocation mechanism to allocate a new instance and Python's default memory allocation mechanism to allocate a new instance and
initialize all its contents to *NULL*. initialize all its contents to ``NULL``.
.. c:function:: PyObject* PyType_GenericNew(PyTypeObject *type, PyObject *args, PyObject *kwds) .. c:function:: PyObject* PyType_GenericNew(PyTypeObject *type, PyObject *args, PyObject *kwds)
@ -98,7 +98,7 @@ Type Objects
.. c:function:: void* PyType_GetSlot(PyTypeObject *type, int slot) .. c:function:: void* PyType_GetSlot(PyTypeObject *type, int slot)
Return the function pointer stored in the given slot. If the Return the function pointer stored in the given slot. If the
result is *NULL*, this indicates that either the slot is *NULL*, result is ``NULL``, this indicates that either the slot is ``NULL``,
or that the function was called with invalid parameters. or that the function was called with invalid parameters.
Callers will typically cast the result pointer into the appropriate Callers will typically cast the result pointer into the appropriate
function type. function type.
@ -124,8 +124,8 @@ The following functions and structs are used to create
If *bases* is a tuple, the created heap type contains all types contained If *bases* is a tuple, the created heap type contains all types contained
in it as base types. in it as base types.
If *bases* is *NULL*, the *Py_tp_base* slot is used instead. If *bases* is ``NULL``, the *Py_tp_base* slot is used instead.
If that also is *NULL*, the new type derives from :class:`object`. If that also is ``NULL``, the new type derives from :class:`object`.
This function calls :c:func:`PyType_Ready` on the new type. This function calls :c:func:`PyType_Ready` on the new type.
@ -205,4 +205,4 @@ The following functions and structs are used to create
The desired value of the slot. In most cases, this is a pointer The desired value of the slot. In most cases, this is a pointer
to a function. to a function.
May not be *NULL*. May not be ``NULL``.

128
Doc/c-api/typeobj.rst
View File

@ -159,20 +159,20 @@ fields exist as well:
A slot name in parentheses indicates it is (effectively) deprecated. A slot name in parentheses indicates it is (effectively) deprecated.
Names in angle brackets should be treated as read-only. Names in angle brackets should be treated as read-only.
Names in square brackets are for internal use only. Names in square brackets are for internal use only.
"<R>" (as a prefix) means the field is required (must be non-*NULL*). "<R>" (as a prefix) means the field is required (must be non-``NULL``).
.. [#cols] Columns: .. [#cols] Columns:
**"O"**: set on :c:type:`PyBaseObject_Type` **"O"**: set on :c:type:`PyBaseObject_Type`
**"T"**: set on :c:type:`PyType_Type` **"T"**: set on :c:type:`PyType_Type`
**"D"**: default (if slot is set to *NULL*) **"D"**: default (if slot is set to ``NULL``)
.. code-block:: none .. code-block:: none
X - *PyType_Ready* sets this value if it is *NULL* X - PyType_Ready sets this value if it is NULL
~ - *PyType_Ready* always sets this value (it should be *NULL*) ~ - PyType_Ready always sets this value (it should be NULL)
? - *PyType_Ready* may set this value depending on other slots ? - PyType_Ready may set this value depending on other slots
Also see the inheritance column ("I"). Also see the inheritance column ("I").
@ -180,7 +180,7 @@ fields exist as well:
.. code-block:: none .. code-block:: none
X - type slot is inherited via *PyType_Ready* if defined with a *NULL* value X - type slot is inherited via PyType_Ready if defined with a NULL value
% - the slots of the sub-struct are inherited individually % - the slots of the sub-struct are inherited individually
G - inherited, but only in combination with other slots; see the slot's description G - inherited, but only in combination with other slots; see the slot's description
? - it's complicated; see the slot's description ? - it's complicated; see the slot's description
@ -491,8 +491,8 @@ type objects) *must* have the :attr:`ob_size` field.
PyObject* PyObject._ob_prev PyObject* PyObject._ob_prev
These fields are only present when the macro ``Py_TRACE_REFS`` is defined. These fields are only present when the macro ``Py_TRACE_REFS`` is defined.
Their initialization to *NULL* is taken care of by the ``PyObject_HEAD_INIT`` Their initialization to ``NULL`` is taken care of by the ``PyObject_HEAD_INIT``
macro. For statically allocated objects, these fields always remain *NULL*. macro. For statically allocated objects, these fields always remain ``NULL``.
For dynamically allocated objects, these two fields are used to link the object For dynamically allocated objects, these two fields are used to link the object
into a doubly-linked list of *all* live objects on the heap. This could be used into a doubly-linked list of *all* live objects on the heap. This could be used
for various debugging purposes; currently the only use is to print the objects for various debugging purposes; currently the only use is to print the objects
@ -523,7 +523,7 @@ type objects) *must* have the :attr:`ob_size` field.
argument to the ``PyObject_HEAD_INIT`` macro, and its value should normally be argument to the ``PyObject_HEAD_INIT`` macro, and its value should normally be
``&PyType_Type``. However, for dynamically loadable extension modules that must ``&PyType_Type``. However, for dynamically loadable extension modules that must
be usable on Windows (at least), the compiler complains that this is not a valid be usable on Windows (at least), the compiler complains that this is not a valid
initializer. Therefore, the convention is to pass *NULL* to the initializer. Therefore, the convention is to pass ``NULL`` to the
``PyObject_HEAD_INIT`` macro and to initialize this field explicitly at the ``PyObject_HEAD_INIT`` macro and to initialize this field explicitly at the
start of the module's initialization function, before doing anything else. This start of the module's initialization function, before doing anything else. This
is typically done like this:: is typically done like this::
@ -531,7 +531,7 @@ type objects) *must* have the :attr:`ob_size` field.
Foo_Type.ob_type = &PyType_Type; Foo_Type.ob_type = &PyType_Type;
This should be done before any instances of the type are created. This should be done before any instances of the type are created.
:c:func:`PyType_Ready` checks if :attr:`ob_type` is *NULL*, and if so, :c:func:`PyType_Ready` checks if :attr:`ob_type` is ``NULL``, and if so,
initializes it to the :attr:`ob_type` field of the base class. initializes it to the :attr:`ob_type` field of the base class.
:c:func:`PyType_Ready` will not change this field if it is non-zero. :c:func:`PyType_Ready` will not change this field if it is non-zero.
@ -557,7 +557,7 @@ PyTypeObject Slots
------------------ ------------------
Each slot has a section describing inheritance. If :c:func:`PyType_Ready` Each slot has a section describing inheritance. If :c:func:`PyType_Ready`
may set a value when the field is set to *NULL* then there will also be may set a value when the field is set to ``NULL`` then there will also be
a "Default" section. (Note that many fields set on :c:type:`PyBaseObject_Type` a "Default" section. (Note that many fields set on :c:type:`PyBaseObject_Type`
and :c:type:`PyType_Type` effectively act as defaults.) and :c:type:`PyType_Type` effectively act as defaults.)
@ -586,7 +586,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
type will be impossible to pickle. Additionally, it will not be listed in type will be impossible to pickle. Additionally, it will not be listed in
module documentations created with pydoc. module documentations created with pydoc.
This field must not be *NULL*. It is the only required field This field must not be ``NULL``. It is the only required field
in :c:func:`PyTypeObject` (other than potentially in :c:func:`PyTypeObject` (other than potentially
:c:member:`~PyTypeObject.tp_itemsize`). :c:member:`~PyTypeObject.tp_itemsize`).
@ -631,7 +631,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
:c:member:`~PyTypeObject.tp_basicsize` is a multiple of ``sizeof(double)`` (assuming this is the :c:member:`~PyTypeObject.tp_basicsize` is a multiple of ``sizeof(double)`` (assuming this is the
alignment requirement for ``double``). alignment requirement for ``double``).
For any type with variable-length instances, this field must not be *NULL*. For any type with variable-length instances, this field must not be ``NULL``.
**Inheritance:** **Inheritance:**
@ -760,7 +760,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_getattro`: a subtype This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_getattro`: a subtype
inherits both :c:member:`~PyTypeObject.tp_getattr` and :c:member:`~PyTypeObject.tp_getattro` from its base type when inherits both :c:member:`~PyTypeObject.tp_getattr` and :c:member:`~PyTypeObject.tp_getattro` from its base type when
the subtype's :c:member:`~PyTypeObject.tp_getattr` and :c:member:`~PyTypeObject.tp_getattro` are both *NULL*. the subtype's :c:member:`~PyTypeObject.tp_getattr` and :c:member:`~PyTypeObject.tp_getattro` are both ``NULL``.
.. c:member:: setattrfunc PyTypeObject.tp_setattr .. c:member:: setattrfunc PyTypeObject.tp_setattr
@ -777,7 +777,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_setattro`: a subtype This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_setattro`: a subtype
inherits both :c:member:`~PyTypeObject.tp_setattr` and :c:member:`~PyTypeObject.tp_setattro` from its base type when inherits both :c:member:`~PyTypeObject.tp_setattr` and :c:member:`~PyTypeObject.tp_setattro` from its base type when
the subtype's :c:member:`~PyTypeObject.tp_setattr` and :c:member:`~PyTypeObject.tp_setattro` are both *NULL*. the subtype's :c:member:`~PyTypeObject.tp_setattr` and :c:member:`~PyTypeObject.tp_setattro` are both ``NULL``.
.. c:member:: PyAsyncMethods* PyTypeObject.tp_as_async .. c:member:: PyAsyncMethods* PyTypeObject.tp_as_async
@ -894,13 +894,13 @@ and :c:type:`PyType_Type` effectively act as defaults.)
This field is inherited by subtypes together with This field is inherited by subtypes together with
:c:member:`~PyTypeObject.tp_richcompare`: a subtype inherits both of :c:member:`~PyTypeObject.tp_richcompare`: a subtype inherits both of
:c:member:`~PyTypeObject.tp_richcompare` and :c:member:`~PyTypeObject.tp_hash`, when the subtype's :c:member:`~PyTypeObject.tp_richcompare` and :c:member:`~PyTypeObject.tp_hash`, when the subtype's
:c:member:`~PyTypeObject.tp_richcompare` and :c:member:`~PyTypeObject.tp_hash` are both *NULL*. :c:member:`~PyTypeObject.tp_richcompare` and :c:member:`~PyTypeObject.tp_hash` are both ``NULL``.
.. c:member:: ternaryfunc PyTypeObject.tp_call .. c:member:: ternaryfunc PyTypeObject.tp_call
An optional pointer to a function that implements calling the object. This An optional pointer to a function that implements calling the object. This
should be *NULL* if the object is not callable. The signature is the same as should be ``NULL`` if the object is not callable. The signature is the same as
for :c:func:`PyObject_Call`:: for :c:func:`PyObject_Call`::
PyObject *tp_call(PyObject *self, PyObject *args, PyObject *kwargs); PyObject *tp_call(PyObject *self, PyObject *args, PyObject *kwargs);
@ -952,7 +952,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_getattr`: a subtype This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_getattr`: a subtype
inherits both :c:member:`~PyTypeObject.tp_getattr` and :c:member:`~PyTypeObject.tp_getattro` from its base type when inherits both :c:member:`~PyTypeObject.tp_getattr` and :c:member:`~PyTypeObject.tp_getattro` from its base type when
the subtype's :c:member:`~PyTypeObject.tp_getattr` and :c:member:`~PyTypeObject.tp_getattro` are both *NULL*. the subtype's :c:member:`~PyTypeObject.tp_getattr` and :c:member:`~PyTypeObject.tp_getattro` are both ``NULL``.
**Default:** **Default:**
@ -967,7 +967,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
PyObject *tp_setattro(PyObject *self, PyObject *attr, PyObject *value); PyObject *tp_setattro(PyObject *self, PyObject *attr, PyObject *value);
In addition, setting *value* to *NULL* to delete an attribute must be In addition, setting *value* to ``NULL`` to delete an attribute must be
supported. It is usually convenient to set this field to supported. It is usually convenient to set this field to
:c:func:`PyObject_GenericSetAttr`, which implements the normal :c:func:`PyObject_GenericSetAttr`, which implements the normal
way of setting object attributes. way of setting object attributes.
@ -978,7 +978,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_setattr`: a subtype This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_setattr`: a subtype
inherits both :c:member:`~PyTypeObject.tp_setattr` and :c:member:`~PyTypeObject.tp_setattro` from its base type when inherits both :c:member:`~PyTypeObject.tp_setattr` and :c:member:`~PyTypeObject.tp_setattro` from its base type when
the subtype's :c:member:`~PyTypeObject.tp_setattr` and :c:member:`~PyTypeObject.tp_setattro` are both *NULL*. the subtype's :c:member:`~PyTypeObject.tp_setattr` and :c:member:`~PyTypeObject.tp_setattro` are both ``NULL``.
**Default:** **Default:**
@ -1005,7 +1005,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
:c:member:`~PyTypeObject.tp_as_number`, :c:member:`~PyTypeObject.tp_as_sequence`, :c:member:`~PyTypeObject.tp_as_mapping`, and :c:member:`~PyTypeObject.tp_as_number`, :c:member:`~PyTypeObject.tp_as_sequence`, :c:member:`~PyTypeObject.tp_as_mapping`, and
:c:member:`~PyTypeObject.tp_as_buffer`) that were historically not always present are valid; if :c:member:`~PyTypeObject.tp_as_buffer`) that were historically not always present are valid; if
such a flag bit is clear, the type fields it guards must not be accessed and such a flag bit is clear, the type fields it guards must not be accessed and
must be considered to have a zero or *NULL* value instead. must be considered to have a zero or ``NULL`` value instead.
**Inheritance:** **Inheritance:**
@ -1018,7 +1018,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
the :c:member:`~PyTypeObject.tp_traverse` and :c:member:`~PyTypeObject.tp_clear` fields, i.e. if the the :c:member:`~PyTypeObject.tp_traverse` and :c:member:`~PyTypeObject.tp_clear` fields, i.e. if the
:const:`Py_TPFLAGS_HAVE_GC` flag bit is clear in the subtype and the :const:`Py_TPFLAGS_HAVE_GC` flag bit is clear in the subtype and the
:c:member:`~PyTypeObject.tp_traverse` and :c:member:`~PyTypeObject.tp_clear` fields in the subtype exist and have :c:member:`~PyTypeObject.tp_traverse` and :c:member:`~PyTypeObject.tp_clear` fields in the subtype exist and have
*NULL* values. ``NULL`` values.
.. XXX are most flag bits *really* inherited individually? .. XXX are most flag bits *really* inherited individually?
@ -1097,7 +1097,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
together with the :attr:`tp_traverse` and :attr:`tp_clear` together with the :attr:`tp_traverse` and :attr:`tp_clear`
fields, i.e. if the :const:`Py_TPFLAGS_HAVE_GC` flag bit is fields, i.e. if the :const:`Py_TPFLAGS_HAVE_GC` flag bit is
clear in the subtype and the :attr:`tp_traverse` and clear in the subtype and the :attr:`tp_traverse` and
:attr:`tp_clear` fields in the subtype exist and have *NULL* :attr:`tp_clear` fields in the subtype exist and have ``NULL``
values. values.
@ -1232,7 +1232,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
Note that :c:func:`Py_VISIT` is called only on those members that can participate Note that :c:func:`Py_VISIT` is called only on those members that can participate
in reference cycles. Although there is also a ``self->key`` member, it can only in reference cycles. Although there is also a ``self->key`` member, it can only
be *NULL* or a Python string and therefore cannot be part of a reference cycle. be ``NULL`` or a Python string and therefore cannot be part of a reference cycle.
On the other hand, even if you know a member can never be part of a cycle, as a On the other hand, even if you know a member can never be part of a cycle, as a
debugging aid you may want to visit it anyway just so the :mod:`gc` module's debugging aid you may want to visit it anyway just so the :mod:`gc` module's
@ -1271,7 +1271,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
Implementations of :c:member:`~PyTypeObject.tp_clear` should drop the instance's references to Implementations of :c:member:`~PyTypeObject.tp_clear` should drop the instance's references to
those of its members that may be Python objects, and set its pointers to those those of its members that may be Python objects, and set its pointers to those
members to *NULL*, as in the following example:: members to ``NULL``, as in the following example::
static int static int
local_clear(localobject *self) local_clear(localobject *self)
@ -1285,12 +1285,12 @@ and :c:type:`PyType_Type` effectively act as defaults.)
The :c:func:`Py_CLEAR` macro should be used, because clearing references is The :c:func:`Py_CLEAR` macro should be used, because clearing references is
delicate: the reference to the contained object must not be decremented until delicate: the reference to the contained object must not be decremented until
after the pointer to the contained object is set to *NULL*. This is because after the pointer to the contained object is set to ``NULL``. This is because
decrementing the reference count may cause the contained object to become trash, decrementing the reference count may cause the contained object to become trash,
triggering a chain of reclamation activity that may include invoking arbitrary triggering a chain of reclamation activity that may include invoking arbitrary
Python code (due to finalizers, or weakref callbacks, associated with the Python code (due to finalizers, or weakref callbacks, associated with the
contained object). If it's possible for such code to reference *self* again, contained object). If it's possible for such code to reference *self* again,
it's important that the pointer to the contained object be *NULL* at that time, it's important that the pointer to the contained object be ``NULL`` at that time,
so that *self* knows the contained object can no longer be used. The so that *self* knows the contained object can no longer be used. The
:c:func:`Py_CLEAR` macro performs the operations in a safe order. :c:func:`Py_CLEAR` macro performs the operations in a safe order.
@ -1324,7 +1324,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
The function should return the result of the comparison (usually ``Py_True`` The function should return the result of the comparison (usually ``Py_True``
or ``Py_False``). If the comparison is undefined, it must return or ``Py_False``). If the comparison is undefined, it must return
``Py_NotImplemented``, if another error occurred it must return *NULL* and ``Py_NotImplemented``, if another error occurred it must return ``NULL`` and
set an exception condition. set an exception condition.
The following constants are defined to be used as the third argument for The following constants are defined to be used as the third argument for
@ -1358,7 +1358,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
The return value's reference count is properly incremented. The return value's reference count is properly incremented.
On error, sets an exception and returns *NULL* from the function. On error, sets an exception and returns ``NULL`` from the function.
.. versionadded:: 3.7 .. versionadded:: 3.7
@ -1369,7 +1369,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_hash`: This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_hash`:
a subtype inherits :c:member:`~PyTypeObject.tp_richcompare` and :c:member:`~PyTypeObject.tp_hash` when a subtype inherits :c:member:`~PyTypeObject.tp_richcompare` and :c:member:`~PyTypeObject.tp_hash` when
the subtype's :c:member:`~PyTypeObject.tp_richcompare` and :c:member:`~PyTypeObject.tp_hash` are both the subtype's :c:member:`~PyTypeObject.tp_richcompare` and :c:member:`~PyTypeObject.tp_hash` are both
*NULL*. ``NULL``.
**Default:** **Default:**
@ -1387,7 +1387,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
reference list head (ignoring the GC header, if present); this offset is used by reference list head (ignoring the GC header, if present); this offset is used by
:c:func:`PyObject_ClearWeakRefs` and the :c:func:`PyWeakref_\*` functions. The :c:func:`PyObject_ClearWeakRefs` and the :c:func:`PyWeakref_\*` functions. The
instance structure needs to include a field of type :c:type:`PyObject\*` which is instance structure needs to include a field of type :c:type:`PyObject\*` which is
initialized to *NULL*. initialized to ``NULL``.
Do not confuse this field with :c:member:`~PyTypeObject.tp_weaklist`; that is the list head for Do not confuse this field with :c:member:`~PyTypeObject.tp_weaklist`; that is the list head for
weak references to the type object itself. weak references to the type object itself.
@ -1436,9 +1436,9 @@ and :c:type:`PyType_Type` effectively act as defaults.)
PyObject *tp_iternext(PyObject *self); PyObject *tp_iternext(PyObject *self);
When the iterator is exhausted, it must return *NULL*; a :exc:`StopIteration` When the iterator is exhausted, it must return ``NULL``; a :exc:`StopIteration`
exception may or may not be set. When another error occurs, it must return exception may or may not be set. When another error occurs, it must return
*NULL* too. Its presence signals that the instances of this type are ``NULL`` too. Its presence signals that the instances of this type are
iterators. iterators.
Iterator types should also define the :c:member:`~PyTypeObject.tp_iter` function, and that Iterator types should also define the :c:member:`~PyTypeObject.tp_iter` function, and that
@ -1454,7 +1454,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
.. c:member:: struct PyMethodDef* PyTypeObject.tp_methods .. c:member:: struct PyMethodDef* PyTypeObject.tp_methods
An optional pointer to a static *NULL*-terminated array of :c:type:`PyMethodDef` An optional pointer to a static ``NULL``-terminated array of :c:type:`PyMethodDef`
structures, declaring regular methods of this type. structures, declaring regular methods of this type.
For each entry in the array, an entry is added to the type's dictionary (see For each entry in the array, an entry is added to the type's dictionary (see
@ -1468,7 +1468,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
.. c:member:: struct PyMemberDef* PyTypeObject.tp_members .. c:member:: struct PyMemberDef* PyTypeObject.tp_members
An optional pointer to a static *NULL*-terminated array of :c:type:`PyMemberDef` An optional pointer to a static ``NULL``-terminated array of :c:type:`PyMemberDef`
structures, declaring regular data members (fields or slots) of instances of structures, declaring regular data members (fields or slots) of instances of
this type. this type.
@ -1483,7 +1483,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
.. c:member:: struct PyGetSetDef* PyTypeObject.tp_getset .. c:member:: struct PyGetSetDef* PyTypeObject.tp_getset
An optional pointer to a static *NULL*-terminated array of :c:type:`PyGetSetDef` An optional pointer to a static ``NULL``-terminated array of :c:type:`PyGetSetDef`
structures, declaring computed attributes of instances of this type. structures, declaring computed attributes of instances of this type.
For each entry in the array, an entry is added to the type's dictionary (see For each entry in the array, an entry is added to the type's dictionary (see
@ -1533,7 +1533,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
The type's dictionary is stored here by :c:func:`PyType_Ready`. The type's dictionary is stored here by :c:func:`PyType_Ready`.
This field should normally be initialized to *NULL* before PyType_Ready is This field should normally be initialized to ``NULL`` before PyType_Ready is
called; it may also be initialized to a dictionary containing initial attributes called; it may also be initialized to a dictionary containing initial attributes
for the type. Once :c:func:`PyType_Ready` has initialized the type, extra for the type. Once :c:func:`PyType_Ready` has initialized the type, extra
attributes for the type may be added to this dictionary only if they don't attributes for the type may be added to this dictionary only if they don't
@ -1546,7 +1546,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
**Default:** **Default:**
If this field is *NULL*, :c:func:`PyType_Ready` will assign a new If this field is ``NULL``, :c:func:`PyType_Ready` will assign a new
dictionary to it. dictionary to it.
.. warning:: .. warning::
@ -1579,7 +1579,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
int tp_descr_set(PyObject *self, PyObject *obj, PyObject *value); int tp_descr_set(PyObject *self, PyObject *obj, PyObject *value);
The *value* argument is set to *NULL* to delete the value. The *value* argument is set to ``NULL`` to delete the value.
.. XXX explain more? .. XXX explain more?
@ -1645,7 +1645,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
**Default:** **Default:**
This slot has no default. For static types, if the field is This slot has no default. For static types, if the field is
*NULL* then no :attr:`__dict__` gets created for instances. ``NULL`` then no :attr:`__dict__` gets created for instances.
.. c:member:: initproc PyTypeObject.tp_init .. c:member:: initproc PyTypeObject.tp_init
@ -1665,7 +1665,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
arguments represent positional and keyword arguments of the call to arguments represent positional and keyword arguments of the call to
:meth:`__init__`. :meth:`__init__`.
The :c:member:`~PyTypeObject.tp_init` function, if not *NULL*, is called when an instance is The :c:member:`~PyTypeObject.tp_init` function, if not ``NULL``, is called when an instance is
created normally by calling its type, after the type's :c:member:`~PyTypeObject.tp_new` function created normally by calling its type, after the type's :c:member:`~PyTypeObject.tp_new` function
has returned an instance of the type. If the :c:member:`~PyTypeObject.tp_new` function returns an has returned an instance of the type. If the :c:member:`~PyTypeObject.tp_new` function returns an
instance of some other type that is not a subtype of the original type, no instance of some other type that is not a subtype of the original type, no
@ -1732,12 +1732,12 @@ and :c:type:`PyType_Type` effectively act as defaults.)
**Inheritance:** **Inheritance:**
This field is inherited by subtypes, except it is not inherited by static types This field is inherited by subtypes, except it is not inherited by static types
whose :c:member:`~PyTypeObject.tp_base` is *NULL* or ``&PyBaseObject_Type``. whose :c:member:`~PyTypeObject.tp_base` is ``NULL`` or ``&PyBaseObject_Type``.
**Default:** **Default:**
For static types this field has no default. This means if the For static types this field has no default. This means if the
slot is defined as *NULL*, the type cannot be called to create new slot is defined as ``NULL``, the type cannot be called to create new
instances; presumably there is some other way to create instances; presumably there is some other way to create
instances, like a factory function. instances, like a factory function.
@ -1788,7 +1788,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
**Default:** **Default:**
This slot has no default. If this field is *NULL*, This slot has no default. If this field is ``NULL``,
:const:`Py_TPFLAGS_HAVE_GC` is used as the functional equivalent. :const:`Py_TPFLAGS_HAVE_GC` is used as the functional equivalent.
@ -1796,7 +1796,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
Tuple of base types. Tuple of base types.
This is set for types created by a class statement. It should be *NULL* for This is set for types created by a class statement. It should be ``NULL`` for
statically defined types. statically defined types.
**Inheritance:** **Inheritance:**
@ -2034,12 +2034,12 @@ Number Object Structures
and implement the necessary conversions (at least one of the operands is and implement the necessary conversions (at least one of the operands is
an instance of the defined type). If the operation is not defined for the an instance of the defined type). If the operation is not defined for the
given operands, binary and ternary functions must return given operands, binary and ternary functions must return
``Py_NotImplemented``, if another error occurred they must return *NULL* ``Py_NotImplemented``, if another error occurred they must return ``NULL``
and set an exception. and set an exception.
.. note:: .. note::
The :c:data:`nb_reserved` field should always be *NULL*. It The :c:data:`nb_reserved` field should always be ``NULL``. It
was previously called :c:data:`nb_long`, and was renamed in was previously called :c:data:`nb_long`, and was renamed in
Python 3.0.1. Python 3.0.1.
@ -2098,14 +2098,14 @@ Mapping Object Structures
This function is used by :c:func:`PyMapping_Size` and This function is used by :c:func:`PyMapping_Size` and
:c:func:`PyObject_Size`, and has the same signature. This slot may be set to :c:func:`PyObject_Size`, and has the same signature. This slot may be set to
*NULL* if the object has no defined length. ``NULL`` if the object has no defined length.
.. c:member:: binaryfunc PyMappingMethods.mp_subscript .. c:member:: binaryfunc PyMappingMethods.mp_subscript
This function is used by :c:func:`PyObject_GetItem` and This function is used by :c:func:`PyObject_GetItem` and
:c:func:`PySequence_GetSlice`, and has the same signature as :c:func:`PySequence_GetSlice`, and has the same signature as
:c:func:`!PyObject_GetItem`. This slot must be filled for the :c:func:`!PyObject_GetItem`. This slot must be filled for the
:c:func:`PyMapping_Check` function to return ``1``, it can be *NULL* :c:func:`PyMapping_Check` function to return ``1``, it can be ``NULL``
otherwise. otherwise.
.. c:member:: objobjargproc PyMappingMethods.mp_ass_subscript .. c:member:: objobjargproc PyMappingMethods.mp_ass_subscript
@ -2113,8 +2113,8 @@ Mapping Object Structures
This function is used by :c:func:`PyObject_SetItem`, This function is used by :c:func:`PyObject_SetItem`,
:c:func:`PyObject_DelItem`, :c:func:`PyObject_SetSlice` and :c:func:`PyObject_DelItem`, :c:func:`PyObject_SetSlice` and
:c:func:`PyObject_DelSlice`. It has the same signature as :c:func:`PyObject_DelSlice`. It has the same signature as
:c:func:`!PyObject_SetItem`, but *v* can also be set to *NULL* to delete :c:func:`!PyObject_SetItem`, but *v* can also be set to ``NULL`` to delete
an item. If this slot is *NULL*, the object does not support item an item. If this slot is ``NULL``, the object does not support item
assignment and deletion. assignment and deletion.
@ -2156,11 +2156,11 @@ Sequence Object Structures
signature. It is also used by :c:func:`PyObject_GetItem`, after trying signature. It is also used by :c:func:`PyObject_GetItem`, after trying
the subscription via the :c:member:`~PyMappingMethods.mp_subscript` slot. the subscription via the :c:member:`~PyMappingMethods.mp_subscript` slot.
This slot must be filled for the :c:func:`PySequence_Check` This slot must be filled for the :c:func:`PySequence_Check`
function to return ``1``, it can be *NULL* otherwise. function to return ``1``, it can be ``NULL`` otherwise.
Negative indexes are handled as follows: if the :attr:`sq_length` slot is Negative indexes are handled as follows: if the :attr:`sq_length` slot is
filled, it is called and the sequence length is used to compute a positive filled, it is called and the sequence length is used to compute a positive
index which is passed to :attr:`sq_item`. If :attr:`sq_length` is *NULL*, index which is passed to :attr:`sq_item`. If :attr:`sq_length` is ``NULL``,
the index is passed as is to the function. the index is passed as is to the function.
.. c:member:: ssizeobjargproc PySequenceMethods.sq_ass_item .. c:member:: ssizeobjargproc PySequenceMethods.sq_ass_item
@ -2169,13 +2169,13 @@ Sequence Object Structures
signature. It is also used by :c:func:`PyObject_SetItem` and signature. It is also used by :c:func:`PyObject_SetItem` and
:c:func:`PyObject_DelItem`, after trying the item assignment and deletion :c:func:`PyObject_DelItem`, after trying the item assignment and deletion
via the :c:member:`~PyMappingMethods.mp_ass_subscript` slot. via the :c:member:`~PyMappingMethods.mp_ass_subscript` slot.
This slot may be left to *NULL* if the object does not support This slot may be left to ``NULL`` if the object does not support
item assignment and deletion. item assignment and deletion.
.. c:member:: objobjproc PySequenceMethods.sq_contains .. c:member:: objobjproc PySequenceMethods.sq_contains
This function may be used by :c:func:`PySequence_Contains` and has the same This function may be used by :c:func:`PySequence_Contains` and has the same
signature. This slot may be left to *NULL*, in this case signature. This slot may be left to ``NULL``, in this case
:c:func:`!PySequence_Contains` simply traverses the sequence until it :c:func:`!PySequence_Contains` simply traverses the sequence until it
finds a match. finds a match.
@ -2183,7 +2183,7 @@ Sequence Object Structures
This function is used by :c:func:`PySequence_InPlaceConcat` and has the same This function is used by :c:func:`PySequence_InPlaceConcat` and has the same
signature. It should modify its first operand, and return it. This slot signature. It should modify its first operand, and return it. This slot
may be left to *NULL*, in this case :c:func:`!PySequence_InPlaceConcat` may be left to ``NULL``, in this case :c:func:`!PySequence_InPlaceConcat`
will fall back to :c:func:`PySequence_Concat`. It is also used by the will fall back to :c:func:`PySequence_Concat`. It is also used by the
augmented assignment ``+=``, after trying numeric in-place addition augmented assignment ``+=``, after trying numeric in-place addition
via the :c:member:`~PyNumberMethods.nb_inplace_add` slot. via the :c:member:`~PyNumberMethods.nb_inplace_add` slot.
@ -2192,7 +2192,7 @@ Sequence Object Structures
This function is used by :c:func:`PySequence_InPlaceRepeat` and has the same This function is used by :c:func:`PySequence_InPlaceRepeat` and has the same
signature. It should modify its first operand, and return it. This slot signature. It should modify its first operand, and return it. This slot
may be left to *NULL*, in this case :c:func:`!PySequence_InPlaceRepeat` may be left to ``NULL``, in this case :c:func:`!PySequence_InPlaceRepeat`
will fall back to :c:func:`PySequence_Repeat`. It is also used by the will fall back to :c:func:`PySequence_Repeat`. It is also used by the
augmented assignment ``*=``, after trying numeric in-place multiplication augmented assignment ``*=``, after trying numeric in-place multiplication
via the :c:member:`~PyNumberMethods.nb_inplace_multiply` slot. via the :c:member:`~PyNumberMethods.nb_inplace_multiply` slot.
@ -2224,7 +2224,7 @@ Buffer Object Structures
steps: steps:
(1) Check if the request can be met. If not, raise :c:data:`PyExc_BufferError`, (1) Check if the request can be met. If not, raise :c:data:`PyExc_BufferError`,
set :c:data:`view->obj` to *NULL* and return ``-1``. set :c:data:`view->obj` to ``NULL`` and return ``-1``.
(2) Fill in the requested fields. (2) Fill in the requested fields.
@ -2270,7 +2270,7 @@ Buffer Object Structures
Handle a request to release the resources of the buffer. If no resources Handle a request to release the resources of the buffer. If no resources
need to be released, :c:member:`PyBufferProcs.bf_releasebuffer` may be need to be released, :c:member:`PyBufferProcs.bf_releasebuffer` may be
*NULL*. Otherwise, a standard implementation of this function will take ``NULL``. Otherwise, a standard implementation of this function will take
these optional steps: these optional steps:
(1) Decrement an internal counter for the number of exports. (1) Decrement an internal counter for the number of exports.
@ -2324,7 +2324,7 @@ Async Object Structures
The returned object must be an iterator, i.e. :c:func:`PyIter_Check` must The returned object must be an iterator, i.e. :c:func:`PyIter_Check` must
return ``1`` for it. return ``1`` for it.
This slot may be set to *NULL* if an object is not an :term:`awaitable`. This slot may be set to ``NULL`` if an object is not an :term:`awaitable`.
.. c:member:: unaryfunc PyAsyncMethods.am_aiter .. c:member:: unaryfunc PyAsyncMethods.am_aiter
@ -2334,7 +2334,7 @@ Async Object Structures
Must return an :term:`awaitable` object. See :meth:`__anext__` for details. Must return an :term:`awaitable` object. See :meth:`__anext__` for details.
This slot may be set to *NULL* if an object does not implement This slot may be set to ``NULL`` if an object does not implement
asynchronous iteration protocol. asynchronous iteration protocol.
.. c:member:: unaryfunc PyAsyncMethods.am_anext .. c:member:: unaryfunc PyAsyncMethods.am_anext
@ -2344,7 +2344,7 @@ Async Object Structures
PyObject *am_anext(PyObject *self); PyObject *am_anext(PyObject *self);
Must return an :term:`awaitable` object. See :meth:`__anext__` for details. Must return an :term:`awaitable` object. See :meth:`__anext__` for details.
This slot may be set to *NULL*. This slot may be set to ``NULL``.
.. _slot-typedefs: .. _slot-typedefs:
@ -2400,7 +2400,7 @@ Slot Type typedefs
.. c:type:: int (*setattrfunc)(PyObject *self, char *attr, PyObject *value) .. c:type:: int (*setattrfunc)(PyObject *self, char *attr, PyObject *value)
Set the value of the named attribute for the object. Set the value of the named attribute for the object.
The value argument is set to *NULL* to delete the attribute. The value argument is set to ``NULL`` to delete the attribute.
.. c:type:: PyObject *(*getattrofunc)(PyObject *self, PyObject *attr) .. c:type:: PyObject *(*getattrofunc)(PyObject *self, PyObject *attr)
@ -2411,7 +2411,7 @@ Slot Type typedefs
.. c:type:: int (*setattrofunc)(PyObject *self, PyObject *attr, PyObject *value) .. c:type:: int (*setattrofunc)(PyObject *self, PyObject *attr, PyObject *value)
Set the value of the named attribute for the object. Set the value of the named attribute for the object.
The value argument is set to *NULL* to delete the attribute. The value argument is set to ``NULL`` to delete the attribute.
See :c:member:`~PyTypeObject.tp_setattro`. See :c:member:`~PyTypeObject.tp_setattro`.

310
Doc/c-api/unicode.rst
View File

@ -236,7 +236,7 @@ access internal read-only data of Unicode objects:
.. versionchanged:: 3.3 .. versionchanged:: 3.3
This macro is now inefficient -- because in many cases the This macro is now inefficient -- because in many cases the
:c:type:`Py_UNICODE` representation does not exist and needs to be created :c:type:`Py_UNICODE` representation does not exist and needs to be created
-- and can fail (return *NULL* with an exception set). Try to port the -- and can fail (return ``NULL`` with an exception set). Try to port the
code to use the new :c:func:`PyUnicode_nBYTE_DATA` macros or use code to use the new :c:func:`PyUnicode_nBYTE_DATA` macros or use
:c:func:`PyUnicode_WRITE` or :c:func:`PyUnicode_READ`. :c:func:`PyUnicode_WRITE` or :c:func:`PyUnicode_READ`.
@ -413,11 +413,11 @@ APIs:
Create a Unicode object from the char buffer *u*. The bytes will be Create a Unicode object from the char buffer *u*. The bytes will be
interpreted as being UTF-8 encoded. The buffer is copied into the new interpreted as being UTF-8 encoded. The buffer is copied into the new
object. If the buffer is not *NULL*, the return value might be a shared object. If the buffer is not ``NULL``, the return value might be a shared
object, i.e. modification of the data is not allowed. object, i.e. modification of the data is not allowed.
If *u* is *NULL*, this function behaves like :c:func:`PyUnicode_FromUnicode` If *u* is ``NULL``, this function behaves like :c:func:`PyUnicode_FromUnicode`
with the buffer set to *NULL*. This usage is deprecated in favor of with the buffer set to ``NULL``. This usage is deprecated in favor of
:c:func:`PyUnicode_New`. :c:func:`PyUnicode_New`.
@ -443,82 +443,82 @@ APIs:
.. tabularcolumns:: |l|l|L| .. tabularcolumns:: |l|l|L|
+-------------------+---------------------+--------------------------------+ +-------------------+---------------------+----------------------------------+
| Format Characters | Type | Comment | | Format Characters | Type | Comment |
+===================+=====================+================================+ +===================+=====================+==================================+
| :attr:`%%` | *n/a* | The literal % character. | | :attr:`%%` | *n/a* | The literal % character. |
+-------------------+---------------------+--------------------------------+ +-------------------+---------------------+----------------------------------+
| :attr:`%c` | int | A single character, | | :attr:`%c` | int | A single character, |
| | | represented as a C int. | | | | represented as a C int. |
+-------------------+---------------------+--------------------------------+ +-------------------+---------------------+----------------------------------+
| :attr:`%d` | int | Equivalent to | | :attr:`%d` | int | Equivalent to |
| | | ``printf("%d")``. [1]_ | | | | ``printf("%d")``. [1]_ |
+-------------------+---------------------+--------------------------------+ +-------------------+---------------------+----------------------------------+
| :attr:`%u` | unsigned int | Equivalent to | | :attr:`%u` | unsigned int | Equivalent to |
| | | ``printf("%u")``. [1]_ | | | | ``printf("%u")``. [1]_ |
+-------------------+---------------------+--------------------------------+ +-------------------+---------------------+----------------------------------+
| :attr:`%ld` | long | Equivalent to | | :attr:`%ld` | long | Equivalent to |
| | | ``printf("%ld")``. [1]_ | | | | ``printf("%ld")``. [1]_ |
+-------------------+---------------------+--------------------------------+ +-------------------+---------------------+----------------------------------+
| :attr:`%li` | long | Equivalent to | | :attr:`%li` | long | Equivalent to |
| | | ``printf("%li")``. [1]_ | | | | ``printf("%li")``. [1]_ |
+-------------------+---------------------+--------------------------------+ +-------------------+---------------------+----------------------------------+
| :attr:`%lu` | unsigned long | Equivalent to | | :attr:`%lu` | unsigned long | Equivalent to |
| | | ``printf("%lu")``. [1]_ | | | | ``printf("%lu")``. [1]_ |
+-------------------+---------------------+--------------------------------+ +-------------------+---------------------+----------------------------------+
| :attr:`%lld` | long long | Equivalent to | | :attr:`%lld` | long long | Equivalent to |
| | | ``printf("%lld")``. [1]_ | | | | ``printf("%lld")``. [1]_ |
+-------------------+---------------------+--------------------------------+ +-------------------+---------------------+----------------------------------+
| :attr:`%lli` | long long | Equivalent to | | :attr:`%lli` | long long | Equivalent to |
| | | ``printf("%lli")``. [1]_ | | | | ``printf("%lli")``. [1]_ |
+-------------------+---------------------+--------------------------------+ +-------------------+---------------------+----------------------------------+
| :attr:`%llu` | unsigned long long | Equivalent to | | :attr:`%llu` | unsigned long long | Equivalent to |
| | | ``printf("%llu")``. [1]_ | | | | ``printf("%llu")``. [1]_ |
+-------------------+---------------------+--------------------------------+ +-------------------+---------------------+----------------------------------+
| :attr:`%zd` | Py_ssize_t | Equivalent to | | :attr:`%zd` | Py_ssize_t | Equivalent to |
| | | ``printf("%zd")``. [1]_ | | | | ``printf("%zd")``. [1]_ |
+-------------------+---------------------+--------------------------------+ +-------------------+---------------------+----------------------------------+
| :attr:`%zi` | Py_ssize_t | Equivalent to | | :attr:`%zi` | Py_ssize_t | Equivalent to |
| | | ``printf("%zi")``. [1]_ | | | | ``printf("%zi")``. [1]_ |
+-------------------+---------------------+--------------------------------+ +-------------------+---------------------+----------------------------------+
| :attr:`%zu` | size_t | Equivalent to | | :attr:`%zu` | size_t | Equivalent to |
| | | ``printf("%zu")``. [1]_ | | | | ``printf("%zu")``. [1]_ |
+-------------------+---------------------+--------------------------------+ +-------------------+---------------------+----------------------------------+
| :attr:`%i` | int | Equivalent to | | :attr:`%i` | int | Equivalent to |
| | | ``printf("%i")``. [1]_ | | | | ``printf("%i")``. [1]_ |
+-------------------+---------------------+--------------------------------+ +-------------------+---------------------+----------------------------------+
| :attr:`%x` | int | Equivalent to | | :attr:`%x` | int | Equivalent to |
| | | ``printf("%x")``. [1]_ | | | | ``printf("%x")``. [1]_ |
+-------------------+---------------------+--------------------------------+ +-------------------+---------------------+----------------------------------+
| :attr:`%s` | const char\* | A null-terminated C character | | :attr:`%s` | const char\* | A null-terminated C character |
| | | array. | | | | array. |
+-------------------+---------------------+--------------------------------+ +-------------------+---------------------+----------------------------------+
| :attr:`%p` | const void\* | The hex representation of a C | | :attr:`%p` | const void\* | The hex representation of a C |
| | | pointer. Mostly equivalent to | | | | pointer. Mostly equivalent to |
| | | ``printf("%p")`` except that | | | | ``printf("%p")`` except that |
| | | it is guaranteed to start with | | | | it is guaranteed to start with |
| | | the literal ``0x`` regardless | | | | the literal ``0x`` regardless |
| | | of what the platform's | | | | of what the platform's |
| | | ``printf`` yields. | | | | ``printf`` yields. |
+-------------------+---------------------+--------------------------------+ +-------------------+---------------------+----------------------------------+
| :attr:`%A` | PyObject\* | The result of calling | | :attr:`%A` | PyObject\* | The result of calling |
| | | :func:`ascii`. | | | | :func:`ascii`. |
+-------------------+---------------------+--------------------------------+ +-------------------+---------------------+----------------------------------+
| :attr:`%U` | PyObject\* | A Unicode object. | | :attr:`%U` | PyObject\* | A Unicode object. |
+-------------------+---------------------+--------------------------------+ +-------------------+---------------------+----------------------------------+
| :attr:`%V` | PyObject\*, | A Unicode object (which may be | | :attr:`%V` | PyObject\*, | A Unicode object (which may be |
| | const char\* | *NULL*) and a null-terminated | | | const char\* | ``NULL``) and a null-terminated |
| | | C character array as a second | | | | C character array as a second |
| | | parameter (which will be used, | | | | parameter (which will be used, |
| | | if the first parameter is | | | | if the first parameter is |
| | | *NULL*). | | | | ``NULL``). |
+-------------------+---------------------+--------------------------------+ +-------------------+---------------------+----------------------------------+
| :attr:`%S` | PyObject\* | The result of calling | | :attr:`%S` | PyObject\* | The result of calling |
| | | :c:func:`PyObject_Str`. | | | | :c:func:`PyObject_Str`. |
+-------------------+---------------------+--------------------------------+ +-------------------+---------------------+----------------------------------+
| :attr:`%R` | PyObject\* | The result of calling | | :attr:`%R` | PyObject\* | The result of calling |
| | | :c:func:`PyObject_Repr`. | | | | :c:func:`PyObject_Repr`. |
+-------------------+---------------------+--------------------------------+ +-------------------+---------------------+----------------------------------+
An unrecognized format character causes all the rest of the format string to be An unrecognized format character causes all the rest of the format string to be
copied as-is to the result string, and any extra arguments discarded. copied as-is to the result string, and any extra arguments discarded.
@ -558,13 +558,13 @@ APIs:
:class:`bytes`, :class:`bytearray` and other :class:`bytes`, :class:`bytearray` and other
:term:`bytes-like objects <bytes-like object>` :term:`bytes-like objects <bytes-like object>`
are decoded according to the given *encoding* and using the error handling are decoded according to the given *encoding* and using the error handling
defined by *errors*. Both can be *NULL* to have the interface use the default defined by *errors*. Both can be ``NULL`` to have the interface use the default
values (see :ref:`builtincodecs` for details). values (see :ref:`builtincodecs` for details).
All other objects, including Unicode objects, cause a :exc:`TypeError` to be All other objects, including Unicode objects, cause a :exc:`TypeError` to be
set. set.
The API returns *NULL* if there was an error. The caller is responsible for The API returns ``NULL`` if there was an error. The caller is responsible for
decref'ing the returned objects. decref'ing the returned objects.
@ -640,7 +640,7 @@ APIs:
Py_ssize_t buflen, int copy_null) Py_ssize_t buflen, int copy_null)
Copy the string *u* into a UCS4 buffer, including a null character, if Copy the string *u* into a UCS4 buffer, including a null character, if
*copy_null* is set. Returns *NULL* and sets an exception on error (in *copy_null* is set. Returns ``NULL`` and sets an exception on error (in
particular, a :exc:`SystemError` if *buflen* is smaller than the length of particular, a :exc:`SystemError` if *buflen* is smaller than the length of
*u*). *buffer* is returned on success. *u*). *buffer* is returned on success.
@ -650,7 +650,7 @@ APIs:
.. c:function:: Py_UCS4* PyUnicode_AsUCS4Copy(PyObject *u) .. c:function:: Py_UCS4* PyUnicode_AsUCS4Copy(PyObject *u)
Copy the string *u* into a new UCS4 buffer that is allocated using Copy the string *u* into a new UCS4 buffer that is allocated using
:c:func:`PyMem_Malloc`. If this fails, *NULL* is returned with a :c:func:`PyMem_Malloc`. If this fails, ``NULL`` is returned with a
:exc:`MemoryError` set. The returned buffer always has an extra :exc:`MemoryError` set. The returned buffer always has an extra
null code point appended. null code point appended.
@ -670,15 +670,15 @@ Extension modules can continue using them, as they will not be removed in Python
.. c:function:: PyObject* PyUnicode_FromUnicode(const Py_UNICODE *u, Py_ssize_t size) .. c:function:: PyObject* PyUnicode_FromUnicode(const Py_UNICODE *u, Py_ssize_t size)
Create a Unicode object from the Py_UNICODE buffer *u* of the given size. *u* Create a Unicode object from the Py_UNICODE buffer *u* of the given size. *u*
may be *NULL* which causes the contents to be undefined. It is the user's may be ``NULL`` which causes the contents to be undefined. It is the user's
responsibility to fill in the needed data. The buffer is copied into the new responsibility to fill in the needed data. The buffer is copied into the new
object. object.
If the buffer is not *NULL*, the return value might be a shared object. If the buffer is not ``NULL``, the return value might be a shared object.
Therefore, modification of the resulting Unicode object is only allowed when Therefore, modification of the resulting Unicode object is only allowed when
*u* is *NULL*. *u* is ``NULL``.
If the buffer is *NULL*, :c:func:`PyUnicode_READY` must be called once the If the buffer is ``NULL``, :c:func:`PyUnicode_READY` must be called once the
string content has been filled before using any of the access macros such as string content has been filled before using any of the access macros such as
:c:func:`PyUnicode_KIND`. :c:func:`PyUnicode_KIND`.
@ -689,7 +689,7 @@ Extension modules can continue using them, as they will not be removed in Python
.. c:function:: Py_UNICODE* PyUnicode_AsUnicode(PyObject *unicode) .. c:function:: Py_UNICODE* PyUnicode_AsUnicode(PyObject *unicode)
Return a read-only pointer to the Unicode object's internal Return a read-only pointer to the Unicode object's internal
:c:type:`Py_UNICODE` buffer, or *NULL* on error. This will create the :c:type:`Py_UNICODE` buffer, or ``NULL`` on error. This will create the
:c:type:`Py_UNICODE*` representation of the object if it is not yet :c:type:`Py_UNICODE*` representation of the object if it is not yet
available. The buffer is always terminated with an extra null code point. available. The buffer is always terminated with an extra null code point.
Note that the resulting :c:type:`Py_UNICODE` string may also contain Note that the resulting :c:type:`Py_UNICODE` string may also contain
@ -705,7 +705,7 @@ Extension modules can continue using them, as they will not be removed in Python
Create a Unicode object by replacing all decimal digits in Create a Unicode object by replacing all decimal digits in
:c:type:`Py_UNICODE` buffer of the given *size* by ASCII digits 0--9 :c:type:`Py_UNICODE` buffer of the given *size* by ASCII digits 0--9
according to their decimal value. Return *NULL* if an exception occurs. according to their decimal value. Return ``NULL`` if an exception occurs.
.. c:function:: Py_UNICODE* PyUnicode_AsUnicodeAndSize(PyObject *unicode, Py_ssize_t *size) .. c:function:: Py_UNICODE* PyUnicode_AsUnicodeAndSize(PyObject *unicode, Py_ssize_t *size)
@ -721,7 +721,7 @@ Extension modules can continue using them, as they will not be removed in Python
.. c:function:: Py_UNICODE* PyUnicode_AsUnicodeCopy(PyObject *unicode) .. c:function:: Py_UNICODE* PyUnicode_AsUnicodeCopy(PyObject *unicode)
Create a copy of a Unicode string ending with a null code point. Return *NULL* Create a copy of a Unicode string ending with a null code point. Return ``NULL``
and raise a :exc:`MemoryError` exception on memory allocation failure, and raise a :exc:`MemoryError` exception on memory allocation failure,
otherwise return a new allocated buffer (use :c:func:`PyMem_Free` to free otherwise return a new allocated buffer (use :c:func:`PyMem_Free` to free
the buffer). Note that the resulting :c:type:`Py_UNICODE*` string may the buffer). Note that the resulting :c:type:`Py_UNICODE*` string may
@ -932,7 +932,7 @@ wchar_t Support
Create a Unicode object from the :c:type:`wchar_t` buffer *w* of the given *size*. Create a Unicode object from the :c:type:`wchar_t` buffer *w* of the given *size*.
Passing ``-1`` as the *size* indicates that the function must itself compute the length, Passing ``-1`` as the *size* indicates that the function must itself compute the length,
using wcslen. using wcslen.
Return *NULL* on failure. Return ``NULL`` on failure.
.. c:function:: Py_ssize_t PyUnicode_AsWideChar(PyObject *unicode, wchar_t *w, Py_ssize_t size) .. c:function:: Py_ssize_t PyUnicode_AsWideChar(PyObject *unicode, wchar_t *w, Py_ssize_t size)
@ -951,22 +951,22 @@ wchar_t Support
.. c:function:: wchar_t* PyUnicode_AsWideCharString(PyObject *unicode, Py_ssize_t *size) .. c:function:: wchar_t* PyUnicode_AsWideCharString(PyObject *unicode, Py_ssize_t *size)
Convert the Unicode object to a wide character string. The output string Convert the Unicode object to a wide character string. The output string
always ends with a null character. If *size* is not *NULL*, write the number always ends with a null character. If *size* is not ``NULL``, write the number
of wide characters (excluding the trailing null termination character) into of wide characters (excluding the trailing null termination character) into
*\*size*. Note that the resulting :c:type:`wchar_t` string might contain *\*size*. Note that the resulting :c:type:`wchar_t` string might contain
null characters, which would cause the string to be truncated when used with null characters, which would cause the string to be truncated when used with
most C functions. If *size* is *NULL* and the :c:type:`wchar_t*` string most C functions. If *size* is ``NULL`` and the :c:type:`wchar_t*` string
contains null characters a :exc:`ValueError` is raised. contains null characters a :exc:`ValueError` is raised.
Returns a buffer allocated by :c:func:`PyMem_Alloc` (use Returns a buffer allocated by :c:func:`PyMem_Alloc` (use
:c:func:`PyMem_Free` to free it) on success. On error, returns *NULL* :c:func:`PyMem_Free` to free it) on success. On error, returns ``NULL``
and *\*size* is undefined. Raises a :exc:`MemoryError` if memory allocation and *\*size* is undefined. Raises a :exc:`MemoryError` if memory allocation
is failed. is failed.
.. versionadded:: 3.2 .. versionadded:: 3.2
.. versionchanged:: 3.7 .. versionchanged:: 3.7
Raises a :exc:`ValueError` if *size* is *NULL* and the :c:type:`wchar_t*` Raises a :exc:`ValueError` if *size* is ``NULL`` and the :c:type:`wchar_t*`
string contains null characters. string contains null characters.
@ -982,7 +982,7 @@ Many of the following APIs take two arguments encoding and errors, and they
have the same semantics as the ones of the built-in :func:`str` string object have the same semantics as the ones of the built-in :func:`str` string object
constructor. constructor.
Setting encoding to *NULL* causes the default encoding to be used Setting encoding to ``NULL`` causes the default encoding to be used
which is ASCII. The file system calls should use which is ASCII. The file system calls should use
:c:func:`PyUnicode_FSConverter` for encoding file names. This uses the :c:func:`PyUnicode_FSConverter` for encoding file names. This uses the
variable :c:data:`Py_FileSystemDefaultEncoding` internally. This variable :c:data:`Py_FileSystemDefaultEncoding` internally. This
@ -990,7 +990,7 @@ variable should be treated as read-only: on some systems, it will be a
pointer to a static string, on others, it will change at run-time pointer to a static string, on others, it will change at run-time
(such as when the application invokes setlocale). (such as when the application invokes setlocale).
Error handling is set by errors which may also be set to *NULL* meaning to use Error handling is set by errors which may also be set to ``NULL`` meaning to use
the default handling defined for the codec. Default error handling for all the default handling defined for the codec. Default error handling for all
built-in codecs is "strict" (:exc:`ValueError` is raised). built-in codecs is "strict" (:exc:`ValueError` is raised).
@ -1010,7 +1010,7 @@ These are the generic codec APIs:
Create a Unicode object by decoding *size* bytes of the encoded string *s*. Create a Unicode object by decoding *size* bytes of the encoded string *s*.
*encoding* and *errors* have the same meaning as the parameters of the same name *encoding* and *errors* have the same meaning as the parameters of the same name
in the :func:`str` built-in function. The codec to be used is looked up in the :func:`str` built-in function. The codec to be used is looked up
using the Python codec registry. Return *NULL* if an exception was raised by using the Python codec registry. Return ``NULL`` if an exception was raised by
the codec. the codec.
@ -1020,7 +1020,7 @@ These are the generic codec APIs:
Encode a Unicode object and return the result as Python bytes object. Encode a Unicode object and return the result as Python bytes object.
*encoding* and *errors* have the same meaning as the parameters of the same *encoding* and *errors* have the same meaning as the parameters of the same
name in the Unicode :meth:`~str.encode` method. The codec to be used is looked up name in the Unicode :meth:`~str.encode` method. The codec to be used is looked up
using the Python codec registry. Return *NULL* if an exception was raised by using the Python codec registry. Return ``NULL`` if an exception was raised by
the codec. the codec.
@ -1030,7 +1030,7 @@ These are the generic codec APIs:
Encode the :c:type:`Py_UNICODE` buffer *s* of the given *size* and return a Python Encode the :c:type:`Py_UNICODE` buffer *s* of the given *size* and return a Python
bytes object. *encoding* and *errors* have the same meaning as the bytes object. *encoding* and *errors* have the same meaning as the
parameters of the same name in the Unicode :meth:`~str.encode` method. The codec parameters of the same name in the Unicode :meth:`~str.encode` method. The codec
to be used is looked up using the Python codec registry. Return *NULL* if an to be used is looked up using the Python codec registry. Return ``NULL`` if an
exception was raised by the codec. exception was raised by the codec.
.. deprecated-removed:: 3.3 4.0 .. deprecated-removed:: 3.3 4.0
@ -1047,14 +1047,14 @@ These are the UTF-8 codec APIs:
.. c:function:: PyObject* PyUnicode_DecodeUTF8(const char *s, Py_ssize_t size, const char *errors) .. c:function:: PyObject* PyUnicode_DecodeUTF8(const char *s, Py_ssize_t size, const char *errors)
Create a Unicode object by decoding *size* bytes of the UTF-8 encoded string Create a Unicode object by decoding *size* bytes of the UTF-8 encoded string
*s*. Return *NULL* if an exception was raised by the codec. *s*. Return ``NULL`` if an exception was raised by the codec.
.. c:function:: PyObject* PyUnicode_DecodeUTF8Stateful(const char *s, Py_ssize_t size, \ .. c:function:: PyObject* PyUnicode_DecodeUTF8Stateful(const char *s, Py_ssize_t size, \
const char *errors, Py_ssize_t *consumed) const char *errors, Py_ssize_t *consumed)
If *consumed* is *NULL*, behave like :c:func:`PyUnicode_DecodeUTF8`. If If *consumed* is ``NULL``, behave like :c:func:`PyUnicode_DecodeUTF8`. If
*consumed* is not *NULL*, trailing incomplete UTF-8 byte sequences will not be *consumed* is not ``NULL``, trailing incomplete UTF-8 byte sequences will not be
treated as an error. Those bytes will not be decoded and the number of bytes treated as an error. Those bytes will not be decoded and the number of bytes
that have been decoded will be stored in *consumed*. that have been decoded will be stored in *consumed*.
@ -1062,7 +1062,7 @@ These are the UTF-8 codec APIs:
.. c:function:: PyObject* PyUnicode_AsUTF8String(PyObject *unicode) .. c:function:: PyObject* PyUnicode_AsUTF8String(PyObject *unicode)
Encode a Unicode object using UTF-8 and return the result as Python bytes Encode a Unicode object using UTF-8 and return the result as Python bytes
object. Error handling is "strict". Return *NULL* if an exception was object. Error handling is "strict". Return ``NULL`` if an exception was
raised by the codec. raised by the codec.
@ -1070,11 +1070,11 @@ These are the UTF-8 codec APIs:
Return a pointer to the UTF-8 encoding of the Unicode object, and Return a pointer to the UTF-8 encoding of the Unicode object, and
store the size of the encoded representation (in bytes) in *size*. The store the size of the encoded representation (in bytes) in *size*. The
*size* argument can be *NULL*; in this case no size will be stored. The *size* argument can be ``NULL``; in this case no size will be stored. The
returned buffer always has an extra null byte appended (not included in returned buffer always has an extra null byte appended (not included in
*size*), regardless of whether there are any other null code points. *size*), regardless of whether there are any other null code points.
In the case of an error, *NULL* is returned with an exception set and no In the case of an error, ``NULL`` is returned with an exception set and no
*size* is stored. *size* is stored.
This caches the UTF-8 representation of the string in the Unicode object, and This caches the UTF-8 representation of the string in the Unicode object, and
@ -1100,7 +1100,7 @@ These are the UTF-8 codec APIs:
.. c:function:: PyObject* PyUnicode_EncodeUTF8(const Py_UNICODE *s, Py_ssize_t size, const char *errors) .. c:function:: PyObject* PyUnicode_EncodeUTF8(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
Encode the :c:type:`Py_UNICODE` buffer *s* of the given *size* using UTF-8 and Encode the :c:type:`Py_UNICODE` buffer *s* of the given *size* using UTF-8 and
return a Python bytes object. Return *NULL* if an exception was raised by return a Python bytes object. Return ``NULL`` if an exception was raised by
the codec. the codec.
.. deprecated-removed:: 3.3 4.0 .. deprecated-removed:: 3.3 4.0
@ -1119,10 +1119,10 @@ These are the UTF-32 codec APIs:
const char *errors, int *byteorder) const char *errors, int *byteorder)
Decode *size* bytes from a UTF-32 encoded buffer string and return the Decode *size* bytes from a UTF-32 encoded buffer string and return the
corresponding Unicode object. *errors* (if non-*NULL*) defines the error corresponding Unicode object. *errors* (if non-``NULL``) defines the error
handling. It defaults to "strict". handling. It defaults to "strict".
If *byteorder* is non-*NULL*, the decoder starts decoding using the given byte If *byteorder* is non-``NULL``, the decoder starts decoding using the given byte
order:: order::
*byteorder == -1: little endian *byteorder == -1: little endian
@ -1137,16 +1137,16 @@ These are the UTF-32 codec APIs:
After completion, *\*byteorder* is set to the current byte order at the end After completion, *\*byteorder* is set to the current byte order at the end
of input data. of input data.
If *byteorder* is *NULL*, the codec starts in native order mode. If *byteorder* is ``NULL``, the codec starts in native order mode.
Return *NULL* if an exception was raised by the codec. Return ``NULL`` if an exception was raised by the codec.
.. c:function:: PyObject* PyUnicode_DecodeUTF32Stateful(const char *s, Py_ssize_t size, \ .. c:function:: PyObject* PyUnicode_DecodeUTF32Stateful(const char *s, Py_ssize_t size, \
const char *errors, int *byteorder, Py_ssize_t *consumed) const char *errors, int *byteorder, Py_ssize_t *consumed)
If *consumed* is *NULL*, behave like :c:func:`PyUnicode_DecodeUTF32`. If If *consumed* is ``NULL``, behave like :c:func:`PyUnicode_DecodeUTF32`. If
*consumed* is not *NULL*, :c:func:`PyUnicode_DecodeUTF32Stateful` will not treat *consumed* is not ``NULL``, :c:func:`PyUnicode_DecodeUTF32Stateful` will not treat
trailing incomplete UTF-32 byte sequences (such as a number of bytes not divisible trailing incomplete UTF-32 byte sequences (such as a number of bytes not divisible
by four) as an error. Those bytes will not be decoded and the number of bytes by four) as an error. Those bytes will not be decoded and the number of bytes
that have been decoded will be stored in *consumed*. that have been decoded will be stored in *consumed*.
@ -1156,7 +1156,7 @@ These are the UTF-32 codec APIs:
Return a Python byte string using the UTF-32 encoding in native byte Return a Python byte string using the UTF-32 encoding in native byte
order. The string always starts with a BOM mark. Error handling is "strict". order. The string always starts with a BOM mark. Error handling is "strict".
Return *NULL* if an exception was raised by the codec. Return ``NULL`` if an exception was raised by the codec.
.. c:function:: PyObject* PyUnicode_EncodeUTF32(const Py_UNICODE *s, Py_ssize_t size, \ .. c:function:: PyObject* PyUnicode_EncodeUTF32(const Py_UNICODE *s, Py_ssize_t size, \
@ -1175,7 +1175,7 @@ These are the UTF-32 codec APIs:
If *Py_UNICODE_WIDE* is not defined, surrogate pairs will be output If *Py_UNICODE_WIDE* is not defined, surrogate pairs will be output
as a single code point. as a single code point.
Return *NULL* if an exception was raised by the codec. Return ``NULL`` if an exception was raised by the codec.
.. deprecated-removed:: 3.3 4.0 .. deprecated-removed:: 3.3 4.0
Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using
@ -1192,10 +1192,10 @@ These are the UTF-16 codec APIs:
const char *errors, int *byteorder) const char *errors, int *byteorder)
Decode *size* bytes from a UTF-16 encoded buffer string and return the Decode *size* bytes from a UTF-16 encoded buffer string and return the
corresponding Unicode object. *errors* (if non-*NULL*) defines the error corresponding Unicode object. *errors* (if non-``NULL``) defines the error
handling. It defaults to "strict". handling. It defaults to "strict".
If *byteorder* is non-*NULL*, the decoder starts decoding using the given byte If *byteorder* is non-``NULL``, the decoder starts decoding using the given byte
order:: order::
*byteorder == -1: little endian *byteorder == -1: little endian
@ -1211,16 +1211,16 @@ These are the UTF-16 codec APIs:
After completion, *\*byteorder* is set to the current byte order at the end After completion, *\*byteorder* is set to the current byte order at the end
of input data. of input data.
If *byteorder* is *NULL*, the codec starts in native order mode. If *byteorder* is ``NULL``, the codec starts in native order mode.
Return *NULL* if an exception was raised by the codec. Return ``NULL`` if an exception was raised by the codec.
.. c:function:: PyObject* PyUnicode_DecodeUTF16Stateful(const char *s, Py_ssize_t size, \ .. c:function:: PyObject* PyUnicode_DecodeUTF16Stateful(const char *s, Py_ssize_t size, \
const char *errors, int *byteorder, Py_ssize_t *consumed) const char *errors, int *byteorder, Py_ssize_t *consumed)
If *consumed* is *NULL*, behave like :c:func:`PyUnicode_DecodeUTF16`. If If *consumed* is ``NULL``, behave like :c:func:`PyUnicode_DecodeUTF16`. If
*consumed* is not *NULL*, :c:func:`PyUnicode_DecodeUTF16Stateful` will not treat *consumed* is not ``NULL``, :c:func:`PyUnicode_DecodeUTF16Stateful` will not treat
trailing incomplete UTF-16 byte sequences (such as an odd number of bytes or a trailing incomplete UTF-16 byte sequences (such as an odd number of bytes or a
split surrogate pair) as an error. Those bytes will not be decoded and the split surrogate pair) as an error. Those bytes will not be decoded and the
number of bytes that have been decoded will be stored in *consumed*. number of bytes that have been decoded will be stored in *consumed*.
@ -1230,7 +1230,7 @@ These are the UTF-16 codec APIs:
Return a Python byte string using the UTF-16 encoding in native byte Return a Python byte string using the UTF-16 encoding in native byte
order. The string always starts with a BOM mark. Error handling is "strict". order. The string always starts with a BOM mark. Error handling is "strict".
Return *NULL* if an exception was raised by the codec. Return ``NULL`` if an exception was raised by the codec.
.. c:function:: PyObject* PyUnicode_EncodeUTF16(const Py_UNICODE *s, Py_ssize_t size, \ .. c:function:: PyObject* PyUnicode_EncodeUTF16(const Py_UNICODE *s, Py_ssize_t size, \
@ -1250,7 +1250,7 @@ These are the UTF-16 codec APIs:
represented as a surrogate pair. If it is not defined, each :c:type:`Py_UNICODE` represented as a surrogate pair. If it is not defined, each :c:type:`Py_UNICODE`
values is interpreted as a UCS-2 character. values is interpreted as a UCS-2 character.
Return *NULL* if an exception was raised by the codec. Return ``NULL`` if an exception was raised by the codec.
.. deprecated-removed:: 3.3 4.0 .. deprecated-removed:: 3.3 4.0
Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using
@ -1266,14 +1266,14 @@ These are the UTF-7 codec APIs:
.. c:function:: PyObject* PyUnicode_DecodeUTF7(const char *s, Py_ssize_t size, const char *errors) .. c:function:: PyObject* PyUnicode_DecodeUTF7(const char *s, Py_ssize_t size, const char *errors)
Create a Unicode object by decoding *size* bytes of the UTF-7 encoded string Create a Unicode object by decoding *size* bytes of the UTF-7 encoded string
*s*. Return *NULL* if an exception was raised by the codec. *s*. Return ``NULL`` if an exception was raised by the codec.
.. c:function:: PyObject* PyUnicode_DecodeUTF7Stateful(const char *s, Py_ssize_t size, \ .. c:function:: PyObject* PyUnicode_DecodeUTF7Stateful(const char *s, Py_ssize_t size, \
const char *errors, Py_ssize_t *consumed) const char *errors, Py_ssize_t *consumed)
If *consumed* is *NULL*, behave like :c:func:`PyUnicode_DecodeUTF7`. If If *consumed* is ``NULL``, behave like :c:func:`PyUnicode_DecodeUTF7`. If
*consumed* is not *NULL*, trailing incomplete UTF-7 base-64 sections will not *consumed* is not ``NULL``, trailing incomplete UTF-7 base-64 sections will not
be treated as an error. Those bytes will not be decoded and the number of be treated as an error. Those bytes will not be decoded and the number of
bytes that have been decoded will be stored in *consumed*. bytes that have been decoded will be stored in *consumed*.
@ -1282,7 +1282,7 @@ These are the UTF-7 codec APIs:
int base64SetO, int base64WhiteSpace, const char *errors) int base64SetO, int base64WhiteSpace, const char *errors)
Encode the :c:type:`Py_UNICODE` buffer of the given size using UTF-7 and Encode the :c:type:`Py_UNICODE` buffer of the given size using UTF-7 and
return a Python bytes object. Return *NULL* if an exception was raised by return a Python bytes object. Return ``NULL`` if an exception was raised by
the codec. the codec.
If *base64SetO* is nonzero, "Set O" (punctuation that has no otherwise If *base64SetO* is nonzero, "Set O" (punctuation that has no otherwise
@ -1305,20 +1305,20 @@ These are the "Unicode Escape" codec APIs:
Py_ssize_t size, const char *errors) Py_ssize_t size, const char *errors)
Create a Unicode object by decoding *size* bytes of the Unicode-Escape encoded Create a Unicode object by decoding *size* bytes of the Unicode-Escape encoded
string *s*. Return *NULL* if an exception was raised by the codec. string *s*. Return ``NULL`` if an exception was raised by the codec.
.. c:function:: PyObject* PyUnicode_AsUnicodeEscapeString(PyObject *unicode) .. c:function:: PyObject* PyUnicode_AsUnicodeEscapeString(PyObject *unicode)
Encode a Unicode object using Unicode-Escape and return the result as a Encode a Unicode object using Unicode-Escape and return the result as a
bytes object. Error handling is "strict". Return *NULL* if an exception was bytes object. Error handling is "strict". Return ``NULL`` if an exception was
raised by the codec. raised by the codec.
.. c:function:: PyObject* PyUnicode_EncodeUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size) .. c:function:: PyObject* PyUnicode_EncodeUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size)
Encode the :c:type:`Py_UNICODE` buffer of the given *size* using Unicode-Escape and Encode the :c:type:`Py_UNICODE` buffer of the given *size* using Unicode-Escape and
return a bytes object. Return *NULL* if an exception was raised by the codec. return a bytes object. Return ``NULL`` if an exception was raised by the codec.
.. deprecated-removed:: 3.3 4.0 .. deprecated-removed:: 3.3 4.0
Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using
@ -1335,13 +1335,13 @@ These are the "Raw Unicode Escape" codec APIs:
Py_ssize_t size, const char *errors) Py_ssize_t size, const char *errors)
Create a Unicode object by decoding *size* bytes of the Raw-Unicode-Escape Create a Unicode object by decoding *size* bytes of the Raw-Unicode-Escape
encoded string *s*. Return *NULL* if an exception was raised by the codec. encoded string *s*. Return ``NULL`` if an exception was raised by the codec.
.. c:function:: PyObject* PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode) .. c:function:: PyObject* PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)
Encode a Unicode object using Raw-Unicode-Escape and return the result as Encode a Unicode object using Raw-Unicode-Escape and return the result as
a bytes object. Error handling is "strict". Return *NULL* if an exception a bytes object. Error handling is "strict". Return ``NULL`` if an exception
was raised by the codec. was raised by the codec.
@ -1349,7 +1349,7 @@ These are the "Raw Unicode Escape" codec APIs:
Py_ssize_t size) Py_ssize_t size)
Encode the :c:type:`Py_UNICODE` buffer of the given *size* using Raw-Unicode-Escape Encode the :c:type:`Py_UNICODE` buffer of the given *size* using Raw-Unicode-Escape
and return a bytes object. Return *NULL* if an exception was raised by the codec. and return a bytes object. Return ``NULL`` if an exception was raised by the codec.
.. deprecated-removed:: 3.3 4.0 .. deprecated-removed:: 3.3 4.0
Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using
@ -1367,20 +1367,20 @@ ordinals and only these are accepted by the codecs during encoding.
.. c:function:: PyObject* PyUnicode_DecodeLatin1(const char *s, Py_ssize_t size, const char *errors) .. c:function:: PyObject* PyUnicode_DecodeLatin1(const char *s, Py_ssize_t size, const char *errors)
Create a Unicode object by decoding *size* bytes of the Latin-1 encoded string Create a Unicode object by decoding *size* bytes of the Latin-1 encoded string
*s*. Return *NULL* if an exception was raised by the codec. *s*. Return ``NULL`` if an exception was raised by the codec.
.. c:function:: PyObject* PyUnicode_AsLatin1String(PyObject *unicode) .. c:function:: PyObject* PyUnicode_AsLatin1String(PyObject *unicode)
Encode a Unicode object using Latin-1 and return the result as Python bytes Encode a Unicode object using Latin-1 and return the result as Python bytes
object. Error handling is "strict". Return *NULL* if an exception was object. Error handling is "strict". Return ``NULL`` if an exception was
raised by the codec. raised by the codec.
.. c:function:: PyObject* PyUnicode_EncodeLatin1(const Py_UNICODE *s, Py_ssize_t size, const char *errors) .. c:function:: PyObject* PyUnicode_EncodeLatin1(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
Encode the :c:type:`Py_UNICODE` buffer of the given *size* using Latin-1 and Encode the :c:type:`Py_UNICODE` buffer of the given *size* using Latin-1 and
return a Python bytes object. Return *NULL* if an exception was raised by return a Python bytes object. Return ``NULL`` if an exception was raised by
the codec. the codec.
.. deprecated-removed:: 3.3 4.0 .. deprecated-removed:: 3.3 4.0
@ -1399,20 +1399,20 @@ codes generate errors.
.. c:function:: PyObject* PyUnicode_DecodeASCII(const char *s, Py_ssize_t size, const char *errors) .. c:function:: PyObject* PyUnicode_DecodeASCII(const char *s, Py_ssize_t size, const char *errors)
Create a Unicode object by decoding *size* bytes of the ASCII encoded string Create a Unicode object by decoding *size* bytes of the ASCII encoded string
*s*. Return *NULL* if an exception was raised by the codec. *s*. Return ``NULL`` if an exception was raised by the codec.
.. c:function:: PyObject* PyUnicode_AsASCIIString(PyObject *unicode) .. c:function:: PyObject* PyUnicode_AsASCIIString(PyObject *unicode)
Encode a Unicode object using ASCII and return the result as Python bytes Encode a Unicode object using ASCII and return the result as Python bytes
object. Error handling is "strict". Return *NULL* if an exception was object. Error handling is "strict". Return ``NULL`` if an exception was
raised by the codec. raised by the codec.
.. c:function:: PyObject* PyUnicode_EncodeASCII(const Py_UNICODE *s, Py_ssize_t size, const char *errors) .. c:function:: PyObject* PyUnicode_EncodeASCII(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
Encode the :c:type:`Py_UNICODE` buffer of the given *size* using ASCII and Encode the :c:type:`Py_UNICODE` buffer of the given *size* using ASCII and
return a Python bytes object. Return *NULL* if an exception was raised by return a Python bytes object. Return ``NULL`` if an exception was raised by
the codec. the codec.
.. deprecated-removed:: 3.3 4.0 .. deprecated-removed:: 3.3 4.0
@ -1436,10 +1436,10 @@ These are the mapping codec APIs:
PyObject *mapping, const char *errors) PyObject *mapping, const char *errors)
Create a Unicode object by decoding *size* bytes of the encoded string *s* Create a Unicode object by decoding *size* bytes of the encoded string *s*
using the given *mapping* object. Return *NULL* if an exception was raised using the given *mapping* object. Return ``NULL`` if an exception was raised
by the codec. by the codec.
If *mapping* is *NULL*, Latin-1 decoding will be applied. Else If *mapping* is ``NULL``, Latin-1 decoding will be applied. Else
*mapping* must map bytes ordinals (integers in the range from 0 to 255) *mapping* must map bytes ordinals (integers in the range from 0 to 255)
to Unicode strings, integers (which are then interpreted as Unicode to Unicode strings, integers (which are then interpreted as Unicode
ordinals) or ``None``. Unmapped data bytes -- ones which cause a ordinals) or ``None``. Unmapped data bytes -- ones which cause a
@ -1451,7 +1451,7 @@ These are the mapping codec APIs:
.. c:function:: PyObject* PyUnicode_AsCharmapString(PyObject *unicode, PyObject *mapping) .. c:function:: PyObject* PyUnicode_AsCharmapString(PyObject *unicode, PyObject *mapping)
Encode a Unicode object using the given *mapping* object and return the Encode a Unicode object using the given *mapping* object and return the
result as a bytes object. Error handling is "strict". Return *NULL* if an result as a bytes object. Error handling is "strict". Return ``NULL`` if an
exception was raised by the codec. exception was raised by the codec.
The *mapping* object must map Unicode ordinal integers to bytes objects, The *mapping* object must map Unicode ordinal integers to bytes objects,
@ -1464,7 +1464,7 @@ These are the mapping codec APIs:
PyObject *mapping, const char *errors) PyObject *mapping, const char *errors)
Encode the :c:type:`Py_UNICODE` buffer of the given *size* using the given Encode the :c:type:`Py_UNICODE` buffer of the given *size* using the given
*mapping* object and return the result as a bytes object. Return *NULL* if *mapping* object and return the result as a bytes object. Return ``NULL`` if
an exception was raised by the codec. an exception was raised by the codec.
.. deprecated-removed:: 3.3 4.0 .. deprecated-removed:: 3.3 4.0
@ -1479,7 +1479,7 @@ The following codec API is special in that maps Unicode to Unicode.
PyObject *mapping, const char *errors) PyObject *mapping, const char *errors)
Translate a Unicode object using the given *mapping* object and return the Translate a Unicode object using the given *mapping* object and return the
resulting Unicode object. Return *NULL* if an exception was raised by the resulting Unicode object. Return ``NULL`` if an exception was raised by the
codec. codec.
The *mapping* object must map Unicode ordinal integers to Unicode strings, The *mapping* object must map Unicode ordinal integers to Unicode strings,
@ -1493,7 +1493,7 @@ The following codec API is special in that maps Unicode to Unicode.
Translate a :c:type:`Py_UNICODE` buffer of the given *size* by applying a Translate a :c:type:`Py_UNICODE` buffer of the given *size* by applying a
character *mapping* table to it and return the resulting Unicode object. character *mapping* table to it and return the resulting Unicode object.
Return *NULL* when an exception was raised by the codec. Return ``NULL`` when an exception was raised by the codec.
.. deprecated-removed:: 3.3 4.0 .. deprecated-removed:: 3.3 4.0
Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using
@ -1512,14 +1512,14 @@ the user settings on the machine running the codec.
.. c:function:: PyObject* PyUnicode_DecodeMBCS(const char *s, Py_ssize_t size, const char *errors) .. c:function:: PyObject* PyUnicode_DecodeMBCS(const char *s, Py_ssize_t size, const char *errors)
Create a Unicode object by decoding *size* bytes of the MBCS encoded string *s*. Create a Unicode object by decoding *size* bytes of the MBCS encoded string *s*.
Return *NULL* if an exception was raised by the codec. Return ``NULL`` if an exception was raised by the codec.
.. c:function:: PyObject* PyUnicode_DecodeMBCSStateful(const char *s, Py_ssize_t size, \ .. c:function:: PyObject* PyUnicode_DecodeMBCSStateful(const char *s, Py_ssize_t size, \
const char *errors, Py_ssize_t *consumed) const char *errors, Py_ssize_t *consumed)
If *consumed* is *NULL*, behave like :c:func:`PyUnicode_DecodeMBCS`. If If *consumed* is ``NULL``, behave like :c:func:`PyUnicode_DecodeMBCS`. If
*consumed* is not *NULL*, :c:func:`PyUnicode_DecodeMBCSStateful` will not decode *consumed* is not ``NULL``, :c:func:`PyUnicode_DecodeMBCSStateful` will not decode
trailing lead byte and the number of bytes that have been decoded will be stored trailing lead byte and the number of bytes that have been decoded will be stored
in *consumed*. in *consumed*.
@ -1527,14 +1527,14 @@ the user settings on the machine running the codec.
.. c:function:: PyObject* PyUnicode_AsMBCSString(PyObject *unicode) .. c:function:: PyObject* PyUnicode_AsMBCSString(PyObject *unicode)
Encode a Unicode object using MBCS and return the result as Python bytes Encode a Unicode object using MBCS and return the result as Python bytes
object. Error handling is "strict". Return *NULL* if an exception was object. Error handling is "strict". Return ``NULL`` if an exception was
raised by the codec. raised by the codec.
.. c:function:: PyObject* PyUnicode_EncodeCodePage(int code_page, PyObject *unicode, const char *errors) .. c:function:: PyObject* PyUnicode_EncodeCodePage(int code_page, PyObject *unicode, const char *errors)
Encode the Unicode object using the specified code page and return a Python Encode the Unicode object using the specified code page and return a Python
bytes object. Return *NULL* if an exception was raised by the codec. Use bytes object. Return ``NULL`` if an exception was raised by the codec. Use
:c:data:`CP_ACP` code page to get the MBCS encoder. :c:data:`CP_ACP` code page to get the MBCS encoder.
.. versionadded:: 3.3 .. versionadded:: 3.3
@ -1543,7 +1543,7 @@ the user settings on the machine running the codec.
.. c:function:: PyObject* PyUnicode_EncodeMBCS(const Py_UNICODE *s, Py_ssize_t size, const char *errors) .. c:function:: PyObject* PyUnicode_EncodeMBCS(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
Encode the :c:type:`Py_UNICODE` buffer of the given *size* using MBCS and return Encode the :c:type:`Py_UNICODE` buffer of the given *size* using MBCS and return
a Python bytes object. Return *NULL* if an exception was raised by the a Python bytes object. Return ``NULL`` if an exception was raised by the
codec. codec.
.. deprecated-removed:: 3.3 4.0 .. deprecated-removed:: 3.3 4.0
@ -1565,7 +1565,7 @@ The following APIs are capable of handling Unicode objects and strings on input
(we refer to them as strings in the descriptions) and return Unicode objects or (we refer to them as strings in the descriptions) and return Unicode objects or
integers as appropriate. integers as appropriate.
They all return *NULL* or ``-1`` if an exception occurs. They all return ``NULL`` or ``-1`` if an exception occurs.
.. c:function:: PyObject* PyUnicode_Concat(PyObject *left, PyObject *right) .. c:function:: PyObject* PyUnicode_Concat(PyObject *left, PyObject *right)
@ -1575,7 +1575,7 @@ They all return *NULL* or ``-1`` if an exception occurs.
.. c:function:: PyObject* PyUnicode_Split(PyObject *s, PyObject *sep, Py_ssize_t maxsplit) .. c:function:: PyObject* PyUnicode_Split(PyObject *s, PyObject *sep, Py_ssize_t maxsplit)
Split a string giving a list of Unicode strings. If *sep* is *NULL*, splitting Split a string giving a list of Unicode strings. If *sep* is ``NULL``, splitting
will be done at all whitespace substrings. Otherwise, splits occur at the given will be done at all whitespace substrings. Otherwise, splits occur at the given
separator. At most *maxsplit* splits will be done. If negative, no limit is separator. At most *maxsplit* splits will be done. If negative, no limit is
set. Separators are not included in the resulting list. set. Separators are not included in the resulting list.
@ -1601,7 +1601,7 @@ They all return *NULL* or ``-1`` if an exception occurs.
and sequences work well. Unmapped character ordinals (ones which cause a and sequences work well. Unmapped character ordinals (ones which cause a
:exc:`LookupError`) are left untouched and are copied as-is. :exc:`LookupError`) are left untouched and are copied as-is.
*errors* has the usual meaning for codecs. It may be *NULL* which indicates to *errors* has the usual meaning for codecs. It may be ``NULL`` which indicates to
use the default error handling. use the default error handling.

38
Doc/c-api/veryhigh.rst
View File

@ -52,7 +52,7 @@ the same library that the Python runtime is using.
.. c:function:: int PyRun_AnyFile(FILE *fp, const char *filename) .. c:function:: int PyRun_AnyFile(FILE *fp, const char *filename)
This is a simplified interface to :c:func:`PyRun_AnyFileExFlags` below, leaving This is a simplified interface to :c:func:`PyRun_AnyFileExFlags` below, leaving
*closeit* set to ``0`` and *flags* set to *NULL*. *closeit* set to ``0`` and *flags* set to ``NULL``.
.. c:function:: int PyRun_AnyFileFlags(FILE *fp, const char *filename, PyCompilerFlags *flags) .. c:function:: int PyRun_AnyFileFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)
@ -64,7 +64,7 @@ the same library that the Python runtime is using.
.. c:function:: int PyRun_AnyFileEx(FILE *fp, const char *filename, int closeit) .. c:function:: int PyRun_AnyFileEx(FILE *fp, const char *filename, int closeit)
This is a simplified interface to :c:func:`PyRun_AnyFileExFlags` below, leaving This is a simplified interface to :c:func:`PyRun_AnyFileExFlags` below, leaving
the *flags* argument set to *NULL*. the *flags* argument set to ``NULL``.
.. c:function:: int PyRun_AnyFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags) .. c:function:: int PyRun_AnyFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)
@ -73,7 +73,7 @@ the same library that the Python runtime is using.
terminal input or Unix pseudo-terminal), return the value of terminal input or Unix pseudo-terminal), return the value of
:c:func:`PyRun_InteractiveLoop`, otherwise return the result of :c:func:`PyRun_InteractiveLoop`, otherwise return the result of
:c:func:`PyRun_SimpleFile`. *filename* is decoded from the filesystem :c:func:`PyRun_SimpleFile`. *filename* is decoded from the filesystem
encoding (:func:`sys.getfilesystemencoding`). If *filename* is *NULL*, this encoding (:func:`sys.getfilesystemencoding`). If *filename* is ``NULL``, this
function uses ``"???"`` as the filename. function uses ``"???"`` as the filename.
@ -99,13 +99,13 @@ the same library that the Python runtime is using.
.. c:function:: int PyRun_SimpleFile(FILE *fp, const char *filename) .. c:function:: int PyRun_SimpleFile(FILE *fp, const char *filename)
This is a simplified interface to :c:func:`PyRun_SimpleFileExFlags` below, This is a simplified interface to :c:func:`PyRun_SimpleFileExFlags` below,
leaving *closeit* set to ``0`` and *flags* set to *NULL*. leaving *closeit* set to ``0`` and *flags* set to ``NULL``.
.. c:function:: int PyRun_SimpleFileEx(FILE *fp, const char *filename, int closeit) .. c:function:: int PyRun_SimpleFileEx(FILE *fp, const char *filename, int closeit)
This is a simplified interface to :c:func:`PyRun_SimpleFileExFlags` below, This is a simplified interface to :c:func:`PyRun_SimpleFileExFlags` below,
leaving *flags* set to *NULL*. leaving *flags* set to ``NULL``.
.. c:function:: int PyRun_SimpleFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags) .. c:function:: int PyRun_SimpleFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)
@ -124,7 +124,7 @@ the same library that the Python runtime is using.
.. c:function:: int PyRun_InteractiveOne(FILE *fp, const char *filename) .. c:function:: int PyRun_InteractiveOne(FILE *fp, const char *filename)
This is a simplified interface to :c:func:`PyRun_InteractiveOneFlags` below, This is a simplified interface to :c:func:`PyRun_InteractiveOneFlags` below,
leaving *flags* set to *NULL*. leaving *flags* set to ``NULL``.
.. c:function:: int PyRun_InteractiveOneFlags(FILE *fp, const char *filename, PyCompilerFlags *flags) .. c:function:: int PyRun_InteractiveOneFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)
@ -144,7 +144,7 @@ the same library that the Python runtime is using.
.. c:function:: int PyRun_InteractiveLoop(FILE *fp, const char *filename) .. c:function:: int PyRun_InteractiveLoop(FILE *fp, const char *filename)
This is a simplified interface to :c:func:`PyRun_InteractiveLoopFlags` below, This is a simplified interface to :c:func:`PyRun_InteractiveLoopFlags` below,
leaving *flags* set to *NULL*. leaving *flags* set to ``NULL``.
.. c:function:: int PyRun_InteractiveLoopFlags(FILE *fp, const char *filename, PyCompilerFlags *flags) .. c:function:: int PyRun_InteractiveLoopFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)
@ -173,13 +173,13 @@ the same library that the Python runtime is using.
``char *func(FILE *stdin, FILE *stdout, char *prompt)``, ``char *func(FILE *stdin, FILE *stdout, char *prompt)``,
overriding the default function used to read a single line of input overriding the default function used to read a single line of input
at the interpreter's prompt. The function is expected to output at the interpreter's prompt. The function is expected to output
the string *prompt* if it's not *NULL*, and then read a line of the string *prompt* if it's not ``NULL``, and then read a line of
input from the provided standard input file, returning the input from the provided standard input file, returning the
resulting string. For example, The :mod:`readline` module sets resulting string. For example, The :mod:`readline` module sets
this hook to provide line-editing and tab-completion features. this hook to provide line-editing and tab-completion features.
The result must be a string allocated by :c:func:`PyMem_RawMalloc` or The result must be a string allocated by :c:func:`PyMem_RawMalloc` or
:c:func:`PyMem_RawRealloc`, or *NULL* if an error occurred. :c:func:`PyMem_RawRealloc`, or ``NULL`` if an error occurred.
.. versionchanged:: 3.4 .. versionchanged:: 3.4
The result must be allocated by :c:func:`PyMem_RawMalloc` or The result must be allocated by :c:func:`PyMem_RawMalloc` or
@ -191,14 +191,14 @@ the same library that the Python runtime is using.
This is a simplified interface to This is a simplified interface to
:c:func:`PyParser_SimpleParseStringFlagsFilename` below, leaving *filename* set :c:func:`PyParser_SimpleParseStringFlagsFilename` below, leaving *filename* set
to *NULL* and *flags* set to ``0``. to ``NULL`` and *flags* set to ``0``.
.. c:function:: struct _node* PyParser_SimpleParseStringFlags( const char *str, int start, int flags) .. c:function:: struct _node* PyParser_SimpleParseStringFlags( const char *str, int start, int flags)
This is a simplified interface to This is a simplified interface to
:c:func:`PyParser_SimpleParseStringFlagsFilename` below, leaving *filename* set :c:func:`PyParser_SimpleParseStringFlagsFilename` below, leaving *filename* set
to *NULL*. to ``NULL``.
.. c:function:: struct _node* PyParser_SimpleParseStringFlagsFilename( const char *str, const char *filename, int start, int flags) .. c:function:: struct _node* PyParser_SimpleParseStringFlagsFilename( const char *str, const char *filename, int start, int flags)
@ -225,7 +225,7 @@ the same library that the Python runtime is using.
.. c:function:: PyObject* PyRun_String(const char *str, int start, PyObject *globals, PyObject *locals) .. c:function:: PyObject* PyRun_String(const char *str, int start, PyObject *globals, PyObject *locals)
This is a simplified interface to :c:func:`PyRun_StringFlags` below, leaving This is a simplified interface to :c:func:`PyRun_StringFlags` below, leaving
*flags* set to *NULL*. *flags* set to ``NULL``.
.. c:function:: PyObject* PyRun_StringFlags(const char *str, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags) .. c:function:: PyObject* PyRun_StringFlags(const char *str, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)
@ -236,20 +236,20 @@ the same library that the Python runtime is using.
that implements the mapping protocol. The parameter *start* specifies that implements the mapping protocol. The parameter *start* specifies
the start token that should be used to parse the source code. the start token that should be used to parse the source code.
Returns the result of executing the code as a Python object, or *NULL* if an Returns the result of executing the code as a Python object, or ``NULL`` if an
exception was raised. exception was raised.
.. c:function:: PyObject* PyRun_File(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals) .. c:function:: PyObject* PyRun_File(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals)
This is a simplified interface to :c:func:`PyRun_FileExFlags` below, leaving This is a simplified interface to :c:func:`PyRun_FileExFlags` below, leaving
*closeit* set to ``0`` and *flags* set to *NULL*. *closeit* set to ``0`` and *flags* set to ``NULL``.
.. c:function:: PyObject* PyRun_FileEx(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit) .. c:function:: PyObject* PyRun_FileEx(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit)
This is a simplified interface to :c:func:`PyRun_FileExFlags` below, leaving This is a simplified interface to :c:func:`PyRun_FileExFlags` below, leaving
*flags* set to *NULL*. *flags* set to ``NULL``.
.. c:function:: PyObject* PyRun_FileFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags) .. c:function:: PyObject* PyRun_FileFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)
@ -270,7 +270,7 @@ the same library that the Python runtime is using.
.. c:function:: PyObject* Py_CompileString(const char *str, const char *filename, int start) .. c:function:: PyObject* Py_CompileString(const char *str, const char *filename, int start)
This is a simplified interface to :c:func:`Py_CompileStringFlags` below, leaving This is a simplified interface to :c:func:`Py_CompileStringFlags` below, leaving
*flags* set to *NULL*. *flags* set to ``NULL``.
.. c:function:: PyObject* Py_CompileStringFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags) .. c:function:: PyObject* Py_CompileStringFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags)
@ -286,7 +286,7 @@ the same library that the Python runtime is using.
code which can be compiled and should be :const:`Py_eval_input`, code which can be compiled and should be :const:`Py_eval_input`,
:const:`Py_file_input`, or :const:`Py_single_input`. The filename specified by :const:`Py_file_input`, or :const:`Py_single_input`. The filename specified by
*filename* is used to construct the code object and may appear in tracebacks or *filename* is used to construct the code object and may appear in tracebacks or
:exc:`SyntaxError` exception messages. This returns *NULL* if the code :exc:`SyntaxError` exception messages. This returns ``NULL`` if the code
cannot be parsed or compiled. cannot be parsed or compiled.
The integer *optimize* specifies the optimization level of the compiler; a The integer *optimize* specifies the optimization level of the compiler; a
@ -309,7 +309,7 @@ the same library that the Python runtime is using.
This is a simplified interface to :c:func:`PyEval_EvalCodeEx`, with just This is a simplified interface to :c:func:`PyEval_EvalCodeEx`, with just
the code object, and global and local variables. The other arguments are the code object, and global and local variables. The other arguments are
set to *NULL*. set to ``NULL``.
.. c:function:: PyObject* PyEval_EvalCodeEx(PyObject *co, PyObject *globals, PyObject *locals, PyObject *const *args, int argcount, PyObject *const *kws, int kwcount, PyObject *const *defs, int defcount, PyObject *kwdefs, PyObject *closure) .. c:function:: PyObject* PyEval_EvalCodeEx(PyObject *co, PyObject *globals, PyObject *locals, PyObject *const *args, int argcount, PyObject *const *kws, int kwcount, PyObject *const *defs, int defcount, PyObject *kwdefs, PyObject *closure)
@ -386,7 +386,7 @@ the same library that the Python runtime is using.
executed, it is passed as ``PyCompilerFlags *flags``. In this case, ``from executed, it is passed as ``PyCompilerFlags *flags``. In this case, ``from
__future__ import`` can modify *flags*. __future__ import`` can modify *flags*.
Whenever ``PyCompilerFlags *flags`` is *NULL*, :attr:`cf_flags` is treated as Whenever ``PyCompilerFlags *flags`` is ``NULL``, :attr:`cf_flags` is treated as
equal to ``0``, and any modification due to ``from __future__ import`` is equal to ``0``, and any modification due to ``from __future__ import`` is
discarded. discarded.

8
Doc/c-api/weakref.rst
View File

@ -33,9 +33,9 @@ as much as it can.
reference object may be returned. The second parameter, *callback*, can be a reference object may be returned. The second parameter, *callback*, can be a
callable object that receives notification when *ob* is garbage collected; it callable object that receives notification when *ob* is garbage collected; it
should accept a single parameter, which will be the weak reference object should accept a single parameter, which will be the weak reference object
itself. *callback* may also be ``None`` or *NULL*. If *ob* is not a itself. *callback* may also be ``None`` or ``NULL``. If *ob* is not a
weakly-referencable object, or if *callback* is not callable, ``None``, or weakly-referencable object, or if *callback* is not callable, ``None``, or
*NULL*, this will return *NULL* and raise :exc:`TypeError`. ``NULL``, this will return ``NULL`` and raise :exc:`TypeError`.
.. c:function:: PyObject* PyWeakref_NewProxy(PyObject *ob, PyObject *callback) .. c:function:: PyObject* PyWeakref_NewProxy(PyObject *ob, PyObject *callback)
@ -45,9 +45,9 @@ as much as it can.
existing proxy object may be returned. The second parameter, *callback*, can existing proxy object may be returned. The second parameter, *callback*, can
be a callable object that receives notification when *ob* is garbage be a callable object that receives notification when *ob* is garbage
collected; it should accept a single parameter, which will be the weak collected; it should accept a single parameter, which will be the weak
reference object itself. *callback* may also be ``None`` or *NULL*. If *ob* reference object itself. *callback* may also be ``None`` or ``NULL``. If *ob*
is not a weakly-referencable object, or if *callback* is not callable, is not a weakly-referencable object, or if *callback* is not callable,
``None``, or *NULL*, this will return *NULL* and raise :exc:`TypeError`. ``None``, or ``NULL``, this will return ``NULL`` and raise :exc:`TypeError`.
.. c:function:: PyObject* PyWeakref_GetObject(PyObject *ref) .. c:function:: PyObject* PyWeakref_GetObject(PyObject *ref)

2
Doc/extending/embedding.rst
View File

@ -196,7 +196,7 @@ function is then made with::
pValue = PyObject_CallObject(pFunc, pArgs); pValue = PyObject_CallObject(pFunc, pArgs);
Upon return of the function, ``pValue`` is either *NULL* or it contains a Upon return of the function, ``pValue`` is either ``NULL`` or it contains a
reference to the return value of the function. Be sure to release the reference reference to the return value of the function. Be sure to release the reference
after examining the value. after examining the value.

50
Doc/extending/extending.rst
View File

@ -117,7 +117,7 @@ store the converted values. More about this later.
type and its components have been stored in the variables whose addresses are type and its components have been stored in the variables whose addresses are
passed. It returns false (zero) if an invalid argument list was passed. In the passed. It returns false (zero) if an invalid argument list was passed. In the
latter case it also raises an appropriate exception so the calling function can latter case it also raises an appropriate exception so the calling function can
return *NULL* immediately (as we saw in the example). return ``NULL`` immediately (as we saw in the example).
.. _extending-errors: .. _extending-errors:
@ -127,8 +127,8 @@ Intermezzo: Errors and Exceptions
An important convention throughout the Python interpreter is the following: when An important convention throughout the Python interpreter is the following: when
a function fails, it should set an exception condition and return an error value a function fails, it should set an exception condition and return an error value
(usually a *NULL* pointer). Exceptions are stored in a static global variable (usually a ``NULL`` pointer). Exceptions are stored in a static global variable
inside the interpreter; if this variable is *NULL* no exception has occurred. A inside the interpreter; if this variable is ``NULL`` no exception has occurred. A
second global variable stores the "associated value" of the exception (the second global variable stores the "associated value" of the exception (the
second argument to :keyword:`raise`). A third variable contains the stack second argument to :keyword:`raise`). A third variable contains the stack
traceback in case the error originated in Python code. These three variables traceback in case the error originated in Python code. These three variables
@ -152,13 +152,13 @@ its associated value. You don't need to :c:func:`Py_INCREF` the objects passed
to any of these functions. to any of these functions.
You can test non-destructively whether an exception has been set with You can test non-destructively whether an exception has been set with
:c:func:`PyErr_Occurred`. This returns the current exception object, or *NULL* :c:func:`PyErr_Occurred`. This returns the current exception object, or ``NULL``
if no exception has occurred. You normally don't need to call if no exception has occurred. You normally don't need to call
:c:func:`PyErr_Occurred` to see whether an error occurred in a function call, :c:func:`PyErr_Occurred` to see whether an error occurred in a function call,
since you should be able to tell from the return value. since you should be able to tell from the return value.
When a function *f* that calls another function *g* detects that the latter When a function *f* that calls another function *g* detects that the latter
fails, *f* should itself return an error value (usually *NULL* or ``-1``). It fails, *f* should itself return an error value (usually ``NULL`` or ``-1``). It
should *not* call one of the :c:func:`PyErr_\*` functions --- one has already should *not* call one of the :c:func:`PyErr_\*` functions --- one has already
been called by *g*. *f*'s caller is then supposed to also return an error been called by *g*. *f*'s caller is then supposed to also return an error
indication to *its* caller, again *without* calling :c:func:`PyErr_\*`, and so on indication to *its* caller, again *without* calling :c:func:`PyErr_\*`, and so on
@ -234,7 +234,7 @@ with an exception object::
Note that the Python name for the exception object is :exc:`spam.error`. The Note that the Python name for the exception object is :exc:`spam.error`. The
:c:func:`PyErr_NewException` function may create a class with the base class :c:func:`PyErr_NewException` function may create a class with the base class
being :exc:`Exception` (unless another class is passed in instead of *NULL*), being :exc:`Exception` (unless another class is passed in instead of ``NULL``),
described in :ref:`bltin-exceptions`. described in :ref:`bltin-exceptions`.
Note also that the :c:data:`SpamError` variable retains a reference to the newly Note also that the :c:data:`SpamError` variable retains a reference to the newly
@ -278,7 +278,7 @@ statement::
if (!PyArg_ParseTuple(args, "s", &command)) if (!PyArg_ParseTuple(args, "s", &command))
return NULL; return NULL;
It returns *NULL* (the error indicator for functions returning object pointers) It returns ``NULL`` (the error indicator for functions returning object pointers)
if an error is detected in the argument list, relying on the exception set by if an error is detected in the argument list, relying on the exception set by
:c:func:`PyArg_ParseTuple`. Otherwise the string value of the argument has been :c:func:`PyArg_ParseTuple`. Otherwise the string value of the argument has been
copied to the local variable :c:data:`command`. This is a pointer assignment and copied to the local variable :c:data:`command`. This is a pointer assignment and
@ -308,7 +308,7 @@ macro)::
return Py_None; return Py_None;
:c:data:`Py_None` is the C name for the special Python object ``None``. It is a :c:data:`Py_None` is the C name for the special Python object ``None``. It is a
genuine Python object rather than a *NULL* pointer, which means "error" in most genuine Python object rather than a ``NULL`` pointer, which means "error" in most
contexts, as we have seen. contexts, as we have seen.
@ -376,7 +376,7 @@ inserts built-in function objects into the newly created module based upon the
table (an array of :c:type:`PyMethodDef` structures) found in the module definition. table (an array of :c:type:`PyMethodDef` structures) found in the module definition.
:c:func:`PyModule_Create` returns a pointer to the module object :c:func:`PyModule_Create` returns a pointer to the module object
that it creates. It may abort with a fatal error for that it creates. It may abort with a fatal error for
certain errors, or return *NULL* if the module could not be initialized certain errors, or return ``NULL`` if the module could not be initialized
satisfactorily. The init function must return the module object to its caller, satisfactorily. The init function must return the module object to its caller,
so that it then gets inserted into ``sys.modules``. so that it then gets inserted into ``sys.modules``.
@ -526,8 +526,8 @@ This function must be registered with the interpreter using the
:ref:`parsetuple`. :ref:`parsetuple`.
The macros :c:func:`Py_XINCREF` and :c:func:`Py_XDECREF` increment/decrement the The macros :c:func:`Py_XINCREF` and :c:func:`Py_XDECREF` increment/decrement the
reference count of an object and are safe in the presence of *NULL* pointers reference count of an object and are safe in the presence of ``NULL`` pointers
(but note that *temp* will not be *NULL* in this context). More info on them (but note that *temp* will not be ``NULL`` in this context). More info on them
in section :ref:`refcounts`. in section :ref:`refcounts`.
.. index:: single: PyObject_CallObject() .. index:: single: PyObject_CallObject()
@ -566,7 +566,7 @@ somehow :c:func:`Py_DECREF` the result, even (especially!) if you are not
interested in its value. interested in its value.
Before you do this, however, it is important to check that the return value Before you do this, however, it is important to check that the return value
isn't *NULL*. If it is, the Python function terminated by raising an exception. isn't ``NULL``. If it is, the Python function terminated by raising an exception.
If the C code that called :c:func:`PyObject_CallObject` is called from Python, it If the C code that called :c:func:`PyObject_CallObject` is called from Python, it
should now return an error indication to its Python caller, so the interpreter should now return an error indication to its Python caller, so the interpreter
can print a stack trace, or the calling Python code can handle the exception. can print a stack trace, or the calling Python code can handle the exception.
@ -723,7 +723,7 @@ The :c:func:`PyArg_ParseTupleAndKeywords` function is declared as follows::
The *arg* and *format* parameters are identical to those of the The *arg* and *format* parameters are identical to those of the
:c:func:`PyArg_ParseTuple` function. The *kwdict* parameter is the dictionary of :c:func:`PyArg_ParseTuple` function. The *kwdict* parameter is the dictionary of
keywords received as the third parameter from the Python runtime. The *kwlist* keywords received as the third parameter from the Python runtime. The *kwlist*
parameter is a *NULL*-terminated list of strings which identify the parameters; parameter is a ``NULL``-terminated list of strings which identify the parameters;
the names are matched with the type information from *format* from left to the names are matched with the type information from *format* from left to
right. On success, :c:func:`PyArg_ParseTupleAndKeywords` returns true, otherwise right. On success, :c:func:`PyArg_ParseTupleAndKeywords` returns true, otherwise
it returns false and raises an appropriate exception. it returns false and raises an appropriate exception.
@ -1084,32 +1084,32 @@ NULL Pointers
------------- -------------
In general, functions that take object references as arguments do not expect you In general, functions that take object references as arguments do not expect you
to pass them *NULL* pointers, and will dump core (or cause later core dumps) if to pass them ``NULL`` pointers, and will dump core (or cause later core dumps) if
you do so. Functions that return object references generally return *NULL* only you do so. Functions that return object references generally return ``NULL`` only
to indicate that an exception occurred. The reason for not testing for *NULL* to indicate that an exception occurred. The reason for not testing for ``NULL``
arguments is that functions often pass the objects they receive on to other arguments is that functions often pass the objects they receive on to other
function --- if each function were to test for *NULL*, there would be a lot of function --- if each function were to test for ``NULL``, there would be a lot of
redundant tests and the code would run more slowly. redundant tests and the code would run more slowly.
It is better to test for *NULL* only at the "source:" when a pointer that may be It is better to test for ``NULL`` only at the "source:" when a pointer that may be
*NULL* is received, for example, from :c:func:`malloc` or from a function that ``NULL`` is received, for example, from :c:func:`malloc` or from a function that
may raise an exception. may raise an exception.
The macros :c:func:`Py_INCREF` and :c:func:`Py_DECREF` do not check for *NULL* The macros :c:func:`Py_INCREF` and :c:func:`Py_DECREF` do not check for ``NULL``
pointers --- however, their variants :c:func:`Py_XINCREF` and :c:func:`Py_XDECREF` pointers --- however, their variants :c:func:`Py_XINCREF` and :c:func:`Py_XDECREF`
do. do.
The macros for checking for a particular object type (``Pytype_Check()``) don't The macros for checking for a particular object type (``Pytype_Check()``) don't
check for *NULL* pointers --- again, there is much code that calls several of check for ``NULL`` pointers --- again, there is much code that calls several of
these in a row to test an object against various different expected types, and these in a row to test an object against various different expected types, and
this would generate redundant tests. There are no variants with *NULL* this would generate redundant tests. There are no variants with ``NULL``
checking. checking.
The C function calling mechanism guarantees that the argument list passed to C The C function calling mechanism guarantees that the argument list passed to C
functions (``args`` in the examples) is never *NULL* --- in fact it guarantees functions (``args`` in the examples) is never ``NULL`` --- in fact it guarantees
that it is always a tuple [#]_. that it is always a tuple [#]_.
It is a severe error to ever let a *NULL* pointer "escape" to the Python user. It is a severe error to ever let a ``NULL`` pointer "escape" to the Python user.
.. Frank Stajano: .. Frank Stajano:
A pedagogically buggy example, along the lines of the previous listing, would A pedagogically buggy example, along the lines of the previous listing, would
@ -1184,7 +1184,7 @@ different ways between the module providing the code and the client modules.
Whichever method you choose, it's important to name your Capsules properly. Whichever method you choose, it's important to name your Capsules properly.
The function :c:func:`PyCapsule_New` takes a name parameter The function :c:func:`PyCapsule_New` takes a name parameter
(:c:type:`const char \*`); you're permitted to pass in a *NULL* name, but (:c:type:`const char \*`); you're permitted to pass in a ``NULL`` name, but
we strongly encourage you to specify a name. Properly named Capsules provide we strongly encourage you to specify a name. Properly named Capsules provide
a degree of runtime type-safety; there is no feasible way to tell one unnamed a degree of runtime type-safety; there is no feasible way to tell one unnamed
Capsule from another. Capsule from another.

36
Doc/extending/newtypes.rst
View File

@ -191,7 +191,7 @@ For every object which can support attributes, the corresponding type must
provide the functions that control how the attributes are resolved. There needs provide the functions that control how the attributes are resolved. There needs
to be a function which can retrieve attributes (if any are defined), and another to be a function which can retrieve attributes (if any are defined), and another
to set attributes (if setting attributes is allowed). Removing an attribute is to set attributes (if setting attributes is allowed). Removing an attribute is
a special case, for which the new value passed to the handler is *NULL*. a special case, for which the new value passed to the handler is ``NULL``.
Python supports two pairs of attribute handlers; a type that supports attributes Python supports two pairs of attribute handlers; a type that supports attributes
only needs to implement the functions for one pair. The difference is that one only needs to implement the functions for one pair. The difference is that one
@ -233,9 +233,9 @@ attributes, when the values are computed, or how relevant data is stored.
When :c:func:`PyType_Ready` is called, it uses three tables referenced by the When :c:func:`PyType_Ready` is called, it uses three tables referenced by the
type object to create :term:`descriptor`\s which are placed in the dictionary of the type object to create :term:`descriptor`\s which are placed in the dictionary of the
type object. Each descriptor controls access to one attribute of the instance type object. Each descriptor controls access to one attribute of the instance
object. Each of the tables is optional; if all three are *NULL*, instances of object. Each of the tables is optional; if all three are ``NULL``, instances of
the type will only have attributes that are inherited from their base type, and the type will only have attributes that are inherited from their base type, and
should leave the :c:member:`~PyTypeObject.tp_getattro` and :c:member:`~PyTypeObject.tp_setattro` fields *NULL* as should leave the :c:member:`~PyTypeObject.tp_getattro` and :c:member:`~PyTypeObject.tp_setattro` fields ``NULL`` as
well, allowing the base type to handle attributes. well, allowing the base type to handle attributes.
The tables are declared as three fields of the type object:: The tables are declared as three fields of the type object::
@ -244,7 +244,7 @@ The tables are declared as three fields of the type object::
struct PyMemberDef *tp_members; struct PyMemberDef *tp_members;
struct PyGetSetDef *tp_getset; struct PyGetSetDef *tp_getset;
If :c:member:`~PyTypeObject.tp_methods` is not *NULL*, it must refer to an array of If :c:member:`~PyTypeObject.tp_methods` is not ``NULL``, it must refer to an array of
:c:type:`PyMethodDef` structures. Each entry in the table is an instance of this :c:type:`PyMethodDef` structures. Each entry in the table is an instance of this
structure:: structure::
@ -258,7 +258,7 @@ structure::
One entry should be defined for each method provided by the type; no entries are One entry should be defined for each method provided by the type; no entries are
needed for methods inherited from a base type. One additional entry is needed needed for methods inherited from a base type. One additional entry is needed
at the end; it is a sentinel that marks the end of the array. The at the end; it is a sentinel that marks the end of the array. The
:attr:`ml_name` field of the sentinel must be *NULL*. :attr:`ml_name` field of the sentinel must be ``NULL``.
The second table is used to define attributes which map directly to data stored The second table is used to define attributes which map directly to data stored
in the instance. A variety of primitive C types are supported, and access may in the instance. A variety of primitive C types are supported, and access may
@ -307,7 +307,7 @@ application can use the introspection API to retrieve the descriptor from the
class object, and get the doc string using its :attr:`__doc__` attribute. class object, and get the doc string using its :attr:`__doc__` attribute.
As with the :c:member:`~PyTypeObject.tp_methods` table, a sentinel entry with a :attr:`name` value As with the :c:member:`~PyTypeObject.tp_methods` table, a sentinel entry with a :attr:`name` value
of *NULL* is required. of ``NULL`` is required.
.. XXX Descriptors need to be explained in more detail somewhere, but not here. .. XXX Descriptors need to be explained in more detail somewhere, but not here.
@ -352,9 +352,9 @@ Here is an example::
The :c:member:`~PyTypeObject.tp_setattr` handler is called when the :meth:`__setattr__` or The :c:member:`~PyTypeObject.tp_setattr` handler is called when the :meth:`__setattr__` or
:meth:`__delattr__` method of a class instance would be called. When an :meth:`__delattr__` method of a class instance would be called. When an
attribute should be deleted, the third parameter will be *NULL*. Here is an attribute should be deleted, the third parameter will be ``NULL``. Here is an
example that simply raises an exception; if this were really all you wanted, the example that simply raises an exception; if this were really all you wanted, the
:c:member:`~PyTypeObject.tp_setattr` handler should be set to *NULL*. :: :c:member:`~PyTypeObject.tp_setattr` handler should be set to ``NULL``. ::
static int static int
newdatatype_setattr(newdatatypeobject *obj, char *name, PyObject *v) newdatatype_setattr(newdatatypeobject *obj, char *name, PyObject *v)
@ -380,7 +380,7 @@ where the operator is one of ``Py_EQ``, ``Py_NE``, ``Py_LE``, ``Py_GT``,
``Py_LT`` or ``Py_GT``. It should compare the two objects with respect to the ``Py_LT`` or ``Py_GT``. It should compare the two objects with respect to the
specified operator and return ``Py_True`` or ``Py_False`` if the comparison is specified operator and return ``Py_True`` or ``Py_False`` if the comparison is
successful, ``Py_NotImplemented`` to indicate that comparison is not successful, ``Py_NotImplemented`` to indicate that comparison is not
implemented and the other object's comparison method should be tried, or *NULL* implemented and the other object's comparison method should be tried, or ``NULL``
if an exception was set. if an exception was set.
Here is a sample implementation, for a datatype that is considered equal if the Here is a sample implementation, for a datatype that is considered equal if the
@ -427,7 +427,7 @@ from the type implementation, the older protocols have been defined as optional
blocks of handlers referenced by the type object. For newer protocols there are blocks of handlers referenced by the type object. For newer protocols there are
additional slots in the main type object, with a flag bit being set to indicate additional slots in the main type object, with a flag bit being set to indicate
that the slots are present and should be checked by the interpreter. (The flag that the slots are present and should be checked by the interpreter. (The flag
bit does not indicate that the slot values are non-*NULL*. The flag may be set bit does not indicate that the slot values are non-``NULL``. The flag may be set
to indicate the presence of a slot, but a slot may still be unfilled.) :: to indicate the presence of a slot, but a slot may still be unfilled.) ::
PyNumberMethods *tp_as_number; PyNumberMethods *tp_as_number;
@ -478,9 +478,9 @@ This function takes three arguments:
:c:func:`PyArg_ParseTuple` to extract the arguments. :c:func:`PyArg_ParseTuple` to extract the arguments.
#. *kwds* is a dictionary of keyword arguments that were passed. If this is #. *kwds* is a dictionary of keyword arguments that were passed. If this is
non-*NULL* and you support keyword arguments, use non-``NULL`` and you support keyword arguments, use
:c:func:`PyArg_ParseTupleAndKeywords` to extract the arguments. If you :c:func:`PyArg_ParseTupleAndKeywords` to extract the arguments. If you
do not want to support keyword arguments and this is non-*NULL*, raise a do not want to support keyword arguments and this is non-``NULL``, raise a
:exc:`TypeError` with a message saying that keyword arguments are not supported. :exc:`TypeError` with a message saying that keyword arguments are not supported.
Here is a toy ``tp_call`` implementation:: Here is a toy ``tp_call`` implementation::
@ -512,7 +512,7 @@ Here is a toy ``tp_call`` implementation::
These functions provide support for the iterator protocol. Both handlers These functions provide support for the iterator protocol. Both handlers
take exactly one parameter, the instance for which they are being called, take exactly one parameter, the instance for which they are being called,
and return a new reference. In the case of an error, they should set an and return a new reference. In the case of an error, they should set an
exception and return *NULL*. :c:member:`~PyTypeObject.tp_iter` corresponds exception and return ``NULL``. :c:member:`~PyTypeObject.tp_iter` corresponds
to the Python :meth:`__iter__` method, while :c:member:`~PyTypeObject.tp_iternext` to the Python :meth:`__iter__` method, while :c:member:`~PyTypeObject.tp_iternext`
corresponds to the Python :meth:`~iterator.__next__` method. corresponds to the Python :meth:`~iterator.__next__` method.
@ -534,11 +534,11 @@ and :c:member:`~PyTypeObject.tp_iternext`. An iterator's
to the iterator. Its :c:member:`~PyTypeObject.tp_iternext` handler should to the iterator. Its :c:member:`~PyTypeObject.tp_iternext` handler should
return a new reference to the next object in the iteration, if there is one. return a new reference to the next object in the iteration, if there is one.
If the iteration has reached the end, :c:member:`~PyTypeObject.tp_iternext` If the iteration has reached the end, :c:member:`~PyTypeObject.tp_iternext`
may return *NULL* without setting an exception, or it may set may return ``NULL`` without setting an exception, or it may set
:exc:`StopIteration` *in addition* to returning *NULL*; avoiding :exc:`StopIteration` *in addition* to returning ``NULL``; avoiding
the exception can yield slightly better performance. If an actual error the exception can yield slightly better performance. If an actual error
occurs, :c:member:`~PyTypeObject.tp_iternext` should always set an exception occurs, :c:member:`~PyTypeObject.tp_iternext` should always set an exception
and return *NULL*. and return ``NULL``.
.. _weakref-support: .. _weakref-support:
@ -557,7 +557,7 @@ For an object to be weakly referencable, the extension type must do two things:
#. Include a :c:type:`PyObject\*` field in the C object structure dedicated to #. Include a :c:type:`PyObject\*` field in the C object structure dedicated to
the weak reference mechanism. The object's constructor should leave it the weak reference mechanism. The object's constructor should leave it
*NULL* (which is automatic when using the default ``NULL`` (which is automatic when using the default
:c:member:`~PyTypeObject.tp_alloc`). :c:member:`~PyTypeObject.tp_alloc`).
#. Set the :c:member:`~PyTypeObject.tp_weaklistoffset` type member #. Set the :c:member:`~PyTypeObject.tp_weaklistoffset` type member
@ -582,7 +582,7 @@ And the corresponding member in the statically-declared type object::
The only further addition is that ``tp_dealloc`` needs to clear any weak The only further addition is that ``tp_dealloc`` needs to clear any weak
references (by calling :c:func:`PyObject_ClearWeakRefs`) if the field is references (by calling :c:func:`PyObject_ClearWeakRefs`) if the field is
non-*NULL*:: non-``NULL``::
static void static void
Trivial_dealloc(TrivialObject *self) Trivial_dealloc(TrivialObject *self)

26
Doc/extending/newtypes_tutorial.rst
View File

@ -177,7 +177,7 @@ Everything else in the file should be familiar, except for some code in
This initializes the :class:`Custom` type, filling in a number of members This initializes the :class:`Custom` type, filling in a number of members
to the appropriate default values, including :attr:`ob_type` that we initially to the appropriate default values, including :attr:`ob_type` that we initially
set to *NULL*. :: set to ``NULL``. ::
Py_INCREF(&CustomType); Py_INCREF(&CustomType);
if (PyModule_AddObject(m, "Custom", (PyObject *) &CustomType) < 0) { if (PyModule_AddObject(m, "Custom", (PyObject *) &CustomType) < 0) {
@ -275,7 +275,7 @@ which is assigned to the :c:member:`~PyTypeObject.tp_dealloc` member::
This method first clears the reference counts of the two Python attributes. This method first clears the reference counts of the two Python attributes.
:c:func:`Py_XDECREF` correctly handles the case where its argument is :c:func:`Py_XDECREF` correctly handles the case where its argument is
*NULL* (which might happen here if ``tp_new`` failed midway). It then ``NULL`` (which might happen here if ``tp_new`` failed midway). It then
calls the :c:member:`~PyTypeObject.tp_free` member of the object's type calls the :c:member:`~PyTypeObject.tp_free` member of the object's type
(computed by ``Py_TYPE(self)``) to free the object's memory. Note that (computed by ``Py_TYPE(self)``) to free the object's memory. Note that
the object's type might not be :class:`CustomType`, because the object may the object's type might not be :class:`CustomType`, because the object may
@ -321,7 +321,7 @@ objects of the type. It is exposed in Python as the :meth:`__new__` method.
It is not required to define a ``tp_new`` member, and indeed many extension It is not required to define a ``tp_new`` member, and indeed many extension
types will simply reuse :c:func:`PyType_GenericNew` as done in the first types will simply reuse :c:func:`PyType_GenericNew` as done in the first
version of the ``Custom`` type above. In this case, we use the ``tp_new`` version of the ``Custom`` type above. In this case, we use the ``tp_new``
handler to initialize the ``first`` and ``last`` attributes to non-*NULL* handler to initialize the ``first`` and ``last`` attributes to non-``NULL``
default values. default values.
``tp_new`` is passed the type being instantiated (not necessarily ``CustomType``, ``tp_new`` is passed the type being instantiated (not necessarily ``CustomType``,
@ -341,7 +341,7 @@ slot to allocate memory::
self = (CustomObject *) type->tp_alloc(type, 0); self = (CustomObject *) type->tp_alloc(type, 0);
Since memory allocation may fail, we must check the :c:member:`~PyTypeObject.tp_alloc` Since memory allocation may fail, we must check the :c:member:`~PyTypeObject.tp_alloc`
result against *NULL* before proceeding. result against ``NULL`` before proceeding.
.. note:: .. note::
We didn't fill the :c:member:`~PyTypeObject.tp_alloc` slot ourselves. Rather We didn't fill the :c:member:`~PyTypeObject.tp_alloc` slot ourselves. Rather
@ -455,9 +455,9 @@ below for details.
A disadvantage of this approach is that it doesn't provide a way to restrict the A disadvantage of this approach is that it doesn't provide a way to restrict the
types of objects that can be assigned to the Python attributes. We expect the types of objects that can be assigned to the Python attributes. We expect the
first and last names to be strings, but any Python objects can be assigned. first and last names to be strings, but any Python objects can be assigned.
Further, the attributes can be deleted, setting the C pointers to *NULL*. Even Further, the attributes can be deleted, setting the C pointers to ``NULL``. Even
though we can make sure the members are initialized to non-*NULL* values, the though we can make sure the members are initialized to non-``NULL`` values, the
members can be set to *NULL* if the attributes are deleted. members can be set to ``NULL`` if the attributes are deleted.
We define a single method, :meth:`Custom.name()`, that outputs the objects name as the We define a single method, :meth:`Custom.name()`, that outputs the objects name as the
concatenation of the first and last names. :: concatenation of the first and last names. ::
@ -489,8 +489,8 @@ equivalent to the Python method:
return "%s %s" % (self.first, self.last) return "%s %s" % (self.first, self.last)
Note that we have to check for the possibility that our :attr:`first` and Note that we have to check for the possibility that our :attr:`first` and
:attr:`last` members are *NULL*. This is because they can be deleted, in which :attr:`last` members are ``NULL``. This is because they can be deleted, in which
case they are set to *NULL*. It would be better to prevent deletion of these case they are set to ``NULL``. It would be better to prevent deletion of these
attributes and to restrict the attribute values to be strings. We'll see how to attributes and to restrict the attribute values to be strings. We'll see how to
do that in the next section. do that in the next section.
@ -584,7 +584,7 @@ could, for example, be used to allow a single set of getter and setter functions
that decide the attribute to get or set based on data in the closure.) that decide the attribute to get or set based on data in the closure.)
The setter function is passed the :class:`Custom` object, the new value, and the The setter function is passed the :class:`Custom` object, the new value, and the
closure. The new value may be *NULL*, in which case the attribute is being closure. The new value may be ``NULL``, in which case the attribute is being
deleted. In our setter, we raise an error if the attribute is deleted or if its deleted. In our setter, we raise an error if the attribute is deleted or if its
new value is not a string. new value is not a string.
@ -603,7 +603,7 @@ and register it in the :c:member:`~PyTypeObject.tp_getset` slot::
.tp_getset = Custom_getsetters, .tp_getset = Custom_getsetters,
The last item in a :c:type:`PyGetSetDef` structure is the "closure" mentioned The last item in a :c:type:`PyGetSetDef` structure is the "closure" mentioned
above. In this case, we aren't using a closure, so we just pass *NULL*. above. In this case, we aren't using a closure, so we just pass ``NULL``.
We also remove the member definitions for these attributes:: We also remove the member definitions for these attributes::
@ -643,7 +643,7 @@ allow strings [#]_ to be passed::
} }
With these changes, we can assure that the ``first`` and ``last`` members are With these changes, we can assure that the ``first`` and ``last`` members are
never *NULL* so we can remove checks for *NULL* values in almost all cases. never ``NULL`` so we can remove checks for ``NULL`` values in almost all cases.
This means that most of the :c:func:`Py_XDECREF` calls can be converted to This means that most of the :c:func:`Py_XDECREF` calls can be converted to
:c:func:`Py_DECREF` calls. The only place we can't change these calls is in :c:func:`Py_DECREF` calls. The only place we can't change these calls is in
the ``tp_dealloc`` implementation, where there is the possibility that the the ``tp_dealloc`` implementation, where there is the possibility that the
@ -749,7 +749,7 @@ participate in cycles::
Notice the use of the :c:func:`Py_CLEAR` macro. It is the recommended and safe Notice the use of the :c:func:`Py_CLEAR` macro. It is the recommended and safe
way to clear data attributes of arbitrary types while decrementing way to clear data attributes of arbitrary types while decrementing
their reference counts. If you were to call :c:func:`Py_XDECREF` instead their reference counts. If you were to call :c:func:`Py_XDECREF` instead
on the attribute before setting it to *NULL*, there is a possibility on the attribute before setting it to ``NULL``, there is a possibility
that the attribute's destructor would call back into code that reads the that the attribute's destructor would call back into code that reads the
attribute again (*especially* if there is a reference cycle). attribute again (*especially* if there is a reference cycle).

2
Doc/faq/extending.rst
View File

@ -89,7 +89,7 @@ For bytes, :c:func:`PyBytes_Size` returns its length and
length. Note that Python bytes objects may contain null bytes so C's length. Note that Python bytes objects may contain null bytes so C's
:c:func:`strlen` should not be used. :c:func:`strlen` should not be used.
To test the type of an object, first make sure it isn't *NULL*, and then use To test the type of an object, first make sure it isn't ``NULL``, and then use
:c:func:`PyBytes_Check`, :c:func:`PyTuple_Check`, :c:func:`PyList_Check`, etc. :c:func:`PyBytes_Check`, :c:func:`PyTuple_Check`, :c:func:`PyList_Check`, etc.
There is also a high-level API to Python objects which is provided by the There is also a high-level API to Python objects which is provided by the

2
Doc/library/ctypes.rst
View File

@ -1083,7 +1083,7 @@ An extended example which also demonstrates the use of pointers accesses the
Quoting the docs for that value: Quoting the docs for that value:
This pointer is initialized to point to an array of :c:type:`struct _frozen` This pointer is initialized to point to an array of :c:type:`struct _frozen`
records, terminated by one whose members are all *NULL* or zero. When a frozen records, terminated by one whose members are all ``NULL`` or zero. When a frozen
module is imported, it is searched in this table. Third-party code could play module is imported, it is searched in this table. Third-party code could play
tricks with this to provide a dynamically created collection of frozen modules. tricks with this to provide a dynamically created collection of frozen modules.

2
Doc/whatsnew/3.4.rst
View File

@ -2503,7 +2503,7 @@ Changes in the C API
* The result of the :c:data:`PyOS_ReadlineFunctionPointer` callback must * The result of the :c:data:`PyOS_ReadlineFunctionPointer` callback must
now be a string allocated by :c:func:`PyMem_RawMalloc` or now be a string allocated by :c:func:`PyMem_RawMalloc` or
:c:func:`PyMem_RawRealloc`, or *NULL* if an error occurred, instead of a :c:func:`PyMem_RawRealloc`, or ``NULL`` if an error occurred, instead of a
string allocated by :c:func:`PyMem_Malloc` or :c:func:`PyMem_Realloc` string allocated by :c:func:`PyMem_Malloc` or :c:func:`PyMem_Realloc`
(:issue:`16742`) (:issue:`16742`)

2
Doc/whatsnew/3.7.rst
View File

@ -1707,7 +1707,7 @@ The type of results of :c:func:`PyThread_start_new_thread` and
(Contributed by Serhiy Storchaka in :issue:`6532`.) (Contributed by Serhiy Storchaka in :issue:`6532`.)
:c:func:`PyUnicode_AsWideCharString` now raises a :exc:`ValueError` if the :c:func:`PyUnicode_AsWideCharString` now raises a :exc:`ValueError` if the
second argument is *NULL* and the :c:type:`wchar_t*` string contains null second argument is ``NULL`` and the :c:type:`wchar_t*` string contains null
characters. (Contributed by Serhiy Storchaka in :issue:`30708`.) characters. (Contributed by Serhiy Storchaka in :issue:`30708`.)
Changes to the startup sequence and the management of dynamic memory Changes to the startup sequence and the management of dynamic memory

6
Include/abstract.h
View File

@ -150,7 +150,7 @@ PyAPI_FUNC(PyObject *) PyObject_CallNoArgs(PyObject *func);
/* Call a callable Python object 'callable' with arguments given by the /* Call a callable Python object 'callable' with arguments given by the
tuple 'args' and keywords arguments given by the dictionary 'kwargs'. tuple 'args' and keywords arguments given by the dictionary 'kwargs'.
'args' must not be *NULL*, use an empty tuple if no arguments are 'args' must not be NULL, use an empty tuple if no arguments are
needed. If no named arguments are needed, 'kwargs' can be NULL. needed. If no named arguments are needed, 'kwargs' can be NULL.
This is the equivalent of the Python expression: This is the equivalent of the Python expression:
@ -160,9 +160,9 @@ PyAPI_FUNC(PyObject *) PyObject_Call(PyObject *callable,
/* Call a callable Python object 'callable', with arguments given by the /* Call a callable Python object 'callable', with arguments given by the
tuple 'args'. If no arguments are needed, then 'args' can be *NULL*. tuple 'args'. If no arguments are needed, then 'args' can be NULL.
Returns the result of the call on success, or *NULL* on failure. Returns the result of the call on success, or NULL on failure.
This is the equivalent of the Python expression: This is the equivalent of the Python expression:
callable(*args). */ callable(*args). */