Commits

Anonymous committed 9e2265d

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

Comments (0)

Files changed (58)

Doc/api/abstract.tex

-\chapter{Abstract Objects Layer \label{abstract}}
-
-The functions in this chapter interact with Python objects regardless
-of their type, or with wide classes of object types (e.g. all
-numerical types, or all sequence types).  When used on object types
-for which they do not apply, they will raise a Python exception.
-
-
-\section{Object Protocol \label{object}}
-
-\begin{cfuncdesc}{int}{PyObject_Print}{PyObject *o, FILE *fp, int flags}
-  Print an object \var{o}, on file \var{fp}.  Returns \code{-1} on
-  error.  The flags argument is used to enable certain printing
-  options.  The only option currently supported is
-  \constant{Py_PRINT_RAW}; if given, the \function{str()} of the
-  object is written instead of the \function{repr()}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyObject_HasAttrString}{PyObject *o, char *attr_name}
-  Returns \code{1} if \var{o} has the attribute \var{attr_name}, and
-  \code{0} otherwise.  This is equivalent to the Python expression
-  \samp{hasattr(\var{o}, \var{attr_name})}.  This function always
-  succeeds.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyObject_GetAttrString}{PyObject *o,
-                                                     char *attr_name}
-  Retrieve an attribute named \var{attr_name} from object \var{o}.
-  Returns the attribute value on success, or \NULL{} on failure.
-  This is the equivalent of the Python expression
-  \samp{\var{o}.\var{attr_name}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyObject_HasAttr}{PyObject *o, PyObject *attr_name}
-  Returns \code{1} if \var{o} has the attribute \var{attr_name}, and
-  \code{0} otherwise.  This is equivalent to the Python expression
-  \samp{hasattr(\var{o}, \var{attr_name})}.  This function always
-  succeeds.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyObject_GetAttr}{PyObject *o,
-                                               PyObject *attr_name}
-  Retrieve an attribute named \var{attr_name} from object \var{o}.
-  Returns the attribute value on success, or \NULL{} on failure.  This
-  is the equivalent of the Python expression
-  \samp{\var{o}.\var{attr_name}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyObject_SetAttrString}{PyObject *o,
-                                               char *attr_name, PyObject *v}
-  Set the value of the attribute named \var{attr_name}, for object
-  \var{o}, to the value \var{v}. Returns \code{-1} on failure.  This
-  is the equivalent of the Python statement
-  \samp{\var{o}.\var{attr_name} = \var{v}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyObject_SetAttr}{PyObject *o,
-                                         PyObject *attr_name, PyObject *v}
-  Set the value of the attribute named \var{attr_name}, for object
-  \var{o}, to the value \var{v}. Returns \code{-1} on failure.  This
-  is the equivalent of the Python statement
-  \samp{\var{o}.\var{attr_name} = \var{v}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyObject_DelAttrString}{PyObject *o, char *attr_name}
-  Delete attribute named \var{attr_name}, for object \var{o}. Returns
-  \code{-1} on failure.  This is the equivalent of the Python
-  statement: \samp{del \var{o}.\var{attr_name}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyObject_DelAttr}{PyObject *o, PyObject *attr_name}
-  Delete attribute named \var{attr_name}, for object \var{o}. Returns
-  \code{-1} on failure.  This is the equivalent of the Python
-  statement \samp{del \var{o}.\var{attr_name}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyObject_RichCompare}{PyObject *o1,
-                                                   PyObject *o2, int opid}
-  Compare the values of \var{o1} and \var{o2} using the operation
-  specified by \var{opid}, which must be one of
-  \constant{Py_LT},
-  \constant{Py_LE},
-  \constant{Py_EQ},
-  \constant{Py_NE},
-  \constant{Py_GT}, or
-  \constant{Py_GE}, corresponding to
-  \code{<},
-  \code{<=},
-  \code{==},
-  \code{!=},
-  \code{>}, or
-  \code{>=} respectively. This is the equivalent of the Python expression
-  \samp{\var{o1} op \var{o2}}, where \code{op} is the operator
-  corresponding to \var{opid}. Returns the value of the comparison on
-  success, or \NULL{} on failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyObject_RichCompareBool}{PyObject *o1,
-                                                 PyObject *o2, int opid}
-  Compare the values of \var{o1} and \var{o2} using the operation
-  specified by \var{opid}, which must be one of
-  \constant{Py_LT},
-  \constant{Py_LE},
-  \constant{Py_EQ},
-  \constant{Py_NE},
-  \constant{Py_GT}, or
-  \constant{Py_GE}, corresponding to
-  \code{<},
-  \code{<=},
-  \code{==},
-  \code{!=},
-  \code{>}, or
-  \code{>=} respectively. Returns \code{-1} on error, \code{0} if the
-  result is false, \code{1} otherwise. This is the equivalent of the
-  Python expression \samp{\var{o1} op \var{o2}}, where
-  \code{op} is the operator corresponding to \var{opid}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyObject_Cmp}{PyObject *o1, PyObject *o2, int *result}
-  Compare the values of \var{o1} and \var{o2} using a routine provided
-  by \var{o1}, if one exists, otherwise with a routine provided by
-  \var{o2}.  The result of the comparison is returned in
-  \var{result}.  Returns \code{-1} on failure.  This is the equivalent
-  of the Python statement\bifuncindex{cmp} \samp{\var{result} =
-  cmp(\var{o1}, \var{o2})}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyObject_Compare}{PyObject *o1, PyObject *o2}
-  Compare the values of \var{o1} and \var{o2} using a routine provided
-  by \var{o1}, if one exists, otherwise with a routine provided by
-  \var{o2}.  Returns the result of the comparison on success.  On
-  error, the value returned is undefined; use
-  \cfunction{PyErr_Occurred()} to detect an error.  This is equivalent
-  to the Python expression\bifuncindex{cmp} \samp{cmp(\var{o1},
-  \var{o2})}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyObject_Repr}{PyObject *o}
-  Compute a string representation of object \var{o}.  Returns the
-  string representation on success, \NULL{} on failure.  This is the
-  equivalent of the Python expression \samp{repr(\var{o})}.  Called by
-  the \function{repr()}\bifuncindex{repr} built-in function and by
-  reverse quotes.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyObject_Str}{PyObject *o}
-  Compute a string representation of object \var{o}.  Returns the
-  string representation on success, \NULL{} on failure.  This is the
-  equivalent of the Python expression \samp{str(\var{o})}.  Called by
-  the \function{str()}\bifuncindex{str} built-in function and by the
-  \keyword{print} statement.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyObject_Unicode}{PyObject *o}
-  Compute a Unicode string representation of object \var{o}.  Returns
-  the Unicode string representation on success, \NULL{} on failure.
-  This is the equivalent of the Python expression
-  \samp{unicode(\var{o})}.  Called by the
-  \function{unicode()}\bifuncindex{unicode} built-in function.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyObject_IsInstance}{PyObject *inst, PyObject *cls}
-  Returns \code{1} if \var{inst} is an instance of the class \var{cls}
-  or a subclass of \var{cls}, or \code{0} if not.  On error, returns
-  \code{-1} and sets an exception.  If \var{cls} is a type object
-  rather than a class object, \cfunction{PyObject_IsInstance()}
-  returns \code{1} if \var{inst} is of type \var{cls}.  If \var{cls}
-  is a tuple, the check will be done against every entry in \var{cls}.
-  The result will be \code{1} when at least one of the checks returns
-  \code{1}, otherwise it will be \code{0}. If \var{inst} is not a class
-  instance and \var{cls} is neither a type object, nor a class object,
-  nor a tuple, \var{inst} must have a \member{__class__} attribute
-  --- the class relationship of the value of that attribute with
-  \var{cls} will be used to determine the result of this function.
-  \versionadded{2.1}
-  \versionchanged[Support for a tuple as the second argument added]{2.2}
-\end{cfuncdesc}
-
-Subclass determination is done in a fairly straightforward way, but
-includes a wrinkle that implementors of extensions to the class system
-may want to be aware of.  If \class{A} and \class{B} are class
-objects, \class{B} is a subclass of \class{A} if it inherits from
-\class{A} either directly or indirectly.  If either is not a class
-object, a more general mechanism is used to determine the class
-relationship of the two objects.  When testing if \var{B} is a
-subclass of \var{A}, if \var{A} is \var{B},
-\cfunction{PyObject_IsSubclass()} returns true.  If \var{A} and
-\var{B} are different objects, \var{B}'s \member{__bases__} attribute
-is searched in a depth-first fashion for \var{A} --- the presence of
-the \member{__bases__} attribute is considered sufficient for this
-determination.
-
-\begin{cfuncdesc}{int}{PyObject_IsSubclass}{PyObject *derived,
-                                            PyObject *cls}
-  Returns \code{1} if the class \var{derived} is identical to or
-  derived from the class \var{cls}, otherwise returns \code{0}.  In
-  case of an error, returns \code{-1}. If \var{cls}
-  is a tuple, the check will be done against every entry in \var{cls}.
-  The result will be \code{1} when at least one of the checks returns
-  \code{1}, otherwise it will be \code{0}. If either \var{derived} or
-  \var{cls} is not an actual class object (or tuple), this function
-  uses the generic algorithm described above.
-  \versionadded{2.1}
-  \versionchanged[Older versions of Python did not support a tuple
-                  as the second argument]{2.3}
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyCallable_Check}{PyObject *o}
-  Determine if the object \var{o} is callable.  Return \code{1} if the
-  object is callable and \code{0} otherwise.  This function always
-  succeeds.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyObject_Call}{PyObject *callable_object,
-                                            PyObject *args,
-                                            PyObject *kw}
-  Call a callable Python object \var{callable_object}, with arguments
-  given by the tuple \var{args}, and named arguments given by the
-  dictionary \var{kw}. If no named arguments are needed, \var{kw} may
-  be \NULL{}. \var{args} must not be \NULL{}, use an empty tuple if
-  no arguments are needed. Returns the result of the call on success,
-  or \NULL{} on failure.  This is the equivalent of the Python
-  expression \samp{apply(\var{callable_object}, \var{args}, \var{kw})}
-  or \samp{\var{callable_object}(*\var{args}, **\var{kw})}.
-  \bifuncindex{apply}
-  \versionadded{2.2}
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyObject_CallObject}{PyObject *callable_object,
-                                                  PyObject *args}
-  Call a callable Python object \var{callable_object}, with arguments
-  given by the tuple \var{args}.  If no arguments are needed, then
-  \var{args} may be \NULL.  Returns the result of the call on
-  success, or \NULL{} on failure.  This is the equivalent of the
-  Python expression \samp{apply(\var{callable_object}, \var{args})} or
-  \samp{\var{callable_object}(*\var{args})}.
-  \bifuncindex{apply}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyObject_CallFunction}{PyObject *callable,
-                                                    char *format, \moreargs}
-  Call a callable Python object \var{callable}, with a variable
-  number of C arguments.  The C arguments are described using a
-  \cfunction{Py_BuildValue()} style format string.  The format may be
-  \NULL, indicating that no arguments are provided.  Returns the
-  result of the call on success, or \NULL{} on failure.  This is the
-  equivalent of the Python expression \samp{apply(\var{callable},
-  \var{args})} or \samp{\var{callable}(*\var{args})}.
-  \bifuncindex{apply}
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyObject_CallMethod}{PyObject *o,
-                                                  char *method, char *format,
-                                                  \moreargs}
-  Call the method named \var{method} of object \var{o} with a variable
-  number of C arguments.  The C arguments are described by a
-  \cfunction{Py_BuildValue()} format string.  The format may be \NULL,
-  indicating that no arguments are provided. Returns the result of the
-  call on success, or \NULL{} on failure.  This is the equivalent of
-  the Python expression \samp{\var{o}.\var{method}(\var{args})}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyObject_CallFunctionObjArgs}{PyObject *callable,
-                                                           \moreargs,
-                                                           \code{NULL}}
-  Call a callable Python object \var{callable}, with a variable
-  number of \ctype{PyObject*} arguments.  The arguments are provided
-  as a variable number of parameters followed by \NULL.
-  Returns the result of the call on success, or \NULL{} on failure.
-  \versionadded{2.2}
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyObject_CallMethodObjArgs}{PyObject *o,
-                                                         PyObject *name,
-                                                         \moreargs,
-                                                         \code{NULL}}
-  Calls a method of the object \var{o}, where the name of the method
-  is given as a Python string object in \var{name}.  It is called with
-  a variable number of \ctype{PyObject*} arguments.  The arguments are
-  provided as a variable number of parameters followed by \NULL.
-  Returns the result of the call on success, or \NULL{} on failure.
-  \versionadded{2.2}
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyObject_Hash}{PyObject *o}
-  Compute and return the hash value of an object \var{o}.  On failure,
-  return \code{-1}.  This is the equivalent of the Python expression
-  \samp{hash(\var{o})}.\bifuncindex{hash}
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyObject_IsTrue}{PyObject *o}
-  Returns \code{1} if the object \var{o} is considered to be true, and
-  \code{0} otherwise.  This is equivalent to the Python expression
-  \samp{not not \var{o}}.  On failure, return \code{-1}. 
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyObject_Not}{PyObject *o}
-  Returns \code{0} if the object \var{o} is considered to be true, and
-  \code{1} otherwise.  This is equivalent to the Python expression
-  \samp{not \var{o}}.  On failure, return \code{-1}. 
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyObject_Type}{PyObject *o}
-  When \var{o} is non-\NULL, returns a type object corresponding to
-  the object type of object \var{o}. On failure, raises
-  \exception{SystemError} and returns \NULL.  This is equivalent to
-  the Python expression \code{type(\var{o})}.\bifuncindex{type}
-  This function increments the reference count of the return value.
-  There's really no reason to use this function instead of the
-  common expression \code{\var{o}->ob_type}, which returns a pointer
-  of type \ctype{PyTypeObject*}, except when the incremented reference
-  count is needed.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyObject_TypeCheck}{PyObject *o, PyTypeObject *type}
-  Return true if the object \var{o} is of type \var{type} or a subtype
-  of \var{type}.  Both parameters must be non-\NULL.
-  \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyObject_Length}{PyObject *o}
-\cfuncline{int}{PyObject_Size}{PyObject *o}
-  Return the length of object \var{o}.  If the object \var{o} provides
-  either the sequence and mapping protocols, the sequence length is
-  returned.  On error, \code{-1} is returned.  This is the equivalent
-  to the Python expression \samp{len(\var{o})}.\bifuncindex{len}
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyObject_GetItem}{PyObject *o, PyObject *key}
-  Return element of \var{o} corresponding to the object \var{key} or
-  \NULL{} on failure.  This is the equivalent of the Python expression
-  \samp{\var{o}[\var{key}]}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyObject_SetItem}{PyObject *o,
-                                         PyObject *key, PyObject *v}
-  Map the object \var{key} to the value \var{v}.  Returns \code{-1} on
-  failure.  This is the equivalent of the Python statement
-  \samp{\var{o}[\var{key}] = \var{v}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyObject_DelItem}{PyObject *o, PyObject *key}
-  Delete the mapping for \var{key} from \var{o}.  Returns \code{-1} on
-  failure. This is the equivalent of the Python statement \samp{del
-  \var{o}[\var{key}]}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyObject_AsFileDescriptor}{PyObject *o}
-  Derives a file-descriptor from a Python object.  If the object is an
-  integer or long integer, its value is returned.  If not, the
-  object's \method{fileno()} method is called if it exists; the method
-  must return an integer or long integer, which is returned as the
-  file descriptor value.  Returns \code{-1} on failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyObject_Dir}{PyObject *o}
-  This is equivalent to the Python expression \samp{dir(\var{o})},
-  returning a (possibly empty) list of strings appropriate for the
-  object argument, or \NULL{} if there was an error.  If the argument
-  is \NULL, this is like the Python \samp{dir()}, returning the names
-  of the current locals; in this case, if no execution frame is active
-  then \NULL{} is returned but \cfunction{PyErr_Occurred()} will
-  return false.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyObject_GetIter}{PyObject *o}
-  This is equivalent to the Python expression \samp{iter(\var{o})}.
-  It returns a new iterator for the object argument, or the object 
-  itself if the object is already an iterator.  Raises
-  \exception{TypeError} and returns \NULL{} if the object cannot be
-  iterated.
-\end{cfuncdesc}
-
-
-\section{Number Protocol \label{number}}
-
-\begin{cfuncdesc}{int}{PyNumber_Check}{PyObject *o}
-  Returns \code{1} if the object \var{o} provides numeric protocols,
-  and false otherwise.  This function always succeeds.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Add}{PyObject *o1, PyObject *o2}
-  Returns the result of adding \var{o1} and \var{o2}, or \NULL{} on
-  failure.  This is the equivalent of the Python expression
-  \samp{\var{o1} + \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Subtract}{PyObject *o1, PyObject *o2}
-  Returns the result of subtracting \var{o2} from \var{o1}, or \NULL{}
-  on failure.  This is the equivalent of the Python expression
-  \samp{\var{o1} - \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Multiply}{PyObject *o1, PyObject *o2}
-  Returns the result of multiplying \var{o1} and \var{o2}, or \NULL{}
-  on failure.  This is the equivalent of the Python expression
-  \samp{\var{o1} * \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Divide}{PyObject *o1, PyObject *o2}
-  Returns the result of dividing \var{o1} by \var{o2}, or \NULL{} on
-  failure.  This is the equivalent of the Python expression
-  \samp{\var{o1} / \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_FloorDivide}{PyObject *o1, PyObject *o2}
-  Return the floor of \var{o1} divided by \var{o2}, or \NULL{} on
-  failure.  This is equivalent to the ``classic'' division of
-  integers.
-  \versionadded{2.2}
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_TrueDivide}{PyObject *o1, PyObject *o2}
-  Return a reasonable approximation for the mathematical value of
-  \var{o1} divided by \var{o2}, or \NULL{} on failure.  The return
-  value is ``approximate'' because binary floating point numbers are
-  approximate; it is not possible to represent all real numbers in
-  base two.  This function can return a floating point value when
-  passed two integers.
-  \versionadded{2.2}
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Remainder}{PyObject *o1, PyObject *o2}
-  Returns the remainder of dividing \var{o1} by \var{o2}, or \NULL{}
-  on failure.  This is the equivalent of the Python expression
-  \samp{\var{o1} \%\ \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Divmod}{PyObject *o1, PyObject *o2}
-  See the built-in function \function{divmod()}\bifuncindex{divmod}.
-  Returns \NULL{} on failure.  This is the equivalent of the Python
-  expression \samp{divmod(\var{o1}, \var{o2})}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Power}{PyObject *o1,
-                                             PyObject *o2, PyObject *o3}
-  See the built-in function \function{pow()}\bifuncindex{pow}.
-  Returns \NULL{} on failure.  This is the equivalent of the Python
-  expression \samp{pow(\var{o1}, \var{o2}, \var{o3})}, where \var{o3}
-  is optional.  If \var{o3} is to be ignored, pass \cdata{Py_None} in
-  its place (passing \NULL{} for \var{o3} would cause an illegal
-  memory access).
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Negative}{PyObject *o}
-  Returns the negation of \var{o} on success, or \NULL{} on failure.
-  This is the equivalent of the Python expression \samp{-\var{o}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Positive}{PyObject *o}
-  Returns \var{o} on success, or \NULL{} on failure.  This is the
-  equivalent of the Python expression \samp{+\var{o}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Absolute}{PyObject *o}
-  Returns the absolute value of \var{o}, or \NULL{} on failure.  This
-  is the equivalent of the Python expression \samp{abs(\var{o})}.
-  \bifuncindex{abs}
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Invert}{PyObject *o}
-  Returns the bitwise negation of \var{o} on success, or \NULL{} on
-  failure.  This is the equivalent of the Python expression
-  \samp{\~\var{o}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Lshift}{PyObject *o1, PyObject *o2}
-  Returns the result of left shifting \var{o1} by \var{o2} on success,
-  or \NULL{} on failure.  This is the equivalent of the Python
-  expression \samp{\var{o1} <\code{<} \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Rshift}{PyObject *o1, PyObject *o2}
-  Returns the result of right shifting \var{o1} by \var{o2} on
-  success, or \NULL{} on failure.  This is the equivalent of the
-  Python expression \samp{\var{o1} >\code{>} \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_And}{PyObject *o1, PyObject *o2}
-  Returns the ``bitwise and'' of \var{o1} and \var{o2} on success and
-  \NULL{} on failure. This is the equivalent of the Python expression
-  \samp{\var{o1} \&\ \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Xor}{PyObject *o1, PyObject *o2}
-  Returns the ``bitwise exclusive or'' of \var{o1} by \var{o2} on
-  success, or \NULL{} on failure.  This is the equivalent of the
-  Python expression \samp{\var{o1} \textasciicircum{} \var{o2}}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Or}{PyObject *o1, PyObject *o2}
-  Returns the ``bitwise or'' of \var{o1} and \var{o2} on success, or
-  \NULL{} on failure.  This is the equivalent of the Python expression
-  \samp{\var{o1} | \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceAdd}{PyObject *o1, PyObject *o2}
-  Returns the result of adding \var{o1} and \var{o2}, or \NULL{} on
-  failure.  The operation is done \emph{in-place} when \var{o1}
-  supports it.  This is the equivalent of the Python statement
-  \samp{\var{o1} += \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceSubtract}{PyObject *o1,
-                                                       PyObject *o2}
-  Returns the result of subtracting \var{o2} from \var{o1}, or \NULL{}
-  on failure.  The operation is done \emph{in-place} when \var{o1}
-  supports it.  This is the equivalent of the Python statement
-  \samp{\var{o1} -= \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceMultiply}{PyObject *o1,
-                                                       PyObject *o2}
-  Returns the result of multiplying \var{o1} and \var{o2}, or \NULL{}
-  on failure.  The operation is done \emph{in-place} when \var{o1}
-  supports it.  This is the equivalent of the Python statement
-  \samp{\var{o1} *= \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceDivide}{PyObject *o1,
-                                                     PyObject *o2}
-  Returns the result of dividing \var{o1} by \var{o2}, or \NULL{} on
-  failure.  The operation is done \emph{in-place} when \var{o1}
-  supports it. This is the equivalent of the Python statement
-  \samp{\var{o1} /= \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceFloorDivide}{PyObject *o1,
-                                                          PyObject *o2}
-  Returns the mathematical of dividing \var{o1} by \var{o2}, or
-  \NULL{} on failure.  The operation is done \emph{in-place} when
-  \var{o1} supports it.  This is the equivalent of the Python
-  statement \samp{\var{o1} //= \var{o2}}.
-  \versionadded{2.2}
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceTrueDivide}{PyObject *o1,
-                                                         PyObject *o2}
-  Return a reasonable approximation for the mathematical value of
-  \var{o1} divided by \var{o2}, or \NULL{} on failure.  The return
-  value is ``approximate'' because binary floating point numbers are
-  approximate; it is not possible to represent all real numbers in
-  base two.  This function can return a floating point value when
-  passed two integers.  The operation is done \emph{in-place} when
-  \var{o1} supports it.
-  \versionadded{2.2}
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceRemainder}{PyObject *o1,
-                                                        PyObject *o2}
-  Returns the remainder of dividing \var{o1} by \var{o2}, or \NULL{}
-  on failure.  The operation is done \emph{in-place} when \var{o1}
-  supports it.  This is the equivalent of the Python statement
-  \samp{\var{o1} \%= \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_InPlacePower}{PyObject *o1,
-                                                    PyObject *o2, PyObject *o3}
-  See the built-in function \function{pow()}.\bifuncindex{pow}
-  Returns \NULL{} on failure.  The operation is done \emph{in-place}
-  when \var{o1} supports it.  This is the equivalent of the Python
-  statement \samp{\var{o1} **= \var{o2}} when o3 is \cdata{Py_None},
-  or an in-place variant of \samp{pow(\var{o1}, \var{o2}, \var{o3})}
-  otherwise. If \var{o3} is to be ignored, pass \cdata{Py_None} in its
-  place (passing \NULL{} for \var{o3} would cause an illegal memory
-  access).
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceLshift}{PyObject *o1,
-                                                     PyObject *o2}
-  Returns the result of left shifting \var{o1} by \var{o2} on success,
-  or \NULL{} on failure.  The operation is done \emph{in-place} when
-  \var{o1} supports it.  This is the equivalent of the Python
-  statement \samp{\var{o1} <\code{<=} \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceRshift}{PyObject *o1,
-                                                     PyObject *o2}
-  Returns the result of right shifting \var{o1} by \var{o2} on
-  success, or \NULL{} on failure.  The operation is done
-  \emph{in-place} when \var{o1} supports it.  This is the equivalent
-  of the Python statement \samp{\var{o1} >\code{>=} \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceAnd}{PyObject *o1, PyObject *o2}
-  Returns the ``bitwise and'' of \var{o1} and \var{o2} on success and
-  \NULL{} on failure. The operation is done \emph{in-place} when
-  \var{o1} supports it.  This is the equivalent of the Python
-  statement \samp{\var{o1} \&= \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceXor}{PyObject *o1, PyObject *o2}
-  Returns the ``bitwise exclusive or'' of \var{o1} by \var{o2} on
-  success, or \NULL{} on failure.  The operation is done
-  \emph{in-place} when \var{o1} supports it.  This is the equivalent
-  of the Python statement \samp{\var{o1} \textasciicircum= \var{o2}}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceOr}{PyObject *o1, PyObject *o2}
-  Returns the ``bitwise or'' of \var{o1} and \var{o2} on success, or
-  \NULL{} on failure.  The operation is done \emph{in-place} when
-  \var{o1} supports it.  This is the equivalent of the Python
-  statement \samp{\var{o1} |= \var{o2}}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyNumber_Coerce}{PyObject **p1, PyObject **p2}
-  This function takes the addresses of two variables of type
-  \ctype{PyObject*}.  If the objects pointed to by \code{*\var{p1}}
-  and \code{*\var{p2}} have the same type, increment their reference
-  count and return \code{0} (success). If the objects can be converted
-  to a common numeric type, replace \code{*p1} and \code{*p2} by their
-  converted value (with 'new' reference counts), and return \code{0}.
-  If no conversion is possible, or if some other error occurs, return
-  \code{-1} (failure) and don't increment the reference counts.  The
-  call \code{PyNumber_Coerce(\&o1, \&o2)} is equivalent to the Python
-  statement \samp{\var{o1}, \var{o2} = coerce(\var{o1}, \var{o2})}.
-  \bifuncindex{coerce}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Int}{PyObject *o}
-  Returns the \var{o} converted to an integer object on success, or
-  \NULL{} on failure.  If the argument is outside the integer range
-  a long object will be returned instead. This is the equivalent
-  of the Python expression \samp{int(\var{o})}.\bifuncindex{int}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Long}{PyObject *o}
-  Returns the \var{o} converted to a long integer object on success,
-  or \NULL{} on failure.  This is the equivalent of the Python
-  expression \samp{long(\var{o})}.\bifuncindex{long}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Float}{PyObject *o}
-  Returns the \var{o} converted to a float object on success, or
-  \NULL{} on failure.  This is the equivalent of the Python expression
-  \samp{float(\var{o})}.\bifuncindex{float}
-\end{cfuncdesc}
-
-
-\section{Sequence Protocol \label{sequence}}
-
-\begin{cfuncdesc}{int}{PySequence_Check}{PyObject *o}
-  Return \code{1} if the object provides sequence protocol, and
-  \code{0} otherwise.  This function always succeeds.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PySequence_Size}{PyObject *o}
-  Returns the number of objects in sequence \var{o} on success, and
-  \code{-1} on failure.  For objects that do not provide sequence
-  protocol, this is equivalent to the Python expression
-  \samp{len(\var{o})}.\bifuncindex{len}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PySequence_Length}{PyObject *o}
-  Alternate name for \cfunction{PySequence_Size()}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PySequence_Concat}{PyObject *o1, PyObject *o2}
-  Return the concatenation of \var{o1} and \var{o2} on success, and
-  \NULL{} on failure.   This is the equivalent of the Python
-  expression \samp{\var{o1} + \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PySequence_Repeat}{PyObject *o, int count}
-  Return the result of repeating sequence object \var{o} \var{count}
-  times, or \NULL{} on failure.  This is the equivalent of the Python
-  expression \samp{\var{o} * \var{count}}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PySequence_InPlaceConcat}{PyObject *o1,
-                                                       PyObject *o2}
-  Return the concatenation of \var{o1} and \var{o2} on success, and
-  \NULL{} on failure.  The operation is done \emph{in-place} when
-  \var{o1} supports it.  This is the equivalent of the Python
-  expression \samp{\var{o1} += \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PySequence_InPlaceRepeat}{PyObject *o, int count}
-  Return the result of repeating sequence object \var{o} \var{count}
-  times, or \NULL{} on failure.  The operation is done \emph{in-place}
-  when \var{o} supports it.  This is the equivalent of the Python
-  expression \samp{\var{o} *= \var{count}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PySequence_GetItem}{PyObject *o, int i}
-  Return the \var{i}th element of \var{o}, or \NULL{} on failure.
-  This is the equivalent of the Python expression
-  \samp{\var{o}[\var{i}]}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PySequence_GetSlice}{PyObject *o, int i1, int i2}
-  Return the slice of sequence object \var{o} between \var{i1} and
-  \var{i2}, or \NULL{} on failure. This is the equivalent of the
-  Python expression \samp{\var{o}[\var{i1}:\var{i2}]}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PySequence_SetItem}{PyObject *o, int i, PyObject *v}
-  Assign object \var{v} to the \var{i}th element of \var{o}.  Returns
-  \code{-1} on failure.  This is the equivalent of the Python
-  statement \samp{\var{o}[\var{i}] = \var{v}}.  This function \emph{does not}
-  steal a reference to \var{v}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PySequence_DelItem}{PyObject *o, int i}
-  Delete the \var{i}th element of object \var{o}.  Returns \code{-1}
-  on failure.  This is the equivalent of the Python statement
-  \samp{del \var{o}[\var{i}]}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PySequence_SetSlice}{PyObject *o, int i1,
-                                            int i2, PyObject *v}
-  Assign the sequence object \var{v} to the slice in sequence object
-  \var{o} from \var{i1} to \var{i2}.  This is the equivalent of the
-  Python statement \samp{\var{o}[\var{i1}:\var{i2}] = \var{v}}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PySequence_DelSlice}{PyObject *o, int i1, int i2}
-  Delete the slice in sequence object \var{o} from \var{i1} to
-  \var{i2}.  Returns \code{-1} on failure.  This is the equivalent of
-  the Python statement \samp{del \var{o}[\var{i1}:\var{i2}]}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PySequence_Tuple}{PyObject *o}
-  Returns the \var{o} as a tuple on success, and \NULL{} on failure.
-  This is equivalent to the Python expression \samp{tuple(\var{o})}.
-  \bifuncindex{tuple}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PySequence_Count}{PyObject *o, PyObject *value}
-  Return the number of occurrences of \var{value} in \var{o}, that is,
-  return the number of keys for which \code{\var{o}[\var{key}] ==
-  \var{value}}.  On failure, return \code{-1}.  This is equivalent to
-  the Python expression \samp{\var{o}.count(\var{value})}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PySequence_Contains}{PyObject *o, PyObject *value}
-  Determine if \var{o} contains \var{value}.  If an item in \var{o} is
-  equal to \var{value}, return \code{1}, otherwise return \code{0}.
-  On error, return \code{-1}.  This is equivalent to the Python
-  expression \samp{\var{value} in \var{o}}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PySequence_Index}{PyObject *o, PyObject *value}
-  Return the first index \var{i} for which \code{\var{o}[\var{i}] ==
-  \var{value}}.  On error, return \code{-1}.    This is equivalent to
-  the Python expression \samp{\var{o}.index(\var{value})}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PySequence_List}{PyObject *o}
-  Return a list object with the same contents as the arbitrary
-  sequence \var{o}.  The returned list is guaranteed to be new.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PySequence_Tuple}{PyObject *o}
-  Return a tuple object with the same contents as the arbitrary
-  sequence \var{o}.  If \var{o} is a tuple, a new reference will be
-  returned, otherwise a tuple will be constructed with the appropriate
-  contents.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PySequence_Fast}{PyObject *o, const char *m}
-  Returns the sequence \var{o} as a tuple, unless it is already a
-  tuple or list, in which case \var{o} is returned.  Use
-  \cfunction{PySequence_Fast_GET_ITEM()} to access the members of the
-  result.  Returns \NULL{} on failure.  If the object is not a
-  sequence, raises \exception{TypeError} with \var{m} as the message
-  text.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PySequence_Fast_GET_ITEM}{PyObject *o, int i}
-  Return the \var{i}th element of \var{o}, assuming that \var{o} was
-  returned by \cfunction{PySequence_Fast()}, \var{o} is not \NULL,
-  and that \var{i} is within bounds.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PySequence_ITEM}{PyObject *o, int i}
-  Return the \var{i}th element of \var{o} or \NULL{} on failure.
-  Macro form of \cfunction{PySequence_GetItem()} but without checking
-  that \cfunction{PySequence_Check(\var{o})} is true and without
-  adjustment for negative indices.
-  \versionadded{2.3}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PySequence_Fast_GET_SIZE}{PyObject *o}
-  Returns the length of \var{o}, assuming that \var{o} was
-  returned by \cfunction{PySequence_Fast()} and that \var{o} is
-  not \NULL.  The size can also be gotten by calling
-  \cfunction{PySequence_Size()} on \var{o}, but
-  \cfunction{PySequence_Fast_GET_SIZE()} is faster because it can
-  assume \var{o} is a list or tuple.
-\end{cfuncdesc}
-
-
-\section{Mapping Protocol \label{mapping}}
-
-\begin{cfuncdesc}{int}{PyMapping_Check}{PyObject *o}
-  Return \code{1} if the object provides mapping protocol, and
-  \code{0} otherwise.  This function always succeeds.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyMapping_Length}{PyObject *o}
-  Returns the number of keys in object \var{o} on success, and
-  \code{-1} on failure.  For objects that do not provide mapping
-  protocol, this is equivalent to the Python expression
-  \samp{len(\var{o})}.\bifuncindex{len}
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyMapping_DelItemString}{PyObject *o, char *key}
-  Remove the mapping for object \var{key} from the object \var{o}.
-  Return \code{-1} on failure.  This is equivalent to the Python
-  statement \samp{del \var{o}[\var{key}]}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyMapping_DelItem}{PyObject *o, PyObject *key}
-  Remove the mapping for object \var{key} from the object \var{o}.
-  Return \code{-1} on failure.  This is equivalent to the Python
-  statement \samp{del \var{o}[\var{key}]}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyMapping_HasKeyString}{PyObject *o, char *key}
-  On success, return \code{1} if the mapping object has the key
-  \var{key} and \code{0} otherwise.  This is equivalent to the Python
-  expression \samp{\var{o}.has_key(\var{key})}.  This function always
-  succeeds.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyMapping_HasKey}{PyObject *o, PyObject *key}
-  Return \code{1} if the mapping object has the key \var{key} and
-  \code{0} otherwise.  This is equivalent to the Python expression
-  \samp{\var{o}.has_key(\var{key})}.  This function always succeeds.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyMapping_Keys}{PyObject *o}
-  On success, return a list of the keys in object \var{o}.  On
-  failure, return \NULL. This is equivalent to the Python expression
-  \samp{\var{o}.keys()}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyMapping_Values}{PyObject *o}
-  On success, return a list of the values in object \var{o}.  On
-  failure, return \NULL. This is equivalent to the Python expression
-  \samp{\var{o}.values()}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyMapping_Items}{PyObject *o}
-  On success, return a list of the items in object \var{o}, where each
-  item is a tuple containing a key-value pair.  On failure, return
-  \NULL. This is equivalent to the Python expression
-  \samp{\var{o}.items()}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyMapping_GetItemString}{PyObject *o, char *key}
-  Return element of \var{o} corresponding to the object \var{key} or
-  \NULL{} on failure. This is the equivalent of the Python expression
-  \samp{\var{o}[\var{key}]}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyMapping_SetItemString}{PyObject *o, char *key,
-                                                PyObject *v}
-  Map the object \var{key} to the value \var{v} in object \var{o}.
-  Returns \code{-1} on failure.  This is the equivalent of the Python
-  statement \samp{\var{o}[\var{key}] = \var{v}}.
-\end{cfuncdesc}
-
-
-\section{Iterator Protocol \label{iterator}}
-
-\versionadded{2.2}
-
-There are only a couple of functions specifically for working with
-iterators.
-
-\begin{cfuncdesc}{int}{PyIter_Check}{PyObject *o}
-  Return true if the object \var{o} supports the iterator protocol.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyIter_Next}{PyObject *o}
-  Return the next value from the iteration \var{o}.  If the object is
-  an iterator, this retrieves the next value from the iteration, and
-  returns \NULL{} with no exception set if there are no remaining
-  items.  If the object is not an iterator, \exception{TypeError} is
-  raised, or if there is an error in retrieving the item, returns
-  \NULL{} and passes along the exception.
-\end{cfuncdesc}
-
-To write a loop which iterates over an iterator, the C code should
-look something like this:
-
-\begin{verbatim}
-PyObject *iterator = PyObject_GetIter(obj);
-PyObject *item;
-
-if (iterator == NULL) {
-    /* propagate error */
-}
-
-while (item = PyIter_Next(iterator)) {
-    /* do something with item */
-    ...
-    /* release reference when done */
-    Py_DECREF(item);
-}
-
-Py_DECREF(iterator);
-
-if (PyErr_Occurred()) {
-    /* propagate error */
-}
-else {
-    /* continue doing useful work */
-}
-\end{verbatim}
-
-
-\section{Buffer Protocol \label{abstract-buffer}}
-
-\begin{cfuncdesc}{int}{PyObject_AsCharBuffer}{PyObject *obj,
-                                              const char **buffer,
-                                              int *buffer_len}
-  Returns a pointer to a read-only memory location useable as character-
-  based input.  The \var{obj} argument must support the single-segment
-  character buffer interface.  On success, returns \code{0}, sets
-  \var{buffer} to the memory location and \var{buffer_len} to the buffer
-  length.  Returns \code{-1} and sets a \exception{TypeError} on error.
-  \versionadded{1.6}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyObject_AsReadBuffer}{PyObject *obj,
-                                              const char **buffer,
-                                              int *buffer_len}
-  Returns a pointer to a read-only memory location containing
-  arbitrary data.  The \var{obj} argument must support the
-  single-segment readable buffer interface.  On success, returns
-  \code{0}, sets \var{buffer} to the memory location and \var{buffer_len}
-  to the buffer length.  Returns \code{-1} and sets a
-  \exception{TypeError} on error.
-  \versionadded{1.6}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyObject_CheckReadBuffer}{PyObject *o}
-  Returns \code{1} if \var{o} supports the single-segment readable
-  buffer interface.  Otherwise returns \code{0}.
-  \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyObject_AsWriteBuffer}{PyObject *obj,
-                                               char **buffer,
-                                               int *buffer_len}
-  Returns a pointer to a writeable memory location.  The \var{obj}
-  argument must support the single-segment, character buffer
-  interface.  On success, returns \code{0}, sets \var{buffer} to the
-  memory location and \var{buffer_len} to the buffer length.  Returns
-  \code{-1} and sets a \exception{TypeError} on error.
-  \versionadded{1.6}
-\end{cfuncdesc}

