python_doc_md/Advanced/c-api/frame.md

# Frame Objects

> The C structure of the objects used to describe frame objects.
>
> There are no public members in this structure.
>
> ::: versionchanged
> 3.11 The members of this structure were removed from the public C API. Refer to the `What's New entry <pyframeobject-3.11-hiding>`{.interpreted-text role="ref"} for details.
> :::

The `PyEval_GetFrame`{.interpreted-text role="c:func"} and `PyThreadState_GetFrame`{.interpreted-text role="c:func"} functions can be used to get a frame object.

See also `Reflection <reflection>`{.interpreted-text role="ref"}.

> The type of frame objects. It is the same object as `types.FrameType`{.interpreted-text role="py:class"} in the Python layer.
>
> ::: versionchanged
> 3.11
>
> Previously, this type was only available after including `<frameobject.h>`.
> :::

> Create a new frame object. This function returns a `strong reference`{.interpreted-text role="term"} to the new frame object on success, and returns `NULL` with an exception set on failure.

> Return non-zero if *obj* is a frame object.
>
> ::: versionchanged
> 3.11
>
> Previously, this function was only available after including `<frameobject.h>`.
> :::

> Get the *frame* next outer frame.
>
> Return a `strong reference`{.interpreted-text role="term"}, or `NULL` if *frame* has no outer frame.
>
> ::: versionadded
> 3.9
> :::

> Get the *frame*\'s `~frame.f_builtins`{.interpreted-text role="attr"} attribute.
>
> Return a `strong reference`{.interpreted-text role="term"}. The result cannot be `NULL`.
>
> ::: versionadded
> 3.11
> :::

> Get the *frame* code.
>
> Return a `strong reference`{.interpreted-text role="term"}.
>
> The result (frame code) cannot be `NULL`.
>
> ::: versionadded
> 3.9
> :::

> 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`{.interpreted-text role="term"}, or `NULL`.
>
> ::: versionadded
> 3.11
> :::

> Get the *frame*\'s `~frame.f_globals`{.interpreted-text role="attr"} attribute.
>
> Return a `strong reference`{.interpreted-text role="term"}. The result cannot be `NULL`.
>
> ::: versionadded
> 3.11
> :::

> Get the *frame*\'s `~frame.f_lasti`{.interpreted-text role="attr"} attribute.
>
> Returns -1 if `frame.f_lasti` is `None`.
>
> ::: versionadded
> 3.11
> :::

> Get the variable *name* of *frame*.
>
> - Return a `strong reference`{.interpreted-text role="term"} to the variable value on success.
> - Raise `NameError`{.interpreted-text role="exc"} and return `NULL` if the variable does not exist.
> - Raise an exception and return `NULL` on error.
>
> *name* type must be a `str`{.interpreted-text role="class"}.
>
> ::: versionadded
> 3.12
> :::

> Similar to `PyFrame_GetVar`{.interpreted-text role="c:func"}, but the variable name is a C string encoded in UTF-8.
>
> ::: versionadded
> 3.12
> :::

> Get the *frame*\'s `~frame.f_locals`{.interpreted-text role="attr"} attribute. If the frame refers to an `optimized scope`{.interpreted-text role="term"}, this returns a write-through proxy object that allows modifying the locals. In all other cases (classes, modules, `exec`{.interpreted-text role="func"}, `eval`{.interpreted-text role="func"}) it returns the mapping representing the frame locals directly (as described for `locals`{.interpreted-text role="func"}).
>
> Return a `strong reference`{.interpreted-text role="term"}.
>
> ::: versionadded
> 3.11
> :::
>
> ::: versionchanged
> 3.13 As part of `667`{.interpreted-text role="pep"}, return an instance of `PyFrameLocalsProxy_Type`{.interpreted-text role="c:var"}.
> :::

> Return the line number that *frame* is currently executing.

## Frame Locals Proxies

::: versionadded
3.13
:::

The `~frame.f_locals`{.interpreted-text role="attr"} attribute on a `frame object <frame-objects>`{.interpreted-text role="ref"} 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 `667`{.interpreted-text role="pep"} for more information.

> The type of frame `locals`{.interpreted-text role="func"} proxy objects.

> Return non-zero if *obj* is a frame `locals`{.interpreted-text role="func"} proxy.

## Legacy Local Variable APIs

These APIs are `soft deprecated`{.interpreted-text role="term"}. As of Python 3.13, they do nothing. They exist solely for backwards compatibility.

> This function is `soft deprecated`{.interpreted-text role="term"} and does nothing.
>
> Prior to Python 3.13, this function would copy the `~frame.f_locals`{.interpreted-text role="attr"} 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.
>
> ::: versionchanged
> 3.13 This function now does nothing.
> :::

> This function is `soft deprecated`{.interpreted-text role="term"} and does nothing.
>
> Prior to Python 3.13, this function would copy the internal \"fast\" array of local variables (which is used by the interpreter) to the `~frame.f_locals`{.interpreted-text role="attr"} attribute of *f*, allowing changes in local variables to be visible to frame objects.
>
> ::: versionchanged
> 3.13 This function now does nothing.
> :::

> This function is `soft deprecated`{.interpreted-text role="term"} and does nothing.
>
> Prior to Python 3.13, this function was similar to `PyFrame_FastToLocals`{.interpreted-text role="c:func"}, but would return `0` on success, and `-1` with an exception set on failure.
>
> ::: versionchanged
> 3.13 This function now does nothing.
> :::

::: seealso
`667`{.interpreted-text role="pep"}
:::

## Internal Frames

Unless using `523`{.interpreted-text role="pep"}, you will not need this.

> The interpreter\'s internal frame representation.
>
> ::: versionadded
> 3.11
> :::

> Return a `strong reference`{.interpreted-text role="term"} to the code object for the frame.
>
> ::: versionadded
> 3.12
> :::

> Return the byte offset into the last executed instruction.
>
> ::: versionadded
> 3.12
> :::

> Return the currently executing line number, or -1 if there is no line number.
>
> ::: versionadded
> 3.12
> :::