*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).
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
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:
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;
``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.
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
*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.
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)
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
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);``
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.
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::
.. 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__`.
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.
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.
.. 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.
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.
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.
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.
: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:: TYPE* PyObject_GC_Resize(TYPE, PyVarObject *op, Py_ssize_t newsize)
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
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
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.
: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.
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.
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.
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.
- 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
``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.
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
: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:
.. 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
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)
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
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`.
.. 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.
.. 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
.. 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)
*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.
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
.. 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,
.. 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,
.. 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,
.. 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,
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.
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``
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`.
``METH_FASTCALL`` is now part of the 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>`:
.. 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
.. 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``.
: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.
method.
-.. data:: METH_CLASS
+.. c:macro:: METH_CLASS
.. index:: pair: built-in function; classmethod
function.
-.. data:: METH_STATIC
+.. c:macro:: METH_STATIC
.. index:: pair: built-in function; staticmethod
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
.. 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.
.. 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)
.. 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.
.. c:function:: PyObject* PyType_FromModuleAndSpec(PyObject *module, PyType_Spec *spec, PyObject *bases)
Creates and returns a :ref:`heap type <heap-types>` from the *spec*
- (:const:`Py_TPFLAGS_HEAPTYPE`).
+ (:c:macro:`Py_TPFLAGS_HEAPTYPE`).
The *bases* argument can be used to specify base classes; it can either
be only one class or a tuple of classes.
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
: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.
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:
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
**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, then the subclass won't use
:ref:`vectorcall <vectorcall>`, except when
:c:func:`PyVectorcall_Call` is explicitly called.
This is in particular the case for types without the
- :const:`Py_TPFLAGS_IMMUTABLETYPE` flag set (including subclasses defined in
+ :c:macro:`Py_TPFLAGS_IMMUTABLETYPE` flag set (including subclasses defined in
Python).
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.
**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
???
- .. 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
???
- .. 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`.
???
- .. 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.
???
- .. 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
**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.
**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.
.. 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
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.
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>`.
**Inheritance:**
This bit is inherited for types with the
- :const:`Py_TPFLAGS_IMMUTABLETYPE` flag set, if
+ :c:macro:`Py_TPFLAGS_IMMUTABLETYPE` flag set, if
:c:member:`~PyTypeObject.tp_call` is also inherited.
.. versionadded:: 3.9
- .. 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.
.. 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__``
.. 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
.. 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
.. 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
.. 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);
**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.
.. 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 *);
**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.
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:
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:**
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.
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
**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
.. 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`)
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
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;
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
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)
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
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.
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
}
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`.
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,
{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::
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,
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,
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
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
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::
.. opcode:: MATCH_MAPPING
If TOS is an instance of :class:`collections.abc.Mapping` (or, more technically: if
- it has the :const:`Py_TPFLAGS_MAPPING` flag set in its
+ 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``.
If TOS 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
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
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
* 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:
* 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`
* ``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>`:
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
* 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.
* 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
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
: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.)
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.
* 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
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`.)
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`.)
#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`)
* 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.
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.
(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.
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`.)
* :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`.)
.. 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.
.. 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.
..
.. 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.
..
.. 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.
.. 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.
.. 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`.
.. 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.
..
.. 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.
..
.. 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.
..
.. 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
.. nonce: qZC0N_
.. section: C API
-The :const:`METH_FASTCALL` calling convention has been documented.
+The :c:macro:`METH_FASTCALL` calling convention has been documented.
..
projects / thirdparty / Python / cpython.git / commitdiff
