Skip to content

Commit ac9aa8a

Browse files
[3.12] gh-106919: Use role :c:macro: for referencing the C "constants" (GH-106920) (GH-106951)
(cherry picked from commit fcc816d)
1 parent 807afda commit ac9aa8a

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

46 files changed

+310
-292
lines changed

Doc/c-api/arg.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -343,7 +343,7 @@ Other objects
343343
*items*. Format units for sequences may be nested.
344344

345345
It is possible to pass "long" integers (integers whose value exceeds the
346-
platform's :const:`LONG_MAX`) however no proper range checking is done --- the
346+
platform's :c:macro:`LONG_MAX`) however no proper range checking is done --- the
347347
most significant bits are silently truncated when the receiving field is too
348348
small to receive the value (actually, the semantics are inherited from downcasts
349349
in C --- your mileage may vary).
@@ -455,7 +455,7 @@ API Functions
455455
456456
A simpler form of parameter retrieval which does not use a format string to
457457
specify the types of the arguments. Functions which use this method to retrieve
458-
their parameters should be declared as :const:`METH_VARARGS` in function or
458+
their parameters should be declared as :c:macro:`METH_VARARGS` in function or
459459
method tables. The tuple containing the actual parameters should be passed as
460460
*args*; it must actually be a tuple. The length of the tuple must be at least
461461
*min* and no more than *max*; *min* and *max* may be equal. Additional

Doc/c-api/call.rst

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -59,20 +59,20 @@ This bears repeating:
5959

6060
.. versionchanged:: 3.12
6161

62-
The :const:`Py_TPFLAGS_HAVE_VECTORCALL` flag is now removed from a class
62+
The :c:macro:`Py_TPFLAGS_HAVE_VECTORCALL` flag is now removed from a class
6363
when the class's :py:meth:`~object.__call__` method is reassigned.
6464
(This internally sets :c:member:`~PyTypeObject.tp_call` only, and thus
6565
may make it behave differently than the vectorcall function.)
6666
In earlier Python versions, vectorcall should only be used with
67-
:const:`immutable <Py_TPFLAGS_IMMUTABLETYPE>` or static types.
67+
:c:macro:`immutable <Py_TPFLAGS_IMMUTABLETYPE>` or static types.
6868

6969
A class should not implement vectorcall if that would be slower
7070
than *tp_call*. For example, if the callee needs to convert
7171
the arguments to an args tuple and kwargs dict anyway, then there is no point
7272
in implementing vectorcall.
7373

7474
Classes can implement the vectorcall protocol by enabling the
75-
:const:`Py_TPFLAGS_HAVE_VECTORCALL` flag and setting
75+
:c:macro:`Py_TPFLAGS_HAVE_VECTORCALL` flag and setting
7676
:c:member:`~PyTypeObject.tp_vectorcall_offset` to the offset inside the
7777
object structure where a *vectorcallfunc* appears.
7878
This is a pointer to a function with the following signature:
@@ -84,7 +84,7 @@ This is a pointer to a function with the following signature:
8484
values of the keyword arguments.
8585
This can be *NULL* if there are no arguments.
8686
- *nargsf* is the number of positional arguments plus possibly the
87-
:const:`PY_VECTORCALL_ARGUMENTS_OFFSET` flag.
87+
:c:macro:`PY_VECTORCALL_ARGUMENTS_OFFSET` flag.
8888
To get the actual number of positional arguments from *nargsf*,
8989
use :c:func:`PyVectorcall_NARGS`.
9090
- *kwnames* is a tuple containing the names of the keyword arguments;
@@ -93,7 +93,7 @@ This is a pointer to a function with the following signature:
9393
and they must be unique.
9494
If there are no keyword arguments, then *kwnames* can instead be *NULL*.
9595

96-
.. data:: PY_VECTORCALL_ARGUMENTS_OFFSET
96+
.. c:macro:: PY_VECTORCALL_ARGUMENTS_OFFSET
9797
9898
If this flag is set in a vectorcall *nargsf* argument, the callee is allowed
9999
to temporarily change ``args[-1]``. In other words, *args* points to
@@ -104,7 +104,7 @@ This is a pointer to a function with the following signature:
104104
``args[0]`` may be changed.
105105

106106
Whenever they can do so cheaply (without additional allocation), callers
107-
are encouraged to use :const:`PY_VECTORCALL_ARGUMENTS_OFFSET`.
107+
are encouraged to use :c:macro:`PY_VECTORCALL_ARGUMENTS_OFFSET`.
108108
Doing so will allow callables such as bound methods to make their onward
109109
calls (which include a prepended *self* argument) very efficiently.
110110

@@ -174,7 +174,7 @@ Vectorcall Support API
174174
175175
This is a specialized function, intended to be put in the
176176
:c:member:`~PyTypeObject.tp_call` slot or be used in an implementation of ``tp_call``.
177-
It does not check the :const:`Py_TPFLAGS_HAVE_VECTORCALL` flag
177+
It does not check the :c:macro:`Py_TPFLAGS_HAVE_VECTORCALL` flag
178178
and it does not fall back to ``tp_call``.
179179
180180
.. versionadded:: 3.8
@@ -392,11 +392,11 @@ please see individual documentation for details.
392392
*args[0]*, and the *args* array starting at *args[1]* represents the arguments
393393
of the call. There must be at least one positional argument.
394394
*nargsf* is the number of positional arguments including *args[0]*,
395-
plus :const:`PY_VECTORCALL_ARGUMENTS_OFFSET` if the value of ``args[0]`` may
395+
plus :c:macro:`PY_VECTORCALL_ARGUMENTS_OFFSET` if the value of ``args[0]`` may
396396
temporarily be changed. Keyword arguments can be passed just like in
397397
:c:func:`PyObject_Vectorcall`.
398398
399-
If the object has the :const:`Py_TPFLAGS_METHOD_DESCRIPTOR` feature,
399+
If the object has the :c:macro:`Py_TPFLAGS_METHOD_DESCRIPTOR` feature,
400400
this will call the unbound method object with the full
401401
*args* vector as arguments.
402402

Doc/c-api/complex.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,7 @@ pointers. This is consistent throughout the API.
6464
representation.
6565
6666
If *divisor* is null, this method returns zero and sets
67-
:c:data:`errno` to :c:data:`EDOM`.
67+
:c:data:`errno` to :c:macro:`EDOM`.
6868
6969
7070
.. c:function:: Py_complex _Py_c_pow(Py_complex num, Py_complex exp)
@@ -73,7 +73,7 @@ pointers. This is consistent throughout the API.
7373
representation.
7474
7575
If *num* is null and *exp* is not a positive real number,
76-
this method returns zero and sets :c:data:`errno` to :c:data:`EDOM`.
76+
this method returns zero and sets :c:data:`errno` to :c:macro:`EDOM`.
7777
7878
7979
Complex Numbers as Python Objects

Doc/c-api/exceptions.rst

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -165,7 +165,7 @@ For convenience, some of these functions will always return a
165165
tuple object whose first item is the integer :c:data:`errno` value and whose
166166
second item is the corresponding error message (gotten from :c:func:`strerror`),
167167
and then calls ``PyErr_SetObject(type, object)``. On Unix, when the
168-
:c:data:`errno` value is :const:`EINTR`, indicating an interrupted system call,
168+
:c:data:`errno` value is :c:macro:`EINTR`, indicating an interrupted system call,
169169
this calls :c:func:`PyErr_CheckSignals`, and if that set the error indicator,
170170
leaves it set to that. The function always returns ``NULL``, so a wrapper
171171
function around a system call can write ``return PyErr_SetFromErrno(type);``
@@ -631,7 +631,7 @@ Signal Handling
631631
be interruptible by user requests (such as by pressing Ctrl-C).
632632
633633
.. note::
634-
The default Python signal handler for :const:`SIGINT` raises the
634+
The default Python signal handler for :c:macro:`SIGINT` raises the
635635
:exc:`KeyboardInterrupt` exception.
636636
637637
@@ -642,7 +642,7 @@ Signal Handling
642642
single: SIGINT
643643
single: KeyboardInterrupt (built-in exception)
644644
645-
Simulate the effect of a :const:`SIGINT` signal arriving.
645+
Simulate the effect of a :c:macro:`SIGINT` signal arriving.
646646
This is equivalent to ``PyErr_SetInterruptEx(SIGINT)``.
647647
648648
.. note::
@@ -754,7 +754,7 @@ Exception Objects
754754
755755
.. c:function:: PyObject* PyException_GetCause(PyObject *ex)
756756
757-
Return the cause (either an exception instance, or :const:`None`,
757+
Return the cause (either an exception instance, or ``None``,
758758
set by ``raise ... from ...``) associated with the exception as a new
759759
reference, as accessible from Python through :attr:`__cause__`.
760760
@@ -763,7 +763,7 @@ Exception Objects
763763
764764
Set the cause associated with the exception to *cause*. Use ``NULL`` to clear
765765
it. There is no type check to make sure that *cause* is either an exception
766-
instance or :const:`None`. This steals a reference to *cause*.
766+
instance or ``None``. This steals a reference to *cause*.
767767
768768
:attr:`__suppress_context__` is implicitly set to ``True`` by this function.
769769
@@ -874,7 +874,7 @@ because the :ref:`call protocol <call>` takes care of recursion handling.
874874
875875
Marks a point where a recursive C-level call is about to be performed.
876876
877-
If :const:`USE_STACKCHECK` is defined, this function checks if the OS
877+
If :c:macro:`USE_STACKCHECK` is defined, this function checks if the OS
878878
stack overflowed using :c:func:`PyOS_CheckStack`. In this is the case, it
879879
sets a :exc:`MemoryError` and returns a nonzero value.
880880

Doc/c-api/file.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -93,7 +93,7 @@ the :mod:`io` APIs instead.
9393
.. index:: single: Py_PRINT_RAW
9494
9595
Write object *obj* to file object *p*. The only supported flag for *flags* is
96-
:const:`Py_PRINT_RAW`; if given, the :func:`str` of the object is written
96+
:c:macro:`Py_PRINT_RAW`; if given, the :func:`str` of the object is written
9797
instead of the :func:`repr`. Return ``0`` on success or ``-1`` on failure; the
9898
appropriate exception will be set.
9999

Doc/c-api/float.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -109,7 +109,7 @@ Pack functions
109109
The pack routines write 2, 4 or 8 bytes, starting at *p*. *le* is an
110110
:c:expr:`int` argument, non-zero if you want the bytes string in little-endian
111111
format (exponent last, at ``p+1``, ``p+3``, or ``p+6`` ``p+7``), zero if you
112-
want big-endian format (exponent first, at *p*). The :c:data:`PY_BIG_ENDIAN`
112+
want big-endian format (exponent first, at *p*). The :c:macro:`PY_BIG_ENDIAN`
113113
constant can be used to use the native endian: it is equal to ``1`` on big
114114
endian processor, or ``0`` on little endian processor.
115115
@@ -140,7 +140,7 @@ Unpack functions
140140
The unpack routines read 2, 4 or 8 bytes, starting at *p*. *le* is an
141141
:c:expr:`int` argument, non-zero if the bytes string is in little-endian format
142142
(exponent last, at ``p+1``, ``p+3`` or ``p+6`` and ``p+7``), zero if big-endian
143-
(exponent first, at *p*). The :c:data:`PY_BIG_ENDIAN` constant can be used to
143+
(exponent first, at *p*). The :c:macro:`PY_BIG_ENDIAN` constant can be used to
144144
use the native endian: it is equal to ``1`` on big endian processor, or ``0``
145145
on little endian processor.
146146

Doc/c-api/gcsupport.rst

Lines changed: 5 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -13,14 +13,12 @@ or strings), do not need to provide any explicit support for garbage
1313
collection.
1414

1515
To create a container type, the :c:member:`~PyTypeObject.tp_flags` field of the type object must
16-
include the :const:`Py_TPFLAGS_HAVE_GC` and provide an implementation of the
16+
include the :c:macro:`Py_TPFLAGS_HAVE_GC` and provide an implementation of the
1717
:c:member:`~PyTypeObject.tp_traverse` handler. If instances of the type are mutable, a
1818
:c:member:`~PyTypeObject.tp_clear` implementation must also be provided.
1919

2020

21-
.. data:: Py_TPFLAGS_HAVE_GC
22-
:noindex:
23-
21+
:c:macro:`Py_TPFLAGS_HAVE_GC`
2422
Objects with a type with this flag set must conform with the rules
2523
documented here. For convenience these objects will be referred to as
2624
container objects.
@@ -52,17 +50,17 @@ rules:
5250
:c:member:`~PyTypeObject.tp_flags`, :c:member:`~PyTypeObject.tp_traverse`
5351
and :c:member:`~PyTypeObject.tp_clear` fields if the type inherits from a
5452
class that implements the garbage collector protocol and the child class
55-
does *not* include the :const:`Py_TPFLAGS_HAVE_GC` flag.
53+
does *not* include the :c:macro:`Py_TPFLAGS_HAVE_GC` flag.
5654

5755
.. c:function:: TYPE* PyObject_GC_New(TYPE, PyTypeObject *type)
5856
5957
Analogous to :c:func:`PyObject_New` but for container objects with the
60-
:const:`Py_TPFLAGS_HAVE_GC` flag set.
58+
:c:macro:`Py_TPFLAGS_HAVE_GC` flag set.
6159
6260
.. c:function:: TYPE* PyObject_GC_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size)
6361
6462
Analogous to :c:func:`PyObject_NewVar` but for container objects with the
65-
:const:`Py_TPFLAGS_HAVE_GC` flag set.
63+
:c:macro:`Py_TPFLAGS_HAVE_GC` flag set.
6664
6765
.. c:function:: PyObject* PyUnstable_Object_GC_NewWithExtraData(PyTypeObject *type, size_t extra_size)
6866

