gh-141004: Add a CI job ensuring that new C APIs include documentation by ZeroIntensity · Pull Request #142102 · python/cpython

ZeroIntensity · 2025-11-30T00:34:05Z

This adds a simple job requiring that any new public C APIs come with documentation, which should prevent things from slipping through the cracks each release.

Issue: Document the entire C API #141004

StanFromIreland · 2025-11-30T11:14:52Z

+ IGNORED.pop(index)
+
+
+def is_documented(name: str) -> bool:


I think is_documented is a little different from is present. Why not improve the check to include verifying it's a doc declaration, i.e. if it's in the text check it's on the same line as the c:func:: etc.?

I thought about that, but I decided that it was a case of "practicality beats purity". Running Sphinx or using a regular expression will make this significantly slower, and probably won't save us much in practice.

As a compromise, we could go ever simpler, just checking if :: and .. are in the same line as the API name.

Hm, that may work, but the list in #141004 was created using a full-text search, not a search for :: or .., so there are probably some APIs that still need work. Let's finish the list in #141004 first, and then we can look into finding more edge cases.

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

ZeroIntensity · 2025-12-01T00:29:07Z

I plan on backporting this to prevent conflicts when things are removed from ignored_c_api.txt. Any objections?

hugovk · 2025-12-01T16:59:50Z

No objection to backporting.

StanFromIreland

This currently picks up decelerations in comments, e.g. Py_OldFunction which is an example. This currently passes as the same example is used in the docs.

Edit: I wrote: ZeroIntensity#6

ZeroIntensity · 2025-12-01T22:56:00Z

I assume that this is broken in strings too, for example: puts("PyAPI_FUNC(int) PySomething(void);"). There are plenty of ways to break the regular expressions.

We can't really get this to work perfectly without using an actual C parser. If those comments aren't causing problems for us, why bother?

ZeroIntensity · 2025-12-02T03:02:01Z

To clarify: I agree with eventually adding better handling, I just don't think it should be done here. I'd like this script to be as close as possible to the script used to generate the list in #141004. We can expand on this in a later iteration.

…ocs-check

ZeroIntensity · 2025-12-04T02:49:05Z

I'm going to merge this. For changes regarding the mock C parsing here, please open a new issue and/or PR.

miss-islington-app · 2025-12-04T03:14:28Z

Thanks @ZeroIntensity for the PR 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14.
🐍🍒⛏🤖

miss-islington-app · 2025-12-04T03:14:31Z

Sorry, @ZeroIntensity, I could not cleanly backport this to 3.14 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker 1a7824a927f0706300af7bfc182884a43e2f587a 3.14

miss-islington-app · 2025-12-04T03:14:35Z

Sorry, @ZeroIntensity, I could not cleanly backport this to 3.13 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker 1a7824a927f0706300af7bfc182884a43e2f587a 3.13

bedevere-app · 2025-12-04T03:56:31Z

GH-142247 is a backport of this pull request to the 3.14 branch.

…ntation (pythonGH-142102) Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> (cherry picked from commit 1a7824a)

… documentation (pythonGH-142102) (cherry picked from commit 1a7824a) Co-authored-by: Peter Bierma <zintensitydev@gmail.com> Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

bedevere-app · 2025-12-04T03:59:06Z

GH-142248 is a backport of this pull request to the 3.13 branch.

…ntation (pythonGH-142102) Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> (cherry picked from commit 1a7824a)

… documentation (pythonGH-142102) (cherry picked from commit 1a7824a) Co-authored-by: Peter Bierma <zintensitydev@gmail.com> Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

…entation (GH-142102) (GH-142247) * gh-141004: Add a CI job ensuring that new C APIs include documentation (GH-142102) Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> (cherry picked from commit 1a7824a) --------- Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

…ntation (pythonGH-142102) Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

…entation (GH-142102) (GH-142248) * gh-141004: Add a CI job ensuring that new C APIs include documentation (GH-142102) Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> (cherry picked from commit 1a7824a) * [3.13] gh-141004: Add a CI job ensuring that new C APIs include documentation (GH-142102) (cherry picked from commit 1a7824a) Co-authored-by: Peter Bierma <zintensitydev@gmail.com> Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> * Update Tools/check-c-api-docs/ignored_c_api.txt --------- Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

ZeroIntensity added 6 commits November 29, 2025 15:04

Add a tool for finding undocumented C API
77d1750

