GV

GeezerVison

The World Wide Web, restored to 800 pixels of glory.

Home|About|Gaming cabinet|Archives|How it works|Starter sites

On this site

  • Sign in
  • ActionsCI/CD and automation
  • CodespacesCloud development environments
  • All Features
  • Documentation
  • Training
  • Certifications
  • Build with Copilot
  • Customize Copilot
  • Integrations
  • Trending repos
  • GitHub Sponsors
  • Developer articles
  • Enterprises

This view

  • Original page
  • New address

GeezerVison is showing github.com — gh-141004: Add a CI job ensuring that new C APIs include documentation by ZeroIntensity · Pull Request #142102 · python/cpython

Conversation

@ZeroIntensity

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

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Member

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
ZeroIntensity added 6 commits November 29, 2025 15:04
@ZeroIntensity
Add a tool for finding undocumented C API
77d1750
@ZeroIntensity
Add a CI job.
e219136
@ZeroIntensity
General improvements.
8c88402
@ZeroIntensity
Add myself as a codeowner.
0f687cf
@ZeroIntensity
Run black.
ec03845
@ZeroIntensity
Eliminate some duplication.
2510476
@ZeroIntensity
ZeroIntensity requested review from AA-Turner, emmatyping, erlend-aasland, ezio-melotti and hugovk as code owners November 30, 2025 00:34
@bedevere-app bedevere-app Bot added the awaiting core review label Nov 30, 2025
@bedevere-app bedevere-app Bot mentioned this pull request Nov 30, 2025
Document the entire C API #141004
Closed
@ZeroIntensity ZeroIntensity added the skip news label Nov 30, 2025
hugovk
hugovk reviewed Nov 30, 2025
View reviewed changes
Comment thread .github/CODEOWNERS Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread .github/workflows/build.yml Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Makefile.pre.in Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Tools/check-c-api-docs/main.py Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Tools/check-c-api-docs/main.py Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Tools/check-c-api-docs/main.py Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Tools/check-c-api-docs/main.py Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Tools/check-c-api-docs/main.py Resolved

Uh oh!

There was an error while loading. Please reload this page.
StanFromIreland
StanFromIreland reviewed Nov 30, 2025
View reviewed changes
Comment thread Tools/check-c-api-docs/main.py
IGNORED.pop(index)


def is_documented(name: str) -> bool:

@StanFromIreland StanFromIreland Nov 30, 2025

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions

@ZeroIntensity ZeroIntensity Nov 30, 2025

Copy link
Copy Markdown
Member Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

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.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions

@StanFromIreland StanFromIreland Nov 30, 2025

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions

@ZeroIntensity ZeroIntensity Dec 1, 2025

Copy link
Copy Markdown
Member Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

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.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
ZeroIntensity and others added 4 commits November 30, 2025 11:15
@ZeroIntensity @hugovk
Apply suggestions from code review
51b2747 
Co-authored-by: Hugo van Kemenade <[email protected]>
@ZeroIntensity
Fix alphabetical order.
cb9a68d
@ZeroIntensity
Change plurality in the message depending on the size of the list.
681962d
@ZeroIntensity
Fix indentation on the output.
1d0c8f6
hugovk
hugovk approved these changes Nov 30, 2025
View reviewed changes
Comment thread Tools/check-c-api-docs/main.py Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread .github/workflows/build.yml Resolved

Uh oh!

There was an error while loading. Please reload this page.
@bedevere-app 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
@ZeroIntensity @hugovk
Update .github/workflows/build.yml
f487d6e 
Co-authored-by: Hugo van Kemenade <[email protected]>
@ZeroIntensity @hugovk
Update Tools/check-c-api-docs/main.py
02d2f07 
Co-authored-by: Hugo van Kemenade <[email protected]>
@ZeroIntensity ZeroIntensity added needs backport to 3.13 only security fixes needs backport to 3.14 bugs and security fixes labels Dec 1, 2025
@ZeroIntensity

ZeroIntensity commented Dec 1, 2025

Copy link
Copy Markdown
Member Author

I plan on backporting this to prevent conflicts when things are removed from ignored_c_api.txt. Any objections?
hugovk reacted with thumbs up emoji
All reactions
  • 👍 1 reaction

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@hugovk

hugovk commented Dec 1, 2025

Copy link
Copy Markdown
Member

No objection to backporting.
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
StanFromIreland
StanFromIreland requested changes Dec 1, 2025
View reviewed changes

@StanFromIreland StanFromIreland left a comment •
edited
Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
@ZeroIntensity

ZeroIntensity commented Dec 1, 2025

Copy link
Copy Markdown
Member Author

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?
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@ZeroIntensity

ZeroIntensity commented Dec 2, 2025

Copy link
Copy Markdown
Member Author

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.
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
ZeroIntensity added 2 commits December 3, 2025 21:46
@ZeroIntensity
Merge branch 'main' of https://github.com/python/cpython into c-api-d…
d1769ab 
…ocs-check
@ZeroIntensity
Remove newly documented C APIs from ignored_c_api.txt
147d710
@ZeroIntensity

ZeroIntensity commented Dec 4, 2025

Copy link
Copy Markdown
Member Author

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@ZeroIntensity
ZeroIntensity enabled auto-merge (squash) December 4, 2025 02:49
@ZeroIntensity
ZeroIntensity merged commit 1a7824a into python:main Dec 4, 2025
44 checks passed

