improve the very-high-level API docs (contributed by Jeff Epler)

Closes SF patch #798638.

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}