Break the Python/C API manual into smaller files by chapter. This manual

has grown beyond what font-lock will work with using the default (X)Emacs
settings.

Indentation of the description has been made consistent, and a number of
smaller markup adjustments have been made as well.

1 files changed, 141 insertions, 0 deletions

diff --git a/Doc/api/veryhigh.tex b/Doc/api/veryhigh.tex
new file mode 100644
index 0000000..e7cb094
--- /dev/null
+++ b/Doc/api/veryhigh.tex
@@ -0,0 +1,141 @@
+\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, char *filename}
+  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}{char *command}
+  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.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyRun_SimpleFile}{FILE *fp, char *filename}
+  Similar to \cfunction{PyRun_SimpleString()}, 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.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyRun_InteractiveOne}{FILE *fp, char *filename}
+  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.)
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyRun_InteractiveLoop}{FILE *fp, char *filename}
+  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,
+                                                             int start}
+  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.
+\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.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyRun_String}{char *str, int start,
+                                           PyObject *globals,
+                                           PyObject *locals}
+  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.
+
+  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,
+                                         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.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{Py_CompileString}{char *str, char *filename,
+                                               int start}
+  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}