[Python-checkins] gh-107091: Fix some uses of :attr: role (GH-107318)
serhiy-storchaka
webhook-mailer at python.org
Thu Jul 27 01:52:58 EDT 2023
https://github.com/python/cpython/commit/d363eb5b0255c055e7b43f5e2c0847f555e1982e
commit: d363eb5b0255c055e7b43f5e2c0847f555e1982e
branch: main
author: Serhiy Storchaka <storchaka at gmail.com>
committer: serhiy-storchaka <storchaka at gmail.com>
date: 2023-07-27T08:52:54+03:00
summary:
gh-107091: Fix some uses of :attr: role (GH-107318)
Fix also formatting of PyMethodDef members.
files:
M Doc/c-api/import.rst
M Doc/c-api/init.rst
M Doc/c-api/structures.rst
M Doc/c-api/tuple.rst
M Doc/c-api/typeobj.rst
M Doc/c-api/veryhigh.rst
M Doc/extending/newtypes.rst
M Doc/extending/newtypes_tutorial.rst
M Doc/tools/.nitignore
M Doc/whatsnew/2.5.rst
M Misc/NEWS.d/next/Core and Builtins/2023-05-30-08-09-43.gh-issue-105035.OWUlHy.rst
diff --git a/Doc/c-api/import.rst b/Doc/c-api/import.rst
index dd599b6687e88..137780cc359cf 100644
--- a/Doc/c-api/import.rst
+++ b/Doc/c-api/import.rst
@@ -310,23 +310,25 @@ Importing Modules
.. c:struct:: _inittab
- Structure describing a single entry in the list of built-in modules. Each of
- these structures gives the name and initialization function for a module built
- into the interpreter. The name is an ASCII encoded string. Programs which
+ Structure describing a single entry in the list of built-in modules.
+ Programs which
embed Python may use an array of these structures in conjunction with
:c:func:`PyImport_ExtendInittab` to provide additional built-in modules.
- The structure is defined in :file:`Include/import.h` as::
+ The structure consists of two members:
- struct _inittab {
- const char *name; /* ASCII encoded string */
- PyObject* (*initfunc)(void);
- };
+ .. c:member:: const char *name
+
+ The module name, as an ASCII encoded string.
+
+ .. c: member:: PyObject* (*initfunc)(void)
+
+ Initialization function for a module built into the interpreter.
.. c:function:: int PyImport_ExtendInittab(struct _inittab *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 :c:member:`~_inittab.name`
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
extend the internal table. In the event of failure, no modules are added to the
diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst
index 8d495da26e34b..a447eefc55e44 100644
--- a/Doc/c-api/init.rst
+++ b/Doc/c-api/init.rst
@@ -827,8 +827,11 @@ code, or when embedding the Python interpreter:
.. c:type:: PyThreadState
This data structure represents the state of a single thread. The only public
- data member is :attr:`interp` (:c:expr:`PyInterpreterState *`), which points to
- this thread's interpreter state.
+ data member is:
+
+ .. c:member:: PyInterpreterState *interp
+
+ This thread's interpreter state.
.. c:function:: PyThreadState* PyEval_SaveThread()
diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst
index cdf09199ecbb5..747cfa62294c2 100644
--- a/Doc/c-api/structures.rst
+++ b/Doc/c-api/structures.rst
@@ -35,7 +35,7 @@ under :ref:`reference counting <countingrefs>`.
.. c:type:: PyVarObject
- This is an extension of :c:type:`PyObject` that adds the :attr:`ob_size`
+ This is an extension of :c:type:`PyObject` that adds the :c:member:`~PyVarObject.ob_size`
field. This is only used for objects that have some notion of *length*.
This type does not often appear in the Python/C API.
Access to the members must be done by using the macros
@@ -152,7 +152,7 @@ under :ref:`reference counting <countingrefs>`.
.. c:macro:: PyVarObject_HEAD_INIT(type, size)
This is a macro which expands to initialization values for a new
- :c:type:`PyVarObject` type, including the :attr:`ob_size` field.
+ :c:type:`PyVarObject` type, including the :c:member:`~PyVarObject.ob_size` field.
This macro expands to::
_PyObject_EXTRA_INIT
@@ -228,21 +228,21 @@ Implementing functions and methods
Structure used to describe a method of an extension type. This structure has
four fields:
- .. c:member:: const char* ml_name
+ .. c:member:: const char *ml_name
- name of the method
+ Name of the method.
.. c:member:: PyCFunction ml_meth
- pointer to the C implementation
+ Pointer to the C implementation.
.. c:member:: int ml_flags
- flags bits indicating how the call should be constructed
+ Flags bits indicating how the call should be constructed.
- .. c:member:: const char* ml_doc
+ .. c:member:: const char *ml_doc
- points to the contents of the docstring
+ Points to the contents of the docstring.
The :c:member:`~PyMethodDef.ml_meth` is a C function pointer.
The functions may be of different
diff --git a/Doc/c-api/tuple.rst b/Doc/c-api/tuple.rst
index 2277a39c95906..d1c9521944705 100644
--- a/Doc/c-api/tuple.rst
+++ b/Doc/c-api/tuple.rst
@@ -167,7 +167,8 @@ type.
Describes a field of a struct sequence. As a struct sequence is modeled as a
tuple, all fields are typed as :c:expr:`PyObject*`. The index in the
- :attr:`fields` array of the :c:type:`PyStructSequence_Desc` determines which
+ :c:member:`~PyStructSequence_Desc.fields` array of
+ the :c:type:`PyStructSequence_Desc` determines which
field of the struct sequence is described.
+-----------+------------------+-----------------------------------------+
diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst
index 7abb4774fb11f..04f426d982bbb 100644
--- a/Doc/c-api/typeobj.rst
+++ b/Doc/c-api/typeobj.rst
@@ -485,17 +485,17 @@ PyObject Slots
--------------
The type object structure extends the :c:type:`PyVarObject` structure. The
-:attr:`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 :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 :attr:`ob_size` field.
+type objects) *must* have the :c:member:`~PyVarObject.ob_size` field.
.. c:member:: Py_ssize_t PyObject.ob_refcnt
This is the type object's reference count, initialized to ``1`` by the
``PyObject_HEAD_INIT`` macro. Note that for :ref:`statically allocated type
- objects <static-types>`, the type's instances (objects whose :attr:`ob_type`
+ objects <static-types>`, the type's instances (objects whose :c:member:`~PyObject.ob_type`
points back to the type) do *not* count as references. But for
:ref:`dynamically allocated type objects <heap-types>`, the instances *do*
count as references.
@@ -519,8 +519,8 @@ type objects) *must* have the :attr:`ob_size` field.
Foo_Type.ob_type = &PyType_Type;
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,
- initializes it to the :attr:`ob_type` field of the base class.
+ :c:func:`PyType_Ready` checks if :c:member:`~PyObject.ob_type` is ``NULL``, and if so,
+ initializes it to the :c:member:`~PyObject.ob_type` field of the base class.
:c:func:`PyType_Ready` will not change this field if it is non-zero.
**Inheritance:**
@@ -619,20 +619,20 @@ and :c:data:`PyType_Type` effectively act as defaults.)
instances have the same size, given in :c:member:`~PyTypeObject.tp_basicsize`.
For a type with variable-length instances, the instances must have an
- :attr:`ob_size` field, and the instance size is :c:member:`~PyTypeObject.tp_basicsize` plus N
+ :c:member:`~PyVarObject.ob_size` field, and the instance size is :c:member:`~PyTypeObject.tp_basicsize` plus N
times :c:member:`~PyTypeObject.tp_itemsize`, where N is the "length" of the object. The value of
- N is typically stored in the instance's :attr:`ob_size` field. There are
- exceptions: for example, ints use a negative :attr:`ob_size` to indicate a
+ N is typically stored in the instance's :c:member:`~PyVarObject.ob_size` field. There are
+ exceptions: for example, ints use a negative :c:member:`~PyVarObject.ob_size` to indicate a
negative number, and N is ``abs(ob_size)`` there. Also, the presence of an
- :attr:`ob_size` field in the instance layout doesn't mean that the instance
+ :c:member:`~PyVarObject.ob_size` field in the instance layout doesn't mean that the instance
structure is variable-length (for example, the structure for the list type has
- fixed-length instances, yet those instances have a meaningful :attr:`ob_size`
+ fixed-length instances, yet those instances have a meaningful :c:member:`~PyVarObject.ob_size`
field).
The basic size includes the fields in the instance declared by the macro
:c:macro:`PyObject_HEAD` or :c:macro:`PyObject_VAR_HEAD` (whichever is used to
- declare the instance struct) and this in turn includes the :attr:`_ob_prev` and
- :attr:`_ob_next` fields if they are present. This means that the only correct
+ declare the instance struct) and this in turn includes the :c:member:`~PyObject._ob_prev` and
+ :c:member:`~PyObject._ob_next` fields if they are present. This means that the only correct
way to get an initializer for the :c:member:`~PyTypeObject.tp_basicsize` is to use the
``sizeof`` operator on the struct used to declare the instance layout.
The basic size does not include the GC header size.
@@ -764,7 +764,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
**Inheritance:**
- Group: :attr:`tp_getattr`, :attr:`tp_getattro`
+ Group: :c:member:`~PyTypeObject.tp_getattr`, :c:member:`~PyTypeObject.tp_getattro`
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
@@ -781,7 +781,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
**Inheritance:**
- Group: :attr:`tp_setattr`, :attr:`tp_setattro`
+ Group: :c:member:`~PyTypeObject.tp_setattr`, :c:member:`~PyTypeObject.tp_setattro`
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
@@ -883,7 +883,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
normal return value; when an error occurs during the computation of the hash
value, the function should set an exception and return ``-1``.
- When this field is not set (*and* :attr:`tp_richcompare` is not set),
+ When this field is not set (*and* :c:member:`~PyTypeObject.tp_richcompare` is not set),
an attempt to take the hash of the object raises :exc:`TypeError`.
This is the same as setting it to :c:func:`PyObject_HashNotImplemented`.
@@ -897,7 +897,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
**Inheritance:**
- Group: :attr:`tp_hash`, :attr:`tp_richcompare`
+ Group: :c:member:`~PyTypeObject.tp_hash`, :c:member:`~PyTypeObject.tp_richcompare`
This field is inherited by subtypes together with
:c:member:`~PyTypeObject.tp_richcompare`: a subtype inherits both of
@@ -956,7 +956,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
**Inheritance:**
- Group: :attr:`tp_getattr`, :attr:`tp_getattro`
+ Group: :c:member:`~PyTypeObject.tp_getattr`, :c:member:`~PyTypeObject.tp_getattro`
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
@@ -982,7 +982,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
**Inheritance:**
- Group: :attr:`tp_setattr`, :attr:`tp_setattro`
+ Group: :c:member:`~PyTypeObject.tp_setattr`, :c:member:`~PyTypeObject.tp_setattro`
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
@@ -1047,7 +1047,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
This bit is set when the type object itself is allocated on the heap, for
example, types created dynamically using :c:func:`PyType_FromSpec`. In this
- case, the :attr:`ob_type` field of its instances is considered a reference to
+ case, the :c:member:`~PyObject.ob_type` field of its instances is considered a reference to
the type, and the type object is INCREF'ed when a new instance is created, and
DECREF'ed when an instance is destroyed (this does not apply to instances of
subtypes; only the type referenced by the instance's ob_type gets INCREF'ed or
@@ -1100,13 +1100,13 @@ and :c:data:`PyType_Type` effectively act as defaults.)
**Inheritance:**
- Group: :c:macro:`Py_TPFLAGS_HAVE_GC`, :attr:`tp_traverse`, :attr:`tp_clear`
+ Group: :c:macro:`Py_TPFLAGS_HAVE_GC`, :c:member:`~PyTypeObject.tp_traverse`, :c:member:`~PyTypeObject.tp_clear`
The :c:macro:`Py_TPFLAGS_HAVE_GC` flag bit is inherited
- together with the :attr:`tp_traverse` and :attr:`tp_clear`
+ together with the :c:member:`~PyTypeObject.tp_traverse` and :c:member:`~PyTypeObject.tp_clear`
fields, i.e. if the :c:macro:`Py_TPFLAGS_HAVE_GC` flag bit is
- clear in the subtype and the :attr:`tp_traverse` and
- :attr:`tp_clear` fields in the subtype exist and have ``NULL``
+ clear in the subtype and the :c:member:`~PyTypeObject.tp_traverse` and
+ :c:member:`~PyTypeObject.tp_clear` fields in the subtype exist and have ``NULL``
values.
@@ -1421,7 +1421,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
**Inheritance:**
- Group: :c:macro:`Py_TPFLAGS_HAVE_GC`, :attr:`tp_traverse`, :attr:`tp_clear`
+ Group: :c:macro:`Py_TPFLAGS_HAVE_GC`, :c:member:`~PyTypeObject.tp_traverse`, :c:member:`~PyTypeObject.tp_clear`
This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_clear` and the
:c:macro:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :c:member:`~PyTypeObject.tp_traverse`, and
@@ -1488,7 +1488,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
**Inheritance:**
- Group: :c:macro:`Py_TPFLAGS_HAVE_GC`, :attr:`tp_traverse`, :attr:`tp_clear`
+ Group: :c:macro:`Py_TPFLAGS_HAVE_GC`, :c:member:`~PyTypeObject.tp_traverse`, :c:member:`~PyTypeObject.tp_clear`
This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_traverse` and the
:c:macro:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :c:member:`~PyTypeObject.tp_traverse`, and
@@ -1547,7 +1547,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
**Inheritance:**
- Group: :attr:`tp_hash`, :attr:`tp_richcompare`
+ Group: :c:member:`~PyTypeObject.tp_hash`, :c:member:`~PyTypeObject.tp_richcompare`
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
@@ -1556,9 +1556,9 @@ and :c:data:`PyType_Type` effectively act as defaults.)
**Default:**
- :c:data:`PyBaseObject_Type` provides a :attr:`tp_richcompare`
+ :c:data:`PyBaseObject_Type` provides a :c:member:`~PyTypeObject.tp_richcompare`
implementation, which may be inherited. However, if only
- :attr:`tp_hash` is defined, not even the inherited function is used
+ :c:member:`~PyTypeObject.tp_hash` is defined, not even the inherited function is used
and instances of the type will not be able to participate in any
comparisons.
@@ -2374,9 +2374,9 @@ Sequence Object Structures
This slot must be filled for the :c:func:`PySequence_Check`
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 :c:member:`~PySequenceMethods.sq_length` slot is
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 :c:member:`~PySequenceMethods.sq_item`. If :c:member:`!sq_length` is ``NULL``,
the index is passed as is to the function.
.. c:member:: ssizeobjargproc PySequenceMethods.sq_ass_item
@@ -2586,8 +2586,8 @@ Slot Type typedefs
The purpose of this function is to separate memory allocation from memory
initialization. It should return a pointer to a block of memory of adequate
length for the instance, suitably aligned, and initialized to zeros, but with
- :attr:`ob_refcnt` set to ``1`` and :attr:`ob_type` set to the type argument. If
- the type's :c:member:`~PyTypeObject.tp_itemsize` is non-zero, the object's :attr:`ob_size` field
+ :c:member:`~PyObject.ob_refcnt` set to ``1`` and :c:member:`~PyObject.ob_type` set to the type argument. If
+ the type's :c:member:`~PyTypeObject.tp_itemsize` is non-zero, the object's :c:member:`~PyVarObject.ob_size` field
should be initialized to *nitems* and the length of the allocated memory block
should be ``tp_basicsize + nitems*tp_itemsize``, rounded up to a multiple of
``sizeof(void*)``; otherwise, *nitems* is not used and the length of the block
diff --git a/Doc/c-api/veryhigh.rst b/Doc/c-api/veryhigh.rst
index a19c274d05f2c..324518c035096 100644
--- a/Doc/c-api/veryhigh.rst
+++ b/Doc/c-api/veryhigh.rst
@@ -353,7 +353,7 @@ the same library that the Python runtime is using.
executed, it is passed as ``PyCompilerFlags *flags``. In this case, ``from
__future__ import`` can modify *flags*.
- Whenever ``PyCompilerFlags *flags`` is ``NULL``, :c:member:`cf_flags` is treated as
+ Whenever ``PyCompilerFlags *flags`` is ``NULL``, :c:member:`~PyCompilerFlags.cf_flags` is treated as
equal to ``0``, and any modification due to ``from __future__ import`` is
discarded.
@@ -367,7 +367,7 @@ the same library that the Python runtime is using.
initialized to ``PY_MINOR_VERSION``.
The field is ignored by default, it is used if and only if
- ``PyCF_ONLY_AST`` flag is set in *cf_flags*.
+ ``PyCF_ONLY_AST`` flag is set in :c:member:`~PyCompilerFlags.cf_flags`.
.. versionchanged:: 3.8
Added *cf_feature_version* field.
diff --git a/Doc/extending/newtypes.rst b/Doc/extending/newtypes.rst
index 7f8f8ddaaaccd..25822744125f8 100644
--- a/Doc/extending/newtypes.rst
+++ b/Doc/extending/newtypes.rst
@@ -270,7 +270,7 @@ structure::
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
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``.
+:c:member:`~PyMethodDef.ml_name` field of the sentinel must be ``NULL``.
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
diff --git a/Doc/extending/newtypes_tutorial.rst b/Doc/extending/newtypes_tutorial.rst
index 67382dfcb759b..0cc366b9c0b51 100644
--- a/Doc/extending/newtypes_tutorial.rst
+++ b/Doc/extending/newtypes_tutorial.rst
@@ -177,7 +177,7 @@ Everything else in the file should be familiar, except for some code in
return;
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 :c:member:`~PyObject.ob_type` that we initially
set to ``NULL``. ::
if (PyModule_AddObjectRef(m, "Custom", (PyObject *) &CustomType) < 0) {
diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore
index cb98e97668d5c..08f215f035d0b 100644
--- a/Doc/tools/.nitignore
+++ b/Doc/tools/.nitignore
@@ -11,7 +11,6 @@ Doc/c-api/exceptions.rst
Doc/c-api/file.rst
Doc/c-api/float.rst
Doc/c-api/gcsupport.rst
-Doc/c-api/import.rst
Doc/c-api/init.rst
Doc/c-api/init_config.rst
Doc/c-api/intro.rst
diff --git a/Doc/whatsnew/2.5.rst b/Doc/whatsnew/2.5.rst
index ec4a7eb9a2361..2bb681bddedbb 100644
--- a/Doc/whatsnew/2.5.rst
+++ b/Doc/whatsnew/2.5.rst
@@ -954,7 +954,7 @@ The return value must be either a Python integer or long integer. The
interpreter will check that the type returned is correct, and raises a
:exc:`TypeError` if this requirement isn't met.
-A corresponding :attr:`nb_index` slot was added to the C-level
+A corresponding :c:member:`~PyNumberMethods.nb_index` slot was added to the C-level
:c:type:`PyNumberMethods` structure to let C extensions implement this protocol.
``PyNumber_Index(obj)`` can be used in extension code to call the
:meth:`__index__` function and retrieve its result.
diff --git a/Misc/NEWS.d/next/Core and Builtins/2023-05-30-08-09-43.gh-issue-105035.OWUlHy.rst b/Misc/NEWS.d/next/Core and Builtins/2023-05-30-08-09-43.gh-issue-105035.OWUlHy.rst
index c0ee2da9d4503..dbfcd658d945d 100644
--- a/Misc/NEWS.d/next/Core and Builtins/2023-05-30-08-09-43.gh-issue-105035.OWUlHy.rst
+++ b/Misc/NEWS.d/next/Core and Builtins/2023-05-30-08-09-43.gh-issue-105035.OWUlHy.rst
@@ -1,2 +1,2 @@
-Fix :func:`super` calls on types with custom :attr:`tp_getattro`
+Fix :func:`super` calls on types with custom :c:member:`~PyTypeObject.tp_getattro`
implementation (e.g. meta-types.)
More information about the Python-checkins
mailing list