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