gh-115653: Add docs for the PyCode_GetFirstFree and correct return type for the PyCode_GetNumFree #115654

wrongnull · 2024-02-19T13:34:47Z

Issue: Missing documentation for public C-API function #115653

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

Doc/c-api/code.rst

wrongnull · 2024-02-20T09:31:29Z

BTW, should PyCode_GetFirstFree cast the return value to Py_ssize_t? As I can see this function is used mostly for calculating offsets.

erlend-aasland · 2024-02-20T21:42:58Z

Doc/c-api/code.rst


   Return the number of free variables in *co*.

+.. c:function:: int PyCode_GetFirstFree(PyCodeObject *co)
+
+   Return the number of local + cell variables in *co*.


Document what the API does, not its implementation details: PyCode_GetFirstFree returns the position (or offset) of the first free variable in co.

FTR: @markshannon and @iritkatriel introduced this API in gh-100721. It is available via Python.h.

Done. But my question above still stands. If I'm right I might make a separate pull request for this.

See the PR I linked to, especially #100721 (comment) and 49ca044.

Thank you. If there is anything else here that I could fix, I'll be happy to do it.

I would still like to hear from either @markshannon or @iritkatriel; I'm not sure this was intended as a public API.

It was and it wasn't. We don't really want to expose it, but if we don't then Cython and other C extensions will access the internal fields directly, which is worse.

Now that we have an unstable API, it should probably be part of that.
I'd like all code object C APIs to be unstable, but it's probably too late for that.

Maybe rename it to PyUnstableCode_GetFirstFree?

Maybe rename it to PyUnstableCode_GetFirstFree?

Sounds like a good idea, but since it is already included in 3.12, we have to deprecate PyCode_GetFirstFree and PyUnstableCode_GetFirstFree in 3.13.

Follow-up issue: #115756.

erlend-aasland · 2024-02-21T07:41:59Z

In general, please split up multiple changes in atomic PRs; the distinct changes might not have equal backport requirements. For these two changes it looks to me both of them are applicable for a 3.12 backport only, so you're fine.

vstinner · 2024-02-21T08:43:22Z

Doc/c-api/code.rst

@@ -30,10 +30,14 @@ bound into a function.
   Return true if *co* is a :ref:`code object <code-objects>`.
   This function always succeeds.

-.. c:function:: int PyCode_GetNumFree(PyCodeObject *co)
+.. c:function:: Py_ssize_t PyCode_GetNumFree(PyCodeObject *co)

   Return the number of free variables in *co*.


Suggested change

Return the number of free variables in *co*.

Return the number of free variables in a code object.

vstinner · 2024-02-21T08:43:38Z

Doc/c-api/code.rst


   Return the number of free variables in *co*.

+.. c:function:: int PyCode_GetFirstFree(PyCodeObject *co)
+
+   Return the position of first free variable in *co*.


Suggested change

Return the position of first free variable in *co*.

Return the position of the first free variable in a code object.

vstinner

LGTM.

miss-islington-app · 2024-02-21T09:01:40Z

Thanks @wrongnull for the PR, and @vstinner for merging it 🌮🎉.. I'm working now to backport this PR to: 3.12.
🐍🍒⛏🤖

Correct the return type of the PyCode_GetNumFree() documentation. (cherry picked from commit 10fc467) Co-authored-by: Bogdan Romanyuk <[email protected]>

bedevere-app · 2024-02-21T09:01:52Z

GH-115752 is a backport of this pull request to the 3.12 branch.

erlend-aasland · 2024-02-21T09:01:08Z

Doc/c-api/code.rst


-   Return the number of free variables in *co*.
+   Return the number of free variables in a code object.


@vstinner, I think this is the suggested style:

Suggested change

Return the number of free variables in a code object.

Return the number of free variables in code object *co*.

Ah, I just merged the change. Is it worth it to change the style, or is it ok to merge PR gh-115752 backport? I let you decide :-)

No, it's not worth it to change the style, but I think we should try to keep it in mind for next time ;)

Doc/c-api/code.rst

gh-115653: Document PyCode_GetFirstFree() (GH-115654) Correct the return type of the PyCode_GetNumFree() documentation. (cherry picked from commit 10fc467) Co-authored-by: Bogdan Romanyuk <[email protected]>

Correct the return type of the PyCode_GetNumFree() documentation.

Add docs for public c-api function

8559119

bedevere-app bot added awaiting review docs Documentation in the Doc dir skip news labels Feb 19, 2024

bedevere-app bot mentioned this pull request Feb 19, 2024

Missing documentation for public C-API function #115653

Closed

add missed period

56f4c39

