diff options
Diffstat (limited to 'Doc/api')
| -rw-r--r-- | Doc/api/veryhigh.tex | 214 |
1 files changed, 180 insertions, 34 deletions
diff --git a/Doc/api/veryhigh.tex b/Doc/api/veryhigh.tex index e7cb094..5c79b44 100644 --- a/Doc/api/veryhigh.tex +++ b/Doc/api/veryhigh.tex @@ -33,7 +33,26 @@ library that the Python runtime is using. represent a valid Python command line. \end{cfuncdesc} -\begin{cfuncdesc}{int}{PyRun_AnyFile}{FILE *fp, char *filename} +\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 @@ -41,76 +60,181 @@ library that the Python runtime is using. \NULL, this function uses \code{"???"} as the filename. \end{cfuncdesc} -\begin{cfuncdesc}{int}{PyRun_SimpleString}{char *command} +\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. 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. + \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, char *filename} - Similar to \cfunction{PyRun_SimpleString()}, but the Python source +\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. + \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_InteractiveOne}{FILE *fp, char *filename} +\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. 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.) + 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_InteractiveLoop}{FILE *fp, char *filename} +\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}{char *str, +\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}. 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. + \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, - 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. + 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}{PyObject*}{PyRun_String}{char *str, int start, +\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}. The parameter - \var{start} specifies the start token that should be used to parse - the source code. + 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, char *filename, +\begin{cfuncdesc}{PyObject*}{PyRun_File}{FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals} - Similar to \cfunction{PyRun_String()}, but the Python source code is + 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}{char *str, char *filename, +\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 @@ -139,3 +263,25 @@ library that the Python runtime is using. 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} |