Add a CI job.
e219136

General improvements.
8c88402

Add myself as a codeowner.
0f687cf

Run black.
ec03845

Eliminate some duplication.
2510476

ZeroIntensity requested review from AA-Turner, emmatyping, erlend-aasland, ezio-melotti and hugovk as code owners November 30, 2025 00:34

bedevere-appBot added the awaiting core review label Nov 30, 2025

bedevere-appBot mentioned this pull request Nov 30, 2025
Document the entire C API #141004
Open

ZeroIntensity added the skip news label Nov 30, 2025

hugovk reviewed Nov 30, 2025
View reviewed changes

StanFromIreland reviewed Nov 30, 2025
View reviewed changes

ZeroIntensityand others added 4 commits November 30, 2025 11:15

Apply suggestions from code review
51b2747
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

Fix alphabetical order.
cb9a68d

Change plurality in the message depending on the size of the list.
681962d

Fix indentation on the output.
1d0c8f6

hugovk approved these changes Nov 30, 2025
View reviewed changes

Comment threadTools/check-c-api-docs/main.py Outdated
Comment thread.github/workflows/build.yml Outdated

bedevere-appBot added awaiting merge and removed awaiting core review labels Nov 30, 2025

ZeroIntensityand others added 2 commits November 30, 2025 19:26

Update .github/workflows/build.yml
f487d6e
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

Update Tools/check-c-api-docs/main.py
02d2f07
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

ZeroIntensity added needs backport to 3.13 bugs and security fixes needs backport to 3.14 bugs and security fixes labels Dec 1, 2025

StanFromIreland requested changes Dec 1, 2025
View reviewed changes

ZeroIntensity added 2 commits December 3, 2025 21:46

Merge branch 'main' ofhttps://github.com/python/cpythoninto c-api-d…
d1769ab
…ocs-check

Remove newly documented C APIs from ignored_c_api.txt
147d710

ZeroIntensity enabled auto-merge (squash) December 4, 2025 02:49

ZeroIntensity merged commit 1a7824a into python:mainDec 4, 2025
44 checks passed

bedevere-appBot removed the awaiting merge label Dec 4, 2025

miss-islington-appBot assigned ZeroIntensity Dec 4, 2025

bedevere-appBot removed the needs backport to 3.14 bugs and security fixes label Dec 4, 2025

bedevere-appBot removed the needs backport to 3.13 bugs and security fixes label Dec 4, 2025

StanFromIreland pushed a commit to StanFromIreland/cpython that referenced this pull request Dec 6, 2025
pythongh-141004: Add a CI job ensuring that new C APIs include docume…
dac341f
…ntation (pythonGH-142102) Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

ZeroIntensity mentioned this pull request Dec 7, 2025
Document PyCF_ALLOW_INCOMPLETE_INPUT#142372
Closed

sobolevn mentioned this pull request Dec 17, 2025
gh-142859: Add Tools/check-c-api-docs to mypy check #142860
Merged

encukou mentioned this pull request May 11, 2026
Undocumented 3.14 C API #135755
Closed
39 tasks

Uh oh!

Uh oh!

Conversation

ZeroIntensity commented Nov 30, 2025• edited by bedevere-app BotLoading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

StanFromIrelandNov 30, 2025

Choose a reason for hiding this comment

Uh oh!

ZeroIntensityNov 30, 2025

Choose a reason for hiding this comment

Uh oh!

StanFromIrelandNov 30, 2025

Choose a reason for hiding this comment

Uh oh!

ZeroIntensityDec 1, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

ZeroIntensity commented Dec 1, 2025

Uh oh!

hugovk commented Dec 1, 2025

Uh oh!

StanFromIreland left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ZeroIntensity commented Dec 1, 2025

Uh oh!

ZeroIntensity commented Dec 2, 2025

Uh oh!

ZeroIntensity commented Dec 4, 2025

Uh oh!

Uh oh!

miss-islington-appBot commented Dec 4, 2025

Uh oh!

miss-islington-appBot commented Dec 4, 2025

Uh oh!

miss-islington-appBot commented Dec 4, 2025

Uh oh!

bedevere-appBot commented Dec 4, 2025

Uh oh!

bedevere-appBot commented Dec 4, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ZeroIntensity commented Nov 30, 2025•
edited by bedevere-app Bot
Loading

StanFromIreland left a comment •
edited
Loading