https://github.com/python/cpython/commit/aed4ad8c4397595df7d822749556681a8a86208d commit: aed4ad8c4397595df7d822749556681a8a86208d branch: main author: Peter Bierma <[email protected]> committer: ZeroIntensity <[email protected]> date: 2026-10-21T22:24:45Z summary:
gh-141004: Document missing descriptor C APIs (GH-159709) Co-authored-by: Petr Viktorin <[email protected]> files: M Doc/c-api/descriptor.rst M Tools/check-c-api-docs/ignored_c_api.txt diff --git a/Doc/c-api/descriptor.rst b/Doc/c-api/descriptor.rst index 539c4610ce4f5b..5d3e7ec95f31e2 100644 --- a/Doc/c-api/descriptor.rst +++ b/Doc/c-api/descriptor.rst @@ -72,38 +72,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) @@ -138,6 +134,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. + + .. c:macro:: PyDescr_COMMON This is a macro including the common fields for a diff --git a/Tools/check-c-api-docs/ignored_c_api.txt b/Tools/check-c-api-docs/ignored_c_api.txt index c2003dff7b6b6b..6e1b77ba2786cb 100644 --- a/Tools/check-c-api-docs/ignored_c_api.txt +++ b/Tools/check-c-api-docs/ignored_c_api.txt @@ -1,4 +1 @@ -# cpython/descrobject.h -PyDescr_NAME -PyDescr_TYPE -PyWrapperFlag_KEYWORDS +# Nothing here :) _______________________________________________ Python-checkins mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3//lists/python-checkins.python.org Member address: [email protected]
