Deprecation of PyException_HEAD

[Krishna-web-hub]

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_HEAD is 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

Links to previous discussion of this feature:

#141522

Linked PRs

• gh-142410: Soft-deprecate PyException_HEAD in C API docs #145391

[picnixz]

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]

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]

Hi @picnixz, @ZeroIntensity
I agree with your point that unlike function where we can use Py_DEPRECATED( ) to deprecate the function which will be clean but the macros can not be deprecated like this but if we go by hard-deprecation then we will have to deprecate the field inside which will be messy and as @ZeroIntensity said we can add the documentation or news file for soft-depreciation. If you can suggest or guide me through any of these method i will be grateful to work on this issue.

[ZeroIntensity]

Let's wait until the C API WG has finished voting, then we can document the soft deprecation.

[picnixz]

@Krishna-web-hub Please avoid using LLM-generated answers that restate what has already been stated. It doesn't help much in the discussion. In addition, please read our policy regarding AI: https://devguide.python.org/getting-started/generative-ai/.

[Krishna-web-hub]

Thanks for the reminder. Just to clarify — the message was written by me, not copied from any LLM. I understand the concern, and I’ll make sure that my future comments contribute new information instead of repeating what is already in the thread.

[vstinner]

This issue proposes the depreciation of the PyException_HEAD macro.

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]

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]

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]

Yes, you can open a PR to soft deprecate the PyException_HEAD macro.