Skip to content

gh-136823: Update documentation on excluded headers in Python.h #136824

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 7 commits into from
Aug 5, 2025
Merged

gh-136823: Update documentation on excluded headers in Python.h #136824

merged 7 commits into from
Aug 5, 2025

Conversation

SZeltaat
Copy link
Contributor

@SZeltaat SZeltaat commented Jul 19, 2025 •
edited by github-actions bot
Loading

This part of the documentation from https://docs.python.org/3/extending/extending.html#a-simple-example is currently outdated:

All user-visible symbols defined by Python.h have a prefix of Py or PY, except those defined in standard header files. For convenience, and since they are used extensively by the Python interpreter, "Python.h" includes a few standard header files: <stdio.h>, <string.h>, <errno.h>, and <stdlib.h>. If the latter header file does not exist on your system, it declares the functions malloc(), free() and realloc() directly.

This PR aligns the documentation with the code and the comments provided by the original author that implemented the changes.

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

@bedevere-app bedevere-app bot added awaiting review docs Documentation in the Doc dir skip news labels Jul 19, 2025
@bedevere-app bedevere-app bot mentioned this pull request Jul 19, 2025
Open
@github-project-automation github-project-automation bot moved this to Todo in Docs PRs Jul 19, 2025
@SZeltaat
Copy link
Contributor Author

Hi @AA-Turner, could you please take a look at this PR?
#EuroPython2025

StanFromIreland
StanFromIreland reviewed Jul 19, 2025
View reviewed changes
ilovelinux
ilovelinux reviewed Jul 19, 2025
View reviewed changes
@AA-Turner AA-Turner added sprint needs backport to 3.13 bugs and security fixes needs backport to 3.14 bugs and security fixes labels Jul 19, 2025
skirpichev
skirpichev reviewed Jul 19, 2025
View reviewed changes
@SZeltaat SZeltaat requested a review from ilovelinux July 22, 2025 11:28
@SZeltaat
Copy link
Contributor Author

SZeltaat commented Aug 4, 2025

Hi @AA-Turner, I think this PR is now ready to be merged. Would you be so kind to review this once more and if all well, merge it? Thank you so much!

StanFromIreland
StanFromIreland reviewed Aug 4, 2025
View reviewed changes
@SZeltaat @StanFromIreland
Update Doc/extending/extending.rst
cefc8f9 
simplify the sentence and supress link

Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
vstinner
vstinner approved these changes Aug 5, 2025
View reviewed changes
Copy link
Member

@vstinner vstinner left a comment

Choose a reason for hiding this comment

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

LGTM.

@encukou: Do you want to review this change?

@encukou
Copy link
Member

encukou commented Aug 5, 2025

The list should also include:

  • <assert.h>, <inttypes.h>, <limits.h>, <math.h>, <stdarg.h>, <wchar.h>
  • <sys/types.h>, <intrin.h> on platforms that have them

Could you also add a comment to the <Python.h> reminding contributors to update the docs when the included headers change.

ilovelinux
ilovelinux approved these changes Aug 5, 2025
View reviewed changes
@SZeltaat
Copy link
Contributor Author

SZeltaat commented Aug 5, 2025

@encukou
Thank you for your review!
I will add a comment to the <Python.h> reminding contributors to update the docs when the included headers change.

But regarding other headers, I think the point of this part of the documentation is that C extensions should only include <Python.h>, and not the other Python header files that are already included by <Python.h>. Would it be enough if I add this to the documentation instead of listing the other included headers?

This way, the documentation communicates clearly what should be done and why. The risk of naming all the included headers is that the documentation can get out of sync with the implementation (even with the reminder).

AA-Turner
AA-Turner reviewed Aug 5, 2025
View reviewed changes
@AA-Turner AA-Turner enabled auto-merge (squash) August 5, 2025 20:28
@AA-Turner AA-Turner merged commit c2428ca into python:main Aug 5, 2025
41 checks passed
@github-project-automation github-project-automation bot moved this from Todo to Done in Docs PRs Aug 5, 2025
@miss-islington-app
Copy link

Thanks @SZeltaat for the PR, and @AA-Turner for merging it 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14.
🐍🍒⛏🤖

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Aug 5, 2025
@SZeltaat @AA-Turner @miss-islington
pythongh-136823: Update documentation on excluded headers in Python.h (…
f8ea441 
…pythonGH-136824)

(cherry picked from commit c2428ca)

Co-authored-by: Sina Zel taat <111974143+SZeltaat@users.noreply.github.com>
Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com>
miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Aug 5, 2025
@SZeltaat @AA-Turner @miss-islington
pythongh-136823: Update documentation on excluded headers in Python.h (…
f552f4a 
…pythonGH-136824)

(cherry picked from commit c2428ca)

Co-authored-by: Sina Zel taat <111974143+SZeltaat@users.noreply.github.com>
Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com>
@bedevere-app
Copy link

bedevere-app bot commented Aug 5, 2025

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

@bedevere-app bedevere-app bot removed the needs backport to 3.14 bugs and security fixes label Aug 5, 2025
@bedevere-app
Copy link

bedevere-app bot commented Aug 5, 2025

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

@bedevere-app bedevere-app bot removed the needs backport to 3.13 bugs and security fixes label Aug 5, 2025
@AA-Turner
Copy link
Member

Thank you @SZeltaat!

A

AA-Turner added a commit that referenced this pull request Aug 5, 2025
@miss-islington @SZeltaat @AA-Turner
[3.13] gh-136823: Update documentation on excluded headers in Python.h (
1bb2ae5 
GH-136824) (#137438)

Co-authored-by: Sina Zel taat <111974143+SZeltaat@users.noreply.github.com>
Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@vstinner vstinner vstinner approved these changes

@skirpichev skirpichev skirpichev left review comments

@StanFromIreland StanFromIreland StanFromIreland left review comments

@AA-Turner AA-Turner AA-Turner approved these changes

@ilovelinux ilovelinux ilovelinux approved these changes

Assignees
No one assigned
Labels
docs Documentation in the Doc dir skip news sprint
Projects
Docs PRs
Status: Done
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
7 participants
@SZeltaat @encukou @AA-Turner @vstinner @skirpichev @ilovelinux @StanFromIreland