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