Skip to content

Commit fcc816d

Browse files
serhiy-storchakaserhiy-storchaka
authored
gh-106919: Use role :c:macro: for referencing the C "constants" (GH-106920)
1 parent 81861fd commit fcc816d

Some content is hidden

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

47 files changed

+312
-294
lines changed

‎Doc/c-api/arg.rst

+2-2
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).
@@ -463,7 +463,7 @@ API Functions
463463
464464
A simpler form of parameter retrieval which does not use a format string to
465465
specify the types of the arguments. Functions which use this method to retrieve
466-
their parameters should be declared as :const:`METH_VARARGS` in function or
466+
their parameters should be declared as :c:macro:`METH_VARARGS` in function or
467467
method tables. The tuple containing the actual parameters should be passed as
468468
*args*; it must actually be a tuple. The length of the tuple must be at least
469469
*min* and no more than *max*; *min* and *max* may be equal. Additional

‎Doc/c-api/call.rst

+9-9
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

@@ -161,7 +161,7 @@ Vectorcall Support API
161161
162162
This is a specialized function, intended to be put in the
163163
:c:member:`~PyTypeObject.tp_call` slot or be used in an implementation of ``tp_call``.
164-
It does not check the :const:`Py_TPFLAGS_HAVE_VECTORCALL` flag
164+
It does not check the :c:macro:`Py_TPFLAGS_HAVE_VECTORCALL` flag
165165
and it does not fall back to ``tp_call``.
166166
167167
.. versionadded:: 3.8
@@ -379,11 +379,11 @@ please see individual documentation for details.
379379
*args[0]*, and the *args* array starting at *args[1]* represents the arguments
380380
of the call. There must be at least one positional argument.
381381
*nargsf* is the number of positional arguments including *args[0]*,
382-
plus :const:`PY_VECTORCALL_ARGUMENTS_OFFSET` if the value of ``args[0]`` may
382+
plus :c:macro:`PY_VECTORCALL_ARGUMENTS_OFFSET` if the value of ``args[0]`` may
383383
temporarily be changed. Keyword arguments can be passed just like in
384384
:c:func:`PyObject_Vectorcall`.
385385
386-
If the object has the :const:`Py_TPFLAGS_METHOD_DESCRIPTOR` feature,
386+
If the object has the :c:macro:`Py_TPFLAGS_METHOD_DESCRIPTOR` feature,
387387
this will call the unbound method object with the full
388388
*args* vector as arguments.
389389

‎Doc/c-api/complex.rst

+2-2
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

+6-6
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

+1-1
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

+2-2
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

+5-7
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

