mirror of
https://github.com/python/cpython.git
synced 2025-07-31 23:23:11 +00:00
gh-106919: Use role :c:macro: for referencing the C "constants" (GH-106920)
This commit is contained in:
Serhiy Storchaka
GitHub
parent
81861fd90b
commit
fcc816dbff
47 changed files with 311 additions and 293 deletions
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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>`)
|
||||
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue