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 or a negative 145 number upon failure. 146 147 148 .. c:var:: int (*PyOS_InputHook)(void) 149 150 Can be set to point to a function with the prototype 151 ``int func(void)``. The function will be called when Python's 152 interpreter prompt is about to become idle and wait for user input 153 from the terminal. The return value is ignored. Overriding this 154 hook can be used to integrate the interpreter's prompt with other 155 event loops, as done in the :file:`Modules/_tkinter.c` in the 156 Python source code. 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 179 .. c:function:: struct _node* PyParser_SimpleParseString(const char *str, int start) 180 181 This is a simplified interface to 182 :c:func:`PyParser_SimpleParseStringFlagsFilename` below, leaving *filename* set 183 to *NULL* and *flags* set to ``0``. 184 185 186 .. c:function:: struct _node* PyParser_SimpleParseStringFlags( const char *str, int start, int flags) 187 188 This is a simplified interface to 189 :c:func:`PyParser_SimpleParseStringFlagsFilename` below, leaving *filename* set 190 to *NULL*. 191 192 193 .. c:function:: struct _node* PyParser_SimpleParseStringFlagsFilename( const char *str, const char *filename, int start, int flags) 194 195 Parse Python source code from *str* using the start token *start* according to 196 the *flags* argument. The result can be used to create a code object which can 197 be evaluated efficiently. This is useful if a code fragment must be evaluated 198 many times. *filename* is decoded from the filesystem encoding 199 (:func:`sys.getfilesystemencoding`). 200 201 202 .. c:function:: struct _node* PyParser_SimpleParseFile(FILE *fp, const char *filename, int start) 203 204 This is a simplified interface to :c:func:`PyParser_SimpleParseFileFlags` below, 205 leaving *flags* set to ``0``. 206 207 208 .. c:function:: struct _node* PyParser_SimpleParseFileFlags(FILE *fp, const char *filename, int start, int flags) 209 210 Similar to :c:func:`PyParser_SimpleParseStringFlagsFilename`, but the Python 211 source code is read from *fp* instead of an in-memory string. 212 213 214 .. c:function:: PyObject* PyRun_String(const char *str, int start, PyObject *globals, PyObject *locals) 215 216 This is a simplified interface to :c:func:`PyRun_StringFlags` below, leaving 217 *flags* set to *NULL*. 218 219 220 .. c:function:: PyObject* PyRun_StringFlags(const char *str, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags) 221 222 Execute Python source code from *str* in the context specified by the 223 objects *globals* and *locals* with the compiler flags specified by 224 *flags*. *globals* must be a dictionary; *locals* can be any object 225 that implements the mapping protocol. The parameter *start* specifies 226 the start token that should be used to parse the source code. 227 228 Returns the result of executing the code as a Python object, or *NULL* if an 229 exception was raised. 230 231 232 .. c:function:: PyObject* PyRun_File(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals) 233 234 This is a simplified interface to :c:func:`PyRun_FileExFlags` below, leaving 235 *closeit* set to ``0`` and *flags* set to *NULL*. 236 237 238 .. c:function:: PyObject* PyRun_FileEx(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit) 239 240 This is a simplified interface to :c:func:`PyRun_FileExFlags` below, leaving 241 *flags* set to *NULL*. 242 243 244 .. c:function:: PyObject* PyRun_FileFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags) 245 246 This is a simplified interface to :c:func:`PyRun_FileExFlags` below, leaving 247 *closeit* set to ``0``. 248 249 250 .. c:function:: PyObject* PyRun_FileExFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit, PyCompilerFlags *flags) 251 252 Similar to :c:func:`PyRun_StringFlags`, but the Python source code is read from 253 *fp* instead of an in-memory string. *filename* should be the name of the file, 254 it is decoded from the filesystem encoding (:func:`sys.getfilesystemencoding`). 255 If *closeit* is true, the file is closed before :c:func:`PyRun_FileExFlags` 256 returns. 257 258 259 .. c:function:: PyObject* Py_CompileString(const char *str, const char *filename, int start) 260 261 This is a simplified interface to :c:func:`Py_CompileStringFlags` below, leaving 262 *flags* set to *NULL*. 263 264 265 .. c:function:: PyObject* Py_CompileStringFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags) 266 267 This is a simplified interface to :c:func:`Py_CompileStringExFlags` below, with 268 *optimize* set to ``-1``. 269 270 271 .. c:function:: PyObject* Py_CompileStringObject(const char *str, PyObject *filename, int start, PyCompilerFlags *flags, int optimize) 272 273 Parse and compile the Python source code in *str*, returning the resulting code 274 object. The start token is given by *start*; this can be used to constrain the 275 code which can be compiled and should be :const:`Py_eval_input`, 276 :const:`Py_file_input`, or :const:`Py_single_input`. The filename specified by 277 *filename* is used to construct the code object and may appear in tracebacks or 278 :exc:`SyntaxError` exception messages. This returns *NULL* if the code 279 cannot be parsed or compiled. 280 281 The integer *optimize* specifies the optimization level of the compiler; a 282 value of ``-1`` selects the optimization level of the interpreter as given by 283 :option:`-O` options. Explicit levels are ``0`` (no optimization; 284 ``__debug__`` is true), ``1`` (asserts are removed, ``__debug__`` is false) 285 or ``2`` (docstrings are removed too). 286 287 .. versionadded:: 3.4 288 289 290 .. c:function:: PyObject* Py_CompileStringExFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags, int optimize) 291 292 Like :c:func:`Py_CompileStringObject`, but *filename* is a byte string 293 decoded from the filesystem encoding (:func:`os.fsdecode`). 294 295 .. versionadded:: 3.2 296 297 .. c:function:: PyObject* PyEval_EvalCode(PyObject *co, PyObject *globals, PyObject *locals) 298 299 This is a simplified interface to :c:func:`PyEval_EvalCodeEx`, with just 300 the code object, and global and local variables. The other arguments are 301 set to *NULL*. 302 303 304 .. 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) 305 306 Evaluate a precompiled code object, given a particular environment for its 307 evaluation. This environment consists of a dictionary of global variables, 308 a mapping object of local variables, arrays of arguments, keywords and 309 defaults, a dictionary of default values for :ref:`keyword-only 310 <keyword-only_parameter>` arguments and a closure tuple of cells. 311 312 313 .. c:type:: PyFrameObject 314 315 The C structure of the objects used to describe frame objects. The 316 fields of this type are subject to change at any time. 317 318 319 .. c:function:: PyObject* PyEval_EvalFrame(PyFrameObject *f) 320 321 Evaluate an execution frame. This is a simplified interface to 322 :c:func:`PyEval_EvalFrameEx`, for backward compatibility. 323 324 325 .. c:function:: PyObject* PyEval_EvalFrameEx(PyFrameObject *f, int throwflag) 326 327 This is the main, unvarnished function of Python interpretation. It is 328 literally 2000 lines long. The code object associated with the execution 329 frame *f* is executed, interpreting bytecode and executing calls as needed. 330 The additional *throwflag* parameter can mostly be ignored - if true, then 331 it causes an exception to immediately be thrown; this is used for the 332 :meth:`~generator.throw` methods of generator objects. 333 334 .. versionchanged:: 3.4 335 This function now includes a debug assertion to help ensure that it 336 does not silently discard an active exception. 337 338 339 .. c:function:: int PyEval_MergeCompilerFlags(PyCompilerFlags *cf) 340 341 This function changes the flags of the current evaluation frame, and returns 342 true on success, false on failure. 343 344 345 .. c:var:: int Py_eval_input 346 347 .. index:: single: Py_CompileString() 348 349 The start symbol from the Python grammar for isolated expressions; for use with 350 :c:func:`Py_CompileString`. 351 352 353 .. c:var:: int Py_file_input 354 355 .. index:: single: Py_CompileString() 356 357 The start symbol from the Python grammar for sequences of statements as read 358 from a file or other source; for use with :c:func:`Py_CompileString`. This is 359 the symbol to use when compiling arbitrarily long Python source code. 360 361 362 .. c:var:: int Py_single_input 363 364 .. index:: single: Py_CompileString() 365 366 The start symbol from the Python grammar for a single statement; for use with 367 :c:func:`Py_CompileString`. This is the symbol used for the interactive 368 interpreter loop. 369 370 371 .. c:type:: struct PyCompilerFlags 372 373 This is the structure used to hold compiler flags. In cases where code is only 374 being compiled, it is passed as ``int flags``, and in cases where code is being 375 executed, it is passed as ``PyCompilerFlags *flags``. In this case, ``from 376 __future__ import`` can modify *flags*. 377 378 Whenever ``PyCompilerFlags *flags`` is *NULL*, :attr:`cf_flags` is treated as 379 equal to ``0``, and any modification due to ``from __future__ import`` is 380 discarded. :: 381 382 struct PyCompilerFlags { 383 int cf_flags; 384 } 385 386 387 .. c:var:: int CO_FUTURE_DIVISION 388 389 This bit can be set in *flags* to cause division operator ``/`` to be 390 interpreted as "true division" according to :pep:`238`. 391
