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

ZeroIntensity · 2025-06-20T14:51:33Z

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

Issue: Undocumented 3.14 C API #135755

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

Doc/c-api/function.rst

Co-authored-by: Brian Schubert <brianm.schubert@gmail.com>

picnixz

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

…ensity/cpython into document-function-macros

picnixz · 2025-06-20T16:08:18Z

Looks good now:

encukou · 2025-06-23T11:24:19Z

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 · 2025-06-23T11:50:29Z

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

encukou · 2025-06-23T14:51:54Z

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

ZeroIntensity · 2025-06-23T18:50:56Z

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

Doc/c-api/function.rst

Co-authored-by: Brian Schubert <brianm.schubert@gmail.com>

Doc/c-api/function.rst

encukou

Thank you!

miss-islington-app · 2025-06-25T08:44:59Z

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

…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 · 2025-06-25T08:45:08Z

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

…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 · 2025-06-25T08:45:13Z

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

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

…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 added 5 commits June 20, 2025 10:35

Add documentation for missing PyFunction_GET* macros

9240c44

Mark PyFunction_GetKwDefaults as returning a borrowed reference.

2e0b172

Add versionadded and fix description.

0c254cf

Add missing versionadded directive.

b0176a7

Remove stray newline change.

6969427

ZeroIntensity requested a review from encukou June 20, 2025 14:51

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 bot added the awaiting core review label Jun 20, 2025

bedevere-app bot mentioned this pull request Jun 20, 2025

Undocumented 3.14 C API #135755

Open

38 tasks

ZeroIntensity added docs Documentation in the Doc dir skip news labels Jun 20, 2025

github-project-automation bot added this to Docs PRs Jun 20, 2025

github-project-automation bot moved this to Todo in Docs PRs Jun 20, 2025

brianschubert reviewed Jun 20, 2025

View reviewed changes

Apply suggestions from code review

184e7e2

Co-authored-by: Brian Schubert <brianm.schubert@gmail.com>

picnixz reviewed Jun 20, 2025

View reviewed changes

ZeroIntensity added 2 commits June 20, 2025 12:03

Document the reference count effect of the macros.

6bd56af

Merge branch 'document-function-macros' of https://github.com/ZeroInt…

856a441

…ensity/cpython into document-function-macros

blockchainGuru1018 approved these changes Jun 20, 2025

View reviewed changes

Flatten things down.

5dd0973

brianschubert reviewed Jun 23, 2025

View reviewed changes

Doc/c-api/function.rst Outdated Show resolved Hide resolved

Update function.rst

dfaa6ff

Co-authored-by: Brian Schubert <brianm.schubert@gmail.com>

encukou reviewed Jun 24, 2025

View reviewed changes

Doc/c-api/function.rst Outdated Show resolved Hide resolved

Fix English.

9ce8dbc

encukou reviewed Jun 25, 2025

View reviewed changes

Doc/c-api/function.rst Outdated Show resolved Hide resolved

Doc/c-api/function.rst Outdated Show resolved Hide resolved

Remove more versionadded:: 3.0

bb685cd

encukou enabled auto-merge (squash) June 25, 2025 08:39

encukou approved these changes Jun 25, 2025

View reviewed changes

bedevere-app bot added awaiting merge and removed awaiting core review labels Jun 25, 2025

encukou merged commit ca87a47 into python:main Jun 25, 2025
29 checks passed

github-project-automation bot moved this from Todo to Done in Docs PRs Jun 25, 2025

bedevere-app bot removed the awaiting merge label Jun 25, 2025

bedevere-app bot removed the needs backport to 3.14 bugs and security fixes label Jun 25, 2025

bedevere-app bot removed the needs backport to 3.13 bugs and security fixes label Jun 25, 2025

ZeroIntensity deleted the document-function-macros branch June 25, 2025 11:31

Uh oh!

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

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

Uh oh!

Conversation

ZeroIntensity commented Jun 20, 2025 • edited 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!

picnixz left a comment

Choose a reason for hiding this comment

Uh oh!

picnixz commented Jun 20, 2025

Uh oh!

encukou commented Jun 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ZeroIntensity commented Jun 23, 2025

Uh oh!

encukou commented Jun 23, 2025

Uh oh!

ZeroIntensity commented Jun 23, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

encukou left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

miss-islington-app bot commented Jun 25, 2025

Uh oh!

bedevere-app bot commented Jun 25, 2025

Uh oh!

bedevere-app bot commented Jun 25, 2025

Uh oh!

Uh oh!

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

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

ZeroIntensity commented Jun 20, 2025 •

edited

Loading

encukou commented Jun 23, 2025 •

edited

Loading