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.
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}