improve the very-high-level API docs (contributed by Jeff Epler)
Closes SF patch #798638.
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 @@
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 @@
\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, char *filename}
+\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. 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, char *filename}
+\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}{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
- read from \var{fp} instead of an in-memory string.
- \var{filename} should be the name of the file.
+ 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*}{Py_CompileString}{char *str, char *filename,
+\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
@@ -139,3 +263,25 @@
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}