wrongnull changed the title ~~gh-115653: Add docs for the PyCode_GetFirstFree and correct return type for the PyCode_GetFirstFree~~ gh-115653: Add docs for the PyCode_GetFirstFree and correct return type for the PyCode_GetNumFree Feb 19, 2024

Eclips4 added the needs backport to 3.12 only security fixes label Feb 19, 2024

Eclips4 reviewed Feb 19, 2024

View reviewed changes

Doc/c-api/code.rst Show resolved Hide resolved

Eclips4 requested a review from vstinner February 20, 2024 08:14

erlend-aasland reviewed Feb 20, 2024

View reviewed changes

Change the wording of the function documentation

6619bb9

vstinner reviewed Feb 21, 2024

View reviewed changes

Eleminate abbreviation and add article

2af8bee

vstinner approved these changes Feb 21, 2024

View reviewed changes

bedevere-app bot added awaiting merge and removed awaiting review labels Feb 21, 2024

vstinner merged commit 10fc467 into python:main Feb 21, 2024

bedevere-app bot removed the awaiting merge label Feb 21, 2024

bedevere-app bot removed the needs backport to 3.12 only security fixes label Feb 21, 2024

erlend-aasland reviewed Feb 21, 2024

View reviewed changes

erlend-aasland mentioned this pull request Feb 21, 2024

Make PyCode_GetFirstFree a PEP-689 unstable API #115756

Closed

wrongnull deleted the patch-3 branch February 21, 2024 10:30

wrongnull mentioned this pull request Feb 21, 2024

gh-115756: make PyCode_GetFirstFree an unstable API #115781

Merged

woodruffw pushed a commit to woodruffw-forks/cpython that referenced this pull request Mar 4, 2024

pythongh-115653: Document PyCode_GetFirstFree() (python#115654)

0ff9c05

Correct the return type of the PyCode_GetNumFree() documentation.

encukou mentioned this pull request Mar 8, 2024

Make PyCode_GetFirstFree unstable capi-workgroup/decisions#18

Closed

5 tasks

diegorusso pushed a commit to diegorusso/cpython that referenced this pull request Apr 17, 2024

pythongh-115653: Document PyCode_GetFirstFree() (python#115654)

3df8eac

Correct the return type of the PyCode_GetNumFree() documentation.

LukasWoodtli pushed a commit to LukasWoodtli/cpython that referenced this pull request Jan 22, 2025

pythongh-115653: Document PyCode_GetFirstFree() (python#115654)

aeced76

Correct the return type of the PyCode_GetNumFree() documentation.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

gh-115653: Add docs for the PyCode_GetFirstFree and correct return type for the PyCode_GetNumFree #115654

gh-115653: Add docs for the PyCode_GetFirstFree and correct return type for the PyCode_GetNumFree #115654

wrongnull commented Feb 19, 2024 •

edited by github-actions bot

Loading

wrongnull commented Feb 20, 2024 •

edited

Loading

erlend-aasland Feb 20, 2024

wrongnull Feb 20, 2024

erlend-aasland Feb 20, 2024

wrongnull Feb 20, 2024

erlend-aasland Feb 21, 2024

markshannon Feb 21, 2024 •

edited

Loading

erlend-aasland Feb 21, 2024

erlend-aasland Feb 21, 2024

erlend-aasland commented Feb 21, 2024

vstinner Feb 21, 2024

vstinner Feb 21, 2024

wrongnull Feb 21, 2024

vstinner left a comment

miss-islington-app bot commented Feb 21, 2024

bedevere-app bot commented Feb 21, 2024

erlend-aasland Feb 21, 2024

vstinner Feb 21, 2024

erlend-aasland Feb 21, 2024

	Return the number of free variables in co.
	Return the number of free variables in a code object.

	Return the position of first free variable in co.
	Return the position of the first free variable in a code object.

	Return the number of free variables in a code object.
	Return the number of free variables in code object co.

gh-115653: Add docs for the PyCode_GetFirstFree and correct return type for the PyCode_GetNumFree #115654

gh-115653: Add docs for the PyCode_GetFirstFree and correct return type for the PyCode_GetNumFree #115654

Conversation

wrongnull commented Feb 19, 2024 • edited by github-actions bot Loading

wrongnull commented Feb 20, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

markshannon Feb 21, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

erlend-aasland commented Feb 21, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vstinner left a comment

Choose a reason for hiding this comment

miss-islington-app bot commented Feb 21, 2024

bedevere-app bot commented Feb 21, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wrongnull commented Feb 19, 2024 •

edited by github-actions bot

Loading

wrongnull commented Feb 20, 2024 •

edited

Loading

markshannon Feb 21, 2024 •

edited

Loading