[Python-checkins] [3.12] gh-107298: Fix yet more Sphinx warnings in the C API doc (GH-107345) (GH-107380)
serhiy-storchaka
webhook-mailer at python.org
Fri Jul 28 04:20:57 EDT 2023
https://github.com/python/cpython/commit/4014869b4b2456b3da1118a37332f9e9e851aebf
commit: 4014869b4b2456b3da1118a37332f9e9e851aebf
branch: 3.12
author: Serhiy Storchaka <storchaka at gmail.com>
committer: serhiy-storchaka <storchaka at gmail.com>
date: 2023-07-28T08:20:53Z
summary:
[3.12] gh-107298: Fix yet more Sphinx warnings in the C API doc (GH-107345) (GH-107380)
(cherry picked from commit 983305268e2291b0a7835621b81bf40cba7c27f3)
files:
M Doc/c-api/capsule.rst
M Doc/c-api/init_config.rst
M Doc/c-api/intro.rst
M Doc/c-api/memory.rst
M Doc/c-api/module.rst
M Doc/c-api/none.rst
M Doc/c-api/object.rst
M Doc/c-api/set.rst
M Doc/c-api/sys.rst
M Doc/c-api/type.rst
M Doc/c-api/typeobj.rst
M Doc/extending/embedding.rst
M Doc/extending/extending.rst
M Doc/extending/newtypes.rst
M Doc/extending/newtypes_tutorial.rst
M Doc/howto/descriptor.rst
M Doc/tools/.nitignore
M Doc/whatsnew/2.5.rst
M Doc/whatsnew/3.8.rst
diff --git a/Doc/c-api/capsule.rst b/Doc/c-api/capsule.rst
index 2a1b602dc79c0..cdb8aa33e9fd3 100644
--- a/Doc/c-api/capsule.rst
+++ b/Doc/c-api/capsule.rst
@@ -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.
diff --git a/Doc/c-api/init_config.rst b/Doc/c-api/init_config.rst
index cf7337f679e69..9da9f873e7448 100644
--- a/Doc/c-api/init_config.rst
+++ b/Doc/c-api/init_config.rst
@@ -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
@@ -920,7 +930,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.
diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst
index 8de76e55cd058..42a5db1893472 100644
--- a/Doc/c-api/intro.rst
+++ b/Doc/c-api/intro.rst
@@ -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::
diff --git a/Doc/c-api/memory.rst b/Doc/c-api/memory.rst
index c51aba3f55536..8968b26b64320 100644
--- a/Doc/c-api/memory.rst
+++ b/Doc/c-api/memory.rst
@@ -431,6 +431,8 @@ Customize Memory Allocators
Enum used to identify an allocator domain. Domains:
+ .. c:namespace:: NULL
+
.. c:macro:: PYMEM_DOMAIN_RAW
Functions:
diff --git a/Doc/c-api/module.rst b/Doc/c-api/module.rst
index fc4dd4ce053e6..8ca48c852d4e6 100644
--- a/Doc/c-api/module.rst
+++ b/Doc/c-api/module.rst
@@ -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.
diff --git a/Doc/c-api/none.rst b/Doc/c-api/none.rst
index 1a497652ac565..dd8bfb5610425 100644
--- a/Doc/c-api/none.rst
+++ b/Doc/c-api/none.rst
@@ -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.
diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst
index 3b922f3b810c7..5b3c3615f7581 100644
--- a/Doc/c-api/object.rst
+++ b/Doc/c-api/object.rst
@@ -256,7 +256,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)
@@ -273,10 +273,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).
diff --git a/Doc/c-api/set.rst b/Doc/c-api/set.rst
index 7e0ebd2f791a4..1e8a09509032f 100644
--- a/Doc/c-api/set.rst
+++ b/Doc/c-api/set.rst
@@ -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.
diff --git a/Doc/c-api/sys.rst b/Doc/c-api/sys.rst
index 2c45ea1427a11..1cec0666f5319 100644
--- a/Doc/c-api/sys.rst
+++ b/Doc/c-api/sys.rst
@@ -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:
diff --git a/Doc/c-api/type.rst b/Doc/c-api/type.rst
index e7b35c43da32a..0f58326f6c06b 100644
--- a/Doc/c-api/type.rst
+++ b/Doc/c-api/type.rst
@@ -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
diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst
index 99b025dc41fc2..26e6133aebaa8 100644
--- a/Doc/c-api/typeobj.rst
+++ b/Doc/c-api/typeobj.rst
@@ -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
diff --git a/Doc/extending/embedding.rst b/Doc/extending/embedding.rst
index e64db37334403..4c7c7ec98a6c9 100644
--- a/Doc/extending/embedding.rst
+++ b/Doc/extending/embedding.rst
@@ -250,7 +250,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
diff --git a/Doc/extending/extending.rst b/Doc/extending/extending.rst
index c13b9371297ee..72e30a6882807 100644
--- a/Doc/extending/extending.rst
+++ b/Doc/extending/extending.rst
@@ -195,7 +195,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,
@@ -206,7 +206,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::
@@ -1209,13 +1209,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
@@ -1278,7 +1278,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::
@@ -1332,8 +1332,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)
diff --git a/Doc/extending/newtypes.rst b/Doc/extending/newtypes.rst
index 25822744125f8..386b3c8f4452c 100644
--- a/Doc/extending/newtypes.rst
+++ b/Doc/extending/newtypes.rst
@@ -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`
diff --git a/Doc/extending/newtypes_tutorial.rst b/Doc/extending/newtypes_tutorial.rst
index 7180191d40f18..f8684df5dd829 100644
--- a/Doc/extending/newtypes_tutorial.rst
+++ b/Doc/extending/newtypes_tutorial.rst
@@ -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;
@@ -220,7 +220,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
@@ -272,7 +272,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::
@@ -311,7 +311,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``
@@ -345,7 +345,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
@@ -388,14 +388,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::
@@ -708,8 +708,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.
@@ -791,9 +791,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
@@ -823,7 +823,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
@@ -835,7 +835,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
diff --git a/Doc/howto/descriptor.rst b/Doc/howto/descriptor.rst
index 3688c47f0d6ec..1d9424cb735a4 100644
--- a/Doc/howto/descriptor.rst
+++ b/Doc/howto/descriptor.rst
@@ -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
diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore
index ab906b3817670..63223de613ff7 100644
--- a/Doc/tools/.nitignore
+++ b/Doc/tools/.nitignore
@@ -6,7 +6,6 @@
Doc/c-api/arg.rst
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/dict.rst
@@ -21,7 +20,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
@@ -30,10 +28,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
diff --git a/Doc/whatsnew/2.5.rst b/Doc/whatsnew/2.5.rst
index 162d2c342f50f..a15eefc2953f4 100644
--- a/Doc/whatsnew/2.5.rst
+++ b/Doc/whatsnew/2.5.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.
diff --git a/Doc/whatsnew/3.8.rst b/Doc/whatsnew/3.8.rst
index 98d97268b5901..3397de5d3e8c4 100644
--- a/Doc/whatsnew/3.8.rst
+++ b/Doc/whatsnew/3.8.rst
@@ -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`.)
More information about the Python-checkins
mailing list