From 65d6ced9e68523a549e74d806021fa503ac7e9a9 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Thu, 15 Jan 2026 22:54:33 -0500 Subject: [PATCH 1/3] Document PyException_HEAD --- Doc/c-api/exceptions.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst index d7fe9e2c9ec9b4..59af470f59ff34 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 ================= From 6898b426a676290efbd7e65a4c00eb627f2df563 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Thu, 15 Jan 2026 22:59:46 -0500 Subject: [PATCH 2/3] Document PyDescr_COMMON --- Doc/c-api/descriptor.rst | 22 +++++++++++++++++----- 1 file changed, 17 insertions(+), 5 deletions(-) diff --git a/Doc/c-api/descriptor.rst b/Doc/c-api/descriptor.rst index 313c534545a861..e23288c6a58590 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 From 83011f7840a8ba1f8e4c128590d03f63629c0f59 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Sat, 17 Jan 2026 10:19:53 -0500 Subject: [PATCH 3/3] Fix my stupid script. --- Tools/check-c-api-docs/ignored_c_api.txt | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/Tools/check-c-api-docs/ignored_c_api.txt b/Tools/check-c-api-docs/ignored_c_api.txt index de78f6425803cb..e0b2670808c79c 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