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

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

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>

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

No objection to backporting.

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

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?

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

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

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

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

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

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>

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-app Bot added the awaiting core review label Nov 30, 2025

bedevere-app Bot 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

ZeroIntensity and 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 thread Tools/check-c-api-docs/main.py Outdated

Comment thread .github/workflows/build.yml Outdated

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

ZeroIntensity and 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' of https://github.com/python/cpython into 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:main Dec 4, 2025
44 checks passed

bedevere-app Bot removed the awaiting merge label Dec 4, 2025

miss-islington-app Bot assigned ZeroIntensity Dec 4, 2025

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

bedevere-app Bot 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

		IGNORED.pop(index)


		def is_documented(name: str) -> bool:

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

Uh oh!

Uh oh!

gh-141004: Add a CI job ensuring that new C APIs include documentation - #142102

gh-141004: Add a CI job ensuring that new C APIs include documentation#142102ZeroIntensity merged 14 commits intopython:mainpython/cpython:mainfrom ZeroIntensity:c-api-docs-checkZeroIntensity/cpython:c-api-docs-checkCopy head branch name to clipboard

Conversation

ZeroIntensity commented Nov 30, 2025 • edited by bedevere-app Bot Loading 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!

StanFromIreland Nov 30, 2025

Choose a reason for hiding this comment

Uh oh!

ZeroIntensity Nov 30, 2025

Choose a reason for hiding this comment

Uh oh!

StanFromIreland Nov 30, 2025

Choose a reason for hiding this comment

Uh oh!

ZeroIntensity Dec 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-app Bot commented Dec 4, 2025

Uh oh!

miss-islington-app Bot commented Dec 4, 2025

Uh oh!

miss-islington-app Bot commented Dec 4, 2025

Uh oh!

bedevere-app Bot commented Dec 4, 2025

Uh oh!

bedevere-app Bot commented Dec 4, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

gh-141004: Add a CI job ensuring that new C APIs include documentation#142102
ZeroIntensity merged 14 commits into
python:mainfrom
ZeroIntensity:c-api-docs-check

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

StanFromIreland left a comment •
edited
Loading