Uh oh!

There was an error while loading. Please reload this page.
@miss-islington-app

miss-islington-app Bot commented Dec 4, 2025

Copy link
Copy Markdown

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@bedevere-app bedevere-app Bot removed the awaiting merge label Dec 4, 2025
@miss-islington-app

miss-islington-app Bot commented Dec 4, 2025

Copy link
Copy Markdown

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@miss-islington-app miss-islington-app Bot assigned ZeroIntensity Dec 4, 2025
@miss-islington-app

miss-islington-app Bot commented Dec 4, 2025

Copy link
Copy Markdown

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@bedevere-app

bedevere-app Bot commented Dec 4, 2025

Copy link
Copy Markdown

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@bedevere-app bedevere-app Bot removed the needs backport to 3.14 bugs and security fixes label Dec 4, 2025
ZeroIntensity added a commit to ZeroIntensity/cpython that referenced this pull request Dec 4, 2025
@ZeroIntensity @hugovk
pythongh-141004: Add a CI job ensuring that new C APIs include docume…
be706b1 
…ntation (pythonGH-142102)

Co-authored-by: Hugo van Kemenade <[email protected]>
(cherry picked from commit 1a7824a)
ZeroIntensity added a commit to ZeroIntensity/cpython that referenced this pull request Dec 4, 2025
@ZeroIntensity @hugovk
[3.14] pythongh-141004: Add a CI job ensuring that new C APIs include…
82878b8 
… documentation (pythonGH-142102)

(cherry picked from commit 1a7824a)

Co-authored-by: Peter Bierma <[email protected]>
Co-authored-by: Hugo van Kemenade <[email protected]>
@bedevere-app

bedevere-app Bot commented Dec 4, 2025

Copy link
Copy Markdown

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@bedevere-app bedevere-app Bot removed the needs backport to 3.13 only security fixes label Dec 4, 2025
ZeroIntensity added a commit to ZeroIntensity/cpython that referenced this pull request Dec 4, 2025
@ZeroIntensity @hugovk
pythongh-141004: Add a CI job ensuring that new C APIs include docume…
aa0d658 
…ntation (pythonGH-142102)

Co-authored-by: Hugo van Kemenade <[email protected]>
(cherry picked from commit 1a7824a)
ZeroIntensity added a commit to ZeroIntensity/cpython that referenced this pull request Dec 4, 2025
@ZeroIntensity @hugovk
[3.13] pythongh-141004: Add a CI job ensuring that new C APIs include…
9345940 
… documentation (pythonGH-142102)

(cherry picked from commit 1a7824a)

Co-authored-by: Peter Bierma <[email protected]>
Co-authored-by: Hugo van Kemenade <[email protected]>
ZeroIntensity added a commit that referenced this pull request Dec 4, 2025
@ZeroIntensity @hugovk
[3.14] gh-141004: Add a CI job ensuring that new C APIs include docum…
d069edc 
…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 <[email protected]>
(cherry picked from commit 1a7824a)

---------

Co-authored-by: Hugo van Kemenade <[email protected]>
StanFromIreland pushed a commit to StanFromIreland/cpython that referenced this pull request Dec 6, 2025
@ZeroIntensity @hugovk @StanFromIreland
pythongh-141004: Add a CI job ensuring that new C APIs include docume…
dac341f 
…ntation (pythonGH-142102)

Co-authored-by: Hugo van Kemenade <[email protected]>
@ZeroIntensity ZeroIntensity mentioned this pull request Dec 7, 2025
Document PyCF_ALLOW_INCOMPLETE_INPUT #142372
Closed
ZeroIntensity added a commit that referenced this pull request Dec 15, 2025
@ZeroIntensity @hugovk
[3.13] gh-141004: Add a CI job ensuring that new C APIs include docum…
5569ffe 
…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 <[email protected]>
(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 <[email protected]>
Co-authored-by: Hugo van Kemenade <[email protected]>

* Update Tools/check-c-api-docs/ignored_c_api.txt

---------

Co-authored-by: Hugo van Kemenade <[email protected]>
@sobolevn sobolevn mentioned this pull request Dec 17, 2025
gh-142859: Add Tools/check-c-api-docs to mypy check #142860
Merged
@encukou encukou mentioned this pull request May 11, 2026
Undocumented 3.14 C API #135755
Closed
39 tasks done
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@StanFromIreland StanFromIreland StanFromIreland requested changes
@hugovk hugovk hugovk approved these changes
@erlend-aasland erlend-aasland Awaiting requested review from erlend-aasland erlend-aasland is a code owner
@AA-Turner AA-Turner Awaiting requested review from AA-Turner AA-Turner is a code owner
@emmatyping emmatyping Awaiting requested review from emmatyping emmatyping is a code owner
@ezio-melotti ezio-melotti Awaiting requested review from ezio-melotti ezio-melotti is a code owner

Uh oh!

There was an error while loading. Please reload this page.

Assignees

@ZeroIntensity ZeroIntensity

Labels

skip news

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Uh oh!

There was an error while loading. Please reload this page.

3 participants

@ZeroIntensity @hugovk @StanFromIreland
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.