Commits

Anonymous committed 354242c

This commit was manufactured by cvs2svn to create tag 'r212c1'.

  • Participants
  • Parent commits 1edf5ed
  • Branches 2.1
  • Tags v2.1.2c1

Comments (0)

Files changed (655)

File Doc/Makefile

 
 # This is the *documentation* release, and is used to construct the file
 # names of the downloadable tarballs.
-RELEASE=2.1.2c1
+RELEASE=2.1.1
 
 PYTHON=	   python
 DVIPS=	   dvips -N0 -t $(PAPER)

File Doc/api/api.tex

-\documentclass{manual}
-
-\title{Python/C API Reference Manual}
-
-\input{boilerplate}
-
-\makeindex			% tell \index to actually write the .idx file
-
-
-\begin{document}
-
-\maketitle
-
-\ifhtml
-\chapter*{Front Matter\label{front}}
-\fi
-
-\input{copyright}
-
-\begin{abstract}
-
-\noindent
-This manual documents the API used by C and \Cpp{} programmers who
-want to write extension modules or embed Python.  It is a companion to
-\citetitle[../ext/ext.html]{Extending and Embedding the Python
-Interpreter}, which describes the general principles of extension
-writing but does not document the API functions in detail.
-
-\strong{Warning:} The current version of this document is incomplete.
-I hope that it is nevertheless useful.  I will continue to work on it,
-and release new versions from time to time, independent from Python
-source code releases.
-
-\end{abstract}
-
-\tableofcontents
-
-% XXX Consider moving all this back to ext.tex and giving api.tex
-% XXX a *really* short intro only.
-
-\chapter{Introduction \label{intro}}
-
-The Application Programmer's Interface to Python gives C and
-\Cpp{} programmers access to the Python interpreter at a variety of
-levels.  The API is equally usable from \Cpp{}, but for brevity it is
-generally referred to as the Python/C API.  There are two
-fundamentally different reasons for using the Python/C API.  The first
-reason is to write \emph{extension modules} for specific purposes;
-these are C modules that extend the Python interpreter.  This is
-probably the most common use.  The second reason is to use Python as a
-component in a larger application; this technique is generally
-referred to as \dfn{embedding} Python in an application.
-
-Writing an extension module is a relatively well-understood process, 
-where a ``cookbook'' approach works well.  There are several tools 
-that automate the process to some extent.  While people have embedded 
-Python in other applications since its early existence, the process of 
-embedding Python is less straightforward than writing an extension.  
-
-Many API functions are useful independent of whether you're embedding 
-or extending Python; moreover, most applications that embed Python 
-will need to provide a custom extension as well, so it's probably a 
-good idea to become familiar with writing an extension before 
-attempting to embed Python in a real application.
-
-
-\section{Include Files \label{includes}}
-
-All function, type and macro definitions needed to use the Python/C
-API are included in your code by the following line:
-
-\begin{verbatim}
-#include "Python.h"
-\end{verbatim}
-
-This implies inclusion of the following standard headers:
-\code{<stdio.h>}, \code{<string.h>}, \code{<errno.h>},
-\code{<limits.h>}, and \code{<stdlib.h>} (if available).
-
-All user visible names defined by Python.h (except those defined by
-the included standard headers) have one of the prefixes \samp{Py} or
-\samp{_Py}.  Names beginning with \samp{_Py} are for internal use by
-the Python implementation and should not be used by extension writers.
-Structure member names do not have a reserved prefix.
-
-\strong{Important:} user code should never define names that begin
-with \samp{Py} or \samp{_Py}.  This confuses the reader, and
-jeopardizes the portability of the user code to future Python
-versions, which may define additional names beginning with one of
-these prefixes.
-
-The header files are typically installed with Python.  On \UNIX, these 
-are located in the directories
-\file{\envvar{prefix}/include/python\var{version}/} and
-\file{\envvar{exec_prefix}/include/python\var{version}/}, where
-\envvar{prefix} and \envvar{exec_prefix} are defined by the
-corresponding parameters to Python's \program{configure} script and
-\var{version} is \code{sys.version[:3]}.  On Windows, the headers are
-installed in \file{\envvar{prefix}/include}, where \envvar{prefix} is
-the installation directory specified to the installer.
-
-To include the headers, place both directories (if different) on your
-compiler's search path for includes.  Do \emph{not} place the parent
-directories on the search path and then use
-\samp{\#include <python\shortversion/Python.h>}; this will break on
-multi-platform builds since the platform independent headers under
-\envvar{prefix} include the platform specific headers from
-\envvar{exec_prefix}.
-
-\Cpp{} users should note that though the API is defined entirely using
-C, the header files do properly declare the entry points to be
-\code{extern "C"}, so there is no need to do anything special to use
-the API from \Cpp.
-
-
-\section{Objects, Types and Reference Counts \label{objects}}
-
-Most Python/C API functions have one or more arguments as well as a
-return value of type \ctype{PyObject*}.  This type is a pointer
-to an opaque data type representing an arbitrary Python
-object.  Since all Python object types are treated the same way by the
-Python language in most situations (e.g., assignments, scope rules,
-and argument passing), it is only fitting that they should be
-represented by a single C type.  Almost all Python objects live on the
-heap: you never declare an automatic or static variable of type
-\ctype{PyObject}, only pointer variables of type \ctype{PyObject*} can 
-be declared.  The sole exception are the type objects\obindex{type};
-since these must never be deallocated, they are typically static
-\ctype{PyTypeObject} objects.
-
-All Python objects (even Python integers) have a \dfn{type} and a
-\dfn{reference count}.  An object's type determines what kind of object 
-it is (e.g., an integer, a list, or a user-defined function; there are 
-many more as explained in the \citetitle[../ref/ref.html]{Python
-Reference Manual}).  For each of the well-known types there is a macro
-to check whether an object is of that type; for instance,
-\samp{PyList_Check(\var{a})} is true if (and only if) the object
-pointed to by \var{a} is a Python list.
-
-
-\subsection{Reference Counts \label{refcounts}}
-
-The reference count is important because today's computers have a 
-finite (and often severely limited) memory size; it counts how many 
-different places there are that have a reference to an object.  Such a 
-place could be another object, or a global (or static) C variable, or 
-a local variable in some C function.  When an object's reference count 
-becomes zero, the object is deallocated.  If it contains references to 
-other objects, their reference count is decremented.  Those other 
-objects may be deallocated in turn, if this decrement makes their 
-reference count become zero, and so on.  (There's an obvious problem 
-with objects that reference each other here; for now, the solution is 
-``don't do that.'')
-
-Reference counts are always manipulated explicitly.  The normal way is 
-to use the macro \cfunction{Py_INCREF()}\ttindex{Py_INCREF()} to
-increment an object's reference count by one, and
-\cfunction{Py_DECREF()}\ttindex{Py_DECREF()} to decrement it by  
-one.  The \cfunction{Py_DECREF()} macro is considerably more complex
-than the incref one, since it must check whether the reference count
-becomes zero and then cause the object's deallocator to be called.
-The deallocator is a function pointer contained in the object's type
-structure.  The type-specific deallocator takes care of decrementing
-the reference counts for other objects contained in the object if this
-is a compound object type, such as a list, as well as performing any
-additional finalization that's needed.  There's no chance that the
-reference count can overflow; at least as many bits are used to hold
-the reference count as there are distinct memory locations in virtual
-memory (assuming \code{sizeof(long) >= sizeof(char*)}).  Thus, the
-reference count increment is a simple operation.
-
-It is not necessary to increment an object's reference count for every 
-local variable that contains a pointer to an object.  In theory, the 
-object's reference count goes up by one when the variable is made to 
-point to it and it goes down by one when the variable goes out of 
-scope.  However, these two cancel each other out, so at the end the 
-reference count hasn't changed.  The only real reason to use the 
-reference count is to prevent the object from being deallocated as 
-long as our variable is pointing to it.  If we know that there is at 
-least one other reference to the object that lives at least as long as 
-our variable, there is no need to increment the reference count 
-temporarily.  An important situation where this arises is in objects 
-that are passed as arguments to C functions in an extension module 
-that are called from Python; the call mechanism guarantees to hold a 
-reference to every argument for the duration of the call.
-
-However, a common pitfall is to extract an object from a list and
-hold on to it for a while without incrementing its reference count.
-Some other operation might conceivably remove the object from the
-list, decrementing its reference count and possible deallocating it.
-The real danger is that innocent-looking operations may invoke
-arbitrary Python code which could do this; there is a code path which
-allows control to flow back to the user from a \cfunction{Py_DECREF()},
-so almost any operation is potentially dangerous.
-
-A safe approach is to always use the generic operations (functions 
-whose name begins with \samp{PyObject_}, \samp{PyNumber_},
-\samp{PySequence_} or \samp{PyMapping_}).  These operations always
-increment the reference count of the object they return.  This leaves
-the caller with the responsibility to call
-\cfunction{Py_DECREF()} when they are done with the result; this soon
-becomes second nature.
-
-
-\subsubsection{Reference Count Details \label{refcountDetails}}
-
-The reference count behavior of functions in the Python/C API is best 
-explained in terms of \emph{ownership of references}.  Note that we 
-talk of owning references, never of owning objects; objects are always 
-shared!  When a function owns a reference, it has to dispose of it 
-properly --- either by passing ownership on (usually to its caller) or 
-by calling \cfunction{Py_DECREF()} or \cfunction{Py_XDECREF()}.  When
-a function passes ownership of a reference on to its caller, the
-caller is said to receive a \emph{new} reference.  When no ownership
-is transferred, the caller is said to \emph{borrow} the reference.
-Nothing needs to be done for a borrowed reference.
-
-Conversely, when a calling function passes it a reference to an 
-object, there are two possibilities: the function \emph{steals} a 
-reference to the object, or it does not.  Few functions steal 
-references; the two notable exceptions are
-\cfunction{PyList_SetItem()}\ttindex{PyList_SetItem()} and
-\cfunction{PyTuple_SetItem()}\ttindex{PyTuple_SetItem()}, which 
-steal a reference to the item (but not to the tuple or list into which
-the item is put!).  These functions were designed to steal a reference
-because of a common idiom for populating a tuple or list with newly
-created objects; for example, the code to create the tuple \code{(1,
-2, "three")} could look like this (forgetting about error handling for
-the moment; a better way to code this is shown below):
-
-\begin{verbatim}
-PyObject *t;
-
-t = PyTuple_New(3);
-PyTuple_SetItem(t, 0, PyInt_FromLong(1L));
-PyTuple_SetItem(t, 1, PyInt_FromLong(2L));
-PyTuple_SetItem(t, 2, PyString_FromString("three"));
-\end{verbatim}
-
-Incidentally, \cfunction{PyTuple_SetItem()} is the \emph{only} way to
-set tuple items; \cfunction{PySequence_SetItem()} and
-\cfunction{PyObject_SetItem()} refuse to do this since tuples are an
-immutable data type.  You should only use
-\cfunction{PyTuple_SetItem()} for tuples that you are creating
-yourself.
-
-Equivalent code for populating a list can be written using 
-\cfunction{PyList_New()} and \cfunction{PyList_SetItem()}.  Such code
-can also use \cfunction{PySequence_SetItem()}; this illustrates the
-difference between the two (the extra \cfunction{Py_DECREF()} calls):
-
-\begin{verbatim}
-PyObject *l, *x;
-
-l = PyList_New(3);
-x = PyInt_FromLong(1L);
-PySequence_SetItem(l, 0, x); Py_DECREF(x);
-x = PyInt_FromLong(2L);
-PySequence_SetItem(l, 1, x); Py_DECREF(x);
-x = PyString_FromString("three");
-PySequence_SetItem(l, 2, x); Py_DECREF(x);
-\end{verbatim}
-
-You might find it strange that the ``recommended'' approach takes more
-code.  However, in practice, you will rarely use these ways of
-creating and populating a tuple or list.  There's a generic function,
-\cfunction{Py_BuildValue()}, that can create most common objects from
-C values, directed by a \dfn{format string}.  For example, the
-above two blocks of code could be replaced by the following (which
-also takes care of the error checking):
-
-\begin{verbatim}
-PyObject *t, *l;
-
-t = Py_BuildValue("(iis)", 1, 2, "three");
-l = Py_BuildValue("[iis]", 1, 2, "three");
-\end{verbatim}
-
-It is much more common to use \cfunction{PyObject_SetItem()} and
-friends with items whose references you are only borrowing, like
-arguments that were passed in to the function you are writing.  In
-that case, their behaviour regarding reference counts is much saner,
-since you don't have to increment a reference count so you can give a
-reference away (``have it be stolen'').  For example, this function
-sets all items of a list (actually, any mutable sequence) to a given
-item:
-
-\begin{verbatim}
-int set_all(PyObject *target, PyObject *item)
-{
-    int i, n;
-
-    n = PyObject_Length(target);
-    if (n < 0)
-        return -1;
-    for (i = 0; i < n; i++) {
-        if (PyObject_SetItem(target, i, item) < 0)
-            return -1;
-    }
-    return 0;
-}
-\end{verbatim}
-\ttindex{set_all()}
-
-The situation is slightly different for function return values.  
-While passing a reference to most functions does not change your 
-ownership responsibilities for that reference, many functions that 
-return a referece to an object give you ownership of the reference.
-The reason is simple: in many cases, the returned object is created 
-on the fly, and the reference you get is the only reference to the 
-object.  Therefore, the generic functions that return object 
-references, like \cfunction{PyObject_GetItem()} and 
-\cfunction{PySequence_GetItem()}, always return a new reference (the
-caller becomes the owner of the reference).
-
-It is important to realize that whether you own a reference returned 
-by a function depends on which function you call only --- \emph{the
-plumage} (the type of the type of the object passed as an
-argument to the function) \emph{doesn't enter into it!}  Thus, if you 
-extract an item from a list using \cfunction{PyList_GetItem()}, you
-don't own the reference --- but if you obtain the same item from the
-same list using \cfunction{PySequence_GetItem()} (which happens to
-take exactly the same arguments), you do own a reference to the
-returned object.
-
-Here is an example of how you could write a function that computes the
-sum of the items in a list of integers; once using 
-\cfunction{PyList_GetItem()}\ttindex{PyList_GetItem()}, and once using
-\cfunction{PySequence_GetItem()}\ttindex{PySequence_GetItem()}.
-
-\begin{verbatim}
-long sum_list(PyObject *list)
-{
-    int i, n;
-    long total = 0;
-    PyObject *item;
-
-    n = PyList_Size(list);
-    if (n < 0)
-        return -1; /* Not a list */
-    for (i = 0; i < n; i++) {
-        item = PyList_GetItem(list, i); /* Can't fail */
-        if (!PyInt_Check(item)) continue; /* Skip non-integers */
-        total += PyInt_AsLong(item);
-    }
-    return total;
-}
-\end{verbatim}
-\ttindex{sum_list()}
-
-\begin{verbatim}
-long sum_sequence(PyObject *sequence)
-{
-    int i, n;
-    long total = 0;
-    PyObject *item;
-    n = PySequence_Length(sequence);
-    if (n < 0)
-        return -1; /* Has no length */
-    for (i = 0; i < n; i++) {
-        item = PySequence_GetItem(sequence, i);
-        if (item == NULL)
-            return -1; /* Not a sequence, or other failure */
-        if (PyInt_Check(item))
-            total += PyInt_AsLong(item);
-        Py_DECREF(item); /* Discard reference ownership */
-    }
-    return total;
-}
-\end{verbatim}
-\ttindex{sum_sequence()}
-
-
-\subsection{Types \label{types}}
-
-There are few other data types that play a significant role in 
-the Python/C API; most are simple C types such as \ctype{int}, 
-\ctype{long}, \ctype{double} and \ctype{char*}.  A few structure types 
-are used to describe static tables used to list the functions exported 
-by a module or the data attributes of a new object type, and another
-is used to describe the value of a complex number.  These will 
-be discussed together with the functions that use them.
-
-
-\section{Exceptions \label{exceptions}}
-
-The Python programmer only needs to deal with exceptions if specific 
-error handling is required; unhandled exceptions are automatically 
-propagated to the caller, then to the caller's caller, and so on, until
-they reach the top-level interpreter, where they are reported to the 
-user accompanied by a stack traceback.
-
-For C programmers, however, error checking always has to be explicit.  
-All functions in the Python/C API can raise exceptions, unless an 
-explicit claim is made otherwise in a function's documentation.  In 
-general, when a function encounters an error, it sets an exception, 
-discards any object references that it owns, and returns an 
-error indicator --- usually \NULL{} or \code{-1}.  A few functions 
-return a Boolean true/false result, with false indicating an error.
-Very few functions return no explicit error indicator or have an 
-ambiguous return value, and require explicit testing for errors with 
-\cfunction{PyErr_Occurred()}\ttindex{PyErr_Occurred()}.
-
-Exception state is maintained in per-thread storage (this is 
-equivalent to using global storage in an unthreaded application).  A 
-thread can be in one of two states: an exception has occurred, or not.
-The function \cfunction{PyErr_Occurred()} can be used to check for
-this: it returns a borrowed reference to the exception type object
-when an exception has occurred, and \NULL{} otherwise.  There are a
-number of functions to set the exception state:
-\cfunction{PyErr_SetString()}\ttindex{PyErr_SetString()} is the most
-common (though not the most general) function to set the exception
-state, and \cfunction{PyErr_Clear()}\ttindex{PyErr_Clear()} clears the
-exception state.
-
-The full exception state consists of three objects (all of which can 
-be \NULL{}): the exception type, the corresponding exception 
-value, and the traceback.  These have the same meanings as the Python
-\withsubitem{(in module sys)}{
-  \ttindex{exc_type}\ttindex{exc_value}\ttindex{exc_traceback}}
-objects \code{sys.exc_type}, \code{sys.exc_value}, and
-\code{sys.exc_traceback}; however, they are not the same: the Python
-objects represent the last exception being handled by a Python 
-\keyword{try} \ldots\ \keyword{except} statement, while the C level
-exception state only exists while an exception is being passed on
-between C functions until it reaches the Python bytecode interpreter's 
-main loop, which takes care of transferring it to \code{sys.exc_type}
-and friends.
-
-Note that starting with Python 1.5, the preferred, thread-safe way to 
-access the exception state from Python code is to call the function
-\withsubitem{(in module sys)}{\ttindex{exc_info()}}
-\function{sys.exc_info()}, which returns the per-thread exception state 
-for Python code.  Also, the semantics of both ways to access the 
-exception state have changed so that a function which catches an 
-exception will save and restore its thread's exception state so as to 
-preserve the exception state of its caller.  This prevents common bugs 
-in exception handling code caused by an innocent-looking function 
-overwriting the exception being handled; it also reduces the often 
-unwanted lifetime extension for objects that are referenced by the 
-stack frames in the traceback.
-
-As a general principle, a function that calls another function to 
-perform some task should check whether the called function raised an 
-exception, and if so, pass the exception state on to its caller.  It 
-should discard any object references that it owns, and return an 
-error indicator, but it should \emph{not} set another exception ---
-that would overwrite the exception that was just raised, and lose
-important information about the exact cause of the error.
-
-A simple example of detecting exceptions and passing them on is shown
-in the \cfunction{sum_sequence()}\ttindex{sum_sequence()} example
-above.  It so happens that that example doesn't need to clean up any
-owned references when it detects an error.  The following example
-function shows some error cleanup.  First, to remind you why you like
-Python, we show the equivalent Python code:
-
-\begin{verbatim}
-def incr_item(dict, key):
-    try:
-        item = dict[key]
-    except KeyError:
-        item = 0
-    dict[key] = item + 1
-\end{verbatim}
-\ttindex{incr_item()}
-
-Here is the corresponding C code, in all its glory:
-
-\begin{verbatim}
-int incr_item(PyObject *dict, PyObject *key)
-{
-    /* Objects all initialized to NULL for Py_XDECREF */
-    PyObject *item = NULL, *const_one = NULL, *incremented_item = NULL;
-    int rv = -1; /* Return value initialized to -1 (failure) */
-
-    item = PyObject_GetItem(dict, key);
-    if (item == NULL) {
-        /* Handle KeyError only: */
-        if (!PyErr_ExceptionMatches(PyExc_KeyError))
-            goto error;
-
-        /* Clear the error and use zero: */
-        PyErr_Clear();
-        item = PyInt_FromLong(0L);
-        if (item == NULL)
-            goto error;
-    }
-    const_one = PyInt_FromLong(1L);
-    if (const_one == NULL)
-        goto error;
-
-    incremented_item = PyNumber_Add(item, const_one);
-    if (incremented_item == NULL)
-        goto error;
-
-    if (PyObject_SetItem(dict, key, incremented_item) < 0)
-        goto error;
-    rv = 0; /* Success */
-    /* Continue with cleanup code */
-
- error:
-    /* Cleanup code, shared by success and failure path */
-
-    /* Use Py_XDECREF() to ignore NULL references */
-    Py_XDECREF(item);
-    Py_XDECREF(const_one);
-    Py_XDECREF(incremented_item);
-
-    return rv; /* -1 for error, 0 for success */
-}
-\end{verbatim}
-\ttindex{incr_item()}
-
-This example represents an endorsed use of the \keyword{goto} statement 
-in C!  It illustrates the use of
-\cfunction{PyErr_ExceptionMatches()}\ttindex{PyErr_ExceptionMatches()} and
-\cfunction{PyErr_Clear()}\ttindex{PyErr_Clear()} to
-handle specific exceptions, and the use of
-\cfunction{Py_XDECREF()}\ttindex{Py_XDECREF()} to
-dispose of owned references that may be \NULL{} (note the
-\character{X} in the name; \cfunction{Py_DECREF()} would crash when
-confronted with a \NULL{} reference).  It is important that the
-variables used to hold owned references are initialized to \NULL{} for
-this to work; likewise, the proposed return value is initialized to
-\code{-1} (failure) and only set to success after the final call made
-is successful.
-
-
-\section{Embedding Python \label{embedding}}
-
-The one important task that only embedders (as opposed to extension
-writers) of the Python interpreter have to worry about is the
-initialization, and possibly the finalization, of the Python
-interpreter.  Most functionality of the interpreter can only be used
-after the interpreter has been initialized.
-
-The basic initialization function is
-\cfunction{Py_Initialize()}\ttindex{Py_Initialize()}.
-This initializes the table of loaded modules, and creates the
-fundamental modules \module{__builtin__}\refbimodindex{__builtin__},
-\module{__main__}\refbimodindex{__main__} and 
-\module{sys}\refbimodindex{sys}.  It also initializes the module
-search path (\code{sys.path}).%
-\indexiii{module}{search}{path}
-\withsubitem{(in module sys)}{\ttindex{path}}
-
-\cfunction{Py_Initialize()} does not set the ``script argument list'' 
-(\code{sys.argv}).  If this variable is needed by Python code that 
-will be executed later, it must be set explicitly with a call to 
-\code{PySys_SetArgv(\var{argc},
-\var{argv})}\ttindex{PySys_SetArgv()} subsequent to the call to
-\cfunction{Py_Initialize()}.
-
-On most systems (in particular, on \UNIX{} and Windows, although the
-details are slightly different),
-\cfunction{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
-\file{lib/python\shortversion} relative to the parent directory where
-the executable named \file{python} is found on the shell command
-search path (the environment variable \envvar{PATH}).
-
-For instance, if the Python executable is found in
-\file{/usr/local/bin/python}, it will assume that the libraries are in
-\file{/usr/local/lib/python\shortversion}.  (In fact, this particular path
-is also the ``fallback'' location, used when no executable file named
-\file{python} is found along \envvar{PATH}.)  The user can override
-this behavior by setting the environment variable \envvar{PYTHONHOME},
-or insert additional directories in front of the standard path by
-setting \envvar{PYTHONPATH}.
-
-The embedding application can steer the search by calling 
-\code{Py_SetProgramName(\var{file})}\ttindex{Py_SetProgramName()} \emph{before} calling 
-\cfunction{Py_Initialize()}.  Note that \envvar{PYTHONHOME} still
-overrides this and \envvar{PYTHONPATH} is still inserted in front of
-the standard path.  An application that requires total control has to
-provide its own implementation of
-\cfunction{Py_GetPath()}\ttindex{Py_GetPath()},
-\cfunction{Py_GetPrefix()}\ttindex{Py_GetPrefix()},
-\cfunction{Py_GetExecPrefix()}\ttindex{Py_GetExecPrefix()}, and
-\cfunction{Py_GetProgramFullPath()}\ttindex{Py_GetProgramFullPath()} (all
-defined in \file{Modules/getpath.c}).
-
-Sometimes, it is desirable to ``uninitialize'' Python.  For instance, 
-the application may want to start over (make another call to 
-\cfunction{Py_Initialize()}) or the application is simply done with its 
-use of Python and wants to free all memory allocated by Python.  This
-can be accomplished by calling \cfunction{Py_Finalize()}.  The function
-\cfunction{Py_IsInitialized()}\ttindex{Py_IsInitialized()} returns
-true if Python is currently in the initialized state.  More
-information about these functions is given in a later chapter.
-
-
-\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
-  in case of 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}
-
-
-\chapter{Reference Counting \label{countingRefs}}
-
-The macros in this section are used for managing reference counts
-of Python objects.
-
-\begin{cfuncdesc}{void}{Py_INCREF}{PyObject *o}
-Increment the reference count for object \var{o}.  The object must
-not be \NULL{}; if you aren't sure that it isn't \NULL{}, use
-\cfunction{Py_XINCREF()}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{Py_XINCREF}{PyObject *o}
-Increment the reference count for object \var{o}.  The object may be
-\NULL{}, in which case the macro has no effect.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{Py_DECREF}{PyObject *o}
-Decrement the reference count for object \var{o}.  The object must
-not be \NULL{}; if you aren't sure that it isn't \NULL{}, use
-\cfunction{Py_XDECREF()}.  If the reference count reaches zero, the
-object's type's deallocation function (which must not be \NULL{}) is
-invoked.
-
-\strong{Warning:} The deallocation function can cause arbitrary Python
-code to be invoked (e.g. when a class instance with a
-\method{__del__()} method is deallocated).  While exceptions in such
-code are not propagated, the executed code has free access to all
-Python global variables.  This means that any object that is reachable
-from a global variable should be in a consistent state before
-\cfunction{Py_DECREF()} is invoked.  For example, code to delete an
-object from a list should copy a reference to the deleted object in a
-temporary variable, update the list data structure, and then call
-\cfunction{Py_DECREF()} for the temporary variable.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{Py_XDECREF}{PyObject *o}
-Decrement the reference count for object \var{o}.  The object may be
-\NULL{}, in which case the macro has no effect; otherwise the effect
-is the same as for \cfunction{Py_DECREF()}, and the same warning
-applies.
-\end{cfuncdesc}
-
-The following functions or macros are only for use within the
-interpreter core: \cfunction{_Py_Dealloc()},
-\cfunction{_Py_ForgetReference()}, \cfunction{_Py_NewReference()}, as
-well as the global variable \cdata{_Py_RefTotal}.
-
-
-\chapter{Exception Handling \label{exceptionHandling}}
-
-The functions described in this chapter will let you handle and raise Python
-exceptions.  It is important to understand some of the basics of
-Python exception handling.  It works somewhat like the
-\UNIX{} \cdata{errno} variable: there is a global indicator (per
-thread) of the last error that occurred.  Most functions don't clear
-this on success, but will set it to indicate the cause of the error on
-failure.  Most functions also return an error indicator, usually
-\NULL{} if they are supposed to return a pointer, or \code{-1} if they
-return an integer (exception: the \cfunction{PyArg_Parse*()} functions
-return \code{1} for success and \code{0} for failure).  When a
-function must fail because some function it called failed, it
-generally doesn't set the error indicator; the function it called
-already set it.
-
-The error indicator consists of three Python objects corresponding to
-\withsubitem{(in module sys)}{
-  \ttindex{exc_type}\ttindex{exc_value}\ttindex{exc_traceback}}
-the Python variables \code{sys.exc_type}, \code{sys.exc_value} and
-\code{sys.exc_traceback}.  API functions exist to interact with the
-error indicator in various ways.  There is a separate error indicator
-for each thread.
-
-% XXX Order of these should be more thoughtful.
-% Either alphabetical or some kind of structure.
-
-\begin{cfuncdesc}{void}{PyErr_Print}{}
-Print a standard traceback to \code{sys.stderr} and clear the error
-indicator.  Call this function only when the error indicator is set.
-(Otherwise it will cause a fatal error!)
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyErr_Occurred}{}
-Test whether the error indicator is set.  If set, return the exception
-\emph{type} (the first argument to the last call to one of the
-\cfunction{PyErr_Set*()} functions or to \cfunction{PyErr_Restore()}).  If
-not set, return \NULL{}.  You do not own a reference to the return
-value, so you do not need to \cfunction{Py_DECREF()} it.
-\strong{Note:}  Do not compare the return value to a specific
-exception; use \cfunction{PyErr_ExceptionMatches()} instead, shown
-below.  (The comparison could easily fail since the exception may be
-an instance instead of a class, in the case of a class exception, or
-it may the a subclass of the expected exception.)
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyErr_ExceptionMatches}{PyObject *exc}
-Equivalent to
-\samp{PyErr_GivenExceptionMatches(PyErr_Occurred(), \var{exc})}.
-This should only be called when an exception is actually set; a memory 
-access violation will occur if no exception has been raised.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyErr_GivenExceptionMatches}{PyObject *given, PyObject *exc}
-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 an instance of a subclass.  If \var{exc} is a tuple, all
-exceptions in the tuple (and recursively in subtuples) are searched
-for a match.  If \var{given} is \NULL, a memory access violation will
-occur.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyErr_NormalizeException}{PyObject**exc, PyObject**val, PyObject**tb}
-Under certain circumstances, the values returned by
-\cfunction{PyErr_Fetch()} below can be ``unnormalized'', meaning that
-\code{*\var{exc}} is a class object but \code{*\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.  The delayed normalization is implemented to improve
-performance.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyErr_Clear}{}
-Clear the error indicator.  If the error indicator is not set, there
-is no effect.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyErr_Fetch}{PyObject **ptype, PyObject **pvalue,
-                                     PyObject **ptraceback}
-Retrieve the error indicator into three variables whose addresses are
-passed.  If the error indicator is not set, set all three variables to
-\NULL{}.  If it is set, it will be cleared and you own a reference to
-each object retrieved.  The value and traceback object may be
-\NULL{} even when the type object is not.  \strong{Note:}  This
-function is normally only used by code that needs to handle exceptions
-or by code that needs to save and restore the error indicator
-temporarily.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyErr_Restore}{PyObject *type, PyObject *value,
-                                       PyObject *traceback}
-Set  the error indicator from the three objects.  If the error
-indicator is already set, it is cleared first.  If the objects are
-\NULL{}, the error indicator is cleared.  Do not pass a \NULL{} type
-and non-\NULL{} value or traceback.  The exception type should be a
-string or class; if it is a class, the value should be an instance of
-that class.  Do not pass an invalid exception type or value.
-(Violating these rules will cause subtle problems later.)  This call
-takes away a reference to each object: you must own a reference
-to each object before the call and after the call you no longer own
-these references.  (If you don't understand this, don't use this
-function.  I warned you.)  \strong{Note:}  This function is normally
-only used by code that needs to save and restore the error indicator
-temporarily.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyErr_SetString}{PyObject *type, char *message}
-This is the most common way to set the error indicator.  The first
-argument specifies the exception type; it is normally one of the
-standard exceptions, e.g. \cdata{PyExc_RuntimeError}.  You need not
-increment its reference count.  The second argument is an error
-message; it is converted to a string object.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyErr_SetObject}{PyObject *type, PyObject *value}
-This function is similar to \cfunction{PyErr_SetString()} but lets you
-specify an arbitrary Python object for the ``value'' of the exception.
-You need not increment its reference count.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyErr_Format}{PyObject *exception,
-                                           const char *format, \moreargs}
-This function sets the error indicator.  \var{exception} should be a
-Python exception (string or class, not an instance).
-\var{format} should be a string, containing format codes, similar to 
-\cfunction{printf}. The \code{width.precision} before a format code
-is parsed, but the width part is ignored.
-
-\begin{tableii}{c|l}{character}{Character}{Meaning}
-  \lineii{c}{Character, as an \ctype{int} parameter}
-  \lineii{d}{Number in decimal, as an \ctype{int} parameter}
-  \lineii{x}{Number in hexadecimal, as an \ctype{int} parameter}
-  \lineii{x}{A string, as a \ctype{char *} parameter}
-\end{tableii}
-
-An unrecognized format character causes all the rest of
-the format string to be copied as-is to the result string,
-and any extra arguments discarded.
-
-A new reference is returned, which is owned by the caller.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyErr_SetNone}{PyObject *type}
-This is a shorthand for \samp{PyErr_SetObject(\var{type}, Py_None)}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyErr_BadArgument}{}
-This is a shorthand for \samp{PyErr_SetString(PyExc_TypeError,
-\var{message})}, where \var{message} indicates that a built-in operation
-was invoked with an illegal argument.  It is mostly for internal use.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyErr_NoMemory}{}
-This is a shorthand for \samp{PyErr_SetNone(PyExc_MemoryError)}; it
-returns \NULL{} so an object allocation function can write
-\samp{return PyErr_NoMemory();} when it runs out of memory.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyErr_SetFromErrno}{PyObject *type}
-This is a convenience function to raise an exception when a C library
-function has returned an error and set the C variable \cdata{errno}.
-It constructs a tuple object whose first item is the integer
-\cdata{errno} value and whose second item is the corresponding error
-message (gotten from \cfunction{strerror()}\ttindex{strerror()}), and
-then calls
-\samp{PyErr_SetObject(\var{type}, \var{object})}.  On \UNIX{}, when
-the \cdata{errno} value is \constant{EINTR}, indicating an interrupted
-system call, this calls \cfunction{PyErr_CheckSignals()}, and if that set
-the error indicator, leaves it set to that.  The function always
-returns \NULL{}, so a wrapper function around a system call can write 
-\samp{return PyErr_SetFromErrno();} when  the system call returns an
-error.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyErr_SetFromErrnoWithFilename}{PyObject *type,
-                                                             char *filename}
-Similar to \cfunction{PyErr_SetFromErrno()}, with the additional
-behavior that if \var{filename} is not \NULL, it is passed to the
-constructor of \var{type} as a third parameter.  In the case of
-exceptions such as \exception{IOError} and \exception{OSError}, this
-is used to define the \member{filename} attribute of the exception
-instance.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyErr_BadInternalCall}{}
-This is a shorthand for \samp{PyErr_SetString(PyExc_TypeError,
-\var{message})}, where \var{message} indicates that an internal
-operation (e.g. a Python/C API function) was invoked with an illegal
-argument.  It is mostly for internal use.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyErr_Warn}{PyObject *category, char *message}
-Issue a warning message.  The \var{category} argument is a warning
-category (see below) or \NULL; the \var{message} argument is a message
-string.
-
-This function normally prints a warning message to \var{sys.stderr};
-however, it is also possible that the user has specified that warnings
-are to be turned into errors, and in that case this will raise an
-exception.  It is also possible that the function raises an exception
-because of a problem with the warning machinery (the implementation
-imports the \module{warnings} module to do the heavy lifting).  The
-return value is \code{0} if no exception is raised, or \code{-1} if
-an exception is raised.  (It is not possible to determine whether a
-warning message is actually printed, nor what the reason is for the
-exception; this is intentional.)  If an exception is raised, the
-caller should do its normal exception handling
-(e.g. \cfunction{Py_DECREF()} owned references and return an error
-value).
-
-Warning categories must be subclasses of \cdata{Warning}; the default
-warning category is \cdata{RuntimeWarning}.  The standard Python
-warning categories are available as global variables whose names are
-\samp{PyExc_} followed by the Python exception name.  These have the
-type \ctype{PyObject*}; they are all class objects.  Their names are
-\cdata{PyExc_Warning}, \cdata{PyExc_UserWarning},
-\cdata{PyExc_DeprecationWarning}, \cdata{PyExc_SyntaxWarning}, and
-\cdata{PyExc_RuntimeWarning}.  \cdata{PyExc_Warning} is a subclass of
-\cdata{PyExc_Exception}; the other warning categories are subclasses
-of \cdata{PyExc_Warning}.
-
-For information about warning control, see the documentation for the
-\module{warnings} module and the \programopt{-W} option in the command
-line documentation.  There is no C API for warning control.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyErr_WarnExplicit}{PyObject *category, char *message,
-char *filename, int lineno, char *module, PyObject *registry}
-Issue a warning message with explicit control over all warning
-attributes.  This is a straightforward wrapper around the Python
-function \function{warnings.warn_explicit()}, see there for more
-information.  The \var{module} and \var{registry} arguments may be
-set to \code{NULL} to get the default effect described there.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyErr_CheckSignals}{}
-This function interacts with Python's signal handling.  It checks
-whether a signal has been sent to the processes and if so, invokes the
-corresponding signal handler.  If the
-\module{signal}\refbimodindex{signal} module is supported, this can
-invoke a signal handler written in Python.  In all cases, the default
-effect for \constant{SIGINT}\ttindex{SIGINT} is to raise the
-\withsubitem{(built-in exception)}{\ttindex{KeyboardInterrupt}}
-\exception{KeyboardInterrupt} exception.  If an exception is raised the 
-error indicator is set and the function returns \code{1}; otherwise
-the function returns \code{0}.  The error indicator may or may not be
-cleared if it was previously set.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyErr_SetInterrupt}{}
-This function is obsolete.  It simulates the effect of a
-\constant{SIGINT}\ttindex{SIGINT} signal arriving --- the next time
-\cfunction{PyErr_CheckSignals()} is called,
-\withsubitem{(built-in exception)}{\ttindex{KeyboardInterrupt}}
-\exception{KeyboardInterrupt} will be raised.
-It may be called without holding the interpreter lock.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyErr_NewException}{char *name,
-                                                 PyObject *base,
-                                                 PyObject *dict}
-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 \NULL{}.  This creates a
-class object derived from the root for all exceptions, the built-in
-name \exception{Exception} (accessible in C as
-\cdata{PyExc_Exception}).  The \member{__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).  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}
-
-\begin{cfuncdesc}{void}{PyErr_WriteUnraisable}{PyObject *obj}
-This utility function prints a warning message to \var{sys.stderr}
-when an exception has been set but it is impossible for the
-interpreter to actually raise the exception.  It is used, for example,
-when an exception occurs in an \member{__del__} method.
-
-The function is called with a single argument \var{obj} that
-identifies where the context in which the unraisable exception
-occurred.  The repr of \var{obj} will be printed in the warning
-message.
-\end{cfuncdesc}
-
-\section{Standard Exceptions \label{standardExceptions}}
-
-All standard Python exceptions are available as global variables whose
-names are \samp{PyExc_} followed by the Python exception name.  These
-have the type \ctype{PyObject*}; they are all class objects.  For
-completeness, here are all the variables:
-
-\begin{tableiii}{l|l|c}{cdata}{C Name}{Python Name}{Notes}
-  \lineiii{PyExc_Exception}{\exception{Exception}}{(1)}
-  \lineiii{PyExc_StandardError}{\exception{StandardError}}{(1)}
-  \lineiii{PyExc_ArithmeticError}{\exception{ArithmeticError}}{(1)}
-  \lineiii{PyExc_LookupError}{\exception{LookupError}}{(1)}
-  \lineiii{PyExc_AssertionError}{\exception{AssertionError}}{}
-  \lineiii{PyExc_AttributeError}{\exception{AttributeError}}{}
-  \lineiii{PyExc_EOFError}{\exception{EOFError}}{}
-  \lineiii{PyExc_EnvironmentError}{\exception{EnvironmentError}}{(1)}
-  \lineiii{PyExc_FloatingPointError}{\exception{FloatingPointError}}{}
-  \lineiii{PyExc_IOError}{\exception{IOError}}{}
-  \lineiii{PyExc_ImportError}{\exception{ImportError}}{}
-  \lineiii{PyExc_IndexError}{\exception{IndexError}}{}
-  \lineiii{PyExc_KeyError}{\exception{KeyError}}{}
-  \lineiii{PyExc_KeyboardInterrupt}{\exception{KeyboardInterrupt}}{}
-  \lineiii{PyExc_MemoryError}{\exception{MemoryError}}{}
-  \lineiii{PyExc_NameError}{\exception{NameError}}{}
-  \lineiii{PyExc_NotImplementedError}{\exception{NotImplementedError}}{}
-  \lineiii{PyExc_OSError}{\exception{OSError}}{}
-  \lineiii{PyExc_OverflowError}{\exception{OverflowError}}{}
-  \lineiii{PyExc_RuntimeError}{\exception{RuntimeError}}{}
-  \lineiii{PyExc_SyntaxError}{\exception{SyntaxError}}{}
-  \lineiii{PyExc_SystemError}{\exception{SystemError}}{}
-  \lineiii{PyExc_SystemExit}{\exception{SystemExit}}{}
-  \lineiii{PyExc_TypeError}{\exception{TypeError}}{}
-  \lineiii{PyExc_ValueError}{\exception{ValueError}}{}
-  \lineiii{PyExc_WindowsError}{\exception{WindowsError}}{(2)}
-  \lineiii{PyExc_ZeroDivisionError}{\exception{ZeroDivisionError}}{}
-\end{tableiii}
-
-\noindent
-Notes:
-\begin{description}
-\item[(1)]
-  This is a base class for other standard exceptions.
-
-\item[(2)]
-  Only defined on Windows; protect code that uses this by testing that
-  the preprocessor macro \code{MS_WINDOWS} is defined.
-\end{description}
-
-
-\section{Deprecation of String Exceptions}
-
-All exceptions built into Python or provided in the standard library
-are derived from \exception{Exception}.
-\withsubitem{(built-in exception)}{\ttindex{Exception}}
-
-String exceptions are still supported in the interpreter to allow
-existing code to run unmodified, but this will also change in a future 
-release.
-
-
-\chapter{Utilities \label{utilities}}
-
-The functions in this chapter perform various utility tasks, such as
-parsing function arguments and constructing Python values from C
-values.
-
-\section{OS Utilities \label{os}}
-
-\begin{cfuncdesc}{int}{Py_FdIsInteractive}{FILE *fp, char *filename}
-Return true (nonzero) if the standard I/O file \var{fp} with name
-\var{filename} is deemed interactive.  This is the case for files for
-which \samp{isatty(fileno(\var{fp}))} is true.  If the global flag
-\cdata{Py_InteractiveFlag} is true, this function also returns true if
-the \var{filename} pointer is \NULL{} or if the name is equal to one of
-the strings \code{'<stdin>'} or \code{'???'}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{long}{PyOS_GetLastModificationTime}{char *filename}
-Return the time of last modification of the file \var{filename}.
-The result is encoded in the same way as the timestamp returned by
-the standard C library function \cfunction{time()}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyOS_AfterFork}{}
-Function to update some internal state after a process fork; this
-should be called in the new process if the Python interpreter will
-continue to be used.  If a new executable is loaded into the new
-process, this function does not need to be called.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyOS_CheckStack}{}
-Return true when the interpreter runs out of stack space.  This is a
-reliable check, but is only available when \code{USE_STACKCHECK} is
-defined (currently on Windows using the Microsoft Visual C++ compiler
-and on the Macintosh).  \code{USE_CHECKSTACK} will be defined
-automatically; you should never change the definition in your own
-code.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyOS_sighandler_t}{PyOS_getsig}{int i}
-Return the current signal handler for signal \var{i}.
-This is a thin wrapper around either \cfunction{sigaction} or
-\cfunction{signal}.  Do not call those functions directly!
-\ctype{PyOS_sighandler_t} is a typedef alias for \ctype{void (*)(int)}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyOS_sighandler_t}{PyOS_setsig}{int i, PyOS_sighandler_t h}
-Set the signal handler for signal \var{i} to be \var{h};
-return the old signal handler.
-This is a thin wrapper around either \cfunction{sigaction} or
-\cfunction{signal}.  Do not call those functions directly!
-\ctype{PyOS_sighandler_t} is a typedef alias for \ctype{void (*)(int)}.
-\end{cfuncdesc}
-
-
-\section{Process Control \label{processControl}}
-
-\begin{cfuncdesc}{void}{Py_FatalError}{char *message}
-Print a fatal error message and kill the process.  No cleanup is
-performed.  This function should only be invoked when a condition is
-detected that would make it dangerous to continue using the Python
-interpreter; e.g., when the object administration appears to be
-corrupted.  On \UNIX{}, the standard C library function
-\cfunction{abort()}\ttindex{abort()} is called which will attempt to
-produce a \file{core} file.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{Py_Exit}{int status}
-Exit the current process.  This calls
-\cfunction{Py_Finalize()}\ttindex{Py_Finalize()} and
-then calls the standard C library function
-\code{exit(\var{status})}\ttindex{exit()}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{Py_AtExit}{void (*func) ()}
-Register a cleanup function to be called by
-\cfunction{Py_Finalize()}\ttindex{Py_Finalize()}.
-The cleanup function will be called with no arguments and should
-return no value.  At most 32 \index{cleanup functions}cleanup
-functions can be registered.
-When the registration is successful, \cfunction{Py_AtExit()} returns
-\code{0}; on failure, it returns \code{-1}.  The cleanup function
-registered last is called first.  Each cleanup function will be called
-at most once.  Since Python's internal finallization will have
-completed before the cleanup function, no Python APIs should be called
-by \var{func}.
-\end{cfuncdesc}
-
-
-\section{Importing Modules \label{importing}}
-
-\begin{cfuncdesc}{PyObject*}{PyImport_ImportModule}{char *name}
-This is a simplified interface to
-\cfunction{PyImport_ImportModuleEx()} below, leaving the
-\var{globals} and \var{locals} arguments set to \NULL{}.  When the
-\var{name} argument contains a dot (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
-\index{package variable!\code{__all__}}
-\withsubitem{(package variable)}{\ttindex{__all__}}loaded.)  Return a
-new reference to the imported module, or
-\NULL{} with an exception set on failure (the module may still be
-created in this case --- examine \code{sys.modules} to find out).
-\withsubitem{(in module sys)}{\ttindex{modules}}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyImport_ImportModuleEx}{char *name, PyObject *globals, PyObject *locals, PyObject *fromlist}
-Import a module.  This is best described by referring to the built-in
-Python function \function{__import__()}\bifuncindex{__import__}, as
-the standard \function{__import__()} function calls this function
-directly.
-
-The return value is a new reference to the imported module or
-top-level package, or \NULL{} with an exception set on failure
-(the module may still be created in this case).  Like for
-\function{__import__()}, the return value when a submodule of a
-package was requested is normally the top-level package, unless a
-non-empty \var{fromlist} was given.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyImport_Import}{PyObject *name}