Debian Codegraph @

Doc/c-api/veryhigh.rst

raw
1 .. highlight:: c
2
3
4 .. _veryhigh:
5
6 *************************
7 The Very High Level Layer
8 *************************
9
10 The functions in this chapter will let you execute Python source code given in a
11 file or a buffer, but they will not let you interact in a more detailed way with
12 the interpreter.
13
14 Several of these functions accept a start symbol from the grammar as a
15 parameter. The available start symbols are :c:data:`Py_eval_input`,
16 :c:data:`Py_file_input`, :c:data:`Py_single_input`, and
17 :c:data:`Py_func_type_input`. These are described following the functions
18 which accept them as parameters.
19
20 Note also that several of these functions take :c:expr:`FILE*` parameters. One
21 particular issue which needs to be handled carefully is that the :c:type:`FILE`
22 structure for different C libraries can be different and incompatible. Under
23 Windows (at least), it is possible for dynamically linked extensions to actually
24 use different libraries, so care should be taken that :c:expr:`FILE*` parameters
25 are only passed to these functions if it is certain that they were created by
26 the same library that the Python runtime is using.
27
28
29 .. c:function:: int PyRun_AnyFile(FILE *fp, const char *filename)
30
31 This is a simplified interface to :c:func:`PyRun_AnyFileExFlags` below, leaving
32 *closeit* set to ``0`` and *flags* set to ``NULL``.
33
34
35 .. c:function:: int PyRun_AnyFileFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)
36
37 This is a simplified interface to :c:func:`PyRun_AnyFileExFlags` below, leaving
38 the *closeit* argument set to ``0``.
39
40
41 .. c:function:: int PyRun_AnyFileEx(FILE *fp, const char *filename, int closeit)
42
43 This is a simplified interface to :c:func:`PyRun_AnyFileExFlags` below, leaving
44 the *flags* argument set to ``NULL``.
45
46
47 .. c:function:: int PyRun_AnyFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)
48
49 If *fp* refers to a file associated with an interactive device (console or
50 terminal input or Unix pseudo-terminal), return the value of
51 :c:func:`PyRun_InteractiveLoop`, otherwise return the result of
52 :c:func:`PyRun_SimpleFile`. *filename* is decoded from the filesystem
53 encoding (:func:`sys.getfilesystemencoding`). If *filename* is ``NULL``, this
54 function uses ``"???"`` as the filename.
55 If *closeit* is true, the file is closed before
56 ``PyRun_SimpleFileExFlags()`` returns.
57
58
59 .. c:function:: int PyRun_SimpleString(const char *command)
60
61 This is a simplified interface to :c:func:`PyRun_SimpleStringFlags` below,
62 leaving the :c:struct:`PyCompilerFlags`\* argument set to ``NULL``.
63
64
65 .. c:function:: int PyRun_SimpleStringFlags(const char *command, PyCompilerFlags *flags)
66
67 Executes the Python source code from *command* in the :mod:`__main__` module
68 according to the *flags* argument. If :mod:`__main__` does not already exist, it
69 is created. Returns ``0`` on success or ``-1`` if an exception was raised. If
70 there was an error, there is no way to get the exception information. For the
71 meaning of *flags*, see below.
72
73 Note that if an otherwise unhandled :exc:`SystemExit` is raised, this
74 function will not return ``-1``, but exit the process, as long as
75 :c:member:`PyConfig.inspect` is zero.
76
77
78 .. c:function:: int PyRun_SimpleFile(FILE *fp, const char *filename)
79
80 This is a simplified interface to :c:func:`PyRun_SimpleFileExFlags` below,
81 leaving *closeit* set to ``0`` and *flags* set to ``NULL``.
82
83
84 .. c:function:: int PyRun_SimpleFileEx(FILE *fp, const char *filename, int closeit)
85
86 This is a simplified interface to :c:func:`PyRun_SimpleFileExFlags` below,
87 leaving *flags* set to ``NULL``.
88
89
90 .. c:function:: int PyRun_SimpleFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)
91
92 Similar to :c:func:`PyRun_SimpleStringFlags`, but the Python source code is read
93 from *fp* instead of an in-memory string. *filename* should be the name of
94 the file, it is decoded from :term:`filesystem encoding and error handler`.
95 If *closeit* is true, the file is closed before
96 ``PyRun_SimpleFileExFlags()`` returns.
97
98 .. note::
99 On Windows, *fp* should be opened as binary mode (e.g. ``fopen(filename, "rb")``).
100 Otherwise, Python may not handle script file with LF line ending correctly.
101
102
103 .. c:function:: int PyRun_InteractiveOneObject(FILE *fp, PyObject *filename, PyCompilerFlags *flags)
104
105 Read and execute a single statement from a file associated with an
106 interactive device according to the *flags* argument. The user will be
107 prompted using ``sys.ps1`` and ``sys.ps2``. *filename* must be a Python
108 :class:`str` object.
109
110 Returns ``0`` when the input was
111 executed successfully, ``-1`` if there was an exception, or an error code
112 from the :file:`errcode.h` include file distributed as part of Python if
113 there was a parse error. (Note that :file:`errcode.h` is not included by
114 :file:`Python.h`, so must be included specifically if needed.)
115
116
117 .. c:function:: int PyRun_InteractiveOne(FILE *fp, const char *filename)
118
119 This is a simplified interface to :c:func:`PyRun_InteractiveOneFlags` below,
120 leaving *flags* set to ``NULL``.
121
122
123 .. c:function:: int PyRun_InteractiveOneFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)
124
125 Similar to :c:func:`PyRun_InteractiveOneObject`, but *filename* is a
126 :c:expr:`const char*`, which is decoded from the
127 :term:`filesystem encoding and error handler`.
128
129
130 .. c:function:: int PyRun_InteractiveLoop(FILE *fp, const char *filename)
131
132 This is a simplified interface to :c:func:`PyRun_InteractiveLoopFlags` below,
133 leaving *flags* set to ``NULL``.
134
135
136 .. c:function:: int PyRun_InteractiveLoopFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)
137
138 Read and execute statements from a file associated with an interactive device
139 until EOF is reached. The user will be prompted using ``sys.ps1`` and
140 ``sys.ps2``. *filename* is decoded from the :term:`filesystem encoding and
141 error handler`. Returns ``0`` at EOF or a negative number upon failure.
142
143
144 .. c:var:: int (*PyOS_InputHook)(void)
145
146 Can be set to point to a function with the prototype
147 ``int func(void)``. The function will be called when Python's
148 interpreter prompt is about to become idle and wait for user input
149 from the terminal. The return value is ignored. Overriding this
150 hook can be used to integrate the interpreter's prompt with other
151 event loops, as done in :file:`Modules/_tkinter.c` in the
152 Python source code.
153
154 .. versionchanged:: 3.12
155 This function is only called from the
156 :ref:`main interpreter <sub-interpreter-support>`.
157
158
159 .. c:var:: char* (*PyOS_ReadlineFunctionPointer)(FILE *, FILE *, const char *)
160
161 Can be set to point to a function with the prototype
162 ``char *func(FILE *stdin, FILE *stdout, char *prompt)``,
163 overriding the default function used to read a single line of input
164 at the interpreter's prompt. The function is expected to output
165 the string *prompt* if it's not ``NULL``, and then read a line of
166 input from the provided standard input file, returning the
167 resulting string. For example, The :mod:`readline` module sets
168 this hook to provide line-editing and tab-completion features.
169
170 The result must be a string allocated by :c:func:`PyMem_RawMalloc` or
171 :c:func:`PyMem_RawRealloc`, or ``NULL`` if an error occurred.
172
173 .. versionchanged:: 3.4
174 The result must be allocated by :c:func:`PyMem_RawMalloc` or
175 :c:func:`PyMem_RawRealloc`, instead of being allocated by
176 :c:func:`PyMem_Malloc` or :c:func:`PyMem_Realloc`.
177
178 .. versionchanged:: 3.12
179 This function is only called from the
180 :ref:`main interpreter <sub-interpreter-support>`.
181
182 .. c:function:: PyObject* PyRun_String(const char *str, int start, PyObject *globals, PyObject *locals)
183
184 This is a simplified interface to :c:func:`PyRun_StringFlags` below, leaving
185 *flags* set to ``NULL``.
186
187
188 .. c:function:: PyObject* PyRun_StringFlags(const char *str, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)
189
190 Execute Python source code from *str* in the context specified by the
191 objects *globals* and *locals* with the compiler flags specified by
192 *flags*. *globals* must be a dictionary; *locals* can be any object
193 that implements the mapping protocol. The parameter *start* specifies
194 the start symbol and must be one of the :ref:`available start symbols <start-symbols>`.
195
196 Returns the result of executing the code as a Python object, or ``NULL`` if an
197 exception was raised.
198
199
200 .. c:function:: PyObject* PyRun_File(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals)
201
202 This is a simplified interface to :c:func:`PyRun_FileExFlags` below, leaving
203 *closeit* set to ``0`` and *flags* set to ``NULL``.
204
205
206 .. c:function:: PyObject* PyRun_FileEx(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit)
207
208 This is a simplified interface to :c:func:`PyRun_FileExFlags` below, leaving
209 *flags* set to ``NULL``.
210
211
212 .. c:function:: PyObject* PyRun_FileFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)
213
214 This is a simplified interface to :c:func:`PyRun_FileExFlags` below, leaving
215 *closeit* set to ``0``.
216
217
218 .. c:function:: PyObject* PyRun_FileExFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit, PyCompilerFlags *flags)
219
220 Similar to :c:func:`PyRun_StringFlags`, but the Python source code is read from
221 *fp* instead of an in-memory string. *filename* should be the name of the file,
222 it is decoded from the :term:`filesystem encoding and error handler`.
223 If *closeit* is true, the file is closed before :c:func:`PyRun_FileExFlags`
224 returns.
225
226
227 .. c:function:: PyObject* Py_CompileString(const char *str, const char *filename, int start)
228
229 This is a simplified interface to :c:func:`Py_CompileStringFlags` below, leaving
230 *flags* set to ``NULL``.
231
232
233 .. c:function:: PyObject* Py_CompileStringFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags)
234
235 This is a simplified interface to :c:func:`Py_CompileStringExFlags` below, with
236 *optimize* set to ``-1``.
237
238
239 .. c:function:: PyObject* Py_CompileStringObject(const char *str, PyObject *filename, int start, PyCompilerFlags *flags, int optimize)
240
241 Parse and compile the Python source code in *str*, returning the resulting code
242 object. The start symbol is given by *start*; this can be used to constrain the
243 code which can be compiled and should be :ref:`available start symbols
244 <start-symbols>`. The filename specified by
245 *filename* is used to construct the code object and may appear in tracebacks or
246 :exc:`SyntaxError` exception messages. This returns ``NULL`` if the code
247 cannot be parsed or compiled.
248
249 The integer *optimize* specifies the optimization level of the compiler; a
250 value of ``-1`` selects the optimization level of the interpreter as given by
251 :option:`-O` options. Explicit levels are ``0`` (no optimization;
252 ``__debug__`` is true), ``1`` (asserts are removed, ``__debug__`` is false)
253 or ``2`` (docstrings are removed too).
254
255 .. versionadded:: 3.4
256
257
258 .. c:function:: PyObject* Py_CompileStringExFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags, int optimize)
259
260 Like :c:func:`Py_CompileStringObject`, but *filename* is a byte string
261 decoded from the :term:`filesystem encoding and error handler`.
262
263 .. versionadded:: 3.2
264
265 .. c:function:: PyObject* PyEval_EvalCode(PyObject *co, PyObject *globals, PyObject *locals)
266
267 This is a simplified interface to :c:func:`PyEval_EvalCodeEx`, with just
268 the code object, and global and local variables. The other arguments are
269 set to ``NULL``.
270
271
272 .. c:function:: PyObject* PyEval_EvalCodeEx(PyObject *co, PyObject *globals, PyObject *locals, PyObject *const *args, int argcount, PyObject *const *kws, int kwcount, PyObject *const *defs, int defcount, PyObject *kwdefs, PyObject *closure)
273
274 Evaluate a precompiled code object, given a particular environment for its
275 evaluation. This environment consists of a dictionary of global variables,
276 a mapping object of local variables, arrays of arguments, keywords and
277 defaults, a dictionary of default values for :ref:`keyword-only
278 <keyword-only_parameter>` arguments and a closure tuple of cells.
279
280
281 .. c:function:: PyObject* PyEval_EvalFrame(PyFrameObject *f)
282
283 Evaluate an execution frame. This is a simplified interface to
284 :c:func:`PyEval_EvalFrameEx`, for backward compatibility.
285
286
287 .. c:function:: PyObject* PyEval_EvalFrameEx(PyFrameObject *f, int throwflag)
288
289 This is the main, unvarnished function of Python interpretation. The code
290 object associated with the execution frame *f* is executed, interpreting
291 bytecode and executing calls as needed. The additional *throwflag*
292 parameter can mostly be ignored - if true, then it causes an exception
293 to immediately be thrown; this is used for the :meth:`~generator.throw`
294 methods of generator objects.
295
296 .. versionchanged:: 3.4
297 This function now includes a debug assertion to help ensure that it
298 does not silently discard an active exception.
299
300
301 .. c:function:: int PyEval_MergeCompilerFlags(PyCompilerFlags *cf)
302
303 This function changes the flags of the current evaluation frame, and returns
304 true on success, false on failure.
305
306
307 .. c:struct:: PyCompilerFlags
308
309 This is the structure used to hold compiler flags. In cases where code is only
310 being compiled, it is passed as ``int flags``, and in cases where code is being
311 executed, it is passed as ``PyCompilerFlags *flags``. In this case, ``from
312 __future__ import`` can modify *flags*.
313
314 Whenever ``PyCompilerFlags *flags`` is ``NULL``, :c:member:`~PyCompilerFlags.cf_flags` is treated as
315 equal to ``0``, and any modification due to ``from __future__ import`` is
316 discarded.
317
318 .. c:member:: int cf_flags
319
320 Compiler flags.
321
322 .. c:member:: int cf_feature_version
323
324 *cf_feature_version* is the minor Python version. It should be
325 initialized to ``PY_MINOR_VERSION``.
326
327 The field is ignored by default, it is used if and only if
328 ``PyCF_ONLY_AST`` flag is set in :c:member:`~PyCompilerFlags.cf_flags`.
329
330 .. versionchanged:: 3.8
331 Added *cf_feature_version* field.
332
333 The available compiler flags are accessible as macros:
334
335 .. c:namespace:: NULL
336
337 .. c:macro:: PyCF_ALLOW_TOP_LEVEL_AWAIT
338 PyCF_ONLY_AST
339 PyCF_OPTIMIZED_AST
340 PyCF_TYPE_COMMENTS
341
342 See :ref:`compiler flags <ast-compiler-flags>` in documentation of the
343 :py:mod:`!ast` Python module, which exports these constants under
344 the same names.
345
346 The "``PyCF``" flags above can be combined with "``CO_FUTURE``" flags such
347 as :c:macro:`CO_FUTURE_ANNOTATIONS` to enable features normally
348 selectable using :ref:`future statements <future>`.
349 See :ref:`c_codeobject_flags` for a complete list.
350
351
352 .. _start-symbols:
353
354 Available start symbols
355 ^^^^^^^^^^^^^^^^^^^^^^^
356
357
358 .. c:var:: int Py_eval_input
359
360 .. index:: single: Py_CompileString (C function)
361
362 The start symbol from the Python grammar for isolated expressions; for use with
363 :c:func:`Py_CompileString`.
364
365
366 .. c:var:: int Py_file_input
367
368 .. index:: single: Py_CompileString (C function)
369
370 The start symbol from the Python grammar for sequences of statements as read
371 from a file or other source; for use with :c:func:`Py_CompileString`. This is
372 the symbol to use when compiling arbitrarily long Python source code.
373
374
375 .. c:var:: int Py_single_input
376
377 .. index:: single: Py_CompileString (C function)
378
379 The start symbol from the Python grammar for a single statement; for use with
380 :c:func:`Py_CompileString`. This is the symbol used for the interactive
381 interpreter loop.
382
383
384 .. c:var:: int Py_func_type_input
385
386 .. index:: single: Py_CompileString (C function)
387
388 The start symbol from the Python grammar for a function type; for use with
389 :c:func:`Py_CompileString`. This is used to parse "signature type comments"
390 from :pep:`484`.
391
392 This requires the :c:macro:`PyCF_ONLY_AST` flag to be set.
393
394 .. seealso::
395 * :py:class:`ast.FunctionType`
396 * :pep:`484`
397
398 .. versionadded:: 3.8
399
400
401 Stack Effects
402 ^^^^^^^^^^^^^
403
404 .. seealso::
405 :py:func:`dis.stack_effect`
406
407
408 .. c:macro:: PY_INVALID_STACK_EFFECT
409
410 Sentinel value representing an invalid stack effect.
411
412 This is currently equivalent to ``INT_MAX``.
413
414 .. versionadded:: 3.8
415
416
417 .. c:function:: int PyCompile_OpcodeStackEffect(int opcode, int oparg)
418
419 Compute the stack effect of *opcode* with argument *oparg*.
420
421 On success, this function returns the stack effect; on failure, this
422 returns :c:macro:`PY_INVALID_STACK_EFFECT`.
423
424 .. versionadded:: 3.4
425
426
427 .. c:function:: int PyCompile_OpcodeStackEffectWithJump(int opcode, int oparg, int jump)
428
429 Similar to :c:func:`PyCompile_OpcodeStackEffect`, but don't include the
430 stack effect of jumping if *jump* is zero.
431
432 If *jump* is ``0``, this will not include the stack effect of jumping, but
433 if *jump* is ``1`` or ``-1``, this will include it.
434
435 On success, this function returns the stack effect; on failure, this
436 returns :c:macro:`PY_INVALID_STACK_EFFECT`.
437
438 .. versionadded:: 3.8