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.

Added in version 3.9.

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.

Added in version 3.11.

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.

Added in version 3.9.

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.

Added in version 3.11.

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.

Added in version 3.11.

int PyFrame_GetLasti(PyFrameObject *frame)

Get the frame’s f_lasti attribute.

Returns -1 if frame.f_lasti is None.

Added in version 3.11.

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.

Added in version 3.12.

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.

Added in version 3.12.

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.

Added in version 3.11.

Changed in version 3.13: As part of PEP 667, return an instance of PyFrameLocalsProxy_Type.

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

Added in version 3.13.

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.

Soft deprecated since version 3.13: This function now does nothing.

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.

Soft deprecated since version 3.13: This function now does nothing.

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.

Soft deprecated since version 3.13: This function now does nothing.

See also

PEP 667

Internal frames

Unless using PEP 523, you will not need this.

struct _PyInterpreterFrame

The interpreter’s internal frame representation.

Added in version 3.11.

PyObject *PyUnstable_InterpreterFrame_GetCode(struct _PyInterpreterFrame *frame);

This is Unstable API. It may change without warning in minor releases.

Return a strong reference to the code object for the frame. Does not raise an exception.

If allocation and reference count changes are not permitted (for example, from a signal handler or a custom memory allocator), use PyUnstable_InterpreterFrame_GetCodeBorrowed() instead.

Added in version 3.12.

PyObject *PyUnstable_InterpreterFrame_GetCodeBorrowed(struct _PyInterpreterFrame *frame);

This is Unstable API. It may change without warning in minor releases.

Return a borrowed reference to the code object for the frame.

Use this instead of PyUnstable_InterpreterFrame_GetCode() when allocation and reference count changes are not permitted (for example, from a custom memory allocator hook). Does not allocate memory, does not change any reference counts, does not acquire or release the GIL, and does not raise an exception. Uses heuristics to detect freed memory — not 100% reliable in the presence of concurrent deallocation.

Added in version 3.15.

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.

Added in version 3.12.

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.

Added in version 3.12.

int PyUnstable_InterpreterFrame_GetLineChecked(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 or the frame is invalid. Does not raise an exception.

Unlike PyUnstable_InterpreterFrame_GetLine(), validates the code object and instruction offset before accessing the line table rather than asserting them, avoiding assertion failures when the frame state may be partially torn down.

Added in version 3.15.

struct _PyInterpreterFrame *PyUnstable_ThreadState_GetCurrentFrame(PyThreadState *tstate)

This is Unstable API. It may change without warning in minor releases.

Return the innermost Python frame of tstate, or NULL if the thread has no Python frame or freed memory is detected. Incomplete frames (interpreter entry trampolines and frames that have not yet begun executing) are skipped automatically.

Does not allocate memory, does not raise an exception, does not acquire or release the GIL, and does not re-enter the interpreter. Racy reads from other threads are intentional. Uses heuristics to detect freed memory — not 100% reliable in the presence of concurrent deallocation.

To iterate over the full call stack, call PyUnstable_InterpreterFrame_GetCaller() repeatedly on the returned frame until it returns NULL.

Added in version 3.15.

struct _PyInterpreterFrame *PyUnstable_InterpreterFrame_GetCaller(struct _PyInterpreterFrame *frame)

This is Unstable API. It may change without warning in minor releases.

Return the frame that called frame, or NULL if frame is the outermost frame or freed memory is detected. Incomplete frames (interpreter entry trampolines and frames that have not yet begun executing) are skipped automatically.

Does not allocate memory, does not raise an exception, does not acquire or release the GIL, and does not re-enter the interpreter. Racy reads from other threads are intentional. Uses heuristics to detect freed memory — not 100% reliable in the presence of concurrent deallocation.

Unlike PyFrame_GetBack(), this function never allocates memory, making it usable from a custom memory allocator hook without risking re-entrant allocation.

Added in version 3.15.