Skip to content

gh-135755: Docs: C API: Document missing PyFunction_GET* macros #135762

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 12 commits into from
Jun 25, 2025
Merged

gh-135755: Docs: C API: Document missing PyFunction_GET* macros #135762

merged 12 commits into from
Jun 25, 2025

Conversation

ZeroIntensity
Copy link
Member

@ZeroIntensity ZeroIntensity commented Jun 20, 2025 •
edited
Loading

I'm documenting all of these before getting to PyFunction_GET_BUILTINS, because this needs to be backported to 3.13. I'll document PyFunction_GET_BUILTINS in a follow-up that goes only to 3.14.

I've included versionadded directives for a few APIs that were added in 3.0 (PEP-3102 and PEP-3107), but I don't know if those are particularly useful these days. AFAIK, it's a controversial topic.

📚 Documentation preview 📚: https://cpython-previews--135762.org.readthedocs.build/en/135762/c-api/function.html#function-objects

@ZeroIntensity ZeroIntensity requested a review from encukou June 20, 2025 14:51
@ZeroIntensity ZeroIntensity added topic-C-API needs backport to 3.13 bugs and security fixes needs backport to 3.14 bugs and security fixes labels Jun 20, 2025
@bedevere-app bedevere-app bot mentioned this pull request Jun 20, 2025
Open
39 tasks
@ZeroIntensity ZeroIntensity added docs Documentation in the Doc dir skip news labels Jun 20, 2025
@github-project-automation github-project-automation bot moved this to Todo in Docs PRs Jun 20, 2025
brianschubert
brianschubert reviewed Jun 20, 2025
View reviewed changes
@ZeroIntensity @brianschubert
Apply suggestions from code review
184e7e2 
Co-authored-by: Brian Schubert <brianm.schubert@gmail.com>
picnixz
picnixz reviewed Jun 20, 2025
View reviewed changes
Copy link
Member

@picnixz picnixz left a comment

Choose a reason for hiding this comment

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

I'd appreciate if we have the "Return value: borrowed reference" for those functions (i.e., update refcounts.dat to add those entries).

@picnixz
Copy link
Member

picnixz commented Jun 20, 2025

Looks good now:

image

@encukou
Copy link
Member

encukou commented Jun 23, 2025 •
edited
Loading

Hm, that's a lot of repetition.
It might be easier for the reader -- and still semantically correct -- to put them all in a single block like this:

.. c:function:: PyObject *PyFunction_GET_CODE(PyObject *op)
                PyObject *PyFunction_GET_GLOBALS(PyObject *op)
                PyObject *PyFunction_GET_MODULE(PyObject *op)
                PyObject *PyFunction_GET_DEFAULTS(PyObject *op)
                PyObject *PyFunction_GET_KW_DEFAULTS(PyObject *op)
                PyObject *PyFunction_GET_CLOSURE(PyObject *op)
                PyObject *PyFunction_GET_ANNOTATIONS(PyObject *op)

   These macros are equivalent to the respective ``PyFunction_GetCode*``
   functions documented above, except they do no type checking.
   That is, if *op* is not of type :c:data:`PyFunction_Type`, the behavior
   is undefined.

