gh-141518: Add PyUnstable_InterpreterFrame_GetFrameObject() function

Doc/c-api/frame.rst

@@ -223,30 +223,44 @@ Internal Frames
 
 Unless using :pep:`523`, you will not need this.
 
-.. c:struct:: _PyInterpreterFrame
+.. c:struct:: PyUnstable_InterpreterFrame
 
    The interpreter's internal frame representation.
 
+   The structure is intentionally opaque, and there are currently no plans to
+   stabilize it. Debuggers and profilers can use the internal C API to access
+   the structure members.
+
    .. versionadded:: 3.11
+   .. versionchanged:: next
+      Renamed to ``PyUnstable_InterpreterFrame``.
 
-.. c:function:: PyObject* PyUnstable_InterpreterFrame_GetCode(struct _PyInterpreterFrame *frame);
+.. c:function:: PyObject* PyUnstable_InterpreterFrame_GetCode(PyUnstable_InterpreterFrame *frame);
 
     Return a :term:`strong reference` to the code object for the frame.
 
    .. versionadded:: 3.12
 
 
-.. c:function:: int PyUnstable_InterpreterFrame_GetLasti(struct _PyInterpreterFrame *frame);
+.. c:function:: PyFrameObject* PyUnstable_InterpreterFrame_GetFrameObject(PyUnstable_InterpreterFrame *frame)
+
+   Get a frame object from an interpreter frame.
+
+   Return a new :term:`strong reference` on success, or set an exception and
+   return ``NULL`` on error.
+
+   .. versionadded:: next
+
+
+.. c:function:: int PyUnstable_InterpreterFrame_GetLasti(PyUnstable_InterpreterFrame *frame);
 
    Return the byte offset into the last executed instruction.
 
    .. versionadded:: 3.12
 
 
-.. c:function:: int PyUnstable_InterpreterFrame_GetLine(struct _PyInterpreterFrame *frame);
+.. c:function:: int PyUnstable_InterpreterFrame_GetLine(PyUnstable_InterpreterFrame *frame);
 
    Return the currently executing line number, or -1 if there is no line number.
 
    .. versionadded:: 3.12
-
-

Doc/c-api/init.rst

@@ -1438,7 +1438,7 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
    .. versionadded:: 3.8
 
 
-.. c:type:: PyObject* (*_PyFrameEvalFunction)(PyThreadState *tstate, _PyInterpreterFrame *frame, int throwflag)
+.. c:type:: PyObject* (*_PyFrameEvalFunction)(PyThreadState *tstate, PyUnstable_InterpreterFrame *frame, int throwflag)
 
    Type of a frame evaluation function.
 

Doc/whatsnew/3.15.rst

@@ -1099,6 +1099,10 @@ New features
 * Add :c:func:`PyTuple_FromArray` to create a :class:`tuple` from an array.
   (Contributed by Victor Stinner in :gh:`111489`.)
 
+* Add :c:func:`PyUnstable_InterpreterFrame_GetFrameObject` to get a frame
+  object from an interpreter frame.
+  (Contributed by Victor Stinner in :gh:`141518`.)
+
 * Add :c:func:`PyUnstable_Object_Dump` to dump an object to ``stderr``.
   It should only be used for debugging.
   (Contributed by Victor Stinner in :gh:`141070`.)

Include/cpython/pyframe.h

