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

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

Doc/c-api/typeobj.rst

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

Doc/data/stable_abi.dat

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

Doc/tools/.nitignore

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

Doc/tools/extensions/c_annotations.py

@@ -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")
+    emph_node = nodes.emphasis('', '', classes=["stableabi"])
-    message = message.center(len(message) + 2)
+    if is_corresponding_slot:
-    emph_node = nodes.emphasis(message, message, classes=["stableabi"])
+        # 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 @@ def run(self) -> list[nodes.Node]:
         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)
 

Misc/stable_abi.toml

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

Tools/build/stable_abi.py

@@ -232,7 +232,7 @@ def sort_key(item):
     'data': 'data',
     'struct': 'type',
     'macro': 'macro',
-    # 'const': 'const',  # all undocumented
+    'const': 'macro',
     'typedef': 'type',
 }