Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

gh-107091: Fix some uses of :attr: role (GH-107318) 

Fix also formatting of PyMethodDef members.
This commit is contained in:
Serhiy Storchaka 2023-07-27 08:52:54 +03:00 committed by GitHub
parent 8d61a71f9c
commit d363eb5b02
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
11 changed files with 64 additions and 59 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -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

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

@ -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()

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

@ -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

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

@ -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.
+-----------+------------------+-----------------------------------------+

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

@ -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

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

@ -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.

2
Doc/extending/newtypes.rst
View File

@ -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

2
Doc/extending/newtypes_tutorial.rst
View File

@ -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) {

1
Doc/tools/.nitignore
View File

@ -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

2
Doc/whatsnew/2.5.rst
View File

@ -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.

2
Misc/NEWS.d/next/Core and Builtins/2023-05-30-08-09-43.gh-issue-105035.OWUlHy.rst
View File

@ -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.)