gh-141004: Document missing descriptor C APIs

Doc/c-api/descriptor.rst

@@ -81,6 +81,26 @@ found in the dictionary of type objects.
    special method implemented by a type slot, together with the wrapper
    function used to adapt that slot to Python's calling convention.
 
+   .. c:member:: int flags
+
+      Bitwise OR of flags that describe the wrapper function. Currently, the
+      only flag is :c:macro:`PyWrapperFlag_KEYWORDS`; all other bits must be
+      zero.
+
+.. c:macro:: PyWrapperFlag_KEYWORDS
+
+   Flag that can be set in the :c:member:`~wrapperbase.flags` field of a
+   :c:struct:`wrapperbase` structure.
+   When set, the wrapper function is passed an additional argument with
+   a :class:`dict` instance containing the passed keyword arguments.
+   When not set, calling the wrapper descriptor with keyword arguments
+   raises :exc:`TypeError`.
+
+   This flag is specific to the way CPython implements slot wrappers; do not
+   use it in extensions.
+
+   .. soft-deprecated:: 3.16
+
 .. c:function:: PyObject* PyDescr_NewWrapper(PyTypeObject *type, struct wrapperbase *base, void *wrapped)
 
    Create a new wrapper descriptor for extension type *type* from the
@@ -138,6 +158,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

Doc/whatsnew/3.16.rst

@@ -1232,6 +1232,10 @@ Deprecated C APIs
   Use the safer :c:type:`PyUnicodeWriter` API instead.
   (Contributed by Victor Stinner in :gh:`157710`.)
 
+* :c:macro:`PyWrapperFlag_KEYWORDS` is :term:`soft deprecated`.
+  It exposes CPython implementation details and has no replacement.
+  (Contributed by Peter Bierma in :gh:`141004`.)
+
 .. Add C API deprecations above alphabetically, not here at the end.
 
 .. include:: ../deprecations/c-api-pending-removal-in-3.18.rst

Tools/check-c-api-docs/ignored_c_api.txt

@@ -29,10 +29,6 @@ PY_DWORD_MAX
 PY_BIG_ENDIAN
 # cpython/methodobject.h
 PyCFunction_GET_CLASS
-# cpython/descrobject.h
-PyDescr_NAME
-PyDescr_TYPE
-PyWrapperFlag_KEYWORDS
 # cpython/fileobject.h
 Py_UniversalNewlineFgets
 # cpython/pylifecycle.h