gh-141004: document pyexpat C API

[picnixz]

The Expat C API does not store a global variable as other C APIs and instead prefer consumers to add both the capsule and the C API pointer in the consumer's state. I don't really llike this but it's probably the best

• Issue: Document the entire C API #141004

---

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

[ZeroIntensity]

Thanks for working on these!

[ZeroIntensity]

Let's avoid making code formatting changes in this PR.

[vstinner]

The PyExpat capsule is used to access Modules/pyexpat.c functions in Modules/_elementtree.c. I'm not sure that it was intended to be used outside Modules/_elementtree.c.

A code search on PyPI top 15,000 projects (at 2025-09-22) found no matching projects.

In 2020, I moved the Unicode capsule C structure to the internal C API (pycore_ucnhash.h): commit 47e1afd. Then I renamed the PyUnicodeData_CAPSULE_NAME to make it private: commit 84f7382. I expected lot of complains and broken projects, but no one was impacted :-) It went well.

[encukou]

If you need this you should probably use expat directly; the vendored copy is aliased so that it shouldn't conflict.

[vstinner]

Should we deprecate the pyexpat public capsule, and use a private capsule in elementtree?

[picnixz]

I don't use this personally so I would prefer deprecating and making it private :') However, while there might not exist public code relying on this, there might exist private one =/. Strictly speaking, there is actually one handler that Python provides and this is DefaultUnknownEncodingHandler. I'm not sure how it's used actually...

[aisk]

Typo:

Suggested change

	module initilisation function and store the pointer to the C API in
	module initialization function and store the pointer to the C API in

[vstinner]

I don't use this personally so I would prefer deprecating and making it private :') However, while there might not exist public code relying on this, there might exist private one =/

That's the purpose of a deprecation over multiple years, communicate that we are going to remove an API, to give users time to report their usage and ask to keep the API and provide a different one.

[picnixz]

Ok, but how do I really deprecate this one? should I just go with a Py_DEPRECATED for the struct? I actually don't know how to smoothly deprecate a capsule API that is used internally. I would say "no need for docs then" since we don't want it to be availablke but at the same time, the only place where it would be deprecated is... in the What's New. Or, is adding docs for deprecated objects fine? (well I could just say that the capsule API for PyExpat is deprecated).

[encukou]

Yeah, Py_DEPRECATED_EXTERNALLY on the struct seems like the way to go.

As is adding docs to hold “porting notes” (i.e. use the Python APIs, or expat directly).