Doc/c-api/init.rst

Lines changed: 31 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1396,7 +1396,7 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
13961396
function does not steal any references to *exc*. To prevent naive misuse, you
13971397
must write your own C extension to call this. Must be called with the GIL held.
13981398
Returns the number of thread states modified; this is normally one, but will be
1399-
zero if the thread id isn't found. If *exc* is :const:`NULL`, the pending
1399+
zero if the thread id isn't found. If *exc* is ``NULL``, the pending
14001400
exception (if any) for the thread is cleared. This raises no exceptions.
14011401
14021402
.. versionchanged:: 3.7
@@ -1675,32 +1675,32 @@ Python-level trace functions in previous versions.
16751675
The type of the trace function registered using :c:func:`PyEval_SetProfile` and
16761676
:c:func:`PyEval_SetTrace`. The first parameter is the object passed to the
16771677
registration function as *obj*, *frame* is the frame object to which the event
1678-
pertains, *what* is one of the constants :const:`PyTrace_CALL`,
1679-
:const:`PyTrace_EXCEPTION`, :const:`PyTrace_LINE`, :const:`PyTrace_RETURN`,
1680-
:const:`PyTrace_C_CALL`, :const:`PyTrace_C_EXCEPTION`, :const:`PyTrace_C_RETURN`,
1681-
or :const:`PyTrace_OPCODE`, and *arg* depends on the value of *what*:
1682-
1683-
+------------------------------+----------------------------------------+
1684-
| Value of *what* | Meaning of *arg* |
1685-
+==============================+========================================+
1686-
| :const:`PyTrace_CALL` | Always :c:data:`Py_None`. |
1687-
+------------------------------+----------------------------------------+
1688-
| :const:`PyTrace_EXCEPTION` | Exception information as returned by |
1689-
| | :func:`sys.exc_info`. |
1690-
+------------------------------+----------------------------------------+
1691-
| :const:`PyTrace_LINE` | Always :c:data:`Py_None`. |
1692-
+------------------------------+----------------------------------------+
1693-
| :const:`PyTrace_RETURN` | Value being returned to the caller, |
1694-
| | or ``NULL`` if caused by an exception. |
1695-
+------------------------------+----------------------------------------+
1696-
| :const:`PyTrace_C_CALL` | Function object being called. |
1697-
+------------------------------+----------------------------------------+
1698-
| :const:`PyTrace_C_EXCEPTION` | Function object being called. |
1699-
+------------------------------+----------------------------------------+
1700-
| :const:`PyTrace_C_RETURN` | Function object being called. |
1701-
+------------------------------+----------------------------------------+
1702-
| :const:`PyTrace_OPCODE` | Always :c:data:`Py_None`. |
1703-
+------------------------------+----------------------------------------+
1678+
pertains, *what* is one of the constants :c:data:`PyTrace_CALL`,
1679+
:c:data:`PyTrace_EXCEPTION`, :c:data:`PyTrace_LINE`, :c:data:`PyTrace_RETURN`,
1680+
:c:data:`PyTrace_C_CALL`, :c:data:`PyTrace_C_EXCEPTION`, :c:data:`PyTrace_C_RETURN`,
1681+
or :c:data:`PyTrace_OPCODE`, and *arg* depends on the value of *what*:
1682+
1683+
+-------------------------------+----------------------------------------+
1684+
| Value of *what* | Meaning of *arg* |
1685+
+===============================+========================================+
1686+
| :c:data:`PyTrace_CALL` | Always :c:data:`Py_None`. |
1687+
+-------------------------------+----------------------------------------+
1688+
| :c:data:`PyTrace_EXCEPTION` | Exception information as returned by |
1689+
| | :func:`sys.exc_info`. |
1690+
+-------------------------------+----------------------------------------+
1691+
| :c:data:`PyTrace_LINE` | Always :c:data:`Py_None`. |
1692+
+-------------------------------+----------------------------------------+
1693+
| :c:data:`PyTrace_RETURN` | Value being returned to the caller, |
1694+
| | or ``NULL`` if caused by an exception. |
1695+
+-------------------------------+----------------------------------------+
1696+
| :c:data:`PyTrace_C_CALL` | Function object being called. |
1697+
+-------------------------------+----------------------------------------+
1698+
| :c:data:`PyTrace_C_EXCEPTION` | Function object being called. |
1699+
+-------------------------------+----------------------------------------+
1700+
| :c:data:`PyTrace_C_RETURN` | Function object being called. |
1701+
+-------------------------------+----------------------------------------+
1702+
| :c:data:`PyTrace_OPCODE` | Always :c:data:`Py_None`. |
1703+
+-------------------------------+----------------------------------------+
17041704
17051705
.. c:var:: int PyTrace_CALL
17061706
@@ -1767,8 +1767,8 @@ Python-level trace functions in previous versions.
17671767
function as its first parameter, and may be any Python object, or ``NULL``. If
17681768
the profile function needs to maintain state, using a different value for *obj*
17691769
for each thread provides a convenient and thread-safe place to store it. The
1770-
profile function is called for all monitored events except :const:`PyTrace_LINE`
1771-
:const:`PyTrace_OPCODE` and :const:`PyTrace_EXCEPTION`.
1770+
profile function is called for all monitored events except :c:data:`PyTrace_LINE`
1771+
:c:data:`PyTrace_OPCODE` and :c:data:`PyTrace_EXCEPTION`.
17721772
17731773
See also the :func:`sys.setprofile` function.
17741774
@@ -1793,8 +1793,8 @@ Python-level trace functions in previous versions.
17931793
:c:func:`PyEval_SetProfile`, except the tracing function does receive line-number
17941794
events and per-opcode events, but does not receive any event related to C function
17951795
objects being called. Any trace function registered using :c:func:`PyEval_SetTrace`
1796-
will not receive :const:`PyTrace_C_CALL`, :const:`PyTrace_C_EXCEPTION` or
1797-
:const:`PyTrace_C_RETURN` as a value for the *what* parameter.
1796+
will not receive :c:data:`PyTrace_C_CALL`, :c:data:`PyTrace_C_EXCEPTION` or
1797+
:c:data:`PyTrace_C_RETURN` as a value for the *what* parameter.
17981798
17991799
See also the :func:`sys.settrace` function.
18001800

