add hg and python

1 files changed, 287 insertions, 0 deletions

diff --git a/sys/src/cmd/python/Doc/api/veryhigh.tex b/sys/src/cmd/python/Doc/api/veryhigh.tex
new file mode 100644
index 000000000..5c79b4440
--- /dev/null
+++ b/sys/src/cmd/python/Doc/api/veryhigh.tex
@@ -0,0 +1,287 @@
+\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}