diff options
Diffstat (limited to 'Doc/api/veryhigh.tex')
| -rw-r--r-- | Doc/api/veryhigh.tex | 287 |
1 files changed, 0 insertions, 287 deletions
diff --git a/Doc/api/veryhigh.tex b/Doc/api/veryhigh.tex deleted file mode 100644 index 5c79b44..0000000 --- a/Doc/api/veryhigh.tex +++ /dev/null @@ -1,287 +0,0 @@ -\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} |