diff --git a/Doc/api/abstract.tex b/Doc/api/abstract.tex
new file mode 100644
index 0000000..8d271df
--- /dev/null
+++ b/Doc/api/abstract.tex
@@ -0,0 +1,842 @@
+\chapter{Abstract Objects Layer \label{abstract}}
+
+The functions in this chapter interact with Python objects regardless
+of their type, or with wide classes of object types (e.g. all
+numerical types, or all sequence types).  When used on object types
+for which they do not apply, they will raise a Python exception.
+
+
+\section{Object Protocol \label{object}}
+
+\begin{cfuncdesc}{int}{PyObject_Print}{PyObject *o, FILE *fp, int flags}
+  Print an object \var{o}, on file \var{fp}.  Returns \code{-1} on
+  error.  The flags argument is used to enable certain printing
+  options.  The only option currently supported is
+  \constant{Py_PRINT_RAW}; if given, the \function{str()} of the
+  object is written instead of the \function{repr()}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyObject_HasAttrString}{PyObject *o, char *attr_name}
+  Returns \code{1} if \var{o} has the attribute \var{attr_name}, and
+  \code{0} otherwise.  This is equivalent to the Python expression
+  \samp{hasattr(\var{o}, \var{attr_name})}.  This function always
+  succeeds.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyObject_GetAttrString}{PyObject *o,
+                                                     char *attr_name}
+  Retrieve an attribute named \var{attr_name} from object \var{o}.
+  Returns the attribute value on success, or \NULL{} on failure.
+  This is the equivalent of the Python expression
+  \samp{\var{o}.\var{attr_name}}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{int}{PyObject_HasAttr}{PyObject *o, PyObject *attr_name}
+  Returns \code{1} if \var{o} has the attribute \var{attr_name}, and
+  \code{0} otherwise.  This is equivalent to the Python expression
+  \samp{hasattr(\var{o}, \var{attr_name})}.  This function always
+  succeeds.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyObject_GetAttr}{PyObject *o,
+                                               PyObject *attr_name}
+  Retrieve an attribute named \var{attr_name} from object \var{o}.
+  Returns the attribute value on success, or \NULL{} on failure.  This
+  is the equivalent of the Python expression
+  \samp{\var{o}.\var{attr_name}}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{int}{PyObject_SetAttrString}{PyObject *o,
+                                               char *attr_name, PyObject *v}
+  Set the value of the attribute named \var{attr_name}, for object
+  \var{o}, to the value \var{v}. Returns \code{-1} on failure.  This
+  is the equivalent of the Python statement
+  \samp{\var{o}.\var{attr_name} = \var{v}}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{int}{PyObject_SetAttr}{PyObject *o,
+                                         PyObject *attr_name, PyObject *v}
+  Set the value of the attribute named \var{attr_name}, for object
+  \var{o}, to the value \var{v}. Returns \code{-1} on failure.  This
+  is the equivalent of the Python statement
+  \samp{\var{o}.\var{attr_name} = \var{v}}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{int}{PyObject_DelAttrString}{PyObject *o, char *attr_name}
+  Delete attribute named \var{attr_name}, for object \var{o}. Returns
+  \code{-1} on failure.  This is the equivalent of the Python
+  statement: \samp{del \var{o}.\var{attr_name}}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{int}{PyObject_DelAttr}{PyObject *o, PyObject *attr_name}
+  Delete attribute named \var{attr_name}, for object \var{o}. Returns
+  \code{-1} on failure.  This is the equivalent of the Python
+  statement \samp{del \var{o}.\var{attr_name}}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{int}{PyObject_Cmp}{PyObject *o1, PyObject *o2, int *result}
+  Compare the values of \var{o1} and \var{o2} using a routine provided
+  by \var{o1}, if one exists, otherwise with a routine provided by
+  \var{o2}.  The result of the comparison is returned in
+  \var{result}.  Returns \code{-1} on failure.  This is the equivalent
+  of the Python statement\bifuncindex{cmp} \samp{\var{result} =
+  cmp(\var{o1}, \var{o2})}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{int}{PyObject_Compare}{PyObject *o1, PyObject *o2}
+  Compare the values of \var{o1} and \var{o2} using a routine provided
+  by \var{o1}, if one exists, otherwise with a routine provided by
+  \var{o2}.  Returns the result of the comparison on success.  On
+  error, the value returned is undefined; use
+  \cfunction{PyErr_Occurred()} to detect an error.  This is equivalent
+  to the Python expression\bifuncindex{cmp} \samp{cmp(\var{o1},
+  \var{o2})}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyObject_Repr}{PyObject *o}
+  Compute a string representation of object \var{o}.  Returns the
+  string representation on success, \NULL{} on failure.  This is the
+  equivalent of the Python expression \samp{repr(\var{o})}.  Called by
+  the \function{repr()}\bifuncindex{repr} built-in function and by
+  reverse quotes.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyObject_Str}{PyObject *o}
+  Compute a string representation of object \var{o}.  Returns the
+  string representation on success, \NULL{} on failure.  This is the
+  equivalent of the Python expression \samp{str(\var{o})}.  Called by
+  the \function{str()}\bifuncindex{str} built-in function and by the
+  \keyword{print} statement.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyObject_Unicode}{PyObject *o}
+  Compute a Unicode string representation of object \var{o}.  Returns
+  the Unicode string representation on success, \NULL{} on failure.
+  This is the equivalent of the Python expression
+  \samp{unistr(\var{o})}.  Called by the
+  \function{unistr()}\bifuncindex{unistr} built-in function. 
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyObject_IsInstance}{PyObject *inst, PyObject *cls}
+  Return \code{1} if \var{inst} is an instance of the class \var{cls}
+  or a subclass of \var{cls}.  If \var{cls} is a type object rather
+  than a class object, \cfunction{PyObject_IsInstance()} returns
+  \code{1} if \var{inst} is of type \var{cls}.  If \var{inst} is not a
+  class instance and \var{cls} is neither a type object or class
+  object, \var{inst} must have a \member{__class__} attribute --- the
+  class relationship of the value of that attribute with \var{cls}
+  will be used to determine the result of this function.
+  \versionadded{2.1}
+\end{cfuncdesc}
+
+Subclass determination is done in a fairly straightforward way, but
+includes a wrinkle that implementors of extensions to the class system
+may want to be aware of.  If \class{A} and \class{B} are class
+objects, \class{B} is a subclass of \class{A} if it inherits from
+\class{A} either directly or indirectly.  If either is not a class
+object, a more general mechanism is used to determine the class
+relationship of the two objects.  When testing if \var{B} is a
+subclass of \var{A}, if \var{A} is \var{B},
+\cfunction{PyObject_IsSubclass()} returns true.  If \var{A} and
+\var{B} are different objects, \var{B}'s \member{__bases__} attribute
+is searched in a depth-first fashion for \var{A} --- the presence of
+the \member{__bases__} attribute is considered sufficient for this
+determination.
+
+\begin{cfuncdesc}{int}{PyObject_IsSubclass}{PyObject *derived,
+                                            PyObject *cls}
+  Returns \code{1} if the class \var{derived} is identical to or
+  derived from the class \var{cls}, otherwise returns \code{0}.  In
+  case of an error, returns \code{-1}.  If either \var{derived} or
+  \var{cls} is not an actual class object, this function uses the
+  generic algorithm described above.
+  \versionadded{2.1}
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{int}{PyCallable_Check}{PyObject *o}
+  Determine if the object \var{o} is callable.  Return \code{1} if the
+  object is callable and \code{0} otherwise.  This function always
+  succeeds.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyObject_CallObject}{PyObject *callable_object,
+                                                  PyObject *args}
+  Call a callable Python object \var{callable_object}, with arguments
+  given by the tuple \var{args}.  If no arguments are needed, then
+  \var{args} may be \NULL.  Returns the result of the call on
+  success, or \NULL{} on failure.  This is the equivalent of the
+  Python expression \samp{apply(\var{callable_object}, \var{args})} or
+  \samp{\var{callable_object}(*\var{args})}.
+  \bifuncindex{apply}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyObject_CallFunction}{PyObject *callable_object,
+                                                    char *format, ...}
+  Call a callable Python object \var{callable_object}, with a variable
+  number of C arguments.  The C arguments are described using a
+  \cfunction{Py_BuildValue()} style format string.  The format may be
+  \NULL, indicating that no arguments are provided.  Returns the
+  result of the call on success, or \NULL{} on failure.  This is the
+  equivalent of the Python expression
+  \samp{apply(\var{callable_object}\var{args})} or
+  \samp{\var{callable_object}(*\var{args})}.
+  \bifuncindex{apply}
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyObject_CallMethod}{PyObject *o,
+                                           char *method, char *format, ...}
+  Call the method named \var{m} of object \var{o} with a variable
+  number of C arguments.  The C arguments are described by a
+  \cfunction{Py_BuildValue()} format string.  The format may be \NULL,
+  indicating that no arguments are provided. Returns the result of the
+  call on success, or \NULL{} on failure.  This is the equivalent of
+  the Python expression \samp{\var{o}.\var{method}(\var{args})}.  Note
+  that special method names, such as \method{__add__()},
+  \method{__getitem__()}, and so on are not supported.  The specific
+  abstract-object routines for these must be used.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{int}{PyObject_Hash}{PyObject *o}
+  Compute and return the hash value of an object \var{o}.  On failure,
+  return \code{-1}.  This is the equivalent of the Python expression
+  \samp{hash(\var{o})}.\bifuncindex{hash}
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{int}{PyObject_IsTrue}{PyObject *o}
+  Returns \code{1} if the object \var{o} is considered to be true, and
+  \code{0} otherwise.  This is equivalent to the Python expression
+  \samp{not not \var{o}}.  This function always succeeds.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyObject_Type}{PyObject *o}
+  When \var{o} is non-\NULL, returns a type object corresponding to
+  the object type of object \var{o}. On failure, raises
+  \exception{SystemError} and returns \NULL.  This is equivalent to
+  the Python expression \code{type(\var{o})}.
+  \bifuncindex{type}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyObject_TypeCheck}{PyObject *o, PyTypeObject *type}
+  Return true if the object \var{o} is of type \var{type} or a subtype
+  of \var{type}.  Both parameters must be non-\NULL.
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyObject_Length}{PyObject *o}
+  Return the length of object \var{o}.  If the object \var{o} provides
+  both sequence and mapping protocols, the sequence length is
+  returned.  On error, \code{-1} is returned.  This is the equivalent
+  to the Python expression \samp{len(\var{o})}.\bifuncindex{len}
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyObject_GetItem}{PyObject *o, PyObject *key}
+  Return element of \var{o} corresponding to the object \var{key} or
+  \NULL{} on failure.  This is the equivalent of the Python expression
+  \samp{\var{o}[\var{key}]}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{int}{PyObject_SetItem}{PyObject *o,
+                                         PyObject *key, PyObject *v}
+  Map the object \var{key} to the value \var{v}.  Returns \code{-1} on
+  failure.  This is the equivalent of the Python statement
+  \samp{\var{o}[\var{key}] = \var{v}}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{int}{PyObject_DelItem}{PyObject *o, PyObject *key}
+  Delete the mapping for \var{key} from \var{o}.  Returns \code{-1} on
+  failure. This is the equivalent of the Python statement \samp{del
+  \var{o}[\var{key}]}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyObject_AsFileDescriptor}{PyObject *o}
+  Derives a file-descriptor from a Python object.  If the object is an
+  integer or long integer, its value is returned.  If not, the
+  object's \method{fileno()} method is called if it exists; the method
+  must return an integer or long integer, which is returned as the
+  file descriptor value.  Returns \code{-1} on failure.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyObject_Dir}{PyObject *o}
+  This is equivalent to the Python expression \samp{dir(\var{o})},
+  returning a (possibly empty) list of strings appropriate for the
+  object argument, or \NULL{} if there was an error.  If the argument
+  is \NULL, this is like the Python \samp{dir()}, returning the names
+  of the current locals; in this case, if no execution frame is active
+  then \NULL{} is returned but \cfunction{PyErr_Occurred()} will
+  return false.
+\end{cfuncdesc}
+
+
+\section{Number Protocol \label{number}}
+
+\begin{cfuncdesc}{int}{PyNumber_Check}{PyObject *o}
+  Returns \code{1} if the object \var{o} provides numeric protocols,
+  and false otherwise.  This function always succeeds.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_Add}{PyObject *o1, PyObject *o2}
+  Returns the result of adding \var{o1} and \var{o2}, or \NULL{} on
+  failure.  This is the equivalent of the Python expression
+  \samp{\var{o1} + \var{o2}}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_Subtract}{PyObject *o1, PyObject *o2}
+  Returns the result of subtracting \var{o2} from \var{o1}, or \NULL{}
+  on failure.  This is the equivalent of the Python expression
+  \samp{\var{o1} - \var{o2}}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_Multiply}{PyObject *o1, PyObject *o2}
+  Returns the result of multiplying \var{o1} and \var{o2}, or \NULL{}
+  on failure.  This is the equivalent of the Python expression
+  \samp{\var{o1} * \var{o2}}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_Divide}{PyObject *o1, PyObject *o2}
+  Returns the result of dividing \var{o1} by \var{o2}, or \NULL{} on
+  failure.  This is the equivalent of the Python expression
+  \samp{\var{o1} / \var{o2}}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_FloorDivide}{PyObject *o1, PyObject *o2}
+  Return the floor of \var{o1} divided by \var{o2}, or \NULL{} on
+  failure.  This is equivalent to the ``classic'' division of
+  integers.
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_TrueDivide}{PyObject *o1, PyObject *o2}
+  Return a reasonable approximation for the mathematical value of
+  \var{o1} divided by \var{o2}, or \NULL{} on failure.  The return
+  value is ``approximate'' because binary floating point numbers are
+  approximate; it is not possible to represent all real numbers in
+  base two.  This function can return a floating point value when
+  passed two integers.
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_Remainder}{PyObject *o1, PyObject *o2}
+  Returns the remainder of dividing \var{o1} by \var{o2}, or \NULL{}
+  on failure.  This is the equivalent of the Python expression
+  \samp{\var{o1} \%\ \var{o2}}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_Divmod}{PyObject *o1, PyObject *o2}
+  See the built-in function \function{divmod()}\bifuncindex{divmod}.
+  Returns \NULL{} on failure.  This is the equivalent of the Python
+  expression \samp{divmod(\var{o1}, \var{o2})}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_Power}{PyObject *o1,
+                                             PyObject *o2, PyObject *o3}
+  See the built-in function \function{pow()}\bifuncindex{pow}.
+  Returns \NULL{} on failure.  This is the equivalent of the Python
+  expression \samp{pow(\var{o1}, \var{o2}, \var{o3})}, where \var{o3}
+  is optional.  If \var{o3} is to be ignored, pass \cdata{Py_None} in
+  its place (passing \NULL{} for \var{o3} would cause an illegal
+  memory access).
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_Negative}{PyObject *o}
+  Returns the negation of \var{o} on success, or \NULL{} on failure.
+  This is the equivalent of the Python expression \samp{-\var{o}}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_Positive}{PyObject *o}
+  Returns \var{o} on success, or \NULL{} on failure.  This is the
+  equivalent of the Python expression \samp{+\var{o}}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_Absolute}{PyObject *o}
+  Returns the absolute value of \var{o}, or \NULL{} on failure.  This
+  is the equivalent of the Python expression \samp{abs(\var{o})}.
+  \bifuncindex{abs}
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_Invert}{PyObject *o}
+  Returns the bitwise negation of \var{o} on success, or \NULL{} on
+  failure.  This is the equivalent of the Python expression
+  \samp{\~\var{o}}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_Lshift}{PyObject *o1, PyObject *o2}
+  Returns the result of left shifting \var{o1} by \var{o2} on success,
+  or \NULL{} on failure.  This is the equivalent of the Python
+  expression \samp{\var{o1} <\code{<} \var{o2}}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_Rshift}{PyObject *o1, PyObject *o2}
+  Returns the result of right shifting \var{o1} by \var{o2} on
+  success, or \NULL{} on failure.  This is the equivalent of the
+  Python expression \samp{\var{o1} >\code{>} \var{o2}}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_And}{PyObject *o1, PyObject *o2}
+  Returns the ``bitwise and'' of \var{o2} and \var{o2} on success and
+  \NULL{} on failure. This is the equivalent of the Python expression
+  \samp{\var{o1} \&\ \var{o2}}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_Xor}{PyObject *o1, PyObject *o2}
+  Returns the ``bitwise exclusive or'' of \var{o1} by \var{o2} on
+  success, or \NULL{} on failure.  This is the equivalent of the
+  Python expression \samp{\var{o1} \textasciicircum{} \var{o2}}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_Or}{PyObject *o1, PyObject *o2}
+  Returns the ``bitwise or'' of \var{o1} and \var{o2} on success, or
+  \NULL{} on failure.  This is the equivalent of the Python expression
+  \samp{\var{o1} | \var{o2}}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceAdd}{PyObject *o1, PyObject *o2}
+  Returns the result of adding \var{o1} and \var{o2}, or \NULL{} on
+  failure.  The operation is done \emph{in-place} when \var{o1}
+  supports it.  This is the equivalent of the Python statement
+  \samp{\var{o1} += \var{o2}}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceSubtract}{PyObject *o1,
+                                                       PyObject *o2}
+  Returns the result of subtracting \var{o2} from \var{o1}, or \NULL{}
+  on failure.  The operation is done \emph{in-place} when \var{o1}
+  supports it.  This is the equivalent of the Python statement
+  \samp{\var{o1} -= \var{o2}}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceMultiply}{PyObject *o1,
+                                                       PyObject *o2}
+  Returns the result of multiplying \var{o1} and \var{o2}, or \NULL{}
+  on failure.  The operation is done \emph{in-place} when \var{o1}
+  supports it.  This is the equivalent of the Python statement
+  \samp{\var{o1} *= \var{o2}}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceDivide}{PyObject *o1,
+                                                     PyObject *o2}
+  Returns the result of dividing \var{o1} by \var{o2}, or \NULL{} on
+  failure.  The operation is done \emph{in-place} when \var{o1}
+  supports it. This is the equivalent of the Python statement
+  \samp{\var{o1} /= \var{o2}}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceFloorDivide}{PyObject *o1,
+                                                          PyObject *o2}
+  Returns the mathematical of dividing \var{o1} by \var{o2}, or
+  \NULL{} on failure.  The operation is done \emph{in-place} when
+  \var{o1} supports it.  This is the equivalent of the Python
+  statement \samp{\var{o1} //= \var{o2}}.
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceTrueDivide}{PyObject *o1,
+                                                         PyObject *o2}
+  Return a reasonable approximation for the mathematical value of
+  \var{o1} divided by \var{o2}, or \NULL{} on failure.  The return
+  value is ``approximate'' because binary floating point numbers are
+  approximate; it is not possible to represent all real numbers in
+  base two.  This function can return a floating point value when
+  passed two integers.  The operation is done \emph{in-place} when
+  \var{o1} supports it.
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceRemainder}{PyObject *o1,
+                                                        PyObject *o2}
+  Returns the remainder of dividing \var{o1} by \var{o2}, or \NULL{}
+  on failure.  The operation is done \emph{in-place} when \var{o1}
+  supports it.  This is the equivalent of the Python statement
+  \samp{\var{o1} \%= \var{o2}}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_InPlacePower}{PyObject *o1,
+                                                    PyObject *o2, PyObject *o3}
+  See the built-in function \function{pow()}.\bifuncindex{pow}
+  Returns \NULL{} on failure.  The operation is done \emph{in-place}
+  when \var{o1} supports it.  This is the equivalent of the Python
+  statement \samp{\var{o1} **= \var{o2}} when o3 is \cdata{Py_None},
+  or an in-place variant of \samp{pow(\var{o1}, \var{o2}, \var{o3})}
+  otherwise. If \var{o3} is to be ignored, pass \cdata{Py_None} in its
+  place (passing \NULL{} for \var{o3} would cause an illegal memory
+  access).
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceLshift}{PyObject *o1,
+                                                     PyObject *o2}
+  Returns the result of left shifting \var{o1} by \var{o2} on success,
+  or \NULL{} on failure.  The operation is done \emph{in-place} when
+  \var{o1} supports it.  This is the equivalent of the Python
+  statement \samp{\var{o1} <\code{<=} \var{o2}}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceRshift}{PyObject *o1,
+                                                     PyObject *o2}
+  Returns the result of right shifting \var{o1} by \var{o2} on
+  success, or \NULL{} on failure.  The operation is done
+  \emph{in-place} when \var{o1} supports it.  This is the equivalent
+  of the Python statement \samp{\var{o1} >\code{>=} \var{o2}}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceAnd}{PyObject *o1, PyObject *o2}
+  Returns the ``bitwise and'' of \var{o1} and \var{o2} on success and
+  \NULL{} on failure. The operation is done \emph{in-place} when
+  \var{o1} supports it.  This is the equivalent of the Python
+  statement \samp{\var{o1} \&= \var{o2}}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceXor}{PyObject *o1, PyObject *o2}
+  Returns the ``bitwise exclusive or'' of \var{o1} by \var{o2} on
+  success, or \NULL{} on failure.  The operation is done
+  \emph{in-place} when \var{o1} supports it.  This is the equivalent
+  of the Python statement \samp{\var{o1} \textasciicircum= \var{o2}}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceOr}{PyObject *o1, PyObject *o2}
+  Returns the ``bitwise or'' of \var{o1} and \var{o2} on success, or
+  \NULL{} on failure.  The operation is done \emph{in-place} when
+  \var{o1} supports it.  This is the equivalent of the Python
+  statement \samp{\var{o1} |= \var{o2}}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyNumber_Coerce}{PyObject **p1, PyObject **p2}
+  This function takes the addresses of two variables of type
+  \ctype{PyObject*}.  If the objects pointed to by \code{*\var{p1}}
+  and \code{*\var{p2}} have the same type, increment their reference
+  count and return \code{0} (success). If the objects can be converted
+  to a common numeric type, replace \code{*p1} and \code{*p2} by their
+  converted value (with 'new' reference counts), and return \code{0}.
+  If no conversion is possible, or if some other error occurs, return
+  \code{-1} (failure) and don't increment the reference counts.  The
+  call \code{PyNumber_Coerce(\&o1, \&o2)} is equivalent to the Python
+  statement \samp{\var{o1}, \var{o2} = coerce(\var{o1}, \var{o2})}.
+  \bifuncindex{coerce}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_Int}{PyObject *o}
+  Returns the \var{o} converted to an integer object on success, or
+  \NULL{} on failure.  This is the equivalent of the Python expression
+  \samp{int(\var{o})}.\bifuncindex{int}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_Long}{PyObject *o}
+  Returns the \var{o} converted to a long integer object on success,
+  or \NULL{} on failure.  This is the equivalent of the Python
+  expression \samp{long(\var{o})}.\bifuncindex{long}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_Float}{PyObject *o}
+  Returns the \var{o} converted to a float object on success, or
+  \NULL{} on failure.  This is the equivalent of the Python expression
+  \samp{float(\var{o})}.\bifuncindex{float}
+\end{cfuncdesc}
+
+
+\section{Sequence Protocol \label{sequence}}
+
+\begin{cfuncdesc}{int}{PySequence_Check}{PyObject *o}
+  Return \code{1} if the object provides sequence protocol, and
+  \code{0} otherwise.  This function always succeeds.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PySequence_Size}{PyObject *o}
+  Returns the number of objects in sequence \var{o} on success, and
+  \code{-1} on failure.  For objects that do not provide sequence
+  protocol, this is equivalent to the Python expression
+  \samp{len(\var{o})}.\bifuncindex{len}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PySequence_Length}{PyObject *o}
+  Alternate name for \cfunction{PySequence_Size()}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PySequence_Concat}{PyObject *o1, PyObject *o2}
+  Return the concatenation of \var{o1} and \var{o2} on success, and
+  \NULL{} on failure.   This is the equivalent of the Python
+  expression \samp{\var{o1} + \var{o2}}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PySequence_Repeat}{PyObject *o, int count}
+  Return the result of repeating sequence object \var{o} \var{count}
+  times, or \NULL{} on failure.  This is the equivalent of the Python
+  expression \samp{\var{o} * \var{count}}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PySequence_InPlaceConcat}{PyObject *o1,
+                                                       PyObject *o2}
+  Return the concatenation of \var{o1} and \var{o2} on success, and
+  \NULL{} on failure.  The operation is done \emph{in-place} when
+  \var{o1} supports it.  This is the equivalent of the Python
+  expression \samp{\var{o1} += \var{o2}}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PySequence_InPlaceRepeat}{PyObject *o, int count}
+  Return the result of repeating sequence object \var{o} \var{count}
+  times, or \NULL{} on failure.  The operation is done \emph{in-place}
+  when \var{o} supports it.  This is the equivalent of the Python
+  expression \samp{\var{o} *= \var{count}}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PySequence_GetItem}{PyObject *o, int i}
+  Return the \var{i}th element of \var{o}, or \NULL{} on failure.
+  This is the equivalent of the Python expression
+  \samp{\var{o}[\var{i}]}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PySequence_GetSlice}{PyObject *o, int i1, int i2}
+  Return the slice of sequence object \var{o} between \var{i1} and
+  \var{i2}, or \NULL{} on failure. This is the equivalent of the
+  Python expression \samp{\var{o}[\var{i1}:\var{i2}]}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{int}{PySequence_SetItem}{PyObject *o, int i, PyObject *v}
+  Assign object \var{v} to the \var{i}th element of \var{o}.  Returns
+  \code{-1} on failure.  This is the equivalent of the Python
+  statement \samp{\var{o}[\var{i}] = \var{v}}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PySequence_DelItem}{PyObject *o, int i}
+  Delete the \var{i}th element of object \var{o}.  Returns \code{-1}
+  on failure.  This is the equivalent of the Python statement
+  \samp{del \var{o}[\var{i}]}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PySequence_SetSlice}{PyObject *o, int i1,
+                                            int i2, PyObject *v}
+  Assign the sequence object \var{v} to the slice in sequence object
+  \var{o} from \var{i1} to \var{i2}.  This is the equivalent of the
+  Python statement \samp{\var{o}[\var{i1}:\var{i2}] = \var{v}}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PySequence_DelSlice}{PyObject *o, int i1, int i2}
+  Delete the slice in sequence object \var{o} from \var{i1} to
+  \var{i2}.  Returns \code{-1} on failure.  This is the equivalent of
+  the Python statement \samp{del \var{o}[\var{i1}:\var{i2}]}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PySequence_Tuple}{PyObject *o}
+  Returns the \var{o} as a tuple on success, and \NULL{} on failure.
+  This is equivalent to the Python expression \samp{tuple(\var{o})}.
+  \bifuncindex{tuple}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PySequence_Count}{PyObject *o, PyObject *value}
+  Return the number of occurrences of \var{value} in \var{o}, that is,
+  return the number of keys for which \code{\var{o}[\var{key}] ==
+  \var{value}}.  On failure, return \code{-1}.  This is equivalent to
+  the Python expression \samp{\var{o}.count(\var{value})}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PySequence_Contains}{PyObject *o, PyObject *value}
+  Determine if \var{o} contains \var{value}.  If an item in \var{o} is
+  equal to \var{value}, return \code{1}, otherwise return \code{0}.
+  On error, return \code{-1}.  This is equivalent to the Python
+  expression \samp{\var{value} in \var{o}}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PySequence_Index}{PyObject *o, PyObject *value}
+  Return the first index \var{i} for which \code{\var{o}[\var{i}] ==
+  \var{value}}.  On error, return \code{-1}.    This is equivalent to
+  the Python expression \samp{\var{o}.index(\var{value})}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PySequence_List}{PyObject *o}
+  Return a list object with the same contents as the arbitrary
+  sequence \var{o}.  The returned list is guaranteed to be new.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PySequence_Tuple}{PyObject *o}
+  Return a tuple object with the same contents as the arbitrary
+  sequence \var{o}.  If \var{o} is a tuple, a new reference will be
+  returned, otherwise a tuple will be constructed with the appropriate
+  contents.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PySequence_Fast}{PyObject *o, const char *m}
+  Returns the sequence \var{o} as a tuple, unless it is already a
+  tuple or list, in which case \var{o} is returned.  Use
+  \cfunction{PySequence_Fast_GET_ITEM()} to access the members of the
+  result.  Returns \NULL{} on failure.  If the object is not a
+  sequence, raises \exception{TypeError} with \var{m} as the message
+  text.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PySequence_Fast_GET_ITEM}{PyObject *o, int i}
+  Return the \var{i}th element of \var{o}, assuming that \var{o} was
+  returned by \cfunction{PySequence_Fast()}, and that \var{i} is
+  within bounds.  The caller is expected to get the length of the
+  sequence by calling \cfunction{PySequence_Size()} on \var{o}, since
+  lists and tuples are guaranteed to always return their true length.
+\end{cfuncdesc}
+
+
+\section{Mapping Protocol \label{mapping}}
+
+\begin{cfuncdesc}{int}{PyMapping_Check}{PyObject *o}
+  Return \code{1} if the object provides mapping protocol, and
+  \code{0} otherwise.  This function always succeeds.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{int}{PyMapping_Length}{PyObject *o}
+  Returns the number of keys in object \var{o} on success, and
+  \code{-1} on failure.  For objects that do not provide mapping
+  protocol, this is equivalent to the Python expression
+  \samp{len(\var{o})}.\bifuncindex{len}
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{int}{PyMapping_DelItemString}{PyObject *o, char *key}
+  Remove the mapping for object \var{key} from the object \var{o}.
+  Return \code{-1} on failure.  This is equivalent to the Python
+  statement \samp{del \var{o}[\var{key}]}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{int}{PyMapping_DelItem}{PyObject *o, PyObject *key}
+  Remove the mapping for object \var{key} from the object \var{o}.
+  Return \code{-1} on failure.  This is equivalent to the Python
+  statement \samp{del \var{o}[\var{key}]}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{int}{PyMapping_HasKeyString}{PyObject *o, char *key}
+  On success, return \code{1} if the mapping object has the key
+  \var{key} and \code{0} otherwise.  This is equivalent to the Python
+  expression \samp{\var{o}.has_key(\var{key})}.  This function always
+  succeeds.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{int}{PyMapping_HasKey}{PyObject *o, PyObject *key}
+  Return \code{1} if the mapping object has the key \var{key} and
+  \code{0} otherwise.  This is equivalent to the Python expression
+  \samp{\var{o}.has_key(\var{key})}.  This function always succeeds.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyMapping_Keys}{PyObject *o}
+  On success, return a list of the keys in object \var{o}.  On
+  failure, return \NULL. This is equivalent to the Python expression
+  \samp{\var{o}.keys()}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyMapping_Values}{PyObject *o}
+  On success, return a list of the values in object \var{o}.  On
+  failure, return \NULL. This is equivalent to the Python expression
+  \samp{\var{o}.values()}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyMapping_Items}{PyObject *o}
+  On success, return a list of the items in object \var{o}, where each
+  item is a tuple containing a key-value pair.  On failure, return
+  \NULL. This is equivalent to the Python expression
+  \samp{\var{o}.items()}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyMapping_GetItemString}{PyObject *o, char *key}
+  Return element of \var{o} corresponding to the object \var{key} or
+  \NULL{} on failure. This is the equivalent of the Python expression
+  \samp{\var{o}[\var{key}]}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyMapping_SetItemString}{PyObject *o, char *key,
+                                                PyObject *v}
+  Map the object \var{key} to the value \var{v} in object \var{o}.
+  Returns \code{-1} on failure.  This is the equivalent of the Python
+  statement \samp{\var{o}[\var{key}] = \var{v}}.
+\end{cfuncdesc}
+
+
+\section{Iterator Protocol \label{iterator}}
+
+\versionadded{2.2}
+
+There are only a couple of functions specifically for working with
+iterators.
+
+\begin{cfuncdesc}{int}{PyIter_Check}{PyObject *o}
+  Return true if the object \var{o} supports the iterator protocol.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyIter_Next}{PyObject *o}
+  Return the next value from the iteration \var{o}.  If the object is
+  an iterator, this retrieves the next value from the iteration, and
+  returns \NULL{} with no exception set if there are no remaining
+  items.  If the object is not an iterator, \exception{TypeError} is
+  raised, or if there is an error in retrieving the item, returns
+  \NULL{} and passes along the exception.
+\end{cfuncdesc}
+
+To write a loop which iterates over an iterator, the C code should
+look something like this:
+
+\begin{verbatim}
+PyObject *iterator = ...;
+PyObject *item;
+
+while (item = PyIter_Next(iter)) {
+    /* do something with item */
+}
+if (PyErr_Occurred()) {
+    /* propogate error */
+}
+else {
+    /* continue doing useful work */
+}
+\end{verbatim}
diff --git a/Doc/api/api.tex b/Doc/api/api.tex
index 2e2c63e..6fa8c41 100644
--- a/Doc/api/api.tex
+++ b/Doc/api/api.tex
@@ -26,6148 +26,26 @@
 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.
+\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).
-Since Python may define some pre-processor definitions which affect
-the standard headers on some systems, you must include \file{Python.h}
-before any standard headers are included.
-
-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__}, \module{sys}\refbimodindex{sys},
-and \module{exceptions}.\refbimodindex{exceptions}  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_ReferenceError}{\exception{ReferenceError}}{(2)}
-  \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}}{(3)}
-  \lineiii{PyExc_ZeroDivisionError}{\exception{ZeroDivisionError}}{}
-\end{tableiii}
-
-\noindent
-Notes:
-\begin{description}
-\item[(1)]
-  This is a base class for other standard exceptions.
-
-\item[(2)]
-  This is the same as \exception{weakref.ReferenceError}.
-
-\item[(3)]
-  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, ranging
-from helping C code be more portable across platforms, using Python
-modules from C, and parsing function arguments and constructing Python
-values from C values.
-
-
-\section{Operating System 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}
-This is a higher-level interface that calls the current ``import hook
-function''.  It invokes the \function{__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 \module{rexec}\refstmodindex{rexec} or
-\module{ihooks}\refstmodindex{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 \function{reload()}\bifuncindex{reload}, as the standard
-\function{reload()} function calls this function directly.  Return a
-new reference to the reloaded module, or \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.
-Warning: this function does not load or import the module; if the
-module wasn't already loaded, you will get an empty module object.
-Use \cfunction{PyImport_ImportModule()} or one of its variants to
-import a module.
-Return \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 \function{compile()}\bifuncindex{compile}, load the
-module.  Return a new reference to the module object, or \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.
-\file{.pyc} and \file{.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{cfuncdesc}{PyObject*}{_PyImport_FindExtension}{char *, char *}
-For internal use only.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{_PyImport_FixupExtension}{char *, char *}
-For internal use only.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyImport_ImportFrozenModule}{char *name}
-Load a frozen module named \var{name}.  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 \cfunction{PyImport_ImportModule()}.
-(Note the misnomer --- this function would reload the module if it was
-already imported.)
-\end{cfuncdesc}
-
-\begin{ctypedesc}[_frozen]{struct _frozen}
-This is the structure type definition for frozen module descriptors,
-as generated by the \program{freeze}\index{freeze utility} utility
-(see \file{Tools/freeze/} in the Python source distribution).  Its
-definition, found in \file{Include/import.h}, is:
-
-\begin{verbatim}
-struct _frozen {
-    char *name;
-    unsigned char *code;
-    int size;
-};
-\end{verbatim}
-\end{ctypedesc}
-
-\begin{cvardesc}{struct _frozen*}{PyImport_FrozenModules}
-This pointer is initialized to point to an array of \ctype{struct
-_frozen} records, terminated by one whose members are all
-\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}
-
-\begin{cfuncdesc}{int}{PyImport_AppendInittab}{char *name,
-                                               void (*initfunc)(void)}
-Add a single module to the existing table of built-in modules.  This
-is a convenience wrapper around \cfunction{PyImport_ExtendInittab()},
-returning \code{-1} if the table could not be extended.  The new
-module can be imported by the name \var{name}, and uses the function
-\var{initfunc} as the initialization function called on the first
-attempted import.  This should be called before
-\cfunction{Py_Initialize()}.
-\end{cfuncdesc}
-
-\begin{ctypedesc}[_inittab]{struct _inittab}
-Structure describing a single entry in the list of built-in modules.
-Each of these structures gives the name and initialization function
-for a module built into the interpreter.  Programs which embed Python
-may use an array of these structures in conjunction with
-\cfunction{PyImport_ExtendInittab()} to provide additional built-in
-modules.  The structure is defined in \file{Include/import.h} as:
-
-\begin{verbatim}
-struct _inittab {
-    char *name;
-    void (*initfunc)(void);
-};
-\end{verbatim}
-\end{ctypedesc}
-
-\begin{cfuncdesc}{int}{PyImport_ExtendInittab}{struct _inittab *newtab}
-Add a collection of modules to the table of built-in modules.  The
-\var{newtab} array must end with a sentinel entry which contains
-\NULL{} for the \member{name} field; failure to provide the sentinel
-value can result in a memory fault.  Returns \code{0} on success or
-\code{-1} if insufficient memory could be allocated to extend the
-internal table.  In the event of failure, no modules are added to the
-internal table.  This should be called before
-\cfunction{Py_Initialize()}.
-\end{cfuncdesc}
-
-
-\section{Parsing arguments and building values
-         \label{arg-parsing}}
-
-These functions are useful when creating your own extensions functions
-and methods.  Additional information and examples are available in
-\citetitle[../ext/ext.html]{Extending and Embedding the Python
-Interpreter}.
-
-\begin{cfuncdesc}{int}{PyArg_ParseTuple}{PyObject *args, char *format,
-                                         \moreargs}
-  Parse the parameters of a function that takes only positional
-  parameters into local variables.  Returns true on success; on
-  failure, it returns false and raises the appropriate exception.  See
-  \citetitle[../ext/parseTuple.html]{Extending and Embedding the
-  Python Interpreter} for more information.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyArg_ParseTupleAndKeywords}{PyObject *args,
-                       PyObject *kw, char *format, char *keywords[],
-                       \moreargs}
-  Parse the parameters of a function that takes both positional and
-  keyword parameters into local variables.  Returns true on success;
-  on failure, it returns false and raises the appropriate exception.
-  See \citetitle[../ext/parseTupleAndKeywords.html]{Extending and
-  Embedding the Python Interpreter} for more information.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyArg_Parse}{PyObject *args, char *format,
-                                    \moreargs}
-  Function used to deconstruct the argument lists of ``old-style''
-  functions --- these are functions which use the
-  \constant{METH_OLDARGS} parameter parsing method.  This is not
-  recommended for use in parameter parsing in new code, and most code
-  in the standard interpreter has been modified to no longer use this
-  for that purpose.  It does remain a convenient way to decompose
-  other tuples, however, and may continue to be used for that
-  purpose.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{Py_BuildValue}{char *format,
-                                            \moreargs}
-  Create a new value based on a format string similar to those
-  accepted by the \cfunction{PyArg_Parse*()} family of functions and a
-  sequence of values.  Returns the value or \NULL{} in the case of an
-  error; an exception will be raised if \NULL{} is returned.  For more
-  information on the format string and additional parameters, see
-  \citetitle[../ext/buildValue.html]{Extending and Embedding the
-  Python Interpreter}.
-\end{cfuncdesc}
-
-
-
-\chapter{Abstract Objects Layer \label{abstract}}
-
-The functions in this chapter interact with Python objects regardless
-of their type, or with wide classes of object types (e.g. all
-numerical types, or all sequence types).  When used on object types
-for which they do not apply, they will raise a Python exception.
-
-\section{Object Protocol \label{object}}
-
-\begin{cfuncdesc}{int}{PyObject_Print}{PyObject *o, FILE *fp, int flags}
-Print an object \var{o}, on file \var{fp}.  Returns \code{-1} on error.
-The flags argument is used to enable certain printing options.  The
-only option currently supported is \constant{Py_PRINT_RAW}; if given,
-the \function{str()} of the object is written instead of the
-\function{repr()}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyObject_HasAttrString}{PyObject *o, char *attr_name}
-Returns \code{1} if \var{o} has the attribute \var{attr_name}, and
-\code{0} otherwise.  This is equivalent to the Python expression
-\samp{hasattr(\var{o}, \var{attr_name})}.
-This function always succeeds.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyObject_GetAttrString}{PyObject *o,
-                                                     char *attr_name}
-Retrieve an attribute named \var{attr_name} from object \var{o}.
-Returns the attribute value on success, or \NULL{} on failure.
-This is the equivalent of the Python expression
-\samp{\var{o}.\var{attr_name}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyObject_HasAttr}{PyObject *o, PyObject *attr_name}
-Returns \code{1} if \var{o} has the attribute \var{attr_name}, and
-\code{0} otherwise.  This is equivalent to the Python expression
-\samp{hasattr(\var{o}, \var{attr_name})}. 
-This function always succeeds.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyObject_GetAttr}{PyObject *o,
-                                               PyObject *attr_name}
-Retrieve an attribute named \var{attr_name} from object \var{o}.
-Returns the attribute value on success, or \NULL{} on failure.
-This is the equivalent of the Python expression
-\samp{\var{o}.\var{attr_name}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyObject_SetAttrString}{PyObject *o,
-                                               char *attr_name, PyObject *v}
-Set the value of the attribute named \var{attr_name}, for object
-\var{o}, to the value \var{v}. Returns \code{-1} on failure.  This is
-the equivalent of the Python statement \samp{\var{o}.\var{attr_name} =
-\var{v}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyObject_SetAttr}{PyObject *o,
-                                         PyObject *attr_name, PyObject *v}
-Set the value of the attribute named \var{attr_name}, for
-object \var{o},
-to the value \var{v}. Returns \code{-1} on failure.  This is
-the equivalent of the Python statement \samp{\var{o}.\var{attr_name} =
-\var{v}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyObject_DelAttrString}{PyObject *o, char *attr_name}
-Delete attribute named \var{attr_name}, for object \var{o}. Returns
-\code{-1} on failure.  This is the equivalent of the Python
-statement: \samp{del \var{o}.\var{attr_name}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyObject_DelAttr}{PyObject *o, PyObject *attr_name}
-Delete attribute named \var{attr_name}, for object \var{o}. Returns
-\code{-1} on failure.  This is the equivalent of the Python
-statement \samp{del \var{o}.\var{attr_name}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyObject_Cmp}{PyObject *o1, PyObject *o2, int *result}
-Compare the values of \var{o1} and \var{o2} using a routine provided
-by \var{o1}, if one exists, otherwise with a routine provided by
-\var{o2}.  The result of the comparison is returned in \var{result}.
-Returns \code{-1} on failure.  This is the equivalent of the Python
-statement\bifuncindex{cmp} \samp{\var{result} = cmp(\var{o1}, \var{o2})}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyObject_Compare}{PyObject *o1, PyObject *o2}
-Compare the values of \var{o1} and \var{o2} using a routine provided
-by \var{o1}, if one exists, otherwise with a routine provided by
-\var{o2}.  Returns the result of the comparison on success.  On error,
-the value returned is undefined; use \cfunction{PyErr_Occurred()} to
-detect an error.  This is equivalent to the Python
-expression\bifuncindex{cmp} \samp{cmp(\var{o1}, \var{o2})}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyObject_Repr}{PyObject *o}
-Compute a string representation of object \var{o}.  Returns the
-string representation on success, \NULL{} on failure.  This is
-the equivalent of the Python expression \samp{repr(\var{o})}.
-Called by the \function{repr()}\bifuncindex{repr} built-in function
-and by reverse quotes.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyObject_Str}{PyObject *o}
-Compute a string representation of object \var{o}.  Returns the
-string representation on success, \NULL{} on failure.  This is
-the equivalent of the Python expression \samp{str(\var{o})}.
-Called by the \function{str()}\bifuncindex{str} built-in function and
-by the \keyword{print} statement.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyObject_Unicode}{PyObject *o}
-Compute a Unicode string representation of object \var{o}.  Returns the
-Unicode string representation on success, \NULL{} on failure.  This is
-the equivalent of the Python expression \samp{unistr(\var{o})}.
-Called by the \function{unistr()}\bifuncindex{unistr} built-in function.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyObject_IsInstance}{PyObject *inst, PyObject *cls}
-Return \code{1} if \var{inst} is an instance of the class \var{cls} or
-a subclass of \var{cls}.  If \var{cls} is a type object rather than a
-class object, \cfunction{PyObject_IsInstance()} returns \code{1} if
-\var{inst} is of type \var{cls}.  If \var{inst} is not a class
-instance and \var{cls} is neither a type object or class object,
-\var{inst} must have a \member{__class__} attribute --- the class
-relationship of the value of that attribute with \var{cls} will be
-used to determine the result of this function.
-\versionadded{2.1}
-\end{cfuncdesc}
-
-Subclass determination is done in a fairly straightforward way, but
-includes a wrinkle that implementors of extensions to the class system
-may want to be aware of.  If \class{A} and \class{B} are class
-objects, \class{B} is a subclass of \class{A} if it inherits from
-\class{A} either directly or indirectly.  If either is not a class
-object, a more general mechanism is used to determine the class
-relationship of the two objects.  When testing if \var{B} is a
-subclass of \var{A}, if \var{A} is \var{B},
-\cfunction{PyObject_IsSubclass()} returns true.  If \var{A} and
-\var{B} are different objects, \var{B}'s \member{__bases__} attribute
-is searched in a depth-first fashion for \var{A} --- the presence of
-the \member{__bases__} attribute is considered sufficient for this
-determination.
-
-\begin{cfuncdesc}{int}{PyObject_IsSubclass}{PyObject *derived,
-                                            PyObject *cls}
-Returns \code{1} if the class \var{derived} is identical to or derived
-from the class \var{cls}, otherwise returns \code{0}.  In case of an
-error, returns \code{-1}.  If either \var{derived} or \var{cls} is not
-an actual class object, this function uses the generic algorithm
-described above.
-\versionadded{2.1}
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyCallable_Check}{PyObject *o}
-Determine if the object \var{o} is callable.  Return \code{1} if the
-object is callable and \code{0} otherwise.
-This function always succeeds.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyObject_CallObject}{PyObject *callable_object,
-                                                  PyObject *args}
-Call a callable Python object \var{callable_object}, with
-arguments given by the tuple \var{args}.  If no arguments are
-needed, then \var{args} may be \NULL{}.  Returns the result of the
-call on success, or \NULL{} on failure.  This is the equivalent
-of the Python expression \samp{apply(\var{callable_object},
-\var{args})} or \samp{\var{callable_object}(*\var{args})}.
-\bifuncindex{apply}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyObject_CallFunction}{PyObject *callable_object,
-                                                    char *format, ...}
-Call a callable Python object \var{callable_object}, with a
-variable number of C arguments. The C arguments are described
-using a \cfunction{Py_BuildValue()} style format string. The format may
-be \NULL{}, indicating that no arguments are provided.  Returns the
-result of the call on success, or \NULL{} on failure.  This is
-the equivalent of the Python expression
-\samp{apply(\var{callable_object}\var{args})} or
-\samp{\var{callable_object}(*\var{args})}.
-\bifuncindex{apply}
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyObject_CallMethod}{PyObject *o,
-                                           char *method, char *format, ...}
-Call the method named \var{m} of object \var{o} with a variable number
-of C arguments.  The C arguments are described by a
-\cfunction{Py_BuildValue()} format string.  The format may be \NULL{},
-indicating that no arguments are provided. Returns the result of the
-call on success, or \NULL{} on failure.  This is the equivalent of the
-Python expression \samp{\var{o}.\var{method}(\var{args})}.
-Note that special method names, such as \method{__add__()},
-\method{__getitem__()}, and so on are not supported.  The specific
-abstract-object routines for these must be used.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyObject_Hash}{PyObject *o}
-Compute and return the hash value of an object \var{o}.  On
-failure, return \code{-1}.  This is the equivalent of the Python
-expression \samp{hash(\var{o})}.\bifuncindex{hash}
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyObject_IsTrue}{PyObject *o}
-Returns \code{1} if the object \var{o} is considered to be true, and
-\code{0} otherwise. This is equivalent to the Python expression
-\samp{not not \var{o}}.
-This function always succeeds.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyObject_Type}{PyObject *o}
-When \var{o} is non-\NULL, returns a type object corresponding to the
-object type of object \var{o}. On failure, raises
-\exception{SystemError} and returns \NULL.  This is equivalent to the
-Python expression \code{type(\var{o})}.
-\bifuncindex{type}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyObject_TypeCheck}{PyObject *o, PyTypeObject *type}
-Return true if the object \var{o} is of type \var{type} or a subtype
-of \var{type}.  Both parameters must be non-\NULL.
-\versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyObject_Length}{PyObject *o}
-Return the length of object \var{o}.  If the object \var{o} provides
-both sequence and mapping protocols, the sequence length is
-returned.  On error, \code{-1} is returned.  This is the equivalent
-to the Python expression \samp{len(\var{o})}.\bifuncindex{len}
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyObject_GetItem}{PyObject *o, PyObject *key}
-Return element of \var{o} corresponding to the object \var{key} or
-\NULL{} on failure. This is the equivalent of the Python expression
-\samp{\var{o}[\var{key}]}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyObject_SetItem}{PyObject *o,
-                                         PyObject *key, PyObject *v}
-Map the object \var{key} to the value \var{v}.
-Returns \code{-1} on failure.  This is the equivalent
-of the Python statement \samp{\var{o}[\var{key}] = \var{v}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyObject_DelItem}{PyObject *o, PyObject *key}
-Delete the mapping for \var{key} from \var{o}.  Returns \code{-1} on
-failure. This is the equivalent of the Python statement \samp{del
-\var{o}[\var{key}]}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyObject_AsFileDescriptor}{PyObject *o}
-Derives a file-descriptor from a Python object.  If the object
-is an integer or long integer, its value is returned.  If not, the
-object's \method{fileno()} method is called if it exists; the method
-must return an integer or long integer, which is returned as the file
-descriptor value.  Returns \code{-1} on failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyObject_Dir}{PyObject *o}
-This is equivalent to the Python expression \samp{dir(\var{o})},
-returning a (possibly empty) list of strings appropriate for the
-object argument, or \NULL{} in case of error.
-If the argument is \NULL{}, this is like the Python \samp{dir()},
-returning the names of the current locals; in this case, if no
-execution frame is active then \NULL{} is returned but
-\cfunction{PyErr_Occurred()} will return false.
-\end{cfuncdesc}
-
-
-\section{Number Protocol \label{number}}
-
-\begin{cfuncdesc}{int}{PyNumber_Check}{PyObject *o}
-Returns \code{1} if the object \var{o} provides numeric protocols, and
-false otherwise. 
-This function always succeeds.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Add}{PyObject *o1, PyObject *o2}
-Returns the result of adding \var{o1} and \var{o2}, or \NULL{} on
-failure.  This is the equivalent of the Python expression
-\samp{\var{o1} + \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Subtract}{PyObject *o1, PyObject *o2}
-Returns the result of subtracting \var{o2} from \var{o1}, or
-\NULL{} on failure.  This is the equivalent of the Python expression
-\samp{\var{o1} - \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Multiply}{PyObject *o1, PyObject *o2}
-Returns the result of multiplying \var{o1} and \var{o2}, or \NULL{} on
-failure.  This is the equivalent of the Python expression
-\samp{\var{o1} * \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Divide}{PyObject *o1, PyObject *o2}
-Returns the result of dividing \var{o1} by \var{o2}, or \NULL{} on
-failure. 
-This is the equivalent of the Python expression \samp{\var{o1} /
-\var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_FloorDivide}{PyObject *o1, PyObject *o2}
-Return the floor of \var{o1} divided by \var{o2}, or \NULL{} on
-failure.  This is equivalent to the ``classic'' division of integers.
-\versionadded{2.2}
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_TrueDivide}{PyObject *o1, PyObject *o2}
-Return a reasonable approximation for the mathematical value of
-\var{o1} divided by \var{o2}, or \NULL{} on failure.  The return value
-is ``approximate'' because binary floating point numbers are
-approximate; it is not possible to represent all real numbers in base
-two.  This function can return a floating point value when passed two
-integers.
-\versionadded{2.2}
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Remainder}{PyObject *o1, PyObject *o2}
-Returns the remainder of dividing \var{o1} by \var{o2}, or \NULL{} on
-failure.  This is the equivalent of the Python expression
-\samp{\var{o1} \%\ \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Divmod}{PyObject *o1, PyObject *o2}
-See the built-in function \function{divmod()}\bifuncindex{divmod}.
-Returns \NULL{} on failure.  This is the equivalent of the Python
-expression \samp{divmod(\var{o1}, \var{o2})}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Power}{PyObject *o1,
-                                             PyObject *o2, PyObject *o3}
-See the built-in function \function{pow()}\bifuncindex{pow}.  Returns
-\NULL{} on failure. This is the equivalent of the Python expression
-\samp{pow(\var{o1}, \var{o2}, \var{o3})}, where \var{o3} is optional.
-If \var{o3} is to be ignored, pass \cdata{Py_None} in its place
-(passing \NULL{} for \var{o3} would cause an illegal memory access).
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Negative}{PyObject *o}
-Returns the negation of \var{o} on success, or \NULL{} on failure.
-This is the equivalent of the Python expression \samp{-\var{o}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Positive}{PyObject *o}
-Returns \var{o} on success, or \NULL{} on failure.
-This is the equivalent of the Python expression \samp{+\var{o}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Absolute}{PyObject *o}
-Returns the absolute value of \var{o}, or \NULL{} on failure.  This is
-the equivalent of the Python expression \samp{abs(\var{o})}.
-\bifuncindex{abs}
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Invert}{PyObject *o}
-Returns the bitwise negation of \var{o} on success, or \NULL{} on
-failure.  This is the equivalent of the Python expression
-\samp{\~\var{o}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Lshift}{PyObject *o1, PyObject *o2}
-Returns the result of left shifting \var{o1} by \var{o2} on success,
-or \NULL{} on failure.  This is the equivalent of the Python
-expression \samp{\var{o1} <\code{<} \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Rshift}{PyObject *o1, PyObject *o2}
-Returns the result of right shifting \var{o1} by \var{o2} on success,
-or \NULL{} on failure.  This is the equivalent of the Python
-expression \samp{\var{o1} >\code{>} \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_And}{PyObject *o1, PyObject *o2}
-Returns the ``bitwise and'' of \var{o2} and \var{o2} on success and
-\NULL{} on failure. This is the equivalent of the Python expression
-\samp{\var{o1} \&\ \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Xor}{PyObject *o1, PyObject *o2}
-Returns the ``bitwise exclusive or'' of \var{o1} by \var{o2} on success,
-or \NULL{} on failure.  This is the equivalent of the Python
-expression \samp{\var{o1} \textasciicircum{} \var{o2}}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Or}{PyObject *o1, PyObject *o2}
-Returns the ``bitwise or'' of \var{o1} and \var{o2} on success, or
-\NULL{} on failure.  This is the equivalent of the Python expression
-\samp{\var{o1} | \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceAdd}{PyObject *o1, PyObject *o2}
-Returns the result of adding \var{o1} and \var{o2}, or \NULL{} on
-failure.  The operation is done \emph{in-place} when \var{o1} supports
-it.  This is the equivalent of the Python statement \samp{\var{o1} +=
-\var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceSubtract}{PyObject *o1,
-                                                       PyObject *o2}
-Returns the result of subtracting \var{o2} from \var{o1}, or
-\NULL{} on failure.  The operation is done \emph{in-place} when
-\var{o1} supports it.  This is the equivalent of the Python statement
-\samp{\var{o1} -= \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceMultiply}{PyObject *o1,
-                                                       PyObject *o2}
-Returns the result of multiplying \var{o1} and \var{o2}, or \NULL{} on
-failure.  The operation is done \emph{in-place} when \var{o1} supports it. 
-This is the equivalent of the Python statement \samp{\var{o1} *= \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceDivide}{PyObject *o1,
-                                                     PyObject *o2}
-Returns the result of dividing \var{o1} by \var{o2}, or \NULL{} on
-failure.  The operation is done \emph{in-place} when \var{o1} supports
-it. This is the equivalent of the Python statement \samp{\var{o1} /=
-\var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceFloorDivide}{PyObject *o1,
-                                                          PyObject *o2}
-Returns the mathematical of dividing \var{o1} by \var{o2}, or \NULL{}
-on failure.  The operation is done \emph{in-place} when \var{o1}
-supports it.  This is the equivalent of the Python statement
-\samp{\var{o1} //= \var{o2}}.
-\versionadded{2.2}
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceTrueDivide}{PyObject *o1,
-                                                         PyObject *o2}
-Return a reasonable approximation for the mathematical value of
-\var{o1} divided by \var{o2}, or \NULL{} on failure.  The return value
-is ``approximate'' because binary floating point numbers are
-approximate; it is not possible to represent all real numbers in base
-two.  This function can return a floating point value when passed two
-integers.  The operation is done \emph{in-place} when \var{o1}
-supports it.
-\versionadded{2.2}
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceRemainder}{PyObject *o1,
-                                                        PyObject *o2}
-Returns the remainder of dividing \var{o1} by \var{o2}, or \NULL{} on
-failure.  The operation is done \emph{in-place} when \var{o1} supports it. 
-This is the equivalent of the Python statement \samp{\var{o1} \%= \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_InPlacePower}{PyObject *o1,
-                                                    PyObject *o2, PyObject *o3}
-See the built-in function \function{pow()}.\bifuncindex{pow}  Returns
-\NULL{} on failure.  The operation is done \emph{in-place} when
-\var{o1} supports it.  This is the equivalent of the Python statement
-\samp{\var{o1} **= \var{o2}} when o3 is \cdata{Py_None}, or an
-in-place variant of \samp{pow(\var{o1}, \var{o2}, \var{o3})}
-otherwise. If \var{o3} is to be ignored, pass \cdata{Py_None} in its
-place (passing \NULL{} for \var{o3} would cause an illegal memory
-access).
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceLshift}{PyObject *o1,
-                                                     PyObject *o2}
-Returns the result of left shifting \var{o1} by \var{o2} on success,
-or \NULL{} on failure.  The operation is done \emph{in-place} when
-\var{o1} supports it.  This is the equivalent of the Python statement
-\samp{\var{o1} <\code{<=} \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceRshift}{PyObject *o1,
-                                                     PyObject *o2}
-Returns the result of right shifting \var{o1} by \var{o2} on success,
-or \NULL{} on failure.  The operation is done \emph{in-place} when
-\var{o1} supports it.  This is the equivalent of the Python statement
-\samp{\var{o1} >\code{>=} \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceAnd}{PyObject *o1, PyObject *o2}
-Returns the ``bitwise and'' of \var{o1} and \var{o2} on success
-and \NULL{} on failure. The operation is done \emph{in-place} when
-\var{o1} supports it.  This is the equivalent of the Python statement
-\samp{\var{o1} \&= \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceXor}{PyObject *o1, PyObject *o2}
-Returns the ``bitwise exclusive or'' of \var{o1} by \var{o2} on
-success, or \NULL{} on failure.  The operation is done \emph{in-place}
-when \var{o1} supports it.  This is the equivalent of the Python
-statement \samp{\var{o1} \textasciicircum= \var{o2}}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceOr}{PyObject *o1, PyObject *o2}
-Returns the ``bitwise or'' of \var{o1} and \var{o2} on success, or
-\NULL{} on failure.  The operation is done \emph{in-place} when
-\var{o1} supports it.  This is the equivalent of the Python statement
-\samp{\var{o1} |= \var{o2}}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyNumber_Coerce}{PyObject **p1, PyObject **p2}
-This function takes the addresses of two variables of type
-\ctype{PyObject*}.  If the objects pointed to by \code{*\var{p1}} and
-\code{*\var{p2}} have the same type, increment their reference count
-and return \code{0} (success). If the objects can be converted to a
-common numeric type, replace \code{*p1} and \code{*p2} by their
-converted value (with 'new' reference counts), and return \code{0}.
-If no conversion is possible, or if some other error occurs, return
-\code{-1} (failure) and don't increment the reference counts.  The
-call \code{PyNumber_Coerce(\&o1, \&o2)} is equivalent to the Python
-statement \samp{\var{o1}, \var{o2} = coerce(\var{o1}, \var{o2})}.
-\bifuncindex{coerce}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Int}{PyObject *o}
-Returns the \var{o} converted to an integer object on success, or
-\NULL{} on failure.  This is the equivalent of the Python
-expression \samp{int(\var{o})}.\bifuncindex{int}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Long}{PyObject *o}
-Returns the \var{o} converted to a long integer object on success,
-or \NULL{} on failure.  This is the equivalent of the Python
-expression \samp{long(\var{o})}.\bifuncindex{long}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Float}{PyObject *o}
-Returns the \var{o} converted to a float object on success, or
-\NULL{} on failure.  This is the equivalent of the Python expression
-\samp{float(\var{o})}.\bifuncindex{float}
-\end{cfuncdesc}
-
-
-\section{Sequence Protocol \label{sequence}}
-
-\begin{cfuncdesc}{int}{PySequence_Check}{PyObject *o}
-Return \code{1} if the object provides sequence protocol, and
-\code{0} otherwise.  This function always succeeds.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PySequence_Size}{PyObject *o}
-Returns the number of objects in sequence \var{o} on success, and
-\code{-1} on failure.  For objects that do not provide sequence
-protocol, this is equivalent to the Python expression
-\samp{len(\var{o})}.\bifuncindex{len}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PySequence_Length}{PyObject *o}
-Alternate name for \cfunction{PySequence_Size()}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PySequence_Concat}{PyObject *o1, PyObject *o2}
-Return the concatenation of \var{o1} and \var{o2} on success, and \NULL{} on
-failure.   This is the equivalent of the Python
-expression \samp{\var{o1} + \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PySequence_Repeat}{PyObject *o, int count}
-Return the result of repeating sequence object
-\var{o} \var{count} times, or \NULL{} on failure.  This is the
-equivalent of the Python expression \samp{\var{o} * \var{count}}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PySequence_InPlaceConcat}{PyObject *o1,
-                                                       PyObject *o2}
-Return the concatenation of \var{o1} and \var{o2} on success, and \NULL{} on
-failure.  The operation is done \emph{in-place} when \var{o1} supports it. 
-This is the equivalent of the Python expression \samp{\var{o1} += \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PySequence_InPlaceRepeat}{PyObject *o, int count}
-Return the result of repeating sequence object \var{o} \var{count} times, or
-\NULL{} on failure.  The operation is done \emph{in-place} when \var{o}
-supports it.  This is the equivalent of the Python expression \samp{\var{o}
-*= \var{count}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PySequence_GetItem}{PyObject *o, int i}
-Return the \var{i}th element of \var{o}, or \NULL{} on failure. This
-is the equivalent of the Python expression \samp{\var{o}[\var{i}]}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PySequence_GetSlice}{PyObject *o, int i1, int i2}
-Return the slice of sequence object \var{o} between \var{i1} and
-\var{i2}, or \NULL{} on failure. This is the equivalent of the Python
-expression \samp{\var{o}[\var{i1}:\var{i2}]}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PySequence_SetItem}{PyObject *o, int i, PyObject *v}
-Assign object \var{v} to the \var{i}th element of \var{o}.
-Returns \code{-1} on failure.  This is the equivalent of the Python
-statement \samp{\var{o}[\var{i}] = \var{v}}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PySequence_DelItem}{PyObject *o, int i}
-Delete the \var{i}th element of object \var{o}.  Returns
-\code{-1} on failure.  This is the equivalent of the Python
-statement \samp{del \var{o}[\var{i}]}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PySequence_SetSlice}{PyObject *o, int i1,
-                                            int i2, PyObject *v}
-Assign the sequence object \var{v} to the slice in sequence
-object \var{o} from \var{i1} to \var{i2}.  This is the equivalent of
-the Python statement \samp{\var{o}[\var{i1}:\var{i2}] = \var{v}}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PySequence_DelSlice}{PyObject *o, int i1, int i2}
-Delete the slice in sequence object \var{o} from \var{i1} to \var{i2}.
-Returns \code{-1} on failure. This is the equivalent of the Python
-statement \samp{del \var{o}[\var{i1}:\var{i2}]}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PySequence_Tuple}{PyObject *o}
-Returns the \var{o} as a tuple on success, and \NULL{} on failure.
-This is equivalent to the Python expression \samp{tuple(\var{o})}.
-\bifuncindex{tuple}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PySequence_Count}{PyObject *o, PyObject *value}
-Return the number of occurrences of \var{value} in \var{o}, that is,
-return the number of keys for which \code{\var{o}[\var{key}] ==
-\var{value}}.  On failure, return \code{-1}.  This is equivalent to
-the Python expression \samp{\var{o}.count(\var{value})}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PySequence_Contains}{PyObject *o, PyObject *value}
-Determine if \var{o} contains \var{value}.  If an item in \var{o} is
-equal to \var{value}, return \code{1}, otherwise return \code{0}.  On
-error, return \code{-1}.  This is equivalent to the Python expression
-\samp{\var{value} in \var{o}}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PySequence_Index}{PyObject *o, PyObject *value}
-Return the first index \var{i} for which \code{\var{o}[\var{i}] ==
-\var{value}}.  On error, return \code{-1}.    This is equivalent to
-the Python expression \samp{\var{o}.index(\var{value})}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PySequence_List}{PyObject *o}
-Return a list object with the same contents as the arbitrary sequence
-\var{o}.  The returned list is guaranteed to be new.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PySequence_Tuple}{PyObject *o}
-Return a tuple object with the same contents as the arbitrary sequence
-\var{o}.  If \var{o} is a tuple, a new reference will be returned,
-otherwise a tuple will be constructed with the appropriate contents.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PySequence_Fast}{PyObject *o, const char *m}
-Returns the sequence \var{o} as a tuple, unless it is already a
-tuple or list, in which case \var{o} is returned.  Use
-\cfunction{PySequence_Fast_GET_ITEM()} to access the members of the
-result.  Returns \NULL{} on failure.  If the object is not a sequence,
-raises \exception{TypeError} with \var{m} as the message text.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PySequence_Fast_GET_ITEM}{PyObject *o, int i}
-Return the \var{i}th element of \var{o}, assuming that \var{o} was
-returned by \cfunction{PySequence_Fast()}, and that \var{i} is within
-bounds.  The caller is expected to get the length of the sequence by
-calling \cfunction{PySequence_Size()} on \var{o}, since lists and tuples
-are guaranteed to always return their true length.
-\end{cfuncdesc}
-
-
-\section{Mapping Protocol \label{mapping}}
-
-\begin{cfuncdesc}{int}{PyMapping_Check}{PyObject *o}
-Return \code{1} if the object provides mapping protocol, and
-\code{0} otherwise.  This function always succeeds.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyMapping_Length}{PyObject *o}
-Returns the number of keys in object \var{o} on success, and
-\code{-1} on failure.  For objects that do not provide mapping
-protocol, this is equivalent to the Python expression
-\samp{len(\var{o})}.\bifuncindex{len}
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyMapping_DelItemString}{PyObject *o, char *key}
-Remove the mapping for object \var{key} from the object \var{o}.
-Return \code{-1} on failure.  This is equivalent to
-the Python statement \samp{del \var{o}[\var{key}]}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyMapping_DelItem}{PyObject *o, PyObject *key}
-Remove the mapping for object \var{key} from the object \var{o}.
-Return \code{-1} on failure.  This is equivalent to
-the Python statement \samp{del \var{o}[\var{key}]}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyMapping_HasKeyString}{PyObject *o, char *key}
-On success, return \code{1} if the mapping object has the key
-\var{key} and \code{0} otherwise.  This is equivalent to the Python
-expression \samp{\var{o}.has_key(\var{key})}. 
-This function always succeeds.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyMapping_HasKey}{PyObject *o, PyObject *key}
-Return \code{1} if the mapping object has the key \var{key} and
-\code{0} otherwise.  This is equivalent to the Python expression
-\samp{\var{o}.has_key(\var{key})}. 
-This function always succeeds.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyMapping_Keys}{PyObject *o}
-On success, return a list of the keys in object \var{o}.  On
-failure, return \NULL{}. This is equivalent to the Python
-expression \samp{\var{o}.keys()}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyMapping_Values}{PyObject *o}
-On success, return a list of the values in object \var{o}.  On
-failure, return \NULL{}. This is equivalent to the Python
-expression \samp{\var{o}.values()}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyMapping_Items}{PyObject *o}
-On success, return a list of the items in object \var{o}, where
-each item is a tuple containing a key-value pair.  On
-failure, return \NULL{}. This is equivalent to the Python
-expression \samp{\var{o}.items()}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyMapping_GetItemString}{PyObject *o, char *key}
-Return element of \var{o} corresponding to the object \var{key} or
-\NULL{} on failure. This is the equivalent of the Python expression
-\samp{\var{o}[\var{key}]}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyMapping_SetItemString}{PyObject *o, char *key,
-                                                PyObject *v}
-Map the object \var{key} to the value \var{v} in object \var{o}.
-Returns \code{-1} on failure.  This is the equivalent of the Python
-statement \samp{\var{o}[\var{key}] = \var{v}}.
-\end{cfuncdesc}
-
-
-\section{Iterator Protocol \label{iterator}}
-
-\versionadded{2.2}
-
-There are only a couple of functions specifically for working with
-iterators.
-
-\begin{cfuncdesc}{int}{PyIter_Check}{PyObject *o}
-  Return true if the object \var{o} supports the iterator protocol.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyIter_Next}{PyObject *o}
-  Return the next value from the iteration \var{o}.  If the object is
-  an iterator, this retrieves the next value from the iteration, and
-  returns \NULL{} with no exception set if there are no remaining
-  items.  If the object is not an iterator, \exception{TypeError} is
-  raised, or if there is an error in retrieving the item, returns
-  \NULL{} and passes along the exception.
-\end{cfuncdesc}
-
-To write a loop which iterates over an iterator, the C code should
-look something like this:
-
-\begin{verbatim}
-PyObject *iterator = ...;
-PyObject *item;
-
-while (item = PyIter_Next(iter)) {
-    /* do something with item */
-}
-if (PyErr_Occurred()) {
-    /* propogate error */
-}
-else {
-    /* continue doing useful work */
-}
-\end{verbatim}
-
-
-\chapter{Concrete Objects Layer \label{concrete}}
-
-The functions in this chapter are specific to certain Python object
-types.  Passing them an object of the wrong type is not a good idea;
-if you receive an object from a Python program and you are not sure
-that it has the right type, you must perform a type check first;
-for example, to check that an object is a dictionary, use
-\cfunction{PyDict_Check()}.  The chapter is structured like the
-``family tree'' of Python object types.
-
-\strong{Warning:}
-While the functions described in this chapter carefully check the type
-of the objects which are passed in, many of them do not check for
-\NULL{} being passed instead of a valid object.  Allowing \NULL{} to
-be passed in can cause memory access violations and immediate
-termination of the interpreter.
-
-
-\section{Fundamental Objects \label{fundamental}}
-
-This section describes Python type objects and the singleton object 
-\code{None}.
-
-
-\subsection{Type Objects \label{typeObjects}}
-
-\obindex{type}
-\begin{ctypedesc}{PyTypeObject}
-The C structure of the objects used to describe built-in types.
-\end{ctypedesc}
-
-\begin{cvardesc}{PyObject*}{PyType_Type}
-This is the type object for type objects; it is the same object as
-\code{types.TypeType} in the Python layer.
-\withsubitem{(in module types)}{\ttindex{TypeType}}
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyType_Check}{PyObject *o}
-Returns true is the object \var{o} is a type object.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyType_HasFeature}{PyObject *o, int feature}
-Returns true if the type object \var{o} sets the feature
-\var{feature}.  Type features are denoted by single bit flags.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyType_IsSubtype}{PyTypeObject *a, PyTypeObject *b}
-Returns true if \var{a} is a subtype of \var{b}.
-\versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyType_GenericAlloc}{PyTypeObject *type,
-                                                  int nitems}
-\versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyType_GenericNew}{PyTypeObject *type,
-                                            PyObject *args, PyObject *kwds}
-\versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyType_Ready}{PyTypeObject *type}
-\versionadded{2.2}
-\end{cfuncdesc}
-
-
-\subsection{The None Object \label{noneObject}}
-
-\obindex{None@\texttt{None}}
-Note that the \ctype{PyTypeObject} for \code{None} is not directly
-exposed in the Python/C API.  Since \code{None} is a singleton,
-testing for object identity (using \samp{==} in C) is sufficient.
-There is no \cfunction{PyNone_Check()} function for the same reason.
-
-\begin{cvardesc}{PyObject*}{Py_None}
-The Python \code{None} object, denoting lack of value.  This object has
-no methods.
-\end{cvardesc}
-
-
-\section{Numeric Objects \label{numericObjects}}
-
-\obindex{numeric}
-
-
-\subsection{Plain Integer Objects \label{intObjects}}
-
-\obindex{integer}
-\begin{ctypedesc}{PyIntObject}
-This subtype of \ctype{PyObject} represents a Python integer object.
-\end{ctypedesc}
-
-\begin{cvardesc}{PyTypeObject}{PyInt_Type}
-This instance of \ctype{PyTypeObject} represents the Python plain 
-integer type.  This is the same object as \code{types.IntType}.
-\withsubitem{(in modules types)}{\ttindex{IntType}}
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyInt_Check}{PyObject* o}
-Returns true if \var{o} is of type \cdata{PyInt_Type} or a subtype of
-\cdata{PyInt_Type}.
-\versionchanged[Allowed subtypes to be accepted]{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyInt_CheckExact}{PyObject* o}
-Returns true if \var{o} is of type \cdata{PyInt_Type}, but not a
-subtype of \cdata{PyInt_Type}.
-\versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyInt_FromLong}{long ival}
-Creates a new integer object with a value of \var{ival}.
-
-The current implementation keeps an array of integer objects for all
-integers between \code{-1} and \code{100}, when you create an int in
-that range you actually just get back a reference to the existing
-object. So it should be possible to change the value of \code{1}. I
-suspect the behaviour of Python in this case is undefined. :-)
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{long}{PyInt_AsLong}{PyObject *io}
-Will first attempt to cast the object to a \ctype{PyIntObject}, if
-it is not already one, and then return its value.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{long}{PyInt_AS_LONG}{PyObject *io}
-Returns the value of the object \var{io}.  No error checking is
-performed.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{long}{PyInt_GetMax}{}
-Returns the system's idea of the largest integer it can handle
-(\constant{LONG_MAX}\ttindex{LONG_MAX}, as defined in the system
-header files).
-\end{cfuncdesc}
-
-
-\subsection{Long Integer Objects \label{longObjects}}
-
-\obindex{long integer}
-\begin{ctypedesc}{PyLongObject}
-This subtype of \ctype{PyObject} represents a Python long integer
-object.
-\end{ctypedesc}
-
-\begin{cvardesc}{PyTypeObject}{PyLong_Type}
-This instance of \ctype{PyTypeObject} represents the Python long
-integer type.  This is the same object as \code{types.LongType}.
-\withsubitem{(in modules types)}{\ttindex{LongType}}
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyLong_Check}{PyObject *p}
-Returns true if its argument is a \ctype{PyLongObject} or a subtype of
-\ctype{PyLongObject}.
-\versionchanged[Allowed subtypes to be accepted]{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyLong_CheckExact}{PyObject *p}
-Returns true if its argument is a \ctype{PyLongObject}, but not a
-subtype of \ctype{PyLongObject}.
-\versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyLong_FromLong}{long v}
-Returns a new \ctype{PyLongObject} object from \var{v}, or \NULL{} on
-failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyLong_FromUnsignedLong}{unsigned long v}
-Returns a new \ctype{PyLongObject} object from a C \ctype{unsigned
-long}, or \NULL{} on failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyLong_FromLongLong}{long long v}
-Returns a new \ctype{PyLongObject} object from a C \ctype{long long},
-or \NULL{} on failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyLong_FromUnsignedLongLong}{unsigned long long v}
-Returns a new \ctype{PyLongObject} object from a C \ctype{unsigned
-long long}, or \NULL{} on failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyLong_FromDouble}{double v}
-Returns a new \ctype{PyLongObject} object from the integer part of
-\var{v}, or \NULL{} on failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyLong_FromString}{char *str, char **pend,
-                                                int base}
-Return a new \ctype{PyLongObject} based on the string value in
-\var{str}, which is interpreted according to the radix in \var{base}.
-If \var{pend} is non-\NULL, \code{*\var{pend}} will point to the first 
-character in \var{str} which follows the representation of the
-number.  If \var{base} is \code{0}, the radix will be determined base
-on the leading characters of \var{str}: if \var{str} starts with
-\code{'0x'} or \code{'0X'}, radix 16 will be used; if \var{str} starts 
-with \code{'0'}, radix 8 will be used; otherwise radix 10 will be
-used.  If \var{base} is not \code{0}, it must be between \code{2} and
-\code{36}, inclusive.  Leading spaces are ignored.  If there are no
-digits, \exception{ValueError} will be raised.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyLong_FromUnicode}{Py_UNICODE *u,
-                                                 int length, int base}
-Convert a sequence of Unicode digits to a Python long integer value.
-The first parameter, \var{u}, points to the first character of the
-Unicode string, \var{length} gives the number of characters, and
-\var{base} is the radix for the conversion.  The radix must be in the
-range [2, 36]; if it is out of range, \exception{ValueError} will be
-raised.
-\versionadded{1.6}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyLong_FromVoidPtr}{void *p}
-Create a Python integer or long integer from the pointer \var{p}.  The
-pointer value can be retrieved from the resulting value using
-\cfunction{PyLong_AsVoidPtr()}.
-\versionadded{1.5.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{long}{PyLong_AsLong}{PyObject *pylong}
-Returns a C \ctype{long} representation of the contents of
-\var{pylong}.  If \var{pylong} is greater than
-\constant{LONG_MAX}\ttindex{LONG_MAX}, an \exception{OverflowError} is
-raised.\withsubitem{(built-in exception)}{\ttindex{OverflowError}}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{unsigned long}{PyLong_AsUnsignedLong}{PyObject *pylong}
-Returns a C \ctype{unsigned long} representation of the contents of 
-\var{pylong}.  If \var{pylong} is greater than
-\constant{ULONG_MAX}\ttindex{ULONG_MAX}, an \exception{OverflowError}
-is raised.\withsubitem{(built-in exception)}{\ttindex{OverflowError}}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{long long}{PyLong_AsLongLong}{PyObject *pylong}
-Return a C \ctype{long long} from a Python long integer.  If
-\var{pylong} cannot be represented as a \ctype{long long}, an
-\exception{OverflowError} will be raised.
-\versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{unsigned long long}{PyLong_AsUnsignedLongLong}{PyObject
-                                                                 *pylong}
-Return a C \ctype{unsigned long long} from a Python long integer.  If
-\var{pylong} cannot be represented as an \ctype{unsigned long long},
-an \exception{OverflowError} will be raised if the value is positive,
-or a \exception{TypeError} will be raised if the value is negative.
-\versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{double}{PyLong_AsDouble}{PyObject *pylong}
-Returns a C \ctype{double} representation of the contents of
-\var{pylong}.  If \var{pylong} cannot be approximately represented as
-a \ctype{double}, an \exception{OverflowError} exception is raised and
-\code{-1.0} will be returned.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void*}{PyLong_AsVoidPtr}{PyObject *pylong}
-Convert a Python integer or long integer \var{pylong} to a C
-\ctype{void} pointer.  If \var{pylong} cannot be converted, an
-\exception{OverflowError} will be raised.  This is only assured to
-produce a usable \ctype{void} pointer for values created with
-\cfunction{PyLong_FromVoidPtr()}.
-\versionadded{1.5.2}
-\end{cfuncdesc}
-
-
-\subsection{Floating Point Objects \label{floatObjects}}
-
-\obindex{floating point}
-\begin{ctypedesc}{PyFloatObject}
-This subtype of \ctype{PyObject} represents a Python floating point
-object.
-\end{ctypedesc}
-
-\begin{cvardesc}{PyTypeObject}{PyFloat_Type}
-This instance of \ctype{PyTypeObject} represents the Python floating
-point type.  This is the same object as \code{types.FloatType}.
-\withsubitem{(in modules types)}{\ttindex{FloatType}}
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyFloat_Check}{PyObject *p}
-Returns true if its argument is a \ctype{PyFloatObject} or a subtype
-of \ctype{PyFloatObject}.
-\versionchanged[Allowed subtypes to be accepted]{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyFloat_CheckExact}{PyObject *p}
-Returns true if its argument is a \ctype{PyFloatObject}, but not a
-subtype of \ctype{PyFloatObject}.
-\versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyFloat_FromDouble}{double v}
-Creates a \ctype{PyFloatObject} object from \var{v}, or \NULL{} on
-failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{double}{PyFloat_AsDouble}{PyObject *pyfloat}
-Returns a C \ctype{double} representation of the contents of \var{pyfloat}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{double}{PyFloat_AS_DOUBLE}{PyObject *pyfloat}
-Returns a C \ctype{double} representation of the contents of
-\var{pyfloat}, but without error checking.
-\end{cfuncdesc}
-
-
-\subsection{Complex Number Objects \label{complexObjects}}
-
-\obindex{complex number}
-Python's complex number objects are implemented as two distinct types
-when viewed from the C API:  one is the Python object exposed to
-Python programs, and the other is a C structure which represents the
-actual complex number value.  The API provides functions for working
-with both.
-
-\subsubsection{Complex Numbers as C Structures}
-
-Note that the functions which accept these structures as parameters
-and return them as results do so \emph{by value} rather than
-dereferencing them through pointers.  This is consistent throughout
-the API.
-
-\begin{ctypedesc}{Py_complex}
-The C structure which corresponds to the value portion of a Python
-complex number object.  Most of the functions for dealing with complex
-number objects use structures of this type as input or output values,
-as appropriate.  It is defined as:
-
-\begin{verbatim}
-typedef struct {
-   double real;
-   double imag;
-} Py_complex;
-\end{verbatim}
-\end{ctypedesc}
-
-\begin{cfuncdesc}{Py_complex}{_Py_c_sum}{Py_complex left, Py_complex right}
-Return the sum of two complex numbers, using the C
-\ctype{Py_complex} representation.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{Py_complex}{_Py_c_diff}{Py_complex left, Py_complex right}
-Return the difference between two complex numbers, using the C
-\ctype{Py_complex} representation.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{Py_complex}{_Py_c_neg}{Py_complex complex}
-Return the negation of the complex number \var{complex}, using the C
-\ctype{Py_complex} representation.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{Py_complex}{_Py_c_prod}{Py_complex left, Py_complex right}
-Return the product of two complex numbers, using the C
-\ctype{Py_complex} representation.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{Py_complex}{_Py_c_quot}{Py_complex dividend,
-                                          Py_complex divisor}
-Return the quotient of two complex numbers, using the C
-\ctype{Py_complex} representation.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{Py_complex}{_Py_c_pow}{Py_complex num, Py_complex exp}
-Return the exponentiation of \var{num} by \var{exp}, using the C
-\ctype{Py_complex} representation.
-\end{cfuncdesc}
-
-
-\subsubsection{Complex Numbers as Python Objects}
-
-\begin{ctypedesc}{PyComplexObject}
-This subtype of \ctype{PyObject} represents a Python complex number object.
-\end{ctypedesc}
-
-\begin{cvardesc}{PyTypeObject}{PyComplex_Type}
-This instance of \ctype{PyTypeObject} represents the Python complex 
-number type.
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyComplex_Check}{PyObject *p}
-Returns true if its argument is a \ctype{PyComplexObject} or a subtype
-of \ctype{PyComplexObject}.
-\versionchanged[Allowed subtypes to be accepted]{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyComplex_CheckExact}{PyObject *p}
-Returns true if its argument is a \ctype{PyComplexObject}, but not a
-subtype of \ctype{PyComplexObject}.
-\versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyComplex_FromCComplex}{Py_complex v}
-Create a new Python complex number object from a C
-\ctype{Py_complex} value.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyComplex_FromDoubles}{double real, double imag}
-Returns a new \ctype{PyComplexObject} object from \var{real} and \var{imag}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{double}{PyComplex_RealAsDouble}{PyObject *op}
-Returns the real part of \var{op} as a C \ctype{double}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{double}{PyComplex_ImagAsDouble}{PyObject *op}
-Returns the imaginary part of \var{op} as a C \ctype{double}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{Py_complex}{PyComplex_AsCComplex}{PyObject *op}
-Returns the \ctype{Py_complex} value of the complex number \var{op}.
-\end{cfuncdesc}
-
-
-
-\section{Sequence Objects \label{sequenceObjects}}
-
-\obindex{sequence}
-Generic operations on sequence objects were discussed in the previous 
-chapter; this section deals with the specific kinds of sequence 
-objects that are intrinsic to the Python language.
-
-
-\subsection{String Objects \label{stringObjects}}
-
-These functions raise \exception{TypeError} when expecting a string
-parameter and are called with a non-string parameter.
-
-\obindex{string}
-\begin{ctypedesc}{PyStringObject}
-This subtype of \ctype{PyObject} represents a Python string object.
-\end{ctypedesc}
-
-\begin{cvardesc}{PyTypeObject}{PyString_Type}
-This instance of \ctype{PyTypeObject} represents the Python string
-type; it is the same object as \code{types.TypeType} in the Python
-layer.\withsubitem{(in module types)}{\ttindex{StringType}}.
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyString_Check}{PyObject *o}
-Returns true if the object \var{o} is a string object or an instance
-of a subtype of the string type.
-\versionchanged[Allowed subtypes to be accepted]{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyString_CheckExact}{PyObject *o}
-Returns true if the object \var{o} is a string object, but not an
-instance of a subtype of the string type.
-\versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyString_FromString}{const char *v}
-Returns a new string object with the value \var{v} on success, and
-\NULL{} on failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyString_FromStringAndSize}{const char *v,
-                                                         int len}
-Returns a new string object with the value \var{v} and length
-\var{len} on success, and \NULL{} on failure.  If \var{v} is \NULL{},
-the contents of the string are uninitialized.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyString_FromFormat}{const char *format, ...}
-Takes a C \code{printf}-style \var{format} string and a variable
-number of arguments, calculates the size of the resulting Python
-string and returns a string with the values formatted into it.  The
-variable arguments must be C types and must correspond exactly to the
-format characters in the \var{format} string.  The following format
-characters are allowed:
-\begin{tableiii}{l|l|l}{member}{Format Characters}{Type}{Comment}
-    \lineiii{\%\%}{\emph{n/a}}{The literal \% character.}
-    \lineiii{\%c}{int}{A single character, represented as an C int.}
-    \lineiii{\%d}{int}{Exactly equivalent to \code{printf("\%d")}.}
-    \lineiii{\%ld}{long}{Exactly equivalent to \code{printf("\%ld")}.}
-    \lineiii{\%i}{int}{Exactly equivalent to \code{printf("\%i")}.}
-    \lineiii{\%x}{int}{Exactly equivalent to \code{printf("\%x")}.}
-    \lineiii{\%s}{char*}{A null-terminated C character array.}
-    \lineiii{\%p}{void*}{The hex representation of a C pointer.
-	Mostly equivalent to \code{printf("\%p")} except that it is
-	guaranteed to start with the literal \code{0x} regardless of
-	what the platform's \code{printf} yields.}
-\end{tableiii}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyString_FromFormatV}{const char *format,
-                                                   va_list vargs}
-Identical to \function{PyString_FromFormat()} except that it takes
-exactly two arguments.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyString_Size}{PyObject *string}
-Returns the length of the string in string object \var{string}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyString_GET_SIZE}{PyObject *string}
-Macro form of \cfunction{PyString_Size()} but without error
-checking.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{char*}{PyString_AsString}{PyObject *string}
-Returns a null-terminated representation of the contents of
-\var{string}.  The pointer refers to the internal buffer of
-\var{string}, not a copy.  The data must not be modified in any way,
-unless the string was just created using
-\code{PyString_FromStringAndSize(NULL, \var{size})}.
-It must not be deallocated.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{char*}{PyString_AS_STRING}{PyObject *string}
-Macro form of \cfunction{PyString_AsString()} but without error
-checking.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyString_AsStringAndSize}{PyObject *obj,
-                                                 char **buffer,
-                                                 int *length}
-Returns a null-terminated representation of the contents of the object
-\var{obj} through the output variables \var{buffer} and \var{length}.
-
-The function accepts both string and Unicode objects as input. For
-Unicode objects it returns the default encoded version of the object.
-If \var{length} is set to \NULL{}, the resulting buffer may not contain
-null characters; if it does, the function returns -1 and a
-TypeError is raised.
-
-The buffer refers to an internal string buffer of \var{obj}, not a
-copy. The data must not be modified in any way, unless the string was
-just created using \code{PyString_FromStringAndSize(NULL,
-\var{size})}.  It must not be deallocated.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyString_Concat}{PyObject **string,
-                                         PyObject *newpart}
-Creates a new string object in \var{*string} containing the
-contents of \var{newpart} appended to \var{string}; the caller will
-own the new reference.  The reference to the old value of \var{string}
-will be stolen.  If the new string
-cannot be created, the old reference to \var{string} will still be
-discarded and the value of \var{*string} will be set to
-\NULL{}; the appropriate exception will be set.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyString_ConcatAndDel}{PyObject **string,
-                                               PyObject *newpart}
-Creates a new string object in \var{*string} containing the contents
-of \var{newpart} appended to \var{string}.  This version decrements
-the reference count of \var{newpart}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{_PyString_Resize}{PyObject **string, int newsize}
-A way to resize a string object even though it is ``immutable''.  
-Only use this to build up a brand new string object; don't use this if
-the string may already be known in other parts of the code.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyString_Format}{PyObject *format,
-                                              PyObject *args}
-Returns a new string object from \var{format} and \var{args}.  Analogous
-to \code{\var{format} \%\ \var{args}}.  The \var{args} argument must be
-a tuple.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyString_InternInPlace}{PyObject **string}
-Intern the argument \var{*string} in place.  The argument must be the
-address of a pointer variable pointing to a Python string object.
-If there is an existing interned string that is the same as
-\var{*string}, it sets \var{*string} to it (decrementing the reference 
-count of the old string object and incrementing the reference count of
-the interned string object), otherwise it leaves \var{*string} alone
-and interns it (incrementing its reference count).  (Clarification:
-even though there is a lot of talk about reference counts, think of
-this function as reference-count-neutral; you own the object after
-the call if and only if you owned it before the call.)
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyString_InternFromString}{const char *v}
-A combination of \cfunction{PyString_FromString()} and
-\cfunction{PyString_InternInPlace()}, returning either a new string object
-that has been interned, or a new (``owned'') reference to an earlier
-interned string object with the same value.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyString_Decode}{const char *s,
-                                               int size,
-                                               const char *encoding,
-                                               const char *errors}
-Creates an object by decoding \var{size} bytes of the encoded
-buffer \var{s} using the codec registered
-for \var{encoding}. \var{encoding} and \var{errors} have the same meaning
-as the parameters of the same name in the unicode() builtin
-function. The codec to be used is looked up using the Python codec
-registry. Returns \NULL{} in case an exception was raised by the
-codec.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyString_AsDecodedObject}{PyObject *str,
-                                               const char *encoding,
-                                               const char *errors}
-Decodes a string object by passing it to the codec registered
-for \var{encoding} and returns the result as Python 
-object. \var{encoding} and \var{errors} have the same meaning as the
-parameters of the same name in the string .encode() method. The codec
-to be used is looked up using the Python codec registry. Returns
-\NULL{} in case an exception was raised by the codec.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyString_Encode}{const char *s,
-                                               int size,
-                                               const char *encoding,
-                                               const char *errors}
-Encodes the \ctype{char} buffer of the given size by passing it to 
-the codec registered for \var{encoding} and returns a Python object. 
-\var{encoding} and \var{errors} have the same
-meaning as the parameters of the same name in the string .encode()
-method. The codec to be used is looked up using the Python codec
-registry. Returns \NULL{} in case an exception was raised by the
-codec.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyString_AsEncodedObject}{PyObject *str,
-                                               const char *encoding,
-                                               const char *errors}
-Encodes a string object using the codec registered
-for \var{encoding} and returns the result as Python 
-object. \var{encoding} and \var{errors} have the same meaning as the
-parameters of the same name in the string .encode() method. The codec
-to be used is looked up using the Python codec registry. Returns
-\NULL{} in case an exception was raised by the codec.
-\end{cfuncdesc}
-
-
-\subsection{Unicode Objects \label{unicodeObjects}}
-\sectionauthor{Marc-Andre Lemburg}{mal@lemburg.com}
-
-%--- Unicode Type -------------------------------------------------------
-
-These are the basic Unicode object types used for the Unicode
-implementation in Python:
-
-\begin{ctypedesc}{Py_UNICODE}
-This type represents a 16-bit unsigned storage type which is used by
-Python internally as basis for holding Unicode ordinals. On platforms
-where \ctype{wchar_t} is available and also has 16-bits,
-\ctype{Py_UNICODE} is a typedef alias for \ctype{wchar_t} to enhance
-native platform compatibility. On all other platforms,
-\ctype{Py_UNICODE} is a typedef alias for \ctype{unsigned short}.
-\end{ctypedesc}
-
-\begin{ctypedesc}{PyUnicodeObject}
-This subtype of \ctype{PyObject} represents a Python Unicode object.
-\end{ctypedesc}
-
-\begin{cvardesc}{PyTypeObject}{PyUnicode_Type}
-This instance of \ctype{PyTypeObject} represents the Python Unicode type.
-\end{cvardesc}
-
-%--- These are really C macros... is there a macrodesc TeX macro ?
-
-The following APIs are really C macros and can be used to do fast
-checks and to access internal read-only data of Unicode objects:
-
-\begin{cfuncdesc}{int}{PyUnicode_Check}{PyObject *o}
-Returns true if the object \var{o} is a Unicode object or an instance
-of a Unicode subtype.
-\versionchanged[Allowed subtypes to be accepted]{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyUnicode_CheckExact}{PyObject *o}
-Returns true if the object \var{o} is a Unicode object, but not an
-instance of a subtype.
-\versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyUnicode_GET_SIZE}{PyObject *o}
-Returns the size of the object.  o has to be a
-PyUnicodeObject (not checked).
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyUnicode_GET_DATA_SIZE}{PyObject *o}
-Returns the size of the object's internal buffer in bytes. o has to be
-a PyUnicodeObject (not checked).
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{Py_UNICODE*}{PyUnicode_AS_UNICODE}{PyObject *o}
-Returns a pointer to the internal Py_UNICODE buffer of the object. o
-has to be a PyUnicodeObject (not checked).
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{const char*}{PyUnicode_AS_DATA}{PyObject *o}
-Returns a (const char *) pointer to the internal buffer of the object.
-o has to be a PyUnicodeObject (not checked).
-\end{cfuncdesc}
-
-% --- Unicode character properties ---------------------------------------
-
-Unicode provides many different character properties. The most often
-needed ones are available through these macros which are mapped to C
-functions depending on the Python configuration.
-
-\begin{cfuncdesc}{int}{Py_UNICODE_ISSPACE}{Py_UNICODE ch}
-Returns 1/0 depending on whether \var{ch} is a whitespace character.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{Py_UNICODE_ISLOWER}{Py_UNICODE ch}
-Returns 1/0 depending on whether \var{ch} is a lowercase character.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{Py_UNICODE_ISUPPER}{Py_UNICODE ch}
-Returns 1/0 depending on whether \var{ch} is an uppercase character.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{Py_UNICODE_ISTITLE}{Py_UNICODE ch}
-Returns 1/0 depending on whether \var{ch} is a titlecase character.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{Py_UNICODE_ISLINEBREAK}{Py_UNICODE ch}
-Returns 1/0 depending on whether \var{ch} is a linebreak character.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{Py_UNICODE_ISDECIMAL}{Py_UNICODE ch}
-Returns 1/0 depending on whether \var{ch} is a decimal character.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{Py_UNICODE_ISDIGIT}{Py_UNICODE ch}
-Returns 1/0 depending on whether \var{ch} is a digit character.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{Py_UNICODE_ISNUMERIC}{Py_UNICODE ch}
-Returns 1/0 depending on whether \var{ch} is a numeric character.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{Py_UNICODE_ISALPHA}{Py_UNICODE ch}
-Returns 1/0 depending on whether \var{ch} is an alphabetic character.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{Py_UNICODE_ISALNUM}{Py_UNICODE ch}
-Returns 1/0 depending on whether \var{ch} is an alphanumeric character.
-\end{cfuncdesc}
-
-These APIs can be used for fast direct character conversions:
-
-\begin{cfuncdesc}{Py_UNICODE}{Py_UNICODE_TOLOWER}{Py_UNICODE ch}
-Returns the character \var{ch} converted to lower case.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{Py_UNICODE}{Py_UNICODE_TOUPPER}{Py_UNICODE ch}
-Returns the character \var{ch} converted to upper case.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{Py_UNICODE}{Py_UNICODE_TOTITLE}{Py_UNICODE ch}
-Returns the character \var{ch} converted to title case.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{Py_UNICODE_TODECIMAL}{Py_UNICODE ch}
-Returns the character \var{ch} converted to a decimal positive integer.
-Returns -1 in case this is not possible. Does not raise exceptions.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{Py_UNICODE_TODIGIT}{Py_UNICODE ch}
-Returns the character \var{ch} converted to a single digit integer.
-Returns -1 in case this is not possible. Does not raise exceptions.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{double}{Py_UNICODE_TONUMERIC}{Py_UNICODE ch}
-Returns the character \var{ch} converted to a (positive) double.
-Returns -1.0 in case this is not possible. Does not raise exceptions.
-\end{cfuncdesc}
-
-% --- Plain Py_UNICODE ---------------------------------------------------
-
-To create Unicode objects and access their basic sequence properties,
-use these APIs:
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_FromUnicode}{const Py_UNICODE *u,
-                                                    int size} 
-
-Create a Unicode Object from the Py_UNICODE buffer \var{u} of the
-given size. \var{u} may be \NULL{} which causes the contents to be
-undefined. It is the user's responsibility to fill in the needed data.
-The buffer is copied into the new object. If the buffer is not \NULL{},
-the return value might be a shared object. Therefore, modification of
-the resulting Unicode Object is only allowed when \var{u} is \NULL{}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{Py_UNICODE*}{PyUnicode_AsUnicode}{PyObject *unicode}
-Return a read-only pointer to the Unicode object's internal
-\ctype{Py_UNICODE} buffer.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyUnicode_GetSize}{PyObject *unicode}
-Return the length of the Unicode object.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_FromEncodedObject}{PyObject *obj,
-                                                      const char *encoding,
-                                                      const char *errors}
-
-Coerce an encoded object obj to an Unicode object and return a
-reference with incremented refcount.
-
-Coercion is done in the following way:
-\begin{enumerate}
-\item  Unicode objects are passed back as-is with incremented
-      refcount. Note: these cannot be decoded; passing a non-NULL
-      value for encoding will result in a TypeError.
-
-\item String and other char buffer compatible objects are decoded
-      according to the given encoding and using the error handling
-      defined by errors. Both can be NULL to have the interface use
-      the default values (see the next section for details).
-
-\item All other objects cause an exception.
-\end{enumerate}
-The API returns NULL in case of an error. The caller is responsible
-for decref'ing the returned objects.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_FromObject}{PyObject *obj}
-
-Shortcut for PyUnicode_FromEncodedObject(obj, NULL, ``strict'')
-which is used throughout the interpreter whenever coercion to
-Unicode is needed.
-\end{cfuncdesc}
-
-% --- wchar_t support for platforms which support it ---------------------
-
-If the platform supports \ctype{wchar_t} and provides a header file
-wchar.h, Python can interface directly to this type using the
-following functions. Support is optimized if Python's own
-\ctype{Py_UNICODE} type is identical to the system's \ctype{wchar_t}.
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_FromWideChar}{const wchar_t *w,
-                                                     int size}
-Create a Unicode Object from the \ctype{whcar_t} buffer \var{w} of the
-given size. Returns \NULL{} on failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyUnicode_AsWideChar}{PyUnicodeObject *unicode,
-                                             wchar_t *w,
-                                             int size}
-Copies the Unicode Object contents into the \ctype{whcar_t} buffer
-\var{w}.  At most \var{size} \ctype{whcar_t} characters are copied.
-Returns the number of \ctype{whcar_t} characters copied or -1 in case
-of an error.
-\end{cfuncdesc}
-
-
-\subsubsection{Builtin Codecs \label{builtinCodecs}}
-
-Python provides a set of builtin codecs which are written in C
-for speed. All of these codecs are directly usable via the
-following functions.
-
-Many of the following APIs take two arguments encoding and
-errors. These parameters encoding and errors have the same semantics
-as the ones of the builtin unicode() Unicode object constructor.
-
-Setting encoding to NULL causes the default encoding to be used which
-is \ASCII{}. The file system calls should use
-\var{Py_FileSystemDefaultEncoding} as the encoding for file
-names. This variable should be treated as read-only: On some systems,
-it will be a pointer to a static string, on others, it will change at
-run-time, e.g. when the application invokes setlocale.
-
-Error handling is set by errors which may also be set to NULL meaning
-to use the default handling defined for the codec. Default error
-handling for all builtin codecs is ``strict'' (ValueErrors are raised).
-
-The codecs all use a similar interface. Only deviation from the
-following generic ones are documented for simplicity.
-
-% --- Generic Codecs -----------------------------------------------------
-
-These are the generic codec APIs:
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_Decode}{const char *s,
-                                               int size,
-                                               const char *encoding,
-                                               const char *errors}
-Create a Unicode object by decoding \var{size} bytes of the encoded
-string \var{s}. \var{encoding} and \var{errors} have the same meaning
-as the parameters of the same name in the unicode() builtin
-function. The codec to be used is looked up using the Python codec
-registry. Returns \NULL{} in case an exception was raised by the
-codec.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_Encode}{const Py_UNICODE *s,
-                                               int size,
-                                               const char *encoding,
-                                               const char *errors}
-Encodes the \ctype{Py_UNICODE} buffer of the given size and returns a
-Python string object. \var{encoding} and \var{errors} have the same
-meaning as the parameters of the same name in the Unicode .encode()
-method. The codec to be used is looked up using the Python codec
-registry. Returns \NULL{} in case an exception was raised by the
-codec.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_AsEncodedString}{PyObject *unicode,
-                                               const char *encoding,
-                                               const char *errors}
-Encodes a Unicode object and returns the result as Python string
-object. \var{encoding} and \var{errors} have the same meaning as the
-parameters of the same name in the Unicode .encode() method. The codec
-to be used is looked up using the Python codec registry. Returns
-\NULL{} in case an exception was raised by the codec.
-\end{cfuncdesc}
-
-% --- UTF-8 Codecs -------------------------------------------------------
-
-These are the UTF-8 codec APIs:
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF8}{const char *s,
-                                               int size,
-                                               const char *errors}
-Creates a Unicode object by decoding \var{size} bytes of the UTF-8
-encoded string \var{s}. Returns \NULL{} in case an exception was
-raised by the codec.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeUTF8}{const Py_UNICODE *s,
-                                               int size,
-                                               const char *errors}
-Encodes the \ctype{Py_UNICODE} buffer of the given size using UTF-8
-and returns a Python string object.  Returns \NULL{} in case an
-exception was raised by the codec.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_AsUTF8String}{PyObject *unicode}
-Encodes a Unicode objects using UTF-8 and returns the result as Python
-string object. Error handling is ``strict''. Returns
-\NULL{} in case an exception was raised by the codec.
-\end{cfuncdesc}
-
-% --- UTF-16 Codecs ------------------------------------------------------ */
-
-These are the UTF-16 codec APIs:
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF16}{const char *s,
-                                               int size,
-                                               const char *errors,
-                                               int *byteorder}
-Decodes \var{length} bytes from a UTF-16 encoded buffer string and
-returns the corresponding Unicode object.
-
-\var{errors} (if non-NULL) defines the error handling. It defaults
-to ``strict''.
-
-If \var{byteorder} is non-\NULL{}, the decoder starts decoding using
-the given byte order:
-
-\begin{verbatim}
-   *byteorder == -1: little endian
-   *byteorder == 0:  native order
-   *byteorder == 1:  big endian
-\end{verbatim}
-
-and then switches according to all byte order marks (BOM) it finds in
-the input data. BOM marks are not copied into the resulting Unicode
-string.  After completion, \var{*byteorder} is set to the current byte
-order at the end of input data.
-
-If \var{byteorder} is \NULL{}, the codec starts in native order mode.
-
-Returns \NULL{} in case an exception was raised by the codec.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeUTF16}{const Py_UNICODE *s,
-                                               int size,
-                                               const char *errors,
-                                               int byteorder}
-Returns a Python string object holding the UTF-16 encoded value of the
-Unicode data in \var{s}.
-
-If \var{byteorder} is not \code{0}, output is written according to the
-following byte order:
-
-\begin{verbatim}
-   byteorder == -1: little endian
-   byteorder == 0:  native byte order (writes a BOM mark)
-   byteorder == 1:  big endian
-\end{verbatim}
-
-If byteorder is \code{0}, the output string will always start with the
-Unicode BOM mark (U+FEFF). In the other two modes, no BOM mark is
-prepended.
-
-Note that \ctype{Py_UNICODE} data is being interpreted as UTF-16
-reduced to UCS-2. This trick makes it possible to add full UTF-16
-capabilities at a later point without comprimising the APIs.
-
-Returns \NULL{} in case an exception was raised by the codec.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_AsUTF16String}{PyObject *unicode}
-Returns a Python string using the UTF-16 encoding in native byte
-order. The string always starts with a BOM mark. Error handling is
-``strict''. Returns \NULL{} in case an exception was raised by the
-codec.
-\end{cfuncdesc}
-
-% --- Unicode-Escape Codecs ----------------------------------------------
-
-These are the ``Unicode Esacpe'' codec APIs:
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUnicodeEscape}{const char *s,
-                                               int size,
-                                               const char *errors}
-Creates a Unicode object by decoding \var{size} bytes of the Unicode-Esacpe
-encoded string \var{s}. Returns \NULL{} in case an exception was
-raised by the codec.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeUnicodeEscape}{const Py_UNICODE *s,
-                                               int size,
-                                               const char *errors}
-Encodes the \ctype{Py_UNICODE} buffer of the given size using Unicode-Escape
-and returns a Python string object.  Returns \NULL{} in case an
-exception was raised by the codec.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_AsUnicodeEscapeString}{PyObject *unicode}
-Encodes a Unicode objects using Unicode-Escape and returns the result
-as Python string object. Error handling is ``strict''. Returns
-\NULL{} in case an exception was raised by the codec.
-\end{cfuncdesc}
-
-% --- Raw-Unicode-Escape Codecs ------------------------------------------
-
-These are the ``Raw Unicode Esacpe'' codec APIs:
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeRawUnicodeEscape}{const char *s,
-                                               int size,
-                                               const char *errors}
-Creates a Unicode object by decoding \var{size} bytes of the Raw-Unicode-Esacpe
-encoded string \var{s}. Returns \NULL{} in case an exception was
-raised by the codec.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeRawUnicodeEscape}{const Py_UNICODE *s,
-                                               int size,
-                                               const char *errors}
-Encodes the \ctype{Py_UNICODE} buffer of the given size using Raw-Unicode-Escape
-and returns a Python string object.  Returns \NULL{} in case an
-exception was raised by the codec.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_AsRawUnicodeEscapeString}{PyObject *unicode}
-Encodes a Unicode objects using Raw-Unicode-Escape and returns the result
-as Python string object. Error handling is ``strict''. Returns
-\NULL{} in case an exception was raised by the codec.
-\end{cfuncdesc}
-
-% --- Latin-1 Codecs ----------------------------------------------------- 
-
-These are the Latin-1 codec APIs:
-
-Latin-1 corresponds to the first 256 Unicode ordinals and only these
-are accepted by the codecs during encoding.
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeLatin1}{const char *s,
-                                                     int size,
-                                                     const char *errors}
-Creates a Unicode object by decoding \var{size} bytes of the Latin-1
-encoded string \var{s}. Returns \NULL{} in case an exception was
-raised by the codec.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeLatin1}{const Py_UNICODE *s,
-                                                     int size,
-                                                     const char *errors}
-Encodes the \ctype{Py_UNICODE} buffer of the given size using Latin-1
-and returns a Python string object.  Returns \NULL{} in case an
-exception was raised by the codec.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_AsLatin1String}{PyObject *unicode}
-Encodes a Unicode objects using Latin-1 and returns the result as
-Python string object. Error handling is ``strict''. Returns
-\NULL{} in case an exception was raised by the codec.
-\end{cfuncdesc}
-
-% --- ASCII Codecs ------------------------------------------------------- 
-
-These are the \ASCII{} codec APIs.  Only 7-bit \ASCII{} data is
-accepted. All other codes generate errors.
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeASCII}{const char *s,
-                                                    int size,
-                                                    const char *errors}
-Creates a Unicode object by decoding \var{size} bytes of the
-\ASCII{} encoded string \var{s}. Returns \NULL{} in case an exception
-was raised by the codec.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeASCII}{const Py_UNICODE *s,
-                                                    int size,
-                                                    const char *errors}
-Encodes the \ctype{Py_UNICODE} buffer of the given size using
-\ASCII{} and returns a Python string object.  Returns \NULL{} in case
-an exception was raised by the codec.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_AsASCIIString}{PyObject *unicode}
-Encodes a Unicode objects using \ASCII{} and returns the result as Python
-string object. Error handling is ``strict''. Returns
-\NULL{} in case an exception was raised by the codec.
-\end{cfuncdesc}
-
-% --- Character Map Codecs ----------------------------------------------- 
-
-These are the mapping codec APIs:
-
-This codec is special in that it can be used to implement many
-different codecs (and this is in fact what was done to obtain most of
-the standard codecs included in the \module{encodings} package). The
-codec uses mapping to encode and decode characters.
-
-Decoding mappings must map single string characters to single Unicode
-characters, integers (which are then interpreted as Unicode ordinals)
-or None (meaning "undefined mapping" and causing an error). 
-
-Encoding mappings must map single Unicode characters to single string
-characters, integers (which are then interpreted as Latin-1 ordinals)
-or None (meaning "undefined mapping" and causing an error).
-
-The mapping objects provided must only support the __getitem__ mapping
-interface.
-
-If a character lookup fails with a LookupError, the character is
-copied as-is meaning that its ordinal value will be interpreted as
-Unicode or Latin-1 ordinal resp. Because of this, mappings only need
-to contain those mappings which map characters to different code
-points.
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeCharmap}{const char *s,
-                                               int size,
-                                               PyObject *mapping,
-                                               const char *errors}
-Creates a Unicode object by decoding \var{size} bytes of the encoded
-string \var{s} using the given \var{mapping} object.  Returns \NULL{}
-in case an exception was raised by the codec.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeCharmap}{const Py_UNICODE *s,
-                                               int size,
-                                               PyObject *mapping,
-                                               const char *errors}
-Encodes the \ctype{Py_UNICODE} buffer of the given size using the
-given \var{mapping} object and returns a Python string object.
-Returns \NULL{} in case an exception was raised by the codec.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_AsCharmapString}{PyObject *unicode,
-                                                        PyObject *mapping}
-Encodes a Unicode objects using the given \var{mapping} object and
-returns the result as Python string object. Error handling is
-``strict''. Returns \NULL{} in case an exception was raised by the
-codec.
-\end{cfuncdesc}
-
-The following codec API is special in that maps Unicode to Unicode.
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_TranslateCharmap}{const Py_UNICODE *s,
-                                               int size,
-                                               PyObject *table,
-                                               const char *errors}
-Translates a \ctype{Py_UNICODE} buffer of the given length by applying
-a character mapping \var{table} to it and returns the resulting
-Unicode object.  Returns \NULL{} when an exception was raised by the
-codec.
-
-The \var{mapping} table must map Unicode ordinal integers to Unicode
-ordinal integers or None (causing deletion of the character).
-
-Mapping tables must only provide the __getitem__ interface,
-e.g. dictionaries or sequences. Unmapped character ordinals (ones
-which cause a LookupError) are left untouched and are copied as-is.
-\end{cfuncdesc}
-
-% --- MBCS codecs for Windows --------------------------------------------
-
-These are the MBCS codec APIs. They are currently only available on
-Windows and use the Win32 MBCS converters to implement the
-conversions.  Note that MBCS (or DBCS) is a class of encodings, not
-just one.  The target encoding is defined by the user settings on the
-machine running the codec.
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeMBCS}{const char *s,
-                                               int size,
-                                               const char *errors}
-Creates a Unicode object by decoding \var{size} bytes of the MBCS
-encoded string \var{s}.  Returns \NULL{} in case an exception was
-raised by the codec.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeMBCS}{const Py_UNICODE *s,
-                                               int size,
-                                               const char *errors}
-Encodes the \ctype{Py_UNICODE} buffer of the given size using MBCS
-and returns a Python string object.  Returns \NULL{} in case an
-exception was raised by the codec.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_AsMBCSString}{PyObject *unicode}
-Encodes a Unicode objects using MBCS and returns the result as Python
-string object.  Error handling is ``strict''.  Returns \NULL{} in case
-an exception was raised by the codec.
-\end{cfuncdesc}
-
-% --- Methods & Slots ----------------------------------------------------
-
-\subsubsection{Methods and Slot Functions \label{unicodeMethodsAndSlots}}
-
-The following APIs are capable of handling Unicode objects and strings
-on input (we refer to them as strings in the descriptions) and return
-Unicode objects or integers as apporpriate.
-
-They all return \NULL{} or -1 in case an exception occurrs.
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_Concat}{PyObject *left,
-                                               PyObject *right}
-Concat two strings giving a new Unicode string.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_Split}{PyObject *s,
-                                              PyObject *sep,
-                                              int maxsplit}
-Split a string giving a list of Unicode strings.
-
-If sep is NULL, splitting will be done at all whitespace
-substrings. Otherwise, splits occur at the given separator.
-
-At most maxsplit splits will be done. If negative, no limit is set.
-
-Separators are not included in the resulting list.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_Splitlines}{PyObject *s,
-                                                   int maxsplit}
-Split a Unicode string at line breaks, returning a list of Unicode
-strings.  CRLF is considered to be one line break.  The Line break
-characters are not included in the resulting strings.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_Translate}{PyObject *str,
-                                                  PyObject *table,
-                                                  const char *errors}
-Translate a string by applying a character mapping table to it and
-return the resulting Unicode object.
-
-The mapping table must map Unicode ordinal integers to Unicode ordinal
-integers or None (causing deletion of the character).
-
-Mapping tables must only provide the __getitem__ interface,
-e.g. dictionaries or sequences. Unmapped character ordinals (ones
-which cause a LookupError) are left untouched and are copied as-is.
-
-\var{errors} has the usual meaning for codecs. It may be \NULL{}
-which indicates to use the default error handling.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_Join}{PyObject *separator,
-                                             PyObject *seq}
-Join a sequence of strings using the given separator and return
-the resulting Unicode string.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_Tailmatch}{PyObject *str,
-                                                  PyObject *substr,
-                                                  int start,
-                                                  int end,
-                                                  int direction}
-Return 1 if \var{substr} matches \var{str}[\var{start}:\var{end}] at
-the given tail end (\var{direction} == -1 means to do a prefix match,
-\var{direction} == 1 a suffix match), 0 otherwise.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_Find}{PyObject *str,
-                                                  PyObject *substr,
-                                                  int start,
-                                                  int end,
-                                                  int direction}
-Return the first position of \var{substr} in
-\var{str}[\var{start}:\var{end}] using the given \var{direction}
-(\var{direction} == 1 means to do a forward search,
-\var{direction} == -1 a backward search), 0 otherwise.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_Count}{PyObject *str,
-                                                  PyObject *substr,
-                                                  int start,
-                                                  int end}
-Count the number of occurrences of \var{substr} in
-\var{str}[\var{start}:\var{end}]
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_Replace}{PyObject *str,
-                                                PyObject *substr,
-                                                PyObject *replstr,
-                                                int maxcount}
-Replace at most \var{maxcount} occurrences of \var{substr} in
-\var{str} with \var{replstr} and return the resulting Unicode object.
-\var{maxcount} == -1 means: replace all occurrences.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyUnicode_Compare}{PyObject *left, PyObject *right}
-Compare two strings and return -1, 0, 1 for less than, equal,
-greater than resp.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_Format}{PyObject *format,
-                                              PyObject *args}
-Returns a new string object from \var{format} and \var{args}; this is
-analogous to \code{\var{format} \%\ \var{args}}.  The
-\var{args} argument must be a tuple.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyUnicode_Contains}{PyObject *container,
-                                           PyObject *element}
-Checks whether \var{element} is contained in \var{container} and
-returns true or false accordingly.
-
-\var{element} has to coerce to a one element Unicode string. \code{-1} is
-returned in case of an error.
-\end{cfuncdesc}
-
-
-\subsection{Buffer Objects \label{bufferObjects}}
-\sectionauthor{Greg Stein}{gstein@lyra.org}
-
-\obindex{buffer}
-Python objects implemented in C can export a group of functions called
-the ``buffer\index{buffer interface} interface.''  These functions can
-be used by an object to expose its data in a raw, byte-oriented
-format. Clients of the object can use the buffer interface to access
-the object data directly, without needing to copy it first.
-
-Two examples of objects that support 
-the buffer interface are strings and arrays. The string object exposes 
-the character contents in the buffer interface's byte-oriented
-form. An array can also expose its contents, but it should be noted
-that array elements may be multi-byte values.
-
-An example user of the buffer interface is the file object's
-\method{write()} method. Any object that can export a series of bytes
-through the buffer interface can be written to a file. There are a
-number of format codes to \cfunction{PyArg_ParseTuple()} that operate 
-against an object's buffer interface, returning data from the target
-object.
-
-More information on the buffer interface is provided in the section
-``Buffer Object Structures'' (section \ref{buffer-structs}), under
-the description for \ctype{PyBufferProcs}\ttindex{PyBufferProcs}.
-
-A ``buffer object'' is defined in the \file{bufferobject.h} header
-(included by \file{Python.h}). These objects look very similar to
-string objects at the Python programming level: they support slicing,
-indexing, concatenation, and some other standard string
-operations. However, their data can come from one of two sources: from
-a block of memory, or from another object which exports the buffer
-interface.
-
-Buffer objects are useful as a way to expose the data from another
-object's buffer interface to the Python programmer. They can also be
-used as a zero-copy slicing mechanism. Using their ability to
-reference a block of memory, it is possible to expose any data to the
-Python programmer quite easily. The memory could be a large, constant
-array in a C extension, it could be a raw block of memory for
-manipulation before passing to an operating system library, or it
-could be used to pass around structured data in its native, in-memory
-format.
-
-\begin{ctypedesc}{PyBufferObject}
-This subtype of \ctype{PyObject} represents a buffer object.
-\end{ctypedesc}
-
-\begin{cvardesc}{PyTypeObject}{PyBuffer_Type}
-The instance of \ctype{PyTypeObject} which represents the Python
-buffer type; it is the same object as \code{types.BufferType} in the
-Python layer.\withsubitem{(in module types)}{\ttindex{BufferType}}.
-\end{cvardesc}
-
-\begin{cvardesc}{int}{Py_END_OF_BUFFER}
-This constant may be passed as the \var{size} parameter to
-\cfunction{PyBuffer_FromObject()} or
-\cfunction{PyBuffer_FromReadWriteObject()}. It indicates that the new
-\ctype{PyBufferObject} should refer to \var{base} object from the
-specified \var{offset} to the end of its exported buffer. Using this
-enables the caller to avoid querying the \var{base} object for its
-length.
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyBuffer_Check}{PyObject *p}
-Return true if the argument has type \cdata{PyBuffer_Type}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyBuffer_FromObject}{PyObject *base,
-                                                  int offset, int size}
-Return a new read-only buffer object.  This raises
-\exception{TypeError} if \var{base} doesn't support the read-only
-buffer protocol or doesn't provide exactly one buffer segment, or it
-raises \exception{ValueError} if \var{offset} is less than zero. The
-buffer will hold a reference to the \var{base} object, and the
-buffer's contents will refer to the \var{base} object's buffer
-interface, starting as position \var{offset} and extending for
-\var{size} bytes. If \var{size} is \constant{Py_END_OF_BUFFER}, then
-the new buffer's contents extend to the length of the
-\var{base} object's exported buffer data.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyBuffer_FromReadWriteObject}{PyObject *base,
-                                                           int offset,
-                                                           int size}
-Return a new writable buffer object.  Parameters and exceptions are
-similar to those for \cfunction{PyBuffer_FromObject()}.
-If the \var{base} object does not export the writeable buffer
-protocol, then \exception{TypeError} is raised.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyBuffer_FromMemory}{void *ptr, int size}
-Return a new read-only buffer object that reads from a specified
-location in memory, with a specified size.
-The caller is responsible for ensuring that the memory buffer, passed
-in as \var{ptr}, is not deallocated while the returned buffer object
-exists.  Raises \exception{ValueError} if \var{size} is less than
-zero.  Note that \constant{Py_END_OF_BUFFER} may \emph{not} be passed
-for the \var{size} parameter; \exception{ValueError} will be raised in 
-that case.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyBuffer_FromReadWriteMemory}{void *ptr, int size}
-Similar to \cfunction{PyBuffer_FromMemory()}, but the returned buffer
-is writable.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyBuffer_New}{int size}
-Returns a new writable buffer object that maintains its own memory
-buffer of \var{size} bytes.  \exception{ValueError} is returned if
-\var{size} is not zero or positive.
-\end{cfuncdesc}
-
-
-\subsection{Tuple Objects \label{tupleObjects}}
-
-\obindex{tuple}
-\begin{ctypedesc}{PyTupleObject}
-This subtype of \ctype{PyObject} represents a Python tuple object.
-\end{ctypedesc}
-
-\begin{cvardesc}{PyTypeObject}{PyTuple_Type}
-This instance of \ctype{PyTypeObject} represents the Python tuple
-type; it is the same object as \code{types.TupleType} in the Python
-layer.\withsubitem{(in module types)}{\ttindex{TupleType}}.
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyTuple_Check}{PyObject *p}
-Return true if \var{p} is a tuple object or an instance of a subtype
-of the tuple type.
-\versionchanged[Allowed subtypes to be accepted]{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyTuple_CheckExact}{PyObject *p}
-Return true if \var{p} is a tuple object, but not an instance of
-a subtype of the tuple type.
-\versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyTuple_New}{int len}
-Return a new tuple object of size \var{len}, or \NULL{} on failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyTuple_Size}{PyObject *p}
-Takes a pointer to a tuple object, and returns the size
-of that tuple.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyTuple_GET_SIZE}{PyObject *p}
-Return the size of the tuple \var{p}, which must be non-\NULL{} and
-point to a tuple; no error checking is performed.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyTuple_GetItem}{PyObject *p, int pos}
-Returns the object at position \var{pos} in the tuple pointed
-to by \var{p}.  If \var{pos} is out of bounds, returns \NULL{} and
-sets an \exception{IndexError} exception.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyTuple_GET_ITEM}{PyObject *p, int pos}
-Like \cfunction{PyTuple_GetItem()}, but does no checking of its
-arguments.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyTuple_GetSlice}{PyObject *p,
-                                               int low, int high}
-Takes a slice of the tuple pointed to by \var{p} from
-\var{low} to \var{high} and returns it as a new tuple.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyTuple_SetItem}{PyObject *p,
-                                        int pos, PyObject *o}
-Inserts a reference to object \var{o} at position \var{pos} of
-the tuple pointed to by \var{p}. It returns \code{0} on success.
-\strong{Note:}  This function ``steals'' a reference to \var{o}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyTuple_SET_ITEM}{PyObject *p,
-                                          int pos, PyObject *o}
-Like \cfunction{PyTuple_SetItem()}, but does no error checking, and
-should \emph{only} be used to fill in brand new tuples.
-\strong{Note:}  This function ``steals'' a reference to \var{o}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{_PyTuple_Resize}{PyObject **p, int newsize}
-Can be used to resize a tuple.  \var{newsize} will be the new length
-of the tuple.  Because tuples are \emph{supposed} to be immutable,
-this should only be used if there is only one reference to the object.
-Do \emph{not} use this if the tuple may already be known to some other
-part of the code.  The tuple will always grow or shrink at the end.
-Think of this as destroying the old tuple and creating a new one, only
-more efficiently.  Returns \code{0} on success.  Client code should
-never assume that the resulting value of \code{*\var{p}} will be the
-same as before calling this function.  If the object referenced by
-\code{*\var{p}} is replaced, the original \code{*\var{p}} is
-destroyed.  On failure, returns \code{-1} and sets \code{*\var{p}} to
-\NULL, and raises \exception{MemoryError} or \exception{SystemError}.
-\versionchanged[Removed unused third parameter, \var{last_is_sticky}]{2.2}
-\end{cfuncdesc}
-
-
-\subsection{List Objects \label{listObjects}}
-
-\obindex{list}
-\begin{ctypedesc}{PyListObject}
-This subtype of \ctype{PyObject} represents a Python list object.
-\end{ctypedesc}
-
-\begin{cvardesc}{PyTypeObject}{PyList_Type}
-This instance of \ctype{PyTypeObject} represents the Python list
-type.  This is the same object as \code{types.ListType}.
-\withsubitem{(in module types)}{\ttindex{ListType}}
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyList_Check}{PyObject *p}
-Returns true if its argument is a \ctype{PyListObject}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyList_New}{int len}
-Returns a new list of length \var{len} on success, or \NULL{} on
-failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyList_Size}{PyObject *list}
-Returns the length of the list object in \var{list}; this is
-equivalent to \samp{len(\var{list})} on a list object.
-\bifuncindex{len}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyList_GET_SIZE}{PyObject *list}
-Macro form of \cfunction{PyList_Size()} without error checking.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyList_GetItem}{PyObject *list, int index}
-Returns the object at position \var{pos} in the list pointed
-to by \var{p}.  If \var{pos} is out of bounds, returns \NULL{} and
-sets an \exception{IndexError} exception.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyList_GET_ITEM}{PyObject *list, int i}
-Macro form of \cfunction{PyList_GetItem()} without error checking.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyList_SetItem}{PyObject *list, int index,
-                                       PyObject *item}
-Sets the item at index \var{index} in list to \var{item}.
-Returns \code{0} on success or \code{-1} on failure.
-\strong{Note:}  This function ``steals'' a reference to \var{item} and
-discards a reference to an item already in the list at the affected
-position.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyList_SET_ITEM}{PyObject *list, int i,
-                                              PyObject *o}
-Macro form of \cfunction{PyList_SetItem()} without error checking.
-\strong{Note:}  This function ``steals'' a reference to \var{item},
-and, unlike \cfunction{PyList_SetItem()}, does \emph{not} discard a
-reference to any item that it being replaced; any reference in
-\var{list} at position \var{i} will be leaked.  This is normally only
-used to fill in new lists where there is no previous content.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyList_Insert}{PyObject *list, int index,
-                                      PyObject *item}
-Inserts the item \var{item} into list \var{list} in front of index
-\var{index}.  Returns \code{0} if successful; returns \code{-1} and
-raises an exception if unsuccessful.  Analogous to
-\code{\var{list}.insert(\var{index}, \var{item})}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyList_Append}{PyObject *list, PyObject *item}
-Appends the object \var{item} at the end of list \var{list}.  Returns
-\code{0} if successful; returns \code{-1} and sets an exception if
-unsuccessful.  Analogous to \code{\var{list}.append(\var{item})}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyList_GetSlice}{PyObject *list,
-                                              int low, int high}
-Returns a list of the objects in \var{list} containing the objects 
-\emph{between} \var{low} and \var{high}.  Returns NULL and sets an
-exception if unsuccessful.
-Analogous to \code{\var{list}[\var{low}:\var{high}]}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyList_SetSlice}{PyObject *list,
-                                        int low, int high,
-                                        PyObject *itemlist}
-Sets the slice of \var{list} between \var{low} and \var{high} to the
-contents of \var{itemlist}.  Analogous to
-\code{\var{list}[\var{low}:\var{high}] = \var{itemlist}}.  Returns
-\code{0} on success, \code{-1} on failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyList_Sort}{PyObject *list}
-Sorts the items of \var{list} in place.  Returns \code{0} on success,
-\code{-1} on failure.  This is equivalent to
-\samp{\var{list}.sort()}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyList_Reverse}{PyObject *list}
-Reverses the items of \var{list} in place.  Returns \code{0} on
-success, \code{-1} on failure.  This is the equivalent of
-\samp{\var{list}.reverse()}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyList_AsTuple}{PyObject *list}
-Returns a new tuple object containing the contents of \var{list};
-equivalent to \samp{tuple(\var{list})}.\bifuncindex{tuple}
-\end{cfuncdesc}
-
-
-\section{Mapping Objects \label{mapObjects}}
-
-\obindex{mapping}
-
-
-\subsection{Dictionary Objects \label{dictObjects}}
-
-\obindex{dictionary}
-\begin{ctypedesc}{PyDictObject}
-This subtype of \ctype{PyObject} represents a Python dictionary object.
-\end{ctypedesc}
-
-\begin{cvardesc}{PyTypeObject}{PyDict_Type}
-This instance of \ctype{PyTypeObject} represents the Python dictionary 
-type.  This is exposed to Python programs as \code{types.DictType} and 
-\code{types.DictionaryType}.
-\withsubitem{(in module types)}{\ttindex{DictType}\ttindex{DictionaryType}}
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyDict_Check}{PyObject *p}
-Returns true if its argument is a \ctype{PyDictObject}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyDict_New}{}
-Returns a new empty dictionary, or \NULL{} on failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyDictProxy_New}{PyObject *dict}
-Return a proxy object for a mapping which enforces read-only
-behavior.  This is normally used to create a proxy to prevent
-modification of the dictionary for non-dynamic class types.
-\versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyDict_Clear}{PyObject *p}
-Empties an existing dictionary of all key-value pairs.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyDict_Copy}{PyObject *p}
-Returns a new dictionary that contains the same key-value pairs as
-\var{p}.
-\versionadded{1.6}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyDict_SetItem}{PyObject *p, PyObject *key,
-                                       PyObject *val}
-Inserts \var{value} into the dictionary \var{p} with a key of \var{key}.
-\var{key} must be hashable; if it isn't, \exception{TypeError} will be 
-raised.
-Returns \code{0} on success or \code{-1} on failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyDict_SetItemString}{PyObject *p,
-            char *key,
-            PyObject *val}
-Inserts \var{value} into the dictionary \var{p} using \var{key}
-as a key. \var{key} should be a \ctype{char*}.  The key object is
-created using \code{PyString_FromString(\var{key})}.
-Returns \code{0} on success or \code{-1} on failure.
-\ttindex{PyString_FromString()}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyDict_DelItem}{PyObject *p, PyObject *key}
-Removes the entry in dictionary \var{p} with key \var{key}.
-\var{key} must be hashable; if it isn't, \exception{TypeError} is
-raised.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyDict_DelItemString}{PyObject *p, char *key}
-Removes the entry in dictionary \var{p} which has a key
-specified by the string \var{key}.
-Returns \code{0} on success or \code{-1} on failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyDict_GetItem}{PyObject *p, PyObject *key}
-Returns the object from dictionary \var{p} which has a key
-\var{key}.  Returns \NULL{} if the key \var{key} is not present, but
-\emph{without} setting an exception.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyDict_GetItemString}{PyObject *p, char *key}
-This is the same as \cfunction{PyDict_GetItem()}, but \var{key} is
-specified as a \ctype{char*}, rather than a \ctype{PyObject*}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyDict_Items}{PyObject *p}
-Returns a \ctype{PyListObject} containing all the items 
-from the dictionary, as in the dictinoary method \method{items()} (see
-the \citetitle[../lib/lib.html]{Python Library Reference}).
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyDict_Keys}{PyObject *p}
-Returns a \ctype{PyListObject} containing all the keys 
-from the dictionary, as in the dictionary method \method{keys()} (see the
-\citetitle[../lib/lib.html]{Python Library Reference}).
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyDict_Values}{PyObject *p}
-Returns a \ctype{PyListObject} containing all the values 
-from the dictionary \var{p}, as in the dictionary method
-\method{values()} (see the \citetitle[../lib/lib.html]{Python Library
-Reference}).
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyDict_Size}{PyObject *p}
-Returns the number of items in the dictionary.  This is equivalent to
-\samp{len(\var{p})} on a dictionary.\bifuncindex{len}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyDict_Next}{PyObject *p, int *ppos,
-                                    PyObject **pkey, PyObject **pvalue}
-Iterate over all key-value pairs in the dictionary \var{p}.  The
-\ctype{int} referred to by \var{ppos} must be initialized to \code{0}
-prior to the first call to this function to start the iteration; the
-function returns true for each pair in the dictionary, and false once
-all pairs have been reported.  The parameters \var{pkey} and
-\var{pvalue} should either point to \ctype{PyObject*} variables that
-will be filled in with each key and value, respectively, or may be
-\NULL.
-
-For example:
-
-\begin{verbatim}
-PyObject *key, *value;
-int pos = 0;
-
-while (PyDict_Next(self->dict, &pos, &key, &value)) {
-    /* do something interesting with the values... */
-    ...
-}
-\end{verbatim}
-
-The dictionary \var{p} should not be mutated during iteration.  It is
-safe (since Python 2.1) to modify the values of the keys as you
-iterate over the dictionary, but only so long as the set of keys does
-not change.  For example:
-
-\begin{verbatim}
-PyObject *key, *value;
-int pos = 0;
-
-while (PyDict_Next(self->dict, &pos, &key, &value)) {
-    int i = PyInt_AS_LONG(value) + 1;
-    PyObject *o = PyInt_FromLong(i);
-    if (o == NULL)
-        return -1;
-    if (PyDict_SetItem(self->dict, key, o) < 0) {
-        Py_DECREF(o);
-        return -1;
-    }
-    Py_DECREF(o);
-}
-\end{verbatim}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyDict_Merge}{PyObject *a, PyObject *b, int override}
-Iterate over dictionary \var{b} adding key-value pairs to dictionary
-\var{a}.  If \var{override} is true, existing pairs in \var{a} will be
-replaced if a matching key is found in \var{b}, otherwise pairs will
-only be added if there is not a matching key in \var{a}.  Returns
-\code{0} on success or \code{-1} if an exception was raised.
-\versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyDict_Update}{PyObject *a, PyObject *b}
-This is the same as \code{PyDict_Merge(\var{a}, \var{b}, 1)} in C, or
-\code{\var{a}.update(\var{b})} in Python.  Returns \code{0} on success
-or \code{-1} if an exception was raised.
-\versionadded{2.2}
-\end{cfuncdesc}
-
-
-\section{Other Objects \label{otherObjects}}
-
-\subsection{File Objects \label{fileObjects}}
-
-\obindex{file}
-Python's built-in file objects are implemented entirely on the
-\ctype{FILE*} support from the C standard library.  This is an
-implementation detail and may change in future releases of Python.
-
-\begin{ctypedesc}{PyFileObject}
-This subtype of \ctype{PyObject} represents a Python file object.
-\end{ctypedesc}
-
-\begin{cvardesc}{PyTypeObject}{PyFile_Type}
-This instance of \ctype{PyTypeObject} represents the Python file
-type.  This is exposed to Python programs as \code{types.FileType}.
-\withsubitem{(in module types)}{\ttindex{FileType}}
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyFile_Check}{PyObject *p}
-Returns true if its argument is a \ctype{PyFileObject} or a subtype of
-\ctype{PyFileObject}.
-\versionchanged[Allowed subtypes to be accepted]{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyFile_CheckExact}{PyObject *p}
-Returns true if its argument is a \ctype{PyFileObject}, but not a
-subtype of \ctype{PyFileObject}.
-\versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyFile_FromString}{char *filename, char *mode}
-On success, returns a new file object that is opened on the
-file given by \var{filename}, with a file mode given by \var{mode},
-where \var{mode} has the same semantics as the standard C routine
-\cfunction{fopen()}\ttindex{fopen()}.  On failure, returns \NULL.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyFile_FromFile}{FILE *fp,
-                                              char *name, char *mode,
-                                              int (*close)(FILE*)}
-Creates a new \ctype{PyFileObject} from the already-open standard C
-file pointer, \var{fp}.  The function \var{close} will be called when
-the file should be closed.  Returns \NULL{} on failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{FILE*}{PyFile_AsFile}{PyFileObject *p}
-Returns the file object associated with \var{p} as a \ctype{FILE*}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyFile_GetLine}{PyObject *p, int n}
-Equivalent to \code{\var{p}.readline(\optional{\var{n}})}, this
-function reads one line from the object \var{p}.  \var{p} may be a
-file object or any object with a \method{readline()} method.  If
-\var{n} is \code{0}, exactly one line is read, regardless of the
-length of the line.  If \var{n} is greater than \code{0}, no more than 
-\var{n} bytes will be read from the file; a partial line can be
-returned.  In both cases, an empty string is returned if the end of
-the file is reached immediately.  If \var{n} is less than \code{0},
-however, one line is read regardless of length, but
-\exception{EOFError} is raised if the end of the file is reached
-immediately.
-\withsubitem{(built-in exception)}{\ttindex{EOFError}}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyFile_Name}{PyObject *p}
-Returns the name of the file specified by \var{p} as a string object.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyFile_SetBufSize}{PyFileObject *p, int n}
-Available on systems with \cfunction{setvbuf()}\ttindex{setvbuf()}
-only.  This should only be called immediately after file object
-creation.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyFile_SoftSpace}{PyObject *p, int newflag}
-This function exists for internal use by the interpreter.
-Sets the \member{softspace} attribute of \var{p} to \var{newflag} and
-\withsubitem{(file attribute)}{\ttindex{softspace}}returns the
-previous value.  \var{p} does not have to be a file object
-for this function to work properly; any object is supported (thought
-its only interesting if the \member{softspace} attribute can be set).
-This function clears any errors, and will return \code{0} as the
-previous value if the attribute either does not exist or if there were
-errors in retrieving it.  There is no way to detect errors from this
-function, but doing so should not be needed.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyFile_WriteObject}{PyObject *obj, PyFileObject *p,
-                                           int flags}
-Writes object \var{obj} to file object \var{p}.  The only supported
-flag for \var{flags} is \constant{Py_PRINT_RAW}\ttindex{Py_PRINT_RAW};
-if given, the \function{str()} of the object is written instead of the 
-\function{repr()}.  Returns \code{0} on success or \code{-1} on
-failure; the appropriate exception will be set.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyFile_WriteString}{char *s, PyFileObject *p}
-Writes string \var{s} to file object \var{p}.  Returns \code{0} on
-success or \code{-1} on failure; the appropriate exception will be
-set.
-\end{cfuncdesc}
-
-
-\subsection{Instance Objects \label{instanceObjects}}
-
-\obindex{instance}
-There are very few functions specific to instance objects.
-
-\begin{cvardesc}{PyTypeObject}{PyInstance_Type}
-  Type object for class instances.
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyInstance_Check}{PyObject *obj}
-  Returns true if \var{obj} is an instance.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyInstance_New}{PyObject *class,
-                                             PyObject *arg,
-                                             PyObject *kw}
-  Create a new instance of a specific class.  The parameters \var{arg}
-  and \var{kw} are used as the positional and keyword parameters to
-  the object's constructor.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyInstance_NewRaw}{PyObject *class,
-                                                PyObject *dict}
-  Create a new instance of a specific class without calling it's
-  constructor.  \var{class} is the class of new object.  The
-  \var{dict} parameter will be used as the object's \member{__dict__};
-  if \NULL, a new dictionary will be created for the instance.
-\end{cfuncdesc}
-
-
-\subsection{Method Objects \label{method-objects}}
-
-\obindex{method}
-There are some useful functions that are useful for working with
-method objects.
-
-\begin{cvardesc}{PyTypeObject}{PyMethod_Type}
-  This instance of \ctype{PyTypeObject} represents the Python method
-  type.  This is exposed to Python programs as \code{types.MethodType}.
-  \withsubitem{(in module types)}{\ttindex{MethodType}}
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyMethod_Check}{PyObject *o}
-  Return true if \var{o} is a method object (has type
-  \cdata{PyMethod_Type}).  The parameter must not be \NULL.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyMethod_New}{PyObject *func.
-                                           PyObject *self, PyObject *class}
-  Return a new method object, with \var{func} being any callable
-  object; this is the function that will be called when the method is
-  called.  If this method should be bound to an instance, \var{self}
-  should be the instance and \var{class} should be the class of
-  \var{self}, otherwise \var{self} should be \NULL{} and \var{class}
-  should be the class which provides the unbound method..
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyMethod_Class}{PyObject *meth}
-  Return the class object from which the method \var{meth} was
-  created; if this was created from an instance, it will be the class
-  of the instance.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyMethod_GET_CLASS}{PyObject *meth}
-  Macro version of \cfunction{PyMethod_Class()} which avoids error
-  checking.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyMethod_Function}{PyObject *meth}
-  Return the function object associated with the method \var{meth}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyMethod_GET_FUNCTION}{PyObject *meth}
-  Macro version of \cfunction{PyMethod_Function()} which avoids error
-  checking.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyMethod_Self}{PyObject *meth}
-  Return the instance associated with the method \var{meth} if it is
-  bound, otherwise return \NULL.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyMethod_GET_SELF}{PyObject *meth}
-  Macro version of \cfunction{PyMethod_Self()} which avoids error
-  checking.
-\end{cfuncdesc}
-
-
-\subsection{Module Objects \label{moduleObjects}}
-
-\obindex{module}
-There are only a few functions special to module objects.
-
-\begin{cvardesc}{PyTypeObject}{PyModule_Type}
-This instance of \ctype{PyTypeObject} represents the Python module
-type.  This is exposed to Python programs as \code{types.ModuleType}.
-\withsubitem{(in module types)}{\ttindex{ModuleType}}
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyModule_Check}{PyObject *p}
-Returns true if \var{p} is a module object, or a subtype of a
-module object.
-\versionchanged[Allowed subtypes to be accepted]{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyModule_CheckExact}{PyObject *p}
-Returns true if \var{p} is a module object, but not a subtype of
-\cdata{PyModule_Type}.
-\versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyModule_New}{char *name}
-Return a new module object with the \member{__name__} attribute set to
-\var{name}.  Only the module's \member{__doc__} and
-\member{__name__} attributes are filled in; the caller is responsible
-for providing a \member{__file__} attribute.
-\withsubitem{(module attribute)}{
-  \ttindex{__name__}\ttindex{__doc__}\ttindex{__file__}}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyModule_GetDict}{PyObject *module}
-Return the dictionary object that implements \var{module}'s namespace; 
-this object is the same as the \member{__dict__} attribute of the
-module object.  This function never fails.
-\withsubitem{(module attribute)}{\ttindex{__dict__}}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{char*}{PyModule_GetName}{PyObject *module}
-Return \var{module}'s \member{__name__} value.  If the module does not 
-provide one, or if it is not a string, \exception{SystemError} is
-raised and \NULL{} is returned.
-\withsubitem{(module attribute)}{\ttindex{__name__}}
-\withsubitem{(built-in exception)}{\ttindex{SystemError}}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{char*}{PyModule_GetFilename}{PyObject *module}
-Return the name of the file from which \var{module} was loaded using
-\var{module}'s \member{__file__} attribute.  If this is not defined,
-or if it is not a string, raise \exception{SystemError} and return
-\NULL.
-\withsubitem{(module attribute)}{\ttindex{__file__}}
-\withsubitem{(built-in exception)}{\ttindex{SystemError}}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyModule_AddObject}{PyObject *module,
-                                           char *name, PyObject *value}
-Add an object to \var{module} as \var{name}.  This is a convenience
-function which can be used from the module's initialization function.
-This steals a reference to \var{value}.  Returns \code{-1} on error,
-\code{0} on success.
-\versionadded{2.0}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyModule_AddIntConstant}{PyObject *module,
-                                                char *name, int value}
-Add an integer constant to \var{module} as \var{name}.  This convenience
-function can be used from the module's initialization function.
-Returns \code{-1} on error, \code{0} on success.
-\versionadded{2.0}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyModule_AddStringConstant}{PyObject *module,
-                                                   char *name, char *value}
-Add a string constant to \var{module} as \var{name}.  This convenience
-function can be used from the module's initialization function.  The
-string \var{value} must be null-terminated.  Returns \code{-1} on
-error, \code{0} on success.
-\versionadded{2.0}
-\end{cfuncdesc}
-
-
-\subsection{Iterator Objects \label{iterator-objects}}
-
-Python provides two general-purpose iterator objects.  The first, a
-sequence iterator, works with an arbitrary sequence supporting the
-\method{__getitem__()} method.  The second works with a callable
-object and a sentinel value, calling the callable for each item in the
-sequence, and ending the iteration when the sentinel value is
-returned.
-
-\begin{cvardesc}{PyTypeObject}{PySeqIter_Type}
-  Type object for iterator objects returned by
-  \cfunction{PySeqIter_New()} and the one-argument form of the
-  \function{iter()} built-in function for built-in sequence types.
-  \versionadded{2.2}
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PySeqIter_Check}{op}
-  Return true if the type of \var{op} is \cdata{PySeqIter_Type}.
-  \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PySeqIter_New}{PyObject *seq}
-  Return an iterator that works with a general sequence object,
-  \var{seq}.  The iteration ends when the sequence raises
-  \exception{IndexError} for the subscripting operation.
-  \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cvardesc}{PyTypeObject}{PyCallIter_Type}
-  Type object for iterator objects returned by
-  \cfunction{PyCallIter_New()} and the two-argument form of the
-  \function{iter()} built-in function.
-  \versionadded{2.2}
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyCallIter_Check}{op}
-  Return true if the type of \var{op} is \cdata{PyCallIter_Type}.
-  \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyCallIter_New}{PyObject *callable,
-                                             PyObject *sentinel}
-  Return a new iterator.  The first parameter, \var{callable}, can be
-  any Python callable object that can be called with no parameters;
-  each call to it should return the next item in the iteration.  When
-  \var{callable} returns a value equal to \var{sentinel}, the
-  iteration will be terminated.
-  \versionadded{2.2}
-\end{cfuncdesc}
-
-
-\subsection{Descriptor Objects \label{descriptor-objects}}
-
-\begin{cvardesc}{PyTypeObject}{PyProperty_Type}
-  The type object for a descriptor.
-  \versionadded{2.2}
-\end{cvardesc}
-
-\begin{cfuncdesc}{PyObject*}{PyDescr_NewGetSet}{PyTypeObject *type,
-					        PyGetSetDef *getset}
-  \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyDescr_NewMember}{PyTypeObject *type,
-					        PyMemberDef *meth}
-  \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyDescr_NewMethod}{PyTypeObject *type,
-                                                PyMethodDef *meth}
-  \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyDescr_NewWrapper}{PyTypeObject *type,
-						 struct wrapperbase *wrapper,
-                                                 void *wrapped}
-  \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyDescr_IsData}{PyObject *descr}
-  Returns true if the descriptor objects \var{descr} describes a data
-  attribute, or false if it describes a method.  \var{descr} must be a
-  descriptor object; there is no error checking.
-  \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyWrapper_New}{PyObject *, PyObject *}
-  \versionadded{2.2}
-\end{cfuncdesc}
-
-
-\subsection{Slice Objects \label{slice-objects}}
-
-\begin{cvardesc}{PyTypeObject}{PySlice_Type}
-  The type object for slice objects.  This is the same as
-  \code{types.SliceType}.
-  \withsubitem{(in module types)}{\ttindex{SliceType}}
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PySlice_Check}{PyObject *ob}
-  Returns true if \var{ob} is a slice object; \var{ob} must not be
-  \NULL.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PySlice_New}{PyObject *start, PyObject *stop,
-                                          PyObject *step}
-  Return a new slice object with the given values.  The \var{start},
-  \var{stop}, and \var{step} parameters are used as the values of the
-  slice object attributes of the same names.  Any of the values may be
-  \NULL, in which case the \code{None} will be used for the
-  corresponding attribute.  Returns \NULL{} if the new object could
-  not be allocated.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PySlice_GetIndices}{PySliceObject *slice, int length,
-                                           int *start, int *stop, int *step}
-\end{cfuncdesc}
-
-
-\subsection{Weak Reference Objects \label{weakref-objects}}
-
-Python supports \emph{weak references} as first-class objects.  There
-are two specific object types which directly implement weak
-references.  The first is a simple reference object, and the second
-acts as a proxy for the original object as much as it can.
-
-\begin{cfuncdesc}{int}{PyWeakref_Check}{ob}
-  Return true if \var{ob} is either a reference or proxy object.
-  \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyWeakref_CheckRef}{ob}
-  Return true if \var{ob} is a reference object.
-  \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyWeakref_CheckProxy}{ob}
-  Return true if \var{ob} is a proxy object.
-  \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyWeakref_NewRef}{PyObject *ob,
-                                               PyObject *callback}
-  Return a weak reference object for the object \var{ob}.  This will
-  always return a new reference, but is not guaranteed to create a new
-  object; an existing reference object may be returned.  The second
-  parameter, \var{callback}, can be a callable object that receives
-  notification when \var{ob} is garbage collected; it should accept a
-  single paramter, which will be the weak reference object itself.
-  \var{callback} may also be \code{None} or \NULL.  If \var{ob}
-  is not a weakly-referencable object, or if \var{callback} is not
-  callable, \code{None}, or \NULL, this will return \NULL{} and
-  raise \exception{TypeError}.
-  \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyWeakref_NewProxy}{PyObject *ob,
-                                                 PyObject *callback}
-  Return a weak reference proxy object for the object \var{ob}.  This
-  will always return a new reference, but is not guaranteed to create
-  a new object; an existing proxy object may be returned.  The second
-  parameter, \var{callback}, can be a callable object that receives
-  notification when \var{ob} is garbage collected; it should accept a
-  single paramter, which will be the weak reference object itself.
-  \var{callback} may also be \code{None} or \NULL.  If \var{ob} is not
-  a weakly-referencable object, or if \var{callback} is not callable,
-  \code{None}, or \NULL, this will return \NULL{} and raise
-  \exception{TypeError}.
-  \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyWeakref_GetObject}{PyObject *ref}
-  Returns the referenced object from a weak reference, \var{ref}.  If
-  the referent is no longer live, returns \NULL.
-  \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyWeakref_GET_OBJECT}{PyObject *ref}
-  Similar to \cfunction{PyWeakref_GetObject()}, but implemented as a
-  macro that does no error checking.
-  \versionadded{2.2}
-\end{cfuncdesc}
-
-
-\subsection{CObjects \label{cObjects}}
-
-\obindex{CObject}
-Refer to \emph{Extending and Embedding the Python Interpreter},
-section 1.12 (``Providing a C API for an Extension Module), for more 
-information on using these objects.
-
-
-\begin{ctypedesc}{PyCObject}
-This subtype of \ctype{PyObject} represents an opaque value, useful for
-C extension modules who need to pass an opaque value (as a
-\ctype{void*} pointer) through Python code to other C code.  It is
-often used to make a C function pointer defined in one module
-available to other modules, so the regular import mechanism can be
-used to access C APIs defined in dynamically loaded modules.
-\end{ctypedesc}
-
-\begin{cfuncdesc}{int}{PyCObject_Check}{PyObject *p}
-Returns true if its argument is a \ctype{PyCObject}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyCObject_FromVoidPtr}{void* cobj, 
-	void (*destr)(void *)}
-Creates a \ctype{PyCObject} from the \code{void *}\var{cobj}.  The
-\var{destr} function will be called when the object is reclaimed, unless
-it is \NULL.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyCObject_FromVoidPtrAndDesc}{void* cobj,
-	void* desc, void (*destr)(void *, void *) }
-Creates a \ctype{PyCObject} from the \ctype{void *}\var{cobj}.  The
-\var{destr} function will be called when the object is reclaimed.  The
-\var{desc} argument can be used to pass extra callback data for the
-destructor function.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void*}{PyCObject_AsVoidPtr}{PyObject* self}
-Returns the object \ctype{void *} that the
-\ctype{PyCObject} \var{self} was created with.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void*}{PyCObject_GetDesc}{PyObject* self}
-Returns the description \ctype{void *} that the
-\ctype{PyCObject} \var{self} was created with.
-\end{cfuncdesc}
-
-
-\chapter{Initialization, Finalization, and Threads
-         \label{initialization}}
-
-\begin{cfuncdesc}{void}{Py_Initialize}{}
-Initialize the Python interpreter.  In an application embedding 
-Python, this should be called before using any other Python/C API 
-functions; with the exception of
-\cfunction{Py_SetProgramName()}\ttindex{Py_SetProgramName()},
-\cfunction{PyEval_InitThreads()}\ttindex{PyEval_InitThreads()},
-\cfunction{PyEval_ReleaseLock()}\ttindex{PyEval_ReleaseLock()},
-and \cfunction{PyEval_AcquireLock()}\ttindex{PyEval_AcquireLock()}.
-This initializes the table of loaded modules (\code{sys.modules}), and
-\withsubitem{(in module sys)}{\ttindex{modules}\ttindex{path}}creates the
-fundamental modules \module{__builtin__}\refbimodindex{__builtin__},
-\module{__main__}\refbimodindex{__main__} and
-\module{sys}\refbimodindex{sys}.  It also initializes the module
-search\indexiii{module}{search}{path} path (\code{sys.path}).
-It does not set \code{sys.argv}; use
-\cfunction{PySys_SetArgv()}\ttindex{PySys_SetArgv()} for that.  This
-is a no-op when called for a second time (without calling
-\cfunction{Py_Finalize()}\ttindex{Py_Finalize()} first).  There is no
-return value; it is a fatal error if the initialization fails.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{Py_IsInitialized}{}
-Return true (nonzero) when the Python interpreter has been
-initialized, false (zero) if not.  After \cfunction{Py_Finalize()} is
-called, this returns false until \cfunction{Py_Initialize()} is called
-again.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{Py_Finalize}{}
-Undo all initializations made by \cfunction{Py_Initialize()} and
-subsequent use of Python/C API functions, and destroy all
-sub-interpreters (see \cfunction{Py_NewInterpreter()} below) that were
-created and not yet destroyed since the last call to
-\cfunction{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 \cfunction{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 
-application might want to restart Python without having to restart the 
-application itself.  An application that has loaded the Python 
-interpreter from a dynamically loadable library (or DLL) might want to 
-free all memory allocated by Python before unloading the DLL. During a 
-hunt for memory leaks in an application a developer might want to free 
-all memory allocated by Python before exiting from the application.
-
-\strong{Bugs and caveats:} The destruction of modules and objects in 
-modules is done in random order; this may cause destructors 
-(\method{__del__()} methods) to fail when they depend on other objects 
-(even functions) or modules.  Dynamically loaded extension modules 
-loaded by Python are not unloaded.  Small amounts of memory allocated 
-by the Python interpreter may not be freed (if you find a leak, please 
-report it).  Memory tied up in circular references between objects is 
-not freed.  Some memory allocated by extension modules may not be 
-freed.  Some extension may not work properly if their initialization 
-routine is called more than once; this can happen if an applcation 
-calls \cfunction{Py_Initialize()} and \cfunction{Py_Finalize()} more
-than once.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyThreadState*}{Py_NewInterpreter}{}
-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
-modules, including the fundamental modules
-\module{__builtin__}\refbimodindex{__builtin__},
-\module{__main__}\refbimodindex{__main__} and
-\module{sys}\refbimodindex{sys}.  The table of loaded modules
-(\code{sys.modules}) and the module search path (\code{sys.path}) are
-also separate.  The new environment has no \code{sys.argv} variable.
-It has new standard I/O stream file objects \code{sys.stdin},
-\code{sys.stdout} and \code{sys.stderr} (however these refer to the
-same underlying \ctype{FILE} structures in the C library).
-\withsubitem{(in module sys)}{
-  \ttindex{stdout}\ttindex{stderr}\ttindex{stdin}}
-
-The return value points to the first thread state created in the new 
-sub-interpreter.  This thread state is made the current thread state.  
-Note that no actual thread is created; see the discussion of thread 
-states below.  If creation of the new interpreter is unsuccessful, 
-\NULL{} is returned; no exception is set since the exception state 
-is stored in the current thread state and there may not be a current 
-thread state.  (Like all other Python/C API functions, the global 
-interpreter lock must be held before calling this function and is 
-still held when it returns; however, unlike most other Python/C API 
-functions, there needn't be a current thread state on entry.)
-
-Extension modules are shared between (sub-)interpreters as follows: 
-the first time a particular extension is imported, it is initialized 
-normally, and a (shallow) copy of its module's dictionary is 
-squirreled away.  When the same extension is imported by another 
-(sub-)interpreter, a new module is initialized and filled with the 
-contents of this copy; the extension's \code{init} function is not
-called.  Note that this is different from what happens when an
-extension is imported after the interpreter has been completely
-re-initialized by calling
-\cfunction{Py_Finalize()}\ttindex{Py_Finalize()} and
-\cfunction{Py_Initialize()}\ttindex{Py_Initialize()}; in that case,
-the extension's \code{init\var{module}} function \emph{is} called
-again.
-
-\strong{Bugs and caveats:} Because sub-interpreters (and the main 
-interpreter) are part of the same process, the insulation between them 
-isn't perfect --- for example, using low-level file operations like 
-\withsubitem{(in module os)}{\ttindex{close()}}
-\function{os.close()} they can (accidentally or maliciously) affect each 
-other's open files.  Because of the way extensions are shared between 
-(sub-)interpreters, some extensions may not work properly; this is 
-especially likely when the extension makes use of (static) global 
-variables, or when the extension manipulates its module's dictionary 
-after its initialization.  It is possible to insert objects created in 
-one sub-interpreter into a namespace of another sub-interpreter; this 
-should be done with great care to avoid sharing user-defined 
-functions, methods, instances or classes between sub-interpreters, 
-since import operations executed by such objects may affect the 
-wrong (sub-)interpreter's dictionary of loaded modules.  (XXX This is 
-a hard-to-fix bug that will be addressed in a future release.)
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{Py_EndInterpreter}{PyThreadState *tstate}
-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 
-thread state is \NULL{}.  All thread states associated with this 
-interpreted are destroyed.  (The global interpreter lock must be held 
-before calling this function and is still held when it returns.)  
-\cfunction{Py_Finalize()}\ttindex{Py_Finalize()} will destroy all
-sub-interpreters that haven't been explicitly destroyed at that point.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{Py_SetProgramName}{char *name}
-This function should be called before
-\cfunction{Py_Initialize()}\ttindex{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
-\cfunction{main()}\ttindex{main()} function of the program.  This is
-used by \cfunction{Py_GetPath()}\ttindex{Py_GetPath()} and some other  
-functions below to find the Python run-time libraries relative to the 
-interpreter executable.  The default value is \code{'python'}.  The 
-argument should point to a zero-terminated character string in static 
-storage whose contents will not change for the duration of the 
-program's execution.  No code in the Python interpreter will change 
-the contents of this storage.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{char*}{Py_GetProgramName}{}
-Return the program name set with
-\cfunction{Py_SetProgramName()}\ttindex{Py_SetProgramName()}, or the
-default.  The returned string points into static storage; the caller 
-should not modify its value.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{char*}{Py_GetPrefix}{}
-Return the \emph{prefix} for installed platform-independent files.  This 
-is derived through a number of complicated rules from the program name 
-set with \cfunction{Py_SetProgramName()} and some environment variables; 
-for example, if the program name is \code{'/usr/local/bin/python'}, 
-the prefix is \code{'/usr/local'}.  The returned string points into 
-static storage; the caller should not modify its value.  This 
-corresponds to the \makevar{prefix} variable in the top-level 
-\file{Makefile} and the \longprogramopt{prefix} argument to the 
-\program{configure} script at build time.  The value is available to 
-Python code as \code{sys.prefix}.  It is only useful on \UNIX{}.  See 
-also the next function.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{char*}{Py_GetExecPrefix}{}
-Return the \emph{exec-prefix} for installed platform-\emph{de}pendent 
-files.  This is derived through a number of complicated rules from the 
-program name set with \cfunction{Py_SetProgramName()} and some environment 
-variables; for example, if the program name is 
-\code{'/usr/local/bin/python'}, the exec-prefix is 
-\code{'/usr/local'}.  The returned string points into static storage; 
-the caller should not modify its value.  This corresponds to the 
-\makevar{exec_prefix} variable in the top-level \file{Makefile} and the 
-\longprogramopt{exec-prefix} argument to the
-\program{configure} script at build  time.  The value is available to
-Python code as \code{sys.exec_prefix}.  It is only useful on \UNIX{}.
-
-Background: The exec-prefix differs from the prefix when platform 
-dependent files (such as executables and shared libraries) are 
-installed in a different directory tree.  In a typical installation, 
-platform dependent files may be installed in the 
-\file{/usr/local/plat} subtree while platform independent may be 
-installed in \file{/usr/local}.
-
-Generally speaking, a platform is a combination of hardware and 
-software families, e.g.  Sparc machines running the Solaris 2.x 
-operating system are considered the same platform, but Intel machines 
-running Solaris 2.x are another platform, and Intel machines running 
-Linux are yet another platform.  Different major revisions of the same 
-operating system generally also form different platforms.  Non-\UNIX{} 
-operating systems are a different story; the installation strategies 
-on those systems are so different that the prefix and exec-prefix are 
-meaningless, and set to the empty string.  Note that compiled Python 
-bytecode files are platform independent (but not independent from the 
-Python version by which they were compiled!).
-
-System administrators will know how to configure the \program{mount} or 
-\program{automount} programs to share \file{/usr/local} between platforms 
-while having \file{/usr/local/plat} be a different filesystem for each 
-platform.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{char*}{Py_GetProgramFullPath}{}
-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
-\cfunction{Py_SetProgramName()}\ttindex{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}.
-\withsubitem{(in module sys)}{\ttindex{executable}}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{char*}{Py_GetPath}{}
-\indexiii{module}{search}{path}
-Return the default module search path; this is computed from the 
-program name (set by \cfunction{Py_SetProgramName()} above) and some 
-environment variables.  The returned string consists of a series of 
-directory names separated by a platform dependent delimiter character.  
-The delimiter character is \character{:} on \UNIX{}, \character{;} on
-DOS/Windows, and \character{\e n} (the \ASCII{} newline character) on
-Macintosh.  The returned string points into static storage; the caller
-should not modify its value.  The value is available to Python code 
-as the list \code{sys.path}\withsubitem{(in module sys)}{\ttindex{path}},
-which may be modified to change the future search path for loaded
-modules.
-
-% XXX should give the exact rules
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{const char*}{Py_GetVersion}{}
-Return the version of this Python interpreter.  This is a string that 
-looks something like
-
-\begin{verbatim}
-"1.5 (#67, Dec 31 1997, 22:34:28) [GCC 2.7.2.2]"
-\end{verbatim}
-
-The first word (up to the first space character) is the current Python 
-version; the first three characters are the major and minor version 
-separated by a period.  The returned string points into static storage; 
-the caller should not modify its value.  The value is available to 
-Python code as the list \code{sys.version}.
-\withsubitem{(in module sys)}{\ttindex{version}}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{const char*}{Py_GetPlatform}{}
-Return the platform identifier for the current platform.  On \UNIX{}, 
-this is formed from the ``official'' name of the operating system, 
-converted to lower case, followed by the major revision number; e.g., 
-for Solaris 2.x, which is also known as SunOS 5.x, the value is 
-\code{'sunos5'}.  On Macintosh, it is \code{'mac'}.  On Windows, it 
-is \code{'win'}.  The returned string points into static storage; 
-the caller should not modify its value.  The value is available to 
-Python code as \code{sys.platform}.
-\withsubitem{(in module sys)}{\ttindex{platform}}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{const char*}{Py_GetCopyright}{}
-Return the official copyright string for the current Python version, 
-for example
-
-\code{'Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam'}
-
-The returned string points into static storage; the caller should not 
-modify its value.  The value is available to Python code as the list 
-\code{sys.copyright}.
-\withsubitem{(in module sys)}{\ttindex{copyright}}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{const char*}{Py_GetCompiler}{}
-Return an indication of the compiler used to build the current Python 
-version, in square brackets, for example:
-
-\begin{verbatim}
-"[GCC 2.7.2.2]"
-\end{verbatim}
-
-The returned string points into static storage; the caller should not 
-modify its value.  The value is available to Python code as part of 
-the variable \code{sys.version}.
-\withsubitem{(in module sys)}{\ttindex{version}}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{const char*}{Py_GetBuildInfo}{}
-Return information about the sequence number and build date and time 
-of the current Python interpreter instance, for example
-
-\begin{verbatim}
-"#67, Aug  1 1997, 22:34:28"
-\end{verbatim}
-
-The returned string points into static storage; the caller should not 
-modify its value.  The value is available to Python code as part of 
-the variable \code{sys.version}.
-\withsubitem{(in module sys)}{\ttindex{version}}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PySys_SetArgv}{int argc, char **argv}
-Set \code{sys.argv} based on \var{argc} and \var{argv}.  These
-parameters are similar to those passed to the program's
-\cfunction{main()}\ttindex{main()} function with the difference that
-the first entry should refer to the script file to be executed rather
-than the executable hosting the Python interpreter.  If there isn't a
-script that will be run, the first entry in \var{argv} can be an empty
-string.  If this function fails to initialize \code{sys.argv}, a fatal 
-condition is signalled using
-\cfunction{Py_FatalError()}\ttindex{Py_FatalError()}.
-\withsubitem{(in module sys)}{\ttindex{argv}}
-% XXX impl. doesn't seem consistent in allowing 0/NULL for the params; 
-% check w/ Guido.
-\end{cfuncdesc}
-
-% XXX Other PySys thingies (doesn't really belong in this chapter)
-
-\section{Thread State and the Global Interpreter Lock
-         \label{threads}}
-
-\index{global interpreter lock}
-\index{interpreter lock}
-\index{lock, interpreter}
-
-The Python interpreter is not fully thread safe.  In order to support
-multi-threaded Python programs, there's a global lock that must be
-held by the current thread before it can safely access Python objects.
-Without the lock, even the simplest operations could cause problems in
-a multi-threaded program: for example, when two threads simultaneously
-increment the reference count of the same object, the reference count
-could end up being incremented only once instead of twice.
-
-Therefore, the rule exists that only the thread that has acquired the
-global interpreter lock may operate on Python objects or call Python/C
-API functions.  In order to support multi-threaded Python programs,
-the interpreter regularly releases and reacquires the lock --- by
-default, every ten bytecode instructions (this can be changed with
-\withsubitem{(in module sys)}{\ttindex{setcheckinterval()}}
-\function{sys.setcheckinterval()}).  The lock is also released and
-reacquired around potentially blocking I/O operations like reading or
-writing a file, so that other threads can run while the thread that
-requests the I/O is waiting for the I/O operation to complete.
-
-The Python interpreter needs to keep some bookkeeping information
-separate per thread --- for this it uses a data structure called
-\ctype{PyThreadState}\ttindex{PyThreadState}.  This is new in Python
-1.5; in earlier versions, such state was stored in global variables,
-and switching threads could cause problems.  In particular, exception
-handling is now thread safe, when the application uses
-\withsubitem{(in module sys)}{\ttindex{exc_info()}}
-\function{sys.exc_info()} to access the exception last raised in the
-current thread.
-
-There's one global variable left, however: the pointer to the current
-\ctype{PyThreadState}\ttindex{PyThreadState} structure.  While most
-thread packages have a way to store ``per-thread global data,''
-Python's internal platform independent thread abstraction doesn't
-support this yet.  Therefore, the current thread state must be
-manipulated explicitly.
-
-This is easy enough in most cases.  Most code manipulating the global
-interpreter lock has the following simple structure:
-
-\begin{verbatim}
-Save the thread state in a local variable.
-Release the interpreter lock.
-...Do some blocking I/O operation...
-Reacquire the interpreter lock.
-Restore the thread state from the local variable.
-\end{verbatim}
-
-This is so common that a pair of macros exists to simplify it:
-
-\begin{verbatim}
-Py_BEGIN_ALLOW_THREADS
-...Do some blocking I/O operation...
-Py_END_ALLOW_THREADS
-\end{verbatim}
-
-The \code{Py_BEGIN_ALLOW_THREADS}\ttindex{Py_BEGIN_ALLOW_THREADS} macro
-opens a new block and declares a hidden local variable; the
-\code{Py_END_ALLOW_THREADS}\ttindex{Py_END_ALLOW_THREADS} macro closes 
-the block.  Another advantage of using these two macros is that when
-Python is compiled without thread support, they are defined empty,
-thus saving the thread state and lock manipulations.
-
-When thread support is enabled, the block above expands to the
-following code:
-
-\begin{verbatim}
-    PyThreadState *_save;
-
-    _save = PyEval_SaveThread();
-    ...Do some blocking I/O operation...
-    PyEval_RestoreThread(_save);
-\end{verbatim}
-
-Using even lower level primitives, we can get roughly the same effect
-as follows:
-
-\begin{verbatim}
-    PyThreadState *_save;
-
-    _save = PyThreadState_Swap(NULL);
-    PyEval_ReleaseLock();
-    ...Do some blocking I/O operation...
-    PyEval_AcquireLock();
-    PyThreadState_Swap(_save);
-\end{verbatim}
-
-There are some subtle differences; in particular,
-\cfunction{PyEval_RestoreThread()}\ttindex{PyEval_RestoreThread()} saves
-and restores the value of the  global variable
-\cdata{errno}\ttindex{errno}, since the lock manipulation does not
-guarantee that \cdata{errno} is left alone.  Also, when thread support
-is disabled,
-\cfunction{PyEval_SaveThread()}\ttindex{PyEval_SaveThread()} and
-\cfunction{PyEval_RestoreThread()} don't manipulate the lock; in this
-case, \cfunction{PyEval_ReleaseLock()}\ttindex{PyEval_ReleaseLock()} and
-\cfunction{PyEval_AcquireLock()}\ttindex{PyEval_AcquireLock()} are not
-available.  This is done so that dynamically loaded extensions
-compiled with thread support enabled can be loaded by an interpreter
-that was compiled with disabled thread support.
-
-The global interpreter lock is used to protect the pointer to the
-current thread state.  When releasing the lock and saving the thread
-state, the current thread state pointer must be retrieved before the
-lock is released (since another thread could immediately acquire the
-lock and store its own thread state in the global variable).
-Conversely, when acquiring the lock and restoring the thread state,
-the lock must be acquired before storing the thread state pointer.
-
-Why am I going on with so much detail about this?  Because when
-threads are created from C, they don't have the global interpreter
-lock, nor is there a thread state data structure for them.  Such
-threads must bootstrap themselves into existence, by first creating a
-thread state data structure, then acquiring the lock, and finally
-storing their thread state pointer, before they can start using the
-Python/C API.  When they are done, they should reset the thread state
-pointer, release the lock, and finally free their thread state data
-structure.
-
-When creating a thread data structure, you need to provide an
-interpreter state data structure.  The interpreter state data
-structure hold global data that is shared by all threads in an
-interpreter, for example the module administration
-(\code{sys.modules}).  Depending on your needs, you can either create
-a new interpreter state data structure, or share the interpreter state
-data structure used by the Python main thread (to access the latter,
-you must obtain the thread state and access its \member{interp} member;
-this must be done by a thread that is created by Python or by the main
-thread after Python is initialized).
-
-
-\begin{ctypedesc}{PyInterpreterState}
-This data structure represents the state shared by a number of
-cooperating threads.  Threads belonging to the same interpreter
-share their module administration and a few other internal items.
-There are no public members in this structure.
-
-Threads belonging to different interpreters initially share nothing,
-except process state like available memory, open file descriptors and
-such.  The global interpreter lock is also shared by all threads,
-regardless of to which interpreter they belong.
-\end{ctypedesc}
-
-\begin{ctypedesc}{PyThreadState}
-This data structure represents the state of a single thread.  The only
-public data member is \ctype{PyInterpreterState *}\member{interp},
-which points to this thread's interpreter state.
-\end{ctypedesc}
-
-\begin{cfuncdesc}{void}{PyEval_InitThreads}{}
-Initialize and acquire the global interpreter lock.  It should be
-called in the main thread before creating a second thread or engaging
-in any other thread operations such as
-\cfunction{PyEval_ReleaseLock()}\ttindex{PyEval_ReleaseLock()} or
-\code{PyEval_ReleaseThread(\var{tstate})}\ttindex{PyEval_ReleaseThread()}.
-It is not needed before calling
-\cfunction{PyEval_SaveThread()}\ttindex{PyEval_SaveThread()} or
-\cfunction{PyEval_RestoreThread()}\ttindex{PyEval_RestoreThread()}.
-
-This is a no-op when called for a second time.  It is safe to call
-this function before calling
-\cfunction{Py_Initialize()}\ttindex{Py_Initialize()}.
-
-When only the main thread exists, no lock operations are needed.  This
-is a common situation (most Python programs do not use threads), and
-the lock operations slow the interpreter down a bit.  Therefore, the
-lock is not created initially.  This situation is equivalent to having
-acquired the lock: when there is only a single thread, all object
-accesses are safe.  Therefore, when this function initializes the
-lock, it also acquires it.  Before the Python
-\module{thread}\refbimodindex{thread} module creates a new thread,
-knowing that either it has the lock or the lock hasn't been created
-yet, it calls \cfunction{PyEval_InitThreads()}.  When this call
-returns, it is guaranteed that the lock has been created and that it
-has acquired it.
-
-It is \strong{not} safe to call this function when it is unknown which
-thread (if any) currently has the global interpreter lock.
-
-This function is not available when thread support is disabled at
-compile time.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyEval_AcquireLock}{}
-Acquire the global interpreter lock.  The lock must have been created
-earlier.  If this thread already has the lock, a deadlock ensues.
-This function is not available when thread support is disabled at
-compile time.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyEval_ReleaseLock}{}
-Release the global interpreter lock.  The lock must have been created
-earlier.  This function is not available when thread support is
-disabled at compile time.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyEval_AcquireThread}{PyThreadState *tstate}
-Acquire the global interpreter lock and then set the current thread
-state to \var{tstate}, which should not be \NULL{}.  The lock must
-have been created earlier.  If this thread already has the lock,
-deadlock ensues.  This function is not available when thread support
-is disabled at compile time.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyEval_ReleaseThread}{PyThreadState *tstate}
-Reset the current thread state to \NULL{} and release the global
-interpreter lock.  The lock must have been created earlier and must be
-held by the current thread.  The \var{tstate} argument, which must not
-be \NULL{}, is only used to check that it represents the current
-thread state --- if it isn't, a fatal error is reported.  This
-function is not available when thread support is disabled at compile
-time.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyThreadState*}{PyEval_SaveThread}{}
-Release the interpreter lock (if it has been created and thread
-support is enabled) and reset the thread state to \NULL{},
-returning the previous thread state (which is not \NULL{}).  If
-the lock has been created, the current thread must have acquired it.
-(This function is available even when thread support is disabled at
-compile time.)
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyEval_RestoreThread}{PyThreadState *tstate}
-Acquire the interpreter lock (if it has been created and thread
-support is enabled) and set the thread state to \var{tstate}, which
-must not be \NULL{}.  If the lock has been created, the current
-thread must not have acquired it, otherwise deadlock ensues.  (This
-function is available even when thread support is disabled at compile
-time.)
-\end{cfuncdesc}
-
-The following macros are normally used without a trailing semicolon;
-look for example usage in the Python source distribution.
-
-\begin{csimplemacrodesc}{Py_BEGIN_ALLOW_THREADS}
-This macro expands to
-\samp{\{ PyThreadState *_save; _save = PyEval_SaveThread();}.
-Note that it contains an opening brace; it must be matched with a
-following \code{Py_END_ALLOW_THREADS} macro.  See above for further
-discussion of this macro.  It is a no-op when thread support is
-disabled at compile time.
-\end{csimplemacrodesc}
-
-\begin{csimplemacrodesc}{Py_END_ALLOW_THREADS}
-This macro expands to
-\samp{PyEval_RestoreThread(_save); \}}.
-Note that it contains a closing brace; it must be matched with an
-earlier \code{Py_BEGIN_ALLOW_THREADS} macro.  See above for further
-discussion of this macro.  It is a no-op when thread support is
-disabled at compile time.
-\end{csimplemacrodesc}
-
-\begin{csimplemacrodesc}{Py_BLOCK_THREADS}
-This macro expands to \samp{PyEval_RestoreThread(_save);}: it
-is equivalent to \code{Py_END_ALLOW_THREADS} without the closing
-brace.  It is a no-op when thread support is disabled at compile
-time.
-\end{csimplemacrodesc}
-
-\begin{csimplemacrodesc}{Py_UNBLOCK_THREADS}
-This macro expands to \samp{_save = PyEval_SaveThread();}: it is
-equivalent to \code{Py_BEGIN_ALLOW_THREADS} without the opening brace
-and variable declaration.  It is a no-op when thread support is
-disabled at compile time.
-\end{csimplemacrodesc}
-
-All of the following functions are only available when thread support
-is enabled at compile time, and must be called only when the
-interpreter lock has been created.
-
-\begin{cfuncdesc}{PyInterpreterState*}{PyInterpreterState_New}{}
-Create a new interpreter state object.  The interpreter lock need not
-be held, but may be held if it is necessary to serialize calls to this
-function.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyInterpreterState_Clear}{PyInterpreterState *interp}
-Reset all information in an interpreter state object.  The interpreter
-lock must be held.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyInterpreterState_Delete}{PyInterpreterState *interp}
-Destroy an interpreter state object.  The interpreter lock need not be
-held.  The interpreter state must have been reset with a previous
-call to \cfunction{PyInterpreterState_Clear()}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyThreadState*}{PyThreadState_New}{PyInterpreterState *interp}
-Create a new thread state object belonging to the given interpreter
-object.  The interpreter lock need not be held, but may be held if it
-is necessary to serialize calls to this function.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyThreadState_Clear}{PyThreadState *tstate}
-Reset all information in a thread state object.  The interpreter lock
-must be held.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyThreadState_Delete}{PyThreadState *tstate}
-Destroy a thread state object.  The interpreter lock need not be
-held.  The thread state must have been reset with a previous
-call to \cfunction{PyThreadState_Clear()}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyThreadState*}{PyThreadState_Get}{}
-Return the current thread state.  The interpreter lock must be held.
-When the current thread state is \NULL{}, this issues a fatal
-error (so that the caller needn't check for \NULL{}).
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyThreadState*}{PyThreadState_Swap}{PyThreadState *tstate}
-Swap the current thread state with the thread state given by the
-argument \var{tstate}, which may be \NULL{}.  The interpreter lock
-must be held.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyThreadState_GetDict}{}
-Return a dictionary in which extensions can store thread-specific
-state information.  Each extension should use a unique key to use to
-store state in the dictionary.  If this function returns \NULL, an
-exception has been raised and the caller should allow it to
-propogate.
-\end{cfuncdesc}
-
-
-\section{Profiling and Tracing \label{profiling}}
-
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-
-The Python interpreter provides some low-level support for attaching
-profiling and execution tracing facilities.  These are used for
-profiling, debugging, and coverage analysis tools.
-
-Starting with Python 2.2, the implementation of this facility was
-substantially revised, and an interface from C was added.  This C
-interface allows the profiling or tracing code to avoid the overhead
-of calling through Python-level callable objects, making a direct C
-function call instead.  The essential attributes of the facility have
-not changed; the interface allows trace functions to be installed
-per-thread, and the basic events reported to the trace function are
-the same as had been reported to the Python-level trace functions in
-previous versions.
-
-\begin{ctypedesc}[Py_tracefunc]{int (*Py_tracefunc)(PyObject *obj,
-                                PyFrameObject *frame, int what,
-                                PyObject *arg)}
-  The type of the trace function registered using
-  \cfunction{PyEval_SetProfile()} and \cfunction{PyEval_SetTrace()}.
-  The first parameter is the object passed to the registration
-  function as \var{obj}, \var{frame} is the frame object to which the
-  event pertains, \var{what} is one of the constants
-  \constant{PyTrace_CALL}, \constant{PyTrace_EXCEPT},
-  \constant{PyTrace_LINE} or \constant{PyTrace_RETURN}, and \var{arg}
-  depends on the value of \var{what}:
-
-  \begin{tableii}{l|l}{constant}{Value of \var{what}}{Meaning of \var{arg}}
-    \lineii{PyTrace_CALL}{Always \NULL.}
-    \lineii{PyTrace_EXCEPT}{Exception information as returned by
-                            \function{sys.exc_info()}.}
-    \lineii{PyTrace_LINE}{Always \NULL.}
-    \lineii{PyTrace_RETURN}{Value being returned to the caller.}
-  \end{tableii}
-\end{ctypedesc}
-
-\begin{cvardesc}{int}{PyTrace_CALL}
-  The value of the \var{what} parameter to a \ctype{Py_tracefunc}
-  function when a new call to a function or method is being reported,
-  or a new entry into a generator.  Note that the creation of the
-  iterator for a generator function is not reported as there is no
-  control transfer to the Python bytecode in the corresponding frame.
-\end{cvardesc}
-
-\begin{cvardesc}{int}{PyTrace_EXCEPT}
-  The value of the \var{what} parameter to a \ctype{Py_tracefunc}
-  function when an exception has been raised by Python code as the
-  result of an operation.  The operation may have explictly intended
-  to raise the operation (as with a \keyword{raise} statement), or may
-  have triggered an exception in the runtime as a result of the
-  specific operation.
-\end{cvardesc}
-
-\begin{cvardesc}{int}{PyTrace_LINE}
-  The value passed as the \var{what} parameter to a trace function
-  (but not a profiling function) when a line-number event is being
-  reported.
-\end{cvardesc}
-
-\begin{cvardesc}{int}{PyTrace_RETURN}
-  The value for the \var{what} parameter to \ctype{Py_tracefunc}
-  functions when a call is returning without propogating an exception.
-\end{cvardesc}
-
-\begin{cfuncdesc}{void}{PyEval_SetProfile}{Py_tracefunc func, PyObject *obj}
-  Set the profiler function to \var{func}.  The \var{obj} parameter is
-  passed to the function as its first parameter, and may be any Python
-  object, or \NULL.  If the profile function needs to maintain state,
-  using a different value for \var{obj} for each thread provides a
-  convenient and thread-safe place to store it.  The profile function
-  is called for all monitored events except the line-number events.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyEval_SetTrace}{Py_tracefunc func, PyObject *obj}
-  Set the the tracing function to \var{func}.  This is similar to
-  \cfunction{PyEval_SetProfile()}, except the tracing function does
-  receive line-number events.
-\end{cfuncdesc}
-
-
-\section{Advanced Debugger Support \label{advanced-debugging}}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-
-These functions are only intended to be used by advanced debugging
-tools.
-
-\begin{cfuncdesc}{PyInterpreterState*}{PyInterpreterState_Head}{}
-Return the interpreter state object at the head of the list of all
-such objects.
-\versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyInterpreterState*}{PyInterpreterState_Next}{PyInterpreterState *interp}
-Return the next interpreter state object after \var{interp} from the
-list of all such objects.
-\versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyThreadState *}{PyInterpreterState_ThreadHead}{PyInterpreterState *interp}
-Return the a pointer to the first \ctype{PyThreadState} object in the
-list of threads associated with the interpreter \var{interp}.
-\versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyThreadState*}{PyThreadState_Next}{PyThreadState *tstate}
-Return the next thread state object after \var{tstate} from the list
-of all such objects belonging to the same \ctype{PyInterpreterState}
-object.
-\versionadded{2.2}
-\end{cfuncdesc}
-
-
-\chapter{Memory Management \label{memory}}
-\sectionauthor{Vladimir Marangozov}{Vladimir.Marangozov@inrialpes.fr}
-
-
-\section{Overview \label{memoryOverview}}
-
-Memory management in Python involves a private heap containing all
-Python objects and data structures. The management of this private
-heap is ensured internally by the \emph{Python memory manager}.  The
-Python memory manager has different components which deal with various
-dynamic storage management aspects, like sharing, segmentation,
-preallocation or caching.
-
-At the lowest level, a raw memory allocator ensures that there is
-enough room in the private heap for storing all Python-related data
-by interacting with the memory manager of the operating system. On top
-of the raw memory allocator, several object-specific allocators
-operate on the same heap and implement distinct memory management
-policies adapted to the peculiarities of every object type. For
-example, integer objects are managed differently within the heap than
-strings, tuples or dictionaries because integers imply different
-storage requirements and speed/space tradeoffs. The Python memory
-manager thus delegates some of the work to the object-specific
-allocators, but ensures that the latter operate within the bounds of
-the private heap.
-
-It is important to understand that the management of the Python heap
-is performed by the interpreter itself and that the user has no
-control on it, even if she regularly manipulates object pointers to
-memory blocks inside that heap.  The allocation of heap space for
-Python objects and other internal buffers is performed on demand by
-the Python memory manager through the Python/C API functions listed in
-this document.
-
-To avoid memory corruption, extension writers should never try to
-operate on Python objects with the functions exported by the C
-library: \cfunction{malloc()}\ttindex{malloc()},
-\cfunction{calloc()}\ttindex{calloc()},
-\cfunction{realloc()}\ttindex{realloc()} and
-\cfunction{free()}\ttindex{free()}.  This will result in 
-mixed calls between the C allocator and the Python memory manager
-with fatal consequences, because they implement different algorithms
-and operate on different heaps.  However, one may safely allocate and
-release memory blocks with the C library allocator for individual
-purposes, as shown in the following example:
-
-\begin{verbatim}
-    PyObject *res;
-    char *buf = (char *) malloc(BUFSIZ); /* for I/O */
-
-    if (buf == NULL)
-        return PyErr_NoMemory();
-    ...Do some I/O operation involving buf...
-    res = PyString_FromString(buf);
-    free(buf); /* malloc'ed */
-    return res;
-\end{verbatim}
-
-In this example, the memory request for the I/O buffer is handled by
-the C library allocator. The Python memory manager is involved only
-in the allocation of the string object returned as a result.
-
-In most situations, however, it is recommended to allocate memory from
-the Python heap specifically because the latter is under control of
-the Python memory manager. For example, this is required when the
-interpreter is extended with new object types written in C. Another
-reason for using the Python heap is the desire to \emph{inform} the
-Python memory manager about the memory needs of the extension module.
-Even when the requested memory is used exclusively for internal,
-highly-specific purposes, delegating all memory requests to the Python
-memory manager causes the interpreter to have a more accurate image of
-its memory footprint as a whole. Consequently, under certain
-circumstances, the Python memory manager may or may not trigger
-appropriate actions, like garbage collection, memory compaction or
-other preventive procedures. Note that by using the C library
-allocator as shown in the previous example, the allocated memory for
-the I/O buffer escapes completely the Python memory manager.
-
-
-\section{Memory Interface \label{memoryInterface}}
-
-The following function sets, modeled after the ANSI C standard, are
-available for allocating and releasing memory from the Python heap:
-
-
-\begin{cfuncdesc}{void*}{PyMem_Malloc}{size_t n}
-Allocates \var{n} bytes and returns a pointer of type \ctype{void*} to
-the allocated memory, or \NULL{} if the request fails.  Requesting zero
-bytes returns a non-\NULL{} pointer.
-The memory will not have been initialized in any way.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void*}{PyMem_Realloc}{void *p, size_t n}
-Resizes the memory block pointed to by \var{p} to \var{n} bytes. The
-contents will be unchanged to the minimum of the old and the new
-sizes. If \var{p} is \NULL{}, the call is equivalent to
-\cfunction{PyMem_Malloc(\var{n})}; if \var{n} is equal to zero, the
-memory block is resized but is not freed, and the returned pointer is
-non-\NULL{}.  Unless \var{p} is \NULL{}, it must have been returned by
-a previous call to \cfunction{PyMem_Malloc()} or
-\cfunction{PyMem_Realloc()}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyMem_Free}{void *p}
-Frees the memory block pointed to by \var{p}, which must have been
-returned by a previous call to \cfunction{PyMem_Malloc()} or
-\cfunction{PyMem_Realloc()}.  Otherwise, or if
-\cfunction{PyMem_Free(p)} has been called before, undefined behaviour
-occurs. If \var{p} is \NULL{}, no operation is performed.
-\end{cfuncdesc}
-
-The following type-oriented macros are provided for convenience.  Note 
-that \var{TYPE} refers to any C type.
-
-\begin{cfuncdesc}{\var{TYPE}*}{PyMem_New}{TYPE, size_t n}
-Same as \cfunction{PyMem_Malloc()}, but allocates \code{(\var{n} *
-sizeof(\var{TYPE}))} bytes of memory.  Returns a pointer cast to
-\ctype{\var{TYPE}*}.
-The memory will not have been initialized in any way.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{\var{TYPE}*}{PyMem_Resize}{void *p, TYPE, size_t n}
-Same as \cfunction{PyMem_Realloc()}, but the memory block is resized
-to \code{(\var{n} * sizeof(\var{TYPE}))} bytes.  Returns a pointer
-cast to \ctype{\var{TYPE}*}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyMem_Del}{void *p}
-Same as \cfunction{PyMem_Free()}.
-\end{cfuncdesc}
-
-In addition, the following macro sets are provided for calling the
-Python memory allocator directly, without involving the C API functions
-listed above. However, note that their use does not preserve binary
-compatibility accross Python versions and is therefore deprecated in
-extension modules.
-
-\cfunction{PyMem_MALLOC()}, \cfunction{PyMem_REALLOC()}, \cfunction{PyMem_FREE()}.
-
-\cfunction{PyMem_NEW()}, \cfunction{PyMem_RESIZE()}, \cfunction{PyMem_DEL()}.
-
-
-\section{Examples \label{memoryExamples}}
-
-Here is the example from section \ref{memoryOverview}, rewritten so
-that the I/O buffer is allocated from the Python heap by using the
-first function set:
-
-\begin{verbatim}
-    PyObject *res;
-    char *buf = (char *) PyMem_Malloc(BUFSIZ); /* for I/O */
-
-    if (buf == NULL)
-        return PyErr_NoMemory();
-    /* ...Do some I/O operation involving buf... */
-    res = PyString_FromString(buf);
-    PyMem_Free(buf); /* allocated with PyMem_Malloc */
-    return res;
-\end{verbatim}
-
-The same code using the type-oriented function set:
-
-\begin{verbatim}
-    PyObject *res;
-    char *buf = PyMem_New(char, BUFSIZ); /* for I/O */
-
-    if (buf == NULL)
-        return PyErr_NoMemory();
-    /* ...Do some I/O operation involving buf... */
-    res = PyString_FromString(buf);
-    PyMem_Del(buf); /* allocated with PyMem_New */
-    return res;
-\end{verbatim}
-
-Note that in the two examples above, the buffer is always
-manipulated via functions belonging to the same set. Indeed, it
-is required to use the same memory API family for a given
-memory block, so that the risk of mixing different allocators is
-reduced to a minimum. The following code sequence contains two errors,
-one of which is labeled as \emph{fatal} because it mixes two different
-allocators operating on different heaps.
-
-\begin{verbatim}
-char *buf1 = PyMem_New(char, BUFSIZ);
-char *buf2 = (char *) malloc(BUFSIZ);
-char *buf3 = (char *) PyMem_Malloc(BUFSIZ);
-...
-PyMem_Del(buf3);  /* Wrong -- should be PyMem_Free() */
-free(buf2);       /* Right -- allocated via malloc() */
-free(buf1);       /* Fatal -- should be PyMem_Del()  */
-\end{verbatim}
-
-In addition to the functions aimed at handling raw memory blocks from
-the Python heap, objects in Python are allocated and released with
-\cfunction{PyObject_New()}, \cfunction{PyObject_NewVar()} and
-\cfunction{PyObject_Del()}, or with their corresponding macros
-\cfunction{PyObject_NEW()}, \cfunction{PyObject_NEW_VAR()} and
-\cfunction{PyObject_DEL()}.
-
-These will be explained in the next chapter on defining and
-implementing new object types in C.
-
-
-\chapter{Defining New Object Types \label{newTypes}}
-
-
-\section{Allocating Objects on the Heap
-         \label{allocating-objects}}
-
-\begin{cfuncdesc}{PyObject*}{_PyObject_New}{PyTypeObject *type}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyVarObject*}{_PyObject_NewVar}{PyTypeObject *type, int size}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{_PyObject_Del}{PyObject *op}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyObject_Init}{PyObject *op,
-					    PyTypeObject *type}
-  Initialize a newly-allocated object \var{op} with its type and
-  initial reference.  Returns the initialized object.  If \var{type}
-  indicates that the object participates in the cyclic garbage
-  detector, it it added to the detector's set of observed objects.
-  Other fields of the object are not affected.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyVarObject*}{PyObject_InitVar}{PyVarObject *op,
-						  PyTypeObject *type, int size}
-  This does everything \cfunction{PyObject_Init()} does, and also
-  initializes the length information for a variable-size object.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{\var{TYPE}*}{PyObject_New}{TYPE, PyTypeObject *type}
-  Allocate a new Python object using the C structure type \var{TYPE}
-  and the Python type object \var{type}.  Fields not defined by the
-  Python object header are not initialized; the object's reference
-  count will be one.  The size of the memory
-  allocation is determined from the \member{tp_basicsize} field of the
-  type object.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{\var{TYPE}*}{PyObject_NewVar}{TYPE, PyTypeObject *type,
-                                                int size}
-  Allocate a new Python object using the C structure type \var{TYPE}
-  and the Python type object \var{type}.  Fields not defined by the
-  Python object header are not initialized.  The allocated memory
-  allows for the \var{TYPE} structure plus \var{size} fields of the
-  size given by the \member{tp_itemsize} field of \var{type}.  This is
-  useful for implementing objects like tuples, which are able to
-  determine their size at construction time.  Embedding the array of
-  fields into the same allocation decreases the number of allocations,
-  improving the memory management efficiency.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyObject_Del}{PyObject *op}
-  Releases memory allocated to an object using
-  \cfunction{PyObject_New()} or \cfunction{PyObject_NewVar()}.  This
-  is normally called from the \member{tp_dealloc} handler specified in
-  the object's type.  The fields of the object should not be accessed
-  after this call as the memory is no longer a valid Python object.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{\var{TYPE}*}{PyObject_NEW}{TYPE, PyTypeObject *type}
-  Macro version of \cfunction{PyObject_New()}, to gain performance at
-  the expense of safety.  This does not check \var{type} for a \NULL{}
-  value.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{\var{TYPE}*}{PyObject_NEW_VAR}{TYPE, PyTypeObject *type,
-                                                int size}
-  Macro version of \cfunction{PyObject_NewVar()}, to gain performance
-  at the expense of safety.  This does not check \var{type} for a
-  \NULL{} value.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyObject_DEL}{PyObject *op}
-  Macro version of \cfunction{PyObject_Del()}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{Py_InitModule}{char *name,
-                                            PyMethodDef *methods}
-  Create a new module object based on a name and table of functions,
-  returning the new module object.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{Py_InitModule3}{char *name,
-                                             PyMethodDef *methods,
-                                             char *doc}
-  Create a new module object based on a name and table of functions,
-  returning the new module object.  If \var{doc} is non-\NULL, it will
-  be used to define the docstring for the module.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{Py_InitModule4}{char *name,
-                                             PyMethodDef *methods,
-                                             char *doc, PyObject *self,
-                                             int apiver}
-  Create a new module object based on a name and table of functions,
-  returning the new module object.  If \var{doc} is non-\NULL, it will
-  be used to define the docstring for the module.  If \var{self} is
-  non-\NULL, it will passed to the functions of the module as their
-  (otherwise \NULL) first parameter.  (This was added as an
-  experimental feature, and there are no known uses in the current
-  version of Python.)  For \var{apiver}, the only value which should
-  be passed is defined by the constant \constant{PYTHON_API_VERSION}.
-
-  \strong{Note:}  Most uses of this function should probably be using
-  the \cfunction{Py_InitModule3()} instead; only use this if you are
-  sure you need it.
-\end{cfuncdesc}
-
-DL_IMPORT
-
-\begin{cvardesc}{PyObject}{_Py_NoneStruct}
-  Object which is visible in Python as \code{None}.  This should only
-  be accessed using the \code{Py_None} macro, which evaluates to a
-  pointer to this object.
-\end{cvardesc}
-
-
-\section{Common Object Structures \label{common-structs}}
-
-PyObject, PyVarObject
-
-PyObject_HEAD, PyObject_HEAD_INIT, PyObject_VAR_HEAD
-
-Typedefs:
-unaryfunc, binaryfunc, ternaryfunc, inquiry, coercion, intargfunc,
-intintargfunc, intobjargproc, intintobjargproc, objobjargproc,
-destructor, printfunc, getattrfunc, getattrofunc, setattrfunc,
-setattrofunc, cmpfunc, reprfunc, hashfunc
-
-\begin{ctypedesc}{PyCFunction}
-Type of the functions used to implement most Python callables in C.
-\end{ctypedesc}
-
-\begin{ctypedesc}{PyMethodDef}
-Structure used to describe a method of an extension type.  This
-structure has four fields:
-
-\begin{tableiii}{l|l|l}{member}{Field}{C Type}{Meaning}
-  \lineiii{ml_name}{char *}{name of the method}
-  \lineiii{ml_meth}{PyCFunction}{pointer to the C implementation}
-  \lineiii{ml_flags}{int}{flag bits indicating how the call should be
-                          constructed}
-  \lineiii{ml_doc}{char *}{points to the contents of the docstring}
-\end{tableiii}
-\end{ctypedesc}
-
-The \var{ml_meth} is a C function pointer. The functions may be of
-different types, but they always return \ctype{PyObject*}. If the
-function is not of the \ctype{PyCFunction}, the compiler will require
-a cast in the method table. Even though \ctype{PyCFunction} defines
-the first parameter as \ctype{PyObject*}, it is common that the method
-implementation uses a the specific C type of the \var{self} object.
-
-The flags can have the following values. Only METH_VARARGS and
-METH_KEYWORDS can be combined; the others can't.
-
-\begin{datadesc}{METH_VARARGS}
-
-This is the typical calling convention, where the methods have the
-type \ctype{PyMethodDef}. The function expects two \ctype{PyObject*}.
-The first one is the \var{self} object for methods; for module
-functions, it has the value given to \cfunction{PyInitModule4} (or
-\NULL{} if \cfunction{PyInitModule} was used). The second parameter
-(often called \var{args}) is a tuple object representing all
-arguments. This parameter is typically processed using
-\cfunction{PyArg_ParseTuple}.
-
-\end{datadesc}
-
-\begin{datadesc}{METH_KEYWORDS}
-
-Methods with these flags must be of type
-\ctype{PyCFunctionWithKeywords}.  The function expects three
-parameters: \var{self}, \var{args}, and a dictionary of all the keyword
-arguments. The flag is typically combined with METH_VARARGS, and the
-parameters are typically processed using
-\cfunction{PyArg_ParseTupleAndKeywords}.
-
-\end{datadesc}
-
-\begin{datadesc}{METH_NOARGS}
-
-Methods without parameters don't need to check whether arguments are
-given if they are listed with the \code{METH_NOARGS} flag. They need
-to be of type \ctype{PyNoArgsFunction}, i.e. they expect a single
-\var{self} parameter.
-
-\end{datadesc}
-
-\begin{datadesc}{METH_O}
-
-Methods with a single object argument can be listed with the
-\code{METH_O} flag, instead of invoking \cfunction{PyArg_ParseTuple}
-with a \code{``O''} argument. They have the type \ctype{PyCFunction},
-with the \var{self} parameter, and a \ctype{PyObject*} parameter
-representing the single argument.
-
-\end{datadesc}
-
-\begin{datadesc}{METH_OLDARGS}
-
-This calling convention is deprecated. The method must be of type
-\ctype{PyCFunction}. The second argument is \NULL{} if no arguments
-are given, a single object if exactly one argument is given, and a
-tuple of objects if more than one argument is given.
-
-\end{datadesc}
-
-\begin{cfuncdesc}{PyObject*}{Py_FindMethod}{PyMethodDef[] table,
-                                            PyObject *ob, char *name}
-Return a bound method object for an extension type implemented in C.
-This function also handles the special attribute \member{__methods__},
-returning a list of all the method names defined in \var{table}.
-\end{cfuncdesc}
-
-
-\section{Mapping Object Structures \label{mapping-structs}}
-
-\begin{ctypedesc}{PyMappingMethods}
-Structure used to hold pointers to the functions used to implement the 
-mapping protocol for an extension type.
-\end{ctypedesc}
-
-
-\section{Number Object Structures \label{number-structs}}
-
-\begin{ctypedesc}{PyNumberMethods}
-Structure used to hold pointers to the functions an extension type
-uses to implement the number protocol.
-\end{ctypedesc}
-
-
-\section{Sequence Object Structures \label{sequence-structs}}
-
-\begin{ctypedesc}{PySequenceMethods}
-Structure used to hold pointers to the functions which an object uses
-to implement the sequence protocol.
-\end{ctypedesc}
-
-
-\section{Buffer Object Structures \label{buffer-structs}}
-\sectionauthor{Greg J. Stein}{greg@lyra.org}
-
-The buffer interface exports a model where an object can expose its
-internal data as a set of chunks of data, where each chunk is
-specified as a pointer/length pair.  These chunks are called
-\dfn{segments} and are presumed to be non-contiguous in memory.
-
-If an object does not export the buffer interface, then its
-\member{tp_as_buffer} member in the \ctype{PyTypeObject} structure
-should be \NULL{}.  Otherwise, the \member{tp_as_buffer} will point to
-a \ctype{PyBufferProcs} structure.
-
-\strong{Note:} It is very important that your
-\ctype{PyTypeObject} structure uses \constant{Py_TPFLAGS_DEFAULT} for
-the value of the \member{tp_flags} member rather than \code{0}.  This
-tells the Python runtime that your \ctype{PyBufferProcs} structure
-contains the \member{bf_getcharbuffer} slot. Older versions of Python
-did not have this member, so a new Python interpreter using an old
-extension needs to be able to test for its presence before using it.
-
-\begin{ctypedesc}{PyBufferProcs}
-Structure used to hold the function pointers which define an
-implementation of the buffer protocol.
-
-The first slot is \member{bf_getreadbuffer}, of type
-\ctype{getreadbufferproc}.  If this slot is \NULL{}, then the object
-does not support reading from the internal data.  This is
-non-sensical, so implementors should fill this in, but callers should
-test that the slot contains a non-\NULL{} value.
-
-The next slot is \member{bf_getwritebuffer} having type
-\ctype{getwritebufferproc}. This slot may be \NULL{} if the object
-does not allow writing into its returned buffers.
-
-The third slot is \member{bf_getsegcount}, with type
-\ctype{getsegcountproc}.  This slot must not be \NULL{} and is used to 
-inform the caller how many segments the object contains.  Simple
-objects such as \ctype{PyString_Type} and
-\ctype{PyBuffer_Type} objects contain a single segment.
-
-The last slot is \member{bf_getcharbuffer}, of type
-\ctype{getcharbufferproc}.  This slot will only be present if the
-\constant{Py_TPFLAGS_HAVE_GETCHARBUFFER} flag is present in the
-\member{tp_flags} field of the object's \ctype{PyTypeObject}.  Before using
-this slot, the caller should test whether it is present by using the
-\cfunction{PyType_HasFeature()}\ttindex{PyType_HasFeature()} function.
-If present, it may be \NULL, indicating that the object's contents
-cannot be used as \emph{8-bit characters}.
-The slot function may also raise an error if the object's contents
-cannot be interpreted as 8-bit characters.  For example, if the object
-is an array which is configured to hold floating point values, an
-exception may be raised if a caller attempts to use
-\member{bf_getcharbuffer} to fetch a sequence of 8-bit characters.
-This notion of exporting the internal buffers as ``text'' is used to
-distinguish between objects that are binary in nature, and those which
-have character-based content.
-
-\strong{Note:} The current policy seems to state that these characters
-may be multi-byte characters. This implies that a buffer size of
-\var{N} does not mean there are \var{N} characters present.
-\end{ctypedesc}
-
-\begin{datadesc}{Py_TPFLAGS_HAVE_GETCHARBUFFER}
-Flag bit set in the type structure to indicate that the
-\member{bf_getcharbuffer} slot is known.  This being set does not
-indicate that the object supports the buffer interface or that the
-\member{bf_getcharbuffer} slot is non-\NULL.
-\end{datadesc}
-
-\begin{ctypedesc}[getreadbufferproc]{int (*getreadbufferproc)
-                            (PyObject *self, int segment, void **ptrptr)}
-Return a pointer to a readable segment of the buffer.  This function
-is allowed to raise an exception, in which case it must return
-\code{-1}.  The \var{segment} which is passed must be zero or
-positive, and strictly less than the number of segments returned by
-the \member{bf_getsegcount} slot function.  On success, it returns the
-length of the buffer memory, and sets \code{*\var{ptrptr}} to a
-pointer to that memory.
-\end{ctypedesc}
-
-\begin{ctypedesc}[getwritebufferproc]{int (*getwritebufferproc)
-                            (PyObject *self, int segment, void **ptrptr)}
-Return a pointer to a writable memory buffer in \code{*\var{ptrptr}},
-and the length of that segment as the function return value.
-The memory buffer must correspond to buffer segment \var{segment}.
-Must return \code{-1} and set an exception on error.
-\exception{TypeError} should be raised if the object only supports
-read-only buffers, and \exception{SystemError} should be raised when
-\var{segment} specifies a segment that doesn't exist.
-% Why doesn't it raise ValueError for this one?
-% GJS: because you shouldn't be calling it with an invalid
-%      segment. That indicates a blatant programming error in the C
-%      code.
-\end{ctypedesc}
-
-\begin{ctypedesc}[getsegcountproc]{int (*getsegcountproc)
-                            (PyObject *self, int *lenp)}
-Return the number of memory segments which comprise the buffer.  If
-\var{lenp} is not \NULL, the implementation must report the sum of the 
-sizes (in bytes) of all segments in \code{*\var{lenp}}.
-The function cannot fail.
-\end{ctypedesc}
-
-\begin{ctypedesc}[getcharbufferproc]{int (*getcharbufferproc)
-                            (PyObject *self, int segment, const char **ptrptr)}
-\end{ctypedesc}
-
-
-\section{Supporting the Iterator Protocol
-         \label{supporting-iteration}}
-
-
-\section{Supporting Cyclic Garbarge Collection
-         \label{supporting-cycle-detection}}
-
-Python's support for detecting and collecting garbage which involves
-circular references requires support from object types which are
-``containers'' for other objects which may also be containers.  Types
-which do not store references to other objects, or which only store
-references to atomic types (such as numbers or strings), do not need
-to provide any explicit support for garbage collection.
-
-To create a container type, the \member{tp_flags} field of the type
-object must include the \constant{Py_TPFLAGS_HAVE_GC} and provide an
-implementation of the \member{tp_traverse} handler.  If instances of the
-type are mutable, a \member{tp_clear} implementation must also be
-provided.
-
-\begin{datadesc}{Py_TPFLAGS_HAVE_GC}
-  Objects with a type with this flag set must conform with the rules
-  documented here.  For convenience these objects will be referred to
-  as container objects.
-\end{datadesc}
-
-Constructors for container types must conform to two rules:
-
-\begin{enumerate}
-\item  The memory for the object must be allocated using
-       \cfunction{PyObject_GC_New()} or \cfunction{PyObject_GC_VarNew()}.
-
-\item  Once all the fields which may contain references to other
-       containers are initialized, it must call
-       \cfunction{PyObject_GC_Track()}.
-\end{enumerate}
-
-\begin{cfuncdesc}{\var{TYPE}*}{PyObject_GC_New}{TYPE, PyTypeObject *type}
-  Analogous to \cfunction{PyObject_New()} but for container objects with
-  the \constant{Py_TPFLAGS_HAVE_GC} flag set.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{\var{TYPE}*}{PyObject_GC_NewVar}{TYPE, PyTypeObject *type,
-                                                   int size}
-  Analogous to \cfunction{PyObject_NewVar()} but for container objects
-  with the \constant{Py_TPFLAGS_HAVE_GC} flag set.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyVarObject *}{PyObject_GC_Resize}{PyVarObject *op, int}
-  Resize an object allocated by \cfunction{PyObject_NewVar()}.  Returns
-  the resized object or \NULL{} on failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyObject_GC_Track}{PyObject *op}
-  Adds the object \var{op} to the set of container objects tracked by
-  the collector.  The collector can run at unexpected times so objects
-  must be valid while being tracked.  This should be called once all
-  the fields followed by the \member{tp_traverse} handler become valid,
-  usually near the end of the constructor.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{_PyObject_GC_TRACK}{PyObject *op}
-  A macro version of \cfunction{PyObject_GC_Track()}.  It should not be
-  used for extension modules.
-\end{cfuncdesc}
-
-Similarly, the deallocator for the object must conform to a similar
-pair of rules:
-
-\begin{enumerate}
-\item  Before fields which refer to other containers are invalidated,
-       \cfunction{PyObject_GC_UnTrack()} must be called.
-
-\item  The object's memory must be deallocated using
-       \cfunction{PyObject_GC_Del()}.
-\end{enumerate}
-
-\begin{cfuncdesc}{void}{PyObject_GC_Del}{PyObject *op}
-  Releases memory allocated to an object using
-  \cfunction{PyObject_GC_New()} or \cfunction{PyObject_GC_NewVar()}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyObject_GC_UnTrack}{PyObject *op}
-  Remove the object \var{op} from the set of container objects tracked
-  by the collector.  Note that \cfunction{PyObject_GC_Track()} can be
-  called again on this object to add it back to the set of tracked
-  objects.  The deallocator (\member{tp_dealloc} handler) should call
-  this for the object before any of the fields used by the
-  \member{tp_traverse} handler become invalid.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{_PyObject_GC_UNTRACK}{PyObject *op}
-  A macro version of \cfunction{PyObject_GC_UnTrack()}.  It should not be
-  used for extension modules.
-\end{cfuncdesc}
-
-The \member{tp_traverse} handler accepts a function parameter of this
-type:
-
-\begin{ctypedesc}[visitproc]{int (*visitproc)(PyObject *object, void *arg)}
-  Type of the visitor function passed to the \member{tp_traverse}
-  handler.  The function should be called with an object to traverse
-  as \var{object} and the third parameter to the \member{tp_traverse}
-  handler as \var{arg}.
-\end{ctypedesc}
-
-The \member{tp_traverse} handler must have the following type:
-
-\begin{ctypedesc}[traverseproc]{int (*traverseproc)(PyObject *self,
-                                visitproc visit, void *arg)}
-  Traversal function for a container object.  Implementations must
-  call the \var{visit} function for each object directly contained by
-  \var{self}, with the parameters to \var{visit} being the contained
-  object and the \var{arg} value passed to the handler.  If
-  \var{visit} returns a non-zero value then an error has occurred and
-  that value should be returned immediately.
-\end{ctypedesc}
-
-The \member{tp_clear} handler must be of the \ctype{inquiry} type, or
-\NULL{} if the object is immutable.
-
-\begin{ctypedesc}[inquiry]{int (*inquiry)(PyObject *self)}
-  Drop references that may have created reference cycles.  Immutable
-  objects do not have to define this method since they can never
-  directly create reference cycles.  Note that the object must still
-  be valid after calling this method (don't just call
-  \cfunction{Py_DECREF()} on a reference).  The collector will call
-  this method if it detects that this object is involved in a
-  reference cycle.
-\end{ctypedesc}
-
-
-\subsection{Example Cycle Collector Support
-            \label{example-cycle-support}}
-
-This example shows only enough of the implementation of an extension
-type to show how the garbage collector support needs to be added.  It
-shows the definition of the object structure, the
-\member{tp_traverse}, \member{tp_clear} and \member{tp_dealloc}
-implementations, the type structure, and a constructor --- the module
-initialization needed to export the constructor to Python is not shown
-as there are no special considerations there for the collector.  To
-make this interesting, assume that the module exposes ways for the
-\member{container} field of the object to be modified.  Note that
-since no checks are made on the type of the object used to initialize
-\member{container}, we have to assume that it may be a container.
-
-\begin{verbatim}
-#include "Python.h"
-
-typedef struct {
-    PyObject_HEAD
-    PyObject *container;
-} MyObject;
-
-static int
-my_traverse(MyObject *self, visitproc visit, void *arg)
-{
-    if (self->container != NULL)
-        return visit(self->container, arg);
-    else
-        return 0;
-}
-
-static int
-my_clear(MyObject *self)
-{
-    Py_XDECREF(self->container);
-    self->container = NULL;
-
-    return 0;
-}
-
-static void
-my_dealloc(MyObject *self)
-{
-    PyObject_GC_UnTrack((PyObject *) self);
-    Py_XDECREF(self->container);
-    PyObject_GC_Del(self);
-}
-\end{verbatim}
-
-\begin{verbatim}
-statichere PyTypeObject
-MyObject_Type = {
-    PyObject_HEAD_INIT(NULL)
-    0,
-    "MyObject",
-    sizeof(MyObject),
-    0,
-    (destructor)my_dealloc,     /* tp_dealloc */
-    0,                          /* tp_print */
-    0,                          /* tp_getattr */
-    0,                          /* tp_setattr */
-    0,                          /* tp_compare */
-    0,                          /* tp_repr */
-    0,                          /* tp_as_number */
-    0,                          /* tp_as_sequence */
-    0,                          /* tp_as_mapping */
-    0,                          /* tp_hash */
-    0,                          /* tp_call */
-    0,                          /* tp_str */
-    0,                          /* tp_getattro */
-    0,                          /* tp_setattro */
-    0,                          /* tp_as_buffer */
-    Py_TPFLAGS_DEFAULT | Py_TPFLAGS_HAVE_GC,
-    0,                          /* tp_doc */
-    (traverseproc)my_traverse,  /* tp_traverse */
-    (inquiry)my_clear,          /* tp_clear */
-    0,                          /* tp_richcompare */
-    0,                          /* tp_weaklistoffset */
-};
-
-/* This constructor should be made accessible from Python. */
-static PyObject *
-new_object(PyObject *unused, PyObject *args)
-{
-    PyObject *container = NULL;
-    MyObject *result = NULL;
-
-    if (PyArg_ParseTuple(args, "|O:new_object", &container)) {
-        result = PyObject_GC_New(MyObject, &MyObject_Type);
-        if (result != NULL) {
-            result->container = container;
-            PyObject_GC_Track(result);
-        }
-    }
-    return (PyObject *) result;
-}
-\end{verbatim}
+\input{intro}
+\input{veryhigh}
+\input{refcounting}
+\input{exceptions}
+\input{utilities}
+\input{abstract}
+\input{concrete}
+\input{init}
+\input{memory}
+\input{newtypes}
 
 
 % \chapter{Debugging \label{debugging}}
diff --git a/Doc/api/concrete.tex b/Doc/api/concrete.tex
new file mode 100644
index 0000000..64653a9
--- /dev/null
+++ b/Doc/api/concrete.tex
@@ -0,0 +1,2342 @@
+\chapter{Concrete Objects Layer \label{concrete}}
+
+
+The functions in this chapter are specific to certain Python object
+types.  Passing them an object of the wrong type is not a good idea;
+if you receive an object from a Python program and you are not sure
+that it has the right type, you must perform a type check first;
+for example, to check that an object is a dictionary, use
+\cfunction{PyDict_Check()}.  The chapter is structured like the
+``family tree'' of Python object types.
+
+\warning{While the functions described in this chapter carefully check
+the type of the objects which are passed in, many of them do not check
+for \NULL{} being passed instead of a valid object.  Allowing \NULL{}
+to be passed in can cause memory access violations and immediate
+termination of the interpreter.}
+
+
+\section{Fundamental Objects \label{fundamental}}
+
+This section describes Python type objects and the singleton object 
+\code{None}.
+
+
+\subsection{Type Objects \label{typeObjects}}
+
+\obindex{type}
+\begin{ctypedesc}{PyTypeObject}
+  The C structure of the objects used to describe built-in types.
+\end{ctypedesc}
+
+\begin{cvardesc}{PyObject*}{PyType_Type}
+  This is the type object for type objects; it is the same object as
+  \code{types.TypeType} in the Python layer.
+  \withsubitem{(in module types)}{\ttindex{TypeType}}
+\end{cvardesc}
+
+\begin{cfuncdesc}{int}{PyType_Check}{PyObject *o}
+  Returns true is the object \var{o} is a type object.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyType_HasFeature}{PyObject *o, int feature}
+  Returns true if the type object \var{o} sets the feature
+  \var{feature}.  Type features are denoted by single bit flags.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyType_IsSubtype}{PyTypeObject *a, PyTypeObject *b}
+  Returns true if \var{a} is a subtype of \var{b}.
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyType_GenericAlloc}{PyTypeObject *type,
+                                                  int nitems}
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyType_GenericNew}{PyTypeObject *type,
+                                            PyObject *args, PyObject *kwds}
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyType_Ready}{PyTypeObject *type}
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+
+\subsection{The None Object \label{noneObject}}
+
+\obindex{None@\texttt{None}}
+Note that the \ctype{PyTypeObject} for \code{None} is not directly
+exposed in the Python/C API.  Since \code{None} is a singleton,
+testing for object identity (using \samp{==} in C) is sufficient.
+There is no \cfunction{PyNone_Check()} function for the same reason.
+
+\begin{cvardesc}{PyObject*}{Py_None}
+  The Python \code{None} object, denoting lack of value.  This object
+  has no methods.
+\end{cvardesc}
+
+
+\section{Numeric Objects \label{numericObjects}}
+
+\obindex{numeric}
+
+
+\subsection{Plain Integer Objects \label{intObjects}}
+
+\obindex{integer}
+\begin{ctypedesc}{PyIntObject}
+  This subtype of \ctype{PyObject} represents a Python integer
+  object.
+\end{ctypedesc}
+
+\begin{cvardesc}{PyTypeObject}{PyInt_Type}
+  This instance of \ctype{PyTypeObject} represents the Python plain 
+  integer type.  This is the same object as \code{types.IntType}.
+  \withsubitem{(in modules types)}{\ttindex{IntType}}
+\end{cvardesc}
+
+\begin{cfuncdesc}{int}{PyInt_Check}{PyObject* o}
+  Returns true if \var{o} is of type \cdata{PyInt_Type} or a subtype
+  of \cdata{PyInt_Type}.
+  \versionchanged[Allowed subtypes to be accepted]{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyInt_CheckExact}{PyObject* o}
+  Returns true if \var{o} is of type \cdata{PyInt_Type}, but not a
+  subtype of \cdata{PyInt_Type}.
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyInt_FromLong}{long ival}
+  Creates a new integer object with a value of \var{ival}.
+
+  The current implementation keeps an array of integer objects for all
+  integers between \code{-1} and \code{100}, when you create an int in
+  that range you actually just get back a reference to the existing
+  object. So it should be possible to change the value of \code{1}.  I
+  suspect the behaviour of Python in this case is undefined. :-)
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{long}{PyInt_AsLong}{PyObject *io}
+  Will first attempt to cast the object to a \ctype{PyIntObject}, if
+  it is not already one, and then return its value.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{long}{PyInt_AS_LONG}{PyObject *io}
+  Returns the value of the object \var{io}.  No error checking is
+  performed.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{long}{PyInt_GetMax}{}
+  Returns the system's idea of the largest integer it can handle
+  (\constant{LONG_MAX}\ttindex{LONG_MAX}, as defined in the system
+  header files).
+\end{cfuncdesc}
+
+
+\subsection{Long Integer Objects \label{longObjects}}
+
+\obindex{long integer}
+\begin{ctypedesc}{PyLongObject}
+  This subtype of \ctype{PyObject} represents a Python long integer
+  object.
+\end{ctypedesc}
+
+\begin{cvardesc}{PyTypeObject}{PyLong_Type}
+  This instance of \ctype{PyTypeObject} represents the Python long
+  integer type.  This is the same object as \code{types.LongType}.
+  \withsubitem{(in modules types)}{\ttindex{LongType}}
+\end{cvardesc}
+
+\begin{cfuncdesc}{int}{PyLong_Check}{PyObject *p}
+  Returns true if its argument is a \ctype{PyLongObject} or a subtype
+  of \ctype{PyLongObject}.
+  \versionchanged[Allowed subtypes to be accepted]{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyLong_CheckExact}{PyObject *p}
+  Returns true if its argument is a \ctype{PyLongObject}, but not a
+  subtype of \ctype{PyLongObject}.
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyLong_FromLong}{long v}
+  Returns a new \ctype{PyLongObject} object from \var{v}, or \NULL{}
+  on failure.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyLong_FromUnsignedLong}{unsigned long v}
+  Returns a new \ctype{PyLongObject} object from a C \ctype{unsigned
+  long}, or \NULL{} on failure.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyLong_FromLongLong}{long long v}
+  Returns a new \ctype{PyLongObject} object from a C \ctype{long long},
+  or \NULL{} on failure.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyLong_FromUnsignedLongLong}{unsigned long long v}
+  Returns a new \ctype{PyLongObject} object from a C \ctype{unsigned
+  long long}, or \NULL{} on failure.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyLong_FromDouble}{double v}
+  Returns a new \ctype{PyLongObject} object from the integer part of
+  \var{v}, or \NULL{} on failure.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyLong_FromString}{char *str, char **pend,
+                                                int base}
+  Return a new \ctype{PyLongObject} based on the string value in
+  \var{str}, which is interpreted according to the radix in
+  \var{base}.  If \var{pend} is non-\NULL, \code{*\var{pend}} will
+  point to the first character in \var{str} which follows the
+  representation of the number.  If \var{base} is \code{0}, the radix
+  will be determined base on the leading characters of \var{str}: if
+  \var{str} starts with \code{'0x'} or \code{'0X'}, radix 16 will be
+  used; if \var{str} starts with \code{'0'}, radix 8 will be used;
+  otherwise radix 10 will be used.  If \var{base} is not \code{0}, it
+  must be between \code{2} and \code{36}, inclusive.  Leading spaces
+  are ignored.  If there are no digits, \exception{ValueError} will be
+  raised.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyLong_FromUnicode}{Py_UNICODE *u,
+                                                 int length, int base}
+  Convert a sequence of Unicode digits to a Python long integer
+  value.  The first parameter, \var{u}, points to the first character
+  of the Unicode string, \var{length} gives the number of characters,
+  and \var{base} is the radix for the conversion.  The radix must be
+  in the range [2, 36]; if it is out of range, \exception{ValueError}
+  will be raised.
+  \versionadded{1.6}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyLong_FromVoidPtr}{void *p}
+  Create a Python integer or long integer from the pointer \var{p}.
+  The pointer value can be retrieved from the resulting value using
+  \cfunction{PyLong_AsVoidPtr()}.
+  \versionadded{1.5.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{long}{PyLong_AsLong}{PyObject *pylong}
+  Returns a C \ctype{long} representation of the contents of
+  \var{pylong}.  If \var{pylong} is greater than
+  \constant{LONG_MAX}\ttindex{LONG_MAX}, an \exception{OverflowError}
+  is raised.
+  \withsubitem{(built-in exception)}{\ttindex{OverflowError}}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{unsigned long}{PyLong_AsUnsignedLong}{PyObject *pylong}
+  Returns a C \ctype{unsigned long} representation of the contents of
+  \var{pylong}.  If \var{pylong} is greater than
+  \constant{ULONG_MAX}\ttindex{ULONG_MAX}, an
+  \exception{OverflowError} is raised.
+  \withsubitem{(built-in exception)}{\ttindex{OverflowError}} 
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{long long}{PyLong_AsLongLong}{PyObject *pylong}
+  Return a C \ctype{long long} from a Python long integer.  If
+  \var{pylong} cannot be represented as a \ctype{long long}, an
+  \exception{OverflowError} will be raised.
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{unsigned long long}{PyLong_AsUnsignedLongLong}{PyObject
+                                                                 *pylong}
+  Return a C \ctype{unsigned long long} from a Python long integer.
+  If \var{pylong} cannot be represented as an \ctype{unsigned long
+  long}, an \exception{OverflowError} will be raised if the value is
+  positive, or a \exception{TypeError} will be raised if the value is
+  negative.
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{double}{PyLong_AsDouble}{PyObject *pylong}
+  Returns a C \ctype{double} representation of the contents of
+  \var{pylong}.  If \var{pylong} cannot be approximately represented
+  as a \ctype{double}, an \exception{OverflowError} exception is
+  raised and \code{-1.0} will be returned.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void*}{PyLong_AsVoidPtr}{PyObject *pylong}
+  Convert a Python integer or long integer \var{pylong} to a C
+  \ctype{void} pointer.  If \var{pylong} cannot be converted, an
+  \exception{OverflowError} will be raised.  This is only assured to
+  produce a usable \ctype{void} pointer for values created with
+  \cfunction{PyLong_FromVoidPtr()}.
+  \versionadded{1.5.2}
+\end{cfuncdesc}
+
+
+\subsection{Floating Point Objects \label{floatObjects}}
+
+\obindex{floating point}
+\begin{ctypedesc}{PyFloatObject}
+  This subtype of \ctype{PyObject} represents a Python floating point
+  object.
+\end{ctypedesc}
+
+\begin{cvardesc}{PyTypeObject}{PyFloat_Type}
+  This instance of \ctype{PyTypeObject} represents the Python floating
+  point type.  This is the same object as \code{types.FloatType}.
+  \withsubitem{(in modules types)}{\ttindex{FloatType}}
+\end{cvardesc}
+
+\begin{cfuncdesc}{int}{PyFloat_Check}{PyObject *p}
+  Returns true if its argument is a \ctype{PyFloatObject} or a subtype
+  of \ctype{PyFloatObject}.
+  \versionchanged[Allowed subtypes to be accepted]{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyFloat_CheckExact}{PyObject *p}
+  Returns true if its argument is a \ctype{PyFloatObject}, but not a
+  subtype of \ctype{PyFloatObject}.
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyFloat_FromDouble}{double v}
+  Creates a \ctype{PyFloatObject} object from \var{v}, or \NULL{} on
+  failure.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{double}{PyFloat_AsDouble}{PyObject *pyfloat}
+  Returns a C \ctype{double} representation of the contents of
+  \var{pyfloat}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{double}{PyFloat_AS_DOUBLE}{PyObject *pyfloat}
+  Returns a C \ctype{double} representation of the contents of
+  \var{pyfloat}, but without error checking.
+\end{cfuncdesc}
+
+
+\subsection{Complex Number Objects \label{complexObjects}}
+
+\obindex{complex number}
+Python's complex number objects are implemented as two distinct types
+when viewed from the C API:  one is the Python object exposed to
+Python programs, and the other is a C structure which represents the
+actual complex number value.  The API provides functions for working
+with both.
+
+\subsubsection{Complex Numbers as C Structures}
+
+Note that the functions which accept these structures as parameters
+and return them as results do so \emph{by value} rather than
+dereferencing them through pointers.  This is consistent throughout
+the API.
+
+\begin{ctypedesc}{Py_complex}
+  The C structure which corresponds to the value portion of a Python
+  complex number object.  Most of the functions for dealing with
+  complex number objects use structures of this type as input or
+  output values, as appropriate.  It is defined as:
+
+\begin{verbatim}
+typedef struct {
+   double real;
+   double imag;
+} Py_complex;
+\end{verbatim}
+\end{ctypedesc}
+
+\begin{cfuncdesc}{Py_complex}{_Py_c_sum}{Py_complex left, Py_complex right}
+  Return the sum of two complex numbers, using the C
+  \ctype{Py_complex} representation.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{Py_complex}{_Py_c_diff}{Py_complex left, Py_complex right}
+  Return the difference between two complex numbers, using the C
+  \ctype{Py_complex} representation.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{Py_complex}{_Py_c_neg}{Py_complex complex}
+  Return the negation of the complex number \var{complex}, using the C
+  \ctype{Py_complex} representation.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{Py_complex}{_Py_c_prod}{Py_complex left, Py_complex right}
+  Return the product of two complex numbers, using the C
+  \ctype{Py_complex} representation.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{Py_complex}{_Py_c_quot}{Py_complex dividend,
+                                          Py_complex divisor}
+  Return the quotient of two complex numbers, using the C
+  \ctype{Py_complex} representation.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{Py_complex}{_Py_c_pow}{Py_complex num, Py_complex exp}
+  Return the exponentiation of \var{num} by \var{exp}, using the C
+  \ctype{Py_complex} representation.
+\end{cfuncdesc}
+
+
+\subsubsection{Complex Numbers as Python Objects}
+
+\begin{ctypedesc}{PyComplexObject}
+  This subtype of \ctype{PyObject} represents a Python complex number
+  object.
+\end{ctypedesc}
+
+\begin{cvardesc}{PyTypeObject}{PyComplex_Type}
+  This instance of \ctype{PyTypeObject} represents the Python complex
+  number type.
+\end{cvardesc}
+
+\begin{cfuncdesc}{int}{PyComplex_Check}{PyObject *p}
+  Returns true if its argument is a \ctype{PyComplexObject} or a
+  subtype of \ctype{PyComplexObject}.
+  \versionchanged[Allowed subtypes to be accepted]{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyComplex_CheckExact}{PyObject *p}
+  Returns true if its argument is a \ctype{PyComplexObject}, but not a
+  subtype of \ctype{PyComplexObject}.
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyComplex_FromCComplex}{Py_complex v}
+  Create a new Python complex number object from a C
+  \ctype{Py_complex} value.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyComplex_FromDoubles}{double real, double imag}
+  Returns a new \ctype{PyComplexObject} object from \var{real} and
+  \var{imag}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{double}{PyComplex_RealAsDouble}{PyObject *op}
+  Returns the real part of \var{op} as a C \ctype{double}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{double}{PyComplex_ImagAsDouble}{PyObject *op}
+  Returns the imaginary part of \var{op} as a C \ctype{double}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{Py_complex}{PyComplex_AsCComplex}{PyObject *op}
+  Returns the \ctype{Py_complex} value of the complex number
+  \var{op}.
+\end{cfuncdesc}
+
+
+
+\section{Sequence Objects \label{sequenceObjects}}
+
+\obindex{sequence}
+Generic operations on sequence objects were discussed in the previous 
+chapter; this section deals with the specific kinds of sequence 
+objects that are intrinsic to the Python language.
+
+
+\subsection{String Objects \label{stringObjects}}
+
+These functions raise \exception{TypeError} when expecting a string
+parameter and are called with a non-string parameter.
+
+\obindex{string}
+\begin{ctypedesc}{PyStringObject}
+  This subtype of \ctype{PyObject} represents a Python string object.
+\end{ctypedesc}
+
+\begin{cvardesc}{PyTypeObject}{PyString_Type}
+  This instance of \ctype{PyTypeObject} represents the Python string
+  type; it is the same object as \code{types.TypeType} in the Python
+  layer.
+  \withsubitem{(in module types)}{\ttindex{StringType}}.
+\end{cvardesc}
+
+\begin{cfuncdesc}{int}{PyString_Check}{PyObject *o}
+  Returns true if the object \var{o} is a string object or an instance
+  of a subtype of the string type.
+  \versionchanged[Allowed subtypes to be accepted]{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyString_CheckExact}{PyObject *o}
+  Returns true if the object \var{o} is a string object, but not an
+  instance of a subtype of the string type.
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyString_FromString}{const char *v}
+  Returns a new string object with the value \var{v} on success, and
+  \NULL{} on failure.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyString_FromStringAndSize}{const char *v,
+                                                         int len}
+  Returns a new string object with the value \var{v} and length
+  \var{len} on success, and \NULL{} on failure.  If \var{v} is
+  \NULL, the contents of the string are uninitialized.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyString_FromFormat}{const char *format, ...}
+  Takes a C \cfunction{printf()}-style \var{format} string and a
+  variable number of arguments, calculates the size of the resulting
+  Python string and returns a string with the values formatted into
+  it.  The variable arguments must be C types and must correspond
+  exactly to the format characters in the \var{format} string.  The
+  following format characters are allowed:
+
+  \begin{tableiii}{l|l|l}{member}{Format Characters}{Type}{Comment}
+    \lineiii{\%\%}{\emph{n/a}}{The literal \% character.}
+    \lineiii{\%c}{int}{A single character, represented as an C int.}
+    \lineiii{\%d}{int}{Exactly equivalent to \code{printf("\%d")}.}
+    \lineiii{\%ld}{long}{Exactly equivalent to \code{printf("\%ld")}.}
+    \lineiii{\%i}{int}{Exactly equivalent to \code{printf("\%i")}.}
+    \lineiii{\%x}{int}{Exactly equivalent to \code{printf("\%x")}.}
+    \lineiii{\%s}{char*}{A null-terminated C character array.}
+    \lineiii{\%p}{void*}{The hex representation of a C pointer.
+	Mostly equivalent to \code{printf("\%p")} except that it is
+	guaranteed to start with the literal \code{0x} regardless of
+	what the platform's \code{printf} yields.}
+  \end{tableiii}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyString_FromFormatV}{const char *format,
+                                                   va_list vargs}
+  Identical to \function{PyString_FromFormat()} except that it takes
+  exactly two arguments.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyString_Size}{PyObject *string}
+  Returns the length of the string in string object \var{string}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyString_GET_SIZE}{PyObject *string}
+  Macro form of \cfunction{PyString_Size()} but without error
+  checking.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{char*}{PyString_AsString}{PyObject *string}
+  Returns a null-terminated representation of the contents of
+  \var{string}.  The pointer refers to the internal buffer of
+  \var{string}, not a copy.  The data must not be modified in any way,
+  unless the string was just created using
+  \code{PyString_FromStringAndSize(NULL, \var{size})}.
+  It must not be deallocated.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{char*}{PyString_AS_STRING}{PyObject *string}
+  Macro form of \cfunction{PyString_AsString()} but without error
+  checking.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyString_AsStringAndSize}{PyObject *obj,
+                                                 char **buffer,
+                                                 int *length}
+  Returns a null-terminated representation of the contents of the
+  object \var{obj} through the output variables \var{buffer} and
+  \var{length}.
+
+  The function accepts both string and Unicode objects as input. For
+  Unicode objects it returns the default encoded version of the
+  object.  If \var{length} is set to \NULL, the resulting buffer may
+  not contain null characters; if it does, the function returns -1 and
+  a \exception{TypeError} is raised.
+
+  The buffer refers to an internal string buffer of \var{obj}, not a
+  copy. The data must not be modified in any way, unless the string
+  was just created using \code{PyString_FromStringAndSize(NULL,
+  \var{size})}.  It must not be deallocated.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyString_Concat}{PyObject **string,
+                                         PyObject *newpart}
+  Creates a new string object in \var{*string} containing the contents
+  of \var{newpart} appended to \var{string}; the caller will own the
+  new reference.  The reference to the old value of \var{string} will
+  be stolen.  If the new string cannot be created, the old reference
+  to \var{string} will still be discarded and the value of
+  \var{*string} will be set to \NULL; the appropriate exception will
+  be set.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyString_ConcatAndDel}{PyObject **string,
+                                               PyObject *newpart}
+  Creates a new string object in \var{*string} containing the contents
+  of \var{newpart} appended to \var{string}.  This version decrements
+  the reference count of \var{newpart}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{_PyString_Resize}{PyObject **string, int newsize}
+  A way to resize a string object even though it is ``immutable''.
+  Only use this to build up a brand new string object; don't use this
+  if the string may already be known in other parts of the code.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyString_Format}{PyObject *format,
+                                              PyObject *args}
+  Returns a new string object from \var{format} and \var{args}.
+  Analogous to \code{\var{format} \%\ \var{args}}.  The \var{args}
+  argument must be a tuple.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyString_InternInPlace}{PyObject **string}
+  Intern the argument \var{*string} in place.  The argument must be
+  the address of a pointer variable pointing to a Python string
+  object.  If there is an existing interned string that is the same as
+  \var{*string}, it sets \var{*string} to it (decrementing the
+  reference count of the old string object and incrementing the
+  reference count of the interned string object), otherwise it leaves
+  \var{*string} alone and interns it (incrementing its reference
+  count).  (Clarification: even though there is a lot of talk about
+  reference counts, think of this function as reference-count-neutral;
+  you own the object after the call if and only if you owned it before
+  the call.)
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyString_InternFromString}{const char *v}
+  A combination of \cfunction{PyString_FromString()} and
+  \cfunction{PyString_InternInPlace()}, returning either a new string
+  object that has been interned, or a new (``owned'') reference to an
+  earlier interned string object with the same value.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyString_Decode}{const char *s,
+                                               int size,
+                                               const char *encoding,
+                                               const char *errors}
+  Creates an object by decoding \var{size} bytes of the encoded
+  buffer \var{s} using the codec registered for
+  \var{encoding}.  \var{encoding} and \var{errors} have the same
+  meaning as the parameters of the same name in the
+  \function{unicode()} built-in function.  The codec to be used is
+  looked up using the Python codec registry.  Returns \NULL{} if
+  an exception was raised by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyString_AsDecodedObject}{PyObject *str,
+                                               const char *encoding,
+                                               const char *errors}
+  Decodes a string object by passing it to the codec registered for
+  \var{encoding} and returns the result as Python
+  object. \var{encoding} and \var{errors} have the same meaning as the
+  parameters of the same name in the string \method{encode()} method.
+  The codec to be used is looked up using the Python codec registry.
+  Returns \NULL{} if an exception was raised by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyString_Encode}{const char *s,
+                                               int size,
+                                               const char *encoding,
+                                               const char *errors}
+  Encodes the \ctype{char} buffer of the given size by passing it to
+  the codec registered for \var{encoding} and returns a Python object.
+  \var{encoding} and \var{errors} have the same meaning as the
+  parameters of the same name in the string \method{encode()} method.
+  The codec to be used is looked up using the Python codec
+  registry.  Returns \NULL{} if an exception was raised by the
+  codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyString_AsEncodedObject}{PyObject *str,
+                                               const char *encoding,
+                                               const char *errors}
+  Encodes a string object using the codec registered for
+  \var{encoding} and returns the result as Python object.
+  \var{encoding} and \var{errors} have the same meaning as the
+  parameters of the same name in the string \method{encode()} method.
+  The codec to be used is looked up using the Python codec registry.
+  Returns \NULL{} if an exception was raised by the codec.
+\end{cfuncdesc}
+
+
+\subsection{Unicode Objects \label{unicodeObjects}}
+\sectionauthor{Marc-Andre Lemburg}{mal@lemburg.com}
+
+%--- Unicode Type -------------------------------------------------------
+
+These are the basic Unicode object types used for the Unicode
+implementation in Python:
+
+\begin{ctypedesc}{Py_UNICODE}
+  This type represents a 16-bit unsigned storage type which is used by
+  Python internally as basis for holding Unicode ordinals.  On
+  platforms where \ctype{wchar_t} is available and also has 16-bits,
+  \ctype{Py_UNICODE} is a typedef alias for \ctype{wchar_t} to enhance
+  native platform compatibility.  On all other platforms,
+  \ctype{Py_UNICODE} is a typedef alias for \ctype{unsigned short}.
+\end{ctypedesc}
+
+\begin{ctypedesc}{PyUnicodeObject}
+  This subtype of \ctype{PyObject} represents a Python Unicode object.
+\end{ctypedesc}
+
+\begin{cvardesc}{PyTypeObject}{PyUnicode_Type}
+  This instance of \ctype{PyTypeObject} represents the Python Unicode
+  type.
+\end{cvardesc}
+
+The following APIs are really C macros and can be used to do fast
+checks and to access internal read-only data of Unicode objects:
+
+\begin{cfuncdesc}{int}{PyUnicode_Check}{PyObject *o}
+  Returns true if the object \var{o} is a Unicode object or an
+  instance of a Unicode subtype.
+  \versionchanged[Allowed subtypes to be accepted]{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyUnicode_CheckExact}{PyObject *o}
+  Returns true if the object \var{o} is a Unicode object, but not an
+  instance of a subtype.
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyUnicode_GET_SIZE}{PyObject *o}
+  Returns the size of the object.  \var{o} has to be a
+  \ctype{PyUnicodeObject} (not checked).
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyUnicode_GET_DATA_SIZE}{PyObject *o}
+  Returns the size of the object's internal buffer in bytes.  \var{o}
+  has to be a \ctype{PyUnicodeObject} (not checked).
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{Py_UNICODE*}{PyUnicode_AS_UNICODE}{PyObject *o}
+  Returns a pointer to the internal \ctype{Py_UNICODE} buffer of the
+  object.  \var{o} has to be a \ctype{PyUnicodeObject} (not checked).
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{const char*}{PyUnicode_AS_DATA}{PyObject *o}
+  Returns a pointer to the internal buffer of the object.
+  \var{o} has to be a \ctype{PyUnicodeObject} (not checked).
+\end{cfuncdesc}
+
+% --- Unicode character properties ---------------------------------------
+
+Unicode provides many different character properties. The most often
+needed ones are available through these macros which are mapped to C
+functions depending on the Python configuration.
+
+\begin{cfuncdesc}{int}{Py_UNICODE_ISSPACE}{Py_UNICODE ch}
+  Returns 1/0 depending on whether \var{ch} is a whitespace
+  character.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{Py_UNICODE_ISLOWER}{Py_UNICODE ch}
+  Returns 1/0 depending on whether \var{ch} is a lowercase character.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{Py_UNICODE_ISUPPER}{Py_UNICODE ch}
+  Returns 1/0 depending on whether \var{ch} is an uppercase
+  character.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{Py_UNICODE_ISTITLE}{Py_UNICODE ch}
+  Returns 1/0 depending on whether \var{ch} is a titlecase character.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{Py_UNICODE_ISLINEBREAK}{Py_UNICODE ch}
+  Returns 1/0 depending on whether \var{ch} is a linebreak character.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{Py_UNICODE_ISDECIMAL}{Py_UNICODE ch}
+  Returns 1/0 depending on whether \var{ch} is a decimal character.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{Py_UNICODE_ISDIGIT}{Py_UNICODE ch}
+  Returns 1/0 depending on whether \var{ch} is a digit character.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{Py_UNICODE_ISNUMERIC}{Py_UNICODE ch}
+  Returns 1/0 depending on whether \var{ch} is a numeric character.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{Py_UNICODE_ISALPHA}{Py_UNICODE ch}
+  Returns 1/0 depending on whether \var{ch} is an alphabetic
+  character.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{Py_UNICODE_ISALNUM}{Py_UNICODE ch}
+  Returns 1/0 depending on whether \var{ch} is an alphanumeric
+  character.
+\end{cfuncdesc}
+
+These APIs can be used for fast direct character conversions:
+
+\begin{cfuncdesc}{Py_UNICODE}{Py_UNICODE_TOLOWER}{Py_UNICODE ch}
+  Returns the character \var{ch} converted to lower case.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{Py_UNICODE}{Py_UNICODE_TOUPPER}{Py_UNICODE ch}
+  Returns the character \var{ch} converted to upper case.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{Py_UNICODE}{Py_UNICODE_TOTITLE}{Py_UNICODE ch}
+  Returns the character \var{ch} converted to title case.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{Py_UNICODE_TODECIMAL}{Py_UNICODE ch}
+  Returns the character \var{ch} converted to a decimal positive
+  integer.  Returns \code{-1} if this is not possible.  Does not raise
+  exceptions.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{Py_UNICODE_TODIGIT}{Py_UNICODE ch}
+  Returns the character \var{ch} converted to a single digit integer.
+  Returns \code{-1} if this is not possible.  Does not raise
+  exceptions.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{double}{Py_UNICODE_TONUMERIC}{Py_UNICODE ch}
+  Returns the character \var{ch} converted to a (positive) double.
+  Returns \code{-1.0} if this is not possible.  Does not raise
+  exceptions.
+\end{cfuncdesc}
+
+% --- Plain Py_UNICODE ---------------------------------------------------
+
+To create Unicode objects and access their basic sequence properties,
+use these APIs:
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_FromUnicode}{const Py_UNICODE *u,
+                                                    int size} 
+  Create a Unicode Object from the Py_UNICODE buffer \var{u} of the
+  given size. \var{u} may be \NULL{} which causes the contents to be
+  undefined. It is the user's responsibility to fill in the needed
+  data.  The buffer is copied into the new object. If the buffer is
+  not \NULL, the return value might be a shared object. Therefore,
+  modification of the resulting Unicode object is only allowed when
+  \var{u} is \NULL.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{Py_UNICODE*}{PyUnicode_AsUnicode}{PyObject *unicode}
+  Return a read-only pointer to the Unicode object's internal
+  \ctype{Py_UNICODE} buffer, \NULL{} if \var{unicode} is not a Unicode
+  object.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyUnicode_GetSize}{PyObject *unicode}
+  Return the length of the Unicode object.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_FromEncodedObject}{PyObject *obj,
+                                                      const char *encoding,
+                                                      const char *errors}
+  Coerce an encoded object \var{obj} to an Unicode object and return a
+  reference with incremented refcount.
+
+  Coercion is done in the following way:
+
+\begin{enumerate}
+\item  Unicode objects are passed back as-is with incremented
+       refcount. \note{These cannot be decoded; passing a non-\NULL{}
+       value for encoding will result in a \exception{TypeError}.}
+
+\item String and other char buffer compatible objects are decoded
+      according to the given encoding and using the error handling
+      defined by errors.  Both can be \NULL{} to have the interface
+      use the default values (see the next section for details).
+
+\item All other objects cause an exception.
+\end{enumerate}
+
+  The API returns \NULL{} if there was an error.  The caller is
+  responsible for decref'ing the returned objects.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_FromObject}{PyObject *obj}
+  Shortcut for \code{PyUnicode_FromEncodedObject(obj, NULL, "strict")}
+  which is used throughout the interpreter whenever coercion to
+  Unicode is needed.
+\end{cfuncdesc}
+
+% --- wchar_t support for platforms which support it ---------------------
+
+If the platform supports \ctype{wchar_t} and provides a header file
+wchar.h, Python can interface directly to this type using the
+following functions. Support is optimized if Python's own
+\ctype{Py_UNICODE} type is identical to the system's \ctype{wchar_t}.
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_FromWideChar}{const wchar_t *w,
+                                                     int size}
+  Create a Unicode object from the \ctype{whcar_t} buffer \var{w} of
+  the given size.  Returns \NULL{} on failure.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyUnicode_AsWideChar}{PyUnicodeObject *unicode,
+                                             wchar_t *w,
+                                             int size}
+  Copies the Unicode object contents into the \ctype{whcar_t} buffer
+  \var{w}.  At most \var{size} \ctype{whcar_t} characters are copied.
+  Returns the number of \ctype{whcar_t} characters copied or -1 in
+  case of an error.
+\end{cfuncdesc}
+
+
+\subsubsection{Built-in Codecs \label{builtinCodecs}}
+
+Python provides a set of builtin codecs which are written in C
+for speed. All of these codecs are directly usable via the
+following functions.
+
+Many of the following APIs take two arguments encoding and
+errors. These parameters encoding and errors have the same semantics
+as the ones of the builtin unicode() Unicode object constructor.
+
+Setting encoding to \NULL{} causes the default encoding to be used
+which is \ASCII.  The file system calls should use
+\cdata{Py_FileSystemDefaultEncoding} as the encoding for file
+names. This variable should be treated as read-only: On some systems,
+it will be a pointer to a static string, on others, it will change at
+run-time, e.g. when the application invokes setlocale.
+
+Error handling is set by errors which may also be set to \NULL{}
+meaning to use the default handling defined for the codec.  Default
+error handling for all builtin codecs is ``strict''
+(\exception{ValueError} is raised).
+
+The codecs all use a similar interface.  Only deviation from the
+following generic ones are documented for simplicity.
+
+% --- Generic Codecs -----------------------------------------------------
+
+These are the generic codec APIs:
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_Decode}{const char *s,
+                                               int size,
+                                               const char *encoding,
+                                               const char *errors}
+  Create a Unicode object by decoding \var{size} bytes of the encoded
+  string \var{s}.  \var{encoding} and \var{errors} have the same
+  meaning as the parameters of the same name in the
+  \function{unicode()} builtin function.  The codec to be used is
+  looked up using the Python codec registry.  Returns \NULL{} if an
+  exception was raised by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_Encode}{const Py_UNICODE *s,
+                                               int size,
+                                               const char *encoding,
+                                               const char *errors}
+  Encodes the \ctype{Py_UNICODE} buffer of the given size and returns
+  a Python string object.  \var{encoding} and \var{errors} have the
+  same meaning as the parameters of the same name in the Unicode
+  \method{encode()} method.  The codec to be used is looked up using
+  the Python codec registry.  Returns \NULL{} if an exception was
+  raised by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_AsEncodedString}{PyObject *unicode,
+                                               const char *encoding,
+                                               const char *errors}
+  Encodes a Unicode object and returns the result as Python string
+  object. \var{encoding} and \var{errors} have the same meaning as the
+  parameters of the same name in the Unicode \method{encode()} method.
+  The codec to be used is looked up using the Python codec registry.
+  Returns \NULL{} if an exception was raised by the codec.
+\end{cfuncdesc}
+
+% --- UTF-8 Codecs -------------------------------------------------------
+
+These are the UTF-8 codec APIs:
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF8}{const char *s,
+                                               int size,
+                                               const char *errors}
+  Creates a Unicode object by decoding \var{size} bytes of the UTF-8
+  encoded string \var{s}. Returns \NULL{} if an exception was raised
+  by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeUTF8}{const Py_UNICODE *s,
+                                               int size,
+                                               const char *errors}
+  Encodes the \ctype{Py_UNICODE} buffer of the given size using UTF-8
+  and returns a Python string object.  Returns \NULL{} if an exception
+  was raised by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_AsUTF8String}{PyObject *unicode}
+  Encodes a Unicode objects using UTF-8 and returns the result as
+  Python string object.  Error handling is ``strict''.  Returns
+  \NULL{} if an exception was raised by the codec.
+\end{cfuncdesc}
+
+% --- UTF-16 Codecs ------------------------------------------------------ */
+
+These are the UTF-16 codec APIs:
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF16}{const char *s,
+                                               int size,
+                                               const char *errors,
+                                               int *byteorder}
+  Decodes \var{length} bytes from a UTF-16 encoded buffer string and
+  returns the corresponding Unicode object.  \var{errors} (if
+  non-\NULL) defines the error handling. It defaults to ``strict''.
+
+  If \var{byteorder} is non-\NULL, the decoder starts decoding using
+  the given byte order:
+
+\begin{verbatim}
+   *byteorder == -1: little endian
+   *byteorder == 0:  native order
+   *byteorder == 1:  big endian
+\end{verbatim}
+
+  and then switches according to all byte order marks (BOM) it finds
+  in the input data.  BOMs are not copied into the resulting Unicode
+  string.  After completion, \var{*byteorder} is set to the current
+  byte order at the end of input data.
+
+  If \var{byteorder} is \NULL, the codec starts in native order mode.
+
+  Returns \NULL{} if an exception was raised by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeUTF16}{const Py_UNICODE *s,
+                                               int size,
+                                               const char *errors,
+                                               int byteorder}
+  Returns a Python string object holding the UTF-16 encoded value of
+  the Unicode data in \var{s}.  If \var{byteorder} is not \code{0},
+  output is written according to the following byte order:
+
+\begin{verbatim}
+   byteorder == -1: little endian
+   byteorder == 0:  native byte order (writes a BOM mark)
+   byteorder == 1:  big endian
+\end{verbatim}
+
+  If byteorder is \code{0}, the output string will always start with
+  the Unicode BOM mark (U+FEFF). In the other two modes, no BOM mark
+  is prepended.
+
+  Note that \ctype{Py_UNICODE} data is being interpreted as UTF-16
+  reduced to UCS-2. This trick makes it possible to add full UTF-16
+  capabilities at a later point without comprimising the APIs.
+
+  Returns \NULL{} if an exception was raised by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_AsUTF16String}{PyObject *unicode}
+  Returns a Python string using the UTF-16 encoding in native byte
+  order. The string always starts with a BOM mark.  Error handling is
+  ``strict''.  Returns \NULL{} if an exception was raised by the
+  codec.
+\end{cfuncdesc}
+
+% --- Unicode-Escape Codecs ----------------------------------------------
+
+These are the ``Unicode Esacpe'' codec APIs:
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUnicodeEscape}{const char *s,
+                                               int size,
+                                               const char *errors}
+  Creates a Unicode object by decoding \var{size} bytes of the
+  Unicode-Escape encoded string \var{s}.  Returns \NULL{} if an
+  exception was raised by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeUnicodeEscape}{const Py_UNICODE *s,
+                                               int size,
+                                               const char *errors}
+  Encodes the \ctype{Py_UNICODE} buffer of the given size using
+  Unicode-Escape and returns a Python string object.  Returns \NULL{}
+  if an exception was raised by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_AsUnicodeEscapeString}{PyObject *unicode}
+  Encodes a Unicode objects using Unicode-Escape and returns the
+  result as Python string object.  Error handling is ``strict''.
+  Returns \NULL{} if an exception was raised by the codec.
+\end{cfuncdesc}
+
+% --- Raw-Unicode-Escape Codecs ------------------------------------------
+
+These are the ``Raw Unicode Esacpe'' codec APIs:
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeRawUnicodeEscape}{const char *s,
+                                               int size,
+                                               const char *errors}
+  Creates a Unicode object by decoding \var{size} bytes of the
+  Raw-Unicode-Esacpe encoded string \var{s}.  Returns \NULL{} if an
+  exception was raised by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeRawUnicodeEscape}{const Py_UNICODE *s,
+                                               int size,
+                                               const char *errors}
+  Encodes the \ctype{Py_UNICODE} buffer of the given size using
+  Raw-Unicode-Escape and returns a Python string object.  Returns
+  \NULL{} if an exception was raised by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_AsRawUnicodeEscapeString}{PyObject *unicode}
+  Encodes a Unicode objects using Raw-Unicode-Escape and returns the
+  result as Python string object. Error handling is ``strict''.
+  Returns \NULL{} if an exception was raised by the codec.
+\end{cfuncdesc}
+
+% --- Latin-1 Codecs ----------------------------------------------------- 
+
+These are the Latin-1 codec APIs:
+Latin-1 corresponds to the first 256 Unicode ordinals and only these
+are accepted by the codecs during encoding.
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeLatin1}{const char *s,
+                                                     int size,
+                                                     const char *errors}
+  Creates a Unicode object by decoding \var{size} bytes of the Latin-1
+  encoded string \var{s}.  Returns \NULL{} if an exception was raised
+  by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeLatin1}{const Py_UNICODE *s,
+                                                     int size,
+                                                     const char *errors}
+  Encodes the \ctype{Py_UNICODE} buffer of the given size using
+  Latin-1 and returns a Python string object.  Returns \NULL{} if an
+  exception was raised by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_AsLatin1String}{PyObject *unicode}
+  Encodes a Unicode objects using Latin-1 and returns the result as
+  Python string object.  Error handling is ``strict''.  Returns
+  \NULL{} if an exception was raised by the codec.
+\end{cfuncdesc}
+
+% --- ASCII Codecs ------------------------------------------------------- 
+
+These are the \ASCII{} codec APIs.  Only 7-bit \ASCII{} data is
+accepted. All other codes generate errors.
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeASCII}{const char *s,
+                                                    int size,
+                                                    const char *errors}
+  Creates a Unicode object by decoding \var{size} bytes of the
+  \ASCII{} encoded string \var{s}.  Returns \NULL{} if an exception
+  was raised by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeASCII}{const Py_UNICODE *s,
+                                                    int size,
+                                                    const char *errors}
+  Encodes the \ctype{Py_UNICODE} buffer of the given size using
+  \ASCII{} and returns a Python string object.  Returns \NULL{} if an
+  exception was raised by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_AsASCIIString}{PyObject *unicode}
+  Encodes a Unicode objects using \ASCII{} and returns the result as
+  Python string object.  Error handling is ``strict''.  Returns
+  \NULL{} if an exception was raised by the codec.
+\end{cfuncdesc}
+
+% --- Character Map Codecs ----------------------------------------------- 
+
+These are the mapping codec APIs:
+
+This codec is special in that it can be used to implement many
+different codecs (and this is in fact what was done to obtain most of
+the standard codecs included in the \module{encodings} package). The
+codec uses mapping to encode and decode characters.
+
+Decoding mappings must map single string characters to single Unicode
+characters, integers (which are then interpreted as Unicode ordinals)
+or None (meaning "undefined mapping" and causing an error). 
+
+Encoding mappings must map single Unicode characters to single string
+characters, integers (which are then interpreted as Latin-1 ordinals)
+or None (meaning "undefined mapping" and causing an error).
+
+The mapping objects provided must only support the __getitem__ mapping
+interface.
+
+If a character lookup fails with a LookupError, the character is
+copied as-is meaning that its ordinal value will be interpreted as
+Unicode or Latin-1 ordinal resp. Because of this, mappings only need
+to contain those mappings which map characters to different code
+points.
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeCharmap}{const char *s,
+                                               int size,
+                                               PyObject *mapping,
+                                               const char *errors}
+  Creates a Unicode object by decoding \var{size} bytes of the encoded
+  string \var{s} using the given \var{mapping} object.  Returns
+  \NULL{} if an exception was raised by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeCharmap}{const Py_UNICODE *s,
+                                               int size,
+                                               PyObject *mapping,
+                                               const char *errors}
+  Encodes the \ctype{Py_UNICODE} buffer of the given size using the
+  given \var{mapping} object and returns a Python string object.
+  Returns \NULL{} if an exception was raised by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_AsCharmapString}{PyObject *unicode,
+                                                        PyObject *mapping}
+  Encodes a Unicode objects using the given \var{mapping} object and
+  returns the result as Python string object.  Error handling is
+  ``strict''.  Returns \NULL{} if an exception was raised by the
+  codec.
+\end{cfuncdesc}
+
+The following codec API is special in that maps Unicode to Unicode.
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_TranslateCharmap}{const Py_UNICODE *s,
+                                               int size,
+                                               PyObject *table,
+                                               const char *errors}
+  Translates a \ctype{Py_UNICODE} buffer of the given length by
+  applying a character mapping \var{table} to it and returns the
+  resulting Unicode object.  Returns \NULL{} when an exception was
+  raised by the codec.
+
+  The \var{mapping} table must map Unicode ordinal integers to Unicode
+  ordinal integers or None (causing deletion of the character).
+
+  Mapping tables need only provide the method{__getitem__()}
+  interface; dictionaries and sequences work well.  Unmapped character
+  ordinals (ones which cause a \exception{LookupError}) are left
+  untouched and are copied as-is.
+\end{cfuncdesc}
+
+% --- MBCS codecs for Windows --------------------------------------------
+
+These are the MBCS codec APIs. They are currently only available on
+Windows and use the Win32 MBCS converters to implement the
+conversions.  Note that MBCS (or DBCS) is a class of encodings, not
+just one.  The target encoding is defined by the user settings on the
+machine running the codec.
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeMBCS}{const char *s,
+                                               int size,
+                                               const char *errors}
+  Creates a Unicode object by decoding \var{size} bytes of the MBCS
+  encoded string \var{s}.  Returns \NULL{} if an exception was
+  raised by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeMBCS}{const Py_UNICODE *s,
+                                               int size,
+                                               const char *errors}
+  Encodes the \ctype{Py_UNICODE} buffer of the given size using MBCS
+  and returns a Python string object.  Returns \NULL{} if an exception
+  was raised by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_AsMBCSString}{PyObject *unicode}
+  Encodes a Unicode objects using MBCS and returns the result as
+  Python string object.  Error handling is ``strict''.  Returns
+  \NULL{} if an exception was raised by the codec.
+\end{cfuncdesc}
+
+% --- Methods & Slots ----------------------------------------------------
+
+\subsubsection{Methods and Slot Functions \label{unicodeMethodsAndSlots}}
+
+The following APIs are capable of handling Unicode objects and strings
+on input (we refer to them as strings in the descriptions) and return
+Unicode objects or integers as apporpriate.
+
+They all return \NULL{} or \code{-1} if an exception occurs.
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_Concat}{PyObject *left,
+                                               PyObject *right}
+  Concat two strings giving a new Unicode string.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_Split}{PyObject *s,
+                                              PyObject *sep,
+                                              int maxsplit}
+  Split a string giving a list of Unicode strings.  If sep is \NULL,
+  splitting will be done at all whitespace substrings.  Otherwise,
+  splits occur at the given separator.  At most \var{maxsplit} splits
+  will be done.  If negative, no limit is set.  Separators are not
+  included in the resulting list.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_Splitlines}{PyObject *s,
+                                                   int maxsplit}
+  Split a Unicode string at line breaks, returning a list of Unicode
+  strings.  CRLF is considered to be one line break.  The Line break
+  characters are not included in the resulting strings.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_Translate}{PyObject *str,
+                                                  PyObject *table,
+                                                  const char *errors}
+  Translate a string by applying a character mapping table to it and
+  return the resulting Unicode object.
+
+  The mapping table must map Unicode ordinal integers to Unicode
+  ordinal integers or None (causing deletion of the character).
+
+  Mapping tables need only provide the \method{__getitem__()}
+  interface; dictionaries and sequences work well.  Unmapped character
+  ordinals (ones which cause a \exception{LookupError}) are left
+  untouched and are copied as-is.
+
+  \var{errors} has the usual meaning for codecs. It may be \NULL{}
+  which indicates to use the default error handling.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_Join}{PyObject *separator,
+                                             PyObject *seq}
+  Join a sequence of strings using the given separator and return the
+  resulting Unicode string.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_Tailmatch}{PyObject *str,
+                                                  PyObject *substr,
+                                                  int start,
+                                                  int end,
+                                                  int direction}
+  Return 1 if \var{substr} matches \var{str}[\var{start}:\var{end}] at
+  the given tail end (\var{direction} == -1 means to do a prefix
+  match, \var{direction} == 1 a suffix match), 0 otherwise.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_Find}{PyObject *str,
+                                                  PyObject *substr,
+                                                  int start,
+                                                  int end,
+                                                  int direction}
+  Return the first position of \var{substr} in
+  \var{str}[\var{start}:\var{end}] using the given \var{direction}
+  (\var{direction} == 1 means to do a forward search,
+  \var{direction} == -1 a backward search), 0 otherwise.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_Count}{PyObject *str,
+                                                  PyObject *substr,
+                                                  int start,
+                                                  int end}
+  Count the number of occurrences of \var{substr} in
+  \var{str}[\var{start}:\var{end}]
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_Replace}{PyObject *str,
+                                                PyObject *substr,
+                                                PyObject *replstr,
+                                                int maxcount}
+  Replace at most \var{maxcount} occurrences of \var{substr} in
+  \var{str} with \var{replstr} and return the resulting Unicode object.
+  \var{maxcount} == -1 means replace all occurrences.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyUnicode_Compare}{PyObject *left, PyObject *right}
+  Compare two strings and return -1, 0, 1 for less than, equal, and
+  greater than, respectively.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_Format}{PyObject *format,
+                                              PyObject *args}
+  Returns a new string object from \var{format} and \var{args}; this
+  is analogous to \code{\var{format} \%\ \var{args}}.  The
+  \var{args} argument must be a tuple.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyUnicode_Contains}{PyObject *container,
+                                           PyObject *element}
+  Checks whether \var{element} is contained in \var{container} and
+  returns true or false accordingly.
+
+  \var{element} has to coerce to a one element Unicode
+  string. \code{-1} is returned if there was an error.
+\end{cfuncdesc}
+
+
+\subsection{Buffer Objects \label{bufferObjects}}
+\sectionauthor{Greg Stein}{gstein@lyra.org}
+
+\obindex{buffer}
+Python objects implemented in C can export a group of functions called
+the ``buffer\index{buffer interface} interface.''  These functions can
+be used by an object to expose its data in a raw, byte-oriented
+format. Clients of the object can use the buffer interface to access
+the object data directly, without needing to copy it first.
+
+Two examples of objects that support 
+the buffer interface are strings and arrays. The string object exposes 
+the character contents in the buffer interface's byte-oriented
+form. An array can also expose its contents, but it should be noted
+that array elements may be multi-byte values.
+
+An example user of the buffer interface is the file object's
+\method{write()} method. Any object that can export a series of bytes
+through the buffer interface can be written to a file. There are a
+number of format codes to \cfunction{PyArg_ParseTuple()} that operate 
+against an object's buffer interface, returning data from the target
+object.
+
+More information on the buffer interface is provided in the section
+``Buffer Object Structures'' (section \ref{buffer-structs}), under
+the description for \ctype{PyBufferProcs}\ttindex{PyBufferProcs}.
+
+A ``buffer object'' is defined in the \file{bufferobject.h} header
+(included by \file{Python.h}). These objects look very similar to
+string objects at the Python programming level: they support slicing,
+indexing, concatenation, and some other standard string
+operations. However, their data can come from one of two sources: from
+a block of memory, or from another object which exports the buffer
+interface.
+
+Buffer objects are useful as a way to expose the data from another
+object's buffer interface to the Python programmer. They can also be
+used as a zero-copy slicing mechanism. Using their ability to
+reference a block of memory, it is possible to expose any data to the
+Python programmer quite easily. The memory could be a large, constant
+array in a C extension, it could be a raw block of memory for
+manipulation before passing to an operating system library, or it
+could be used to pass around structured data in its native, in-memory
+format.
+
+\begin{ctypedesc}{PyBufferObject}
+  This subtype of \ctype{PyObject} represents a buffer object.
+\end{ctypedesc}
+
+\begin{cvardesc}{PyTypeObject}{PyBuffer_Type}
+  The instance of \ctype{PyTypeObject} which represents the Python
+  buffer type; it is the same object as \code{types.BufferType} in the
+  Python layer.\withsubitem{(in module types)}{\ttindex{BufferType}}.
+\end{cvardesc}
+
+\begin{cvardesc}{int}{Py_END_OF_BUFFER}
+  This constant may be passed as the \var{size} parameter to
+  \cfunction{PyBuffer_FromObject()} or
+  \cfunction{PyBuffer_FromReadWriteObject()}.  It indicates that the
+  new \ctype{PyBufferObject} should refer to \var{base} object from
+  the specified \var{offset} to the end of its exported buffer.  Using
+  this enables the caller to avoid querying the \var{base} object for
+  its length.
+\end{cvardesc}
+
+\begin{cfuncdesc}{int}{PyBuffer_Check}{PyObject *p}
+  Return true if the argument has type \cdata{PyBuffer_Type}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyBuffer_FromObject}{PyObject *base,
+                                                  int offset, int size}
+  Return a new read-only buffer object.  This raises
+  \exception{TypeError} if \var{base} doesn't support the read-only
+  buffer protocol or doesn't provide exactly one buffer segment, or it
+  raises \exception{ValueError} if \var{offset} is less than zero. The
+  buffer will hold a reference to the \var{base} object, and the
+  buffer's contents will refer to the \var{base} object's buffer
+  interface, starting as position \var{offset} and extending for
+  \var{size} bytes. If \var{size} is \constant{Py_END_OF_BUFFER}, then
+  the new buffer's contents extend to the length of the \var{base}
+  object's exported buffer data.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyBuffer_FromReadWriteObject}{PyObject *base,
+                                                           int offset,
+                                                           int size}
+  Return a new writable buffer object.  Parameters and exceptions are
+  similar to those for \cfunction{PyBuffer_FromObject()}.  If the
+  \var{base} object does not export the writeable buffer protocol,
+  then \exception{TypeError} is raised.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyBuffer_FromMemory}{void *ptr, int size}
+  Return a new read-only buffer object that reads from a specified
+  location in memory, with a specified size.  The caller is
+  responsible for ensuring that the memory buffer, passed in as
+  \var{ptr}, is not deallocated while the returned buffer object
+  exists.  Raises \exception{ValueError} if \var{size} is less than
+  zero.  Note that \constant{Py_END_OF_BUFFER} may \emph{not} be
+  passed for the \var{size} parameter; \exception{ValueError} will be
+  raised in that case.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyBuffer_FromReadWriteMemory}{void *ptr, int size}
+  Similar to \cfunction{PyBuffer_FromMemory()}, but the returned
+  buffer is writable.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyBuffer_New}{int size}
+  Returns a new writable buffer object that maintains its own memory
+  buffer of \var{size} bytes.  \exception{ValueError} is returned if
+  \var{size} is not zero or positive.
+\end{cfuncdesc}
+
+
+\subsection{Tuple Objects \label{tupleObjects}}
+
+\obindex{tuple}
+\begin{ctypedesc}{PyTupleObject}
+  This subtype of \ctype{PyObject} represents a Python tuple object.
+\end{ctypedesc}
+
+\begin{cvardesc}{PyTypeObject}{PyTuple_Type}
+  This instance of \ctype{PyTypeObject} represents the Python tuple
+  type; it is the same object as \code{types.TupleType} in the Python
+  layer.\withsubitem{(in module types)}{\ttindex{TupleType}}.
+\end{cvardesc}
+
+\begin{cfuncdesc}{int}{PyTuple_Check}{PyObject *p}
+  Return true if \var{p} is a tuple object or an instance of a subtype
+  of the tuple type.
+  \versionchanged[Allowed subtypes to be accepted]{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyTuple_CheckExact}{PyObject *p}
+  Return true if \var{p} is a tuple object, but not an instance of a
+  subtype of the tuple type.
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyTuple_New}{int len}
+  Return a new tuple object of size \var{len}, or \NULL{} on failure.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyTuple_Size}{PyObject *p}
+  Takes a pointer to a tuple object, and returns the size of that
+  tuple.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyTuple_GET_SIZE}{PyObject *p}
+  Return the size of the tuple \var{p}, which must be non-\NULL{} and
+  point to a tuple; no error checking is performed.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyTuple_GetItem}{PyObject *p, int pos}
+  Returns the object at position \var{pos} in the tuple pointed to by
+  \var{p}.  If \var{pos} is out of bounds, returns \NULL{} and sets an
+  \exception{IndexError} exception.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyTuple_GET_ITEM}{PyObject *p, int pos}
+  Like \cfunction{PyTuple_GetItem()}, but does no checking of its
+  arguments.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyTuple_GetSlice}{PyObject *p,
+                                               int low, int high}
+  Takes a slice of the tuple pointed to by \var{p} from \var{low} to
+  \var{high} and returns it as a new tuple.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyTuple_SetItem}{PyObject *p,
+                                        int pos, PyObject *o}
+  Inserts a reference to object \var{o} at position \var{pos} of the
+  tuple pointed to by \var{p}. It returns \code{0} on success.
+  \note{This function ``steals'' a reference to \var{o}.}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyTuple_SET_ITEM}{PyObject *p,
+                                          int pos, PyObject *o}
+  Like \cfunction{PyTuple_SetItem()}, but does no error checking, and
+  should \emph{only} be used to fill in brand new tuples.  \note{This
+  function ``steals'' a reference to \var{o}.}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{_PyTuple_Resize}{PyObject **p, int newsize}
+  Can be used to resize a tuple.  \var{newsize} will be the new length
+  of the tuple.  Because tuples are \emph{supposed} to be immutable,
+  this should only be used if there is only one reference to the
+  object.  Do \emph{not} use this if the tuple may already be known to
+  some other part of the code.  The tuple will always grow or shrink
+  at the end.  Think of this as destroying the old tuple and creating
+  a new one, only more efficiently.  Returns \code{0} on success.
+  Client code should never assume that the resulting value of
+  \code{*\var{p}} will be the same as before calling this function.
+  If the object referenced by \code{*\var{p}} is replaced, the
+  original \code{*\var{p}} is destroyed.  On failure, returns
+  \code{-1} and sets \code{*\var{p}} to \NULL, and raises
+  \exception{MemoryError} or
+  \exception{SystemError}.
+  \versionchanged[Removed unused third parameter, \var{last_is_sticky}]{2.2} 
+\end{cfuncdesc}
+
+
+\subsection{List Objects \label{listObjects}}
+
+\obindex{list}
+\begin{ctypedesc}{PyListObject}
+  This subtype of \ctype{PyObject} represents a Python list object.
+\end{ctypedesc}
+
+\begin{cvardesc}{PyTypeObject}{PyList_Type}
+  This instance of \ctype{PyTypeObject} represents the Python list
+  type.  This is the same object as \code{types.ListType}.
+  \withsubitem{(in module types)}{\ttindex{ListType}}
+\end{cvardesc}
+
+\begin{cfuncdesc}{int}{PyList_Check}{PyObject *p}
+  Returns true if its argument is a \ctype{PyListObject}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyList_New}{int len}
+  Returns a new list of length \var{len} on success, or \NULL{} on
+  failure.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyList_Size}{PyObject *list}
+  Returns the length of the list object in \var{list}; this is
+  equivalent to \samp{len(\var{list})} on a list object.
+  \bifuncindex{len}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyList_GET_SIZE}{PyObject *list}
+  Macro form of \cfunction{PyList_Size()} without error checking.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyList_GetItem}{PyObject *list, int index}
+  Returns the object at position \var{pos} in the list pointed to by
+  \var{p}.  If \var{pos} is out of bounds, returns \NULL{} and sets an
+  \exception{IndexError} exception.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyList_GET_ITEM}{PyObject *list, int i}
+  Macro form of \cfunction{PyList_GetItem()} without error checking.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyList_SetItem}{PyObject *list, int index,
+                                       PyObject *item}
+  Sets the item at index \var{index} in list to \var{item}.  Returns
+  \code{0} on success or \code{-1} on failure.  \note{This function
+  ``steals'' a reference to \var{item} and discards a reference to an
+  item already in the list at the affected position.}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyList_SET_ITEM}{PyObject *list, int i,
+                                              PyObject *o}
+  Macro form of \cfunction{PyList_SetItem()} without error checking.
+  This is normally only used to fill in new lists where there is no
+  previous content.
+  \note{This function ``steals'' a reference to \var{item}, and,
+  unlike \cfunction{PyList_SetItem()}, does \emph{not} discard a
+  reference to any item that it being replaced; any reference in
+  \var{list} at position \var{i} will be leaked.}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyList_Insert}{PyObject *list, int index,
+                                      PyObject *item}
+  Inserts the item \var{item} into list \var{list} in front of index
+  \var{index}.  Returns \code{0} if successful; returns \code{-1} and
+  raises an exception if unsuccessful.  Analogous to
+  \code{\var{list}.insert(\var{index}, \var{item})}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyList_Append}{PyObject *list, PyObject *item}
+  Appends the object \var{item} at the end of list \var{list}.
+  Returns \code{0} if successful; returns \code{-1} and sets an
+  exception if unsuccessful.  Analogous to
+  \code{\var{list}.append(\var{item})}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyList_GetSlice}{PyObject *list,
+                                              int low, int high}
+  Returns a list of the objects in \var{list} containing the objects
+  \emph{between} \var{low} and \var{high}.  Returns \NULL{} and sets
+  an exception if unsuccessful.
+  Analogous to \code{\var{list}[\var{low}:\var{high}]}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyList_SetSlice}{PyObject *list,
+                                        int low, int high,
+                                        PyObject *itemlist}
+  Sets the slice of \var{list} between \var{low} and \var{high} to the
+  contents of \var{itemlist}.  Analogous to
+  \code{\var{list}[\var{low}:\var{high}] = \var{itemlist}}.  Returns
+  \code{0} on success, \code{-1} on failure.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyList_Sort}{PyObject *list}
+  Sorts the items of \var{list} in place.  Returns \code{0} on
+  success, \code{-1} on failure.  This is equivalent to
+  \samp{\var{list}.sort()}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyList_Reverse}{PyObject *list}
+  Reverses the items of \var{list} in place.  Returns \code{0} on
+  success, \code{-1} on failure.  This is the equivalent of
+  \samp{\var{list}.reverse()}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyList_AsTuple}{PyObject *list}
+  Returns a new tuple object containing the contents of \var{list};
+  equivalent to \samp{tuple(\var{list})}.\bifuncindex{tuple}
+\end{cfuncdesc}
+
+
+\section{Mapping Objects \label{mapObjects}}
+
+\obindex{mapping}
+
+
+\subsection{Dictionary Objects \label{dictObjects}}
+
+\obindex{dictionary}
+\begin{ctypedesc}{PyDictObject}
+  This subtype of \ctype{PyObject} represents a Python dictionary
+  object.
+\end{ctypedesc}
+
+\begin{cvardesc}{PyTypeObject}{PyDict_Type}
+  This instance of \ctype{PyTypeObject} represents the Python
+  dictionary type.  This is exposed to Python programs as
+  \code{types.DictType} and \code{types.DictionaryType}.
+  \withsubitem{(in module types)}{\ttindex{DictType}\ttindex{DictionaryType}}
+\end{cvardesc}
+
+\begin{cfuncdesc}{int}{PyDict_Check}{PyObject *p}
+  Returns true if its argument is a \ctype{PyDictObject}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyDict_New}{}
+  Returns a new empty dictionary, or \NULL{} on failure.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyDictProxy_New}{PyObject *dict}
+  Return a proxy object for a mapping which enforces read-only
+  behavior.  This is normally used to create a proxy to prevent
+  modification of the dictionary for non-dynamic class types.
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyDict_Clear}{PyObject *p}
+  Empties an existing dictionary of all key-value pairs.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyDict_Copy}{PyObject *p}
+  Returns a new dictionary that contains the same key-value pairs as
+  \var{p}.
+  \versionadded{1.6}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyDict_SetItem}{PyObject *p, PyObject *key,
+                                       PyObject *val}
+  Inserts \var{value} into the dictionary \var{p} with a key of
+  \var{key}.  \var{key} must be hashable; if it isn't,
+  \exception{TypeError} will be raised.
+  Returns \code{0} on success or \code{-1} on failure.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyDict_SetItemString}{PyObject *p,
+            char *key,
+            PyObject *val}
+  Inserts \var{value} into the dictionary \var{p} using \var{key} as a
+  key. \var{key} should be a \ctype{char*}.  The key object is created
+  using \code{PyString_FromString(\var{key})}. Returns \code{0} on
+  success or \code{-1} on failure.
+  \ttindex{PyString_FromString()}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyDict_DelItem}{PyObject *p, PyObject *key}
+  Removes the entry in dictionary \var{p} with key \var{key}.
+  \var{key} must be hashable; if it isn't, \exception{TypeError} is
+  raised.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyDict_DelItemString}{PyObject *p, char *key}
+  Removes the entry in dictionary \var{p} which has a key specified by
+  the string \var{key}.  Returns \code{0} on success or \code{-1} on
+  failure.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyDict_GetItem}{PyObject *p, PyObject *key}
+  Returns the object from dictionary \var{p} which has a key
+  \var{key}.  Returns \NULL{} if the key \var{key} is not present, but
+  \emph{without} setting an exception.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyDict_GetItemString}{PyObject *p, char *key}
+  This is the same as \cfunction{PyDict_GetItem()}, but \var{key} is
+  specified as a \ctype{char*}, rather than a \ctype{PyObject*}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyDict_Items}{PyObject *p}
+  Returns a \ctype{PyListObject} containing all the items from the
+  dictionary, as in the dictinoary method \method{items()} (see the
+  \citetitle[../lib/lib.html]{Python Library Reference}).
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyDict_Keys}{PyObject *p}
+  Returns a \ctype{PyListObject} containing all the keys from the
+  dictionary, as in the dictionary method \method{keys()} (see the
+  \citetitle[../lib/lib.html]{Python Library Reference}).
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyDict_Values}{PyObject *p}
+  Returns a \ctype{PyListObject} containing all the values from the
+  dictionary \var{p}, as in the dictionary method \method{values()}
+  (see the \citetitle[../lib/lib.html]{Python Library Reference}).
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyDict_Size}{PyObject *p}
+  Returns the number of items in the dictionary.  This is equivalent
+  to \samp{len(\var{p})} on a dictionary.\bifuncindex{len}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyDict_Next}{PyObject *p, int *ppos,
+                                    PyObject **pkey, PyObject **pvalue}
+  Iterate over all key-value pairs in the dictionary \var{p}.  The
+  \ctype{int} referred to by \var{ppos} must be initialized to
+  \code{0} prior to the first call to this function to start the
+  iteration; the function returns true for each pair in the
+  dictionary, and false once all pairs have been reported.  The
+  parameters \var{pkey} and \var{pvalue} should either point to
+  \ctype{PyObject*} variables that will be filled in with each key and
+  value, respectively, or may be \NULL.
+
+  For example:
+
+\begin{verbatim}
+PyObject *key, *value;
+int pos = 0;
+
+while (PyDict_Next(self->dict, &pos, &key, &value)) {
+    /* do something interesting with the values... */
+    ...
+}
+\end{verbatim}
+
+  The dictionary \var{p} should not be mutated during iteration.  It
+  is safe (since Python 2.1) to modify the values of the keys as you
+  iterate over the dictionary, but only so long as the set of keys
+  does not change.  For example:
+
+\begin{verbatim}
+PyObject *key, *value;
+int pos = 0;
+
+while (PyDict_Next(self->dict, &pos, &key, &value)) {
+    int i = PyInt_AS_LONG(value) + 1;
+    PyObject *o = PyInt_FromLong(i);
+    if (o == NULL)
+        return -1;
+    if (PyDict_SetItem(self->dict, key, o) < 0) {
+        Py_DECREF(o);
+        return -1;
+    }
+    Py_DECREF(o);
+}
+\end{verbatim}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyDict_Merge}{PyObject *a, PyObject *b, int override}
+  Iterate over dictionary \var{b} adding key-value pairs to dictionary
+  \var{a}.  If \var{override} is true, existing pairs in \var{a} will
+  be replaced if a matching key is found in \var{b}, otherwise pairs
+  will only be added if there is not a matching key in \var{a}.
+  Returns \code{0} on success or \code{-1} if an exception was
+  raised.
+\versionadded{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyDict_Update}{PyObject *a, PyObject *b}
+  This is the same as \code{PyDict_Merge(\var{a}, \var{b}, 1)} in C,
+  or \code{\var{a}.update(\var{b})} in Python.  Returns \code{0} on
+  success or \code{-1} if an exception was raised.
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+
+\section{Other Objects \label{otherObjects}}
+
+\subsection{File Objects \label{fileObjects}}
+
+\obindex{file}
+Python's built-in file objects are implemented entirely on the
+\ctype{FILE*} support from the C standard library.  This is an
+implementation detail and may change in future releases of Python.
+
+\begin{ctypedesc}{PyFileObject}
+  This subtype of \ctype{PyObject} represents a Python file object.
+\end{ctypedesc}
+
+\begin{cvardesc}{PyTypeObject}{PyFile_Type}
+  This instance of \ctype{PyTypeObject} represents the Python file
+  type.  This is exposed to Python programs as \code{types.FileType}.
+  \withsubitem{(in module types)}{\ttindex{FileType}}
+\end{cvardesc}
+
+\begin{cfuncdesc}{int}{PyFile_Check}{PyObject *p}
+  Returns true if its argument is a \ctype{PyFileObject} or a subtype
+  of \ctype{PyFileObject}.
+  \versionchanged[Allowed subtypes to be accepted]{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyFile_CheckExact}{PyObject *p}
+  Returns true if its argument is a \ctype{PyFileObject}, but not a
+  subtype of \ctype{PyFileObject}.
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyFile_FromString}{char *filename, char *mode}
+  On success, returns a new file object that is opened on the file
+  given by \var{filename}, with a file mode given by \var{mode}, where
+  \var{mode} has the same semantics as the standard C routine
+  \cfunction{fopen()}\ttindex{fopen()}.  On failure, returns \NULL.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyFile_FromFile}{FILE *fp,
+                                              char *name, char *mode,
+                                              int (*close)(FILE*)}
+  Creates a new \ctype{PyFileObject} from the already-open standard C
+  file pointer, \var{fp}.  The function \var{close} will be called
+  when the file should be closed.  Returns \NULL{} on failure.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{FILE*}{PyFile_AsFile}{PyFileObject *p}
+  Returns the file object associated with \var{p} as a \ctype{FILE*}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyFile_GetLine}{PyObject *p, int n}
+  Equivalent to \code{\var{p}.readline(\optional{\var{n}})}, this
+  function reads one line from the object \var{p}.  \var{p} may be a
+  file object or any object with a \method{readline()} method.  If
+  \var{n} is \code{0}, exactly one line is read, regardless of the
+  length of the line.  If \var{n} is greater than \code{0}, no more
+  than \var{n} bytes will be read from the file; a partial line can be
+  returned.  In both cases, an empty string is returned if the end of
+  the file is reached immediately.  If \var{n} is less than \code{0},
+  however, one line is read regardless of length, but
+  \exception{EOFError} is raised if the end of the file is reached
+  immediately.
+  \withsubitem{(built-in exception)}{\ttindex{EOFError}}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyFile_Name}{PyObject *p}
+  Returns the name of the file specified by \var{p} as a string
+  object.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyFile_SetBufSize}{PyFileObject *p, int n}
+  Available on systems with \cfunction{setvbuf()}\ttindex{setvbuf()}
+  only.  This should only be called immediately after file object
+  creation.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyFile_SoftSpace}{PyObject *p, int newflag}
+  This function exists for internal use by the interpreter.  Sets the
+  \member{softspace} attribute of \var{p} to \var{newflag} and
+  \withsubitem{(file attribute)}{\ttindex{softspace}}returns the
+  previous value.  \var{p} does not have to be a file object for this
+  function to work properly; any object is supported (thought its only
+  interesting if the \member{softspace} attribute can be set).  This
+  function clears any errors, and will return \code{0} as the previous
+  value if the attribute either does not exist or if there were errors
+  in retrieving it.  There is no way to detect errors from this
+  function, but doing so should not be needed.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyFile_WriteObject}{PyObject *obj, PyFileObject *p,
+                                           int flags}
+  Writes object \var{obj} to file object \var{p}.  The only supported
+  flag for \var{flags} is
+  \constant{Py_PRINT_RAW}\ttindex{Py_PRINT_RAW}; if given, the
+  \function{str()} of the object is written instead of the
+  \function{repr()}.  Returns \code{0} on success or \code{-1} on
+  failure; the appropriate exception will be set.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyFile_WriteString}{char *s, PyFileObject *p}
+  Writes string \var{s} to file object \var{p}.  Returns \code{0} on
+  success or \code{-1} on failure; the appropriate exception will be
+  set.
+\end{cfuncdesc}
+
+
+\subsection{Instance Objects \label{instanceObjects}}
+
+\obindex{instance}
+There are very few functions specific to instance objects.
+
+\begin{cvardesc}{PyTypeObject}{PyInstance_Type}
+  Type object for class instances.
+\end{cvardesc}
+
+\begin{cfuncdesc}{int}{PyInstance_Check}{PyObject *obj}
+  Returns true if \var{obj} is an instance.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyInstance_New}{PyObject *class,
+                                             PyObject *arg,
+                                             PyObject *kw}
+  Create a new instance of a specific class.  The parameters \var{arg}
+  and \var{kw} are used as the positional and keyword parameters to
+  the object's constructor.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyInstance_NewRaw}{PyObject *class,
+                                                PyObject *dict}
+  Create a new instance of a specific class without calling it's
+  constructor.  \var{class} is the class of new object.  The
+  \var{dict} parameter will be used as the object's \member{__dict__};
+  if \NULL, a new dictionary will be created for the instance.
+\end{cfuncdesc}
+
+
+\subsection{Method Objects \label{method-objects}}
+
+\obindex{method}
+There are some useful functions that are useful for working with
+method objects.
+
+\begin{cvardesc}{PyTypeObject}{PyMethod_Type}
+  This instance of \ctype{PyTypeObject} represents the Python method
+  type.  This is exposed to Python programs as \code{types.MethodType}.
+  \withsubitem{(in module types)}{\ttindex{MethodType}}
+\end{cvardesc}
+
+\begin{cfuncdesc}{int}{PyMethod_Check}{PyObject *o}
+  Return true if \var{o} is a method object (has type
+  \cdata{PyMethod_Type}).  The parameter must not be \NULL.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyMethod_New}{PyObject *func.
+                                           PyObject *self, PyObject *class}
+  Return a new method object, with \var{func} being any callable
+  object; this is the function that will be called when the method is
+  called.  If this method should be bound to an instance, \var{self}
+  should be the instance and \var{class} should be the class of
+  \var{self}, otherwise \var{self} should be \NULL{} and \var{class}
+  should be the class which provides the unbound method..
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyMethod_Class}{PyObject *meth}
+  Return the class object from which the method \var{meth} was
+  created; if this was created from an instance, it will be the class
+  of the instance.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyMethod_GET_CLASS}{PyObject *meth}
+  Macro version of \cfunction{PyMethod_Class()} which avoids error
+  checking.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyMethod_Function}{PyObject *meth}
+  Return the function object associated with the method \var{meth}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyMethod_GET_FUNCTION}{PyObject *meth}
+  Macro version of \cfunction{PyMethod_Function()} which avoids error
+  checking.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyMethod_Self}{PyObject *meth}
+  Return the instance associated with the method \var{meth} if it is
+  bound, otherwise return \NULL.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyMethod_GET_SELF}{PyObject *meth}
+  Macro version of \cfunction{PyMethod_Self()} which avoids error
+  checking.
+\end{cfuncdesc}
+
+
+\subsection{Module Objects \label{moduleObjects}}
+
+\obindex{module}
+There are only a few functions special to module objects.
+
+\begin{cvardesc}{PyTypeObject}{PyModule_Type}
+  This instance of \ctype{PyTypeObject} represents the Python module
+  type.  This is exposed to Python programs as
+  \code{types.ModuleType}.
+  \withsubitem{(in module types)}{\ttindex{ModuleType}}
+\end{cvardesc}
+
+\begin{cfuncdesc}{int}{PyModule_Check}{PyObject *p}
+  Returns true if \var{p} is a module object, or a subtype of a module
+  object.
+  \versionchanged[Allowed subtypes to be accepted]{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyModule_CheckExact}{PyObject *p}
+  Returns true if \var{p} is a module object, but not a subtype of
+  \cdata{PyModule_Type}.
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyModule_New}{char *name}
+  Return a new module object with the \member{__name__} attribute set
+  to \var{name}.  Only the module's \member{__doc__} and
+  \member{__name__} attributes are filled in; the caller is
+  responsible for providing a \member{__file__} attribute.
+  \withsubitem{(module attribute)}{
+    \ttindex{__name__}\ttindex{__doc__}\ttindex{__file__}}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyModule_GetDict}{PyObject *module}
+  Return the dictionary object that implements \var{module}'s
+  namespace; this object is the same as the \member{__dict__}
+  attribute of the module object.  This function never fails.
+  \withsubitem{(module attribute)}{\ttindex{__dict__}}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{char*}{PyModule_GetName}{PyObject *module}
+  Return \var{module}'s \member{__name__} value.  If the module does
+  not provide one, or if it is not a string, \exception{SystemError}
+  is raised and \NULL{} is returned.
+  \withsubitem{(module attribute)}{\ttindex{__name__}}
+  \withsubitem{(built-in exception)}{\ttindex{SystemError}}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{char*}{PyModule_GetFilename}{PyObject *module}
+  Return the name of the file from which \var{module} was loaded using
+  \var{module}'s \member{__file__} attribute.  If this is not defined,
+  or if it is not a string, raise \exception{SystemError} and return
+  \NULL.
+  \withsubitem{(module attribute)}{\ttindex{__file__}}
+  \withsubitem{(built-in exception)}{\ttindex{SystemError}}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyModule_AddObject}{PyObject *module,
+                                           char *name, PyObject *value}
+  Add an object to \var{module} as \var{name}.  This is a convenience
+  function which can be used from the module's initialization
+  function.  This steals a reference to \var{value}.  Returns
+  \code{-1} on error, \code{0} on success.
+  \versionadded{2.0}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyModule_AddIntConstant}{PyObject *module,
+                                                char *name, int value}
+  Add an integer constant to \var{module} as \var{name}.  This
+  convenience function can be used from the module's initialization
+  function. Returns \code{-1} on error, \code{0} on success.
+  \versionadded{2.0}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyModule_AddStringConstant}{PyObject *module,
+                                                   char *name, char *value}
+  Add a string constant to \var{module} as \var{name}.  This
+  convenience function can be used from the module's initialization
+  function.  The string \var{value} must be null-terminated.  Returns
+  \code{-1} on error, \code{0} on success.
+  \versionadded{2.0}
+\end{cfuncdesc}
+
+
+\subsection{Iterator Objects \label{iterator-objects}}
+
+Python provides two general-purpose iterator objects.  The first, a
+sequence iterator, works with an arbitrary sequence supporting the
+\method{__getitem__()} method.  The second works with a callable
+object and a sentinel value, calling the callable for each item in the
+sequence, and ending the iteration when the sentinel value is
+returned.
+
+\begin{cvardesc}{PyTypeObject}{PySeqIter_Type}
+  Type object for iterator objects returned by
+  \cfunction{PySeqIter_New()} and the one-argument form of the
+  \function{iter()} built-in function for built-in sequence types.
+  \versionadded{2.2}
+\end{cvardesc}
+
+\begin{cfuncdesc}{int}{PySeqIter_Check}{op}
+  Return true if the type of \var{op} is \cdata{PySeqIter_Type}.
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PySeqIter_New}{PyObject *seq}
+  Return an iterator that works with a general sequence object,
+  \var{seq}.  The iteration ends when the sequence raises
+  \exception{IndexError} for the subscripting operation.
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+\begin{cvardesc}{PyTypeObject}{PyCallIter_Type}
+  Type object for iterator objects returned by
+  \cfunction{PyCallIter_New()} and the two-argument form of the
+  \function{iter()} built-in function.
+  \versionadded{2.2}
+\end{cvardesc}
+
+\begin{cfuncdesc}{int}{PyCallIter_Check}{op}
+  Return true if the type of \var{op} is \cdata{PyCallIter_Type}.
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyCallIter_New}{PyObject *callable,
+                                             PyObject *sentinel}
+  Return a new iterator.  The first parameter, \var{callable}, can be
+  any Python callable object that can be called with no parameters;
+  each call to it should return the next item in the iteration.  When
+  \var{callable} returns a value equal to \var{sentinel}, the
+  iteration will be terminated.
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+
+\subsection{Descriptor Objects \label{descriptor-objects}}
+
+\begin{cvardesc}{PyTypeObject}{PyProperty_Type}
+  The type object for a descriptor.
+  \versionadded{2.2}
+\end{cvardesc}
+
+\begin{cfuncdesc}{PyObject*}{PyDescr_NewGetSet}{PyTypeObject *type,
+					        PyGetSetDef *getset}
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyDescr_NewMember}{PyTypeObject *type,
+					        PyMemberDef *meth}
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyDescr_NewMethod}{PyTypeObject *type,
+                                                PyMethodDef *meth}
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyDescr_NewWrapper}{PyTypeObject *type,
+						 struct wrapperbase *wrapper,
+                                                 void *wrapped}
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyDescr_IsData}{PyObject *descr}
+  Returns true if the descriptor objects \var{descr} describes a data
+  attribute, or false if it describes a method.  \var{descr} must be a
+  descriptor object; there is no error checking.
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyWrapper_New}{PyObject *, PyObject *}
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+
+\subsection{Slice Objects \label{slice-objects}}
+
+\begin{cvardesc}{PyTypeObject}{PySlice_Type}
+  The type object for slice objects.  This is the same as
+  \code{types.SliceType}.
+  \withsubitem{(in module types)}{\ttindex{SliceType}}
+\end{cvardesc}
+
+\begin{cfuncdesc}{int}{PySlice_Check}{PyObject *ob}
+  Returns true if \var{ob} is a slice object; \var{ob} must not be
+  \NULL.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PySlice_New}{PyObject *start, PyObject *stop,
+                                          PyObject *step}
+  Return a new slice object with the given values.  The \var{start},
+  \var{stop}, and \var{step} parameters are used as the values of the
+  slice object attributes of the same names.  Any of the values may be
+  \NULL, in which case the \code{None} will be used for the
+  corresponding attribute.  Returns \NULL{} if the new object could
+  not be allocated.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PySlice_GetIndices}{PySliceObject *slice, int length,
+                                           int *start, int *stop, int *step}
+\end{cfuncdesc}
+
+
+\subsection{Weak Reference Objects \label{weakref-objects}}
+
+Python supports \emph{weak references} as first-class objects.  There
+are two specific object types which directly implement weak
+references.  The first is a simple reference object, and the second
+acts as a proxy for the original object as much as it can.
+
+\begin{cfuncdesc}{int}{PyWeakref_Check}{ob}
+  Return true if \var{ob} is either a reference or proxy object.
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyWeakref_CheckRef}{ob}
+  Return true if \var{ob} is a reference object.
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyWeakref_CheckProxy}{ob}
+  Return true if \var{ob} is a proxy object.
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyWeakref_NewRef}{PyObject *ob,
+                                               PyObject *callback}
+  Return a weak reference object for the object \var{ob}.  This will
+  always return a new reference, but is not guaranteed to create a new
+  object; an existing reference object may be returned.  The second
+  parameter, \var{callback}, can be a callable object that receives
+  notification when \var{ob} is garbage collected; it should accept a
+  single paramter, which will be the weak reference object itself.
+  \var{callback} may also be \code{None} or \NULL.  If \var{ob}
+  is not a weakly-referencable object, or if \var{callback} is not
+  callable, \code{None}, or \NULL, this will return \NULL{} and
+  raise \exception{TypeError}.
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyWeakref_NewProxy}{PyObject *ob,
+                                                 PyObject *callback}
+  Return a weak reference proxy object for the object \var{ob}.  This
+  will always return a new reference, but is not guaranteed to create
+  a new object; an existing proxy object may be returned.  The second
+  parameter, \var{callback}, can be a callable object that receives
+  notification when \var{ob} is garbage collected; it should accept a
+  single paramter, which will be the weak reference object itself.
+  \var{callback} may also be \code{None} or \NULL.  If \var{ob} is not
+  a weakly-referencable object, or if \var{callback} is not callable,
+  \code{None}, or \NULL, this will return \NULL{} and raise
+  \exception{TypeError}.
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyWeakref_GetObject}{PyObject *ref}
+  Returns the referenced object from a weak reference, \var{ref}.  If
+  the referent is no longer live, returns \NULL.
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyWeakref_GET_OBJECT}{PyObject *ref}
+  Similar to \cfunction{PyWeakref_GetObject()}, but implemented as a
+  macro that does no error checking.
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+
+\subsection{CObjects \label{cObjects}}
+
+\obindex{CObject}
+Refer to \emph{Extending and Embedding the Python Interpreter},
+section 1.12 (``Providing a C API for an Extension Module), for more 
+information on using these objects.
+
+
+\begin{ctypedesc}{PyCObject}
+  This subtype of \ctype{PyObject} represents an opaque value, useful
+  for C extension modules who need to pass an opaque value (as a
+  \ctype{void*} pointer) through Python code to other C code.  It is
+  often used to make a C function pointer defined in one module
+  available to other modules, so the regular import mechanism can be
+  used to access C APIs defined in dynamically loaded modules.
+\end{ctypedesc}
+
+\begin{cfuncdesc}{int}{PyCObject_Check}{PyObject *p}
+  Returns true if its argument is a \ctype{PyCObject}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyCObject_FromVoidPtr}{void* cobj, 
+	                                            void (*destr)(void *)}
+  Creates a \ctype{PyCObject} from the \code{void *}\var{cobj}.  The
+  \var{destr} function will be called when the object is reclaimed,
+  unless it is \NULL.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyCObject_FromVoidPtrAndDesc}{void* cobj,
+	                          void* desc, void (*destr)(void *, void *)}
+  Creates a \ctype{PyCObject} from the \ctype{void *}\var{cobj}.  The
+  \var{destr} function will be called when the object is reclaimed.
+  The \var{desc} argument can be used to pass extra callback data for
+  the destructor function.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void*}{PyCObject_AsVoidPtr}{PyObject* self}
+  Returns the object \ctype{void *} that the \ctype{PyCObject}
+  \var{self} was created with.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void*}{PyCObject_GetDesc}{PyObject* self}
+  Returns the description \ctype{void *} that the \ctype{PyCObject}
+  \var{self} was created with.
+\end{cfuncdesc}
diff --git a/Doc/api/exceptions.tex b/Doc/api/exceptions.tex
new file mode 100644
index 0000000..355e6fb
--- /dev/null
+++ b/Doc/api/exceptions.tex
@@ -0,0 +1,353 @@
+\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.  \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.  \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.)  \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 (for example, \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 \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 \code{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 \method{__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_ReferenceError}{\exception{ReferenceError}}{(2)}
+  \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}}{(3)}
+  \lineiii{PyExc_ZeroDivisionError}{\exception{ZeroDivisionError}}{}
+\end{tableiii}
+
+\noindent
+Notes:
+\begin{description}
+\item[(1)]
+  This is a base class for other standard exceptions.
+
+\item[(2)]
+  This is the same as \exception{weakref.ReferenceError}.
+
+\item[(3)]
+  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.
diff --git a/Doc/api/init.tex b/Doc/api/init.tex
new file mode 100644
index 0000000..890ca0d
--- /dev/null
+++ b/Doc/api/init.tex
@@ -0,0 +1,774 @@
+\chapter{Initialization, Finalization, and Threads
+         \label{initialization}}
+
+\begin{cfuncdesc}{void}{Py_Initialize}{}
+  Initialize the Python interpreter.  In an application embedding 
+  Python, this should be called before using any other Python/C API
+  functions; with the exception of
+  \cfunction{Py_SetProgramName()}\ttindex{Py_SetProgramName()},
+  \cfunction{PyEval_InitThreads()}\ttindex{PyEval_InitThreads()},
+  \cfunction{PyEval_ReleaseLock()}\ttindex{PyEval_ReleaseLock()},
+  and \cfunction{PyEval_AcquireLock()}\ttindex{PyEval_AcquireLock()}.
+  This initializes the table of loaded modules (\code{sys.modules}),
+  and\withsubitem{(in module sys)}{\ttindex{modules}\ttindex{path}}
+  creates the fundamental modules
+  \module{__builtin__}\refbimodindex{__builtin__},
+  \module{__main__}\refbimodindex{__main__} and
+  \module{sys}\refbimodindex{sys}.  It also initializes the module
+  search\indexiii{module}{search}{path} path (\code{sys.path}).
+  It does not set \code{sys.argv}; use
+  \cfunction{PySys_SetArgv()}\ttindex{PySys_SetArgv()} for that.  This
+  is a no-op when called for a second time (without calling
+  \cfunction{Py_Finalize()}\ttindex{Py_Finalize()} first).  There is
+  no return value; it is a fatal error if the initialization fails.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{Py_IsInitialized}{}
+  Return true (nonzero) when the Python interpreter has been
+  initialized, false (zero) if not.  After \cfunction{Py_Finalize()}
+  is called, this returns false until \cfunction{Py_Initialize()} is
+  called again.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{Py_Finalize}{}
+  Undo all initializations made by \cfunction{Py_Initialize()} and
+  subsequent use of Python/C API functions, and destroy all
+  sub-interpreters (see \cfunction{Py_NewInterpreter()} below) that
+  were created and not yet destroyed since the last call to
+  \cfunction{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 \cfunction{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
+  application might want to restart Python without having to restart
+  the application itself.  An application that has loaded the Python
+  interpreter from a dynamically loadable library (or DLL) might want
+  to free all memory allocated by Python before unloading the
+  DLL. During a hunt for memory leaks in an application a developer
+  might want to free all memory allocated by Python before exiting
+  from the application.
+
+  \strong{Bugs and caveats:} The destruction of modules and objects in
+  modules is done in random order; this may cause destructors
+  (\method{__del__()} methods) to fail when they depend on other
+  objects (even functions) or modules.  Dynamically loaded extension
+  modules loaded by Python are not unloaded.  Small amounts of memory
+  allocated by the Python interpreter may not be freed (if you find a
+  leak, please report it).  Memory tied up in circular references
+  between objects is not freed.  Some memory allocated by extension
+  modules may not be freed.  Some extension may not work properly if
+  their initialization routine is called more than once; this can
+  happen if an applcation calls \cfunction{Py_Initialize()} and
+  \cfunction{Py_Finalize()} more than once.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyThreadState*}{Py_NewInterpreter}{}
+  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
+  modules, including the fundamental modules
+  \module{__builtin__}\refbimodindex{__builtin__},
+  \module{__main__}\refbimodindex{__main__} and
+  \module{sys}\refbimodindex{sys}.  The table of loaded modules
+  (\code{sys.modules}) and the module search path (\code{sys.path})
+  are also separate.  The new environment has no \code{sys.argv}
+  variable.  It has new standard I/O stream file objects
+  \code{sys.stdin}, \code{sys.stdout} and \code{sys.stderr} (however
+  these refer to the same underlying \ctype{FILE} structures in the C
+  library).
+  \withsubitem{(in module sys)}{
+    \ttindex{stdout}\ttindex{stderr}\ttindex{stdin}}
+
+  The return value points to the first thread state created in the new
+  sub-interpreter.  This thread state is made the current thread
+  state.  Note that no actual thread is created; see the discussion of
+  thread states below.  If creation of the new interpreter is
+  unsuccessful, \NULL{} is returned; no exception is set since the
+  exception state is stored in the current thread state and there may
+  not be a current thread state.  (Like all other Python/C API
+  functions, the global interpreter lock must be held before calling
+  this function and is still held when it returns; however, unlike
+  most other Python/C API functions, there needn't be a current thread
+  state on entry.)
+
+  Extension modules are shared between (sub-)interpreters as follows:
+  the first time a particular extension is imported, it is initialized
+  normally, and a (shallow) copy of its module's dictionary is
+  squirreled away.  When the same extension is imported by another
+  (sub-)interpreter, a new module is initialized and filled with the
+  contents of this copy; the extension's \code{init} function is not
+  called.  Note that this is different from what happens when an
+  extension is imported after the interpreter has been completely
+  re-initialized by calling
+  \cfunction{Py_Finalize()}\ttindex{Py_Finalize()} and
+  \cfunction{Py_Initialize()}\ttindex{Py_Initialize()}; in that case,
+  the extension's \code{init\var{module}} function \emph{is} called
+  again.
+
+  \strong{Bugs and caveats:} Because sub-interpreters (and the main
+  interpreter) are part of the same process, the insulation between
+  them isn't perfect --- for example, using low-level file operations
+  like \withsubitem{(in module os)}{\ttindex{close()}}
+  \function{os.close()} they can (accidentally or maliciously) affect
+  each other's open files.  Because of the way extensions are shared
+  between (sub-)interpreters, some extensions may not work properly;
+  this is especially likely when the extension makes use of (static)
+  global variables, or when the extension manipulates its module's
+  dictionary after its initialization.  It is possible to insert
+  objects created in one sub-interpreter into a namespace of another
+  sub-interpreter; this should be done with great care to avoid
+  sharing user-defined functions, methods, instances or classes
+  between sub-interpreters, since import operations executed by such
+  objects may affect the wrong (sub-)interpreter's dictionary of
+  loaded modules.  (XXX This is a hard-to-fix bug that will be
+  addressed in a future release.)
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{Py_EndInterpreter}{PyThreadState *tstate}
+  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 thread state is \NULL.  All thread states associated with
+  this interpreted are destroyed.  (The global interpreter lock must
+  be held before calling this function and is still held when it
+  returns.)  \cfunction{Py_Finalize()}\ttindex{Py_Finalize()} will
+  destroy all sub-interpreters that haven't been explicitly destroyed
+  at that point.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{Py_SetProgramName}{char *name}
+  This function should be called before
+  \cfunction{Py_Initialize()}\ttindex{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
+  \cfunction{main()}\ttindex{main()} function of the program.  This is
+  used by \cfunction{Py_GetPath()}\ttindex{Py_GetPath()} and some
+  other functions below to find the Python run-time libraries relative
+  to the interpreter executable.  The default value is
+  \code{'python'}.  The argument should point to a zero-terminated
+  character string in static storage whose contents will not change
+  for the duration of the program's execution.  No code in the Python
+  interpreter will change the contents of this storage.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{char*}{Py_GetProgramName}{}
+  Return the program name set with
+  \cfunction{Py_SetProgramName()}\ttindex{Py_SetProgramName()}, or the
+  default.  The returned string points into static storage; the caller
+  should not modify its value.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{char*}{Py_GetPrefix}{}
+  Return the \emph{prefix} for installed platform-independent files.
+  This is derived through a number of complicated rules from the
+  program name set with \cfunction{Py_SetProgramName()} and some
+  environment variables; for example, if the program name is
+  \code{'/usr/local/bin/python'}, the prefix is \code{'/usr/local'}.
+  The returned string points into static storage; the caller should
+  not modify its value.  This corresponds to the \makevar{prefix}
+  variable in the top-level \file{Makefile} and the
+  \longprogramopt{prefix} argument to the \program{configure} script
+  at build time.  The value is available to Python code as
+  \code{sys.prefix}.  It is only useful on \UNIX.  See also the next
+  function.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{char*}{Py_GetExecPrefix}{}
+  Return the \emph{exec-prefix} for installed
+  platform-\emph{de}pendent files.  This is derived through a number
+  of complicated rules from the program name set with
+  \cfunction{Py_SetProgramName()} and some environment variables; for
+  example, if the program name is \code{'/usr/local/bin/python'}, the
+  exec-prefix is \code{'/usr/local'}.  The returned string points into
+  static storage; the caller should not modify its value.  This
+  corresponds to the \makevar{exec_prefix} variable in the top-level
+  \file{Makefile} and the \longprogramopt{exec-prefix} argument to the
+  \program{configure} script at build  time.  The value is available
+  to Python code as \code{sys.exec_prefix}.  It is only useful on
+  \UNIX.
+
+  Background: The exec-prefix differs from the prefix when platform
+  dependent files (such as executables and shared libraries) are
+  installed in a different directory tree.  In a typical installation,
+  platform dependent files may be installed in the
+  \file{/usr/local/plat} subtree while platform independent may be
+  installed in \file{/usr/local}.
+
+  Generally speaking, a platform is a combination of hardware and
+  software families, e.g.  Sparc machines running the Solaris 2.x
+  operating system are considered the same platform, but Intel
+  machines running Solaris 2.x are another platform, and Intel
+  machines running Linux are yet another platform.  Different major
+  revisions of the same operating system generally also form different
+  platforms.  Non-\UNIX{} operating systems are a different story; the
+  installation strategies on those systems are so different that the
+  prefix and exec-prefix are meaningless, and set to the empty string.
+  Note that compiled Python bytecode files are platform independent
+  (but not independent from the Python version by which they were
+  compiled!).
+
+  System administrators will know how to configure the \program{mount}
+  or \program{automount} programs to share \file{/usr/local} between
+  platforms while having \file{/usr/local/plat} be a different
+  filesystem for each platform.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{char*}{Py_GetProgramFullPath}{}
+  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
+  \cfunction{Py_SetProgramName()}\ttindex{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}.
+  \withsubitem{(in module sys)}{\ttindex{executable}}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{char*}{Py_GetPath}{}
+  \indexiii{module}{search}{path}
+  Return the default module search path; this is computed from the 
+  program name (set by \cfunction{Py_SetProgramName()} above) and some
+  environment variables.  The returned string consists of a series of
+  directory names separated by a platform dependent delimiter
+  character.  The delimiter character is \character{:} on \UNIX,
+  \character{;} on DOS/Windows, and \character{\e n} (the \ASCII{}
+  newline character) on Macintosh.  The returned string points into
+  static storage; the caller should not modify its value.  The value
+  is available to Python code as the list
+  \code{sys.path}\withsubitem{(in module sys)}{\ttindex{path}}, which
+  may be modified to change the future search path for loaded
+  modules.
+
+  % XXX should give the exact rules
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{const char*}{Py_GetVersion}{}
+  Return the version of this Python interpreter.  This is a string
+  that looks something like
+
+\begin{verbatim}
+"1.5 (#67, Dec 31 1997, 22:34:28) [GCC 2.7.2.2]"
+\end{verbatim}
+
+  The first word (up to the first space character) is the current
+  Python version; the first three characters are the major and minor
+  version separated by a period.  The returned string points into
+  static storage; the caller should not modify its value.  The value
+  is available to Python code as the list \code{sys.version}.
+  \withsubitem{(in module sys)}{\ttindex{version}}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{const char*}{Py_GetPlatform}{}
+  Return the platform identifier for the current platform.  On \UNIX,
+  this is formed from the ``official'' name of the operating system,
+  converted to lower case, followed by the major revision number;
+  e.g., for Solaris 2.x, which is also known as SunOS 5.x, the value
+  is \code{'sunos5'}.  On Macintosh, it is \code{'mac'}.  On Windows,
+  it is \code{'win'}.  The returned string points into static storage;
+  the caller should not modify its value.  The value is available to
+  Python code as \code{sys.platform}.
+  \withsubitem{(in module sys)}{\ttindex{platform}}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{const char*}{Py_GetCopyright}{}
+  Return the official copyright string for the current Python version,
+  for example
+
+  \code{'Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam'}
+
+  The returned string points into static storage; the caller should
+  not modify its value.  The value is available to Python code as the
+  list \code{sys.copyright}.
+  \withsubitem{(in module sys)}{\ttindex{copyright}}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{const char*}{Py_GetCompiler}{}
+  Return an indication of the compiler used to build the current
+  Python version, in square brackets, for example:
+
+\begin{verbatim}
+"[GCC 2.7.2.2]"
+\end{verbatim}
+
+  The returned string points into static storage; the caller should
+  not modify its value.  The value is available to Python code as part
+  of the variable \code{sys.version}.
+  \withsubitem{(in module sys)}{\ttindex{version}}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{const char*}{Py_GetBuildInfo}{}
+  Return information about the sequence number and build date and time 
+  of the current Python interpreter instance, for example
+
+\begin{verbatim}
+"#67, Aug  1 1997, 22:34:28"
+\end{verbatim}
+
+  The returned string points into static storage; the caller should
+  not modify its value.  The value is available to Python code as part
+  of the variable \code{sys.version}.
+  \withsubitem{(in module sys)}{\ttindex{version}}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PySys_SetArgv}{int argc, char **argv}
+  Set \code{sys.argv} based on \var{argc} and \var{argv}.  These
+  parameters are similar to those passed to the program's
+  \cfunction{main()}\ttindex{main()} function with the difference that
+  the first entry should refer to the script file to be executed
+  rather than the executable hosting the Python interpreter.  If there
+  isn't a script that will be run, the first entry in \var{argv} can
+  be an empty string.  If this function fails to initialize
+  \code{sys.argv}, a fatal condition is signalled using
+  \cfunction{Py_FatalError()}\ttindex{Py_FatalError()}.
+  \withsubitem{(in module sys)}{\ttindex{argv}}
+  % XXX impl. doesn't seem consistent in allowing 0/NULL for the params; 
+  % check w/ Guido.
+\end{cfuncdesc}
+
+% XXX Other PySys thingies (doesn't really belong in this chapter)
+
+\section{Thread State and the Global Interpreter Lock
+         \label{threads}}
+
+\index{global interpreter lock}
+\index{interpreter lock}
+\index{lock, interpreter}
+
+The Python interpreter is not fully thread safe.  In order to support
+multi-threaded Python programs, there's a global lock that must be
+held by the current thread before it can safely access Python objects.
+Without the lock, even the simplest operations could cause problems in
+a multi-threaded program: for example, when two threads simultaneously
+increment the reference count of the same object, the reference count
+could end up being incremented only once instead of twice.
+
+Therefore, the rule exists that only the thread that has acquired the
+global interpreter lock may operate on Python objects or call Python/C
+API functions.  In order to support multi-threaded Python programs,
+the interpreter regularly releases and reacquires the lock --- by
+default, every ten bytecode instructions (this can be changed with
+\withsubitem{(in module sys)}{\ttindex{setcheckinterval()}}
+\function{sys.setcheckinterval()}).  The lock is also released and
+reacquired around potentially blocking I/O operations like reading or
+writing a file, so that other threads can run while the thread that
+requests the I/O is waiting for the I/O operation to complete.
+
+The Python interpreter needs to keep some bookkeeping information
+separate per thread --- for this it uses a data structure called
+\ctype{PyThreadState}\ttindex{PyThreadState}.  This is new in Python
+1.5; in earlier versions, such state was stored in global variables,
+and switching threads could cause problems.  In particular, exception
+handling is now thread safe, when the application uses
+\withsubitem{(in module sys)}{\ttindex{exc_info()}}
+\function{sys.exc_info()} to access the exception last raised in the
+current thread.
+
+There's one global variable left, however: the pointer to the current
+\ctype{PyThreadState}\ttindex{PyThreadState} structure.  While most
+thread packages have a way to store ``per-thread global data,''
+Python's internal platform independent thread abstraction doesn't
+support this yet.  Therefore, the current thread state must be
+manipulated explicitly.
+
+This is easy enough in most cases.  Most code manipulating the global
+interpreter lock has the following simple structure:
+
+\begin{verbatim}
+Save the thread state in a local variable.
+Release the interpreter lock.
+...Do some blocking I/O operation...
+Reacquire the interpreter lock.
+Restore the thread state from the local variable.
+\end{verbatim}
+
+This is so common that a pair of macros exists to simplify it:
+
+\begin{verbatim}
+Py_BEGIN_ALLOW_THREADS
+...Do some blocking I/O operation...
+Py_END_ALLOW_THREADS
+\end{verbatim}
+
+The \code{Py_BEGIN_ALLOW_THREADS}\ttindex{Py_BEGIN_ALLOW_THREADS} macro
+opens a new block and declares a hidden local variable; the
+\code{Py_END_ALLOW_THREADS}\ttindex{Py_END_ALLOW_THREADS} macro closes 
+the block.  Another advantage of using these two macros is that when
+Python is compiled without thread support, they are defined empty,
+thus saving the thread state and lock manipulations.
+
+When thread support is enabled, the block above expands to the
+following code:
+
+\begin{verbatim}
+    PyThreadState *_save;
+
+    _save = PyEval_SaveThread();
+    ...Do some blocking I/O operation...
+    PyEval_RestoreThread(_save);
+\end{verbatim}
+
+Using even lower level primitives, we can get roughly the same effect
+as follows:
+
+\begin{verbatim}
+    PyThreadState *_save;
+
+    _save = PyThreadState_Swap(NULL);
+    PyEval_ReleaseLock();
+    ...Do some blocking I/O operation...
+    PyEval_AcquireLock();
+    PyThreadState_Swap(_save);
+\end{verbatim}
+
+There are some subtle differences; in particular,
+\cfunction{PyEval_RestoreThread()}\ttindex{PyEval_RestoreThread()} saves
+and restores the value of the  global variable
+\cdata{errno}\ttindex{errno}, since the lock manipulation does not
+guarantee that \cdata{errno} is left alone.  Also, when thread support
+is disabled,
+\cfunction{PyEval_SaveThread()}\ttindex{PyEval_SaveThread()} and
+\cfunction{PyEval_RestoreThread()} don't manipulate the lock; in this
+case, \cfunction{PyEval_ReleaseLock()}\ttindex{PyEval_ReleaseLock()} and
+\cfunction{PyEval_AcquireLock()}\ttindex{PyEval_AcquireLock()} are not
+available.  This is done so that dynamically loaded extensions
+compiled with thread support enabled can be loaded by an interpreter
+that was compiled with disabled thread support.
+
+The global interpreter lock is used to protect the pointer to the
+current thread state.  When releasing the lock and saving the thread
+state, the current thread state pointer must be retrieved before the
+lock is released (since another thread could immediately acquire the
+lock and store its own thread state in the global variable).
+Conversely, when acquiring the lock and restoring the thread state,
+the lock must be acquired before storing the thread state pointer.
+
+Why am I going on with so much detail about this?  Because when
+threads are created from C, they don't have the global interpreter
+lock, nor is there a thread state data structure for them.  Such
+threads must bootstrap themselves into existence, by first creating a
+thread state data structure, then acquiring the lock, and finally
+storing their thread state pointer, before they can start using the
+Python/C API.  When they are done, they should reset the thread state
+pointer, release the lock, and finally free their thread state data
+structure.
+
+When creating a thread data structure, you need to provide an
+interpreter state data structure.  The interpreter state data
+structure hold global data that is shared by all threads in an
+interpreter, for example the module administration
+(\code{sys.modules}).  Depending on your needs, you can either create
+a new interpreter state data structure, or share the interpreter state
+data structure used by the Python main thread (to access the latter,
+you must obtain the thread state and access its \member{interp} member;
+this must be done by a thread that is created by Python or by the main
+thread after Python is initialized).
+
+
+\begin{ctypedesc}{PyInterpreterState}
+  This data structure represents the state shared by a number of
+  cooperating threads.  Threads belonging to the same interpreter
+  share their module administration and a few other internal items.
+  There are no public members in this structure.
+
+  Threads belonging to different interpreters initially share nothing,
+  except process state like available memory, open file descriptors
+  and such.  The global interpreter lock is also shared by all
+  threads, regardless of to which interpreter they belong.
+\end{ctypedesc}
+
+\begin{ctypedesc}{PyThreadState}
+  This data structure represents the state of a single thread.  The
+  only public data member is \ctype{PyInterpreterState
+  *}\member{interp}, which points to this thread's interpreter state.
+\end{ctypedesc}
+
+\begin{cfuncdesc}{void}{PyEval_InitThreads}{}
+  Initialize and acquire the global interpreter lock.  It should be
+  called in the main thread before creating a second thread or
+  engaging in any other thread operations such as
+  \cfunction{PyEval_ReleaseLock()}\ttindex{PyEval_ReleaseLock()} or
+  \code{PyEval_ReleaseThread(\var{tstate})}\ttindex{PyEval_ReleaseThread()}.
+  It is not needed before calling
+  \cfunction{PyEval_SaveThread()}\ttindex{PyEval_SaveThread()} or
+  \cfunction{PyEval_RestoreThread()}\ttindex{PyEval_RestoreThread()}.
+
+  This is a no-op when called for a second time.  It is safe to call
+  this function before calling
+  \cfunction{Py_Initialize()}\ttindex{Py_Initialize()}.
+
+  When only the main thread exists, no lock operations are needed.
+  This is a common situation (most Python programs do not use
+  threads), and the lock operations slow the interpreter down a bit.
+  Therefore, the lock is not created initially.  This situation is
+  equivalent to having acquired the lock: when there is only a single
+  thread, all object accesses are safe.  Therefore, when this function
+  initializes the lock, it also acquires it.  Before the Python
+  \module{thread}\refbimodindex{thread} module creates a new thread,
+  knowing that either it has the lock or the lock hasn't been created
+  yet, it calls \cfunction{PyEval_InitThreads()}.  When this call
+  returns, it is guaranteed that the lock has been created and that it
+  has acquired it.
+
+  It is \strong{not} safe to call this function when it is unknown
+  which thread (if any) currently has the global interpreter lock.
+
+  This function is not available when thread support is disabled at
+  compile time.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyEval_AcquireLock}{}
+  Acquire the global interpreter lock.  The lock must have been
+  created earlier.  If this thread already has the lock, a deadlock
+  ensues.  This function is not available when thread support is
+  disabled at compile time.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyEval_ReleaseLock}{}
+  Release the global interpreter lock.  The lock must have been
+  created earlier.  This function is not available when thread support
+  is disabled at compile time.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyEval_AcquireThread}{PyThreadState *tstate}
+  Acquire the global interpreter lock and then set the current thread
+  state to \var{tstate}, which should not be \NULL.  The lock must
+  have been created earlier.  If this thread already has the lock,
+  deadlock ensues.  This function is not available when thread support
+  is disabled at compile time.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyEval_ReleaseThread}{PyThreadState *tstate}
+  Reset the current thread state to \NULL{} and release the global
+  interpreter lock.  The lock must have been created earlier and must
+  be held by the current thread.  The \var{tstate} argument, which
+  must not be \NULL, is only used to check that it represents the
+  current thread state --- if it isn't, a fatal error is reported.
+  This function is not available when thread support is disabled at
+  compile time.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyThreadState*}{PyEval_SaveThread}{}
+  Release the interpreter lock (if it has been created and thread
+  support is enabled) and reset the thread state to \NULL, returning
+  the previous thread state (which is not \NULL).  If the lock has
+  been created, the current thread must have acquired it.  (This
+  function is available even when thread support is disabled at
+  compile time.)
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyEval_RestoreThread}{PyThreadState *tstate}
+  Acquire the interpreter lock (if it has been created and thread
+  support is enabled) and set the thread state to \var{tstate}, which
+  must not be \NULL.  If the lock has been created, the current thread
+  must not have acquired it, otherwise deadlock ensues.  (This
+  function is available even when thread support is disabled at
+  compile time.)
+\end{cfuncdesc}
+
+The following macros are normally used without a trailing semicolon;
+look for example usage in the Python source distribution.
+
+\begin{csimplemacrodesc}{Py_BEGIN_ALLOW_THREADS}
+  This macro expands to
+  \samp{\{ PyThreadState *_save; _save = PyEval_SaveThread();}.
+  Note that it contains an opening brace; it must be matched with a
+  following \code{Py_END_ALLOW_THREADS} macro.  See above for further
+  discussion of this macro.  It is a no-op when thread support is
+  disabled at compile time.
+\end{csimplemacrodesc}
+
+\begin{csimplemacrodesc}{Py_END_ALLOW_THREADS}
+  This macro expands to \samp{PyEval_RestoreThread(_save); \}}.
+  Note that it contains a closing brace; it must be matched with an
+  earlier \code{Py_BEGIN_ALLOW_THREADS} macro.  See above for further
+  discussion of this macro.  It is a no-op when thread support is
+  disabled at compile time.
+\end{csimplemacrodesc}
+
+\begin{csimplemacrodesc}{Py_BLOCK_THREADS}
+  This macro expands to \samp{PyEval_RestoreThread(_save);}: it is
+  equivalent to \code{Py_END_ALLOW_THREADS} without the closing brace.
+  It is a no-op when thread support is disabled at compile time.
+\end{csimplemacrodesc}
+
+\begin{csimplemacrodesc}{Py_UNBLOCK_THREADS}
+  This macro expands to \samp{_save = PyEval_SaveThread();}: it is
+  equivalent to \code{Py_BEGIN_ALLOW_THREADS} without the opening
+  brace and variable declaration.  It is a no-op when thread support
+  is disabled at compile time.
+\end{csimplemacrodesc}
+
+All of the following functions are only available when thread support
+is enabled at compile time, and must be called only when the
+interpreter lock has been created.
+
+\begin{cfuncdesc}{PyInterpreterState*}{PyInterpreterState_New}{}
+  Create a new interpreter state object.  The interpreter lock need
+  not be held, but may be held if it is necessary to serialize calls
+  to this function.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyInterpreterState_Clear}{PyInterpreterState *interp}
+  Reset all information in an interpreter state object.  The
+  interpreter lock must be held.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyInterpreterState_Delete}{PyInterpreterState *interp}
+  Destroy an interpreter state object.  The interpreter lock need not
+  be held.  The interpreter state must have been reset with a previous
+  call to \cfunction{PyInterpreterState_Clear()}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyThreadState*}{PyThreadState_New}{PyInterpreterState *interp}
+  Create a new thread state object belonging to the given interpreter
+  object.  The interpreter lock need not be held, but may be held if
+  it is necessary to serialize calls to this function.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyThreadState_Clear}{PyThreadState *tstate}
+  Reset all information in a thread state object.  The interpreter lock
+  must be held.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyThreadState_Delete}{PyThreadState *tstate}
+  Destroy a thread state object.  The interpreter lock need not be
+  held.  The thread state must have been reset with a previous call to
+  \cfunction{PyThreadState_Clear()}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyThreadState*}{PyThreadState_Get}{}
+  Return the current thread state.  The interpreter lock must be
+  held.  When the current thread state is \NULL, this issues a fatal
+  error (so that the caller needn't check for \NULL).
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyThreadState*}{PyThreadState_Swap}{PyThreadState *tstate}
+  Swap the current thread state with the thread state given by the
+  argument \var{tstate}, which may be \NULL.  The interpreter lock
+  must be held.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyThreadState_GetDict}{}
+  Return a dictionary in which extensions can store thread-specific
+  state information.  Each extension should use a unique key to use to
+  store state in the dictionary.  If this function returns \NULL, an
+  exception has been raised and the caller should allow it to
+  propogate.
+\end{cfuncdesc}
+
+
+\section{Profiling and Tracing \label{profiling}}
+
+\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
+
+The Python interpreter provides some low-level support for attaching
+profiling and execution tracing facilities.  These are used for
+profiling, debugging, and coverage analysis tools.
+
+Starting with Python 2.2, the implementation of this facility was
+substantially revised, and an interface from C was added.  This C
+interface allows the profiling or tracing code to avoid the overhead
+of calling through Python-level callable objects, making a direct C
+function call instead.  The essential attributes of the facility have
+not changed; the interface allows trace functions to be installed
+per-thread, and the basic events reported to the trace function are
+the same as had been reported to the Python-level trace functions in
+previous versions.
+
+\begin{ctypedesc}[Py_tracefunc]{int (*Py_tracefunc)(PyObject *obj,
+                                PyFrameObject *frame, int what,
+                                PyObject *arg)}
+  The type of the trace function registered using
+  \cfunction{PyEval_SetProfile()} and \cfunction{PyEval_SetTrace()}.
+  The first parameter is the object passed to the registration
+  function as \var{obj}, \var{frame} is the frame object to which the
+  event pertains, \var{what} is one of the constants
+  \constant{PyTrace_CALL}, \constant{PyTrace_EXCEPT},
+  \constant{PyTrace_LINE} or \constant{PyTrace_RETURN}, and \var{arg}
+  depends on the value of \var{what}:
+
+  \begin{tableii}{l|l}{constant}{Value of \var{what}}{Meaning of \var{arg}}
+    \lineii{PyTrace_CALL}{Always \NULL.}
+    \lineii{PyTrace_EXCEPT}{Exception information as returned by
+                            \function{sys.exc_info()}.}
+    \lineii{PyTrace_LINE}{Always \NULL.}
+    \lineii{PyTrace_RETURN}{Value being returned to the caller.}
+  \end{tableii}
+\end{ctypedesc}
+
+\begin{cvardesc}{int}{PyTrace_CALL}
+  The value of the \var{what} parameter to a \ctype{Py_tracefunc}
+  function when a new call to a function or method is being reported,
+  or a new entry into a generator.  Note that the creation of the
+  iterator for a generator function is not reported as there is no
+  control transfer to the Python bytecode in the corresponding frame.
+\end{cvardesc}
+
+\begin{cvardesc}{int}{PyTrace_EXCEPT}
+  The value of the \var{what} parameter to a \ctype{Py_tracefunc}
+  function when an exception has been raised by Python code as the
+  result of an operation.  The operation may have explictly intended
+  to raise the operation (as with a \keyword{raise} statement), or may
+  have triggered an exception in the runtime as a result of the
+  specific operation.
+\end{cvardesc}
+
+\begin{cvardesc}{int}{PyTrace_LINE}
+  The value passed as the \var{what} parameter to a trace function
+  (but not a profiling function) when a line-number event is being
+  reported.
+\end{cvardesc}
+
+\begin{cvardesc}{int}{PyTrace_RETURN}
+  The value for the \var{what} parameter to \ctype{Py_tracefunc}
+  functions when a call is returning without propogating an exception.
+\end{cvardesc}
+
+\begin{cfuncdesc}{void}{PyEval_SetProfile}{Py_tracefunc func, PyObject *obj}
+  Set the profiler function to \var{func}.  The \var{obj} parameter is
+  passed to the function as its first parameter, and may be any Python
+  object, or \NULL.  If the profile function needs to maintain state,
+  using a different value for \var{obj} for each thread provides a
+  convenient and thread-safe place to store it.  The profile function
+  is called for all monitored events except the line-number events.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyEval_SetTrace}{Py_tracefunc func, PyObject *obj}
+  Set the the tracing function to \var{func}.  This is similar to
+  \cfunction{PyEval_SetProfile()}, except the tracing function does
+  receive line-number events.
+\end{cfuncdesc}
+
+
+\section{Advanced Debugger Support \label{advanced-debugging}}
+\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
+
+These functions are only intended to be used by advanced debugging
+tools.
+
+\begin{cfuncdesc}{PyInterpreterState*}{PyInterpreterState_Head}{}
+  Return the interpreter state object at the head of the list of all
+  such objects.
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyInterpreterState*}{PyInterpreterState_Next}{PyInterpreterState *interp}
+  Return the next interpreter state object after \var{interp} from the
+  list of all such objects.
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyThreadState *}{PyInterpreterState_ThreadHead}{PyInterpreterState *interp}
+  Return the a pointer to the first \ctype{PyThreadState} object in
+  the list of threads associated with the interpreter \var{interp}.
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyThreadState*}{PyThreadState_Next}{PyThreadState *tstate}
+  Return the next thread state object after \var{tstate} from the list
+  of all such objects belonging to the same \ctype{PyInterpreterState}
+  object.
+  \versionadded{2.2}
+\end{cfuncdesc}
diff --git a/Doc/api/intro.tex b/Doc/api/intro.tex
new file mode 100644
index 0000000..d148ba8
--- /dev/null
+++ b/Doc/api/intro.tex
@@ -0,0 +1,558 @@
+\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).
+Since Python may define some pre-processor definitions which affect
+the standard headers on some systems, you must include \file{Python.h}
+before any standard headers are included.
+
+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__}, \module{sys}\refbimodindex{sys},
+and \module{exceptions}.\refbimodindex{exceptions}  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.
diff --git a/Doc/api/memory.tex b/Doc/api/memory.tex
new file mode 100644
index 0000000..2f45259
--- /dev/null
+++ b/Doc/api/memory.tex
@@ -0,0 +1,201 @@
+\chapter{Memory Management \label{memory}}
+\sectionauthor{Vladimir Marangozov}{Vladimir.Marangozov@inrialpes.fr}
+
+
+\section{Overview \label{memoryOverview}}
+
+Memory management in Python involves a private heap containing all
+Python objects and data structures. The management of this private
+heap is ensured internally by the \emph{Python memory manager}.  The
+Python memory manager has different components which deal with various
+dynamic storage management aspects, like sharing, segmentation,
+preallocation or caching.
+
+At the lowest level, a raw memory allocator ensures that there is
+enough room in the private heap for storing all Python-related data
+by interacting with the memory manager of the operating system. On top
+of the raw memory allocator, several object-specific allocators
+operate on the same heap and implement distinct memory management
+policies adapted to the peculiarities of every object type. For
+example, integer objects are managed differently within the heap than
+strings, tuples or dictionaries because integers imply different
+storage requirements and speed/space tradeoffs. The Python memory
+manager thus delegates some of the work to the object-specific
+allocators, but ensures that the latter operate within the bounds of
+the private heap.
+
+It is important to understand that the management of the Python heap
+is performed by the interpreter itself and that the user has no
+control on it, even if she regularly manipulates object pointers to
+memory blocks inside that heap.  The allocation of heap space for
+Python objects and other internal buffers is performed on demand by
+the Python memory manager through the Python/C API functions listed in
+this document.
+
+To avoid memory corruption, extension writers should never try to
+operate on Python objects with the functions exported by the C
+library: \cfunction{malloc()}\ttindex{malloc()},
+\cfunction{calloc()}\ttindex{calloc()},
+\cfunction{realloc()}\ttindex{realloc()} and
+\cfunction{free()}\ttindex{free()}.  This will result in 
+mixed calls between the C allocator and the Python memory manager
+with fatal consequences, because they implement different algorithms
+and operate on different heaps.  However, one may safely allocate and
+release memory blocks with the C library allocator for individual
+purposes, as shown in the following example:
+
+\begin{verbatim}
+    PyObject *res;
+    char *buf = (char *) malloc(BUFSIZ); /* for I/O */
+
+    if (buf == NULL)
+        return PyErr_NoMemory();
+    ...Do some I/O operation involving buf...
+    res = PyString_FromString(buf);
+    free(buf); /* malloc'ed */
+    return res;
+\end{verbatim}
+
+In this example, the memory request for the I/O buffer is handled by
+the C library allocator. The Python memory manager is involved only
+in the allocation of the string object returned as a result.
+
+In most situations, however, it is recommended to allocate memory from
+the Python heap specifically because the latter is under control of
+the Python memory manager. For example, this is required when the
+interpreter is extended with new object types written in C. Another
+reason for using the Python heap is the desire to \emph{inform} the
+Python memory manager about the memory needs of the extension module.
+Even when the requested memory is used exclusively for internal,
+highly-specific purposes, delegating all memory requests to the Python
+memory manager causes the interpreter to have a more accurate image of
+its memory footprint as a whole. Consequently, under certain
+circumstances, the Python memory manager may or may not trigger
+appropriate actions, like garbage collection, memory compaction or
+other preventive procedures. Note that by using the C library
+allocator as shown in the previous example, the allocated memory for
+the I/O buffer escapes completely the Python memory manager.
+
+
+\section{Memory Interface \label{memoryInterface}}
+
+The following function sets, modeled after the ANSI C standard, are
+available for allocating and releasing memory from the Python heap:
+
+
+\begin{cfuncdesc}{void*}{PyMem_Malloc}{size_t n}
+  Allocates \var{n} bytes and returns a pointer of type \ctype{void*}
+  to the allocated memory, or \NULL{} if the request fails.
+  Requesting zero bytes returns a non-\NULL{} pointer.
+  The memory will not have been initialized in any way.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void*}{PyMem_Realloc}{void *p, size_t n}
+  Resizes the memory block pointed to by \var{p} to \var{n} bytes.
+  The contents will be unchanged to the minimum of the old and the new
+  sizes. If \var{p} is \NULL, the call is equivalent to
+  \cfunction{PyMem_Malloc(\var{n})}; if \var{n} is equal to zero, the
+  memory block is resized but is not freed, and the returned pointer
+  is non-\NULL.  Unless \var{p} is \NULL, it must have been
+  returned by a previous call to \cfunction{PyMem_Malloc()} or
+  \cfunction{PyMem_Realloc()}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyMem_Free}{void *p}
+  Frees the memory block pointed to by \var{p}, which must have been
+  returned by a previous call to \cfunction{PyMem_Malloc()} or
+  \cfunction{PyMem_Realloc()}.  Otherwise, or if
+  \cfunction{PyMem_Free(p)} has been called before, undefined
+  behaviour occurs. If \var{p} is \NULL, no operation is performed.
+\end{cfuncdesc}
+
+The following type-oriented macros are provided for convenience.  Note 
+that \var{TYPE} refers to any C type.
+
+\begin{cfuncdesc}{\var{TYPE}*}{PyMem_New}{TYPE, size_t n}
+  Same as \cfunction{PyMem_Malloc()}, but allocates \code{(\var{n} *
+  sizeof(\var{TYPE}))} bytes of memory.  Returns a pointer cast to
+  \ctype{\var{TYPE}*}.  The memory will not have been initialized in
+  any way.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{\var{TYPE}*}{PyMem_Resize}{void *p, TYPE, size_t n}
+  Same as \cfunction{PyMem_Realloc()}, but the memory block is resized
+  to \code{(\var{n} * sizeof(\var{TYPE}))} bytes.  Returns a pointer
+  cast to \ctype{\var{TYPE}*}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyMem_Del}{void *p}
+  Same as \cfunction{PyMem_Free()}.
+\end{cfuncdesc}
+
+In addition, the following macro sets are provided for calling the
+Python memory allocator directly, without involving the C API functions
+listed above. However, note that their use does not preserve binary
+compatibility accross Python versions and is therefore deprecated in
+extension modules.
+
+\cfunction{PyMem_MALLOC()}, \cfunction{PyMem_REALLOC()}, \cfunction{PyMem_FREE()}.
+
+\cfunction{PyMem_NEW()}, \cfunction{PyMem_RESIZE()}, \cfunction{PyMem_DEL()}.
+
+
+\section{Examples \label{memoryExamples}}
+
+Here is the example from section \ref{memoryOverview}, rewritten so
+that the I/O buffer is allocated from the Python heap by using the
+first function set:
+
+\begin{verbatim}
+    PyObject *res;
+    char *buf = (char *) PyMem_Malloc(BUFSIZ); /* for I/O */
+
+    if (buf == NULL)
+        return PyErr_NoMemory();
+    /* ...Do some I/O operation involving buf... */
+    res = PyString_FromString(buf);
+    PyMem_Free(buf); /* allocated with PyMem_Malloc */
+    return res;
+\end{verbatim}
+
+The same code using the type-oriented function set:
+
+\begin{verbatim}
+    PyObject *res;
+    char *buf = PyMem_New(char, BUFSIZ); /* for I/O */
+
+    if (buf == NULL)
+        return PyErr_NoMemory();
+    /* ...Do some I/O operation involving buf... */
+    res = PyString_FromString(buf);
+    PyMem_Del(buf); /* allocated with PyMem_New */
+    return res;
+\end{verbatim}
+
+Note that in the two examples above, the buffer is always
+manipulated via functions belonging to the same set. Indeed, it
+is required to use the same memory API family for a given
+memory block, so that the risk of mixing different allocators is
+reduced to a minimum. The following code sequence contains two errors,
+one of which is labeled as \emph{fatal} because it mixes two different
+allocators operating on different heaps.
+
+\begin{verbatim}
+char *buf1 = PyMem_New(char, BUFSIZ);
+char *buf2 = (char *) malloc(BUFSIZ);
+char *buf3 = (char *) PyMem_Malloc(BUFSIZ);
+...
+PyMem_Del(buf3);  /* Wrong -- should be PyMem_Free() */
+free(buf2);       /* Right -- allocated via malloc() */
+free(buf1);       /* Fatal -- should be PyMem_Del()  */
+\end{verbatim}
+
+In addition to the functions aimed at handling raw memory blocks from
+the Python heap, objects in Python are allocated and released with
+\cfunction{PyObject_New()}, \cfunction{PyObject_NewVar()} and
+\cfunction{PyObject_Del()}, or with their corresponding macros
+\cfunction{PyObject_NEW()}, \cfunction{PyObject_NEW_VAR()} and
+\cfunction{PyObject_DEL()}.
+
+These will be explained in the next chapter on defining and
+implementing new object types in C.
diff --git a/Doc/api/newtypes.tex b/Doc/api/newtypes.tex
new file mode 100644
index 0000000..870b9d6
--- /dev/null
+++ b/Doc/api/newtypes.tex
@@ -0,0 +1,578 @@
+\chapter{Defining New Object Types \label{newTypes}}
+
+
+\section{Allocating Objects on the Heap
+         \label{allocating-objects}}
+
+\begin{cfuncdesc}{PyObject*}{_PyObject_New}{PyTypeObject *type}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyVarObject*}{_PyObject_NewVar}{PyTypeObject *type, int size}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{_PyObject_Del}{PyObject *op}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyObject_Init}{PyObject *op,
+					    PyTypeObject *type}
+  Initialize a newly-allocated object \var{op} with its type and
+  initial reference.  Returns the initialized object.  If \var{type}
+  indicates that the object participates in the cyclic garbage
+  detector, it it added to the detector's set of observed objects.
+  Other fields of the object are not affected.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyVarObject*}{PyObject_InitVar}{PyVarObject *op,
+						  PyTypeObject *type, int size}
+  This does everything \cfunction{PyObject_Init()} does, and also
+  initializes the length information for a variable-size object.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{\var{TYPE}*}{PyObject_New}{TYPE, PyTypeObject *type}
+  Allocate a new Python object using the C structure type \var{TYPE}
+  and the Python type object \var{type}.  Fields not defined by the
+  Python object header are not initialized; the object's reference
+  count will be one.  The size of the memory
+  allocation is determined from the \member{tp_basicsize} field of the
+  type object.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{\var{TYPE}*}{PyObject_NewVar}{TYPE, PyTypeObject *type,
+                                                int size}
+  Allocate a new Python object using the C structure type \var{TYPE}
+  and the Python type object \var{type}.  Fields not defined by the
+  Python object header are not initialized.  The allocated memory
+  allows for the \var{TYPE} structure plus \var{size} fields of the
+  size given by the \member{tp_itemsize} field of \var{type}.  This is
+  useful for implementing objects like tuples, which are able to
+  determine their size at construction time.  Embedding the array of
+  fields into the same allocation decreases the number of allocations,
+  improving the memory management efficiency.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyObject_Del}{PyObject *op}
+  Releases memory allocated to an object using
+  \cfunction{PyObject_New()} or \cfunction{PyObject_NewVar()}.  This
+  is normally called from the \member{tp_dealloc} handler specified in
+  the object's type.  The fields of the object should not be accessed
+  after this call as the memory is no longer a valid Python object.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{\var{TYPE}*}{PyObject_NEW}{TYPE, PyTypeObject *type}
+  Macro version of \cfunction{PyObject_New()}, to gain performance at
+  the expense of safety.  This does not check \var{type} for a \NULL{}
+  value.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{\var{TYPE}*}{PyObject_NEW_VAR}{TYPE, PyTypeObject *type,
+                                                int size}
+  Macro version of \cfunction{PyObject_NewVar()}, to gain performance
+  at the expense of safety.  This does not check \var{type} for a
+  \NULL{} value.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyObject_DEL}{PyObject *op}
+  Macro version of \cfunction{PyObject_Del()}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{Py_InitModule}{char *name,
+                                            PyMethodDef *methods}
+  Create a new module object based on a name and table of functions,
+  returning the new module object.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{Py_InitModule3}{char *name,
+                                             PyMethodDef *methods,
+                                             char *doc}
+  Create a new module object based on a name and table of functions,
+  returning the new module object.  If \var{doc} is non-\NULL, it will
+  be used to define the docstring for the module.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{Py_InitModule4}{char *name,
+                                             PyMethodDef *methods,
+                                             char *doc, PyObject *self,
+                                             int apiver}
+  Create a new module object based on a name and table of functions,
+  returning the new module object.  If \var{doc} is non-\NULL, it will
+  be used to define the docstring for the module.  If \var{self} is
+  non-\NULL, it will passed to the functions of the module as their
+  (otherwise \NULL) first parameter.  (This was added as an
+  experimental feature, and there are no known uses in the current
+  version of Python.)  For \var{apiver}, the only value which should
+  be passed is defined by the constant \constant{PYTHON_API_VERSION}.
+
+  \note{Most uses of this function should probably be using
+  the \cfunction{Py_InitModule3()} instead; only use this if you are
+  sure you need it.}
+\end{cfuncdesc}
+
+DL_IMPORT
+
+\begin{cvardesc}{PyObject}{_Py_NoneStruct}
+  Object which is visible in Python as \code{None}.  This should only
+  be accessed using the \code{Py_None} macro, which evaluates to a
+  pointer to this object.
+\end{cvardesc}
+
+
+\section{Common Object Structures \label{common-structs}}
+
+PyObject, PyVarObject
+
+PyObject_HEAD, PyObject_HEAD_INIT, PyObject_VAR_HEAD
+
+Typedefs:
+unaryfunc, binaryfunc, ternaryfunc, inquiry, coercion, intargfunc,
+intintargfunc, intobjargproc, intintobjargproc, objobjargproc,
+destructor, printfunc, getattrfunc, getattrofunc, setattrfunc,
+setattrofunc, cmpfunc, reprfunc, hashfunc
+
+\begin{ctypedesc}{PyCFunction}
+  Type of the functions used to implement most Python callables in C.
+\end{ctypedesc}
+
+\begin{ctypedesc}{PyMethodDef}
+  Structure used to describe a method of an extension type.  This
+  structure has four fields:
+
+  \begin{tableiii}{l|l|l}{member}{Field}{C Type}{Meaning}
+    \lineiii{ml_name}{char *}{name of the method}
+    \lineiii{ml_meth}{PyCFunction}{pointer to the C implementation}
+    \lineiii{ml_flags}{int}{flag bits indicating how the call should be
+                            constructed}
+    \lineiii{ml_doc}{char *}{points to the contents of the docstring}
+  \end{tableiii}
+\end{ctypedesc}
+
+The \member{ml_meth} is a C function pointer.  The functions may be of
+different types, but they always return \ctype{PyObject*}.  If the
+function is not of the \ctype{PyCFunction}, the compiler will require
+a cast in the method table.  Even though \ctype{PyCFunction} defines
+the first parameter as \ctype{PyObject*}, it is common that the method
+implementation uses a the specific C type of the \var{self} object.
+
+The flags can have the following values. Only \constant{METH_VARARGS}
+and \constant{METH_KEYWORDS} can be combined; the others can't.
+
+\begin{datadesc}{METH_VARARGS}
+  This is the typical calling convention, where the methods have the
+  type \ctype{PyMethodDef}. The function expects two
+  \ctype{PyObject*}.  The first one is the \var{self} object for
+  methods; for module functions, it has the value given to
+  \cfunction{Py_InitModule4()} (or \NULL{} if
+  \cfunction{Py_InitModule()} was used).  The second parameter
+  (often called \var{args}) is a tuple object representing all
+  arguments. This parameter is typically processed using
+  \cfunction{PyArg_ParseTuple()}.
+\end{datadesc}
+
+\begin{datadesc}{METH_KEYWORDS}
+  Methods with these flags must be of type
+  \ctype{PyCFunctionWithKeywords}.  The function expects three
+  parameters: \var{self}, \var{args}, and a dictionary of all the
+  keyword arguments.  The flag is typically combined with
+  \constant{METH_VARARGS}, and the parameters are typically processed
+  using \cfunction{PyArg_ParseTupleAndKeywords()}.
+\end{datadesc}
+
+\begin{datadesc}{METH_NOARGS}
+  Methods without parameters don't need to check whether arguments are
+  given if they are listed with the \constant{METH_NOARGS} flag.  They
+  need to be of type \ctype{PyNoArgsFunction}: they expect a single
+  single \ctype{PyObject*} as a parameter.  When used with object
+  methods, this parameter is typically named \code{self} and will hold
+  a reference to the object instance.
+\end{datadesc}
+
+\begin{datadesc}{METH_O}
+  Methods with a single object argument can be listed with the
+  \constant{METH_O} flag, instead of invoking
+  \cfunction{PyArg_ParseTuple()} with a \code{"O"} argument. They have
+  the type \ctype{PyCFunction}, with the \var{self} parameter, and a
+  \ctype{PyObject*} parameter representing the single argument.
+\end{datadesc}
+
+\begin{datadesc}{METH_OLDARGS}
+  This calling convention is deprecated.  The method must be of type
+  \ctype{PyCFunction}.  The second argument is \NULL{} if no arguments
+  are given, a single object if exactly one argument is given, and a
+  tuple of objects if more than one argument is given.  There is no
+  way for a function using this convention to distinguish between a
+  call with multiple arguments and a call with a tuple as the only
+  argument.
+\end{datadesc}
+
+\begin{cfuncdesc}{PyObject*}{Py_FindMethod}{PyMethodDef table[],
+                                            PyObject *ob, char *name}
+  Return a bound method object for an extension type implemented in
+  C.  This function also handles the special attribute
+  \member{__methods__},  returning a list of all the method names
+  defined in \var{table}.
+\end{cfuncdesc}
+
+
+\section{Mapping Object Structures \label{mapping-structs}}
+
+\begin{ctypedesc}{PyMappingMethods}
+  Structure used to hold pointers to the functions used to implement
+  the mapping protocol for an extension type.
+\end{ctypedesc}
+
+
+\section{Number Object Structures \label{number-structs}}
+
+\begin{ctypedesc}{PyNumberMethods}
+  Structure used to hold pointers to the functions an extension type
+  uses to implement the number protocol.
+\end{ctypedesc}
+
+
+\section{Sequence Object Structures \label{sequence-structs}}
+
+\begin{ctypedesc}{PySequenceMethods}
+  Structure used to hold pointers to the functions which an object
+  uses to implement the sequence protocol.
+\end{ctypedesc}
+
+
+\section{Buffer Object Structures \label{buffer-structs}}
+\sectionauthor{Greg J. Stein}{greg@lyra.org}
+
+The buffer interface exports a model where an object can expose its
+internal data as a set of chunks of data, where each chunk is
+specified as a pointer/length pair.  These chunks are called
+\dfn{segments} and are presumed to be non-contiguous in memory.
+
+If an object does not export the buffer interface, then its
+\member{tp_as_buffer} member in the \ctype{PyTypeObject} structure
+should be \NULL.  Otherwise, the \member{tp_as_buffer} will point to
+a \ctype{PyBufferProcs} structure.
+
+\note{It is very important that your \ctype{PyTypeObject} structure
+uses \constant{Py_TPFLAGS_DEFAULT} for the value of the
+\member{tp_flags} member rather than \code{0}.  This tells the Python
+runtime that your \ctype{PyBufferProcs} structure contains the
+\member{bf_getcharbuffer} slot. Older versions of Python did not have
+this member, so a new Python interpreter using an old extension needs
+to be able to test for its presence before using it.}
+
+\begin{ctypedesc}{PyBufferProcs}
+  Structure used to hold the function pointers which define an
+  implementation of the buffer protocol.
+
+  The first slot is \member{bf_getreadbuffer}, of type
+  \ctype{getreadbufferproc}.  If this slot is \NULL, then the object
+  does not support reading from the internal data.  This is
+  non-sensical, so implementors should fill this in, but callers
+  should test that the slot contains a non-\NULL{} value.
+
+  The next slot is \member{bf_getwritebuffer} having type
+  \ctype{getwritebufferproc}.  This slot may be \NULL{} if the object
+  does not allow writing into its returned buffers.
+
+  The third slot is \member{bf_getsegcount}, with type
+  \ctype{getsegcountproc}.  This slot must not be \NULL{} and is used
+  to inform the caller how many segments the object contains.  Simple
+  objects such as \ctype{PyString_Type} and \ctype{PyBuffer_Type}
+  objects contain a single segment.
+
+  The last slot is \member{bf_getcharbuffer}, of type
+  \ctype{getcharbufferproc}.  This slot will only be present if the
+  \constant{Py_TPFLAGS_HAVE_GETCHARBUFFER} flag is present in the
+  \member{tp_flags} field of the object's \ctype{PyTypeObject}.
+  Before using this slot, the caller should test whether it is present
+  by using the
+  \cfunction{PyType_HasFeature()}\ttindex{PyType_HasFeature()}
+  function.  If present, it may be \NULL, indicating that the object's
+  contents cannot be used as \emph{8-bit characters}.
+  The slot function may also raise an error if the object's contents
+  cannot be interpreted as 8-bit characters.  For example, if the
+  object is an array which is configured to hold floating point
+  values, an exception may be raised if a caller attempts to use
+  \member{bf_getcharbuffer} to fetch a sequence of 8-bit characters.
+  This notion of exporting the internal buffers as ``text'' is used to
+  distinguish between objects that are binary in nature, and those
+  which have character-based content.
+
+  \note{The current policy seems to state that these characters
+  may be multi-byte characters. This implies that a buffer size of
+  \var{N} does not mean there are \var{N} characters present.}
+\end{ctypedesc}
+
+\begin{datadesc}{Py_TPFLAGS_HAVE_GETCHARBUFFER}
+  Flag bit set in the type structure to indicate that the
+  \member{bf_getcharbuffer} slot is known.  This being set does not
+  indicate that the object supports the buffer interface or that the
+  \member{bf_getcharbuffer} slot is non-\NULL.
+\end{datadesc}
+
+\begin{ctypedesc}[getreadbufferproc]{int (*getreadbufferproc)
+                            (PyObject *self, int segment, void **ptrptr)}
+  Return a pointer to a readable segment of the buffer.  This function
+  is allowed to raise an exception, in which case it must return
+  \code{-1}.  The \var{segment} which is passed must be zero or
+  positive, and strictly less than the number of segments returned by
+  the \member{bf_getsegcount} slot function.  On success, it returns
+  the length of the buffer memory, and sets \code{*\var{ptrptr}} to a
+  pointer to that memory.
+\end{ctypedesc}
+
+\begin{ctypedesc}[getwritebufferproc]{int (*getwritebufferproc)
+                            (PyObject *self, int segment, void **ptrptr)}
+  Return a pointer to a writable memory buffer in
+  \code{*\var{ptrptr}}, and the length of that segment as the function
+  return value.  The memory buffer must correspond to buffer segment
+  \var{segment}.  Must return \code{-1} and set an exception on
+  error.  \exception{TypeError} should be raised if the object only
+  supports read-only buffers, and \exception{SystemError} should be
+  raised when \var{segment} specifies a segment that doesn't exist.
+% Why doesn't it raise ValueError for this one?
+% GJS: because you shouldn't be calling it with an invalid
+%      segment. That indicates a blatant programming error in the C
+%      code.
+\end{ctypedesc}
+
+\begin{ctypedesc}[getsegcountproc]{int (*getsegcountproc)
+                            (PyObject *self, int *lenp)}
+  Return the number of memory segments which comprise the buffer.  If
+  \var{lenp} is not \NULL, the implementation must report the sum of
+  the sizes (in bytes) of all segments in \code{*\var{lenp}}.
+  The function cannot fail.
+\end{ctypedesc}
+
+\begin{ctypedesc}[getcharbufferproc]{int (*getcharbufferproc)
+                            (PyObject *self, int segment, const char **ptrptr)}
+\end{ctypedesc}
+
+
+\section{Supporting the Iterator Protocol
+         \label{supporting-iteration}}
+
+
+\section{Supporting Cyclic Garbarge Collection
+         \label{supporting-cycle-detection}}
+
+Python's support for detecting and collecting garbage which involves
+circular references requires support from object types which are
+``containers'' for other objects which may also be containers.  Types
+which do not store references to other objects, or which only store
+references to atomic types (such as numbers or strings), do not need
+to provide any explicit support for garbage collection.
+
+To create a container type, the \member{tp_flags} field of the type
+object must include the \constant{Py_TPFLAGS_HAVE_GC} and provide an
+implementation of the \member{tp_traverse} handler.  If instances of the
+type are mutable, a \member{tp_clear} implementation must also be
+provided.
+
+\begin{datadesc}{Py_TPFLAGS_HAVE_GC}
+  Objects with a type with this flag set must conform with the rules
+  documented here.  For convenience these objects will be referred to
+  as container objects.
+\end{datadesc}
+
+Constructors for container types must conform to two rules:
+
+\begin{enumerate}
+\item  The memory for the object must be allocated using
+       \cfunction{PyObject_GC_New()} or \cfunction{PyObject_GC_VarNew()}.
+
+\item  Once all the fields which may contain references to other
+       containers are initialized, it must call
+       \cfunction{PyObject_GC_Track()}.
+\end{enumerate}
+
+\begin{cfuncdesc}{\var{TYPE}*}{PyObject_GC_New}{TYPE, PyTypeObject *type}
+  Analogous to \cfunction{PyObject_New()} but for container objects with
+  the \constant{Py_TPFLAGS_HAVE_GC} flag set.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{\var{TYPE}*}{PyObject_GC_NewVar}{TYPE, PyTypeObject *type,
+                                                   int size}
+  Analogous to \cfunction{PyObject_NewVar()} but for container objects
+  with the \constant{Py_TPFLAGS_HAVE_GC} flag set.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyVarObject *}{PyObject_GC_Resize}{PyVarObject *op, int}
+  Resize an object allocated by \cfunction{PyObject_NewVar()}.  Returns
+  the resized object or \NULL{} on failure.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyObject_GC_Track}{PyObject *op}
+  Adds the object \var{op} to the set of container objects tracked by
+  the collector.  The collector can run at unexpected times so objects
+  must be valid while being tracked.  This should be called once all
+  the fields followed by the \member{tp_traverse} handler become valid,
+  usually near the end of the constructor.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{_PyObject_GC_TRACK}{PyObject *op}
+  A macro version of \cfunction{PyObject_GC_Track()}.  It should not be
+  used for extension modules.
+\end{cfuncdesc}
+
+Similarly, the deallocator for the object must conform to a similar
+pair of rules:
+
+\begin{enumerate}
+\item  Before fields which refer to other containers are invalidated,
+       \cfunction{PyObject_GC_UnTrack()} must be called.
+
+\item  The object's memory must be deallocated using
+       \cfunction{PyObject_GC_Del()}.
+\end{enumerate}
+
+\begin{cfuncdesc}{void}{PyObject_GC_Del}{PyObject *op}
+  Releases memory allocated to an object using
+  \cfunction{PyObject_GC_New()} or \cfunction{PyObject_GC_NewVar()}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyObject_GC_UnTrack}{PyObject *op}
+  Remove the object \var{op} from the set of container objects tracked
+  by the collector.  Note that \cfunction{PyObject_GC_Track()} can be
+  called again on this object to add it back to the set of tracked
+  objects.  The deallocator (\member{tp_dealloc} handler) should call
+  this for the object before any of the fields used by the
+  \member{tp_traverse} handler become invalid.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{_PyObject_GC_UNTRACK}{PyObject *op}
+  A macro version of \cfunction{PyObject_GC_UnTrack()}.  It should not be
+  used for extension modules.
+\end{cfuncdesc}
+
+The \member{tp_traverse} handler accepts a function parameter of this
+type:
+
+\begin{ctypedesc}[visitproc]{int (*visitproc)(PyObject *object, void *arg)}
+  Type of the visitor function passed to the \member{tp_traverse}
+  handler.  The function should be called with an object to traverse
+  as \var{object} and the third parameter to the \member{tp_traverse}
+  handler as \var{arg}.
+\end{ctypedesc}
+
+The \member{tp_traverse} handler must have the following type:
+
+\begin{ctypedesc}[traverseproc]{int (*traverseproc)(PyObject *self,
+                                visitproc visit, void *arg)}
+  Traversal function for a container object.  Implementations must
+  call the \var{visit} function for each object directly contained by
+  \var{self}, with the parameters to \var{visit} being the contained
+  object and the \var{arg} value passed to the handler.  If
+  \var{visit} returns a non-zero value then an error has occurred and
+  that value should be returned immediately.
+\end{ctypedesc}
+
+The \member{tp_clear} handler must be of the \ctype{inquiry} type, or
+\NULL{} if the object is immutable.
+
+\begin{ctypedesc}[inquiry]{int (*inquiry)(PyObject *self)}
+  Drop references that may have created reference cycles.  Immutable
+  objects do not have to define this method since they can never
+  directly create reference cycles.  Note that the object must still
+  be valid after calling this method (don't just call
+  \cfunction{Py_DECREF()} on a reference).  The collector will call
+  this method if it detects that this object is involved in a
+  reference cycle.
+\end{ctypedesc}
+
+
+\subsection{Example Cycle Collector Support
+            \label{example-cycle-support}}
+
+This example shows only enough of the implementation of an extension
+type to show how the garbage collector support needs to be added.  It
+shows the definition of the object structure, the
+\member{tp_traverse}, \member{tp_clear} and \member{tp_dealloc}
+implementations, the type structure, and a constructor --- the module
+initialization needed to export the constructor to Python is not shown
+as there are no special considerations there for the collector.  To
+make this interesting, assume that the module exposes ways for the
+\member{container} field of the object to be modified.  Note that
+since no checks are made on the type of the object used to initialize
+\member{container}, we have to assume that it may be a container.
+
+\begin{verbatim}
+#include "Python.h"
+
+typedef struct {
+    PyObject_HEAD
+    PyObject *container;
+} MyObject;
+
+static int
+my_traverse(MyObject *self, visitproc visit, void *arg)
+{
+    if (self->container != NULL)
+        return visit(self->container, arg);
+    else
+        return 0;
+}
+
+static int
+my_clear(MyObject *self)
+{
+    Py_XDECREF(self->container);
+    self->container = NULL;
+
+    return 0;
+}
+
+static void
+my_dealloc(MyObject *self)
+{
+    PyObject_GC_UnTrack((PyObject *) self);
+    Py_XDECREF(self->container);
+    PyObject_GC_Del(self);
+}
+\end{verbatim}
+
+\begin{verbatim}
+statichere PyTypeObject
+MyObject_Type = {
+    PyObject_HEAD_INIT(NULL)
+    0,
+    "MyObject",
+    sizeof(MyObject),
+    0,
+    (destructor)my_dealloc,     /* tp_dealloc */
+    0,                          /* tp_print */
+    0,                          /* tp_getattr */
+    0,                          /* tp_setattr */
+    0,                          /* tp_compare */
+    0,                          /* tp_repr */
+    0,                          /* tp_as_number */
+    0,                          /* tp_as_sequence */
+    0,                          /* tp_as_mapping */
+    0,                          /* tp_hash */
+    0,                          /* tp_call */
+    0,                          /* tp_str */
+    0,                          /* tp_getattro */
+    0,                          /* tp_setattro */
+    0,                          /* tp_as_buffer */
+    Py_TPFLAGS_DEFAULT | Py_TPFLAGS_HAVE_GC,
+    0,                          /* tp_doc */
+    (traverseproc)my_traverse,  /* tp_traverse */
+    (inquiry)my_clear,          /* tp_clear */
+    0,                          /* tp_richcompare */
+    0,                          /* tp_weaklistoffset */
+};
+
+/* This constructor should be made accessible from Python. */
+static PyObject *
+new_object(PyObject *unused, PyObject *args)
+{
+    PyObject *container = NULL;
+    MyObject *result = NULL;
+
+    if (PyArg_ParseTuple(args, "|O:new_object", &container)) {
+        result = PyObject_GC_New(MyObject, &MyObject_Type);
+        if (result != NULL) {
+            result->container = container;
+            PyObject_GC_Track(result);
+        }
+    }
+    return (PyObject *) result;
+}
+\end{verbatim}
diff --git a/Doc/api/refcounting.tex b/Doc/api/refcounting.tex
new file mode 100644
index 0000000..03530f0
--- /dev/null
+++ b/Doc/api/refcounting.tex
@@ -0,0 +1,48 @@
+\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.
+
+  \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}.
diff --git a/Doc/api/utilities.tex b/Doc/api/utilities.tex
new file mode 100644
index 0000000..5820524
--- /dev/null
+++ b/Doc/api/utilities.tex
@@ -0,0 +1,320 @@
+\chapter{Utilities \label{utilities}}
+
+The functions in this chapter perform various utility tasks, ranging
+from helping C code be more portable across platforms, using Python
+modules from C, and parsing function arguments and constructing Python
+values from C values.
+
+
+\section{Operating System 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 \constant{USE_STACKCHECK}
+  is defined (currently on Windows using the Microsoft Visual \Cpp{}
+  compiler and on the Macintosh).  \constant{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}
+  This is a higher-level interface that calls the current ``import
+  hook function''.  It invokes the \function{__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 \module{rexec}\refstmodindex{rexec}
+  or \module{ihooks}\refstmodindex{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 \function{reload()}\bifuncindex{reload}, as
+  the standard \function{reload()} function calls this function
+  directly.  Return a new reference to the reloaded module, or \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.
+  \note{This function does not load or import the module; if the
+  module wasn't already loaded, you will get an empty module object.
+  Use \cfunction{PyImport_ImportModule()} or one of its variants to
+  import a module.  Return \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 \function{compile()}\bifuncindex{compile}, load
+  the module.  Return a new reference to the module object, or \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. \file{.pyc} and \file{.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{cfuncdesc}{PyObject*}{_PyImport_FindExtension}{char *, char *}
+  For internal use only.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{_PyImport_FixupExtension}{char *, char *}
+  For internal use only.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyImport_ImportFrozenModule}{char *name}
+  Load a frozen module named \var{name}.  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 \cfunction{PyImport_ImportModule()}.  (Note
+  the misnomer --- this function would reload the module if it was
+  already imported.)
+\end{cfuncdesc}
+
+\begin{ctypedesc}[_frozen]{struct _frozen}
+  This is the structure type definition for frozen module descriptors,
+  as generated by the \program{freeze}\index{freeze utility} utility
+  (see \file{Tools/freeze/} in the Python source distribution).  Its
+  definition, found in \file{Include/import.h}, is:
+
+\begin{verbatim}
+struct _frozen {
+    char *name;
+    unsigned char *code;
+    int size;
+};
+\end{verbatim}
+\end{ctypedesc}
+
+\begin{cvardesc}{struct _frozen*}{PyImport_FrozenModules}
+  This pointer is initialized to point to an array of \ctype{struct
+  _frozen} records, terminated by one whose members are all \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}
+
+\begin{cfuncdesc}{int}{PyImport_AppendInittab}{char *name,
+                                               void (*initfunc)(void)}
+  Add a single module to the existing table of built-in modules.  This
+  is a convenience wrapper around
+  \cfunction{PyImport_ExtendInittab()}, returning \code{-1} if the
+  table could not be extended.  The new module can be imported by the
+  name \var{name}, and uses the function \var{initfunc} as the
+  initialization function called on the first attempted import.  This
+  should be called before \cfunction{Py_Initialize()}.
+\end{cfuncdesc}
+
+\begin{ctypedesc}[_inittab]{struct _inittab}
+  Structure describing a single entry in the list of built-in
+  modules.  Each of these structures gives the name and initialization
+  function for a module built into the interpreter.  Programs which
+  embed Python may use an array of these structures in conjunction
+  with \cfunction{PyImport_ExtendInittab()} to provide additional
+  built-in modules.  The structure is defined in
+  \file{Include/import.h} as:
+
+\begin{verbatim}
+struct _inittab {
+    char *name;
+    void (*initfunc)(void);
+};
+\end{verbatim}
+\end{ctypedesc}
+
+\begin{cfuncdesc}{int}{PyImport_ExtendInittab}{struct _inittab *newtab}
+  Add a collection of modules to the table of built-in modules.  The
+  \var{newtab} array must end with a sentinel entry which contains
+  \NULL{} for the \member{name} field; failure to provide the sentinel
+  value can result in a memory fault.  Returns \code{0} on success or
+  \code{-1} if insufficient memory could be allocated to extend the
+  internal table.  In the event of failure, no modules are added to
+  the internal table.  This should be called before
+  \cfunction{Py_Initialize()}.
+\end{cfuncdesc}
+
+
+\section{Parsing arguments and building values
+         \label{arg-parsing}}
+
+These functions are useful when creating your own extensions functions
+and methods.  Additional information and examples are available in
+\citetitle[../ext/ext.html]{Extending and Embedding the Python
+Interpreter}.
+
+\begin{cfuncdesc}{int}{PyArg_ParseTuple}{PyObject *args, char *format,
+                                         \moreargs}
+  Parse the parameters of a function that takes only positional
+  parameters into local variables.  Returns true on success; on
+  failure, it returns false and raises the appropriate exception.  See
+  \citetitle[../ext/parseTuple.html]{Extending and Embedding the
+  Python Interpreter} for more information.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyArg_ParseTupleAndKeywords}{PyObject *args,
+                       PyObject *kw, char *format, char *keywords[],
+                       \moreargs}
+  Parse the parameters of a function that takes both positional and
+  keyword parameters into local variables.  Returns true on success;
+  on failure, it returns false and raises the appropriate exception.
+  See \citetitle[../ext/parseTupleAndKeywords.html]{Extending and
+  Embedding the Python Interpreter} for more information.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyArg_Parse}{PyObject *args, char *format,
+                                    \moreargs}
+  Function used to deconstruct the argument lists of ``old-style''
+  functions --- these are functions which use the
+  \constant{METH_OLDARGS} parameter parsing method.  This is not
+  recommended for use in parameter parsing in new code, and most code
+  in the standard interpreter has been modified to no longer use this
+  for that purpose.  It does remain a convenient way to decompose
+  other tuples, however, and may continue to be used for that
+  purpose.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{Py_BuildValue}{char *format,
+                                            \moreargs}
+  Create a new value based on a format string similar to those
+  accepted by the \cfunction{PyArg_Parse*()} family of functions and a
+  sequence of values.  Returns the value or \NULL{} in the case of an
+  error; an exception will be raised if \NULL{} is returned.  For more
+  information on the format string and additional parameters, see
+  \citetitle[../ext/buildValue.html]{Extending and Embedding the
+  Python Interpreter}.
+\end{cfuncdesc}
diff --git a/Doc/api/veryhigh.tex b/Doc/api/veryhigh.tex
new file mode 100644
index 0000000..e7cb094
--- /dev/null
+++ b/Doc/api/veryhigh.tex
@@ -0,0 +1,141 @@
+\chapter{The Very High Level Layer \label{veryhigh}}
+
+
+The functions in this chapter will let you execute Python source code
+given in a file or a buffer, but they will not let you interact in a
+more detailed way with the interpreter.
+
+Several of these functions accept a start symbol from the grammar as a 
+parameter.  The available start symbols are \constant{Py_eval_input},
+\constant{Py_file_input}, and \constant{Py_single_input}.  These are
+described following the functions which accept them as parameters.
+
+Note also that several of these functions take \ctype{FILE*}
+parameters.  On particular issue which needs to be handled carefully
+is that the \ctype{FILE} structure for different C libraries can be
+different and incompatible.  Under Windows (at least), it is possible
+for dynamically linked extensions to actually use different libraries,
+so care should be taken that \ctype{FILE*} parameters are only passed
+to these functions if it is certain that they were created by the same
+library that the Python runtime is using.
+
+
+\begin{cfuncdesc}{int}{Py_Main}{int argc, char **argv}
+  The main program for the standard interpreter.  This is made
+  available for programs which embed Python.  The \var{argc} and
+  \var{argv} parameters should be prepared exactly as those which are
+  passed to a C program's \cfunction{main()} function.  It is
+  important to note that the argument list may be modified (but the
+  contents of the strings pointed to by the argument list are not).
+  The return value will be the integer passed to the
+  \function{sys.exit()} function, \code{1} if the interpreter exits
+  due to an exception, or \code{2} if the parameter list does not
+  represent a valid Python command line.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyRun_AnyFile}{FILE *fp, char *filename}
+  If \var{fp} refers to a file associated with an interactive device
+  (console or terminal input or \UNIX{} pseudo-terminal), return the
+  value of \cfunction{PyRun_InteractiveLoop()}, otherwise return the
+  result of \cfunction{PyRun_SimpleFile()}.  If \var{filename} is
+  \NULL, this function uses \code{"???"} as the filename.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyRun_SimpleString}{char *command}
+  Executes the Python source code from \var{command} in the
+  \module{__main__} module.  If \module{__main__} does not already
+  exist, it is created.  Returns \code{0} on success or \code{-1} if
+  an exception was raised.  If there was an error, there is no way to
+  get the exception information.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyRun_SimpleFile}{FILE *fp, char *filename}
+  Similar to \cfunction{PyRun_SimpleString()}, but the Python source
+  code is read from \var{fp} instead of an in-memory string.
+  \var{filename} should be the name of the file.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyRun_InteractiveOne}{FILE *fp, char *filename}
+  Read and execute a single statement from a file associated with an
+  interactive device.  If \var{filename} is \NULL, \code{"???"} is
+  used instead.  The user will be prompted using \code{sys.ps1} and
+  \code{sys.ps2}.  Returns \code{0} when the input was executed
+  successfully, \code{-1} if there was an exception, or an error code
+  from the \file{errcode.h} include file distributed as part of Python
+  if there was a parse error.  (Note that \file{errcode.h} is not
+  included by \file{Python.h}, so must be included specifically if
+  needed.)
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyRun_InteractiveLoop}{FILE *fp, char *filename}
+  Read and execute statements from a file associated with an
+  interactive device until \EOF{} is reached.  If \var{filename} is
+  \NULL, \code{"???"} is used instead.  The user will be prompted
+  using \code{sys.ps1} and \code{sys.ps2}.  Returns \code{0} at \EOF.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{struct _node*}{PyParser_SimpleParseString}{char *str,
+                                                             int start}
+  Parse Python source code from \var{str} using the start token
+  \var{start}.  The result can be used to create a code object which
+  can be evaluated efficiently.  This is useful if a code fragment
+  must be evaluated many times.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{struct _node*}{PyParser_SimpleParseFile}{FILE *fp,
+                                 char *filename, int start}
+  Similar to \cfunction{PyParser_SimpleParseString()}, but the Python
+  source code is read from \var{fp} instead of an in-memory string.
+  \var{filename} should be the name of the file.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyRun_String}{char *str, int start,
+                                           PyObject *globals,
+                                           PyObject *locals}
+  Execute Python source code from \var{str} in the context specified
+  by the dictionaries \var{globals} and \var{locals}.  The parameter
+  \var{start} specifies the start token that should be used to parse
+  the source code.
+
+  Returns the result of executing the code as a Python object, or
+  \NULL{} if an exception was raised.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyRun_File}{FILE *fp, char *filename,
+                                         int start, PyObject *globals,
+                                         PyObject *locals}
+  Similar to \cfunction{PyRun_String()}, but the Python source code is
+  read from \var{fp} instead of an in-memory string.
+  \var{filename} should be the name of the file.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{Py_CompileString}{char *str, char *filename,
+                                               int start}
+  Parse and compile the Python source code in \var{str}, returning the
+  resulting code object.  The start token is given by \var{start};
+  this can be used to constrain the code which can be compiled and should
+  be \constant{Py_eval_input}, \constant{Py_file_input}, or
+  \constant{Py_single_input}.  The filename specified by
+  \var{filename} is used to construct the code object and may appear
+  in tracebacks or \exception{SyntaxError} exception messages.  This
+  returns \NULL{} if the code cannot be parsed or compiled.
+\end{cfuncdesc}
+
+\begin{cvardesc}{int}{Py_eval_input}
+  The start symbol from the Python grammar for isolated expressions;
+  for use with
+  \cfunction{Py_CompileString()}\ttindex{Py_CompileString()}.
+\end{cvardesc}
+
+\begin{cvardesc}{int}{Py_file_input}
+  The start symbol from the Python grammar for sequences of statements
+  as read from a file or other source; for use with
+  \cfunction{Py_CompileString()}\ttindex{Py_CompileString()}.  This is
+  the symbol to use when compiling arbitrarily long Python source code.
+\end{cvardesc}
+
+\begin{cvardesc}{int}{Py_single_input}
+  The start symbol from the Python grammar for a single statement; for
+  use with \cfunction{Py_CompileString()}\ttindex{Py_CompileString()}.
+  This is the symbol used for the interactive interpreter loop.
+\end{cvardesc}