Skip to content

GH-96803: Add three C-API functions to make _PyInterpreterFrame less opaque for users of PEP 523. #96849

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

Merged
markshannon merged 9 commits into from
May 5, 2023
Merged

GH-96803: Add three C-API functions to make _PyInterpreterFrame less opaque for users of PEP 523. #96849

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
ce23394
Add three C-API functions to make _PyInterpreterFrame more usable for…
markshannon Sep 15, 2022
6ff2f4d
Remove duplicate definition.
markshannon Sep 15, 2022
821de76
Update Misc/NEWS.d/next/C API/2022-09-15-15-21-34.gh-issue-96803.ynBK…
markshannon Sep 15, 2022
5aed2cb
Update Include/cpython/frameobject.h
markshannon Sep 15, 2022
fea57fb
Attempt to fix rst formatting.
markshannon Sep 15, 2022
a6a6662
Make new function part of unstable API.
markshannon May 4, 2023
19bc82e
Update news item
markshannon May 4, 2023
53ce02c
Merge branch 'main' into py-interpreter-frame-api
markshannon May 4, 2023
7fbece8
Fix merge.
markshannon May 4, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions Include/cpython/frameobject.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,3 +27,18 @@ PyAPI_FUNC(int) _PyFrame_IsEntryFrame(PyFrameObject *frame);

PyAPI_FUNC(int) PyFrame_FastToLocalsWithError(PyFrameObject *f);
PyAPI_FUNC(void) PyFrame_FastToLocals(PyFrameObject *);

/* The following functions are for use by debuggers and other tools
* implementing custom frame evaluators with PEP 523. */

/* Returns the code object of the frame.
Comment thread
markshannon marked this conversation as resolved.
Outdated
* Does not raise an exception. */
Copy link
Copy Markdown
Member

@vstinner vstinner Sep 15, 2022

Choose a reason for hiding this comment

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

Somewhere I saw the expression: "This function cannot fail" but I can no longer find it in the doc.

PyAPI_FUNC(PyCodeObject *) _PyInterpreterFrame_GetCode(struct _PyInterpreterFrame *frame);

/* Returns a byte ofsset into the last executed instruction.
Comment thread
markshannon marked this conversation as resolved.
* Does not raise an exception. */
PyAPI_FUNC(int) _PyInterpreterFrame_GetLasti(struct _PyInterpreterFrame *frame);

/* Returns the currently executing line number, or -1 if there is no line number.
* Does not raise an exception. */
PyAPI_FUNC(int) _PyInterpreterFrame_GetLine(struct _PyInterpreterFrame *frame);
Copy link
Copy Markdown
Member

@pablogsal pablogsal Sep 15, 2022

Choose a reason for hiding this comment

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

Using struct here is confusing the Windows compiler

Copy link
Copy Markdown
Member

@vstinner vstinner Sep 16, 2022

Choose a reason for hiding this comment

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

You can add struct _PyInterpreterFrame; somewhere to declare that "this structure exists" without having to declare the structure members (so it's declared as an opaque structure), to avoid such compiler warning. For example, at the top of this file.

9 changes: 9 additions & 0 deletions Misc/NEWS.d/next/C API/2022-09-15-15-21-34.gh-issue-96803.ynBKIS.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
Expose C-API functions to get the code object, lasti and line number from
Copy link
Copy Markdown
Member

@pablogsal pablogsal Sep 15, 2022

Choose a reason for hiding this comment

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

Not sure if this needs a news entry since the functions are exposed technically on a private header.

the internal ``_PyInterpreterFrame`` in the limited API. The functions are:
Comment thread
markshannon marked this conversation as resolved.

``PyCodeObject * _PyInterpreterFrame_GetCode(struct _PyInterpreterFrame
*frame);``

``int _PyInterpreterFrame_GetLasti(struct _PyInterpreterFrame *frame);``

``int _PyInterpreterFrame_GetLine(struct _PyInterpreterFrame *frame);``
Comment thread
markshannon marked this conversation as resolved.
Outdated
14 changes: 14 additions & 0 deletions Python/frame.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -118,6 +118,20 @@ _PyFrame_Clear(_PyInterpreterFrame *frame)
Py_DECREF(frame->f_code);
}

/* Limited API functions */
Copy link
Copy Markdown
Member

@vstinner vstinner Sep 15, 2022

Choose a reason for hiding this comment

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

These functions are excluded from the limited API, they are declared in cpython/.

Copy link
Copy Markdown
Member Author

@markshannon markshannon Sep 15, 2022

Choose a reason for hiding this comment

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

What is the part of the API that isn't portable called? "unlimited", "non-limited"?

Copy link
Copy Markdown
Member

@vstinner vstinner Sep 16, 2022

Choose a reason for hiding this comment

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

The Limited API is supposed to be the most portable. The "not portable" API is called the "Public API".

For me, the reference documentation about that is now: https://devguide.python.org/developer-workflow/c-api/index.html#changing-python-s-c-api

See also: Include/README.rst.


PyCodeObject *_PyInterpreterFrame_GetCode(struct _PyInterpreterFrame *frame)
{
PyCodeObject *code = frame->f_code;
Py_INCREF(code);
return code;
Comment thread
markshannon marked this conversation as resolved.
}

int _PyInterpreterFrame_GetLasti(struct _PyInterpreterFrame *frame)
{
return _PyInterpreterFrame_LASTI(frame) * sizeof(_Py_CODEUNIT);
}

int
_PyInterpreterFrame_GetLine(_PyInterpreterFrame *frame)
{
Expand Down