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)

Get theframe next outer frame.

Return astrong reference, orNULL ifframe has no outerframe.

Added in version 3.9.

PyObject*PyFrame_GetBuiltins(PyFrameObject*frame)

Get theframe’sf_builtins attribute.

Return astrong reference. The result cannot beNULL.

Added in version 3.11.

PyCodeObject*PyFrame_GetCode(PyFrameObject*frame)
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)

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)

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)

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)

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

Added in version 3.12.

PyObject*PyFrame_GetLocals(PyFrameObject*frame)

Get theframe’sf_locals attribute (dict).

Return astrong reference.

Added in version 3.11.

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

Return the line number thatframe is currently executing.

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.