Spaces:
Running on Zero
Running on Zero
File size: 6,439 Bytes
9273228 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 | # 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
> :::
|