gh-141004: Document PyException_HEAD

[StanFromIreland]

• Issue: Document the entire C API #141004

---

📚 Documentation preview 📚: https://cpython-previews--141522.org.readthedocs.build/

[ZeroIntensity]

Please bring this one up with the C API WG for soft-deprecation. Ideally, new types should use PEP-697.

[vstinner]

Is PyException_HEAD used by 3rd party projects? I hope that it's not :-) I don't think that we should document this internal macro.

[StanFromIreland]

In the top 7000 or so projects:

./confluent_kafka-2.11.0.tar.gz: confluent_kafka-2.11.0/src/confluent_kafka/src/confluent_kafka.c: PyException_HEAD
./confluent_kafka-2.11.1.tar.gz: confluent_kafka-2.11.1/src/confluent_kafka/src/confluent_kafka.c: PyException_HEAD

Time: 0:00:17.890798
Found 2 matching lines in 2 projects

[ZeroIntensity]

I would assume that's being used there because they saw how we define exceptions internally and must have thought, "Oh, so that's how you do that". I'd be in favor of hard-deprecating this one, since it will likely create an actual maintenance burden if we want to change exceptions to use PEP 697 someday.