[Python-checkins] [3.12] gh-106919: Use role :c:macro: for referencing the C "constants" (GH-106920) (GH-106951)
serhiy-storchaka
webhook-mailer at python.org
Fri Jul 21 07:48:19 EDT 2023
https://github.com/python/cpython/commit/ac9aa8a369e03784c5df7f2f8b598959fc9ef5f4
commit: ac9aa8a369e03784c5df7f2f8b598959fc9ef5f4
branch: 3.12
author: Serhiy Storchaka <storchaka at gmail.com>
committer: serhiy-storchaka <storchaka at gmail.com>
date: 2023-07-21T14:48:15+03:00
summary:
[3.12] gh-106919: Use role :c:macro: for referencing the C "constants" (GH-106920) (GH-106951)
(cherry picked from commit fcc816dbff7ca66c26f57a506e4d2330fe41d0ff)
files:
M Doc/c-api/arg.rst
M Doc/c-api/call.rst
M Doc/c-api/complex.rst
M Doc/c-api/exceptions.rst
M Doc/c-api/file.rst
M Doc/c-api/float.rst
M Doc/c-api/gcsupport.rst
M Doc/c-api/init.rst
M Doc/c-api/long.rst
M Doc/c-api/memory.rst
M Doc/c-api/module.rst
M Doc/c-api/object.rst
M Doc/c-api/slice.rst
M Doc/c-api/stable.rst
M Doc/c-api/structures.rst
M Doc/c-api/sys.rst
M Doc/c-api/type.rst
M Doc/c-api/typeobj.rst
M Doc/c-api/unicode.rst
M Doc/c-api/veryhigh.rst
M Doc/extending/extending.rst
M Doc/extending/newtypes_tutorial.rst
M Doc/howto/isolating-extensions.rst
M Doc/library/dis.rst
M Doc/library/os.rst
M Doc/reference/compound_stmts.rst
M Doc/using/cmdline.rst
M Doc/whatsnew/2.2.rst
M Doc/whatsnew/2.3.rst
M Doc/whatsnew/2.4.rst
M Doc/whatsnew/2.6.rst
M Doc/whatsnew/2.7.rst
M Doc/whatsnew/3.10.rst
M Doc/whatsnew/3.11.rst
M Doc/whatsnew/3.12.rst
M Doc/whatsnew/3.6.rst
M Doc/whatsnew/3.8.rst
M Doc/whatsnew/3.9.rst
M Misc/NEWS.d/3.10.0a3.rst
M Misc/NEWS.d/3.10.0b1.rst
M Misc/NEWS.d/3.11.0a1.rst
M Misc/NEWS.d/3.11.0a7.rst
M Misc/NEWS.d/3.12.0a1.rst
M Misc/NEWS.d/3.12.0a2.rst
M Misc/NEWS.d/3.6.0a1.rst
M Misc/NEWS.d/3.9.0a1.rst
diff --git a/Doc/c-api/arg.rst b/Doc/c-api/arg.rst
index 9713431688d49..eba8f2be70b45 100644
--- a/Doc/c-api/arg.rst
+++ b/Doc/c-api/arg.rst
@@ -343,7 +343,7 @@ Other objects
*items*. Format units for sequences may be nested.
It is possible to pass "long" integers (integers whose value exceeds the
-platform's :const:`LONG_MAX`) however no proper range checking is done --- the
+platform's :c:macro:`LONG_MAX`) however no proper range checking is done --- the
most significant bits are silently truncated when the receiving field is too
small to receive the value (actually, the semantics are inherited from downcasts
in C --- your mileage may vary).
@@ -455,7 +455,7 @@ API Functions
A simpler form of parameter retrieval which does not use a format string to
specify the types of the arguments. Functions which use this method to retrieve
- their parameters should be declared as :const:`METH_VARARGS` in function or
+ their parameters should be declared as :c:macro:`METH_VARARGS` in function or
method tables. The tuple containing the actual parameters should be passed as
*args*; it must actually be a tuple. The length of the tuple must be at least
*min* and no more than *max*; *min* and *max* may be equal. Additional
diff --git a/Doc/c-api/call.rst b/Doc/c-api/call.rst
index 4dc66e318cd12..143fce3cdf477 100644
--- a/Doc/c-api/call.rst
+++ b/Doc/c-api/call.rst
@@ -59,12 +59,12 @@ This bears repeating:
.. versionchanged:: 3.12
- The :const:`Py_TPFLAGS_HAVE_VECTORCALL` flag is now removed from a class
+ The :c:macro:`Py_TPFLAGS_HAVE_VECTORCALL` flag is now removed from a class
when the class's :py:meth:`~object.__call__` method is reassigned.
(This internally sets :c:member:`~PyTypeObject.tp_call` only, and thus
may make it behave differently than the vectorcall function.)
In earlier Python versions, vectorcall should only be used with
- :const:`immutable <Py_TPFLAGS_IMMUTABLETYPE>` or static types.
+ :c:macro:`immutable <Py_TPFLAGS_IMMUTABLETYPE>` or static types.
A class should not implement vectorcall if that would be slower
than *tp_call*. For example, if the callee needs to convert
@@ -72,7 +72,7 @@ the arguments to an args tuple and kwargs dict anyway, then there is no point
in implementing vectorcall.
Classes can implement the vectorcall protocol by enabling the
-:const:`Py_TPFLAGS_HAVE_VECTORCALL` flag and setting
+:c:macro:`Py_TPFLAGS_HAVE_VECTORCALL` flag and setting
:c:member:`~PyTypeObject.tp_vectorcall_offset` to the offset inside the
object structure where a *vectorcallfunc* appears.
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:
values of the keyword arguments.
This can be *NULL* if there are no arguments.
- *nargsf* is the number of positional arguments plus possibly the
- :const:`PY_VECTORCALL_ARGUMENTS_OFFSET` flag.
+ :c:macro:`PY_VECTORCALL_ARGUMENTS_OFFSET` flag.
To get the actual number of positional arguments from *nargsf*,
use :c:func:`PyVectorcall_NARGS`.
- *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:
and they must be unique.
If there are no keyword arguments, then *kwnames* can instead be *NULL*.
-.. data:: PY_VECTORCALL_ARGUMENTS_OFFSET
+.. c:macro:: PY_VECTORCALL_ARGUMENTS_OFFSET
If this flag is set in a vectorcall *nargsf* argument, the callee is allowed
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:
``args[0]`` may be changed.
Whenever they can do so cheaply (without additional allocation), callers
- are encouraged to use :const:`PY_VECTORCALL_ARGUMENTS_OFFSET`.
+ are encouraged to use :c:macro:`PY_VECTORCALL_ARGUMENTS_OFFSET`.
Doing so will allow callables such as bound methods to make their onward
calls (which include a prepended *self* argument) very efficiently.
@@ -174,7 +174,7 @@ Vectorcall Support API
This is a specialized function, intended to be put in the
:c:member:`~PyTypeObject.tp_call` slot or be used in an implementation of ``tp_call``.
- It does not check the :const:`Py_TPFLAGS_HAVE_VECTORCALL` flag
+ It does not check the :c:macro:`Py_TPFLAGS_HAVE_VECTORCALL` flag
and it does not fall back to ``tp_call``.
.. versionadded:: 3.8
@@ -392,11 +392,11 @@ please see individual documentation for details.
*args[0]*, and the *args* array starting at *args[1]* represents the arguments
of the call. There must be at least one positional argument.
*nargsf* is the number of positional arguments including *args[0]*,
- plus :const:`PY_VECTORCALL_ARGUMENTS_OFFSET` if the value of ``args[0]`` may
+ plus :c:macro:`PY_VECTORCALL_ARGUMENTS_OFFSET` if the value of ``args[0]`` may
temporarily be changed. Keyword arguments can be passed just like in
:c:func:`PyObject_Vectorcall`.
- If the object has the :const:`Py_TPFLAGS_METHOD_DESCRIPTOR` feature,
+ If the object has the :c:macro:`Py_TPFLAGS_METHOD_DESCRIPTOR` feature,
this will call the unbound method object with the full
*args* vector as arguments.
diff --git a/Doc/c-api/complex.rst b/Doc/c-api/complex.rst
index cb8b270fcbab6..6679ce76f1dc6 100644
--- a/Doc/c-api/complex.rst
+++ b/Doc/c-api/complex.rst
@@ -64,7 +64,7 @@ pointers. This is consistent throughout the API.
representation.
If *divisor* is null, this method returns zero and sets
- :c:data:`errno` to :c:data:`EDOM`.
+ :c:data:`errno` to :c:macro:`EDOM`.
.. c:function:: Py_complex _Py_c_pow(Py_complex num, Py_complex exp)
@@ -73,7 +73,7 @@ pointers. This is consistent throughout the API.
representation.
If *num* is null and *exp* is not a positive real number,
- this method returns zero and sets :c:data:`errno` to :c:data:`EDOM`.
+ this method returns zero and sets :c:data:`errno` to :c:macro:`EDOM`.
Complex Numbers as Python Objects
diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst
index a24ecac861e76..6e09f829da304 100644
--- a/Doc/c-api/exceptions.rst
+++ b/Doc/c-api/exceptions.rst
@@ -165,7 +165,7 @@ For convenience, some of these functions will always return a
tuple object whose first item is the integer :c:data:`errno` value and whose
second item is the corresponding error message (gotten from :c:func:`strerror`),
and then calls ``PyErr_SetObject(type, object)``. On Unix, when the
- :c:data:`errno` value is :const:`EINTR`, indicating an interrupted system call,
+ :c:data:`errno` value is :c:macro:`EINTR`, indicating an interrupted system call,
this calls :c:func:`PyErr_CheckSignals`, and if that set the error indicator,
leaves it set to that. The function always returns ``NULL``, so a wrapper
function around a system call can write ``return PyErr_SetFromErrno(type);``
@@ -631,7 +631,7 @@ Signal Handling
be interruptible by user requests (such as by pressing Ctrl-C).
.. note::
- The default Python signal handler for :const:`SIGINT` raises the
+ The default Python signal handler for :c:macro:`SIGINT` raises the
:exc:`KeyboardInterrupt` exception.
@@ -642,7 +642,7 @@ Signal Handling
single: SIGINT
single: KeyboardInterrupt (built-in exception)
- Simulate the effect of a :const:`SIGINT` signal arriving.
+ Simulate the effect of a :c:macro:`SIGINT` signal arriving.
This is equivalent to ``PyErr_SetInterruptEx(SIGINT)``.
.. note::
@@ -754,7 +754,7 @@ Exception Objects
.. c:function:: PyObject* PyException_GetCause(PyObject *ex)
- Return the cause (either an exception instance, or :const:`None`,
+ Return the cause (either an exception instance, or ``None``,
set by ``raise ... from ...``) associated with the exception as a new
reference, as accessible from Python through :attr:`__cause__`.
@@ -763,7 +763,7 @@ Exception Objects
Set the cause associated with the exception to *cause*. Use ``NULL`` to clear
it. There is no type check to make sure that *cause* is either an exception
- instance or :const:`None`. This steals a reference to *cause*.
+ instance or ``None``. This steals a reference to *cause*.
:attr:`__suppress_context__` is implicitly set to ``True`` by this function.
@@ -874,7 +874,7 @@ because the :ref:`call protocol <call>` takes care of recursion handling.
Marks a point where a recursive C-level call is about to be performed.
- If :const:`USE_STACKCHECK` is defined, this function checks if the OS
+ If :c:macro:`USE_STACKCHECK` is defined, this function checks if the OS
stack overflowed using :c:func:`PyOS_CheckStack`. In this is the case, it
sets a :exc:`MemoryError` and returns a nonzero value.
diff --git a/Doc/c-api/file.rst b/Doc/c-api/file.rst
index f32ecba9f2702..b36c800e00444 100644
--- a/Doc/c-api/file.rst
+++ b/Doc/c-api/file.rst
@@ -93,7 +93,7 @@ the :mod:`io` APIs instead.
.. index:: single: Py_PRINT_RAW
Write object *obj* to file object *p*. The only supported flag for *flags* is
- :const:`Py_PRINT_RAW`; if given, the :func:`str` of the object is written
+ :c:macro:`Py_PRINT_RAW`; if given, the :func:`str` of the object is written
instead of the :func:`repr`. Return ``0`` on success or ``-1`` on failure; the
appropriate exception will be set.
diff --git a/Doc/c-api/float.rst b/Doc/c-api/float.rst
index fd0be1108c630..4f6ac0d8175c6 100644
--- a/Doc/c-api/float.rst
+++ b/Doc/c-api/float.rst
@@ -109,7 +109,7 @@ Pack functions
The pack routines write 2, 4 or 8 bytes, starting at *p*. *le* is an
:c:expr:`int` argument, non-zero if you want the bytes string in little-endian
format (exponent last, at ``p+1``, ``p+3``, or ``p+6`` ``p+7``), zero if you
-want big-endian format (exponent first, at *p*). The :c:data:`PY_BIG_ENDIAN`
+want big-endian format (exponent first, at *p*). The :c:macro:`PY_BIG_ENDIAN`
constant can be used to use the native endian: it is equal to ``1`` on big
endian processor, or ``0`` on little endian processor.
@@ -140,7 +140,7 @@ Unpack functions
The unpack routines read 2, 4 or 8 bytes, starting at *p*. *le* is an
:c:expr:`int` argument, non-zero if the bytes string is in little-endian format
(exponent last, at ``p+1``, ``p+3`` or ``p+6`` and ``p+7``), zero if big-endian
-(exponent first, at *p*). The :c:data:`PY_BIG_ENDIAN` constant can be used to
+(exponent first, at *p*). The :c:macro:`PY_BIG_ENDIAN` constant can be used to
use the native endian: it is equal to ``1`` on big endian processor, or ``0``
on little endian processor.
diff --git a/Doc/c-api/gcsupport.rst b/Doc/c-api/gcsupport.rst
index c3260a21bc7f8..e56414ab9f754 100644
--- a/Doc/c-api/gcsupport.rst
+++ b/Doc/c-api/gcsupport.rst
@@ -13,14 +13,12 @@ or strings), do not need to provide any explicit support for garbage
collection.
To create a container type, the :c:member:`~PyTypeObject.tp_flags` field of the type object must
-include the :const:`Py_TPFLAGS_HAVE_GC` and provide an implementation of the
+include the :c:macro:`Py_TPFLAGS_HAVE_GC` and provide an implementation of the
:c:member:`~PyTypeObject.tp_traverse` handler. If instances of the type are mutable, a
:c:member:`~PyTypeObject.tp_clear` implementation must also be provided.
-.. data:: Py_TPFLAGS_HAVE_GC
- :noindex:
-
+:c:macro:`Py_TPFLAGS_HAVE_GC`
Objects with a type with this flag set must conform with the rules
documented here. For convenience these objects will be referred to as
container objects.
@@ -52,17 +50,17 @@ rules:
:c:member:`~PyTypeObject.tp_flags`, :c:member:`~PyTypeObject.tp_traverse`
and :c:member:`~PyTypeObject.tp_clear` fields if the type inherits from a
class that implements the garbage collector protocol and the child class
- does *not* include the :const:`Py_TPFLAGS_HAVE_GC` flag.
+ does *not* include the :c:macro:`Py_TPFLAGS_HAVE_GC` flag.
.. c:function:: TYPE* PyObject_GC_New(TYPE, PyTypeObject *type)
Analogous to :c:func:`PyObject_New` but for container objects with the
- :const:`Py_TPFLAGS_HAVE_GC` flag set.
+ :c:macro:`Py_TPFLAGS_HAVE_GC` flag set.
.. c:function:: TYPE* PyObject_GC_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size)
Analogous to :c:func:`PyObject_NewVar` but for container objects with the
- :const:`Py_TPFLAGS_HAVE_GC` flag set.
+ :c:macro:`Py_TPFLAGS_HAVE_GC` flag set.
.. c:function:: PyObject* PyUnstable_Object_GC_NewWithExtraData(PyTypeObject *type, size_t extra_size)
diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst
index 26762969ef8eb..c99377fb45a6b 100644
--- a/Doc/c-api/init.rst
+++ b/Doc/c-api/init.rst
@@ -1396,7 +1396,7 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
function does not steal any references to *exc*. To prevent naive misuse, you
must write your own C extension to call this. Must be called with the GIL held.
Returns the number of thread states modified; this is normally one, but will be
- zero if the thread id isn't found. If *exc* is :const:`NULL`, the pending
+ zero if the thread id isn't found. If *exc* is ``NULL``, the pending
exception (if any) for the thread is cleared. This raises no exceptions.
.. versionchanged:: 3.7
@@ -1675,32 +1675,32 @@ Python-level trace functions in previous versions.
The type of the trace function registered using :c:func:`PyEval_SetProfile` and
:c:func:`PyEval_SetTrace`. The first parameter is the object passed to the
registration function as *obj*, *frame* is the frame object to which the event
- pertains, *what* is one of the constants :const:`PyTrace_CALL`,
- :const:`PyTrace_EXCEPTION`, :const:`PyTrace_LINE`, :const:`PyTrace_RETURN`,
- :const:`PyTrace_C_CALL`, :const:`PyTrace_C_EXCEPTION`, :const:`PyTrace_C_RETURN`,
- or :const:`PyTrace_OPCODE`, and *arg* depends on the value of *what*:
-
- +------------------------------+----------------------------------------+
- | Value of *what* | Meaning of *arg* |
- +==============================+========================================+
- | :const:`PyTrace_CALL` | Always :c:data:`Py_None`. |
- +------------------------------+----------------------------------------+
- | :const:`PyTrace_EXCEPTION` | Exception information as returned by |
- | | :func:`sys.exc_info`. |
- +------------------------------+----------------------------------------+
- | :const:`PyTrace_LINE` | Always :c:data:`Py_None`. |
- +------------------------------+----------------------------------------+
- | :const:`PyTrace_RETURN` | Value being returned to the caller, |
- | | or ``NULL`` if caused by an exception. |
- +------------------------------+----------------------------------------+
- | :const:`PyTrace_C_CALL` | Function object being called. |
- +------------------------------+----------------------------------------+
- | :const:`PyTrace_C_EXCEPTION` | Function object being called. |
- +------------------------------+----------------------------------------+
- | :const:`PyTrace_C_RETURN` | Function object being called. |
- +------------------------------+----------------------------------------+
- | :const:`PyTrace_OPCODE` | Always :c:data:`Py_None`. |
- +------------------------------+----------------------------------------+
+ pertains, *what* is one of the constants :c:data:`PyTrace_CALL`,
+ :c:data:`PyTrace_EXCEPTION`, :c:data:`PyTrace_LINE`, :c:data:`PyTrace_RETURN`,
+ :c:data:`PyTrace_C_CALL`, :c:data:`PyTrace_C_EXCEPTION`, :c:data:`PyTrace_C_RETURN`,
+ or :c:data:`PyTrace_OPCODE`, and *arg* depends on the value of *what*:
+
+ +-------------------------------+----------------------------------------+
+ | Value of *what* | Meaning of *arg* |
+ +===============================+========================================+
+ | :c:data:`PyTrace_CALL` | Always :c:data:`Py_None`. |
+ +-------------------------------+----------------------------------------+
+ | :c:data:`PyTrace_EXCEPTION` | Exception information as returned by |
+ | | :func:`sys.exc_info`. |
+ +-------------------------------+----------------------------------------+
+ | :c:data:`PyTrace_LINE` | Always :c:data:`Py_None`. |
+ +-------------------------------+----------------------------------------+
+ | :c:data:`PyTrace_RETURN` | Value being returned to the caller, |
+ | | or ``NULL`` if caused by an exception. |
+ +-------------------------------+----------------------------------------+
+ | :c:data:`PyTrace_C_CALL` | Function object being called. |
+ +-------------------------------+----------------------------------------+
+ | :c:data:`PyTrace_C_EXCEPTION` | Function object being called. |
+ +-------------------------------+----------------------------------------+
+ | :c:data:`PyTrace_C_RETURN` | Function object being called. |
+ +-------------------------------+----------------------------------------+
+ | :c:data:`PyTrace_OPCODE` | Always :c:data:`Py_None`. |
+ +-------------------------------+----------------------------------------+
.. c:var:: int PyTrace_CALL
@@ -1767,8 +1767,8 @@ Python-level trace functions in previous versions.
function as its first parameter, and may be any Python object, or ``NULL``. If
the profile function needs to maintain state, using a different value for *obj*
for each thread provides a convenient and thread-safe place to store it. The
- profile function is called for all monitored events except :const:`PyTrace_LINE`
- :const:`PyTrace_OPCODE` and :const:`PyTrace_EXCEPTION`.
+ profile function is called for all monitored events except :c:data:`PyTrace_LINE`
+ :c:data:`PyTrace_OPCODE` and :c:data:`PyTrace_EXCEPTION`.
See also the :func:`sys.setprofile` function.
@@ -1793,8 +1793,8 @@ Python-level trace functions in previous versions.
:c:func:`PyEval_SetProfile`, except the tracing function does receive line-number
events and per-opcode events, but does not receive any event related to C function
objects being called. Any trace function registered using :c:func:`PyEval_SetTrace`
- will not receive :const:`PyTrace_C_CALL`, :const:`PyTrace_C_EXCEPTION` or
- :const:`PyTrace_C_RETURN` as a value for the *what* parameter.
+ will not receive :c:data:`PyTrace_C_CALL`, :c:data:`PyTrace_C_EXCEPTION` or
+ :c:data:`PyTrace_C_RETURN` as a value for the *what* parameter.
See also the :func:`sys.settrace` function.
diff --git a/Doc/c-api/long.rst b/Doc/c-api/long.rst
index fe379ffe91239..f1354a34f2b2d 100644
--- a/Doc/c-api/long.rst
+++ b/Doc/c-api/long.rst
@@ -142,8 +142,8 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
instance of :c:type:`PyLongObject`, first call its :meth:`~object.__index__`
method (if present) to convert it to a :c:type:`PyLongObject`.
- If the value of *obj* is greater than :const:`LONG_MAX` or less than
- :const:`LONG_MIN`, set *\*overflow* to ``1`` or ``-1``, respectively, and
+ If the value of *obj* is greater than :c:macro:`LONG_MAX` or less than
+ :c:macro:`LONG_MIN`, set *\*overflow* to ``1`` or ``-1``, respectively, and
return ``-1``; otherwise, set *\*overflow* to ``0``. If any other exception
occurs set *\*overflow* to ``0`` and return ``-1`` as usual.
@@ -183,8 +183,8 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
instance of :c:type:`PyLongObject`, first call its :meth:`~object.__index__` method
(if present) to convert it to a :c:type:`PyLongObject`.
- If the value of *obj* is greater than :const:`LLONG_MAX` or less than
- :const:`LLONG_MIN`, set *\*overflow* to ``1`` or ``-1``, respectively,
+ If the value of *obj* is greater than :c:macro:`LLONG_MAX` or less than
+ :c:macro:`LLONG_MIN`, set *\*overflow* to ``1`` or ``-1``, respectively,
and return ``-1``; otherwise, set *\*overflow* to ``0``. If any other
exception occurs set *\*overflow* to ``0`` and return ``-1`` as usual.
diff --git a/Doc/c-api/memory.rst b/Doc/c-api/memory.rst
index 7041c15d23fb8..35c356f25c6c7 100644
--- a/Doc/c-api/memory.rst
+++ b/Doc/c-api/memory.rst
@@ -470,7 +470,7 @@ Customize Memory Allocators
The new allocator must return a distinct non-``NULL`` pointer when requesting
zero bytes.
- For the :c:data:`PYMEM_DOMAIN_RAW` domain, the allocator must be
+ For the :c:macro:`PYMEM_DOMAIN_RAW` domain, the allocator must be
thread-safe: the :term:`GIL <global interpreter lock>` is not held when the
allocator is called.
@@ -536,8 +536,8 @@ Runtime checks:
- Detect write before the start of the buffer (buffer underflow).
- Detect write after the end of the buffer (buffer overflow).
- Check that the :term:`GIL <global interpreter lock>` is held when
- allocator functions of :c:data:`PYMEM_DOMAIN_OBJ` (ex:
- :c:func:`PyObject_Malloc`) and :c:data:`PYMEM_DOMAIN_MEM` (ex:
+ allocator functions of :c:macro:`PYMEM_DOMAIN_OBJ` (ex:
+ :c:func:`PyObject_Malloc`) and :c:macro:`PYMEM_DOMAIN_MEM` (ex:
:c:func:`PyMem_Malloc`) domains are called.
On error, the debug hooks use the :mod:`tracemalloc` module to get the
@@ -557,9 +557,9 @@ that the treatment of negative indices differs from a Python slice):
``p[-S]``
API identifier (ASCII character):
- * ``'r'`` for :c:data:`PYMEM_DOMAIN_RAW`.
- * ``'m'`` for :c:data:`PYMEM_DOMAIN_MEM`.
- * ``'o'`` for :c:data:`PYMEM_DOMAIN_OBJ`.
+ * ``'r'`` for :c:macro:`PYMEM_DOMAIN_RAW`.
+ * ``'m'`` for :c:macro:`PYMEM_DOMAIN_MEM`.
+ * ``'o'`` for :c:macro:`PYMEM_DOMAIN_OBJ`.
``p[-S+1:0]``
Copies of PYMEM_FORBIDDENBYTE. Used to catch under- writes and reads.
@@ -601,7 +601,7 @@ PYMEM_CLEANBYTE (meaning uninitialized memory is getting used).
compiled in release mode. On error, the debug hooks now use
:mod:`tracemalloc` to get the traceback where a memory block was allocated.
The debug hooks now also check if the GIL is held when functions of
- :c:data:`PYMEM_DOMAIN_OBJ` and :c:data:`PYMEM_DOMAIN_MEM` domains are
+ :c:macro:`PYMEM_DOMAIN_OBJ` and :c:macro:`PYMEM_DOMAIN_MEM` domains are
called.
.. versionchanged:: 3.8
@@ -622,8 +622,8 @@ with a fixed size of 256 KiB. It falls back to :c:func:`PyMem_RawMalloc` and
:c:func:`PyMem_RawRealloc` for allocations larger than 512 bytes.
*pymalloc* is the :ref:`default allocator <default-memory-allocators>` of the
-:c:data:`PYMEM_DOMAIN_MEM` (ex: :c:func:`PyMem_Malloc`) and
-:c:data:`PYMEM_DOMAIN_OBJ` (ex: :c:func:`PyObject_Malloc`) domains.
+:c:macro:`PYMEM_DOMAIN_MEM` (ex: :c:func:`PyMem_Malloc`) and
+:c:macro:`PYMEM_DOMAIN_OBJ` (ex: :c:func:`PyObject_Malloc`) domains.
The arena allocator uses the following functions:
diff --git a/Doc/c-api/module.rst b/Doc/c-api/module.rst
index 230b471d473be..bc8e3b23b9957 100644
--- a/Doc/c-api/module.rst
+++ b/Doc/c-api/module.rst
@@ -145,7 +145,7 @@ or request "multi-phase initialization" by returning the definition struct itsel
.. c:member:: PyModuleDef_Base m_base
- Always initialize this member to :const:`PyModuleDef_HEAD_INIT`.
+ Always initialize this member to :c:data:`PyModuleDef_HEAD_INIT`.
.. c:member:: const char *m_name
@@ -256,7 +256,7 @@ of the following two module creation functions:
Create a new module object, given the definition in *def*. This behaves
like :c:func:`PyModule_Create2` with *module_api_version* set to
- :const:`PYTHON_API_VERSION`.
+ :c:macro:`PYTHON_API_VERSION`.
.. c:function:: PyObject* PyModule_Create2(PyModuleDef *def, int module_api_version)
@@ -390,7 +390,7 @@ objects dynamically. Note that both ``PyModule_FromDefAndSpec`` and
Create a new module object, given the definition in *def* and the
ModuleSpec *spec*. This behaves like :c:func:`PyModule_FromDefAndSpec2`
- with *module_api_version* set to :const:`PYTHON_API_VERSION`.
+ with *module_api_version* set to :c:macro:`PYTHON_API_VERSION`.
.. versionadded:: 3.5
diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst
index 22e7458013fb3..3b922f3b810c7 100644
--- a/Doc/c-api/object.rst
+++ b/Doc/c-api/object.rst
@@ -23,7 +23,7 @@ Object Protocol
Print an object *o*, on file *fp*. Returns ``-1`` on error. The flags argument
is used to enable certain printing options. The only option currently supported
- is :const:`Py_PRINT_RAW`; if given, the :func:`str` of the object is written
+ is :c:macro:`Py_PRINT_RAW`; if given, the :func:`str` of the object is written
instead of the :func:`repr`.
@@ -162,8 +162,8 @@ Object Protocol
.. c:function:: PyObject* PyObject_RichCompare(PyObject *o1, PyObject *o2, int opid)
Compare the values of *o1* and *o2* using the operation specified by *opid*,
- which must be one of :const:`Py_LT`, :const:`Py_LE`, :const:`Py_EQ`,
- :const:`Py_NE`, :const:`Py_GT`, or :const:`Py_GE`, corresponding to ``<``,
+ which must be one of :c:macro:`Py_LT`, :c:macro:`Py_LE`, :c:macro:`Py_EQ`,
+ :c:macro:`Py_NE`, :c:macro:`Py_GT`, or :c:macro:`Py_GE`, corresponding to ``<``,
``<=``, ``==``, ``!=``, ``>``, or ``>=`` respectively. This is the equivalent of
the Python expression ``o1 op o2``, where ``op`` is the operator corresponding
to *opid*. Returns the value of the comparison on success, or ``NULL`` on failure.
@@ -172,8 +172,8 @@ Object Protocol
.. c:function:: int PyObject_RichCompareBool(PyObject *o1, PyObject *o2, int opid)
Compare the values of *o1* and *o2* using the operation specified by *opid*,
- which must be one of :const:`Py_LT`, :const:`Py_LE`, :const:`Py_EQ`,
- :const:`Py_NE`, :const:`Py_GT`, or :const:`Py_GE`, corresponding to ``<``,
+ which must be one of :c:macro:`Py_LT`, :c:macro:`Py_LE`, :c:macro:`Py_EQ`,
+ :c:macro:`Py_NE`, :c:macro:`Py_GT`, or :c:macro:`Py_GE`, corresponding to ``<``,
``<=``, ``==``, ``!=``, ``>``, or ``>=`` respectively. Returns ``-1`` on error,
``0`` if the result is false, ``1`` otherwise. This is the equivalent of the
Python expression ``o1 op o2``, where ``op`` is the operator corresponding to
@@ -181,7 +181,7 @@ Object Protocol
.. note::
If *o1* and *o2* are the same object, :c:func:`PyObject_RichCompareBool`
- will always return ``1`` for :const:`Py_EQ` and ``0`` for :const:`Py_NE`.
+ will always return ``1`` for :c:macro:`Py_EQ` and ``0`` for :c:macro:`Py_NE`.
.. c:function:: PyObject* PyObject_Format(PyObject *obj, PyObject *format_spec)
@@ -431,10 +431,10 @@ Object Protocol
.. c:function:: void *PyObject_GetItemData(PyObject *o)
Get a pointer to per-item data for a class with
- :const:`Py_TPFLAGS_ITEMS_AT_END`.
+ :c:macro:`Py_TPFLAGS_ITEMS_AT_END`.
On error, set an exception and return ``NULL``.
:py:exc:`TypeError` is raised if *o* does not have
- :const:`Py_TPFLAGS_ITEMS_AT_END` set.
+ :c:macro:`Py_TPFLAGS_ITEMS_AT_END` set.
.. versionadded:: 3.12
diff --git a/Doc/c-api/slice.rst b/Doc/c-api/slice.rst
index c54a659cf2ffd..9e880c6b7f25a 100644
--- a/Doc/c-api/slice.rst
+++ b/Doc/c-api/slice.rst
@@ -34,7 +34,7 @@ Slice Objects
*length* as errors.
Returns ``0`` on success and ``-1`` on error with no exception set (unless one of
- the indices was not :const:`None` and failed to be converted to an integer,
+ the indices was not ``None`` and failed to be converted to an integer,
in which case ``-1`` is returned with an exception set).
You probably do not want to use this function.
diff --git a/Doc/c-api/stable.rst b/Doc/c-api/stable.rst
index 149d4d6bac3ee..c66b296d304ad 100644
--- a/Doc/c-api/stable.rst
+++ b/Doc/c-api/stable.rst
@@ -74,7 +74,7 @@ Contents of the Limited API are :ref:`listed below <limited-api-list>`.
Define this macro before including ``Python.h`` to opt in to only use
the Limited API, and to select the Limited API version.
- Define ``Py_LIMITED_API`` to the value of :c:data:`PY_VERSION_HEX`
+ Define ``Py_LIMITED_API`` to the value of :c:macro:`PY_VERSION_HEX`
corresponding to the lowest Python version your extension supports.
The extension will work without recompilation with all Python 3 releases
from the specified one onward, and can use Limited API introduced up to that
diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst
index 766f881463c00..720ab31f3de85 100644
--- a/Doc/c-api/structures.rst
+++ b/Doc/c-api/structures.rst
@@ -179,7 +179,7 @@ Implementing functions and methods
.. c:type:: PyCFunctionWithKeywords
Type of the functions used to implement Python callables in C
- with signature :const:`METH_VARARGS | METH_KEYWORDS`.
+ with signature :ref:`METH_VARARGS | METH_KEYWORDS <METH_VARARGS-METH_KEYWORDS>`.
The function signature is::
PyObject *PyCFunctionWithKeywords(PyObject *self,
@@ -190,7 +190,7 @@ Implementing functions and methods
.. c:type:: _PyCFunctionFast
Type of the functions used to implement Python callables in C
- with signature :const:`METH_FASTCALL`.
+ with signature :c:macro:`METH_FASTCALL`.
The function signature is::
PyObject *_PyCFunctionFast(PyObject *self,
@@ -200,7 +200,7 @@ Implementing functions and methods
.. c:type:: _PyCFunctionFastWithKeywords
Type of the functions used to implement Python callables in C
- with signature :const:`METH_FASTCALL | METH_KEYWORDS`.
+ with signature :ref:`METH_FASTCALL | METH_KEYWORDS <METH_FASTCALL-METH_KEYWORDS>`.
The function signature is::
PyObject *_PyCFunctionFastWithKeywords(PyObject *self,
@@ -211,7 +211,7 @@ Implementing functions and methods
.. c:type:: PyCMethod
Type of the functions used to implement Python callables in C
- with signature :const:`METH_METHOD | METH_FASTCALL | METH_KEYWORDS`.
+ with signature :ref:`METH_METHOD | METH_FASTCALL | METH_KEYWORDS <METH_METHOD-METH_FASTCALL-METH_KEYWORDS>`.
The function signature is::
PyObject *PyCMethod(PyObject *self,
@@ -257,7 +257,7 @@ convention.
There are these calling conventions:
-.. data:: METH_VARARGS
+.. c:macro:: METH_VARARGS
This is the typical calling convention, where the methods have the type
:c:type:`PyCFunction`. The function expects two :c:expr:`PyObject*` values.
@@ -267,8 +267,17 @@ There are these calling conventions:
using :c:func:`PyArg_ParseTuple` or :c:func:`PyArg_UnpackTuple`.
-.. data:: METH_VARARGS | METH_KEYWORDS
+.. c:macro:: METH_KEYWORDS
+ Can only be used in certain combinations with other flags:
+ :ref:`METH_VARARGS | METH_KEYWORDS <METH_VARARGS-METH_KEYWORDS>`,
+ :ref:`METH_FASTCALL | METH_KEYWORDS <METH_FASTCALL-METH_KEYWORDS>` and
+ :ref:`METH_METHOD | METH_FASTCALL | METH_KEYWORDS <METH_METHOD-METH_FASTCALL-METH_KEYWORDS>`.
+
+
+.. _METH_VARARGS-METH_KEYWORDS:
+
+:c:expr:`METH_VARARGS | METH_KEYWORDS`
Methods with these flags must be of type :c:type:`PyCFunctionWithKeywords`.
The function expects three parameters: *self*, *args*, *kwargs* where
*kwargs* is a dictionary of all the keyword arguments or possibly ``NULL``
@@ -276,7 +285,7 @@ There are these calling conventions:
using :c:func:`PyArg_ParseTupleAndKeywords`.
-.. data:: METH_FASTCALL
+.. c:macro:: METH_FASTCALL
Fast calling convention supporting only positional arguments.
The methods have the type :c:type:`_PyCFunctionFast`.
@@ -291,9 +300,10 @@ There are these calling conventions:
``METH_FASTCALL`` is now part of the :ref:`stable ABI <stable-abi>`.
-.. data:: METH_FASTCALL | METH_KEYWORDS
+.. _METH_FASTCALL-METH_KEYWORDS:
- Extension of :const:`METH_FASTCALL` supporting also keyword arguments,
+:c:expr:`METH_FASTCALL | METH_KEYWORDS`
+ Extension of :c:macro:`METH_FASTCALL` supporting also keyword arguments,
with methods of type :c:type:`_PyCFunctionFastWithKeywords`.
Keyword arguments are passed the same way as in the
:ref:`vectorcall protocol <vectorcall>`:
@@ -306,10 +316,18 @@ There are these calling conventions:
.. versionadded:: 3.7
-.. data:: METH_METHOD | METH_FASTCALL | METH_KEYWORDS
+.. c:macro:: METH_METHOD
+
+ Can only be used in the combination with other flags:
+ :ref:`METH_METHOD | METH_FASTCALL | METH_KEYWORDS <METH_METHOD-METH_FASTCALL-METH_KEYWORDS>`.
+
+
+.. _METH_METHOD-METH_FASTCALL-METH_KEYWORDS:
- Extension of :const:`METH_FASTCALL | METH_KEYWORDS` supporting the *defining
- class*, that is, the class that contains the method in question.
+:c:expr:`METH_METHOD | METH_FASTCALL | METH_KEYWORDS`
+ Extension of :ref:`METH_FASTCALL | METH_KEYWORDS <METH_FASTCALL-METH_KEYWORDS>`
+ supporting the *defining class*, that is,
+ the class that contains the method in question.
The defining class might be a superclass of ``Py_TYPE(self)``.
The method needs to be of type :c:type:`PyCMethod`, the same as for
@@ -319,10 +337,10 @@ There are these calling conventions:
.. versionadded:: 3.9
-.. data:: METH_NOARGS
+.. c:macro:: METH_NOARGS
Methods without parameters don't need to check whether arguments are given if
- they are listed with the :const:`METH_NOARGS` flag. They need to be of type
+ they are listed with the :c:macro:`METH_NOARGS` flag. They need to be of type
:c:type:`PyCFunction`. The first parameter is typically named *self* and will
hold a reference to the module or object instance. In all cases the second
parameter will be ``NULL``.
@@ -331,9 +349,9 @@ There are these calling conventions:
:c:macro:`Py_UNUSED` can be used to prevent a compiler warning.
-.. data:: METH_O
+.. c:macro:: METH_O
- Methods with a single object argument can be listed with the :const:`METH_O`
+ Methods with a single object argument can be listed with the :c:macro:`METH_O`
flag, instead of invoking :c:func:`PyArg_ParseTuple` with a ``"O"`` argument.
They have the type :c:type:`PyCFunction`, with the *self* parameter, and a
:c:expr:`PyObject*` parameter representing the single argument.
@@ -345,7 +363,7 @@ defined for modules. At most one of these flags may be set for any given
method.
-.. data:: METH_CLASS
+.. c:macro:: METH_CLASS
.. index:: pair: built-in function; classmethod
@@ -355,7 +373,7 @@ method.
function.
-.. data:: METH_STATIC
+.. c:macro:: METH_STATIC
.. index:: pair: built-in function; staticmethod
@@ -367,7 +385,7 @@ One other constant controls whether a method is loaded in place of another
definition with the same method name.
-.. data:: METH_COEXIST
+.. c:macro:: METH_COEXIST
The method will be loaded in place of existing definitions. Without
*METH_COEXIST*, the default is to skip repeated definitions. Since slot
@@ -440,8 +458,8 @@ Accessing attributes of extension types
The legacy offsets :c:member:`~PyTypeObject.tp_dictoffset` and
:c:member:`~PyTypeObject.tp_weaklistoffset` can be defined similarly using
``"__dictoffset__"`` and ``"__weaklistoffset__"`` members, but extensions
- are strongly encouraged to use :const:`Py_TPFLAGS_MANAGED_DICT` and
- :const:`Py_TPFLAGS_MANAGED_WEAKREF` instead.
+ are strongly encouraged to use :c:macro:`Py_TPFLAGS_MANAGED_DICT` and
+ :c:macro:`Py_TPFLAGS_MANAGED_WEAKREF` instead.
.. versionchanged:: 3.12
@@ -509,19 +527,19 @@ The following flags can be used with :c:member:`PyMemberDef.flags`:
.. versionchanged:: 3.10
- The :const:`!RESTRICTED`, :const:`!READ_RESTRICTED` and
- :const:`!WRITE_RESTRICTED` macros available with
+ The :c:macro:`!RESTRICTED`, :c:macro:`!READ_RESTRICTED` and
+ :c:macro:`!WRITE_RESTRICTED` macros available with
``#include "structmember.h"`` are deprecated.
- :const:`!READ_RESTRICTED` and :const:`!RESTRICTED` are equivalent to
- :const:`Py_AUDIT_READ`; :const:`!WRITE_RESTRICTED` does nothing.
+ :c:macro:`!READ_RESTRICTED` and :c:macro:`!RESTRICTED` are equivalent to
+ :c:macro:`Py_AUDIT_READ`; :c:macro:`!WRITE_RESTRICTED` does nothing.
.. index::
single: READONLY
.. versionchanged:: 3.12
- The :const:`!READONLY` macro was renamed to :const:`Py_READONLY`.
- The :const:`!PY_AUDIT_READ` macro was renamed with the ``Py_`` prefix.
+ The :c:macro:`!READONLY` macro was renamed to :c:macro:`Py_READONLY`.
+ The :c:macro:`!PY_AUDIT_READ` macro was renamed with the ``Py_`` prefix.
The new names are now always available.
Previously, these required ``#include "structmember.h"``.
The header is still available and it provides the old names.
diff --git a/Doc/c-api/sys.rst b/Doc/c-api/sys.rst
index 6fc8a3aff9568..3550193c1af82 100644
--- a/Doc/c-api/sys.rst
+++ b/Doc/c-api/sys.rst
@@ -97,9 +97,9 @@ Operating System Utilities
.. c:function:: int PyOS_CheckStack()
Return true when the interpreter runs out of stack space. This is a reliable
- check, but is only available when :const:`USE_STACKCHECK` is defined (currently
+ check, but is only available when :c:macro:`USE_STACKCHECK` is defined (currently
on certain versions of Windows using the Microsoft Visual C++ compiler).
- :const:`USE_STACKCHECK` will be defined automatically; you should never
+ :c:macro:`USE_STACKCHECK` will be defined automatically; you should never
change the definition in your own code.
diff --git a/Doc/c-api/type.rst b/Doc/c-api/type.rst
index a5f333e2a31e0..d9dcd22a24839 100644
--- a/Doc/c-api/type.rst
+++ b/Doc/c-api/type.rst
@@ -132,7 +132,7 @@ Type Objects
.. c:function:: int PyType_IS_GC(PyTypeObject *o)
Return true if the type object includes support for the cycle detector; this
- tests the type flag :const:`Py_TPFLAGS_HAVE_GC`.
+ tests the type flag :c:macro:`Py_TPFLAGS_HAVE_GC`.
.. c:function:: int PyType_IsSubtype(PyTypeObject *a, PyTypeObject *b)
@@ -165,10 +165,10 @@ Type Objects
.. note::
If some of the base classes implements the GC protocol and the provided
- type does not include the :const:`Py_TPFLAGS_HAVE_GC` in its flags, then
+ type does not include the :c:macro:`Py_TPFLAGS_HAVE_GC` in its flags, then
the GC protocol will be automatically implemented from its parents. On
the contrary, if the type being created does include
- :const:`Py_TPFLAGS_HAVE_GC` in its flags then it **must** implement the
+ :c:macro:`Py_TPFLAGS_HAVE_GC` in its flags then it **must** implement the
GC protocol itself by at least implementing the
:c:member:`~PyTypeObject.tp_traverse` handle.
@@ -268,7 +268,7 @@ The following functions and structs are used to create
.. c:function:: PyObject* PyType_FromMetaclass(PyTypeObject *metaclass, PyObject *module, PyType_Spec *spec, PyObject *bases)
Create and return a :ref:`heap type <heap-types>` from the *spec*
- (see :const:`Py_TPFLAGS_HEAPTYPE`).
+ (see :c:macro:`Py_TPFLAGS_HEAPTYPE`).
The metaclass *metaclass* is used to construct the resulting type object.
When *metaclass* is ``NULL``, the metaclass is derived from *bases*
@@ -420,7 +420,7 @@ The following functions and structs are used to create
- The requested :c:member:`PyType_Spec.basicsize` is zero,
suggesting that the subclass does not access the instance's memory
directly.
- - With the :const:`Py_TPFLAGS_ITEMS_AT_END` flag.
+ - With the :c:macro:`Py_TPFLAGS_ITEMS_AT_END` flag.
.. c:member:: unsigned int flags
@@ -471,9 +471,9 @@ The following functions and structs are used to create
* :c:member:`~PyTypeObject.tp_weaklist`
* :c:member:`~PyTypeObject.tp_vectorcall`
* :c:member:`~PyTypeObject.tp_weaklistoffset`
- (use :const:`Py_TPFLAGS_MANAGED_WEAKREF` instead)
+ (use :c:macro:`Py_TPFLAGS_MANAGED_WEAKREF` instead)
* :c:member:`~PyTypeObject.tp_dictoffset`
- (use :const:`Py_TPFLAGS_MANAGED_DICT` instead)
+ (use :c:macro:`Py_TPFLAGS_MANAGED_DICT` instead)
* :c:member:`~PyTypeObject.tp_vectorcall_offset`
(see :ref:`PyMemberDef <pymemberdef-offsets>`)
diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst
index 7249cfe79c32e..33591ed14eaf1 100644
--- a/Doc/c-api/typeobj.rst
+++ b/Doc/c-api/typeobj.rst
@@ -669,7 +669,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
memory buffers owned by the instance (using the freeing function corresponding
to the allocation function used to allocate the buffer), and call the type's
:c:member:`~PyTypeObject.tp_free` function. If the type is not subtypable
- (doesn't have the :const:`Py_TPFLAGS_BASETYPE` flag bit set), it is
+ (doesn't have the :c:macro:`Py_TPFLAGS_BASETYPE` flag bit set), it is
permissible to call the object deallocator directly instead of via
:c:member:`~PyTypeObject.tp_free`. The object deallocator should be the one used to allocate the
instance; this is normally :c:func:`PyObject_Del` if the instance was allocated
@@ -677,7 +677,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
:c:func:`PyObject_GC_Del` if the instance was allocated using
:c:func:`PyObject_GC_New` or :c:func:`PyObject_GC_NewVar`.
- If the type supports garbage collection (has the :const:`Py_TPFLAGS_HAVE_GC`
+ If the type supports garbage collection (has the :c:macro:`Py_TPFLAGS_HAVE_GC`
flag bit set), the destructor should call :c:func:`PyObject_GC_UnTrack`
before clearing any member fields.
@@ -689,7 +689,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
Py_TYPE(self)->tp_free((PyObject *)self);
}
- Finally, if the type is heap allocated (:const:`Py_TPFLAGS_HEAPTYPE`), the
+ Finally, if the type is heap allocated (:c:macro:`Py_TPFLAGS_HEAPTYPE`), the
deallocator should decrement the reference count for its type object after
calling the type deallocator. In order to avoid dangling pointers, the
recommended way to achieve this is:
@@ -716,12 +716,12 @@ and :c:type:`PyType_Type` effectively act as defaults.)
a more efficient alternative
of the simpler :c:member:`~PyTypeObject.tp_call`.
- This field is only used if the flag :const:`Py_TPFLAGS_HAVE_VECTORCALL`
+ This field is only used if the flag :c:macro:`Py_TPFLAGS_HAVE_VECTORCALL`
is set. If so, this must be a positive integer containing the offset in the
instance of a :c:type:`vectorcallfunc` pointer.
The *vectorcallfunc* pointer may be ``NULL``, in which case the instance behaves
- as if :const:`Py_TPFLAGS_HAVE_VECTORCALL` was not set: calling the instance
+ as if :c:macro:`Py_TPFLAGS_HAVE_VECTORCALL` was not set: calling the instance
falls back to :c:member:`~PyTypeObject.tp_call`.
Any class that sets ``Py_TPFLAGS_HAVE_VECTORCALL`` must also set
@@ -743,12 +743,12 @@ and :c:type:`PyType_Type` effectively act as defaults.)
When a user sets :attr:`~type.__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 :const:`Py_TPFLAGS_HAVE_VECTORCALL` flag.
+ by clearing the :c:macro:`Py_TPFLAGS_HAVE_VECTORCALL` flag.
**Inheritance:**
This field is always inherited.
- However, the :const:`Py_TPFLAGS_HAVE_VECTORCALL` flag is not
+ However, the :c:macro:`Py_TPFLAGS_HAVE_VECTORCALL` flag is not
always inherited. If it's not set, then the subclass won't use
:ref:`vectorcall <vectorcall>`, except when
:c:func:`PyVectorcall_Call` is explicitly called.
@@ -1022,9 +1022,9 @@ and :c:type:`PyType_Type` effectively act as defaults.)
this flag bit. The flag bits that pertain to extension structures are strictly
inherited if the extension structure is inherited, i.e. the base type's value of
the flag bit is copied into the subtype together with a pointer to the extension
- structure. The :const:`Py_TPFLAGS_HAVE_GC` flag bit is inherited together with
+ structure. The :c:macro:`Py_TPFLAGS_HAVE_GC` flag bit is inherited together with
the :c:member:`~PyTypeObject.tp_traverse` and :c:member:`~PyTypeObject.tp_clear` fields, i.e. if the
- :const:`Py_TPFLAGS_HAVE_GC` flag bit is clear in the subtype and the
+ :c:macro:`Py_TPFLAGS_HAVE_GC` flag bit is 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.
.. XXX are most flag bits *really* inherited individually?
@@ -1036,12 +1036,14 @@ and :c:type:`PyType_Type` effectively act as defaults.)
**Bit Masks:**
+ .. c:namespace:: NULL
+
The following bit masks are currently defined; these can be ORed together using
the ``|`` operator to form the value of the :c:member:`~PyTypeObject.tp_flags` field. The macro
:c:func:`PyType_HasFeature` takes a type and a flags value, *tp* and *f*, and
checks whether ``tp->tp_flags & f`` is non-zero.
- .. data:: Py_TPFLAGS_HEAPTYPE
+ .. c:macro:: Py_TPFLAGS_HEAPTYPE
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
@@ -1056,7 +1058,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
???
- .. data:: Py_TPFLAGS_BASETYPE
+ .. c:macro:: Py_TPFLAGS_BASETYPE
This bit is set when the type can be used as the base type of another type. If
this bit is clear, the type cannot be subtyped (similar to a "final" class in
@@ -1067,7 +1069,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
???
- .. data:: Py_TPFLAGS_READY
+ .. c:macro:: Py_TPFLAGS_READY
This bit is set when the type object has been fully initialized by
:c:func:`PyType_Ready`.
@@ -1077,7 +1079,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
???
- .. data:: Py_TPFLAGS_READYING
+ .. c:macro:: Py_TPFLAGS_READYING
This bit is set while :c:func:`PyType_Ready` is in the process of initializing
the type object.
@@ -1087,7 +1089,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
???
- .. data:: Py_TPFLAGS_HAVE_GC
+ .. c:macro:: Py_TPFLAGS_HAVE_GC
This bit is set when the object supports garbage collection. If this bit
is set, instances must be created using :c:func:`PyObject_GC_New` and
@@ -1098,28 +1100,28 @@ and :c:type:`PyType_Type` effectively act as defaults.)
**Inheritance:**
- Group: :const:`Py_TPFLAGS_HAVE_GC`, :attr:`tp_traverse`, :attr:`tp_clear`
+ Group: :c:macro:`Py_TPFLAGS_HAVE_GC`, :attr:`tp_traverse`, :attr:`tp_clear`
- The :const:`Py_TPFLAGS_HAVE_GC` flag bit is inherited
+ The :c:macro:`Py_TPFLAGS_HAVE_GC` flag bit is inherited
together with the :attr:`tp_traverse` and :attr:`tp_clear`
- fields, i.e. if the :const:`Py_TPFLAGS_HAVE_GC` flag bit is
+ 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``
values.
- .. data:: Py_TPFLAGS_DEFAULT
+ .. c:macro:: Py_TPFLAGS_DEFAULT
This is a bitmask of all the bits that pertain to the existence of certain
fields in the type object and its extension structures. Currently, it includes
- the following bits: :const:`Py_TPFLAGS_HAVE_STACKLESS_EXTENSION`.
+ the following bits: :c:macro:`Py_TPFLAGS_HAVE_STACKLESS_EXTENSION`.
**Inheritance:**
???
- .. data:: Py_TPFLAGS_METHOD_DESCRIPTOR
+ .. c:macro:: Py_TPFLAGS_METHOD_DESCRIPTOR
This bit indicates that objects behave like unbound methods.
@@ -1140,15 +1142,15 @@ and :c:type:`PyType_Type` effectively act as defaults.)
**Inheritance:**
This flag is never inherited by types without the
- :const:`Py_TPFLAGS_IMMUTABLETYPE` flag set. For extension types, it is
+ :c:macro:`Py_TPFLAGS_IMMUTABLETYPE` flag set. For extension types, it is
inherited whenever :c:member:`~PyTypeObject.tp_descr_get` is inherited.
- .. data:: Py_TPFLAGS_MANAGED_DICT
+ .. c:macro:: Py_TPFLAGS_MANAGED_DICT
This bit indicates that instances of the class have a ``__dict__``
attribute, and that the space for the dictionary is managed by the VM.
- If this flag is set, :const:`Py_TPFLAGS_HAVE_GC` should also be set.
+ If this flag is set, :c:macro:`Py_TPFLAGS_HAVE_GC` should also be set.
.. versionadded:: 3.12
@@ -1158,7 +1160,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
:c:member:`~PyTypeObject.tp_dictoffset` field is set in a superclass.
- .. data:: Py_TPFLAGS_MANAGED_WEAKREF
+ .. c:macro:: Py_TPFLAGS_MANAGED_WEAKREF
This bit indicates that instances of the class should be weakly
referenceable.
@@ -1171,7 +1173,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
:c:member:`~PyTypeObject.tp_weaklistoffset` field is set in a superclass.
- .. data:: Py_TPFLAGS_ITEMS_AT_END
+ .. c:macro:: Py_TPFLAGS_ITEMS_AT_END
Only usable with variable-size types, i.e. ones with non-zero
:c:member:`~PyObject.tp_itemsize`.
@@ -1194,14 +1196,14 @@ and :c:type:`PyType_Type` effectively act as defaults.)
.. XXX Document more flags here?
- .. data:: Py_TPFLAGS_LONG_SUBCLASS
- .. data:: Py_TPFLAGS_LIST_SUBCLASS
- .. data:: Py_TPFLAGS_TUPLE_SUBCLASS
- .. data:: Py_TPFLAGS_BYTES_SUBCLASS
- .. data:: Py_TPFLAGS_UNICODE_SUBCLASS
- .. data:: Py_TPFLAGS_DICT_SUBCLASS
- .. data:: Py_TPFLAGS_BASE_EXC_SUBCLASS
- .. data:: Py_TPFLAGS_TYPE_SUBCLASS
+ .. c:macro:: Py_TPFLAGS_LONG_SUBCLASS
+ .. c:macro:: Py_TPFLAGS_LIST_SUBCLASS
+ .. c:macro:: Py_TPFLAGS_TUPLE_SUBCLASS
+ .. c:macro:: Py_TPFLAGS_BYTES_SUBCLASS
+ .. c:macro:: Py_TPFLAGS_UNICODE_SUBCLASS
+ .. c:macro:: Py_TPFLAGS_DICT_SUBCLASS
+ .. c:macro:: Py_TPFLAGS_BASE_EXC_SUBCLASS
+ .. c:macro:: Py_TPFLAGS_TYPE_SUBCLASS
These flags are used by functions such as
:c:func:`PyLong_Check` to quickly determine if a type is a subclass
@@ -1212,7 +1214,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
will behave differently depending on what kind of check is used.
- .. data:: Py_TPFLAGS_HAVE_FINALIZE
+ .. c:macro:: Py_TPFLAGS_HAVE_FINALIZE
This bit is set when the :c:member:`~PyTypeObject.tp_finalize` slot is present in the
type structure.
@@ -1225,7 +1227,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
type structure.
- .. data:: Py_TPFLAGS_HAVE_VECTORCALL
+ .. c:macro:: Py_TPFLAGS_HAVE_VECTORCALL
This bit is set when the class implements
the :ref:`vectorcall protocol <vectorcall>`.
@@ -1245,7 +1247,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
This flag can now be inherited by mutable classes.
- .. data:: Py_TPFLAGS_IMMUTABLETYPE
+ .. c:macro:: Py_TPFLAGS_IMMUTABLETYPE
This bit is set for type objects that are immutable: type attributes cannot be set nor deleted.
@@ -1258,7 +1260,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
.. versionadded:: 3.10
- .. data:: Py_TPFLAGS_DISALLOW_INSTANTIATION
+ .. c:macro:: Py_TPFLAGS_DISALLOW_INSTANTIATION
Disallow creating instances of the type: set
:c:member:`~PyTypeObject.tp_new` to NULL and don't create the ``__new__``
@@ -1289,7 +1291,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
.. versionadded:: 3.10
- .. data:: Py_TPFLAGS_MAPPING
+ .. c:macro:: Py_TPFLAGS_MAPPING
This bit indicates that instances of the class may match mapping patterns
when used as the subject of a :keyword:`match` block. It is automatically
@@ -1298,20 +1300,20 @@ and :c:type:`PyType_Type` effectively act as defaults.)
.. note::
- :const:`Py_TPFLAGS_MAPPING` and :const:`Py_TPFLAGS_SEQUENCE` are
+ :c:macro:`Py_TPFLAGS_MAPPING` and :c:macro:`Py_TPFLAGS_SEQUENCE` are
mutually exclusive; it is an error to enable both flags simultaneously.
**Inheritance:**
This flag is inherited by types that do not already set
- :const:`Py_TPFLAGS_SEQUENCE`.
+ :c:macro:`Py_TPFLAGS_SEQUENCE`.
.. seealso:: :pep:`634` -- Structural Pattern Matching: Specification
.. versionadded:: 3.10
- .. data:: Py_TPFLAGS_SEQUENCE
+ .. c:macro:: Py_TPFLAGS_SEQUENCE
This bit indicates that instances of the class may match sequence patterns
when used as the subject of a :keyword:`match` block. It is automatically
@@ -1320,20 +1322,20 @@ and :c:type:`PyType_Type` effectively act as defaults.)
.. note::
- :const:`Py_TPFLAGS_MAPPING` and :const:`Py_TPFLAGS_SEQUENCE` are
+ :c:macro:`Py_TPFLAGS_MAPPING` and :c:macro:`Py_TPFLAGS_SEQUENCE` are
mutually exclusive; it is an error to enable both flags simultaneously.
**Inheritance:**
This flag is inherited by types that do not already set
- :const:`Py_TPFLAGS_MAPPING`.
+ :c:macro:`Py_TPFLAGS_MAPPING`.
.. seealso:: :pep:`634` -- Structural Pattern Matching: Specification
.. versionadded:: 3.10
- .. data:: Py_TPFLAGS_VALID_VERSION_TAG
+ .. c:macro:: Py_TPFLAGS_VALID_VERSION_TAG
Internal. Do not set or unset this flag.
To indicate that a class has changed call :c:func:`PyType_Modified`
@@ -1357,7 +1359,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
.. c:member:: traverseproc PyTypeObject.tp_traverse
An optional pointer to a traversal function for the garbage collector. This is
- only used if the :const:`Py_TPFLAGS_HAVE_GC` flag bit is set. The signature is::
+ only used if the :c:macro:`Py_TPFLAGS_HAVE_GC` flag bit is set. The signature is::
int tp_traverse(PyObject *self, visitproc visit, void *arg);
@@ -1419,10 +1421,10 @@ and :c:type:`PyType_Type` effectively act as defaults.)
**Inheritance:**
- Group: :const:`Py_TPFLAGS_HAVE_GC`, :attr:`tp_traverse`, :attr:`tp_clear`
+ Group: :c:macro:`Py_TPFLAGS_HAVE_GC`, :attr:`tp_traverse`, :attr:`tp_clear`
This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_clear` and the
- :const:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :c:member:`~PyTypeObject.tp_traverse`, and
+ :c:macro:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :c:member:`~PyTypeObject.tp_traverse`, and
:c:member:`~PyTypeObject.tp_clear` are all inherited from the base type if they are all zero in
the subtype.
@@ -1430,7 +1432,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
.. c:member:: inquiry PyTypeObject.tp_clear
An optional pointer to a clear function for the garbage collector. This is only
- used if the :const:`Py_TPFLAGS_HAVE_GC` flag bit is set. The signature is::
+ used if the :c:macro:`Py_TPFLAGS_HAVE_GC` flag bit is set. The signature is::
int tp_clear(PyObject *);
@@ -1486,10 +1488,10 @@ and :c:type:`PyType_Type` effectively act as defaults.)
**Inheritance:**
- Group: :const:`Py_TPFLAGS_HAVE_GC`, :attr:`tp_traverse`, :attr:`tp_clear`
+ Group: :c:macro:`Py_TPFLAGS_HAVE_GC`, :attr:`tp_traverse`, :attr:`tp_clear`
This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_traverse` and the
- :const:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :c:member:`~PyTypeObject.tp_traverse`, and
+ :c:macro:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :c:member:`~PyTypeObject.tp_traverse`, and
:c:member:`~PyTypeObject.tp_clear` are all inherited from the base type if they are all zero in
the subtype.
@@ -1511,21 +1513,21 @@ and :c:type:`PyType_Type` effectively act as defaults.)
The following constants are defined to be used as the third argument for
:c:member:`~PyTypeObject.tp_richcompare` and for :c:func:`PyObject_RichCompare`:
- +----------------+------------+
- | Constant | Comparison |
- +================+============+
- | :const:`Py_LT` | ``<`` |
- +----------------+------------+
- | :const:`Py_LE` | ``<=`` |
- +----------------+------------+
- | :const:`Py_EQ` | ``==`` |
- +----------------+------------+
- | :const:`Py_NE` | ``!=`` |
- +----------------+------------+
- | :const:`Py_GT` | ``>`` |
- +----------------+------------+
- | :const:`Py_GE` | ``>=`` |
- +----------------+------------+
+ +------------------+------------+
+ | Constant | Comparison |
+ +==================+============+
+ | :c:macro:`Py_LT` | ``<`` |
+ +------------------+------------+
+ | :c:macro:`Py_LE` | ``<=`` |
+ +------------------+------------+
+ | :c:macro:`Py_EQ` | ``==`` |
+ +------------------+------------+
+ | :c:macro:`Py_NE` | ``!=`` |
+ +------------------+------------+
+ | :c:macro:`Py_GT` | ``>`` |
+ +------------------+------------+
+ | :c:macro:`Py_GE` | ``>=`` |
+ +------------------+------------+
The following macro is defined to ease writing rich comparison functions:
@@ -1563,7 +1565,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
.. c:member:: Py_ssize_t PyTypeObject.tp_weaklistoffset
- While this field is still supported, :const:`Py_TPFLAGS_MANAGED_WEAKREF`
+ While this field is still supported, :c:macro:`Py_TPFLAGS_MANAGED_WEAKREF`
should be used instead, if at all possible.
If the instances of this type are weakly referenceable, this field is greater
@@ -1576,7 +1578,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
Do not confuse this field with :c:member:`~PyTypeObject.tp_weaklist`; that is the list head for
weak references to the type object itself.
- It is an error to set both the :const:`Py_TPFLAGS_MANAGED_WEAKREF` bit and
+ It is an error to set both the :c:macro:`Py_TPFLAGS_MANAGED_WEAKREF` bit and
:c:member:`~PyTypeObject.tp_weaklist`.
**Inheritance:**
@@ -1588,7 +1590,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
**Default:**
- If the :const:`Py_TPFLAGS_MANAGED_WEAKREF` bit is set in the
+ If the :c:macro:`Py_TPFLAGS_MANAGED_WEAKREF` bit is set in the
:c:member:`~PyTypeObject.tp_dict` field, then
:c:member:`~PyTypeObject.tp_weaklistoffset` will be set to a negative value,
to indicate that it is unsafe to use this field.
@@ -1782,7 +1784,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
.. c:member:: Py_ssize_t PyTypeObject.tp_dictoffset
- While this field is still supported, :const:`Py_TPFLAGS_MANAGED_DICT` should be
+ While this field is still supported, :c:macro:`Py_TPFLAGS_MANAGED_DICT` should be
used instead, if at all possible.
If the instances of this type have a dictionary containing instance variables,
@@ -1801,7 +1803,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
dictionary, so it is may be more efficient to call :c:func:`PyObject_GetAttr`
when accessing an attribute on the object.
- It is an error to set both the :const:`Py_TPFLAGS_MANAGED_WEAKREF` bit and
+ It is an error to set both the :c:macro:`Py_TPFLAGS_MANAGED_WEAKREF` bit and
:c:member:`~PyTypeObject.tp_dictoffset`.
**Inheritance:**
@@ -1809,14 +1811,14 @@ and :c:type:`PyType_Type` effectively act as defaults.)
This field is inherited by subtypes. A subtype should not override this offset;
doing so could be unsafe, if C code tries to access the dictionary at the
previous offset.
- To properly support inheritance, use :const:`Py_TPFLAGS_MANAGED_DICT`.
+ To properly support inheritance, use :c:macro:`Py_TPFLAGS_MANAGED_DICT`.
**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.
- If the :const:`Py_TPFLAGS_MANAGED_DICT` bit is set in the
+ If the :c:macro:`Py_TPFLAGS_MANAGED_DICT` bit is set in the
:c:member:`~PyTypeObject.tp_dict` field, then
:c:member:`~PyTypeObject.tp_dictoffset` will be set to ``-1``, to indicate
that it is unsafe to use this field.
@@ -1903,7 +1905,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
in :c:member:`~PyTypeObject.tp_new`, while for mutable types, most initialization should be
deferred to :c:member:`~PyTypeObject.tp_init`.
- Set the :const:`Py_TPFLAGS_DISALLOW_INSTANTIATION` flag to disallow creating
+ Set the :c:macro:`Py_TPFLAGS_DISALLOW_INSTANTIATION` flag to disallow creating
instances of the type in Python.
**Inheritance:**
@@ -1937,7 +1939,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
In dynamic subtypes, this field is set to a deallocator suitable to
match :c:func:`PyType_GenericAlloc` and the value of the
- :const:`Py_TPFLAGS_HAVE_GC` flag bit.
+ :c:macro:`Py_TPFLAGS_HAVE_GC` flag bit.
For static subtypes, :c:type:`PyBaseObject_Type` uses PyObject_Del.
@@ -1948,7 +1950,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
The garbage collector needs to know whether a particular object is collectible
or not. Normally, it is sufficient to look at the object's type's
- :c:member:`~PyTypeObject.tp_flags` field, and check the :const:`Py_TPFLAGS_HAVE_GC` flag bit. But
+ :c:member:`~PyTypeObject.tp_flags` field, and check the :c:macro:`Py_TPFLAGS_HAVE_GC` flag bit. But
some types have a mixture of statically and dynamically allocated instances, and
the statically allocated instances are not collectible. Such types should
define this function; it should return ``1`` for a collectible instance, and
@@ -1967,7 +1969,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
**Default:**
This slot has no default. If this field is ``NULL``,
- :const:`Py_TPFLAGS_HAVE_GC` is used as the functional equivalent.
+ :c:macro:`Py_TPFLAGS_HAVE_GC` is used as the functional equivalent.
.. c:member:: PyObject* PyTypeObject.tp_bases
@@ -2114,7 +2116,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
.. versionchanged:: 3.8
Before version 3.8 it was necessary to set the
- :const:`Py_TPFLAGS_HAVE_FINALIZE` flags bit in order for this field to be
+ :c:macro:`Py_TPFLAGS_HAVE_FINALIZE` flags bit in order for this field to be
used. This is no longer required.
.. seealso:: "Safe object finalization" (:pep:`442`)
@@ -2173,7 +2175,7 @@ Heap Types
An alternative to :ref:`static types <static-types>` is *heap-allocated types*,
or *heap types* for short, which correspond closely to classes created by
-Python's ``class`` statement. Heap types have the :const:`Py_TPFLAGS_HEAPTYPE`
+Python's ``class`` statement. Heap types have the :c:macro:`Py_TPFLAGS_HEAPTYPE`
flag set.
This is done by filling a :c:type:`PyType_Spec` structure and calling
@@ -2781,7 +2783,7 @@ A type that supports weakrefs, instance dicts, and hashing::
A str subclass that cannot be subclassed and cannot be called
to create instances (e.g. uses a separate factory func) using
-:c:data:`Py_TPFLAGS_DISALLOW_INSTANTIATION` flag::
+:c:macro:`Py_TPFLAGS_DISALLOW_INSTANTIATION` flag::
typedef struct {
PyUnicodeObject raw;
diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst
index 33437b6193919..8a989c2afe871 100644
--- a/Doc/c-api/unicode.rst
+++ b/Doc/c-api/unicode.rst
@@ -1299,7 +1299,7 @@ the user settings on the machine running the codec.
Encode the Unicode object using the specified code page and return a Python
bytes object. Return ``NULL`` if an exception was raised by the codec. Use
- :c:data:`CP_ACP` code page to get the MBCS encoder.
+ :c:macro:`CP_ACP` code page to get the MBCS encoder.
.. versionadded:: 3.3
@@ -1418,11 +1418,11 @@ They all return ``NULL`` or ``-1`` if an exception occurs.
Rich compare two Unicode strings and return one of the following:
* ``NULL`` in case an exception was raised
- * :const:`Py_True` or :const:`Py_False` for successful comparisons
- * :const:`Py_NotImplemented` in case the type combination is unknown
+ * :c:data:`Py_True` or :c:data:`Py_False` for successful comparisons
+ * :c:data:`Py_NotImplemented` in case the type combination is unknown
- Possible values for *op* are :const:`Py_GT`, :const:`Py_GE`, :const:`Py_EQ`,
- :const:`Py_NE`, :const:`Py_LT`, and :const:`Py_LE`.
+ Possible values for *op* are :c:macro:`Py_GT`, :c:macro:`Py_GE`, :c:macro:`Py_EQ`,
+ :c:macro:`Py_NE`, :c:macro:`Py_LT`, and :c:macro:`Py_LE`.
.. c:function:: PyObject* PyUnicode_Format(PyObject *format, PyObject *args)
diff --git a/Doc/c-api/veryhigh.rst b/Doc/c-api/veryhigh.rst
index 000a2d3d8790b..1e8a945512d78 100644
--- a/Doc/c-api/veryhigh.rst
+++ b/Doc/c-api/veryhigh.rst
@@ -12,8 +12,8 @@ file or a buffer, but they will not let you interact in a more detailed way with
the interpreter.
Several of these functions accept a start symbol from the grammar as a
-parameter. The available start symbols are :const:`Py_eval_input`,
-:const:`Py_file_input`, and :const:`Py_single_input`. These are described
+parameter. The available start symbols are :c:data:`Py_eval_input`,
+:c:data:`Py_file_input`, and :c:data:`Py_single_input`. These are described
following the functions which accept them as parameters.
Note also that several of these functions take :c:expr:`FILE*` parameters. One
@@ -256,8 +256,8 @@ the same library that the Python runtime is using.
Parse and compile the Python source code in *str*, returning the resulting code
object. The start token is given by *start*; this can be used to constrain the
- code which can be compiled and should be :const:`Py_eval_input`,
- :const:`Py_file_input`, or :const:`Py_single_input`. The filename specified by
+ code which can be compiled and should be :c:data:`Py_eval_input`,
+ :c:data:`Py_file_input`, or :c:data:`Py_single_input`. The filename specified by
*filename* is used to construct the code object and may appear in tracebacks or
:exc:`SyntaxError` exception messages. This returns ``NULL`` if the code
cannot be parsed or compiled.
diff --git a/Doc/extending/extending.rst b/Doc/extending/extending.rst
index d9bf4fd6c7ae0..76e0490d0d22d 100644
--- a/Doc/extending/extending.rst
+++ b/Doc/extending/extending.rst
@@ -335,7 +335,7 @@ When using only ``METH_VARARGS``, the function should expect the Python-level
parameters to be passed in as a tuple acceptable for parsing via
:c:func:`PyArg_ParseTuple`; more information on this function is provided below.
-The :const:`METH_KEYWORDS` bit may be set in the third field if keyword
+The :c:macro:`METH_KEYWORDS` bit may be set in the third field if keyword
arguments should be passed to the function. In this case, the C function should
accept a third ``PyObject *`` parameter which will be a dictionary of keywords.
Use :c:func:`PyArg_ParseTupleAndKeywords` to parse the arguments to such a
@@ -527,7 +527,7 @@ be part of a module definition::
}
This function must be registered with the interpreter using the
-:const:`METH_VARARGS` flag; this is described in section :ref:`methodtable`. The
+:c:macro:`METH_VARARGS` flag; this is described in section :ref:`methodtable`. The
:c:func:`PyArg_ParseTuple` function and its arguments are documented in section
:ref:`parsetuple`.
diff --git a/Doc/extending/newtypes_tutorial.rst b/Doc/extending/newtypes_tutorial.rst
index f89934a11f12a..ba09fb1b05c0b 100644
--- a/Doc/extending/newtypes_tutorial.rst
+++ b/Doc/extending/newtypes_tutorial.rst
@@ -151,7 +151,7 @@ only used for variable-sized objects and should otherwise be zero.
base type will be :class:`object`, or else you will be adding data members to
your base type, and therefore increasing its size.
-We set the class flags to :const:`Py_TPFLAGS_DEFAULT`. ::
+We set the class flags to :c:macro:`Py_TPFLAGS_DEFAULT`. ::
.tp_flags = Py_TPFLAGS_DEFAULT,
@@ -498,7 +498,7 @@ definitions::
{NULL} /* Sentinel */
};
-(note that we used the :const:`METH_NOARGS` flag to indicate that the method
+(note that we used the :c:macro:`METH_NOARGS` flag to indicate that the method
is expecting no arguments other than *self*)
and assign it to the :c:member:`~PyTypeObject.tp_methods` slot::
@@ -508,7 +508,7 @@ and assign it to the :c:member:`~PyTypeObject.tp_methods` slot::
Finally, we'll make our type usable as a base class for subclassing. We've
written our methods carefully so far so that they don't make any assumptions
about the type of the object being created or used, so all we need to do is
-to add the :const:`Py_TPFLAGS_BASETYPE` to our class flag definition::
+to add the :c:macro:`Py_TPFLAGS_BASETYPE` to our class flag definition::
.tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE,
@@ -774,7 +774,7 @@ and ``Custom_clear``::
Py_TYPE(self)->tp_free((PyObject *) self);
}
-Finally, we add the :const:`Py_TPFLAGS_HAVE_GC` flag to the class flags::
+Finally, we add the :c:macro:`Py_TPFLAGS_HAVE_GC` flag to the class flags::
.tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC,
diff --git a/Doc/howto/isolating-extensions.rst b/Doc/howto/isolating-extensions.rst
index 8adb85f3a8740..f01801ea47212 100644
--- a/Doc/howto/isolating-extensions.rst
+++ b/Doc/howto/isolating-extensions.rst
@@ -298,10 +298,10 @@ Watch out for the following two points in particular (but note that this is not
a comprehensive list):
* Unlike static types, heap type objects are mutable by default.
- Use the :c:data:`Py_TPFLAGS_IMMUTABLETYPE` flag to prevent mutability.
+ Use the :c:macro:`Py_TPFLAGS_IMMUTABLETYPE` flag to prevent mutability.
* Heap types inherit :c:member:`~PyTypeObject.tp_new` by default,
so it may become possible to instantiate them from Python code.
- You can prevent this with the :c:data:`Py_TPFLAGS_DISALLOW_INSTANTIATION` flag.
+ You can prevent this with the :c:macro:`Py_TPFLAGS_DISALLOW_INSTANTIATION` flag.
Defining Heap Types
@@ -333,12 +333,12 @@ To avoid memory leaks, instances of heap types must implement the
garbage collection protocol.
That is, heap types should:
-- Have the :c:data:`Py_TPFLAGS_HAVE_GC` flag.
+- Have the :c:macro:`Py_TPFLAGS_HAVE_GC` flag.
- Define a traverse function using ``Py_tp_traverse``, which
visits the type (e.g. using :c:expr:`Py_VISIT(Py_TYPE(self))`).
Please refer to the :ref:`the documentation <type-structs>` of
-:c:data:`Py_TPFLAGS_HAVE_GC` and :c:member:`~PyTypeObject.tp_traverse`
+:c:macro:`Py_TPFLAGS_HAVE_GC` and :c:member:`~PyTypeObject.tp_traverse`
for additional considerations.
If your traverse function delegates to the ``tp_traverse`` of its base class
@@ -411,7 +411,7 @@ that subclass, which may be defined in different module than yours.
pass
For a method to get its "defining class", it must use the
-:data:`METH_METHOD | METH_FASTCALL | METH_KEYWORDS`
+:ref:`METH_METHOD | METH_FASTCALL | METH_KEYWORDS <METH_METHOD-METH_FASTCALL-METH_KEYWORDS>`
:c:type:`calling convention <PyMethodDef>`
and the corresponding :c:type:`PyCMethod` signature::
diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst
index 3b31384edeb54..97d5121c4e8a5 100644
--- a/Doc/library/dis.rst
+++ b/Doc/library/dis.rst
@@ -818,7 +818,7 @@ iterations of the loop.
.. opcode:: MATCH_MAPPING
If ``STACK[-1]`` is an instance of :class:`collections.abc.Mapping` (or, more
- technically: if it has the :const:`Py_TPFLAGS_MAPPING` flag set in its
+ technically: if it has the :c:macro:`Py_TPFLAGS_MAPPING` flag set in its
:c:member:`~PyTypeObject.tp_flags`), push ``True`` onto the stack. Otherwise,
push ``False``.
@@ -829,7 +829,7 @@ iterations of the loop.
If ``STACK[-1]`` is an instance of :class:`collections.abc.Sequence` and is *not* an instance
of :class:`str`/:class:`bytes`/:class:`bytearray` (or, more technically: if it has
- the :const:`Py_TPFLAGS_SEQUENCE` flag set in its :c:member:`~PyTypeObject.tp_flags`),
+ the :c:macro:`Py_TPFLAGS_SEQUENCE` flag set in its :c:member:`~PyTypeObject.tp_flags`),
push ``True`` onto the stack. Otherwise, push ``False``.
.. versionadded:: 3.10
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index 83abb5d5ca1e4..b35010498f214 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -4308,7 +4308,7 @@ written in Python, such as a mail server's external command delivery program.
specified. If the value specified is 0, the child's process group ID will be
made the same as its process ID. If the value of *setpgroup* is not set, the
child will inherit the parent's process group ID. This argument corresponds
- to the C library :c:data:`POSIX_SPAWN_SETPGROUP` flag.
+ to the C library :c:macro:`POSIX_SPAWN_SETPGROUP` flag.
If the *resetids* argument is ``True`` it will reset the effective UID and
GID of the child to the real UID and GID of the parent process. If the
@@ -4316,27 +4316,27 @@ written in Python, such as a mail server's external command delivery program.
the parent. In either case, if the set-user-ID and set-group-ID permission
bits are enabled on the executable file, their effect will override the
setting of the effective UID and GID. This argument corresponds to the C
- library :c:data:`POSIX_SPAWN_RESETIDS` flag.
+ library :c:macro:`POSIX_SPAWN_RESETIDS` flag.
If the *setsid* argument is ``True``, it will create a new session ID
- for ``posix_spawn``. *setsid* requires :c:data:`POSIX_SPAWN_SETSID`
- or :c:data:`POSIX_SPAWN_SETSID_NP` flag. Otherwise, :exc:`NotImplementedError`
+ for ``posix_spawn``. *setsid* requires :c:macro:`POSIX_SPAWN_SETSID`
+ or :c:macro:`POSIX_SPAWN_SETSID_NP` flag. Otherwise, :exc:`NotImplementedError`
is raised.
The *setsigmask* argument will set the signal mask to the signal set
specified. If the parameter is not used, then the child inherits the
parent's signal mask. This argument corresponds to the C library
- :c:data:`POSIX_SPAWN_SETSIGMASK` flag.
+ :c:macro:`POSIX_SPAWN_SETSIGMASK` flag.
The *sigdef* argument will reset the disposition of all signals in the set
specified. This argument corresponds to the C library
- :c:data:`POSIX_SPAWN_SETSIGDEF` flag.
+ :c:macro:`POSIX_SPAWN_SETSIGDEF` flag.
The *scheduler* argument must be a tuple containing the (optional) scheduler
policy and an instance of :class:`sched_param` with the scheduler parameters.
A value of ``None`` in the place of the scheduler policy indicates that is
not being provided. This argument is a combination of the C library
- :c:data:`POSIX_SPAWN_SETSCHEDPARAM` and :c:data:`POSIX_SPAWN_SETSCHEDULER`
+ :c:macro:`POSIX_SPAWN_SETSCHEDPARAM` and :c:macro:`POSIX_SPAWN_SETSCHEDULER`
flags.
.. audit-event:: os.posix_spawn path,argv,env os.posix_spawn
diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst
index 6d30eccab1990..12ad18d411961 100644
--- a/Doc/reference/compound_stmts.rst
+++ b/Doc/reference/compound_stmts.rst
@@ -1840,7 +1840,7 @@ like ``TYPE_PARAMS_OF_ListOrSet`` are not actually bound at runtime.
* a class that inherits from :class:`collections.abc.Sequence`
* a Python class that has been registered as :class:`collections.abc.Sequence`
- * a builtin class that has its (CPython) :data:`Py_TPFLAGS_SEQUENCE` bit set
+ * a builtin class that has its (CPython) :c:macro:`Py_TPFLAGS_SEQUENCE` bit set
* a class that inherits from any of the above
The following standard library classes are sequences:
@@ -1859,7 +1859,7 @@ like ``TYPE_PARAMS_OF_ListOrSet`` are not actually bound at runtime.
* a class that inherits from :class:`collections.abc.Mapping`
* a Python class that has been registered as :class:`collections.abc.Mapping`
- * a builtin class that has its (CPython) :data:`Py_TPFLAGS_MAPPING` bit set
+ * a builtin class that has its (CPython) :c:macro:`Py_TPFLAGS_MAPPING` bit set
* a class that inherits from any of the above
The standard library classes :class:`dict` and :class:`types.MappingProxyType`
diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst
index 1b470d395d6d5..4bf67eb439ec6 100644
--- a/Doc/using/cmdline.rst
+++ b/Doc/using/cmdline.rst
@@ -897,11 +897,11 @@ conflict.
* ``default``: use the :ref:`default memory allocators
<default-memory-allocators>`.
* ``malloc``: use the :c:func:`malloc` function of the C library
- for all domains (:c:data:`PYMEM_DOMAIN_RAW`, :c:data:`PYMEM_DOMAIN_MEM`,
- :c:data:`PYMEM_DOMAIN_OBJ`).
+ for all domains (:c:macro:`PYMEM_DOMAIN_RAW`, :c:macro:`PYMEM_DOMAIN_MEM`,
+ :c:macro:`PYMEM_DOMAIN_OBJ`).
* ``pymalloc``: use the :ref:`pymalloc allocator <pymalloc>` for
- :c:data:`PYMEM_DOMAIN_MEM` and :c:data:`PYMEM_DOMAIN_OBJ` domains and use
- the :c:func:`malloc` function for the :c:data:`PYMEM_DOMAIN_RAW` domain.
+ :c:macro:`PYMEM_DOMAIN_MEM` and :c:macro:`PYMEM_DOMAIN_OBJ` domains and use
+ the :c:func:`malloc` function for the :c:macro:`PYMEM_DOMAIN_RAW` domain.
Install :ref:`debug hooks <pymem-debug-hooks>`:
diff --git a/Doc/whatsnew/2.2.rst b/Doc/whatsnew/2.2.rst
index 82aff0be1ed3b..44e9bd8d492bf 100644
--- a/Doc/whatsnew/2.2.rst
+++ b/Doc/whatsnew/2.2.rst
@@ -1105,11 +1105,11 @@ code, none of the changes described here will affect you very much.
expected, and a set of pointers to :c:expr:`PyObject*` variables that will be
filled in with argument values.
-* Two new flags :const:`METH_NOARGS` and :const:`METH_O` are available in method
+* Two new flags :c:macro:`METH_NOARGS` and :c:macro:`METH_O` are available in method
definition tables to simplify implementation of methods with no arguments or a
single untyped argument. Calling such methods is more efficient than calling a
- corresponding method that uses :const:`METH_VARARGS`. Also, the old
- :const:`METH_OLDARGS` style of writing C methods is now officially deprecated.
+ corresponding method that uses :c:macro:`METH_VARARGS`. Also, the old
+ :c:macro:`METH_OLDARGS` style of writing C methods is now officially deprecated.
* Two new wrapper functions, :c:func:`PyOS_snprintf` and :c:func:`PyOS_vsnprintf`
were added to provide cross-platform implementations for the relatively new
diff --git a/Doc/whatsnew/2.3.rst b/Doc/whatsnew/2.3.rst
index 4eb864f5092d3..14f951174ba54 100644
--- a/Doc/whatsnew/2.3.rst
+++ b/Doc/whatsnew/2.3.rst
@@ -1474,7 +1474,7 @@ complete list of changes, or look through the CVS logs for all the details.
* On Windows, the :mod:`socket` module now ships with Secure Sockets Layer
(SSL) support.
-* The value of the C :const:`PYTHON_API_VERSION` macro is now exposed at the
+* The value of the C :c:macro:`PYTHON_API_VERSION` macro is now exposed at the
Python level as ``sys.api_version``. The current exception can be cleared by
calling the new :func:`sys.exc_clear` function.
@@ -1899,10 +1899,10 @@ Changes to Python's build process and to the C API include:
* The :c:func:`PyArg_NoArgs` macro is now deprecated, and code that uses it
should be changed. For Python 2.2 and later, the method definition table can
- specify the :const:`METH_NOARGS` flag, signalling that there are no arguments,
+ specify the :c:macro:`METH_NOARGS` flag, signalling that there are no arguments,
and the argument checking can then be removed. If compatibility with pre-2.2
versions of Python is important, the code could use ``PyArg_ParseTuple(args,
- "")`` instead, but this will be slower than using :const:`METH_NOARGS`.
+ "")`` instead, but this will be slower than using :c:macro:`METH_NOARGS`.
* :c:func:`PyArg_ParseTuple` accepts new format characters for various sizes of
unsigned integers: ``B`` for :c:expr:`unsigned char`, ``H`` for :c:expr:`unsigned
@@ -1918,7 +1918,7 @@ Changes to Python's build process and to the C API include:
seconds, according to one measurement).
* It's now possible to define class and static methods for a C extension type by
- setting either the :const:`METH_CLASS` or :const:`METH_STATIC` flags in a
+ setting either the :c:macro:`METH_CLASS` or :c:macro:`METH_STATIC` flags in a
method's :c:type:`PyMethodDef` structure.
* Python now includes a copy of the Expat XML parser's source code, removing any
diff --git a/Doc/whatsnew/2.4.rst b/Doc/whatsnew/2.4.rst
index 98dc83fe935d5..d68f600ba44f6 100644
--- a/Doc/whatsnew/2.4.rst
+++ b/Doc/whatsnew/2.4.rst
@@ -1476,7 +1476,7 @@ Some of the changes to Python's build process and to the C API are:
:c:func:`PyArg_ParseTupleAndKeywords` but takes a :c:type:`va_list` instead of a
number of arguments. (Contributed by Greg Chapman.)
-* A new method flag, :const:`METH_COEXISTS`, allows a function defined in slots
+* A new method flag, :c:macro:`METH_COEXISTS`, allows a function defined in slots
to co-exist with a :c:type:`PyCFunction` having the same name. This can halve
the access time for a method such as :meth:`set.__contains__`. (Contributed by
Raymond Hettinger.)
diff --git a/Doc/whatsnew/2.6.rst b/Doc/whatsnew/2.6.rst
index 84bb651e68eed..72a273fdd8d12 100644
--- a/Doc/whatsnew/2.6.rst
+++ b/Doc/whatsnew/2.6.rst
@@ -1138,11 +1138,11 @@ indicate that the external caller is done.
The *flags* argument to :c:func:`PyObject_GetBuffer` specifies
constraints upon the memory returned. Some examples are:
- * :const:`PyBUF_WRITABLE` indicates that the memory must be writable.
+ * :c:macro:`PyBUF_WRITABLE` indicates that the memory must be writable.
- * :const:`PyBUF_LOCK` requests a read-only or exclusive lock on the memory.
+ * :c:macro:`PyBUF_LOCK` requests a read-only or exclusive lock on the memory.
- * :const:`PyBUF_C_CONTIGUOUS` and :const:`PyBUF_F_CONTIGUOUS`
+ * :c:macro:`PyBUF_C_CONTIGUOUS` and :c:macro:`PyBUF_F_CONTIGUOUS`
requests a C-contiguous (last dimension varies the fastest) or
Fortran-contiguous (first dimension varies the fastest) array layout.
diff --git a/Doc/whatsnew/2.7.rst b/Doc/whatsnew/2.7.rst
index 36afcb163f1af..e6bc9a21b365d 100644
--- a/Doc/whatsnew/2.7.rst
+++ b/Doc/whatsnew/2.7.rst
@@ -2231,7 +2231,7 @@ Changes to Python's build process and to the C API include:
* When using the :c:type:`PyMemberDef` structure to define attributes
of a type, Python will no longer let you try to delete or set a
- :const:`T_STRING_INPLACE` attribute.
+ :c:macro:`T_STRING_INPLACE` attribute.
.. rev 79644
diff --git a/Doc/whatsnew/3.10.rst b/Doc/whatsnew/3.10.rst
index 661eeaedbfc0d..7f80852c49548 100644
--- a/Doc/whatsnew/3.10.rst
+++ b/Doc/whatsnew/3.10.rst
@@ -2124,11 +2124,11 @@ New Features
These functions allow to activate, deactivate and query the state of the garbage collector from C code without
having to import the :mod:`gc` module.
-* Add a new :c:data:`Py_TPFLAGS_DISALLOW_INSTANTIATION` type flag to disallow
+* Add a new :c:macro:`Py_TPFLAGS_DISALLOW_INSTANTIATION` type flag to disallow
creating type instances.
(Contributed by Victor Stinner in :issue:`43916`.)
-* Add a new :c:data:`Py_TPFLAGS_IMMUTABLETYPE` type flag for creating immutable
+* Add a new :c:macro:`Py_TPFLAGS_IMMUTABLETYPE` type flag for creating immutable
type objects: type attributes cannot be set nor deleted.
(Contributed by Victor Stinner and Erlend E. Aasland in :issue:`43908`.)
@@ -2187,9 +2187,9 @@ Porting to Python 3.10
been included directly, consider including ``Python.h`` instead.
(Contributed by Nicholas Sim in :issue:`35134`.)
-* Use the :c:data:`Py_TPFLAGS_IMMUTABLETYPE` type flag to create immutable type
- objects. Do not rely on :c:data:`Py_TPFLAGS_HEAPTYPE` to decide if a type
- object is mutable or not; check if :c:data:`Py_TPFLAGS_IMMUTABLETYPE` is set
+* Use the :c:macro:`Py_TPFLAGS_IMMUTABLETYPE` type flag to create immutable type
+ objects. Do not rely on :c:macro:`Py_TPFLAGS_HEAPTYPE` to decide if a type
+ object is mutable or not; check if :c:macro:`Py_TPFLAGS_IMMUTABLETYPE` is set
instead.
(Contributed by Victor Stinner and Erlend E. Aasland in :issue:`43908`.)
diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst
index c06ce78368985..5ff99fc2d3f61 100644
--- a/Doc/whatsnew/3.11.rst
+++ b/Doc/whatsnew/3.11.rst
@@ -2347,11 +2347,11 @@ Porting to Python 3.11
#endif
* The :c:func:`PyType_Ready` function now raises an error if a type is defined
- with the :const:`Py_TPFLAGS_HAVE_GC` flag set but has no traverse function
+ with the :c:macro:`Py_TPFLAGS_HAVE_GC` flag set but has no traverse function
(:c:member:`PyTypeObject.tp_traverse`).
(Contributed by Victor Stinner in :issue:`44263`.)
-* Heap types with the :const:`Py_TPFLAGS_IMMUTABLETYPE` flag can now inherit
+* Heap types with the :c:macro:`Py_TPFLAGS_IMMUTABLETYPE` flag can now inherit
the :pep:`590` vectorcall protocol. Previously, this was only possible for
:ref:`static types <static-types>`.
(Contributed by Erlend E. Aasland in :issue:`43908`)
diff --git a/Doc/whatsnew/3.12.rst b/Doc/whatsnew/3.12.rst
index 068618fe48e1b..03d559e455393 100644
--- a/Doc/whatsnew/3.12.rst
+++ b/Doc/whatsnew/3.12.rst
@@ -1110,7 +1110,7 @@ Pending Removal in Python 3.14
* :class:`typing.ByteString`, deprecated since Python 3.9, now causes a
:exc:`DeprecationWarning` to be emitted when it is used.
-* Creating immutable types (:data:`Py_TPFLAGS_IMMUTABLETYPE`) with mutable
+* Creating immutable types (:c:macro:`Py_TPFLAGS_IMMUTABLETYPE`) with mutable
bases using the C API.
* Deprecated the *isdst* parameter in :func:`email.utils.localtime`.
@@ -1621,7 +1621,7 @@ New Features
inheriting or extending the base class size.
- :c:func:`PyObject_GetTypeData` and :c:func:`PyType_GetTypeDataSize`
added to allow access to subclass-specific instance data.
- - :const:`Py_TPFLAGS_ITEMS_AT_END` and :c:func:`PyObject_GetItemData`
+ - :c:macro:`Py_TPFLAGS_ITEMS_AT_END` and :c:func:`PyObject_GetItemData`
added to allow safely extending certain variable-sized types, including
:c:var:`PyType_Type`.
- :c:macro:`Py_RELATIVE_OFFSET` added to allow defining
@@ -1638,20 +1638,20 @@ New Features
:ref:`the vectorcall protocol <vectorcall>` was added to the
:ref:`Limited API <stable>`:
- * :const:`Py_TPFLAGS_HAVE_VECTORCALL`
+ * :c:macro:`Py_TPFLAGS_HAVE_VECTORCALL`
* :c:func:`PyVectorcall_NARGS`
* :c:func:`PyVectorcall_Call`
* :c:type:`vectorcallfunc`
- The :const:`Py_TPFLAGS_HAVE_VECTORCALL` flag is now removed from a class
+ The :c:macro:`Py_TPFLAGS_HAVE_VECTORCALL` flag is now removed from a class
when the class's :py:meth:`~object.__call__` method is reassigned.
This makes vectorcall safe to use with mutable types (i.e. heap types
- without the immutable flag, :const:`Py_TPFLAGS_IMMUTABLETYPE`).
+ without the immutable flag, :c:macro:`Py_TPFLAGS_IMMUTABLETYPE`).
Mutable types that do not override :c:member:`~PyTypeObject.tp_call` now
inherit the ``Py_TPFLAGS_HAVE_VECTORCALL`` flag.
(Contributed by Petr Viktorin in :gh:`93274`.)
- The :const:`Py_TPFLAGS_MANAGED_DICT` and :const:`Py_TPFLAGS_MANAGED_WEAKREF`
+ The :c:macro:`Py_TPFLAGS_MANAGED_DICT` and :c:macro:`Py_TPFLAGS_MANAGED_WEAKREF`
flags have been added. This allows extensions classes to support object
``__dict__`` and weakrefs with less bookkeeping,
using less memory and with faster access.
@@ -1662,7 +1662,7 @@ New Features
* :c:func:`PyObject_Vectorcall`
* :c:func:`PyObject_VectorcallMethod`
- * :const:`PY_VECTORCALL_ARGUMENTS_OFFSET`
+ * :c:macro:`PY_VECTORCALL_ARGUMENTS_OFFSET`
This means that both the incoming and outgoing ends of the vector call
protocol are now available in the :ref:`Limited API <stable>`. (Contributed
@@ -1784,13 +1784,13 @@ Porting to Python 3.12
(Contributed by Philip Georgi in :gh:`95504`.)
* Extension classes wanting to add a ``__dict__`` or weak reference slot
- should use :const:`Py_TPFLAGS_MANAGED_DICT` and
- :const:`Py_TPFLAGS_MANAGED_WEAKREF` instead of ``tp_dictoffset`` and
+ should use :c:macro:`Py_TPFLAGS_MANAGED_DICT` and
+ :c:macro:`Py_TPFLAGS_MANAGED_WEAKREF` instead of ``tp_dictoffset`` and
``tp_weaklistoffset``, respectively.
The use of ``tp_dictoffset`` and ``tp_weaklistoffset`` is still
supported, but does not fully support multiple inheritance
(:gh:`95589`), and performance may be worse.
- Classes declaring :const:`Py_TPFLAGS_MANAGED_DICT` should call
+ Classes declaring :c:macro:`Py_TPFLAGS_MANAGED_DICT` should call
:c:func:`!_PyObject_VisitManagedDict` and :c:func:`!_PyObject_ClearManagedDict`
to traverse and clear their instance's dictionaries.
To clear weakrefs, call :c:func:`PyObject_ClearWeakRefs`, as before.
@@ -1844,7 +1844,7 @@ Porting to Python 3.12
:c:member:`~PyTypeObject.tp_init` instead.
- If the metaclass doesn't need to be instantiated from Python,
set its ``tp_new`` to ``NULL`` using
- the :const:`Py_TPFLAGS_DISALLOW_INSTANTIATION` flag.
+ the :c:macro:`Py_TPFLAGS_DISALLOW_INSTANTIATION` flag.
This makes it acceptable for ``PyType_From*`` functions.
- Avoid ``PyType_From*`` functions: if you don't need C-specific features
@@ -1895,7 +1895,7 @@ Deprecated
:c:type:`PyConfig` instead.
(Contributed by Victor Stinner in :gh:`77782`.)
-* Creating immutable types (:const:`Py_TPFLAGS_IMMUTABLETYPE`) with mutable
+* Creating immutable types (:c:macro:`Py_TPFLAGS_IMMUTABLETYPE`) with mutable
bases is deprecated and will be disabled in Python 3.14.
* The ``structmember.h`` header is deprecated, though it continues to be
diff --git a/Doc/whatsnew/3.6.rst b/Doc/whatsnew/3.6.rst
index 3a681754e25dd..07a65d264c435 100644
--- a/Doc/whatsnew/3.6.rst
+++ b/Doc/whatsnew/3.6.rst
@@ -650,8 +650,8 @@ compiled in release mode using ``PYTHONMALLOC=debug``. Effects of debug hooks:
* Detect writes before the start of a buffer (buffer underflows)
* Detect writes after the end of a buffer (buffer overflows)
* Check that the :term:`GIL <global interpreter lock>` is held when allocator
- functions of :c:data:`PYMEM_DOMAIN_OBJ` (ex: :c:func:`PyObject_Malloc`) and
- :c:data:`PYMEM_DOMAIN_MEM` (ex: :c:func:`PyMem_Malloc`) domains are called.
+ functions of :c:macro:`PYMEM_DOMAIN_OBJ` (ex: :c:func:`PyObject_Malloc`) and
+ :c:macro:`PYMEM_DOMAIN_MEM` (ex: :c:func:`PyMem_Malloc`) domains are called.
Checking if the GIL is held is also a new feature of Python 3.6.
@@ -1822,7 +1822,7 @@ Optimizations
up to 80% faster. (Contributed by Josh Snider in :issue:`26574`).
* Allocator functions of the :c:func:`PyMem_Malloc` domain
- (:c:data:`PYMEM_DOMAIN_MEM`) now use the :ref:`pymalloc memory allocator
+ (:c:macro:`PYMEM_DOMAIN_MEM`) now use the :ref:`pymalloc memory allocator
<pymalloc>` instead of :c:func:`malloc` function of the C library. The
pymalloc allocator is optimized for objects smaller or equal to 512 bytes
with a short lifetime, and use :c:func:`malloc` for larger memory blocks.
@@ -1874,8 +1874,8 @@ Build and C API Changes
(Original patch by Alecsandru Patrascu of Intel in :issue:`26359`.)
* The :term:`GIL <global interpreter lock>` must now be held when allocator
- functions of :c:data:`PYMEM_DOMAIN_OBJ` (ex: :c:func:`PyObject_Malloc`) and
- :c:data:`PYMEM_DOMAIN_MEM` (ex: :c:func:`PyMem_Malloc`) domains are called.
+ functions of :c:macro:`PYMEM_DOMAIN_OBJ` (ex: :c:func:`PyObject_Malloc`) and
+ :c:macro:`PYMEM_DOMAIN_MEM` (ex: :c:func:`PyMem_Malloc`) domains are called.
* New :c:func:`Py_FinalizeEx` API which indicates if flushing buffered data
failed.
diff --git a/Doc/whatsnew/3.8.rst b/Doc/whatsnew/3.8.rst
index 85e088b64acb2..61249d479fa04 100644
--- a/Doc/whatsnew/3.8.rst
+++ b/Doc/whatsnew/3.8.rst
@@ -2116,7 +2116,7 @@ Changes in the C API
extension types across feature releases, anymore. A :c:type:`PyTypeObject`
exported by a third-party extension module is supposed to have all the
slots expected in the current Python version, including
- :c:member:`~PyTypeObject.tp_finalize` (:const:`Py_TPFLAGS_HAVE_FINALIZE`
+ :c:member:`~PyTypeObject.tp_finalize` (:c:macro:`Py_TPFLAGS_HAVE_FINALIZE`
is not checked anymore before reading :c:member:`~PyTypeObject.tp_finalize`).
(Contributed by Antoine Pitrou in :issue:`32388`.)
diff --git a/Doc/whatsnew/3.9.rst b/Doc/whatsnew/3.9.rst
index fd86db9630235..49c8bd2f3e07d 100644
--- a/Doc/whatsnew/3.9.rst
+++ b/Doc/whatsnew/3.9.rst
@@ -1276,7 +1276,7 @@ New Features
* :pep:`573`: Added :c:func:`PyType_FromModuleAndSpec` to associate
a module with a class; :c:func:`PyType_GetModule` and
:c:func:`PyType_GetModuleState` to retrieve the module and its state; and
- :c:data:`PyCMethod` and :c:data:`METH_METHOD` to allow a method to
+ :c:data:`PyCMethod` and :c:macro:`METH_METHOD` to allow a method to
access the class it was defined in.
(Contributed by Marcel Plch and Petr Viktorin in :issue:`38787`.)
diff --git a/Misc/NEWS.d/3.10.0a3.rst b/Misc/NEWS.d/3.10.0a3.rst
index 699a0dd9e8d7c..70b79f5f250a1 100644
--- a/Misc/NEWS.d/3.10.0a3.rst
+++ b/Misc/NEWS.d/3.10.0a3.rst
@@ -1466,7 +1466,7 @@ success. Patch by Victor Stinner.
.. nonce: S3FWTP
.. section: C API
-The :c:data:`METH_FASTCALL` calling convention is added to the limited API.
+The :c:macro:`METH_FASTCALL` calling convention is added to the limited API.
The functions :c:func:`PyModule_AddType`,
:c:func:`PyType_FromModuleAndSpec`, :c:func:`PyType_GetModule` and
:c:func:`PyType_GetModuleState` are added to the limited API on Windows.
diff --git a/Misc/NEWS.d/3.10.0b1.rst b/Misc/NEWS.d/3.10.0b1.rst
index f29fc6632db26..38e0af17a2c66 100644
--- a/Misc/NEWS.d/3.10.0b1.rst
+++ b/Misc/NEWS.d/3.10.0b1.rst
@@ -1375,8 +1375,8 @@ Add "Annotations Best Practices" document as a new HOWTO.
.. nonce: K5aSl1
.. section: Documentation
-Document the new :const:`Py_TPFLAGS_MAPPING` and
-:const:`Py_TPFLAGS_SEQUENCE` type flags.
+Document the new :c:macro:`Py_TPFLAGS_MAPPING` and
+:c:macro:`Py_TPFLAGS_SEQUENCE` type flags.
..
@@ -1711,7 +1711,7 @@ IDLE's shell now shows prompts in a separate side-bar.
.. nonce: wvWt23
.. section: C API
-Add a new :c:data:`Py_TPFLAGS_DISALLOW_INSTANTIATION` type flag to disallow
+Add a new :c:macro:`Py_TPFLAGS_DISALLOW_INSTANTIATION` type flag to disallow
creating type instances. Patch by Victor Stinner.
..
@@ -1759,7 +1759,7 @@ module.
.. nonce: Co3YhZ
.. section: C API
-Introduce :const:`Py_TPFLAGS_IMMUTABLETYPE` flag for immutable type objects,
+Introduce :c:macro:`Py_TPFLAGS_IMMUTABLETYPE` flag for immutable type objects,
and modify :c:func:`PyType_Ready` to set it for static types. Patch by
Erlend E. Aasland.
diff --git a/Misc/NEWS.d/3.11.0a1.rst b/Misc/NEWS.d/3.11.0a1.rst
index 447d5c0e7d903..fb60ac5560102 100644
--- a/Misc/NEWS.d/3.11.0a1.rst
+++ b/Misc/NEWS.d/3.11.0a1.rst
@@ -888,7 +888,7 @@ zlib.decompress on input data that expands that large.
.. nonce: YHuV_s
.. section: Core and Builtins
-Heap types with the :const:`Py_TPFLAGS_IMMUTABLETYPE` flag can now inherit
+Heap types with the :c:macro:`Py_TPFLAGS_IMMUTABLETYPE` flag can now inherit
the :pep:`590` vectorcall protocol. Previously, this was only possible for
:ref:`static types <static-types>`. Patch by Erlend E. Aasland.
@@ -2575,7 +2575,7 @@ E. Aasland.
.. nonce: bamAGF
.. section: Library
-Set the proper :const:`Py_TPFLAGS_MAPPING` and :const:`Py_TPFLAGS_SEQUENCE`
+Set the proper :c:macro:`Py_TPFLAGS_MAPPING` and :c:macro:`Py_TPFLAGS_SEQUENCE`
flags for subclasses created before a parent has been registered as a
:class:`collections.abc.Mapping` or :class:`collections.abc.Sequence`.
@@ -2693,7 +2693,7 @@ libgcc_s.so file (ex: EMFILE error). Patch by Victor Stinner.
.. section: Library
The _thread.RLock type now fully implement the GC protocol: add a traverse
-function and the :const:`Py_TPFLAGS_HAVE_GC` flag. Patch by Victor Stinner.
+function and the :c:macro:`Py_TPFLAGS_HAVE_GC` flag. Patch by Victor Stinner.
..
@@ -5014,7 +5014,7 @@ must now be used to set an object type and size. Patch by Victor Stinner.
.. section: C API
The :c:func:`PyType_Ready` function now raises an error if a type is defined
-with the :const:`Py_TPFLAGS_HAVE_GC` flag set but has no traverse function
+with the :c:macro:`Py_TPFLAGS_HAVE_GC` flag set but has no traverse function
(:c:member:`PyTypeObject.tp_traverse`). Patch by Victor Stinner.
..
diff --git a/Misc/NEWS.d/3.11.0a7.rst b/Misc/NEWS.d/3.11.0a7.rst
index 8e7ccd4d6771e..2172c02e2fc84 100644
--- a/Misc/NEWS.d/3.11.0a7.rst
+++ b/Misc/NEWS.d/3.11.0a7.rst
@@ -275,7 +275,7 @@ initializing to ``list_extend``. Patch by Jeremiah Pascual.
.. nonce: cnaIK3
.. section: Core and Builtins
-Speed up throwing exception in generator with :const:`METH_FASTCALL` calling
+Speed up throwing exception in generator with :c:macro:`METH_FASTCALL` calling
convention. Patch by Kumar Aditya.
..
diff --git a/Misc/NEWS.d/3.12.0a1.rst b/Misc/NEWS.d/3.12.0a1.rst
index ff5064f89d8dd..9afeba2526351 100644
--- a/Misc/NEWS.d/3.12.0a1.rst
+++ b/Misc/NEWS.d/3.12.0a1.rst
@@ -5856,8 +5856,8 @@ Configuration for the :ref:`integer string conversion length limitation
Extensions classes that set ``tp_dictoffset`` and ``tp_weaklistoffset`` lose
the support for multiple inheritance, but are now safe. Extension classes
-should use :const:`Py_TPFLAGS_MANAGED_DICT` and
-:const:`Py_TPFLAGS_MANAGED_WEAKREF` instead.
+should use :c:macro:`Py_TPFLAGS_MANAGED_DICT` and
+:c:macro:`Py_TPFLAGS_MANAGED_WEAKREF` instead.
..
@@ -5898,7 +5898,7 @@ Support C extensions using managed dictionaries by setting the
.. nonce: QoDHEu
.. section: C API
-API for implementing vectorcall (:c:data:`Py_TPFLAGS_HAVE_VECTORCALL`,
+API for implementing vectorcall (:c:macro:`Py_TPFLAGS_HAVE_VECTORCALL`,
:c:func:`PyVectorcall_NARGS` and :c:func:`PyVectorcall_Call`) was added to
the limited API and stable ABI.
@@ -5920,12 +5920,12 @@ Philip Georgi.
.. nonce: -DdGEy
.. section: C API
-The :const:`Py_TPFLAGS_HAVE_VECTORCALL` flag is now removed from a class
+The :c:macro:`Py_TPFLAGS_HAVE_VECTORCALL` flag is now removed from a class
when the class's :py:meth:`~object.__call__` method is reassigned. This
makes vectorcall safe to use with mutable types (i.e. heap types without the
:const:`immutable <Py_TPFLAGS_IMMUTABLETYPE>` flag). Mutable types that do
not override :c:member:`~PyTypeObject.tp_call` now inherit the
-:const:`Py_TPFLAGS_HAVE_VECTORCALL` flag.
+:c:macro:`Py_TPFLAGS_HAVE_VECTORCALL` flag.
..
diff --git a/Misc/NEWS.d/3.12.0a2.rst b/Misc/NEWS.d/3.12.0a2.rst
index d871384903e7c..5a3ccab02016f 100644
--- a/Misc/NEWS.d/3.12.0a2.rst
+++ b/Misc/NEWS.d/3.12.0a2.rst
@@ -279,7 +279,7 @@ Fix source locations of :keyword:`match` sub-patterns.
Added the methods :c:func:`PyObject_Vectorcall` and
:c:func:`PyObject_VectorcallMethod` to the :ref:`Limited API <stable>` along
-with the auxiliary macro constant :const:`PY_VECTORCALL_ARGUMENTS_OFFSET`.
+with the auxiliary macro constant :c:macro:`PY_VECTORCALL_ARGUMENTS_OFFSET`.
The availability of these functions enables more efficient :PEP:`590` vector
calls from binary extension modules that avoid argument boxing/unboxing
diff --git a/Misc/NEWS.d/3.6.0a1.rst b/Misc/NEWS.d/3.6.0a1.rst
index 53f09b3dfe336..98f1215fb9187 100644
--- a/Misc/NEWS.d/3.6.0a1.rst
+++ b/Misc/NEWS.d/3.6.0a1.rst
@@ -125,7 +125,7 @@ Setuptools 19.0.
.. section: Core and Builtins
Memory functions of the :c:func:`PyMem_Malloc` domain
-(:c:data:`PYMEM_DOMAIN_MEM`) now use the :ref:`pymalloc allocator
+(:c:macro:`PYMEM_DOMAIN_MEM`) now use the :ref:`pymalloc allocator
<pymalloc>` rather than system :c:func:`malloc`. Applications calling
:c:func:`PyMem_Malloc` without holding the GIL can now crash: use
``PYTHONMALLOC=debug`` environment variable to validate the usage of memory
diff --git a/Misc/NEWS.d/3.9.0a1.rst b/Misc/NEWS.d/3.9.0a1.rst
index 0888a5c43087b..7af7f2e412053 100644
--- a/Misc/NEWS.d/3.9.0a1.rst
+++ b/Misc/NEWS.d/3.9.0a1.rst
@@ -5706,7 +5706,7 @@ and :c:func:`_PyObject_CallMethodOneArg`.
.. nonce: qZC0N_
.. section: C API
-The :const:`METH_FASTCALL` calling convention has been documented.
+The :c:macro:`METH_FASTCALL` calling convention has been documented.
..
More information about the Python-checkins
mailing list