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, char **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. It is important to note that the argument list may be modified (but 34 the contents of the strings pointed to by the argument list are not). The return 35 value will be ``0`` if the interpreter exits normally (ie, without an 36 exception), ``1`` if the interpreter exits due to an exception, or ``2`` 37 if the parameter list does not represent a valid Python command line. 38 39 Note that if an otherwise unhandled :exc:`SystemExit` is raised, this 40 function will not return ``1``, but exit the process, as long as 41 ``Py_InspectFlag`` is not set. 42 43 44 .. c:function:: int PyRun_AnyFile(FILE *fp, const char *filename) 45 46 This is a simplified interface to :c:func:`PyRun_AnyFileExFlags` below, leaving 47 *closeit* set to ``0`` and *flags* set to *NULL*. 48 49 50 .. c:function:: int PyRun_AnyFileFlags(FILE *fp, const char *filename, PyCompilerFlags *flags) 51 52 This is a simplified interface to :c:func:`PyRun_AnyFileExFlags` below, leaving 53 the *closeit* argument set to ``0``. 54 55 56 .. c:function:: int PyRun_AnyFileEx(FILE *fp, const char *filename, int closeit) 57 58 This is a simplified interface to :c:func:`PyRun_AnyFileExFlags` below, leaving 59 the *flags* argument set to *NULL*. 60 61 62 .. c:function:: int PyRun_AnyFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags) 63 64 If *fp* refers to a file associated with an interactive device (console or 65 terminal input or Unix pseudo-terminal), return the value of 66 :c:func:`PyRun_InteractiveLoop`, otherwise return the result of 67 :c:func:`PyRun_SimpleFile`. If *filename* is *NULL*, this function uses 68 ``"???"`` as the filename. 69 70 71 .. c:function:: int PyRun_SimpleString(const char *command) 72 73 This is a simplified interface to :c:func:`PyRun_SimpleStringFlags` below, 74 leaving the *PyCompilerFlags\** argument set to NULL. 75 76 77 .. c:function:: int PyRun_SimpleStringFlags(const char *command, PyCompilerFlags *flags) 78 79 Executes the Python source code from *command* in the :mod:`__main__` module 80 according to the *flags* argument. If :mod:`__main__` does not already exist, it 81 is created. Returns ``0`` on success or ``-1`` if an exception was raised. If 82 there was an error, there is no way to get the exception information. For the 83 meaning of *flags*, see below. 84 85 Note that if an otherwise unhandled :exc:`SystemExit` is raised, this 86 function will not return ``-1``, but exit the process, as long as 87 ``Py_InspectFlag`` is not set. 88 89 90 .. c:function:: int PyRun_SimpleFile(FILE *fp, const char *filename) 91 92 This is a simplified interface to :c:func:`PyRun_SimpleFileExFlags` below, 93 leaving *closeit* set to ``0`` and *flags* set to *NULL*. 94 95 96 .. c:function:: int PyRun_SimpleFileFlags(FILE *fp, const char *filename, PyCompilerFlags *flags) 97 98 This is a simplified interface to :c:func:`PyRun_SimpleFileExFlags` below, 99 leaving *closeit* set to ``0``. 100 101 102 .. c:function:: int PyRun_SimpleFileEx(FILE *fp, const char *filename, int closeit) 103 104 This is a simplified interface to :c:func:`PyRun_SimpleFileExFlags` below, 105 leaving *flags* set to *NULL*. 106 107 108 .. c:function:: int PyRun_SimpleFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags) 109 110 Similar to :c:func:`PyRun_SimpleStringFlags`, but the Python source code is read 111 from *fp* instead of an in-memory string. *filename* should be the name of the 112 file. If *closeit* is true, the file is closed before PyRun_SimpleFileExFlags 113 returns. 114 115 116 .. c:function:: int PyRun_InteractiveOne(FILE *fp, const char *filename) 117 118 This is a simplified interface to :c:func:`PyRun_InteractiveOneFlags` below, 119 leaving *flags* set to *NULL*. 120 121 122 .. c:function:: int PyRun_InteractiveOneFlags(FILE *fp, const char *filename, PyCompilerFlags *flags) 123 124 Read and execute a single statement from a file associated with an 125 interactive device according to the *flags* argument. The user will be 126 prompted using ``sys.ps1`` and ``sys.ps2``. 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``. Returns ``0`` at EOF. 144 145 146 .. c:function:: struct _node* PyParser_SimpleParseString(const char *str, int start) 147 148 This is a simplified interface to 149 :c:func:`PyParser_SimpleParseStringFlagsFilename` below, leaving *filename* set 150 to *NULL* and *flags* set to ``0``. 151 152 153 .. c:function:: struct _node* PyParser_SimpleParseStringFlags( const char *str, int start, int flags) 154 155 This is a simplified interface to 156 :c:func:`PyParser_SimpleParseStringFlagsFilename` below, leaving *filename* set 157 to *NULL*. 158 159 160 .. c:function:: struct _node* PyParser_SimpleParseStringFlagsFilename( const char *str, const char *filename, int start, int flags) 161 162 Parse Python source code from *str* using the start token *start* according to 163 the *flags* argument. The result can be used to create a code object which can 164 be evaluated efficiently. This is useful if a code fragment must be evaluated 165 many times. 166 167 168 .. c:function:: struct _node* PyParser_SimpleParseFile(FILE *fp, const char *filename, int start) 169 170 This is a simplified interface to :c:func:`PyParser_SimpleParseFileFlags` below, 171 leaving *flags* set to ``0``. 172 173 174 .. c:function:: struct _node* PyParser_SimpleParseFileFlags(FILE *fp, const char *filename, int start, int flags) 175 176 Similar to :c:func:`PyParser_SimpleParseStringFlagsFilename`, but the Python 177 source code is read from *fp* instead of an in-memory string. 178 179 180 .. c:function:: PyObject* PyRun_String(const char *str, int start, PyObject *globals, PyObject *locals) 181 182 This is a simplified interface to :c:func:`PyRun_StringFlags` below, leaving 183 *flags* set to *NULL*. 184 185 186 .. c:function:: PyObject* PyRun_StringFlags(const char *str, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags) 187 188 Execute Python source code from *str* in the context specified by the 189 dictionaries *globals* and *locals* with the compiler flags specified by 190 *flags*. The parameter *start* specifies the start token that should be used to 191 parse the source code. 192 193 Returns the result of executing the code as a Python object, or *NULL* if an 194 exception was raised. 195 196 197 .. c:function:: PyObject* PyRun_File(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals) 198 199 This is a simplified interface to :c:func:`PyRun_FileExFlags` below, leaving 200 *closeit* set to ``0`` and *flags* set to *NULL*. 201 202 203 .. c:function:: PyObject* PyRun_FileEx(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit) 204 205 This is a simplified interface to :c:func:`PyRun_FileExFlags` below, leaving 206 *flags* set to *NULL*. 207 208 209 .. c:function:: PyObject* PyRun_FileFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags) 210 211 This is a simplified interface to :c:func:`PyRun_FileExFlags` below, leaving 212 *closeit* set to ``0``. 213 214 215 .. c:function:: PyObject* PyRun_FileExFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit, PyCompilerFlags *flags) 216 217 Similar to :c:func:`PyRun_StringFlags`, but the Python source code is read from 218 *fp* instead of an in-memory string. *filename* should be the name of the file. 219 If *closeit* is true, the file is closed before :c:func:`PyRun_FileExFlags` 220 returns. 221 222 223 .. c:function:: PyObject* Py_CompileString(const char *str, const char *filename, int start) 224 225 This is a simplified interface to :c:func:`Py_CompileStringFlags` below, leaving 226 *flags* set to *NULL*. 227 228 229 .. c:function:: PyObject* Py_CompileStringFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags) 230 231 Parse and compile the Python source code in *str*, returning the resulting code 232 object. The start token is given by *start*; this can be used to constrain the 233 code which can be compiled and should be :const:`Py_eval_input`, 234 :const:`Py_file_input`, or :const:`Py_single_input`. The filename specified by 235 *filename* is used to construct the code object and may appear in tracebacks or 236 :exc:`SyntaxError` exception messages. This returns *NULL* if the code cannot 237 be parsed or compiled. 238 239 240 .. c:function:: PyObject* PyEval_EvalCode(PyCodeObject *co, PyObject *globals, PyObject *locals) 241 242 This is a simplified interface to :c:func:`PyEval_EvalCodeEx`, with just 243 the code object, and the dictionaries of global and local variables. 244 The other arguments are set to *NULL*. 245 246 247 .. c:function:: PyObject* PyEval_EvalCodeEx(PyCodeObject *co, PyObject *globals, PyObject *locals, PyObject **args, int argcount, PyObject **kws, int kwcount, PyObject **defs, int defcount, PyObject *closure) 248 249 Evaluate a precompiled code object, given a particular environment for its 250 evaluation. This environment consists of dictionaries of global and local 251 variables, arrays of arguments, keywords and defaults, and a closure tuple of 252 cells. 253 254 255 .. c:function:: PyObject* PyEval_EvalFrame(PyFrameObject *f) 256 257 Evaluate an execution frame. This is a simplified interface to 258 PyEval_EvalFrameEx, for backward compatibility. 259 260 261 .. c:function:: PyObject* PyEval_EvalFrameEx(PyFrameObject *f, int throwflag) 262 263 This is the main, unvarnished function of Python interpretation. It is 264 literally 2000 lines long. The code object associated with the execution 265 frame *f* is executed, interpreting bytecode and executing calls as needed. 266 The additional *throwflag* parameter can mostly be ignored - if true, then 267 it causes an exception to immediately be thrown; this is used for the 268 :meth:`~generator.throw` methods of generator objects. 269 270 271 .. c:function:: int PyEval_MergeCompilerFlags(PyCompilerFlags *cf) 272 273 This function changes the flags of the current evaluation frame, and returns 274 true on success, false on failure. 275 276 277 .. c:var:: int Py_eval_input 278 279 .. index:: single: Py_CompileString() 280 281 The start symbol from the Python grammar for isolated expressions; for use with 282 :c:func:`Py_CompileString`. 283 284 285 .. c:var:: int Py_file_input 286 287 .. index:: single: Py_CompileString() 288 289 The start symbol from the Python grammar for sequences of statements as read 290 from a file or other source; for use with :c:func:`Py_CompileString`. This is 291 the symbol to use when compiling arbitrarily long Python source code. 292 293 294 .. c:var:: int Py_single_input 295 296 .. index:: single: Py_CompileString() 297 298 The start symbol from the Python grammar for a single statement; for use with 299 :c:func:`Py_CompileString`. This is the symbol used for the interactive 300 interpreter loop. 301 302 303 .. c:type:: struct PyCompilerFlags 304 305 This is the structure used to hold compiler flags. In cases where code is only 306 being compiled, it is passed as ``int flags``, and in cases where code is being 307 executed, it is passed as ``PyCompilerFlags *flags``. In this case, ``from 308 __future__ import`` can modify *flags*. 309 310 Whenever ``PyCompilerFlags *flags`` is *NULL*, :attr:`cf_flags` is treated as 311 equal to ``0``, and any modification due to ``from __future__ import`` is 312 discarded. :: 313 314 struct PyCompilerFlags { 315 int cf_flags; 316 } 317 318 319 .. c:var:: int CO_FUTURE_DIVISION 320 321 This bit can be set in *flags* to cause division operator ``/`` to be 322 interpreted as "true division" according to :pep:`238`. 323 324
