Frame Objects¶
-
type PyFrameObject¶
- Part of the Limited API (as an opaque struct).
The C structure of the objects used to describe frame objects.
There are no public members in this structure.
Changed in version 3.11: The members of this structure were removed from the public C API.
Refer to the What’s New entry
for details.
The PyEval_GetFrame() and PyThreadState_GetFrame() functions
can be used to get a frame object.
See also Reflection.
-
PyTypeObject PyFrame_Type¶
The type of frame objects.
It is the same object as types.FrameType in the Python layer.
Changed in version 3.11: Previously, this type was only available after including
<frameobject.h>.
-
int PyFrame_Check(PyObject *obj)¶
Return non-zero if obj is a frame object.
Changed in version 3.11: Previously, this function was only available after including
<frameobject.h>.
-
PyFrameObject *PyFrame_GetBack(PyFrameObject *frame)¶
Get the frame next outer frame.
Return a strong reference, or NULL if frame has no outer
frame.
-
PyObject *PyFrame_GetBuiltins(PyFrameObject *frame)¶
Get the frame’s f_builtins attribute.
Return a strong reference. The result cannot be NULL.
-
PyCodeObject *PyFrame_GetCode(PyFrameObject *frame)¶
- Part of the Stable ABI since version 3.10.
Get the frame code.
Return a strong reference.
The result (frame code) cannot be NULL.
-
PyObject *PyFrame_GetGenerator(PyFrameObject *frame)¶
Get the generator, coroutine, or async generator that owns this frame,
or NULL if this frame is not owned by a generator.
Does not raise an exception, even if the return value is NULL.
Return a strong reference, or NULL.
-
PyObject *PyFrame_GetGlobals(PyFrameObject *frame)¶
Get the frame’s f_globals attribute.
Return a strong reference. The result cannot be NULL.
-
int PyFrame_GetLasti(PyFrameObject *frame)¶
Get the frame’s f_lasti attribute.
Returns -1 if frame.f_lasti is None.
-
PyObject *PyFrame_GetVar(PyFrameObject *frame, PyObject *name)¶
Get the variable name of frame.
Return a strong reference to the variable value on success.
Raise NameError and return NULL if the variable does not exist.
Raise an exception and return NULL on error.
name type must be a str.
-
PyObject *PyFrame_GetVarString(PyFrameObject *frame, const char *name)¶
Similar to PyFrame_GetVar(), but the variable name is a C string
encoded in UTF-8.
-
PyObject *PyFrame_GetLocals(PyFrameObject *frame)¶
Get the frame’s f_locals attribute (dict).
Return a strong reference.
-
int PyFrame_GetLineNumber(PyFrameObject *frame)¶
- Part of the Stable ABI since version 3.10.
Return the line number that frame is currently executing.
Internal Frames¶
Unless using PEP 523, you will not need this.
-
struct _PyInterpreterFrame¶
The interpreter’s internal frame representation.
-
PyObject *PyUnstable_InterpreterFrame_GetCode(struct _PyInterpreterFrame *frame);¶
This is Unstable API. It may change without warning in minor releases.
-
int PyUnstable_InterpreterFrame_GetLasti(struct _PyInterpreterFrame *frame);¶
This is Unstable API. It may change without warning in minor releases.
Return the byte offset into the last executed instruction.
-
int PyUnstable_InterpreterFrame_GetLine(struct _PyInterpreterFrame *frame);¶
This is Unstable API. It may change without warning in minor releases.
Return the currently executing line number, or -1 if there is no line number.
©
Copyright 2001-2026, Python Software Foundation.
This page is licensed under the Python Software Foundation License Version 2.
Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.
See
History and License for more information.
The Python Software Foundation is a non-profit corporation.
Please donate.
Last updated on Oct 26, 2026 (15:00 UTC).
Found a bug?
Created using
Sphinx 8.2.3.