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

.github/CODEOWNERS

.github/workflows/build.yml

Makefile.pre.in

Tools/check-c-api-docs/main.py

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

Tools/check-c-api-docs/main.py

+        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>

Tools/check-c-api-docs/main.py

.github/workflows/build.yml

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

Tools/check-c-api-docs/main.py Outdated Show resolved Hide resolved

.github/workflows/build.yml Outdated Show resolved Hide resolved

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

Open

sobolevn mentioned this pull request Dec 17, 2025

gh-142859: Add Tools/check-c-api-docs to mypy check #142860

Merged

Uh oh!

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

Comments

ZeroIntensity commented Nov 30, 2025 •

edited by bedevere-app bot

Loading

StanFromIreland left a comment •

edited

Loading