142 lines
6.7 KiB
TeX
142 lines
6.7 KiB
TeX
|
\chapter{The Very High Level Layer \label{veryhigh}}
|
||
|
|
|
||
|
|
|
||
|
|
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 \constant{Py_eval_input},
|
||
|
|
\constant{Py_file_input}, and \constant{Py_single_input}. These are
|
||
|
|
described following the functions which accept them as parameters.
|
||
|
|
|
||
|
|
Note also that several of these functions take \ctype{FILE*}
|
||
|
|
parameters. On particular issue which needs to be handled carefully
|
||
|
|
is that the \ctype{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 \ctype{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.
|
||
|
|
|
||
|
|
|
||
|
|
\begin{cfuncdesc}{int}{Py_Main}{int argc, char **argv}
|
||
|
|
The main program for the standard interpreter. This is made
|
||
|
|
available for programs which embed Python. The \var{argc} and
|
||
|
|
\var{argv} parameters should be prepared exactly as those which are
|
||
|
|
passed to a C program's \cfunction{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 the integer passed to the
|
||
|
|
\function{sys.exit()} function, \code{1} if the interpreter exits
|
||
|
|
due to an exception, or \code{2} if the parameter list does not
|
||
|
|
represent a valid Python command line.
|
||
|
|
\end{cfuncdesc}
|
||
|
|
|
||
|
|
\begin{cfuncdesc}{int}{PyRun_AnyFile}{FILE *fp, char *filename}
|
||
|
|
If \var{fp} refers to a file associated with an interactive device
|
||
|
|
(console or terminal input or \UNIX{} pseudo-terminal), return the
|
||
|
|
value of \cfunction{PyRun_InteractiveLoop()}, otherwise return the
|
||
|
|
result of \cfunction{PyRun_SimpleFile()}. If \var{filename} is
|
||
|
|
\NULL, this function uses \code{"???"} as the filename.
|
||
|
|
\end{cfuncdesc}
|
||
|
|
|
||
|
|
\begin{cfuncdesc}{int}{PyRun_SimpleString}{char *command}
|
||
|
|
Executes the Python source code from \var{command} in the
|
||
|
|
\module{__main__} module. If \module{__main__} does not already
|
||
|
|
exist, it is created. Returns \code{0} on success or \code{-1} if
|
||
|
|
an exception was raised. If there was an error, there is no way to
|
||
|
|
get the exception information.
|
||
|
|
\end{cfuncdesc}
|
||
|
|
|
||
|
|
\begin{cfuncdesc}{int}{PyRun_SimpleFile}{FILE *fp, char *filename}
|
||
|
|
Similar to \cfunction{PyRun_SimpleString()}, but the Python source
|
||
|
|
code is read from \var{fp} instead of an in-memory string.
|
||
|
|
\var{filename} should be the name of the file.
|
||
|
|
\end{cfuncdesc}
|
||
|
|
|
||
|
|
\begin{cfuncdesc}{int}{PyRun_InteractiveOne}{FILE *fp, char *filename}
|
||
|
|
Read and execute a single statement from a file associated with an
|
||
|
|
interactive device. If \var{filename} is \NULL, \code{"???"} is
|
||
|
|
used instead. The user will be prompted using \code{sys.ps1} and
|
||
|
|
\code{sys.ps2}. Returns \code{0} when the input was executed
|
||
|
|
successfully, \code{-1} if there was an exception, or an error code
|
||
|
|
from the \file{errcode.h} include file distributed as part of Python
|
||
|
|
if there was a parse error. (Note that \file{errcode.h} is not
|
||
|
|
included by \file{Python.h}, so must be included specifically if
|
||
|
|
needed.)
|
||
|
|
\end{cfuncdesc}
|
||
|
|
|
||
|
|
\begin{cfuncdesc}{int}{PyRun_InteractiveLoop}{FILE *fp, char *filename}
|
||
|
|
Read and execute statements from a file associated with an
|
||
|
|
interactive device until \EOF{} is reached. If \var{filename} is
|
||
|
|
\NULL, \code{"???"} is used instead. The user will be prompted
|
||
|
|
using \code{sys.ps1} and \code{sys.ps2}. Returns \code{0} at \EOF.
|
||
|
|
\end{cfuncdesc}
|
||
|
|
|
||
|
|
\begin{cfuncdesc}{struct _node*}{PyParser_SimpleParseString}{char *str,
|
||
|
|
int start}
|
||
|
|
Parse Python source code from \var{str} using the start token
|
||
|
|
\var{start}. 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.
|
||
|
|
\end{cfuncdesc}
|
||
|
|
|
||
|
|
\begin{cfuncdesc}{struct _node*}{PyParser_SimpleParseFile}{FILE *fp,
|
||
|
|
char *filename, int start}
|
||
|
|
Similar to \cfunction{PyParser_SimpleParseString()}, but the Python
|
||
|
|
source code is read from \var{fp} instead of an in-memory string.
|
||
|
|
\var{filename} should be the name of the file.
|
||
|
|
\end{cfuncdesc}
|
||
|
|
|
||
|
|
\begin{cfuncdesc}{PyObject*}{PyRun_String}{char *str, int start,
|
||
|
|
PyObject *globals,
|
||
|
|
PyObject *locals}
|
||
|
|
Execute Python source code from \var{str} in the context specified
|
||
|
|
by the dictionaries \var{globals} and \var{locals}. The parameter
|
||
|
|
\var{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.
|
||
|
|
\end{cfuncdesc}
|
||
|
|
|
||
|
|
\begin{cfuncdesc}{PyObject*}{PyRun_File}{FILE *fp, char *filename,
|
||
|
|
int start, PyObject *globals,
|
||
|
|
PyObject *locals}
|
||
|
|
Similar to \cfunction{PyRun_String()}, but the Python source code is
|
||
|
|
read from \var{fp} instead of an in-memory string.
|
||
|
|
\var{filename} should be the name of the file.
|
||
|
|
\end{cfuncdesc}
|
||
|
|
|
||
|
|
\begin{cfuncdesc}{PyObject*}{Py_CompileString}{char *str, char *filename,
|
||
|
|
int start}
|
||
|
|
Parse and compile the Python source code in \var{str}, returning the
|
||
|
|
resulting code object. The start token is given by \var{start};
|
||
|
|
this can be used to constrain the code which can be compiled and should
|
||
|
|
be \constant{Py_eval_input}, \constant{Py_file_input}, or
|
||
|
|
\constant{Py_single_input}. The filename specified by
|
||
|
|
\var{filename} is used to construct the code object and may appear
|
||
|
|
in tracebacks or \exception{SyntaxError} exception messages. This
|
||
|
|
returns \NULL{} if the code cannot be parsed or compiled.
|
||
|
|
\end{cfuncdesc}
|
||
|
|
|
||
|
|
\begin{cvardesc}{int}{Py_eval_input}
|
||
|
|
The start symbol from the Python grammar for isolated expressions;
|
||
|
|
for use with
|
||
|
|
\cfunction{Py_CompileString()}\ttindex{Py_CompileString()}.
|
||
|
|
\end{cvardesc}
|
||
|
|
|
||
|
|
\begin{cvardesc}{int}{Py_file_input}
|
||
|
|
The start symbol from the Python grammar for sequences of statements
|
||
|
|
as read from a file or other source; for use with
|
||
|
|
\cfunction{Py_CompileString()}\ttindex{Py_CompileString()}. This is
|
||
|
|
the symbol to use when compiling arbitrarily long Python source code.
|
||
|
|
\end{cvardesc}
|
||
|
|
|
||
|
|
\begin{cvardesc}{int}{Py_single_input}
|
||
|
|
The start symbol from the Python grammar for a single statement; for
|
||
|
|
use with \cfunction{Py_CompileString()}\ttindex{Py_CompileString()}.
|
||
|
|
This is the symbol used for the interactive interpreter loop.
|
||
|
|
\end{cvardesc}
|