Doc/api/concrete.tex

-\chapter{Concrete Objects Layer \label{concrete}}
-
-
-The functions in this chapter are specific to certain Python object
-types.  Passing them an object of the wrong type is not a good idea;
-if you receive an object from a Python program and you are not sure
-that it has the right type, you must perform a type check first;
-for example, to check that an object is a dictionary, use
-\cfunction{PyDict_Check()}.  The chapter is structured like the
-``family tree'' of Python object types.
-
-\warning{While the functions described in this chapter carefully check
-the type of the objects which are passed in, many of them do not check
-for \NULL{} being passed instead of a valid object.  Allowing \NULL{}
-to be passed in can cause memory access violations and immediate
-termination of the interpreter.}
-
-
-\section{Fundamental Objects \label{fundamental}}
-
-This section describes Python type objects and the singleton object
-\code{None}.
-
-
-\subsection{Type Objects \label{typeObjects}}
-
-\obindex{type}
-\begin{ctypedesc}{PyTypeObject}
-  The C structure of the objects used to describe built-in types.
-\end{ctypedesc}
-
-\begin{cvardesc}{PyObject*}{PyType_Type}
-  This is the type object for type objects; it is the same object as
-  \code{types.TypeType} in the Python layer.
-  \withsubitem{(in module types)}{\ttindex{TypeType}}
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyType_Check}{PyObject *o}
-  Returns true if the object \var{o} is a type object, including
-  instances of types derived from the standard type object.  Returns
-  false in all other cases.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyType_CheckExact}{PyObject *o}
-  Returns true if the object \var{o} is a type object, but not a
-  subtype of the standard type object.  Returns false in all other
-  cases.
-  \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyType_HasFeature}{PyObject *o, int feature}
-  Returns true if the type object \var{o} sets the feature
-  \var{feature}.  Type features are denoted by single bit flags.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyType_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}
-  Returns true if \var{a} is a subtype of \var{b}.
-  \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyType_GenericAlloc}{PyTypeObject *type,
-                                                  int nitems}
-  \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyType_GenericNew}{PyTypeObject *type,
-                                            PyObject *args, PyObject *kwds}
-  \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyType_Ready}{PyTypeObject *type}
-  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.  Returns \code{0}
-  on success, or returns \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}
-
-
-\section{Numeric Objects \label{numericObjects}}
-
-\obindex{numeric}
-
-
-\subsection{Plain Integer Objects \label{intObjects}}
-
-\obindex{integer}
-\begin{ctypedesc}{PyIntObject}
-  This subtype of \ctype{PyObject} represents a Python integer
-  object.
-\end{ctypedesc}
-
-\begin{cvardesc}{PyTypeObject}{PyInt_Type}
-  This instance of \ctype{PyTypeObject} represents the Python plain
-  integer type.  This is the same object as \code{types.IntType}.
-  \withsubitem{(in modules types)}{\ttindex{IntType}}
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyInt_Check}{PyObject* o}
-  Returns true if \var{o} is of type \cdata{PyInt_Type} or a subtype
-  of \cdata{PyInt_Type}.
-  \versionchanged[Allowed subtypes to be accepted]{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyInt_CheckExact}{PyObject* o}
-  Returns true if \var{o} is of type \cdata{PyInt_Type}, but not a
-  subtype of \cdata{PyInt_Type}.
-  \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyInt_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}
-  Creates a new integer object with a value of \var{ival}.
-
-  The current implementation keeps an array of integer objects for all
-  integers between \code{-1} and \code{100}, when you create an int in
-  that range you actually just get back a reference to the existing
-  object. So it should be possible to change the value of \code{1}.  I
-  suspect the behaviour of Python in this case is undefined. :-)
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{long}{PyInt_AsLong}{PyObject *io}
-  Will first attempt to cast the object to a \ctype{PyIntObject}, if
-  it is not already one, and then return its value.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{long}{PyInt_AS_LONG}{PyObject *io}
-  Returns the value of the object \var{io}.  No error checking is
-  performed.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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 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}{long}{PyInt_GetMax}{}
-  Returns the system's idea of the largest integer it can handle
-  (\constant{LONG_MAX}\ttindex{LONG_MAX}, as defined in the system
-  header files).
-\end{cfuncdesc}
-
-
-\subsection{Long Integer Objects \label{longObjects}}
-
-\obindex{long integer}
-\begin{ctypedesc}{PyLongObject}
-  This subtype of \ctype{PyObject} represents a Python long integer
-  object.
-\end{ctypedesc}
-
-\begin{cvardesc}{PyTypeObject}{PyLong_Type}
-  This instance of \ctype{PyTypeObject} represents the Python long
-  integer type.  This is the same object as \code{types.LongType}.
-  \withsubitem{(in modules types)}{\ttindex{LongType}}
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyLong_Check}{PyObject *p}
-  Returns true if its argument is a \ctype{PyLongObject} or a subtype
-  of \ctype{PyLongObject}.
-  \versionchanged[Allowed subtypes to be accepted]{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyLong_CheckExact}{PyObject *p}
-  Returns true if its argument is a \ctype{PyLongObject}, but not a
-  subtype of \ctype{PyLongObject}.
-  \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyLong_FromLong}{long v}
-  Returns a new \ctype{PyLongObject} object from \var{v}, or \NULL{}
-  on failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyLong_FromUnsignedLong}{unsigned long v}
-  Returns a new \ctype{PyLongObject} object from a C \ctype{unsigned
-  long}, or \NULL{} on failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyLong_FromLongLong}{long long v}
-  Returns a new \ctype{PyLongObject} object from a C \ctype{long long},
-  or \NULL{} on failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyLong_FromUnsignedLongLong}{unsigned long long v}
-  Returns a new \ctype{PyLongObject} object from a C \ctype{unsigned
-  long long}, or \NULL{} on failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyLong_FromDouble}{double v}
-  Returns a new \ctype{PyLongObject} object from the integer part of
-  \var{v}, or \NULL{} on failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyLong_FromString}{char *str, char **pend,
-                                                int base}
-  Return a new \ctype{PyLongObject} based on the string value in
-  \var{str}, which is interpreted according to the radix in
-  \var{base}.  If \var{pend} is non-\NULL, \code{*\var{pend}} will
-  point to the first character in \var{str} which follows the
-  representation of the number.  If \var{base} is \code{0}, the radix
-  will be determined 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,
-                                                 int length, int base}
-  Convert a sequence of Unicode digits to a Python long integer
-  value.  The first parameter, \var{u}, points to the first character
-  of the Unicode string, \var{length} gives the number of characters,
-  and \var{base} is the radix for the conversion.  The radix must be
-  in the range [2, 36]; if it is out of range, \exception{ValueError}
-  will be raised.
-  \versionadded{1.6}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyLong_FromVoidPtr}{void *p}
-  Create a Python integer or long integer from the pointer \var{p}.
-  The pointer value can be retrieved from the resulting value using
-  \cfunction{PyLong_AsVoidPtr()}.
-  \versionadded{1.5.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{long}{PyLong_AsLong}{PyObject *pylong}
-  Returns a C \ctype{long} representation of the contents of
-  \var{pylong}.  If \var{pylong} is greater than
-  \constant{LONG_MAX}\ttindex{LONG_MAX}, an \exception{OverflowError}
-  is raised.
-  \withsubitem{(built-in exception)}{\ttindex{OverflowError}}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{unsigned long}{PyLong_AsUnsignedLong}{PyObject *pylong}
-  Returns a C \ctype{unsigned long} representation of the contents of
-  \var{pylong}.  If \var{pylong} is greater than
-  \constant{ULONG_MAX}\ttindex{ULONG_MAX}, an
-  \exception{OverflowError} is raised.
-  \withsubitem{(built-in exception)}{\ttindex{OverflowError}}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{long long}{PyLong_AsLongLong}{PyObject *pylong}
-  Return a C \ctype{long long} from a Python long integer.  If
-  \var{pylong} cannot be represented as a \ctype{long long}, an
-  \exception{OverflowError} will be raised.
-  \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{unsigned long long}{PyLong_AsUnsignedLongLong}{PyObject
-                                                                 *pylong}
-  Return a C \ctype{unsigned long long} from a Python long integer.
-  If \var{pylong} cannot be represented as an \ctype{unsigned long
-  long}, an \exception{OverflowError} will be raised if the value is
-  positive, or a \exception{TypeError} will be raised if the value is
-  negative.
-  \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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 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}
-  Returns a C \ctype{double} representation of the contents of
-  \var{pylong}.  If \var{pylong} cannot be approximately represented
-  as a \ctype{double}, an \exception{OverflowError} exception is
-  raised and \code{-1.0} will be returned.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void*}{PyLong_AsVoidPtr}{PyObject *pylong}
-  Convert a Python integer or long integer \var{pylong} to a C
-  \ctype{void} pointer.  If \var{pylong} cannot be converted, an
-  \exception{OverflowError} will be raised.  This is only assured to
-  produce a usable \ctype{void} pointer for values created with
-  \cfunction{PyLong_FromVoidPtr()}.
-  \versionadded{1.5.2}
-\end{cfuncdesc}
-
-
-\subsection{Floating Point Objects \label{floatObjects}}
-
-\obindex{floating point}
-\begin{ctypedesc}{PyFloatObject}
-  This subtype of \ctype{PyObject} represents a Python floating point
-  object.
-\end{ctypedesc}
-
-\begin{cvardesc}{PyTypeObject}{PyFloat_Type}
-  This instance of \ctype{PyTypeObject} represents the Python floating
-  point type.  This is the same object as \code{types.FloatType}.
-  \withsubitem{(in modules types)}{\ttindex{FloatType}}
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyFloat_Check}{PyObject *p}
-  Returns true if its argument is a \ctype{PyFloatObject} or a subtype
-  of \ctype{PyFloatObject}.
-  \versionchanged[Allowed subtypes to be accepted]{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyFloat_CheckExact}{PyObject *p}
-  Returns true if its argument is a \ctype{PyFloatObject}, but not a
-  subtype of \ctype{PyFloatObject}.
-  \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyFloat_FromString}{PyObject *str, char **pend}
-  Creates 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}
-  Creates a \ctype{PyFloatObject} object from \var{v}, or \NULL{} on
-  failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{double}{PyFloat_AsDouble}{PyObject *pyfloat}
-  Returns a C \ctype{double} representation of the contents of
-  \var{pyfloat}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{double}{PyFloat_AS_DOUBLE}{PyObject *pyfloat}
-  Returns a C \ctype{double} representation of the contents of
-  \var{pyfloat}, but without error checking.
-\end{cfuncdesc}
-
-
-\subsection{Complex Number Objects \label{complexObjects}}
-
-\obindex{complex number}
-Python's complex number objects are implemented as two distinct types
-when viewed from the C API:  one is the Python object exposed to
-Python programs, and the other is a C structure which represents the
-actual complex number value.  The API provides functions for working
-with both.
-
-\subsubsection{Complex Numbers as C Structures}
-
-Note that the functions which accept these structures as parameters
-and return them as results do so \emph{by value} rather than
-dereferencing them through pointers.  This is consistent throughout
-the API.
-
-\begin{ctypedesc}{Py_complex}
-  The C structure which corresponds to the value portion of a Python
-  complex number object.  Most of the functions for dealing with
-  complex number objects use structures of this type as input or
-  output values, as appropriate.  It is defined as:
-
-\begin{verbatim}
-typedef struct {
-   double real;
-   double imag;
-} Py_complex;
-\end{verbatim}
-\end{ctypedesc}
-
-\begin{cfuncdesc}{Py_complex}{_Py_c_sum}{Py_complex left, Py_complex right}
-  Return the sum of two complex numbers, using the C
-  \ctype{Py_complex} representation.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{Py_complex}{_Py_c_diff}{Py_complex left, Py_complex right}
-  Return the difference between two complex numbers, using the C
-  \ctype{Py_complex} representation.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{Py_complex}{_Py_c_neg}{Py_complex complex}
-  Return the negation of the complex number \var{complex}, using the C
-  \ctype{Py_complex} representation.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{Py_complex}{_Py_c_prod}{Py_complex left, Py_complex right}
-  Return the product of two complex numbers, using the C
-  \ctype{Py_complex} representation.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{Py_complex}{_Py_c_quot}{Py_complex dividend,
-                                          Py_complex divisor}
-  Return the quotient of two complex numbers, using the C
-  \ctype{Py_complex} representation.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{Py_complex}{_Py_c_pow}{Py_complex num, Py_complex exp}
-  Return the exponentiation of \var{num} by \var{exp}, using the C
-  \ctype{Py_complex} representation.
-\end{cfuncdesc}
-
-
-\subsubsection{Complex Numbers as Python Objects}
-
-\begin{ctypedesc}{PyComplexObject}
-  This subtype of \ctype{PyObject} represents a Python complex number
-  object.
-\end{ctypedesc}
-
-\begin{cvardesc}{PyTypeObject}{PyComplex_Type}
-  This instance of \ctype{PyTypeObject} represents the Python complex
-  number type.
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyComplex_Check}{PyObject *p}
-  Returns true if its argument is a \ctype{PyComplexObject} or a
-  subtype of \ctype{PyComplexObject}.
-  \versionchanged[Allowed subtypes to be accepted]{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyComplex_CheckExact}{PyObject *p}
-  Returns true if its argument is a \ctype{PyComplexObject}, but not a
-  subtype of \ctype{PyComplexObject}.
-  \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyComplex_FromCComplex}{Py_complex v}
-  Create a new Python complex number object from a C
-  \ctype{Py_complex} value.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyComplex_FromDoubles}{double real, double imag}
-  Returns a new \ctype{PyComplexObject} object from \var{real} and
-  \var{imag}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{double}{PyComplex_RealAsDouble}{PyObject *op}
-  Returns the real part of \var{op} as a C \ctype{double}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{double}{PyComplex_ImagAsDouble}{PyObject *op}
-  Returns the imaginary part of \var{op} as a C \ctype{double}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{Py_complex}{PyComplex_AsCComplex}{PyObject *op}
-  Returns the \ctype{Py_complex} value of the complex number
-  \var{op}.
-\end{cfuncdesc}
-
-
-
-\section{Sequence Objects \label{sequenceObjects}}
-
-\obindex{sequence}
-Generic operations on sequence objects were discussed in the previous
-chapter; this section deals with the specific kinds of sequence
-objects that are intrinsic to the Python language.
-
-
-\subsection{String Objects \label{stringObjects}}
-
-These functions raise \exception{TypeError} when expecting a string
-parameter and are called with a non-string parameter.
-
-\obindex{string}
-\begin{ctypedesc}{PyStringObject}
-  This subtype of \ctype{PyObject} represents a Python string object.
-\end{ctypedesc}
-
-\begin{cvardesc}{PyTypeObject}{PyString_Type}
-  This instance of \ctype{PyTypeObject} represents the Python string
-  type; it is the same object as \code{types.TypeType} in the Python
-  layer.
-  \withsubitem{(in module types)}{\ttindex{StringType}}.
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyString_Check}{PyObject *o}
-  Returns true if the object \var{o} is a string object or an instance
-  of a subtype of the string type.
-  \versionchanged[Allowed subtypes to be accepted]{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyString_CheckExact}{PyObject *o}
-  Returns true if the object \var{o} is a string object, but not an
-  instance of a subtype of the string type.
-  \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyString_FromString}{const char *v}
-  Returns a new string object with the value \var{v} on success, and
-  \NULL{} on failure.  The parameter \var{v} must not be \NULL; it
-  will not be checked.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyString_FromStringAndSize}{const char *v,
-                                                         int len}
-  Returns a new string object with the value \var{v} and length
-  \var{len} on success, and \NULL{} on failure.  If \var{v} is
-  \NULL, the contents of the string are uninitialized.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyString_FromFormat}{const char *format, ...}
-  Takes a C \cfunction{printf()}-style \var{format} string and a
-  variable number of arguments, calculates the size of the resulting
-  Python string and returns a string with the values formatted into
-  it.  The variable arguments must be C types and must correspond
-  exactly to the format characters in the \var{format} string.  The
-  following format characters are allowed:
-
-  \begin{tableiii}{l|l|l}{member}{Format Characters}{Type}{Comment}
-    \lineiii{\%\%}{\emph{n/a}}{The literal \% character.}
-    \lineiii{\%c}{int}{A single character, represented as an C int.}
-    \lineiii{\%d}{int}{Exactly equivalent to \code{printf("\%d")}.}
-    \lineiii{\%ld}{long}{Exactly equivalent to \code{printf("\%ld")}.}
-    \lineiii{\%i}{int}{Exactly equivalent to \code{printf("\%i")}.}
-    \lineiii{\%x}{int}{Exactly equivalent to \code{printf("\%x")}.}
-    \lineiii{\%s}{char*}{A null-terminated C character array.}
-    \lineiii{\%p}{void*}{The hex representation of a C pointer.
-	Mostly equivalent to \code{printf("\%p")} except that it is
-	guaranteed to start with the literal \code{0x} regardless of
-	what the platform's \code{printf} yields.}
-  \end{tableiii}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyString_FromFormatV}{const char *format,
-                                                   va_list vargs}
-  Identical to \function{PyString_FromFormat()} except that it takes
-  exactly two arguments.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyString_Size}{PyObject *string}
-  Returns the length of the string in string object \var{string}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyString_GET_SIZE}{PyObject *string}
-  Macro form of \cfunction{PyString_Size()} but without error
-  checking.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{char*}{PyString_AsString}{PyObject *string}
-  Returns a 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,
-                                                 int *length}
-  Returns 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_AsString()} returns \NULL{} and
-  raises \exception{TypeError}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyString_Concat}{PyObject **string,
-                                         PyObject *newpart}
-  Creates a new string object in \var{*string} containing the contents
-  of \var{newpart} appended to \var{string}; the caller will own the
-  new reference.  The reference to the old value of \var{string} will
-  be stolen.  If the new string cannot be created, the old reference
-  to \var{string} will still be discarded and the value of
-  \var{*string} will be set to \NULL; the appropriate exception will
-  be set.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyString_ConcatAndDel}{PyObject **string,
-                                               PyObject *newpart}
-  Creates a new string object in \var{*string} containing the contents
-  of \var{newpart} appended to \var{string}.  This version decrements
-  the reference count of \var{newpart}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{_PyString_Resize}{PyObject **string, int newsize}
-  A way to resize a string object even though it is ``immutable''.
-  Only use this to build up a brand new string object; don't use this
-  if the string may already be known in other parts of the code.  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}
-  Returns a new string object from \var{format} and \var{args}.
-  Analogous to \code{\var{format} \%\ \var{args}}.  The \var{args}
-  argument must be a tuple.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyString_InternInPlace}{PyObject **string}
-  Intern the argument \var{*string} in place.  The argument must be
-  the address of a pointer variable pointing to a Python string
-  object.  If there is an existing interned string that is the same as
-  \var{*string}, it sets \var{*string} to it (decrementing the
-  reference count of the old string object and incrementing the
-  reference count of the interned string object), otherwise it leaves
-  \var{*string} alone and interns it (incrementing its reference
-  count).  (Clarification: even though there is a lot of talk about
-  reference counts, think of this function as reference-count-neutral;
-  you own the object after the call if and only if you owned it before
-  the call.)
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyString_InternFromString}{const char *v}
-  A combination of \cfunction{PyString_FromString()} and
-  \cfunction{PyString_InternInPlace()}, returning either a new string
-  object that has been interned, or a new (``owned'') reference to an
-  earlier interned string object with the same value.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyString_Decode}{const char *s,
-                                               int size,
-                                               const char *encoding,
-                                               const char *errors}
-  Creates an object by decoding \var{size} bytes of the encoded
-  buffer \var{s} using the codec registered for
-  \var{encoding}.  \var{encoding} and \var{errors} have the same
-  meaning as the parameters of the same name in the
-  \function{unicode()} built-in function.  The codec to be used is
-  looked up using the Python codec registry.  Returns \NULL{} if
-  an exception was raised by the codec.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyString_AsDecodedObject}{PyObject *str,
-                                               const char *encoding,
-                                               const char *errors}
-  Decodes a string object by passing it to the codec registered for
-  \var{encoding} and returns the result as Python
-  object. \var{encoding} and \var{errors} have the same meaning as the
-  parameters of the same name in the string \method{encode()} method.
-  The codec to be used is looked up using the Python codec registry.
-  Returns \NULL{} if an exception was raised by the codec.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyString_Encode}{const char *s,
-                                               int size,
-                                               const char *encoding,
-                                               const char *errors}
-  Encodes the \ctype{char} buffer of the given size by passing it to
-  the codec registered for \var{encoding} and returns a Python object.
-  \var{encoding} and \var{errors} have the same meaning as the
-  parameters of the same name in the string \method{encode()} method.
-  The codec to be used is looked up using the Python codec
-  registry.  Returns \NULL{} if an exception was raised by the
-  codec.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyString_AsEncodedObject}{PyObject *str,
-                                               const char *encoding,
-                                               const char *errors}
-  Encodes a string object using the codec registered for
-  \var{encoding} and returns the result as Python object.
-  \var{encoding} and \var{errors} have the same meaning as the
-  parameters of the same name in the string \method{encode()} method.
-  The codec to be used is looked up using the Python codec registry.
-  Returns \NULL{} if an exception was raised by the codec.
-\end{cfuncdesc}
-
-
-\subsection{Unicode Objects \label{unicodeObjects}}
-\sectionauthor{Marc-Andre Lemburg}{mal@lemburg.com}
-
-%--- Unicode Type -------------------------------------------------------
-
-These are the basic Unicode object types used for the Unicode
-implementation in Python:
-
-\begin{ctypedesc}{Py_UNICODE}
-  This type represents a 16-bit unsigned storage type which is used by
-  Python internally as basis for holding Unicode ordinals.  On
-  platforms where \ctype{wchar_t} is available and also has 16-bits,
-  \ctype{Py_UNICODE} is a typedef alias for \ctype{wchar_t} to enhance
-  native platform compatibility.  On all other platforms,
-  \ctype{Py_UNICODE} is a typedef alias for \ctype{unsigned short}.
-\end{ctypedesc}
-
-\begin{ctypedesc}{PyUnicodeObject}
-  This subtype of \ctype{PyObject} represents a Python Unicode object.
-\end{ctypedesc}
-
-\begin{cvardesc}{PyTypeObject}{PyUnicode_Type}
-  This instance of \ctype{PyTypeObject} represents the Python Unicode
-  type.
-\end{cvardesc}
-
-The following APIs are really C macros and can be used to do fast
-checks and to access internal read-only data of Unicode objects:
-
-\begin{cfuncdesc}{int}{PyUnicode_Check}{PyObject *o}
-  Returns true if the object \var{o} is a Unicode object or an
-  instance of a Unicode subtype.
-  \versionchanged[Allowed subtypes to be accepted]{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyUnicode_CheckExact}{PyObject *o}
-  Returns true if the object \var{o} is a Unicode object, but not an
-  instance of a subtype.
-  \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyUnicode_GET_SIZE}{PyObject *o}
-  Returns the size of the object.  \var{o} has to be a
-  \ctype{PyUnicodeObject} (not checked).
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyUnicode_GET_DATA_SIZE}{PyObject *o}
-  Returns the size of the object's internal buffer in bytes.  \var{o}
-  has to be a \ctype{PyUnicodeObject} (not checked).
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{Py_UNICODE*}{PyUnicode_AS_UNICODE}{PyObject *o}
-  Returns a pointer to the internal \ctype{Py_UNICODE} buffer of the
-  object.  \var{o} has to be a \ctype{PyUnicodeObject} (not checked).
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{const char*}{PyUnicode_AS_DATA}{PyObject *o}
-  Returns a pointer to the internal buffer of the object.
-  \var{o} has to be a \ctype{PyUnicodeObject} (not checked).
-\end{cfuncdesc}
-
-% --- Unicode character properties ---------------------------------------
-
-Unicode provides many different character properties. The most often
-needed ones are available through these macros which are mapped to C
-functions depending on the Python configuration.
-
-\begin{cfuncdesc}{int}{Py_UNICODE_ISSPACE}{Py_UNICODE ch}
-  Returns 1/0 depending on whether \var{ch} is a whitespace
-  character.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{Py_UNICODE_ISLOWER}{Py_UNICODE ch}
-  Returns 1/0 depending on whether \var{ch} is a lowercase character.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{Py_UNICODE_ISUPPER}{Py_UNICODE ch}
-  Returns 1/0 depending on whether \var{ch} is an uppercase
-  character.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{Py_UNICODE_ISTITLE}{Py_UNICODE ch}
-  Returns 1/0 depending on whether \var{ch} is a titlecase character.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{Py_UNICODE_ISLINEBREAK}{Py_UNICODE ch}
-  Returns 1/0 depending on whether \var{ch} is a linebreak character.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{Py_UNICODE_ISDECIMAL}{Py_UNICODE ch}
-  Returns 1/0 depending on whether \var{ch} is a decimal character.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{Py_UNICODE_ISDIGIT}{Py_UNICODE ch}
-  Returns 1/0 depending on whether \var{ch} is a digit character.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{Py_UNICODE_ISNUMERIC}{Py_UNICODE ch}
-  Returns 1/0 depending on whether \var{ch} is a numeric character.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{Py_UNICODE_ISALPHA}{Py_UNICODE ch}
-  Returns 1/0 depending on whether \var{ch} is an alphabetic
-  character.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{Py_UNICODE_ISALNUM}{Py_UNICODE ch}
-  Returns 1/0 depending on whether \var{ch} is an alphanumeric
-  character.
-\end{cfuncdesc}
-
-These APIs can be used for fast direct character conversions:
-
-\begin{cfuncdesc}{Py_UNICODE}{Py_UNICODE_TOLOWER}{Py_UNICODE ch}
-  Returns the character \var{ch} converted to lower case.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{Py_UNICODE}{Py_UNICODE_TOUPPER}{Py_UNICODE ch}
-  Returns the character \var{ch} converted to upper case.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{Py_UNICODE}{Py_UNICODE_TOTITLE}{Py_UNICODE ch}
-  Returns the character \var{ch} converted to title case.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{Py_UNICODE_TODECIMAL}{Py_UNICODE ch}
-  Returns the character \var{ch} converted to a decimal positive
-  integer.  Returns \code{-1} if this is not possible.  Does not raise
-  exceptions.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{Py_UNICODE_TODIGIT}{Py_UNICODE ch}
-  Returns the character \var{ch} converted to a single digit integer.
-  Returns \code{-1} if this is not possible.  Does not raise
-  exceptions.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{double}{Py_UNICODE_TONUMERIC}{Py_UNICODE ch}
-  Returns the character \var{ch} converted to a (positive) double.
-  Returns \code{-1.0} if this is not possible.  Does not raise
-  exceptions.
-\end{cfuncdesc}
-
-% --- Plain Py_UNICODE ---------------------------------------------------
-
-To create Unicode objects and access their basic sequence properties,
-use these APIs:
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_FromUnicode}{const Py_UNICODE *u,
-                                                    int size}
-  Create a Unicode Object from the Py_UNICODE buffer \var{u} of the
-  given size. \var{u} may be \NULL{} which causes the contents to be
-  undefined. It is the user's responsibility to fill in the needed
-  data.  The buffer is copied into the new object. If the buffer is
-  not \NULL, the return value might be a shared object. Therefore,
-  modification of the resulting Unicode object is only allowed when
-  \var{u} is \NULL.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{Py_UNICODE*}{PyUnicode_AsUnicode}{PyObject *unicode}
-  Return a read-only pointer to the Unicode object's internal
-  \ctype{Py_UNICODE} buffer, \NULL{} if \var{unicode} is not a Unicode
-  object.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyUnicode_GetSize}{PyObject *unicode}
-  Return the length of the Unicode object.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_FromEncodedObject}{PyObject *obj,
-                                                      const char *encoding,
-                                                      const char *errors}
-  Coerce an encoded object \var{obj} to an Unicode object and return a
-  reference with incremented refcount.
-
-  Coercion is done in the following way:
-
-\begin{enumerate}
-\item  Unicode objects are passed back as-is with incremented
-       refcount. \note{These cannot be decoded; passing a non-\NULL{}
-       value for encoding will result in a \exception{TypeError}.}
-
-\item String and other char buffer compatible objects are decoded
-      according to the given encoding and using the error handling
-      defined by errors.  Both can be \NULL{} to have the interface
-      use the default values (see the next section for details).
-
-\item All other objects cause an exception.
-\end{enumerate}
-
-  The API returns \NULL{} if there was an error.  The caller is
-  responsible for decref'ing the returned objects.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_FromObject}{PyObject *obj}
-  Shortcut for \code{PyUnicode_FromEncodedObject(obj, NULL, "strict")}
-  which is used throughout the interpreter whenever coercion to
-  Unicode is needed.
-\end{cfuncdesc}
-
-% --- wchar_t support for platforms which support it ---------------------
-
-If the platform supports \ctype{wchar_t} and provides a header file
-wchar.h, Python can interface directly to this type using the
-following functions. Support is optimized if Python's own
-\ctype{Py_UNICODE} type is identical to the system's \ctype{wchar_t}.
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_FromWideChar}{const wchar_t *w,
-                                                     int size}
-  Create a Unicode object from the \ctype{wchar_t} buffer \var{w} of
-  the given size.  Returns \NULL{} on failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyUnicode_AsWideChar}{PyUnicodeObject *unicode,
-                                             wchar_t *w,
-                                             int size}
-  Copies the Unicode object contents into the \ctype{wchar_t} buffer
-  \var{w}.  At most \var{size} \ctype{wchar_t} characters are copied.
-  Returns the number of \ctype{wchar_t} characters copied or -1 in
-  case of an error.
-\end{cfuncdesc}
-
-
-\subsubsection{Built-in Codecs \label{builtinCodecs}}
-
-Python provides a set of builtin codecs which are written in C
-for speed. All of these codecs are directly usable via the
-following functions.
-
-Many of the following APIs take two arguments encoding and
-errors. These parameters encoding and errors have the same semantics
-as the ones of the builtin unicode() Unicode object constructor.
-
-Setting encoding to \NULL{} causes the default encoding to be used
-which is \ASCII.  The file system calls should use
-\cdata{Py_FileSystemDefaultEncoding} as the encoding for file
-names. This variable should be treated as read-only: On some systems,
-it will be a pointer to a static string, on others, it will change at
-run-time, e.g. when the application invokes setlocale.
-
-Error handling is set by errors which may also be set to \NULL{}
-meaning to use the default handling defined for the codec.  Default
-error handling for all builtin codecs is ``strict''
-(\exception{ValueError} is raised).
-
-The codecs all use a similar interface.  Only deviation from the
-following generic ones are documented for simplicity.
-
-% --- Generic Codecs -----------------------------------------------------
-
-These are the generic codec APIs:
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_Decode}{const char *s,
-                                               int size,
-                                               const char *encoding,
-                                               const char *errors}
-  Create a Unicode object by decoding \var{size} bytes of the encoded
-  string \var{s}.  \var{encoding} and \var{errors} have the same
-  meaning as the parameters of the same name in the
-  \function{unicode()} builtin function.  The codec to be used is
-  looked up using the Python codec registry.  Returns \NULL{} if an
-  exception was raised by the codec.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_Encode}{const Py_UNICODE *s,
-                                               int size,
-                                               const char *encoding,
-                                               const char *errors}
-  Encodes the \ctype{Py_UNICODE} buffer of the given size and returns
-  a Python string object.  \var{encoding} and \var{errors} have the
-  same meaning as the parameters of the same name in the Unicode
-  \method{encode()} method.  The codec to be used is looked up using
-  the Python codec registry.  Returns \NULL{} if an exception was
-  raised by the codec.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_AsEncodedString}{PyObject *unicode,
-                                               const char *encoding,
-                                               const char *errors}
-  Encodes a Unicode object and returns the result as Python string
-  object. \var{encoding} and \var{errors} have the same meaning as the
-  parameters of the same name in the Unicode \method{encode()} method.
-  The codec to be used is looked up using the Python codec registry.
-  Returns \NULL{} if an exception was raised by the codec.
-\end{cfuncdesc}
-
-% --- UTF-8 Codecs -------------------------------------------------------
-
-These are the UTF-8 codec APIs:
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF8}{const char *s,
-                                               int size,
-                                               const char *errors}
-  Creates a Unicode object by decoding \var{size} bytes of the UTF-8
-  encoded string \var{s}. Returns \NULL{} if an exception was raised
-  by the codec.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeUTF8}{const Py_UNICODE *s,
-                                               int size,
-                                               const char *errors}
-  Encodes the \ctype{Py_UNICODE} buffer of the given size using UTF-8
-  and returns a Python string object.  Returns \NULL{} if an exception
-  was raised by the codec.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_AsUTF8String}{PyObject *unicode}
-  Encodes a Unicode objects using UTF-8 and returns the result as
-  Python string object.  Error handling is ``strict''.  Returns
-  \NULL{} if an exception was raised by the codec.
-\end{cfuncdesc}
-
-% --- UTF-16 Codecs ------------------------------------------------------ */
-
-These are the UTF-16 codec APIs:
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF16}{const char *s,
-                                               int size,
-                                               const char *errors,
-                                               int *byteorder}
-  Decodes \var{length} bytes from a UTF-16 encoded buffer string and
-  returns the corresponding Unicode object.  \var{errors} (if
-  non-\NULL) defines the error handling. It defaults to ``strict''.
-
-  If \var{byteorder} is non-\NULL, the decoder starts decoding using
-  the given byte order:
-
-\begin{verbatim}
-   *byteorder == -1: little endian
-   *byteorder == 0:  native order
-   *byteorder == 1:  big endian
-\end{verbatim}
-