Debian Codegraph @

Doc/c-api/frame.rst

raw
1 .. highlight:: c
2
3 Frame objects
4 -------------
5
6 .. c:type:: PyFrameObject
7
8 The C structure of the objects used to describe frame objects.
9
10 There are no public members in this structure.
11
12 .. versionchanged:: 3.11
13 The members of this structure were removed from the public C API.
14 Refer to the :ref:`What's New entry <pyframeobject-3.11-hiding>`
15 for details.
16
17 The :c:func:`PyEval_GetFrame` and :c:func:`PyThreadState_GetFrame` functions
18 can be used to get a frame object.
19
20 See also :ref:`Reflection <reflection>`.
21
22 .. c:var:: PyTypeObject PyFrame_Type
23
24 The type of frame objects.
25 It is the same object as :py:class:`types.FrameType` in the Python layer.
26
27 .. versionchanged:: 3.11
28
29 Previously, this type was only available after including
30 ``<frameobject.h>``.
31
32 .. c:function:: PyFrameObject *PyFrame_New(PyThreadState *tstate, PyCodeObject *code, PyObject *globals, PyObject *locals)
33
34 Create a new frame object. This function returns a :term:`strong reference`
35 to the new frame object on success, and returns ``NULL`` with an exception
36 set on failure.
37
38 .. c:function:: int PyFrame_Check(PyObject *obj)
39
40 Return non-zero if *obj* is a frame object.
41
42 .. versionchanged:: 3.11
43
44 Previously, this function was only available after including
45 ``<frameobject.h>``.
46
47 .. c:function:: PyFrameObject* PyFrame_GetBack(PyFrameObject *frame)
48
49 Get the *frame* next outer frame.
50
51 Return a :term:`strong reference`, or ``NULL`` if *frame* has no outer
52 frame.
53 This raises no exceptions.
54
55 .. versionadded:: 3.9
56
57
58 .. c:function:: PyObject* PyFrame_GetBuiltins(PyFrameObject *frame)
59
60 Get the *frame*'s :attr:`~frame.f_builtins` attribute.
61
62 Return a :term:`strong reference`. The result cannot be ``NULL``.
63
64 .. versionadded:: 3.11
65
66
67 .. c:function:: PyCodeObject* PyFrame_GetCode(PyFrameObject *frame)
68
69 Get the *frame* code.
70
71 Return a :term:`strong reference`.
72
73 The result (frame code) cannot be ``NULL``.
74
75 .. versionadded:: 3.9
76
77
78 .. c:function:: PyObject* PyFrame_GetGenerator(PyFrameObject *frame)
79
80 Get the generator, coroutine, or async generator that owns this frame,
81 or ``NULL`` if this frame is not owned by a generator.
82 Does not raise an exception, even if the return value is ``NULL``.
83
84 Return a :term:`strong reference`, or ``NULL``.
85
86 .. versionadded:: 3.11
87
88
89 .. c:function:: PyObject* PyFrame_GetGlobals(PyFrameObject *frame)
90
91 Get the *frame*'s :attr:`~frame.f_globals` attribute.
92
93 Return a :term:`strong reference`. The result cannot be ``NULL``.
94
95 .. versionadded:: 3.11
96
97
98 .. c:function:: int PyFrame_GetLasti(PyFrameObject *frame)
99
100 Get the *frame*'s :attr:`~frame.f_lasti` attribute.
101
102 Returns -1 if ``frame.f_lasti`` is ``None``.
103
104 .. versionadded:: 3.11
105
106
107 .. c:function:: PyObject* PyFrame_GetVar(PyFrameObject *frame, PyObject *name)
108
109 Get the variable *name* of *frame*.
110
111 * Return a :term:`strong reference` to the variable value on success.
112 * Raise :exc:`NameError` and return ``NULL`` if the variable does not exist.
113 * Raise an exception and return ``NULL`` on error.
114
115 *name* type must be a :class:`str`.
116
117 .. versionadded:: 3.12
118
119
120 .. c:function:: PyObject* PyFrame_GetVarString(PyFrameObject *frame, const char *name)
121
122 Similar to :c:func:`PyFrame_GetVar`, but the variable name is a C string
123 encoded in UTF-8.
124
125 .. versionadded:: 3.12
126
127
128 .. c:function:: PyObject* PyFrame_GetLocals(PyFrameObject *frame)
129
130 Get the *frame*'s :attr:`~frame.f_locals` attribute.
131 If the frame refers to an :term:`optimized scope`, this returns a
132 write-through proxy object that allows modifying the locals.
133 In all other cases (classes, modules, :func:`exec`, :func:`eval`) it returns
134 the mapping representing the frame locals directly (as described for
135 :func:`locals`).
136
137 Return a :term:`strong reference`.
138
139 .. versionadded:: 3.11
140
141 .. versionchanged:: 3.13
142 As part of :pep:`667`, return an instance of :c:var:`PyFrameLocalsProxy_Type`.
143
144
145 .. c:function:: int PyFrame_GetLineNumber(PyFrameObject *frame)
146
147 Return the line number that *frame* is currently executing.
148
149
150 Frame locals proxies
151 ^^^^^^^^^^^^^^^^^^^^
152
153 .. versionadded:: 3.13
154
155 The :attr:`~frame.f_locals` attribute on a :ref:`frame object <frame-objects>`
156 is an instance of a "frame-locals proxy". The proxy object exposes a
157 write-through view of the underlying locals dictionary for the frame. This
158 ensures that the variables exposed by ``f_locals`` are always up to date with
159 the live local variables in the frame itself.
160
161 See :pep:`667` for more information.
162
163 .. c:var:: PyTypeObject PyFrameLocalsProxy_Type
164
165 The type of frame :func:`locals` proxy objects.
166
167 .. c:function:: int PyFrameLocalsProxy_Check(PyObject *obj)
168
169 Return non-zero if *obj* is a frame :func:`locals` proxy.
170
171
172 Legacy local variable APIs
173 ^^^^^^^^^^^^^^^^^^^^^^^^^^
174
175 These APIs are :term:`soft deprecated`. As of Python 3.13, they do nothing.
176 They exist solely for backwards compatibility.
177
178
179 .. c:function:: void PyFrame_LocalsToFast(PyFrameObject *f, int clear)
180
181 Prior to Python 3.13, this function would copy the :attr:`~frame.f_locals`
182 attribute of *f* to the internal "fast" array of local variables, allowing
183 changes in frame objects to be visible to the interpreter. If *clear* was
184 true, this function would process variables that were unset in the locals
185 dictionary.
186
187 .. soft-deprecated:: 3.13
188 This function now does nothing.
189
190
191 .. c:function:: void PyFrame_FastToLocals(PyFrameObject *f)
192
193 Prior to Python 3.13, this function would copy the internal "fast" array
194 of local variables (which is used by the interpreter) to the
195 :attr:`~frame.f_locals` attribute of *f*, allowing changes in local
196 variables to be visible to frame objects.
197
198 .. soft-deprecated:: 3.13
199 This function now does nothing.
200
201
202 .. c:function:: int PyFrame_FastToLocalsWithError(PyFrameObject *f)
203
204 Prior to Python 3.13, this function was similar to
205 :c:func:`PyFrame_FastToLocals`, but would return ``0`` on success, and
206 ``-1`` with an exception set on failure.
207
208 .. soft-deprecated:: 3.13
209 This function now does nothing.
210
211
212 .. seealso::
213 :pep:`667`
214
215
216 Internal frames
217 ^^^^^^^^^^^^^^^
218
219 Unless using :pep:`523`, you will not need this.
220
221 .. c:struct:: _PyInterpreterFrame
222
223 The interpreter's internal frame representation.
224
225 .. versionadded:: 3.11
226
227 .. c:function:: PyObject* PyUnstable_InterpreterFrame_GetCode(struct _PyInterpreterFrame *frame);
228
229 Return a :term:`strong reference` to the code object for the frame.
230
231 .. versionadded:: 3.12
232
233
234 .. c:function:: int PyUnstable_InterpreterFrame_GetLasti(struct _PyInterpreterFrame *frame);
235
236 Return the byte offset into the last executed instruction.
237
238 .. versionadded:: 3.12
239
240
241 .. c:function:: int PyUnstable_InterpreterFrame_GetLine(struct _PyInterpreterFrame *frame);
242
243 Return the currently executing line number, or -1 if there is no line number.
244
245 .. versionadded:: 3.12