add hg and python

1 files changed, 3203 insertions, 0 deletions

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}