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.
Py_Main
(int argc, char **argv)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.
PyRun_AnyFile
(FILE *fp, const char *filename)PyRun_AnyFileExFlags()
below, leaving closeit set to 0
and flags set to NULL.PyRun_AnyFileFlags
(FILE *fp, const char *filename, PyCompilerFlags *flags)PyRun_AnyFileExFlags()
below, leaving the closeit argument set to 0
.PyRun_AnyFileEx
(FILE *fp, const char *filename, int closeit)PyRun_AnyFileExFlags()
below, leaving the flags argument set to NULL.PyRun_AnyFileExFlags
(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)PyRun_InteractiveLoop()
, otherwise return the result of PyRun_SimpleFile()
. If filename is NULL, this function uses "???"
as the filename.PyRun_SimpleString
(const char *command)PyRun_SimpleStringFlags()
below, leaving the PyCompilerFlags* argument set to NULL.PyRun_SimpleStringFlags
(const char *command, PyCompilerFlags *flags)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.
PyRun_SimpleFile
(FILE *fp, const char *filename)PyRun_SimpleFileExFlags()
below, leaving closeit set to 0
and flags set to NULL.PyRun_SimpleFileFlags
(FILE *fp, const char *filename, PyCompilerFlags *flags)PyRun_SimpleFileExFlags()
below, leaving closeit set to 0
.PyRun_SimpleFileEx
(FILE *fp, const char *filename, int closeit)PyRun_SimpleFileExFlags()
below, leaving flags set to NULL.PyRun_SimpleFileExFlags
(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)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.PyRun_InteractiveOne
(FILE *fp, const char *filename)PyRun_InteractiveOneFlags()
below, leaving flags set to NULL.PyRun_InteractiveOneFlags
(FILE *fp, const char *filename, PyCompilerFlags *flags)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.)PyRun_InteractiveLoop
(FILE *fp, const char *filename)PyRun_InteractiveLoopFlags()
below, leaving flags set to NULL.PyRun_InteractiveLoopFlags
(FILE *fp, const char *filename, PyCompilerFlags *flags)sys.ps1
and sys.ps2
. Returns 0
at EOF.PyParser_SimpleParseString
(const char *str, int start)PyParser_SimpleParseStringFlagsFilename()
below, leaving filename set to NULL and flags set to 0
.PyParser_SimpleParseStringFlags
(const char *str, int start, int flags)PyParser_SimpleParseStringFlagsFilename()
below, leaving filename set to NULL.PyParser_SimpleParseStringFlagsFilename
(const char *str, const char *filename, int start, int flags)PyParser_SimpleParseFile
(FILE *fp, const char *filename, int start)PyParser_SimpleParseFileFlags()
below, leaving flags set to 0
.PyParser_SimpleParseFileFlags
(FILE *fp, const char *filename, int start, int flags)PyParser_SimpleParseStringFlagsFilename()
, but the Python source code is read from fp instead of an in-memory string.PyRun_String
(const char *str, int start, PyObject *globals, PyObject *locals)Return value: New reference.
This is a simplified interface to PyRun_StringFlags()
below, leaving
flags set to NULL.
PyRun_StringFlags
(const char *str, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)Return value: New reference.
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.
PyRun_File
(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals)Return value: New reference.
This is a simplified interface to PyRun_FileExFlags()
below, leaving
closeit set to 0
and flags set to NULL.
PyRun_FileEx
(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit)Return value: New reference.
This is a simplified interface to PyRun_FileExFlags()
below, leaving
flags set to NULL.
PyRun_FileFlags
(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)Return value: New reference.
This is a simplified interface to PyRun_FileExFlags()
below, leaving
closeit set to 0
.
PyRun_FileExFlags
(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit, PyCompilerFlags *flags)Return value: New reference.
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.
Py_CompileString
(const char *str, const char *filename, int start)Return value: New reference.
This is a simplified interface to Py_CompileStringFlags()
below, leaving
flags set to NULL.
Py_CompileStringFlags
(const char *str, const char *filename, int start, PyCompilerFlags *flags)Return value: New reference.
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.
PyEval_EvalCode
(PyCodeObject *co, PyObject *globals, PyObject *locals)Return value: New reference.
This is a simplified interface to PyEval_EvalCodeEx()
, with just
the code object, and the dictionaries of global and local variables.
The other arguments are set to NULL.
PyEval_EvalCodeEx
(PyCodeObject *co, PyObject *globals, PyObject *locals, PyObject **args, int argcount, PyObject **kws, int kwcount, PyObject **defs, int defcount, PyObject *closure)PyEval_EvalFrame
(PyFrameObject *f)PyEval_EvalFrameEx
(PyFrameObject *f, int throwflag)throw()
methods of generator objects.PyEval_MergeCompilerFlags
(PyCompilerFlags *cf)Py_eval_input
Py_CompileString()
.Py_file_input
Py_CompileString()
. This is the symbol to use when compiling arbitrarily long Python source code.Py_single_input
Py_CompileString()
. This is the symbol used for the interactive interpreter loop.PyCompilerFlags
This is the structure used to hold compiler flags. In cases where code is only
being compiled, it is passed as int flags
, 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.
struct PyCompilerFlags {
int cf_flags;
}
CO_FUTURE_DIVISION
/
to be interpreted as “true division” according to PEP 238.