| \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, const char *filename} |
| This is a simplified interface to \cfunction{PyRun_AnyFileExFlags()} |
| below, leaving \var{closeit} set to \code{0} and \var{flags} set to \NULL. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyRun_AnyFileFlags}{FILE *fp, const char *filename, |
| PyCompilerFlags *flags} |
| This is a simplified interface to \cfunction{PyRun_AnyFileExFlags()} |
| below, leaving the \var{closeit} argument set to \code{0}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyRun_AnyFileEx}{FILE *fp, const char *filename, |
| int closeit} |
| This is a simplified interface to \cfunction{PyRun_AnyFileExFlags()} |
| below, leaving the \var{flags} argument set to \NULL. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyRun_AnyFileExFlags}{FILE *fp, const char *filename, |
| int closeit, |
| PyCompilerFlags *flags} |
| 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}{const char *command} |
| This is a simplified interface to \cfunction{PyRun_SimpleStringFlags()} |
| below, leaving the \var{PyCompilerFlags*} argument set to NULL. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyRun_SimpleStringFlags}{const char *command, |
| PyCompilerFlags *flags} |
| Executes the Python source code from \var{command} in the |
| \module{__main__} module according to the \var{flags} argument. |
| 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. |
| For the meaning of \var{flags}, see below. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyRun_SimpleFile}{FILE *fp, const char *filename} |
| This is a simplified interface to \cfunction{PyRun_SimpleFileExFlags()} |
| below, leaving \var{closeit} set to \code{0} and \var{flags} set to |
| \NULL. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyRun_SimpleFileFlags}{FILE *fp, const char *filename, |
| PyCompilerFlags *flags} |
| This is a simplified interface to \cfunction{PyRun_SimpleFileExFlags()} |
| below, leaving \var{closeit} set to \code{0}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyRun_SimpleFileEx}{FILE *fp, const char *filename, |
| int closeit} |
| This is a simplified interface to \cfunction{PyRun_SimpleFileExFlags()} |
| below, leaving \var{flags} set to \NULL. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyRun_SimpleFileExFlags}{FILE *fp, const char *filename, |
| int closeit, |
| PyCompilerFlags *flags} |
| Similar to \cfunction{PyRun_SimpleStringFlags()}, 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. If \var{closeit} is |
| true, the file is closed before PyRun_SimpleFileExFlags returns. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyRun_InteractiveOne}{FILE *fp, const char *filename} |
| This is a simplified interface to \cfunction{PyRun_InteractiveOneFlags()} |
| below, leaving \var{flags} set to \NULL. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyRun_InteractiveOneFlags}{FILE *fp, |
| const char *filename, |
| PyCompilerFlags *flags} |
| Read and execute a single statement from a file associated with an |
| interactive device according to the \var{flags} argument. 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, const char *filename} |
| This is a simplified interface to \cfunction{PyRun_InteractiveLoopFlags()} |
| below, leaving \var{flags} set to \NULL. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyRun_InteractiveLoopFlags}{FILE *fp, |
| const char *filename, |
| PyCompilerFlags *flags} |
| 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}{const char *str, |
| int start} |
| This is a simplified interface to |
| \cfunction{PyParser_SimpleParseStringFlagsFilename()} below, leaving |
| \var{filename} set to \NULL{} and \var{flags} set to \code{0}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{struct _node*}{PyParser_SimpleParseStringFlags}{ |
| const char *str, int start, int flags} |
| This is a simplified interface to |
| \cfunction{PyParser_SimpleParseStringFlagsFilename()} below, leaving |
| \var{filename} set to \NULL. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{struct _node*}{PyParser_SimpleParseStringFlagsFilename}{ |
| const char *str, const char *filename, |
| int start, int flags} |
| Parse Python source code from \var{str} using the start token |
| \var{start} according to the \var{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. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{struct _node*}{PyParser_SimpleParseFile}{FILE *fp, |
| const char *filename, int start} |
| This is a simplified interface to \cfunction{PyParser_SimpleParseFileFlags()} |
| below, leaving \var{flags} set to \code{0} |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{struct _node*}{PyParser_SimpleParseFileFlags}{FILE *fp, |
| const char *filename, int start, int flags} |
| Similar to \cfunction{PyParser_SimpleParseStringFlagsFilename()}, but |
| the Python source code is read from \var{fp} instead of an in-memory |
| string. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyRun_String}{const char *str, int start, |
| PyObject *globals, |
| PyObject *locals} |
| This is a simplified interface to \cfunction{PyRun_StringFlags()} below, |
| leaving \var{flags} set to \NULL. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyRun_StringFlags}{const char *str, int start, |
| PyObject *globals, |
| PyObject *locals, |
| PyCompilerFlags *flags} |
| Execute Python source code from \var{str} in the context specified |
| by the dictionaries \var{globals} and \var{locals} with the compiler |
| flags specified by \var{flags}. 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, const char *filename, |
| int start, PyObject *globals, |
| PyObject *locals} |
| This is a simplified interface to \cfunction{PyRun_FileExFlags()} below, |
| leaving \var{closeit} set to \code{0} and \var{flags} set to \NULL. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyRun_FileEx}{FILE *fp, const char *filename, |
| int start, PyObject *globals, |
| PyObject *locals, int closeit} |
| This is a simplified interface to \cfunction{PyRun_FileExFlags()} below, |
| leaving \var{flags} set to \NULL. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyRun_FileFlags}{FILE *fp, const char *filename, |
| int start, PyObject *globals, |
| PyObject *locals, |
| PyCompilerFlags *flags} |
| This is a simplified interface to \cfunction{PyRun_FileExFlags()} below, |
| leaving \var{closeit} set to \code{0}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyRun_FileExFlags}{FILE *fp, const char *filename, |
| int start, PyObject *globals, |
| PyObject *locals, int closeit, |
| PyCompilerFlags *flags} |
| Similar to \cfunction{PyRun_StringFlags()}, 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. |
| If \var{closeit} is true, the file is closed before |
| \cfunction{PyRun_FileExFlags()} returns. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{Py_CompileString}{const char *str, |
| const char *filename, |
| int start} |
| This is a simplified interface to \cfunction{Py_CompileStringFlags()} below, |
| leaving \var{flags} set to \NULL. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{Py_CompileStringFlags}{const char *str, |
| const char *filename, |
| int start, |
| PyCompilerFlags *flags} |
| 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} |
| |
| \begin{ctypedesc}[PyCompilerFlags]{struct PyCompilerFlags} |
| This is the structure used to hold compiler flags. In cases where |
| code is only being compiled, it is passed as \code{int flags}, and in |
| cases where code is being executed, it is passed as |
| \code{PyCompilerFlags *flags}. In this case, \code{from __future__ |
| import} can modify \var{flags}. |
| |
| Whenever \code{PyCompilerFlags *flags} is \NULL, \member{cf_flags} |
| is treated as equal to \code{0}, and any modification due to |
| \code{from __future__ import} is discarded. |
| \begin{verbatim} |
| struct PyCompilerFlags { |
| int cf_flags; |
| } |
| \end{verbatim} |
| \end{ctypedesc} |
| |
| \begin{cvardesc}{int}{CO_FUTURE_DIVISION} |
| This bit can be set in \var{flags} to cause division operator \code{/} |
| to be interpreted as ``true division'' according to \pep{238}. |
| \end{cvardesc} |