From d51c01a2715ae7f2b0c6fc3bd3881f049c2a8d9e Mon Sep 17 00:00:00 2001
From: Peter Bierma <zintensitydev@gmail.com>
Date: Sat, 17 Jan 2026 07:39:29 -0800
Subject: [PATCH] gh-141004: Document `PyException_HEAD` and `PyDescr_COMMON`
 (GH-143896)

---
 Doc/c-api/descriptor.rst                 | 22 +++++++++++++++++-----
 Doc/c-api/exceptions.rst                 | 11 +++++++++++
 Tools/check-c-api-docs/ignored_c_api.txt |  5 +----
 3 files changed, 29 insertions(+), 9 deletions(-)

diff --git a/Doc/c-api/descriptor.rst b/Doc/c-api/descriptor.rst
index 313c534545a8..e23288c6a585 100644
--- a/Doc/c-api/descriptor.rst
+++ b/Doc/c-api/descriptor.rst
@@ -10,11 +10,6 @@ found in the dictionary of type objects.
 
 .. XXX document these!
 
-.. c:var:: PyTypeObject PyProperty_Type
-
-   The type object for the built-in descriptor types.
-
-
 .. c:function:: PyObject* PyDescr_NewGetSet(PyTypeObject *type, struct PyGetSetDef *getset)
 
 
@@ -74,9 +69,26 @@ found in the dictionary of type objects.
 .. c:function:: PyObject* PyWrapper_New(PyObject *, PyObject *)
 
 
+.. c:macro:: PyDescr_COMMON
+
+   This is a :term:`soft deprecated` macro including the common fields for a
+   descriptor object.
+
+   This was included in Python's C API by mistake; do not use it in extensions.
+   For creating custom descriptor objects, create a class implementing the
+   descriptor protocol (:c:member:`~PyTypeObject.tp_descr_get` and
+   :c:member:`~PyTypeObject.tp_descr_set`).
+
+
 Built-in descriptors
 ^^^^^^^^^^^^^^^^^^^^
 
+.. c:var:: PyTypeObject PyProperty_Type
+
+   The type object for property objects. This is the same object as
+   :class:`property` in the Python layer.
+
+
 .. c:var:: PyTypeObject PySuper_Type
 
    The type object for super objects. This is the same object as
diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst
index d7fe9e2c9ec9..59af470f59ff 100644
--- a/Doc/c-api/exceptions.rst
+++ b/Doc/c-api/exceptions.rst
@@ -793,6 +793,17 @@ Exception Classes
    Return :c:member:`~PyTypeObject.tp_name` of the exception class *ob*.
 
 
+.. c:macro:: PyException_HEAD
+
+   This is a :term:`soft deprecated` macro including the base fields for an
+   exception object.
+
+   This was included in Python's C API by mistake and is not designed for use
+   in extensions. For creating custom exception objects, use
+   :c:func:`PyErr_NewException` or otherwise create a class inheriting from
+   :c:data:`PyExc_BaseException`.
+
+
 Exception Objects
 =================
 
diff --git a/Tools/check-c-api-docs/ignored_c_api.txt b/Tools/check-c-api-docs/ignored_c_api.txt
index de78f6425803..e0b2670808c7 100644
--- a/Tools/check-c-api-docs/ignored_c_api.txt
+++ b/Tools/check-c-api-docs/ignored_c_api.txt
@@ -66,7 +66,6 @@ PyCF_MASK
 PyCF_MASK_OBSOLETE
 PyCF_SOURCE_IS_UTF8
 # cpython/descrobject.h
-PyDescr_COMMON
 PyDescr_NAME
 PyDescr_TYPE
 PyWrapperFlag_KEYWORDS
@@ -76,8 +75,6 @@ Py_UniversalNewlineFgets
 PyUnstable_CopyPerfMapFile
 PyUnstable_PerfTrampoline_CompileCode
 PyUnstable_PerfTrampoline_SetPersistAfterFork
-# cpython/pyerrors.h
-PyException_HEAD
 # cpython/pyframe.h
 PyUnstable_EXECUTABLE_KINDS
 PyUnstable_EXECUTABLE_KIND_BUILTIN_FUNCTION
@@ -121,4 +118,4 @@ PY_MONITORING_EVENT_BRANCH
 PY_DEF_EVENT
 PY_FOREACH_DICT_EVENT
 # cpython/pystats.h
-PYSTATS_MAX_UOP_ID
\ No newline at end of file
+PYSTATS_MAX_UOP_ID
-- 
2.47.3