Stowage/cpython
2
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-12-08 06:10:17 +00:00
Code Issues Projects Releases Packages 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
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
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);