Repository navigation
Deprecation of PyException_HEAD #142410
Description
Summary
This issue proposes the depreciation of the PyException_HEAD macro.
During review of PR #141522 (Document PyException_HEAD), the reviewers indicated that
this macro is internal, should not be documented, and should instead be deprecated.
PyException_HEADis an internal macro used in CPython to define exception types.- It is not part of the public C API and was never intended to be used externally.
- However, a small number of external projects have copied this pattern (for example,
confluent_kafka). - If there are some internals change in the future (e.g. for PEP 697), this macro will
create a maintenance burden.
This deprecation would allow external projects time to migrate, rather than breaking
them immediately.
Proposed actions
- Marking the macro as deprecated in the header using
Py_DEPRECATED()or a
compiler warning. - We can also add the documentation note stating that the macro is deprecated and may be
removed in a future release. - We can add a NEWS entry.
- Recommending that new code use exception creation patterns compatible with PEP 697.
No behavior change or removal is proposed at this time.
CC
@ZeroIntensity
@vstinner
@StanFromIreland
Has this already been discussed elsewhere?
This has been discussed in one of the closed pr #141522
Activity
picnixz commentedon Dec 8, 2025
For the record, it's non-trivial to deprecate a macro. Unlike functions, macros don't have compiler's attributes. We could make an ugly hack where the fields in this macro are deprecated though.
ZeroIntensity commentedon Dec 8, 2025
We'll just soft-deprecate this if approved by the C API WG: capi-workgroup/decisions#86. It might be worth doing a hard-deprecation at some point, but I'm not going to bother fighting that battle right now.
Krishna-web-hub commentedon Dec 8, 2025
ZeroIntensity commentedon Dec 8, 2025
Let's wait until the C API WG has finished voting, then we can document the soft deprecation.
picnixz commentedon Dec 8, 2025
Krishna-web-hub commentedon Dec 8, 2025
vstinner commentedon Dec 8, 2025
I would prefer a soft deprecation rather than a hard deprecation. I don't think that this issue is severe enough to justify a hard deprecation.
Krishna-web-hub commentedon Dec 9, 2025
Thank you @vstinner. That makes sense. I will wait for the C API WG decision, and if approved, I can submit a PR that
adds the documentation note and NEWS entry for the soft deprecation.
Krishna-web-hub commentedon Feb 13, 2026
Hello @vstinner , @picnixz , @ZeroIntensity as C API WG has decided to soft deprecate the PyException_Head so should i raise a pr for the soft deprecation of PyException_Head.
vstinner commentedon Feb 13, 2026
Yes, you can open a PR to soft deprecate the PyException_HEAD macro.
pythongh-142410: Soft-deprecate PyException_HEAD in C API docs
pythongh-142410: Soft-deprecate PyException_HEAD in C API docs
ZeroIntensity commentedon Mar 1, 2026
I thought I already marked it as deprecated as part of #143896. I haven't added a warning note to any of the other soft-deprecated APIs, so I don't think it makes sense for
PyException_HEADto have one either.Krishna-web-hub commentedon Mar 1, 2026
@ZeroIntensity then should i close the PR and the Issue for this or any changes you want?.
ZeroIntensity commentedon Mar 2, 2026
Yeah, I think we're done here.