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