From 2920c55d44b448d55f75d883565fdf7507abca82 Mon Sep 17 00:00:00 2001 From: Boy Steven Benaya Aritonang Date: Tue, 31 Mar 2026 03:33:30 +0700 Subject: [PATCH 1/3] Docs: fill in descriptor C API docs --- Doc/c-api/descriptor.rst | 54 ++++++++++++++++++++++++++++++++-------- 1 file changed, 44 insertions(+), 10 deletions(-) diff --git a/Doc/c-api/descriptor.rst b/Doc/c-api/descriptor.rst index e23288c6a58590..115441e85a2dc7 100644 --- a/Doc/c-api/descriptor.rst +++ b/Doc/c-api/descriptor.rst @@ -8,13 +8,21 @@ Descriptor Objects "Descriptors" are objects that describe some attribute of an object. They are found in the dictionary of type objects. -.. XXX document these! - .. c:function:: PyObject* PyDescr_NewGetSet(PyTypeObject *type, struct PyGetSetDef *getset) + Create a new get-set descriptor for extension type *type* from the + :c:type:`PyGetSetDef` structure *getset*. + + On success, return a :term:`strong reference` to the descriptor. Return + ``NULL`` with an exception set on failure. -.. c:function:: PyObject* PyDescr_NewMember(PyTypeObject *type, struct PyMemberDef *meth) +.. c:function:: PyObject* PyDescr_NewMember(PyTypeObject *type, struct PyMemberDef *member) + Create a new member descriptor for extension type *type* from the + :c:type:`PyMemberDef` structure *member*. + + On success, return a :term:`strong reference` to the descriptor. Return + ``NULL`` with an exception set on failure. .. c:var:: PyTypeObject PyMemberDescr_Type @@ -30,22 +38,37 @@ found in the dictionary of type objects. The type object for get/set descriptor objects created from :c:type:`PyGetSetDef` structures. These descriptors implement attributes whose value is computed by C getter and setter functions, and are used - for many built-in type attributes. + for many built-in type attributes. They correspond to + :class:`types.GetSetDescriptorType` objects in Python. .. c:function:: PyObject* PyDescr_NewMethod(PyTypeObject *type, struct PyMethodDef *meth) + Create a new method descriptor for extension type *type* from the + :c:type:`PyMethodDef` structure *meth*. + + On success, return a :term:`strong reference` to the descriptor. Return + ``NULL`` with an exception set on failure. .. c:var:: PyTypeObject PyMethodDescr_Type The type object for method descriptor objects created from :c:type:`PyMethodDef` structures. These descriptors expose C functions as - methods on a type, and correspond to :class:`types.MemberDescriptorType` + methods on a type, and correspond to :class:`types.MethodDescriptorType` objects in Python. -.. c:function:: PyObject* PyDescr_NewWrapper(PyTypeObject *type, struct wrapperbase *wrapper, void *wrapped) +.. c:function:: PyObject* PyDescr_NewWrapper(PyTypeObject *type, struct wrapperbase *base, void *wrapped) + Create a new wrapper descriptor for extension type *type* from the + ``struct wrapperbase`` structure *base* and the wrapped C function pointer + *wrapped*. + + Wrapper descriptors are used internally to expose special methods + implemented by slot wrappers. + + On success, return a :term:`strong reference` to the descriptor. Return + ``NULL`` with an exception set on failure. .. c:var:: PyTypeObject PyWrapperDescr_Type @@ -58,6 +81,11 @@ found in the dictionary of type objects. .. c:function:: PyObject* PyDescr_NewClassMethod(PyTypeObject *type, PyMethodDef *method) + Create a new class method descriptor for extension type *type* from the + :c:type:`PyMethodDef` structure *method*. + + On success, return a :term:`strong reference` to the descriptor. Return + ``NULL`` with an exception set on failure. .. c:function:: int PyDescr_IsData(PyObject *descr) @@ -66,8 +94,14 @@ found in the dictionary of type objects. no error checking. -.. c:function:: PyObject* PyWrapper_New(PyObject *, PyObject *) +.. c:function:: PyObject* PyWrapper_New(PyObject *d, PyObject *self) + + Create a new bound wrapper object from the wrapper descriptor *d* and the + object *self*. The returned object appears in Python as a + :class:`types.MethodWrapperType` instance. + On success, return a :term:`strong reference` to the wrapper object. Return + ``NULL`` with an exception set on failure. .. c:macro:: PyDescr_COMMON @@ -104,9 +138,9 @@ Built-in descriptors .. c:var:: PyTypeObject PyClassMethodDescr_Type The type object for C-level class method descriptor objects. - This is the type of the descriptors created for :func:`classmethod` defined in - C extension types, and is the same object as :class:`classmethod` - in Python. + This is the type of the descriptors created for :func:`classmethod` defined + in C extension types, and corresponds to + :class:`types.ClassMethodDescriptorType` objects in Python. .. c:function:: PyObject *PyClassMethod_New(PyObject *callable) From 3b1855c7dcfbe03a058863def38ccaaccc42f7f9 Mon Sep 17 00:00:00 2001 From: Boy Steven Benaya Aritonang Date: Tue, 31 Mar 2026 10:31:44 +0700 Subject: [PATCH 2/3] Docs: expand descriptor C API docs --- Doc/c-api/descriptor.rst | 45 +++++++++++++++++++++++++++++++++++----- 1 file changed, 40 insertions(+), 5 deletions(-) diff --git a/Doc/c-api/descriptor.rst b/Doc/c-api/descriptor.rst index 115441e85a2dc7..b913e24b3c7cc8 100644 --- a/Doc/c-api/descriptor.rst +++ b/Doc/c-api/descriptor.rst @@ -13,6 +13,11 @@ found in the dictionary of type objects. Create a new get-set descriptor for extension type *type* from the :c:type:`PyGetSetDef` structure *getset*. + Get-set descriptors expose attributes implemented by C getter and setter + functions rather than stored directly in the instance. This is the same kind + of descriptor created for entries in :c:member:`~PyTypeObject.tp_getset`, and + it appears in Python as a :class:`types.GetSetDescriptorType` object. + On success, return a :term:`strong reference` to the descriptor. Return ``NULL`` with an exception set on failure. @@ -21,6 +26,11 @@ found in the dictionary of type objects. Create a new member descriptor for extension type *type* from the :c:type:`PyMemberDef` structure *member*. + Member descriptors expose fields in the type's C struct as Python + attributes. This is the same kind of descriptor created for entries in + :c:member:`~PyTypeObject.tp_members`, and it appears in Python as a + :class:`types.MemberDescriptorType` object. + On success, return a :term:`strong reference` to the descriptor. Return ``NULL`` with an exception set on failure. @@ -47,6 +57,11 @@ found in the dictionary of type objects. Create a new method descriptor for extension type *type* from the :c:type:`PyMethodDef` structure *meth*. + Method descriptors expose C functions as methods on a type. This is the same + kind of descriptor created for entries in + :c:member:`~PyTypeObject.tp_methods`, and it appears in Python as a + :class:`types.MethodDescriptorType` object. + On success, return a :term:`strong reference` to the descriptor. Return ``NULL`` with an exception set on failure. @@ -58,14 +73,25 @@ found in the dictionary of type objects. objects in Python. +.. c:struct:: wrapperbase + + Describes a slot wrapper used by :c:func:`PyDescr_NewWrapper`. + + 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) Create a new wrapper descriptor for extension type *type* from the - ``struct wrapperbase`` structure *base* and the wrapped C function pointer + :c:struct:`wrapperbase` structure *base* and the wrapped slot function + pointer *wrapped*. - Wrapper descriptors are used internally to expose special methods - implemented by slot wrappers. + 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. On success, return a :term:`strong reference` to the descriptor. Return ``NULL`` with an exception set on failure. @@ -84,6 +110,11 @@ found in the dictionary of type objects. Create a new class method descriptor for extension type *type* from the :c:type:`PyMethodDef` structure *method*. + Class method descriptors expose C methods that receive the class rather than + an instance when accessed. This is the same kind of descriptor created for + ``METH_CLASS`` entries in :c:member:`~PyTypeObject.tp_methods`, and it + appears in Python as a :class:`types.ClassMethodDescriptorType` object. + On success, return a :term:`strong reference` to the descriptor. Return ``NULL`` with an exception set on failure. @@ -97,8 +128,12 @@ found in the dictionary of type objects. .. c:function:: PyObject* PyWrapper_New(PyObject *d, PyObject *self) Create a new bound wrapper object from the wrapper descriptor *d* and the - object *self*. The returned object appears in Python as a - :class:`types.MethodWrapperType` instance. + instance *self*. + + This is the bound form of a wrapper descriptor created by + :c:func:`PyDescr_NewWrapper`. CPython creates these objects when a slot + wrapper is accessed through an instance, and they appear in Python as + :class:`types.MethodWrapperType` objects. On success, return a :term:`strong reference` to the wrapper object. Return ``NULL`` with an exception set on failure. From 32befca7e7b80254567d7667f3cdc22d3c975cb2 Mon Sep 17 00:00:00 2001 From: Boy Steven Benaya Aritonang Date: Tue, 31 Mar 2026 10:42:49 +0700 Subject: [PATCH 3/3] Docs: remove descriptor page from nitignore --- Doc/tools/.nitignore | 1 - 1 file changed, 1 deletion(-) diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore index ffe98d332d6e93..189173a5f8a75f 100644 --- a/Doc/tools/.nitignore +++ b/Doc/tools/.nitignore @@ -2,7 +2,6 @@ # as tested on the CI via check-warnings.py in reusable-docs.yml. # Keep lines sorted lexicographically to help avoid merge conflicts. -Doc/c-api/descriptor.rst Doc/c-api/init_config.rst Doc/c-api/intro.rst Doc/c-api/stable.rst