mirrors/cpython
0
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2024-12-03 06:46:01 +08:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
Closes SF patch #798638.
This commit is contained in:
Fred Drake 2004-03-25 15:44:56 +00:00
parent 1c0f1f97fb
commit d0c3b26bd0
1 changed files with 182 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

218
Doc/api/veryhigh.tex
View File

@ -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, 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 @@ 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}