typePyFrameObject
Part of the
(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
for details.
The
and
functions can be used to get a frame object.
See also
.
PyFrame_Type
The type of frame objects. It is the same object as
in the Python layer.
Changed in version 3.11: Previously, this type was only available after including <frameobject.h>.
*PyFrame_New(
*tstate,
*code,
*globals,
*locals)
Create a new frame object. This function returns a
to the new frame object on success, and returns NULL with an exception set on failure.
intPyFrame_Check(
*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>.
*PyFrame_GetBack(
*frame)
Return value: New reference.Get the frame next outer frame.
Return a
, or NULL if frame has no outer frame. This raises no exceptions.
Added in version 3.9.
*PyFrame_GetBuiltins(
*frame)
Return value: New reference.Get the frame’s
attribute.
Return a
. The result cannot be NULL.
Added in version 3.11.
*PyFrame_GetCode(
*frame)
Return value: New reference. Part of the
since version 3.10.Get the frame code.
Return a
.
The result (frame code) cannot be NULL.
Added in version 3.9.
*PyFrame_GetGenerator(
*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
, or NULL.
Added in version 3.11.
*PyFrame_GetGlobals(
*frame)
Return value: New reference.Get the frame’s
attribute.
Return a
. The result cannot be NULL.
Added in version 3.11.
intPyFrame_GetLasti(
*frame)
Get the frame’s
attribute.
Returns -1 if frame.f_lasti is None.
Added in version 3.11.
*PyFrame_GetVar(
*frame,
*name)
Return value: New reference.Get the variable name of frame.
Return a
to the variable value on success.
Raise
and return NULL if the variable does not exist.
Raise an exception and return NULL on error.
name type must be a
.
Added in version 3.12.
*PyFrame_GetVarString(
*frame, constchar*name)
Return value: New reference.Similar to
, but the variable name is a C string encoded in UTF-8.
Added in version 3.12.
*PyFrame_GetLocals(
*frame)
Return value: New reference.Get the frame’s
attribute. If the frame refers to an
, this returns a write-through proxy object that allows modifying the locals. In all other cases (classes, modules,
,
) it returns the mapping representing the frame locals directly (as described for
).
Return a
.
Added in version 3.11.
Changed in version 3.13: As part of
, return an instance of
.
intPyFrame_GetLineNumber(
*frame)
Part of the
since version 3.10.Return the line number that frame is currently executing.
Frame locals proxies
Added in version 3.13.
The
attribute on a
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
for more information.
PyFrameLocalsProxy_Type
The type of frame
proxy objects.
intPyFrameLocalsProxy_Check(
*obj)
Return non-zero if obj is a frame
proxy.
Legacy local variable APIs
These APIs are
. As of Python 3.13, they do nothing. They exist solely for backwards compatibility.
voidPyFrame_LocalsToFast(
*f, intclear)
Prior to Python 3.13, this function would copy the
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.
since version 3.13: This function now does nothing.
voidPyFrame_FastToLocals(
*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
attribute of f, allowing changes in local variables to be visible to frame objects.
since version 3.13: This function now does nothing.
intPyFrame_FastToLocalsWithError(
*f)
Prior to Python 3.13, this function was similar to
, but would return 0 on success, and -1 with an exception set on failure.
since version 3.13: This function now does nothing.
Internal frames
Unless using
, you will not need this.
struct_PyInterpreterFrame
The interpreter’s internal frame representation.
Added in version 3.11.
*PyUnstable_InterpreterFrame_GetCode(struct
*frame);
This is
. It may change without warning in minor releases.
Added in version 3.12.
intPyUnstable_InterpreterFrame_GetLasti(struct
*frame);
This is
. 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
*frame);
This is
. 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.