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>.

PyFrameObject*PyFrame_New(PyThreadState*tstate,PyCodeObject*code,PyObject*globals,PyObject*locals)

Create a new frame object. This function returns astrong referenceto the new frame object on success, and returnsNULL with an exceptionset on failure.

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.

Legacy Local Variable APIs

These APIs aresoft deprecated. As of Python 3.13, they do nothing.They exist solely for backwards compatibility.

voidPyFrame_LocalsToFast(PyFrameObject*f,intclear)

This function issoft deprecated and does nothing.

Prior to Python 3.13, this function would copy thef_localsattribute off to the internal “fast” array of local variables, allowingchanges in frame objects to be visible to the interpreter. Ifclear wastrue, this function would process variables that were unset in the localsdictionary.

Changed in version 3.13:This function now does nothing.

voidPyFrame_FastToLocals(PyFrameObject*f)

This function issoft deprecated and does nothing.

Prior to Python 3.13, this function would copy the internal “fast” arrayof local variables (which is used by the interpreter) to thef_locals attribute off, allowing changes in localvariables to be visible to frame objects.

Changed in version 3.13:This function now does nothing.

intPyFrame_FastToLocalsWithError(PyFrameObject*f)

This function issoft deprecated and does nothing.

Prior to Python 3.13, this function was similar toPyFrame_FastToLocals(), but would return0 on success, and-1 with an exception set on failure.

Changed in version 3.13:This function now does nothing.

See also

PEP 667

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.