mirror of
https://github.com/python/cpython
synced 2024-09-05 00:05:39 +00:00
gh-107298: Fix yet more Sphinx warnings in the C API doc (GH-107345)
This commit is contained in:
parent
ac7a0f858a
commit
983305268e
|
@ -121,7 +121,7 @@ Refer to :ref:`using-capsules` for more information on using these objects.
|
|||
compared.)
|
||||
|
||||
In other words, if :c:func:`PyCapsule_IsValid` returns a true value, calls to
|
||||
any of the accessors (any function starting with :c:func:`PyCapsule_Get`) are
|
||||
any of the accessors (any function starting with ``PyCapsule_Get``) are
|
||||
guaranteed to succeed.
|
||||
|
||||
Return a nonzero value if the object is valid and matches the name passed in.
|
||||
|
|
|
@ -135,6 +135,8 @@ PyStatus
|
|||
|
||||
Name of the function which created an error, can be ``NULL``.
|
||||
|
||||
.. c:namespace:: NULL
|
||||
|
||||
Functions to create a status:
|
||||
|
||||
.. c:function:: PyStatus PyStatus_Ok(void)
|
||||
|
@ -210,6 +212,8 @@ PyPreConfig
|
|||
|
||||
Structure used to preinitialize Python.
|
||||
|
||||
.. c:namespace:: NULL
|
||||
|
||||
Function to initialize a preconfiguration:
|
||||
|
||||
.. c:function:: void PyPreConfig_InitPythonConfig(PyPreConfig *preconfig)
|
||||
|
@ -222,6 +226,8 @@ PyPreConfig
|
|||
Initialize the preconfiguration with :ref:`Isolated Configuration
|
||||
<init-isolated-conf>`.
|
||||
|
||||
.. c:namespace:: PyPreConfig
|
||||
|
||||
Structure fields:
|
||||
|
||||
.. c:member:: int allocator
|
||||
|
@ -429,6 +435,8 @@ PyConfig
|
|||
When done, the :c:func:`PyConfig_Clear` function must be used to release the
|
||||
configuration memory.
|
||||
|
||||
.. c:namespace:: NULL
|
||||
|
||||
Structure methods:
|
||||
|
||||
.. c:function:: void PyConfig_InitPythonConfig(PyConfig *config)
|
||||
|
@ -527,6 +535,8 @@ PyConfig
|
|||
The caller of these methods is responsible to handle exceptions (error or
|
||||
exit) using ``PyStatus_Exception()`` and ``Py_ExitStatusException()``.
|
||||
|
||||
.. c:namespace:: PyConfig
|
||||
|
||||
Structure fields:
|
||||
|
||||
.. c:member:: PyWideStringList argv
|
||||
|
@ -938,7 +948,7 @@ PyConfig
|
|||
.. c:member:: wchar_t* pythonpath_env
|
||||
|
||||
Module search paths (:data:`sys.path`) as a string separated by ``DELIM``
|
||||
(:data:`os.path.pathsep`).
|
||||
(:data:`os.pathsep`).
|
||||
|
||||
Set by the :envvar:`PYTHONPATH` environment variable.
|
||||
|
||||
|
|
|
@ -616,7 +616,7 @@ and lose important information about the exact cause of the error.
|
|||
.. index:: single: sum_sequence()
|
||||
|
||||
A simple example of detecting exceptions and passing them on is shown in the
|
||||
:c:func:`sum_sequence` example above. It so happens that this example doesn't
|
||||
:c:func:`!sum_sequence` example above. It so happens that this example doesn't
|
||||
need to clean up any owned references when it detects an error. The following
|
||||
example function shows some error cleanup. First, to remind you why you like
|
||||
Python, we show the equivalent Python code::
|
||||
|
|
|
@ -431,6 +431,8 @@ Customize Memory Allocators
|
|||
|
||||
Enum used to identify an allocator domain. Domains:
|
||||
|
||||
.. c:namespace:: NULL
|
||||
|
||||
.. c:macro:: PYMEM_DOMAIN_RAW
|
||||
|
||||
Functions:
|
||||
|
|
|
@ -119,7 +119,7 @@ Module Objects
|
|||
encoded to 'utf-8'.
|
||||
|
||||
.. deprecated:: 3.2
|
||||
:c:func:`PyModule_GetFilename` raises :c:type:`UnicodeEncodeError` on
|
||||
:c:func:`PyModule_GetFilename` raises :exc:`UnicodeEncodeError` on
|
||||
unencodable filenames, use :c:func:`PyModule_GetFilenameObject` instead.
|
||||
|
||||
|
||||
|
|
|
@ -9,7 +9,7 @@ The ``None`` Object
|
|||
|
||||
Note that the :c:type:`PyTypeObject` for ``None`` is not directly exposed in the
|
||||
Python/C API. Since ``None`` is a singleton, testing for object identity (using
|
||||
``==`` in C) is sufficient. There is no :c:func:`PyNone_Check` function for the
|
||||
``==`` in C) is sufficient. There is no :c:func:`!PyNone_Check` function for the
|
||||
same reason.
|
||||
|
||||
|
||||
|
|
|
@ -293,7 +293,7 @@ Object Protocol
|
|||
|
||||
Normally only class objects, i.e. instances of :class:`type` or a derived
|
||||
class, are considered classes. However, objects can override this by having
|
||||
a :attr:`__bases__` attribute (which must be a tuple of base classes).
|
||||
a :attr:`~class.__bases__` attribute (which must be a tuple of base classes).
|
||||
|
||||
|
||||
.. c:function:: int PyObject_IsInstance(PyObject *inst, PyObject *cls)
|
||||
|
@ -310,10 +310,10 @@ Object Protocol
|
|||
is an instance of *cls* if its class is a subclass of *cls*.
|
||||
|
||||
An instance *inst* can override what is considered its class by having a
|
||||
:attr:`__class__` attribute.
|
||||
:attr:`~instance.__class__` attribute.
|
||||
|
||||
An object *cls* can override if it is considered a class, and what its base
|
||||
classes are, by having a :attr:`__bases__` attribute (which must be a tuple
|
||||
classes are, by having a :attr:`~class.__bases__` attribute (which must be a tuple
|
||||
of base classes).
|
||||
|
||||
|
||||
|
|
|
@ -110,7 +110,7 @@ or :class:`frozenset` or instances of their subtypes.
|
|||
.. index:: pair: built-in function; len
|
||||
|
||||
Return the length of a :class:`set` or :class:`frozenset` object. Equivalent to
|
||||
``len(anyset)``. Raises a :exc:`PyExc_SystemError` if *anyset* is not a
|
||||
``len(anyset)``. Raises a :exc:`SystemError` if *anyset* is not a
|
||||
:class:`set`, :class:`frozenset`, or an instance of a subtype.
|
||||
|
||||
|
||||
|
@ -124,7 +124,7 @@ or :class:`frozenset` or instances of their subtypes.
|
|||
Return ``1`` if found, ``0`` if not found, and ``-1`` if an error is encountered. Unlike
|
||||
the Python :meth:`~object.__contains__` method, this function does not automatically
|
||||
convert unhashable sets into temporary frozensets. Raise a :exc:`TypeError` if
|
||||
the *key* is unhashable. Raise :exc:`PyExc_SystemError` if *anyset* is not a
|
||||
the *key* is unhashable. Raise :exc:`SystemError` if *anyset* is not a
|
||||
:class:`set`, :class:`frozenset`, or an instance of a subtype.
|
||||
|
||||
|
||||
|
@ -149,7 +149,7 @@ subtypes but not for instances of :class:`frozenset` or its subtypes.
|
|||
error is encountered. Does not raise :exc:`KeyError` for missing keys. Raise a
|
||||
:exc:`TypeError` if the *key* is unhashable. Unlike the Python :meth:`~set.discard`
|
||||
method, this function does not automatically convert unhashable sets into
|
||||
temporary frozensets. Raise :exc:`PyExc_SystemError` if *set* is not an
|
||||
temporary frozensets. Raise :exc:`SystemError` if *set* is not an
|
||||
instance of :class:`set` or its subtype.
|
||||
|
||||
|
||||
|
|
|
@ -167,7 +167,7 @@ Operating System Utilities
|
|||
|
||||
.. versionchanged:: 3.8
|
||||
The function now uses the UTF-8 encoding on Windows if
|
||||
:c:member:`PyConfig.legacy_windows_fs_encoding` is zero;
|
||||
:c:member:`PyPreConfig.legacy_windows_fs_encoding` is zero;
|
||||
|
||||
|
||||
.. c:function:: char* Py_EncodeLocale(const wchar_t *text, size_t *error_pos)
|
||||
|
@ -209,7 +209,7 @@ Operating System Utilities
|
|||
|
||||
.. versionchanged:: 3.8
|
||||
The function now uses the UTF-8 encoding on Windows if
|
||||
:c:member:`PyConfig.legacy_windows_fs_encoding` is zero.
|
||||
:c:member:`PyPreConfig.legacy_windows_fs_encoding` is zero.
|
||||
|
||||
|
||||
.. _systemfunctions:
|
||||
|
|
|
@ -103,7 +103,7 @@ Type Objects
|
|||
:c:func:`PyType_AddWatcher` will be called whenever
|
||||
:c:func:`PyType_Modified` reports a change to *type*. (The callback may be
|
||||
called only once for a series of consecutive modifications to *type*, if
|
||||
:c:func:`PyType_Lookup` is not called on *type* between the modifications;
|
||||
:c:func:`!_PyType_Lookup` is not called on *type* between the modifications;
|
||||
this is an implementation detail and subject to change.)
|
||||
|
||||
An extension should never call ``PyType_Watch`` with a *watcher_id* that was
|
||||
|
|
|
@ -485,7 +485,7 @@ PyObject Slots
|
|||
--------------
|
||||
|
||||
The type object structure extends the :c:type:`PyVarObject` structure. The
|
||||
:c:member:`~PyVarObject.ob_size` field is used for dynamic types (created by :func:`type_new`,
|
||||
:c:member:`~PyVarObject.ob_size` field is used for dynamic types (created by :c:func:`!type_new`,
|
||||
usually called from a class statement). Note that :c:data:`PyType_Type` (the
|
||||
metatype) initializes :c:member:`~PyTypeObject.tp_itemsize`, which means that its instances (i.e.
|
||||
type objects) *must* have the :c:member:`~PyVarObject.ob_size` field.
|
||||
|
@ -740,7 +740,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
|
|||
Before version 3.12, it was not recommended for
|
||||
:ref:`mutable heap types <heap-types>` to implement the vectorcall
|
||||
protocol.
|
||||
When a user sets :attr:`~type.__call__` in Python code, only *tp_call* is
|
||||
When a user sets :attr:`~object.__call__` in Python code, only *tp_call* is
|
||||
updated, likely making it inconsistent with the vectorcall function.
|
||||
Since 3.12, setting ``__call__`` will disable vectorcall optimization
|
||||
by clearing the :c:macro:`Py_TPFLAGS_HAVE_VECTORCALL` flag.
|
||||
|
@ -1369,8 +1369,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
|
|||
The :c:member:`~PyTypeObject.tp_traverse` pointer is used by the garbage collector to detect
|
||||
reference cycles. A typical implementation of a :c:member:`~PyTypeObject.tp_traverse` function
|
||||
simply calls :c:func:`Py_VISIT` on each of the instance's members that are Python
|
||||
objects that the instance owns. For example, this is function :c:func:`local_traverse` from the
|
||||
:mod:`_thread` extension module::
|
||||
objects that the instance owns. For example, this is function :c:func:`!local_traverse` from the
|
||||
:mod:`!_thread` extension module::
|
||||
|
||||
static int
|
||||
local_traverse(localobject *self, visitproc visit, void *arg)
|
||||
|
@ -1721,7 +1721,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
|
|||
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
|
||||
attributes for the type may be added to this dictionary only if they don't
|
||||
correspond to overloaded operations (like :meth:`__add__`). Once
|
||||
correspond to overloaded operations (like :meth:`~object.__add__`). Once
|
||||
initialization for the type has finished, this field should be
|
||||
treated as read-only.
|
||||
|
||||
|
@ -1818,7 +1818,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
|
|||
**Default:**
|
||||
|
||||
This slot has no default. For :ref:`static types <static-types>`, if the
|
||||
field is ``NULL`` then no :attr:`__dict__` gets created for instances.
|
||||
field is ``NULL`` then no :attr:`~object.__dict__` gets created for instances.
|
||||
|
||||
If the :c:macro:`Py_TPFLAGS_MANAGED_DICT` bit is set in the
|
||||
:c:member:`~PyTypeObject.tp_dict` field, then
|
||||
|
@ -1830,10 +1830,10 @@ and :c:data:`PyType_Type` effectively act as defaults.)
|
|||
|
||||
An optional pointer to an instance initialization function.
|
||||
|
||||
This function corresponds to the :meth:`__init__` method of classes. Like
|
||||
:meth:`__init__`, it is possible to create an instance without calling
|
||||
:meth:`__init__`, and it is possible to reinitialize an instance by calling its
|
||||
:meth:`__init__` method again.
|
||||
This function corresponds to the :meth:`~object.__init__` method of classes. Like
|
||||
:meth:`!__init__`, it is possible to create an instance without calling
|
||||
:meth:`!__init__`, and it is possible to reinitialize an instance by calling its
|
||||
:meth:`!__init__` method again.
|
||||
|
||||
The function signature is::
|
||||
|
||||
|
@ -1841,7 +1841,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
|
|||
|
||||
The self argument is the instance to be initialized; the *args* and *kwds*
|
||||
arguments represent positional and keyword arguments of the call to
|
||||
:meth:`__init__`.
|
||||
:meth:`~object.__init__`.
|
||||
|
||||
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
|
||||
|
@ -2130,7 +2130,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
|
|||
In other words, it is used to implement
|
||||
:ref:`vectorcall <vectorcall>` for ``type.__call__``.
|
||||
If ``tp_vectorcall`` is ``NULL``, the default call implementation
|
||||
using :attr:`__new__` and :attr:`__init__` is used.
|
||||
using :meth:`~object.__new__` and :meth:`~object.__init__` is used.
|
||||
|
||||
**Inheritance:**
|
||||
|
||||
|
@ -2329,8 +2329,8 @@ Mapping Object Structures
|
|||
.. c:member:: objobjargproc PyMappingMethods.mp_ass_subscript
|
||||
|
||||
This function is used by :c:func:`PyObject_SetItem`,
|
||||
:c:func:`PyObject_DelItem`, :c:func:`PyObject_SetSlice` and
|
||||
:c:func:`PyObject_DelSlice`. It has the same signature as
|
||||
:c:func:`PyObject_DelItem`, :c:func:`PySequence_SetSlice` and
|
||||
:c:func:`PySequence_DelSlice`. It has the same signature as
|
||||
: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
|
||||
assignment and deletion.
|
||||
|
@ -2552,7 +2552,7 @@ Async Object Structures
|
|||
PyObject *am_aiter(PyObject *self);
|
||||
|
||||
Must return an :term:`asynchronous iterator` object.
|
||||
See :meth:`__anext__` for details.
|
||||
See :meth:`~object.__anext__` for details.
|
||||
|
||||
This slot may be set to ``NULL`` if an object does not implement
|
||||
asynchronous iteration protocol.
|
||||
|
@ -2563,7 +2563,8 @@ Async Object Structures
|
|||
|
||||
PyObject *am_anext(PyObject *self);
|
||||
|
||||
Must return an :term:`awaitable` object. See :meth:`__anext__` for details.
|
||||
Must return an :term:`awaitable` object.
|
||||
See :meth:`~object.__anext__` for details.
|
||||
This slot may be set to ``NULL``.
|
||||
|
||||
.. c:member:: sendfunc PyAsyncMethods.am_send
|
||||
|
|
|
@ -269,7 +269,7 @@ following two statements before the call to :c:func:`Py_Initialize`::
|
|||
PyImport_AppendInittab("emb", &PyInit_emb);
|
||||
|
||||
These two lines initialize the ``numargs`` variable, and make the
|
||||
:func:`emb.numargs` function accessible to the embedded Python interpreter.
|
||||
:func:`!emb.numargs` function accessible to the embedded Python interpreter.
|
||||
With these extensions, the Python script can do things like
|
||||
|
||||
.. code-block:: python
|
||||
|
|
|
@ -197,7 +197,7 @@ The choice of which exception to raise is entirely yours. There are predeclared
|
|||
C objects corresponding to all built-in Python exceptions, such as
|
||||
:c:data:`PyExc_ZeroDivisionError`, which you can use directly. Of course, you
|
||||
should choose exceptions wisely --- don't use :c:data:`PyExc_TypeError` to mean
|
||||
that a file couldn't be opened (that should probably be :c:data:`PyExc_IOError`).
|
||||
that a file couldn't be opened (that should probably be :c:data:`PyExc_OSError`).
|
||||
If something's wrong with the argument list, the :c:func:`PyArg_ParseTuple`
|
||||
function usually raises :c:data:`PyExc_TypeError`. If you have an argument whose
|
||||
value must be in a particular range or must satisfy other conditions,
|
||||
|
@ -208,7 +208,7 @@ usually declare a static object variable at the beginning of your file::
|
|||
|
||||
static PyObject *SpamError;
|
||||
|
||||
and initialize it in your module's initialization function (:c:func:`PyInit_spam`)
|
||||
and initialize it in your module's initialization function (:c:func:`!PyInit_spam`)
|
||||
with an exception object::
|
||||
|
||||
PyMODINIT_FUNC
|
||||
|
@ -354,7 +354,7 @@ The method table must be referenced in the module definition structure::
|
|||
|
||||
This structure, in turn, must be passed to the interpreter in the module's
|
||||
initialization function. The initialization function must be named
|
||||
:c:func:`PyInit_name`, where *name* is the name of the module, and should be the
|
||||
:c:func:`!PyInit_name`, where *name* is the name of the module, and should be the
|
||||
only non-\ ``static`` item defined in the module file::
|
||||
|
||||
PyMODINIT_FUNC
|
||||
|
@ -368,7 +368,7 @@ declares any special linkage declarations required by the platform, and for C++
|
|||
declares the function as ``extern "C"``.
|
||||
|
||||
When the Python program imports module :mod:`!spam` for the first time,
|
||||
:c:func:`PyInit_spam` is called. (See below for comments about embedding Python.)
|
||||
:c:func:`!PyInit_spam` is called. (See below for comments about embedding Python.)
|
||||
It calls :c:func:`PyModule_Create`, which returns a module object, and
|
||||
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.
|
||||
|
@ -378,7 +378,7 @@ certain errors, or return ``NULL`` if the module could not be initialized
|
|||
satisfactorily. The init function must return the module object to its caller,
|
||||
so that it then gets inserted into ``sys.modules``.
|
||||
|
||||
When embedding Python, the :c:func:`PyInit_spam` function is not called
|
||||
When embedding Python, the :c:func:`!PyInit_spam` function is not called
|
||||
automatically unless there's an entry in the :c:data:`PyImport_Inittab` table.
|
||||
To add the module to the initialization table, use :c:func:`PyImport_AppendInittab`,
|
||||
optionally followed by an import of the module::
|
||||
|
@ -1220,13 +1220,13 @@ the module and retrieving its C API pointers; client modules only have to call
|
|||
this macro before accessing the C API.
|
||||
|
||||
The exporting module is a modification of the :mod:`!spam` module from section
|
||||
:ref:`extending-simpleexample`. The function :func:`spam.system` does not call
|
||||
:ref:`extending-simpleexample`. The function :func:`!spam.system` does not call
|
||||
the C library function :c:func:`system` directly, but a function
|
||||
:c:func:`PySpam_System`, which would of course do something more complicated in
|
||||
:c:func:`!PySpam_System`, which would of course do something more complicated in
|
||||
reality (such as adding "spam" to every command). This function
|
||||
:c:func:`PySpam_System` is also exported to other extension modules.
|
||||
:c:func:`!PySpam_System` is also exported to other extension modules.
|
||||
|
||||
The function :c:func:`PySpam_System` is a plain C function, declared
|
||||
The function :c:func:`!PySpam_System` is a plain C function, declared
|
||||
``static`` like everything else::
|
||||
|
||||
static int
|
||||
|
@ -1288,7 +1288,7 @@ function must take care of initializing the C API pointer array::
|
|||
}
|
||||
|
||||
Note that ``PySpam_API`` is declared ``static``; otherwise the pointer
|
||||
array would disappear when :func:`PyInit_spam` terminates!
|
||||
array would disappear when :c:func:`!PyInit_spam` terminates!
|
||||
|
||||
The bulk of the work is in the header file :file:`spammodule.h`, which looks
|
||||
like this::
|
||||
|
@ -1342,8 +1342,8 @@ like this::
|
|||
#endif /* !defined(Py_SPAMMODULE_H) */
|
||||
|
||||
All that a client module must do in order to have access to the function
|
||||
:c:func:`PySpam_System` is to call the function (or rather macro)
|
||||
:c:func:`import_spam` in its initialization function::
|
||||
:c:func:`!PySpam_System` is to call the function (or rather macro)
|
||||
:c:func:`!import_spam` in its initialization function::
|
||||
|
||||
PyMODINIT_FUNC
|
||||
PyInit_client(void)
|
||||
|
|
|
@ -286,9 +286,9 @@ be read-only or read-write. The structures in the table are defined as::
|
|||
|
||||
For each entry in the table, a :term:`descriptor` will be constructed and added to the
|
||||
type which will be able to extract a value from the instance structure. The
|
||||
:attr:`type` field should contain a type code like :c:macro:`Py_T_INT` or
|
||||
:c:member:`~PyMemberDef.type` field should contain a type code like :c:macro:`Py_T_INT` or
|
||||
:c:macro:`Py_T_DOUBLE`; the value will be used to determine how to
|
||||
convert Python values to and from C values. The :attr:`flags` field is used to
|
||||
convert Python values to and from C values. The :c:member:`~PyMemberDef.flags` field is used to
|
||||
store flags which control how the attribute can be accessed: you can set it to
|
||||
:c:macro:`Py_READONLY` to prevent Python code from setting it.
|
||||
|
||||
|
@ -298,7 +298,7 @@ have an associated doc string simply by providing the text in the table. An
|
|||
application can use the introspection API to retrieve the descriptor from the
|
||||
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 :c:member:`~PyMethodDef.name` value
|
||||
of ``NULL`` is required.
|
||||
|
||||
.. XXX Descriptors need to be explained in more detail somewhere, but not here.
|
||||
|
@ -323,7 +323,7 @@ called, so that if you do need to extend their functionality, you'll understand
|
|||
what needs to be done.
|
||||
|
||||
The :c:member:`~PyTypeObject.tp_getattr` handler is called when the object requires an attribute
|
||||
look-up. It is called in the same situations where the :meth:`__getattr__`
|
||||
look-up. It is called in the same situations where the :meth:`~object.__getattr__`
|
||||
method of a class would be called.
|
||||
|
||||
Here is an example::
|
||||
|
@ -342,8 +342,8 @@ Here is an example::
|
|||
return NULL;
|
||||
}
|
||||
|
||||
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
|
||||
The :c:member:`~PyTypeObject.tp_setattr` handler is called when the :meth:`~object.__setattr__` or
|
||||
:meth:`~object.__delattr__` method of a class instance would be called. When 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
|
||||
:c:member:`~PyTypeObject.tp_setattr` handler should be set to ``NULL``. ::
|
||||
|
@ -364,7 +364,7 @@ Object Comparison
|
|||
|
||||
The :c:member:`~PyTypeObject.tp_richcompare` handler is called when comparisons are needed. It is
|
||||
analogous to the :ref:`rich comparison methods <richcmpfuncs>`, like
|
||||
:meth:`__lt__`, and also called by :c:func:`PyObject_RichCompare` and
|
||||
:meth:`!__lt__`, and also called by :c:func:`PyObject_RichCompare` and
|
||||
:c:func:`PyObject_RichCompareBool`.
|
||||
|
||||
This function is called with two Python objects and the operator as arguments,
|
||||
|
@ -505,7 +505,7 @@ These functions provide support for the iterator protocol. Both handlers
|
|||
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
|
||||
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:`~object.__iter__` method, while :c:member:`~PyTypeObject.tp_iternext`
|
||||
corresponds to the Python :meth:`~iterator.__next__` method.
|
||||
|
||||
Any :term:`iterable` object must implement the :c:member:`~PyTypeObject.tp_iter`
|
||||
|
|
|
@ -145,7 +145,7 @@ only used for variable-sized objects and should otherwise be zero.
|
|||
:c:member:`~PyTypeObject.tp_basicsize` as its base type, you may have problems with multiple
|
||||
inheritance. A Python subclass of your type will have to list your type first
|
||||
in its :attr:`~class.__bases__`, or else it will not be able to call your type's
|
||||
:meth:`__new__` method without getting an error. You can avoid this problem by
|
||||
:meth:`~object.__new__` method without getting an error. You can avoid this problem by
|
||||
ensuring that your type has a larger value for :c:member:`~PyTypeObject.tp_basicsize` than its
|
||||
base type does. Most of the time, this will be true anyway, because either your
|
||||
base type will be :class:`object`, or else you will be adding data members to
|
||||
|
@ -164,14 +164,14 @@ We provide a doc string for the type in :c:member:`~PyTypeObject.tp_doc`. ::
|
|||
.tp_doc = PyDoc_STR("Custom objects"),
|
||||
|
||||
To enable object creation, we have to provide a :c:member:`~PyTypeObject.tp_new`
|
||||
handler. This is the equivalent of the Python method :meth:`__new__`, but
|
||||
handler. This is the equivalent of the Python method :meth:`~object.__new__`, but
|
||||
has to be specified explicitly. In this case, we can just use the default
|
||||
implementation provided by the API function :c:func:`PyType_GenericNew`. ::
|
||||
|
||||
.tp_new = PyType_GenericNew,
|
||||
|
||||
Everything else in the file should be familiar, except for some code in
|
||||
:c:func:`PyInit_custom`::
|
||||
:c:func:`!PyInit_custom`::
|
||||
|
||||
if (PyType_Ready(&CustomType) < 0)
|
||||
return;
|
||||
|
@ -218,7 +218,7 @@ Of course, the current Custom type is pretty uninteresting. It has no data and
|
|||
doesn't do anything. It can't even be subclassed.
|
||||
|
||||
.. note::
|
||||
While this documentation showcases the standard :mod:`distutils` module
|
||||
While this documentation showcases the standard :mod:`!distutils` module
|
||||
for building C extensions, it is recommended in real-world use cases to
|
||||
use the newer and better-maintained ``setuptools`` library. Documentation
|
||||
on how to do this is out of scope for this document and can be found in
|
||||
|
@ -270,7 +270,7 @@ This method first clears the reference counts of the two Python attributes.
|
|||
``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
|
||||
(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
|
||||
be an instance of a subclass.
|
||||
|
||||
.. note::
|
||||
|
@ -309,7 +309,7 @@ and install it in the :c:member:`~PyTypeObject.tp_new` member::
|
|||
.tp_new = Custom_new,
|
||||
|
||||
The ``tp_new`` handler is responsible for creating (as opposed to initializing)
|
||||
objects of the type. It is exposed in Python as the :meth:`__new__` method.
|
||||
objects of the type. It is exposed in Python as the :meth:`~object.__new__` method.
|
||||
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
|
||||
version of the :class:`!Custom` type above. In this case, we use the ``tp_new``
|
||||
|
@ -343,7 +343,7 @@ result against ``NULL`` before proceeding.
|
|||
|
||||
.. note::
|
||||
If you are creating a co-operative :c:member:`~PyTypeObject.tp_new` (one
|
||||
that calls a base type's :c:member:`~PyTypeObject.tp_new` or :meth:`__new__`),
|
||||
that calls a base type's :c:member:`~PyTypeObject.tp_new` or :meth:`~object.__new__`),
|
||||
you must *not* try to determine what method to call using method resolution
|
||||
order at runtime. Always statically determine what type you are going to
|
||||
call, and call its :c:member:`~PyTypeObject.tp_new` directly, or via
|
||||
|
@ -386,14 +386,14 @@ by filling the :c:member:`~PyTypeObject.tp_init` slot. ::
|
|||
.tp_init = (initproc) Custom_init,
|
||||
|
||||
The :c:member:`~PyTypeObject.tp_init` slot is exposed in Python as the
|
||||
:meth:`__init__` method. It is used to initialize an object after it's
|
||||
:meth:`~object.__init__` method. It is used to initialize an object after it's
|
||||
created. Initializers always accept positional and keyword arguments,
|
||||
and they should return either ``0`` on success or ``-1`` on error.
|
||||
|
||||
Unlike the ``tp_new`` handler, there is no guarantee that ``tp_init``
|
||||
is called at all (for example, the :mod:`pickle` module by default
|
||||
doesn't call :meth:`__init__` on unpickled instances). It can also be
|
||||
called multiple times. Anyone can call the :meth:`__init__` method on
|
||||
doesn't call :meth:`~object.__init__` on unpickled instances). It can also be
|
||||
called multiple times. Anyone can call the :meth:`!__init__` method on
|
||||
our objects. For this reason, we have to be extra careful when assigning
|
||||
the new attribute values. We might be tempted, for example to assign the
|
||||
``first`` member like this::
|
||||
|
@ -706,8 +706,8 @@ participate in cycles::
|
|||
}
|
||||
|
||||
For each subobject that can participate in cycles, we need to call the
|
||||
:c:func:`visit` function, which is passed to the traversal method. The
|
||||
:c:func:`visit` function takes as arguments the subobject and the extra argument
|
||||
:c:func:`!visit` function, which is passed to the traversal method. The
|
||||
:c:func:`!visit` function takes as arguments the subobject and the extra argument
|
||||
*arg* passed to the traversal method. It returns an integer value that must be
|
||||
returned if it is non-zero.
|
||||
|
||||
|
@ -789,9 +789,9 @@ types. It is easiest to inherit from the built in types, since an extension can
|
|||
easily use the :c:type:`PyTypeObject` it needs. It can be difficult to share
|
||||
these :c:type:`PyTypeObject` structures between extension modules.
|
||||
|
||||
In this example we will create a :class:`SubList` type that inherits from the
|
||||
In this example we will create a :class:`!SubList` type that inherits from the
|
||||
built-in :class:`list` type. The new type will be completely compatible with
|
||||
regular lists, but will have an additional :meth:`increment` method that
|
||||
regular lists, but will have an additional :meth:`!increment` method that
|
||||
increases an internal counter:
|
||||
|
||||
.. code-block:: pycon
|
||||
|
@ -821,7 +821,7 @@ The primary difference for derived type objects is that the base type's
|
|||
object structure must be the first value. The base type will already include
|
||||
the :c:func:`PyObject_HEAD` at the beginning of its structure.
|
||||
|
||||
When a Python object is a :class:`SubList` instance, its ``PyObject *`` pointer
|
||||
When a Python object is a :class:`!SubList` instance, its ``PyObject *`` pointer
|
||||
can be safely cast to both ``PyListObject *`` and ``SubListObject *``::
|
||||
|
||||
static int
|
||||
|
@ -833,7 +833,7 @@ can be safely cast to both ``PyListObject *`` and ``SubListObject *``::
|
|||
return 0;
|
||||
}
|
||||
|
||||
We see above how to call through to the :attr:`__init__` method of the base
|
||||
We see above how to call through to the :meth:`~object.__init__` method of the base
|
||||
type.
|
||||
|
||||
This pattern is important when writing a type with custom
|
||||
|
|
|
@ -779,8 +779,8 @@ by a search through the class's :term:`method resolution order`.
|
|||
|
||||
If a descriptor is found, it is invoked with ``desc.__get__(None, A)``.
|
||||
|
||||
The full C implementation can be found in :c:func:`type_getattro()` and
|
||||
:c:func:`_PyType_Lookup()` in :source:`Objects/typeobject.c`.
|
||||
The full C implementation can be found in :c:func:`!type_getattro` and
|
||||
:c:func:`!_PyType_Lookup` in :source:`Objects/typeobject.c`.
|
||||
|
||||
|
||||
Invocation from super
|
||||
|
@ -794,7 +794,7 @@ for the base class ``B`` immediately following ``A`` and then returns
|
|||
``B.__dict__['m'].__get__(obj, A)``. If not a descriptor, ``m`` is returned
|
||||
unchanged.
|
||||
|
||||
The full C implementation can be found in :c:func:`super_getattro()` in
|
||||
The full C implementation can be found in :c:func:`!super_getattro` in
|
||||
:source:`Objects/typeobject.c`. A pure Python equivalent can be found in
|
||||
`Guido's Tutorial
|
||||
<https://www.python.org/download/releases/2.2.3/descrintro/#cooperation>`_.
|
||||
|
@ -836,8 +836,8 @@ and if they define :meth:`__set_name__`, that method is called with two
|
|||
arguments. The *owner* is the class where the descriptor is used, and the
|
||||
*name* is the class variable the descriptor was assigned to.
|
||||
|
||||
The implementation details are in :c:func:`type_new()` and
|
||||
:c:func:`set_names()` in :source:`Objects/typeobject.c`.
|
||||
The implementation details are in :c:func:`!type_new` and
|
||||
:c:func:`!set_names` in :source:`Objects/typeobject.c`.
|
||||
|
||||
Since the update logic is in :meth:`type.__new__`, notifications only take
|
||||
place at the time of class creation. If descriptors are added to the class
|
||||
|
|
|
@ -4,7 +4,6 @@
|
|||
|
||||
Doc/c-api/bool.rst
|
||||
Doc/c-api/buffer.rst
|
||||
Doc/c-api/capsule.rst
|
||||
Doc/c-api/datetime.rst
|
||||
Doc/c-api/descriptor.rst
|
||||
Doc/c-api/exceptions.rst
|
||||
|
@ -17,7 +16,6 @@ Doc/c-api/intro.rst
|
|||
Doc/c-api/memory.rst
|
||||
Doc/c-api/memoryview.rst
|
||||
Doc/c-api/module.rst
|
||||
Doc/c-api/none.rst
|
||||
Doc/c-api/object.rst
|
||||
Doc/c-api/set.rst
|
||||
Doc/c-api/stable.rst
|
||||
|
@ -26,10 +24,8 @@ Doc/c-api/sys.rst
|
|||
Doc/c-api/type.rst
|
||||
Doc/c-api/typeobj.rst
|
||||
Doc/c-api/unicode.rst
|
||||
Doc/extending/embedding.rst
|
||||
Doc/extending/extending.rst
|
||||
Doc/extending/newtypes.rst
|
||||
Doc/extending/newtypes_tutorial.rst
|
||||
Doc/faq/design.rst
|
||||
Doc/faq/extending.rst
|
||||
Doc/faq/gui.rst
|
||||
|
|
|
@ -2151,8 +2151,8 @@ Changes to Python's build process and to the C API include:
|
|||
|
||||
Previously these different families all reduced to the platform's
|
||||
:c:func:`malloc` and :c:func:`free` functions. This meant it didn't matter if
|
||||
you got things wrong and allocated memory with the :c:func:`PyMem` function but
|
||||
freed it with the :c:func:`PyObject` function. With 2.5's changes to obmalloc,
|
||||
you got things wrong and allocated memory with the ``PyMem`` function but
|
||||
freed it with the ``PyObject`` function. With 2.5's changes to obmalloc,
|
||||
these families now do different things and mismatches will probably result in a
|
||||
segfault. You should carefully test your C extension modules with Python 2.5.
|
||||
|
||||
|
|
|
@ -1850,7 +1850,7 @@ Changes in Python behavior
|
|||
finalizing, making them consistent with :c:func:`PyEval_RestoreThread`,
|
||||
:c:func:`Py_END_ALLOW_THREADS`, and :c:func:`PyGILState_Ensure`. If this
|
||||
behavior is not desired, guard the call by checking :c:func:`_Py_IsFinalizing`
|
||||
or :c:func:`sys.is_finalizing`.
|
||||
or :func:`sys.is_finalizing`.
|
||||
(Contributed by Joannah Nanjekye in :issue:`36475`.)
|
||||
|
||||
|
||||
|
|
Loading…
Reference in a new issue