add hg and python

12 files changed, 11392 insertions, 0 deletions

diff --git a/sys/src/cmd/python/Doc/api/abstract.tex b/sys/src/cmd/python/Doc/api/abstract.tex
new file mode 100644
index 000000000..5bd5a9a3d
--- /dev/null
+++ b/sys/src/cmd/python/Doc/api/abstract.tex
@@ -0,0 +1,1057 @@
+\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.
+
+It is not possible to use these functions on objects that are not properly
+initialized, such as a list object that has been created by
+\cfunction{PyList_New()}, but whose items have not been set to some
+non-\code{NULL} value yet.
+
+\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, const 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,
+                                                     const 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,
+                                               const 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, const 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}{PyObject*}{PyObject_RichCompare}{PyObject *o1,
+                                                   PyObject *o2, int opid}
+  Compare the values of \var{o1} and \var{o2} using the operation
+  specified by \var{opid}, which must be one of
+  \constant{Py_LT},
+  \constant{Py_LE},
+  \constant{Py_EQ},
+  \constant{Py_NE},
+  \constant{Py_GT}, or
+  \constant{Py_GE}, corresponding to
+  \code{<},
+  \code{<=},
+  \code{==},
+  \code{!=},
+  \code{>}, or
+  \code{>=} respectively. This is the equivalent of the Python expression
+  \samp{\var{o1} op \var{o2}}, where \code{op} is the operator
+  corresponding to \var{opid}. Returns the value of the comparison on
+  success, or \NULL{} on failure.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyObject_RichCompareBool}{PyObject *o1,
+                                                 PyObject *o2, int opid}
+  Compare the values of \var{o1} and \var{o2} using the operation
+  specified by \var{opid}, which must be one of
+  \constant{Py_LT},
+  \constant{Py_LE},
+  \constant{Py_EQ},
+  \constant{Py_NE},
+  \constant{Py_GT}, or
+  \constant{Py_GE}, corresponding to
+  \code{<},
+  \code{<=},
+  \code{==},
+  \code{!=},
+  \code{>}, or
+  \code{>=} respectively. Returns \code{-1} on error, \code{0} if the
+  result is false, \code{1} otherwise. This is the equivalent of the
+  Python expression \samp{\var{o1} op \var{o2}}, where
+  \code{op} is the operator corresponding to \var{opid}.
+\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{unicode(\var{o})}.  Called by the
+  \function{unicode()}\bifuncindex{unicode} built-in function.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyObject_IsInstance}{PyObject *inst, PyObject *cls}
+  Returns \code{1} if \var{inst} is an instance of the class \var{cls}
+  or a subclass of \var{cls}, or \code{0} if not.  On error, returns
+  \code{-1} and sets an exception.  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{cls}
+  is a tuple, the check will be done against every entry in \var{cls}.
+  The result will be \code{1} when at least one of the checks returns
+  \code{1}, otherwise it will be \code{0}. If \var{inst} is not a class
+  instance and \var{cls} is neither a type object, nor a class object,
+  nor a tuple, \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}
+  \versionchanged[Support for a tuple as the second argument added]{2.2}
+\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 \var{cls}
+  is a tuple, the check will be done against every entry in \var{cls}.
+  The result will be \code{1} when at least one of the checks returns
+  \code{1}, otherwise it will be \code{0}. If either \var{derived} or
+  \var{cls} is not an actual class object (or tuple), this function
+  uses the generic algorithm described above.
+  \versionadded{2.1}
+  \versionchanged[Older versions of Python did not support a tuple
+                  as the second argument]{2.3}
+\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_Call}{PyObject *callable_object,
+                                            PyObject *args,
+                                            PyObject *kw}
+  Call a callable Python object \var{callable_object}, with arguments
+  given by the tuple \var{args}, and named arguments given by the
+  dictionary \var{kw}. If no named arguments are needed, \var{kw} may
+  be \NULL{}. \var{args} must not be \NULL{}, use an empty tuple if
+  no arguments are needed. 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}, \var{kw})}
+  or \samp{\var{callable_object}(*\var{args}, **\var{kw})}.
+  \bifuncindex{apply}
+  \versionadded{2.2}
+\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,
+                                                    char *format, \moreargs}
+  Call a callable Python object \var{callable}, 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},
+  \var{args})} or \samp{\var{callable}(*\var{args})}.
+  Note that if you only pass \ctype{PyObject *} args,
+  \cfunction{PyObject_CallFunctionObjArgs} is a faster alternative.
+  \bifuncindex{apply}
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyObject_CallMethod}{PyObject *o,
+                                                  char *method, char *format,
+                                                  \moreargs}
+  Call the method named \var{method} of object \var{o} with a variable
+  number of C arguments.  The C arguments are described by a
+  \cfunction{Py_BuildValue()} format string that should 
+  produce a tuple.  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 if you only pass \ctype{PyObject *} args,
+  \cfunction{PyObject_CallMethodObjArgs} is a faster alternative.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyObject_CallFunctionObjArgs}{PyObject *callable,
+                                                           \moreargs,
+                                                           \code{NULL}}
+  Call a callable Python object \var{callable}, with a variable
+  number of \ctype{PyObject*} arguments.  The arguments are provided
+  as a variable number of parameters followed by \NULL.
+  Returns the result of the call on success, or \NULL{} on failure.
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyObject_CallMethodObjArgs}{PyObject *o,
+                                                         PyObject *name,
+                                                         \moreargs,
+                                                         \code{NULL}}
+  Calls a method of the object \var{o}, where the name of the method
+  is given as a Python string object in \var{name}.  It is called with
+  a variable number of \ctype{PyObject*} arguments.  The arguments are
+  provided as a variable number of parameters followed by \NULL.
+  Returns the result of the call on success, or \NULL{} on failure.
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{long}{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}}.  On failure, return \code{-1}. 
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{int}{PyObject_Not}{PyObject *o}
+  Returns \code{0} if the object \var{o} is considered to be true, and
+  \code{1} otherwise.  This is equivalent to the Python expression
+  \samp{not \var{o}}.  On failure, return \code{-1}. 
+\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}
+  This function increments the reference count of the return value.
+  There's really no reason to use this function instead of the
+  common expression \code{\var{o}->ob_type}, which returns a pointer
+  of type \ctype{PyTypeObject*}, except when the incremented reference
+  count is needed.
+\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}{Py_ssize_t}{PyObject_Length}{PyObject *o}
+\cfuncline{Py_ssize_t}{PyObject_Size}{PyObject *o}
+  Return the length of object \var{o}.  If the object \var{o} provides
+  either the 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}
+
+\begin{cfuncdesc}{PyObject*}{PyObject_GetIter}{PyObject *o}
+  This is equivalent to the Python expression \samp{iter(\var{o})}.
+  It returns a new iterator for the object argument, or the object 
+  itself if the object is already an iterator.  Raises
+  \exception{TypeError} and returns \NULL{} if the object cannot be
+  iterated.
+\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{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*}{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 floor 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} >>= \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.  If the argument is outside the integer range
+  a long object will be returned instead. 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}
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_Index}{PyObject *o}
+  Returns the \var{o} converted to a Python int or long on success or \NULL{}
+  with a TypeError exception raised on failure.
+  \versionadded{2.5}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{Py_ssize_t}{PyNumber_AsSsize_t}{PyObject *o, PyObject *exc}
+  Returns \var{o} converted to a Py_ssize_t value if \var{o}
+  can be interpreted as an integer. If \var{o} can be converted to a Python
+  int or long but the attempt to convert to a Py_ssize_t value
+  would raise an \exception{OverflowError}, then the \var{exc} argument
+  is the type of exception that will be raised (usually \exception{IndexError}
+  or \exception{OverflowError}).  If \var{exc} is \NULL{}, then the exception
+  is cleared and the value is clipped to \var{PY_SSIZE_T_MIN}
+  for a negative integer or \var{PY_SSIZE_T_MAX} for a positive integer.
+  \versionadded{2.5}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyIndex_Check}{PyObject *o}
+  Returns True if \var{o} is an index integer (has the nb_index slot of 
+  the tp_as_number structure filled in).  
+  \versionadded{2.5}
+\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}{Py_ssize_t}{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}{Py_ssize_t}{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, Py_ssize_t 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, Py_ssize_t 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, Py_ssize_t 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, Py_ssize_t i1, Py_ssize_t 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, Py_ssize_t 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}}.  This function \emph{does not}
+  steal a reference to \var{v}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PySequence_DelItem}{PyObject *o, Py_ssize_t 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, Py_ssize_t i1,
+                                            Py_ssize_t 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, Py_ssize_t i1, Py_ssize_t 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}{Py_ssize_t}{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}{Py_ssize_t}{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} or \NULL{} on failure.  If \var{o} is a tuple,
+  a new reference will be returned, otherwise a tuple will be
+  constructed with the appropriate contents.  This is equivalent
+  to the Python expression \samp{tuple(\var{o})}.
+  \bifuncindex{tuple}
+\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, Py_ssize_t i}
+  Return the \var{i}th element of \var{o}, assuming that \var{o} was
+  returned by \cfunction{PySequence_Fast()}, \var{o} is not \NULL,
+  and that \var{i} is within bounds.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject**}{PySequence_Fast_ITEMS}{PyObject *o}
+  Return the underlying array of PyObject pointers.  Assumes that
+  \var{o} was returned by \cfunction{PySequence_Fast()} and
+  \var{o} is not \NULL.
+  \versionadded{2.4}  
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PySequence_ITEM}{PyObject *o, Py_ssize_t i}
+  Return the \var{i}th element of \var{o} or \NULL{} on failure.
+  Macro form of \cfunction{PySequence_GetItem()} but without checking
+  that \cfunction{PySequence_Check(\var{o})} is true and without
+  adjustment for negative indices.
+  \versionadded{2.3}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{Py_ssize_t}{PySequence_Fast_GET_SIZE}{PyObject *o}
+  Returns the length of \var{o}, assuming that \var{o} was
+  returned by \cfunction{PySequence_Fast()} and that \var{o} is
+  not \NULL.  The size can also be gotten by calling
+  \cfunction{PySequence_Size()} on \var{o}, but
+  \cfunction{PySequence_Fast_GET_SIZE()} is faster because it can
+  assume \var{o} is a list or tuple.
+\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}{Py_ssize_t}{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_GetIter(obj);
+PyObject *item;
+
+if (iterator == NULL) {
+    /* propagate error */
+}
+
+while (item = PyIter_Next(iterator)) {
+    /* do something with item */
+    ...
+    /* release reference when done */
+    Py_DECREF(item);
+}
+
+Py_DECREF(iterator);
+
+if (PyErr_Occurred()) {
+    /* propagate error */
+}
+else {
+    /* continue doing useful work */
+}
+\end{verbatim}
+
+
+\section{Buffer Protocol \label{abstract-buffer}}
+
+\begin{cfuncdesc}{int}{PyObject_AsCharBuffer}{PyObject *obj,
+                                              const char **buffer,
+                                              Py_ssize_t *buffer_len}
+  Returns a pointer to a read-only memory location useable as character-
+  based input.  The \var{obj} argument must support the single-segment
+  character buffer interface.  On success, returns \code{0}, sets
+  \var{buffer} to the memory location and \var{buffer_len} to the buffer
+  length.  Returns \code{-1} and sets a \exception{TypeError} on error.
+  \versionadded{1.6}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyObject_AsReadBuffer}{PyObject *obj,
+                                              const void **buffer,
+                                              Py_ssize_t *buffer_len}
+  Returns a pointer to a read-only memory location containing
+  arbitrary data.  The \var{obj} argument must support the
+  single-segment readable buffer interface.  On success, returns
+  \code{0}, sets \var{buffer} to the memory location and \var{buffer_len}
+  to the buffer length.  Returns \code{-1} and sets a
+  \exception{TypeError} on error.
+  \versionadded{1.6}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyObject_CheckReadBuffer}{PyObject *o}
+  Returns \code{1} if \var{o} supports the single-segment readable
+  buffer interface.  Otherwise returns \code{0}.
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyObject_AsWriteBuffer}{PyObject *obj,
+                                               void **buffer,
+                                               Py_ssize_t *buffer_len}
+  Returns a pointer to a writeable memory location.  The \var{obj}
+  argument must support the single-segment, character buffer
+  interface.  On success, returns \code{0}, sets \var{buffer} to the
+  memory location and \var{buffer_len} to the buffer length.  Returns
+  \code{-1} and sets a \exception{TypeError} on error.
+  \versionadded{1.6}
+\end{cfuncdesc}
diff --git a/sys/src/cmd/python/Doc/api/api.tex b/sys/src/cmd/python/Doc/api/api.tex
new file mode 100644
index 000000000..cf28f5b4c
--- /dev/null
+++ b/sys/src/cmd/python/Doc/api/api.tex
@@ -0,0 +1,60 @@
+\documentclass{manual}
+
+\title{Python/C API Reference Manual}
+
+\input{boilerplate}
+
+\makeindex			% tell \index to actually write the .idx file
+
+
+\begin{document}
+
+\maketitle
+
+\ifhtml
+\chapter*{Front Matter\label{front}}
+\fi
+
+\input{copyright}
+
+\begin{abstract}
+
+\noindent
+This manual documents the API used by C and \Cpp{} programmers who
+want to write extension modules or embed Python.  It is a companion to
+\citetitle[../ext/ext.html]{Extending and Embedding the Python
+Interpreter}, which describes the general principles of extension
+writing but does not document the API functions in detail.
+
+\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
+
+
+\input{intro}
+\input{veryhigh}
+\input{refcounting}
+\input{exceptions}
+\input{utilities}
+\input{abstract}
+\input{concrete}
+\input{init}
+\input{memory}
+\input{newtypes}
+
+
+\appendix
+\chapter{Reporting Bugs}
+\input{reportingbugs}
+
+\chapter{History and License}
+\input{license}
+
+\input{api.ind}			% Index -- must be last
+
+\end{document}
diff --git a/sys/src/cmd/python/Doc/api/concrete.tex b/sys/src/cmd/python/Doc/api/concrete.tex
new file mode 100644
index 000000000..e1f3e9a1f
--- /dev/null
+++ b/sys/src/cmd/python/Doc/api/concrete.tex
@@ -0,0 +1,3203 @@
+\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{type} and \code{types.TypeType} in the Python layer.
+  \withsubitem{(in module types)}{\ttindex{TypeType}}
+\end{cvardesc}
+
+\begin{cfuncdesc}{int}{PyType_Check}{PyObject *o}
+  Return true if the object \var{o} is a type object, including
+  instances of types derived from the standard type object.  Return
+  false in all other cases.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyType_CheckExact}{PyObject *o}
+  Return true if the object \var{o} is a type object, but not a
+  subtype of the standard type object.  Return false in all other
+  cases.
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyType_HasFeature}{PyObject *o, int feature}
+  Return 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_IS_GC}{PyObject *o}
+  Return true if the type object includes support for the cycle
+  detector; this tests the type flag \constant{Py_TPFLAGS_HAVE_GC}.
+  \versionadded{2.0}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyType_IsSubtype}{PyTypeObject *a, PyTypeObject *b}
+  Return true if \var{a} is a subtype of \var{b}.
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyType_GenericAlloc}{PyTypeObject *type,
+                                                  Py_ssize_t 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}
+  Finalize a type object.  This should be called on all type objects
+  to finish their initialization.  This function is responsible for
+  adding inherited slots from a type's base class.  Return \code{0}
+  on success, or return \code{-1} and sets an exception on error.
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+
+\subsection{The None Object \label{noneObject}}
+
+\obindex{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.  It needs to be treated just like any other object
+  with respect to reference counts.
+\end{cvardesc}
+
+\begin{csimplemacrodesc}{Py_RETURN_NONE}
+  Properly handle returning \cdata{Py_None} from within a C function.
+\end{csimplemacrodesc}
+
+
+\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{int} and
+  \code{types.IntType}.
+  \withsubitem{(in modules types)}{\ttindex{IntType}}
+\end{cvardesc}
+
+\begin{cfuncdesc}{int}{PyInt_Check}{PyObject *o}
+  Return 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}
+  Return 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_FromString}{char *str, char **pend,
+                                               int base}
+  Return a new \ctype{PyIntObject} or \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 based 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.  If the string represents a number
+  too large to be contained within the machine's \ctype{long int} type and
+  overflow warnings are being suppressed, a \ctype{PyLongObject} will be
+  returned.  If overflow warnings are not being suppressed, \NULL{} will be
+  returned in this case.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyInt_FromLong}{long ival}
+  Create a new integer object with a value of \var{ival}.
+
+  The current implementation keeps an array of integer objects for all
+  integers between \code{-5} and \code{256}, 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}{PyObject*}{PyInt_FromSsize_t}{Py_ssize_t ival}
+  Create a new integer object with a value of \var{ival}.
+  If the value exceeds \code{LONG_MAX}, a long integer object is
+  returned.
+
+ \versionadded{2.5}
+\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. If there is an
+  error, \code{-1} is returned, and the caller should check
+  \code{PyErr_Occurred()} to find out whether there was an error, or
+  whether the value just happened to be -1.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{long}{PyInt_AS_LONG}{PyObject *io}
+  Return the value of the object \var{io}.  No error checking is
+  performed.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{unsigned long}{PyInt_AsUnsignedLongMask}{PyObject *io}
+  Will first attempt to cast the object to a \ctype{PyIntObject} or
+  \ctype{PyLongObject}, if it is not already one, and then return its
+  value as unsigned long.  This function does not check for overflow.
+  \versionadded{2.3}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{unsigned PY_LONG_LONG}{PyInt_AsUnsignedLongLongMask}{PyObject *io}
+  Will first attempt to cast the object to a \ctype{PyIntObject} or
+  \ctype{PyLongObject}, if it is not already one, and then return its
+  value as unsigned long long, without checking for overflow.
+  \versionadded{2.3}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{Py_ssize_t}{PyInt_AsSsize_t}{PyObject *io}
+  Will first attempt to cast the object to a \ctype{PyIntObject} or
+  \ctype{PyLongObject}, if it is not already one, and then return its
+  value as \ctype{Py_ssize_t}.
+  \versionadded{2.5}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{long}{PyInt_GetMax}{}
+  Return 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{Boolean Objects \label{boolObjects}}
+
+Booleans in Python are implemented as a subclass of integers.  There
+are only two booleans, \constant{Py_False} and \constant{Py_True}.  As
+such, the normal creation and deletion functions don't apply to
+booleans.  The following macros are available, however.
+
+\begin{cfuncdesc}{int}{PyBool_Check}{PyObject *o}
+  Return true if \var{o} is of type \cdata{PyBool_Type}.
+  \versionadded{2.3}
+\end{cfuncdesc}
+
+\begin{cvardesc}{PyObject*}{Py_False}
+  The Python \code{False} object.  This object has no methods.  It needs to
+  be treated just like any other object with respect to reference counts.
+\end{cvardesc}
+
+\begin{cvardesc}{PyObject*}{Py_True}
+  The Python \code{True} object.  This object has no methods.  It needs to
+  be treated just like any other object with respect to reference counts.
+\end{cvardesc}
+
+\begin{csimplemacrodesc}{Py_RETURN_FALSE}
+  Return \constant{Py_False} from a function, properly incrementing its
+  reference count.
+\versionadded{2.4}
+\end{csimplemacrodesc}
+
+\begin{csimplemacrodesc}{Py_RETURN_TRUE}
+  Return \constant{Py_True} from a function, properly incrementing its
+  reference count.
+\versionadded{2.4}
+\end{csimplemacrodesc}
+
+\begin{cfuncdesc}{PyObject*}{PyBool_FromLong}{long v}
+  Return a new reference to \constant{Py_True} or \constant{Py_False}
+  depending on the truth value of \var{v}.
+\versionadded{2.3}
+\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{long} and
+  \code{types.LongType}.
+  \withsubitem{(in modules types)}{\ttindex{LongType}}
+\end{cvardesc}
+
+\begin{cfuncdesc}{int}{PyLong_Check}{PyObject *p}
+  Return 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}
+  Return 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}
+  Return a new \ctype{PyLongObject} object from \var{v}, or \NULL{}
+  on failure.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyLong_FromUnsignedLong}{unsigned long v}
+  Return a new \ctype{PyLongObject} object from a C \ctype{unsigned
+  long}, or \NULL{} on failure.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyLong_FromLongLong}{PY_LONG_LONG v}
+  Return a new \ctype{PyLongObject} object from a C \ctype{long long},
+  or \NULL{} on failure.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyLong_FromUnsignedLongLong}{unsigned PY_LONG_LONG v}
+  Return 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}
+  Return 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 based 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,
+                                                 Py_ssize_t 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}
+  \versionchanged[If the integer is larger than LONG_MAX,
+  a positive long integer is returned]{2.5}
+ \end{cfuncdesc}
+
+\begin{cfuncdesc}{long}{PyLong_AsLong}{PyObject *pylong}
+  Return 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}
+  Return 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}{PY_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 PY_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}{unsigned long}{PyLong_AsUnsignedLongMask}{PyObject *io}
+  Return a C \ctype{unsigned long} from a Python long integer, without
+  checking for overflow.
+  \versionadded{2.3}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{unsigned PY_LONG_LONG}{PyLong_AsUnsignedLongLongMask}{PyObject *io}
+  Return a C \ctype{unsigned long long} from a Python long integer, without
+  checking for overflow.
+  \versionadded{2.3}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{double}{PyLong_AsDouble}{PyObject *pylong}
+  Return 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}
+  \versionchanged[For values outside 0..LONG_MAX, both signed and
+  unsigned integers are acccepted]{2.5}
+\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{float} and
+  \code{types.FloatType}.
+  \withsubitem{(in modules types)}{\ttindex{FloatType}}
+\end{cvardesc}
+
+\begin{cfuncdesc}{int}{PyFloat_Check}{PyObject *p}
+  Return 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}
+  Return true if its argument is a \ctype{PyFloatObject}, but not a
+  subtype of \ctype{PyFloatObject}.
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyFloat_FromString}{PyObject *str, char **pend}
+  Create a \ctype{PyFloatObject} object based on the string value in
+  \var{str}, or \NULL{} on failure.  The \var{pend} argument is ignored.  It
+  remains only for backward compatibility.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyFloat_FromDouble}{double v}
+  Create a \ctype{PyFloatObject} object from \var{v}, or \NULL{} on
+  failure.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{double}{PyFloat_AsDouble}{PyObject *pyfloat}
+  Return a C \ctype{double} representation of the contents of
+  \var{pyfloat}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{double}{PyFloat_AS_DOUBLE}{PyObject *pyfloat}
+  Return 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. It is the same object as \code{complex} and
+  \code{types.ComplexType}.
+\end{cvardesc}
+
+\begin{cfuncdesc}{int}{PyComplex_Check}{PyObject *p}
+  Return 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}
+  Return 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}
+  Return a new \ctype{PyComplexObject} object from \var{real} and
+  \var{imag}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{double}{PyComplex_RealAsDouble}{PyObject *op}
+  Return the real part of \var{op} as a C \ctype{double}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{double}{PyComplex_ImagAsDouble}{PyObject *op}
+  Return the imaginary part of \var{op} as a C \ctype{double}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{Py_complex}{PyComplex_AsCComplex}{PyObject *op}
+  Return 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{str} and \code{types.StringType}
+  in the Python layer.
+  \withsubitem{(in module types)}{\ttindex{StringType}}.
+\end{cvardesc}
+
+\begin{cfuncdesc}{int}{PyString_Check}{PyObject *o}
+  Return 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}
+  Return 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}
+  Return a new string object with a copy of the string \var{v} as value
+  on success, and \NULL{} on failure.  The parameter \var{v} must not be
+  \NULL{}; it will not be checked.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyString_FromStringAndSize}{const char *v,
+                                                         Py_ssize_t len}
+  Return a new string object with a copy of the string \var{v} as value
+  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, ...}
+  Take a C \cfunction{printf()}-style \var{format} string and a
+  variable number of arguments, calculate the size of the resulting
+  Python string and return 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:
+
+  % This should be exactly the same as the table in PyErr_Format.
+  % One should just refer to the other.
+
+  % The descriptions for %zd and %zu are wrong, but the truth is complicated
+  % because not all compilers support the %z width modifier -- we fake it
+  % when necessary via interpolating PY_FORMAT_SIZE_T.
+
+  % %u, %lu, %zu should have "new in Python 2.5" blurbs.
+
+  \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{\%u}{unsigned int}{Exactly equivalent to \code{printf("\%u")}.}
+    \lineiii{\%ld}{long}{Exactly equivalent to \code{printf("\%ld")}.}
+    \lineiii{\%lu}{unsigned long}{Exactly equivalent to \code{printf("\%lu")}.}
+    \lineiii{\%zd}{Py_ssize_t}{Exactly equivalent to \code{printf("\%zd")}.}
+    \lineiii{\%zu}{size_t}{Exactly equivalent to \code{printf("\%zu")}.}
+    \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}
+
+  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.
+\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}{Py_ssize_t}{PyString_Size}{PyObject *string}
+  Return the length of the string in string object \var{string}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{Py_ssize_t}{PyString_GET_SIZE}{PyObject *string}
+  Macro form of \cfunction{PyString_Size()} but without error
+  checking.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{char*}{PyString_AsString}{PyObject *string}
+  Return a NUL-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.  If \var{string} is a Unicode object,
+  this function computes the default encoding of \var{string} and
+  operates on that.  If \var{string} is not a string object at all,
+  \cfunction{PyString_AsString()} returns \NULL{} and raises
+  \exception{TypeError}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{char*}{PyString_AS_STRING}{PyObject *string}
+  Macro form of \cfunction{PyString_AsString()} but without error
+  checking.  Only string objects are supported; no Unicode objects
+  should be passed.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyString_AsStringAndSize}{PyObject *obj,
+                                                 char **buffer,
+                                                 Py_ssize_t *length}
+  Return a NUL-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 \NULL{}, the resulting buffer may not
+  contain NUL characters; if it does, the function returns \code{-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.  If \var{string} is a
+  Unicode object, this function computes the default encoding of
+  \var{string} and operates on that.  If \var{string} is not a string
+  object at all, \cfunction{PyString_AsStringAndSize()} returns
+  \code{-1} and raises \exception{TypeError}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyString_Concat}{PyObject **string,
+                                         PyObject *newpart}
+  Create 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}
+  Create 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, Py_ssize_t 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.  It
+  is an error to call this function if the refcount on the input string
+  object is not one.
+  Pass the address of an existing string object as an lvalue (it may
+  be written into), and the new size desired.  On success, \var{*string}
+  holds the resized string object and \code{0} is returned; the address in
+  \var{*string} may differ from its input value.  If the
+  reallocation fails, the original string object at \var{*string} is
+  deallocated, \var{*string} is set to \NULL{}, a memory exception is set,
+  and \code{-1} is returned.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyString_Format}{PyObject *format,
+                                              PyObject *args}
+  Return 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,
+                                               Py_ssize_t size,
+                                               const char *encoding,
+                                               const char *errors}
+  Create 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.  Return \NULL{} if
+  an exception was raised by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyString_AsDecodedObject}{PyObject *str,
+                                               const char *encoding,
+                                               const char *errors}
+  Decode a string object by passing it to the codec registered for
+  \var{encoding} and return 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.
+  Return \NULL{} if an exception was raised by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyString_Encode}{const char *s,
+                                               Py_ssize_t size,
+                                               const char *encoding,
+                                               const char *errors}
+  Encode the \ctype{char} buffer of the given size by passing it to
+  the codec registered for \var{encoding} and return 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.  Return \NULL{} if an exception was raised by the
+  codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyString_AsEncodedObject}{PyObject *str,
+                                               const char *encoding,
+                                               const char *errors}
+  Encode a string object using the codec registered for
+  \var{encoding} and return 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.
+  Return \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 the storage type which is used by Python
+  internally as basis for holding Unicode ordinals.  Python's default
+  builds use a 16-bit type for \ctype{Py_UNICODE} and store Unicode
+  values internally as UCS2. It is also possible to build a UCS4
+  version of Python (most recent Linux distributions come with UCS4
+  builds of Python). These builds then use a 32-bit type for
+  \ctype{Py_UNICODE} and store Unicode data internally as UCS4. On
+  platforms where \ctype{wchar_t} is available and compatible with the
+  chosen Python Unicode build variant, \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
+  either \ctype{unsigned short} (UCS2) or \ctype{unsigned long}
+  (UCS4).
+\end{ctypedesc}
+
+Note that UCS2 and UCS4 Python builds are not binary compatible.
+Please keep this in mind when writing extensions or interfaces.
+
+\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.  It is exposed to Python code as \code{unicode} and
+  \code{types.UnicodeType}.
+\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}
+  Return 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}
+  Return true if the object \var{o} is a Unicode object, but not an
+  instance of a subtype.
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{Py_ssize_t}{PyUnicode_GET_SIZE}{PyObject *o}
+  Return the size of the object.  \var{o} has to be a
+  \ctype{PyUnicodeObject} (not checked).
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{Py_ssize_t}{PyUnicode_GET_DATA_SIZE}{PyObject *o}
+  Return 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}
+  Return 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}
+  Return 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}
+  Return 1 or 0 depending on whether \var{ch} is a whitespace
+  character.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{Py_UNICODE_ISLOWER}{Py_UNICODE ch}
+  Return 1 or 0 depending on whether \var{ch} is a lowercase character.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{Py_UNICODE_ISUPPER}{Py_UNICODE ch}
+  Return 1 or 0 depending on whether \var{ch} is an uppercase
+  character.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{Py_UNICODE_ISTITLE}{Py_UNICODE ch}
+  Return 1 or 0 depending on whether \var{ch} is a titlecase character.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{Py_UNICODE_ISLINEBREAK}{Py_UNICODE ch}
+  Return 1 or 0 depending on whether \var{ch} is a linebreak character.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{Py_UNICODE_ISDECIMAL}{Py_UNICODE ch}
+  Return 1 or 0 depending on whether \var{ch} is a decimal character.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{Py_UNICODE_ISDIGIT}{Py_UNICODE ch}
+  Return 1 or 0 depending on whether \var{ch} is a digit character.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{Py_UNICODE_ISNUMERIC}{Py_UNICODE ch}
+  Return 1 or 0 depending on whether \var{ch} is a numeric character.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{Py_UNICODE_ISALPHA}{Py_UNICODE ch}
+  Return 1 or 0 depending on whether \var{ch} is an alphabetic
+  character.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{Py_UNICODE_ISALNUM}{Py_UNICODE ch}
+  Return 1 or 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}
+  Return the character \var{ch} converted to lower case.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{Py_UNICODE}{Py_UNICODE_TOUPPER}{Py_UNICODE ch}
+  Return the character \var{ch} converted to upper case.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{Py_UNICODE}{Py_UNICODE_TOTITLE}{Py_UNICODE ch}
+  Return the character \var{ch} converted to title case.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{Py_UNICODE_TODECIMAL}{Py_UNICODE ch}
+  Return the character \var{ch} converted to a decimal positive
+  integer.  Return \code{-1} if this is not possible.  This macro
+  does not raise exceptions.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{Py_UNICODE_TODIGIT}{Py_UNICODE ch}
+  Return the character \var{ch} converted to a single digit integer.
+  Return \code{-1} if this is not possible.  This macro does not raise
+  exceptions.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{double}{Py_UNICODE_TONUMERIC}{Py_UNICODE ch}
+  Return the character \var{ch} converted to a double.
+  Return \code{-1.0} if this is not possible.  This macro 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,
+                                                    Py_ssize_t 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}{Py_ssize_t}{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.
+  
+  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).
+
+  All other objects, including Unicode objects, cause a
+  \exception{TypeError} to be set.
+
+  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,
+                                                     Py_ssize_t size}
+  Create a Unicode object from the \ctype{wchar_t} buffer \var{w} of
+  the given size.  Return \NULL{} on failure.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{Py_ssize_t}{PyUnicode_AsWideChar}{PyUnicodeObject *unicode,
+                                             wchar_t *w,
+                                             Py_ssize_t size}
+  Copy the Unicode object contents into the \ctype{wchar_t} buffer
+  \var{w}.  At most \var{size} \ctype{wchar_t} characters are copied
+  (excluding a possibly trailing 0-termination character).  Return
+  the number of \ctype{wchar_t} characters copied or -1 in case of an
+  error.  Note that the resulting \ctype{wchar_t} string may or may
+  not be 0-terminated.  It is the responsibility of the caller to make
+  sure that the \ctype{wchar_t} string is 0-terminated in case this is
+  required by the application.
+\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 (such as 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,
+                                               Py_ssize_t 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.  Return \NULL{} if an
+  exception was raised by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_Encode}{const Py_UNICODE *s,
+                                               Py_ssize_t size,
+                                               const char *encoding,
+                                               const char *errors}
+  Encode the \ctype{Py_UNICODE} buffer of the given size and return
+  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.  Return \NULL{} if an exception was
+  raised by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_AsEncodedString}{PyObject *unicode,
+                                               const char *encoding,
+                                               const char *errors}
+  Encode a Unicode object and return 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.
+  Return \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,
+                                               Py_ssize_t size,
+                                               const char *errors}
+  Create a Unicode object by decoding \var{size} bytes of the UTF-8
+  encoded string \var{s}. Return \NULL{} if an exception was raised
+  by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF8Stateful}{const char *s,
+                                               Py_ssize_t size,
+                                               const char *errors,
+                                               Py_ssize_t *consumed}
+  If \var{consumed} is \NULL{}, behave like \cfunction{PyUnicode_DecodeUTF8()}.
+  If \var{consumed} is not \NULL{}, trailing incomplete UTF-8 byte sequences
+  will not be treated as an error. Those bytes will not be decoded and the
+  number of bytes that have been decoded will be stored in \var{consumed}.
+  \versionadded{2.4}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeUTF8}{const Py_UNICODE *s,
+                                               Py_ssize_t size,
+                                               const char *errors}
+  Encode the \ctype{Py_UNICODE} buffer of the given size using UTF-8
+  and return a Python string object.  Return \NULL{} if an exception
+  was raised by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_AsUTF8String}{PyObject *unicode}
+  Encode a Unicode objects using UTF-8 and return the result as
+  Python string object.  Error handling is ``strict''.  Return
+  \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,
+                                               Py_ssize_t size,
+                                               const char *errors,
+                                               int *byteorder}
+  Decode \var{length} bytes from a UTF-16 encoded buffer string and
+  return 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.
+
+  Return \NULL{} if an exception was raised by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF16Stateful}{const char *s,
+                                               Py_ssize_t size,
+                                               const char *errors,
+                                               int *byteorder,
+                                               Py_ssize_t *consumed}
+  If \var{consumed} is \NULL{}, behave like
+  \cfunction{PyUnicode_DecodeUTF16()}. If \var{consumed} is not \NULL{},
+  \cfunction{PyUnicode_DecodeUTF16Stateful()} will not treat trailing incomplete
+  UTF-16 byte sequences (such as an odd number of bytes or a split surrogate pair)
+  as an error. Those bytes will not be decoded and the number of bytes that
+  have been decoded will be stored in \var{consumed}.
+  \versionadded{2.4}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeUTF16}{const Py_UNICODE *s,
+                                               Py_ssize_t size,
+                                               const char *errors,
+                                               int byteorder}
+  Return 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.
+
+  If \var{Py_UNICODE_WIDE} is defined, a single \ctype{Py_UNICODE}
+  value may get represented as a surrogate pair. If it is not
+  defined, each \ctype{Py_UNICODE} values is interpreted as an
+  UCS-2 character.
+
+  Return \NULL{} if an exception was raised by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_AsUTF16String}{PyObject *unicode}
+  Return a Python string using the UTF-16 encoding in native byte
+  order. The string always starts with a BOM mark.  Error handling is
+  ``strict''.  Return \NULL{} if an exception was raised by the
+  codec.
+\end{cfuncdesc}
+
+% --- Unicode-Escape Codecs ----------------------------------------------
+
+These are the ``Unicode Escape'' codec APIs:
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUnicodeEscape}{const char *s,
+                                               Py_ssize_t size,
+                                               const char *errors}
+  Create a Unicode object by decoding \var{size} bytes of the
+  Unicode-Escape encoded string \var{s}.  Return \NULL{} if an
+  exception was raised by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeUnicodeEscape}{const Py_UNICODE *s,
+                                               Py_ssize_t size}
+  Encode the \ctype{Py_UNICODE} buffer of the given size using
+  Unicode-Escape and return a Python string object.  Return \NULL{}
+  if an exception was raised by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_AsUnicodeEscapeString}{PyObject *unicode}
+  Encode a Unicode objects using Unicode-Escape and return the
+  result as Python string object.  Error handling is ``strict''.
+  Return \NULL{} if an exception was raised by the codec.
+\end{cfuncdesc}
+
+% --- Raw-Unicode-Escape Codecs ------------------------------------------
+
+These are the ``Raw Unicode Escape'' codec APIs:
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeRawUnicodeEscape}{const char *s,
+                                               Py_ssize_t size,
+                                               const char *errors}
+  Create a Unicode object by decoding \var{size} bytes of the
+  Raw-Unicode-Escape encoded string \var{s}.  Return \NULL{} if an
+  exception was raised by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeRawUnicodeEscape}{const Py_UNICODE *s,
+                                               Py_ssize_t size,
+                                               const char *errors}
+  Encode the \ctype{Py_UNICODE} buffer of the given size using
+  Raw-Unicode-Escape and return a Python string object.  Return
+  \NULL{} if an exception was raised by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_AsRawUnicodeEscapeString}{PyObject *unicode}
+  Encode a Unicode objects using Raw-Unicode-Escape and return the
+  result as Python string object. Error handling is ``strict''.
+  Return \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,
+                                                     Py_ssize_t size,
+                                                     const char *errors}
+  Create a Unicode object by decoding \var{size} bytes of the Latin-1
+  encoded string \var{s}.  Return \NULL{} if an exception was raised
+  by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeLatin1}{const Py_UNICODE *s,
+                                                     Py_ssize_t size,
+                                                     const char *errors}
+  Encode the \ctype{Py_UNICODE} buffer of the given size using
+  Latin-1 and return a Python string object.  Return \NULL{} if an
+  exception was raised by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_AsLatin1String}{PyObject *unicode}
+  Encode a Unicode objects using Latin-1 and return the result as
+  Python string object.  Error handling is ``strict''.  Return
+  \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,
+                                                    Py_ssize_t size,
+                                                    const char *errors}
+  Create a Unicode object by decoding \var{size} bytes of the
+  \ASCII{} encoded string \var{s}.  Return \NULL{} if an exception
+  was raised by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeASCII}{const Py_UNICODE *s,
+                                                    Py_ssize_t size,
+                                                    const char *errors}
+  Encode the \ctype{Py_UNICODE} buffer of the given size using
+  \ASCII{} and return a Python string object.  Return \NULL{} if an
+  exception was raised by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_AsASCIIString}{PyObject *unicode}
+  Encode a Unicode objects using \ASCII{} and return the result as
+  Python string object.  Error handling is ``strict''.  Return
+  \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,
+                                               Py_ssize_t size,
+                                               PyObject *mapping,
+                                               const char *errors}
+  Create a Unicode object by decoding \var{size} bytes of the encoded
+  string \var{s} using the given \var{mapping} object.  Return
+  \NULL{} if an exception was raised by the codec. If \var{mapping} is \NULL{}
+  latin-1 decoding will be done. Else it can be a dictionary mapping byte or a
+  unicode string, which is treated as a lookup table. Byte values greater
+  that the length of the string and U+FFFE "characters" are treated as
+  "undefined mapping".
+  \versionchanged[Allowed unicode string as mapping argument]{2.4}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeCharmap}{const Py_UNICODE *s,
+                                               Py_ssize_t size,
+                                               PyObject *mapping,
+                                               const char *errors}
+  Encode the \ctype{Py_UNICODE} buffer of the given size using the
+  given \var{mapping} object and return a Python string object.
+  Return \NULL{} if an exception was raised by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_AsCharmapString}{PyObject *unicode,
+                                                        PyObject *mapping}
+  Encode a Unicode objects using the given \var{mapping} object and
+  return the result as Python string object.  Error handling is
+  ``strict''.  Return \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,
+                                               Py_ssize_t size,
+                                               PyObject *table,
+                                               const char *errors}
+  Translate a \ctype{Py_UNICODE} buffer of the given length by
+  applying a character mapping \var{table} to it and return the
+  resulting Unicode object.  Return \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,
+                                               Py_ssize_t size,
+                                               const char *errors}
+  Create a Unicode object by decoding \var{size} bytes of the MBCS
+  encoded string \var{s}.  Return \NULL{} if an exception was
+  raised by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeMBCSStateful}{const char *s,
+                                               int size,
+                                               const char *errors,
+                                               int *consumed}
+  If \var{consumed} is \NULL{}, behave like
+  \cfunction{PyUnicode_DecodeMBCS()}. If \var{consumed} is not \NULL{},
+  \cfunction{PyUnicode_DecodeMBCSStateful()} will not decode trailing lead
+  byte and the number of bytes that have been decoded will be stored in
+  \var{consumed}.
+  \versionadded{2.5}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeMBCS}{const Py_UNICODE *s,
+                                               Py_ssize_t size,
+                                               const char *errors}
+  Encode the \ctype{Py_UNICODE} buffer of the given size using MBCS
+  and return a Python string object.  Return \NULL{} if an exception
+  was raised by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_AsMBCSString}{PyObject *unicode}
+  Encode a Unicode objects using MBCS and return the result as
+  Python string object.  Error handling is ``strict''.  Return
+  \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 appropriate.
+
+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,
+                                              Py_ssize_t 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 keepend}
+  Split a Unicode string at line breaks, returning a list of Unicode
+  strings.  CRLF is considered to be one line break.  If \var{keepend}
+  is 0, 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}{int}{PyUnicode_Tailmatch}{PyObject *str,
+                                                  PyObject *substr,
+                                                  Py_ssize_t start,
+                                                  Py_ssize_t 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.
+  Return \code{-1} if an error occurred.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{Py_ssize_t}{PyUnicode_Find}{PyObject *str,
+                                       PyObject *substr,
+                                       Py_ssize_t start,
+                                       Py_ssize_t 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).  The return value is the
+  index of the first match; a value of \code{-1} indicates that no
+  match was found, and \code{-2} indicates that an error occurred and
+  an exception has been set.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{Py_ssize_t}{PyUnicode_Count}{PyObject *str,
+                                        PyObject *substr,
+                                        Py_ssize_t start,
+                                        Py_ssize_t end}
+  Return the number of non-overlapping occurrences of \var{substr} in
+  \code{\var{str}[\var{start}:\var{end}]}.  Return \code{-1} if an
+  error occurred.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_Replace}{PyObject *str,
+                                                PyObject *substr,
+                                                PyObject *replstr,
+                                                Py_ssize_t 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}{int}{PyUnicode_RichCompare}{PyObject *left, 
+                                              PyObject *right, 
+                                              int op}
+
+  Rich compare two unicode strings and return one of the following:
+  \begin{itemize}
+    \item \code{NULL} in case an exception was raised
+    \item \constant{Py_True} or \constant{Py_False} for successful comparisons
+    \item \constant{Py_NotImplemented} in case the type combination is unknown
+  \end{itemize}
+
+   Note that \constant{Py_EQ} and \constant{Py_NE} comparisons can cause a
+   \exception{UnicodeWarning} in case the conversion of the arguments to
+   Unicode fails with a \exception{UnicodeDecodeError}.
+
+   Possible values for \var{op} are
+   \constant{Py_GT}, \constant{Py_GE}, \constant{Py_EQ},
+   \constant{Py_NE}, \constant{Py_LT}, and \constant{Py_LE}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_Format}{PyObject *format,
+                                              PyObject *args}
+  Return 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}
+  Check whether \var{element} is contained in \var{container} and
+  return 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{buffer} and 
+  \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,
+                                                  Py_ssize_t offset, Py_ssize_t 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,
+                                                           Py_ssize_t offset,
+                                                           Py_ssize_t 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, Py_ssize_t 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, Py_ssize_t size}
+  Similar to \cfunction{PyBuffer_FromMemory()}, but the returned
+  buffer is writable.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyBuffer_New}{Py_ssize_t size}
+  Return 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.  Note that the memory buffer (as
+  returned by \cfunction{PyObject_AsWriteBuffer()}) is not specifically
+  aligned.
+\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{tuple} and \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}{Py_ssize_t len}
+  Return a new tuple object of size \var{len}, or \NULL{} on failure.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyTuple_Pack}{Py_ssize_t n, \moreargs}
+  Return a new tuple object of size \var{n}, or \NULL{} on failure.
+  The tuple values are initialized to the subsequent \var{n} C arguments
+  pointing to Python objects.  \samp{PyTuple_Pack(2, \var{a}, \var{b})}
+  is equivalent to \samp{Py_BuildValue("(OO)", \var{a}, \var{b})}.
+  \versionadded{2.4}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyTuple_Size}{PyObject *p}
+  Take a pointer to a tuple object, and return 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, Py_ssize_t pos}
+  Return the object at position \var{pos} in the tuple pointed to by
+  \var{p}.  If \var{pos} is out of bounds, return \NULL{} and sets an
+  \exception{IndexError} exception.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyTuple_GET_ITEM}{PyObject *p, Py_ssize_t pos}
+  Like \cfunction{PyTuple_GetItem()}, but does no checking of its
+  arguments.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyTuple_GetSlice}{PyObject *p,
+                                               Py_ssize_t low, Py_ssize_t high}
+  Take a slice of the tuple pointed to by \var{p} from \var{low} to
+  \var{high} and return it as a new tuple.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyTuple_SetItem}{PyObject *p,
+                                        Py_ssize_t pos, PyObject *o}
+  Insert a reference to object \var{o} at position \var{pos} of the
+  tuple pointed to by \var{p}. Return \code{0} on success.
+  \note{This function ``steals'' a reference to \var{o}.}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyTuple_SET_ITEM}{PyObject *p,
+                                          Py_ssize_t 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, Py_ssize_t 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{list} and \code{types.ListType}
+  in the Python layer.\withsubitem{(in module types)}{\ttindex{ListType}}
+\end{cvardesc}
+
+\begin{cfuncdesc}{int}{PyList_Check}{PyObject *p}
+  Return true if \var{p} is a list object or an instance of a
+  subtype of the list type.
+  \versionchanged[Allowed subtypes to be accepted]{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyList_CheckExact}{PyObject *p}
+  Return true if \var{p} is a list object, but not an instance of a
+  subtype of the list type.
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyList_New}{Py_ssize_t len}
+  Return a new list of length \var{len} on success, or \NULL{} on
+  failure.
+  \note{If \var{length} is greater than zero, the returned list object's
+        items are set to \code{NULL}.  Thus you cannot use abstract
+        API functions such as \cfunction{PySequence_SetItem()} 
+        or expose the object to Python code before setting all items to a
+        real object with \cfunction{PyList_SetItem()}.}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{Py_ssize_t}{PyList_Size}{PyObject *list}
+  Return 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}{Py_ssize_t}{PyList_GET_SIZE}{PyObject *list}
+  Macro form of \cfunction{PyList_Size()} without error checking.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyList_GetItem}{PyObject *list, Py_ssize_t index}
+  Return the object at position \var{pos} in the list pointed to by
+  \var{p}.  The position must be positive, indexing from the end of the
+  list is not supported.  If \var{pos} is out of bounds, return \NULL{}
+  and set an \exception{IndexError} exception.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyList_GET_ITEM}{PyObject *list, Py_ssize_t i}
+  Macro form of \cfunction{PyList_GetItem()} without error checking.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyList_SetItem}{PyObject *list, Py_ssize_t index,
+                                       PyObject *item}
+  Set the item at index \var{index} in list to \var{item}.  Return
+  \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, Py_ssize_t 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, Py_ssize_t index,
+                                      PyObject *item}
+  Insert the item \var{item} into list \var{list} in front of index
+  \var{index}.  Return \code{0} if successful; return \code{-1} and
+  set 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}
+  Append the object \var{item} at the end of list \var{list}.
+  Return \code{0} if successful; return \code{-1} and set an
+  exception if unsuccessful.  Analogous to
+  \code{\var{list}.append(\var{item})}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyList_GetSlice}{PyObject *list,
+                                              Py_ssize_t low, Py_ssize_t high}
+  Return a list of the objects in \var{list} containing the objects
+  \emph{between} \var{low} and \var{high}.  Return \NULL{} and set
+  an exception if unsuccessful.
+  Analogous to \code{\var{list}[\var{low}:\var{high}]}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyList_SetSlice}{PyObject *list,
+                                        Py_ssize_t low, Py_ssize_t high,
+                                        PyObject *itemlist}
+  Set 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}}.
+  The \var{itemlist} may be \NULL{}, indicating the assignment
+  of an empty list (slice deletion).
+  Return \code{0} on success, \code{-1} on failure.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyList_Sort}{PyObject *list}
+  Sort the items of \var{list} in place.  Return \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}
+  Reverse the items of \var{list} in place.  Return \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}
+  Return 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{dict} and \code{types.DictType}.
+  \withsubitem{(in module types)}{\ttindex{DictType}\ttindex{DictionaryType}}
+\end{cvardesc}
+
+\begin{cfuncdesc}{int}{PyDict_Check}{PyObject *p}
+  Return true if \var{p} is a dict object or an instance of a
+  subtype of the dict type.
+  \versionchanged[Allowed subtypes to be accepted]{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyDict_CheckExact}{PyObject *p}
+  Return true if \var{p} is a dict object, but not an instance of a
+  subtype of the dict type.
+  \versionadded{2.4}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyDict_New}{}
+  Return 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}
+  Empty an existing dictionary of all key-value pairs.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyDict_Contains}{PyObject *p, PyObject *key}
+  Determine if dictionary \var{p} contains \var{key}.  If an item
+  in \var{p} is matches \var{key}, return \code{1}, otherwise return
+  \code{0}.  On error, return \code{-1}.  This is equivalent to the
+  Python expression \samp{\var{key} in \var{p}}.
+  \versionadded{2.4}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyDict_Copy}{PyObject *p}
+  Return 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}
+  Insert \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.
+  Return \code{0} on success or \code{-1} on failure.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyDict_SetItemString}{PyObject *p,
+            const char *key,
+            PyObject *val}
+  Insert \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})}. Return \code{0} on
+  success or \code{-1} on failure.
+  \ttindex{PyString_FromString()}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyDict_DelItem}{PyObject *p, PyObject *key}
+  Remove the entry in dictionary \var{p} with key \var{key}.
+  \var{key} must be hashable; if it isn't, \exception{TypeError} is
+  raised.  Return \code{0} on success or \code{-1} on failure.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyDict_DelItemString}{PyObject *p, char *key}
+  Remove the entry in dictionary \var{p} which has a key specified by
+  the string \var{key}.  Return \code{0} on success or \code{-1} on
+  failure.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyDict_GetItem}{PyObject *p, PyObject *key}
+  Return the object from dictionary \var{p} which has a key
+  \var{key}.  Return \NULL{} if the key \var{key} is not present, but
+  \emph{without} setting an exception.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyDict_GetItemString}{PyObject *p, const 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}
+  Return a \ctype{PyListObject} containing all the items from the
+  dictionary, as in the dictionary method \method{items()} (see the
+  \citetitle[../lib/lib.html]{Python Library Reference}).
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyDict_Keys}{PyObject *p}
+  Return 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}
+  Return 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}{Py_ssize_t}{PyDict_Size}{PyObject *p}
+  Return 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, Py_ssize_t *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{}.  Any references returned through
+  them are borrowed.  \var{ppos} should not be altered during iteration.
+  Its value represents offsets within the internal dictionary structure,
+  and since the structure is sparse, the offsets are not consecutive.
+
+  For example:
+
+\begin{verbatim}
+PyObject *key, *value;
+Py_ssize_t 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;
+Py_ssize_t 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 mapping object \var{b} adding key-value pairs to dictionary
+  \var{a}.
+  \var{b} may be a dictionary, or any object supporting
+  \function{PyMapping_Keys()} and \function{PyObject_GetItem()}.
+  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}.
+  Return \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.  Return \code{0} on
+  success or \code{-1} if an exception was raised.
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyDict_MergeFromSeq2}{PyObject *a, PyObject *seq2,
+                                             int override}
+  Update or merge into dictionary \var{a}, from the key-value pairs in
+  \var{seq2}.  \var{seq2} must be an iterable object producing
+  iterable objects of length 2, viewed as key-value pairs.  In case of
+  duplicate keys, the last wins if \var{override} is true, else the
+  first wins.
+  Return \code{0} on success or \code{-1} if an exception
+  was raised.
+  Equivalent Python (except for the return value):
+
+\begin{verbatim}
+def PyDict_MergeFromSeq2(a, seq2, override):
+    for key, value in seq2:
+        if override or key not in a:
+            a[key] = value
+\end{verbatim}
+
+  \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{file} and
+  \code{types.FileType}.
+  \withsubitem{(in module types)}{\ttindex{FileType}}
+\end{cvardesc}
+
+\begin{cfuncdesc}{int}{PyFile_Check}{PyObject *p}
+  Return 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}
+  Return 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, return 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, return \NULL{}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyFile_FromFile}{FILE *fp,
+                                              char *name, char *mode,
+                                              int (*close)(FILE*)}
+  Create 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.  Return \NULL{} on failure.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{FILE*}{PyFile_AsFile}{PyObject *p}
+  Return 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}
+  Return 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_Encoding}{PyFileObject *p, char *enc}
+  Set the file's encoding for Unicode output to \var{enc}. Return
+  1 on success and 0 on failure.
+  \versionadded{2.3}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyFile_SoftSpace}{PyObject *p, int newflag}
+  This function exists for internal use by the interpreter.  Set the
+  \member{softspace} attribute of \var{p} to \var{newflag} and
+  \withsubitem{(file attribute)}{\ttindex{softspace}}return 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, PyObject *p,
+                                           int flags}
+  Write 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()}.  Return \code{0} on success or \code{-1} on
+  failure; the appropriate exception will be set.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyFile_WriteString}{const char *s, PyObject *p}
+  Write string \var{s} to file object \var{p}.  Return \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}
+  Return 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 its
+  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{Function Objects \label{function-objects}}
+
+\obindex{function}
+There are a few functions specific to Python functions.
+
+\begin{ctypedesc}{PyFunctionObject}
+  The C structure used for functions.
+\end{ctypedesc}
+
+\begin{cvardesc}{PyTypeObject}{PyFunction_Type}
+  This is an instance of \ctype{PyTypeObject} and represents the
+  Python function type.  It is exposed to Python programmers as
+  \code{types.FunctionType}.
+  \withsubitem{(in module types)}{\ttindex{MethodType}}
+\end{cvardesc}
+
+\begin{cfuncdesc}{int}{PyFunction_Check}{PyObject *o}
+  Return true if \var{o} is a function object (has type
+  \cdata{PyFunction_Type}).  The parameter must not be \NULL{}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyFunction_New}{PyObject *code,
+                                             PyObject *globals}
+  Return a new function object associated with the code object
+  \var{code}. \var{globals} must be a dictionary with the global
+  variables accessible to the function.
+
+  The function's docstring, name and \var{__module__} are retrieved
+  from the code object, the argument defaults and closure are set to
+  \NULL{}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyFunction_GetCode}{PyObject *op}
+  Return the code object associated with the function object \var{op}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyFunction_GetGlobals}{PyObject *op}
+  Return the globals dictionary associated with the function object
+  \var{op}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyFunction_GetModule}{PyObject *op}
+  Return the \var{__module__} attribute of the function object \var{op}.
+  This is normally a string containing the module name, but can be set
+  to any other object by Python code.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyFunction_GetDefaults}{PyObject *op}
+  Return the argument default values of the function object \var{op}.
+  This can be a tuple of arguments or \NULL{}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyFunction_SetDefaults}{PyObject *op,
+                                               PyObject *defaults}
+  Set the argument default values for the function object \var{op}.
+  \var{defaults} must be \var{Py_None} or a tuple.
+
+  Raises \exception{SystemError} and returns \code{-1} on failure.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyFunction_GetClosure}{PyObject *op}
+  Return the closure associated with the function object \var{op}.
+  This can be \NULL{} or a tuple of cell objects.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyFunction_SetClosure}{PyObject *op,
+                                              PyObject *closure}
+  Set the closure associated with the function object \var{op}.
+  \var{closure} must be \var{Py_None} or a tuple of cell objects.
+
+  Raises \exception{SystemError} and returns \code{-1} on failure.
+\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}
+  Return 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}
+  Return 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}{const 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__}}
+  It is recommended extensions use other \cfunction{PyModule_*()}
+  and \cfunction{PyObject_*()} functions rather than directly
+  manipulate a module's \member{__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,
+                                           const 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}.  Return
+  \code{-1} on error, \code{0} on success.
+  \versionadded{2.0}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyModule_AddIntConstant}{PyObject *module,
+                                                const char *name, long value}
+  Add an integer constant to \var{module} as \var{name}.  This
+  convenience function can be used from the module's initialization
+  function. Return \code{-1} on error, \code{0} on success.
+  \versionadded{2.0}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyModule_AddStringConstant}{PyObject *module,
+                                                   const char *name, const 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.  Return
+  \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}}
+
+``Descriptors'' are objects that describe some attribute of an object.
+They are found in the dictionary of type objects.
+
+\begin{cvardesc}{PyTypeObject}{PyProperty_Type}
+  The type object for the built-in descriptor types.
+  \versionadded{2.2}
+\end{cvardesc}
+
+\begin{cfuncdesc}{PyObject*}{PyDescr_NewGetSet}{PyTypeObject *type,
+					        struct PyGetSetDef *getset}
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyDescr_NewMember}{PyTypeObject *type,
+					        struct PyMemberDef *meth}
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyDescr_NewMethod}{PyTypeObject *type,
+                                                struct 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}{PyObject*}{PyDescr_NewClassMethod}{PyTypeObject *type,
+						     PyMethodDef *method}
+  \versionadded{2.3}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyDescr_IsData}{PyObject *descr}
+  Return 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{slice} and \code{types.SliceType}.
+  \withsubitem{(in module types)}{\ttindex{SliceType}}
+\end{cvardesc}
+
+\begin{cfuncdesc}{int}{PySlice_Check}{PyObject *ob}
+  Return 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.  Return \NULL{} if the new object could
+  not be allocated.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PySlice_GetIndices}{PySliceObject *slice, Py_ssize_t length,
+                                           Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step}
+Retrieve the start, stop and step indices from the slice object
+\var{slice}, assuming a sequence of length \var{length}. Treats
+indices greater than \var{length} as errors.
+
+Returns 0 on success and -1 on error with no exception set (unless one
+of the indices was not \constant{None} and failed to be converted to
+an integer, in which case -1 is returned with an exception set).
+
+You probably do not want to use this function.  If you want to use
+slice objects in versions of Python prior to 2.3, you would probably
+do well to incorporate the source of \cfunction{PySlice_GetIndicesEx},
+suitably renamed, in the source of your extension.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PySlice_GetIndicesEx}{PySliceObject *slice, Py_ssize_t length,
+                                             Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step,
+                                             Py_ssize_t *slicelength}
+Usable replacement for \cfunction{PySlice_GetIndices}.  Retrieve the
+start, stop, and step indices from the slice object \var{slice}
+assuming a sequence of length \var{length}, and store the length of
+the slice in \var{slicelength}.  Out of bounds indices are clipped in
+a manner consistent with the handling of normal slices.
+
+Returns 0 on success and -1 on error with exception set.
+
+\versionadded{2.3}
+\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 parameter, 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 parameter, 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}
+  Return the referenced object from a weak reference, \var{ref}.  If
+  the referent is no longer live, returns \code{None}.
+  \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}
+  Return true if its argument is a \ctype{PyCObject}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyCObject_FromVoidPtr}{void* cobj,
+                                                    void (*destr)(void *)}
+  Create 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 *)}
+  Create 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}
+  Return the object \ctype{void *} that the \ctype{PyCObject}
+  \var{self} was created with.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void*}{PyCObject_GetDesc}{PyObject* self}
+  Return the description \ctype{void *} that the \ctype{PyCObject}
+  \var{self} was created with.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyCObject_SetVoidPtr}{PyObject* self, void* cobj}
+  Set the void pointer inside \var{self} to \var{cobj}.
+  The \ctype{PyCObject} must not have an associated destructor.
+  Return true on success, false on failure.
+\end{cfuncdesc}
+
+
+\subsection{Cell Objects \label{cell-objects}}
+
+``Cell'' objects are used to implement variables referenced by
+multiple scopes.  For each such variable, a cell object is created to
+store the value; the local variables of each stack frame that
+references the value contains a reference to the cells from outer
+scopes which also use that variable.  When the value is accessed, the
+value contained in the cell is used instead of the cell object
+itself.  This de-referencing of the cell object requires support from
+the generated byte-code; these are not automatically de-referenced
+when accessed.  Cell objects are not likely to be useful elsewhere.
+
+\begin{ctypedesc}{PyCellObject}
+  The C structure used for cell objects.
+\end{ctypedesc}
+
+\begin{cvardesc}{PyTypeObject}{PyCell_Type}
+  The type object corresponding to cell objects.
+\end{cvardesc}
+
+\begin{cfuncdesc}{int}{PyCell_Check}{ob}
+  Return true if \var{ob} is a cell object; \var{ob} must not be
+  \NULL{}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyCell_New}{PyObject *ob}
+  Create and return a new cell object containing the value \var{ob}.
+  The parameter may be \NULL{}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyCell_Get}{PyObject *cell}
+  Return the contents of the cell \var{cell}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyCell_GET}{PyObject *cell}
+  Return the contents of the cell \var{cell}, but without checking
+  that \var{cell} is non-\NULL{} and a cell object.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyCell_Set}{PyObject *cell, PyObject *value}
+  Set the contents of the cell object \var{cell} to \var{value}.  This
+  releases the reference to any current content of the cell.
+  \var{value} may be \NULL{}.  \var{cell} must be non-\NULL{}; if it is
+  not a cell object, \code{-1} will be returned.  On success, \code{0}
+  will be returned.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyCell_SET}{PyObject *cell, PyObject *value}
+  Sets the value of the cell object \var{cell} to \var{value}.  No
+  reference counts are adjusted, and no checks are made for safety;
+  \var{cell} must be non-\NULL{} and must be a cell object.
+\end{cfuncdesc}
+
+
+\subsection{Generator Objects \label{gen-objects}}
+
+Generator objects are what Python uses to implement generator iterators.
+They are normally created by iterating over a function that yields values,
+rather than explicitly calling \cfunction{PyGen_New}.
+
+\begin{ctypedesc}{PyGenObject}
+  The C structure used for generator objects.
+\end{ctypedesc}
+
+\begin{cvardesc}{PyTypeObject}{PyGen_Type}
+  The type object corresponding to generator objects
+\end{cvardesc}
+
+\begin{cfuncdesc}{int}{PyGen_Check}{ob}
+  Return true if \var{ob} is a generator object; \var{ob} must not be
+  \NULL{}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyGen_CheckExact}{ob}
+  Return true if \var{ob}'s type is \var{PyGen_Type}
+  is a generator object; \var{ob} must not be
+  \NULL{}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyGen_New}{PyFrameObject *frame}
+  Create and return a new generator object based on the \var{frame} object.
+  A reference to \var{frame} is stolen by this function.
+  The parameter must not be \NULL{}.
+\end{cfuncdesc}
+
+
+\subsection{DateTime Objects \label{datetime-objects}}
+
+Various date and time objects are supplied by the \module{datetime}
+module.  Before using any of these functions, the header file
+\file{datetime.h} must be included in your source (note that this is
+not included by \file{Python.h}), and the macro
+\cfunction{PyDateTime_IMPORT} must be invoked.  The macro puts a
+pointer to a C structure into a static variable, 
+\code{PyDateTimeAPI}, that is used by the following macros.
+
+Type-check macros:
+
+\begin{cfuncdesc}{int}{PyDate_Check}{PyObject *ob}
+  Return true if \var{ob} is of type \cdata{PyDateTime_DateType} or
+  a subtype of \cdata{PyDateTime_DateType}.  \var{ob} must not be
+  \NULL{}.
+  \versionadded{2.4}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyDate_CheckExact}{PyObject *ob}
+  Return true if \var{ob} is of type \cdata{PyDateTime_DateType}.
+  \var{ob} must not be \NULL{}.
+  \versionadded{2.4}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyDateTime_Check}{PyObject *ob}
+  Return true if \var{ob} is of type \cdata{PyDateTime_DateTimeType} or
+  a subtype of \cdata{PyDateTime_DateTimeType}.  \var{ob} must not be
+  \NULL{}.
+  \versionadded{2.4}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyDateTime_CheckExact}{PyObject *ob}
+  Return true if \var{ob} is of type \cdata{PyDateTime_DateTimeType}.
+  \var{ob} must not be \NULL{}.
+  \versionadded{2.4}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyTime_Check}{PyObject *ob}
+  Return true if \var{ob} is of type \cdata{PyDateTime_TimeType} or
+  a subtype of \cdata{PyDateTime_TimeType}.  \var{ob} must not be
+  \NULL{}.
+  \versionadded{2.4}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyTime_CheckExact}{PyObject *ob}
+  Return true if \var{ob} is of type \cdata{PyDateTime_TimeType}.
+  \var{ob} must not be \NULL{}.
+  \versionadded{2.4}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyDelta_Check}{PyObject *ob}
+  Return true if \var{ob} is of type \cdata{PyDateTime_DeltaType} or
+  a subtype of \cdata{PyDateTime_DeltaType}.  \var{ob} must not be
+  \NULL{}.
+  \versionadded{2.4}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyDelta_CheckExact}{PyObject *ob}
+  Return true if \var{ob} is of type \cdata{PyDateTime_DeltaType}.
+  \var{ob} must not be \NULL{}.
+  \versionadded{2.4}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyTZInfo_Check}{PyObject *ob}
+  Return true if \var{ob} is of type \cdata{PyDateTime_TZInfoType} or
+  a subtype of \cdata{PyDateTime_TZInfoType}.  \var{ob} must not be
+  \NULL{}.
+  \versionadded{2.4}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyTZInfo_CheckExact}{PyObject *ob}
+  Return true if \var{ob} is of type \cdata{PyDateTime_TZInfoType}.
+  \var{ob} must not be \NULL{}.
+  \versionadded{2.4}
+\end{cfuncdesc}
+
+Macros to create objects:
+
+\begin{cfuncdesc}{PyObject*}{PyDate_FromDate}{int year, int month, int day}
+  Return a \code{datetime.date} object with the specified year, month
+  and day.
+  \versionadded{2.4}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyDateTime_FromDateAndTime}{int year, int month,
+        int day, int hour, int minute, int second, int usecond}
+  Return a \code{datetime.datetime} object with the specified year, month,
+  day, hour, minute, second and microsecond.
+  \versionadded{2.4}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyTime_FromTime}{int hour, int minute,
+        int second, int usecond}
+  Return a \code{datetime.time} object with the specified hour, minute,
+  second and microsecond.
+  \versionadded{2.4}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyDelta_FromDSU}{int days, int seconds,
+        int useconds}
+  Return a \code{datetime.timedelta} object representing the given number
+  of days, seconds and microseconds.  Normalization is performed so that
+  the resulting number of microseconds and seconds lie in the ranges
+  documented for \code{datetime.timedelta} objects.
+  \versionadded{2.4}
+\end{cfuncdesc}
+
+Macros to extract fields from date objects.  The argument must be an
+instance of \cdata{PyDateTime_Date}, including subclasses (such as
+\cdata{PyDateTime_DateTime}).  The argument must not be \NULL{}, and
+the type is not checked:
+
+\begin{cfuncdesc}{int}{PyDateTime_GET_YEAR}{PyDateTime_Date *o}
+  Return the year, as a positive int.
+  \versionadded{2.4}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyDateTime_GET_MONTH}{PyDateTime_Date *o}
+  Return the month, as an int from 1 through 12.
+  \versionadded{2.4}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyDateTime_GET_DAY}{PyDateTime_Date *o}
+  Return the day, as an int from 1 through 31.
+  \versionadded{2.4}
+\end{cfuncdesc}
+
+Macros to extract fields from datetime objects.  The argument must be an
+instance of \cdata{PyDateTime_DateTime}, including subclasses.
+The argument must not be \NULL{}, and the type is not checked:
+
+\begin{cfuncdesc}{int}{PyDateTime_DATE_GET_HOUR}{PyDateTime_DateTime *o}
+  Return the hour, as an int from 0 through 23.
+  \versionadded{2.4}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyDateTime_DATE_GET_MINUTE}{PyDateTime_DateTime *o}
+  Return the minute, as an int from 0 through 59.
+  \versionadded{2.4}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyDateTime_DATE_GET_SECOND}{PyDateTime_DateTime *o}
+  Return the second, as an int from 0 through 59.
+  \versionadded{2.4}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyDateTime_DATE_GET_MICROSECOND}{PyDateTime_DateTime *o}
+  Return the microsecond, as an int from 0 through 999999.
+  \versionadded{2.4}
+\end{cfuncdesc}
+
+Macros to extract fields from time objects.  The argument must be an
+instance of \cdata{PyDateTime_Time}, including subclasses.
+The argument must not be \NULL{}, and the type is not checked:
+
+\begin{cfuncdesc}{int}{PyDateTime_TIME_GET_HOUR}{PyDateTime_Time *o}
+  Return the hour, as an int from 0 through 23.
+  \versionadded{2.4}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyDateTime_TIME_GET_MINUTE}{PyDateTime_Time *o}
+  Return the minute, as an int from 0 through 59.
+  \versionadded{2.4}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyDateTime_TIME_GET_SECOND}{PyDateTime_Time *o}
+  Return the second, as an int from 0 through 59.
+  \versionadded{2.4}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyDateTime_TIME_GET_MICROSECOND}{PyDateTime_Time *o}
+  Return the microsecond, as an int from 0 through 999999.
+  \versionadded{2.4}
+\end{cfuncdesc}
+
+Macros for the convenience of modules implementing the DB API:
+
+\begin{cfuncdesc}{PyObject*}{PyDateTime_FromTimestamp}{PyObject *args}
+  Create and return a new \code{datetime.datetime} object given an argument
+  tuple suitable for passing to \code{datetime.datetime.fromtimestamp()}.
+  \versionadded{2.4}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyDate_FromTimestamp}{PyObject *args}
+  Create and return a new \code{datetime.date} object given an argument
+  tuple suitable for passing to \code{datetime.date.fromtimestamp()}.
+  \versionadded{2.4}
+\end{cfuncdesc}
+
+
+\subsection{Set Objects \label{setObjects}}
+\sectionauthor{Raymond D. Hettinger}{python@rcn.com}
+
+\obindex{set}
+\obindex{frozenset}
+\versionadded{2.5}
+
+This section details the public API for \class{set} and \class{frozenset}
+objects.  Any functionality not listed below is best accessed using the
+either the abstract object protocol (including
+\cfunction{PyObject_CallMethod()}, \cfunction{PyObject_RichCompareBool()},
+\cfunction{PyObject_Hash()}, \cfunction{PyObject_Repr()},
+\cfunction{PyObject_IsTrue()}, \cfunction{PyObject_Print()}, and
+\cfunction{PyObject_GetIter()})
+or the abstract number protocol (including
+\cfunction{PyNumber_Add()}, \cfunction{PyNumber_Subtract()},
+\cfunction{PyNumber_Or()}, \cfunction{PyNumber_Xor()},
+\cfunction{PyNumber_InPlaceAdd()}, \cfunction{PyNumber_InPlaceSubtract()},
+\cfunction{PyNumber_InPlaceOr()}, and \cfunction{PyNumber_InPlaceXor()}).
+
+\begin{ctypedesc}{PySetObject}
+  This subtype of \ctype{PyObject} is used to hold the internal data for
+  both \class{set} and \class{frozenset} objects.  It is like a
+  \ctype{PyDictObject} in that it is a fixed size for small sets
+  (much like tuple storage) and will point to a separate, variable sized
+  block of memory for medium and large sized sets (much like list storage).
+  None of the fields of this structure should be considered public and
+  are subject to change.  All access should be done through the
+  documented API rather than by manipulating the values in the structure.
+
+\end{ctypedesc}
+
+\begin{cvardesc}{PyTypeObject}{PySet_Type}
+  This is an instance of \ctype{PyTypeObject} representing the Python
+  \class{set} type.
+\end{cvardesc}
+
+\begin{cvardesc}{PyTypeObject}{PyFrozenSet_Type}
+  This is an instance of \ctype{PyTypeObject} representing the Python
+  \class{frozenset} type.
+\end{cvardesc}
+
+
+The following type check macros work on pointers to any Python object.
+Likewise, the constructor functions work with any iterable Python object.
+
+\begin{cfuncdesc}{int}{PyAnySet_Check}{PyObject *p}
+  Return true if \var{p} is a \class{set} object, a \class{frozenset}
+  object, or an instance of a subtype.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyAnySet_CheckExact}{PyObject *p}
+  Return true if \var{p} is a \class{set} object or a \class{frozenset}
+  object but not an instance of a subtype.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyFrozenSet_CheckExact}{PyObject *p}
+  Return true if \var{p} is a \class{frozenset} object
+  but not an instance of a subtype.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PySet_New}{PyObject *iterable}
+  Return a new \class{set} containing objects returned by the
+  \var{iterable}.  The \var{iterable} may be \NULL{} to create a
+  new empty set.  Return the new set on success or \NULL{} on
+  failure.  Raise \exception{TypeError} if \var{iterable} is
+  not actually iterable.  The constructor is also useful for
+  copying a set (\code{c=set(s)}).
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyFrozenSet_New}{PyObject *iterable}
+  Return a new \class{frozenset} containing objects returned by the
+  \var{iterable}.  The \var{iterable} may be \NULL{} to create a
+  new empty frozenset.  Return the new set on success or \NULL{} on
+  failure.  Raise \exception{TypeError} if \var{iterable} is
+  not actually iterable.
+\end{cfuncdesc}
+
+
+The following functions and macros are available for instances of
+\class{set} or \class{frozenset} or instances of their subtypes.
+
+\begin{cfuncdesc}{int}{PySet_Size}{PyObject *anyset}
+  Return the length of a \class{set} or \class{frozenset} object.
+  Equivalent to \samp{len(\var{anyset})}.  Raises a
+  \exception{PyExc_SystemError} if \var{anyset} is not a \class{set},
+  \class{frozenset}, or an instance of a subtype.
+  \bifuncindex{len}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PySet_GET_SIZE}{PyObject *anyset}
+  Macro form of \cfunction{PySet_Size()} without error checking.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PySet_Contains}{PyObject *anyset, PyObject *key}
+  Return 1 if found, 0 if not found, and -1 if an error is
+  encountered.  Unlike the Python \method{__contains__()} method, this
+  function does not automatically convert unhashable sets into temporary
+  frozensets.  Raise a \exception{TypeError} if the \var{key} is unhashable.
+  Raise \exception{PyExc_SystemError} if \var{anyset} is not a \class{set},
+  \class{frozenset}, or an instance of a subtype.
+\end{cfuncdesc}
+
+The following functions are available for instances of \class{set} or
+its subtypes but not for instances of \class{frozenset} or its subtypes.
+
+\begin{cfuncdesc}{int}{PySet_Add}{PyObject *set, PyObject *key}
+  Add \var{key} to a \class{set} instance.  Does not apply to
+  \class{frozenset} instances.  Return 0 on success or -1 on failure.
+  Raise a \exception{TypeError} if the \var{key} is unhashable.
+  Raise a \exception{MemoryError} if there is no room to grow.
+  Raise a \exception{SystemError} if \var{set} is an not an instance
+  of \class{set} or its subtype.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PySet_Discard}{PyObject *set, PyObject *key}
+  Return 1 if found and removed, 0 if not found (no action taken),
+  and -1 if an error is encountered.  Does not raise \exception{KeyError}
+  for missing keys.  Raise a \exception{TypeError} if the \var{key} is
+  unhashable.  Unlike the Python \method{discard()} method, this function
+  does not automatically convert unhashable sets into temporary frozensets.
+  Raise \exception{PyExc_SystemError} if \var{set} is an not an instance
+  of \class{set} or its subtype.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PySet_Pop}{PyObject *set}
+  Return a new reference to an arbitrary object in the \var{set},
+  and removes the object from the \var{set}.  Return \NULL{} on
+  failure.  Raise \exception{KeyError} if the set is empty.
+  Raise a \exception{SystemError} if \var{set} is an not an instance
+  of \class{set} or its subtype.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PySet_Clear}{PyObject *set}
+  Empty an existing set of all elements.
+\end{cfuncdesc}
diff --git a/sys/src/cmd/python/Doc/api/exceptions.tex b/sys/src/cmd/python/Doc/api/exceptions.tex
new file mode 100644
index 000000000..2dabeee62
--- /dev/null
+++ b/sys/src/cmd/python/Doc/api/exceptions.tex
@@ -0,0 +1,442 @@
+\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_*()} 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.  It is responsible for either handling the error and
+clearing the exception or returning after cleaning up any resources it
+holds (such as object references or memory allocations); it should
+\emph{not} continue normally if it is not prepared to handle the
+error.  If returning due to an error, it is important to indicate to
+the caller that an error has been set.  If the error is not handled or
+carefully propagated, additional calls into the Python/C API may not
+behave as intended and may fail in mysterious ways.
+
+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
+  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; use \cfunction{PyErr_Fetch()} to save the current
+  exception state.}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyErr_SetString}{PyObject *type, const 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.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyErr_Format}{PyObject *exception,
+                                           const char *format, \moreargs}
+  This function sets the error indicator and returns \NULL.
+  \var{exception} should be a Python exception (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.
+
+  % This should be exactly the same as the table in PyString_FromFormat.
+  % One should just refer to the other.
+
+  % The descriptions for %zd and %zu are wrong, but the truth is complicated
+  % because not all compilers support the %z width modifier -- we fake it
+  % when necessary via interpolating PY_FORMAT_SIZE_T.
+
+  % %u, %lu, %zu should have "new in Python 2.5" blurbs.
+
+  \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{\%u}{unsigned int}{Exactly equivalent to \code{printf("\%u")}.}
+    \lineiii{\%ld}{long}{Exactly equivalent to \code{printf("\%ld")}.}
+    \lineiii{\%lu}{unsigned long}{Exactly equivalent to \code{printf("\%lu")}.}
+    \lineiii{\%zd}{Py_ssize_t}{Exactly equivalent to \code{printf("\%zd")}.}
+    \lineiii{\%zu}{size_t}{Exactly equivalent to \code{printf("\%zu")}.}
+    \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}
+
+  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.
+\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(\var{type});} when the system call
+  returns an error.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyErr_SetFromErrnoWithFilename}{PyObject *type,
+                                                             const 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}{PyObject*}{PyErr_SetFromWindowsErr}{int ierr}
+  This is a convenience function to raise \exception{WindowsError}.
+  If called with \var{ierr} of \cdata{0}, the error code returned by a
+  call to \cfunction{GetLastError()} is used instead.  It calls the
+  Win32 function \cfunction{FormatMessage()} to retrieve the Windows
+  description of error code given by \var{ierr} or
+  \cfunction{GetLastError()}, then it constructs a tuple object whose
+  first item is the \var{ierr} value and whose second item is the
+  corresponding error message (gotten from
+  \cfunction{FormatMessage()}), and then calls
+  \samp{PyErr_SetObject(\var{PyExc_WindowsError}, \var{object})}.
+  This function always returns \NULL.
+  Availability: Windows.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyErr_SetExcFromWindowsErr}{PyObject *type,
+	                                                 int ierr}
+  Similar to \cfunction{PyErr_SetFromWindowsErr()}, with an additional
+  parameter specifying the exception type to be raised.
+  Availability: Windows.
+  \versionadded{2.3}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyErr_SetFromWindowsErrWithFilename}{int ierr,
+                                                                const char *filename}
+  Similar to \cfunction{PyErr_SetFromWindowsErr()}, with the
+  additional behavior that if \var{filename} is not \NULL, it is
+  passed to the constructor of \exception{WindowsError} as a third
+  parameter.
+  Availability: Windows.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyErr_SetExcFromWindowsErrWithFilename}
+	{PyObject *type, int ierr, char *filename}
+  Similar to \cfunction{PyErr_SetFromWindowsErrWithFilename()}, with
+  an additional parameter specifying the exception type to be raised.
+  Availability: Windows.
+  \versionadded{2.3}
+\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_WarnEx}{PyObject *category, char *message, int stacklevel}
+  Issue a warning message.  The \var{category} argument is a warning
+  category (see below) or \NULL; the \var{message} argument is a
+  message string.  \var{stacklevel} is a positive number giving a
+  number of stack frames; the warning will be issued from the 
+  currently executing line of code in that stack frame.  A \var{stacklevel}
+  of 1 is the function calling \cfunction{PyErr_WarnEx()}, 2 is 
+  the function above that, and so forth.
+
+  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_UnicodeWarning}, \cdata{PyExc_DeprecationWarning},
+  \cdata{PyExc_SyntaxWarning}, \cdata{PyExc_RuntimeWarning}, and
+  \cdata{PyExc_FutureWarning}.  \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_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.  The warning will appear to be issued from the function
+  calling \cfunction{PyErr_Warn()}, equivalent to calling
+  \cfunction{PyErr_WarnEx()} with a \var{stacklevel} of 1.
+  
+  Deprecated; use \cfunction{PyErr_WarnEx()} instead.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyErr_WarnExplicit}{PyObject *category,
+                const char *message, const char *filename, int lineno,
+                const 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 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.
+  % XXX This was described as obsolete, but is used in
+  % thread.interrupt_main() (used from IDLE), so it's still needed.
+\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 \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 alternate base classes;
+  it can either be only one class or a tuple of classes.
+  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 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_BaseException\ttindex{PyExc_BaseException}}{\exception{BaseException}}{(1), (4)}
+  \lineiii{PyExc_Exception\ttindex{PyExc_Exception}}{\exception{Exception}}{(1)}
+  \lineiii{PyExc_StandardError\ttindex{PyExc_StandardError}}{\exception{StandardError}}{(1)}
+  \lineiii{PyExc_ArithmeticError\ttindex{PyExc_ArithmeticError}}{\exception{ArithmeticError}}{(1)}
+  \lineiii{PyExc_LookupError\ttindex{PyExc_LookupError}}{\exception{LookupError}}{(1)}
+  \lineiii{PyExc_AssertionError\ttindex{PyExc_AssertionError}}{\exception{AssertionError}}{}
+  \lineiii{PyExc_AttributeError\ttindex{PyExc_AttributeError}}{\exception{AttributeError}}{}
+  \lineiii{PyExc_EOFError\ttindex{PyExc_EOFError}}{\exception{EOFError}}{}
+  \lineiii{PyExc_EnvironmentError\ttindex{PyExc_EnvironmentError}}{\exception{EnvironmentError}}{(1)}
+  \lineiii{PyExc_FloatingPointError\ttindex{PyExc_FloatingPointError}}{\exception{FloatingPointError}}{}
+  \lineiii{PyExc_IOError\ttindex{PyExc_IOError}}{\exception{IOError}}{}
+  \lineiii{PyExc_ImportError\ttindex{PyExc_ImportError}}{\exception{ImportError}}{}
+  \lineiii{PyExc_IndexError\ttindex{PyExc_IndexError}}{\exception{IndexError}}{}
+  \lineiii{PyExc_KeyError\ttindex{PyExc_KeyError}}{\exception{KeyError}}{}
+  \lineiii{PyExc_KeyboardInterrupt\ttindex{PyExc_KeyboardInterrupt}}{\exception{KeyboardInterrupt}}{}
+  \lineiii{PyExc_MemoryError\ttindex{PyExc_MemoryError}}{\exception{MemoryError}}{}
+  \lineiii{PyExc_NameError\ttindex{PyExc_NameError}}{\exception{NameError}}{}
+  \lineiii{PyExc_NotImplementedError\ttindex{PyExc_NotImplementedError}}{\exception{NotImplementedError}}{}
+  \lineiii{PyExc_OSError\ttindex{PyExc_OSError}}{\exception{OSError}}{}
+  \lineiii{PyExc_OverflowError\ttindex{PyExc_OverflowError}}{\exception{OverflowError}}{}
+  \lineiii{PyExc_ReferenceError\ttindex{PyExc_ReferenceError}}{\exception{ReferenceError}}{(2)}
+  \lineiii{PyExc_RuntimeError\ttindex{PyExc_RuntimeError}}{\exception{RuntimeError}}{}
+  \lineiii{PyExc_SyntaxError\ttindex{PyExc_SyntaxError}}{\exception{SyntaxError}}{}
+  \lineiii{PyExc_SystemError\ttindex{PyExc_SystemError}}{\exception{SystemError}}{}
+  \lineiii{PyExc_SystemExit\ttindex{PyExc_SystemExit}}{\exception{SystemExit}}{}
+  \lineiii{PyExc_TypeError\ttindex{PyExc_TypeError}}{\exception{TypeError}}{}
+  \lineiii{PyExc_ValueError\ttindex{PyExc_ValueError}}{\exception{ValueError}}{}
+  \lineiii{PyExc_WindowsError\ttindex{PyExc_WindowsError}}{\exception{WindowsError}}{(3)}
+  \lineiii{PyExc_ZeroDivisionError\ttindex{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.
+
+\item[(4)]
+  \versionadded{2.5}
+\end{description}
+
+
+\section{Deprecation of String Exceptions}
+
+All exceptions built into Python or provided in the standard library
+are derived from \exception{BaseException}.
+\withsubitem{(built-in exception)}{\ttindex{BaseException}}
+
+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/sys/src/cmd/python/Doc/api/init.tex b/sys/src/cmd/python/Doc/api/init.tex
new file mode 100644
index 000000000..e380bdb25
--- /dev/null
+++ b/sys/src/cmd/python/Doc/api/init.tex
@@ -0,0 +1,884 @@
+\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}{void}{Py_InitializeEx}{int initsigs}
+  This function works like \cfunction{Py_Initialize()} if
+  \var{initsigs} is 1. If \var{initsigs} is 0, it skips
+  initialization registration of signal handlers, which
+  might be useful when Python is embedded. \versionadded{2.4}
+\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 extensions may not work properly if
+  their initialization routine is called more than once; this can
+  happen if an application 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 in 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.)
+
+  Also note that the use of this functionality is incompatible with
+  extension modules such as PyObjC and ctypes that use the
+  \cfunction{PyGILState_*} APIs (and this is inherent in the way the
+  \cfunction{PyGILState_*} functions work).  Simple things may work,
+  but confusing behavior will always be near.
+\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 interpreter 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 and Mac OS X,
+  \character{;} on Windows.  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 \code{sys.version}.
+  \withsubitem{(in module sys)}{\ttindex{version}}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{const char*}{Py_GetBuildNumber}{}
+  Return a string representing the Subversion revision that this Python
+  executable was built from.  This number is a string because it may contain a
+  trailing 'M' if Python was built from a mixed revision source tree.
+  \versionadded{2.5}
+\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 Mac OS X, it is \code{'darwin'}.  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
+  \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}{void}{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 100 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}.  There's one global
+variable, 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
+\csimplemacro{Py_BEGIN_ALLOW_THREADS}\ttindex{Py_BEGIN_ALLOW_THREADS}
+macro opens a new block and declares a hidden local variable; the
+\csimplemacro{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.
+
+Beginning with version 2.3, threads can now take advantage of the 
+\cfunction{PyGILState_*()} functions to do all of the above
+automatically.  The typical idiom for calling into Python from a C
+thread is now:
+
+\begin{verbatim}
+    PyGILState_STATE gstate;
+    gstate = PyGILState_Ensure();
+
+    /* Perform Python actions here.  */
+    result = CallSomeFunction();
+    /* evaluate result */
+
+    /* Release the thread. No Python API allowed beyond this point. */
+    PyGILState_Release(gstate);
+\end{verbatim}
+
+Note that the \cfunction{PyGILState_*()} functions assume there is
+only one global interpreter (created automatically by
+\cfunction{Py_Initialize()}).  Python still supports the creation of
+additional interpreters (using \cfunction{Py_NewInterpreter()}), but
+mixing multiple interpreters and the \cfunction{PyGILState_*()} API is
+unsupported.
+
+\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 the
+  calling thread 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}{int}{PyEval_ThreadsInitialized}{}
+  Returns a non-zero value if \cfunction{PyEval_InitThreads()} has been
+  called.  This function can be called without holding the lock, and
+  therefore can be used to avoid calls to the locking API when running
+  single-threaded.  This function is not available when thread support
+  is disabled at compile time. \versionadded{2.4}
+\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 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 \csimplemacro{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 \csimplemacro{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 \csimplemacro{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 \csimplemacro{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.  It is okay to call this function
+  when no current thread state is available.
+  If this function returns \NULL, no exception has been raised and the
+  caller should assume no current thread state is available.
+  \versionchanged[Previously this could only be called when a current
+  thread is active, and \NULL{} meant that an exception was raised]{2.3}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyThreadState_SetAsyncExc}{long id, PyObject *exc}
+  Asynchronously raise an exception in a thread.
+  The \var{id} argument is the thread id of the target thread;
+  \var{exc} is the exception object to be raised.
+  This function does not steal any references to \var{exc}.
+  To prevent naive misuse, you must write your own C extension
+  to call this.  Must be called with the GIL held.
+  Returns the number of thread states modified; this is normally one, but
+  will be zero if the thread id isn't found.  If \var{exc} is
+  \constant{NULL}, the pending exception (if any) for the thread is cleared.
+  This raises no exceptions.
+  \versionadded{2.3}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyGILState_STATE}{PyGILState_Ensure}{}
+Ensure that the current thread is ready to call the Python C API
+regardless of the current state of Python, or of its thread lock.
+This may be called as many times as desired by a thread as long as
+each call is matched with a call to \cfunction{PyGILState_Release()}.
+In general, other thread-related APIs may be used between
+\cfunction{PyGILState_Ensure()} and \cfunction{PyGILState_Release()}
+calls as long as the thread state is restored to its previous state
+before the Release().  For example, normal usage of the
+\csimplemacro{Py_BEGIN_ALLOW_THREADS} and
+\csimplemacro{Py_END_ALLOW_THREADS} macros is acceptable.
+    
+The return value is an opaque "handle" to the thread state when
+\cfunction{PyGILState_Acquire()} was called, and must be passed to
+\cfunction{PyGILState_Release()} to ensure Python is left in the same
+state. Even though recursive calls are allowed, these handles
+\emph{cannot} be shared - each unique call to
+\cfunction{PyGILState_Ensure} must save the handle for its call to
+\cfunction{PyGILState_Release}.
+    
+When the function returns, the current thread will hold the GIL.
+Failure is a fatal error.
+  \versionadded{2.3}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyGILState_Release}{PyGILState_STATE}
+Release any resources previously acquired.  After this call, Python's
+state will be the same as it was prior to the corresponding
+\cfunction{PyGILState_Ensure} call (but generally this state will be
+unknown to the caller, hence the use of the GILState API.)
+    
+Every call to \cfunction{PyGILState_Ensure()} must be matched by a call to 
+\cfunction{PyGILState_Release()} on the same thread.
+  \versionadded{2.3}
+\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_EXCEPTION},
+  \constant{PyTrace_LINE}, \constant{PyTrace_RETURN},
+  \constant{PyTrace_C_CALL}, \constant{PyTrace_C_EXCEPTION},
+  or \constant{PyTrace_C_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_EXCEPTION}{Exception information as returned by
+                            \function{sys.exc_info()}.}
+    \lineii{PyTrace_LINE}{Always \NULL.}
+    \lineii{PyTrace_RETURN}{Value being returned to the caller.}
+    \lineii{PyTrace_C_CALL}{Name of function being called.}
+    \lineii{PyTrace_C_EXCEPTION}{Always \NULL.}
+    \lineii{PyTrace_C_RETURN}{Always \NULL.}
+  \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_EXCEPTION}
+  The value of the \var{what} parameter to a \ctype{Py_tracefunc}
+  function when an exception has been raised.  The callback function
+  is called with this value for \var{what} when after any bytecode is
+  processed after which the exception becomes set within the frame
+  being executed.  The effect of this is that as exception propagation
+  causes the Python stack to unwind, the callback is called upon
+  return to each frame as the exception propagates.  Only trace
+  functions receives these events; they are not needed by the
+  profiler.
+\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 propagating an exception.
+\end{cvardesc}
+
+\begin{cvardesc}{int}{PyTrace_C_CALL}
+  The value for the \var{what} parameter to \ctype{Py_tracefunc}
+  functions when a C function is about to be called.
+\end{cvardesc}
+
+\begin{cvardesc}{int}{PyTrace_C_EXCEPTION}
+  The value for the \var{what} parameter to \ctype{Py_tracefunc}
+  functions when a C function has thrown an exception.
+\end{cvardesc}
+
+\begin{cvardesc}{int}{PyTrace_C_RETURN}
+  The value for the \var{what} parameter to \ctype{Py_tracefunc}
+  functions when a C function has returned.
+\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 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/sys/src/cmd/python/Doc/api/intro.tex b/sys/src/cmd/python/Doc/api/intro.tex
new file mode 100644
index 000000000..80650fede
--- /dev/null
+++ b/sys/src/cmd/python/Doc/api/intro.tex
@@ -0,0 +1,627 @@
+\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).
+
+\begin{notice}[warning]
+  Since Python may define some pre-processor definitions which affect
+  the standard headers on some systems, you \emph{must} include
+  \file{Python.h} before any standard headers are included.
+\end{notice}
+
+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}.  Ownership
+pertains to references, never to objects (objects are not owned: they
+are always shared).  "Owning a reference" means being responsible for
+calling Py_DECREF on it when the reference is no longer needed. 
+Ownership can also be transferred, meaning that the code that receives
+ownership of the reference then becomes responsible for eventually
+decref'ing it by calling \cfunction{Py_DECREF()} or
+\cfunction{Py_XDECREF()} when it's no longer needed---or passing on
+this responsibility (usually to its caller).
+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.  \emph{Stealing a reference}
+means that when you pass a reference to a function, that function
+assumes that it now owns that reference, and you are not responsible
+for it any longer.
+
+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}
+
+Here, \cfunction{PyInt_FromLong()} returns a new reference which is
+immediately stolen by \cfunction{PyTuple_SetItem()}.  When you want to
+keep using an object although the reference to it will be stolen,
+use \cfunction{Py_INCREF()} to grab another reference before calling the
+reference-stealing function.
+
+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()}.
+
+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 *tuple, *list;
+
+tuple = Py_BuildValue("(iis)", 1, 2, "three");
+list = 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++) {
+        PyObject *index = PyInt_FromLong(i);
+        if (!index)
+            return -1;
+        if (PyObject_SetItem(target, index, item) < 0)
+            return -1;
+        Py_DECREF(index);
+    }
+    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 reference 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 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 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.
+Notice that \cfunction{Py_Finalize} does \emph{not} free all memory
+allocated by the Python interpreter, e.g. memory allocated by extension
+modules currently cannot be released.
+
+
+\section{Debugging Builds \label{debugging}}
+
+Python can be built with several macros to enable extra checks of the
+interpreter and extension modules.  These checks tend to add a large
+amount of overhead to the runtime so they are not enabled by default.
+
+A full list of the various types of debugging builds is in the file
+\file{Misc/SpecialBuilds.txt} in the Python source distribution.
+Builds are available that support tracing of reference counts,
+debugging the memory allocator, or low-level profiling of the main
+interpreter loop.  Only the most frequently-used builds will be
+described in the remainder of this section.
+
+Compiling the interpreter with the \csimplemacro{Py_DEBUG} macro
+defined produces what is generally meant by "a debug build" of Python.
+\csimplemacro{Py_DEBUG} is enabled in the \UNIX{} build by adding
+\longprogramopt{with-pydebug} to the \file{configure} command.  It is also
+implied by the presence of the not-Python-specific
+\csimplemacro{_DEBUG} macro.  When \csimplemacro{Py_DEBUG} is enabled
+in the \UNIX{} build, compiler optimization is disabled.
+
+In addition to the reference count debugging described below, the
+following extra checks are performed:
+
+\begin{itemize}
+      \item Extra checks are added to the object allocator.
+      \item Extra checks are added to the parser and compiler.
+      \item Downcasts from wide types to narrow types are checked for
+            loss of information.
+      \item A number of assertions are added to the dictionary and set
+            implementations.  In addition, the set object acquires a
+            \method{test_c_api} method.
+      \item Sanity checks of the input arguments are added to frame
+            creation. 
+      \item The storage for long ints is initialized with a known
+            invalid pattern to catch reference to uninitialized
+            digits. 
+      \item Low-level tracing and extra exception checking are added
+            to the runtime virtual machine.
+      \item Extra checks are added to the memory arena implementation.
+      \item Extra debugging is added to the thread module.
+\end{itemize}
+
+There may be additional checks not mentioned here.
+
+Defining \csimplemacro{Py_TRACE_REFS} enables reference tracing.  When
+defined, a circular doubly linked list of active objects is maintained
+by adding two extra fields to every \ctype{PyObject}.  Total
+allocations are tracked as well.  Upon exit, all existing references
+are printed.  (In interactive mode this happens after every statement
+run by the interpreter.)  Implied by \csimplemacro{Py_DEBUG}.
+
+Please refer to \file{Misc/SpecialBuilds.txt} in the Python source
+distribution for more detailed information.
diff --git a/sys/src/cmd/python/Doc/api/memory.tex b/sys/src/cmd/python/Doc/api/memory.tex
new file mode 100644
index 000000000..18abe9838
--- /dev/null
+++ b/sys/src/cmd/python/Doc/api/memory.tex
@@ -0,0 +1,204 @@
+\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 over 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,
+but specifying  behavior when requesting zero bytes,
+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 distinct non-\NULL{} pointer if
+  possible, as if \cfunction{PyMem_Malloc(1)} had been called instead.
+  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})}; else 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()}. If the request fails,
+  \cfunction{PyMem_Realloc()} returns \NULL{} and \var{p} remains a
+  valid pointer to the previous memory area.
+\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
+  behavior 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}*}. On return, \var{p} will be a pointer to
+  the new memory area, or \NULL{} in the event of failure.
+\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 across 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()}.
+
+These will be explained in the next chapter on defining and
+implementing new object types in C.
diff --git a/sys/src/cmd/python/Doc/api/newtypes.tex b/sys/src/cmd/python/Doc/api/newtypes.tex
new file mode 100644
index 000000000..e5c5aaced
--- /dev/null
+++ b/sys/src/cmd/python/Doc/api/newtypes.tex
@@ -0,0 +1,1780 @@
+\chapter{Object Implementation Support \label{newTypes}}
+
+
+This chapter describes the functions, types, and macros used when
+defining new object types.
+
+
+\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, Py_ssize_t 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 is 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, Py_ssize_t 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,
+                                                Py_ssize_t 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}{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.
+
+  \versionchanged[Older versions of Python did not support \NULL{} as
+                  the value for the \var{methods} argument]{2.3}
+\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.
+
+  \versionchanged[Older versions of Python did not support \NULL{} as
+                  the value for the \var{methods} argument]{2.3}
+\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.}
+
+  \versionchanged[Older versions of Python did not support \NULL{} as
+                  the value for the \var{methods} argument]{2.3}
+\end{cfuncdesc}
+
+\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}}
+
+There are a large number of structures which are used in the
+definition of object types for Python.  This section describes these
+structures and how they are used.
+
+All Python objects ultimately share a small number of fields at the
+beginning of the object's representation in memory.  These are
+represented by the \ctype{PyObject} and \ctype{PyVarObject} types,
+which are defined, in turn, by the expansions of some macros also
+used, whether directly or indirectly, in the definition of all other
+Python objects.
+
+\begin{ctypedesc}{PyObject}
+  All object types are extensions of this type.  This is a type which
+  contains the information Python needs to treat a pointer to an
+  object as an object.  In a normal ``release'' build, it contains
+  only the objects reference count and a pointer to the corresponding
+  type object.  It corresponds to the fields defined by the
+  expansion of the \code{PyObject_HEAD} macro.
+\end{ctypedesc}
+
+\begin{ctypedesc}{PyVarObject}
+  This is an extension of \ctype{PyObject} that adds the
+  \member{ob_size} field.  This is only used for objects that have
+  some notion of \emph{length}.  This type does not often appear in
+  the Python/C API.  It corresponds to the fields defined by the
+  expansion of the \code{PyObject_VAR_HEAD} macro.
+\end{ctypedesc}
+
+These macros are used in the definition of \ctype{PyObject} and
+\ctype{PyVarObject}:
+
+\begin{csimplemacrodesc}{PyObject_HEAD}
+  This is a macro which expands to the declarations of the fields of
+  the \ctype{PyObject} type; it is used when declaring new types which
+  represent objects without a varying length.  The specific fields it
+  expands to depend on the definition of
+  \csimplemacro{Py_TRACE_REFS}.  By default, that macro is not
+  defined, and \csimplemacro{PyObject_HEAD} expands to:
+  \begin{verbatim}
+    Py_ssize_t ob_refcnt;
+    PyTypeObject *ob_type;
+  \end{verbatim}
+  When \csimplemacro{Py_TRACE_REFS} is defined, it expands to:
+  \begin{verbatim}
+    PyObject *_ob_next, *_ob_prev;
+    Py_ssize_t ob_refcnt;
+    PyTypeObject *ob_type;
+  \end{verbatim}
+\end{csimplemacrodesc}
+
+\begin{csimplemacrodesc}{PyObject_VAR_HEAD}
+  This is a macro which expands to the declarations of the fields of
+  the \ctype{PyVarObject} type; it is used when declaring new types which
+  represent objects with a length that varies from instance to
+  instance.  This macro always expands to:
+  \begin{verbatim}
+    PyObject_HEAD
+    Py_ssize_t ob_size;
+  \end{verbatim}
+  Note that \csimplemacro{PyObject_HEAD} is part of the expansion, and
+  that its own expansion varies depending on the definition of
+  \csimplemacro{Py_TRACE_REFS}.
+\end{csimplemacrodesc}
+
+PyObject_HEAD_INIT
+
+\begin{ctypedesc}{PyCFunction}
+  Type of the functions used to implement most Python callables in C.
+  Functions of this type take two \ctype{PyObject*} parameters and
+  return one such value.  If the return value is \NULL, an exception
+  shall have been set.  If not \NULL, the return value is interpreted
+  as the return value of the function as exposed in Python.  The
+  function must return a new reference.
+\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 \member{ml_flags} field is a bitfield which can include the
+following flags.  The individual flags indicate either a calling
+convention or a binding convention.  Of the calling convention flags,
+only \constant{METH_VARARGS} and \constant{METH_KEYWORDS} can be
+combined (but note that \constant{METH_KEYWORDS} alone is equivalent
+to \code{\constant{METH_VARARGS} | \constant{METH_KEYWORDS}}).
+Any of the calling convention flags can be combined with a
+binding flag.
+
+\begin{datadesc}{METH_VARARGS}
+  This is the typical calling convention, where the methods have the
+  type \ctype{PyCFunction}. The function expects two
+  \ctype{PyObject*} values.  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()} or \cfunction{PyArg_UnpackTuple}.
+\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{PyCFunction}.  When used with object
+  methods, the first parameter is typically named \code{self} and will
+  hold a reference to the object instance.  In all cases the second
+  parameter will be \NULL.
+\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}
+
+These two constants are not used to indicate the calling convention
+but the binding when use with methods of classes.  These may not be
+used for functions defined for modules.  At most one of these flags
+may be set for any given method.
+
+\begin{datadesc}{METH_CLASS}
+  The method will be passed the type object as the first parameter
+  rather than an instance of the type.  This is used to create
+  \emph{class methods}, similar to what is created when using the
+  \function{classmethod()}\bifuncindex{classmethod} built-in
+  function.
+  \versionadded{2.3}
+\end{datadesc}
+
+\begin{datadesc}{METH_STATIC}
+  The method will be passed \NULL{} as the first parameter rather than
+  an instance of the type.  This is used to create \emph{static
+  methods}, similar to what is created when using the
+  \function{staticmethod()}\bifuncindex{staticmethod} built-in
+  function.
+  \versionadded{2.3}
+\end{datadesc}
+
+One other constant controls whether a method is loaded in place of
+another definition with the same method name.
+
+\begin{datadesc}{METH_COEXIST}
+  The method will be loaded in place of existing definitions.  Without
+  \var{METH_COEXIST}, the default is to skip repeated definitions.  Since
+  slot wrappers are loaded before the method table, the existence of a
+  \var{sq_contains} slot, for example, would generate a wrapped method
+  named \method{__contains__()} and preclude the loading of a
+  corresponding PyCFunction with the same name.  With the flag defined,
+  the PyCFunction will be loaded in place of the wrapper object and will
+  co-exist with the slot.  This is helpful because calls to PyCFunctions
+  are optimized more than wrapper object calls.
+  \versionadded{2.4}
+\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 can be useful in the implementation of a
+  \member{tp_getattro} or \member{tp_getattr} handler that does not
+  use the \cfunction{PyObject_GenericGetAttr()} function.
+\end{cfuncdesc}
+
+
+\section{Type Objects \label{type-structs}}
+
+Perhaps one of the most important structures of the Python object
+system is the structure that defines a new type: the
+\ctype{PyTypeObject} structure.  Type objects can be handled using any
+of the \cfunction{PyObject_*()} or \cfunction{PyType_*()} functions,
+but do not offer much that's interesting to most Python applications.
+These objects are fundamental to how objects behave, so they are very
+important to the interpreter itself and to any extension module that
+implements new types.
+
+Type objects are fairly large compared to most of the standard types.
+The reason for the size is that each type object stores a large number
+of values, mostly C function pointers, each of which implements a
+small part of the type's functionality.  The fields of the type object
+are examined in detail in this section.  The fields will be described
+in the order in which they occur in the structure.
+
+Typedefs:
+unaryfunc, binaryfunc, ternaryfunc, inquiry, coercion, intargfunc,
+intintargfunc, intobjargproc, intintobjargproc, objobjargproc,
+destructor, freefunc, printfunc, getattrfunc, getattrofunc, setattrfunc,
+setattrofunc, cmpfunc, reprfunc, hashfunc
+
+The structure definition for \ctype{PyTypeObject} can be found in
+\file{Include/object.h}.  For convenience of reference, this repeats
+the definition found there:
+
+\verbatiminput{typestruct.h}
+
+The type object structure extends the \ctype{PyVarObject} structure.
+The \member{ob_size} field is used for dynamic types (created
+by  \function{type_new()}, usually called from a class statement).
+Note that \cdata{PyType_Type} (the metatype) initializes
+\member{tp_itemsize}, which means that its instances (i.e. type
+objects) \emph{must} have the \member{ob_size} field.
+
+\begin{cmemberdesc}{PyObject}{PyObject*}{_ob_next}
+\cmemberline{PyObject}{PyObject*}{_ob_prev}
+  These fields are only present when the macro \code{Py_TRACE_REFS} is
+  defined.  Their initialization to \NULL{} is taken care of by the
+  \code{PyObject_HEAD_INIT} macro.  For statically allocated objects,
+  these fields always remain \NULL.  For dynamically allocated
+  objects, these two fields are used to link the object into a
+  doubly-linked list of \emph{all} live objects on the heap.  This
+  could be used for various debugging purposes; currently the only use
+  is to print the objects that are still alive at the end of a run
+  when the environment variable \envvar{PYTHONDUMPREFS} is set.
+
+  These fields are not inherited by subtypes.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyObject}{Py_ssize_t}{ob_refcnt}
+  This is the type object's reference count, initialized to \code{1}
+  by the \code{PyObject_HEAD_INIT} macro.  Note that for statically
+  allocated type objects, the type's instances (objects whose
+  \member{ob_type} points back to the type) do \emph{not} count as
+  references.  But for dynamically allocated type objects, the
+  instances \emph{do} count as references.
+
+  This field is not inherited by subtypes.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyObject}{PyTypeObject*}{ob_type}
+  This is the type's type, in other words its metatype.  It is
+  initialized by the argument to the \code{PyObject_HEAD_INIT} macro,
+  and its value should normally be \code{\&PyType_Type}.  However, for
+  dynamically loadable extension modules that must be usable on
+  Windows (at least), the compiler complains that this is not a valid
+  initializer.  Therefore, the convention is to pass \NULL{} to the
+  \code{PyObject_HEAD_INIT} macro and to initialize this field
+  explicitly at the start of the module's initialization function,
+  before doing anything else.  This is typically done like this:
+
+\begin{verbatim}
+Foo_Type.ob_type = &PyType_Type;
+\end{verbatim}
+
+  This should be done before any instances of the type are created.
+  \cfunction{PyType_Ready()} checks if \member{ob_type} is \NULL, and
+  if so, initializes it: in Python 2.2, it is set to
+  \code{\&PyType_Type}; in Python 2.2.1 and later it is
+  initialized to the \member{ob_type} field of the base class.
+  \cfunction{PyType_Ready()} will not change this field if it is
+  non-zero.
+
+  In Python 2.2, this field is not inherited by subtypes.  In 2.2.1,
+  and in 2.3 and beyond, it is inherited by subtypes.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyVarObject}{Py_ssize_t}{ob_size}
+  For statically allocated type objects, this should be initialized
+  to zero.  For dynamically allocated type objects, this field has a
+  special internal meaning.
+
+  This field is not inherited by subtypes.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{char*}{tp_name}
+  Pointer to a NUL-terminated string containing the name of the type.
+  For types that are accessible as module globals, the string should
+  be the full module name, followed by a dot, followed by the type
+  name; for built-in types, it should be just the type name.  If the
+  module is a submodule of a package, the full package name is part of
+  the full module name.  For example, a type named \class{T} defined
+  in module \module{M} in subpackage \module{Q} in package \module{P}
+  should have the \member{tp_name} initializer \code{"P.Q.M.T"}.
+
+  For dynamically allocated type objects, this should just be the type
+  name, and the module name explicitly stored in the type dict as the
+  value for key \code{'__module__'}.
+
+  For statically allocated type objects, the tp_name field should
+  contain a dot.  Everything before the last dot is made accessible as
+  the \member{__module__} attribute, and everything after the last dot
+  is made accessible as the \member{__name__} attribute.
+
+  If no dot is present, the entire \member{tp_name} field is made
+  accessible as the \member{__name__} attribute, and the
+  \member{__module__} attribute is undefined (unless explicitly set in
+  the dictionary, as explained above).  This means your type will be
+  impossible to pickle.
+
+  This field is not inherited by subtypes.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{Py_ssize_t}{tp_basicsize}
+\cmemberline{PyTypeObject}{Py_ssize_t}{tp_itemsize}
+  These fields allow calculating the size in bytes of instances of
+  the type.
+
+  There are two kinds of types: types with fixed-length instances have
+  a zero \member{tp_itemsize} field, types with variable-length
+  instances have a non-zero \member{tp_itemsize} field.  For a type
+  with fixed-length instances, all instances have the same size,
+  given in \member{tp_basicsize}.
+
+  For a type with variable-length instances, the instances must have
+  an \member{ob_size} field, and the instance size is
+  \member{tp_basicsize} plus N times \member{tp_itemsize}, where N is
+  the ``length'' of the object.  The value of N is typically stored in
+  the instance's \member{ob_size} field.  There are exceptions:  for
+  example, long ints use a negative \member{ob_size} to indicate a
+  negative number, and N is \code{abs(\member{ob_size})} there.  Also,
+  the presence of an \member{ob_size} field in the instance layout
+  doesn't mean that the instance structure is variable-length (for
+  example, the structure for the list type has fixed-length instances,
+  yet those instances have a meaningful \member{ob_size} field).
+
+  The basic size includes the fields in the instance declared by the
+  macro \csimplemacro{PyObject_HEAD} or
+  \csimplemacro{PyObject_VAR_HEAD} (whichever is used to declare the
+  instance struct) and this in turn includes the \member{_ob_prev} and
+  \member{_ob_next} fields if they are present.  This means that the
+  only correct way to get an initializer for the \member{tp_basicsize}
+  is to use the \keyword{sizeof} operator on the struct used to
+  declare the instance layout.  The basic size does not include the GC
+  header size (this is new in Python 2.2; in 2.1 and 2.0, the GC
+  header size was included in \member{tp_basicsize}).
+
+  These fields are inherited separately by subtypes.  If the base type
+  has a non-zero \member{tp_itemsize}, it is generally not safe to set
+  \member{tp_itemsize} to a different non-zero value in a subtype
+  (though this depends on the implementation of the base type).
+
+  A note about alignment: if the variable items require a particular
+  alignment, this should be taken care of by the value of
+  \member{tp_basicsize}.  Example: suppose a type implements an array
+  of \code{double}. \member{tp_itemsize} is \code{sizeof(double)}.
+  It is the programmer's responsibility that \member{tp_basicsize} is
+  a multiple of \code{sizeof(double)} (assuming this is the alignment
+  requirement for \code{double}).
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{destructor}{tp_dealloc}
+  A pointer to the instance destructor function.  This function must
+  be defined unless the type guarantees that its instances will never
+  be deallocated (as is the case for the singletons \code{None} and
+  \code{Ellipsis}).
+
+  The destructor function is called by the \cfunction{Py_DECREF()} and
+  \cfunction{Py_XDECREF()} macros when the new reference count is
+  zero.  At this point, the instance is still in existence, but there
+  are no references to it.  The destructor function should free all
+  references which the instance owns, free all memory buffers owned by
+  the instance (using the freeing function corresponding to the
+  allocation function used to allocate the buffer), and finally (as
+  its last action) call the type's \member{tp_free} function.  If the
+  type is not subtypable (doesn't have the
+  \constant{Py_TPFLAGS_BASETYPE} flag bit set), it is permissible to
+  call the object deallocator directly instead of via
+  \member{tp_free}.  The object deallocator should be the one used to
+  allocate the instance; this is normally \cfunction{PyObject_Del()}
+  if the instance was allocated using \cfunction{PyObject_New()} or
+  \cfunction{PyObject_VarNew()}, or \cfunction{PyObject_GC_Del()} if
+  the instance was allocated using \cfunction{PyObject_GC_New()} or
+  \cfunction{PyObject_GC_VarNew()}.
+
+  This field is inherited by subtypes.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{printfunc}{tp_print}
+  An optional pointer to the instance print function.
+
+  The print function is only called when the instance is printed to a
+  \emph{real} file; when it is printed to a pseudo-file (like a
+  \class{StringIO} instance), the instance's \member{tp_repr} or
+  \member{tp_str} function is called to convert it to a string.  These
+  are also called when the type's \member{tp_print} field is \NULL.  A
+  type should never implement \member{tp_print} in a way that produces
+  different output than \member{tp_repr} or \member{tp_str} would.
+
+  The print function is called with the same signature as
+  \cfunction{PyObject_Print()}: \code{int tp_print(PyObject *self, FILE
+  *file, int flags)}.  The \var{self} argument is the instance to be
+  printed.  The \var{file} argument is the stdio file to which it is
+  to be printed.  The \var{flags} argument is composed of flag bits.
+  The only flag bit currently defined is \constant{Py_PRINT_RAW}.
+  When the \constant{Py_PRINT_RAW} flag bit is set, the instance
+  should be printed the same way as \member{tp_str} would format it;
+  when the \constant{Py_PRINT_RAW} flag bit is clear, the instance
+  should be printed the same was as \member{tp_repr} would format it.
+  It should return \code{-1} and set an exception condition when an
+  error occurred during the comparison.
+
+  It is possible that the \member{tp_print} field will be deprecated.
+  In any case, it is recommended not to define \member{tp_print}, but
+  instead to rely on \member{tp_repr} and \member{tp_str} for
+  printing.
+
+  This field is inherited by subtypes.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{getattrfunc}{tp_getattr}
+  An optional pointer to the get-attribute-string function.
+
+  This field is deprecated.  When it is defined, it should point to a
+  function that acts the same as the \member{tp_getattro} function,
+  but taking a C string instead of a Python string object to give the
+  attribute name.  The signature is the same as for
+  \cfunction{PyObject_GetAttrString()}.
+
+  This field is inherited by subtypes together with
+  \member{tp_getattro}: a subtype inherits both \member{tp_getattr}
+  and \member{tp_getattro} from its base type when the subtype's
+  \member{tp_getattr} and \member{tp_getattro} are both \NULL.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{setattrfunc}{tp_setattr}
+  An optional pointer to the set-attribute-string function.
+
+  This field is deprecated.  When it is defined, it should point to a
+  function that acts the same as the \member{tp_setattro} function,
+  but taking a C string instead of a Python string object to give the
+  attribute name.  The signature is the same as for
+  \cfunction{PyObject_SetAttrString()}.
+
+  This field is inherited by subtypes together with
+  \member{tp_setattro}: a subtype inherits both \member{tp_setattr}
+  and \member{tp_setattro} from its base type when the subtype's
+  \member{tp_setattr} and \member{tp_setattro} are both \NULL.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{cmpfunc}{tp_compare}
+  An optional pointer to the three-way comparison function.
+
+  The signature is the same as for \cfunction{PyObject_Compare()}.
+  The function should return \code{1} if \var{self} greater than
+  \var{other}, \code{0} if \var{self} is equal to \var{other}, and
+  \code{-1} if \var{self} less than \var{other}.  It should return
+  \code{-1} and set an exception condition when an error occurred
+  during the comparison.
+
+  This field is inherited by subtypes together with
+  \member{tp_richcompare} and \member{tp_hash}: a subtypes inherits
+  all three of \member{tp_compare}, \member{tp_richcompare}, and
+  \member{tp_hash} when the subtype's \member{tp_compare},
+  \member{tp_richcompare}, and \member{tp_hash} are all \NULL.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{reprfunc}{tp_repr}
+  An optional pointer to a function that implements the built-in
+  function \function{repr()}.\bifuncindex{repr}
+
+  The signature is the same as for \cfunction{PyObject_Repr()}; it
+  must return a string or a Unicode object.  Ideally, this function
+  should return a string that, when passed to \function{eval()}, given
+  a suitable environment, returns an object with the same value.  If
+  this is not feasible, it should return a string starting with
+  \character{\textless} and ending with \character{\textgreater} from
+  which both the type and the value of the object can be deduced.
+
+  When this field is not set, a string of the form \samp{<\%s object
+  at \%p>} is returned, where \code{\%s} is replaced by the type name,
+  and \code{\%p} by the object's memory address.
+
+  This field is inherited by subtypes.
+\end{cmemberdesc}
+
+PyNumberMethods *tp_as_number;
+
+    XXX
+
+PySequenceMethods *tp_as_sequence;
+
+    XXX
+
+PyMappingMethods *tp_as_mapping;
+
+    XXX
+
+\begin{cmemberdesc}{PyTypeObject}{hashfunc}{tp_hash}
+  An optional pointer to a function that implements the built-in
+  function \function{hash()}.\bifuncindex{hash}
+
+  The signature is the same as for \cfunction{PyObject_Hash()}; it
+  must return a C long.  The value \code{-1} should not be returned as
+  a normal return value; when an error occurs during the computation
+  of the hash value, the function should set an exception and return
+  \code{-1}.
+
+  When this field is not set, two possibilities exist: if the
+  \member{tp_compare} and \member{tp_richcompare} fields are both
+  \NULL, a default hash value based on the object's address is
+  returned; otherwise, a \exception{TypeError} is raised.
+
+  This field is inherited by subtypes together with
+  \member{tp_richcompare} and \member{tp_compare}: a subtypes inherits
+  all three of \member{tp_compare}, \member{tp_richcompare}, and
+  \member{tp_hash}, when the subtype's \member{tp_compare},
+  \member{tp_richcompare} and \member{tp_hash} are all \NULL.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{ternaryfunc}{tp_call}
+  An optional pointer to a function that implements calling the
+  object.  This should be \NULL{} if the object is not callable.  The
+  signature is the same as for \cfunction{PyObject_Call()}.
+
+  This field is inherited by subtypes.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{reprfunc}{tp_str}
+  An optional pointer to a function that implements the built-in
+  operation \function{str()}.  (Note that \class{str} is a type now,
+  and \function{str()} calls the constructor for that type.  This
+  constructor calls \cfunction{PyObject_Str()} to do the actual work,
+  and \cfunction{PyObject_Str()} will call this handler.)
+
+  The signature is the same as for \cfunction{PyObject_Str()}; it must
+  return a string or a Unicode object.  This function should return a
+  ``friendly'' string representation of the object, as this is the
+  representation that will be used by the print statement.
+
+  When this field is not set, \cfunction{PyObject_Repr()} is called to
+  return a string representation.
+
+  This field is inherited by subtypes.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{getattrofunc}{tp_getattro}
+  An optional pointer to the get-attribute function.
+
+  The signature is the same as for \cfunction{PyObject_GetAttr()}.  It
+  is usually convenient to set this field to
+  \cfunction{PyObject_GenericGetAttr()}, which implements the normal
+  way of looking for object attributes.
+
+  This field is inherited by subtypes together with
+  \member{tp_getattr}: a subtype inherits both \member{tp_getattr} and
+  \member{tp_getattro} from its base type when the subtype's
+  \member{tp_getattr} and \member{tp_getattro} are both \NULL.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{setattrofunc}{tp_setattro}
+  An optional pointer to the set-attribute function.
+
+  The signature is the same as for \cfunction{PyObject_SetAttr()}.  It
+  is usually convenient to set this field to
+  \cfunction{PyObject_GenericSetAttr()}, which implements the normal
+  way of setting object attributes.
+
+  This field is inherited by subtypes together with
+  \member{tp_setattr}: a subtype inherits both \member{tp_setattr} and
+  \member{tp_setattro} from its base type when the subtype's
+  \member{tp_setattr} and \member{tp_setattro} are both \NULL.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{PyBufferProcs*}{tp_as_buffer}
+  Pointer to an additional structure that contains fields relevant only to
+  objects which implement the buffer interface.  These fields are
+  documented in ``Buffer Object Structures'' (section
+  \ref{buffer-structs}).
+
+  The \member{tp_as_buffer} field is not inherited, but the contained
+  fields are inherited individually.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{long}{tp_flags}
+  This field is a bit mask of various flags.  Some flags indicate
+  variant semantics for certain situations; others are used to
+  indicate that certain fields in the type object (or in the extension
+  structures referenced via \member{tp_as_number},
+  \member{tp_as_sequence}, \member{tp_as_mapping}, and
+  \member{tp_as_buffer}) that were historically not always present are
+  valid; if such a flag bit is clear, the type fields it guards must
+  not be accessed and must be considered to have a zero or \NULL{}
+  value instead.
+
+  Inheritance of this field is complicated.  Most flag bits are
+  inherited individually, i.e. if the base type has a flag bit set,
+  the subtype inherits this flag bit.  The flag bits that pertain to
+  extension structures are strictly inherited if the extension
+  structure is inherited, i.e. the base type's value of the flag bit
+  is copied into the subtype together with a pointer to the extension
+  structure.  The \constant{Py_TPFLAGS_HAVE_GC} flag bit is inherited
+  together with the \member{tp_traverse} and \member{tp_clear} fields,
+  i.e. if the \constant{Py_TPFLAGS_HAVE_GC} flag bit is clear in the
+  subtype and the \member{tp_traverse} and \member{tp_clear} fields in
+  the subtype exist (as indicated by the
+  \constant{Py_TPFLAGS_HAVE_RICHCOMPARE} flag bit) and have \NULL{}
+  values.
+
+  The following bit masks are currently defined; these can be or-ed
+  together using the \code{|} operator to form the value of the
+  \member{tp_flags} field.  The macro \cfunction{PyType_HasFeature()}
+  takes a type and a flags value, \var{tp} and \var{f}, and checks
+  whether \code{\var{tp}->tp_flags \& \var{f}} is non-zero.
+
+  \begin{datadesc}{Py_TPFLAGS_HAVE_GETCHARBUFFER}
+    If this bit is set, the \ctype{PyBufferProcs} struct referenced by
+    \member{tp_as_buffer} has the \member{bf_getcharbuffer} field.
+  \end{datadesc}
+
+  \begin{datadesc}{Py_TPFLAGS_HAVE_SEQUENCE_IN}
+    If this bit is set, the \ctype{PySequenceMethods} struct
+    referenced by \member{tp_as_sequence} has the \member{sq_contains}
+    field.
+  \end{datadesc}
+
+  \begin{datadesc}{Py_TPFLAGS_GC}
+    This bit is obsolete.  The bit it used to name is no longer in
+    use.  The symbol is now defined as zero.
+  \end{datadesc}
+
+  \begin{datadesc}{Py_TPFLAGS_HAVE_INPLACEOPS}
+    If this bit is set, the \ctype{PySequenceMethods} struct
+    referenced by \member{tp_as_sequence} and the
+    \ctype{PyNumberMethods} structure referenced by
+    \member{tp_as_number} contain the fields for in-place operators.
+    In particular, this means that the \ctype{PyNumberMethods}
+    structure has the fields \member{nb_inplace_add},
+    \member{nb_inplace_subtract}, \member{nb_inplace_multiply},
+    \member{nb_inplace_divide}, \member{nb_inplace_remainder},
+    \member{nb_inplace_power}, \member{nb_inplace_lshift},
+    \member{nb_inplace_rshift}, \member{nb_inplace_and},
+    \member{nb_inplace_xor}, and \member{nb_inplace_or}; and the
+    \ctype{PySequenceMethods} struct has the fields
+    \member{sq_inplace_concat} and \member{sq_inplace_repeat}.
+  \end{datadesc}
+
+  \begin{datadesc}{Py_TPFLAGS_CHECKTYPES}
+    If this bit is set, the binary and ternary operations in the
+    \ctype{PyNumberMethods} structure referenced by
+    \member{tp_as_number} accept arguments of arbitrary object types,
+    and do their own type conversions if needed.  If this bit is
+    clear, those operations require that all arguments have the
+    current type as their type, and the caller is supposed to perform
+    a coercion operation first.  This applies to \member{nb_add},
+    \member{nb_subtract}, \member{nb_multiply}, \member{nb_divide},
+    \member{nb_remainder}, \member{nb_divmod}, \member{nb_power},
+    \member{nb_lshift}, \member{nb_rshift}, \member{nb_and},
+    \member{nb_xor}, and \member{nb_or}.
+  \end{datadesc}
+
+  \begin{datadesc}{Py_TPFLAGS_HAVE_RICHCOMPARE}
+    If this bit is set, the type object has the
+    \member{tp_richcompare} field, as well as the \member{tp_traverse}
+    and the \member{tp_clear} fields.
+  \end{datadesc}
+
+  \begin{datadesc}{Py_TPFLAGS_HAVE_WEAKREFS}
+    If this bit is set, the \member{tp_weaklistoffset} field is
+    defined.  Instances of a type are weakly referenceable if the
+    type's \member{tp_weaklistoffset} field has a value greater than
+    zero.
+  \end{datadesc}
+
+  \begin{datadesc}{Py_TPFLAGS_HAVE_ITER}
+    If this bit is set, the type object has the \member{tp_iter} and
+    \member{tp_iternext} fields.
+  \end{datadesc}
+
+  \begin{datadesc}{Py_TPFLAGS_HAVE_CLASS}
+    If this bit is set, the type object has several new fields defined
+    starting in Python 2.2: \member{tp_methods}, \member{tp_members},
+    \member{tp_getset}, \member{tp_base}, \member{tp_dict},
+    \member{tp_descr_get}, \member{tp_descr_set},
+    \member{tp_dictoffset}, \member{tp_init}, \member{tp_alloc},
+    \member{tp_new}, \member{tp_free}, \member{tp_is_gc},
+    \member{tp_bases}, \member{tp_mro}, \member{tp_cache},
+    \member{tp_subclasses}, and \member{tp_weaklist}.
+  \end{datadesc}
+
+  \begin{datadesc}{Py_TPFLAGS_HEAPTYPE}
+    This bit is set when the type object itself is allocated on the
+    heap.  In this case, the \member{ob_type} field of its instances
+    is considered a reference to the type, and the type object is
+    INCREF'ed when a new instance is created, and DECREF'ed when an
+    instance is destroyed (this does not apply to instances of
+    subtypes; only the type referenced by the instance's ob_type gets
+    INCREF'ed or DECREF'ed).
+  \end{datadesc}
+
+  \begin{datadesc}{Py_TPFLAGS_BASETYPE}
+    This bit is set when the type can be used as the base type of
+    another type.  If this bit is clear, the type cannot be subtyped
+    (similar to a "final" class in Java).
+  \end{datadesc}
+
+  \begin{datadesc}{Py_TPFLAGS_READY}
+    This bit is set when the type object has been fully initialized by
+    \cfunction{PyType_Ready()}.
+  \end{datadesc}
+
+  \begin{datadesc}{Py_TPFLAGS_READYING}
+    This bit is set while \cfunction{PyType_Ready()} is in the process
+    of initializing the type object.
+  \end{datadesc}
+
+  \begin{datadesc}{Py_TPFLAGS_HAVE_GC}
+    This bit is set when the object supports garbage collection.  If
+    this bit is set, instances must be created using
+    \cfunction{PyObject_GC_New()} and destroyed using
+    \cfunction{PyObject_GC_Del()}.  More information in section XXX
+    about garbage collection.  This bit also implies that the
+    GC-related fields \member{tp_traverse} and \member{tp_clear} are
+    present in the type object; but those fields also exist when
+    \constant{Py_TPFLAGS_HAVE_GC} is clear but
+    \constant{Py_TPFLAGS_HAVE_RICHCOMPARE} is set.
+  \end{datadesc}
+
+  \begin{datadesc}{Py_TPFLAGS_DEFAULT}
+    This is a bitmask of all the bits that pertain to the existence of
+    certain fields in the type object and its extension structures.
+    Currently, it includes the following bits:
+    \constant{Py_TPFLAGS_HAVE_GETCHARBUFFER},
+    \constant{Py_TPFLAGS_HAVE_SEQUENCE_IN},
+    \constant{Py_TPFLAGS_HAVE_INPLACEOPS},
+    \constant{Py_TPFLAGS_HAVE_RICHCOMPARE},
+    \constant{Py_TPFLAGS_HAVE_WEAKREFS},
+    \constant{Py_TPFLAGS_HAVE_ITER}, and
+    \constant{Py_TPFLAGS_HAVE_CLASS}.
+  \end{datadesc}
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{char*}{tp_doc}
+  An optional pointer to a NUL-terminated C string giving the
+  docstring for this type object.  This is exposed as the
+  \member{__doc__} attribute on the type and instances of the type.
+
+  This field is \emph{not} inherited by subtypes.
+\end{cmemberdesc}
+
+The following three fields only exist if the
+\constant{Py_TPFLAGS_HAVE_RICHCOMPARE} flag bit is set.
+
+\begin{cmemberdesc}{PyTypeObject}{traverseproc}{tp_traverse}
+  An optional pointer to a traversal function for the garbage
+  collector.  This is only used if the \constant{Py_TPFLAGS_HAVE_GC}
+  flag bit is set.  More information about Python's garbage collection
+  scheme can be found in section \ref{supporting-cycle-detection}.
+
+  The \member{tp_traverse} pointer is used by the garbage collector
+  to detect reference cycles. A typical implementation of a
+  \member{tp_traverse} function simply calls \cfunction{Py_VISIT()} on
+  each of the instance's members that are Python objects.  For exampe, this
+  is function \cfunction{local_traverse} from the \module{thread} extension
+  module:
+
+  \begin{verbatim}
+  static int
+  local_traverse(localobject *self, visitproc visit, void *arg)
+  {
+      Py_VISIT(self->args);
+      Py_VISIT(self->kw);
+      Py_VISIT(self->dict);
+      return 0;
+  }
+  \end{verbatim}
+
+  Note that \cfunction{Py_VISIT()} is called only on those members that can
+  participate in reference cycles.  Although there is also a
+  \samp{self->key} member, it can only be \NULL{} or a Python string and
+  therefore cannot be part of a reference cycle.
+
+  On the other hand, even if you know a member can never be part of a cycle,
+  as a debugging aid you may want to visit it anyway just so the
+  \module{gc} module's \function{get_referents()} function will include it.
+
+  Note that \cfunction{Py_VISIT()} requires the \var{visit} and \var{arg}
+  parameters to \cfunction{local_traverse} to have these specific names;
+  don't name them just anything.
+
+  This field is inherited by subtypes together with \member{tp_clear}
+  and the \constant{Py_TPFLAGS_HAVE_GC} flag bit: the flag bit,
+  \member{tp_traverse}, and \member{tp_clear} are all inherited from
+  the base type if they are all zero in the subtype \emph{and} the
+  subtype has the \constant{Py_TPFLAGS_HAVE_RICHCOMPARE} flag bit set.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{inquiry}{tp_clear}
+  An optional pointer to a clear function for the garbage collector.
+  This is only used if the \constant{Py_TPFLAGS_HAVE_GC} flag bit is
+  set.
+
+  The \member{tp_clear} member function is used to break reference
+  cycles in cyclic garbage detected by the garbage collector.  Taken
+  together, all \member{tp_clear} functions in the system must combine to
+  break all reference cycles.  This is subtle, and if in any doubt supply a
+  \member{tp_clear} function.  For example, the tuple type does not
+  implement a \member{tp_clear} function, because it's possible to prove
+  that no reference cycle can be composed entirely of tuples.  Therefore
+  the \member{tp_clear} functions of other types must be sufficient to
+  break any cycle containing a tuple.  This isn't immediately obvious, and
+  there's rarely a good reason to avoid implementing \member{tp_clear}.
+
+  Implementations of \member{tp_clear} should drop the instance's
+  references to those of its members that may be Python objects, and set
+  its pointers to those members to \NULL{}, as in the following example:
+
+  \begin{verbatim}
+  static int
+  local_clear(localobject *self)
+  {
+      Py_CLEAR(self->key);
+      Py_CLEAR(self->args);
+      Py_CLEAR(self->kw);
+      Py_CLEAR(self->dict);
+      return 0;
+  }
+  \end{verbatim}
+
+  The \cfunction{Py_CLEAR()} macro should be used, because clearing
+  references is delicate:  the reference to the contained object must not be
+  decremented until after the pointer to the contained object is set to
+  \NULL{}.  This is because decrementing the reference count may cause
+  the contained object to become trash, triggering a chain of reclamation
+  activity that may include invoking arbitrary Python code (due to
+  finalizers, or weakref callbacks, associated with the contained object).
+  If it's possible for such code to reference \var{self} again, it's
+  important that the pointer to the contained object be \NULL{} at that
+  time, so that \var{self} knows the contained object can no longer be
+  used.  The \cfunction{Py_CLEAR()} macro performs the operations in a
+  safe order.
+
+  Because the goal of \member{tp_clear} functions is to break reference
+  cycles, it's not necessary to clear contained objects like Python strings
+  or Python integers, which can't participate in reference cycles.
+  On the other hand, it may be convenient to clear all contained Python
+  objects, and write the type's \member{tp_dealloc} function to
+  invoke \member{tp_clear}.
+
+  More information about Python's garbage collection
+  scheme can be found in section \ref{supporting-cycle-detection}.
+
+  This field is inherited by subtypes together with \member{tp_traverse}
+  and the \constant{Py_TPFLAGS_HAVE_GC} flag bit: the flag bit,
+  \member{tp_traverse}, and \member{tp_clear} are all inherited from
+  the base type if they are all zero in the subtype \emph{and} the
+  subtype has the \constant{Py_TPFLAGS_HAVE_RICHCOMPARE} flag bit set.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{richcmpfunc}{tp_richcompare}
+  An optional pointer to the rich comparison function.
+
+  The signature is the same as for \cfunction{PyObject_RichCompare()}.
+  The function should return the result of the comparison (usually
+  \code{Py_True} or \code{Py_False}).  If the comparison is undefined,
+  it must return \code{Py_NotImplemented}, if another error occurred
+  it must return \code{NULL} and set an exception condition.
+
+  This field is inherited by subtypes together with
+  \member{tp_compare} and \member{tp_hash}: a subtype inherits all
+  three of \member{tp_compare}, \member{tp_richcompare}, and
+  \member{tp_hash}, when the subtype's \member{tp_compare},
+  \member{tp_richcompare}, and \member{tp_hash} are all \NULL.
+
+  The following constants are defined to be used as the third argument
+  for \member{tp_richcompare} and for \cfunction{PyObject_RichCompare()}:
+
+  \begin{tableii}{l|c}{constant}{Constant}{Comparison}
+    \lineii{Py_LT}{\code{<}}
+    \lineii{Py_LE}{\code{<=}}
+    \lineii{Py_EQ}{\code{==}}
+    \lineii{Py_NE}{\code{!=}}
+    \lineii{Py_GT}{\code{>}}
+    \lineii{Py_GE}{\code{>=}}
+  \end{tableii}
+\end{cmemberdesc}
+
+The next field only exists if the \constant{Py_TPFLAGS_HAVE_WEAKREFS}
+flag bit is set.
+
+\begin{cmemberdesc}{PyTypeObject}{long}{tp_weaklistoffset}
+  If the instances of this type are weakly referenceable, this field
+  is greater than zero and contains the offset in the instance
+  structure of the weak reference list head (ignoring the GC header,
+  if present); this offset is used by
+  \cfunction{PyObject_ClearWeakRefs()} and the
+  \cfunction{PyWeakref_*()} functions.  The instance structure needs
+  to include a field of type \ctype{PyObject*} which is initialized to
+  \NULL.
+
+  Do not confuse this field with \member{tp_weaklist}; that is the
+  list head for weak references to the type object itself.
+
+  This field is inherited by subtypes, but see the rules listed below.
+  A subtype may override this offset; this means that the subtype uses
+  a different weak reference list head than the base type.  Since the
+  list head is always found via \member{tp_weaklistoffset}, this
+  should not be a problem.
+
+  When a type defined by a class statement has no \member{__slots__}
+  declaration, and none of its base types are weakly referenceable,
+  the type is made weakly referenceable by adding a weak reference
+  list head slot to the instance layout and setting the
+  \member{tp_weaklistoffset} of that slot's offset.
+
+  When a type's \member{__slots__} declaration contains a slot named
+  \member{__weakref__}, that slot becomes the weak reference list head
+  for instances of the type, and the slot's offset is stored in the
+  type's \member{tp_weaklistoffset}.
+
+  When a type's \member{__slots__} declaration does not contain a slot
+  named \member{__weakref__}, the type inherits its
+  \member{tp_weaklistoffset} from its base type.
+\end{cmemberdesc}
+
+The next two fields only exist if the
+\constant{Py_TPFLAGS_HAVE_CLASS} flag bit is set.
+
+\begin{cmemberdesc}{PyTypeObject}{getiterfunc}{tp_iter}
+  An optional pointer to a function that returns an iterator for the
+  object.  Its presence normally signals that the instances of this
+  type are iterable (although sequences may be iterable without this
+  function, and classic instances always have this function, even if
+  they don't define an \method{__iter__()} method).
+
+  This function has the same signature as
+  \cfunction{PyObject_GetIter()}.
+
+  This field is inherited by subtypes.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{iternextfunc}{tp_iternext}
+  An optional pointer to a function that returns the next item in an
+  iterator, or raises \exception{StopIteration} when the iterator is
+  exhausted.  Its presence normally signals that the instances of this
+  type are iterators (although classic instances always have this
+  function, even if they don't define a \method{next()} method).
+
+  Iterator types should also define the \member{tp_iter} function, and
+  that function should return the iterator instance itself (not a new
+  iterator instance).
+
+  This function has the same signature as \cfunction{PyIter_Next()}.
+
+  This field is inherited by subtypes.
+\end{cmemberdesc}
+
+The next fields, up to and including \member{tp_weaklist}, only exist
+if the \constant{Py_TPFLAGS_HAVE_CLASS} flag bit is set.
+
+\begin{cmemberdesc}{PyTypeObject}{struct PyMethodDef*}{tp_methods}
+  An optional pointer to a static \NULL-terminated array of
+  \ctype{PyMethodDef} structures, declaring regular methods of this
+  type.
+
+  For each entry in the array, an entry is added to the type's
+  dictionary (see \member{tp_dict} below) containing a method
+  descriptor.
+
+  This field is not inherited by subtypes (methods are
+  inherited through a different mechanism).
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{struct PyMemberDef*}{tp_members}
+  An optional pointer to a static \NULL-terminated array of
+  \ctype{PyMemberDef} structures, declaring regular data members
+  (fields or slots) of instances of this type.
+
+  For each entry in the array, an entry is added to the type's
+  dictionary (see \member{tp_dict} below) containing a member
+  descriptor.
+
+  This field is not inherited by subtypes (members are inherited
+  through a different mechanism).
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{struct PyGetSetDef*}{tp_getset}
+  An optional pointer to a static \NULL-terminated array of
+  \ctype{PyGetSetDef} structures, declaring computed attributes of
+  instances of this type.
+
+  For each entry in the array, an entry is added to the type's
+  dictionary (see \member{tp_dict} below) containing a getset
+  descriptor.
+
+  This field is not inherited by subtypes (computed attributes are
+  inherited through a different mechanism).
+
+  Docs for PyGetSetDef (XXX belong elsewhere):
+
+\begin{verbatim}
+typedef PyObject *(*getter)(PyObject *, void *);
+typedef int (*setter)(PyObject *, PyObject *, void *);
+
+typedef struct PyGetSetDef {
+    char *name;    /* attribute name */
+    getter get;    /* C function to get the attribute */
+    setter set;    /* C function to set the attribute */
+    char *doc;     /* optional doc string */
+    void *closure; /* optional additional data for getter and setter */
+} PyGetSetDef;
+\end{verbatim}
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{PyTypeObject*}{tp_base}
+  An optional pointer to a base type from which type properties are
+  inherited.  At this level, only single inheritance is supported;
+  multiple inheritance require dynamically creating a type object by
+  calling the metatype.
+
+  This field is not inherited by subtypes (obviously), but it defaults
+  to \code{\&PyBaseObject_Type} (which to Python programmers is known
+  as the type \class{object}).
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{PyObject*}{tp_dict}
+  The type's dictionary is stored here by \cfunction{PyType_Ready()}.
+
+  This field should normally be initialized to \NULL{} before
+  PyType_Ready is called; it may also be initialized to a dictionary
+  containing initial attributes for the type.  Once
+  \cfunction{PyType_Ready()} has initialized the type, extra
+  attributes for the type may be added to this dictionary only if they
+  don't correspond to overloaded operations (like \method{__add__()}).
+
+  This field is not inherited by subtypes (though the attributes
+  defined in here are inherited through a different mechanism).
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{descrgetfunc}{tp_descr_get}
+  An optional pointer to a "descriptor get" function.
+
+
+  The function signature is
+
+\begin{verbatim}
+PyObject * tp_descr_get(PyObject *self, PyObject *obj, PyObject *type);
+\end{verbatim}
+
+  XXX blah, blah.
+
+  This field is inherited by subtypes.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{descrsetfunc}{tp_descr_set}
+  An optional pointer to a "descriptor set" function.
+
+  The function signature is
+
+\begin{verbatim}
+int tp_descr_set(PyObject *self, PyObject *obj, PyObject *value);
+\end{verbatim}
+
+  This field is inherited by subtypes.
+
+  XXX blah, blah.
+
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{long}{tp_dictoffset}
+  If the instances of this type have a dictionary containing instance
+  variables, this field is non-zero and contains the offset in the
+  instances of the type of the instance variable dictionary; this
+  offset is used by \cfunction{PyObject_GenericGetAttr()}.
+
+  Do not confuse this field with \member{tp_dict}; that is the
+  dictionary for attributes of the type object itself.
+
+  If the value of this field is greater than zero, it specifies the
+  offset from the start of the instance structure.  If the value is
+  less than zero, it specifies the offset from the \emph{end} of the
+  instance structure.  A negative offset is more expensive to use, and
+  should only be used when the instance structure contains a
+  variable-length part.  This is used for example to add an instance
+  variable dictionary to subtypes of \class{str} or \class{tuple}.
+  Note that the \member{tp_basicsize} field should account for the
+  dictionary added to the end in that case, even though the dictionary
+  is not included in the basic object layout.  On a system with a
+  pointer size of 4 bytes, \member{tp_dictoffset} should be set to
+  \code{-4} to indicate that the dictionary is at the very end of the
+  structure.
+
+  The real dictionary offset in an instance can be computed from a
+  negative \member{tp_dictoffset} as follows:
+
+\begin{verbatim}
+dictoffset = tp_basicsize + abs(ob_size)*tp_itemsize + tp_dictoffset
+if dictoffset is not aligned on sizeof(void*):
+    round up to sizeof(void*)
+\end{verbatim}
+
+  where \member{tp_basicsize}, \member{tp_itemsize} and
+  \member{tp_dictoffset} are taken from the type object, and
+  \member{ob_size} is taken from the instance.  The absolute value is
+  taken because long ints use the sign of \member{ob_size} to store
+  the sign of the number.  (There's never a need to do this
+  calculation yourself; it is done for you by
+  \cfunction{_PyObject_GetDictPtr()}.)
+
+  This field is inherited by subtypes, but see the rules listed below.
+  A subtype may override this offset; this means that the subtype
+  instances store the dictionary at a difference offset than the base
+  type.  Since the dictionary is always found via
+  \member{tp_dictoffset}, this should not be a problem.
+
+  When a type defined by a class statement has no \member{__slots__}
+  declaration, and none of its base types has an instance variable
+  dictionary, a dictionary slot is added to the instance layout and
+  the \member{tp_dictoffset} is set to that slot's offset.
+
+  When a type defined by a class statement has a \member{__slots__}
+  declaration, the type inherits its \member{tp_dictoffset} from its
+  base type.
+
+  (Adding a slot named \member{__dict__} to the \member{__slots__}
+  declaration does not have the expected effect, it just causes
+  confusion.  Maybe this should be added as a feature just like
+  \member{__weakref__} though.)
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{initproc}{tp_init}
+  An optional pointer to an instance initialization function.
+
+  This function corresponds to the \method{__init__()} method of
+  classes.  Like \method{__init__()}, it is possible to create an
+  instance without calling \method{__init__()}, and it is possible to
+  reinitialize an instance by calling its \method{__init__()} method
+  again.
+
+  The function signature is
+
+\begin{verbatim}
+int tp_init(PyObject *self, PyObject *args, PyObject *kwds)
+\end{verbatim}
+
+  The self argument is the instance to be initialized; the \var{args}
+  and \var{kwds} arguments represent positional and keyword arguments
+  of the call to \method{__init__()}.
+
+  The \member{tp_init} function, if not \NULL, is called when an
+  instance is created normally by calling its type, after the type's
+  \member{tp_new} function has returned an instance of the type.  If
+  the \member{tp_new} function returns an instance of some other type
+  that is not a subtype of the original type, no \member{tp_init}
+  function is called; if \member{tp_new} returns an instance of a
+  subtype of the original type, the subtype's \member{tp_init} is
+  called.  (VERSION NOTE: described here is what is implemented in
+  Python 2.2.1 and later.  In Python 2.2, the \member{tp_init} of the
+  type of the object returned by \member{tp_new} was always called, if
+  not \NULL.)
+
+  This field is inherited by subtypes.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{allocfunc}{tp_alloc}
+  An optional pointer to an instance allocation function.
+
+  The function signature is
+
+\begin{verbatim}
+PyObject *tp_alloc(PyTypeObject *self, Py_ssize_t nitems)
+\end{verbatim}
+
+  The purpose of this function is to separate memory allocation from
+  memory initialization.  It should return a pointer to a block of
+  memory of adequate length for the instance, suitably aligned, and
+  initialized to zeros, but with \member{ob_refcnt} set to \code{1}
+  and \member{ob_type} set to the type argument.  If the type's
+  \member{tp_itemsize} is non-zero, the object's \member{ob_size} field
+  should be initialized to \var{nitems} and the length of the
+  allocated memory block should be \code{tp_basicsize +
+  \var{nitems}*tp_itemsize}, rounded up to a multiple of
+  \code{sizeof(void*)}; otherwise, \var{nitems} is not used and the
+  length of the block should be \member{tp_basicsize}.
+
+  Do not use this function to do any other instance initialization,
+  not even to allocate additional memory; that should be done by
+  \member{tp_new}.
+
+  This field is inherited by static subtypes, but not by dynamic
+  subtypes (subtypes created by a class statement); in the latter,
+  this field is always set to \cfunction{PyType_GenericAlloc()}, to
+  force a standard heap allocation strategy.  That is also the
+  recommended value for statically defined types.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{newfunc}{tp_new}
+  An optional pointer to an instance creation function.
+
+  If this function is \NULL{} for a particular type, that type cannot
+  be called to create new instances; presumably there is some other
+  way to create instances, like a factory function.
+
+  The function signature is
+
+\begin{verbatim}
+PyObject *tp_new(PyTypeObject *subtype, PyObject *args, PyObject *kwds)
+\end{verbatim}
+
+  The subtype argument is the type of the object being created; the
+  \var{args} and \var{kwds} arguments represent positional and keyword
+  arguments of the call to the type.  Note that subtype doesn't have
+  to equal the type whose \member{tp_new} function is called; it may
+  be a subtype of that type (but not an unrelated type).
+
+  The \member{tp_new} function should call
+  \code{\var{subtype}->tp_alloc(\var{subtype}, \var{nitems})} to
+  allocate space for the object, and then do only as much further
+  initialization as is absolutely necessary.  Initialization that can
+  safely be ignored or repeated should be placed in the
+  \member{tp_init} handler.  A good rule of thumb is that for
+  immutable types, all initialization should take place in
+  \member{tp_new}, while for mutable types, most initialization should
+  be deferred to \member{tp_init}.
+
+  This field is inherited by subtypes, except it is not inherited by
+  static types whose \member{tp_base} is \NULL{} or
+  \code{\&PyBaseObject_Type}.  The latter exception is a precaution so
+  that old extension types don't become callable simply by being
+  linked with Python 2.2.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{destructor}{tp_free}
+  An optional pointer to an instance deallocation function.
+
+  The signature of this function has changed slightly: in Python
+  2.2 and 2.2.1, its signature is \ctype{destructor}:
+
+\begin{verbatim}
+void tp_free(PyObject *)
+\end{verbatim}
+
+  In Python 2.3 and beyond, its signature is \ctype{freefunc}:
+
+\begin{verbatim}
+void tp_free(void *)
+\end{verbatim}
+
+  The only initializer that is compatible with both versions is
+  \code{_PyObject_Del}, whose definition has suitably adapted in
+  Python 2.3.
+
+  This field is inherited by static subtypes, but not by dynamic
+  subtypes (subtypes created by a class statement); in the latter,
+  this field is set to a deallocator suitable to match
+  \cfunction{PyType_GenericAlloc()} and the value of the
+  \constant{Py_TPFLAGS_HAVE_GC} flag bit.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{inquiry}{tp_is_gc}
+  An optional pointer to a function called by the garbage collector.
+
+  The garbage collector needs to know whether a particular object is
+  collectible or not.  Normally, it is sufficient to look at the
+  object's type's \member{tp_flags} field, and check the
+  \constant{Py_TPFLAGS_HAVE_GC} flag bit.  But some types have a
+  mixture of statically and dynamically allocated instances, and the
+  statically allocated instances are not collectible.  Such types
+  should define this function; it should return \code{1} for a
+  collectible instance, and \code{0} for a non-collectible instance.
+  The signature is
+
+\begin{verbatim}
+int tp_is_gc(PyObject *self)
+\end{verbatim}
+
+  (The only example of this are types themselves.  The metatype,
+  \cdata{PyType_Type}, defines this function to distinguish between
+  statically and dynamically allocated types.)
+
+  This field is inherited by subtypes.  (VERSION NOTE: in Python
+  2.2, it was not inherited.  It is inherited in 2.2.1 and later
+  versions.)
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{PyObject*}{tp_bases}
+  Tuple of base types.
+
+  This is set for types created by a class statement.  It should be
+  \NULL{} for statically defined types.
+
+  This field is not inherited.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{PyObject*}{tp_mro}
+  Tuple containing the expanded set of base types, starting with the
+  type itself and ending with \class{object}, in Method Resolution
+  Order.
+
+  This field is not inherited; it is calculated fresh by
+  \cfunction{PyType_Ready()}.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{PyObject*}{tp_cache}
+  Unused.  Not inherited.  Internal use only.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{PyObject*}{tp_subclasses}
+  List of weak references to subclasses.  Not inherited.  Internal
+  use only.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{PyObject*}{tp_weaklist}
+  Weak reference list head, for weak references to this type
+  object.  Not inherited.  Internal use only.
+\end{cmemberdesc}
+
+The remaining fields are only defined if the feature test macro
+\constant{COUNT_ALLOCS} is defined, and are for internal use only.
+They are documented here for completeness.  None of these fields are
+inherited by subtypes.
+
+\begin{cmemberdesc}{PyTypeObject}{Py_ssize_t}{tp_allocs}
+  Number of allocations.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{Py_ssize_t}{tp_frees}
+  Number of frees.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{Py_ssize_t}{tp_maxalloc}
+  Maximum simultaneously allocated objects.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{PyTypeObject*}{tp_next}
+  Pointer to the next type object with a non-zero \member{tp_allocs}
+  field.
+\end{cmemberdesc}
+
+Also, note that, in a garbage collected Python, tp_dealloc may be
+called from any Python thread, not just the thread which created the
+object (if the object becomes part of a refcount cycle, that cycle
+might be collected by a garbage collection on any thread).  This is
+not a problem for Python API calls, since the thread on which
+tp_dealloc is called will own the Global Interpreter Lock (GIL).
+However, if the object being destroyed in turn destroys objects from
+some other C or \Cpp{} library, care should be taken to ensure that
+destroying those objects on the thread which called tp_dealloc will
+not violate any assumptions of the library.
+
+\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 the flag is present, \member{bf_getcharbuffer} 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]{Py_ssize_t (*readbufferproc)
+                            (PyObject *self, Py_ssize_t segment, void **ptrptr)}
+  Return a pointer to a readable segment of the buffer in
+  \code{*\var{ptrptr}}.  This function
+  is allowed to raise an exception, in which case it must return
+  \code{-1}.  The \var{segment} which is specified 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 segment, and sets \code{*\var{ptrptr}} to a
+  pointer to that memory.
+\end{ctypedesc}
+
+\begin{ctypedesc}[getwritebufferproc]{Py_ssize_t (*writebufferproc)
+                            (PyObject *self, Py_ssize_t 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]{Py_ssize_t (*segcountproc)
+                            (PyObject *self, Py_ssize_t *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]{Py_ssize_t (*charbufferproc)
+                            (PyObject *self, Py_ssize_t segment, const char **ptrptr)}
+  Return the size of the segment \var{segment} that \var{ptrptr} 
+  is set to.  \code{*\var{ptrptr}} is set to the memory buffer.
+  Returns \code{-1} on error.
+\end{ctypedesc}
+
+
+\section{Supporting the Iterator Protocol
+         \label{supporting-iteration}}
+
+
+\section{Supporting Cyclic Garbage 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.
+
+An example showing the use of these interfaces can be found in
+``\ulink{Supporting the Cycle
+Collector}{../ext/example-cycle-support.html}'' in
+\citetitle[../ext/ext.html]{Extending and Embedding the Python
+Interpreter}.
+
+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,
+                                                   Py_ssize_t 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, Py_ssize_t}
+  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}{void *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}{void *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}.  The Python core uses several visitor functions
+  to implement cyclic garbage detection; it's not expected that users will
+  need to write their own visitor functions.
+\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.  The \var{visit}
+  function must not be called with a \NULL{} object argument.  If
+  \var{visit} returns a non-zero value
+  that value should be returned immediately.
+\end{ctypedesc}
+
+To simplify writing \member{tp_traverse} handlers, a
+\cfunction{Py_VISIT()} macro is provided.  In order to use this macro,
+the \member{tp_traverse} implementation must name its arguments
+exactly \var{visit} and \var{arg}:
+
+\begin{cfuncdesc}{void}{Py_VISIT}{PyObject *o}
+  Call the \var{visit} callback, with arguments \var{o} and \var{arg}.
+  If \var{visit} returns a non-zero value, then return it.  Using this
+  macro, \member{tp_traverse} handlers look like:
+
+\begin{verbatim}
+static int
+my_traverse(Noddy *self, visitproc visit, void *arg)
+{
+    Py_VISIT(self->foo);
+    Py_VISIT(self->bar);
+    return 0;
+}
+\end{verbatim}
+
+\versionadded{2.4}
+\end{cfuncdesc}
+
+
+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}
diff --git a/sys/src/cmd/python/Doc/api/refcounting.tex b/sys/src/cmd/python/Doc/api/refcounting.tex
new file mode 100644
index 000000000..077543b85
--- /dev/null
+++ b/sys/src/cmd/python/Doc/api/refcounting.tex
@@ -0,0 +1,69 @@
+\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}
+
+\begin{cfuncdesc}{void}{Py_CLEAR}{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()}, except that the argument
+  is also set to \NULL.  The warning for \cfunction{Py_DECREF()} does
+  not apply with respect to the object passed because the macro
+  carefully uses a temporary variable and sets the argument to \NULL
+  before decrementing its reference count.
+
+  It is a good idea to use this macro whenever decrementing the value
+  of a variable that might be traversed during garbage collection.
+
+\versionadded{2.4}
+\end{cfuncdesc}
+
+
+The following functions are for runtime dynamic embedding of Python:
+\cfunction{Py_IncRef(PyObject *o)}, \cfunction{Py_DecRef(PyObject *o)}.
+They are simply exported function versions of \cfunction{Py_XINCREF()} and 
+\cfunction{Py_XDECREF()}, respectively.
+
+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/sys/src/cmd/python/Doc/api/refcounts.dat b/sys/src/cmd/python/Doc/api/refcounts.dat
new file mode 100644
index 000000000..b8aaad543
--- /dev/null
+++ b/sys/src/cmd/python/Doc/api/refcounts.dat
@@ -0,0 +1,1756 @@
+# Created by Skip Montanaro <skip@mojam.com>.
+
+# Format:
+#	function ':' type ':' [param name] ':' [refcount effect] ':' [comment]
+# If the param name slot is empty, that line corresponds to the function's
+# return value, otherwise it's the type of the named parameter.
+
+# The first line of a function block gives type/refcount information for the
+# function's return value.  Successive lines with the same function name
+# correspond to the function's parameter list and appear in the order the
+# parameters appear in the function's prototype.
+
+# For readability, each function's lines are surrounded by a blank line.
+# The blocks are sorted alphabetically by function name.
+
+# Refcount behavior is given for all PyObject* types: 0 (no change), +1
+# (increment) and -1 (decrement).  A blank refcount field indicates the
+# parameter or function value is not a PyObject* and is therefore not
+# subject to reference counting.  A special case for the value "null"
+# (without quotes) is used for functions which return a PyObject* type but
+# always return NULL.  This is used by some of the PyErr_*() functions, in
+# particular.
+
+# XXX NOTE: the 0/+1/-1 refcount information for arguments is
+# confusing!  Much more useful would be to indicate whether the
+# function "steals" a reference to the argument or not.  Take for
+# example PyList_SetItem(list, i, item).  This lists as a 0 change for
+# both the list and the item arguments.  However, in fact it steals a
+# reference to the item argument!
+
+# The parameter names are as they appear in the API manual, not the source
+# code. 
+
+PyBool_FromLong:PyObject*::+1:
+PyBool_FromLong:long:v:0:
+
+PyBuffer_FromObject:PyObject*::+1:
+PyBuffer_FromObject:PyObject*:base:+1:
+PyBuffer_FromObject:int:offset::
+PyBuffer_FromObject:int:size::
+
+PyBuffer_FromReadWriteObject:PyObject*::+1:
+PyBuffer_FromReadWriteObject:PyObject*:base:+1:
+PyBuffer_FromReadWriteObject:int:offset::
+PyBuffer_FromReadWriteObject:int:size::
+
+PyBuffer_FromMemory:PyObject*::+1:
+PyBuffer_FromMemory:void*:ptr::
+PyBuffer_FromMemory:int:size::
+
+PyBuffer_FromReadWriteMemory:PyObject*::+1:
+PyBuffer_FromReadWriteMemory:void*:ptr::
+PyBuffer_FromReadWriteMemory:int:size::
+
+PyBuffer_New:PyObject*::+1:
+PyBuffer_New:int:size::
+
+PyCObject_AsVoidPtr:void*:::
+PyCObject_AsVoidPtr:PyObject*:self:0:
+
+PyCObject_FromVoidPtr:PyObject*::+1:
+PyCObject_FromVoidPtr:void*:cobj::
+PyCObject_FromVoidPtr::void (* destr)(void* )::
+
+PyCObject_FromVoidPtrAndDesc:PyObject*::+1:
+PyCObject_FromVoidPtrAndDesc:void*:cobj::
+PyCObject_FromVoidPtrAndDesc:void*:desc::
+PyCObject_FromVoidPtrAndDesc:void(*)(void*,void*):destr::
+
+PyCObject_GetDesc:void*:::
+PyCObject_GetDesc:PyObject*:self:0:
+
+PyCell_New:PyObject*::+1:
+PyCell_New:PyObject*:ob:0:
+
+PyCell_GET:PyObject*::0:
+PyCell_GET:PyObject*:ob:0:
+
+PyCell_Get:PyObject*::+1:
+PyCell_Get:PyObject*:cell:0:
+
+PyCell_SET:void:::
+PyCell_SET:PyObject*:cell:0:
+PyCell_SET:PyObject*:value:0:
+
+PyCell_Set:int:::
+PyCell_Set:PyObject*:cell:0:
+PyCell_Set:PyObject*:value:0:
+
+PyCallIter_New:PyObject*::+1:
+PyCallIter_New:PyObject*:callable::
+PyCallIter_New:PyObject*:sentinel::
+
+PyCallable_Check:int:::
+PyCallable_Check:PyObject*:o:0:
+
+PyComplex_AsCComplex:Py_complex:::
+PyComplex_AsCComplex:PyObject*:op:0:
+
+PyComplex_Check:int:::
+PyComplex_Check:PyObject*:p:0:
+
+PyComplex_FromCComplex:PyObject*::+1:
+PyComplex_FromCComplex::Py_complex v::
+
+PyComplex_FromDoubles:PyObject*::+1:
+PyComplex_FromDoubles::double real::
+PyComplex_FromDoubles::double imag::
+
+PyComplex_ImagAsDouble:double:::
+PyComplex_ImagAsDouble:PyObject*:op:0:
+
+PyComplex_RealAsDouble:double:::
+PyComplex_RealAsDouble:PyObject*:op:0:
+
+PyDate_FromDate:PyObject*::+1:
+PyDate_FromDate:int:year::
+PyDate_FromDate:int:month::
+PyDate_FromDate:int:day::
+
+PyDate_FromTimestamp:PyObject*::+1:
+PyDate_FromTimestamp:PyObject*:args:0:
+
+PyDateTime_FromDateAndTime:PyObject*::+1:
+PyDateTime_FromDateAndTime:int:year::
+PyDateTime_FromDateAndTime:int:month::
+PyDateTime_FromDateAndTime:int:day::
+PyDateTime_FromDateAndTime:int:hour::
+PyDateTime_FromDateAndTime:int:minute::
+PyDateTime_FromDateAndTime:int:second::
+PyDateTime_FromDateAndTime:int:usecond::
+
+PyDateTime_FromTimestamp:PyObject*::+1:
+PyDateTime_FromTimestamp:PyObject*:args:0:
+
+PyDelta_FromDSU:PyObject*::+1:
+PyDelta_FromDSU:int:days::
+PyDelta_FromDSU:int:seconds::
+PyDelta_FromDSU:int:useconds::
+
+PyDescr_NewClassMethod:PyObject*::+1:
+PyDescr_NewClassMethod:PyTypeObject*:type::
+PyDescr_NewClassMethod:PyMethodDef*:method::
+
+PyDescr_NewGetSet:PyObject*::+1:
+PyDescr_NewGetSet:PyTypeObject*:type::
+PyDescr_NewGetSet:PyGetSetDef*:getset::
+
+PyDescr_NewMember:PyObject*::+1:
+PyDescr_NewMember:PyTypeObject*:type::
+PyDescr_NewMember:PyMemberDef*:member::
+
+PyDescr_NewMethod:PyObject*::+1:
+PyDescr_NewMethod:PyTypeObject*:type::
+PyDescr_NewMethod:PyMethodDef*:meth::
+
+PyDescr_NewWrapper:PyObject*::+1:
+PyDescr_NewWrapper:PyTypeObject*:type::
+PyDescr_NewWrapper:struct wrapperbase*:base::
+PyDescr_NewWrapper:void*:wrapped::
+
+PyDict_Check:int:::
+PyDict_Check:PyObject*:p:0:
+
+PyDict_Clear:void:::
+PyDict_Clear:PyObject*:p:0:
+
+PyDict_DelItem:int:::
+PyDict_DelItem:PyObject*:p:0:
+PyDict_DelItem:PyObject*:key:0:
+
+PyDict_DelItemString:int:::
+PyDict_DelItemString:PyObject*:p:0:
+PyDict_DelItemString:char*:key::
+
+PyDict_GetItem:PyObject*::0:0
+PyDict_GetItem:PyObject*:p:0:
+PyDict_GetItem:PyObject*:key:0:
+
+PyDict_GetItemString:PyObject*::0:
+PyDict_GetItemString:PyObject*:p:0:
+PyDict_GetItemString:char*:key::
+
+PyDict_Items:PyObject*::+1:
+PyDict_Items:PyObject*:p:0:
+
+PyDict_Keys:PyObject*::+1:
+PyDict_Keys:PyObject*:p:0:
+
+PyDict_New:PyObject*::+1:
+
+PyDict_Copy:PyObject*::+1:
+PyDict_Copy:PyObject*:p:0:
+
+PyDict_Next:int:::
+PyDict_Next:PyObject*:p:0:
+PyDict_Next:int:ppos::
+PyDict_Next:PyObject**:pkey:0:
+PyDict_Next:PyObject**:pvalue:0:
+
+PyDict_SetItem:int:::
+PyDict_SetItem:PyObject*:p:0:
+PyDict_SetItem:PyObject*:key:+1:
+PyDict_SetItem:PyObject*:val:+1:
+
+PyDict_SetItemString:int:::
+PyDict_SetItemString:PyObject*:p:0:
+PyDict_SetItemString:char*:key::
+PyDict_SetItemString:PyObject*:val:+1:
+
+PyDict_Size:int:::
+PyDict_Size:PyObject*:p::
+
+PyDict_Values:PyObject*::+1:
+PyDict_Values:PyObject*:p:0:
+
+PyDictProxy_New:PyObject*::+1:
+PyDictProxy_New:PyObject*:dict:0:
+
+PyErr_BadArgument:int:::
+
+PyErr_BadInternalCall:void:::
+
+PyErr_CheckSignals:int:::
+
+PyErr_Clear:void:::
+
+PyErr_ExceptionMatches:int:::
+PyErr_ExceptionMatches:PyObject*:exc:0:
+
+PyErr_Fetch:void:::
+PyErr_Fetch:PyObject**:ptype:0:
+PyErr_Fetch:PyObject**:pvalue:0:
+PyErr_Fetch:PyObject**:ptraceback:0:
+
+PyErr_GivenExceptionMatches:int:::
+PyErr_GivenExceptionMatches:PyObject*:given:0:
+PyErr_GivenExceptionMatches:PyObject*:exc:0:
+
+PyErr_NewException:PyObject*::+1:
+PyErr_NewException:char*:name::
+PyErr_NewException:PyObject*:base:0:
+PyErr_NewException:PyObject*:dict:0:
+
+PyErr_NoMemory:PyObject*::null:
+
+PyErr_NormalizeException:void:::
+PyErr_NormalizeException:PyObject**:exc::???
+PyErr_NormalizeException:PyObject**:val::???
+PyErr_NormalizeException:PyObject**:tb::???
+
+PyErr_Occurred:PyObject*::0:
+
+PyErr_Print:void:::
+
+PyErr_Restore:void:::
+PyErr_Restore:PyObject*:type:-1:
+PyErr_Restore:PyObject*:value:-1:
+PyErr_Restore:PyObject*:traceback:-1:
+
+PyErr_SetExcFromWindowsErr:PyObject*::null:
+PyErr_SetExcFromWindowsErr:PyObject*:type:0:
+PyErr_SetExcFromWindowsErr:int:ierr::
+
+PyErr_SetExcFromWindowsErrWithFilename:PyObject*::null:
+PyErr_SetExcFromWindowsErrWithFilename:PyObject*:type:0:
+PyErr_SetExcFromWindowsErrWithFilename:int:ierr::
+PyErr_SetExcFromWindowsErrWithFilename:char*:filename::
+
+PyErr_SetFromErrno:PyObject*::null:
+PyErr_SetFromErrno:PyObject*:type:0:
+
+PyErr_SetFromErrnoWithFilename:PyObject*::null:
+PyErr_SetFromErrnoWithFilename:PyObject*:type:0:
+PyErr_SetFromErrnoWithFilename:char*:filename::
+
+PyErr_SetFromWindowsErr:PyObject*::null:
+PyErr_SetFromWindowsErr:int:ierr::
+
+PyErr_SetFromWindowsErrWithFilename:PyObject*::null:
+PyErr_SetFromWindowsErrWithFilename:int:ierr::
+PyErr_SetFromWindowsErrWithFilename:char*:filename::
+
+PyErr_SetInterrupt:void:::
+
+PyErr_SetNone:void:::
+PyErr_SetNone:PyObject*:type:+1:
+
+PyErr_SetObject:void:::
+PyErr_SetObject:PyObject*:type:+1:
+PyErr_SetObject:PyObject*:value:+1:
+
+PyErr_SetString:void:::
+PyErr_SetString:PyObject*:type:+1:
+PyErr_SetString:char*:message::
+
+PyErr_Format:PyObject*::null:
+PyErr_Format:PyObject*:exception:+1:
+PyErr_Format:char*:format::
+PyErr_Format::...::
+
+PyErr_Warn:int:::
+PyErr_Warn:PyObject*:category:0:
+PyErr_Warn:char*:message::
+
+PyErr_WarnEx:int:::
+PyErr_WarnEx:PyObject*:category:0:
+PyErr_WarnEx:const char*:message::
+PyErr_WarnEx:Py_ssize_t:stack_level::
+
+PyEval_AcquireLock:void:::
+
+PyEval_AcquireThread:void:::
+PyEval_AcquireThread:PyThreadState*:tstate::
+
+PyEval_InitThreads:void:::
+
+PyEval_ReleaseLock:void:::
+
+PyEval_ReleaseThread:void:::
+PyEval_ReleaseThread:PyThreadState*:tstate::
+
+PyEval_RestoreThread:void:::
+PyEval_RestoreThread:PyThreadState*:tstate::
+
+PyEval_SaveThread:PyThreadState*:::
+
+PyEval_EvalCode:PyObject*::+1:
+PyEval_EvalCode:PyCodeObject*:co:0:
+PyEval_EvalCode:PyObject*:globals:0:
+PyEval_EvalCode:PyObject*:locals:0:
+
+PyFile_AsFile:FILE*:::
+PyFile_AsFile:PyFileObject*:p:0:
+
+PyFile_Check:int:::
+PyFile_Check:PyObject*:p:0:
+
+PyFile_FromFile:PyObject*::+1:
+PyFile_FromFile:FILE*:fp::
+PyFile_FromFile:char*:name::
+PyFile_FromFile:char*:mode::
+PyFile_FromFile:int(*:close)::
+
+PyFile_FromString:PyObject*::+1:
+PyFile_FromString:char*:name::
+PyFile_FromString:char*:mode::
+
+PyFile_GetLine:PyObject*::+1:
+PyFile_GetLine:PyObject*:p::
+PyFile_GetLine:int:n::
+
+PyFile_Name:PyObject*::0:
+PyFile_Name:PyObject*:p:0:
+
+PyFile_SetBufSize:void:::
+PyFile_SetBufSize:PyFileObject*:p:0:
+PyFile_SetBufSize:int:n::
+
+PyFile_SoftSpace:int:::
+PyFile_SoftSpace:PyFileObject*:p:0:
+PyFile_SoftSpace:int:newflag::
+
+PyFile_WriteObject:int:::
+PyFile_WriteObject:PyObject*:obj:0:
+PyFile_WriteObject:PyFileObject*:p:0:
+PyFile_WriteObject:int:flags::
+
+PyFile_WriteString:int:::
+PyFile_WriteString:const char*:s::
+PyFile_WriteString:PyFileObject*:p:0:
+PyFile_WriteString:int:flags::
+
+PyFloat_AS_DOUBLE:double:::
+PyFloat_AS_DOUBLE:PyObject*:pyfloat:0:
+
+PyFloat_AsDouble:double:::
+PyFloat_AsDouble:PyObject*:pyfloat:0:
+
+PyFloat_Check:int:::
+PyFloat_Check:PyObject*:p:0:
+
+PyFloat_FromDouble:PyObject*::+1:
+PyFloat_FromDouble:double:v::
+
+PyFloat_FromString:PyObject*::+1:
+PyFloat_FromString:PyObject*:str:0:
+PyFloat_FromString:char**:pend:0:ignored
+
+PyFrozenSet_New:PyObject*::+1:
+PyFrozenSet_New:PyObject*:iterable:0:
+
+PyFunction_GetClosure:PyObject*::0:
+PyFunction_GetClosure:PyObject*:op:0:
+
+PyFunction_GetCode:PyObject*::0:
+PyFunction_GetCode:PyObject*:op:0:
+
+PyFunction_GetDefaults:PyObject*::0:
+PyFunction_GetDefaults:PyObject*:op:0:
+
+PyFunction_GetGlobals:PyObject*::0:
+PyFunction_GetGlobals:PyObject*:op:0:
+
+PyFunction_GetModule:PyObject*::0:
+PyFunction_GetModule:PyObject*:op:0:
+
+PyFunction_New:PyObject*::+1:
+PyFunction_New:PyObject*:code:+1:
+PyFunction_New:PyObject*:globals:+1:
+
+PyFunction_SetClosure:int:::
+PyFunction_SetClosure:PyObject*:op:0:
+PyFunction_SetClosure:PyObject*:closure:+1:
+
+PyFunction_SetDefaults:int:::
+PyFunction_SetDefaults:PyObject*:op:0:
+PyFunction_SetDefaults:PyObject*:defaults:+1:
+
+PyGen_New:PyObject*::+1:
+PyGen_New:PyFrameObject*:frame:0:
+
+Py_InitModule:PyObject*::0:
+Py_InitModule:char*:name::
+Py_InitModule:PyMethodDef[]:methods::
+
+Py_InitModule3:PyObject*::0:
+Py_InitModule3:char*:name::
+Py_InitModule3:PyMethodDef[]:methods::
+Py_InitModule3:char*:doc::
+
+Py_InitModule4:PyObject*::0:
+Py_InitModule4:char*:name::
+Py_InitModule4:PyMethodDef[]:methods::
+Py_InitModule4:char*:doc::
+Py_InitModule4:PyObject*:self::
+Py_InitModule4:int:apiver::usually provided by Py_InitModule or Py_InitModule3
+
+PyImport_AddModule:PyObject*::0:reference borrowed from sys.modules
+PyImport_AddModule:char*:name::
+
+PyImport_Cleanup:void:::
+
+PyImport_ExecCodeModule:PyObject*::+1:
+PyImport_ExecCodeModule:char*:name::
+PyImport_ExecCodeModule:PyObject*:co:0:
+
+PyImport_GetMagicNumber:long:::
+
+PyImport_GetModuleDict:PyObject*::0:
+
+PyImport_Import:PyObject*::+1:
+PyImport_Import:PyObject*:name:0:
+
+PyImport_ImportFrozenModule:int:::
+PyImport_ImportFrozenModule:char*:::
+
+PyImport_ImportModule:PyObject*::+1:
+PyImport_ImportModule:char*:name::
+
+PyImport_ImportModuleEx:PyObject*::+1:
+PyImport_ImportModuleEx:char*:name::
+PyImport_ImportModuleEx:PyObject*:globals:0:???
+PyImport_ImportModuleEx:PyObject*:locals:0:???
+PyImport_ImportModuleEx:PyObject*:fromlist:0:???
+
+PyImport_ReloadModule:PyObject*::+1:
+PyImport_ReloadModule:PyObject*:m:0:
+
+PyInstance_New:PyObject*::+1:
+PyInstance_New:PyObject*:klass:+1:
+PyInstance_New:PyObject*:arg:0:
+PyInstance_New:PyObject*:kw:0:
+
+PyInstance_NewRaw:PyObject*::+1:
+PyInstance_NewRaw:PyObject*:klass:+1:
+PyInstance_NewRaw:PyObject*:dict:+1:
+
+PyInt_AS_LONG:long:::
+PyInt_AS_LONG:PyIntObject*:io:0:
+
+PyInt_AsLong:long:::
+PyInt_AsLong:PyObject*:io:0:
+
+PyInt_Check:int:::
+PyInt_Check:PyObject*:op:0:
+
+PyInt_FromLong:PyObject*::+1:
+PyInt_FromLong:long:ival::
+
+PyInt_FromString:PyObject*::+1:
+PyInt_FromString:char*:str:0:
+PyInt_FromString:char**:pend:0:
+PyInt_FromString:int:base:0:
+
+PyInt_FromSsize_t:PyObject*::+1:
+PyInt_FromSsize_t:Py_ssize_t:ival::
+
+PyInt_GetMax:long:::
+
+PyInterpreterState_Clear:void:::
+PyInterpreterState_Clear:PyInterpreterState*:interp::
+
+PyInterpreterState_Delete:void:::
+PyInterpreterState_Delete:PyInterpreterState*:interp::
+
+PyInterpreterState_New:PyInterpreterState*:::
+
+PyIter_Check:int:o:0:
+
+PyIter_Next:PyObject*::+1:
+PyIter_Next:PyObject*:o:0:
+
+PyList_Append:int:::
+PyList_Append:PyObject*:list:0:
+PyList_Append:PyObject*:item:+1:
+
+PyList_AsTuple:PyObject*::+1:
+PyList_AsTuple:PyObject*:list:0:
+
+PyList_Check:int:::
+PyList_Check:PyObject*:p:0:
+
+PyList_GET_ITEM:PyObject*::0:
+PyList_GET_ITEM:PyObject*:list:0:
+PyList_GET_ITEM:int:i:0:
+
+PyList_GET_SIZE:int:::
+PyList_GET_SIZE:PyObject*:list:0:
+
+PyList_GetItem:PyObject*::0:
+PyList_GetItem:PyObject*:list:0:
+PyList_GetItem:int:index::
+
+PyList_GetSlice:PyObject*::+1:
+PyList_GetSlice:PyObject*:list:0:
+PyList_GetSlice:int:low::
+PyList_GetSlice:int:high::
+
+PyList_Insert:int:::
+PyList_Insert:PyObject*:list:0:
+PyList_Insert:int:index::
+PyList_Insert:PyObject*:item:+1:
+
+PyList_New:PyObject*::+1:
+PyList_New:int:len::
+
+PyList_Reverse:int:::
+PyList_Reverse:PyObject*:list:0:
+
+PyList_SET_ITEM:void:::
+PyList_SET_ITEM:PyObject*:list:0:
+PyList_SET_ITEM:int:i::
+PyList_SET_ITEM:PyObject*:o:0:
+
+PyList_SetItem:int:::
+PyList_SetItem:PyObject*:list:0:
+PyList_SetItem:int:index::
+PyList_SetItem:PyObject*:item:0:
+
+PyList_SetSlice:int:::
+PyList_SetSlice:PyObject*:list:0:
+PyList_SetSlice:int:low::
+PyList_SetSlice:int:high::
+PyList_SetSlice:PyObject*:itemlist:0:but increfs its elements?
+
+PyList_Size:int:::
+PyList_Size:PyObject*:list:0:
+
+PyList_Sort:int:::
+PyList_Sort:PyObject*:list:0:
+
+PyLong_AsDouble:double:::
+PyLong_AsDouble:PyObject*:pylong:0:
+
+PyLong_AsLong:long:::
+PyLong_AsLong:PyObject*:pylong:0:
+
+PyLong_AsUnsignedLong:unsigned long:::
+PyLong_AsUnsignedLong:PyObject*:pylong:0:
+
+PyLong_Check:int:::
+PyLong_Check:PyObject*:p:0:
+
+PyLong_FromDouble:PyObject*::+1:
+PyLong_FromDouble:double:v::
+
+PyLong_FromLong:PyObject*::+1:
+PyLong_FromLong:long:v::
+
+PyLong_FromLongLong:PyObject*::+1:
+PyLong_FromLongLong:long long:v::
+
+PyLong_FromUnsignedLongLong:PyObject*::+1:
+PyLong_FromUnsignedLongLong:unsigned long long:v::
+
+PyLong_FromString:PyObject*::+1:
+PyLong_FromString:char*:str::
+PyLong_FromString:char**:pend::
+PyLong_FromString:int:base::
+
+PyLong_FromUnicode:PyObject*::+1:
+PyLong_FromUnicode:Py_UNICODE:u::
+PyLong_FromUnicode:int:length::
+PyLong_FromUnicode:int:base::
+
+PyLong_FromUnsignedLong:PyObject*::+1:
+PyLong_FromUnsignedLong:unsignedlong:v::
+
+PyLong_FromVoidPtr:PyObject*::+1:
+PyLong_FromVoidPtr:void*:p::
+
+PyMapping_Check:int:::
+PyMapping_Check:PyObject*:o:0:
+
+PyMapping_DelItem:int:::
+PyMapping_DelItem:PyObject*:o:0:
+PyMapping_DelItem:PyObject*:key:0:
+
+PyMapping_DelItemString:int:::
+PyMapping_DelItemString:PyObject*:o:0:
+PyMapping_DelItemString:char*:key::
+
+PyMapping_GetItemString:PyObject*::+1:
+PyMapping_GetItemString:PyObject*:o:0:
+PyMapping_GetItemString:char*:key::
+
+PyMapping_HasKey:int:::
+PyMapping_HasKey:PyObject*:o:0:
+PyMapping_HasKey:PyObject*:key::
+
+PyMapping_HasKeyString:int:::
+PyMapping_HasKeyString:PyObject*:o:0:
+PyMapping_HasKeyString:char*:key::
+
+PyMapping_Items:PyObject*::+1:
+PyMapping_Items:PyObject*:o:0:
+
+PyMapping_Keys:PyObject*::+1:
+PyMapping_Keys:PyObject*:o:0:
+
+PyMapping_Length:int:::
+PyMapping_Length:PyObject*:o:0:
+
+PyMapping_SetItemString:int:::
+PyMapping_SetItemString:PyObject*:o:0:
+PyMapping_SetItemString:char*:key::
+PyMapping_SetItemString:PyObject*:v:+1:
+
+PyMapping_Values:PyObject*::+1:
+PyMapping_Values:PyObject*:o:0:
+
+PyMarshal_ReadLastObjectFromFile:PyObject*::+1:
+PyMarshal_ReadLastObjectFromFile:FILE*:file::
+
+PyMarshal_ReadObjectFromFile:PyObject*::+1:
+PyMarshal_ReadObjectFromFile:FILE*:file::
+
+PyMarshal_ReadObjectFromString:PyObject*::+1:
+PyMarshal_ReadObjectFromString:char*:string::
+PyMarshal_ReadObjectFromString:int:len::
+
+PyMarshal_WriteObjectToString:PyObject*::+1:
+PyMarshal_WriteObjectToString:PyObject*:value:0:
+
+PyMethod_Class:PyObject*::0:
+PyMethod_Class:PyObject*:im:0:
+
+PyMethod_Function:PyObject*::0:
+PyMethod_Function:PyObject*:im:0:
+
+PyMethod_GET_CLASS:PyObject*::0:
+PyMethod_GET_CLASS:PyObject*:im:0:
+
+PyMethod_GET_FUNCTION:PyObject*::0:
+PyMethod_GET_FUNCTION:PyObject*:im:0:
+
+PyMethod_GET_SELF:PyObject*::0:
+PyMethod_GET_SELF:PyObject*:im:0:
+
+PyMethod_New:PyObject*::+1:
+PyMethod_New:PyObject*:func:0:
+PyMethod_New:PyObject*:self:0:
+PyMethod_New:PyObject*:class:0:
+
+PyMethod_Self:PyObject*::0:
+PyMethod_Self:PyObject*:im:0:
+
+PyModule_GetDict:PyObject*::0:
+PyModule_GetDict::PyObject* module:0:
+
+PyModule_GetFilename:char*:::
+PyModule_GetFilename:PyObject*:module:0:
+
+PyModule_GetName:char*:::
+PyModule_GetName:PyObject*:module:0:
+
+PyModule_New:PyObject*::+1:
+PyModule_New::char* name::
+
+PyNumber_Absolute:PyObject*::+1:
+PyNumber_Absolute:PyObject*:o:0:
+
+PyNumber_Add:PyObject*::+1:
+PyNumber_Add:PyObject*:o1:0:
+PyNumber_Add:PyObject*:o2:0:
+
+PyNumber_And:PyObject*::+1:
+PyNumber_And:PyObject*:o1:0:
+PyNumber_And:PyObject*:o2:0:
+
+PyNumber_Check:PyObject*:o:0:
+PyNumber_Check:int:::
+
+PyNumber_Coerce:int:::
+PyNumber_Coerce:PyObject**:p1:+1:
+PyNumber_Coerce:PyObject**:p2:+1:
+
+PyNumber_Divide:PyObject*::+1:
+PyNumber_Divide:PyObject*:o1:0:
+PyNumber_Divide:PyObject*:o2:0:
+
+PyNumber_Divmod:PyObject*::+1:
+PyNumber_Divmod:PyObject*:o1:0:
+PyNumber_Divmod:PyObject*:o2:0:
+
+PyNumber_Float:PyObject*::+1:
+PyNumber_Float:PyObject*:o:0:
+
+PyNumber_FloorDivide:PyObject*::+1:
+PyNumber_FloorDivide:PyObject*:v:0:
+PyNumber_FloorDivide:PyObject*:w:0:
+
+PyNumber_InPlaceAdd:PyObject*::+1:
+PyNumber_InPlaceAdd:PyObject*:v:0:
+PyNumber_InPlaceAdd:PyObject*:w:0:
+
+PyNumber_InPlaceAnd:PyObject*::+1:
+PyNumber_InPlaceAnd:PyObject*:v:0:
+PyNumber_InPlaceAnd:PyObject*:w:0:
+
+PyNumber_InPlaceDivide:PyObject*::+1:
+PyNumber_InPlaceDivide:PyObject*:v:0:
+PyNumber_InPlaceDivide:PyObject*:w:0:
+
+PyNumber_InPlaceFloorDivide:PyObject*::+1:
+PyNumber_InPlaceFloorDivide:PyObject*:v:0:
+PyNumber_InPlaceFloorDivide:PyObject*:w:0:
+
+PyNumber_InPlaceLshift:PyObject*::+1:
+PyNumber_InPlaceLshift:PyObject*:v:0:
+PyNumber_InPlaceLshift:PyObject*:w:0:
+
+PyNumber_InPlaceMultiply:PyObject*::+1:
+PyNumber_InPlaceMultiply:PyObject*:v:0:
+PyNumber_InPlaceMultiply:PyObject*:w:0:
+
+PyNumber_InPlaceOr:PyObject*::+1:
+PyNumber_InPlaceOr:PyObject*:v:0:
+PyNumber_InPlaceOr:PyObject*:w:0:
+
+PyNumber_InPlacePower:PyObject*::+1:
+PyNumber_InPlacePower:PyObject*:v:0:
+PyNumber_InPlacePower:PyObject*:w:0:
+PyNumber_InPlacePower:PyObject*:z:0:
+
+PyNumber_InPlaceRemainder:PyObject*::+1:
+PyNumber_InPlaceRemainder:PyObject*:v:0:
+PyNumber_InPlaceRemainder:PyObject*:w:0:
+
+PyNumber_InPlaceRshift:PyObject*::+1:
+PyNumber_InPlaceRshift:PyObject*:v:0:
+PyNumber_InPlaceRshift:PyObject*:w:0:
+
+PyNumber_InPlaceSubtract:PyObject*::+1:
+PyNumber_InPlaceSubtract:PyObject*:v:0:
+PyNumber_InPlaceSubtract:PyObject*:w:0:
+
+PyNumber_InPlaceTrueDivide:PyObject*::+1:
+PyNumber_InPlaceTrueDivide:PyObject*:v:0:
+PyNumber_InPlaceTrueDivide:PyObject*:w:0:
+
+PyNumber_InPlaceXor:PyObject*::+1:
+PyNumber_InPlaceXor:PyObject*:v:0:
+PyNumber_InPlaceXor:PyObject*:w:0:
+
+PyNumber_Int:PyObject*::+1:
+PyNumber_Int:PyObject*:o:0:
+
+PyNumber_Invert:PyObject*::+1:
+PyNumber_Invert:PyObject*:o:0:
+
+PyNumber_Long:PyObject*::+1:
+PyNumber_Long:PyObject*:o:0:
+
+PyNumber_Lshift:PyObject*::+1:
+PyNumber_Lshift:PyObject*:o1:0:
+PyNumber_Lshift:PyObject*:o2:0:
+
+PyNumber_Multiply:PyObject*::+1:
+PyNumber_Multiply:PyObject*:o1:0:
+PyNumber_Multiply:PyObject*:o2:0:
+
+PyNumber_Negative:PyObject*::+1:
+PyNumber_Negative:PyObject*:o:0:
+
+PyNumber_Or:PyObject*::+1:
+PyNumber_Or:PyObject*:o1:0:
+PyNumber_Or:PyObject*:o2:0:
+
+PyNumber_Positive:PyObject*::+1:
+PyNumber_Positive:PyObject*:o:0:
+
+PyNumber_Power:PyObject*::+1:
+PyNumber_Power:PyObject*:o1:0:
+PyNumber_Power:PyObject*:o2:0:
+PyNumber_Power:PyObject*:o3:0:
+
+PyNumber_Remainder:PyObject*::+1:
+PyNumber_Remainder:PyObject*:o1:0:
+PyNumber_Remainder:PyObject*:o2:0:
+
+PyNumber_Rshift:PyObject*::+1:
+PyNumber_Rshift:PyObject*:o1:0:
+PyNumber_Rshift:PyObject*:o2:0:
+
+PyNumber_Subtract:PyObject*::+1:
+PyNumber_Subtract:PyObject*:o1:0:
+PyNumber_Subtract:PyObject*:o2:0:
+
+PyNumber_TrueDivide:PyObject*::+1:
+PyNumber_TrueDivide:PyObject*:v:0:
+PyNumber_TrueDivide:PyObject*:w:0:
+
+PyNumber_Xor:PyObject*::+1:
+PyNumber_Xor:PyObject*:o1:0:
+PyNumber_Xor:PyObject*:o2:0:
+
+PyOS_GetLastModificationTime:long:::
+PyOS_GetLastModificationTime:char*:filename::
+
+PyObject_AsFileDescriptor:int::: 
+PyObject_AsFileDescriptor:PyObject*:o:0:
+
+PyObject_Call:PyObject*::+1:
+PyObject_Call:PyObject*:callable_object:0:
+PyObject_Call:PyObject*:args:0:
+PyObject_Call:PyObject*:kw:0:
+
+PyObject_CallFunction:PyObject*::+1:
+PyObject_CallFunction:PyObject*:callable_object:0:
+PyObject_CallFunction:char*:format::
+PyObject_CallFunction::...::
+
+PyObject_CallFunctionObjArgs:PyObject*::+1:
+PyObject_CallFunctionObjArgs:PyObject*:callable:0:
+PyObject_CallFunctionObjArgs::...::
+
+PyObject_CallMethod:PyObject*::+1:
+PyObject_CallMethod:PyObject*:o:0:
+PyObject_CallMethod:char*:m::
+PyObject_CallMethod:char*:format::
+PyObject_CallMethod::...::
+
+PyObject_CallMethodObjArgs:PyObject*::+1:
+PyObject_CallMethodObjArgs:PyObject*:o:0:
+PyObject_CallMethodObjArgs:char*:name::
+PyObject_CallMethodObjArgs::...::
+
+PyObject_CallObject:PyObject*::+1:
+PyObject_CallObject:PyObject*:callable_object:0:
+PyObject_CallObject:PyObject*:args:0:
+
+PyObject_Cmp:int:::
+PyObject_Cmp:PyObject*:o1:0:
+PyObject_Cmp:PyObject*:o2:0:
+PyObject_Cmp:int*:result::
+
+PyObject_Compare:int:::
+PyObject_Compare:PyObject*:o1:0:
+PyObject_Compare:PyObject*:o2:0:
+
+PyObject_DelAttr:int:::
+PyObject_DelAttr:PyObject*:o:0:
+PyObject_DelAttr:PyObject*:attr_name:0:
+
+PyObject_DelAttrString:int:::
+PyObject_DelAttrString:PyObject*:o:0:
+PyObject_DelAttrString:char*:attr_name::
+
+PyObject_DelItem:int:::
+PyObject_DelItem:PyObject*:o:0:
+PyObject_DelItem:PyObject*:key:0:
+
+PyObject_Dir:PyObject*::+1:
+PyObject_Dir:PyObject*:o:0:
+
+PyObject_GetAttr:PyObject*::+1:
+PyObject_GetAttr:PyObject*:o:0:
+PyObject_GetAttr:PyObject*:attr_name:0:
+
+PyObject_GetAttrString:PyObject*::+1:
+PyObject_GetAttrString:PyObject*:o:0:
+PyObject_GetAttrString:char*:attr_name::
+
+PyObject_GetItem:PyObject*::+1:
+PyObject_GetItem:PyObject*:o:0:
+PyObject_GetItem:PyObject*:key:0:
+
+PyObject_GetIter:PyObject*::+1:
+PyObject_GetIter:PyObject*:o:0:
+
+PyObject_HasAttr:int:::
+PyObject_HasAttr:PyObject*:o:0:
+PyObject_HasAttr:PyObject*:attr_name:0:
+
+PyObject_HasAttrString:int:::
+PyObject_HasAttrString:PyObject*:o:0:
+PyObject_HasAttrString:char*:attr_name:0:
+
+PyObject_Hash:int:::
+PyObject_Hash:PyObject*:o:0:
+
+PyObject_IsTrue:int:::
+PyObject_IsTrue:PyObject*:o:0:
+
+PyObject_Init:PyObject*::0:
+PyObject_Init:PyObject*:op:0:
+
+PyObject_InitVar:PyVarObject*::0:
+PyObject_InitVar:PyVarObject*:op:0:
+
+PyObject_Length:int:::
+PyObject_Length:PyObject*:o:0:
+
+PyObject_NEW:PyObject*::+1:
+
+PyObject_New:PyObject*::+1:
+
+PyObject_NEW_VAR:PyObject*::+1:
+
+PyObject_NewVar:PyObject*::+1:
+
+PyObject_Print:int:::
+PyObject_Print:PyObject*:o:0:
+PyObject_Print:FILE*:fp::
+PyObject_Print:int:flags::
+
+PyObject_Repr:PyObject*::+1:
+PyObject_Repr:PyObject*:o:0:
+
+PyObject_RichCompare:PyObject*::+1:
+PyObject_RichCompare:PyObject*:o1:0:
+PyObject_RichCompare:PyObject*:o2:0:
+PyObject_RichCompare:int:opid::
+
+PyObject_RichCompareBool:int:::
+PyObject_RichCompareBool:PyObject*:o1:0:
+PyObject_RichCompareBool:PyObject*:o2:0:
+PyObject_RichCompareBool:int:opid::
+
+PyObject_SetAttr:int:::
+PyObject_SetAttr:PyObject*:o:0:
+PyObject_SetAttr:PyObject*:attr_name:0:
+PyObject_SetAttr:PyObject*:v:+1:
+
+PyObject_SetAttrString:int:::
+PyObject_SetAttrString:PyObject*:o:0:
+PyObject_SetAttrString:char*:attr_name::
+PyObject_SetAttrString:PyObject*:v:+1:
+
+PyObject_SetItem:int:::
+PyObject_SetItem:PyObject*:o:0:
+PyObject_SetItem:PyObject*:key:0:
+PyObject_SetItem:PyObject*:v:+1:
+
+PyObject_Str:PyObject*::+1:
+PyObject_Str:PyObject*:o:0:
+
+PyObject_Type:PyObject*::+1:
+PyObject_Type:PyObject*:o:0:
+
+PyObject_Unicode:PyObject*::+1:
+PyObject_Unicode:PyObject*:o:0:
+
+PyParser_SimpleParseFile:struct _node*:::
+PyParser_SimpleParseFile:FILE*:fp::
+PyParser_SimpleParseFile:char*:filename::
+PyParser_SimpleParseFile:int:start::
+
+PyParser_SimpleParseString:struct _node*:::
+PyParser_SimpleParseString:char*:str::
+PyParser_SimpleParseString:int:start::
+
+PyRun_AnyFile:int:::
+PyRun_AnyFile:FILE*:fp::
+PyRun_AnyFile:char*:filename::
+
+PyRun_File:PyObject*::+1:??? -- same as eval_code2()
+PyRun_File:FILE*:fp::
+PyRun_File:char*:filename::
+PyRun_File:int:start::
+PyRun_File:PyObject*:globals:0:
+PyRun_File:PyObject*:locals:0:
+
+PyRun_FileEx:PyObject*::+1:??? -- same as eval_code2()
+PyRun_FileEx:FILE*:fp::
+PyRun_FileEx:char*:filename::
+PyRun_FileEx:int:start::
+PyRun_FileEx:PyObject*:globals:0:
+PyRun_FileEx:PyObject*:locals:0:
+PyRun_FileEx:int:closeit::
+
+PyRun_FileFlags:PyObject*::+1:??? -- same as eval_code2()
+PyRun_FileFlags:FILE*:fp::
+PyRun_FileFlags:char*:filename::
+PyRun_FileFlags:int:start::
+PyRun_FileFlags:PyObject*:globals:0:
+PyRun_FileFlags:PyObject*:locals:0:
+PyRun_FileFlags:PyCompilerFlags*:flags::
+
+PyRun_FileExFlags:PyObject*::+1:??? -- same as eval_code2()
+PyRun_FileExFlags:FILE*:fp::
+PyRun_FileExFlags:char*:filename::
+PyRun_FileExFlags:int:start::
+PyRun_FileExFlags:PyObject*:globals:0:
+PyRun_FileExFlags:PyObject*:locals:0:
+PyRun_FileExFlags:int:closeit::
+PyRun_FileExFlags:PyCompilerFlags*:flags::
+
+PyRun_InteractiveLoop:int:::
+PyRun_InteractiveLoop:FILE*:fp::
+PyRun_InteractiveLoop:char*:filename::
+
+PyRun_InteractiveOne:int:::
+PyRun_InteractiveOne:FILE*:fp::
+PyRun_InteractiveOne:char*:filename::
+
+PyRun_SimpleFile:int:::
+PyRun_SimpleFile:FILE*:fp::
+PyRun_SimpleFile:char*:filename::
+
+PyRun_SimpleString:int:::
+PyRun_SimpleString:char*:command::
+
+PyRun_String:PyObject*::+1:??? -- same as eval_code2()
+PyRun_String:char*:str::
+PyRun_String:int:start::
+PyRun_String:PyObject*:globals:0:
+PyRun_String:PyObject*:locals:0:
+
+PyRun_StringFlags:PyObject*::+1:??? -- same as eval_code2()
+PyRun_StringFlags:char*:str::
+PyRun_StringFlags:int:start::
+PyRun_StringFlags:PyObject*:globals:0:
+PyRun_StringFlags:PyObject*:locals:0:
+PyRun_StringFlags:PyCompilerFlags*:flags::
+
+PySeqIter_New:PyObject*::+1:
+PySeqIter_New:PyObject*:seq::
+
+PySequence_Check:int:::
+PySequence_Check:PyObject*:o:0:
+
+PySequence_Concat:PyObject*::+1:
+PySequence_Concat:PyObject*:o1:0:
+PySequence_Concat:PyObject*:o2:0:
+
+PySequence_Count:int:::
+PySequence_Count:PyObject*:o:0:
+PySequence_Count:PyObject*:value:0:
+
+PySequence_DelItem:int:::
+PySequence_DelItem:PyObject*:o:0:
+PySequence_DelItem:int:i::
+
+PySequence_DelSlice:int:::
+PySequence_DelSlice:PyObject*:o:0:
+PySequence_DelSlice:int:i1::
+PySequence_DelSlice:int:i2::
+
+PySequence_Fast:PyObject*::+1:
+PySequence_Fast:PyObject*:v:0:
+PySequence_Fast:const char*:m::
+
+PySequence_Fast_GET_ITEM:PyObject*::0:
+PySequence_Fast_GET_ITEM:PyObject*:o:0:
+PySequence_Fast_GET_ITEM:int:i::
+
+PySequence_GetItem:PyObject*::+1:
+PySequence_GetItem:PyObject*:o:0:
+PySequence_GetItem:int:i::
+
+PySequence_GetSlice:PyObject*::+1:
+PySequence_GetSlice:PyObject*:o:0:
+PySequence_GetSlice:int:i1::
+PySequence_GetSlice:int:i2::
+
+PySequence_In:int:::
+PySequence_In:PyObject*:o:0:
+PySequence_In:PyObject*:value:0:
+
+PySequence_Index:int:::
+PySequence_Index:PyObject*:o:0:
+PySequence_Index:PyObject*:value:0:
+
+PySequence_InPlaceConcat:PyObject*::+1:
+PySequence_InPlaceConcat:PyObject*:s:0:
+PySequence_InPlaceConcat:PyObject*:o:0:
+
+PySequence_InPlaceRepeat:PyObject*::+1:
+PySequence_InPlaceRepeat:PyObject*:s:0:
+PySequence_InPlaceRepeat:PyObject*:o:0:
+
+PySequence_ITEM:PyObject*::+1:
+PySequence_ITEM:PyObject*:o:0:
+PySequence_ITEM:int:i::
+
+PySequence_Repeat:PyObject*::+1:
+PySequence_Repeat:PyObject*:o:0:
+PySequence_Repeat:int:count::
+
+PySequence_SetItem:int:::
+PySequence_SetItem:PyObject*:o:0:
+PySequence_SetItem:int:i::
+PySequence_SetItem:PyObject*:v:+1:
+
+PySequence_SetSlice:int:::
+PySequence_SetSlice:PyObject*:o:0:
+PySequence_SetSlice:int:i1::
+PySequence_SetSlice:int:i2::
+PySequence_SetSlice:PyObject*:v:+1:
+
+PySequence_List:PyObject*::+1:
+PySequence_List:PyObject*:o:0:
+
+PySequence_Tuple:PyObject*::+1:
+PySequence_Tuple:PyObject*:o:0:
+
+PySet_Append:int:::
+PySet_Append:PyObject*:set:0:
+PySet_Append:PyObject*:key:+1:
+
+PySet_Contains:int:::
+PySet_Contains:PyObject*:anyset:0:
+PySet_Contains:PyObject*:key:0:
+
+PySet_Discard:int:::
+PySet_Discard:PyObject*:set:0:
+PySet_Discard:PyObject*:key:-1:no effect if key not found
+
+PySet_New:PyObject*::+1:
+PySet_New:PyObject*:iterable:0:
+
+PySet_Pop:PyObject*::+1:or returns NULL and raises KeyError if set is empty
+PySet_Pop:PyObject*:set:0:
+
+PySet_Size:int:::
+PySet_Size:PyObject*:anyset:0:
+
+PySlice_Check:int:::
+PySlice_Check:PyObject*:ob:0:
+
+PySlice_New:PyObject*::+1:
+PySlice_New:PyObject*:start:0:
+PySlice_New:PyObject*:stop:0:
+PySlice_New:PyObject*:step:0:
+
+PyString_AS_STRING:char*:::
+PyString_AS_STRING:PyObject*:string:0:
+
+PyString_AsDecodedObject:PyObject*::+1:
+PyString_AsDecodedObject:PyObject*:str:0:
+PyString_AsDecodedObject:const char*:encoding::
+PyString_AsDecodedObject:const char*:errors::
+
+PyString_AsEncodedObject:PyObject*::+1:
+PyString_AsEncodedObject:PyObject*:str:0:
+PyString_AsEncodedObject:const char*:encoding::
+PyString_AsEncodedObject:const char*:errors::
+
+PyString_AsString:char*:::
+PyString_AsString:PyObject*:string:0:
+
+PyString_AsStringAndSize:int:::
+PyString_AsStringAndSize:PyObject*:obj:0:
+PyString_AsStringAndSize:char**:buffer::
+PyString_AsStringAndSize:int*:length::
+
+PyString_Check:int:::
+PyString_Check:PyObject*:o:0:
+
+PyString_Concat:void:::
+PyString_Concat:PyObject**:string:0:??? -- replaces w/ new string or NULL
+PyString_Concat:PyObject*:newpart:0:
+
+PyString_ConcatAndDel:void:::
+PyString_ConcatAndDel:PyObject**:string:0:??? -- replaces w/ new string or NULL
+PyString_ConcatAndDel:PyObject*:newpart:-1:
+
+PyString_Format:PyObject*::+1:
+PyString_Format:PyObject*:format:0:
+PyString_Format:PyObject*:args:0:
+
+PyString_FromString:PyObject*::+1:
+PyString_FromString:const char*:v::
+
+PyString_FromStringAndSize:PyObject*::+1:
+PyString_FromStringAndSize:const char*:v::
+PyString_FromStringAndSize:int:len::
+
+PyString_FromFormat:PyObject*::+1:
+PyString_FromFormat:const char*:format::
+PyString_FromFormat::...::
+
+PyString_FromFormatV:PyObject*::+1:
+PyString_FromFormatV:const char*:format::
+PyString_FromFormatV:va_list:vargs::
+
+PyString_GET_SIZE:int:::
+PyString_GET_SIZE:PyObject*:string:0:
+
+PyString_InternFromString:PyObject*::+1:
+PyString_InternFromString:const char*:v::
+
+PyString_InternInPlace:void:::
+PyString_InternInPlace:PyObject**:string:+1:???
+
+PyString_Size:int:::
+PyString_Size:PyObject*:string:0:
+
+PyString_Decode:PyObject*::+1:
+PyString_Decode:const char*:s::
+PyString_Decode:int:size::
+PyString_Decode:const char*:encoding::
+PyString_Decode:const char*:errors::
+
+PyString_Encode:PyObject*::+1:
+PyString_Encode:const char*:s::
+PyString_Encode:int:size::
+PyString_Encode:const char*:encoding::
+PyString_Encode:const char*:errors::
+
+PyString_AsEncodedString:PyObject*::+1:
+PyString_AsEncodedString:PyObject*:str::
+PyString_AsEncodedString:const char*:encoding::
+PyString_AsEncodedString:const char*:errors::
+
+PySys_SetArgv:int:::
+PySys_SetArgv:int:argc::
+PySys_SetArgv:char**:argv::
+
+PyThreadState_Clear:void:::
+PyThreadState_Clear:PyThreadState*:tstate::
+
+PyThreadState_Delete:void:::
+PyThreadState_Delete:PyThreadState*:tstate::
+
+PyThreadState_Get:PyThreadState*:::
+
+PyThreadState_GetDict:PyObject*::0:
+
+PyThreadState_New:PyThreadState*:::
+PyThreadState_New:PyInterpreterState*:interp::
+
+PyThreadState_Swap:PyThreadState*:::
+PyThreadState_Swap:PyThreadState*:tstate::
+
+PyTime_FromTime:PyObject*::+1:
+PyTime_FromTime:int:hour::
+PyTime_FromTime:int:minute::
+PyTime_FromTime:int:second::
+PyTime_FromTime:int:usecond::
+
+PyTuple_Check:int:::
+PyTuple_Check:PyObject*:p:0:
+
+PyTuple_GET_ITEM:PyObject*::0:
+PyTuple_GET_ITEM:PyTupleObject*:p:0:
+PyTuple_GET_ITEM:int:pos::
+
+PyTuple_GetItem:PyObject*::0:
+PyTuple_GetItem:PyTupleObject*:p:0:
+PyTuple_GetItem:int:pos::
+
+PyTuple_GetSlice:PyObject*::+1:
+PyTuple_GetSlice:PyTupleObject*:p:0:
+PyTuple_GetSlice:int:low::
+PyTuple_GetSlice:int:high::
+
+PyTuple_New:PyObject*::+1:
+PyTuple_New:int:len::
+
+PyTuple_Pack:PyObject*::+1:
+PyTuple_Pack:int:len::
+PyTuple_Pack:PyObject*:...:0:
+
+PyTuple_SET_ITEM:void:::
+PyTuple_SET_ITEM:PyTupleObject*:p:0:
+PyTuple_SET_ITEM:int:pos::
+PyTuple_SET_ITEM:PyObject*:o:0:
+
+PyTuple_SetItem:int:::
+PyTuple_SetItem:PyTupleObject*:p:0:
+PyTuple_SetItem:int:pos::
+PyTuple_SetItem:PyObject*:o:0:
+
+PyTuple_Size:int:::
+PyTuple_Size:PyTupleObject*:p:0:
+
+PyType_GenericAlloc:PyObject*::+1:
+PyType_GenericAlloc:PyObject*:type:0:
+PyType_GenericAlloc:int:nitems:0:
+
+PyType_GenericNew:PyObject*::+1:
+PyType_GenericNew:PyObject*:type:0:
+PyType_GenericNew:PyObject*:args:0:
+PyType_GenericNew:PyObject*:kwds:0:
+
+PyUnicode_Check:int:::
+PyUnicode_Check:PyObject*:o:0:
+
+PyUnicode_GET_SIZE:int:::
+PyUnicode_GET_SIZE:PyObject*:o:0:
+
+PyUnicode_GET_DATA_SIZE:int:::
+PyUnicode_GET_DATA_SIZE:PyObject*:o:0:
+
+PyUnicode_AS_UNICODE:Py_UNICODE*:::
+PyUnicode_AS_UNICODE:PyObject*:o:0:
+
+PyUnicode_AS_DATA:const char*:::
+PyUnicode_AS_DATA:PyObject*:o:0:
+
+Py_UNICODE_ISSPACE:int:::
+Py_UNICODE_ISSPACE:Py_UNICODE:ch::
+
+Py_UNICODE_ISLOWER:int:::
+Py_UNICODE_ISLOWER:Py_UNICODE:ch::
+
+Py_UNICODE_ISUPPER:int:::
+Py_UNICODE_ISUPPER:Py_UNICODE:ch::
+
+Py_UNICODE_ISTITLE:int:::
+Py_UNICODE_ISTITLE:Py_UNICODE:ch::
+
+Py_UNICODE_ISLINEBREAK:int:::
+Py_UNICODE_ISLINEBREAK:Py_UNICODE:ch::
+
+Py_UNICODE_ISDECIMAL:int:::
+Py_UNICODE_ISDECIMAL:Py_UNICODE:ch::
+
+Py_UNICODE_ISDIGIT:int:::
+Py_UNICODE_ISDIGIT:Py_UNICODE:ch::
+
+Py_UNICODE_ISNUMERIC:int:::
+Py_UNICODE_ISNUMERIC:Py_UNICODE:ch::
+
+Py_UNICODE_TOLOWER:Py_UNICODE:::
+Py_UNICODE_TOLOWER:Py_UNICODE:ch::
+
+Py_UNICODE_TOUPPER:Py_UNICODE:::
+Py_UNICODE_TOUPPER:Py_UNICODE:ch::
+
+Py_UNICODE_TOTITLE:Py_UNICODE:::
+Py_UNICODE_TOTITLE:Py_UNICODE:ch::
+
+Py_UNICODE_TODECIMAL:int:::
+Py_UNICODE_TODECIMAL:Py_UNICODE:ch::
+
+Py_UNICODE_TODIGIT:int:::
+Py_UNICODE_TODIGIT:Py_UNICODE:ch::
+
+Py_UNICODE_TONUMERIC:double:::
+Py_UNICODE_TONUMERIC:Py_UNICODE:ch::
+
+PyUnicode_FromUnicode:PyObject*::+1:
+PyUnicode_FromUnicode:const Py_UNICODE*:u::
+PyUnicode_FromUnicode:int:size::
+
+PyUnicode_AsUnicode:Py_UNICODE*:::
+PyUnicode_AsUnicode:PyObject :*unicode:0:
+
+PyUnicode_GetSize:int:::
+PyUnicode_GetSize:PyObject :*unicode:0:
+
+PyUnicode_FromObject:PyObject*::+1:
+PyUnicode_FromObject:PyObject*:*obj:0:
+
+PyUnicode_FromEncodedObject:PyObject*::+1:
+PyUnicode_FromEncodedObject:PyObject*:*obj:0:
+PyUnicode_FromEncodedObject:const char*:encoding::
+PyUnicode_FromEncodedObject:const char*:errors::
+
+PyUnicode_FromWideChar:PyObject*::+1:
+PyUnicode_FromWideChar:const wchar_t*:w::
+PyUnicode_FromWideChar:int:size::
+
+PyUnicode_AsWideChar:int:::
+PyUnicode_AsWideChar:PyObject*:*unicode:0:
+PyUnicode_AsWideChar:wchar_t*:w::
+PyUnicode_AsWideChar:int:size::
+
+PyUnicode_Decode:PyObject*::+1:
+PyUnicode_Decode:const char*:s::
+PyUnicode_Decode:int:size::
+PyUnicode_Decode:const char*:encoding::
+PyUnicode_Decode:const char*:errors::
+
+PyUnicode_DecodeUTF16Stateful:PyObject*::+1:
+PyUnicode_DecodeUTF16Stateful:const char*:s::
+PyUnicode_DecodeUTF16Stateful:int:size::
+PyUnicode_DecodeUTF16Stateful:const char*:errors::
+PyUnicode_DecodeUTF16Stateful:int*:byteorder::
+PyUnicode_DecodeUTF16Stateful:int*:consumed::
+
+PyUnicode_DecodeUTF8Stateful:PyObject*::+1:
+PyUnicode_DecodeUTF8Stateful:const char*:s::
+PyUnicode_DecodeUTF8Stateful:int:size::
+PyUnicode_DecodeUTF8Stateful:const char*:errors::
+PyUnicode_DecodeUTF8Stateful:int*:consumed::
+
+PyUnicode_Encode:PyObject*::+1:
+PyUnicode_Encode:const Py_UNICODE*:s::
+PyUnicode_Encode:int:size::
+PyUnicode_Encode:const char*:encoding::
+PyUnicode_Encode:const char*:errors::
+
+PyUnicode_AsEncodedString:PyObject*::+1:
+PyUnicode_AsEncodedString:PyObject*:unicode::
+PyUnicode_AsEncodedString:const char*:encoding::
+PyUnicode_AsEncodedString:const char*:errors::
+
+PyUnicode_DecodeUTF8:PyObject*::+1:
+PyUnicode_DecodeUTF8:const char*:s::
+PyUnicode_DecodeUTF8:int:size::
+PyUnicode_DecodeUTF8:const char*:errors::
+
+PyUnicode_EncodeUTF8:PyObject*::+1:
+PyUnicode_EncodeUTF8:const Py_UNICODE*:s::
+PyUnicode_EncodeUTF8:int:size::
+PyUnicode_EncodeUTF8:const char*:errors::
+
+PyUnicode_AsUTF8String:PyObject*::+1:
+PyUnicode_AsUTF8String:PyObject*:unicode::
+
+PyUnicode_DecodeUTF16:PyObject*::+1:
+PyUnicode_DecodeUTF16:const char*:s::
+PyUnicode_DecodeUTF16:int:size::
+PyUnicode_DecodeUTF16:const char*:errors::
+PyUnicode_DecodeUTF16:int*:byteorder::
+
+PyUnicode_EncodeUTF16:PyObject*::+1:
+PyUnicode_EncodeUTF16:const Py_UNICODE*:s::
+PyUnicode_EncodeUTF16:int:size::
+PyUnicode_EncodeUTF16:const char*:errors::
+PyUnicode_EncodeUTF16:int:byteorder::
+
+PyUnicode_AsUTF16String:PyObject*::+1:
+PyUnicode_AsUTF16String:PyObject*:unicode::
+
+PyUnicode_DecodeUnicodeEscape:PyObject*::+1:
+PyUnicode_DecodeUnicodeEscape:const char*:s::
+PyUnicode_DecodeUnicodeEscape:int:size::
+PyUnicode_DecodeUnicodeEscape:const char*:errors::
+
+PyUnicode_EncodeUnicodeEscape:PyObject*::+1:
+PyUnicode_EncodeUnicodeEscape:const Py_UNICODE*:s::
+PyUnicode_EncodeUnicodeEscape:int:size::
+PyUnicode_EncodeUnicodeEscape:const char*:errors::
+
+PyUnicode_AsUnicodeEscapeString:PyObject*::+1:
+PyUnicode_AsUnicodeEscapeString:PyObject*:unicode::
+
+PyUnicode_DecodeRawUnicodeEscape:PyObject*::+1:
+PyUnicode_DecodeRawUnicodeEscape:const char*:s::
+PyUnicode_DecodeRawUnicodeEscape:int:size::
+PyUnicode_DecodeRawUnicodeEscape:const char*:errors::
+
+PyUnicode_EncodeRawUnicodeEscape:PyObject*::+1:
+PyUnicode_EncodeRawUnicodeEscape:const Py_UNICODE*:s::
+PyUnicode_EncodeRawUnicodeEscape:int:size::
+PyUnicode_EncodeRawUnicodeEscape:const char*:errors::
+
+PyUnicode_AsRawUnicodeEscapeString:PyObject*::+1:
+PyUnicode_AsRawUnicodeEscapeString:PyObject*:unicode::
+
+PyUnicode_DecodeLatin1:PyObject*::+1:
+PyUnicode_DecodeLatin1:const char*:s::
+PyUnicode_DecodeLatin1:int:size::
+PyUnicode_DecodeLatin1:const char*:errors::
+
+PyUnicode_EncodeLatin1:PyObject*::+1:
+PyUnicode_EncodeLatin1:const Py_UNICODE*:s::
+PyUnicode_EncodeLatin1:int:size::
+PyUnicode_EncodeLatin1:const char*:errors::
+
+PyUnicode_AsLatin1String:PyObject*::+1:
+PyUnicode_AsLatin1String:PyObject*:unicode::
+
+PyUnicode_DecodeASCII:PyObject*::+1:
+PyUnicode_DecodeASCII:const char*:s::
+PyUnicode_DecodeASCII:int:size::
+PyUnicode_DecodeASCII:const char*:errors::
+
+PyUnicode_EncodeASCII:PyObject*::+1:
+PyUnicode_EncodeASCII:const Py_UNICODE*:s::
+PyUnicode_EncodeASCII:int:size::
+PyUnicode_EncodeASCII:const char*:errors::
+
+PyUnicode_AsASCIIString:PyObject*::+1:
+PyUnicode_AsASCIIString:PyObject*:unicode::
+
+PyUnicode_DecodeCharmap:PyObject*::+1:
+PyUnicode_DecodeCharmap:const char*:s::
+PyUnicode_DecodeCharmap:int:size::
+PyUnicode_DecodeCharmap:PyObject*:mapping:0:
+PyUnicode_DecodeCharmap:const char*:errors::
+
+PyUnicode_EncodeCharmap:PyObject*::+1:
+PyUnicode_EncodeCharmap:const Py_UNICODE*:s::
+PyUnicode_EncodeCharmap:int:size::
+PyUnicode_EncodeCharmap:PyObject*:mapping:0:
+PyUnicode_EncodeCharmap:const char*:errors::
+
+PyUnicode_AsCharmapString:PyObject*::+1:
+PyUnicode_AsCharmapString:PyObject*:unicode:0:
+PyUnicode_AsCharmapString:PyObject*:mapping:0:
+
+PyUnicode_TranslateCharmap:PyObject*::+1:
+PyUnicode_TranslateCharmap:const Py_UNICODE*:s::
+PyUnicode_TranslateCharmap:int:size::
+PyUnicode_TranslateCharmap:PyObject*:table:0:
+PyUnicode_TranslateCharmap:const char*:errors::
+
+PyUnicode_DecodeMBCS:PyObject*::+1:
+PyUnicode_DecodeMBCS:const char*:s::
+PyUnicode_DecodeMBCS:int:size::
+PyUnicode_DecodeMBCS:const char*:errors::
+
+PyUnicode_EncodeMBCS:PyObject*::+1:
+PyUnicode_EncodeMBCS:const Py_UNICODE*:s::
+PyUnicode_EncodeMBCS:int:size::
+PyUnicode_EncodeMBCS:const char*:errors::
+
+PyUnicode_AsMBCSString:PyObject*::+1:
+PyUnicode_AsMBCSString:PyObject*:unicode::
+
+PyUnicode_Concat:PyObject*::+1:
+PyUnicode_Concat:PyObject*:left:0:
+PyUnicode_Concat:PyObject*:right:0:
+
+PyUnicode_Split:PyObject*::+1:
+PyUnicode_Split:PyObject*:left:0:
+PyUnicode_Split:PyObject*:right:0:
+PyUnicode_Split:int:maxsplit::
+
+PyUnicode_Splitlines:PyObject*::+1:
+PyUnicode_Splitlines:PyObject*:s:0:
+PyUnicode_Splitlines:int:maxsplit::
+
+PyUnicode_Translate:PyObject*::+1:
+PyUnicode_Translate:PyObject*:str:0:
+PyUnicode_Translate:PyObject*:table:0:
+PyUnicode_Translate:const char*:errors::
+
+PyUnicode_Join:PyObject*::+1:
+PyUnicode_Join:PyObject*:separator:0:
+PyUnicode_Join:PyObject*:seq:0:
+
+PyUnicode_Tailmatch:PyObject*::+1:
+PyUnicode_Tailmatch:PyObject*:str:0:
+PyUnicode_Tailmatch:PyObject*:substr:0:
+PyUnicode_Tailmatch:int:start::
+PyUnicode_Tailmatch:int:end::
+PyUnicode_Tailmatch:int:direction::
+
+PyUnicode_Find:int:::
+PyUnicode_Find:PyObject*:str:0:
+PyUnicode_Find:PyObject*:substr:0:
+PyUnicode_Find:int:start::
+PyUnicode_Find:int:end::
+PyUnicode_Find:int:direction::
+
+PyUnicode_Count:int:::
+PyUnicode_Count:PyObject*:str:0:
+PyUnicode_Count:PyObject*:substr:0:
+PyUnicode_Count:int:start::
+PyUnicode_Count:int:end::
+
+PyUnicode_Replace:PyObject*::+1:
+PyUnicode_Replace:PyObject*:str:0:
+PyUnicode_Replace:PyObject*:substr:0:
+PyUnicode_Replace:PyObject*:replstr:0:
+PyUnicode_Replace:int:maxcount::
+
+PyUnicode_Compare:int:::
+PyUnicode_Compare:PyObject*:left:0:
+PyUnicode_Compare:PyObject*:right:0:
+
+PyUnicode_Format:PyObject*::+1:
+PyUnicode_Format:PyObject*:format:0:
+PyUnicode_Format:PyObject*:args:0:
+
+PyUnicode_Contains:int:::
+PyUnicode_Contains:PyObject*:container:0:
+PyUnicode_Contains:PyObject*:element:0:
+
+PyWeakref_GET_OBJECT:PyObject*::0:
+PyWeakref_GET_OBJECT:PyObject*:ref:0:
+
+PyWeakref_GetObject:PyObject*::0:
+PyWeakref_GetObject:PyObject*:ref:0:
+
+PyWeakref_NewProxy:PyObject*::+1:
+PyWeakref_NewProxy:PyObject*:ob:0:
+PyWeakref_NewProxy:PyObject*:callback:0:
+
+PyWeakref_NewRef:PyObject*::+1:
+PyWeakref_NewRef:PyObject*:ob:0:
+PyWeakref_NewRef:PyObject*:callback:0:
+
+PyWrapper_New:PyObject*::+1:
+PyWrapper_New:PyObject*:d:0:
+PyWrapper_New:PyObject*:self:0:
+
+Py_AtExit:int:::
+Py_AtExit:void (*)():func::
+
+Py_BuildValue:PyObject*::+1:
+Py_BuildValue:char*:format::
+
+Py_CompileString:PyObject*::+1:
+Py_CompileString:char*:str::
+Py_CompileString:char*:filename::
+Py_CompileString:int:start::
+
+Py_CompileStringFlags:PyObject*::+1:
+Py_CompileStringFlags:char*:str::
+Py_CompileStringFlags:char*:filename::
+Py_CompileStringFlags:int:start::
+Py_CompileStringFlags:PyCompilerFlags*:flags::
+
+Py_DECREF:void:::
+Py_DECREF:PyObject*:o:-1:
+
+Py_EndInterpreter:void:::
+Py_EndInterpreter:PyThreadState*:tstate::
+
+Py_Exit:void:::
+Py_Exit:int:status::
+
+Py_FatalError:void:::
+Py_FatalError:char*:message::
+
+Py_FdIsInteractive:int:::
+Py_FdIsInteractive:FILE*:fp::
+Py_FdIsInteractive:char*:filename::
+
+Py_Finalize:void:::
+
+Py_FindMethod:PyObject*::+1:
+Py_FindMethod:PyMethodDef[]:methods::
+Py_FindMethod:PyObject*:self:+1:
+Py_FindMethod:char*:name::
+
+Py_GetBuildInfoconst:char*:::
+
+Py_GetCompilerconst:char*:::
+
+Py_GetCopyrightconst:char*:::
+
+Py_GetExecPrefix:char*:::
+
+Py_GetPath:char*:::
+
+Py_GetPlatformconst:char*:::
+
+Py_GetPrefix:char*:::
+
+Py_GetProgramFullPath:char*:::
+
+Py_GetProgramName:char*:::
+
+Py_GetVersionconst:char*:::
+
+Py_INCREF:void:::
+Py_INCREF:PyObject*:o:+1:
+
+Py_Initialize:void:::
+
+Py_IsInitialized:int:::
+
+Py_NewInterpreter:PyThreadState*:::
+
+Py_SetProgramName:void:::
+Py_SetProgramName:char*:name::
+
+Py_XDECREF:void:::
+Py_XDECREF:PyObject*:o:-1:if o is not NULL
+
+Py_XINCREF:void:::
+Py_XINCREF:PyObject*:o:+1:if o is not NULL
+
+_PyImport_FindExtension:PyObject*::0:??? see PyImport_AddModule
+_PyImport_FindExtension:char*:::
+_PyImport_FindExtension:char*:::
+
+_PyImport_Fini:void:::
+
+_PyImport_FixupExtension:PyObject*:::???
+_PyImport_FixupExtension:char*:::
+_PyImport_FixupExtension:char*:::
+
+_PyImport_Init:void:::
+
+_PyObject_Del:void:::
+_PyObject_Del:PyObject*:op:0:
+
+_PyObject_New:PyObject*::+1:
+_PyObject_New:PyTypeObject*:type:0:
+
+_PyObject_NewVar:PyObject*::+1:
+_PyObject_NewVar:PyTypeObject*:type:0:
+_PyObject_NewVar:int:size::
+
+_PyString_Resize:int:::
+_PyString_Resize:PyObject**:string:+1:
+_PyString_Resize:int:newsize::
+
+_PyTuple_Resize:int:::
+_PyTuple_Resize:PyTupleObject**:p:+1:
+_PyTuple_Resize:int:new::
+
+_Py_c_diff:Py_complex:::
+_Py_c_diff:Py_complex:left::
+_Py_c_diff:Py_complex:right::
+
+_Py_c_neg:Py_complex:::
+_Py_c_neg:Py_complex:complex::
+
+_Py_c_pow:Py_complex:::
+_Py_c_pow:Py_complex:num::
+_Py_c_pow:Py_complex:exp::
+
+_Py_c_prod:Py_complex:::
+_Py_c_prod:Py_complex:left::
+_Py_c_prod:Py_complex:right::
+
+_Py_c_quot:Py_complex:::
+_Py_c_quot:Py_complex:dividend::
+_Py_c_quot:Py_complex:divisor::
+
+_Py_c_sum:Py_complex:::
+_Py_c_sum:Py_complex:left::
+_Py_c_sum:Py_complex:right::
diff --git a/sys/src/cmd/python/Doc/api/utilities.tex b/sys/src/cmd/python/Doc/api/utilities.tex
new file mode 100644
index 000000000..93e379645
--- /dev/null
+++ b/sys/src/cmd/python/Doc/api/utilities.tex
@@ -0,0 +1,1023 @@
+\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, const 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).  \constant{USE_STACKCHECK} 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}{const 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 finalization 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}{const 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.  Before Python 2.4, the module may still be created in
+  the failure case --- examine \code{sys.modules} to find out.  Starting
+  with Python 2.4, a failing import of a module no longer leaves the
+  module in \code{sys.modules}.
+  \versionchanged[failing imports remove incomplete module objects]{2.4}
+  \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 (before
+  Python 2.4, 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.
+  \versionchanged[failing imports remove incomplete module objects]{2.4}
+\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}{const 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 it in the modules dictionary.
+  Return \NULL{} with an exception set on failure.
+  \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.  Package structures implied by a dotted name for
+  \var{name} are not created if not already present.}
+\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.  Before Python 2.4, the module
+  could still be created in error cases.  Starting with Python 2.4,
+  \var{name} is removed from \code{sys.modules} in error cases, and even
+  if \var{name} was already in \code{sys.modules} on entry to
+  \cfunction{PyImport_ExecCodeModule()}.  Leaving incompletely initialized
+  modules in \code{sys.modules} is dangerous, as imports of such modules
+  have no way to know that the module object is an unknown (and probably
+  damaged with respect to the module author's intents) state.
+
+  This function will reload the module if it was already imported.  See
+  \cfunction{PyImport_ReloadModule()} for the intended way to reload a
+  module.
+
+  If \var{name} points to a dotted name of the
+  form \code{package.module}, any package structures not already
+  created will still not be created.
+
+  \versionchanged[\var{name} is removed from \code{sys.modules} in error cases]{2.4}
+
+\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{Data marshalling support \label{marshalling-utils}}
+
+These routines allow C code to work with serialized objects using the
+same data format as the \module{marshal} module.  There are functions
+to write data into the serialization format, and additional functions
+that can be used to read the data back.  Files used to store marshalled
+data must be opened in binary mode.
+
+Numeric values are stored with the least significant byte first.
+
+The module supports two versions of the data format: version 0 is the
+historical version, version 1 (new in Python 2.4) shares interned
+strings in the file, and upon unmarshalling. \var{Py_MARSHAL_VERSION}
+indicates the current file format (currently 1).
+
+\begin{cfuncdesc}{void}{PyMarshal_WriteLongToFile}{long value, FILE *file, int version}
+  Marshal a \ctype{long} integer, \var{value}, to \var{file}.  This
+  will only write the least-significant 32 bits of \var{value};
+  regardless of the size of the native \ctype{long} type.
+
+  \versionchanged[\var{version} indicates the file format]{2.4}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyMarshal_WriteObjectToFile}{PyObject *value,
+                                                     FILE *file, int version}
+  Marshal a Python object, \var{value}, to \var{file}.
+
+  \versionchanged[\var{version} indicates the file format]{2.4}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyMarshal_WriteObjectToString}{PyObject *value, int version}
+  Return a string object containing the marshalled representation of
+  \var{value}.
+
+  \versionchanged[\var{version} indicates the file format]{2.4}
+\end{cfuncdesc}
+
+The following functions allow marshalled values to be read back in.
+
+XXX What about error detection?  It appears that reading past the end
+of the file will always result in a negative numeric value (where
+that's relevant), but it's not clear that negative values won't be
+handled properly when there's no error.  What's the right way to tell?
+Should only non-negative values be written using these routines?
+
+\begin{cfuncdesc}{long}{PyMarshal_ReadLongFromFile}{FILE *file}
+  Return a C \ctype{long} from the data stream in a \ctype{FILE*}
+  opened for reading.  Only a 32-bit value can be read in using
+  this function, regardless of the native size of \ctype{long}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyMarshal_ReadShortFromFile}{FILE *file}
+  Return a C \ctype{short} from the data stream in a \ctype{FILE*}
+  opened for reading.  Only a 16-bit value can be read in using
+  this function, regardless of the native size of \ctype{short}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyMarshal_ReadObjectFromFile}{FILE *file}
+  Return a Python object from the data stream in a \ctype{FILE*}
+  opened for reading.  On error, sets the appropriate exception
+  (\exception{EOFError} or \exception{TypeError}) and returns \NULL.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyMarshal_ReadLastObjectFromFile}{FILE *file}
+  Return a Python object from the data stream in a \ctype{FILE*}
+  opened for reading.  Unlike
+  \cfunction{PyMarshal_ReadObjectFromFile()}, this function assumes
+  that no further objects will be read from the file, allowing it to
+  aggressively load file data into memory so that the de-serialization
+  can operate from data in memory rather than reading a byte at a time
+  from the file.  Only use these variant if you are certain that you
+  won't be reading anything else from the file.  On error, sets the
+  appropriate exception (\exception{EOFError} or
+  \exception{TypeError}) and returns \NULL.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyMarshal_ReadObjectFromString}{char *string,
+                                                             Py_ssize_t len}
+  Return a Python object from the data stream in a character buffer
+  containing \var{len} bytes pointed to by \var{string}.  On error,
+  sets the appropriate exception (\exception{EOFError} or
+  \exception{TypeError}) and returns \NULL.
+\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}.
+
+The first three of these functions described,
+\cfunction{PyArg_ParseTuple()},
+\cfunction{PyArg_ParseTupleAndKeywords()}, and
+\cfunction{PyArg_Parse()}, all use \emph{format strings} which are
+used to tell the function about the expected arguments.  The format
+strings use the same syntax for each of these functions.
+
+A format string consists of zero or more ``format units.''  A format
+unit describes one Python object; it is usually a single character or
+a parenthesized sequence of format units.  With a few exceptions, a
+format unit that is not a parenthesized sequence normally corresponds
+to a single address argument to these functions.  In the following
+description, the quoted form is the format unit; the entry in (round)
+parentheses is the Python object type that matches the format unit;
+and the entry in [square] brackets is the type of the C variable(s)
+whose address should be passed.
+
+\begin{description}
+  \item[\samp{s} (string or Unicode object) {[const char *]}]
+  Convert a Python string or Unicode object to a C pointer to a
+  character string.  You must not provide storage for the string
+  itself; a pointer to an existing string is stored into the character
+  pointer variable whose address you pass.  The C string is
+  NUL-terminated.  The Python string must not contain embedded NUL
+  bytes; if it does, a \exception{TypeError} exception is raised.
+  Unicode objects are converted to C strings using the default
+  encoding.  If this conversion fails, a \exception{UnicodeError} is
+  raised.
+
+  \item[\samp{s\#} (string, Unicode or any read buffer compatible object)
+  {[const char *, int]}]
+  This variant on \samp{s} stores into two C variables, the first one
+  a pointer to a character string, the second one its length.  In this
+  case the Python string may contain embedded null bytes.  Unicode
+  objects pass back a pointer to the default encoded string version of
+  the object if such a conversion is possible.  All other read-buffer
+  compatible objects pass back a reference to the raw internal data
+  representation.
+
+  \item[\samp{z} (string or \code{None}) {[const char *]}]
+  Like \samp{s}, but the Python object may also be \code{None}, in
+  which case the C pointer is set to \NULL.
+
+  \item[\samp{z\#} (string or \code{None} or any read buffer
+  compatible object) {[const char *, int]}]
+  This is to \samp{s\#} as \samp{z} is to \samp{s}.
+
+  \item[\samp{u} (Unicode object) {[Py_UNICODE *]}]
+  Convert a Python Unicode object to a C pointer to a NUL-terminated
+  buffer of 16-bit Unicode (UTF-16) data.  As with \samp{s}, there is
+  no need to provide storage for the Unicode data buffer; a pointer to
+  the existing Unicode data is stored into the \ctype{Py_UNICODE}
+  pointer variable whose address you pass.
+
+  \item[\samp{u\#} (Unicode object) {[Py_UNICODE *, int]}]
+  This variant on \samp{u} stores into two C variables, the first one
+  a pointer to a Unicode data buffer, the second one its length.
+  Non-Unicode objects are handled by interpreting their read-buffer
+  pointer as pointer to a \ctype{Py_UNICODE} array.
+
+  \item[\samp{es} (string, Unicode object or character buffer
+  compatible object) {[const char *encoding, char **buffer]}]
+  This variant on \samp{s} is used for encoding Unicode and objects
+  convertible to Unicode into a character buffer. It only works for
+  encoded data without embedded NUL bytes.
+
+  This format requires two arguments.  The first is only used as
+  input, and must be a \ctype{const char*} which points to the name of an
+  encoding as a NUL-terminated string, or \NULL, in which case the
+  default encoding is used.  An exception is raised if the named
+  encoding is not known to Python.  The second argument must be a
+  \ctype{char**}; the value of the pointer it references will be set
+  to a buffer with the contents of the argument text.  The text will
+  be encoded in the encoding specified by the first argument.
+
+  \cfunction{PyArg_ParseTuple()} will allocate a buffer of the needed
+  size, copy the encoded data into this buffer and adjust
+  \var{*buffer} to reference the newly allocated storage.  The caller
+  is responsible for calling \cfunction{PyMem_Free()} to free the
+  allocated buffer after use.
+
+  \item[\samp{et} (string, Unicode object or character buffer
+  compatible object) {[const char *encoding, char **buffer]}]
+  Same as \samp{es} except that 8-bit string objects are passed
+  through without recoding them.  Instead, the implementation assumes
+  that the string object uses the encoding passed in as parameter.
+
+  \item[\samp{es\#} (string, Unicode object or character buffer compatible
+  object) {[const char *encoding, char **buffer, int *buffer_length]}]
+  This variant on \samp{s\#} is used for encoding Unicode and objects
+  convertible to Unicode into a character buffer.  Unlike the
+  \samp{es} format, this variant allows input data which contains NUL
+  characters.
+
+  It requires three arguments.  The first is only used as input, and
+  must be a \ctype{const char*} which points to the name of an encoding as a
+  NUL-terminated string, or \NULL, in which case the default encoding
+  is used.  An exception is raised if the named encoding is not known
+  to Python.  The second argument must be a \ctype{char**}; the value
+  of the pointer it references will be set to a buffer with the
+  contents of the argument text.  The text will be encoded in the
+  encoding specified by the first argument.  The third argument must
+  be a pointer to an integer; the referenced integer will be set to
+  the number of bytes in the output buffer.
+
+  There are two modes of operation:
+
+  If \var{*buffer} points a \NULL{} pointer, the function will
+  allocate a buffer of the needed size, copy the encoded data into
+  this buffer and set \var{*buffer} to reference the newly allocated
+  storage.  The caller is responsible for calling
+  \cfunction{PyMem_Free()} to free the allocated buffer after usage.
+
+  If \var{*buffer} points to a non-\NULL{} pointer (an already
+  allocated buffer), \cfunction{PyArg_ParseTuple()} will use this
+  location as the buffer and interpret the initial value of
+  \var{*buffer_length} as the buffer size.  It will then copy the
+  encoded data into the buffer and NUL-terminate it.  If the buffer
+  is not large enough, a \exception{ValueError} will be set.
+
+  In both cases, \var{*buffer_length} is set to the length of the
+  encoded data without the trailing NUL byte.
+
+  \item[\samp{et\#} (string, Unicode object or character buffer compatible
+  object) {[const char *encoding, char **buffer]}]
+  Same as \samp{es\#} except that string objects are passed through
+  without recoding them. Instead, the implementation assumes that the
+  string object uses the encoding passed in as parameter.
+
+  \item[\samp{b} (integer) {[char]}]
+  Convert a Python integer to a tiny int, stored in a C \ctype{char}.
+
+  \item[\samp{B} (integer) {[unsigned char]}]
+  Convert a Python integer to a tiny int without overflow checking,
+  stored in a C \ctype{unsigned char}. \versionadded{2.3}
+
+  \item[\samp{h} (integer) {[short int]}]
+  Convert a Python integer to a C \ctype{short int}.
+
+  \item[\samp{H} (integer) {[unsigned short int]}]
+  Convert a Python integer to a C \ctype{unsigned short int}, without
+  overflow checking.  \versionadded{2.3}
+
+  \item[\samp{i} (integer) {[int]}]
+  Convert a Python integer to a plain C \ctype{int}.
+
+  \item[\samp{I} (integer) {[unsigned int]}]
+  Convert a Python integer to a C \ctype{unsigned int}, without
+  overflow checking.  \versionadded{2.3}
+
+  \item[\samp{l} (integer) {[long int]}]
+  Convert a Python integer to a C \ctype{long int}.
+
+  \item[\samp{k} (integer) {[unsigned long]}]
+  Convert a Python integer or long integer to a C \ctype{unsigned long} without
+  overflow checking.  \versionadded{2.3}
+
+  \item[\samp{L} (integer) {[PY_LONG_LONG]}]
+  Convert a Python integer to a C \ctype{long long}.  This format is
+  only available on platforms that support \ctype{long long} (or
+  \ctype{_int64} on Windows).
+
+  \item[\samp{K} (integer) {[unsigned PY_LONG_LONG]}]
+  Convert a Python integer or long integer to a C \ctype{unsigned long long}
+  without overflow checking.  This format is only available on
+  platforms that support \ctype{unsigned long long} (or
+  \ctype{unsigned _int64} on Windows).  \versionadded{2.3}
+
+  \item[\samp{n} (integer) {[Py_ssize_t]}]
+  Convert a Python integer or long integer to a C \ctype{Py_ssize_t}.
+  \versionadded{2.5}
+
+  \item[\samp{c} (string of length 1) {[char]}]
+  Convert a Python character, represented as a string of length 1, to
+  a C \ctype{char}.
+
+  \item[\samp{f} (float) {[float]}]
+  Convert a Python floating point number to a C \ctype{float}.
+
+  \item[\samp{d} (float) {[double]}]
+  Convert a Python floating point number to a C \ctype{double}.
+
+  \item[\samp{D} (complex) {[Py_complex]}]
+  Convert a Python complex number to a C \ctype{Py_complex} structure.
+
+  \item[\samp{O} (object) {[PyObject *]}]
+  Store a Python object (without any conversion) in a C object
+  pointer.  The C program thus receives the actual object that was
+  passed.  The object's reference count is not increased.  The pointer
+  stored is not \NULL.
+
+  \item[\samp{O!} (object) {[\var{typeobject}, PyObject *]}]
+  Store a Python object in a C object pointer.  This is similar to
+  \samp{O}, but takes two C arguments: the first is the address of a
+  Python type object, the second is the address of the C variable (of
+  type \ctype{PyObject*}) into which the object pointer is stored.  If
+  the Python object does not have the required type,
+  \exception{TypeError} is raised.
+
+  \item[\samp{O\&} (object) {[\var{converter}, \var{anything}]}]
+  Convert a Python object to a C variable through a \var{converter}
+  function.  This takes two arguments: the first is a function, the
+  second is the address of a C variable (of arbitrary type), converted
+  to \ctype{void *}.  The \var{converter} function in turn is called
+  as follows:
+
+  \var{status}\code{ = }\var{converter}\code{(}\var{object},
+  \var{address}\code{);}
+
+  where \var{object} is the Python object to be converted and
+  \var{address} is the \ctype{void*} argument that was passed to the
+  \cfunction{PyArg_Parse*()} function.  The returned \var{status}
+  should be \code{1} for a successful conversion and \code{0} if the
+  conversion has failed.  When the conversion fails, the
+  \var{converter} function should raise an exception.
+
+  \item[\samp{S} (string) {[PyStringObject *]}]
+  Like \samp{O} but requires that the Python object is a string
+  object.  Raises \exception{TypeError} if the object is not a string
+  object.  The C variable may also be declared as \ctype{PyObject*}.
+
+  \item[\samp{U} (Unicode string) {[PyUnicodeObject *]}]
+  Like \samp{O} but requires that the Python object is a Unicode
+  object.  Raises \exception{TypeError} if the object is not a Unicode
+  object.  The C variable may also be declared as \ctype{PyObject*}.
+
+  \item[\samp{t\#} (read-only character buffer) {[char *, int]}]
+  Like \samp{s\#}, but accepts any object which implements the
+  read-only buffer interface.  The \ctype{char*} variable is set to
+  point to the first byte of the buffer, and the \ctype{int} is set to
+  the length of the buffer.  Only single-segment buffer objects are
+  accepted; \exception{TypeError} is raised for all others.
+
+  \item[\samp{w} (read-write character buffer) {[char *]}]
+  Similar to \samp{s}, but accepts any object which implements the
+  read-write buffer interface.  The caller must determine the length
+  of the buffer by other means, or use \samp{w\#} instead.  Only
+  single-segment buffer objects are accepted; \exception{TypeError} is
+  raised for all others.
+
+  \item[\samp{w\#} (read-write character buffer) {[char *, int]}]
+  Like \samp{s\#}, but accepts any object which implements the
+  read-write buffer interface.  The \ctype{char *} variable is set to
+  point to the first byte of the buffer, and the \ctype{int} is set to
+  the length of the buffer.  Only single-segment buffer objects are
+  accepted; \exception{TypeError} is raised for all others.
+
+  \item[\samp{(\var{items})} (tuple) {[\var{matching-items}]}]
+  The object must be a Python sequence whose length is the number of
+  format units in \var{items}.  The C arguments must correspond to the
+  individual format units in \var{items}.  Format units for sequences
+  may be nested.
+
+  \note{Prior to Python version 1.5.2, this format specifier only
+  accepted a tuple containing the individual parameters, not an
+  arbitrary sequence.  Code which previously caused
+  \exception{TypeError} to be raised here may now proceed without an
+  exception.  This is not expected to be a problem for existing code.}
+\end{description}
+
+It is possible to pass Python long integers where integers are
+requested; however no proper range checking is done --- the most
+significant bits are silently truncated when the receiving field is
+too small to receive the value (actually, the semantics are inherited
+from downcasts in C --- your mileage may vary).
+
+A few other characters have a meaning in a format string.  These may
+not occur inside nested parentheses.  They are:
+
+\begin{description}
+  \item[\samp{|}]
+  Indicates that the remaining arguments in the Python argument list
+  are optional.  The C variables corresponding to optional arguments
+  should be initialized to their default value --- when an optional
+  argument is not specified, \cfunction{PyArg_ParseTuple()} does not
+  touch the contents of the corresponding C variable(s).
+
+  \item[\samp{:}]
+  The list of format units ends here; the string after the colon is
+  used as the function name in error messages (the ``associated
+  value'' of the exception that \cfunction{PyArg_ParseTuple()}
+  raises).
+
+  \item[\samp{;}]
+  The list of format units ends here; the string after the semicolon
+  is used as the error message \emph{instead} of the default error
+  message.  Clearly, \samp{:} and \samp{;} mutually exclude each
+  other.
+\end{description}
+
+Note that any Python object references which are provided to the
+caller are \emph{borrowed} references; do not decrement their
+reference count!
+
+Additional arguments passed to these functions must be addresses of
+variables whose type is determined by the format string; these are
+used to store values from the input tuple.  There are a few cases, as
+described in the list of format units above, where these parameters
+are used as input values; they should match what is specified for the
+corresponding format unit in that case.
+
+For the conversion to succeed, the \var{arg} object must match the
+format and the format must be exhausted.  On success, the
+\cfunction{PyArg_Parse*()} functions return true, otherwise they
+return false and raise an appropriate exception.
+
+\begin{cfuncdesc}{int}{PyArg_ParseTuple}{PyObject *args, const 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.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyArg_VaParse}{PyObject *args, const char *format,
+                                         va_list vargs}
+  Identical to \cfunction{PyArg_ParseTuple()}, except that it accepts a
+  va_list rather than a variable number of arguments.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyArg_ParseTupleAndKeywords}{PyObject *args,
+                       PyObject *kw, const 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.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyArg_VaParseTupleAndKeywords}{PyObject *args,
+                       PyObject *kw, const char *format, char *keywords[],
+                       va_list vargs}
+  Identical to \cfunction{PyArg_ParseTupleAndKeywords()}, except that it
+  accepts a va_list rather than a variable number of arguments.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyArg_Parse}{PyObject *args, const 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}{int}{PyArg_UnpackTuple}{PyObject *args, const char *name,
+                                          Py_ssize_t min, Py_ssize_t max, \moreargs}
+  A simpler form of parameter retrieval which does not use a format
+  string to specify the types of the arguments.  Functions which use
+  this method to retrieve their parameters should be declared as
+  \constant{METH_VARARGS} in function or method tables.  The tuple
+  containing the actual parameters should be passed as \var{args}; it
+  must actually be a tuple.  The length of the tuple must be at least
+  \var{min} and no more than \var{max}; \var{min} and \var{max} may be
+  equal.  Additional arguments must be passed to the function, each of
+  which should be a pointer to a \ctype{PyObject*} variable; these
+  will be filled in with the values from \var{args}; they will contain
+  borrowed references.  The variables which correspond to optional
+  parameters not given by \var{args} will not be filled in; these
+  should be initialized by the caller.
+  This function returns true on success and false if \var{args} is not
+  a tuple or contains the wrong number of elements; an exception will
+  be set if there was a failure.
+
+  This is an example of the use of this function, taken from the
+  sources for the \module{_weakref} helper module for weak references:
+
+\begin{verbatim}
+static PyObject *
+weakref_ref(PyObject *self, PyObject *args)
+{
+    PyObject *object;
+    PyObject *callback = NULL;
+    PyObject *result = NULL;
+
+    if (PyArg_UnpackTuple(args, "ref", 1, 2, &object, &callback)) {
+        result = PyWeakref_NewRef(object, callback);
+    }
+    return result;
+}
+\end{verbatim}
+
+  The call to \cfunction{PyArg_UnpackTuple()} in this example is
+  entirely equivalent to this call to \cfunction{PyArg_ParseTuple()}:
+
+\begin{verbatim}
+PyArg_ParseTuple(args, "O|O:ref", &object, &callback)
+\end{verbatim}
+
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{Py_BuildValue}{const 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.
+
+  \cfunction{Py_BuildValue()} does not always build a tuple.  It
+  builds a tuple only if its format string contains two or more format
+  units.  If the format string is empty, it returns \code{None}; if it
+  contains exactly one format unit, it returns whatever object is
+  described by that format unit.  To force it to return a tuple of
+  size 0 or one, parenthesize the format string.
+
+  When memory buffers are passed as parameters to supply data to build
+  objects, as for the \samp{s} and \samp{s\#} formats, the required
+  data is copied.  Buffers provided by the caller are never referenced
+  by the objects created by \cfunction{Py_BuildValue()}.  In other
+  words, if your code invokes \cfunction{malloc()} and passes the
+  allocated memory to \cfunction{Py_BuildValue()}, your code is
+  responsible for calling \cfunction{free()} for that memory once
+  \cfunction{Py_BuildValue()} returns.
+
+  In the following description, the quoted form is the format unit;
+  the entry in (round) parentheses is the Python object type that the
+  format unit will return; and the entry in [square] brackets is the
+  type of the C value(s) to be passed.
+
+  The characters space, tab, colon and comma are ignored in format
+  strings (but not within format units such as \samp{s\#}).  This can
+  be used to make long format strings a tad more readable.
+
+  \begin{description}
+    \item[\samp{s} (string) {[char *]}]
+    Convert a null-terminated C string to a Python object.  If the C
+    string pointer is \NULL, \code{None} is used.
+
+    \item[\samp{s\#} (string) {[char *, int]}]
+    Convert a C string and its length to a Python object.  If the C
+    string pointer is \NULL, the length is ignored and \code{None} is
+    returned.
+
+    \item[\samp{z} (string or \code{None}) {[char *]}]
+    Same as \samp{s}.
+
+    \item[\samp{z\#} (string or \code{None}) {[char *, int]}]
+    Same as \samp{s\#}.
+
+    \item[\samp{u} (Unicode string) {[Py_UNICODE *]}]
+    Convert a null-terminated buffer of Unicode (UCS-2 or UCS-4)
+    data to a Python Unicode object.  If the Unicode buffer pointer
+    is \NULL, \code{None} is returned.
+
+    \item[\samp{u\#} (Unicode string) {[Py_UNICODE *, int]}]
+    Convert a Unicode (UCS-2 or UCS-4) data buffer and its length
+    to a Python Unicode object.   If the Unicode buffer pointer
+    is \NULL, the length is ignored and \code{None} is returned.
+
+    \item[\samp{i} (integer) {[int]}]
+    Convert a plain C \ctype{int} to a Python integer object.
+
+    \item[\samp{b} (integer) {[char]}]
+    Convert a plain C \ctype{char} to a Python integer object.
+
+    \item[\samp{h} (integer) {[short int]}]
+    Convert a plain C \ctype{short int} to a Python integer object.
+
+    \item[\samp{l} (integer) {[long int]}]
+    Convert a C \ctype{long int} to a Python integer object.
+
+    \item[\samp{B} (integer) {[unsigned char]}]
+    Convert a C \ctype{unsigned char} to a Python integer object.
+
+    \item[\samp{H} (integer) {[unsigned short int]}]
+    Convert a C \ctype{unsigned short int} to a Python integer object.
+
+    \item[\samp{I} (integer/long) {[unsigned int]}]
+    Convert a C \ctype{unsigned int} to a Python integer object
+    or a Python long integer object, if it is larger than \code{sys.maxint}.
+
+    \item[\samp{k} (integer/long) {[unsigned long]}]
+    Convert a C \ctype{unsigned long} to a Python integer object
+    or a Python long integer object, if it is larger than \code{sys.maxint}.
+
+    \item[\samp{L} (long) {[PY_LONG_LONG]}]
+    Convert a C \ctype{long long} to a Python long integer object. Only
+    available on platforms that support \ctype{long long}.
+
+    \item[\samp{K} (long) {[unsigned PY_LONG_LONG]}]
+    Convert a C \ctype{unsigned long long} to a Python long integer object.
+    Only available on platforms that support \ctype{unsigned long long}.
+
+    \item[\samp{n} (int) {[Py_ssize_t]}]
+    Convert a C \ctype{Py_ssize_t} to a Python integer or long integer.
+    \versionadded{2.5}
+
+    \item[\samp{c} (string of length 1) {[char]}]
+    Convert a C \ctype{int} representing a character to a Python
+    string of length 1.
+
+    \item[\samp{d} (float) {[double]}]
+    Convert a C \ctype{double} to a Python floating point number.
+
+    \item[\samp{f} (float) {[float]}]
+    Same as \samp{d}.
+
+    \item[\samp{D} (complex) {[Py_complex *]}]
+    Convert a C \ctype{Py_complex} structure to a Python complex
+    number.
+
+    \item[\samp{O} (object) {[PyObject *]}]
+    Pass a Python object untouched (except for its reference count,
+    which is incremented by one).  If the object passed in is a
+    \NULL{} pointer, it is assumed that this was caused because the
+    call producing the argument found an error and set an exception.
+    Therefore, \cfunction{Py_BuildValue()} will return \NULL{} but
+    won't raise an exception.  If no exception has been raised yet,
+    \exception{SystemError} is set.
+
+    \item[\samp{S} (object) {[PyObject *]}]
+    Same as \samp{O}.
+
+    \item[\samp{N} (object) {[PyObject *]}]
+    Same as \samp{O}, except it doesn't increment the reference count
+    on the object.  Useful when the object is created by a call to an
+    object constructor in the argument list.
+
+    \item[\samp{O\&} (object) {[\var{converter}, \var{anything}]}]
+    Convert \var{anything} to a Python object through a
+    \var{converter} function.  The function is called with
+    \var{anything} (which should be compatible with \ctype{void *}) as
+    its argument and should return a ``new'' Python object, or \NULL{}
+    if an error occurred.
+
+    \item[\samp{(\var{items})} (tuple) {[\var{matching-items}]}]
+    Convert a sequence of C values to a Python tuple with the same
+    number of items.
+
+    \item[\samp{[\var{items}]} (list) {[\var{matching-items}]}]
+    Convert a sequence of C values to a Python list with the same
+    number of items.
+
+    \item[\samp{\{\var{items}\}} (dictionary) {[\var{matching-items}]}]
+    Convert a sequence of C values to a Python dictionary.  Each pair
+    of consecutive C values adds one item to the dictionary, serving
+    as key and value, respectively.
+
+  \end{description}
+
+  If there is an error in the format string, the
+  \exception{SystemError} exception is set and \NULL{} returned.
+\end{cfuncdesc}
+
+\section{String conversion and formatting \label{string-formatting}}
+
+Functions for number conversion and formatted string output.
+
+\begin{cfuncdesc}{int}{PyOS_snprintf}{char *str, size_t size, 
+                                      const char *format, \moreargs}
+Output not more than \var{size} bytes to \var{str} according to the format
+string \var{format} and the extra arguments. See the \UNIX{} man
+page \manpage{snprintf}{2}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyOS_vsnprintf}{char *str, size_t size,
+                                       const char *format, va_list va}
+Output not more than \var{size} bytes to \var{str} according to the format
+string \var{format} and the variable argument list \var{va}. \UNIX{}
+man page \manpage{vsnprintf}{2}.
+\end{cfuncdesc}
+
+\cfunction{PyOS_snprintf} and \cfunction{PyOS_vsnprintf} wrap the
+Standard C library functions \cfunction{snprintf()} and
+\cfunction{vsnprintf()}. Their purpose is to guarantee consistent
+behavior in corner cases, which the Standard C functions do not.
+
+The wrappers ensure that \var{str}[\var{size}-1] is always
+\character{\textbackslash0} upon return. They never write more than
+\var{size} bytes (including the trailing \character{\textbackslash0}
+into str. Both functions require that \code{\var{str} != NULL},
+\code{\var{size} > 0} and \code{\var{format} != NULL}.
+
+If the platform doesn't have \cfunction{vsnprintf()} and the buffer
+size needed to avoid truncation exceeds \var{size} by more than 512
+bytes, Python aborts with a \var{Py_FatalError}.
+
+The return value (\var{rv}) for these functions should be interpreted
+as follows:
+
+\begin{itemize}
+
+\item When \code{0 <= \var{rv} < \var{size}}, the output conversion
+  was successful and \var{rv} characters were written to \var{str}
+  (excluding the trailing \character{\textbackslash0} byte at
+  \var{str}[\var{rv}]).
+
+\item When \code{\var{rv} >= \var{size}}, the output conversion was
+  truncated and a buffer with \code{\var{rv} + 1} bytes would have
+  been needed to succeed. \var{str}[\var{size}-1] is
+  \character{\textbackslash0} in this case.
+
+\item When \code{\var{rv} < 0}, ``something bad happened.''
+  \var{str}[\var{size}-1] is \character{\textbackslash0} in this case
+  too, but the rest of \var{str} is undefined. The exact cause of the
+  error depends on the underlying platform.
+
+\end{itemize}
+
+The following functions provide locale-independent string to number
+conversions.
+
+\begin{cfuncdesc}{double}{PyOS_ascii_strtod}{const char *nptr, char **endptr}
+Convert a string to a \ctype{double}. This function behaves like the
+Standard C function \cfunction{strtod()} does in the C locale. It does
+this without changing the current locale, since that would not be
+thread-safe.
+
+\cfunction{PyOS_ascii_strtod} should typically be used for reading
+configuration files or other non-user input that should be locale
+independent. \versionadded{2.4}
+
+See the \UNIX{} man page \manpage{strtod}{2} for details.
+
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{char *}{PyOS_ascii_formatd}{char *buffer, size_t buf_len,
+                                              const char *format, double d}
+Convert a \ctype{double} to a string using the \character{.} as the
+decimal separator. \var{format} is a \cfunction{printf()}-style format
+string specifying the number format. Allowed conversion characters are
+\character{e}, \character{E}, \character{f}, \character{F},
+\character{g} and \character{G}.
+
+The return value is a pointer to \var{buffer} with the converted
+string or NULL if the conversion failed. \versionadded{2.4}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{double}{PyOS_ascii_atof}{const char *nptr}
+Convert a string to a \ctype{double} in a locale-independent
+way. \versionadded{2.4}
+
+See the \UNIX{} man page \manpage{atof}{2} for details.
+\end{cfuncdesc}
diff --git a/sys/src/cmd/python/Doc/api/veryhigh.tex b/sys/src/cmd/python/Doc/api/veryhigh.tex
new file mode 100644
index 000000000..5c79b4440
--- /dev/null
+++ b/sys/src/cmd/python/Doc/api/veryhigh.tex
@@ -0,0 +1,287 @@
+\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, const char *filename}
+  This is a simplified interface to \cfunction{PyRun_AnyFileExFlags()}
+  below, leaving \var{closeit} set to \code{0} and \var{flags} set to \NULL.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyRun_AnyFileFlags}{FILE *fp, const char *filename,
+                                           PyCompilerFlags *flags}
+  This is a simplified interface to \cfunction{PyRun_AnyFileExFlags()}
+  below, leaving the \var{closeit} argument set to \code{0}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyRun_AnyFileEx}{FILE *fp, const char *filename,
+                                        int closeit}
+  This is a simplified interface to \cfunction{PyRun_AnyFileExFlags()}
+  below, leaving the \var{flags} argument set to \NULL.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyRun_AnyFileExFlags}{FILE *fp, const char *filename,
+                                             int closeit,
+                                             PyCompilerFlags *flags}
+  If \var{fp} refers to a file associated with an interactive device
+  (console or terminal input or \UNIX{} pseudo-terminal), return the
+  value of \cfunction{PyRun_InteractiveLoop()}, otherwise return the
+  result of \cfunction{PyRun_SimpleFile()}.  If \var{filename} is
+  \NULL, this function uses \code{"???"} as the filename.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyRun_SimpleString}{const char *command}
+  This is a simplified interface to \cfunction{PyRun_SimpleStringFlags()}
+  below, leaving the \var{PyCompilerFlags*} argument set to NULL.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyRun_SimpleStringFlags}{const char *command,
+                                                PyCompilerFlags *flags}
+  Executes the Python source code from \var{command} in the
+  \module{__main__} module according to the \var{flags} argument.
+  If \module{__main__} does not already exist, it is created.  Returns
+  \code{0} on success or \code{-1} if an exception was raised.  If there
+  was an error, there is no way to get the exception information.
+  For the meaning of \var{flags}, see below.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyRun_SimpleFile}{FILE *fp, const char *filename}
+  This is a simplified interface to \cfunction{PyRun_SimpleFileExFlags()}
+  below, leaving \var{closeit} set to \code{0} and \var{flags} set to
+  \NULL.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyRun_SimpleFileFlags}{FILE *fp, const char *filename,
+                                              PyCompilerFlags *flags}
+  This is a simplified interface to \cfunction{PyRun_SimpleFileExFlags()}
+  below, leaving \var{closeit} set to \code{0}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyRun_SimpleFileEx}{FILE *fp, const char *filename,
+                                           int closeit}
+  This is a simplified interface to \cfunction{PyRun_SimpleFileExFlags()}
+  below, leaving \var{flags} set to \NULL.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyRun_SimpleFileExFlags}{FILE *fp, const char *filename,
+                                                int closeit,
+                                                PyCompilerFlags *flags}
+  Similar to \cfunction{PyRun_SimpleStringFlags()}, but the Python source
+  code is read from \var{fp} instead of an in-memory string.
+  \var{filename} should be the name of the file.  If \var{closeit} is
+  true, the file is closed before PyRun_SimpleFileExFlags returns.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyRun_InteractiveOne}{FILE *fp, const char *filename}
+  This is a simplified interface to \cfunction{PyRun_InteractiveOneFlags()}
+  below, leaving \var{flags} set to \NULL.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyRun_InteractiveOneFlags}{FILE *fp,
+                                                  const char *filename,
+                                                  PyCompilerFlags *flags}
+  Read and execute a single statement from a file associated with an
+  interactive device according to the \var{flags} argument.  If
+  \var{filename} is \NULL, \code{"???"} is used instead.  The user will
+  be prompted using \code{sys.ps1} and \code{sys.ps2}.  Returns \code{0}
+  when the input was executed successfully, \code{-1} if there was an
+  exception, or an error code from the \file{errcode.h} include file
+  distributed as part of Python if there was a parse error.  (Note that
+  \file{errcode.h} is not included by \file{Python.h}, so must be included
+  specifically if needed.)
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyRun_InteractiveLoop}{FILE *fp, const char *filename}
+  This is a simplified interface to \cfunction{PyRun_InteractiveLoopFlags()}
+  below, leaving \var{flags} set to \NULL.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyRun_InteractiveLoopFlags}{FILE *fp, 
+                                                   const char *filename,
+                                                   PyCompilerFlags *flags}
+  Read and execute statements from a file associated with an
+  interactive device until \EOF{} is reached.  If \var{filename} is
+  \NULL, \code{"???"} is used instead.  The user will be prompted
+  using \code{sys.ps1} and \code{sys.ps2}.  Returns \code{0} at \EOF.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{struct _node*}{PyParser_SimpleParseString}{const char *str,
+                                                             int start}
+  This is a simplified interface to
+  \cfunction{PyParser_SimpleParseStringFlagsFilename()} below, leaving 
+  \var{filename} set to \NULL{} and \var{flags} set to \code{0}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{struct _node*}{PyParser_SimpleParseStringFlags}{
+                                 const char *str, int start, int flags}
+  This is a simplified interface to
+  \cfunction{PyParser_SimpleParseStringFlagsFilename()} below, leaving 
+  \var{filename} set to \NULL.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{struct _node*}{PyParser_SimpleParseStringFlagsFilename}{
+                                 const char *str, const char *filename,
+                                 int start, int flags}
+  Parse Python source code from \var{str} using the start token
+  \var{start} according to the \var{flags} argument.  The result can
+  be used to create a code object which can be evaluated efficiently.
+  This is useful if a code fragment must be evaluated many times.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{struct _node*}{PyParser_SimpleParseFile}{FILE *fp,
+                                 const char *filename, int start}
+  This is a simplified interface to \cfunction{PyParser_SimpleParseFileFlags()}
+  below, leaving \var{flags} set to \code{0}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{struct _node*}{PyParser_SimpleParseFileFlags}{FILE *fp,
+                                 const char *filename, int start, int flags}
+  Similar to \cfunction{PyParser_SimpleParseStringFlagsFilename()}, but
+  the Python source code is read from \var{fp} instead of an in-memory
+  string.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyRun_String}{const char *str, int start,
+                                           PyObject *globals,
+                                           PyObject *locals}
+  This is a simplified interface to \cfunction{PyRun_StringFlags()} below,
+  leaving \var{flags} set to \NULL.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyRun_StringFlags}{const char *str, int start,
+                                                PyObject *globals,
+                                                PyObject *locals,
+                                                PyCompilerFlags *flags}
+  Execute Python source code from \var{str} in the context specified
+  by the dictionaries \var{globals} and \var{locals} with the compiler
+  flags specified by \var{flags}.  The parameter \var{start} specifies
+  the start token that should be used to parse the source code.
+
+  Returns the result of executing the code as a Python object, or
+  \NULL{} if an exception was raised.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyRun_File}{FILE *fp, const char *filename,
+                                         int start, PyObject *globals,
+                                         PyObject *locals}
+  This is a simplified interface to \cfunction{PyRun_FileExFlags()} below,
+  leaving \var{closeit} set to \code{0} and \var{flags} set to \NULL.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyRun_FileEx}{FILE *fp, const char *filename,
+                                         int start, PyObject *globals,
+                                         PyObject *locals, int closeit}
+  This is a simplified interface to \cfunction{PyRun_FileExFlags()} below,
+  leaving \var{flags} set to \NULL.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyRun_FileFlags}{FILE *fp, const char *filename,
+                                         int start, PyObject *globals,
+                                         PyObject *locals,
+                                         PyCompilerFlags *flags}
+  This is a simplified interface to \cfunction{PyRun_FileExFlags()} below,
+  leaving \var{closeit} set to \code{0}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyRun_FileExFlags}{FILE *fp, const char *filename,
+                                                int start, PyObject *globals,
+                                                PyObject *locals, int closeit,
+                                                PyCompilerFlags *flags}
+  Similar to \cfunction{PyRun_StringFlags()}, but the Python source code is
+  read from \var{fp} instead of an in-memory string.
+  \var{filename} should be the name of the file.
+  If \var{closeit} is true, the file is closed before
+  \cfunction{PyRun_FileExFlags()} returns.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{Py_CompileString}{const char *str,
+                                               const char *filename,
+                                               int start}
+  This is a simplified interface to \cfunction{Py_CompileStringFlags()} below,
+  leaving \var{flags} set to \NULL.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{Py_CompileStringFlags}{const char *str,
+                                                    const char *filename,
+                                                    int start,
+                                                    PyCompilerFlags *flags}
+  Parse and compile the Python source code in \var{str}, returning the
+  resulting code object.  The start token is given by \var{start};
+  this can be used to constrain the code which can be compiled and should
+  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}
+
+\begin{ctypedesc}[PyCompilerFlags]{struct PyCompilerFlags}
+  This is the structure used to hold compiler flags.  In cases where
+  code is only being compiled, it is passed as \code{int flags}, and in
+  cases where code is being executed, it is passed as
+  \code{PyCompilerFlags *flags}.  In this case, \code{from __future__
+  import} can modify \var{flags}.
+
+  Whenever \code{PyCompilerFlags *flags} is \NULL, \member{cf_flags}
+  is treated as equal to \code{0}, and any modification due to
+  \code{from __future__ import} is discarded.
+\begin{verbatim}
+struct PyCompilerFlags {
+    int cf_flags;
+}
+\end{verbatim}
+\end{ctypedesc}
+
+\begin{cvardesc}{int}{CO_FUTURE_DIVISION}
+  This bit can be set in \var{flags} to cause division operator \code{/}
+  to be interpreted as ``true division'' according to \pep{238}.
+\end{cvardesc}