We don't use versionadded:: for differences from 2.x; I don't think we should start now.
(What's controversial is whether we should remove versionadded:: 3.1 and such.)

@ZeroIntensity
Copy link
Member Author

Do we lose the reference count effect when we do that?

@encukou
Copy link
Member

encukou commented Jun 23, 2025

Visually, it's at the end of the block. Together with the “equivalent to the respective functions” bit, I think it's enough.

@ZeroIntensity
Copy link
Member Author

Ok, I've updated it. Let me know what you think of the wording I chose.

brianschubert
brianschubert reviewed Jun 23, 2025
View reviewed changes
@ZeroIntensity @brianschubert
Update function.rst
dfaa6ff 
Co-authored-by: Brian Schubert <brianm.schubert@gmail.com>
encukou
encukou reviewed Jun 24, 2025
View reviewed changes
encukou
encukou reviewed Jun 25, 2025
View reviewed changes
@encukou encukou enabled auto-merge (squash) June 25, 2025 08:39
encukou
encukou approved these changes Jun 25, 2025
View reviewed changes
Copy link
Member

@encukou encukou left a comment

Choose a reason for hiding this comment

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

Thank you!

@encukou encukou merged commit ca87a47 into python:main Jun 25, 2025
29 checks passed
@github-project-automation github-project-automation bot moved this from Todo to Done in Docs PRs Jun 25, 2025
@miss-islington-app
Copy link

Thanks @ZeroIntensity for the PR, and @encukou 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 Jun 25, 2025
@ZeroIntensity @brianschubert
@encukou @miss-islington
pythongh-135755: Docs: C API: Document missing PyFunction_GET* macr…
fa7a8e9 
…os (pythonGH-135762)

(cherry picked from commit ca87a47)

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
Co-authored-by: Brian Schubert <brianm.schubert@gmail.com>
Co-authored-by: Petr Viktorin <encukou@gmail.com>
@bedevere-app
Copy link

bedevere-app bot commented Jun 25, 2025

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

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Jun 25, 2025
@ZeroIntensity @brianschubert
@encukou @miss-islington
pythongh-135755: Docs: C API: Document missing PyFunction_GET* macr…
0a2ab8c 
…os (pythonGH-135762)

(cherry picked from commit ca87a47)

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
Co-authored-by: Brian Schubert <brianm.schubert@gmail.com>
Co-authored-by: Petr Viktorin <encukou@gmail.com>
@bedevere-app bedevere-app bot removed the needs backport to 3.14 bugs and security fixes label Jun 25, 2025
@bedevere-app
Copy link

bedevere-app bot commented Jun 25, 2025

GH-135917 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 Jun 25, 2025
encukou added a commit that referenced this pull request Jun 25, 2025
@miss-islington @ZeroIntensity
@brianschubert @encukou
[3.14] gh-135755: Docs: C API: Document missing PyFunction_GET* mac…
349f4c2 
…ros (GH-135762) (GH-135916)

gh-135755: Docs: C API: Document missing `PyFunction_GET*` macros (GH-135762)

(cherry picked from commit ca87a47)

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
Co-authored-by: Brian Schubert <brianm.schubert@gmail.com>
Co-authored-by: Petr Viktorin <encukou@gmail.com>
encukou added a commit that referenced this pull request Jun 25, 2025
@miss-islington @ZeroIntensity
@brianschubert @encukou
[3.13] gh-135755: Docs: C API: Document missing PyFunction_GET* mac…
c344aad 
…ros (GH-135762) (GH-135917)

(cherry picked from commit ca87a47)

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
Co-authored-by: Brian Schubert <brianm.schubert@gmail.com>
Co-authored-by: Petr Viktorin <encukou@gmail.com>
@ZeroIntensity ZeroIntensity deleted the document-function-macros branch June 25, 2025 11:31
AndPuQing pushed a commit to AndPuQing/cpython that referenced this pull request Jul 11, 2025
@ZeroIntensity @brianschubert
@encukou @AndPuQing
pythongh-135755: Docs: C API: Document missing PyFunction_GET* macr…
cd18690 
…os (pythonGH-135762)

Co-authored-by: Brian Schubert <brianm.schubert@gmail.com>
Co-authored-by: Petr Viktorin <encukou@gmail.com>
Pranjal095 pushed a commit to Pranjal095/cpython that referenced this pull request Jul 12, 2025
@ZeroIntensity @brianschubert
@encukou @Pranjal095
pythongh-135755: Docs: C API: Document missing PyFunction_GET* macr…
87af0ec 
…os (pythonGH-135762)

Co-authored-by: Brian Schubert <brianm.schubert@gmail.com>
Co-authored-by: Petr Viktorin <encukou@gmail.com>
taegyunkim pushed a commit to taegyunkim/cpython that referenced this pull request Aug 4, 2025
@ZeroIntensity @brianschubert
@encukou @taegyunkim
pythongh-135755: Docs: C API: Document missing PyFunction_GET* macr…
d2c6bf5 
…os (pythonGH-135762)

Co-authored-by: Brian Schubert <brianm.schubert@gmail.com>
Co-authored-by: Petr Viktorin <encukou@gmail.com>
Agent-Hellboy pushed a commit to Agent-Hellboy/cpython that referenced this pull request Aug 19, 2025
@ZeroIntensity @brianschubert
@encukou @Agent-Hellboy
pythongh-135755: Docs: C API: Document missing PyFunction_GET* macr…
57ea284 
…os (pythonGH-135762)

Co-authored-by: Brian Schubert <brianm.schubert@gmail.com>
Co-authored-by: Petr Viktorin <encukou@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@picnixz picnixz picnixz left review comments

@brianschubert brianschubert brianschubert left review comments

@encukou encukou encukou approved these changes

+1 more reviewer

@blockchainGuru1018 blockchainGuru1018 blockchainGuru1018 approved these changes

Reviewers whose approvals may not affect merge requirements
Assignees
No one assigned
Labels
docs Documentation in the Doc dir skip news topic-C-API
Projects
Docs PRs
Status: Done
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
5 participants
@ZeroIntensity @picnixz @encukou @brianschubert @blockchainGuru1018