languages/cpython
languages/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython synced 2024-09-05 00:05:39 +00:00
Code Issues Packages Projects Releases Wiki Activity

gh-106919: Use role :c:macro: for referencing the C "constants" (GH-106920)

Browse source
This commit is contained in:
Serhiy Storchaka 2023-07-21 10:52:07 +03:00 committed by GitHub
parent 81861fd90b
commit fcc816dbff
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
47 changed files with 311 additions and 293 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
Doc/c-api/arg.rst
View file

@ -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).
@ -463,7 +463,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

18
Doc/c-api/call.rst
View file

@ -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.
@ -161,7 +161,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
@ -379,11 +379,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.

4
Doc/c-api/complex.rst
View file

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

12
Doc/c-api/exceptions.rst
View file

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

2
Doc/c-api/file.rst
View file

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

4
Doc/c-api/float.rst
View file

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

12
Doc/c-api/gcsupport.rst
View file

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

60
Doc/c-api/init.rst
View file

@ -1161,7 +1161,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
@ -1407,32 +1407,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*:
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* |
+==============================+========================================+
| :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`. |
+------------------------------+----------------------------------------+
+-------------------------------+----------------------------------------+
| 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
@ -1499,8 +1499,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.
@ -1525,8 +1525,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.

8
Doc/c-api/long.rst
View file

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

18
Doc/c-api/memory.rst
View file

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

6
Doc/c-api/module.rst
View file

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

16
Doc/c-api/object.rst
View file

@ -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`.
@ -199,8 +199,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.
@ -209,8 +209,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
@ -218,7 +218,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)
@ -468,10 +468,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

2
Doc/c-api/slice.rst
View file

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

2
Doc/c-api/stable.rst
View file

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

72
Doc/c-api/structures.rst
View file

@ -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
Extension of :const:`METH_FASTCALL | METH_KEYWORDS` supporting the *defining
class*, that is, the class that contains the method in question.
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:
: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.

4
Doc/c-api/sys.rst
View file

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

14
Doc/c-api/type.rst
View file

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

160
Doc/c-api/typeobj.rst
View file

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

10
Doc/c-api/unicode.rst
View file

@ -1292,7 +1292,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
@ -1411,11 +1411,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)

8
Doc/c-api/veryhigh.rst
View file

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

4
Doc/extending/extending.rst
View file

@ -337,7 +337,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
@ -540,7 +540,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`.

8
Doc/extending/newtypes_tutorial.rst
View file

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

10
Doc/howto/isolating-extensions.rst
View file

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

4
Doc/library/dis.rst
View file

@ -876,7 +876,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``.
@ -887,7 +887,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

14
Doc/library/os.rst
View file

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

4
Doc/reference/compound_stmts.rst
View file

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

8
Doc/using/cmdline.rst
View file

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

6
Doc/whatsnew/2.2.rst
View file

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

8
Doc/whatsnew/2.3.rst
View file

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

2
Doc/whatsnew/2.4.rst
View file

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

6
Doc/whatsnew/2.6.rst
View file

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

2
Doc/whatsnew/2.7.rst
View file

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

10
Doc/whatsnew/3.10.rst
View file

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

4
Doc/whatsnew/3.11.rst
View file

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

24
Doc/whatsnew/3.12.rst
View file

@ -1111,7 +1111,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`.
@ -1622,7 +1622,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
@ -1639,20 +1639,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.
@ -1663,7 +1663,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
@ -1785,13 +1785,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.
@ -1845,7 +1845,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
@ -1896,7 +1896,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

4
Doc/whatsnew/3.13.rst
View file

@ -961,7 +961,7 @@ Removed
Pending Removal in Python 3.14
------------------------------
* Creating immutable types (:data:`Py_TPFLAGS_IMMUTABLETYPE`) with mutable
* Creating immutable types (:c:macro:`Py_TPFLAGS_IMMUTABLETYPE`) with mutable
bases using the C API.
* Global configuration variables:
@ -1017,7 +1017,7 @@ Pending Removal in Future Versions
The following APIs were deprecated in earlier Python versions and will be
removed, although there is currently no date scheduled for their removal.
* :const:`Py_TPFLAGS_HAVE_FINALIZE`: no needed since Python 3.8.
* :c:macro:`Py_TPFLAGS_HAVE_FINALIZE`: no needed since Python 3.8.
* :c:func:`PyErr_Fetch`: use :c:func:`PyErr_GetRaisedException`.
* :c:func:`PyErr_NormalizeException`: use :c:func:`PyErr_GetRaisedException`.
* :c:func:`PyErr_Restore`: use :c:func:`PyErr_SetRaisedException`.

10
Doc/whatsnew/3.6.rst
View file

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

2
Doc/whatsnew/3.8.rst
View file

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

2
Doc/whatsnew/3.9.rst
View file

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

2
Misc/NEWS.d/3.10.0a3.rst
View file

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

8
Misc/NEWS.d/3.10.0b1.rst
View file

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

8
Misc/NEWS.d/3.11.0a1.rst
View file

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

2
Misc/NEWS.d/3.11.0a7.rst
View file

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

10
Misc/NEWS.d/3.12.0a1.rst
View file

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

2
Misc/NEWS.d/3.12.0a2.rst
View file

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

2
Misc/NEWS.d/3.6.0a1.rst
View file

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

2
Misc/NEWS.d/3.9.0a1.rst
View file

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