FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

gh-141004: document `pyexpat` C API by picnixz · Pull Request #141259 · python/cpython · GitHub

/ cpython Public

gh-141004: document pyexpat C API - #141259

Open
picnixz wants to merge 10 commits into
python:mainfrom
picnixz:docs/capi/expat-141004
ConversationCommits (10)ChecksFiles changed
Open

gh-141004: document pyexpat C API#141259
picnixz wants to merge 10 commits into
python:mainfrom
picnixz:docs/capi/expat-141004

Conversation

picnixz commented Nov 8, 2025 •
edited by github-actions Bot
Loading

Copy link
Copy Markdown
Member

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

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

bedevere-app Bot added awaiting core review docs Documentation in the Doc dir labels Nov 8, 2025
github-project-automation Bot moved this to Todo in Docs PRs Nov 8, 2025
bedevere-app Bot mentioned this pull request Nov 8, 2025
Open
picnixz force-pushed the docs/capi/expat-141004 branch from 6164db5 to dc77ab0 Compare November 8, 2025 17:15
picnixz force-pushed the docs/capi/expat-141004 branch from dc77ab0 to 5b857a4 Compare November 8, 2025 17:18
ZeroIntensity reviewed Nov 8, 2025
View reviewed changes

ZeroIntensity left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

Thanks for working on these!

Comment thread Include/pyexpat.h Outdated
Comment thread Doc/conf.py
Comment thread Doc/c-api/expat.rst Outdated
picnixz commented Nov 8, 2025
View reviewed changes
Comment thread Include/pyexpat.h
This was referenced Nov 9, 2025
Closed
Closed
ZeroIntensity reviewed Nov 10, 2025
View reviewed changes
Comment thread Include/pyexpat.h
Comment on lines +9 to +10
struct PyExpat_CAPI {
char *magic; /* set to PyExpat_CAPI_MAGIC */

ZeroIntensity Nov 10, 2025

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

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

vstinner reviewed Nov 10, 2025
View reviewed changes

vstinner left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

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 commented Nov 11, 2025

Copy link
Copy Markdown
Member

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

vstinner commented Nov 13, 2025

Copy link
Copy Markdown
Member

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

picnixz commented Nov 14, 2025

Copy link
Copy Markdown
Member Author

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 reviewed Nov 23, 2025
View reviewed changes
Comment thread Doc/c-api/expat.rst
included by default by :file:`Python.h`) and ``expat.h`` for Expat.

To use the C API, consider adding the following code in your extension
module initilisation function and store the pointer to the C API in

aisk Nov 23, 2025

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

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 commented Nov 23, 2025

Copy link
Copy Markdown
Member

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 commented Nov 29, 2025 •
edited
Loading

Copy link
Copy Markdown
Member Author

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 commented Dec 1, 2025

Copy link
Copy Markdown
Member

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).

github-actions Bot commented May 1, 2026

Copy link
Copy Markdown

This PR is stale because it has been open for 30 days with no activity.

github-actions Bot added the stale Stale PR or inactive for long period of time. label May 1, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
Show hidden characters
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

vstinner vstinner left review comments
aisk aisk left review comments
ZeroIntensity ZeroIntensity left review comments
AA-Turner Awaiting requested review from AA-Turner AA-Turner is a code owner
hugovk Awaiting requested review from hugovk hugovk is a code owner

Assignees

No one assigned

Labels

awaiting core review docs Documentation in the Doc dir skip news stale Stale PR or inactive for long period of time.

Projects

Docs PRs
Status: Todo

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

6 participants

Back | FazBrowse Home | New Git URL