summaryrefslogtreecommitdiffstats
path: root/Doc
diff options
context:
space:
mode:
authorGuido van Rossum <guido@python.org>1997-10-05 15:27:29 (GMT)
committerGuido van Rossum <guido@python.org>1997-10-05 15:27:29 (GMT)
commit42cefd03cf6097d016cded315b0d496eecdbaf89 (patch)
treec0603559a58a93f35a1e7720ec69478a928d092e /Doc
parent474ba3bd46648ae9f7b87aa0abcf20e10df7a78c (diff)
downloadcpython-42cefd03cf6097d016cded315b0d496eecdbaf89.zip
cpython-42cefd03cf6097d016cded315b0d496eecdbaf89.tar.gz
cpython-42cefd03cf6097d016cded315b0d496eecdbaf89.tar.bz2
Checkpoint. Added docs for the new exception handling APIs and for
the interfaces defined in import.h.
Diffstat (limited to 'Doc')
-rw-r--r--Doc/api.tex288
-rw-r--r--Doc/api/api.tex288
2 files changed, 506 insertions, 70 deletions
diff --git a/Doc/api.tex b/Doc/api.tex
index 98969b7..63ba307 100644
--- a/Doc/api.tex
+++ b/Doc/api.tex
@@ -463,21 +463,24 @@ will be executed later, it must be set explicitly with a call to
\code{PySys_SetArgv(\var{argc}, \var{argv})} subsequent to the call
to \code{Py_Initialize()}.
-On Unix, \code{Py_Initialize()} calculates the module search path
-based upon its best guess for the location of the standard Python
-interpreter executable, assuming that the Python library is found in a
-fixed location relative to the Python interpreter executable. In
-particular, it looks for a directory named \code{lib/python1.5}
-(replacing \code{1.5} with the current interpreter version) relative
-to the parent directory where the executable named \code{python} is
-found on the shell command search path (the environment variable
-\code{\$PATH}). For instance, if the Python executable is found in
-\code{/usr/local/bin/python}, it will assume that the libraries are in
-\code{/usr/local/lib/python1.5}. In fact, this also the ``fallback''
-location, used when no executable file named \code{python} is found
-along \code{\$PATH}. The user can change this behavior by setting the
-environment variable \code{\$PYTHONHOME}, and can insert additional
-directories in front of the standard path by setting
+On most systems (in particular, on Unix and Windows, although the
+details are slightly different), \code{Py_Initialize()} calculates the
+module search path based upon its best guess for the location of the
+standard Python interpreter executable, assuming that the Python
+library is found in a fixed location relative to the Python
+interpreter executable. In particular, it looks for a directory named
+\code{lib/python1.5} (replacing \code{1.5} with the current
+interpreter version) relative to the parent directory where the
+executable named \code{python} is found on the shell command search
+path (the environment variable \code{\$PATH}).
+
+For instance, if the Python executable is found in
+\code{/usr/local/bin/python}, it will assume that the libraries are in
+\code{/usr/local/lib/python1.5}. In fact, this also the ``fallback''
+location, used when no executable file named \code{python} is found
+along \code{\$PATH}. The user can change this behavior by setting the
+environment variable \code{\$PYTHONHOME}, and can insert additional
+directories in front of the standard path by setting
\code{\$PYTHONPATH}.
The embedding application can steer the search by calling
@@ -646,14 +649,6 @@ would make it dangerous to continue using the Python interpreter;
e.g., when the object administration appears to be corrupted.
\end{cfuncdesc}
-\begin{cfuncdesc}{void}{PyImport_Init}{}
-Initialize the module table. For internal use only.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyImport_Cleanup}{}
-Empty the module table. For internal use only.
-\end{cfuncdesc}
-
\begin{cfuncdesc}{void}{PyBuiltin_Init}{}
Initialize the \code{__builtin__} module. For internal use only.
\end{cfuncdesc}
@@ -742,7 +737,35 @@ Test whether the error indicator is set. If set, return the exception
\code{type} (the first argument to the last call to one of the
\code{PyErr_Set*()} functions or to \code{PyErr_Restore()}). If not
set, return \NULL{}. You do not own a reference to the return value,
-so you do not need to \code{Py_DECREF()} it.
+so you do not need to \code{Py_DECREF()} it. Note: do not compare the
+return value to a specific exception; use
+\code{PyErr_ExceptionMatches} instead, shown below.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyErr_ExceptionMatches}{PyObject *exc}
+\strong{NEW in 1.5a4!}
+Equivalent to
+\code{PyErr_GivenExceptionMatches(PyErr_Occurred(), \var{exc})}.
+This should only be called when an exception is actually set.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyErr_GivenExceptionMatches}{PyObject *given, PyObject *exc}
+\strong{NEW in 1.5a4!}
+Return true if the \var{given} exception matches the exception in
+\var{exc}. If \var{exc} is a class object, this also returns true
+when \var{given} is a subclass. If \var{exc} is a tuple, all
+exceptions in the tuple (and recursively in subtuples) are searched
+for a match. This should only be called when an exception is actually
+set.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyErr_NormalizeException}{PyObject**exc, PyObject**val, PyObject**tb}
+\strong{NEW in 1.5a4!}
+Under certain circumstances, the values returned by
+\code{PyErr_Fetch()} below can be ``unnormalized'', meaning that
+\var{*exc} is a class object but \var{*val} is not an instance of the
+same class. This function can be used to instantiate the class in
+that case. If the values are already normalized, nothing happens.
\end{cfuncdesc}
\begin{cfuncdesc}{void}{PyErr_Clear}{}
@@ -846,13 +869,39 @@ the effect of a \code{SIGINT} signal arriving -- the next time
raised.
\end{cfuncdesc}
+\begin{cfuncdesc}{PyObject *}{PyErr_NewException}{char *name,
+PyObject *base, PyObject *dict}
+\strong{NEW in 1.5a4!}
+This utility function creates and returns a new exception object. The
+\var{name} argument must be the name of the new exception, a C string
+of the form \code{module.class}. The \var{base} and \var{dict}
+arguments are normally \code{NULL}. Normally, this creates a class
+object derived from the root for all exceptions, the built-in name
+\code{Exception} (accessible in C as \code{PyExc_Exception}). In this
+case the \code{__module__} attribute of the new class is set to the
+first part (up to the last dot) of the \var{name} argument, and the
+class name is set to the last part (after the last dot). When the
+user has specified the \code{-X} command line option to use string
+exceptions, for backward compatibility, or when the \var{base}
+argument is not a class object (and not \code{NULL}), a string object
+created from the entire \var{name} argument is returned. The
+\var{base} argument can be used to specify an alternate base class.
+The \var{dict} argument can be used to specify a dictionary of class
+variables and methods.
+\end{cfuncdesc}
+
+
\section{Standard Exceptions}
All standard Python exceptions are available as global variables whose
names are \code{PyExc_} followed by the Python exception name.
These have the type \code{PyObject *}; they are all string objects.
-For completion, here are all the variables:
-\code{PyExc_AccessError},
+For completeness, here are all the variables (the first four are new
+in Python 1.5a4):
+\code{PyExc_Exception},
+\code{PyExc_StandardError},
+\code{PyExc_ArithmeticError},
+\code{PyExc_LookupError},
\code{PyExc_AssertionError},
\code{PyExc_AttributeError},
\code{PyExc_EOFError},
@@ -880,6 +929,8 @@ The functions in this chapter perform various utility tasks, such as
parsing function arguments and constructing Python values from C
values.
+\section{OS Utilities}
+
\begin{cfuncdesc}{int}{Py_FdIsInteractive}{FILE *fp, char *filename}
Return true (nonzero) if the standard I/O file \code{fp} with name
\code{filename} is deemed interactive. This is the case for files for
@@ -896,6 +947,153 @@ the standard C library function \code{time()}.
\end{cfuncdesc}
+\section{Importing modules}
+
+\begin{cfuncdesc}{PyObject *}{PyImport_ImportModule}{char *name}
+This is a simplified interface to \code{PyImport_ImportModuleEx}
+below, leaving the \var{globals} and \var{locals} arguments set to
+\code{NULL}. When the \var{name} argument contains a dot (i.e., when
+it specifies a submodule of a package), the \var{fromlist} argument is
+set to the list \code{['*']} so that the return value is the named
+module rather than the top-level package containing it as would
+otherwise be the case. (Unfortunately, this has an additional side
+effect when \var{name} in fact specifies a subpackage instead of a
+submodule: the submodules specified in the package's \code{__all__}
+variable are loaded.) Return a new reference to the imported module,
+or \code{NULL} with an exception set on failure (the module may still
+be created in this case).
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject *}{PyImport_ImportModuleEx}{char *name, PyObject *globals, PyObject *locals, PyObject *fromlist}
+\strong{NEW in 1.5a4!}
+Import a module. This is best described by referring to the built-in
+Python function \code{__import()__}, as the standard
+\code{__import__()} function calls this function directly.
+
+% Should move this para to libfuncs.tex:
+For example, the statement \code{import spam} results in the following
+call:
+\code{__import__('spam', globals(), locals(), [])};
+the statement \code{from spam.ham import eggs} results in
+\code{__import__('spam.ham', globals(), locals(), ['eggs'])}.
+Note that even though \code{locals()} and \code{['eggs']} are passed
+in as arguments, the \code{__import__()} function does not set the
+local variable named \code{eggs}; this is done by subsequent code that
+is generated for the import statement.
+
+The return value is a new reference to the imported module or
+top-level package, or \code{NULL} with an exception set on failure
+(the module may still be created in this case). When the \var{name}
+variable is of the form \code{package.module}, normally, the top-level
+package (the name up till the first dot) is returned, \emph{not} the
+module named by \var{name}. However, when a non-empty \var{fromlist}
+argument is given, the module named by \var{name} is returned. This
+is done for compatibility with the bytecode generated for the
+different kinds of import statement; when using \code{import
+spam.ham.eggs}, the top-level package \code{spam} must be placed in
+the importing namespace, but when using \code{from spam.ham import
+eggs}, the \code{spam.ham} subpackage must be used to find the
+\code{eggs} variable.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject *}{PyImport_Import}{PyObject *name}
+This is a higher-level interface that calls the current ``import hook
+function''. It invokes the \code{__import__()} function from the
+\code{__builtins__} of the current globals. This means that the
+import is done using whatever import hooks are installed in the
+current environment, e.g. by \code{rexec} or \code{ihooks}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject *}{PyImport_ReloadModule}{PyObject *m}
+Reload a module. This is best described by referring to the built-in
+Python function \code{reload()}, as the standard \code{reload()}
+function calls this function directly. Return a new reference to the
+reloaded module, or \code{NULL} with an exception set on failure (the
+module still exists in this case).
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject *}{PyImport_AddModule}{char *name}
+Return the module object corresponding to a module name. The
+\var{name} argument may be of the form \code{package.module}). First
+check the modules dictionary if there's one there, and if not, create
+a new one and insert in in the modules dictionary. Because the former
+action is most common, this does not return a new reference, and you
+do not own the returned reference. Return \code{NULL} with an
+exception set on failure.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject *}{PyImport_ExecCodeModule}{char *name, PyObject *co}
+Given a module name (possibly of the form \code{package.module}) and a
+code object read from a Python bytecode file or obtained from the
+built-in function \code{compile()}, load the module. Return a new
+reference to the module object, or \code{NULL} with an exception set
+if an error occurred (the module may still be created in this case).
+(This function would reload the module if it was already imported.)
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{long}{PyImport_GetMagicNumber}{}
+Return the magic number for Python bytecode files (a.k.a. \code{.pyc}
+and \code{.pyo} files). The magic number should be present in the
+first four bytes of the bytecode file, in little-endian byte order.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject *}{PyImport_GetModuleDict}{}
+Return the dictionary used for the module administration
+(a.k.a. \code{sys.modules}). Note that this is a per-interpreter
+variable.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{_PyImport_Init}{}
+Initialize the import mechanism. For internal use only.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyImport_Cleanup}{}
+Empty the module table. For internal use only.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{_PyImport_Fini}{}
+Finalize the import mechanism. For internal use only.
+\end{cfuncdesc}
+
+\begin{cvardesc}{extern PyObject *}{_PyImport_FindExtension}{char *, char *}
+For internal use only.
+\end{cvardesc}
+
+\begin{cvardesc}{extern PyObject *}{_PyImport_FixupExtension}{char *, char *}
+For internal use only.
+\end{cvardesc}
+
+\begin{cfuncdesc}{int}{PyImport_ImportFrozenModule}{char *}
+Load a frozen module. Return \code{1} for success, \code{0} if the
+module is not found, and \code{-1} with an exception set if the
+initialization failed. To access the imported module on a successful
+load, use \code{PyImport_ImportModule()).
+(Note the misnomer -- this function would reload the module if it was
+already imported.)
+\end{cfuncdesc}
+
+\begin{ctypedesc}{struct _frozen}
+This is the structure type definition for frozen module descriptors,
+as generated by the \code{freeze} utility (see \file{Tools/freeze/} in
+the Python source distribution). Its definition is:
+\bcode\begin{verbatim}
+struct _frozen {
+ char *name;
+ unsigned char *code;
+ int size;
+};
+\end{verbatim}\ecode
+\end{ctypedesc}
+
+\begin{cvardesc}{struct _frozen *}{PyImport_FrozenModules}
+This pointer is initialized to point to an array of \code{struct
+_freeze} records, terminated by one whose members are all \code{NULL}
+or zero. When a frozen module is imported, it is searched in this
+table. Third party code could play tricks with this to provide a
+dynamically created collection of frozen modules.
+\end{cvardesc}
+
+
\chapter{Debugging}
XXX Explain Py_DEBUG, Py_TRACE_REFS, Py_REF_DEBUG.
@@ -1557,20 +1755,29 @@ functions; with the exception of \code{Py_SetProgramName()},
modules (\code{sys.modules}), and creates the fundamental modules
\code{__builtin__}, \code{__main__} and \code{sys}. It also
initializes the module search path (\code{sys.path}). It does not set
-\code{sys.argv}; use \code{PySys_SetArgv()} for that. It is a fatal
-error to call it for a second time without calling
-\code{Py_Finalize()} first. There is no return value; it is a fatal
-error if the initialization fails.
+\code{sys.argv}; use \code{PySys_SetArgv()} for that. This is a no-op
+when called for a second time (without calling \code{Py_Finalize()}
+first). There is no return value; it is a fatal error if the
+initialization fails.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{Py_IsInitialized}{}
+\strong{NEW in 1.5a4!}
+Return true (nonzero) when the Python interpreter has been
+initialized, false (zero) if not. After \code{Py_Finalize()} is
+called, this returns false until \code{Py_Initialize()} is called
+again.
\end{cfuncdesc}
\begin{cfuncdesc}{void}{Py_Finalize}{}
+\strong{NEW in 1.5a3!}
Undo all initializations made by \code{Py_Initialize()} and subsequent
use of Python/C API functions, and destroy all sub-interpreters (see
\code{Py_NewInterpreter()} below) that were created and not yet
-destroyed since the last call to \code{Py_Initialize()}. Ideally,
-this frees all memory allocated by the Python interpreter. It is a
-fatal error to call it for a second time without calling
-\code{Py_Initialize()} again first. There is no return value; errors
+destroyed since the last call to \code{Py_Initialize()}. Ideally,
+this frees all memory allocated by the Python interpreter. This is a
+no-op when called for a second time (without calling
+\code{Py_Initialize()} again first). There is no return value; errors
during finalization are ignored.
This function is provided for a number of reasons. An embedding
@@ -1595,6 +1802,7 @@ calls \code{Py_Initialize()} and \code{Py_Finalize()} more than once.
\end{cfuncdesc}
\begin{cfuncdesc}{PyThreadState *}{Py_NewInterpreter}{}
+\strong{NEW in 1.5a3!}
Create a new sub-interpreter. This is an (almost) totally separate
environment for the execution of Python code. In particular, the new
interpreter has separate, independent versions of all imported
@@ -1647,6 +1855,7 @@ a hard-to-fix bug that will be addressed in a future release.)
\end{cfuncdesc}
\begin{cfuncdesc}{void}{Py_EndInterpreter}{PyThreadState *tstate}
+\strong{NEW in 1.5a3!}
Destroy the (sub-)interpreter represented by the given thread state.
The given thread state must be the current thread state. See the
discussion of thread states below. When the call returns, the current
@@ -1658,6 +1867,7 @@ been explicitly destroyed at that point.
\end{cfuncdesc}
\begin{cfuncdesc}{void}{Py_SetProgramName}{char *name}
+\strong{NEW in 1.5a3!}
This function should be called before \code{Py_Initialize()} is called
for the first time, if it is called at all. It tells the interpreter
the value of the \code{argv[0]} argument to the \code{main()} function
@@ -1729,12 +1939,13 @@ platform.
\end{cfuncdesc}
\begin{cfuncdesc}{char *}{Py_GetProgramFullPath}{}
+\strong{NEW in 1.5a3!}
Return the full program name of the Python executable; this is
computed as a side-effect of deriving the default module search path
from the program name (set by \code{Py_SetProgramName()} above). The
returned string points into static storage; the caller should not
modify its value. The value is available to Python code as
-\code{sys.executable}. % XXX is that the right sys.name?
+\code{sys.executable}.
\end{cfuncdesc}
\begin{cfuncdesc}{char *}{Py_GetPath}{}
@@ -1822,15 +2033,22 @@ the variable \code{sys.version}.
\section{Thread State and the Global Interpreter Lock}
\begin{cfuncdesc}{void}{PyEval_AcquireLock}{}
+\strong{NEW in 1.5a3!}
+HIRO
+
+
\end{cfuncdesc}
\begin{cfuncdesc}{void}{PyEval_ReleaseLock}{}
+\strong{NEW in 1.5a3!}
\end{cfuncdesc}
\begin{cfuncdesc}{void}{PyEval_AcquireThread}{PyThreadState *tstate}
+\strong{NEW in 1.5a3!}
\end{cfuncdesc}
\begin{cfuncdesc}{void}{PyEval_ReleaseThread}{PyThreadState *tstate}
+\strong{NEW in 1.5a3!}
\end{cfuncdesc}
\begin{cfuncdesc}{void}{PyEval_RestoreThread}{PyThreadState *tstate}
diff --git a/Doc/api/api.tex b/Doc/api/api.tex
index 98969b7..63ba307 100644
--- a/Doc/api/api.tex
+++ b/Doc/api/api.tex
@@ -463,21 +463,24 @@ will be executed later, it must be set explicitly with a call to
\code{PySys_SetArgv(\var{argc}, \var{argv})} subsequent to the call
to \code{Py_Initialize()}.
-On Unix, \code{Py_Initialize()} calculates the module search path
-based upon its best guess for the location of the standard Python
-interpreter executable, assuming that the Python library is found in a
-fixed location relative to the Python interpreter executable. In
-particular, it looks for a directory named \code{lib/python1.5}
-(replacing \code{1.5} with the current interpreter version) relative
-to the parent directory where the executable named \code{python} is
-found on the shell command search path (the environment variable
-\code{\$PATH}). For instance, if the Python executable is found in
-\code{/usr/local/bin/python}, it will assume that the libraries are in
-\code{/usr/local/lib/python1.5}. In fact, this also the ``fallback''
-location, used when no executable file named \code{python} is found
-along \code{\$PATH}. The user can change this behavior by setting the
-environment variable \code{\$PYTHONHOME}, and can insert additional
-directories in front of the standard path by setting
+On most systems (in particular, on Unix and Windows, although the
+details are slightly different), \code{Py_Initialize()} calculates the
+module search path based upon its best guess for the location of the
+standard Python interpreter executable, assuming that the Python
+library is found in a fixed location relative to the Python
+interpreter executable. In particular, it looks for a directory named
+\code{lib/python1.5} (replacing \code{1.5} with the current
+interpreter version) relative to the parent directory where the
+executable named \code{python} is found on the shell command search
+path (the environment variable \code{\$PATH}).
+
+For instance, if the Python executable is found in
+\code{/usr/local/bin/python}, it will assume that the libraries are in
+\code{/usr/local/lib/python1.5}. In fact, this also the ``fallback''
+location, used when no executable file named \code{python} is found
+along \code{\$PATH}. The user can change this behavior by setting the
+environment variable \code{\$PYTHONHOME}, and can insert additional
+directories in front of the standard path by setting
\code{\$PYTHONPATH}.
The embedding application can steer the search by calling
@@ -646,14 +649,6 @@ would make it dangerous to continue using the Python interpreter;
e.g., when the object administration appears to be corrupted.
\end{cfuncdesc}
-\begin{cfuncdesc}{void}{PyImport_Init}{}
-Initialize the module table. For internal use only.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyImport_Cleanup}{}
-Empty the module table. For internal use only.
-\end{cfuncdesc}
-
\begin{cfuncdesc}{void}{PyBuiltin_Init}{}
Initialize the \code{__builtin__} module. For internal use only.
\end{cfuncdesc}
@@ -742,7 +737,35 @@ Test whether the error indicator is set. If set, return the exception
\code{type} (the first argument to the last call to one of the
\code{PyErr_Set*()} functions or to \code{PyErr_Restore()}). If not
set, return \NULL{}. You do not own a reference to the return value,
-so you do not need to \code{Py_DECREF()} it.
+so you do not need to \code{Py_DECREF()} it. Note: do not compare the
+return value to a specific exception; use
+\code{PyErr_ExceptionMatches} instead, shown below.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyErr_ExceptionMatches}{PyObject *exc}
+\strong{NEW in 1.5a4!}
+Equivalent to
+\code{PyErr_GivenExceptionMatches(PyErr_Occurred(), \var{exc})}.
+This should only be called when an exception is actually set.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyErr_GivenExceptionMatches}{PyObject *given, PyObject *exc}
+\strong{NEW in 1.5a4!}
+Return true if the \var{given} exception matches the exception in
+\var{exc}. If \var{exc} is a class object, this also returns true
+when \var{given} is a subclass. If \var{exc} is a tuple, all
+exceptions in the tuple (and recursively in subtuples) are searched
+for a match. This should only be called when an exception is actually
+set.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyErr_NormalizeException}{PyObject**exc, PyObject**val, PyObject**tb}
+\strong{NEW in 1.5a4!}
+Under certain circumstances, the values returned by
+\code{PyErr_Fetch()} below can be ``unnormalized'', meaning that
+\var{*exc} is a class object but \var{*val} is not an instance of the
+same class. This function can be used to instantiate the class in
+that case. If the values are already normalized, nothing happens.
\end{cfuncdesc}
\begin{cfuncdesc}{void}{PyErr_Clear}{}
@@ -846,13 +869,39 @@ the effect of a \code{SIGINT} signal arriving -- the next time
raised.
\end{cfuncdesc}
+\begin{cfuncdesc}{PyObject *}{PyErr_NewException}{char *name,
+PyObject *base, PyObject *dict}
+\strong{NEW in 1.5a4!}
+This utility function creates and returns a new exception object. The
+\var{name} argument must be the name of the new exception, a C string
+of the form \code{module.class}. The \var{base} and \var{dict}
+arguments are normally \code{NULL}. Normally, this creates a class
+object derived from the root for all exceptions, the built-in name
+\code{Exception} (accessible in C as \code{PyExc_Exception}). In this
+case the \code{__module__} attribute of the new class is set to the
+first part (up to the last dot) of the \var{name} argument, and the
+class name is set to the last part (after the last dot). When the
+user has specified the \code{-X} command line option to use string
+exceptions, for backward compatibility, or when the \var{base}
+argument is not a class object (and not \code{NULL}), a string object
+created from the entire \var{name} argument is returned. The
+\var{base} argument can be used to specify an alternate base class.
+The \var{dict} argument can be used to specify a dictionary of class
+variables and methods.
+\end{cfuncdesc}
+
+
\section{Standard Exceptions}
All standard Python exceptions are available as global variables whose
names are \code{PyExc_} followed by the Python exception name.
These have the type \code{PyObject *}; they are all string objects.
-For completion, here are all the variables:
-\code{PyExc_AccessError},
+For completeness, here are all the variables (the first four are new
+in Python 1.5a4):
+\code{PyExc_Exception},
+\code{PyExc_StandardError},
+\code{PyExc_ArithmeticError},
+\code{PyExc_LookupError},
\code{PyExc_AssertionError},
\code{PyExc_AttributeError},
\code{PyExc_EOFError},
@@ -880,6 +929,8 @@ The functions in this chapter perform various utility tasks, such as
parsing function arguments and constructing Python values from C
values.
+\section{OS Utilities}
+
\begin{cfuncdesc}{int}{Py_FdIsInteractive}{FILE *fp, char *filename}
Return true (nonzero) if the standard I/O file \code{fp} with name
\code{filename} is deemed interactive. This is the case for files for
@@ -896,6 +947,153 @@ the standard C library function \code{time()}.
\end{cfuncdesc}
+\section{Importing modules}
+
+\begin{cfuncdesc}{PyObject *}{PyImport_ImportModule}{char *name}
+This is a simplified interface to \code{PyImport_ImportModuleEx}
+below, leaving the \var{globals} and \var{locals} arguments set to
+\code{NULL}. When the \var{name} argument contains a dot (i.e., when
+it specifies a submodule of a package), the \var{fromlist} argument is
+set to the list \code{['*']} so that the return value is the named
+module rather than the top-level package containing it as would
+otherwise be the case. (Unfortunately, this has an additional side
+effect when \var{name} in fact specifies a subpackage instead of a
+submodule: the submodules specified in the package's \code{__all__}
+variable are loaded.) Return a new reference to the imported module,
+or \code{NULL} with an exception set on failure (the module may still
+be created in this case).
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject *}{PyImport_ImportModuleEx}{char *name, PyObject *globals, PyObject *locals, PyObject *fromlist}
+\strong{NEW in 1.5a4!}
+Import a module. This is best described by referring to the built-in
+Python function \code{__import()__}, as the standard
+\code{__import__()} function calls this function directly.
+
+% Should move this para to libfuncs.tex:
+For example, the statement \code{import spam} results in the following
+call:
+\code{__import__('spam', globals(), locals(), [])};
+the statement \code{from spam.ham import eggs} results in
+\code{__import__('spam.ham', globals(), locals(), ['eggs'])}.
+Note that even though \code{locals()} and \code{['eggs']} are passed
+in as arguments, the \code{__import__()} function does not set the
+local variable named \code{eggs}; this is done by subsequent code that
+is generated for the import statement.
+
+The return value is a new reference to the imported module or
+top-level package, or \code{NULL} with an exception set on failure
+(the module may still be created in this case). When the \var{name}
+variable is of the form \code{package.module}, normally, the top-level
+package (the name up till the first dot) is returned, \emph{not} the
+module named by \var{name}. However, when a non-empty \var{fromlist}
+argument is given, the module named by \var{name} is returned. This
+is done for compatibility with the bytecode generated for the
+different kinds of import statement; when using \code{import
+spam.ham.eggs}, the top-level package \code{spam} must be placed in
+the importing namespace, but when using \code{from spam.ham import
+eggs}, the \code{spam.ham} subpackage must be used to find the
+\code{eggs} variable.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject *}{PyImport_Import}{PyObject *name}
+This is a higher-level interface that calls the current ``import hook
+function''. It invokes the \code{__import__()} function from the
+\code{__builtins__} of the current globals. This means that the
+import is done using whatever import hooks are installed in the
+current environment, e.g. by \code{rexec} or \code{ihooks}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject *}{PyImport_ReloadModule}{PyObject *m}
+Reload a module. This is best described by referring to the built-in
+Python function \code{reload()}, as the standard \code{reload()}
+function calls this function directly. Return a new reference to the
+reloaded module, or \code{NULL} with an exception set on failure (the
+module still exists in this case).
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject *}{PyImport_AddModule}{char *name}
+Return the module object corresponding to a module name. The
+\var{name} argument may be of the form \code{package.module}). First
+check the modules dictionary if there's one there, and if not, create
+a new one and insert in in the modules dictionary. Because the former
+action is most common, this does not return a new reference, and you
+do not own the returned reference. Return \code{NULL} with an
+exception set on failure.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject *}{PyImport_ExecCodeModule}{char *name, PyObject *co}
+Given a module name (possibly of the form \code{package.module}) and a
+code object read from a Python bytecode file or obtained from the
+built-in function \code{compile()}, load the module. Return a new
+reference to the module object, or \code{NULL} with an exception set
+if an error occurred (the module may still be created in this case).
+(This function would reload the module if it was already imported.)
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{long}{PyImport_GetMagicNumber}{}
+Return the magic number for Python bytecode files (a.k.a. \code{.pyc}
+and \code{.pyo} files). The magic number should be present in the
+first four bytes of the bytecode file, in little-endian byte order.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject *}{PyImport_GetModuleDict}{}
+Return the dictionary used for the module administration
+(a.k.a. \code{sys.modules}). Note that this is a per-interpreter
+variable.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{_PyImport_Init}{}
+Initialize the import mechanism. For internal use only.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyImport_Cleanup}{}
+Empty the module table. For internal use only.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{_PyImport_Fini}{}
+Finalize the import mechanism. For internal use only.
+\end{cfuncdesc}
+
+\begin{cvardesc}{extern PyObject *}{_PyImport_FindExtension}{char *, char *}
+For internal use only.
+\end{cvardesc}
+
+\begin{cvardesc}{extern PyObject *}{_PyImport_FixupExtension}{char *, char *}
+For internal use only.
+\end{cvardesc}
+
+\begin{cfuncdesc}{int}{PyImport_ImportFrozenModule}{char *}
+Load a frozen module. Return \code{1} for success, \code{0} if the
+module is not found, and \code{-1} with an exception set if the
+initialization failed. To access the imported module on a successful
+load, use \code{PyImport_ImportModule()).
+(Note the misnomer -- this function would reload the module if it was
+already imported.)
+\end{cfuncdesc}
+
+\begin{ctypedesc}{struct _frozen}
+This is the structure type definition for frozen module descriptors,
+as generated by the \code{freeze} utility (see \file{Tools/freeze/} in
+the Python source distribution). Its definition is:
+\bcode\begin{verbatim}
+struct _frozen {
+ char *name;
+ unsigned char *code;
+ int size;
+};
+\end{verbatim}\ecode
+\end{ctypedesc}
+
+\begin{cvardesc}{struct _frozen *}{PyImport_FrozenModules}
+This pointer is initialized to point to an array of \code{struct
+_freeze} records, terminated by one whose members are all \code{NULL}
+or zero. When a frozen module is imported, it is searched in this
+table. Third party code could play tricks with this to provide a
+dynamically created collection of frozen modules.
+\end{cvardesc}
+
+
\chapter{Debugging}
XXX Explain Py_DEBUG, Py_TRACE_REFS, Py_REF_DEBUG.
@@ -1557,20 +1755,29 @@ functions; with the exception of \code{Py_SetProgramName()},
modules (\code{sys.modules}), and creates the fundamental modules
\code{__builtin__}, \code{__main__} and \code{sys}. It also
initializes the module search path (\code{sys.path}). It does not set
-\code{sys.argv}; use \code{PySys_SetArgv()} for that. It is a fatal
-error to call it for a second time without calling
-\code{Py_Finalize()} first. There is no return value; it is a fatal
-error if the initialization fails.
+\code{sys.argv}; use \code{PySys_SetArgv()} for that. This is a no-op
+when called for a second time (without calling \code{Py_Finalize()}
+first). There is no return value; it is a fatal error if the
+initialization fails.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{Py_IsInitialized}{}
+\strong{NEW in 1.5a4!}
+Return true (nonzero) when the Python interpreter has been
+initialized, false (zero) if not. After \code{Py_Finalize()} is
+called, this returns false until \code{Py_Initialize()} is called
+again.
\end{cfuncdesc}
\begin{cfuncdesc}{void}{Py_Finalize}{}
+\strong{NEW in 1.5a3!}
Undo all initializations made by \code{Py_Initialize()} and subsequent
use of Python/C API functions, and destroy all sub-interpreters (see
\code{Py_NewInterpreter()} below) that were created and not yet
-destroyed since the last call to \code{Py_Initialize()}. Ideally,
-this frees all memory allocated by the Python interpreter. It is a
-fatal error to call it for a second time without calling
-\code{Py_Initialize()} again first. There is no return value; errors
+destroyed since the last call to \code{Py_Initialize()}. Ideally,
+this frees all memory allocated by the Python interpreter. This is a
+no-op when called for a second time (without calling
+\code{Py_Initialize()} again first). There is no return value; errors
during finalization are ignored.
This function is provided for a number of reasons. An embedding
@@ -1595,6 +1802,7 @@ calls \code{Py_Initialize()} and \code{Py_Finalize()} more than once.
\end{cfuncdesc}
\begin{cfuncdesc}{PyThreadState *}{Py_NewInterpreter}{}
+\strong{NEW in 1.5a3!}
Create a new sub-interpreter. This is an (almost) totally separate
environment for the execution of Python code. In particular, the new
interpreter has separate, independent versions of all imported
@@ -1647,6 +1855,7 @@ a hard-to-fix bug that will be addressed in a future release.)
\end{cfuncdesc}
\begin{cfuncdesc}{void}{Py_EndInterpreter}{PyThreadState *tstate}
+\strong{NEW in 1.5a3!}
Destroy the (sub-)interpreter represented by the given thread state.
The given thread state must be the current thread state. See the
discussion of thread states below. When the call returns, the current
@@ -1658,6 +1867,7 @@ been explicitly destroyed at that point.
\end{cfuncdesc}
\begin{cfuncdesc}{void}{Py_SetProgramName}{char *name}
+\strong{NEW in 1.5a3!}
This function should be called before \code{Py_Initialize()} is called
for the first time, if it is called at all. It tells the interpreter
the value of the \code{argv[0]} argument to the \code{main()} function
@@ -1729,12 +1939,13 @@ platform.
\end{cfuncdesc}
\begin{cfuncdesc}{char *}{Py_GetProgramFullPath}{}
+\strong{NEW in 1.5a3!}
Return the full program name of the Python executable; this is
computed as a side-effect of deriving the default module search path
from the program name (set by \code{Py_SetProgramName()} above). The
returned string points into static storage; the caller should not
modify its value. The value is available to Python code as
-\code{sys.executable}. % XXX is that the right sys.name?
+\code{sys.executable}.
\end{cfuncdesc}
\begin{cfuncdesc}{char *}{Py_GetPath}{}
@@ -1822,15 +2033,22 @@ the variable \code{sys.version}.
\section{Thread State and the Global Interpreter Lock}
\begin{cfuncdesc}{void}{PyEval_AcquireLock}{}
+\strong{NEW in 1.5a3!}
+HIRO
+
+
\end{cfuncdesc}
\begin{cfuncdesc}{void}{PyEval_ReleaseLock}{}
+\strong{NEW in 1.5a3!}
\end{cfuncdesc}
\begin{cfuncdesc}{void}{PyEval_AcquireThread}{PyThreadState *tstate}
+\strong{NEW in 1.5a3!}
\end{cfuncdesc}
\begin{cfuncdesc}{void}{PyEval_ReleaseThread}{PyThreadState *tstate}
+\strong{NEW in 1.5a3!}
\end{cfuncdesc}
\begin{cfuncdesc}{void}{PyEval_RestoreThread}{PyThreadState *tstate}