From 23e13320baab76a45a7d9fac3da158dc30bd4dd3 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Wed, 21 Oct 2026 18:24:45 -0400 Subject: [PATCH] [3.14] gh-141004: Document missing descriptor C APIs (GH-159709) (cherry picked from commit aed4ad8c4397595df7d822749556681a8a86208d) Co-authored-by: Peter Bierma Co-authored-by: Petr Viktorin --- Doc/c-api/descriptor.rst | 64 ++++++++++++++++-------- Tools/check-c-api-docs/ignored_c_api.txt | 3 -- 2 files changed, 42 insertions(+), 25 deletions(-) diff --git a/Doc/c-api/descriptor.rst b/Doc/c-api/descriptor.rst index 813741f3eda51a5..ad3accd905efb35 100644 --- a/Doc/c-api/descriptor.rst +++ b/Doc/c-api/descriptor.rst @@ -77,38 +77,34 @@ found in the dictionary of type objects. methods on a type, and correspond to :class:`types.MethodDescriptorType` objects in Python. +.. c:var:: PyTypeObject PyWrapperDescr_Type -.. c:struct:: wrapperbase + The type object for wrapper descriptor objects created by + :c:func:`PyDescr_NewWrapper` and :c:func:`PyWrapper_New`. - Describes a slot wrapper used by :c:func:`PyDescr_NewWrapper`. + Wrapper descriptors are used internally to expose special methods + such as ``__repr__`` or ``__add__``, which are implemented by type slots. + The type is exposed in Python as :class:`types.WrapperDescriptorType`. - Each ``wrapperbase`` record stores the Python-visible name and metadata for a - special method implemented by a type slot, together with the wrapper - function used to adapt that slot to Python's calling convention. -.. c:function:: PyObject* PyDescr_NewWrapper(PyTypeObject *type, struct wrapperbase *base, void *wrapped) +.. `wrapperbase` & `PyWrapperFlag_KEYWORDS` show up in search and index, + and link here, but are only referenced in prose: - Create a new wrapper descriptor for extension type *type* from the - :c:struct:`wrapperbase` structure *base* and the wrapped slot function - pointer - *wrapped*. +.. c:struct:: wrapperbase + :no-typesetting: - Wrapper descriptors expose special methods implemented by type slots. This - is the same kind of descriptor that CPython creates for slot-based special - methods such as ``__repr__`` or ``__add__``, and it appears in Python as a - :class:`types.WrapperDescriptorType` object. +.. c:macro:: PyWrapperFlag_KEYWORDS + :no-typesetting: - On success, return a :term:`strong reference` to the descriptor. Return - ``NULL`` with an exception set on failure. +.. c:function:: PyObject* PyDescr_NewWrapper(PyTypeObject *type, struct wrapperbase *base, void *wrapped) -.. c:var:: PyTypeObject PyWrapperDescr_Type + Create a new wrapper descriptor of type :c:var:`PyWrapperDescr_Type`. - The type object for wrapper descriptor objects created by - :c:func:`PyDescr_NewWrapper` and :c:func:`PyWrapper_New`. Wrapper - descriptors are used internally to expose special methods implemented - via wrapper structures, and appear in Python as - :class:`types.WrapperDescriptorType` objects. + This function is meant for internal use only; it and + related API (``struct wrapperbase`` and the ``PyWrapperFlag_KEYWORDS`` + flag) are exposed publicly for backwards compatibility reasons. + See :c:func:`PyCMethod_New` for wrapping a C function. .. c:function:: PyObject* PyDescr_NewClassMethod(PyTypeObject *type, PyMethodDef *method) @@ -143,6 +139,30 @@ found in the dictionary of type objects. On success, return a :term:`strong reference` to the wrapper object. Return ``NULL`` with an exception set on failure. +.. c:macro:: PyDescr_TYPE(descr) + + Return a :term:`borrowed reference` to the type that the descriptor + *descr* belongs to. This is accessible as :attr:`~object.__objclass__` + in Python. + + *descr* must be a descriptor object created by one of the + ``PyDescr_New*`` functions (an instance of + :c:var:`PyMethodDescr_Type`, :c:var:`PyClassMethodDescr_Type`, + :c:var:`PyMemberDescr_Type`, :c:var:`PyGetSetDescr_Type`, or + :c:var:`PyWrapperDescr_Type`). If the passed descriptor is not + an instance of one of these types, the behavior is undefined. + + +.. c:macro:: PyDescr_NAME(descr) + + Return the name of the descriptor *descr* as a :term:`borrowed reference` + to a :class:`str` object. This is available as :attr:`~definition.__name__` + in Python. + + *descr* must be a descriptor object created by one of the ``PyDescr_New*`` + functions. If not, the behavior is undefined. + + Built-in descriptors ^^^^^^^^^^^^^^^^^^^^ diff --git a/Tools/check-c-api-docs/ignored_c_api.txt b/Tools/check-c-api-docs/ignored_c_api.txt index a68fff6ae57e39b..3423f1862f0c1d3 100644 --- a/Tools/check-c-api-docs/ignored_c_api.txt +++ b/Tools/check-c-api-docs/ignored_c_api.txt @@ -28,9 +28,6 @@ PY_VERSION Py_UNICODE_SIZE # cpython/descrobject.h PyDescr_COMMON -PyDescr_NAME -PyDescr_TYPE -PyWrapperFlag_KEYWORDS # 3.14 only Py_TPFLAGS_PREHEADER PyUnicode_AsDecodedObject