https://github.com/python/cpython/commit/d51c01a2715ae7f2b0c6fc3bd3881f049c2a8d9e
commit: d51c01a2715ae7f2b0c6fc3bd3881f049c2a8d9e
branch: main
author: Peter Bierma <[email protected]>
committer: ZeroIntensity <[email protected]>
date: 2026-01-17T10:39:29-05:00
summary:
gh-141004: Document `PyException_HEAD` and `PyDescr_COMMON` (GH-143896)
files:
M Doc/c-api/descriptor.rst
M Doc/c-api/exceptions.rst
M Tools/check-c-api-docs/ignored_c_api.txt
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
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
=================
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
_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3//lists/python-checkins.python.org
Member address: [email protected]