@@ -23,18 +23,26 @@ PyAPI_FUNC(PyObject*) PyFrame_GetVarString(PyFrameObject *frame, const char *nam
  * implementing custom frame evaluators with PEP 523. */
 
 struct _PyInterpreterFrame;
+typedef struct _PyInterpreterFrame PyUnstable_InterpreterFrame;
 
 /* Returns the code object of the frame (strong reference).
  * Does not raise an exception. */
-PyAPI_FUNC(PyObject *) PyUnstable_InterpreterFrame_GetCode(struct _PyInterpreterFrame *frame);
+PyAPI_FUNC(PyObject *) PyUnstable_InterpreterFrame_GetCode(
+    PyUnstable_InterpreterFrame *frame);
 
 /* Returns a byte offset into the last executed instruction.
  * Does not raise an exception. */
-PyAPI_FUNC(int) PyUnstable_InterpreterFrame_GetLasti(struct _PyInterpreterFrame *frame);
+PyAPI_FUNC(int) PyUnstable_InterpreterFrame_GetLasti(
+    PyUnstable_InterpreterFrame *frame);
 
 /* Returns the currently executing line number, or -1 if there is no line number.
  * Does not raise an exception. */
-PyAPI_FUNC(int) PyUnstable_InterpreterFrame_GetLine(struct _PyInterpreterFrame *frame);
+PyAPI_FUNC(int) PyUnstable_InterpreterFrame_GetLine(
+    PyUnstable_InterpreterFrame *frame);
+
+/* Get a frame object from an interpreter frame. */
+PyAPI_FUNC(PyFrameObject*) PyUnstable_InterpreterFrame_GetFrameObject(
+    PyUnstable_InterpreterFrame *frame);
 
 #define PyUnstable_EXECUTABLE_KIND_SKIP 0
 #define PyUnstable_EXECUTABLE_KIND_PY_FUNCTION 1

Include/cpython/pystate.h

@@ -302,7 +302,7 @@ PyAPI_FUNC(void) PyThreadState_DeleteCurrent(void);
 
 /* Frame evaluation API */
 
-typedef PyObject* (*_PyFrameEvalFunction)(PyThreadState *tstate, struct _PyInterpreterFrame *, int);
+typedef PyObject* (*_PyFrameEvalFunction)(PyThreadState *tstate, PyUnstable_InterpreterFrame *, int);
 
 PyAPI_FUNC(_PyFrameEvalFunction) _PyInterpreterState_GetEvalFrameFunc(
     PyInterpreterState *interp);

Include/internal/pycore_interpframe.h

@@ -290,7 +290,7 @@ _PyFrame_GetFrameObject(_PyInterpreterFrame *frame)
 {
 
     assert(!_PyFrame_IsIncomplete(frame));
-    PyFrameObject *res =  frame->frame_obj;
+    PyFrameObject *res = frame->frame_obj;
     if (res != NULL) {
         return res;
     }

Lib/test/test_capi/test_frame.py

@@ -4,6 +4,7 @@
 
 
 _testcapi = import_helper.import_module('_testcapi')
+_testinternalcapi = import_helper.import_module('_testinternalcapi')
 
 
 class FrameTest(unittest.TestCase):
@@ -52,5 +53,34 @@ def dummy():
         self.assertIsNone(frame.f_back)
 
 
+class InterpreterFrameTest(unittest.TestCase):
+
+    @staticmethod
+    def func():
+        return sys._getframe()
+
+    def test_code(self):
+        frame = self.func()
+        code = _testinternalcapi.iframe_getcode(frame)
+        self.assertIs(code, self.func.__code__)
+
+    def test_lasti(self):
+        frame = self.func()
+        lasti = _testinternalcapi.iframe_getlasti(frame)
+        self.assertGreater(lasti, 0)
+        self.assertLess(lasti, len(self.func.__code__.co_code))
+
+    def test_line(self):
+        frame = self.func()
+        line = _testinternalcapi.iframe_getline(frame)
+        firstline = self.func.__code__.co_firstlineno
+        self.assertEqual(line, firstline + 2)
+
+    def test_frame_object(self):
+        frame = sys._getframe()
+        obj = _testinternalcapi.iframe_getframeobject(frame)
+        self.assertIs(obj, frame)
+
+
 if __name__ == "__main__":
     unittest.main()

Lib/test/test_capi/test_misc.py

@@ -2754,30 +2754,6 @@ class Subclass(BaseException, self.module.StateAccessType):
         self.assertIs(Subclass().get_defining_module(), self.module)
 
 
-class TestInternalFrameApi(unittest.TestCase):
-
-    @staticmethod
-    def func():
-        return sys._getframe()
-
-    def test_code(self):
-        frame = self.func()
-        code = _testinternalcapi.iframe_getcode(frame)
-        self.assertIs(code, self.func.__code__)
-
-    def test_lasti(self):
-        frame = self.func()
-        lasti = _testinternalcapi.iframe_getlasti(frame)
-        self.assertGreater(lasti, 0)
-        self.assertLess(lasti, len(self.func.__code__.co_code))
-
-    def test_line(self):
-        frame = self.func()
-        line = _testinternalcapi.iframe_getline(frame)
-        firstline = self.func.__code__.co_firstlineno
-        self.assertEqual(line, firstline + 2)
-
-
 SUFFICIENT_TO_DEOPT_AND_SPECIALIZE = 100
 
 class Test_Pep523API(unittest.TestCase):

Misc/NEWS.d/3.14.0a1.rst

@@ -4222,7 +4222,7 @@ docstrings are now removed from the optimized AST in optimization level 2.
 .. nonce: A7uxqa
 .. section: Core and Builtins
 
-The ``f_executable`` field in the internal :c:struct:`_PyInterpreterFrame`
+The ``f_executable`` field in the internal :c:struct:`!_PyInterpreterFrame`
 struct now uses a tagged pointer.  Profilers and debuggers that uses this
 field should clear the least significant bit to recover the
 :c:expr:`PyObject*` pointer.

Misc/NEWS.d/next/C_API/2025-11-25-16-35-36.gh-issue-141518.gEueQd.rst

@@ -0,0 +1,2 @@
+Add :c:func:`PyUnstable_InterpreterFrame_GetFrameObject` to get a frame
+object from an interpreter frame. Patch by Victor Stinner.

Modules/_testinternalcapi.c

@@ -959,6 +959,17 @@ iframe_getlasti(PyObject *self, PyObject *frame)
     return PyLong_FromLong(PyUnstable_InterpreterFrame_GetLasti(f));
 }
 
+static PyObject *
+iframe_getframeobject(PyObject *self, PyObject *frame)
+{
+    if (!PyFrame_Check(frame)) {
+        PyErr_SetString(PyExc_TypeError, "argument must be a frame");
+        return NULL;
+    }
+    struct _PyInterpreterFrame *f = ((PyFrameObject *)frame)->f_frame;
+    return (PyObject*)PyUnstable_InterpreterFrame_GetFrameObject(f);
+}
+
 static PyObject *
 code_returns_only_none(PyObject *self, PyObject *arg)
 {
@@ -2529,6 +2540,7 @@ static PyMethodDef module_functions[] = {
     {"iframe_getcode", iframe_getcode, METH_O, NULL},
     {"iframe_getline", iframe_getline, METH_O, NULL},
     {"iframe_getlasti", iframe_getlasti, METH_O, NULL},
+    {"iframe_getframeobject", iframe_getframeobject, METH_O, NULL},
     {"code_returns_only_none", code_returns_only_none, METH_O, NULL},
     {"get_co_framesize", get_co_framesize, METH_O, NULL},
     {"get_co_localskinds", get_co_localskinds, METH_O, NULL},

Objects/frameobject.c

@@ -2457,3 +2457,10 @@ PyFrame_GetGenerator(PyFrameObject *frame)
     assert(!_PyFrame_IsIncomplete(frame->f_frame));
     return frame_generator_get((PyObject *)frame, NULL);
 }
+
+
+PyFrameObject*
+PyUnstable_InterpreterFrame_GetFrameObject(PyUnstable_InterpreterFrame *frame)
+{
+    return (PyFrameObject*)Py_XNewRef(_PyFrame_GetFrameObject(frame));
+}