diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst index 59af470f59ff34..2c749d55aaa31b 100644 --- a/Doc/c-api/exceptions.rst +++ b/Doc/c-api/exceptions.rst @@ -795,11 +795,15 @@ Exception Classes .. c:macro:: PyException_HEAD - This is a :term:`soft deprecated` macro including the base fields for an - exception object. + Include 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 + .. deprecated:: 3.14 + ``PyException_HEAD`` is an internal implementation detail that was not + intended to be exposed as part of the python C API and is not designed + for use by third-party extensions. + + The macro may be changed or removed in a future Python version. + Extensions authors should instead create exception class using :c:func:`PyErr_NewException` or otherwise create a class inheriting from :c:data:`PyExc_BaseException`. diff --git a/Misc/NEWS.d/next/Documentation/2026-03-01-19-54-44.gh-issue-142410.8f-dkN.rst b/Misc/NEWS.d/next/Documentation/2026-03-01-19-54-44.gh-issue-142410.8f-dkN.rst new file mode 100644 index 00000000000000..270401100ac9d7 --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2026-03-01-19-54-44.gh-issue-142410.8f-dkN.rst @@ -0,0 +1,3 @@ +Soft-deprecate the ``PyException_HEAD`` macro in the C API documentation. +The macro is an internal implementation detail and should not be used by +third-party extensions.