greg/cpython
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

gh-138189: Document type slots, and other constants, as part of Limited API (GH-138190)

Browse Source 
Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
This commit is contained in:
Petr Viktorin
2025-11-04 22:58:53 +01:00
committed by GitHub
parent bfe54810c4
commit d81e1ef0f3
6 changed files with 430 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

200
Doc/c-api/typeobj.rst
View File

@@ -676,6 +676,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
.. c:member:: destructor PyTypeObject.tp_dealloc
.. corresponding-type-slot:: Py_tp_dealloc
A pointer to the instance destructor function. The function signature is::
void tp_dealloc(PyObject *self);
@@ -860,6 +862,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
.. c:member:: getattrfunc PyTypeObject.tp_getattr
.. corresponding-type-slot:: Py_tp_getattr
An optional pointer to the get-attribute-string function.
This field is deprecated. When it is defined, it should point to a function
@@ -877,6 +881,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
.. c:member:: setattrfunc PyTypeObject.tp_setattr
.. corresponding-type-slot:: Py_tp_setattr
An optional pointer to the function for setting and deleting attributes.
This field is deprecated. When it is defined, it should point to a function
@@ -909,6 +915,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
.. c:member:: reprfunc PyTypeObject.tp_repr
.. corresponding-type-slot:: Py_tp_repr
.. index:: pair: built-in function; repr
An optional pointer to a function that implements the built-in function
@@ -974,6 +982,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
.. c:member:: hashfunc PyTypeObject.tp_hash
.. corresponding-type-slot:: Py_tp_hash
.. index:: pair: built-in function; hash
An optional pointer to a function that implements the built-in function
@@ -1015,6 +1025,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
.. c:member:: ternaryfunc PyTypeObject.tp_call
.. corresponding-type-slot:: Py_tp_call
An optional pointer to a function that implements calling the object. This
should be ``NULL`` if the object is not callable. The signature is the same as
for :c:func:`PyObject_Call`::
@@ -1028,6 +1040,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
.. c:member:: reprfunc PyTypeObject.tp_str
.. corresponding-type-slot:: Py_tp_str
An optional pointer to a function that implements the built-in operation
:func:`str`. (Note that :class:`str` is a type now, and :func:`str` calls the
constructor for that type. This constructor calls :c:func:`PyObject_Str` to do
@@ -1053,6 +1067,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
.. c:member:: getattrofunc PyTypeObject.tp_getattro
.. corresponding-type-slot:: Py_tp_getattro
An optional pointer to the get-attribute function.
The signature is the same as for :c:func:`PyObject_GetAttr`::
@@ -1077,6 +1093,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
.. c:member:: setattrofunc PyTypeObject.tp_setattro
.. corresponding-type-slot:: Py_tp_setattro
An optional pointer to the function for setting and deleting attributes.
The signature is the same as for :c:func:`PyObject_SetAttr`::
@@ -1475,6 +1493,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
.. c:member:: const char* PyTypeObject.tp_doc
.. corresponding-type-slot:: Py_tp_doc
An optional pointer to a NUL-terminated C string giving the docstring for this
type object. This is exposed as the :attr:`~type.__doc__` attribute on the
type and instances of the type.
@@ -1486,6 +1506,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
.. c:member:: traverseproc PyTypeObject.tp_traverse
.. corresponding-type-slot:: Py_tp_traverse
An optional pointer to a traversal function for the garbage collector. This is
only used if the :c:macro:`Py_TPFLAGS_HAVE_GC` flag bit is set. The signature is::
@@ -1582,6 +1604,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
.. c:member:: inquiry PyTypeObject.tp_clear
.. corresponding-type-slot:: Py_tp_clear
An optional pointer to a clear function. The signature is::
int tp_clear(PyObject *);
@@ -1730,6 +1754,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
.. c:member:: richcmpfunc PyTypeObject.tp_richcompare
.. corresponding-type-slot:: Py_tp_richcompare
An optional pointer to the rich comparison function, whose signature is::
PyObject *tp_richcompare(PyObject *self, PyObject *other, int op);
@@ -1832,6 +1858,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
.. c:member:: getiterfunc PyTypeObject.tp_iter
.. corresponding-type-slot:: Py_tp_iter
An optional pointer to a function that returns an :term:`iterator` for the
object. Its presence normally signals that the instances of this type are
:term:`iterable` (although sequences may be iterable without this function).
@@ -1847,6 +1875,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
.. c:member:: iternextfunc PyTypeObject.tp_iternext
.. corresponding-type-slot:: Py_tp_iternext
An optional pointer to a function that returns the next item in an
:term:`iterator`. The signature is::
@@ -1870,6 +1900,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
.. c:member:: struct PyMethodDef* PyTypeObject.tp_methods
.. corresponding-type-slot:: Py_tp_methods
An optional pointer to a static ``NULL``-terminated array of :c:type:`PyMethodDef`
structures, declaring regular methods of this type.
@@ -1884,6 +1916,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
.. c:member:: struct PyMemberDef* PyTypeObject.tp_members
.. corresponding-type-slot:: Py_tp_members
An optional pointer to a static ``NULL``-terminated array of :c:type:`PyMemberDef`
structures, declaring regular data members (fields or slots) of instances of
this type.
@@ -1899,6 +1933,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
.. c:member:: struct PyGetSetDef* PyTypeObject.tp_getset
.. corresponding-type-slot:: Py_tp_getset
An optional pointer to a static ``NULL``-terminated array of :c:type:`PyGetSetDef`
structures, declaring computed attributes of instances of this type.
@@ -1913,6 +1949,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
.. c:member:: PyTypeObject* PyTypeObject.tp_base
.. corresponding-type-slot:: Py_tp_base
An optional pointer to a base type from which type properties are inherited. At
this level, only single inheritance is supported; multiple inheritance require
dynamically creating a type object by calling the metatype.
@@ -1985,6 +2023,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
.. c:member:: descrgetfunc PyTypeObject.tp_descr_get
.. corresponding-type-slot:: Py_tp_descr_get
An optional pointer to a "descriptor get" function.
The function signature is::
@@ -2000,6 +2040,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
.. c:member:: descrsetfunc PyTypeObject.tp_descr_set
.. corresponding-type-slot:: Py_tp_descr_set
An optional pointer to a function for setting and deleting
a descriptor's value.
@@ -2060,6 +2102,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
.. c:member:: initproc PyTypeObject.tp_init
.. corresponding-type-slot:: Py_tp_init
An optional pointer to an instance initialization function.
This function corresponds to the :meth:`~object.__init__` method of classes. Like
@@ -2095,6 +2139,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
.. c:member:: allocfunc PyTypeObject.tp_alloc
.. corresponding-type-slot:: Py_tp_alloc
An optional pointer to an instance allocation function.
The function signature is::
@@ -2118,6 +2164,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
.. c:member:: newfunc PyTypeObject.tp_new
.. corresponding-type-slot:: Py_tp_new
An optional pointer to an instance creation function.
The function signature is::
@@ -2157,6 +2205,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
.. c:member:: freefunc PyTypeObject.tp_free
.. corresponding-type-slot:: Py_tp_free
An optional pointer to an instance deallocation function. Its signature is::
void tp_free(void *self);
@@ -2186,6 +2236,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
.. c:member:: inquiry PyTypeObject.tp_is_gc
.. corresponding-type-slot:: Py_tp_is_gc
An optional pointer to a function called by the garbage collector.
The garbage collector needs to know whether a particular object is collectible
@@ -2214,6 +2266,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
.. c:member:: PyObject* PyTypeObject.tp_bases
.. corresponding-type-slot:: Py_tp_bases
Tuple of base types.
This field should be set to ``NULL`` and treated as read-only.
@@ -2294,6 +2348,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
.. c:member:: destructor PyTypeObject.tp_del
.. corresponding-type-slot:: Py_tp_del
This field is deprecated. Use :c:member:`~PyTypeObject.tp_finalize` instead.
@@ -2308,6 +2364,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
.. c:member:: destructor PyTypeObject.tp_finalize
.. corresponding-type-slot:: Py_tp_finalize
An optional pointer to an instance finalization function. This is the C
implementation of the :meth:`~object.__del__` special method. Its signature
is::
@@ -2466,6 +2524,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
.. c:member:: vectorcallfunc PyTypeObject.tp_vectorcall
.. corresponding-type-slot:: Py_tp_vectorcall
A :ref:`vectorcall function <vectorcall>` to use for calls of this type
object (rather than instances).
In other words, ``tp_vectorcall`` can be used to optimize ``type.__call__``,
@@ -2631,42 +2691,148 @@ Number Object Structures
Python 3.0.1.
.. c:member:: binaryfunc PyNumberMethods.nb_add
.. corresponding-type-slot:: Py_nb_add
.. c:member:: binaryfunc PyNumberMethods.nb_subtract
.. corresponding-type-slot:: Py_nb_subtract
.. c:member:: binaryfunc PyNumberMethods.nb_multiply
.. corresponding-type-slot:: Py_nb_multiply
.. c:member:: binaryfunc PyNumberMethods.nb_remainder
.. corresponding-type-slot:: Py_nb_remainder
.. c:member:: binaryfunc PyNumberMethods.nb_divmod
.. corresponding-type-slot:: Py_nb_divmod
.. c:member:: ternaryfunc PyNumberMethods.nb_power
.. corresponding-type-slot:: Py_nb_power
.. c:member:: unaryfunc PyNumberMethods.nb_negative
.. corresponding-type-slot:: Py_nb_negative
.. c:member:: unaryfunc PyNumberMethods.nb_positive
.. corresponding-type-slot:: Py_nb_positive
.. c:member:: unaryfunc PyNumberMethods.nb_absolute
.. corresponding-type-slot:: Py_nb_absolute
.. c:member:: inquiry PyNumberMethods.nb_bool
.. corresponding-type-slot:: Py_nb_bool
.. c:member:: unaryfunc PyNumberMethods.nb_invert
.. corresponding-type-slot:: Py_nb_invert
.. c:member:: binaryfunc PyNumberMethods.nb_lshift
.. corresponding-type-slot:: Py_nb_lshift
.. c:member:: binaryfunc PyNumberMethods.nb_rshift
.. corresponding-type-slot:: Py_nb_rshift
.. c:member:: binaryfunc PyNumberMethods.nb_and
.. corresponding-type-slot:: Py_nb_and
.. c:member:: binaryfunc PyNumberMethods.nb_xor
.. corresponding-type-slot:: Py_nb_xor
.. c:member:: binaryfunc PyNumberMethods.nb_or
.. corresponding-type-slot:: Py_nb_or
.. c:member:: unaryfunc PyNumberMethods.nb_int
.. corresponding-type-slot:: Py_nb_int
.. c:member:: void *PyNumberMethods.nb_reserved
.. c:member:: unaryfunc PyNumberMethods.nb_float
.. corresponding-type-slot:: Py_nb_float
.. c:member:: binaryfunc PyNumberMethods.nb_inplace_add
.. corresponding-type-slot:: Py_nb_inplace_add
.. c:member:: binaryfunc PyNumberMethods.nb_inplace_subtract
.. corresponding-type-slot:: Py_nb_inplace_subtract
.. c:member:: binaryfunc PyNumberMethods.nb_inplace_multiply
.. corresponding-type-slot:: Py_nb_inplace_multiply
.. c:member:: binaryfunc PyNumberMethods.nb_inplace_remainder
.. corresponding-type-slot:: Py_nb_inplace_remainder
.. c:member:: ternaryfunc PyNumberMethods.nb_inplace_power
.. corresponding-type-slot:: Py_nb_inplace_power
.. c:member:: binaryfunc PyNumberMethods.nb_inplace_lshift
.. corresponding-type-slot:: Py_nb_inplace_lshift
.. c:member:: binaryfunc PyNumberMethods.nb_inplace_rshift
.. corresponding-type-slot:: Py_nb_inplace_rshift
.. c:member:: binaryfunc PyNumberMethods.nb_inplace_and
.. corresponding-type-slot:: Py_nb_inplace_and
.. c:member:: binaryfunc PyNumberMethods.nb_inplace_xor
.. corresponding-type-slot:: Py_nb_inplace_xor
.. c:member:: binaryfunc PyNumberMethods.nb_inplace_or
.. corresponding-type-slot:: Py_nb_inplace_or
.. c:member:: binaryfunc PyNumberMethods.nb_floor_divide
.. corresponding-type-slot:: Py_nb_floor_divide
.. c:member:: binaryfunc PyNumberMethods.nb_true_divide
.. corresponding-type-slot:: Py_nb_true_divide
.. c:member:: binaryfunc PyNumberMethods.nb_inplace_floor_divide
.. corresponding-type-slot:: Py_nb_inplace_floor_divide
.. c:member:: binaryfunc PyNumberMethods.nb_inplace_true_divide
.. corresponding-type-slot:: Py_nb_inplace_true_divide
.. c:member:: unaryfunc PyNumberMethods.nb_index
.. corresponding-type-slot:: Py_nb_index
.. c:member:: binaryfunc PyNumberMethods.nb_matrix_multiply
.. corresponding-type-slot:: Py_nb_matrix_multiply
.. c:member:: binaryfunc PyNumberMethods.nb_inplace_matrix_multiply
.. corresponding-type-slot:: Py_nb_inplace_matrix_multiply
.. _mapping-structs:
@@ -2683,12 +2849,16 @@ Mapping Object Structures
.. c:member:: lenfunc PyMappingMethods.mp_length
.. corresponding-type-slot:: Py_mp_length
This function is used by :c:func:`PyMapping_Size` and
:c:func:`PyObject_Size`, and has the same signature. This slot may be set to
``NULL`` if the object has no defined length.
.. c:member:: binaryfunc PyMappingMethods.mp_subscript
.. corresponding-type-slot:: Py_mp_subscript
This function is used by :c:func:`PyObject_GetItem` and
:c:func:`PySequence_GetSlice`, and has the same signature as
:c:func:`!PyObject_GetItem`. This slot must be filled for the
@@ -2697,6 +2867,8 @@ Mapping Object Structures
.. c:member:: objobjargproc PyMappingMethods.mp_ass_subscript
.. corresponding-type-slot:: Py_mp_ass_subscript
This function is used by :c:func:`PyObject_SetItem`,
:c:func:`PyObject_DelItem`, :c:func:`PySequence_SetSlice` and
:c:func:`PySequence_DelSlice`. It has the same signature as
@@ -2720,6 +2892,8 @@ Sequence Object Structures
.. c:member:: lenfunc PySequenceMethods.sq_length
.. corresponding-type-slot:: Py_sq_length
This function is used by :c:func:`PySequence_Size` and
:c:func:`PyObject_Size`, and has the same signature. It is also used for
handling negative indices via the :c:member:`~PySequenceMethods.sq_item`
@@ -2727,18 +2901,24 @@ Sequence Object Structures
.. c:member:: binaryfunc PySequenceMethods.sq_concat
.. corresponding-type-slot:: Py_sq_concat
This function is used by :c:func:`PySequence_Concat` and has the same
signature. It is also used by the ``+`` operator, after trying the numeric
addition via the :c:member:`~PyNumberMethods.nb_add` slot.
.. c:member:: ssizeargfunc PySequenceMethods.sq_repeat
.. corresponding-type-slot:: Py_sq_repeat
This function is used by :c:func:`PySequence_Repeat` and has the same
signature. It is also used by the ``*`` operator, after trying numeric
multiplication via the :c:member:`~PyNumberMethods.nb_multiply` slot.
.. c:member:: ssizeargfunc PySequenceMethods.sq_item
.. corresponding-type-slot:: Py_sq_item
This function is used by :c:func:`PySequence_GetItem` and has the same
signature. It is also used by :c:func:`PyObject_GetItem`, after trying
the subscription via the :c:member:`~PyMappingMethods.mp_subscript` slot.
@@ -2752,6 +2932,8 @@ Sequence Object Structures
.. c:member:: ssizeobjargproc PySequenceMethods.sq_ass_item
.. corresponding-type-slot:: Py_sq_ass_item
This function is used by :c:func:`PySequence_SetItem` and has the same
signature. It is also used by :c:func:`PyObject_SetItem` and
:c:func:`PyObject_DelItem`, after trying the item assignment and deletion
@@ -2761,6 +2943,8 @@ Sequence Object Structures
.. c:member:: objobjproc PySequenceMethods.sq_contains
.. corresponding-type-slot:: Py_sq_contains
This function may be used by :c:func:`PySequence_Contains` and has the same
signature. This slot may be left to ``NULL``, in this case
:c:func:`!PySequence_Contains` simply traverses the sequence until it
@@ -2768,6 +2952,8 @@ Sequence Object Structures
.. c:member:: binaryfunc PySequenceMethods.sq_inplace_concat
.. corresponding-type-slot:: Py_sq_inplace_concat
This function is used by :c:func:`PySequence_InPlaceConcat` and has the same
signature. It should modify its first operand, and return it. This slot
may be left to ``NULL``, in this case :c:func:`!PySequence_InPlaceConcat`
@@ -2777,6 +2963,8 @@ Sequence Object Structures
.. c:member:: ssizeargfunc PySequenceMethods.sq_inplace_repeat
.. corresponding-type-slot:: Py_sq_inplace_repeat
This function is used by :c:func:`PySequence_InPlaceRepeat` and has the same
signature. It should modify its first operand, and return it. This slot
may be left to ``NULL``, in this case :c:func:`!PySequence_InPlaceRepeat`
@@ -2802,6 +2990,8 @@ Buffer Object Structures
.. c:member:: getbufferproc PyBufferProcs.bf_getbuffer
.. corresponding-type-slot:: Py_bf_getbuffer
The signature of this function is::
int (PyObject *exporter, Py_buffer *view, int flags);
@@ -2851,6 +3041,8 @@ Buffer Object Structures
.. c:member:: releasebufferproc PyBufferProcs.bf_releasebuffer
.. corresponding-type-slot:: Py_bf_releasebuffer
The signature of this function is::
void (PyObject *exporter, Py_buffer *view);
@@ -2905,6 +3097,8 @@ Async Object Structures
.. c:member:: unaryfunc PyAsyncMethods.am_await
.. corresponding-type-slot:: Py_am_await
The signature of this function is::
PyObject *am_await(PyObject *self);
@@ -2916,6 +3110,8 @@ Async Object Structures
.. c:member:: unaryfunc PyAsyncMethods.am_aiter
.. corresponding-type-slot:: Py_am_aiter
The signature of this function is::
PyObject *am_aiter(PyObject *self);
@@ -2928,6 +3124,8 @@ Async Object Structures
.. c:member:: unaryfunc PyAsyncMethods.am_anext
.. corresponding-type-slot:: Py_am_anext
The signature of this function is::
PyObject *am_anext(PyObject *self);
@@ -2938,6 +3136,8 @@ Async Object Structures
.. c:member:: sendfunc PyAsyncMethods.am_send
.. corresponding-type-slot:: Py_am_send
The signature of this function is::
PySendResult am_send(PyObject *self, PyObject *arg, PyObject **result);

153
Doc/data/stable_abi.dat generated
View File

@@ -1,7 +1,21 @@
role,name,added,ifdef_note,struct_abi_kind
macro,METH_CLASS,3.2,,
macro,METH_COEXIST,3.2,,
macro,METH_FASTCALL,3.7,,
macro,METH_METHOD,3.7,,
macro,METH_NOARGS,3.2,,
macro,METH_O,3.2,,
macro,METH_STATIC,3.2,,
macro,METH_VARARGS,3.2,,
macro,PY_VECTORCALL_ARGUMENTS_OFFSET,3.12,,
type,PyABIInfo,3.15,,full-abi
func,PyABIInfo_Check,3.15,,
macro,PyABIInfo_DEFAULT_ABI_VERSION,3.15,,
macro,PyABIInfo_DEFAULT_FLAGS,3.15,,
macro,PyABIInfo_FREETHREADED,3.15,,
macro,PyABIInfo_FREETHREADING_AGNOSTIC,3.15,,
macro,PyABIInfo_GIL,3.15,,
macro,PyABIInfo_STABLE,3.15,,
macro,PyABIInfo_VAR,3.15,,
func,PyAIter_Check,3.10,,
func,PyArg_Parse,3.2,,
@@ -11,6 +25,26 @@ func,PyArg_UnpackTuple,3.2,,
func,PyArg_VaParse,3.2,,
func,PyArg_VaParseTupleAndKeywords,3.2,,
func,PyArg_ValidateKeywordArguments,3.2,,
macro,PyBUF_ANY_CONTIGUOUS,3.11,,
macro,PyBUF_CONTIG,3.11,,
macro,PyBUF_CONTIG_RO,3.11,,
macro,PyBUF_C_CONTIGUOUS,3.11,,
macro,PyBUF_FORMAT,3.11,,
macro,PyBUF_FULL,3.11,,
macro,PyBUF_FULL_RO,3.11,,
macro,PyBUF_F_CONTIGUOUS,3.11,,
macro,PyBUF_INDIRECT,3.11,,
macro,PyBUF_MAX_NDIM,3.11,,
macro,PyBUF_ND,3.11,,
macro,PyBUF_READ,3.11,,
macro,PyBUF_RECORDS,3.11,,
macro,PyBUF_RECORDS_RO,3.11,,
macro,PyBUF_SIMPLE,3.11,,
macro,PyBUF_STRIDED,3.11,,
macro,PyBUF_STRIDED_RO,3.11,,
macro,PyBUF_STRIDES,3.11,,
macro,PyBUF_WRITABLE,3.11,,
macro,PyBUF_WRITE,3.11,,
data,PyBaseObject_Type,3.2,,
func,PyBool_FromLong,3.2,,
data,PyBool_Type,3.2,,
@@ -836,6 +870,14 @@ func,PyWeakref_NewRef,3.2,,
data,PyWrapperDescr_Type,3.2,,
func,PyWrapper_New,3.2,,
data,PyZip_Type,3.2,,
macro,Py_ASNATIVEBYTES_ALLOW_INDEX,3.14,,
macro,Py_ASNATIVEBYTES_BIG_ENDIAN,3.14,,
macro,Py_ASNATIVEBYTES_DEFAULTS,3.14,,
macro,Py_ASNATIVEBYTES_LITTLE_ENDIAN,3.14,,
macro,Py_ASNATIVEBYTES_NATIVE_ENDIAN,3.14,,
macro,Py_ASNATIVEBYTES_REJECT_NEGATIVE,3.14,,
macro,Py_ASNATIVEBYTES_UNSIGNED_BUFFER,3.14,,
macro,Py_AUDIT_READ,3.12,,
func,Py_AddPendingCall,3.2,,
func,Py_AtExit,3.2,,
macro,Py_BEGIN_ALLOW_THREADS,3.2,,
@@ -882,22 +924,133 @@ func,Py_NewInterpreter,3.2,,
func,Py_NewRef,3.10,,
func,Py_PACK_FULL_VERSION,3.14,,
func,Py_PACK_VERSION,3.14,,
macro,Py_READONLY,3.12,,
func,Py_REFCNT,3.14,,
macro,Py_RELATIVE_OFFSET,3.12,,
func,Py_ReprEnter,3.2,,
func,Py_ReprLeave,3.2,,
func,Py_SetProgramName,3.2,,
func,Py_SetPythonHome,3.2,,
func,Py_SetRecursionLimit,3.2,,
macro,Py_TPFLAGS_BASETYPE,3.2,,
macro,Py_TPFLAGS_DEFAULT,3.2,,
macro,Py_TPFLAGS_HAVE_GC,3.2,,
macro,Py_TPFLAGS_HAVE_VECTORCALL,3.12,,
macro,Py_TPFLAGS_ITEMS_AT_END,3.12,,
macro,Py_TPFLAGS_METHOD_DESCRIPTOR,3.8,,
macro,Py_TP_USE_SPEC,3.14,,
func,Py_TYPE,3.14,,
macro,Py_T_BOOL,3.12,,
macro,Py_T_BYTE,3.12,,
macro,Py_T_CHAR,3.12,,
macro,Py_T_DOUBLE,3.12,,
macro,Py_T_FLOAT,3.12,,
macro,Py_T_INT,3.12,,
macro,Py_T_LONG,3.12,,
macro,Py_T_LONGLONG,3.12,,
macro,Py_T_OBJECT_EX,3.12,,
macro,Py_T_PYSSIZET,3.12,,
macro,Py_T_SHORT,3.12,,
macro,Py_T_STRING,3.12,,
macro,Py_T_STRING_INPLACE,3.12,,
macro,Py_T_UBYTE,3.12,,
macro,Py_T_UINT,3.12,,
macro,Py_T_ULONG,3.12,,
macro,Py_T_ULONGLONG,3.12,,
macro,Py_T_USHORT,3.12,,
type,Py_UCS4,3.2,,
macro,Py_UNBLOCK_THREADS,3.2,,
data,Py_UTF8Mode,3.8,,
func,Py_VaBuildValue,3.2,,
data,Py_Version,3.11,,
func,Py_XNewRef,3.10,,
macro,Py_am_aiter,3.5,,
macro,Py_am_anext,3.5,,
macro,Py_am_await,3.5,,
macro,Py_am_send,3.10,,
macro,Py_bf_getbuffer,3.11,,
macro,Py_bf_releasebuffer,3.11,,
type,Py_buffer,3.11,,full-abi
type,Py_intptr_t,3.2,,
macro,Py_mod_abi,3.15,,
macro,Py_mp_ass_subscript,3.2,,
macro,Py_mp_length,3.2,,
macro,Py_mp_subscript,3.2,,
macro,Py_nb_absolute,3.2,,
macro,Py_nb_add,3.2,,
macro,Py_nb_and,3.2,,
macro,Py_nb_bool,3.2,,
macro,Py_nb_divmod,3.2,,
macro,Py_nb_float,3.2,,
macro,Py_nb_floor_divide,3.2,,
macro,Py_nb_index,3.2,,
macro,Py_nb_inplace_add,3.2,,
macro,Py_nb_inplace_and,3.2,,
macro,Py_nb_inplace_floor_divide,3.2,,
macro,Py_nb_inplace_lshift,3.2,,
macro,Py_nb_inplace_matrix_multiply,3.5,,
macro,Py_nb_inplace_multiply,3.2,,
macro,Py_nb_inplace_or,3.2,,
macro,Py_nb_inplace_power,3.2,,
macro,Py_nb_inplace_remainder,3.2,,
macro,Py_nb_inplace_rshift,3.2,,
macro,Py_nb_inplace_subtract,3.2,,
macro,Py_nb_inplace_true_divide,3.2,,
macro,Py_nb_inplace_xor,3.2,,
macro,Py_nb_int,3.2,,
macro,Py_nb_invert,3.2,,
macro,Py_nb_lshift,3.2,,
macro,Py_nb_matrix_multiply,3.5,,
macro,Py_nb_multiply,3.2,,
macro,Py_nb_negative,3.2,,
macro,Py_nb_or,3.2,,
macro,Py_nb_positive,3.2,,
macro,Py_nb_power,3.2,,
macro,Py_nb_remainder,3.2,,
macro,Py_nb_rshift,3.2,,
macro,Py_nb_subtract,3.2,,
macro,Py_nb_true_divide,3.2,,
macro,Py_nb_xor,3.2,,
macro,Py_sq_ass_item,3.2,,
macro,Py_sq_concat,3.2,,
macro,Py_sq_contains,3.2,,
macro,Py_sq_inplace_concat,3.2,,
macro,Py_sq_inplace_repeat,3.2,,
macro,Py_sq_item,3.2,,
macro,Py_sq_length,3.2,,
macro,Py_sq_repeat,3.2,,
type,Py_ssize_t,3.2,,
macro,Py_tp_alloc,3.2,,
macro,Py_tp_base,3.2,,
macro,Py_tp_bases,3.2,,
macro,Py_tp_call,3.2,,
macro,Py_tp_clear,3.2,,
macro,Py_tp_dealloc,3.2,,
macro,Py_tp_del,3.2,,
macro,Py_tp_descr_get,3.2,,
macro,Py_tp_descr_set,3.2,,
macro,Py_tp_doc,3.2,,
macro,Py_tp_finalize,3.5,,
macro,Py_tp_free,3.2,,
macro,Py_tp_getattr,3.2,,
macro,Py_tp_getattro,3.2,,
macro,Py_tp_getset,3.2,,
macro,Py_tp_hash,3.2,,
macro,Py_tp_init,3.2,,
macro,Py_tp_is_gc,3.2,,
macro,Py_tp_iter,3.2,,
macro,Py_tp_iternext,3.2,,
macro,Py_tp_members,3.2,,
macro,Py_tp_methods,3.2,,
macro,Py_tp_new,3.2,,
macro,Py_tp_repr,3.2,,
macro,Py_tp_richcompare,3.2,,
macro,Py_tp_setattr,3.2,,
macro,Py_tp_setattro,3.2,,
macro,Py_tp_str,3.2,,
macro,Py_tp_token,3.14,,
macro,Py_tp_traverse,3.2,,
macro,Py_tp_vectorcall,3.14,,
type,Py_uintptr_t,3.2,,
type,allocfunc,3.2,,
type,binaryfunc,3.2,,

1
Doc/tools/.nitignore
View File

@@ -8,7 +8,6 @@ Doc/c-api/init_config.rst
Doc/c-api/intro.rst
Doc/c-api/module.rst
Doc/c-api/stable.rst
Doc/c-api/type.rst
Doc/c-api/typeobj.rst
Doc/library/ast.rst
Doc/library/asyncio-extending.rst

76
Doc/tools/extensions/c_annotations.py
View File

@@ -154,7 +154,10 @@ def add_annotations(app: Sphinx, doctree: nodes.document) -> None:
node.insert(0, annotation)
def _stable_abi_annotation(record: StableABIEntry) -> nodes.emphasis:
def _stable_abi_annotation(
record: StableABIEntry,
is_corresponding_slot: bool = False,
) -> nodes.emphasis:
"""Create the Stable ABI annotation.
These have two forms:
@@ -168,9 +171,28 @@ def _stable_abi_annotation(record: StableABIEntry) -> nodes.emphasis:
... all of which can have "since version X.Y" appended.
"""
stable_added = record.added
message = sphinx_gettext("Part of the")
message = message.center(len(message) + 2)
emph_node = nodes.emphasis(message, message, classes=["stableabi"])
emph_node = nodes.emphasis('', '', classes=["stableabi"])
if is_corresponding_slot:
# See "Type slot annotations" in add_annotations
ref_node = addnodes.pending_xref(
"slot ID",
refdomain="c",
reftarget="PyType_Slot",
reftype="type",
refexplicit="True",
)
ref_node += nodes.Text(sphinx_gettext("slot ID"))
message = sphinx_gettext("The corresponding")
emph_node += nodes.Text(" " + message + " ")
emph_node += ref_node
emph_node += nodes.Text(" ")
emph_node += nodes.literal(record.name, record.name)
message = sphinx_gettext("is part of the")
emph_node += nodes.Text(" " + message + " ")
else:
message = sphinx_gettext("Part of the")
emph_node += nodes.Text(" " + message + " ")
ref_node = addnodes.pending_xref(
"Stable ABI",
refdomain="std",
@@ -265,6 +287,51 @@ class LimitedAPIList(SphinxDirective):
return [node]
class CorrespondingTypeSlot(SphinxDirective):
"""Type slot annotations
Docs for these are with the corresponding field, for example,
"Py_tp_repr" is documented under "PyTypeObject.tp_repr", with
only a stable ABI note mentioning "Py_tp_repr" (and linking to
docs on how this works).
If there is no corresponding field, these should be documented as normal
macros.
"""
has_content = False
required_arguments = 1
optional_arguments = 0
def run(self) -> list[nodes.Node]:
name = self.arguments[0]
state = self.env.domaindata["c_annotations"]
stable_abi_data = state["stable_abi_data"]
try:
record = stable_abi_data[name]
except LookupError as err:
raise LookupError(
f"{name} is not part of stable ABI. "
+ "Document it as `c:macro::` rather than "
+ "`corresponding-type-slot::`."
) from err
annotation = _stable_abi_annotation(record, is_corresponding_slot=True)
node = nodes.paragraph()
content = [
".. c:namespace:: NULL",
"",
".. c:macro:: " + name,
" :no-typesetting:",
]
self.state.nested_parse(StringList(content), 0, node)
node.insert(0, annotation)
return [node]
def init_annotations(app: Sphinx) -> None:
# Using domaindata is a bit hack-ish,
# but allows storing state without a global variable or closure.
@@ -281,6 +348,7 @@ def setup(app: Sphinx) -> ExtensionMetadata:
app.add_config_value("refcount_file", "", "env", types={str})
app.add_config_value("stable_abi_file", "", "env", types={str})
app.add_directive("limited-api-list", LimitedAPIList)
app.add_directive("corresponding-type-slot", CorrespondingTypeSlot)
app.connect("builder-inited", init_annotations)
app.connect("doctree-read", add_annotations)

4
Misc/stable_abi.toml
View File

@@ -2306,6 +2306,10 @@
added = '3.11'
[function.PyMemoryView_FromBuffer]
added = '3.11'
[const.Py_bf_getbuffer]
added = '3.11'
[const.Py_bf_releasebuffer]
added = '3.11'
# Constants for Py_buffer API added to this list in Python 3.11.1 (https://github.com/python/cpython/issues/98680)
# (they were available with 3.11.0)

2
Tools/build/stable_abi.py
View File

@@ -232,7 +232,7 @@ ITEM_KIND_TO_DOC_ROLE = {
'data': 'data',
'struct': 'type',
'macro': 'macro',
# 'const': 'const', # all undocumented
'const': 'macro',
'typedef': 'type',
}