GeezerVison is showing docs.python.org — Frame objects
Frame objects¶
-
type PyFrameObject¶
- Part of the Stable ABI (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>.
-
PyFrameObject *PyFrame_New(PyThreadState *tstate, PyCodeObject *code, PyObject *globals, PyObject *locals)¶
Create a new frame object. This function returns a strong reference
to the new frame object on success, and returns NULL with an exception
set on failure.
-
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)¶
- Return value: New reference.
Get the frame next outer frame.
Return a strong reference, or NULL if frame has no outer
frame.
This raises no exceptions.
-
PyObject *PyFrame_GetBuiltins(PyFrameObject *frame)¶
- Return value: New reference.
Get the frame’s f_builtins attribute.
Return a strong reference. The result cannot be NULL.
-
PyCodeObject *PyFrame_GetCode(PyFrameObject *frame)¶
- Return value: New reference. 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)¶
- Return value: New reference.
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)¶
- Return value: New reference.
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.
-
PyObject *PyFrame_GetVar(PyFrameObject *frame, PyObject *name)¶
- Return value: New reference.
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)¶
- Return value: New reference.
Similar to PyFrame_GetVar(), but the variable name is a C string
encoded in UTF-8.
-
PyObject *PyFrame_GetLocals(PyFrameObject *frame)¶
- Return value: New reference.
Get the frame’s f_locals attribute.
If the frame refers to an optimized scope, this returns a
write-through proxy object that allows modifying the locals.
In all other cases (classes, modules, exec(), eval()) it returns
the mapping representing the frame locals directly (as described for
locals()).
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.
Frame locals proxies¶
The f_locals attribute on a frame object
is an instance of a “frame-locals proxy”. The proxy object exposes a
write-through view of the underlying locals dictionary for the frame. This
ensures that the variables exposed by f_locals are always up to date with
the live local variables in the frame itself.
See PEP 667 for more information.
-
PyTypeObject PyFrameLocalsProxy_Type¶
The type of frame locals() proxy objects.
-
int PyFrameLocalsProxy_Check(PyObject *obj)¶
Return non-zero if obj is a frame locals() proxy.
Legacy local variable APIs¶
These APIs are soft deprecated. As of Python 3.13, they do nothing.
They exist solely for backwards compatibility.
-
void PyFrame_LocalsToFast(PyFrameObject *f, int clear)¶
Prior to Python 3.13, this function would copy the f_locals
attribute of f to the internal “fast” array of local variables, allowing
changes in frame objects to be visible to the interpreter. If clear was
true, this function would process variables that were unset in the locals
dictionary.
-
void PyFrame_FastToLocals(PyFrameObject *f)¶
Prior to Python 3.13, this function would copy the internal “fast” array
of local variables (which is used by the interpreter) to the
f_locals attribute of f, allowing changes in local
variables to be visible to frame objects.
-
int PyFrame_FastToLocalsWithError(PyFrameObject *f)¶
Prior to Python 3.13, this function was similar to
PyFrame_FastToLocals(), but would return 0 on success, and
-1 with an exception set on failure.
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.
-
int PyUnstable_InterpreterFrame_GetLocal(struct _PyInterpreterFrame *frame, Py_ssize_t index, PyObject **result)¶
This is Unstable API. It may change without warning in minor releases.
Retrieve the local variable at index.
To determine the index of a particular variable, use
PyUnstable_InterpreterFrame_GetCode() and
PyUnstable_Code_GetLocalPlusNames().
Cell and free variables are unboxed to their contents. Free variables are
resolved from the function closure, so this also works on a frame that has
not started executing.
On success, store a new strong reference in result and return 1. If the slot is unset or hidden, store NULL in result and return 0. On error, raise an exception, store NULL in result and return -1.
© Copyright 2001 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 Nov 12, 2026 (18:57 UTC).
Found a bug?
Created using Sphinx 9.1.1.
|