Frame Objects

typePyFrameObject
Part of theLimited 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 theWhat’s New entryfor details.

ThePyEval_GetFrame() andPyThreadState_GetFrame() functionscan be used to get a frame object.

See alsoReflection.

PyTypeObjectPyFrame_Type

The type of frame objects.It is the same object astypes.FrameType in the Python layer.

Changed in version 3.11:Previously, this type was only available after including<frameobject.h>.

intPyFrame_Check(PyObject*obj)

Return non-zero ifobj 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 theframe next outer frame.

Return astrong reference, orNULL ifframe has no outerframe.

Added in version 3.9.

PyObject*PyFrame_GetBuiltins(PyFrameObject*frame)
Return value: New reference.

Get theframe’sf_builtins attribute.

Return astrong reference. The result cannot beNULL.

Added in version 3.11.

PyCodeObject*PyFrame_GetCode(PyFrameObject*frame)
Return value: New reference. Part of theStable ABI since version 3.10.

Get theframe code.

Return astrong reference.

The result (frame code) cannot beNULL.

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,orNULL if this frame is not owned by a generator.Does not raise an exception, even if the return value isNULL.

Return astrong reference, orNULL.

Added in version 3.11.

PyObject*PyFrame_GetGlobals(PyFrameObject*frame)
Return value: New reference.

Get theframe’sf_globals attribute.

Return astrong reference. The result cannot beNULL.

Added in version 3.11.

intPyFrame_GetLasti(PyFrameObject*frame)

Get theframe’sf_lasti attribute.

Returns -1 ifframe.f_lasti isNone.

Added in version 3.11.

PyObject*PyFrame_GetVar(PyFrameObject*frame,PyObject*name)
Return value: New reference.

Get the variablename offrame.

  • Return astrong reference to the variable value on success.

  • RaiseNameError and returnNULL if the variable does not exist.

  • Raise an exception and returnNULL on error.

name type must be astr.

Added in version 3.12.

PyObject*PyFrame_GetVarString(PyFrameObject*frame,constchar*name)
Return value: New reference.

Similar toPyFrame_GetVar(), but the variable name is a C stringencoded in UTF-8.

Added in version 3.12.

PyObject*PyFrame_GetLocals(PyFrameObject*frame)
Return value: New reference.

Get theframe’sf_locals attribute.If the frame refers to anoptimized scope, this returns awrite-through proxy object that allows modifying the locals.In all other cases (classes, modules,exec(),eval()) it returnsthe mapping representing the frame locals directly (as described forlocals()).

Return astrong reference.

Added in version 3.11.

Changed in version 3.13:As part ofPEP 667, return an instance ofPyFrameLocalsProxy_Type.

intPyFrame_GetLineNumber(PyFrameObject*frame)
Part of theStable ABI since version 3.10.

Return the line number thatframe is currently executing.

Frame Locals Proxies

Added in version 3.13.

Thef_locals attribute on aframe objectis an instance of a “frame-locals proxy”. The proxy object exposes awrite-through view of the underlying locals dictionary for the frame. Thisensures that the variables exposed byf_locals are always up to date withthe live local variables in the frame itself.

SeePEP 667 for more information.

PyTypeObjectPyFrameLocalsProxy_Type

The type of framelocals() proxy objects.

intPyFrameLocalsProxy_Check(PyObject*obj)

Return non-zero ifobj is a framelocals() proxy.

Internal Frames

Unless usingPEP 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 isUnstable API. It may change without warning in minor releases.

Return astrong reference to the code object for the frame.

Added in version 3.12.

intPyUnstable_InterpreterFrame_GetLasti(struct_PyInterpreterFrame*frame);
This isUnstable API. It may change without warning in minor releases.

Return the byte offset into the last executed instruction.

Added in version 3.12.

intPyUnstable_InterpreterFrame_GetLine(struct_PyInterpreterFrame*frame);
This isUnstable 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.