Debian Codegraph @

Doc/c-api/code.rst

raw
1 .. highlight:: c
2
3 .. index:: object; code, code object
4
5 .. _codeobjects:
6
7 Code Objects
8 ------------
9
10 .. sectionauthor:: Jeffrey Yasskin <[email protected]>
11
12 Code objects are a low-level detail of the CPython implementation.
13 Each one represents a chunk of executable code that hasn't yet been
14 bound into a function.
15
16 .. c:type:: PyCodeObject
17
18 The C structure of the objects used to describe code objects. The
19 fields of this type are subject to change at any time.
20
21
22 .. c:var:: PyTypeObject PyCode_Type
23
24 This is an instance of :c:type:`PyTypeObject` representing the Python
25 :ref:`code object <code-objects>`.
26
27
28 .. c:function:: int PyCode_Check(PyObject *co)
29
30 Return true if *co* is a :ref:`code object <code-objects>`.
31 This function always succeeds.
32
33 .. c:function:: Py_ssize_t PyCode_GetNumFree(PyCodeObject *co)
34
35 Return the number of :term:`free (closure) variables <closure variable>`
36 in a code object.
37
38 .. c:function:: int PyUnstable_Code_GetFirstFree(PyCodeObject *co)
39
40 Return the position of the first :term:`free (closure) variable <closure variable>`
41 in a code object.
42
43 .. versionchanged:: 3.13
44
45 Renamed from ``PyCode_GetFirstFree`` as part of :ref:`unstable-c-api`.
46 The old name is deprecated, but will remain available until the
47 signature changes again.
48
49 .. c:function:: PyCodeObject* PyUnstable_Code_New(int argcount, int kwonlyargcount, int nlocals, int stacksize, int flags, PyObject *code, PyObject *consts, PyObject *names, PyObject *varnames, PyObject *freevars, PyObject *cellvars, PyObject *filename, PyObject *name, PyObject *qualname, int firstlineno, PyObject *linetable, PyObject *exceptiontable)
50
51 Return a new code object. If you need a dummy code object to create a frame,
52 use :c:func:`PyCode_NewEmpty` instead.
53
54 Since the definition of the bytecode changes often, calling
55 :c:func:`PyUnstable_Code_New` directly can bind you to a precise Python version.
56
57 The many arguments of this function are inter-dependent in complex
58 ways, meaning that subtle changes to values are likely to result in incorrect
59 execution or VM crashes. Use this function only with extreme care.
60
61 .. versionchanged:: 3.11
62 Added ``qualname`` and ``exceptiontable`` parameters.
63
64 .. index:: single: PyCode_New (C function)
65
66 .. versionchanged:: 3.12
67
68 Renamed from ``PyCode_New`` as part of :ref:`unstable-c-api`.
69 The old name is deprecated, but will remain available until the
70 signature changes again.
71
72 .. c:function:: PyCodeObject* PyCode_NewWithPosOnlyArgs(...)
73 :no-typesetting:
74
75 .. c:function:: PyCodeObject* PyUnstable_Code_NewWithPosOnlyArgs(int argcount, int posonlyargcount, int kwonlyargcount, int nlocals, int stacksize, int flags, PyObject *code, PyObject *consts, PyObject *names, PyObject *varnames, PyObject *freevars, PyObject *cellvars, PyObject *filename, PyObject *name, PyObject *qualname, int firstlineno, PyObject *linetable, PyObject *exceptiontable)
76
77 Similar to :c:func:`PyUnstable_Code_New`, but with an extra "posonlyargcount" for positional-only arguments.
78 The same caveats that apply to ``PyUnstable_Code_New`` also apply to this function.
79
80 .. versionadded:: 3.8 as ``PyCode_NewWithPosOnlyArgs``
81
82 .. versionchanged:: 3.11
83 Added ``qualname`` and ``exceptiontable`` parameters.
84
85 .. versionchanged:: 3.12
86
87 Renamed to ``PyUnstable_Code_NewWithPosOnlyArgs``.
88 The old name is deprecated, but will remain available until the
89 signature changes again.
90
91 .. c:function:: PyCodeObject* PyCode_NewEmpty(const char *filename, const char *funcname, int firstlineno)
92
93 Return a new empty code object with the specified filename,
94 function name, and first line number. The resulting code
95 object will raise an ``Exception`` if executed.
96
97 .. c:function:: int PyCode_Addr2Line(PyCodeObject *co, int byte_offset)
98
99 Return the line number of the instruction that occurs on or before ``byte_offset`` and ends after it.
100 If you just need the line number of a frame, use :c:func:`PyFrame_GetLineNumber` instead.
101
102 For efficiently iterating over the line numbers in a code object, use :pep:`the API described in PEP 626
103 <0626#out-of-process-debuggers-and-profilers>`.
104
105 .. c:function:: int PyCode_Addr2Location(PyObject *co, int byte_offset, int *start_line, int *start_column, int *end_line, int *end_column)
106
107 Sets the passed ``int`` pointers to the source code line and column numbers
108 for the instruction at ``byte_offset``. Sets the value to ``0`` when
109 information is not available for any particular element.
110
111 Returns ``1`` if the function succeeds and 0 otherwise.
112
113 .. versionadded:: 3.11
114
115 .. c:function:: PyObject* PyCode_GetCode(PyCodeObject *co)
116
117 Equivalent to the Python code ``getattr(co, 'co_code')``.
118 Returns a strong reference to a :c:type:`PyBytesObject` representing the
119 bytecode in a code object. On error, ``NULL`` is returned and an exception
120 is raised.
121
122 This ``PyBytesObject`` may be created on-demand by the interpreter and does
123 not necessarily represent the bytecode actually executed by CPython. The
124 primary use case for this function is debuggers and profilers.
125
126 .. versionadded:: 3.11
127
128 .. c:function:: PyObject* PyCode_GetVarnames(PyCodeObject *co)
129
130 Equivalent to the Python code ``getattr(co, 'co_varnames')``.
131 Returns a new reference to a :c:type:`PyTupleObject` containing the names of
132 the local variables. On error, ``NULL`` is returned and an exception
133 is raised.
134
135 .. versionadded:: 3.11
136
137 .. c:function:: PyObject* PyCode_GetCellvars(PyCodeObject *co)
138
139 Equivalent to the Python code ``getattr(co, 'co_cellvars')``.
140 Returns a new reference to a :c:type:`PyTupleObject` containing the names of
141 the local variables that are referenced by nested functions. On error, ``NULL``
142 is returned and an exception is raised.
143
144 .. versionadded:: 3.11
145
146 .. c:function:: PyObject* PyCode_GetFreevars(PyCodeObject *co)
147
148 Equivalent to the Python code ``getattr(co, 'co_freevars')``.
149 Returns a new reference to a :c:type:`PyTupleObject` containing the names of
150 the :term:`free (closure) variables <closure variable>`. On error, ``NULL`` is returned
151 and an exception is raised.
152
153 .. versionadded:: 3.11
154
155 .. c:function:: int PyCode_AddWatcher(PyCode_WatchCallback callback)
156
157 Register *callback* as a code object watcher for the current interpreter.
158 Return an ID which may be passed to :c:func:`PyCode_ClearWatcher`.
159 In case of error (e.g. no more watcher IDs available),
160 return ``-1`` and set an exception.
161
162 .. versionadded:: 3.12
163
164 .. c:function:: int PyCode_ClearWatcher(int watcher_id)
165
166 Clear watcher identified by *watcher_id* previously returned from
167 :c:func:`PyCode_AddWatcher` for the current interpreter.
168 Return ``0`` on success, or ``-1`` and set an exception on error
169 (e.g. if the given *watcher_id* was never registered.)
170
171 .. versionadded:: 3.12
172
173 .. c:type:: PyCodeEvent
174
175 Enumeration of possible code object watcher events:
176 - ``PY_CODE_EVENT_CREATE``
177 - ``PY_CODE_EVENT_DESTROY``
178
179 .. versionadded:: 3.12
180
181 .. c:type:: int (*PyCode_WatchCallback)(PyCodeEvent event, PyCodeObject* co)
182
183 Type of a code object watcher callback function.
184
185 If *event* is ``PY_CODE_EVENT_CREATE``, then the callback is invoked
186 after *co* has been fully initialized. Otherwise, the callback is invoked
187 before the destruction of *co* takes place, so the prior state of *co*
188 can be inspected.
189
190 If *event* is ``PY_CODE_EVENT_DESTROY``, taking a reference in the callback
191 to the about-to-be-destroyed code object will resurrect it and prevent it
192 from being freed at this time. When the resurrected object is destroyed
193 later, any watcher callbacks active at that time will be called again.
194
195 Users of this API should not rely on internal runtime implementation
196 details. Such details may include, but are not limited to, the exact
197 order and timing of creation and destruction of code objects. While
198 changes in these details may result in differences observable by watchers
199 (including whether a callback is invoked or not), it does not change
200 the semantics of the Python code being executed.
201
202 If the callback sets an exception, it must return ``-1``; this exception will
203 be printed as an unraisable exception using :c:func:`PyErr_WriteUnraisable`.
204 Otherwise it should return ``0``.
205
206 There may already be a pending exception set on entry to the callback. In
207 this case, the callback should return ``0`` with the same exception still
208 set. This means the callback may not call any other API that can set an
209 exception unless it saves and clears the exception state first, and restores
210 it before returning.
211
212 .. versionadded:: 3.12
213
214
215 .. c:function:: PyObject *PyCode_Optimize(PyObject *code, PyObject *consts, PyObject *names, PyObject *lnotab_obj)
216
217 This is a :term:`soft deprecated` function that does nothing.
218
219 Prior to Python 3.10, this function would perform basic optimizations to a
220 code object.
221
222 .. versionchanged:: 3.10
223 This function now does nothing.
224
225
226 .. _c_codeobject_flags:
227
228 Code Object Flags
229 -----------------
230
231 Code objects contain a bit-field of flags, which can be retrieved as the
232 :attr:`~codeobject.co_flags` Python attribute (for example using
233 :c:func:`PyObject_GetAttrString`), and set using a *flags* argument to
234 :c:func:`PyUnstable_Code_New` and similar functions.
235
236 Flags whose names start with ``CO_FUTURE_`` correspond to features normally
237 selectable by :ref:`future statements <future>`. These flags can be used in
238 :c:member:`PyCompilerFlags.cf_flags`.
239 Note that many ``CO_FUTURE_`` flags are mandatory in current versions of
240 Python, and setting them has no effect.
241
242 The following flags are available.
243 For their meaning, see the linked documentation of their Python equivalents.
244
245
246 .. list-table::
247 :widths: auto
248 :header-rows: 1
249
250 * * Flag
251 * Meaning
252 * * .. c:macro:: CO_OPTIMIZED
253 * :py:data:`inspect.CO_OPTIMIZED`
254 * * .. c:macro:: CO_NEWLOCALS
255 * :py:data:`inspect.CO_NEWLOCALS`
256 * * .. c:macro:: CO_VARARGS
257 * :py:data:`inspect.CO_VARARGS`
258 * * .. c:macro:: CO_VARKEYWORDS
259 * :py:data:`inspect.CO_VARKEYWORDS`
260 * * .. c:macro:: CO_NESTED
261 * :py:data:`inspect.CO_NESTED`
262 * * .. c:macro:: CO_GENERATOR
263 * :py:data:`inspect.CO_GENERATOR`
264 * * .. c:macro:: CO_COROUTINE
265 * :py:data:`inspect.CO_COROUTINE`
266 * * .. c:macro:: CO_ITERABLE_COROUTINE
267 * :py:data:`inspect.CO_ITERABLE_COROUTINE`
268 * * .. c:macro:: CO_ASYNC_GENERATOR
269 * :py:data:`inspect.CO_ASYNC_GENERATOR`
270 * * .. c:macro:: CO_HAS_DOCSTRING
271 * :py:data:`inspect.CO_HAS_DOCSTRING`
272 * * .. c:macro:: CO_METHOD
273 * :py:data:`inspect.CO_METHOD`
274
275 * * .. c:macro:: CO_FUTURE_DIVISION
276 * no effect (:py:data:`__future__.division`)
277 * * .. c:macro:: CO_FUTURE_ABSOLUTE_IMPORT
278 * no effect (:py:data:`__future__.absolute_import`)
279 * * .. c:macro:: CO_FUTURE_WITH_STATEMENT
280 * no effect (:py:data:`__future__.with_statement`)
281 * * .. c:macro:: CO_FUTURE_PRINT_FUNCTION
282 * no effect (:py:data:`__future__.print_function`)
283 * * .. c:macro:: CO_FUTURE_UNICODE_LITERALS
284 * no effect (:py:data:`__future__.unicode_literals`)
285 * * .. c:macro:: CO_FUTURE_GENERATOR_STOP
286 * no effect (:py:data:`__future__.generator_stop`)
287 * * .. c:macro:: CO_FUTURE_ANNOTATIONS
288 * :py:data:`__future__.annotations`
289
290
291 Extra information
292 -----------------
293
294 To support low-level extensions to frame evaluation, such as external
295 just-in-time compilers, it is possible to attach arbitrary extra data to
296 code objects.
297
298 These functions are part of the unstable C API tier:
299 this functionality is a CPython implementation detail, and the API
300 may change without deprecation warnings.
301
302 .. c:function:: Py_ssize_t _PyEval_RequestCodeExtraIndex(freefunc free)
303 :no-typesetting:
304
305 .. c:function:: Py_ssize_t PyUnstable_Eval_RequestCodeExtraIndex(freefunc free)
306
307 Return a new opaque index value used to adding data to code objects.
308
309 You generally call this function once (per interpreter) and use the result
310 with ``PyCode_GetExtra`` and ``PyCode_SetExtra`` to manipulate
311 data on individual code objects.
312
313 If *free* is not ``NULL``: when a code object is deallocated,
314 *free* will be called on non-``NULL`` data stored under the new index.
315 Use :c:func:`Py_DecRef` when storing :c:type:`PyObject`.
316
317 .. versionadded:: 3.6 as ``_PyEval_RequestCodeExtraIndex``
318
319 .. versionchanged:: 3.12
320
321 Renamed to ``PyUnstable_Eval_RequestCodeExtraIndex``.
322 The old private name is deprecated, but will be available until the API
323 changes.
324
325 .. c:function:: int _PyCode_GetExtra(PyObject *code, Py_ssize_t index, void **extra)
326 :no-typesetting:
327
328 .. c:function:: int PyUnstable_Code_GetExtra(PyObject *code, Py_ssize_t index, void **extra)
329
330 Set *extra* to the extra data stored under the given index.
331 Return 0 on success. Set an exception and return -1 on failure.
332
333 If no data was set under the index, set *extra* to ``NULL`` and return
334 0 without setting an exception.
335
336 .. versionadded:: 3.6 as ``_PyCode_GetExtra``
337
338 .. versionchanged:: 3.12
339
340 Renamed to ``PyUnstable_Code_GetExtra``.
341 The old private name is deprecated, but will be available until the API
342 changes.
343
344 .. c:function:: int _PyCode_SetExtra(PyObject *code, Py_ssize_t index, void *extra)
345 :no-typesetting:
346
347 .. c:function:: int PyUnstable_Code_SetExtra(PyObject *code, Py_ssize_t index, void *extra)
348
349 Set the extra data stored under the given index to *extra*.
350 Return 0 on success. Set an exception and return -1 on failure.
351
352 .. versionadded:: 3.6 as ``_PyCode_SetExtra``
353
354 .. versionchanged:: 3.12
355
356 Renamed to ``PyUnstable_Code_SetExtra``.
357 The old private name is deprecated, but will be available until the API
358 changes.