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