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 :ctype:`FILE\*` parameters.  On

    20 particular issue which needs to be handled carefully is that the :ctype:`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 :ctype:`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 .. cfunction:: 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 :cfunc:`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 the integer passed to the :func:`sys.exit` function, ``1`` if the

    36    interpreter exits due to an exception, or ``2`` if the parameter list does not

    37    represent a valid Python command line.

    38 

    39 

    40 .. cfunction:: int PyRun_AnyFile(FILE *fp, const char *filename)

    41 

    42    This is a simplified interface to :cfunc:`PyRun_AnyFileExFlags` below, leaving

    43    *closeit* set to ``0`` and *flags* set to *NULL*.

    44 

    45 

    46 .. cfunction:: int PyRun_AnyFileFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)

    47 

    48    This is a simplified interface to :cfunc:`PyRun_AnyFileExFlags` below, leaving

    49    the *closeit* argument set to ``0``.

    50 

    51 

    52 .. cfunction:: int PyRun_AnyFileEx(FILE *fp, const char *filename, int closeit)

    53 

    54    This is a simplified interface to :cfunc:`PyRun_AnyFileExFlags` below, leaving

    55    the *flags* argument set to *NULL*.

    56 

    57 

    58 .. cfunction:: int PyRun_AnyFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)

    59 

    60    If *fp* refers to a file associated with an interactive device (console or

    61    terminal input or Unix pseudo-terminal), return the value of

    62    :cfunc:`PyRun_InteractiveLoop`, otherwise return the result of

    63    :cfunc:`PyRun_SimpleFile`.  If *filename* is *NULL*, this function uses

    64    ``"???"`` as the filename.

    65 

    66 

    67 .. cfunction:: int PyRun_SimpleString(const char *command)

    68 

    69    This is a simplified interface to :cfunc:`PyRun_SimpleStringFlags` below,

    70    leaving the *PyCompilerFlags\** argument set to NULL.

    71 

    72 

    73 .. cfunction:: int PyRun_SimpleStringFlags(const char *command, PyCompilerFlags *flags)

    74 

    75    Executes the Python source code from *command* in the :mod:`__main__` module

    76    according to the *flags* argument. If :mod:`__main__` does not already exist, it

    77    is created.  Returns ``0`` on success or ``-1`` if an exception was raised.  If

    78    there was an error, there is no way to get the exception information. For the

    79    meaning of *flags*, see below.

    80 

    81 

    82 .. cfunction:: int PyRun_SimpleFile(FILE *fp, const char *filename)

    83 

    84    This is a simplified interface to :cfunc:`PyRun_SimpleFileExFlags` below,

    85    leaving *closeit* set to ``0`` and *flags* set to *NULL*.

    86 

    87 

    88 .. cfunction:: int PyRun_SimpleFileFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)

    89 

    90    This is a simplified interface to :cfunc:`PyRun_SimpleFileExFlags` below,

    91    leaving *closeit* set to ``0``.

    92 

    93 

    94 .. cfunction:: int PyRun_SimpleFileEx(FILE *fp, const char *filename, int closeit)

    95 

    96    This is a simplified interface to :cfunc:`PyRun_SimpleFileExFlags` below,

    97    leaving *flags* set to *NULL*.

    98 

    99 

   100 .. cfunction:: int PyRun_SimpleFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)

   101 

   102    Similar to :cfunc:`PyRun_SimpleStringFlags`, but the Python source code is read

   103    from *fp* instead of an in-memory string. *filename* should be the name of the

   104    file.  If *closeit* is true, the file is closed before PyRun_SimpleFileExFlags

   105    returns.

   106 

   107 

   108 .. cfunction:: int PyRun_InteractiveOne(FILE *fp, const char *filename)

   109 

   110    This is a simplified interface to :cfunc:`PyRun_InteractiveOneFlags` below,

   111    leaving *flags* set to *NULL*.

   112 

   113 

   114 .. cfunction:: int PyRun_InteractiveOneFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)

   115 

   116    Read and execute a single statement from a file associated with an interactive

   117    device according to the *flags* argument.  If *filename* is *NULL*, ``"???"`` is

   118    used instead.  The user will be prompted using ``sys.ps1`` and ``sys.ps2``.

   119    Returns ``0`` when the input was executed successfully, ``-1`` if there was an

   120    exception, or an error code from the :file:`errcode.h` include file distributed

   121    as part of Python if there was a parse error.  (Note that :file:`errcode.h` is

   122    not included by :file:`Python.h`, so must be included specifically if needed.)

   123 

   124 

   125 .. cfunction:: int PyRun_InteractiveLoop(FILE *fp, const char *filename)

   126 

   127    This is a simplified interface to :cfunc:`PyRun_InteractiveLoopFlags` below,

   128    leaving *flags* set to *NULL*.

   129 

   130 

   131 .. cfunction:: int PyRun_InteractiveLoopFlags(FILE *fp,  const char *filename, PyCompilerFlags *flags)

   132 

   133    Read and execute statements from a file associated with an interactive device

   134    until EOF is reached.  If *filename* is *NULL*, ``"???"`` is used instead.  The

   135    user will be prompted using ``sys.ps1`` and ``sys.ps2``.  Returns ``0`` at EOF.

   136 

   137 

   138 .. cfunction:: struct _node* PyParser_SimpleParseString(const char *str, int start)

   139 

   140    This is a simplified interface to

   141    :cfunc:`PyParser_SimpleParseStringFlagsFilename` below, leaving  *filename* set

   142    to *NULL* and *flags* set to ``0``.

   143 

   144 

   145 .. cfunction:: struct _node* PyParser_SimpleParseStringFlags( const char *str, int start, int flags)

   146 

   147    This is a simplified interface to

   148    :cfunc:`PyParser_SimpleParseStringFlagsFilename` below, leaving  *filename* set

   149    to *NULL*.

   150 

   151 

   152 .. cfunction:: struct _node* PyParser_SimpleParseStringFlagsFilename( const char *str, const char *filename, int start, int flags)

   153 

   154    Parse Python source code from *str* using the start token *start* according to

   155    the *flags* argument.  The result can be used to create a code object which can

   156    be evaluated efficiently. This is useful if a code fragment must be evaluated

   157    many times.

   158 

   159 

   160 .. cfunction:: struct _node* PyParser_SimpleParseFile(FILE *fp, const char *filename, int start)

   161 

   162    This is a simplified interface to :cfunc:`PyParser_SimpleParseFileFlags` below,

   163    leaving *flags* set to ``0``

   164 

   165 

   166 .. cfunction:: struct _node* PyParser_SimpleParseFileFlags(FILE *fp, const char *filename, int start, int flags)

   167 

   168    Similar to :cfunc:`PyParser_SimpleParseStringFlagsFilename`, but the Python

   169    source code is read from *fp* instead of an in-memory string.

   170 

   171 

   172 .. cfunction:: PyObject* PyRun_String(const char *str, int start, PyObject *globals, PyObject *locals)

   173 

   174    This is a simplified interface to :cfunc:`PyRun_StringFlags` below, leaving

   175    *flags* set to *NULL*.

   176 

   177 

   178 .. cfunction:: PyObject* PyRun_StringFlags(const char *str, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)

   179 

   180    Execute Python source code from *str* in the context specified by the

   181    dictionaries *globals* and *locals* with the compiler flags specified by

   182    *flags*.  The parameter *start* specifies the start token that should be used to

   183    parse the source code.

   184 

   185    Returns the result of executing the code as a Python object, or *NULL* if an

   186    exception was raised.

   187 

   188 

   189 .. cfunction:: PyObject* PyRun_File(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals)

   190 

   191    This is a simplified interface to :cfunc:`PyRun_FileExFlags` below, leaving

   192    *closeit* set to ``0`` and *flags* set to *NULL*.

   193 

   194 

   195 .. cfunction:: PyObject* PyRun_FileEx(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit)

   196 

   197    This is a simplified interface to :cfunc:`PyRun_FileExFlags` below, leaving

   198    *flags* set to *NULL*.

   199 

   200 

   201 .. cfunction:: PyObject* PyRun_FileFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)

   202 

   203    This is a simplified interface to :cfunc:`PyRun_FileExFlags` below, leaving

   204    *closeit* set to ``0``.

   205 

   206 

   207 .. cfunction:: PyObject* PyRun_FileExFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit, PyCompilerFlags *flags)

   208 

   209    Similar to :cfunc:`PyRun_StringFlags`, but the Python source code is read from

   210    *fp* instead of an in-memory string. *filename* should be the name of the file.

   211    If *closeit* is true, the file is closed before :cfunc:`PyRun_FileExFlags`

   212    returns.

   213 

   214 

   215 .. cfunction:: PyObject* Py_CompileString(const char *str, const char *filename, int start)

   216 

   217    This is a simplified interface to :cfunc:`Py_CompileStringFlags` below, leaving

   218    *flags* set to *NULL*.

   219 

   220 

   221 .. cfunction:: PyObject* Py_CompileStringFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags)

   222 

   223    Parse and compile the Python source code in *str*, returning the resulting code

   224    object.  The start token is given by *start*; this can be used to constrain the

   225    code which can be compiled and should be :const:`Py_eval_input`,

   226    :const:`Py_file_input`, or :const:`Py_single_input`.  The filename specified by

   227    *filename* is used to construct the code object and may appear in tracebacks or

   228    :exc:`SyntaxError` exception messages.  This returns *NULL* if the code cannot

   229    be parsed or compiled.

   230 

   231 

   232 .. cfunction:: PyObject* PyEval_EvalCode(PyCodeObject *co, PyObject *globals, PyObject *locals)

   233 

   234    This is a simplified interface to :cfunc:`PyEval_EvalCodeEx`, with just

   235    the code object, and the dictionaries of global and local variables.

   236    The other arguments are set to *NULL*.

   237 

   238 

   239 .. cfunction:: PyObject* PyEval_EvalCodeEx(PyCodeObject *co, PyObject *globals, PyObject *locals, PyObject **args, int argcount, PyObject **kws, int kwcount, PyObject **defs, int defcount, PyObject *closure)

   240 

   241    Evaluate a precompiled code object, given a particular environment for its

   242    evaluation.  This environment consists of dictionaries of global and local

   243    variables, arrays of arguments, keywords and defaults, and a closure tuple of

   244    cells.

   245 

   246 

   247 .. cfunction:: PyObject* PyEval_EvalFrame(PyFrameObject *f)

   248 

   249    Evaluate an execution frame.  This is a simplified interface to

   250    PyEval_EvalFrameEx, for backward compatibility.

   251 

   252 

   253 .. cfunction:: PyObject* PyEval_EvalFrameEx(PyFrameObject *f, int throwflag)

   254 

   255    This is the main, unvarnished function of Python interpretation.  It is

   256    literally 2000 lines long.  The code object associated with the execution

   257    frame *f* is executed, interpreting bytecode and executing calls as needed.

   258    The additional *throwflag* parameter can mostly be ignored - if true, then

   259    it causes an exception to immediately be thrown; this is used for the

   260    :meth:`throw` methods of generator objects.

   261 

   262 

   263 .. cfunction:: int PyEval_MergeCompilerFlags(PyCompilerFlags *cf)

   264 

   265    This function changes the flags of the current evaluation frame, and returns

   266    true on success, false on failure.

   267 

   268 

   269 .. cvar:: int Py_eval_input

   270 

   271    .. index:: single: Py_CompileString()

   272 

   273    The start symbol from the Python grammar for isolated expressions; for use with

   274    :cfunc:`Py_CompileString`.

   275 

   276 

   277 .. cvar:: int Py_file_input

   278 

   279    .. index:: single: Py_CompileString()

   280 

   281    The start symbol from the Python grammar for sequences of statements as read

   282    from a file or other source; for use with :cfunc:`Py_CompileString`.  This is

   283    the symbol to use when compiling arbitrarily long Python source code.

   284 

   285 

   286 .. cvar:: int Py_single_input

   287 

   288    .. index:: single: Py_CompileString()

   289 

   290    The start symbol from the Python grammar for a single statement; for use with

   291    :cfunc:`Py_CompileString`. This is the symbol used for the interactive

   292    interpreter loop.

   293 

   294 

   295 .. ctype:: struct PyCompilerFlags

   296 

   297    This is the structure used to hold compiler flags.  In cases where code is only

   298    being compiled, it is passed as ``int flags``, and in cases where code is being

   299    executed, it is passed as ``PyCompilerFlags *flags``.  In this case, ``from

   300    __future__ import`` can modify *flags*.

   301 

   302    Whenever ``PyCompilerFlags *flags`` is *NULL*, :attr:`cf_flags` is treated as

   303    equal to ``0``, and any modification due to ``from __future__ import`` is

   304    discarded.  ::

   305 

   306       struct PyCompilerFlags {

   307           int cf_flags;

   308       }

   309 

   310 

   311 .. cvar:: int CO_FUTURE_DIVISION

   312 

   313    This bit can be set in *flags* to cause division operator ``/`` to be

   314    interpreted as "true division" according to :pep:`238`.

   315