Navigation

The functions in this chapter will let you execute Python source code given in a
file or a buffer, but they will not let you interact in a more detailed way with
the interpreter.

Several of these functions accept a start symbol from the grammar as a
parameter. The available start symbols are Py_eval_input,
Py_file_input, and Py_single_input. These are described
following the functions which accept them as parameters.

Note also that several of these functions take FILE* parameters. One
particular issue which needs to be handled carefully is that the FILE
structure for different C libraries can be different and incompatible. Under
Windows (at least), it is possible for dynamically linked extensions to actually
use different libraries, so care should be taken that FILE* parameters
are only passed to these functions if it is certain that they were created by
the same library that the Python runtime is using.

The main program for the standard interpreter. This is made available for
programs which embed Python. The argc and argv parameters should be
prepared exactly as those which are passed to a C program’s main()
function. It is important to note that the argument list may be modified (but
the contents of the strings pointed to by the argument list are not). The return
value will be 0 if the interpreter exits normally (ie, without an
exception), 1 if the interpreter exits due to an exception, or 2
if the parameter list does not represent a valid Python command line.

Note that if an otherwise unhandled SystemExit is raised, this
function will not return 1, but exit the process, as long as
Py_InspectFlag is not set.

If fp refers to a file associated with an interactive device (console or
terminal input or Unix pseudo-terminal), return the value of
PyRun_InteractiveLoop(), otherwise return the result of
PyRun_SimpleFile(). If filename is NULL, this function uses
"???" as the filename.

Executes the Python source code from command in the __main__ module
according to the flags argument. If __main__ does not already exist, it
is created. Returns 0 on success or -1 if an exception was raised. If
there was an error, there is no way to get the exception information. For the
meaning of flags, see below.

Note that if an otherwise unhandled SystemExit is raised, this
function will not return -1, but exit the process, as long as
Py_InspectFlag is not set.

Similar to PyRun_SimpleStringFlags(), but the Python source code is read
from fp instead of an in-memory string. filename should be the name of the
file. If closeit is true, the file is closed before PyRun_SimpleFileExFlags
returns.

Read and execute a single statement from a file associated with an
interactive device according to the flags argument. The user will be
prompted using sys.ps1 and sys.ps2. Returns 0 when the input was
executed successfully, -1 if there was an exception, or an error code
from the errcode.h include file distributed as part of Python if
there was a parse error. (Note that errcode.h is not included by
Python.h, so must be included specifically if needed.)

Parse Python source code from str using the start token start according to
the flags argument. The result can be used to create a code object which can
be evaluated efficiently. This is useful if a code fragment must be evaluated
many times.

Execute Python source code from str in the context specified by the
dictionaries globals and locals with the compiler flags specified by
flags. The parameter start specifies the start token that should be used to
parse the source code.

Returns the result of executing the code as a Python object, or NULL if an
exception was raised.

Similar to PyRun_StringFlags(), but the Python source code is read from
fp instead of an in-memory string. filename should be the name of the file.
If closeit is true, the file is closed before PyRun_FileExFlags()
returns.

Parse and compile the Python source code in str, returning the resulting code
object. The start token is given by start; this can be used to constrain the
code which can be compiled and should be Py_eval_input,
Py_file_input, or Py_single_input. The filename specified by
filename is used to construct the code object and may appear in tracebacks or
SyntaxError exception messages. This returns NULL if the code cannot
be parsed or compiled.

Evaluate a precompiled code object, given a particular environment for its
evaluation. This environment consists of dictionaries of global and local
variables, arrays of arguments, keywords and defaults, and a closure tuple of
cells.

This is the main, unvarnished function of Python interpretation. It is
literally 2000 lines long. The code object associated with the execution
frame f is executed, interpreting bytecode and executing calls as needed.
The additional throwflag parameter can mostly be ignored - if true, then
it causes an exception to immediately be thrown; this is used for the
throw() methods of generator objects.

The start symbol from the Python grammar for sequences of statements as read
from a file or other source; for use with Py_CompileString(). This is
the symbol to use when compiling arbitrarily long Python source code.

This is the structure used to hold compiler flags. In cases where code is only
being compiled, it is passed as intflags, and in cases where code is being
executed, it is passed as PyCompilerFlags*flags. In this case, from__future__import can modify flags.

Whenever PyCompilerFlags*flags is NULL, cf_flags is treated as
equal to 0, and any modification due to from__future__import is
discarded.