From b5dd2e8407ef0673185e06b13f50ff3bfd339d1f Mon Sep 17 00:00:00 2001
From: Peter Bierma <zintensitydev@gmail.com>
Date: Mon, 19 Oct 2026 12:44:36 -0400
Subject: [PATCH 1/2] Document missing descriptor C APIs.

---
 Doc/c-api/descriptor.rst                 | 39 ++++++++++++++++++++++++
 Tools/check-c-api-docs/ignored_c_api.txt |  4 ---
 2 files changed, 39 insertions(+), 4 deletions(-)

diff --git a/Doc/c-api/descriptor.rst b/Doc/c-api/descriptor.rst
index 539c4610ce4f5bc..db4a95c48a19d08 100644
--- a/Doc/c-api/descriptor.rst
+++ b/Doc/c-api/descriptor.rst
@@ -81,6 +81,21 @@ 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`.
+
 .. 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 +153,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 af7b2772ef5e085..2da956df1043d45 100644
--- a/Tools/check-c-api-docs/ignored_c_api.txt
+++ b/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

From 75633aff727ad4a320f537c069baa0e9d025ffc2 Mon Sep 17 00:00:00 2001
From: Peter Bierma <zintensitydev@gmail.com>
Date: Mon, 19 Oct 2026 12:48:46 -0400
Subject: [PATCH 2/2] Add soft deprecation.

---
 Doc/c-api/descriptor.rst | 5 +++++
 Doc/whatsnew/3.16.rst    | 4 ++++
 2 files changed, 9 insertions(+)

diff --git a/Doc/c-api/descriptor.rst b/Doc/c-api/descriptor.rst
index db4a95c48a19d08..a81e4fc0a0494c8 100644
--- a/Doc/c-api/descriptor.rst
+++ b/Doc/c-api/descriptor.rst
@@ -96,6 +96,11 @@ found in the dictionary of type objects.
    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
diff --git a/Doc/whatsnew/3.16.rst b/Doc/whatsnew/3.16.rst
index a1d7d1eaae7d526..baaa8bcf22ef36e 100644
--- a/Doc/whatsnew/3.16.rst
+++ b/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