Doc/c-api/long.rst

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -142,8 +142,8 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
142142
instance of :c:type:`PyLongObject`, first call its :meth:`~object.__index__`
143143
method (if present) to convert it to a :c:type:`PyLongObject`.
144144
145-
If the value of *obj* is greater than :const:`LONG_MAX` or less than
146-
:const:`LONG_MIN`, set *\*overflow* to ``1`` or ``-1``, respectively, and
145+
If the value of *obj* is greater than :c:macro:`LONG_MAX` or less than
146+
:c:macro:`LONG_MIN`, set *\*overflow* to ``1`` or ``-1``, respectively, and
147147
return ``-1``; otherwise, set *\*overflow* to ``0``. If any other exception
148148
occurs set *\*overflow* to ``0`` and return ``-1`` as usual.
149149
@@ -183,8 +183,8 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
183183
instance of :c:type:`PyLongObject`, first call its :meth:`~object.__index__` method
184184
(if present) to convert it to a :c:type:`PyLongObject`.
185185
186-
If the value of *obj* is greater than :const:`LLONG_MAX` or less than
187-
:const:`LLONG_MIN`, set *\*overflow* to ``1`` or ``-1``, respectively,
186+
If the value of *obj* is greater than :c:macro:`LLONG_MAX` or less than
187+
:c:macro:`LLONG_MIN`, set *\*overflow* to ``1`` or ``-1``, respectively,
188188
and return ``-1``; otherwise, set *\*overflow* to ``0``. If any other
189189
exception occurs set *\*overflow* to ``0`` and return ``-1`` as usual.
190190

0 commit comments

Comments
 (0)