+31-31
Original file line numberDiff line numberDiff line change
@@ -1161,7 +1161,7 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
11611161
function does not steal any references to *exc*. To prevent naive misuse, you
11621162
must write your own C extension to call this. Must be called with the GIL held.
11631163
Returns the number of thread states modified; this is normally one, but will be
1164-
zero if the thread id isn't found. If *exc* is :const:`NULL`, the pending
1164+
zero if the thread id isn't found. If *exc* is ``NULL``, the pending
11651165
exception (if any) for the thread is cleared. This raises no exceptions.
11661166
11671167
.. versionchanged:: 3.7
@@ -1407,32 +1407,32 @@ Python-level trace functions in previous versions.
14071407
The type of the trace function registered using :c:func:`PyEval_SetProfile` and
14081408
:c:func:`PyEval_SetTrace`. The first parameter is the object passed to the
14091409
registration function as *obj*, *frame* is the frame object to which the event
1410-
pertains, *what* is one of the constants :const:`PyTrace_CALL`,
1411-
:const:`PyTrace_EXCEPTION`, :const:`PyTrace_LINE`, :const:`PyTrace_RETURN`,
1412-
:const:`PyTrace_C_CALL`, :const:`PyTrace_C_EXCEPTION`, :const:`PyTrace_C_RETURN`,
1413-
or :const:`PyTrace_OPCODE`, and *arg* depends on the value of *what*:
1414-
1415-
+------------------------------+----------------------------------------+
1416-
| Value of *what* | Meaning of *arg* |
1417-
+==============================+========================================+
1418-
| :const:`PyTrace_CALL` | Always :c:data:`Py_None`. |
1419-
+------------------------------+----------------------------------------+
1420-
| :const:`PyTrace_EXCEPTION` | Exception information as returned by |
1421-
| | :func:`sys.exc_info`. |
1422-
+------------------------------+----------------------------------------+
1423-
| :const:`PyTrace_LINE` | Always :c:data:`Py_None`. |
1424-
+------------------------------+----------------------------------------+
1425-
| :const:`PyTrace_RETURN` | Value being returned to the caller, |
1426-
| | or ``NULL`` if caused by an exception. |
1427-
+------------------------------+----------------------------------------+
1428-
| :const:`PyTrace_C_CALL` | Function object being called. |
1429-
+------------------------------+----------------------------------------+
1430-
| :const:`PyTrace_C_EXCEPTION` | Function object being called. |
1431-
+------------------------------+----------------------------------------+
1432-
| :const:`PyTrace_C_RETURN` | Function object being called. |
1433-
+------------------------------+----------------------------------------+
1434-
| :const:`PyTrace_OPCODE` | Always :c:data:`Py_None`. |
1435-
+------------------------------+----------------------------------------+
1410+
pertains, *what* is one of the constants :c:data:`PyTrace_CALL`,
1411+
:c:data:`PyTrace_EXCEPTION`, :c:data:`PyTrace_LINE`, :c:data:`PyTrace_RETURN`,
1412+
:c:data:`PyTrace_C_CALL`, :c:data:`PyTrace_C_EXCEPTION`, :c:data:`PyTrace_C_RETURN`,
1413+
or :c:data:`PyTrace_OPCODE`, and *arg* depends on the value of *what*:
1414+
1415+
+-------------------------------+----------------------------------------+
1416+
| Value of *what* | Meaning of *arg* |
1417+
+===============================+========================================+
1418+
| :c:data:`PyTrace_CALL` | Always :c:data:`Py_None`. |
1419+
+-------------------------------+----------------------------------------+
1420+
| :c:data:`PyTrace_EXCEPTION` | Exception information as returned by |
1421+
| | :func:`sys.exc_info`. |
1422+
+-------------------------------+----------------------------------------+
1423+
| :c:data:`PyTrace_LINE` | Always :c:data:`Py_None`. |
1424+
+-------------------------------+----------------------------------------+
1425+
| :c:data:`PyTrace_RETURN` | Value being returned to the caller, |
1426+
| | or ``NULL`` if caused by an exception. |
1427+
+-------------------------------+----------------------------------------+
1428+
| :c:data:`PyTrace_C_CALL` | Function object being called. |
1429+
+-------------------------------+----------------------------------------+
1430+
| :c:data:`PyTrace_C_EXCEPTION` | Function object being called. |
1431+
+-------------------------------+----------------------------------------+
1432+
| :c:data:`PyTrace_C_RETURN` | Function object being called. |
1433+
+-------------------------------+----------------------------------------+
1434+
| :c:data:`PyTrace_OPCODE` | Always :c:data:`Py_None`. |
1435+
+-------------------------------+----------------------------------------+
14361436
14371437
.. c:var:: int PyTrace_CALL
14381438
@@ -1499,8 +1499,8 @@ Python-level trace functions in previous versions.
14991499
function as its first parameter, and may be any Python object, or ``NULL``. If
15001500
the profile function needs to maintain state, using a different value for *obj*
15011501
for each thread provides a convenient and thread-safe place to store it. The
1502-
profile function is called for all monitored events except :const:`PyTrace_LINE`
1503-
:const:`PyTrace_OPCODE` and :const:`PyTrace_EXCEPTION`.
1502+
profile function is called for all monitored events except :c:data:`PyTrace_LINE`
1503+
:c:data:`PyTrace_OPCODE` and :c:data:`PyTrace_EXCEPTION`.
15041504
15051505
See also the :func:`sys.setprofile` function.
15061506
@@ -1525,8 +1525,8 @@ Python-level trace functions in previous versions.
15251525
:c:func:`PyEval_SetProfile`, except the tracing function does receive line-number
15261526
events and per-opcode events, but does not receive any event related to C function
15271527
objects being called. Any trace function registered using :c:func:`PyEval_SetTrace`
1528-
will not receive :const:`PyTrace_C_CALL`, :const:`PyTrace_C_EXCEPTION` or
1529-
:const:`PyTrace_C_RETURN` as a value for the *what* parameter.
1528+
will not receive :c:data:`PyTrace_C_CALL`, :c:data:`PyTrace_C_EXCEPTION` or
1529+
:c:data:`PyTrace_C_RETURN` as a value for the *what* parameter.
15301530
15311531
See also the :func:`sys.settrace` function.
15321532

‎Doc/c-api/long.rst

+4-4
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)