Sun Jan 20 10:31:00 CET 2008

Author: georg.brandl
Date: Sun Jan 20 10:30:57 2008
New Revision: 60126

Added:
   python/branches/py3k/Doc/c-api/allocation.rst
   python/branches/py3k/Doc/c-api/arg.rst
   python/branches/py3k/Doc/c-api/bool.rst
   python/branches/py3k/Doc/c-api/buffer.rst
   python/branches/py3k/Doc/c-api/cell.rst
   python/branches/py3k/Doc/c-api/cobject.rst
   python/branches/py3k/Doc/c-api/complex.rst
   python/branches/py3k/Doc/c-api/conversion.rst
   python/branches/py3k/Doc/c-api/datetime.rst
   python/branches/py3k/Doc/c-api/descriptor.rst
   python/branches/py3k/Doc/c-api/dict.rst
   python/branches/py3k/Doc/c-api/file.rst
   python/branches/py3k/Doc/c-api/float.rst
   python/branches/py3k/Doc/c-api/function.rst
   python/branches/py3k/Doc/c-api/gcsupport.rst
   python/branches/py3k/Doc/c-api/gen.rst
   python/branches/py3k/Doc/c-api/import.rst
   python/branches/py3k/Doc/c-api/iter.rst
   python/branches/py3k/Doc/c-api/iterator.rst
   python/branches/py3k/Doc/c-api/list.rst
   python/branches/py3k/Doc/c-api/long.rst
   python/branches/py3k/Doc/c-api/mapping.rst
   python/branches/py3k/Doc/c-api/marshal.rst
   python/branches/py3k/Doc/c-api/method.rst
   python/branches/py3k/Doc/c-api/module.rst
   python/branches/py3k/Doc/c-api/none.rst
   python/branches/py3k/Doc/c-api/number.rst
   python/branches/py3k/Doc/c-api/objbuffer.rst
   python/branches/py3k/Doc/c-api/object.rst
   python/branches/py3k/Doc/c-api/objimpl.rst
   python/branches/py3k/Doc/c-api/reflection.rst
   python/branches/py3k/Doc/c-api/sequence.rst
   python/branches/py3k/Doc/c-api/set.rst
   python/branches/py3k/Doc/c-api/slice.rst
   python/branches/py3k/Doc/c-api/string.rst
   python/branches/py3k/Doc/c-api/structures.rst
   python/branches/py3k/Doc/c-api/sys.rst
   python/branches/py3k/Doc/c-api/tuple.rst
   python/branches/py3k/Doc/c-api/type.rst
   python/branches/py3k/Doc/c-api/typeobj.rst
   python/branches/py3k/Doc/c-api/unicode.rst
   python/branches/py3k/Doc/c-api/weakref.rst
Modified:
   python/branches/py3k/Doc/c-api/abstract.rst
   python/branches/py3k/Doc/c-api/concrete.rst
   python/branches/py3k/Doc/c-api/utilities.rst
Log:
Split C API docs in Py3k branch.


Modified: python/branches/py3k/Doc/c-api/abstract.rst
==============================================================================

--- python/branches/py3k/Doc/c-api/abstract.rst	(original)
+++ python/branches/py3k/Doc/c-api/abstract.rst	Sun Jan 20 10:30:57 2008
@@ -1,6 +1,5 @@
 .. highlightlang:: c
 
-
 .. _abstract:
 
 **********************
@@ -16,928 +15,11 @@
 initialized, such as a list object that has been created by :cfunc:`PyList_New`,
 but whose items have not been set to some non-\ ``NULL`` value yet.
 
+.. toctree::
 
-.. _object:
-
-Object Protocol
-===============
-
-
-.. cfunction:: int PyObject_Print(PyObject *o, FILE *fp, int flags)
-
-   Print an object *o*, on file *fp*.  Returns ``-1`` on error.  The flags argument
-   is used to enable certain printing options.  The only option currently supported
-   is :const:`Py_PRINT_RAW`; if given, the :func:`str` of the object is written
-   instead of the :func:`repr`.
-
-
-.. cfunction:: int PyObject_HasAttr(PyObject *o, PyObject *attr_name)
-
-   Returns ``1`` if *o* has the attribute *attr_name*, and ``0`` otherwise.  This
-   is equivalent to the Python expression ``hasattr(o, attr_name)``.  This function
-   always succeeds.
-
-
-.. cfunction:: int PyObject_HasAttrString(PyObject *o, const char *attr_name)
-
-   Returns ``1`` if *o* has the attribute *attr_name*, and ``0`` otherwise.  This
-   is equivalent to the Python expression ``hasattr(o, attr_name)``.  This function
-   always succeeds.
-
-
-.. cfunction:: PyObject* PyObject_GetAttr(PyObject *o, PyObject *attr_name)
-
-   Retrieve an attribute named *attr_name* from object *o*. Returns the attribute
-   value on success, or *NULL* on failure.  This is the equivalent of the Python
-   expression ``o.attr_name``.
-
-
-.. cfunction:: PyObject* PyObject_GetAttrString(PyObject *o, const char *attr_name)
-
-   Retrieve an attribute named *attr_name* from object *o*. Returns the attribute
-   value on success, or *NULL* on failure. This is the equivalent of the Python
-   expression ``o.attr_name``.
-
-
-.. cfunction:: int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v)
-
-   Set the value of the attribute named *attr_name*, for object *o*, to the value
-   *v*. Returns ``-1`` on failure.  This is the equivalent of the Python statement
-   ``o.attr_name = v``.
-
-
-.. cfunction:: int PyObject_SetAttrString(PyObject *o, const char *attr_name, PyObject *v)
-
-   Set the value of the attribute named *attr_name*, for object *o*, to the value
-   *v*. Returns ``-1`` on failure.  This is the equivalent of the Python statement
-   ``o.attr_name = v``.
-
-
-.. cfunction:: int PyObject_DelAttr(PyObject *o, PyObject *attr_name)
-
-   Delete attribute named *attr_name*, for object *o*. Returns ``-1`` on failure.
-   This is the equivalent of the Python statement ``del o.attr_name``.
-
-
-.. cfunction:: int PyObject_DelAttrString(PyObject *o, const char *attr_name)
-
-   Delete attribute named *attr_name*, for object *o*. Returns ``-1`` on failure.
-   This is the equivalent of the Python statement ``del o.attr_name``.
-
-
-.. cfunction:: PyObject* PyObject_RichCompare(PyObject *o1, PyObject *o2, int opid)
-
-   Compare the values of *o1* and *o2* using the operation specified by *opid*,
-   which must be one of :const:`Py_LT`, :const:`Py_LE`, :const:`Py_EQ`,
-   :const:`Py_NE`, :const:`Py_GT`, or :const:`Py_GE`, corresponding to ``<``,
-   ``<=``, ``==``, ``!=``, ``>``, or ``>=`` respectively. This is the equivalent of
-   the Python expression ``o1 op o2``, where ``op`` is the operator corresponding
-   to *opid*. Returns the value of the comparison on success, or *NULL* on failure.
-
-
-.. cfunction:: int PyObject_RichCompareBool(PyObject *o1, PyObject *o2, int opid)
-
-   Compare the values of *o1* and *o2* using the operation specified by *opid*,
-   which must be one of :const:`Py_LT`, :const:`Py_LE`, :const:`Py_EQ`,
-   :const:`Py_NE`, :const:`Py_GT`, or :const:`Py_GE`, corresponding to ``<``,
-   ``<=``, ``==``, ``!=``, ``>``, or ``>=`` respectively. Returns ``-1`` on error,
-   ``0`` if the result is false, ``1`` otherwise. This is the equivalent of the
-   Python expression ``o1 op o2``, where ``op`` is the operator corresponding to
-   *opid*.
-
-
-.. cfunction:: int PyObject_Cmp(PyObject *o1, PyObject *o2, int *result)
-
-   .. index:: builtin: cmp
-
-   Compare the values of *o1* and *o2* using a routine provided by *o1*, if one
-   exists, otherwise with a routine provided by *o2*.  The result of the comparison
-   is returned in *result*.  Returns ``-1`` on failure.  This is the equivalent of
-   the Python statement ``result = cmp(o1, o2)``.
-
-
-.. cfunction:: int PyObject_Compare(PyObject *o1, PyObject *o2)
-
-   .. index:: builtin: cmp
-
-   Compare the values of *o1* and *o2* using a routine provided by *o1*, if one
-   exists, otherwise with a routine provided by *o2*.  Returns the result of the
-   comparison on success.  On error, the value returned is undefined; use
-   :cfunc:`PyErr_Occurred` to detect an error.  This is equivalent to the Python
-   expression ``cmp(o1, o2)``.
-
-
-.. cfunction:: PyObject* PyObject_Repr(PyObject *o)
-
-   .. index:: builtin: repr
-
-   Compute a string representation of object *o*.  Returns the string
-   representation on success, *NULL* on failure.  This is the equivalent of the
-   Python expression ``repr(o)``.  Called by the :func:`repr` built-in function and
-   by reverse quotes.
-
-
-.. cfunction:: PyObject* PyObject_Str(PyObject *o)
-
-   .. index:: builtin: str
-
-   Compute a string representation of object *o*.  Returns the string
-   representation on success, *NULL* on failure.  This is the equivalent of the
-   Python expression ``str(o)``.  Called by the :func:`str` built-in function
-   and, therefore, by the :func:`print` function.
-
-
-.. cfunction:: PyObject* PyObject_Unicode(PyObject *o)
-
-   .. index:: builtin: unicode
-
-   Compute a Unicode string representation of object *o*.  Returns the Unicode
-   string representation on success, *NULL* on failure. This is the equivalent of
-   the Python expression ``unicode(o)``.  Called by the :func:`unicode` built-in
-   function.
-
-
-.. cfunction:: int PyObject_IsInstance(PyObject *inst, PyObject *cls)
-
-   Returns ``1`` if *inst* is an instance of the class *cls* or a subclass of
-   *cls*, or ``0`` if not.  On error, returns ``-1`` and sets an exception.  If
-   *cls* is a type object rather than a class object, :cfunc:`PyObject_IsInstance`
-   returns ``1`` if *inst* is of type *cls*.  If *cls* is a tuple, the check will
-   be done against every entry in *cls*. The result will be ``1`` when at least one
-   of the checks returns ``1``, otherwise it will be ``0``. If *inst* is not a
-   class instance and *cls* is neither a type object, nor a class object, nor a
-   tuple, *inst* must have a :attr:`__class__` attribute --- the class relationship
-   of the value of that attribute with *cls* will be used to determine the result
-   of this function.
-
-
-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 *B* is a subclass of
-*A*, if *A* is *B*, :cfunc:`PyObject_IsSubclass` returns true.  If *A* and *B*
-are different objects, *B*'s :attr:`__bases__` attribute is searched in a
-depth-first fashion for *A* --- the presence of the :attr:`__bases__` attribute
-is considered sufficient for this determination.
-
-
-.. cfunction:: int PyObject_IsSubclass(PyObject *derived, PyObject *cls)
-
-   Returns ``1`` if the class *derived* is identical to or derived from the class
-   *cls*, otherwise returns ``0``.  In case of an error, returns ``-1``. If *cls*
-   is a tuple, the check will be done against every entry in *cls*. The result will
-   be ``1`` when at least one of the checks returns ``1``, otherwise it will be
-   ``0``. If either *derived* or *cls* is not an actual class object (or tuple),
-   this function uses the generic algorithm described above.
-
-
-.. cfunction:: int PyCallable_Check(PyObject *o)
-
-   Determine if the object *o* is callable.  Return ``1`` if the object is callable
-   and ``0`` otherwise.  This function always succeeds.
-
-
-.. cfunction:: PyObject* PyObject_Call(PyObject *callable_object, PyObject *args, PyObject *kw)
-
-   Call a callable Python object *callable_object*, with arguments given by the
-   tuple *args*, and named arguments given by the dictionary *kw*. If no named
-   arguments are needed, *kw* may be *NULL*. *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
-   ``callable_object(*args, **kw)``.
-
-
-.. cfunction:: PyObject* PyObject_CallObject(PyObject *callable_object, PyObject *args)
-
-   Call a callable Python object *callable_object*, with arguments given by the
-   tuple *args*.  If no arguments are needed, then *args* may be *NULL*.  Returns
-   the result of the call on success, or *NULL* on failure.  This is the equivalent
-   of the Python expression ``callable_object(*args)``.
-
-
-.. cfunction:: PyObject* PyObject_CallFunction(PyObject *callable, char *format, ...)
-
-   Call a callable Python object *callable*, with a variable number of C arguments.
-   The C arguments are described using a :cfunc:`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 ``callable(*args)``. Note that if you only
-   pass :ctype:`PyObject \*` args, :cfunc:`PyObject_CallFunctionObjArgs` is a
-   faster alternative.
-
-
-.. cfunction:: PyObject* PyObject_CallMethod(PyObject *o, char *method, char *format, ...)
-
-   Call the method named *method* of object *o* with a variable number of C
-   arguments.  The C arguments are described by a :cfunc:`Py_BuildValue` format
-   string that should  produce a tuple.  The format may be *NULL*, indicating that
-   no arguments are provided. Returns the result of the call on success, or *NULL*
-   on failure.  This is the equivalent of the Python expression ``o.method(args)``.
-   Note that if you only pass :ctype:`PyObject \*` args,
-   :cfunc:`PyObject_CallMethodObjArgs` is a faster alternative.
-
-
-.. cfunction:: PyObject* PyObject_CallFunctionObjArgs(PyObject *callable, ..., NULL)
-
-   Call a callable Python object *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.
-
-
-.. cfunction:: PyObject* PyObject_CallMethodObjArgs(PyObject *o, PyObject *name, ..., NULL)
-
-   Calls a method of the object *o*, where the name of the method is given as a
-   Python string object in *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.
-
-
-.. cfunction:: long PyObject_Hash(PyObject *o)
-
-   .. index:: builtin: hash
-
-   Compute and return the hash value of an object *o*.  On failure, return ``-1``.
-   This is the equivalent of the Python expression ``hash(o)``.
-
-
-.. cfunction:: int PyObject_IsTrue(PyObject *o)
-
-   Returns ``1`` if the object *o* is considered to be true, and ``0`` otherwise.
-   This is equivalent to the Python expression ``not not o``.  On failure, return
-   ``-1``.
-
-
-.. cfunction:: int PyObject_Not(PyObject *o)
-
-   Returns ``0`` if the object *o* is considered to be true, and ``1`` otherwise.
-   This is equivalent to the Python expression ``not o``.  On failure, return
-   ``-1``.
-
-
-.. cfunction:: PyObject* PyObject_Type(PyObject *o)
-
-   .. index:: builtin: type
-
-   When *o* is non-*NULL*, returns a type object corresponding to the object type
-   of object *o*. On failure, raises :exc:`SystemError` and returns *NULL*.  This
-   is equivalent to the Python expression ``type(o)``. This function increments the
-   reference count of the return value. There's really no reason to use this
-   function instead of the common expression ``o->ob_type``, which returns a
-   pointer of type :ctype:`PyTypeObject\*`, except when the incremented reference
-   count is needed.
-
-
-.. cfunction:: int PyObject_TypeCheck(PyObject *o, PyTypeObject *type)
-
-   Return true if the object *o* is of type *type* or a subtype of *type*.  Both
-   parameters must be non-*NULL*.
-
-
-.. cfunction:: Py_ssize_t PyObject_Length(PyObject *o)
-               Py_ssize_t PyObject_Size(PyObject *o)
-
-   .. index:: builtin: len
-
-   Return the length of object *o*.  If the object *o* provides either the sequence
-   and mapping protocols, the sequence length is returned.  On error, ``-1`` is
-   returned.  This is the equivalent to the Python expression ``len(o)``.
-
-
-.. cfunction:: PyObject* PyObject_GetItem(PyObject *o, PyObject *key)
-
-   Return element of *o* corresponding to the object *key* or *NULL* on failure.
-   This is the equivalent of the Python expression ``o[key]``.
-
-
-.. cfunction:: int PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v)
-
-   Map the object *key* to the value *v*.  Returns ``-1`` on failure.  This is the
-   equivalent of the Python statement ``o[key] = v``.
-
-
-.. cfunction:: int PyObject_DelItem(PyObject *o, PyObject *key)
-
-   Delete the mapping for *key* from *o*.  Returns ``-1`` on failure. This is the
-   equivalent of the Python statement ``del o[key]``.
-
-
-.. cfunction:: PyObject* PyObject_Dir(PyObject *o)
-
-   This is equivalent to the Python expression ``dir(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 ``dir()``,
-   returning the names of the current locals; in this case, if no execution frame
-   is active then *NULL* is returned but :cfunc:`PyErr_Occurred` will return false.
-
-
-.. cfunction:: PyObject* PyObject_GetIter(PyObject *o)
-
-   This is equivalent to the Python expression ``iter(o)``. It returns a new
-   iterator for the object argument, or the object  itself if the object is already
-   an iterator.  Raises :exc:`TypeError` and returns *NULL* if the object cannot be
-   iterated.
-
-
-.. _number:
-
-Number Protocol
-===============
-
-
-.. cfunction:: int PyNumber_Check(PyObject *o)
-
-   Returns ``1`` if the object *o* provides numeric protocols, and false otherwise.
-   This function always succeeds.
-
-
-.. cfunction:: PyObject* PyNumber_Add(PyObject *o1, PyObject *o2)
-
-   Returns the result of adding *o1* and *o2*, or *NULL* on failure.  This is the
-   equivalent of the Python expression ``o1 + o2``.
-
-
-.. cfunction:: PyObject* PyNumber_Subtract(PyObject *o1, PyObject *o2)
-
-   Returns the result of subtracting *o2* from *o1*, or *NULL* on failure.  This is
-   the equivalent of the Python expression ``o1 - o2``.
-
-
-.. cfunction:: PyObject* PyNumber_Multiply(PyObject *o1, PyObject *o2)
-
-   Returns the result of multiplying *o1* and *o2*, or *NULL* on failure.  This is
-   the equivalent of the Python expression ``o1 * o2``.
-
-
-.. cfunction:: PyObject* PyNumber_Divide(PyObject *o1, PyObject *o2)
-
-   Returns the result of dividing *o1* by *o2*, or *NULL* on failure.  This is the
-   equivalent of the Python expression ``o1 / o2``.
-
-
-.. cfunction:: PyObject* PyNumber_FloorDivide(PyObject *o1, PyObject *o2)
-
-   Return the floor of *o1* divided by *o2*, or *NULL* on failure.  This is
-   equivalent to the "classic" division of integers.
-
-
-.. cfunction:: PyObject* PyNumber_TrueDivide(PyObject *o1, PyObject *o2)
-
-   Return a reasonable approximation for the mathematical value of *o1* divided by
-   *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.
-
-
-.. cfunction:: PyObject* PyNumber_Remainder(PyObject *o1, PyObject *o2)
-
-   Returns the remainder of dividing *o1* by *o2*, or *NULL* on failure.  This is
-   the equivalent of the Python expression ``o1 % o2``.
-
-
-.. cfunction:: PyObject* PyNumber_Divmod(PyObject *o1, PyObject *o2)
-
-   .. index:: builtin: divmod
-
-   See the built-in function :func:`divmod`. Returns *NULL* on failure.  This is
-   the equivalent of the Python expression ``divmod(o1, o2)``.
-
-
-.. cfunction:: PyObject* PyNumber_Power(PyObject *o1, PyObject *o2, PyObject *o3)
-
-   .. index:: builtin: pow
-
-   See the built-in function :func:`pow`. Returns *NULL* on failure.  This is the
-   equivalent of the Python expression ``pow(o1, o2, o3)``, where *o3* is optional.
-   If *o3* is to be ignored, pass :cdata:`Py_None` in its place (passing *NULL* for
-   *o3* would cause an illegal memory access).
-
-
-.. cfunction:: PyObject* PyNumber_Negative(PyObject *o)
-
-   Returns the negation of *o* on success, or *NULL* on failure. This is the
-   equivalent of the Python expression ``-o``.
-
-
-.. cfunction:: PyObject* PyNumber_Positive(PyObject *o)
-
-   Returns *o* on success, or *NULL* on failure.  This is the equivalent of the
-   Python expression ``+o``.
-
-
-.. cfunction:: PyObject* PyNumber_Absolute(PyObject *o)
-
-   .. index:: builtin: abs
-
-   Returns the absolute value of *o*, or *NULL* on failure.  This is the equivalent
-   of the Python expression ``abs(o)``.
-
-
-.. cfunction:: PyObject* PyNumber_Invert(PyObject *o)
-
-   Returns the bitwise negation of *o* on success, or *NULL* on failure.  This is
-   the equivalent of the Python expression ``~o``.
-
-
-.. cfunction:: PyObject* PyNumber_Lshift(PyObject *o1, PyObject *o2)
-
-   Returns the result of left shifting *o1* by *o2* on success, or *NULL* on
-   failure.  This is the equivalent of the Python expression ``o1 << o2``.
-
-
-.. cfunction:: PyObject* PyNumber_Rshift(PyObject *o1, PyObject *o2)
-
-   Returns the result of right shifting *o1* by *o2* on success, or *NULL* on
-   failure.  This is the equivalent of the Python expression ``o1 >> o2``.
-
-
-.. cfunction:: PyObject* PyNumber_And(PyObject *o1, PyObject *o2)
-
-   Returns the "bitwise and" of *o1* and *o2* on success and *NULL* on failure.
-   This is the equivalent of the Python expression ``o1 & o2``.
-
-
-.. cfunction:: PyObject* PyNumber_Xor(PyObject *o1, PyObject *o2)
-
-   Returns the "bitwise exclusive or" of *o1* by *o2* on success, or *NULL* on
-   failure.  This is the equivalent of the Python expression ``o1 ^ o2``.
-
-
-.. cfunction:: PyObject* PyNumber_Or(PyObject *o1, PyObject *o2)
-
-   Returns the "bitwise or" of *o1* and *o2* on success, or *NULL* on failure.
-   This is the equivalent of the Python expression ``o1 | o2``.
-
-
-.. cfunction:: PyObject* PyNumber_InPlaceAdd(PyObject *o1, PyObject *o2)
-
-   Returns the result of adding *o1* and *o2*, or *NULL* on failure.  The operation
-   is done *in-place* when *o1* supports it.  This is the equivalent of the Python
-   statement ``o1 += o2``.
-
-
-.. cfunction:: PyObject* PyNumber_InPlaceSubtract(PyObject *o1, PyObject *o2)
-
-   Returns the result of subtracting *o2* from *o1*, or *NULL* on failure.  The
-   operation is done *in-place* when *o1* supports it.  This is the equivalent of
-   the Python statement ``o1 -= o2``.
-
-
-.. cfunction:: PyObject* PyNumber_InPlaceMultiply(PyObject *o1, PyObject *o2)
-
-   Returns the result of multiplying *o1* and *o2*, or *NULL* on failure.  The
-   operation is done *in-place* when *o1* supports it.  This is the equivalent of
-   the Python statement ``o1 *= o2``.
-
-
-.. cfunction:: PyObject* PyNumber_InPlaceDivide(PyObject *o1, PyObject *o2)
-
-   Returns the result of dividing *o1* by *o2*, or *NULL* on failure.  The
-   operation is done *in-place* when *o1* supports it. This is the equivalent of
-   the Python statement ``o1 /= o2``.
-
-
-.. cfunction:: PyObject* PyNumber_InPlaceFloorDivide(PyObject *o1, PyObject *o2)
-
-   Returns the mathematical floor of dividing *o1* by *o2*, or *NULL* on failure.
-   The operation is done *in-place* when *o1* supports it.  This is the equivalent
-   of the Python statement ``o1 //= o2``.
-
-
-.. cfunction:: PyObject* PyNumber_InPlaceTrueDivide(PyObject *o1, PyObject *o2)
-
-   Return a reasonable approximation for the mathematical value of *o1* divided by
-   *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 *in-place* when *o1* supports it.
-
-
-.. cfunction:: PyObject* PyNumber_InPlaceRemainder(PyObject *o1, PyObject *o2)
-
-   Returns the remainder of dividing *o1* by *o2*, or *NULL* on failure.  The
-   operation is done *in-place* when *o1* supports it.  This is the equivalent of
-   the Python statement ``o1 %= o2``.
-
-
-.. cfunction:: PyObject* PyNumber_InPlacePower(PyObject *o1, PyObject *o2, PyObject *o3)
-
-   .. index:: builtin: pow
-
-   See the built-in function :func:`pow`. Returns *NULL* on failure.  The operation
-   is done *in-place* when *o1* supports it.  This is the equivalent of the Python
-   statement ``o1 **= o2`` when o3 is :cdata:`Py_None`, or an in-place variant of
-   ``pow(o1, o2, o3)`` otherwise. If *o3* is to be ignored, pass :cdata:`Py_None`
-   in its place (passing *NULL* for *o3* would cause an illegal memory access).
-
-
-.. cfunction:: PyObject* PyNumber_InPlaceLshift(PyObject *o1, PyObject *o2)
-
-   Returns the result of left shifting *o1* by *o2* on success, or *NULL* on
-   failure.  The operation is done *in-place* when *o1* supports it.  This is the
-   equivalent of the Python statement ``o1 <<= o2``.
-
-
-.. cfunction:: PyObject* PyNumber_InPlaceRshift(PyObject *o1, PyObject *o2)
-
-   Returns the result of right shifting *o1* by *o2* on success, or *NULL* on
-   failure.  The operation is done *in-place* when *o1* supports it.  This is the
-   equivalent of the Python statement ``o1 >>= o2``.
-
-
-.. cfunction:: PyObject* PyNumber_InPlaceAnd(PyObject *o1, PyObject *o2)
-
-   Returns the "bitwise and" of *o1* and *o2* on success and *NULL* on failure. The
-   operation is done *in-place* when *o1* supports it.  This is the equivalent of
-   the Python statement ``o1 &= o2``.
-
-
-.. cfunction:: PyObject* PyNumber_InPlaceXor(PyObject *o1, PyObject *o2)
-
-   Returns the "bitwise exclusive or" of *o1* by *o2* on success, or *NULL* on
-   failure.  The operation is done *in-place* when *o1* supports it.  This is the
-   equivalent of the Python statement ``o1 ^= o2``.
-
-
-.. cfunction:: PyObject* PyNumber_InPlaceOr(PyObject *o1, PyObject *o2)
-
-   Returns the "bitwise or" of *o1* and *o2* on success, or *NULL* on failure.  The
-   operation is done *in-place* when *o1* supports it.  This is the equivalent of
-   the Python statement ``o1 |= o2``.
-
-
-.. cfunction:: PyObject* PyNumber_Int(PyObject *o)
-
-   .. index:: builtin: int
-
-   Returns the *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 ``int(o)``.
-
-
-.. cfunction:: PyObject* PyNumber_Long(PyObject *o)
-
-   .. index:: builtin: long
-
-   Returns the *o* converted to an integer object on success, or *NULL* on
-   failure.  This is the equivalent of the Python expression ``long(o)``.
-
-
-.. cfunction:: PyObject* PyNumber_Float(PyObject *o)
-
-   .. index:: builtin: float
-
-   Returns the *o* converted to a float object on success, or *NULL* on failure.
-   This is the equivalent of the Python expression ``float(o)``.
-
-
-.. cfunction:: PyObject* PyNumber_Index(PyObject *o)
-
-   Returns the *o* converted to a Python int or long on success or *NULL* with a
-   TypeError exception raised on failure.
-
-
-.. cfunction:: Py_ssize_t PyNumber_AsSsize_t(PyObject *o, PyObject *exc)
-
-   Returns *o* converted to a Py_ssize_t value if *o* can be interpreted as an
-   integer. If *o* can be converted to a Python int or long but the attempt to
-   convert to a Py_ssize_t value would raise an :exc:`OverflowError`, then the
-   *exc* argument is the type of exception that will be raised (usually
-   :exc:`IndexError` or :exc:`OverflowError`).  If *exc* is *NULL*, then the
-   exception is cleared and the value is clipped to *PY_SSIZE_T_MIN* for a negative
-   integer or *PY_SSIZE_T_MAX* for a positive integer.
-
-
-.. cfunction:: int PyIndex_Check(PyObject *o)
-
-   Returns True if *o* is an index integer (has the nb_index slot of  the
-   tp_as_number structure filled in).
-
-
-.. _sequence:
-
-Sequence Protocol
-=================
-
-
-.. cfunction:: int PySequence_Check(PyObject *o)
-
-   Return ``1`` if the object provides sequence protocol, and ``0`` otherwise.
-   This function always succeeds.
-
-
-.. cfunction:: Py_ssize_t PySequence_Size(PyObject *o)
-
-   .. index:: builtin: len
-
-   Returns the number of objects in sequence *o* on success, and ``-1`` on failure.
-   For objects that do not provide sequence protocol, this is equivalent to the
-   Python expression ``len(o)``.
-
-
-.. cfunction:: Py_ssize_t PySequence_Length(PyObject *o)
-
-   Alternate name for :cfunc:`PySequence_Size`.
-
-
-.. cfunction:: PyObject* PySequence_Concat(PyObject *o1, PyObject *o2)
-
-   Return the concatenation of *o1* and *o2* on success, and *NULL* on failure.
-   This is the equivalent of the Python expression ``o1 + o2``.
-
-
-.. cfunction:: PyObject* PySequence_Repeat(PyObject *o, Py_ssize_t count)
-
-   Return the result of repeating sequence object *o* *count* times, or *NULL* on
-   failure.  This is the equivalent of the Python expression ``o * count``.
-
-
-.. cfunction:: PyObject* PySequence_InPlaceConcat(PyObject *o1, PyObject *o2)
-
-   Return the concatenation of *o1* and *o2* on success, and *NULL* on failure.
-   The operation is done *in-place* when *o1* supports it.  This is the equivalent
-   of the Python expression ``o1 += o2``.
-
-
-.. cfunction:: PyObject* PySequence_InPlaceRepeat(PyObject *o, Py_ssize_t count)
-
-   Return the result of repeating sequence object *o* *count* times, or *NULL* on
-   failure.  The operation is done *in-place* when *o* supports it.  This is the
-   equivalent of the Python expression ``o *= count``.
-
-
-.. cfunction:: PyObject* PySequence_GetItem(PyObject *o, Py_ssize_t i)
-
-   Return the *i*th element of *o*, or *NULL* on failure. This is the equivalent of
-   the Python expression ``o[i]``.
-
-
-.. cfunction:: PyObject* PySequence_GetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2)
-
-   Return the slice of sequence object *o* between *i1* and *i2*, or *NULL* on
-   failure. This is the equivalent of the Python expression ``o[i1:i2]``.
-
-
-.. cfunction:: int PySequence_SetItem(PyObject *o, Py_ssize_t i, PyObject *v)
-
-   Assign object *v* to the *i*th element of *o*.  Returns ``-1`` on failure.  This
-   is the equivalent of the Python statement ``o[i] = v``.  This function *does
-   not* steal a reference to *v*.
-
-
-.. cfunction:: int PySequence_DelItem(PyObject *o, Py_ssize_t i)
-
-   Delete the *i*th element of object *o*.  Returns ``-1`` on failure.  This is the
-   equivalent of the Python statement ``del o[i]``.
-
-
-.. cfunction:: int PySequence_SetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2, PyObject *v)
-
-   Assign the sequence object *v* to the slice in sequence object *o* from *i1* to
-   *i2*.  This is the equivalent of the Python statement ``o[i1:i2] = v``.
-
-
-.. cfunction:: int PySequence_DelSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2)
-
-   Delete the slice in sequence object *o* from *i1* to *i2*.  Returns ``-1`` on
-   failure.  This is the equivalent of the Python statement ``del o[i1:i2]``.
-
-
-.. cfunction:: Py_ssize_t PySequence_Count(PyObject *o, PyObject *value)
-
-   Return the number of occurrences of *value* in *o*, that is, return the number
-   of keys for which ``o[key] == value``.  On failure, return ``-1``.  This is
-   equivalent to the Python expression ``o.count(value)``.
-
-
-.. cfunction:: int PySequence_Contains(PyObject *o, PyObject *value)
-
-   Determine if *o* contains *value*.  If an item in *o* is equal to *value*,
-   return ``1``, otherwise return ``0``. On error, return ``-1``.  This is
-   equivalent to the Python expression ``value in o``.
-
-
-.. cfunction:: Py_ssize_t PySequence_Index(PyObject *o, PyObject *value)
-
-   Return the first index *i* for which ``o[i] == value``.  On error, return
-   ``-1``.    This is equivalent to the Python expression ``o.index(value)``.
-
-
-.. cfunction:: PyObject* PySequence_List(PyObject *o)
-
-   Return a list object with the same contents as the arbitrary sequence *o*.  The
-   returned list is guaranteed to be new.
-
-
-.. cfunction:: PyObject* PySequence_Tuple(PyObject *o)
-
-   .. index:: builtin: tuple
-
-   Return a tuple object with the same contents as the arbitrary sequence *o* or
-   *NULL* on failure.  If *o* is a tuple, a new reference will be returned,
-   otherwise a tuple will be constructed with the appropriate contents.  This is
-   equivalent to the Python expression ``tuple(o)``.
-
-
-.. cfunction:: PyObject* PySequence_Fast(PyObject *o, const char *m)
-
-   Returns the sequence *o* as a tuple, unless it is already a tuple or list, in
-   which case *o* is returned.  Use :cfunc:`PySequence_Fast_GET_ITEM` to access the
-   members of the result.  Returns *NULL* on failure.  If the object is not a
-   sequence, raises :exc:`TypeError` with *m* as the message text.
-
-
-.. cfunction:: PyObject* PySequence_Fast_GET_ITEM(PyObject *o, Py_ssize_t i)
-
-   Return the *i*th element of *o*, assuming that *o* was returned by
-   :cfunc:`PySequence_Fast`, *o* is not *NULL*, and that *i* is within bounds.
-
-
-.. cfunction:: PyObject** PySequence_Fast_ITEMS(PyObject *o)
-
-   Return the underlying array of PyObject pointers.  Assumes that *o* was returned
-   by :cfunc:`PySequence_Fast` and *o* is not *NULL*.
-
-
-.. cfunction:: PyObject* PySequence_ITEM(PyObject *o, Py_ssize_t i)
-
-   Return the *i*th element of *o* or *NULL* on failure. Macro form of
-   :cfunc:`PySequence_GetItem` but without checking that
-   :cfunc:`PySequence_Check(o)` is true and without adjustment for negative
-   indices.
-
-
-.. cfunction:: Py_ssize_t PySequence_Fast_GET_SIZE(PyObject *o)
-
-   Returns the length of *o*, assuming that *o* was returned by
-   :cfunc:`PySequence_Fast` and that *o* is not *NULL*.  The size can also be
-   gotten by calling :cfunc:`PySequence_Size` on *o*, but
-   :cfunc:`PySequence_Fast_GET_SIZE` is faster because it can assume *o* is a list
-   or tuple.
-
-
-.. _mapping:
-
-Mapping Protocol
-================
-
-
-.. cfunction:: int PyMapping_Check(PyObject *o)
-
-   Return ``1`` if the object provides mapping protocol, and ``0`` otherwise.  This
-   function always succeeds.
-
-
-.. cfunction:: Py_ssize_t PyMapping_Length(PyObject *o)
-
-   .. index:: builtin: len
-
-   Returns the number of keys in object *o* on success, and ``-1`` on failure.  For
-   objects that do not provide mapping protocol, this is equivalent to the Python
-   expression ``len(o)``.
-
-
-.. cfunction:: int PyMapping_DelItemString(PyObject *o, char *key)
-
-   Remove the mapping for object *key* from the object *o*. Return ``-1`` on
-   failure.  This is equivalent to the Python statement ``del o[key]``.
-
-
-.. cfunction:: int PyMapping_DelItem(PyObject *o, PyObject *key)
-
-   Remove the mapping for object *key* from the object *o*. Return ``-1`` on
-   failure.  This is equivalent to the Python statement ``del o[key]``.
-
-
-.. cfunction:: int PyMapping_HasKeyString(PyObject *o, char *key)
-
-   On success, return ``1`` if the mapping object has the key *key* and ``0``
-   otherwise.  This is equivalent to the Python expression ``key in o``.
-   This function always succeeds.
-
-
-.. cfunction:: int PyMapping_HasKey(PyObject *o, PyObject *key)
-
-   Return ``1`` if the mapping object has the key *key* and ``0`` otherwise.  This
-   is equivalent to the Python expression ``key in o``.  This function always
-   succeeds.
-
-
-.. cfunction:: PyObject* PyMapping_Keys(PyObject *o)
-
-   On success, return a list of the keys in object *o*.  On failure, return *NULL*.
-   This is equivalent to the Python expression ``o.keys()``.
-
-
-.. cfunction:: PyObject* PyMapping_Values(PyObject *o)
-
-   On success, return a list of the values in object *o*.  On failure, return
-   *NULL*. This is equivalent to the Python expression ``o.values()``.
-
-
-.. cfunction:: PyObject* PyMapping_Items(PyObject *o)
-
-   On success, return a list of the items in object *o*, where each item is a tuple
-   containing a key-value pair.  On failure, return *NULL*. This is equivalent to
-   the Python expression ``o.items()``.
-
-
-.. cfunction:: PyObject* PyMapping_GetItemString(PyObject *o, char *key)
-
-   Return element of *o* corresponding to the object *key* or *NULL* on failure.
-   This is the equivalent of the Python expression ``o[key]``.
-
-
-.. cfunction:: int PyMapping_SetItemString(PyObject *o, char *key, PyObject *v)
-
-   Map the object *key* to the value *v* in object *o*. Returns ``-1`` on failure.
-   This is the equivalent of the Python statement ``o[key] = v``.
-
-
-.. _iterator:
-
-Iterator Protocol
-=================
-
-There are only a couple of functions specifically for working with iterators.
-
-.. cfunction:: int PyIter_Check(PyObject *o)
-
-   Return true if the object *o* supports the iterator protocol.
-
-
-.. cfunction:: PyObject* PyIter_Next(PyObject *o)
-
-   Return the next value from the iteration *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, :exc:`TypeError` is raised, or if there is an error in retrieving the
-   item, returns *NULL* and passes along the exception.
-
-To write a loop which iterates over an iterator, the C code should look
-something like this::
-
-   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 */
-   }
-
-
-.. _abstract-buffer:
-
-Buffer Protocol
-===============
-
-
-.. cfunction:: int PyObject_AsCharBuffer(PyObject *obj, const char **buffer, Py_ssize_t *buffer_len)
-
-   Returns a pointer to a read-only memory location useable as character- based
-   input.  The *obj* argument must support the single-segment character buffer
-   interface.  On success, returns ``0``, sets *buffer* to the memory location and
-   *buffer_len* to the buffer length.  Returns ``-1`` and sets a :exc:`TypeError`
-   on error.
-
-
-.. cfunction:: int PyObject_AsReadBuffer(PyObject *obj, const void **buffer, Py_ssize_t *buffer_len)
-
-   Returns a pointer to a read-only memory location containing arbitrary data.  The
-   *obj* argument must support the single-segment readable buffer interface.  On
-   success, returns ``0``, sets *buffer* to the memory location and *buffer_len* to
-   the buffer length.  Returns ``-1`` and sets a :exc:`TypeError` on error.
-
-
-.. cfunction:: int PyObject_CheckReadBuffer(PyObject *o)
-
-   Returns ``1`` if *o* supports the single-segment readable buffer interface.
-   Otherwise returns ``0``.
-
-
-.. cfunction:: int PyObject_AsWriteBuffer(PyObject *obj, void **buffer, Py_ssize_t *buffer_len)
-
-   Returns a pointer to a writable memory location.  The *obj* argument must
-   support the single-segment, character buffer interface.  On success, returns
-   ``0``, sets *buffer* to the memory location and *buffer_len* to the buffer
-   length.  Returns ``-1`` and sets a :exc:`TypeError` on error.
-
+   object.rst
+   number.rst
+   sequence.rst
+   mapping.rst
+   iter.rst
+   objbuffer.rst

Added: python/branches/py3k/Doc/c-api/allocation.rst
==============================================================================
--- (empty file)
+++ python/branches/py3k/Doc/c-api/allocation.rst	Sun Jan 20 10:30:57 2008
@@ -0,0 +1,93 @@
+.. highlightlang:: c
+
+.. _allocating-objects:
+
+Allocating Objects on the Heap
+==============================
+
+
+.. cfunction:: PyObject* _PyObject_New(PyTypeObject *type)
+
+
+.. cfunction:: PyVarObject* _PyObject_NewVar(PyTypeObject *type, Py_ssize_t size)
+
+
+.. cfunction:: PyObject* PyObject_Init(PyObject *op, PyTypeObject *type)
+
+   Initialize a newly-allocated object *op* with its type and initial reference.
+   Returns the initialized object.  If *type* indicates that the object
+   participates in the cyclic garbage detector, it is added to the detector's set
+   of observed objects. Other fields of the object are not affected.
+
+
+.. cfunction:: PyVarObject* PyObject_InitVar(PyVarObject *op, PyTypeObject *type, Py_ssize_t size)
+
+   This does everything :cfunc:`PyObject_Init` does, and also initializes the
+   length information for a variable-size object.
+
+
+.. cfunction:: TYPE* PyObject_New(TYPE, PyTypeObject *type)
+
+   Allocate a new Python object using the C structure type *TYPE* and the Python
+   type object *type*.  Fields not defined by the Python object header are not
+   initialized; the object's reference count will be one.  The size of the memory
+   allocation is determined from the :attr:`tp_basicsize` field of the type object.
+
+
+.. cfunction:: TYPE* PyObject_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size)
+
+   Allocate a new Python object using the C structure type *TYPE* and the Python
+   type object *type*.  Fields not defined by the Python object header are not
+   initialized.  The allocated memory allows for the *TYPE* structure plus *size*
+   fields of the size given by the :attr:`tp_itemsize` field of *type*.  This is
+   useful for implementing objects like tuples, which are able to determine their
+   size at construction time.  Embedding the array of fields into the same
+   allocation decreases the number of allocations, improving the memory management
+   efficiency.
+
+
+.. cfunction:: void PyObject_Del(PyObject *op)
+
+   Releases memory allocated to an object using :cfunc:`PyObject_New` or
+   :cfunc:`PyObject_NewVar`.  This is normally called from the :attr:`tp_dealloc`
+   handler specified in the object's type.  The fields of the object should not be
+   accessed after this call as the memory is no longer a valid Python object.
+
+
+.. cfunction:: PyObject* Py_InitModule(char *name, PyMethodDef *methods)
+
+   Create a new module object based on a name and table of functions, returning
+   the new module object; the *methods* argument can be *NULL* if no methods are
+   to be defined for the module.
+
+
+.. cfunction:: PyObject* Py_InitModule3(char *name, PyMethodDef *methods, char *doc)
+
+   Create a new module object based on a name and table of functions, returning
+   the new module object.  The *methods* argument can be *NULL* if no methods
+   are to be defined for the module.  If *doc* is non-*NULL*, it will be used to
+   define the docstring for the module.
+
+
+.. cfunction:: PyObject* Py_InitModule4(char *name, PyMethodDef *methods, char *doc, PyObject *self, int apiver)
+
+   Create a new module object based on a name and table of functions, returning
+   the new module object.  The *methods* argument can be *NULL* if no methods
+   are to be defined for the module.  If *doc* is non-*NULL*, it will be used to
+   define the docstring for the module.  If *self* is non-*NULL*, it will passed
+   to the functions of the module as their (otherwise *NULL*) first parameter.
+   (This was added as an experimental feature, and there are no known uses in
+   the current version of Python.)  For *apiver*, the only value which should be
+   passed is defined by the constant :const:`PYTHON_API_VERSION`.
+
+   .. note::
+
+      Most uses of this function should probably be using the :cfunc:`Py_InitModule3`
+      instead; only use this if you are sure you need it.
+
+
+.. cvar:: PyObject _Py_NoneStruct
+
+   Object which is visible in Python as ``None``.  This should only be accessed
+   using the :cmacro:`Py_None` macro, which evaluates to a pointer to this
+   object.

Added: python/branches/py3k/Doc/c-api/arg.rst
==============================================================================
--- (empty file)
+++ python/branches/py3k/Doc/c-api/arg.rst	Sun Jan 20 10:30:57 2008
@@ -0,0 +1,509 @@
+.. highlightlang:: c
+
+.. _arg-parsing:
+
+Parsing arguments and building values
+=====================================
+
+These functions are useful when creating your own extensions functions and
+methods.  Additional information and examples are available in
+:ref:`extending-index`.
+
+The first three of these functions described, :cfunc:`PyArg_ParseTuple`,
+:cfunc:`PyArg_ParseTupleAndKeywords`, and :cfunc:`PyArg_Parse`, all use *format
+strings* which are used to tell the function about the expected arguments.  The
+format strings use the same syntax for each of these functions.
+
+A format string consists of zero or more "format units."  A format unit
+describes one Python object; it is usually a single character or a parenthesized
+sequence of format units.  With a few exceptions, a format unit that is not a
+parenthesized sequence normally corresponds to a single address argument to
+these functions.  In the following description, the quoted form is the format
+unit; the entry in (round) parentheses is the Python object type that matches
+the format unit; and the entry in [square] brackets is the type of the C
+variable(s) whose address should be passed.
+
+``s`` (string or Unicode object) [const char \*]
+   Convert a Python string or Unicode object to a C pointer to a character string.
+   You must not provide storage for the string itself; a pointer to an existing
+   string is stored into the character pointer variable whose address you pass.
+   The C string is NUL-terminated.  The Python string must not contain embedded NUL
+   bytes; if it does, a :exc:`TypeError` exception is raised. Unicode objects are
+   converted to C strings using the default encoding.  If this conversion fails, a
+   :exc:`UnicodeError` is raised.
+
+``s#`` (string, Unicode or any read buffer compatible object) [const char \*, int]
+   This variant on ``s`` stores into two C variables, the first one a pointer to a
+   character string, the second one its length.  In this case the Python string may
+   contain embedded null bytes.  Unicode objects pass back a pointer to the default
+   encoded string version of the object if such a conversion is possible.  All
+   other read-buffer compatible objects pass back a reference to the raw internal
+   data representation.
+
+``y`` (bytes object) [const char \*]
+   This variant on ``s`` convert a Python bytes object to a C pointer to a
+   character string. The bytes object must not contain embedded NUL bytes; if it
+   does, a :exc:`TypeError` exception is raised.
+
+``y#`` (bytes object) [const char \*, int]
+   This variant on ``s#`` stores into two C variables, the first one a pointer to a
+   character string, the second one its length.  This only accepts bytes objects.
+
+``z`` (string or ``None``) [const char \*]
+   Like ``s``, but the Python object may also be ``None``, in which case the C
+   pointer is set to *NULL*.
+
+``z#`` (string or ``None`` or any read buffer compatible object) [const char \*, int]
+   This is to ``s#`` as ``z`` is to ``s``.
+
+``u`` (Unicode object) [Py_UNICODE \*]
+   Convert a Python Unicode object to a C pointer to a NUL-terminated buffer of
+   16-bit Unicode (UTF-16) data.  As with ``s``, there is no need to provide
+   storage for the Unicode data buffer; a pointer to the existing Unicode data is
+   stored into the :ctype:`Py_UNICODE` pointer variable whose address you pass.
+
+``u#`` (Unicode object) [Py_UNICODE \*, int]
+   This variant on ``u`` stores into two C variables, the first one a pointer to a
+   Unicode data buffer, the second one its length. Non-Unicode objects are handled
+   by interpreting their read-buffer pointer as pointer to a :ctype:`Py_UNICODE`
+   array.
+
+``Z`` (Unicode or ``None``) [Py_UNICODE \*]
+   Like ``s``, but the Python object may also be ``None``, in which case the C
+   pointer is set to *NULL*.
+
+``Z#`` (Unicode or ``None``) [Py_UNICODE \*, int]
+   This is to ``u#`` as ``Z`` is to ``u``.
+
+``es`` (string, Unicode object or character buffer compatible object) [const char \*encoding, char \*\*buffer]
+   This variant on ``s`` is used for encoding Unicode and objects convertible to
+   Unicode into a character buffer. It only works for encoded data without embedded
+   NUL bytes.
+
+   This format requires two arguments.  The first is only used as input, and
+   must be a :ctype:`const char\*` which points to the name of an encoding as a
+   NUL-terminated string, or *NULL*, in which case the default encoding is used.
+   An exception is raised if the named encoding is not known to Python.  The
+   second argument must be a :ctype:`char\*\*`; the value of the pointer it
+   references will be set to a buffer with the contents of the argument text.
+   The text will be encoded in the encoding specified by the first argument.
+
+   :cfunc:`PyArg_ParseTuple` will allocate a buffer of the needed size, copy the
+   encoded data into this buffer and adjust *\*buffer* to reference the newly
+   allocated storage.  The caller is responsible for calling :cfunc:`PyMem_Free` to
+   free the allocated buffer after use.
+
+``et`` (string, Unicode object or character buffer compatible object) [const char \*encoding, char \*\*buffer]
+   Same as ``es`` except that 8-bit string objects are passed through without
+   recoding them.  Instead, the implementation assumes that the string object uses
+   the encoding passed in as parameter.
+
+``es#`` (string, Unicode object or character buffer compatible object) [const char \*encoding, char \*\*buffer, int \*buffer_length]
+   This variant on ``s#`` is used for encoding Unicode and objects convertible to
+   Unicode into a character buffer.  Unlike the ``es`` format, this variant allows
+   input data which contains NUL characters.
+
+   It requires three arguments.  The first is only used as input, and must be a
+   :ctype:`const char\*` which points to the name of an encoding as a
+   NUL-terminated string, or *NULL*, in which case the default encoding is used.
+   An exception is raised if the named encoding is not known to Python.  The
+   second argument must be a :ctype:`char\*\*`; the value of the pointer it
+   references will be set to a buffer with the contents of the argument text.
+   The text will be encoded in the encoding specified by the first argument.
+   The third argument must be a pointer to an integer; the referenced integer
+   will be set to the number of bytes in the output buffer.
+
+   There are two modes of operation:
+
+   If *\*buffer* points a *NULL* pointer, the function will allocate a buffer of
+   the needed size, copy the encoded data into this buffer and set *\*buffer* to
+   reference the newly allocated storage.  The caller is responsible for calling
+   :cfunc:`PyMem_Free` to free the allocated buffer after usage.
+
+   If *\*buffer* points to a non-*NULL* pointer (an already allocated buffer),
+   :cfunc:`PyArg_ParseTuple` will use this location as the buffer and interpret the
+   initial value of *\*buffer_length* as the buffer size.  It will then copy the
+   encoded data into the buffer and NUL-terminate it.  If the buffer is not large
+   enough, a :exc:`ValueError` will be set.
+
+   In both cases, *\*buffer_length* is set to the length of the encoded data
+   without the trailing NUL byte.
+
+``et#`` (string, Unicode object or character buffer compatible object) [const char \*encoding, char \*\*buffer]
+   Same as ``es#`` except that string objects are passed through without recoding
+   them. Instead, the implementation assumes that the string object uses the
+   encoding passed in as parameter.
+
+``b`` (integer) [char]
+   Convert a Python integer to a tiny int, stored in a C :ctype:`char`.
+
+``B`` (integer) [unsigned char]
+   Convert a Python integer to a tiny int without overflow checking, stored in a C
+   :ctype:`unsigned char`.
+
+``h`` (integer) [short int]
+   Convert a Python integer to a C :ctype:`short int`.
+
+``H`` (integer) [unsigned short int]
+   Convert a Python integer to a C :ctype:`unsigned short int`, without overflow
+   checking.
+
+``i`` (integer) [int]
+   Convert a Python integer to a plain C :ctype:`int`.
+
+``I`` (integer) [unsigned int]
+   Convert a Python integer to a C :ctype:`unsigned int`, without overflow
+   checking.
+
+``l`` (integer) [long int]
+   Convert a Python integer to a C :ctype:`long int`.
+
+``k`` (integer) [unsigned long]
+   Convert a Python integer to a C :ctype:`unsigned long` without
+   overflow checking.
+
+``L`` (integer) [PY_LONG_LONG]
+   Convert a Python integer to a C :ctype:`long long`.  This format is only
+   available on platforms that support :ctype:`long long` (or :ctype:`_int64` on
+   Windows).
+
+``K`` (integer) [unsigned PY_LONG_LONG]
+   Convert a Python integer to a C :ctype:`unsigned long long`
+   without overflow checking.  This format is only available on platforms that
+   support :ctype:`unsigned long long` (or :ctype:`unsigned _int64` on Windows).
+
+``n`` (integer) [Py_ssize_t]
+   Convert a Python integer to a C :ctype:`Py_ssize_t`.
+
+``c`` (string of length 1) [char]
+   Convert a Python character, represented as a string of length 1, to a C
+   :ctype:`char`.
+
+``f`` (float) [float]
+   Convert a Python floating point number to a C :ctype:`float`.
+
+``d`` (float) [double]
+   Convert a Python floating point number to a C :ctype:`double`.
+
+``D`` (complex) [Py_complex]
+   Convert a Python complex number to a C :ctype:`Py_complex` structure.
+
+``O`` (object) [PyObject \*]
+   Store a Python object (without any conversion) in a C object pointer.  The C
+   program thus receives the actual object that was passed.  The object's reference
+   count is not increased.  The pointer stored is not *NULL*.
+
+``O!`` (object) [*typeobject*, PyObject \*]
+   Store a Python object in a C object pointer.  This is similar to ``O``, but
+   takes two C arguments: the first is the address of a Python type object, the
+   second is the address of the C variable (of type :ctype:`PyObject\*`) into which
+   the object pointer is stored.  If the Python object does not have the required
+   type, :exc:`TypeError` is raised.
+
+``O&`` (object) [*converter*, *anything*]
+   Convert a Python object to a C variable through a *converter* function.  This
+   takes two arguments: the first is a function, the second is the address of a C
+   variable (of arbitrary type), converted to :ctype:`void \*`.  The *converter*
+   function in turn is called as follows::
+
+      status = converter(object, address);
+
+   where *object* is the Python object to be converted and *address* is the
+   :ctype:`void\*` argument that was passed to the :cfunc:`PyArg_Parse\*` function.
+   The returned *status* should be ``1`` for a successful conversion and ``0`` if
+   the conversion has failed.  When the conversion fails, the *converter* function
+   should raise an exception.
+
+``S`` (string) [PyStringObject \*]
+   Like ``O`` but requires that the Python object is a string object.  Raises
+   :exc:`TypeError` if the object is not a string object.  The C variable may also
+   be declared as :ctype:`PyObject\*`.
+
+``U`` (Unicode string) [PyUnicodeObject \*]
+   Like ``O`` but requires that the Python object is a Unicode object.  Raises
+   :exc:`TypeError` if the object is not a Unicode object.  The C variable may also
+   be declared as :ctype:`PyObject\*`.
+
+``t#`` (read-only character buffer) [char \*, int]
+   Like ``s#``, but accepts any object which implements the read-only buffer
+   interface.  The :ctype:`char\*` variable is set to point to the first byte of
+   the buffer, and the :ctype:`int` is set to the length of the buffer.  Only
+   single-segment buffer objects are accepted; :exc:`TypeError` is raised for all
+   others.
+
+``w`` (read-write character buffer) [char \*]
+   Similar to ``s``, but accepts any object which implements the read-write buffer
+   interface.  The caller must determine the length of the buffer by other means,
+   or use ``w#`` instead.  Only single-segment buffer objects are accepted;
+   :exc:`TypeError` is raised for all others.
+
+``w#`` (read-write character buffer) [char \*, int]
+   Like ``s#``, but accepts any object which implements the read-write buffer
+   interface.  The :ctype:`char \*` variable is set to point to the first byte of
+   the buffer, and the :ctype:`int` is set to the length of the buffer.  Only
+   single-segment buffer objects are accepted; :exc:`TypeError` is raised for all
+   others.
+
+``(items)`` (tuple) [*matching-items*]
+   The object must be a Python sequence whose length is the number of format units
+   in *items*.  The C arguments must correspond to the individual format units in
+   *items*.  Format units for sequences may be nested.
+
+It is possible to pass "long" integers (integers whose value exceeds the
+platform's :const:`LONG_MAX`) however no proper range checking is done --- the
+most significant bits are silently truncated when the receiving field is too
+small to receive the value (actually, the semantics are inherited from downcasts
+in C --- your mileage may vary).
+
+A few other characters have a meaning in a format string.  These may not occur
+inside nested parentheses.  They are:
+
+``|``
+   Indicates that the remaining arguments in the Python argument list are optional.
+   The C variables corresponding to optional arguments should be initialized to
+   their default value --- when an optional argument is not specified,
+   :cfunc:`PyArg_ParseTuple` does not touch the contents of the corresponding C
+   variable(s).
+
+``:``
+   The list of format units ends here; the string after the colon is used as the
+   function name in error messages (the "associated value" of the exception that
+   :cfunc:`PyArg_ParseTuple` raises).
+
+``;``
+   The list of format units ends here; the string after the semicolon is used as
+   the error message *instead* of the default error message.  Clearly, ``:`` and
+   ``;`` mutually exclude each other.
+
+Note that any Python object references which are provided to the caller are
+*borrowed* references; do not decrement their reference count!
+
+Additional arguments passed to these functions must be addresses of variables
+whose type is determined by the format string; these are used to store values
+from the input tuple.  There are a few cases, as described in the list of format
+units above, where these parameters are used as input values; they should match
+what is specified for the corresponding format unit in that case.
+
+For the conversion to succeed, the *arg* object must match the format and the
+format must be exhausted.  On success, the :cfunc:`PyArg_Parse\*` functions
+return true, otherwise they return false and raise an appropriate exception.
+
+
+.. cfunction:: int PyArg_ParseTuple(PyObject *args, const char *format, ...)
+
+   Parse the parameters of a function that takes only positional parameters into
+   local variables.  Returns true on success; on failure, it returns false and
+   raises the appropriate exception.
+
+
+.. cfunction:: int PyArg_VaParse(PyObject *args, const char *format, va_list vargs)
+
+   Identical to :cfunc:`PyArg_ParseTuple`, except that it accepts a va_list rather
+   than a variable number of arguments.
+
+
+.. cfunction:: int PyArg_ParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], ...)
+
+   Parse the parameters of a function that takes both positional and keyword
+   parameters into local variables.  Returns true on success; on failure, it
+   returns false and raises the appropriate exception.
+
+
+.. cfunction:: int PyArg_VaParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], va_list vargs)
+
+   Identical to :cfunc:`PyArg_ParseTupleAndKeywords`, except that it accepts a
+   va_list rather than a variable number of arguments.
+
+
+.. XXX deprecated, will be removed
+.. cfunction:: int PyArg_Parse(PyObject *args, const char *format, ...)
+
+   Function used to deconstruct the argument lists of "old-style" functions ---
+   these are functions which use the :const:`METH_OLDARGS` parameter parsing
+   method.  This is not recommended for use in parameter parsing in new code, and
+   most code in the standard interpreter has been modified to no longer use this
+   for that purpose.  It does remain a convenient way to decompose other tuples,
+   however, and may continue to be used for that purpose.
+
+
+.. cfunction:: int PyArg_UnpackTuple(PyObject *args, const char *name, Py_ssize_t min, Py_ssize_t max, ...)
+
+   A simpler form of parameter retrieval which does not use a format string to
+   specify the types of the arguments.  Functions which use this method to retrieve
+   their parameters should be declared as :const:`METH_VARARGS` in function or
+   method tables.  The tuple containing the actual parameters should be passed as
+   *args*; it must actually be a tuple.  The length of the tuple must be at least
+   *min* and no more than *max*; *min* and *max* may be equal.  Additional
+   arguments must be passed to the function, each of which should be a pointer to a
+   :ctype:`PyObject\*` variable; these will be filled in with the values from
+   *args*; they will contain borrowed references.  The variables which correspond
+   to optional parameters not given by *args* will not be filled in; these should
+   be initialized by the caller. This function returns true on success and false if
+   *args* is not a tuple or contains the wrong number of elements; an exception
+   will be set if there was a failure.
+
+   This is an example of the use of this function, taken from the sources for the
+   :mod:`_weakref` helper module for weak references::
+
+      static PyObject *
+      weakref_ref(PyObject *self, PyObject *args)
+      {
+          PyObject *object;
+          PyObject *callback = NULL;
+          PyObject *result = NULL;
+
+          if (PyArg_UnpackTuple(args, "ref", 1, 2, &object, &callback)) {
+              result = PyWeakref_NewRef(object, callback);
+          }
+          return result;
+      }
+
+   The call to :cfunc:`PyArg_UnpackTuple` in this example is entirely equivalent to
+   this call to :cfunc:`PyArg_ParseTuple`::
+
+      PyArg_ParseTuple(args, "O|O:ref", &object, &callback)
+
+
+.. cfunction:: PyObject* Py_BuildValue(const char *format, ...)
+
+   Create a new value based on a format string similar to those accepted by the
+   :cfunc:`PyArg_Parse\*` family of functions and a sequence of values.  Returns
+   the value or *NULL* in the case of an error; an exception will be raised if
+   *NULL* is returned.
+
+   :cfunc:`Py_BuildValue` does not always build a tuple.  It builds a tuple only if
+   its format string contains two or more format units.  If the format string is
+   empty, it returns ``None``; if it contains exactly one format unit, it returns
+   whatever object is described by that format unit.  To force it to return a tuple
+   of size 0 or one, parenthesize the format string.
+
+   When memory buffers are passed as parameters to supply data to build objects, as
+   for the ``s`` and ``s#`` formats, the required data is copied.  Buffers provided
+   by the caller are never referenced by the objects created by
+   :cfunc:`Py_BuildValue`.  In other words, if your code invokes :cfunc:`malloc`
+   and passes the allocated memory to :cfunc:`Py_BuildValue`, your code is
+   responsible for calling :cfunc:`free` for that memory once
+   :cfunc:`Py_BuildValue` returns.
+
+   In the following description, the quoted form is the format unit; the entry in
+   (round) parentheses is the Python object type that the format unit will return;
+   and the entry in [square] brackets is the type of the C value(s) to be passed.
+
+   The characters space, tab, colon and comma are ignored in format strings (but
+   not within format units such as ``s#``).  This can be used to make long format
+   strings a tad more readable.
+
+   ``s`` (string) [char \*]
+      Convert a null-terminated C string to a Python object.  If the C string pointer
+      is *NULL*, ``None`` is used.
+
+   ``s#`` (string) [char \*, int]
+      Convert a C string and its length to a Python object.  If the C string pointer
+      is *NULL*, the length is ignored and ``None`` is returned.
+
+   ``z`` (string or ``None``) [char \*]
+      Same as ``s``.
+
+   ``z#`` (string or ``None``) [char \*, int]
+      Same as ``s#``.
+
+   ``u`` (Unicode string) [Py_UNICODE \*]
+      Convert a null-terminated buffer of Unicode (UCS-2 or UCS-4) data to a Python
+      Unicode object.  If the Unicode buffer pointer is *NULL*, ``None`` is returned.
+
+   ``u#`` (Unicode string) [Py_UNICODE \*, int]
+      Convert a Unicode (UCS-2 or UCS-4) data buffer and its length to a Python
+      Unicode object.   If the Unicode buffer pointer is *NULL*, the length is ignored
+      and ``None`` is returned.
+
+   ``U`` (string) [char \*]
+      Convert a null-terminated C string to a Python unicode object. If the C string
+      pointer is *NULL*, ``None`` is used.
+
+   ``U#`` (string) [char \*, int]
+      Convert a C string and its length to a Python unicode object. If the C string
+      pointer is *NULL*, the length is ignored and ``None`` is returned.
+
+   ``i`` (integer) [int]
+      Convert a plain C :ctype:`int` to a Python integer object.
+
+   ``b`` (integer) [char]
+      Convert a plain C :ctype:`char` to a Python integer object.
+
+   ``h`` (integer) [short int]
+      Convert a plain C :ctype:`short int` to a Python integer object.
+
+   ``l`` (integer) [long int]
+      Convert a C :ctype:`long int` to a Python integer object.
+
+   ``B`` (integer) [unsigned char]
+      Convert a C :ctype:`unsigned char` to a Python integer object.
+
+   ``H`` (integer) [unsigned short int]
+      Convert a C :ctype:`unsigned short int` to a Python integer object.
+
+   ``I`` (integer/long) [unsigned int]
+      Convert a C :ctype:`unsigned int` to a Python long integer object.
+
+   ``k`` (integer/long) [unsigned long]
+      Convert a C :ctype:`unsigned long` to a Python long integer object.
+
+   ``L`` (long) [PY_LONG_LONG]
+      Convert a C :ctype:`long long` to a Python integer object. Only available
+      on platforms that support :ctype:`long long`.
+
+   ``K`` (long) [unsigned PY_LONG_LONG]
+      Convert a C :ctype:`unsigned long long` to a Python integer object. Only
+      available on platforms that support :ctype:`unsigned long long`.
+
+   ``n`` (int) [Py_ssize_t]
+      Convert a C :ctype:`Py_ssize_t` to a Python integer.
+
+   ``c`` (string of length 1) [char]
+      Convert a C :ctype:`int` representing a character to a Python string of length
+      1.
+
+   ``d`` (float) [double]
+      Convert a C :ctype:`double` to a Python floating point number.
+
+   ``f`` (float) [float]
+      Same as ``d``.
+
+   ``D`` (complex) [Py_complex \*]
+      Convert a C :ctype:`Py_complex` structure to a Python complex number.
+
+   ``O`` (object) [PyObject \*]
+      Pass a Python object untouched (except for its reference count, which is
+      incremented by one).  If the object passed in is a *NULL* pointer, it is assumed
+      that this was caused because the call producing the argument found an error and
+      set an exception. Therefore, :cfunc:`Py_BuildValue` will return *NULL* but won't
+      raise an exception.  If no exception has been raised yet, :exc:`SystemError` is
+      set.
+
+   ``S`` (object) [PyObject \*]
+      Same as ``O``.
+
+   ``N`` (object) [PyObject \*]
+      Same as ``O``, except it doesn't increment the reference count on the object.
+      Useful when the object is created by a call to an object constructor in the
+      argument list.
+
+   ``O&`` (object) [*converter*, *anything*]
+      Convert *anything* to a Python object through a *converter* function.  The
+      function is called with *anything* (which should be compatible with :ctype:`void
+      \*`) as its argument and should return a "new" Python object, or *NULL* if an
+      error occurred.
+
+   ``(items)`` (tuple) [*matching-items*]
+      Convert a sequence of C values to a Python tuple with the same number of items.
+
+   ``[items]`` (list) [*matching-items*]
+      Convert a sequence of C values to a Python list with the same number of items.
+
+   ``{items}`` (dictionary) [*matching-items*]
+      Convert a sequence of C values to a Python dictionary.  Each pair of consecutive
+      C values adds one item to the dictionary, serving as key and value,
+      respectively.
+
+   If there is an error in the format string, the :exc:`SystemError` exception is
+   set and *NULL* returned.

Added: python/branches/py3k/Doc/c-api/bool.rst
==============================================================================
--- (empty file)
+++ python/branches/py3k/Doc/c-api/bool.rst	Sun Jan 20 10:30:57 2008
@@ -0,0 +1,46 @@
+.. highlightlang:: c
+
+.. _boolobjects:
+
+Boolean Objects
+---------------
+
+Booleans in Python are implemented as a subclass of integers.  There are only
+two booleans, :const:`Py_False` and :const:`Py_True`.  As such, the normal
+creation and deletion functions don't apply to booleans.  The following macros
+are available, however.
+
+
+.. cfunction:: int PyBool_Check(PyObject *o)
+
+   Return true if *o* is of type :cdata:`PyBool_Type`.
+
+
+.. cvar:: PyObject* Py_False
+
+   The Python ``False`` object.  This object has no methods.  It needs to be
+   treated just like any other object with respect to reference counts.
+
+
+.. cvar:: PyObject* Py_True
+
+   The Python ``True`` object.  This object has no methods.  It needs to be treated
+   just like any other object with respect to reference counts.
+
+
+.. cmacro:: Py_RETURN_FALSE
+
+   Return :const:`Py_False` from a function, properly incrementing its reference
+   count.
+
+
+.. cmacro:: Py_RETURN_TRUE
+
+   Return :const:`Py_True` from a function, properly incrementing its reference
+   count.
+
+
+.. cfunction:: PyObject* PyBool_FromLong(long v)
+
+   Return a new reference to :const:`Py_True` or :const:`Py_False` depending on the
+   truth value of *v*.

Added: python/branches/py3k/Doc/c-api/buffer.rst
==============================================================================
--- (empty file)
+++ python/branches/py3k/Doc/c-api/buffer.rst	Sun Jan 20 10:30:57 2008
@@ -0,0 +1,119 @@
+.. highlightlang:: c
+
+.. _bufferobjects:
+
+Buffer Objects
+--------------
+
+.. sectionauthor:: Greg Stein <gstein at lyra.org>
+
+
+.. index::
+   object: buffer
+   single: buffer interface
+
+Python objects implemented in C can export a group of functions called the
+"buffer 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 :meth:`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
+:cfunc:`PyArg_ParseTuple` that operate against an object's buffer interface,
+returning data from the target object.
+
+.. index:: single: PyBufferProcs
+
+More information on the buffer interface is provided in the section 
+:ref:`buffer-structs`, under the description for :ctype:`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.
+
+
+.. ctype:: PyBufferObject
+
+   This subtype of :ctype:`PyObject` represents a buffer object.
+
+
+.. cvar:: PyTypeObject PyBuffer_Type
+
+   .. index:: single: BufferType (in module types)
+
+   The instance of :ctype:`PyTypeObject` which represents the Python buffer type;
+   it is the same object as ``buffer`` and  ``types.BufferType`` in the Python
+   layer. .
+
+
+.. cvar:: int Py_END_OF_BUFFER
+
+   This constant may be passed as the *size* parameter to
+   :cfunc:`PyBuffer_FromObject` or :cfunc:`PyBuffer_FromReadWriteObject`.  It
+   indicates that the new :ctype:`PyBufferObject` should refer to *base* object
+   from the specified *offset* to the end of its exported buffer.  Using this
+   enables the caller to avoid querying the *base* object for its length.
+
+
+.. cfunction:: int PyBuffer_Check(PyObject *p)
+
+   Return true if the argument has type :cdata:`PyBuffer_Type`.
+
+
+.. cfunction:: PyObject* PyBuffer_FromObject(PyObject *base, Py_ssize_t offset, Py_ssize_t size)
+
+   Return a new read-only buffer object.  This raises :exc:`TypeError` if *base*
+   doesn't support the read-only buffer protocol or doesn't provide exactly one
+   buffer segment, or it raises :exc:`ValueError` if *offset* is less than zero.
+   The buffer will hold a reference to the *base* object, and the buffer's contents
+   will refer to the *base* object's buffer interface, starting as position
+   *offset* and extending for *size* bytes. If *size* is :const:`Py_END_OF_BUFFER`,
+   then the new buffer's contents extend to the length of the *base* object's
+   exported buffer data.
+
+
+.. cfunction:: 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 :cfunc:`PyBuffer_FromObject`.  If the *base* object does not export
+   the writable buffer protocol, then :exc:`TypeError` is raised.
+
+
+.. cfunction:: 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 *ptr*, is not deallocated while the returned buffer
+   object exists.  Raises :exc:`ValueError` if *size* is less than zero.  Note that
+   :const:`Py_END_OF_BUFFER` may *not* be passed for the *size* parameter;
+   :exc:`ValueError` will be raised in that case.
+
+
+.. cfunction:: PyObject* PyBuffer_FromReadWriteMemory(void *ptr, Py_ssize_t size)
+
+   Similar to :cfunc:`PyBuffer_FromMemory`, but the returned buffer is writable.
+
+
+.. cfunction:: PyObject* PyBuffer_New(Py_ssize_t size)
+
+   Return a new writable buffer object that maintains its own memory buffer of
+   *size* bytes.  :exc:`ValueError` is returned if *size* is not zero or positive.
+   Note that the memory buffer (as returned by :cfunc:`PyObject_AsWriteBuffer`) is
+   not specifically aligned.

Added: python/branches/py3k/Doc/c-api/cell.rst
==============================================================================
--- (empty file)
+++ python/branches/py3k/Doc/c-api/cell.rst	Sun Jan 20 10:30:57 2008
@@ -0,0 +1,62 @@
+.. highlightlang:: c
+
+.. _cell-objects:
+
+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.
+
+
+.. ctype:: PyCellObject
+
+   The C structure used for cell objects.
+
+
+.. cvar:: PyTypeObject PyCell_Type
+
+   The type object corresponding to cell objects.
+
+
+.. cfunction:: int PyCell_Check(ob)
+
+   Return true if *ob* is a cell object; *ob* must not be *NULL*.
+
+
+.. cfunction:: PyObject* PyCell_New(PyObject *ob)
+
+   Create and return a new cell object containing the value *ob*. The parameter may
+   be *NULL*.
+
+
+.. cfunction:: PyObject* PyCell_Get(PyObject *cell)
+
+   Return the contents of the cell *cell*.
+
+
+.. cfunction:: PyObject* PyCell_GET(PyObject *cell)
+
+   Return the contents of the cell *cell*, but without checking that *cell* is
+   non-*NULL* and a cell object.
+
+
+.. cfunction:: int PyCell_Set(PyObject *cell, PyObject *value)
+
+   Set the contents of the cell object *cell* to *value*.  This releases the
+   reference to any current content of the cell. *value* may be *NULL*.  *cell*
+   must be non-*NULL*; if it is not a cell object, ``-1`` will be returned.  On
+   success, ``0`` will be returned.
+
+
+.. cfunction:: void PyCell_SET(PyObject *cell, PyObject *value)
+
+   Sets the value of the cell object *cell* to *value*.  No reference counts are
+   adjusted, and no checks are made for safety; *cell* must be non-*NULL* and must
+   be a cell object.

Added: python/branches/py3k/Doc/c-api/cobject.rst
==============================================================================
--- (empty file)
+++ python/branches/py3k/Doc/c-api/cobject.rst	Sun Jan 20 10:30:57 2008
@@ -0,0 +1,56 @@
+.. highlightlang:: c
+
+.. _cobjects:
+
+CObjects
+--------
+
+.. index:: object: CObject
+
+Refer to :ref:`using-cobjects` for more information on using these objects.
+
+
+.. ctype:: 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.
+
+
+.. cfunction:: int PyCObject_Check(PyObject *p)
+
+   Return true if its argument is a :ctype:`PyCObject`.
+
+
+.. cfunction:: PyObject* PyCObject_FromVoidPtr(void* cobj, void (*destr)(void *))
+
+   Create a :ctype:`PyCObject` from the ``void *`` *cobj*.  The *destr* function
+   will be called when the object is reclaimed, unless it is *NULL*.
+
+
+.. cfunction:: PyObject* PyCObject_FromVoidPtrAndDesc(void* cobj, void* desc, void (*destr)(void *, void *))
+
+   Create a :ctype:`PyCObject` from the :ctype:`void \*` *cobj*.  The *destr*
+   function will be called when the object is reclaimed. The *desc* argument can
+   be used to pass extra callback data for the destructor function.
+
+
+.. cfunction:: void* PyCObject_AsVoidPtr(PyObject* self)
+
+   Return the object :ctype:`void \*` that the :ctype:`PyCObject` *self* was
+   created with.
+
+
+.. cfunction:: void* PyCObject_GetDesc(PyObject* self)
+
+   Return the description :ctype:`void \*` that the :ctype:`PyCObject` *self* was
+   created with.
+
+
+.. cfunction:: int PyCObject_SetVoidPtr(PyObject* self, void* cobj)
+
+   Set the void pointer inside *self* to *cobj*. The :ctype:`PyCObject` must not
+   have an associated destructor. Return true on success, false on failure.

Added: python/branches/py3k/Doc/c-api/complex.rst
==============================================================================
--- (empty file)
+++ python/branches/py3k/Doc/c-api/complex.rst	Sun Jan 20 10:30:57 2008
@@ -0,0 +1,126 @@
+.. highlightlang:: c
+
+.. _complexobjects:
+
+Complex Number Objects
+----------------------
+
+.. index:: object: 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.
+
+
+Complex Numbers as C Structures
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Note that the functions which accept these structures as parameters and return
+them as results do so *by value* rather than dereferencing them through
+pointers.  This is consistent throughout the API.
+
+
+.. ctype:: 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::
+
+      typedef struct {
+         double real;
+         double imag;
+      } Py_complex;
+
+
+.. cfunction:: 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.
+
+
+.. cfunction:: 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.
+
+
+.. cfunction:: Py_complex _Py_c_neg(Py_complex complex)
+
+   Return the negation of the complex number *complex*, using the C
+   :ctype:`Py_complex` representation.
+
+
+.. cfunction:: 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.
+
+
+.. cfunction:: 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.
+
+
+.. cfunction:: Py_complex _Py_c_pow(Py_complex num, Py_complex exp)
+
+   Return the exponentiation of *num* by *exp*, using the C :ctype:`Py_complex`
+   representation.
+
+
+Complex Numbers as Python Objects
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+.. ctype:: PyComplexObject
+
+   This subtype of :ctype:`PyObject` represents a Python complex number object.
+
+
+.. cvar:: PyTypeObject PyComplex_Type
+
+   This instance of :ctype:`PyTypeObject` represents the Python complex number
+   type. It is the same object as ``complex`` and ``types.ComplexType``.
+
+
+.. cfunction:: int PyComplex_Check(PyObject *p)
+
+   Return true if its argument is a :ctype:`PyComplexObject` or a subtype of
+   :ctype:`PyComplexObject`.
+
+
+.. cfunction:: int PyComplex_CheckExact(PyObject *p)
+
+   Return true if its argument is a :ctype:`PyComplexObject`, but not a subtype of
+   :ctype:`PyComplexObject`.
+
+
+.. cfunction:: PyObject* PyComplex_FromCComplex(Py_complex v)
+
+   Create a new Python complex number object from a C :ctype:`Py_complex` value.
+
+
+.. cfunction:: PyObject* PyComplex_FromDoubles(double real, double imag)
+
+   Return a new :ctype:`PyComplexObject` object from *real* and *imag*.
+
+
+.. cfunction:: double PyComplex_RealAsDouble(PyObject *op)
+
+   Return the real part of *op* as a C :ctype:`double`.
+
+
+.. cfunction:: double PyComplex_ImagAsDouble(PyObject *op)
+
+   Return the imaginary part of *op* as a C :ctype:`double`.
+
+
+.. cfunction:: Py_complex PyComplex_AsCComplex(PyObject *op)
+
+   Return the :ctype:`Py_complex` value of the complex number *op*.
+
+   If *op* is not a Python complex number object but has a :meth:`__complex__`
+   method, this method will first be called to convert *op* to a Python complex
+   number object.

Modified: python/branches/py3k/Doc/c-api/concrete.rst
==============================================================================
--- python/branches/py3k/Doc/c-api/concrete.rst	(original)
+++ python/branches/py3k/Doc/c-api/concrete.rst	Sun Jan 20 10:30:57 2008
@@ -29,99 +29,10 @@
 
 This section describes Python type objects and the singleton object ``None``.
 
+.. toctree::
 
-.. _typeobjects:
-
-Type Objects
-------------
-
-.. index:: object: type
-
-
-.. ctype:: PyTypeObject
-
-   The C structure of the objects used to describe built-in types.
-
-
-.. cvar:: PyObject* PyType_Type
-
-   .. index:: single: TypeType (in module types)
-
-   This is the type object for type objects; it is the same object as ``type`` and
-   ``types.TypeType`` in the Python layer.
-
-
-.. cfunction:: int PyType_Check(PyObject *o)
-
-   Return true if the object *o* is a type object, including instances of types
-   derived from the standard type object.  Return false in all other cases.
-
-
-.. cfunction:: int PyType_CheckExact(PyObject *o)
-
-   Return true if the object *o* is a type object, but not a subtype of the
-   standard type object.  Return false in all other cases.
-
-
-.. cfunction:: int PyType_HasFeature(PyObject *o, int feature)
-
-   Return true if the type object *o* sets the feature *feature*.  Type features
-   are denoted by single bit flags.
-
-
-.. cfunction:: int PyType_IS_GC(PyObject *o)
-
-   Return true if the type object includes support for the cycle detector; this
-   tests the type flag :const:`Py_TPFLAGS_HAVE_GC`.
-
-
-.. cfunction:: int PyType_IsSubtype(PyTypeObject *a, PyTypeObject *b)
-
-   Return true if *a* is a subtype of *b*.
-
-
-.. cfunction:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
-
-   XXX: Document.
-
-
-.. cfunction:: PyObject* PyType_GenericNew(PyTypeObject *type, PyObject *args, PyObject *kwds)
-
-   XXX: Document.
-
-
-.. cfunction:: 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 ``0`` on success, or return ``-1`` and sets an
-   exception on error.
-
-
-.. _noneobject:
-
-The None Object
----------------
-
-.. index:: object: None
-
-Note that the :ctype:`PyTypeObject` for ``None`` is not directly exposed in the
-Python/C API.  Since ``None`` is a singleton, testing for object identity (using
-``==`` in C) is sufficient. There is no :cfunc:`PyNone_Check` function for the
-same reason.
-
-
-.. cvar:: PyObject* Py_None
-
-   The Python ``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.
-
-
-.. cmacro:: Py_RETURN_NONE
-
-   Properly handle returning :cdata:`Py_None` from within a C function (that is,
-   increment the reference count of None and return it.)
+   type.rst
+   none.rst
 
 
 .. _numericobjects:
@@ -131,447 +42,12 @@
 
 .. index:: object: numeric
 
+.. toctree::
 
-.. _boolobjects:
-
-Boolean Objects
----------------
-
-Booleans in Python are implemented as a subclass of integers.  There are only
-two booleans, :const:`Py_False` and :const:`Py_True`.  As such, the normal
-creation and deletion functions don't apply to booleans.  The following macros
-are available, however.
-
-
-.. cfunction:: int PyBool_Check(PyObject *o)
-
-   Return true if *o* is of type :cdata:`PyBool_Type`.
-
-
-.. cvar:: PyObject* Py_False
-
-   The Python ``False`` object.  This object has no methods.  It needs to be
-   treated just like any other object with respect to reference counts.
-
-
-.. cvar:: PyObject* Py_True
-
-   The Python ``True`` object.  This object has no methods.  It needs to be treated
-   just like any other object with respect to reference counts.
-
-
-.. cmacro:: Py_RETURN_FALSE
-
-   Return :const:`Py_False` from a function, properly incrementing its reference
-   count.
-
-
-.. cmacro:: Py_RETURN_TRUE
-
-   Return :const:`Py_True` from a function, properly incrementing its reference
-   count.
-
-
-.. cfunction:: PyObject* PyBool_FromLong(long v)
-
-   Return a new reference to :const:`Py_True` or :const:`Py_False` depending on the
-   truth value of *v*.
-
-
-.. _longobjects:
-
-Integer Objects
----------------
-
-.. index:: object: long integer
-           object: integer
-
-All integers are implemented as "long" integer objects of arbitrary size.
-
-.. ctype:: PyLongObject
-
-   This subtype of :ctype:`PyObject` represents a Python integer object.
-
-
-.. cvar:: PyTypeObject PyLong_Type
-
-   This instance of :ctype:`PyTypeObject` represents the Python integer type.
-   This is the same object as ``int``.
-
-
-.. cfunction:: int PyLong_Check(PyObject *p)
-
-   Return true if its argument is a :ctype:`PyLongObject` or a subtype of
-   :ctype:`PyLongObject`.
-
-
-.. cfunction:: int PyLong_CheckExact(PyObject *p)
-
-   Return true if its argument is a :ctype:`PyLongObject`, but not a subtype of
-   :ctype:`PyLongObject`.
-
-
-.. cfunction:: PyObject* PyLong_FromLong(long v)
-
-   Return a new :ctype:`PyLongObject` object from *v*, or *NULL* on failure.
-
-   The current implementation keeps an array of integer objects for all integers
-   between ``-5`` and ``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 ``1``.  I suspect the behaviour of Python in this case is
-   undefined. :-)
-
-
-.. cfunction:: PyObject* PyLong_FromUnsignedLong(unsigned long v)
-
-   Return a new :ctype:`PyLongObject` object from a C :ctype:`unsigned long`, or
-   *NULL* on failure.
-
-
-.. cfunction:: PyObject* PyLong_FromSsize_t(Py_ssize_t v)
-
-   Return a new :ctype:`PyLongObject` object with a value of *v*, or *NULL*
-   on failure.
-
-
-.. cfunction:: PyObject* PyLong_FromSize_t(size_t v)
-
-   Return a new :ctype:`PyLongObject` object with a value of *v*, or *NULL*
-   on failure.
-
-
-.. cfunction:: PyObject* PyLong_FromLongLong(PY_LONG_LONG v)
-
-   Return a new :ctype:`PyLongObject` object from a C :ctype:`long long`, or *NULL*
-   on failure.
-
-
-.. cfunction:: 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.
-
-
-.. cfunction:: PyObject* PyLong_FromDouble(double v)
-
-   Return a new :ctype:`PyLongObject` object from the integer part of *v*, or
-   *NULL* on failure.
-
-
-.. cfunction:: PyObject* PyLong_FromString(char *str, char **pend, int base)
-
-   Return a new :ctype:`PyLongObject` based on the string value in *str*, which
-   is interpreted according to the radix in *base*.  If *pend* is non-*NULL*,
-   ``*pend`` will point to the first character in *str* which follows the
-   representation of the number.  If *base* is ``0``, the radix will be
-   determined based on the leading characters of *str*: if *str* starts with
-   ``'0x'`` or ``'0X'``, radix 16 will be used; if *str* starts with ``'0o'`` or
-   ``'0O'``, radix 8 will be used; if *str* starts with ``'0b'`` or ``'0B'``,
-   radix 2 will be used; otherwise radix 10 will be used.  If *base* is not
-   ``0``, it must be between ``2`` and ``36``, inclusive.  Leading spaces are
-   ignored.  If there are no digits, :exc:`ValueError` will be raised.
-
-
-.. cfunction:: PyObject* PyLong_FromUnicode(Py_UNICODE *u, Py_ssize_t length, int base)
-
-   Convert a sequence of Unicode digits to a Python integer value.  The Unicode
-   string is first encoded to a byte string using :cfunc:`PyUnicode_EncodeDecimal`
-   and then converted using :cfunc:`PyLong_FromString`.
-
-
-.. cfunction:: PyObject* PyLong_FromVoidPtr(void *p)
-
-   Create a Python integer from the pointer *p*. The pointer value can be
-   retrieved from the resulting value using :cfunc:`PyLong_AsVoidPtr`.
-
-
-.. XXX alias PyLong_AS_LONG (for now) 
-.. cfunction:: long PyLong_AsLong(PyObject *pylong)
-
-   .. index::
-      single: LONG_MAX
-      single: OverflowError (built-in exception)
-
-   Return a C :ctype:`long` representation of the contents of *pylong*.  If
-   *pylong* is greater than :const:`LONG_MAX`, raise an :exc:`OverflowError`,
-   and return -1. Convert non-long objects automatically to long first,
-   and return -1 if that raises exceptions.
-
-.. cfunction:: long PyLong_AsLongAndOverflow(PyObject *pylong, int* overflow)
-
-   Return a C :ctype:`long` representation of the contents of *pylong*.  If
-   *pylong* is greater than :const:`LONG_MAX`, return -1 and
-   set `*overflow` to 1 (for overflow) or -1 (for underflow). 
-   If an exception is set because of type errors, also return -1.
-
-
-.. cfunction:: unsigned long PyLong_AsUnsignedLong(PyObject *pylong)
-
-   .. index::
-      single: ULONG_MAX
-      single: OverflowError (built-in exception)
-
-   Return a C :ctype:`unsigned long` representation of the contents of *pylong*.
-   If *pylong* is greater than :const:`ULONG_MAX`, an :exc:`OverflowError` is
-   raised.
-
-
-.. cfunction:: Py_ssize_t PyLong_AsSsize_t(PyObject *pylong)
-
-   .. index::
-      single: PY_SSIZE_T_MAX
-
-   Return a :ctype:`Py_ssize_t` representation of the contents of *pylong*.  If
-   *pylong* is greater than :const:`PY_SSIZE_T_MAX`, an :exc:`OverflowError` is
-   raised.
-
-
-.. cfunction:: size_t PyLong_AsSize_t(PyObject *pylong)
-
-   Return a :ctype:`size_t` representation of the contents of *pylong*.  If
-   *pylong* is greater than the maximum value for a :ctype:`size_t`, an
-   :exc:`OverflowError` is raised.
-
-
-.. cfunction:: PY_LONG_LONG PyLong_AsLongLong(PyObject *pylong)
-
-   Return a C :ctype:`long long` from a Python integer.  If *pylong* cannot be
-   represented as a :ctype:`long long`, an :exc:`OverflowError` will be raised.
-
-
-.. cfunction:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLong(PyObject *pylong)
-
-   Return a C :ctype:`unsigned long long` from a Python integer. If *pylong*
-   cannot be represented as an :ctype:`unsigned long long`, an :exc:`OverflowError`
-   will be raised if the value is positive, or a :exc:`TypeError` will be raised if
-   the value is negative.
-
-
-.. cfunction:: unsigned long PyLong_AsUnsignedLongMask(PyObject *io)
-
-   Return a C :ctype:`unsigned long` from a Python integer, without checking for
-   overflow.
-
-
-.. cfunction:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLongMask(PyObject *io)
-
-   Return a C :ctype:`unsigned long long` from a Python integer, without
-   checking for overflow.
-
-
-.. cfunction:: double PyLong_AsDouble(PyObject *pylong)
-
-   Return a C :ctype:`double` representation of the contents of *pylong*.  If
-   *pylong* cannot be approximately represented as a :ctype:`double`, an
-   :exc:`OverflowError` exception is raised and ``-1.0`` will be returned.
-
-
-.. cfunction:: void* PyLong_AsVoidPtr(PyObject *pylong)
-
-   Convert a Python integer *pylong* to a C :ctype:`void` pointer.  If *pylong*
-   cannot be converted, an :exc:`OverflowError` will be raised.  This is only
-   assured to produce a usable :ctype:`void` pointer for values created with
-   :cfunc:`PyLong_FromVoidPtr`.
-
-
-.. _floatobjects:
-
-Floating Point Objects
-----------------------
-
-.. index:: object: floating point
-
-
-.. ctype:: PyFloatObject
-
-   This subtype of :ctype:`PyObject` represents a Python floating point object.
-
-
-.. cvar:: PyTypeObject PyFloat_Type
-
-   .. index:: single: FloatType (in modules types)
-
-   This instance of :ctype:`PyTypeObject` represents the Python floating point
-   type.  This is the same object as ``float`` and ``types.FloatType``.
-
-
-.. cfunction:: int PyFloat_Check(PyObject *p)
-
-   Return true if its argument is a :ctype:`PyFloatObject` or a subtype of
-   :ctype:`PyFloatObject`.
-
-
-.. cfunction:: int PyFloat_CheckExact(PyObject *p)
-
-   Return true if its argument is a :ctype:`PyFloatObject`, but not a subtype of
-   :ctype:`PyFloatObject`.
-
-
-.. cfunction:: PyObject* PyFloat_FromString(PyObject *str)
-
-   Create a :ctype:`PyFloatObject` object based on the string value in *str*, or
-   *NULL* on failure.
-
-
-.. cfunction:: PyObject* PyFloat_FromDouble(double v)
-
-   Create a :ctype:`PyFloatObject` object from *v*, or *NULL* on failure.
-
-
-.. cfunction:: double PyFloat_AsDouble(PyObject *pyfloat)
-
-   Return a C :ctype:`double` representation of the contents of *pyfloat*.  If
-   *pyfloat* is not a Python floating point object but has a :meth:`__float__`
-   method, this method will first be called to convert *pyfloat* into a float.
-
-
-.. cfunction:: double PyFloat_AS_DOUBLE(PyObject *pyfloat)
-
-   Return a C :ctype:`double` representation of the contents of *pyfloat*, but
-   without error checking.
-
-
-.. cfunction:: PyObject* PyFloat_GetInfo(void)
-
-   Return a structseq instance which contains information about the
-   precision, minimum and maximum values of a float. It's a thin wrapper
-   around the header file :file:`float.h`.
-
-
-.. cfunction:: double PyFloat_GetMax(void)
-
-   Return the maximum representable finite float *DBL_MAX* as C :ctype:`double`.
-
-
-.. cfunction:: double PyFloat_GetMin(void)
-
-   Return the minimum normalized positive float *DBL_MIN* as C :ctype:`double`.
-
-
-.. _complexobjects:
-
-Complex Number Objects
-----------------------
-
-.. index:: object: 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.
-
-
-Complex Numbers as C Structures
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Note that the functions which accept these structures as parameters and return
-them as results do so *by value* rather than dereferencing them through
-pointers.  This is consistent throughout the API.
-
-
-.. ctype:: 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::
-
-      typedef struct {
-         double real;
-         double imag;
-      } Py_complex;
-
-
-.. cfunction:: 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.
-
-
-.. cfunction:: 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.
-
-
-.. cfunction:: Py_complex _Py_c_neg(Py_complex complex)
-
-   Return the negation of the complex number *complex*, using the C
-   :ctype:`Py_complex` representation.
-
-
-.. cfunction:: 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.
-
-
-.. cfunction:: 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.
-
-
-.. cfunction:: Py_complex _Py_c_pow(Py_complex num, Py_complex exp)
-
-   Return the exponentiation of *num* by *exp*, using the C :ctype:`Py_complex`
-   representation.
-
-
-Complex Numbers as Python Objects
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-
-.. ctype:: PyComplexObject
-
-   This subtype of :ctype:`PyObject` represents a Python complex number object.
-
-
-.. cvar:: PyTypeObject PyComplex_Type
-
-   This instance of :ctype:`PyTypeObject` represents the Python complex number
-   type. It is the same object as ``complex`` and ``types.ComplexType``.
-
-
-.. cfunction:: int PyComplex_Check(PyObject *p)
-
-   Return true if its argument is a :ctype:`PyComplexObject` or a subtype of
-   :ctype:`PyComplexObject`.
-
-
-.. cfunction:: int PyComplex_CheckExact(PyObject *p)
-
-   Return true if its argument is a :ctype:`PyComplexObject`, but not a subtype of
-   :ctype:`PyComplexObject`.
-
-
-.. cfunction:: PyObject* PyComplex_FromCComplex(Py_complex v)
-
-   Create a new Python complex number object from a C :ctype:`Py_complex` value.
-
-
-.. cfunction:: PyObject* PyComplex_FromDoubles(double real, double imag)
-
-   Return a new :ctype:`PyComplexObject` object from *real* and *imag*.
-
-
-.. cfunction:: double PyComplex_RealAsDouble(PyObject *op)
-
-   Return the real part of *op* as a C :ctype:`double`.
-
-
-.. cfunction:: double PyComplex_ImagAsDouble(PyObject *op)
-
-   Return the imaginary part of *op* as a C :ctype:`double`.
-
-
-.. cfunction:: Py_complex PyComplex_AsCComplex(PyObject *op)
-
-   Return the :ctype:`Py_complex` value of the complex number *op*.
-
-   If *op* is not a Python complex number object but has a :meth:`__complex__`
-   method, this method will first be called to convert *op* to a Python complex
-   number object.
+   long.rst
+   bool.rst
+   float.rst
+   complex.rst
 
 
 .. _sequenceobjects:
@@ -587,2819 +63,44 @@
 
 .. XXX sort out unicode, str, bytes and bytearray
 
-.. _stringobjects:
-
-String Objects
---------------
-
-These functions raise :exc:`TypeError` when expecting a string parameter and are
-called with a non-string parameter.
-
-.. index:: object: string
-
+.. toctree::
 
-.. ctype:: PyStringObject
+   string.rst
+   unicode.rst
+   buffer.rst
+   tuple.rst
+   list.rst
 
-   This subtype of :ctype:`PyObject` represents a Python string object.
 
+.. _mapobjects:
 
-.. cvar:: PyTypeObject PyString_Type
-
-   .. index:: single: StringType (in module types)
-
-   This instance of :ctype:`PyTypeObject` represents the Python string type; it is
-   the same object as ``str`` and ``types.StringType`` in the Python layer. .
-
+Mapping Objects
+===============
 
-.. cfunction:: int PyString_Check(PyObject *o)
+.. index:: object: mapping
 
-   Return true if the object *o* is a string object or an instance of a subtype of
-   the string type.
+.. toctree::
 
+   dict.rst
 
-.. cfunction:: int PyString_CheckExact(PyObject *o)
 
-   Return true if the object *o* is a string object, but not an instance of a
-   subtype of the string type.
+.. _otherobjects:
 
+Other Objects
+=============
 
-.. cfunction:: PyObject* PyString_FromString(const char *v)
-
-   Return a new string object with a copy of the string *v* as value on success,
-   and *NULL* on failure.  The parameter *v* must not be *NULL*; it will not be
-   checked.
-
-
-.. cfunction:: PyObject* PyString_FromStringAndSize(const char *v, Py_ssize_t len)
-
-   Return a new string object with a copy of the string *v* as value and length
-   *len* on success, and *NULL* on failure.  If *v* is *NULL*, the contents of the
-   string are uninitialized.
-
-
-.. cfunction:: PyObject* PyString_FromFormat(const char *format, ...)
-
-   Take a C :cfunc:`printf`\ -style *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 *format* string.  The
-   following format characters are allowed:
-
-   .. % XXX: This should be exactly the same as the table in PyErr_Format.
-   .. % One should just refer to the other.
-   .. % XXX: 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.
-
-   +-------------------+---------------+--------------------------------+
-   | Format Characters | Type          | Comment                        |
-   +===================+===============+================================+
-   | :attr:`%%`        | *n/a*         | The literal % character.       |
-   +-------------------+---------------+--------------------------------+
-   | :attr:`%c`        | int           | A single character,            |
-   |                   |               | represented as an C int.       |
-   +-------------------+---------------+--------------------------------+
-   | :attr:`%d`        | int           | Exactly equivalent to          |
-   |                   |               | ``printf("%d")``.              |
-   +-------------------+---------------+--------------------------------+
-   | :attr:`%u`        | unsigned int  | Exactly equivalent to          |
-   |                   |               | ``printf("%u")``.              |
-   +-------------------+---------------+--------------------------------+
-   | :attr:`%ld`       | long          | Exactly equivalent to          |
-   |                   |               | ``printf("%ld")``.             |
-   +-------------------+---------------+--------------------------------+
-   | :attr:`%lu`       | unsigned long | Exactly equivalent to          |
-   |                   |               | ``printf("%lu")``.             |
-   +-------------------+---------------+--------------------------------+
-   | :attr:`%zd`       | Py_ssize_t    | Exactly equivalent to          |
-   |                   |               | ``printf("%zd")``.             |
-   +-------------------+---------------+--------------------------------+
-   | :attr:`%zu`       | size_t        | Exactly equivalent to          |
-   |                   |               | ``printf("%zu")``.             |
-   +-------------------+---------------+--------------------------------+
-   | :attr:`%i`        | int           | Exactly equivalent to          |
-   |                   |               | ``printf("%i")``.              |
-   +-------------------+---------------+--------------------------------+
-   | :attr:`%x`        | int           | Exactly equivalent to          |
-   |                   |               | ``printf("%x")``.              |
-   +-------------------+---------------+--------------------------------+
-   | :attr:`%s`        | char\*        | A null-terminated C character  |
-   |                   |               | array.                         |
-   +-------------------+---------------+--------------------------------+
-   | :attr:`%p`        | void\*        | The hex representation of a C  |
-   |                   |               | pointer. Mostly equivalent to  |
-   |                   |               | ``printf("%p")`` except that   |
-   |                   |               | it is guaranteed to start with |
-   |                   |               | the literal ``0x`` regardless  |
-   |                   |               | of what the platform's         |
-   |                   |               | ``printf`` yields.             |
-   +-------------------+---------------+--------------------------------+
-
-   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.
-
-
-.. cfunction:: PyObject* PyString_FromFormatV(const char *format, va_list vargs)
-
-   Identical to :func:`PyString_FromFormat` except that it takes exactly two
-   arguments.
-
-
-.. cfunction:: Py_ssize_t PyString_Size(PyObject *string)
-
-   Return the length of the string in string object *string*.
-
-
-.. cfunction:: Py_ssize_t PyString_GET_SIZE(PyObject *string)
-
-   Macro form of :cfunc:`PyString_Size` but without error checking.
-
-
-.. cfunction:: char* PyString_AsString(PyObject *string)
-
-   Return a NUL-terminated representation of the contents of *string*.  The pointer
-   refers to the internal buffer of *string*, not a copy.  The data must not be
-   modified in any way, unless the string was just created using
-   ``PyString_FromStringAndSize(NULL, size)``. It must not be deallocated.  If
-   *string* is a Unicode object, this function computes the default encoding of
-   *string* and operates on that.  If *string* is not a string object at all,
-   :cfunc:`PyString_AsString` returns *NULL* and raises :exc:`TypeError`.
-
-
-.. cfunction:: char* PyString_AS_STRING(PyObject *string)
-
-   Macro form of :cfunc:`PyString_AsString` but without error checking.  Only
-   string objects are supported; no Unicode objects should be passed.
-
-
-.. cfunction:: int PyString_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length)
-
-   Return a NUL-terminated representation of the contents of the object *obj*
-   through the output variables *buffer* and *length*.
-
-   The function accepts both string and Unicode objects as input. For Unicode
-   objects it returns the default encoded version of the object.  If *length* is
-   *NULL*, the resulting buffer may not contain NUL characters; if it does, the
-   function returns ``-1`` and a :exc:`TypeError` is raised.
-
-   The buffer refers to an internal string buffer of *obj*, not a copy. The data
-   must not be modified in any way, unless the string was just created using
-   ``PyString_FromStringAndSize(NULL, size)``.  It must not be deallocated.  If
-   *string* is a Unicode object, this function computes the default encoding of
-   *string* and operates on that.  If *string* is not a string object at all,
-   :cfunc:`PyString_AsStringAndSize` returns ``-1`` and raises :exc:`TypeError`.
-
-
-.. cfunction:: void PyString_Concat(PyObject **string, PyObject *newpart)
-
-   Create a new string object in *\*string* containing the contents of *newpart*
-   appended to *string*; the caller will own the new reference.  The reference to
-   the old value of *string* will be stolen.  If the new string cannot be created,
-   the old reference to *string* will still be discarded and the value of
-   *\*string* will be set to *NULL*; the appropriate exception will be set.
-
-
-.. cfunction:: void PyString_ConcatAndDel(PyObject **string, PyObject *newpart)
-
-   Create a new string object in *\*string* containing the contents of *newpart*
-   appended to *string*.  This version decrements the reference count of *newpart*.
-
-
-.. cfunction:: 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, *\*string* holds the resized string object and ``0`` is returned;
-   the address in *\*string* may differ from its input value.  If the reallocation
-   fails, the original string object at *\*string* is deallocated, *\*string* is
-   set to *NULL*, a memory exception is set, and ``-1`` is returned.
-
-
-.. cfunction:: PyObject* PyString_Format(PyObject *format, PyObject *args)
-
-   Return a new string object from *format* and *args*. Analogous to ``format %
-   args``.  The *args* argument must be a tuple.
-
-
-.. cfunction:: void PyString_InternInPlace(PyObject **string)
-
-   Intern the argument *\*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 *\*string*, it sets *\*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 *\*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.)
-
-
-.. cfunction:: PyObject* PyString_InternFromString(const char *v)
-
-   A combination of :cfunc:`PyString_FromString` and
-   :cfunc:`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.
-
-
-.. cfunction:: PyObject* PyString_Decode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)
-
-   Create an object by decoding *size* bytes of the encoded buffer *s* using the
-   codec registered for *encoding*.  *encoding* and *errors* have the same meaning
-   as the parameters of the same name in the :func:`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.
-
-
-.. cfunction:: PyObject* PyString_AsDecodedObject(PyObject *str, const char *encoding, const char *errors)
-
-   Decode a string object by passing it to the codec registered for *encoding* and
-   return the result as Python object. *encoding* and *errors* have the same
-   meaning as the parameters of the same name in the string :meth:`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.
-
-
-.. cfunction:: PyObject* PyString_AsEncodedObject(PyObject *str, const char *encoding, const char *errors)
-
-   Encode a string object using the codec registered for *encoding* and return the
-   result as Python object. *encoding* and *errors* have the same meaning as the
-   parameters of the same name in the string :meth:`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.
-
-
-.. _unicodeobjects:
-
-Unicode Objects
----------------
-
-.. sectionauthor:: Marc-Andre Lemburg <mal at lemburg.com>
-
-
-These are the basic Unicode object types used for the Unicode implementation in
-Python:
-
-.. % --- Unicode Type -------------------------------------------------------
-
-
-.. ctype:: 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).
-
-Note that UCS2 and UCS4 Python builds are not binary compatible. Please keep
-this in mind when writing extensions or interfaces.
-
-
-.. ctype:: PyUnicodeObject
-
-   This subtype of :ctype:`PyObject` represents a Python Unicode object.
-
-
-.. cvar:: PyTypeObject PyUnicode_Type
-
-   This instance of :ctype:`PyTypeObject` represents the Python Unicode type.  It
-   is exposed to Python code as ``str``.
-
-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:
-
-
-.. cfunction:: int PyUnicode_Check(PyObject *o)
-
-   Return true if the object *o* is a Unicode object or an instance of a Unicode
-   subtype.
-
-
-.. cfunction:: int PyUnicode_CheckExact(PyObject *o)
-
-   Return true if the object *o* is a Unicode object, but not an instance of a
-   subtype.
-
-
-.. cfunction:: Py_ssize_t PyUnicode_GET_SIZE(PyObject *o)
-
-   Return the size of the object.  *o* has to be a :ctype:`PyUnicodeObject` (not
-   checked).
-
-
-.. cfunction:: Py_ssize_t PyUnicode_GET_DATA_SIZE(PyObject *o)
-
-   Return the size of the object's internal buffer in bytes.  *o* has to be a
-   :ctype:`PyUnicodeObject` (not checked).
-
-
-.. cfunction:: Py_UNICODE* PyUnicode_AS_UNICODE(PyObject *o)
-
-   Return a pointer to the internal :ctype:`Py_UNICODE` buffer of the object.  *o*
-   has to be a :ctype:`PyUnicodeObject` (not checked).
-
-
-.. cfunction:: const char* PyUnicode_AS_DATA(PyObject *o)
-
-   Return a pointer to the internal buffer of the object. *o* has to be a
-   :ctype:`PyUnicodeObject` (not checked).
-
-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.
-
-.. % --- Unicode character properties ---------------------------------------
-
-
-.. cfunction:: int Py_UNICODE_ISSPACE(Py_UNICODE ch)
-
-   Return 1 or 0 depending on whether *ch* is a whitespace character.
-
-
-.. cfunction:: int Py_UNICODE_ISLOWER(Py_UNICODE ch)
-
-   Return 1 or 0 depending on whether *ch* is a lowercase character.
-
-
-.. cfunction:: int Py_UNICODE_ISUPPER(Py_UNICODE ch)
-
-   Return 1 or 0 depending on whether *ch* is an uppercase character.
-
-
-.. cfunction:: int Py_UNICODE_ISTITLE(Py_UNICODE ch)
-
-   Return 1 or 0 depending on whether *ch* is a titlecase character.
-
-
-.. cfunction:: int Py_UNICODE_ISLINEBREAK(Py_UNICODE ch)
-
-   Return 1 or 0 depending on whether *ch* is a linebreak character.
-
-
-.. cfunction:: int Py_UNICODE_ISDECIMAL(Py_UNICODE ch)
-
-   Return 1 or 0 depending on whether *ch* is a decimal character.
-
-
-.. cfunction:: int Py_UNICODE_ISDIGIT(Py_UNICODE ch)
-
-   Return 1 or 0 depending on whether *ch* is a digit character.
-
-
-.. cfunction:: int Py_UNICODE_ISNUMERIC(Py_UNICODE ch)
-
-   Return 1 or 0 depending on whether *ch* is a numeric character.
-
-
-.. cfunction:: int Py_UNICODE_ISALPHA(Py_UNICODE ch)
-
-   Return 1 or 0 depending on whether *ch* is an alphabetic character.
-
-
-.. cfunction:: int Py_UNICODE_ISALNUM(Py_UNICODE ch)
-
-   Return 1 or 0 depending on whether *ch* is an alphanumeric character.
-
-These APIs can be used for fast direct character conversions:
-
-
-.. cfunction:: Py_UNICODE Py_UNICODE_TOLOWER(Py_UNICODE ch)
-
-   Return the character *ch* converted to lower case.
-
-
-.. cfunction:: Py_UNICODE Py_UNICODE_TOUPPER(Py_UNICODE ch)
-
-   Return the character *ch* converted to upper case.
-
-
-.. cfunction:: Py_UNICODE Py_UNICODE_TOTITLE(Py_UNICODE ch)
-
-   Return the character *ch* converted to title case.
-
-
-.. cfunction:: int Py_UNICODE_TODECIMAL(Py_UNICODE ch)
-
-   Return the character *ch* converted to a decimal positive integer.  Return
-   ``-1`` if this is not possible.  This macro does not raise exceptions.
-
-
-.. cfunction:: int Py_UNICODE_TODIGIT(Py_UNICODE ch)
-
-   Return the character *ch* converted to a single digit integer. Return ``-1`` if
-   this is not possible.  This macro does not raise exceptions.
-
-
-.. cfunction:: double Py_UNICODE_TONUMERIC(Py_UNICODE ch)
-
-   Return the character *ch* converted to a double. Return ``-1.0`` if this is not
-   possible.  This macro does not raise exceptions.
-
-To create Unicode objects and access their basic sequence properties, use these
-APIs:
-
-.. % --- Plain Py_UNICODE ---------------------------------------------------
-
-
-.. cfunction:: PyObject* PyUnicode_FromUnicode(const Py_UNICODE *u, Py_ssize_t size)
-
-   Create a Unicode Object from the Py_UNICODE buffer *u* of the given size. *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 *u*
-   is *NULL*.
-
-
-.. cfunction:: PyObject* PyUnicode_FromStringAndSize(const char *u, Py_ssize_t size)
-
-   Create a Unicode Object from the char buffer *u*.  The bytes will be interpreted
-   as being UTF-8 encoded.  *u* may also 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 *u* is *NULL*.
-
-
-.. cfunction:: PyObject *PyUnicode_FromString(const char *u)
-
-   Create a Unicode object from an UTF-8 encoded null-terminated char buffer
-   *u*.
-
-
-.. cfunction:: PyObject* PyUnicode_FromFormat(const char *format, ...)
-
-   Take a C :cfunc:`printf`\ -style *format* string and a variable number of
-   arguments, calculate the size of the resulting Python unicode 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 *format*
-   string.  The following format characters are allowed:
-
-   .. % 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.
-
-   +-------------------+---------------------+--------------------------------+
-   | Format Characters | Type                | Comment                        |
-   +===================+=====================+================================+
-   | :attr:`%%`        | *n/a*               | The literal % character.       |
-   +-------------------+---------------------+--------------------------------+
-   | :attr:`%c`        | int                 | A single character,            |
-   |                   |                     | represented as an C int.       |
-   +-------------------+---------------------+--------------------------------+
-   | :attr:`%d`        | int                 | Exactly equivalent to          |
-   |                   |                     | ``printf("%d")``.              |
-   +-------------------+---------------------+--------------------------------+
-   | :attr:`%u`        | unsigned int        | Exactly equivalent to          |
-   |                   |                     | ``printf("%u")``.              |
-   +-------------------+---------------------+--------------------------------+
-   | :attr:`%ld`       | long                | Exactly equivalent to          |
-   |                   |                     | ``printf("%ld")``.             |
-   +-------------------+---------------------+--------------------------------+
-   | :attr:`%lu`       | unsigned long       | Exactly equivalent to          |
-   |                   |                     | ``printf("%lu")``.             |
-   +-------------------+---------------------+--------------------------------+
-   | :attr:`%zd`       | Py_ssize_t          | Exactly equivalent to          |
-   |                   |                     | ``printf("%zd")``.             |
-   +-------------------+---------------------+--------------------------------+
-   | :attr:`%zu`       | size_t              | Exactly equivalent to          |
-   |                   |                     | ``printf("%zu")``.             |
-   +-------------------+---------------------+--------------------------------+
-   | :attr:`%i`        | int                 | Exactly equivalent to          |
-   |                   |                     | ``printf("%i")``.              |
-   +-------------------+---------------------+--------------------------------+
-   | :attr:`%x`        | int                 | Exactly equivalent to          |
-   |                   |                     | ``printf("%x")``.              |
-   +-------------------+---------------------+--------------------------------+
-   | :attr:`%s`        | char\*              | A null-terminated C character  |
-   |                   |                     | array.                         |
-   +-------------------+---------------------+--------------------------------+
-   | :attr:`%p`        | void\*              | The hex representation of a C  |
-   |                   |                     | pointer. Mostly equivalent to  |
-   |                   |                     | ``printf("%p")`` except that   |
-   |                   |                     | it is guaranteed to start with |
-   |                   |                     | the literal ``0x`` regardless  |
-   |                   |                     | of what the platform's         |
-   |                   |                     | ``printf`` yields.             |
-   +-------------------+---------------------+--------------------------------+
-   | :attr:`%U`        | PyObject\*          | A unicode object.              |
-   +-------------------+---------------------+--------------------------------+
-   | :attr:`%V`        | PyObject\*, char \* | A unicode object (which may be |
-   |                   |                     | *NULL*) and a null-terminated  |
-   |                   |                     | C character array as a second  |
-   |                   |                     | parameter (which will be used, |
-   |                   |                     | if the first parameter is      |
-   |                   |                     | *NULL*).                       |
-   +-------------------+---------------------+--------------------------------+
-   | :attr:`%S`        | PyObject\*          | The result of calling          |
-   |                   |                     | :func:`PyObject_Unicode`.      |
-   +-------------------+---------------------+--------------------------------+
-   | :attr:`%R`        | PyObject\*          | The result of calling          |
-   |                   |                     | :func:`PyObject_Repr`.         |
-   +-------------------+---------------------+--------------------------------+
-
-   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.
-
-
-.. cfunction:: PyObject* PyUnicode_FromFormatV(const char *format, va_list vargs)
-
-   Identical to :func:`PyUnicode_FromFormat` except that it takes exactly two
-   arguments.
-
-
-.. cfunction:: Py_UNICODE* PyUnicode_AsUnicode(PyObject *unicode)
-
-   Return a read-only pointer to the Unicode object's internal :ctype:`Py_UNICODE`
-   buffer, *NULL* if *unicode* is not a Unicode object.
-
-
-.. cfunction:: Py_ssize_t PyUnicode_GetSize(PyObject *unicode)
-
-   Return the length of the Unicode object.
-
-
-.. cfunction:: PyObject* PyUnicode_FromEncodedObject(PyObject *obj, const char *encoding, const char *errors)
-
-   Coerce an encoded object *obj* to an Unicode object and return a reference with
-   incremented refcount.
-
-   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 :exc:`TypeError` to be
-   set.
-
-   The API returns *NULL* if there was an error.  The caller is responsible for
-   decref'ing the returned objects.
-
-
-.. cfunction:: PyObject* PyUnicode_FromObject(PyObject *obj)
-
-   Shortcut for ``PyUnicode_FromEncodedObject(obj, NULL, "strict")`` which is used
-   throughout the interpreter whenever coercion to Unicode is needed.
-
-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`.
-
-.. % --- wchar_t support for platforms which support it ---------------------
-
-
-.. cfunction:: PyObject* PyUnicode_FromWideChar(const wchar_t *w, Py_ssize_t size)
-
-   Create a Unicode object from the :ctype:`wchar_t` buffer *w* of the given size.
-   Return *NULL* on failure.
-
-
-.. cfunction:: 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 *w*.  At most
-   *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.
-
-
-.. _builtincodecs:
-
-Built-in Codecs
-^^^^^^^^^^^^^^^
-
-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" (:exc:`ValueError` is raised).
-
-The codecs all use a similar interface.  Only deviation from the following
-generic ones are documented for simplicity.
-
-These are the generic codec APIs:
-
-.. % --- Generic Codecs -----------------------------------------------------
-
-
-.. cfunction:: PyObject* PyUnicode_Decode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)
-
-   Create a Unicode object by decoding *size* bytes of the encoded string *s*.
-   *encoding* and *errors* have the same meaning as the parameters of the same name
-   in the :func:`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.
-
-
-.. cfunction:: 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.  *encoding* and *errors* have the same meaning as the parameters
-   of the same name in the Unicode :meth:`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.
-
-
-.. cfunction:: PyObject* PyUnicode_AsEncodedString(PyObject *unicode, const char *encoding, const char *errors)
-
-   Encode a Unicode object and return the result as Python string object.
-   *encoding* and *errors* have the same meaning as the parameters of the same name
-   in the Unicode :meth:`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.
-
-These are the UTF-8 codec APIs:
-
-.. % --- UTF-8 Codecs -------------------------------------------------------
-
-
-.. cfunction:: PyObject* PyUnicode_DecodeUTF8(const char *s, Py_ssize_t size, const char *errors)
-
-   Create a Unicode object by decoding *size* bytes of the UTF-8 encoded string
-   *s*. Return *NULL* if an exception was raised by the codec.
-
-
-.. cfunction:: PyObject* PyUnicode_DecodeUTF8Stateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)
-
-   If *consumed* is *NULL*, behave like :cfunc:`PyUnicode_DecodeUTF8`. If
-   *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 *consumed*.
-
-
-.. cfunction:: 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.
-
-
-.. cfunction:: PyObject* PyUnicode_AsUTF8String(PyObject *unicode)
-
-   Encode a Unicode object 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.
-
-These are the UTF-32 codec APIs:
-
-.. % --- UTF-32 Codecs ------------------------------------------------------ */
-
-
-.. cfunction:: PyObject* PyUnicode_DecodeUTF32(const char *s, Py_ssize_t size, const char *errors, int *byteorder)
-
-   Decode *length* bytes from a UTF-32 encoded buffer string and return the
-   corresponding Unicode object.  *errors* (if non-*NULL*) defines the error
-   handling. It defaults to "strict".
-
-   If *byteorder* is non-*NULL*, the decoder starts decoding using the given byte
-   order::
-
-      *byteorder == -1: little endian
-      *byteorder == 0:  native order
-      *byteorder == 1:  big endian
-
-   and then switches if the first four bytes of the input data are a byte order mark
-   (BOM) and the specified byte order is native order.  This BOM is not copied into
-   the resulting Unicode string.  After completion, *\*byteorder* is set to the
-   current byte order at the end of input data.
-
-   In a narrow build codepoints outside the BMP will be decoded as surrogate pairs.
-
-   If *byteorder* is *NULL*, the codec starts in native order mode.
-
-   Return *NULL* if an exception was raised by the codec.
-
-
-.. cfunction:: PyObject* PyUnicode_DecodeUTF32Stateful(const char *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)
-
-   If *consumed* is *NULL*, behave like :cfunc:`PyUnicode_DecodeUTF32`. If
-   *consumed* is not *NULL*, :cfunc:`PyUnicode_DecodeUTF32Stateful` will not treat
-   trailing incomplete UTF-32 byte sequences (such as a number of bytes not divisible
-   by four) as an error. Those bytes will not be decoded and the number of bytes
-   that have been decoded will be stored in *consumed*.
-
-
-.. cfunction:: PyObject* PyUnicode_EncodeUTF32(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder)
-
-   Return a Python bytes object holding the UTF-32 encoded value of the Unicode
-   data in *s*.  If *byteorder* is not ``0``, output is written according to the
-   following byte order::
-
-      byteorder == -1: little endian
-      byteorder == 0:  native byte order (writes a BOM mark)
-      byteorder == 1:  big endian
-
-   If byteorder is ``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 *Py_UNICODE_WIDE* is not defined, surrogate pairs will be output
-   as a single codepoint.
-
-   Return *NULL* if an exception was raised by the codec.
-
-
-.. cfunction:: PyObject* PyUnicode_AsUTF32String(PyObject *unicode)
-
-   Return a Python string using the UTF-32 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.
-
-
-These are the UTF-16 codec APIs:
-
-.. % --- UTF-16 Codecs ------------------------------------------------------ */
-
-
-.. cfunction:: PyObject* PyUnicode_DecodeUTF16(const char *s, Py_ssize_t size, const char *errors, int *byteorder)
-
-   Decode *length* bytes from a UTF-16 encoded buffer string and return the
-   corresponding Unicode object.  *errors* (if non-*NULL*) defines the error
-   handling. It defaults to "strict".
-
-   If *byteorder* is non-*NULL*, the decoder starts decoding using the given byte
-   order::
-
-      *byteorder == -1: little endian
-      *byteorder == 0:  native order
-      *byteorder == 1:  big endian
-
-   and then switches if the first two bytes of the input data are a byte order mark
-   (BOM) and the specified byte order is native order.  This BOM is not copied into
-   the resulting Unicode string.  After completion, *\*byteorder* is set to the
-   current byte order at the end of input data.
-
-   If *byteorder* is *NULL*, the codec starts in native order mode.
-
-   Return *NULL* if an exception was raised by the codec.
-
-
-.. cfunction:: PyObject* PyUnicode_DecodeUTF16Stateful(const char *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)
-
-   If *consumed* is *NULL*, behave like :cfunc:`PyUnicode_DecodeUTF16`. If
-   *consumed* is not *NULL*, :cfunc:`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 *consumed*.
-
-
-.. cfunction:: 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 *s*.  If *byteorder* is not ``0``, output is written according to the
-   following byte order::
-
-      byteorder == -1: little endian
-      byteorder == 0:  native byte order (writes a BOM mark)
-      byteorder == 1:  big endian
-
-   If byteorder is ``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 *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.
-
-
-.. cfunction:: 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.
-
-These are the "Unicode Escape" codec APIs:
-
-.. % --- Unicode-Escape Codecs ----------------------------------------------
-
-
-.. cfunction:: PyObject* PyUnicode_DecodeUnicodeEscape(const char *s, Py_ssize_t size, const char *errors)
-
-   Create a Unicode object by decoding *size* bytes of the Unicode-Escape encoded
-   string *s*.  Return *NULL* if an exception was raised by the codec.
-
-
-.. cfunction:: 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.
-
-
-.. cfunction:: PyObject* PyUnicode_AsUnicodeEscapeString(PyObject *unicode)
-
-   Encode a Unicode object 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.
-
-These are the "Raw Unicode Escape" codec APIs:
-
-.. % --- Raw-Unicode-Escape Codecs ------------------------------------------
-
-
-.. cfunction:: PyObject* PyUnicode_DecodeRawUnicodeEscape(const char *s, Py_ssize_t size, const char *errors)
-
-   Create a Unicode object by decoding *size* bytes of the Raw-Unicode-Escape
-   encoded string *s*.  Return *NULL* if an exception was raised by the codec.
-
-
-.. cfunction:: 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.
-
-
-.. cfunction:: PyObject* PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)
-
-   Encode a Unicode object 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.
-
-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.
-
-.. % --- Latin-1 Codecs -----------------------------------------------------
-
-
-.. cfunction:: PyObject* PyUnicode_DecodeLatin1(const char *s, Py_ssize_t size, const char *errors)
-
-   Create a Unicode object by decoding *size* bytes of the Latin-1 encoded string
-   *s*.  Return *NULL* if an exception was raised by the codec.
-
-
-.. cfunction:: 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.
-
-
-.. cfunction:: PyObject* PyUnicode_AsLatin1String(PyObject *unicode)
-
-   Encode a Unicode object 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.
-
-These are the ASCII codec APIs.  Only 7-bit ASCII data is accepted. All other
-codes generate errors.
-
-.. % --- ASCII Codecs -------------------------------------------------------
-
-
-.. cfunction:: PyObject* PyUnicode_DecodeASCII(const char *s, Py_ssize_t size, const char *errors)
-
-   Create a Unicode object by decoding *size* bytes of the ASCII encoded string
-   *s*.  Return *NULL* if an exception was raised by the codec.
-
-
-.. cfunction:: 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.
-
-
-.. cfunction:: PyObject* PyUnicode_AsASCIIString(PyObject *unicode)
-
-   Encode a Unicode object using ASCII and return the result as Python string
-   object.  Error handling is "strict".  Return *NULL* if an exception was raised
-   by the codec.
-
-These are the mapping codec APIs:
-
-.. % --- Character Map Codecs -----------------------------------------------
-
-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 :mod:`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.
-
-
-.. cfunction:: PyObject* PyUnicode_DecodeCharmap(const char *s, Py_ssize_t size, PyObject *mapping, const char *errors)
-
-   Create a Unicode object by decoding *size* bytes of the encoded string *s* using
-   the given *mapping* object.  Return *NULL* if an exception was raised by the
-   codec. If *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".
-
-
-.. cfunction:: 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
-   *mapping* object and return a Python string object. Return *NULL* if an
-   exception was raised by the codec.
-
-
-.. cfunction:: PyObject* PyUnicode_AsCharmapString(PyObject *unicode, PyObject *mapping)
-
-   Encode a Unicode object using the given *mapping* object and return the result
-   as Python string object.  Error handling is "strict".  Return *NULL* if an
-   exception was raised by the codec.
-
-The following codec API is special in that maps Unicode to Unicode.
-
-
-.. cfunction:: 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 *table* to it and return the resulting Unicode object.  Return
-   *NULL* when an exception was raised by the codec.
-
-   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 :meth:`__getitem__` interface; dictionaries
-   and sequences work well.  Unmapped character ordinals (ones which cause a
-   :exc:`LookupError`) are left untouched and are copied as-is.
-
-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.
-
-.. % --- MBCS codecs for Windows --------------------------------------------
-
-
-.. cfunction:: PyObject* PyUnicode_DecodeMBCS(const char *s, Py_ssize_t size, const char *errors)
-
-   Create a Unicode object by decoding *size* bytes of the MBCS encoded string *s*.
-   Return *NULL* if an exception was raised by the codec.
-
-
-.. cfunction:: PyObject* PyUnicode_DecodeMBCSStateful(const char *s, int size, const char *errors, int *consumed)
-
-   If *consumed* is *NULL*, behave like :cfunc:`PyUnicode_DecodeMBCS`. If
-   *consumed* is not *NULL*, :cfunc:`PyUnicode_DecodeMBCSStateful` will not decode
-   trailing lead byte and the number of bytes that have been decoded will be stored
-   in *consumed*.
-
-
-.. cfunction:: 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.
-
-
-.. cfunction:: PyObject* PyUnicode_AsMBCSString(PyObject *unicode)
-
-   Encode a Unicode object using MBCS and return the result as Python string
-   object.  Error handling is "strict".  Return *NULL* if an exception was raised
-   by the codec.
-
-.. % --- Methods & Slots ----------------------------------------------------
-
-
-.. _unicodemethodsandslots:
-
-Methods and Slot Functions
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-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 ``-1`` if an exception occurs.
-
-
-.. cfunction:: PyObject* PyUnicode_Concat(PyObject *left, PyObject *right)
-
-   Concat two strings giving a new Unicode string.
-
-
-.. cfunction:: 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 *maxsplit* splits will be done.  If negative, no limit is
-   set.  Separators are not included in the resulting list.
-
-
-.. cfunction:: 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 *keepend* is 0, the Line break
-   characters are not included in the resulting strings.
-
-
-.. cfunction:: 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 :meth:`__getitem__` interface; dictionaries
-   and sequences work well.  Unmapped character ordinals (ones which cause a
-   :exc:`LookupError`) are left untouched and are copied as-is.
-
-   *errors* has the usual meaning for codecs. It may be *NULL* which indicates to
-   use the default error handling.
-
-
-.. cfunction:: PyObject* PyUnicode_Join(PyObject *separator, PyObject *seq)
-
-   Join a sequence of strings using the given separator and return the resulting
-   Unicode string.
-
-
-.. cfunction:: int PyUnicode_Tailmatch(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)
-
-   Return 1 if *substr* matches *str*[*start*:*end*] at the given tail end
-   (*direction* == -1 means to do a prefix match, *direction* == 1 a suffix match),
-   0 otherwise. Return ``-1`` if an error occurred.
-
-
-.. cfunction:: Py_ssize_t PyUnicode_Find(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)
-
-   Return the first position of *substr* in *str*[*start*:*end*] using the given
-   *direction* (*direction* == 1 means to do a forward search, *direction* == -1 a
-   backward search).  The return value is the index of the first match; a value of
-   ``-1`` indicates that no match was found, and ``-2`` indicates that an error
-   occurred and an exception has been set.
-
-
-.. cfunction:: 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 *substr* in
-   ``str[start:end]``.  Return ``-1`` if an error occurred.
-
-
-.. cfunction:: PyObject* PyUnicode_Replace(PyObject *str, PyObject *substr, PyObject *replstr, Py_ssize_t maxcount)
-
-   Replace at most *maxcount* occurrences of *substr* in *str* with *replstr* and
-   return the resulting Unicode object. *maxcount* == -1 means replace all
-   occurrences.
-
-
-.. cfunction:: int PyUnicode_Compare(PyObject *left, PyObject *right)
-
-   Compare two strings and return -1, 0, 1 for less than, equal, and greater than,
-   respectively.
-
-
-.. cfunction:: int PyUnicode_RichCompare(PyObject *left,  PyObject *right,  int op)
-
-   Rich compare two unicode strings and return one of the following:
-
-   * ``NULL`` in case an exception was raised
-   * :const:`Py_True` or :const:`Py_False` for successful comparisons
-   * :const:`Py_NotImplemented` in case the type combination is unknown
-
-   Note that :const:`Py_EQ` and :const:`Py_NE` comparisons can cause a
-   :exc:`UnicodeWarning` in case the conversion of the arguments to Unicode fails
-   with a :exc:`UnicodeDecodeError`.
-
-   Possible values for *op* are :const:`Py_GT`, :const:`Py_GE`, :const:`Py_EQ`,
-   :const:`Py_NE`, :const:`Py_LT`, and :const:`Py_LE`.
-
-
-.. cfunction:: PyObject* PyUnicode_Format(PyObject *format, PyObject *args)
-
-   Return a new string object from *format* and *args*; this is analogous to
-   ``format % args``.  The *args* argument must be a tuple.
-
-
-.. cfunction:: int PyUnicode_Contains(PyObject *container, PyObject *element)
-
-   Check whether *element* is contained in *container* and return true or false
-   accordingly.
-
-   *element* has to coerce to a one element Unicode string. ``-1`` is returned if
-   there was an error.
-
-
-.. cfunction:: void PyUnicode_InternInPlace(PyObject **string)
-
-   Intern the argument *\*string* in place.  The argument must be the address of a
-   pointer variable pointing to a Python unicode string object.  If there is an
-   existing interned string that is the same as *\*string*, it sets *\*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
-   *\*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.)
-
-
-.. cfunction:: PyObject* PyUnicode_InternFromString(const char *v)
-
-   A combination of :cfunc:`PyUnicode_FromString` and
-   :cfunc:`PyUnicode_InternInPlace`, returning either a new unicode string object
-   that has been interned, or a new ("owned") reference to an earlier interned
-   string object with the same value.
-
-
-.. _bufferobjects:
-
-Buffer Objects
---------------
-
-.. sectionauthor:: Greg Stein <gstein at lyra.org>
-
-
-.. index::
-   object: buffer
-   single: buffer interface
-
-Python objects implemented in C can export a group of functions called the
-"buffer 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 :meth:`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
-:cfunc:`PyArg_ParseTuple` that operate against an object's buffer interface,
-returning data from the target object.
-
-.. index:: single: PyBufferProcs
-
-More information on the buffer interface is provided in the section 
-:ref:`buffer-structs`, under the description for :ctype:`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.
-
-
-.. ctype:: PyBufferObject
-
-   This subtype of :ctype:`PyObject` represents a buffer object.
-
-
-.. cvar:: PyTypeObject PyBuffer_Type
-
-   .. index:: single: BufferType (in module types)
-
-   The instance of :ctype:`PyTypeObject` which represents the Python buffer type;
-   it is the same object as ``buffer`` and  ``types.BufferType`` in the Python
-   layer. .
-
-
-.. cvar:: int Py_END_OF_BUFFER
-
-   This constant may be passed as the *size* parameter to
-   :cfunc:`PyBuffer_FromObject` or :cfunc:`PyBuffer_FromReadWriteObject`.  It
-   indicates that the new :ctype:`PyBufferObject` should refer to *base* object
-   from the specified *offset* to the end of its exported buffer.  Using this
-   enables the caller to avoid querying the *base* object for its length.
-
-
-.. cfunction:: int PyBuffer_Check(PyObject *p)
-
-   Return true if the argument has type :cdata:`PyBuffer_Type`.
-
-
-.. cfunction:: PyObject* PyBuffer_FromObject(PyObject *base, Py_ssize_t offset, Py_ssize_t size)
-
-   Return a new read-only buffer object.  This raises :exc:`TypeError` if *base*
-   doesn't support the read-only buffer protocol or doesn't provide exactly one
-   buffer segment, or it raises :exc:`ValueError` if *offset* is less than zero.
-   The buffer will hold a reference to the *base* object, and the buffer's contents
-   will refer to the *base* object's buffer interface, starting as position
-   *offset* and extending for *size* bytes. If *size* is :const:`Py_END_OF_BUFFER`,
-   then the new buffer's contents extend to the length of the *base* object's
-   exported buffer data.
-
-
-.. cfunction:: 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 :cfunc:`PyBuffer_FromObject`.  If the *base* object does not export
-   the writable buffer protocol, then :exc:`TypeError` is raised.
-
-
-.. cfunction:: 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 *ptr*, is not deallocated while the returned buffer
-   object exists.  Raises :exc:`ValueError` if *size* is less than zero.  Note that
-   :const:`Py_END_OF_BUFFER` may *not* be passed for the *size* parameter;
-   :exc:`ValueError` will be raised in that case.
-
-
-.. cfunction:: PyObject* PyBuffer_FromReadWriteMemory(void *ptr, Py_ssize_t size)
-
-   Similar to :cfunc:`PyBuffer_FromMemory`, but the returned buffer is writable.
-
-
-.. cfunction:: PyObject* PyBuffer_New(Py_ssize_t size)
-
-   Return a new writable buffer object that maintains its own memory buffer of
-   *size* bytes.  :exc:`ValueError` is returned if *size* is not zero or positive.
-   Note that the memory buffer (as returned by :cfunc:`PyObject_AsWriteBuffer`) is
-   not specifically aligned.
-
-
-.. _tupleobjects:
-
-Tuple Objects
--------------
-
-.. index:: object: tuple
-
-
-.. ctype:: PyTupleObject
-
-   This subtype of :ctype:`PyObject` represents a Python tuple object.
-
-
-.. cvar:: PyTypeObject PyTuple_Type
-
-   .. index:: single: TupleType (in module types)
-
-   This instance of :ctype:`PyTypeObject` represents the Python tuple type; it is
-   the same object as ``tuple`` and ``types.TupleType`` in the Python layer..
-
-
-.. cfunction:: int PyTuple_Check(PyObject *p)
-
-   Return true if *p* is a tuple object or an instance of a subtype of the tuple
-   type.
-
-
-.. cfunction:: int PyTuple_CheckExact(PyObject *p)
-
-   Return true if *p* is a tuple object, but not an instance of a subtype of the
-   tuple type.
-
-
-.. cfunction:: PyObject* PyTuple_New(Py_ssize_t len)
-
-   Return a new tuple object of size *len*, or *NULL* on failure.
-
-
-.. cfunction:: PyObject* PyTuple_Pack(Py_ssize_t n, ...)
-
-   Return a new tuple object of size *n*, or *NULL* on failure. The tuple values
-   are initialized to the subsequent *n* C arguments pointing to Python objects.
-   ``PyTuple_Pack(2, a, b)`` is equivalent to ``Py_BuildValue("(OO)", a, b)``.
-
-
-.. cfunction:: Py_ssize_t PyTuple_Size(PyObject *p)
-
-   Take a pointer to a tuple object, and return the size of that tuple.
-
-
-.. cfunction:: Py_ssize_t PyTuple_GET_SIZE(PyObject *p)
-
-   Return the size of the tuple *p*, which must be non-*NULL* and point to a tuple;
-   no error checking is performed.
-
-
-.. cfunction:: PyObject* PyTuple_GetItem(PyObject *p, Py_ssize_t pos)
-
-   Return the object at position *pos* in the tuple pointed to by *p*.  If *pos* is
-   out of bounds, return *NULL* and sets an :exc:`IndexError` exception.
-
-
-.. cfunction:: PyObject* PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos)
-
-   Like :cfunc:`PyTuple_GetItem`, but does no checking of its arguments.
-
-
-.. cfunction:: PyObject* PyTuple_GetSlice(PyObject *p, Py_ssize_t low, Py_ssize_t high)
-
-   Take a slice of the tuple pointed to by *p* from *low* to *high* and return it
-   as a new tuple.
-
-
-.. cfunction:: int PyTuple_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)
-
-   Insert a reference to object *o* at position *pos* of the tuple pointed to by
-   *p*. Return ``0`` on success.
-
-   .. note::
-
-      This function "steals" a reference to *o*.
-
-
-.. cfunction:: void PyTuple_SET_ITEM(PyObject *p, Py_ssize_t pos, PyObject *o)
-
-   Like :cfunc:`PyTuple_SetItem`, but does no error checking, and should *only* be
-   used to fill in brand new tuples.
-
-   .. note::
-
-      This function "steals" a reference to *o*.
-
-
-.. cfunction:: int _PyTuple_Resize(PyObject **p, Py_ssize_t newsize)
-
-   Can be used to resize a tuple.  *newsize* will be the new length of the tuple.
-   Because tuples are *supposed* to be immutable, this should only be used if there
-   is only one reference to the object.  Do *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 ``0`` on success. Client code should never
-   assume that the resulting value of ``*p`` will be the same as before calling
-   this function. If the object referenced by ``*p`` is replaced, the original
-   ``*p`` is destroyed.  On failure, returns ``-1`` and sets ``*p`` to *NULL*, and
-   raises :exc:`MemoryError` or :exc:`SystemError`.
-
-
-.. _listobjects:
-
-List Objects
-------------
-
-.. index:: object: list
-
-
-.. ctype:: PyListObject
-
-   This subtype of :ctype:`PyObject` represents a Python list object.
-
-
-.. cvar:: PyTypeObject PyList_Type
-
-   .. index:: single: ListType (in module types)
-
-   This instance of :ctype:`PyTypeObject` represents the Python list type.  This is
-   the same object as ``list`` and ``types.ListType`` in the Python layer.
-
-
-.. cfunction:: int PyList_Check(PyObject *p)
-
-   Return true if *p* is a list object or an instance of a subtype of the list
-   type.
-
-
-.. cfunction:: int PyList_CheckExact(PyObject *p)
-
-   Return true if *p* is a list object, but not an instance of a subtype of the
-   list type.
-
-
-.. cfunction:: PyObject* PyList_New(Py_ssize_t len)
-
-   Return a new list of length *len* on success, or *NULL* on failure.
-
-   .. note::
-
-      If *length* is greater than zero, the returned list object's items are set to
-      ``NULL``.  Thus you cannot use abstract API functions such as
-      :cfunc:`PySequence_SetItem`  or expose the object to Python code before setting
-      all items to a real object with :cfunc:`PyList_SetItem`.
-
-
-.. cfunction:: Py_ssize_t PyList_Size(PyObject *list)
-
-   .. index:: builtin: len
-
-   Return the length of the list object in *list*; this is equivalent to
-   ``len(list)`` on a list object.
-
-
-.. cfunction:: Py_ssize_t PyList_GET_SIZE(PyObject *list)
-
-   Macro form of :cfunc:`PyList_Size` without error checking.
-
-
-.. cfunction:: PyObject* PyList_GetItem(PyObject *list, Py_ssize_t index)
-
-   Return the object at position *pos* in the list pointed to by *p*.  The position
-   must be positive, indexing from the end of the list is not supported.  If *pos*
-   is out of bounds, return *NULL* and set an :exc:`IndexError` exception.
-
-
-.. cfunction:: PyObject* PyList_GET_ITEM(PyObject *list, Py_ssize_t i)
-
-   Macro form of :cfunc:`PyList_GetItem` without error checking.
-
-
-.. cfunction:: int PyList_SetItem(PyObject *list, Py_ssize_t index, PyObject *item)
-
-   Set the item at index *index* in list to *item*.  Return ``0`` on success or
-   ``-1`` on failure.
-
-   .. note::
-
-      This function "steals" a reference to *item* and discards a reference to an item
-      already in the list at the affected position.
-
-
-.. cfunction:: void PyList_SET_ITEM(PyObject *list, Py_ssize_t i, PyObject *o)
-
-   Macro form of :cfunc:`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 *item*, and, unlike
-      :cfunc:`PyList_SetItem`, does *not* discard a reference to any item that it
-      being replaced; any reference in *list* at position *i* will be leaked.
-
-
-.. cfunction:: int PyList_Insert(PyObject *list, Py_ssize_t index, PyObject *item)
-
-   Insert the item *item* into list *list* in front of index *index*.  Return ``0``
-   if successful; return ``-1`` and set an exception if unsuccessful.  Analogous to
-   ``list.insert(index, item)``.
-
-
-.. cfunction:: int PyList_Append(PyObject *list, PyObject *item)
-
-   Append the object *item* at the end of list *list*. Return ``0`` if successful;
-   return ``-1`` and set an exception if unsuccessful.  Analogous to
-   ``list.append(item)``.
-
-
-.. cfunction:: PyObject* PyList_GetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high)
-
-   Return a list of the objects in *list* containing the objects *between* *low*
-   and *high*.  Return *NULL* and set an exception if unsuccessful. Analogous to
-   ``list[low:high]``.
-
-
-.. cfunction:: int PyList_SetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high, PyObject *itemlist)
-
-   Set the slice of *list* between *low* and *high* to the contents of *itemlist*.
-   Analogous to ``list[low:high] = itemlist``. The *itemlist* may be *NULL*,
-   indicating the assignment of an empty list (slice deletion). Return ``0`` on
-   success, ``-1`` on failure.
-
-
-.. cfunction:: int PyList_Sort(PyObject *list)
-
-   Sort the items of *list* in place.  Return ``0`` on success, ``-1`` on failure.
-   This is equivalent to ``list.sort()``.
-
-
-.. cfunction:: int PyList_Reverse(PyObject *list)
-
-   Reverse the items of *list* in place.  Return ``0`` on success, ``-1`` on
-   failure.  This is the equivalent of ``list.reverse()``.
-
-
-.. cfunction:: PyObject* PyList_AsTuple(PyObject *list)
-
-   .. index:: builtin: tuple
-
-   Return a new tuple object containing the contents of *list*; equivalent to
-   ``tuple(list)``.
-
-
-.. _mapobjects:
-
-Mapping Objects
-===============
-
-.. index:: object: mapping
-
-
-.. _dictobjects:
-
-Dictionary Objects
-------------------
-
-.. index:: object: dictionary
-
-
-.. ctype:: PyDictObject
-
-   This subtype of :ctype:`PyObject` represents a Python dictionary object.
-
-
-.. cvar:: PyTypeObject PyDict_Type
-
-   .. index::
-      single: DictType (in module types)
-      single: DictionaryType (in module types)
-
-   This instance of :ctype:`PyTypeObject` represents the Python dictionary type.
-   This is exposed to Python programs as ``dict`` and ``types.DictType``.
-
-
-.. cfunction:: int PyDict_Check(PyObject *p)
-
-   Return true if *p* is a dict object or an instance of a subtype of the dict
-   type.
-
-
-.. cfunction:: int PyDict_CheckExact(PyObject *p)
-
-   Return true if *p* is a dict object, but not an instance of a subtype of the
-   dict type.
-
-
-.. cfunction:: PyObject* PyDict_New()
-
-   Return a new empty dictionary, or *NULL* on failure.
-
-
-.. cfunction:: 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.
-
-
-.. cfunction:: void PyDict_Clear(PyObject *p)
-
-   Empty an existing dictionary of all key-value pairs.
-
-
-.. cfunction:: int PyDict_Contains(PyObject *p, PyObject *key)
-
-   Determine if dictionary *p* contains *key*.  If an item in *p* is matches *key*,
-   return ``1``, otherwise return ``0``.  On error, return ``-1``.  This is
-   equivalent to the Python expression ``key in p``.
-
-
-.. cfunction:: PyObject* PyDict_Copy(PyObject *p)
-
-   Return a new dictionary that contains the same key-value pairs as *p*.
-
-
-.. cfunction:: int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)
-
-   Insert *value* into the dictionary *p* with a key of *key*.  *key* must be
-   :term:`hashable`; if it isn't, :exc:`TypeError` will be raised. Return ``0``
-   on success or ``-1`` on failure.
-
-
-.. cfunction:: int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)
-
-   .. index:: single: PyString_FromString()
-
-   Insert *value* into the dictionary *p* using *key* as a key. *key* should be a
-   :ctype:`char\*`.  The key object is created using ``PyString_FromString(key)``.
-   Return ``0`` on success or ``-1`` on failure.
-
-
-.. cfunction:: int PyDict_DelItem(PyObject *p, PyObject *key)
-
-   Remove the entry in dictionary *p* with key *key*. *key* must be hashable; if it
-   isn't, :exc:`TypeError` is raised.  Return ``0`` on success or ``-1`` on
-   failure.
-
-
-.. cfunction:: int PyDict_DelItemString(PyObject *p, char *key)
-
-   Remove the entry in dictionary *p* which has a key specified by the string
-   *key*.  Return ``0`` on success or ``-1`` on failure.
-
-
-.. cfunction:: PyObject* PyDict_GetItem(PyObject *p, PyObject *key)
-
-   Return the object from dictionary *p* which has a key *key*.  Return *NULL* if
-   the key *key* is not present, but *without* setting an exception.
-
-
-.. cfunction:: PyObject* PyDict_GetItemString(PyObject *p, const char *key)
-
-   This is the same as :cfunc:`PyDict_GetItem`, but *key* is specified as a
-   :ctype:`char\*`, rather than a :ctype:`PyObject\*`.
-
-
-.. cfunction:: PyObject* PyDict_Items(PyObject *p)
-
-   Return a :ctype:`PyListObject` containing all the items from the dictionary, as
-   in the dictionary method :meth:`dict.items`.
-
-
-.. cfunction:: PyObject* PyDict_Keys(PyObject *p)
-
-   Return a :ctype:`PyListObject` containing all the keys from the dictionary, as
-   in the dictionary method :meth:`dict.keys`.
-
-
-.. cfunction:: PyObject* PyDict_Values(PyObject *p)
-
-   Return a :ctype:`PyListObject` containing all the values from the dictionary
-   *p*, as in the dictionary method :meth:`dict.values`.
-
-
-.. cfunction:: Py_ssize_t PyDict_Size(PyObject *p)
-
-   .. index:: builtin: len
-
-   Return the number of items in the dictionary.  This is equivalent to ``len(p)``
-   on a dictionary.
-
-
-.. cfunction:: int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)
-
-   Iterate over all key-value pairs in the dictionary *p*.  The :ctype:`int`
-   referred to by *ppos* must be initialized to ``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
-   *pkey* and *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.  *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::
-
-      PyObject *key, *value;
-      Py_ssize_t pos = 0;
-
-      while (PyDict_Next(self->dict, &pos, &key, &value)) {
-          /* do something interesting with the values... */
-          ...
-      }
-
-   The dictionary *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::
-
-      PyObject *key, *value;
-      Py_ssize_t pos = 0;
-
-      while (PyDict_Next(self->dict, &pos, &key, &value)) {
-          long i = PyLong_AsLong(value);
-          if (i == -1 && PyErr_Occurred()) {
-              return -1;
-          }
-          PyObject *o = PyLong_FromLong(i + 1);
-          if (o == NULL)
-              return -1;
-          if (PyDict_SetItem(self->dict, key, o) < 0) {
-              Py_DECREF(o);
-              return -1;
-          }
-          Py_DECREF(o);
-      }
-
-
-.. cfunction:: int PyDict_Merge(PyObject *a, PyObject *b, int override)
-
-   Iterate over mapping object *b* adding key-value pairs to dictionary *a*. *b*
-   may be a dictionary, or any object supporting :func:`PyMapping_Keys` and
-   :func:`PyObject_GetItem`. If *override* is true, existing pairs in *a* will be
-   replaced if a matching key is found in *b*, otherwise pairs will only be added
-   if there is not a matching key in *a*. Return ``0`` on success or ``-1`` if an
-   exception was raised.
-
-
-.. cfunction:: int PyDict_Update(PyObject *a, PyObject *b)
-
-   This is the same as ``PyDict_Merge(a, b, 1)`` in C, or ``a.update(b)`` in
-   Python.  Return ``0`` on success or ``-1`` if an exception was raised.
-
-
-.. cfunction:: int PyDict_MergeFromSeq2(PyObject *a, PyObject *seq2, int override)
-
-   Update or merge into dictionary *a*, from the key-value pairs in *seq2*.  *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 *override* is
-   true, else the first wins. Return ``0`` on success or ``-1`` if an exception was
-   raised. Equivalent Python (except for the return value)::
-
-      def PyDict_MergeFromSeq2(a, seq2, override):
-          for key, value in seq2:
-              if override or key not in a:
-                  a[key] = value
-
-
-.. _otherobjects:
-
-Other Objects
-=============
-
-.. _fileobjects:
-
-File Objects
-------------
-
-.. index:: object: 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.
-
-
-.. ctype:: PyFileObject
-
-   This subtype of :ctype:`PyObject` represents a Python file object.
-
-
-.. cvar:: PyTypeObject PyFile_Type
-
-   .. index:: single: FileType (in module types)
-
-   This instance of :ctype:`PyTypeObject` represents the Python file type.  This is
-   exposed to Python programs as ``file`` and ``types.FileType``.
-
-
-.. cfunction:: int PyFile_Check(PyObject *p)
-
-   Return true if its argument is a :ctype:`PyFileObject` or a subtype of
-   :ctype:`PyFileObject`.
-
-
-.. cfunction:: int PyFile_CheckExact(PyObject *p)
-
-   Return true if its argument is a :ctype:`PyFileObject`, but not a subtype of
-   :ctype:`PyFileObject`.
-
-
-.. cfunction:: PyFile_FromFd(int fd, char *name, char *mode, int buffering, char *encoding, char *newline, int closefd)
-
-   Create a new :ctype:`PyFileObject` from the file descriptor of an already
-   opened file *fd*. The arguments *name*, *encoding* and *newline* can be
-   *NULL* to use the defaults; *buffering* can be *-1* to use the default.
-   Return *NULL* on failure.
-
-   .. warning::
-
-     Take care when you are mixing streams and descriptors! For more 
-     information, see `the GNU C Library docs
-     <http://www.gnu.org/software/libc/manual/html_node/Stream_002fDescriptor-Precautions.html#Stream_002fDescriptor-Precautions>`_.
-
-
-.. cfunction:: int PyObject_AsFileDescriptor(PyObject *p)
-
-   Return the file descriptor associated with *p* as an :ctype:`int`.  If the
-   object is an integer, its value is returned.  If not, the
-   object's :meth:`fileno` method is called if it exists; the method must return
-   an integer, which is returned as the file descriptor value.  Sets an
-   exception and returns ``-1`` on failure.
-
-
-.. cfunction:: PyObject* PyFile_GetLine(PyObject *p, int n)
-
-   .. index:: single: EOFError (built-in exception)
-
-   Equivalent to ``p.readline([n])``, this function reads one line from the
-   object *p*.  *p* may be a file object or any object with a :meth:`readline`
-   method.  If *n* is ``0``, exactly one line is read, regardless of the length of
-   the line.  If *n* is greater than ``0``, no more than *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 *n* is less than
-   ``0``, however, one line is read regardless of length, but :exc:`EOFError` is
-   raised if the end of the file is reached immediately.
-
-
-.. cfunction:: PyObject* PyFile_Name(PyObject *p)
-
-   Return the name of the file specified by *p* as a string object.
-
-
-.. cfunction:: void PyFile_SetBufSize(PyFileObject *p, int n)
-
-   .. index:: single: setvbuf()
-
-   Available on systems with :cfunc:`setvbuf` only.  This should only be called
-   immediately after file object creation.
-
-
-.. cfunction:: int PyFile_SetEncoding(PyFileObject *p, const char *enc)
-
-   Set the file's encoding for Unicode output to *enc*. Return 1 on success and 0
-   on failure.
-
-
-.. cfunction:: int PyFile_SoftSpace(PyObject *p, int newflag)
-
-   .. index:: single: softspace (file attribute)
-
-   This function exists for internal use by the interpreter.  Set the
-   :attr:`softspace` attribute of *p* to *newflag* and return the previous value.
-   *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 :attr:`softspace`
-   attribute can be set).  This function clears any errors, and will return ``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.
-
-
-.. cfunction:: int PyFile_WriteObject(PyObject *obj, PyObject *p, int flags)
-
-   .. index:: single: Py_PRINT_RAW
-
-   Write object *obj* to file object *p*.  The only supported flag for *flags* is
-   :const:`Py_PRINT_RAW`; if given, the :func:`str` of the object is written
-   instead of the :func:`repr`.  Return ``0`` on success or ``-1`` on failure; the
-   appropriate exception will be set.
-
-
-.. cfunction:: int PyFile_WriteString(const char *s, PyObject *p)
-
-   Write string *s* to file object *p*.  Return ``0`` on success or ``-1`` on
-   failure; the appropriate exception will be set.
-
-
-.. _function-objects:
-
-Function Objects
-----------------
-
-.. index:: object: function
-
-There are a few functions specific to Python functions.
-
-
-.. ctype:: PyFunctionObject
-
-   The C structure used for functions.
-
-
-.. cvar:: PyTypeObject PyFunction_Type
-
-   .. index:: single: MethodType (in module types)
-
-   This is an instance of :ctype:`PyTypeObject` and represents the Python function
-   type.  It is exposed to Python programmers as ``types.FunctionType``.
-
-
-.. cfunction:: int PyFunction_Check(PyObject *o)
-
-   Return true if *o* is a function object (has type :cdata:`PyFunction_Type`).
-   The parameter must not be *NULL*.
-
-
-.. cfunction:: PyObject* PyFunction_New(PyObject *code, PyObject *globals)
-
-   Return a new function object associated with the code object *code*. *globals*
-   must be a dictionary with the global variables accessible to the function.
-
-   The function's docstring, name and *__module__* are retrieved from the code
-   object, the argument defaults and closure are set to *NULL*.
-
-
-.. cfunction:: PyObject* PyFunction_GetCode(PyObject *op)
-
-   Return the code object associated with the function object *op*.
-
-
-.. cfunction:: PyObject* PyFunction_GetGlobals(PyObject *op)
-
-   Return the globals dictionary associated with the function object *op*.
-
-
-.. cfunction:: PyObject* PyFunction_GetModule(PyObject *op)
-
-   Return the *__module__* attribute of the function object *op*. This is normally
-   a string containing the module name, but can be set to any other object by
-   Python code.
-
-
-.. cfunction:: PyObject* PyFunction_GetDefaults(PyObject *op)
-
-   Return the argument default values of the function object *op*. This can be a
-   tuple of arguments or *NULL*.
-
-
-.. cfunction:: int PyFunction_SetDefaults(PyObject *op, PyObject *defaults)
-
-   Set the argument default values for the function object *op*. *defaults* must be
-   *Py_None* or a tuple.
-
-   Raises :exc:`SystemError` and returns ``-1`` on failure.
-
-
-.. cfunction:: PyObject* PyFunction_GetClosure(PyObject *op)
-
-   Return the closure associated with the function object *op*. This can be *NULL*
-   or a tuple of cell objects.
-
-
-.. cfunction:: int PyFunction_SetClosure(PyObject *op, PyObject *closure)
-
-   Set the closure associated with the function object *op*. *closure* must be
-   *Py_None* or a tuple of cell objects.
-
-   Raises :exc:`SystemError` and returns ``-1`` on failure.
-
-
-.. _instancemethod-objects:
-
-Instance Method Objects
------------------------
-
-.. index:: object: instancemethod
-
-An instance method is a wrapper for a :cdata:`PyCFunction` and the new way
-to bind a :cdata:`PyCFunction` to a class object. It replaces the former call
-``PyMethod_New(func, NULL, class)``.
-
-
-.. cvar:: PyTypeObject PyInstanceMethod_Type
-
-   This instance of :ctype:`PyTypeObject` represents the Python instance
-   method type. It is not exposed to Python programs.
-
-
-.. cfunction:: int PyInstanceMethod_Check(PyObject *o)
-
-   Return true if *o* is an instance method object (has type
-   :cdata:`PyInstanceMethod_Type`).  The parameter must not be *NULL*.
-
-
-.. cfunction:: PyObject* PyInstanceMethod_New(PyObject *func)
-
-   Return a new instance method object, with *func* being any callable object
-   *func* is is the function that will be called when the instance method is
-   called.
-
-
-.. cfunction:: PyObject* PyInstanceMethod_Function(PyObject *im)
-
-   Return the function object associated with the instance method *im*.
-
-
-.. cfunction:: PyObject* PyInstanceMethod_GET_FUNCTION(PyObject *im)
-
-   Macro version of :cfunc:`PyInstanceMethod_Function` which avoids error checking.
-
-
-.. _method-objects:
-
-Method Objects
---------------
-
-.. index:: object: method
-
-Methods are bound function objects. Methods are always bound to an instance of
-an user-defined class. Unbound methods (methods bound to a class object) are
-no longer available.
-
-
-.. cvar:: PyTypeObject PyMethod_Type
-
-   .. index:: single: MethodType (in module types)
-
-   This instance of :ctype:`PyTypeObject` represents the Python method type.  This
-   is exposed to Python programs as ``types.MethodType``.
-
-
-.. cfunction:: int PyMethod_Check(PyObject *o)
-
-   Return true if *o* is a method object (has type :cdata:`PyMethod_Type`).  The
-   parameter must not be *NULL*.
-
-
-.. cfunction:: PyObject* PyMethod_New(PyObject *func, PyObject *self)
-
-   Return a new method object, with *func* being any callable object and *self*
-   the instance the method should be bound. *func* is is the function that will
-   be called when the method is called. *self* must not be *NULL*.
-
-
-.. cfunction:: PyObject* PyMethod_Function(PyObject *meth)
-
-   Return the function object associated with the method *meth*.
-
-
-.. cfunction:: PyObject* PyMethod_GET_FUNCTION(PyObject *meth)
-
-   Macro version of :cfunc:`PyMethod_Function` which avoids error checking.
-
-
-.. cfunction:: PyObject* PyMethod_Self(PyObject *meth)
-
-   Return the instance associated with the method *meth*.
-
-
-.. cfunction:: PyObject* PyMethod_GET_SELF(PyObject *meth)
-
-   Macro version of :cfunc:`PyMethod_Self` which avoids error checking.
-
-
-.. _moduleobjects:
-
-Module Objects
---------------
-
-.. index:: object: module
-
-There are only a few functions special to module objects.
-
-
-.. cvar:: PyTypeObject PyModule_Type
-
-   .. index:: single: ModuleType (in module types)
-
-   This instance of :ctype:`PyTypeObject` represents the Python module type.  This
-   is exposed to Python programs as ``types.ModuleType``.
-
-
-.. cfunction:: int PyModule_Check(PyObject *p)
-
-   Return true if *p* is a module object, or a subtype of a module object.
-
-
-.. cfunction:: int PyModule_CheckExact(PyObject *p)
-
-   Return true if *p* is a module object, but not a subtype of
-   :cdata:`PyModule_Type`.
-
-
-.. cfunction:: PyObject* PyModule_New(const char *name)
-
-   .. index::
-      single: __name__ (module attribute)
-      single: __doc__ (module attribute)
-      single: __file__ (module attribute)
-
-   Return a new module object with the :attr:`__name__` attribute set to *name*.
-   Only the module's :attr:`__doc__` and :attr:`__name__` attributes are filled in;
-   the caller is responsible for providing a :attr:`__file__` attribute.
-
-
-.. cfunction:: PyObject* PyModule_GetDict(PyObject *module)
-
-   .. index:: single: __dict__ (module attribute)
-
-   Return the dictionary object that implements *module*'s namespace; this object
-   is the same as the :attr:`__dict__` attribute of the module object.  This
-   function never fails.  It is recommended extensions use other
-   :cfunc:`PyModule_\*` and :cfunc:`PyObject_\*` functions rather than directly
-   manipulate a module's :attr:`__dict__`.
-
-
-.. cfunction:: char* PyModule_GetName(PyObject *module)
-
-   .. index::
-      single: __name__ (module attribute)
-      single: SystemError (built-in exception)
-
-   Return *module*'s :attr:`__name__` value.  If the module does not provide one,
-   or if it is not a string, :exc:`SystemError` is raised and *NULL* is returned.
-
-
-.. cfunction:: char* PyModule_GetFilename(PyObject *module)
-
-   .. index::
-      single: __file__ (module attribute)
-      single: SystemError (built-in exception)
-
-   Return the name of the file from which *module* was loaded using *module*'s
-   :attr:`__file__` attribute.  If this is not defined, or if it is not a string,
-   raise :exc:`SystemError` and return *NULL*.
-
-
-.. cfunction:: int PyModule_AddObject(PyObject *module, const char *name, PyObject *value)
-
-   Add an object to *module* as *name*.  This is a convenience function which can
-   be used from the module's initialization function.  This steals a reference to
-   *value*.  Return ``-1`` on error, ``0`` on success.
-
-
-.. cfunction:: int PyModule_AddIntConstant(PyObject *module, const char *name, long value)
-
-   Add an integer constant to *module* as *name*.  This convenience function can be
-   used from the module's initialization function. Return ``-1`` on error, ``0`` on
-   success.
-
-
-.. cfunction:: int PyModule_AddStringConstant(PyObject *module, const char *name, const char *value)
-
-   Add a string constant to *module* as *name*.  This convenience function can be
-   used from the module's initialization function.  The string *value* must be
-   null-terminated.  Return ``-1`` on error, ``0`` on success.
-
-
-.. _iterator-objects:
-
-Iterator Objects
-----------------
-
-Python provides two general-purpose iterator objects.  The first, a sequence
-iterator, works with an arbitrary sequence supporting the :meth:`__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.
-
-
-.. cvar:: PyTypeObject PySeqIter_Type
-
-   Type object for iterator objects returned by :cfunc:`PySeqIter_New` and the
-   one-argument form of the :func:`iter` built-in function for built-in sequence
-   types.
-
-
-.. cfunction:: int PySeqIter_Check(op)
-
-   Return true if the type of *op* is :cdata:`PySeqIter_Type`.
-
-
-.. cfunction:: PyObject* PySeqIter_New(PyObject *seq)
-
-   Return an iterator that works with a general sequence object, *seq*.  The
-   iteration ends when the sequence raises :exc:`IndexError` for the subscripting
-   operation.
-
-
-.. cvar:: PyTypeObject PyCallIter_Type
-
-   Type object for iterator objects returned by :cfunc:`PyCallIter_New` and the
-   two-argument form of the :func:`iter` built-in function.
-
-
-.. cfunction:: int PyCallIter_Check(op)
-
-   Return true if the type of *op* is :cdata:`PyCallIter_Type`.
-
-
-.. cfunction:: PyObject* PyCallIter_New(PyObject *callable, PyObject *sentinel)
-
-   Return a new iterator.  The first parameter, *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 *callable* returns a value equal to
-   *sentinel*, the iteration will be terminated.
-
-
-.. _descriptor-objects:
-
-Descriptor Objects
-------------------
-
-"Descriptors" are objects that describe some attribute of an object. They are
-found in the dictionary of type objects.
-
-.. XXX document these!
-
-.. cvar:: PyTypeObject PyProperty_Type
-
-   The type object for the built-in descriptor types.
-
-
-.. cfunction:: PyObject* PyDescr_NewGetSet(PyTypeObject *type, struct PyGetSetDef *getset)
-
-
-.. cfunction:: PyObject* PyDescr_NewMember(PyTypeObject *type, struct PyMemberDef *meth)
-
-
-.. cfunction:: PyObject* PyDescr_NewMethod(PyTypeObject *type, struct PyMethodDef *meth)
-
-
-.. cfunction:: PyObject* PyDescr_NewWrapper(PyTypeObject *type, struct wrapperbase *wrapper, void *wrapped)
-
-
-.. cfunction:: PyObject* PyDescr_NewClassMethod(PyTypeObject *type, PyMethodDef *method)
-
-
-.. cfunction:: int PyDescr_IsData(PyObject *descr)
-
-   Return true if the descriptor objects *descr* describes a data attribute, or
-   false if it describes a method.  *descr* must be a descriptor object; there is
-   no error checking.
-
-
-.. cfunction:: PyObject* PyWrapper_New(PyObject *, PyObject *)
-
-
-.. _slice-objects:
-
-Slice Objects
--------------
-
-
-.. cvar:: PyTypeObject PySlice_Type
-
-   .. index:: single: SliceType (in module types)
-
-   The type object for slice objects.  This is the same as ``slice`` and
-   ``types.SliceType``.
-
-
-.. cfunction:: int PySlice_Check(PyObject *ob)
-
-   Return true if *ob* is a slice object; *ob* must not be *NULL*.
-
-
-.. cfunction:: PyObject* PySlice_New(PyObject *start, PyObject *stop, PyObject *step)
-
-   Return a new slice object with the given values.  The *start*, *stop*, and
-   *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 ``None`` will be
-   used for the corresponding attribute.  Return *NULL* if the new object could not
-   be allocated.
-
-
-.. cfunction:: 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 *slice*,
-   assuming a sequence of length *length*. Treats indices greater than *length* as
-   errors.
-
-   Returns 0 on success and -1 on error with no exception set (unless one of the
-   indices was not :const:`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 :cfunc:`PySlice_GetIndicesEx`, suitably renamed, in the source of
-   your extension.
-
-
-.. cfunction:: 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 :cfunc:`PySlice_GetIndices`.  Retrieve the start, stop,
-   and step indices from the slice object *slice* assuming a sequence of length
-   *length*, and store the length of the slice in *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.
-
-
-.. _weakrefobjects:
-
-Weak Reference Objects
-----------------------
-
-Python supports *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.
-
-
-.. cfunction:: int PyWeakref_Check(ob)
-
-   Return true if *ob* is either a reference or proxy object.
-
-
-.. cfunction:: int PyWeakref_CheckRef(ob)
-
-   Return true if *ob* is a reference object.
-
-
-.. cfunction:: int PyWeakref_CheckProxy(ob)
-
-   Return true if *ob* is a proxy object.
-
-
-.. cfunction:: PyObject* PyWeakref_NewRef(PyObject *ob, PyObject *callback)
-
-   Return a weak reference object for the object *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, *callback*, can be a
-   callable object that receives notification when *ob* is garbage collected; it
-   should accept a single parameter, which will be the weak reference object
-   itself. *callback* may also be ``None`` or *NULL*.  If *ob* is not a
-   weakly-referencable object, or if *callback* is not callable, ``None``, or
-   *NULL*, this will return *NULL* and raise :exc:`TypeError`.
-
-
-.. cfunction:: PyObject* PyWeakref_NewProxy(PyObject *ob, PyObject *callback)
-
-   Return a weak reference proxy object for the object *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, *callback*, can
-   be a callable object that receives notification when *ob* is garbage
-   collected; it should accept a single parameter, which will be the weak
-   reference object itself. *callback* may also be ``None`` or *NULL*.  If *ob*
-   is not a weakly-referencable object, or if *callback* is not callable,
-   ``None``, or *NULL*, this will return *NULL* and raise :exc:`TypeError`.
-
-
-.. cfunction:: PyObject* PyWeakref_GetObject(PyObject *ref)
-
-   Return the referenced object from a weak reference, *ref*.  If the referent is
-   no longer live, returns ``None``.
-
-
-.. cfunction:: PyObject* PyWeakref_GET_OBJECT(PyObject *ref)
-
-   Similar to :cfunc:`PyWeakref_GetObject`, but implemented as a macro that does no
-   error checking.
-
-
-.. _cobjects:
-
-CObjects
---------
-
-.. index:: object: CObject
-
-Refer to *Extending and Embedding the Python Interpreter*, section 1.12,
-"Providing a C API for an Extension Module," for more information on using these
-objects.
-
-
-.. ctype:: 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.
-
-
-.. cfunction:: int PyCObject_Check(PyObject *p)
-
-   Return true if its argument is a :ctype:`PyCObject`.
-
-
-.. cfunction:: PyObject* PyCObject_FromVoidPtr(void* cobj, void (*destr)(void *))
-
-   Create a :ctype:`PyCObject` from the ``void *`` *cobj*.  The *destr* function
-   will be called when the object is reclaimed, unless it is *NULL*.
-
-
-.. cfunction:: PyObject* PyCObject_FromVoidPtrAndDesc(void* cobj, void* desc, void (*destr)(void *, void *))
-
-   Create a :ctype:`PyCObject` from the :ctype:`void \*` *cobj*.  The *destr*
-   function will be called when the object is reclaimed. The *desc* argument can
-   be used to pass extra callback data for the destructor function.
-
-
-.. cfunction:: void* PyCObject_AsVoidPtr(PyObject* self)
-
-   Return the object :ctype:`void \*` that the :ctype:`PyCObject` *self* was
-   created with.
-
-
-.. cfunction:: void* PyCObject_GetDesc(PyObject* self)
-
-   Return the description :ctype:`void \*` that the :ctype:`PyCObject` *self* was
-   created with.
-
-
-.. cfunction:: int PyCObject_SetVoidPtr(PyObject* self, void* cobj)
-
-   Set the void pointer inside *self* to *cobj*. The :ctype:`PyCObject` must not
-   have an associated destructor. Return true on success, false on failure.
-
-
-.. _cell-objects:
-
-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.
-
-
-.. ctype:: PyCellObject
-
-   The C structure used for cell objects.
-
-
-.. cvar:: PyTypeObject PyCell_Type
-
-   The type object corresponding to cell objects.
-
-
-.. cfunction:: int PyCell_Check(ob)
-
-   Return true if *ob* is a cell object; *ob* must not be *NULL*.
-
-
-.. cfunction:: PyObject* PyCell_New(PyObject *ob)
-
-   Create and return a new cell object containing the value *ob*. The parameter may
-   be *NULL*.
-
-
-.. cfunction:: PyObject* PyCell_Get(PyObject *cell)
-
-   Return the contents of the cell *cell*.
-
-
-.. cfunction:: PyObject* PyCell_GET(PyObject *cell)
-
-   Return the contents of the cell *cell*, but without checking that *cell* is
-   non-*NULL* and a cell object.
-
-
-.. cfunction:: int PyCell_Set(PyObject *cell, PyObject *value)
-
-   Set the contents of the cell object *cell* to *value*.  This releases the
-   reference to any current content of the cell. *value* may be *NULL*.  *cell*
-   must be non-*NULL*; if it is not a cell object, ``-1`` will be returned.  On
-   success, ``0`` will be returned.
-
-
-.. cfunction:: void PyCell_SET(PyObject *cell, PyObject *value)
-
-   Sets the value of the cell object *cell* to *value*.  No reference counts are
-   adjusted, and no checks are made for safety; *cell* must be non-*NULL* and must
-   be a cell object.
-
-
-.. _gen-objects:
-
-Generator 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 :cfunc:`PyGen_New`.
-
-
-.. ctype:: PyGenObject
-
-   The C structure used for generator objects.
-
-
-.. cvar:: PyTypeObject PyGen_Type
-
-   The type object corresponding to generator objects
-
-
-.. cfunction:: int PyGen_Check(ob)
-
-   Return true if *ob* is a generator object; *ob* must not be *NULL*.
-
-
-.. cfunction:: int PyGen_CheckExact(ob)
-
-   Return true if *ob*'s type is *PyGen_Type* is a generator object; *ob* must not
-   be *NULL*.
-
-
-.. cfunction:: PyObject* PyGen_New(PyFrameObject *frame)
-
-   Create and return a new generator object based on the *frame* object. A
-   reference to *frame* is stolen by this function. The parameter must not be
-   *NULL*.
-
-
-.. _datetimeobjects:
-
-DateTime Objects
-----------------
-
-Various date and time objects are supplied by the :mod:`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 :cfunc:`PyDateTime_IMPORT` must be invoked.  The macro puts a
-pointer to a C structure into a static variable,  ``PyDateTimeAPI``, that is
-used by the following macros.
-
-Type-check macros:
-
-.. cfunction:: int PyDate_Check(PyObject *ob)
-
-   Return true if *ob* is of type :cdata:`PyDateTime_DateType` or a subtype of
-   :cdata:`PyDateTime_DateType`.  *ob* must not be *NULL*.
-
-
-.. cfunction:: int PyDate_CheckExact(PyObject *ob)
-
-   Return true if *ob* is of type :cdata:`PyDateTime_DateType`. *ob* must not be
-   *NULL*.
-
-
-.. cfunction:: int PyDateTime_Check(PyObject *ob)
-
-   Return true if *ob* is of type :cdata:`PyDateTime_DateTimeType` or a subtype of
-   :cdata:`PyDateTime_DateTimeType`.  *ob* must not be *NULL*.
-
-
-.. cfunction:: int PyDateTime_CheckExact(PyObject *ob)
-
-   Return true if *ob* is of type :cdata:`PyDateTime_DateTimeType`. *ob* must not
-   be *NULL*.
-
-
-.. cfunction:: int PyTime_Check(PyObject *ob)
-
-   Return true if *ob* is of type :cdata:`PyDateTime_TimeType` or a subtype of
-   :cdata:`PyDateTime_TimeType`.  *ob* must not be *NULL*.
-
-
-.. cfunction:: int PyTime_CheckExact(PyObject *ob)
-
-   Return true if *ob* is of type :cdata:`PyDateTime_TimeType`. *ob* must not be
-   *NULL*.
-
-
-.. cfunction:: int PyDelta_Check(PyObject *ob)
-
-   Return true if *ob* is of type :cdata:`PyDateTime_DeltaType` or a subtype of
-   :cdata:`PyDateTime_DeltaType`.  *ob* must not be *NULL*.
-
-
-.. cfunction:: int PyDelta_CheckExact(PyObject *ob)
-
-   Return true if *ob* is of type :cdata:`PyDateTime_DeltaType`. *ob* must not be
-   *NULL*.
-
-
-.. cfunction:: int PyTZInfo_Check(PyObject *ob)
-
-   Return true if *ob* is of type :cdata:`PyDateTime_TZInfoType` or a subtype of
-   :cdata:`PyDateTime_TZInfoType`.  *ob* must not be *NULL*.
-
-
-.. cfunction:: int PyTZInfo_CheckExact(PyObject *ob)
-
-   Return true if *ob* is of type :cdata:`PyDateTime_TZInfoType`. *ob* must not be
-   *NULL*.
-
-
-Macros to create objects:
-
-.. cfunction:: PyObject* PyDate_FromDate(int year, int month, int day)
-
-   Return a ``datetime.date`` object with the specified year, month and day.
-
-
-.. cfunction:: PyObject* PyDateTime_FromDateAndTime(int year, int month, int day, int hour, int minute, int second, int usecond)
-
-   Return a ``datetime.datetime`` object with the specified year, month, day, hour,
-   minute, second and microsecond.
-
-
-.. cfunction:: PyObject* PyTime_FromTime(int hour, int minute, int second, int usecond)
-
-   Return a ``datetime.time`` object with the specified hour, minute, second and
-   microsecond.
-
-
-.. cfunction:: PyObject* PyDelta_FromDSU(int days, int seconds, int useconds)
-
-   Return a ``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
-   ``datetime.timedelta`` objects.
-
-
-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:
-
-.. cfunction:: int PyDateTime_GET_YEAR(PyDateTime_Date *o)
-
-   Return the year, as a positive int.
-
-
-.. cfunction:: int PyDateTime_GET_MONTH(PyDateTime_Date *o)
-
-   Return the month, as an int from 1 through 12.
-
-
-.. cfunction:: int PyDateTime_GET_DAY(PyDateTime_Date *o)
-
-   Return the day, as an int from 1 through 31.
-
-
-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:
-
-.. cfunction:: int PyDateTime_DATE_GET_HOUR(PyDateTime_DateTime *o)
-
-   Return the hour, as an int from 0 through 23.
-
-
-.. cfunction:: int PyDateTime_DATE_GET_MINUTE(PyDateTime_DateTime *o)
-
-   Return the minute, as an int from 0 through 59.
-
-
-.. cfunction:: int PyDateTime_DATE_GET_SECOND(PyDateTime_DateTime *o)
-
-   Return the second, as an int from 0 through 59.
-
-
-.. cfunction:: int PyDateTime_DATE_GET_MICROSECOND(PyDateTime_DateTime *o)
-
-   Return the microsecond, as an int from 0 through 999999.
-
-
-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:
-
-.. cfunction:: int PyDateTime_TIME_GET_HOUR(PyDateTime_Time *o)
-
-   Return the hour, as an int from 0 through 23.
-
-
-.. cfunction:: int PyDateTime_TIME_GET_MINUTE(PyDateTime_Time *o)
-
-   Return the minute, as an int from 0 through 59.
-
-
-.. cfunction:: int PyDateTime_TIME_GET_SECOND(PyDateTime_Time *o)
-
-   Return the second, as an int from 0 through 59.
-
-
-.. cfunction:: int PyDateTime_TIME_GET_MICROSECOND(PyDateTime_Time *o)
-
-   Return the microsecond, as an int from 0 through 999999.
-
-
-Macros for the convenience of modules implementing the DB API:
-
-.. cfunction:: PyObject* PyDateTime_FromTimestamp(PyObject *args)
-
-   Create and return a new ``datetime.datetime`` object given an argument tuple
-   suitable for passing to ``datetime.datetime.fromtimestamp()``.
-
-
-.. cfunction:: PyObject* PyDate_FromTimestamp(PyObject *args)
-
-   Create and return a new ``datetime.date`` object given an argument tuple
-   suitable for passing to ``datetime.date.fromtimestamp()``.
-
-
-.. _setobjects:
-
-Set Objects
------------
-
-.. sectionauthor:: Raymond D. Hettinger <python at rcn.com>
-
-
-.. index::
-   object: set
-   object: frozenset
-
-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 :cfunc:`PyObject_CallMethod`,
-:cfunc:`PyObject_RichCompareBool`, :cfunc:`PyObject_Hash`,
-:cfunc:`PyObject_Repr`, :cfunc:`PyObject_IsTrue`, :cfunc:`PyObject_Print`, and
-:cfunc:`PyObject_GetIter`) or the abstract number protocol (including
-:cfunc:`PyNumber_And`, :cfunc:`PyNumber_Subtract`, :cfunc:`PyNumber_Or`,
-:cfunc:`PyNumber_Xor`, :cfunc:`PyNumber_InPlaceAnd`,
-:cfunc:`PyNumber_InPlaceSubtract`, :cfunc:`PyNumber_InPlaceOr`, and
-:cfunc:`PyNumber_InPlaceXor`).
-
-
-.. ctype:: 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.
-
-
-.. cvar:: PyTypeObject PySet_Type
-
-   This is an instance of :ctype:`PyTypeObject` representing the Python
-   :class:`set` type.
-
-
-.. cvar:: PyTypeObject PyFrozenSet_Type
-
-   This is an instance of :ctype:`PyTypeObject` representing the Python
-   :class:`frozenset` type.
-
-The following type check macros work on pointers to any Python object. Likewise,
-the constructor functions work with any iterable Python object.
-
-
-.. cfunction:: int PyAnySet_Check(PyObject *p)
-
-   Return true if *p* is a :class:`set` object, a :class:`frozenset` object, or an
-   instance of a subtype.
-
-
-.. cfunction:: int PyAnySet_CheckExact(PyObject *p)
-
-   Return true if *p* is a :class:`set` object or a :class:`frozenset` object but
-   not an instance of a subtype.
-
-
-.. cfunction:: int PyFrozenSet_CheckExact(PyObject *p)
-
-   Return true if *p* is a :class:`frozenset` object but not an instance of a
-   subtype.
-
-
-.. cfunction:: PyObject* PySet_New(PyObject *iterable)
-
-   Return a new :class:`set` containing objects returned by the *iterable*.  The
-   *iterable* may be *NULL* to create a new empty set.  Return the new set on
-   success or *NULL* on failure.  Raise :exc:`TypeError` if *iterable* is not
-   actually iterable.  The constructor is also useful for copying a set
-   (``c=set(s)``).
-
-
-.. cfunction:: PyObject* PyFrozenSet_New(PyObject *iterable)
-
-   Return a new :class:`frozenset` containing objects returned by the *iterable*.
-   The *iterable* may be *NULL* to create a new empty frozenset.  Return the new
-   set on success or *NULL* on failure.  Raise :exc:`TypeError` if *iterable* is
-   not actually iterable.
-
-The following functions and macros are available for instances of :class:`set`
-or :class:`frozenset` or instances of their subtypes.
-
-
-.. cfunction:: Py_ssize_t PySet_Size(PyObject *anyset)
-
-   .. index:: builtin: len
-
-   Return the length of a :class:`set` or :class:`frozenset` object. Equivalent to
-   ``len(anyset)``.  Raises a :exc:`PyExc_SystemError` if *anyset* is not a
-   :class:`set`, :class:`frozenset`, or an instance of a subtype.
-
-
-.. cfunction:: Py_ssize_t PySet_GET_SIZE(PyObject *anyset)
-
-   Macro form of :cfunc:`PySet_Size` without error checking.
-
-
-.. cfunction:: 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 :meth:`__contains__` method, this function does not automatically
-   convert unhashable sets into temporary frozensets.  Raise a :exc:`TypeError` if
-   the *key* is unhashable. Raise :exc:`PyExc_SystemError` if *anyset* is not a
-   :class:`set`, :class:`frozenset`, or an instance of a subtype.
-
-The following functions are available for instances of :class:`set` or its
-subtypes but not for instances of :class:`frozenset` or its subtypes.
-
-
-.. cfunction:: int PySet_Add(PyObject *set, PyObject *key)
-
-   Add *key* to a :class:`set` instance.  Does not apply to :class:`frozenset`
-   instances.  Return 0 on success or -1 on failure. Raise a :exc:`TypeError` if
-   the *key* is unhashable. Raise a :exc:`MemoryError` if there is no room to grow.
-   Raise a :exc:`SystemError` if *set* is an not an instance of :class:`set` or its
-   subtype.
-
-
-.. cfunction:: 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 :exc:`KeyError` for missing keys.  Raise a
-   :exc:`TypeError` if the *key* is unhashable.  Unlike the Python :meth:`discard`
-   method, this function does not automatically convert unhashable sets into
-   temporary frozensets. Raise :exc:`PyExc_SystemError` if *set* is an not an
-   instance of :class:`set` or its subtype.
-
-
-.. cfunction:: PyObject* PySet_Pop(PyObject *set)
-
-   Return a new reference to an arbitrary object in the *set*, and removes the
-   object from the *set*.  Return *NULL* on failure.  Raise :exc:`KeyError` if the
-   set is empty. Raise a :exc:`SystemError` if *set* is an not an instance of
-   :class:`set` or its subtype.
-
-
-.. cfunction:: int PySet_Clear(PyObject *set)
-
-   Empty an existing set of all elements.
+.. toctree::
 
+   set.rst
+   function.rst
+   method.rst
+   file.rst
+   module.rst
+   iterator.rst
+   descriptor.rst
+   slice.rst
+   weakref.rst
+   cobject.rst
+   cell.rst
+   gen.rst
+   datetime.rst

Added: python/branches/py3k/Doc/c-api/conversion.rst
==============================================================================
--- (empty file)
+++ python/branches/py3k/Doc/c-api/conversion.rst	Sun Jan 20 10:30:57 2008
@@ -0,0 +1,93 @@
+.. highlightlang:: c
+
+.. _string-conversion:
+
+String conversion and formatting
+================================
+
+Functions for number conversion and formatted string output.
+
+
+.. cfunction:: int PyOS_snprintf(char *str, size_t size,  const char *format, ...)
+
+   Output not more than *size* bytes to *str* according to the format string
+   *format* and the extra arguments. See the Unix man page :manpage:`snprintf(2)`.
+
+
+.. cfunction:: int PyOS_vsnprintf(char *str, size_t size, const char *format, va_list va)
+
+   Output not more than *size* bytes to *str* according to the format string
+   *format* and the variable argument list *va*. Unix man page
+   :manpage:`vsnprintf(2)`.
+
+:cfunc:`PyOS_snprintf` and :cfunc:`PyOS_vsnprintf` wrap the Standard C library
+functions :cfunc:`snprintf` and :cfunc:`vsnprintf`. Their purpose is to
+guarantee consistent behavior in corner cases, which the Standard C functions do
+not.
+
+The wrappers ensure that *str*[*size*-1] is always ``'\0'`` upon return. They
+never write more than *size* bytes (including the trailing ``'\0'``) into str.
+Both functions require that ``str != NULL``, ``size > 0`` and ``format !=
+NULL``.
+
+If the platform doesn't have :cfunc:`vsnprintf` and the buffer size needed to
+avoid truncation exceeds *size* by more than 512 bytes, Python aborts with a
+*Py_FatalError*.
+
+The return value (*rv*) for these functions should be interpreted as follows:
+
+* When ``0 <= rv < size``, the output conversion was successful and *rv*
+  characters were written to *str* (excluding the trailing ``'\0'`` byte at
+  *str*[*rv*]).
+
+* When ``rv >= size``, the output conversion was truncated and a buffer with
+  ``rv + 1`` bytes would have been needed to succeed. *str*[*size*-1] is ``'\0'``
+  in this case.
+
+* When ``rv < 0``, "something bad happened." *str*[*size*-1] is ``'\0'`` in
+  this case too, but the rest of *str* is undefined. The exact cause of the error
+  depends on the underlying platform.
+
+The following functions provide locale-independent string to number conversions.
+
+
+.. cfunction:: double PyOS_ascii_strtod(const char *nptr, char **endptr)
+
+   Convert a string to a :ctype:`double`. This function behaves like the Standard C
+   function :cfunc:`strtod` does in the C locale. It does this without changing the
+   current locale, since that would not be thread-safe.
+
+   :cfunc:`PyOS_ascii_strtod` should typically be used for reading configuration
+   files or other non-user input that should be locale independent.
+
+   See the Unix man page :manpage:`strtod(2)` for details.
+
+
+.. cfunction:: char * PyOS_ascii_formatd(char *buffer, size_t buf_len, const char *format, double d)
+
+   Convert a :ctype:`double` to a string using the ``'.'`` as the decimal
+   separator. *format* is a :cfunc:`printf`\ -style format string specifying the
+   number format. Allowed conversion characters are ``'e'``, ``'E'``, ``'f'``,
+   ``'F'``, ``'g'`` and ``'G'``.
+
+   The return value is a pointer to *buffer* with the converted string or NULL if
+   the conversion failed.
+
+
+.. cfunction:: double PyOS_ascii_atof(const char *nptr)
+
+   Convert a string to a :ctype:`double` in a locale-independent way.
+
+   See the Unix man page :manpage:`atof(2)` for details.
+
+   
+.. cfunction:: char * PyOS_stricmp(char *s1, char *s2)
+
+   Case insensitive comparsion of strings. The functions works almost
+   identical to :cfunc:`strcmp` except that it ignores the case.
+
+
+.. cfunction:: char * PyOS_strnicmp(char *s1, char *s2, Py_ssize_t  size)
+
+   Case insensitive comparsion of strings. The functions works almost
+   identical to :cfunc:`strncmp` except that it ignores the case.

Added: python/branches/py3k/Doc/c-api/datetime.rst
==============================================================================
--- (empty file)
+++ python/branches/py3k/Doc/c-api/datetime.rst	Sun Jan 20 10:30:57 2008
@@ -0,0 +1,183 @@
+.. highlightlang:: c
+
+.. _datetimeobjects:
+
+DateTime Objects
+----------------
+
+Various date and time objects are supplied by the :mod:`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 :cfunc:`PyDateTime_IMPORT` must be invoked.  The macro puts a
+pointer to a C structure into a static variable,  ``PyDateTimeAPI``, that is
+used by the following macros.
+
+Type-check macros:
+
+.. cfunction:: int PyDate_Check(PyObject *ob)
+
+   Return true if *ob* is of type :cdata:`PyDateTime_DateType` or a subtype of
+   :cdata:`PyDateTime_DateType`.  *ob* must not be *NULL*.
+
+
+.. cfunction:: int PyDate_CheckExact(PyObject *ob)
+
+   Return true if *ob* is of type :cdata:`PyDateTime_DateType`. *ob* must not be
+   *NULL*.
+
+
+.. cfunction:: int PyDateTime_Check(PyObject *ob)
+
+   Return true if *ob* is of type :cdata:`PyDateTime_DateTimeType` or a subtype of
+   :cdata:`PyDateTime_DateTimeType`.  *ob* must not be *NULL*.
+
+
+.. cfunction:: int PyDateTime_CheckExact(PyObject *ob)
+
+   Return true if *ob* is of type :cdata:`PyDateTime_DateTimeType`. *ob* must not
+   be *NULL*.
+
+
+.. cfunction:: int PyTime_Check(PyObject *ob)
+
+   Return true if *ob* is of type :cdata:`PyDateTime_TimeType` or a subtype of
+   :cdata:`PyDateTime_TimeType`.  *ob* must not be *NULL*.
+
+
+.. cfunction:: int PyTime_CheckExact(PyObject *ob)
+
+   Return true if *ob* is of type :cdata:`PyDateTime_TimeType`. *ob* must not be
+   *NULL*.
+
+
+.. cfunction:: int PyDelta_Check(PyObject *ob)
+
+   Return true if *ob* is of type :cdata:`PyDateTime_DeltaType` or a subtype of
+   :cdata:`PyDateTime_DeltaType`.  *ob* must not be *NULL*.
+
+
+.. cfunction:: int PyDelta_CheckExact(PyObject *ob)
+
+   Return true if *ob* is of type :cdata:`PyDateTime_DeltaType`. *ob* must not be
+   *NULL*.
+
+
+.. cfunction:: int PyTZInfo_Check(PyObject *ob)
+
+   Return true if *ob* is of type :cdata:`PyDateTime_TZInfoType` or a subtype of
+   :cdata:`PyDateTime_TZInfoType`.  *ob* must not be *NULL*.
+
+
+.. cfunction:: int PyTZInfo_CheckExact(PyObject *ob)
+
+   Return true if *ob* is of type :cdata:`PyDateTime_TZInfoType`. *ob* must not be
+   *NULL*.
+
+
+Macros to create objects:
+
+.. cfunction:: PyObject* PyDate_FromDate(int year, int month, int day)
+
+   Return a ``datetime.date`` object with the specified year, month and day.
+
+
+.. cfunction:: PyObject* PyDateTime_FromDateAndTime(int year, int month, int day, int hour, int minute, int second, int usecond)
+
+   Return a ``datetime.datetime`` object with the specified year, month, day, hour,
+   minute, second and microsecond.
+
+
+.. cfunction:: PyObject* PyTime_FromTime(int hour, int minute, int second, int usecond)
+
+   Return a ``datetime.time`` object with the specified hour, minute, second and
+   microsecond.
+
+
+.. cfunction:: PyObject* PyDelta_FromDSU(int days, int seconds, int useconds)
+
+   Return a ``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
+   ``datetime.timedelta`` objects.
+
+
+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:
+
+.. cfunction:: int PyDateTime_GET_YEAR(PyDateTime_Date *o)
+
+   Return the year, as a positive int.
+
+
+.. cfunction:: int PyDateTime_GET_MONTH(PyDateTime_Date *o)
+
+   Return the month, as an int from 1 through 12.
+
+
+.. cfunction:: int PyDateTime_GET_DAY(PyDateTime_Date *o)
+
+   Return the day, as an int from 1 through 31.
+
+
+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:
+
+.. cfunction:: int PyDateTime_DATE_GET_HOUR(PyDateTime_DateTime *o)
+
+   Return the hour, as an int from 0 through 23.
+
+
+.. cfunction:: int PyDateTime_DATE_GET_MINUTE(PyDateTime_DateTime *o)
+
+   Return the minute, as an int from 0 through 59.
+
+
+.. cfunction:: int PyDateTime_DATE_GET_SECOND(PyDateTime_DateTime *o)
+
+   Return the second, as an int from 0 through 59.
+
+
+.. cfunction:: int PyDateTime_DATE_GET_MICROSECOND(PyDateTime_DateTime *o)
+
+   Return the microsecond, as an int from 0 through 999999.
+
+
+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:
+
+.. cfunction:: int PyDateTime_TIME_GET_HOUR(PyDateTime_Time *o)
+
+   Return the hour, as an int from 0 through 23.
+
+
+.. cfunction:: int PyDateTime_TIME_GET_MINUTE(PyDateTime_Time *o)
+
+   Return the minute, as an int from 0 through 59.
+
+
+.. cfunction:: int PyDateTime_TIME_GET_SECOND(PyDateTime_Time *o)
+
+   Return the second, as an int from 0 through 59.
+
+
+.. cfunction:: int PyDateTime_TIME_GET_MICROSECOND(PyDateTime_Time *o)
+
+   Return the microsecond, as an int from 0 through 999999.
+
+
+Macros for the convenience of modules implementing the DB API:
+
+.. cfunction:: PyObject* PyDateTime_FromTimestamp(PyObject *args)
+
+   Create and return a new ``datetime.datetime`` object given an argument tuple
+   suitable for passing to ``datetime.datetime.fromtimestamp()``.
+
+
+.. cfunction:: PyObject* PyDate_FromTimestamp(PyObject *args)
+
+   Create and return a new ``datetime.date`` object given an argument tuple
+   suitable for passing to ``datetime.date.fromtimestamp()``.

Added: python/branches/py3k/Doc/c-api/descriptor.rst
==============================================================================
--- (empty file)
+++ python/branches/py3k/Doc/c-api/descriptor.rst	Sun Jan 20 10:30:57 2008
@@ -0,0 +1,40 @@
+.. highlightlang:: c
+
+.. _descriptor-objects:
+
+Descriptor Objects
+------------------
+
+"Descriptors" are objects that describe some attribute of an object. They are
+found in the dictionary of type objects.
+
+.. XXX document these!
+
+.. cvar:: PyTypeObject PyProperty_Type
+
+   The type object for the built-in descriptor types.
+
+
+.. cfunction:: PyObject* PyDescr_NewGetSet(PyTypeObject *type, struct PyGetSetDef *getset)
+
+
+.. cfunction:: PyObject* PyDescr_NewMember(PyTypeObject *type, struct PyMemberDef *meth)
+
+
+.. cfunction:: PyObject* PyDescr_NewMethod(PyTypeObject *type, struct PyMethodDef *meth)
+
+
+.. cfunction:: PyObject* PyDescr_NewWrapper(PyTypeObject *type, struct wrapperbase *wrapper, void *wrapped)
+
+
+.. cfunction:: PyObject* PyDescr_NewClassMethod(PyTypeObject *type, PyMethodDef *method)
+
+
+.. cfunction:: int PyDescr_IsData(PyObject *descr)
+
+   Return true if the descriptor objects *descr* describes a data attribute, or
+   false if it describes a method.  *descr* must be a descriptor object; there is
+   no error checking.
+
+
+.. cfunction:: PyObject* PyWrapper_New(PyObject *, PyObject *)

Added: python/branches/py3k/Doc/c-api/dict.rst
==============================================================================
--- (empty file)
+++ python/branches/py3k/Doc/c-api/dict.rst	Sun Jan 20 10:30:57 2008
@@ -0,0 +1,206 @@
+.. highlightlang:: c
+
+.. _dictobjects:
+
+Dictionary Objects
+------------------
+
+.. index:: object: dictionary
+
+
+.. ctype:: PyDictObject
+
+   This subtype of :ctype:`PyObject` represents a Python dictionary object.
+
+
+.. cvar:: PyTypeObject PyDict_Type
+
+   .. index::
+      single: DictType (in module types)
+      single: DictionaryType (in module types)
+
+   This instance of :ctype:`PyTypeObject` represents the Python dictionary type.
+   This is exposed to Python programs as ``dict`` and ``types.DictType``.
+
+
+.. cfunction:: int PyDict_Check(PyObject *p)
+
+   Return true if *p* is a dict object or an instance of a subtype of the dict
+   type.
+
+
+.. cfunction:: int PyDict_CheckExact(PyObject *p)
+
+   Return true if *p* is a dict object, but not an instance of a subtype of the
+   dict type.
+
+
+.. cfunction:: PyObject* PyDict_New()
+
+   Return a new empty dictionary, or *NULL* on failure.
+
+
+.. cfunction:: 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.
+
+
+.. cfunction:: void PyDict_Clear(PyObject *p)
+
+   Empty an existing dictionary of all key-value pairs.
+
+
+.. cfunction:: int PyDict_Contains(PyObject *p, PyObject *key)
+
+   Determine if dictionary *p* contains *key*.  If an item in *p* is matches *key*,
+   return ``1``, otherwise return ``0``.  On error, return ``-1``.  This is
+   equivalent to the Python expression ``key in p``.
+
+
+.. cfunction:: PyObject* PyDict_Copy(PyObject *p)
+
+   Return a new dictionary that contains the same key-value pairs as *p*.
+
+
+.. cfunction:: int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)
+
+   Insert *value* into the dictionary *p* with a key of *key*.  *key* must be
+   :term:`hashable`; if it isn't, :exc:`TypeError` will be raised. Return ``0``
+   on success or ``-1`` on failure.
+
+
+.. cfunction:: int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)
+
+   .. index:: single: PyString_FromString()
+
+   Insert *value* into the dictionary *p* using *key* as a key. *key* should be a
+   :ctype:`char\*`.  The key object is created using ``PyString_FromString(key)``.
+   Return ``0`` on success or ``-1`` on failure.
+
+
+.. cfunction:: int PyDict_DelItem(PyObject *p, PyObject *key)
+
+   Remove the entry in dictionary *p* with key *key*. *key* must be hashable; if it
+   isn't, :exc:`TypeError` is raised.  Return ``0`` on success or ``-1`` on
+   failure.
+
+
+.. cfunction:: int PyDict_DelItemString(PyObject *p, char *key)
+
+   Remove the entry in dictionary *p* which has a key specified by the string
+   *key*.  Return ``0`` on success or ``-1`` on failure.
+
+
+.. cfunction:: PyObject* PyDict_GetItem(PyObject *p, PyObject *key)
+
+   Return the object from dictionary *p* which has a key *key*.  Return *NULL* if
+   the key *key* is not present, but *without* setting an exception.
+
+
+.. cfunction:: PyObject* PyDict_GetItemString(PyObject *p, const char *key)
+
+   This is the same as :cfunc:`PyDict_GetItem`, but *key* is specified as a
+   :ctype:`char\*`, rather than a :ctype:`PyObject\*`.
+
+
+.. cfunction:: PyObject* PyDict_Items(PyObject *p)
+
+   Return a :ctype:`PyListObject` containing all the items from the dictionary, as
+   in the dictionary method :meth:`dict.items`.
+
+
+.. cfunction:: PyObject* PyDict_Keys(PyObject *p)
+
+   Return a :ctype:`PyListObject` containing all the keys from the dictionary, as
+   in the dictionary method :meth:`dict.keys`.
+
+
+.. cfunction:: PyObject* PyDict_Values(PyObject *p)
+
+   Return a :ctype:`PyListObject` containing all the values from the dictionary
+   *p*, as in the dictionary method :meth:`dict.values`.
+
+
+.. cfunction:: Py_ssize_t PyDict_Size(PyObject *p)
+
+   .. index:: builtin: len
+
+   Return the number of items in the dictionary.  This is equivalent to ``len(p)``
+   on a dictionary.
+
+
+.. cfunction:: int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)
+
+   Iterate over all key-value pairs in the dictionary *p*.  The :ctype:`int`
+   referred to by *ppos* must be initialized to ``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
+   *pkey* and *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.  *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::
+
+      PyObject *key, *value;
+      Py_ssize_t pos = 0;
+
+      while (PyDict_Next(self->dict, &pos, &key, &value)) {
+          /* do something interesting with the values... */
+          ...
+      }
+
+   The dictionary *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::
+
+      PyObject *key, *value;
+      Py_ssize_t pos = 0;
+
+      while (PyDict_Next(self->dict, &pos, &key, &value)) {
+          long i = PyLong_AsLong(value);
+          if (i == -1 && PyErr_Occurred()) {
+              return -1;
+          }
+          PyObject *o = PyLong_FromLong(i + 1);
+          if (o == NULL)
+              return -1;
+          if (PyDict_SetItem(self->dict, key, o) < 0) {
+              Py_DECREF(o);
+              return -1;
+          }
+          Py_DECREF(o);
+      }
+
+
+.. cfunction:: int PyDict_Merge(PyObject *a, PyObject *b, int override)
+
+   Iterate over mapping object *b* adding key-value pairs to dictionary *a*. *b*
+   may be a dictionary, or any object supporting :func:`PyMapping_Keys` and
+   :func:`PyObject_GetItem`. If *override* is true, existing pairs in *a* will be
+   replaced if a matching key is found in *b*, otherwise pairs will only be added
+   if there is not a matching key in *a*. Return ``0`` on success or ``-1`` if an
+   exception was raised.
+
+
+.. cfunction:: int PyDict_Update(PyObject *a, PyObject *b)
+
+   This is the same as ``PyDict_Merge(a, b, 1)`` in C, or ``a.update(b)`` in
+   Python.  Return ``0`` on success or ``-1`` if an exception was raised.
+
+
+.. cfunction:: int PyDict_MergeFromSeq2(PyObject *a, PyObject *seq2, int override)
+
+   Update or merge into dictionary *a*, from the key-value pairs in *seq2*.  *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 *override* is
+   true, else the first wins. Return ``0`` on success or ``-1`` if an exception was
+   raised. Equivalent Python (except for the return value)::
+
+      def PyDict_MergeFromSeq2(a, seq2, override):
+          for key, value in seq2:
+              if override or key not in a:
+                  a[key] = value

Added: python/branches/py3k/Doc/c-api/file.rst
==============================================================================
--- (empty file)
+++ python/branches/py3k/Doc/c-api/file.rst	Sun Jan 20 10:30:57 2008
@@ -0,0 +1,123 @@
+.. highlightlang:: c
+
+.. _fileobjects:
+
+File Objects
+------------
+
+.. index:: object: 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.
+
+
+.. ctype:: PyFileObject
+
+   This subtype of :ctype:`PyObject` represents a Python file object.
+
+
+.. cvar:: PyTypeObject PyFile_Type
+
+   .. index:: single: FileType (in module types)
+
+   This instance of :ctype:`PyTypeObject` represents the Python file type.  This is
+   exposed to Python programs as ``file`` and ``types.FileType``.
+
+
+.. cfunction:: int PyFile_Check(PyObject *p)
+
+   Return true if its argument is a :ctype:`PyFileObject` or a subtype of
+   :ctype:`PyFileObject`.
+
+
+.. cfunction:: int PyFile_CheckExact(PyObject *p)
+
+   Return true if its argument is a :ctype:`PyFileObject`, but not a subtype of
+   :ctype:`PyFileObject`.
+
+
+.. cfunction:: PyFile_FromFd(int fd, char *name, char *mode, int buffering, char *encoding, char *newline, int closefd)
+
+   Create a new :ctype:`PyFileObject` from the file descriptor of an already
+   opened file *fd*. The arguments *name*, *encoding* and *newline* can be
+   *NULL* to use the defaults; *buffering* can be *-1* to use the default.
+   Return *NULL* on failure.
+
+   .. warning::
+
+     Take care when you are mixing streams and descriptors! For more 
+     information, see `the GNU C Library docs
+     <http://www.gnu.org/software/libc/manual/html_node/Stream_002fDescriptor-Precautions.html#Stream_002fDescriptor-Precautions>`_.
+
+
+.. cfunction:: int PyObject_AsFileDescriptor(PyObject *p)
+
+   Return the file descriptor associated with *p* as an :ctype:`int`.  If the
+   object is an integer, its value is returned.  If not, the
+   object's :meth:`fileno` method is called if it exists; the method must return
+   an integer, which is returned as the file descriptor value.  Sets an
+   exception and returns ``-1`` on failure.
+
+
+.. cfunction:: PyObject* PyFile_GetLine(PyObject *p, int n)
+
+   .. index:: single: EOFError (built-in exception)
+
+   Equivalent to ``p.readline([n])``, this function reads one line from the
+   object *p*.  *p* may be a file object or any object with a :meth:`readline`
+   method.  If *n* is ``0``, exactly one line is read, regardless of the length of
+   the line.  If *n* is greater than ``0``, no more than *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 *n* is less than
+   ``0``, however, one line is read regardless of length, but :exc:`EOFError` is
+   raised if the end of the file is reached immediately.
+
+
+.. cfunction:: PyObject* PyFile_Name(PyObject *p)
+
+   Return the name of the file specified by *p* as a string object.
+
+
+.. cfunction:: void PyFile_SetBufSize(PyFileObject *p, int n)
+
+   .. index:: single: setvbuf()
+
+   Available on systems with :cfunc:`setvbuf` only.  This should only be called
+   immediately after file object creation.
+
+
+.. cfunction:: int PyFile_SetEncoding(PyFileObject *p, const char *enc)
+
+   Set the file's encoding for Unicode output to *enc*. Return 1 on success and 0
+   on failure.
+
+
+.. cfunction:: int PyFile_SoftSpace(PyObject *p, int newflag)
+
+   .. index:: single: softspace (file attribute)
+
+   This function exists for internal use by the interpreter.  Set the
+   :attr:`softspace` attribute of *p* to *newflag* and return the previous value.
+   *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 :attr:`softspace`
+   attribute can be set).  This function clears any errors, and will return ``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.
+
+
+.. cfunction:: int PyFile_WriteObject(PyObject *obj, PyObject *p, int flags)
+
+   .. index:: single: Py_PRINT_RAW
+
+   Write object *obj* to file object *p*.  The only supported flag for *flags* is
+   :const:`Py_PRINT_RAW`; if given, the :func:`str` of the object is written
+   instead of the :func:`repr`.  Return ``0`` on success or ``-1`` on failure; the
+   appropriate exception will be set.
+
+
+.. cfunction:: int PyFile_WriteString(const char *s, PyObject *p)
+
+   Write string *s* to file object *p*.  Return ``0`` on success or ``-1`` on
+   failure; the appropriate exception will be set.

Added: python/branches/py3k/Doc/c-api/float.rst
==============================================================================
--- (empty file)
+++ python/branches/py3k/Doc/c-api/float.rst	Sun Jan 20 10:30:57 2008
@@ -0,0 +1,74 @@
+.. highlightlang:: c
+
+.. _floatobjects:
+
+Floating Point Objects
+----------------------
+
+.. index:: object: floating point
+
+
+.. ctype:: PyFloatObject
+
+   This subtype of :ctype:`PyObject` represents a Python floating point object.
+
+
+.. cvar:: PyTypeObject PyFloat_Type
+
+   .. index:: single: FloatType (in modules types)
+
+   This instance of :ctype:`PyTypeObject` represents the Python floating point
+   type.  This is the same object as ``float`` and ``types.FloatType``.
+
+
+.. cfunction:: int PyFloat_Check(PyObject *p)
+
+   Return true if its argument is a :ctype:`PyFloatObject` or a subtype of
+   :ctype:`PyFloatObject`.
+
+
+.. cfunction:: int PyFloat_CheckExact(PyObject *p)
+
+   Return true if its argument is a :ctype:`PyFloatObject`, but not a subtype of
+   :ctype:`PyFloatObject`.
+
+
+.. cfunction:: PyObject* PyFloat_FromString(PyObject *str)
+
+   Create a :ctype:`PyFloatObject` object based on the string value in *str*, or
+   *NULL* on failure.
+
+
+.. cfunction:: PyObject* PyFloat_FromDouble(double v)
+
+   Create a :ctype:`PyFloatObject` object from *v*, or *NULL* on failure.
+
+
+.. cfunction:: double PyFloat_AsDouble(PyObject *pyfloat)
+
+   Return a C :ctype:`double` representation of the contents of *pyfloat*.  If
+   *pyfloat* is not a Python floating point object but has a :meth:`__float__`
+   method, this method will first be called to convert *pyfloat* into a float.
+
+
+.. cfunction:: double PyFloat_AS_DOUBLE(PyObject *pyfloat)
+
+   Return a C :ctype:`double` representation of the contents of *pyfloat*, but
+   without error checking.
+
+
+.. cfunction:: PyObject* PyFloat_GetInfo(void)
+
+   Return a structseq instance which contains information about the
+   precision, minimum and maximum values of a float. It's a thin wrapper
+   around the header file :file:`float.h`.
+
+
+.. cfunction:: double PyFloat_GetMax(void)
+
+   Return the maximum representable finite float *DBL_MAX* as C :ctype:`double`.
+
+
+.. cfunction:: double PyFloat_GetMin(void)
+
+   Return the minimum normalized positive float *DBL_MIN* as C :ctype:`double`.

Added: python/branches/py3k/Doc/c-api/function.rst
==============================================================================
--- (empty file)
+++ python/branches/py3k/Doc/c-api/function.rst	Sun Jan 20 10:30:57 2008
@@ -0,0 +1,83 @@
+.. highlightlang:: c
+
+.. _function-objects:
+
+Function Objects
+----------------
+
+.. index:: object: function
+
+There are a few functions specific to Python functions.
+
+
+.. ctype:: PyFunctionObject
+
+   The C structure used for functions.
+
+
+.. cvar:: PyTypeObject PyFunction_Type
+
+   .. index:: single: MethodType (in module types)
+
+   This is an instance of :ctype:`PyTypeObject` and represents the Python function
+   type.  It is exposed to Python programmers as ``types.FunctionType``.
+
+
+.. cfunction:: int PyFunction_Check(PyObject *o)
+
+   Return true if *o* is a function object (has type :cdata:`PyFunction_Type`).
+   The parameter must not be *NULL*.
+
+
+.. cfunction:: PyObject* PyFunction_New(PyObject *code, PyObject *globals)
+
+   Return a new function object associated with the code object *code*. *globals*
+   must be a dictionary with the global variables accessible to the function.
+
+   The function's docstring, name and *__module__* are retrieved from the code
+   object, the argument defaults and closure are set to *NULL*.
+
+
+.. cfunction:: PyObject* PyFunction_GetCode(PyObject *op)
+
+   Return the code object associated with the function object *op*.
+
+
+.. cfunction:: PyObject* PyFunction_GetGlobals(PyObject *op)
+
+   Return the globals dictionary associated with the function object *op*.
+
+
+.. cfunction:: PyObject* PyFunction_GetModule(PyObject *op)
+
+   Return the *__module__* attribute of the function object *op*. This is normally
+   a string containing the module name, but can be set to any other object by
+   Python code.
+
+
+.. cfunction:: PyObject* PyFunction_GetDefaults(PyObject *op)
+
+   Return the argument default values of the function object *op*. This can be a
+   tuple of arguments or *NULL*.
+
+
+.. cfunction:: int PyFunction_SetDefaults(PyObject *op, PyObject *defaults)
+
+   Set the argument default values for the function object *op*. *defaults* must be
+   *Py_None* or a tuple.
+
+   Raises :exc:`SystemError` and returns ``-1`` on failure.
+
+
+.. cfunction:: PyObject* PyFunction_GetClosure(PyObject *op)
+
+   Return the closure associated with the function object *op*. This can be *NULL*
+   or a tuple of cell objects.
+
+
+.. cfunction:: int PyFunction_SetClosure(PyObject *op, PyObject *closure)
+
+   Set the closure associated with the function object *op*. *closure* must be
+   *Py_None* or a tuple of cell objects.
+
+   Raises :exc:`SystemError` and returns ``-1`` on failure.

Added: python/branches/py3k/Doc/c-api/gcsupport.rst
==============================================================================
--- (empty file)
+++ python/branches/py3k/Doc/c-api/gcsupport.rst	Sun Jan 20 10:30:57 2008
@@ -0,0 +1,147 @@
+.. highlightlang:: c
+
+.. _supporting-cycle-detection:
+
+Supporting Cyclic Garbage Collection
+====================================
+
+Python's support for detecting and collecting garbage which involves circular
+references requires support from object types which are "containers" for other
+objects which may also be containers.  Types which do not store references to
+other objects, or which only store references to atomic types (such as numbers
+or strings), do not need to provide any explicit support for garbage collection.
+
+To create a container type, the :attr:`tp_flags` field of the type object must
+include the :const:`Py_TPFLAGS_HAVE_GC` and provide an implementation of the
+:attr:`tp_traverse` handler.  If instances of the type are mutable, a
+:attr:`tp_clear` implementation must also be provided.
+
+
+.. data:: Py_TPFLAGS_HAVE_GC
+
+   Objects with a type with this flag set must conform with the rules documented
+   here.  For convenience these objects will be referred to as container objects.
+
+Constructors for container types must conform to two rules:
+
+#. The memory for the object must be allocated using :cfunc:`PyObject_GC_New` or
+   :cfunc:`PyObject_GC_VarNew`.
+
+#. Once all the fields which may contain references to other containers are
+   initialized, it must call :cfunc:`PyObject_GC_Track`.
+
+
+.. cfunction:: TYPE* PyObject_GC_New(TYPE, PyTypeObject *type)
+
+   Analogous to :cfunc:`PyObject_New` but for container objects with the
+   :const:`Py_TPFLAGS_HAVE_GC` flag set.
+
+
+.. cfunction:: TYPE* PyObject_GC_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size)
+
+   Analogous to :cfunc:`PyObject_NewVar` but for container objects with the
+   :const:`Py_TPFLAGS_HAVE_GC` flag set.
+
+
+.. cfunction:: PyVarObject * PyObject_GC_Resize(PyVarObject *op, Py_ssize_t)
+
+   Resize an object allocated by :cfunc:`PyObject_NewVar`.  Returns the resized
+   object or *NULL* on failure.
+
+
+.. cfunction:: void PyObject_GC_Track(PyObject *op)
+
+   Adds the object *op* to the set of container objects tracked by the collector.
+   The collector can run at unexpected times so objects must be valid while being
+   tracked.  This should be called once all the fields followed by the
+   :attr:`tp_traverse` handler become valid, usually near the end of the
+   constructor.
+
+
+.. cfunction:: void _PyObject_GC_TRACK(PyObject *op)
+
+   A macro version of :cfunc:`PyObject_GC_Track`.  It should not be used for
+   extension modules.
+
+Similarly, the deallocator for the object must conform to a similar pair of
+rules:
+
+#. Before fields which refer to other containers are invalidated,
+   :cfunc:`PyObject_GC_UnTrack` must be called.
+
+#. The object's memory must be deallocated using :cfunc:`PyObject_GC_Del`.
+
+
+.. cfunction:: void PyObject_GC_Del(void *op)
+
+   Releases memory allocated to an object using :cfunc:`PyObject_GC_New` or
+   :cfunc:`PyObject_GC_NewVar`.
+
+
+.. cfunction:: void PyObject_GC_UnTrack(void *op)
+
+   Remove the object *op* from the set of container objects tracked by the
+   collector.  Note that :cfunc:`PyObject_GC_Track` can be called again on this
+   object to add it back to the set of tracked objects.  The deallocator
+   (:attr:`tp_dealloc` handler) should call this for the object before any of the
+   fields used by the :attr:`tp_traverse` handler become invalid.
+
+
+.. cfunction:: void _PyObject_GC_UNTRACK(PyObject *op)
+
+   A macro version of :cfunc:`PyObject_GC_UnTrack`.  It should not be used for
+   extension modules.
+
+The :attr:`tp_traverse` handler accepts a function parameter of this type:
+
+
+.. ctype:: int (*visitproc)(PyObject *object, void *arg)
+
+   Type of the visitor function passed to the :attr:`tp_traverse` handler.  The
+   function should be called with an object to traverse as *object* and the third
+   parameter to the :attr:`tp_traverse` handler as *arg*.  The Python core uses
+   several visitor functions to implement cyclic garbage detection; it's not
+   expected that users will need to write their own visitor functions.
+
+The :attr:`tp_traverse` handler must have the following type:
+
+
+.. ctype:: int (*traverseproc)(PyObject *self, visitproc visit, void *arg)
+
+   Traversal function for a container object.  Implementations must call the
+   *visit* function for each object directly contained by *self*, with the
+   parameters to *visit* being the contained object and the *arg* value passed to
+   the handler.  The *visit* function must not be called with a *NULL* object
+   argument.  If *visit* returns a non-zero value that value should be returned
+   immediately.
+
+To simplify writing :attr:`tp_traverse` handlers, a :cfunc:`Py_VISIT` macro is
+provided.  In order to use this macro, the :attr:`tp_traverse` implementation
+must name its arguments exactly *visit* and *arg*:
+
+
+.. cfunction:: void Py_VISIT(PyObject *o)
+
+   Call the *visit* callback, with arguments *o* and *arg*. If *visit* returns a
+   non-zero value, then return it.  Using this macro, :attr:`tp_traverse` handlers
+   look like::
+
+      static int
+      my_traverse(Noddy *self, visitproc visit, void *arg)
+      {
+          Py_VISIT(self->foo);
+          Py_VISIT(self->bar);
+          return 0;
+      }
+
+The :attr:`tp_clear` handler must be of the :ctype:`inquiry` type, or *NULL* if
+the object is immutable.
+
+
+.. ctype:: int (*inquiry)(PyObject *self)
+
+   Drop references that may have created reference cycles.  Immutable objects do
+   not have to define this method since they can never directly create reference
+   cycles.  Note that the object must still be valid after calling this method
+   (don't just call :cfunc:`Py_DECREF` on a reference).  The collector will call
+   this method if it detects that this object is involved in a reference cycle.

Added: python/branches/py3k/Doc/c-api/gen.rst
==============================================================================
--- (empty file)
+++ python/branches/py3k/Doc/c-api/gen.rst	Sun Jan 20 10:30:57 2008
@@ -0,0 +1,38 @@
+.. highlightlang:: c
+
+.. _gen-objects:
+
+Generator 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 :cfunc:`PyGen_New`.
+
+
+.. ctype:: PyGenObject
+
+   The C structure used for generator objects.
+
+
+.. cvar:: PyTypeObject PyGen_Type
+
+   The type object corresponding to generator objects
+
+
+.. cfunction:: int PyGen_Check(ob)
+
+   Return true if *ob* is a generator object; *ob* must not be *NULL*.
+
+
+.. cfunction:: int PyGen_CheckExact(ob)
+
+   Return true if *ob*'s type is *PyGen_Type* is a generator object; *ob* must not
+   be *NULL*.
+
+
+.. cfunction:: PyObject* PyGen_New(PyFrameObject *frame)
+
+   Create and return a new generator object based on the *frame* object. A
+   reference to *frame* is stolen by this function. The parameter must not be
+   *NULL*.

Added: python/branches/py3k/Doc/c-api/import.rst
==============================================================================
--- (empty file)
+++ python/branches/py3k/Doc/c-api/import.rst	Sun Jan 20 10:30:57 2008
@@ -0,0 +1,227 @@
+.. highlightlang:: c
+
+.. _importing:
+
+Importing Modules
+=================
+
+
+.. cfunction:: PyObject* PyImport_ImportModule(const char *name)
+
+   .. index::
+      single: package variable; __all__
+      single: __all__ (package variable)
+      single: modules (in module sys)
+
+   This is a simplified interface to :cfunc:`PyImport_ImportModuleEx` below,
+   leaving the *globals* and *locals* arguments set to *NULL* and *level* set
+   to 0.  When the *name*
+   argument contains a dot (when it specifies a submodule of a package), the
+   *fromlist* argument is set to the list ``['*']`` so that the return value is the
+   named module rather than the top-level package containing it as would otherwise
+   be the case.  (Unfortunately, this has an additional side effect when *name* in
+   fact specifies a subpackage instead of a submodule: the submodules specified in
+   the package's ``__all__`` variable are  loaded.)  Return a new reference to the
+   imported module, or *NULL* with an exception set on failure.  Before Python 2.4,
+   the module may still be created in the failure case --- examine ``sys.modules``
+   to find out.  Starting with Python 2.4, a failing import of a module no longer
+   leaves the module in ``sys.modules``.
+
+
+.. cfunction:: PyObject* PyImport_ImportModuleNoBlock(const char *name)
+
+   This version of :cfunc:`PyImport_ImportModule` does not block. It's intended
+   to be used in C functions that import other modules to execute a function.
+   The import may block if another thread holds the import lock. The function
+   :cfunc:`PyImport_ImportModuleNoBlock` never blocks. It first tries to fetch
+   the module from sys.modules and falls back to :cfunc:`PyImport_ImportModule`
+   unless the lock is held, in which case the function will raise an
+   :exc:`ImportError`.
+
+
+.. cfunction:: PyObject* PyImport_ImportModuleEx(char *name, PyObject *globals, PyObject *locals, PyObject *fromlist)
+
+   .. index:: builtin: __import__
+
+   Import a module.  This is best described by referring to the built-in Python
+   function :func:`__import__`, as the standard :func:`__import__` function calls
+   this function directly.
+
+   The return value is a new reference to the imported module or top-level package,
+   or *NULL* with an exception set on failure (before Python 2.4, the module may
+   still be created in this case).  Like for :func:`__import__`, the return value
+   when a submodule of a package was requested is normally the top-level package,
+   unless a non-empty *fromlist* was given.
+
+   Failing imports remove incomplete module objects, like with
+   :cfunc:`PyImport_ImportModule`.
+
+
+.. cfunction:: PyObject* PyImport_ImportModuleLevel(char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)
+
+   Import a module.  This is best described by referring to the built-in Python
+   function :func:`__import__`, as the standard :func:`__import__` function calls
+   this function directly.
+
+   The return value is a new reference to the imported module or top-level package,
+   or *NULL* with an exception set on failure.  Like for :func:`__import__`,
+   the return value when a submodule of a package was requested is normally the
+   top-level package, unless a non-empty *fromlist* was given.
+
+
+.. cfunction:: PyObject* PyImport_Import(PyObject *name)
+
+   This is a higher-level interface that calls the current "import hook
+   function" (with an explicit *level* of 0, meaning absolute import).  It
+   invokes the :func:`__import__` function from the ``__builtins__`` of the
+   current globals.  This means that the import is done using whatever import
+   hooks are installed in the current environment.
+
+
+.. cfunction:: PyObject* PyImport_ReloadModule(PyObject *m)
+
+   Reload a module.  Return a new reference to the reloaded module, or *NULL* with
+   an exception set on failure (the module still exists in this case).
+
+
+.. cfunction:: PyObject* PyImport_AddModule(const char *name)
+
+   Return the module object corresponding to a module name.  The *name* argument
+   may be of the form ``package.module``. First check the modules dictionary if
+   there's one there, and if not, create a new one and insert it in the modules
+   dictionary. Return *NULL* with an exception set on failure.
+
+   .. note::
+
+      This function does not load or import the module; if the module wasn't already
+      loaded, you will get an empty module object. Use :cfunc:`PyImport_ImportModule`
+      or one of its variants to import a module.  Package structures implied by a
+      dotted name for *name* are not created if not already present.
+
+
+.. cfunction:: PyObject* PyImport_ExecCodeModule(char *name, PyObject *co)
+
+   .. index:: builtin: compile
+
+   Given a module name (possibly of the form ``package.module``) and a code object
+   read from a Python bytecode file or obtained from the built-in function
+   :func:`compile`, load the module.  Return a new reference to the module object,
+   or *NULL* with an exception set if an error occurred.  Before Python 2.4, the
+   module could still be created in error cases.  Starting with Python 2.4, *name*
+   is removed from :attr:`sys.modules` in error cases, and even if *name* was already
+   in :attr:`sys.modules` on entry to :cfunc:`PyImport_ExecCodeModule`.  Leaving
+   incompletely initialized modules in :attr:`sys.modules` is dangerous, as imports of
+   such modules have no way to know that the module object is an unknown (and
+   probably damaged with respect to the module author's intents) state.
+
+   This function will reload the module if it was already imported.  See
+   :cfunc:`PyImport_ReloadModule` for the intended way to reload a module.
+
+   If *name* points to a dotted name of the form ``package.module``, any package
+   structures not already created will still not be created.
+
+
+.. cfunction:: long PyImport_GetMagicNumber()
+
+   Return the magic number for Python bytecode files (a.k.a. :file:`.pyc` and
+   :file:`.pyo` files).  The magic number should be present in the first four bytes
+   of the bytecode file, in little-endian byte order.
+
+
+.. cfunction:: PyObject* PyImport_GetModuleDict()
+
+   Return the dictionary used for the module administration (a.k.a.
+   ``sys.modules``).  Note that this is a per-interpreter variable.
+
+
+.. cfunction:: void _PyImport_Init()
+
+   Initialize the import mechanism.  For internal use only.
+
+
+.. cfunction:: void PyImport_Cleanup()
+
+   Empty the module table.  For internal use only.
+
+
+.. cfunction:: void _PyImport_Fini()
+
+   Finalize the import mechanism.  For internal use only.
+
+
+.. cfunction:: PyObject* _PyImport_FindExtension(char *, char *)
+
+   For internal use only.
+
+
+.. cfunction:: PyObject* _PyImport_FixupExtension(char *, char *)
+
+   For internal use only.
+
+
+.. cfunction:: int PyImport_ImportFrozenModule(char *name)
+
+   Load a frozen module named *name*.  Return ``1`` for success, ``0`` if the
+   module is not found, and ``-1`` with an exception set if the initialization
+   failed.  To access the imported module on a successful load, use
+   :cfunc:`PyImport_ImportModule`.  (Note the misnomer --- this function would
+   reload the module if it was already imported.)
+
+
+.. ctype:: struct _frozen
+
+   .. index:: single: freeze utility
+
+   This is the structure type definition for frozen module descriptors, as
+   generated by the :program:`freeze` utility (see :file:`Tools/freeze/` in the
+   Python source distribution).  Its definition, found in :file:`Include/import.h`,
+   is::
+
+      struct _frozen {
+          char *name;
+          unsigned char *code;
+          int size;
+      };
+
+
+.. cvar:: struct _frozen* PyImport_FrozenModules
+
+   This pointer is initialized to point to an array of :ctype:`struct _frozen`
+   records, terminated by one whose members are all *NULL* or zero.  When a frozen
+   module is imported, it is searched in this table.  Third-party code could play
+   tricks with this to provide a dynamically created collection of frozen modules.
+
+
+.. cfunction:: int PyImport_AppendInittab(char *name, void (*initfunc)(void))
+
+   Add a single module to the existing table of built-in modules.  This is a
+   convenience wrapper around :cfunc:`PyImport_ExtendInittab`, returning ``-1`` if
+   the table could not be extended.  The new module can be imported by the name
+   *name*, and uses the function *initfunc* as the initialization function called
+   on the first attempted import.  This should be called before
+   :cfunc:`Py_Initialize`.
+
+
+.. ctype:: struct _inittab
+
+   Structure describing a single entry in the list of built-in modules.  Each of
+   these structures gives the name and initialization function for a module built
+   into the interpreter.  Programs which embed Python may use an array of these
+   structures in conjunction with :cfunc:`PyImport_ExtendInittab` to provide
+   additional built-in modules.  The structure is defined in
+   :file:`Include/import.h` as::
+
+      struct _inittab {
+          char *name;
+          void (*initfunc)(void);
+      };
+
+
+.. cfunction:: int PyImport_ExtendInittab(struct _inittab *newtab)
+
+   Add a collection of modules to the table of built-in modules.  The *newtab*
+   array must end with a sentinel entry which contains *NULL* for the :attr:`name`
+   field; failure to provide the sentinel value can result in a memory fault.
+   Returns ``0`` on success or ``-1`` if insufficient memory could be allocated to
+   extend the internal table.  In the event of failure, no modules are added to the
+   internal table.  This should be called before :cfunc:`Py_Initialize`.

Added: python/branches/py3k/Doc/c-api/iter.rst
==============================================================================
--- (empty file)
+++ python/branches/py3k/Doc/c-api/iter.rst	Sun Jan 20 10:30:57 2008
@@ -0,0 +1,47 @@
+.. highlightlang:: c
+
+.. _iterator:
+
+Iterator Protocol
+=================
+
+There are only a couple of functions specifically for working with iterators.
+
+.. cfunction:: int PyIter_Check(PyObject *o)
+
+   Return true if the object *o* supports the iterator protocol.
+
+
+.. cfunction:: PyObject* PyIter_Next(PyObject *o)
+
+   Return the next value from the iteration *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, :exc:`TypeError` is raised, or if there is an error in retrieving the
+   item, returns *NULL* and passes along the exception.
+
+To write a loop which iterates over an iterator, the C code should look
+something like this::
+
+   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 */
+   }

Added: python/branches/py3k/Doc/c-api/iterator.rst
==============================================================================
--- (empty file)
+++ python/branches/py3k/Doc/c-api/iterator.rst	Sun Jan 20 10:30:57 2008
@@ -0,0 +1,50 @@
+.. highlightlang:: c
+
+.. _iterator-objects:
+
+Iterator Objects
+----------------
+
+Python provides two general-purpose iterator objects.  The first, a sequence
+iterator, works with an arbitrary sequence supporting the :meth:`__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.
+
+
+.. cvar:: PyTypeObject PySeqIter_Type
+
+   Type object for iterator objects returned by :cfunc:`PySeqIter_New` and the
+   one-argument form of the :func:`iter` built-in function for built-in sequence
+   types.
+
+
+.. cfunction:: int PySeqIter_Check(op)
+
+   Return true if the type of *op* is :cdata:`PySeqIter_Type`.
+
+
+.. cfunction:: PyObject* PySeqIter_New(PyObject *seq)
+
+   Return an iterator that works with a general sequence object, *seq*.  The
+   iteration ends when the sequence raises :exc:`IndexError` for the subscripting
+   operation.
+
+
+.. cvar:: PyTypeObject PyCallIter_Type
+
+   Type object for iterator objects returned by :cfunc:`PyCallIter_New` and the
+   two-argument form of the :func:`iter` built-in function.
+
+
+.. cfunction:: int PyCallIter_Check(op)
+
+   Return true if the type of *op* is :cdata:`PyCallIter_Type`.
+
+
+.. cfunction:: PyObject* PyCallIter_New(PyObject *callable, PyObject *sentinel)
+
+   Return a new iterator.  The first parameter, *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 *callable* returns a value equal to
+   *sentinel*, the iteration will be terminated.

Added: python/branches/py3k/Doc/c-api/list.rst
==============================================================================
--- (empty file)
+++ python/branches/py3k/Doc/c-api/list.rst	Sun Jan 20 10:30:57 2008
@@ -0,0 +1,142 @@
+.. highlightlang:: c
+
+.. _listobjects:
+
+List Objects
+------------
+
+.. index:: object: list
+
+
+.. ctype:: PyListObject
+
+   This subtype of :ctype:`PyObject` represents a Python list object.
+
+
+.. cvar:: PyTypeObject PyList_Type
+
+   .. index:: single: ListType (in module types)
+
+   This instance of :ctype:`PyTypeObject` represents the Python list type.  This is
+   the same object as ``list`` and ``types.ListType`` in the Python layer.
+
+
+.. cfunction:: int PyList_Check(PyObject *p)
+
+   Return true if *p* is a list object or an instance of a subtype of the list
+   type.
+
+
+.. cfunction:: int PyList_CheckExact(PyObject *p)
+
+   Return true if *p* is a list object, but not an instance of a subtype of the
+   list type.
+
+
+.. cfunction:: PyObject* PyList_New(Py_ssize_t len)
+
+   Return a new list of length *len* on success, or *NULL* on failure.
+
+   .. note::
+
+      If *length* is greater than zero, the returned list object's items are set to
+      ``NULL``.  Thus you cannot use abstract API functions such as
+      :cfunc:`PySequence_SetItem`  or expose the object to Python code before setting
+      all items to a real object with :cfunc:`PyList_SetItem`.
+
+
+.. cfunction:: Py_ssize_t PyList_Size(PyObject *list)
+
+   .. index:: builtin: len
+
+   Return the length of the list object in *list*; this is equivalent to
+   ``len(list)`` on a list object.
+
+
+.. cfunction:: Py_ssize_t PyList_GET_SIZE(PyObject *list)
+
+   Macro form of :cfunc:`PyList_Size` without error checking.
+
+
+.. cfunction:: PyObject* PyList_GetItem(PyObject *list, Py_ssize_t index)
+
+   Return the object at position *pos* in the list pointed to by *p*.  The position
+   must be positive, indexing from the end of the list is not supported.  If *pos*
+   is out of bounds, return *NULL* and set an :exc:`IndexError` exception.
+
+
+.. cfunction:: PyObject* PyList_GET_ITEM(PyObject *list, Py_ssize_t i)
+
+   Macro form of :cfunc:`PyList_GetItem` without error checking.
+
+
+.. cfunction:: int PyList_SetItem(PyObject *list, Py_ssize_t index, PyObject *item)
+
+   Set the item at index *index* in list to *item*.  Return ``0`` on success or
+   ``-1`` on failure.
+
+   .. note::
+
+      This function "steals" a reference to *item* and discards a reference to an item
+      already in the list at the affected position.
+
+
+.. cfunction:: void PyList_SET_ITEM(PyObject *list, Py_ssize_t i, PyObject *o)
+
+   Macro form of :cfunc:`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 *item*, and, unlike
+      :cfunc:`PyList_SetItem`, does *not* discard a reference to any item that it
+      being replaced; any reference in *list* at position *i* will be leaked.
+
+
+.. cfunction:: int PyList_Insert(PyObject *list, Py_ssize_t index, PyObject *item)
+
+   Insert the item *item* into list *list* in front of index *index*.  Return ``0``
+   if successful; return ``-1`` and set an exception if unsuccessful.  Analogous to
+   ``list.insert(index, item)``.
+
+
+.. cfunction:: int PyList_Append(PyObject *list, PyObject *item)
+
+   Append the object *item* at the end of list *list*. Return ``0`` if successful;
+   return ``-1`` and set an exception if unsuccessful.  Analogous to
+   ``list.append(item)``.
+
+
+.. cfunction:: PyObject* PyList_GetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high)
+
+   Return a list of the objects in *list* containing the objects *between* *low*
+   and *high*.  Return *NULL* and set an exception if unsuccessful. Analogous to
+   ``list[low:high]``.
+
+
+.. cfunction:: int PyList_SetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high, PyObject *itemlist)
+
+   Set the slice of *list* between *low* and *high* to the contents of *itemlist*.
+   Analogous to ``list[low:high] = itemlist``. The *itemlist* may be *NULL*,
+   indicating the assignment of an empty list (slice deletion). Return ``0`` on
+   success, ``-1`` on failure.
+
+
+.. cfunction:: int PyList_Sort(PyObject *list)
+
+   Sort the items of *list* in place.  Return ``0`` on success, ``-1`` on failure.
+   This is equivalent to ``list.sort()``.
+
+
+.. cfunction:: int PyList_Reverse(PyObject *list)
+
+   Reverse the items of *list* in place.  Return ``0`` on success, ``-1`` on
+   failure.  This is the equivalent of ``list.reverse()``.
+
+
+.. cfunction:: PyObject* PyList_AsTuple(PyObject *list)
+
+   .. index:: builtin: tuple
+
+   Return a new tuple object containing the contents of *list*; equivalent to
+   ``tuple(list)``.

Added: python/branches/py3k/Doc/c-api/long.rst
==============================================================================
--- (empty file)
+++ python/branches/py3k/Doc/c-api/long.rst	Sun Jan 20 10:30:57 2008
@@ -0,0 +1,196 @@
+.. highlightlang:: c
+
+.. _longobjects:
+
+Integer Objects
+---------------
+
+.. index:: object: long integer
+           object: integer
+
+All integers are implemented as "long" integer objects of arbitrary size.
+
+.. ctype:: PyLongObject
+
+   This subtype of :ctype:`PyObject` represents a Python integer object.
+
+
+.. cvar:: PyTypeObject PyLong_Type
+
+   This instance of :ctype:`PyTypeObject` represents the Python integer type.
+   This is the same object as ``int``.
+
+
+.. cfunction:: int PyLong_Check(PyObject *p)
+
+   Return true if its argument is a :ctype:`PyLongObject` or a subtype of
+   :ctype:`PyLongObject`.
+
+
+.. cfunction:: int PyLong_CheckExact(PyObject *p)
+
+   Return true if its argument is a :ctype:`PyLongObject`, but not a subtype of
+   :ctype:`PyLongObject`.
+
+
+.. cfunction:: PyObject* PyLong_FromLong(long v)
+
+   Return a new :ctype:`PyLongObject` object from *v*, or *NULL* on failure.
+
+   The current implementation keeps an array of integer objects for all integers
+   between ``-5`` and ``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 ``1``.  I suspect the behaviour of Python in this case is
+   undefined. :-)
+
+
+.. cfunction:: PyObject* PyLong_FromUnsignedLong(unsigned long v)
+
+   Return a new :ctype:`PyLongObject` object from a C :ctype:`unsigned long`, or
+   *NULL* on failure.
+
+
+.. cfunction:: PyObject* PyLong_FromSsize_t(Py_ssize_t v)
+
+   Return a new :ctype:`PyLongObject` object with a value of *v*, or *NULL*
+   on failure.
+
+
+.. cfunction:: PyObject* PyLong_FromSize_t(size_t v)
+
+   Return a new :ctype:`PyLongObject` object with a value of *v*, or *NULL*
+   on failure.
+
+
+.. cfunction:: PyObject* PyLong_FromLongLong(PY_LONG_LONG v)
+
+   Return a new :ctype:`PyLongObject` object from a C :ctype:`long long`, or *NULL*
+   on failure.
+
+
+.. cfunction:: 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.
+
+
+.. cfunction:: PyObject* PyLong_FromDouble(double v)
+
+   Return a new :ctype:`PyLongObject` object from the integer part of *v*, or
+   *NULL* on failure.
+
+
+.. cfunction:: PyObject* PyLong_FromString(char *str, char **pend, int base)
+
+   Return a new :ctype:`PyLongObject` based on the string value in *str*, which
+   is interpreted according to the radix in *base*.  If *pend* is non-*NULL*,
+   ``*pend`` will point to the first character in *str* which follows the
+   representation of the number.  If *base* is ``0``, the radix will be
+   determined based on the leading characters of *str*: if *str* starts with
+   ``'0x'`` or ``'0X'``, radix 16 will be used; if *str* starts with ``'0o'`` or
+   ``'0O'``, radix 8 will be used; if *str* starts with ``'0b'`` or ``'0B'``,
+   radix 2 will be used; otherwise radix 10 will be used.  If *base* is not
+   ``0``, it must be between ``2`` and ``36``, inclusive.  Leading spaces are
+   ignored.  If there are no digits, :exc:`ValueError` will be raised.
+
+
+.. cfunction:: PyObject* PyLong_FromUnicode(Py_UNICODE *u, Py_ssize_t length, int base)
+
+   Convert a sequence of Unicode digits to a Python integer value.  The Unicode
+   string is first encoded to a byte string using :cfunc:`PyUnicode_EncodeDecimal`
+   and then converted using :cfunc:`PyLong_FromString`.
+
+
+.. cfunction:: PyObject* PyLong_FromVoidPtr(void *p)
+
+   Create a Python integer from the pointer *p*. The pointer value can be
+   retrieved from the resulting value using :cfunc:`PyLong_AsVoidPtr`.
+
+
+.. XXX alias PyLong_AS_LONG (for now) 
+.. cfunction:: long PyLong_AsLong(PyObject *pylong)
+
+   .. index::
+      single: LONG_MAX
+      single: OverflowError (built-in exception)
+
+   Return a C :ctype:`long` representation of the contents of *pylong*.  If
+   *pylong* is greater than :const:`LONG_MAX`, raise an :exc:`OverflowError`,
+   and return -1. Convert non-long objects automatically to long first,
+   and return -1 if that raises exceptions.
+
+.. cfunction:: long PyLong_AsLongAndOverflow(PyObject *pylong, int* overflow)
+
+   Return a C :ctype:`long` representation of the contents of *pylong*.  If
+   *pylong* is greater than :const:`LONG_MAX`, return -1 and
+   set `*overflow` to 1 (for overflow) or -1 (for underflow). 
+   If an exception is set because of type errors, also return -1.
+
+
+.. cfunction:: unsigned long PyLong_AsUnsignedLong(PyObject *pylong)
+
+   .. index::
+      single: ULONG_MAX
+      single: OverflowError (built-in exception)
+
+   Return a C :ctype:`unsigned long` representation of the contents of *pylong*.
+   If *pylong* is greater than :const:`ULONG_MAX`, an :exc:`OverflowError` is
+   raised.
+
+
+.. cfunction:: Py_ssize_t PyLong_AsSsize_t(PyObject *pylong)
+
+   .. index::
+      single: PY_SSIZE_T_MAX
+
+   Return a :ctype:`Py_ssize_t` representation of the contents of *pylong*.  If
+   *pylong* is greater than :const:`PY_SSIZE_T_MAX`, an :exc:`OverflowError` is
+   raised.
+
+
+.. cfunction:: size_t PyLong_AsSize_t(PyObject *pylong)
+
+   Return a :ctype:`size_t` representation of the contents of *pylong*.  If
+   *pylong* is greater than the maximum value for a :ctype:`size_t`, an
+   :exc:`OverflowError` is raised.
+
+
+.. cfunction:: PY_LONG_LONG PyLong_AsLongLong(PyObject *pylong)
+
+   Return a C :ctype:`long long` from a Python integer.  If *pylong* cannot be
+   represented as a :ctype:`long long`, an :exc:`OverflowError` will be raised.
+
+
+.. cfunction:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLong(PyObject *pylong)
+
+   Return a C :ctype:`unsigned long long` from a Python integer. If *pylong*
+   cannot be represented as an :ctype:`unsigned long long`, an :exc:`OverflowError`
+   will be raised if the value is positive, or a :exc:`TypeError` will be raised if
+   the value is negative.
+
+
+.. cfunction:: unsigned long PyLong_AsUnsignedLongMask(PyObject *io)
+
+   Return a C :ctype:`unsigned long` from a Python integer, without checking for
+   overflow.
+
+
+.. cfunction:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLongMask(PyObject *io)
+
+   Return a C :ctype:`unsigned long long` from a Python integer, without
+   checking for overflow.
+
+
+.. cfunction:: double PyLong_AsDouble(PyObject *pylong)
+
+   Return a C :ctype:`double` representation of the contents of *pylong*.  If
+   *pylong* cannot be approximately represented as a :ctype:`double`, an
+   :exc:`OverflowError` exception is raised and ``-1.0`` will be returned.
+
+
+.. cfunction:: void* PyLong_AsVoidPtr(PyObject *pylong)
+
+   Convert a Python integer *pylong* to a C :ctype:`void` pointer.  If *pylong*
+   cannot be converted, an :exc:`OverflowError` will be raised.  This is only
+   assured to produce a usable :ctype:`void` pointer for values created with
+   :cfunc:`PyLong_FromVoidPtr`.

Added: python/branches/py3k/Doc/c-api/mapping.rst
==============================================================================
--- (empty file)
+++ python/branches/py3k/Doc/c-api/mapping.rst	Sun Jan 20 10:30:57 2008
@@ -0,0 +1,78 @@
+.. highlightlang:: c
+
+.. _mapping:
+
+Mapping Protocol
+================
+
+
+.. cfunction:: int PyMapping_Check(PyObject *o)
+
+   Return ``1`` if the object provides mapping protocol, and ``0`` otherwise.  This
+   function always succeeds.
+
+
+.. cfunction:: Py_ssize_t PyMapping_Length(PyObject *o)
+
+   .. index:: builtin: len
+
+   Returns the number of keys in object *o* on success, and ``-1`` on failure.  For
+   objects that do not provide mapping protocol, this is equivalent to the Python
+   expression ``len(o)``.
+
+
+.. cfunction:: int PyMapping_DelItemString(PyObject *o, char *key)
+
+   Remove the mapping for object *key* from the object *o*. Return ``-1`` on
+   failure.  This is equivalent to the Python statement ``del o[key]``.
+
+
+.. cfunction:: int PyMapping_DelItem(PyObject *o, PyObject *key)
+
+   Remove the mapping for object *key* from the object *o*. Return ``-1`` on
+   failure.  This is equivalent to the Python statement ``del o[key]``.
+
+
+.. cfunction:: int PyMapping_HasKeyString(PyObject *o, char *key)
+
+   On success, return ``1`` if the mapping object has the key *key* and ``0``
+   otherwise.  This is equivalent to the Python expression ``key in o``.
+   This function always succeeds.
+
+
+.. cfunction:: int PyMapping_HasKey(PyObject *o, PyObject *key)
+
+   Return ``1`` if the mapping object has the key *key* and ``0`` otherwise.  This
+   is equivalent to the Python expression ``key in o``.  This function always
+   succeeds.
+
+
+.. cfunction:: PyObject* PyMapping_Keys(PyObject *o)
+
+   On success, return a list of the keys in object *o*.  On failure, return *NULL*.
+   This is equivalent to the Python expression ``o.keys()``.
+
+
+.. cfunction:: PyObject* PyMapping_Values(PyObject *o)
+
+   On success, return a list of the values in object *o*.  On failure, return
+   *NULL*. This is equivalent to the Python expression ``o.values()``.
+
+
+.. cfunction:: PyObject* PyMapping_Items(PyObject *o)
+
+   On success, return a list of the items in object *o*, where each item is a tuple
+   containing a key-value pair.  On failure, return *NULL*. This is equivalent to
+   the Python expression ``o.items()``.
+
+
+.. cfunction:: PyObject* PyMapping_GetItemString(PyObject *o, char *key)
+
+   Return element of *o* corresponding to the object *key* or *NULL* on failure.
+   This is the equivalent of the Python expression ``o[key]``.
+
+
+.. cfunction:: int PyMapping_SetItemString(PyObject *o, char *key, PyObject *v)
+
+   Map the object *key* to the value *v* in object *o*. Returns ``-1`` on failure.
+   This is the equivalent of the Python statement ``o[key] = v``.

Added: python/branches/py3k/Doc/c-api/marshal.rst
==============================================================================
--- (empty file)
+++ python/branches/py3k/Doc/c-api/marshal.rst	Sun Jan 20 10:30:57 2008
@@ -0,0 +1,86 @@
+.. highlightlang:: c
+
+.. _marshalling-utils:
+
+Data marshalling support
+========================
+
+These routines allow C code to work with serialized objects using the same data
+format as the :mod:`marshal` module.  There are functions to write data into the
+serialization format, and additional functions that can be used to read the data
+back.  Files used to store marshalled data must be opened in binary mode.
+
+Numeric values are stored with the least significant byte first.
+
+The module supports two versions of the data format: version 0 is the historical
+version, version 1 (new in Python 2.4) shares interned strings in the file, and
+upon unmarshalling. *Py_MARSHAL_VERSION* indicates the current file format
+(currently 1).
+
+
+.. cfunction:: void PyMarshal_WriteLongToFile(long value, FILE *file, int version)
+
+   Marshal a :ctype:`long` integer, *value*, to *file*.  This will only write the
+   least-significant 32 bits of *value*; regardless of the size of the native
+   :ctype:`long` type.  *version* indicates the file format.
+
+
+.. cfunction:: void PyMarshal_WriteObjectToFile(PyObject *value, FILE *file, int version)
+
+   Marshal a Python object, *value*, to *file*.
+   *version* indicates the file format.
+
+
+.. cfunction:: PyObject* PyMarshal_WriteObjectToString(PyObject *value, int version)
+
+   Return a string object containing the marshalled representation of *value*.
+   *version* indicates the file format.
+
+
+The following functions allow marshalled values to be read back in.
+
+XXX What about error detection?  It appears that reading past the end of the
+file will always result in a negative numeric value (where that's relevant), but
+it's not clear that negative values won't be handled properly when there's no
+error.  What's the right way to tell? Should only non-negative values be written
+using these routines?
+
+
+.. cfunction:: long PyMarshal_ReadLongFromFile(FILE *file)
+
+   Return a C :ctype:`long` from the data stream in a :ctype:`FILE\*` opened for
+   reading.  Only a 32-bit value can be read in using this function, regardless of
+   the native size of :ctype:`long`.
+
+
+.. cfunction:: int PyMarshal_ReadShortFromFile(FILE *file)
+
+   Return a C :ctype:`short` from the data stream in a :ctype:`FILE\*` opened for
+   reading.  Only a 16-bit value can be read in using this function, regardless of
+   the native size of :ctype:`short`.
+
+
+.. cfunction:: PyObject* PyMarshal_ReadObjectFromFile(FILE *file)
+
+   Return a Python object from the data stream in a :ctype:`FILE\*` opened for
+   reading.  On error, sets the appropriate exception (:exc:`EOFError` or
+   :exc:`TypeError`) and returns *NULL*.
+
+
+.. cfunction:: PyObject* PyMarshal_ReadLastObjectFromFile(FILE *file)
+
+   Return a Python object from the data stream in a :ctype:`FILE\*` opened for
+   reading.  Unlike :cfunc:`PyMarshal_ReadObjectFromFile`, this function assumes
+   that no further objects will be read from the file, allowing it to aggressively
+   load file data into memory so that the de-serialization can operate from data in
+   memory rather than reading a byte at a time from the file.  Only use these
+   variant if you are certain that you won't be reading anything else from the
+   file.  On error, sets the appropriate exception (:exc:`EOFError` or
+   :exc:`TypeError`) and returns *NULL*.
+
+
+.. cfunction:: PyObject* PyMarshal_ReadObjectFromString(char *string, Py_ssize_t len)
+
+   Return a Python object from the data stream in a character buffer containing
+   *len* bytes pointed to by *string*.  On error, sets the appropriate exception
+   (:exc:`EOFError` or :exc:`TypeError`) and returns *NULL*.

Added: python/branches/py3k/Doc/c-api/method.rst
==============================================================================
--- (empty file)
+++ python/branches/py3k/Doc/c-api/method.rst	Sun Jan 20 10:30:57 2008
@@ -0,0 +1,94 @@
+.. highlightlang:: c
+
+.. _instancemethod-objects:
+
+Instance Method Objects
+-----------------------
+
+.. index:: object: instancemethod
+
+An instance method is a wrapper for a :cdata:`PyCFunction` and the new way
+to bind a :cdata:`PyCFunction` to a class object. It replaces the former call
+``PyMethod_New(func, NULL, class)``.
+
+
+.. cvar:: PyTypeObject PyInstanceMethod_Type
+
+   This instance of :ctype:`PyTypeObject` represents the Python instance
+   method type. It is not exposed to Python programs.
+
+
+.. cfunction:: int PyInstanceMethod_Check(PyObject *o)
+
+   Return true if *o* is an instance method object (has type
+   :cdata:`PyInstanceMethod_Type`).  The parameter must not be *NULL*.
+
+
+.. cfunction:: PyObject* PyInstanceMethod_New(PyObject *func)
+
+   Return a new instance method object, with *func* being any callable object
+   *func* is is the function that will be called when the instance method is
+   called.
+
+
+.. cfunction:: PyObject* PyInstanceMethod_Function(PyObject *im)
+
+   Return the function object associated with the instance method *im*.
+
+
+.. cfunction:: PyObject* PyInstanceMethod_GET_FUNCTION(PyObject *im)
+
+   Macro version of :cfunc:`PyInstanceMethod_Function` which avoids error checking.
+
+
+.. _method-objects:
+
+Method Objects
+--------------
+
+.. index:: object: method
+
+Methods are bound function objects. Methods are always bound to an instance of
+an user-defined class. Unbound methods (methods bound to a class object) are
+no longer available.
+
+
+.. cvar:: PyTypeObject PyMethod_Type
+
+   .. index:: single: MethodType (in module types)
+
+   This instance of :ctype:`PyTypeObject` represents the Python method type.  This
+   is exposed to Python programs as ``types.MethodType``.
+
+
+.. cfunction:: int PyMethod_Check(PyObject *o)
+
+   Return true if *o* is a method object (has type :cdata:`PyMethod_Type`).  The
+   parameter must not be *NULL*.
+
+
+.. cfunction:: PyObject* PyMethod_New(PyObject *func, PyObject *self)
+
+   Return a new method object, with *func* being any callable object and *self*
+   the instance the method should be bound. *func* is is the function that will
+   be called when the method is called. *self* must not be *NULL*.
+
+
+.. cfunction:: PyObject* PyMethod_Function(PyObject *meth)
+
+   Return the function object associated with the method *meth*.
+
+
+.. cfunction:: PyObject* PyMethod_GET_FUNCTION(PyObject *meth)
+
+   Macro version of :cfunc:`PyMethod_Function` which avoids error checking.
+
+
+.. cfunction:: PyObject* PyMethod_Self(PyObject *meth)
+
+   Return the instance associated with the method *meth*.
+
+
+.. cfunction:: PyObject* PyMethod_GET_SELF(PyObject *meth)
+
+   Macro version of :cfunc:`PyMethod_Self` which avoids error checking.

Added: python/branches/py3k/Doc/c-api/module.rst
==============================================================================
--- (empty file)
+++ python/branches/py3k/Doc/c-api/module.rst	Sun Jan 20 10:30:57 2008
@@ -0,0 +1,94 @@
+.. highlightlang:: c
+
+.. _moduleobjects:
+
+Module Objects
+--------------
+
+.. index:: object: module
+
+There are only a few functions special to module objects.
+
+
+.. cvar:: PyTypeObject PyModule_Type
+
+   .. index:: single: ModuleType (in module types)
+
+   This instance of :ctype:`PyTypeObject` represents the Python module type.  This
+   is exposed to Python programs as ``types.ModuleType``.
+
+
+.. cfunction:: int PyModule_Check(PyObject *p)
+
+   Return true if *p* is a module object, or a subtype of a module object.
+
+
+.. cfunction:: int PyModule_CheckExact(PyObject *p)
+
+   Return true if *p* is a module object, but not a subtype of
+   :cdata:`PyModule_Type`.
+
+
+.. cfunction:: PyObject* PyModule_New(const char *name)
+
+   .. index::
+      single: __name__ (module attribute)
+      single: __doc__ (module attribute)
+      single: __file__ (module attribute)
+
+   Return a new module object with the :attr:`__name__` attribute set to *name*.
+   Only the module's :attr:`__doc__` and :attr:`__name__` attributes are filled in;
+   the caller is responsible for providing a :attr:`__file__` attribute.
+
+
+.. cfunction:: PyObject* PyModule_GetDict(PyObject *module)
+
+   .. index:: single: __dict__ (module attribute)
+
+   Return the dictionary object that implements *module*'s namespace; this object
+   is the same as the :attr:`__dict__` attribute of the module object.  This
+   function never fails.  It is recommended extensions use other
+   :cfunc:`PyModule_\*` and :cfunc:`PyObject_\*` functions rather than directly
+   manipulate a module's :attr:`__dict__`.
+
+
+.. cfunction:: char* PyModule_GetName(PyObject *module)
+
+   .. index::
+      single: __name__ (module attribute)
+      single: SystemError (built-in exception)
+
+   Return *module*'s :attr:`__name__` value.  If the module does not provide one,
+   or if it is not a string, :exc:`SystemError` is raised and *NULL* is returned.
+
+
+.. cfunction:: char* PyModule_GetFilename(PyObject *module)
+
+   .. index::
+      single: __file__ (module attribute)
+      single: SystemError (built-in exception)
+
+   Return the name of the file from which *module* was loaded using *module*'s
+   :attr:`__file__` attribute.  If this is not defined, or if it is not a string,
+   raise :exc:`SystemError` and return *NULL*.
+
+
+.. cfunction:: int PyModule_AddObject(PyObject *module, const char *name, PyObject *value)
+
+   Add an object to *module* as *name*.  This is a convenience function which can
+   be used from the module's initialization function.  This steals a reference to
+   *value*.  Return ``-1`` on error, ``0`` on success.
+
+
+.. cfunction:: int PyModule_AddIntConstant(PyObject *module, const char *name, long value)
+
+   Add an integer constant to *module* as *name*.  This convenience function can be
+   used from the module's initialization function. Return ``-1`` on error, ``0`` on
+   success.
+
+
+.. cfunction:: int PyModule_AddStringConstant(PyObject *module, const char *name, const char *value)
+
+   Add a string constant to *module* as *name*.  This convenience function can be
+   used from the module's initialization function.  The string *value* must be
+   null-terminated.  Return ``-1`` on error, ``0`` on success.

Added: python/branches/py3k/Doc/c-api/none.rst
==============================================================================
--- (empty file)
+++ python/branches/py3k/Doc/c-api/none.rst	Sun Jan 20 10:30:57 2008
@@ -0,0 +1,26 @@
+.. highlightlang:: c
+
+.. _noneobject:
+
+The None Object
+---------------
+
+.. index:: object: None
+
+Note that the :ctype:`PyTypeObject` for ``None`` is not directly exposed in the
+Python/C API.  Since ``None`` is a singleton, testing for object identity (using
+``==`` in C) is sufficient. There is no :cfunc:`PyNone_Check` function for the
+same reason.
+
+
+.. cvar:: PyObject* Py_None
+
+   The Python ``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.
+
+
+.. cmacro:: Py_RETURN_NONE
+
+   Properly handle returning :cdata:`Py_None` from within a C function (that is,
+   increment the reference count of None and return it.)

Added: python/branches/py3k/Doc/c-api/number.rst
==============================================================================
--- (empty file)
+++ python/branches/py3k/Doc/c-api/number.rst	Sun Jan 20 10:30:57 2008
@@ -0,0 +1,276 @@
+.. highlightlang:: c
+
+.. _number:
+
+Number Protocol
+===============
+
+
+.. cfunction:: int PyNumber_Check(PyObject *o)
+
+   Returns ``1`` if the object *o* provides numeric protocols, and false otherwise.
+   This function always succeeds.
+
+
+.. cfunction:: PyObject* PyNumber_Add(PyObject *o1, PyObject *o2)
+
+   Returns the result of adding *o1* and *o2*, or *NULL* on failure.  This is the
+   equivalent of the Python expression ``o1 + o2``.
+
+
+.. cfunction:: PyObject* PyNumber_Subtract(PyObject *o1, PyObject *o2)
+
+   Returns the result of subtracting *o2* from *o1*, or *NULL* on failure.  This is
+   the equivalent of the Python expression ``o1 - o2``.
+
+
+.. cfunction:: PyObject* PyNumber_Multiply(PyObject *o1, PyObject *o2)
+
+   Returns the result of multiplying *o1* and *o2*, or *NULL* on failure.  This is
+   the equivalent of the Python expression ``o1 * o2``.
+
+
+.. cfunction:: PyObject* PyNumber_Divide(PyObject *o1, PyObject *o2)
+
+   Returns the result of dividing *o1* by *o2*, or *NULL* on failure.  This is the
+   equivalent of the Python expression ``o1 / o2``.
+
+
+.. cfunction:: PyObject* PyNumber_FloorDivide(PyObject *o1, PyObject *o2)
+
+   Return the floor of *o1* divided by *o2*, or *NULL* on failure.  This is
+   equivalent to the "classic" division of integers.
+
+
+.. cfunction:: PyObject* PyNumber_TrueDivide(PyObject *o1, PyObject *o2)
+
+   Return a reasonable approximation for the mathematical value of *o1* divided by
+   *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.
+
+
+.. cfunction:: PyObject* PyNumber_Remainder(PyObject *o1, PyObject *o2)
+
+   Returns the remainder of dividing *o1* by *o2*, or *NULL* on failure.  This is
+   the equivalent of the Python expression ``o1 % o2``.
+
+
+.. cfunction:: PyObject* PyNumber_Divmod(PyObject *o1, PyObject *o2)
+
+   .. index:: builtin: divmod
+
+   See the built-in function :func:`divmod`. Returns *NULL* on failure.  This is
+   the equivalent of the Python expression ``divmod(o1, o2)``.
+
+
+.. cfunction:: PyObject* PyNumber_Power(PyObject *o1, PyObject *o2, PyObject *o3)
+
+   .. index:: builtin: pow
+
+   See the built-in function :func:`pow`. Returns *NULL* on failure.  This is the
+   equivalent of the Python expression ``pow(o1, o2, o3)``, where *o3* is optional.
+   If *o3* is to be ignored, pass :cdata:`Py_None` in its place (passing *NULL* for
+   *o3* would cause an illegal memory access).
+
+
+.. cfunction:: PyObject* PyNumber_Negative(PyObject *o)
+
+   Returns the negation of *o* on success, or *NULL* on failure. This is the
+   equivalent of the Python expression ``-o``.
+
+
+.. cfunction:: PyObject* PyNumber_Positive(PyObject *o)
+
+   Returns *o* on success, or *NULL* on failure.  This is the equivalent of the
+   Python expression ``+o``.
+
+
+.. cfunction:: PyObject* PyNumber_Absolute(PyObject *o)
+
+   .. index:: builtin: abs
+
+   Returns the absolute value of *o*, or *NULL* on failure.  This is the equivalent
+   of the Python expression ``abs(o)``.
+
+
+.. cfunction:: PyObject* PyNumber_Invert(PyObject *o)
+
+   Returns the bitwise negation of *o* on success, or *NULL* on failure.  This is
+   the equivalent of the Python expression ``~o``.
+
+
+.. cfunction:: PyObject* PyNumber_Lshift(PyObject *o1, PyObject *o2)
+
+   Returns the result of left shifting *o1* by *o2* on success, or *NULL* on
+   failure.  This is the equivalent of the Python expression ``o1 << o2``.
+
+
+.. cfunction:: PyObject* PyNumber_Rshift(PyObject *o1, PyObject *o2)
+
+   Returns the result of right shifting *o1* by *o2* on success, or *NULL* on
+   failure.  This is the equivalent of the Python expression ``o1 >> o2``.
+
+
+.. cfunction:: PyObject* PyNumber_And(PyObject *o1, PyObject *o2)
+
+   Returns the "bitwise and" of *o1* and *o2* on success and *NULL* on failure.
+   This is the equivalent of the Python expression ``o1 & o2``.
+
+
+.. cfunction:: PyObject* PyNumber_Xor(PyObject *o1, PyObject *o2)
+
+   Returns the "bitwise exclusive or" of *o1* by *o2* on success, or *NULL* on
+   failure.  This is the equivalent of the Python expression ``o1 ^ o2``.
+
+
+.. cfunction:: PyObject* PyNumber_Or(PyObject *o1, PyObject *o2)
+
+   Returns the "bitwise or" of *o1* and *o2* on success, or *NULL* on failure.
+   This is the equivalent of the Python expression ``o1 | o2``.
+
+
+.. cfunction:: PyObject* PyNumber_InPlaceAdd(PyObject *o1, PyObject *o2)
+
+   Returns the result of adding *o1* and *o2*, or *NULL* on failure.  The operation
+   is done *in-place* when *o1* supports it.  This is the equivalent of the Python
+   statement ``o1 += o2``.
+
+
+.. cfunction:: PyObject* PyNumber_InPlaceSubtract(PyObject *o1, PyObject *o2)
+
+   Returns the result of subtracting *o2* from *o1*, or *NULL* on failure.  The
+   operation is done *in-place* when *o1* supports it.  This is the equivalent of
+   the Python statement ``o1 -= o2``.
+
+
+.. cfunction:: PyObject* PyNumber_InPlaceMultiply(PyObject *o1, PyObject *o2)
+
+   Returns the result of multiplying *o1* and *o2*, or *NULL* on failure.  The
+   operation is done *in-place* when *o1* supports it.  This is the equivalent of
+   the Python statement ``o1 *= o2``.
+
+
+.. cfunction:: PyObject* PyNumber_InPlaceDivide(PyObject *o1, PyObject *o2)
+
+   Returns the result of dividing *o1* by *o2*, or *NULL* on failure.  The
+   operation is done *in-place* when *o1* supports it. This is the equivalent of
+   the Python statement ``o1 /= o2``.
+
+
+.. cfunction:: PyObject* PyNumber_InPlaceFloorDivide(PyObject *o1, PyObject *o2)
+
+   Returns the mathematical floor of dividing *o1* by *o2*, or *NULL* on failure.
+   The operation is done *in-place* when *o1* supports it.  This is the equivalent
+   of the Python statement ``o1 //= o2``.
+
+
+.. cfunction:: PyObject* PyNumber_InPlaceTrueDivide(PyObject *o1, PyObject *o2)
+
+   Return a reasonable approximation for the mathematical value of *o1* divided by
+   *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 *in-place* when *o1* supports it.
+
+
+.. cfunction:: PyObject* PyNumber_InPlaceRemainder(PyObject *o1, PyObject *o2)
+
+   Returns the remainder of dividing *o1* by *o2*, or *NULL* on failure.  The
+   operation is done *in-place* when *o1* supports it.  This is the equivalent of
+   the Python statement ``o1 %= o2``.
+
+
+.. cfunction:: PyObject* PyNumber_InPlacePower(PyObject *o1, PyObject *o2, PyObject *o3)
+
+   .. index:: builtin: pow
+
+   See the built-in function :func:`pow`. Returns *NULL* on failure.  The operation
+   is done *in-place* when *o1* supports it.  This is the equivalent of the Python
+   statement ``o1 **= o2`` when o3 is :cdata:`Py_None`, or an in-place variant of
+   ``pow(o1, o2, o3)`` otherwise. If *o3* is to be ignored, pass :cdata:`Py_None`
+   in its place (passing *NULL* for *o3* would cause an illegal memory access).
+
+
+.. cfunction:: PyObject* PyNumber_InPlaceLshift(PyObject *o1, PyObject *o2)
+
+   Returns the result of left shifting *o1* by *o2* on success, or *NULL* on
+   failure.  The operation is done *in-place* when *o1* supports it.  This is the
+   equivalent of the Python statement ``o1 <<= o2``.
+
+
+.. cfunction:: PyObject* PyNumber_InPlaceRshift(PyObject *o1, PyObject *o2)
+
+   Returns the result of right shifting *o1* by *o2* on success, or *NULL* on
+   failure.  The operation is done *in-place* when *o1* supports it.  This is the
+   equivalent of the Python statement ``o1 >>= o2``.
+
+
+.. cfunction:: PyObject* PyNumber_InPlaceAnd(PyObject *o1, PyObject *o2)
+
+   Returns the "bitwise and" of *o1* and *o2* on success and *NULL* on failure. The
+   operation is done *in-place* when *o1* supports it.  This is the equivalent of
+   the Python statement ``o1 &= o2``.
+
+
+.. cfunction:: PyObject* PyNumber_InPlaceXor(PyObject *o1, PyObject *o2)
+
+   Returns the "bitwise exclusive or" of *o1* by *o2* on success, or *NULL* on
+   failure.  The operation is done *in-place* when *o1* supports it.  This is the
+   equivalent of the Python statement ``o1 ^= o2``.
+
+
+.. cfunction:: PyObject* PyNumber_InPlaceOr(PyObject *o1, PyObject *o2)
+
+   Returns the "bitwise or" of *o1* and *o2* on success, or *NULL* on failure.  The
+   operation is done *in-place* when *o1* supports it.  This is the equivalent of
+   the Python statement ``o1 |= o2``.
+
+
+.. cfunction:: PyObject* PyNumber_Int(PyObject *o)
+
+   .. index:: builtin: int
+
+   Returns the *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 ``int(o)``.
+
+
+.. cfunction:: PyObject* PyNumber_Long(PyObject *o)
+
+   .. index:: builtin: long
+
+   Returns the *o* converted to an integer object on success, or *NULL* on
+   failure.  This is the equivalent of the Python expression ``long(o)``.
+
+
+.. cfunction:: PyObject* PyNumber_Float(PyObject *o)
+
+   .. index:: builtin: float
+
+   Returns the *o* converted to a float object on success, or *NULL* on failure.
+   This is the equivalent of the Python expression ``float(o)``.
+
+
+.. cfunction:: PyObject* PyNumber_Index(PyObject *o)
+
+   Returns the *o* converted to a Python int or long on success or *NULL* with a
+   TypeError exception raised on failure.
+
+
+.. cfunction:: Py_ssize_t PyNumber_AsSsize_t(PyObject *o, PyObject *exc)
+
+   Returns *o* converted to a Py_ssize_t value if *o* can be interpreted as an
+   integer. If *o* can be converted to a Python int or long but the attempt to
+   convert to a Py_ssize_t value would raise an :exc:`OverflowError`, then the
+   *exc* argument is the type of exception that will be raised (usually
+   :exc:`IndexError` or :exc:`OverflowError`).  If *exc* is *NULL*, then the
+   exception is cleared and the value is clipped to *PY_SSIZE_T_MIN* for a negative
+   integer or *PY_SSIZE_T_MAX* for a positive integer.
+
+
+.. cfunction:: int PyIndex_Check(PyObject *o)
+
+   Returns True if *o* is an index integer (has the nb_index slot of  the
+   tp_as_number structure filled in).

Added: python/branches/py3k/Doc/c-api/objbuffer.rst
==============================================================================
--- (empty file)
+++ python/branches/py3k/Doc/c-api/objbuffer.rst	Sun Jan 20 10:30:57 2008
@@ -0,0 +1,37 @@
+.. highlightlang:: c
+
+.. _abstract-buffer:
+
+Buffer Protocol
+===============
+
+
+.. cfunction:: int PyObject_AsCharBuffer(PyObject *obj, const char **buffer, Py_ssize_t *buffer_len)
+
+   Returns a pointer to a read-only memory location useable as character- based
+   input.  The *obj* argument must support the single-segment character buffer
+   interface.  On success, returns ``0``, sets *buffer* to the memory location and
+   *buffer_len* to the buffer length.  Returns ``-1`` and sets a :exc:`TypeError`
+   on error.
+
+
+.. cfunction:: int PyObject_AsReadBuffer(PyObject *obj, const void **buffer, Py_ssize_t *buffer_len)
+
+   Returns a pointer to a read-only memory location containing arbitrary data.  The
+   *obj* argument must support the single-segment readable buffer interface.  On
+   success, returns ``0``, sets *buffer* to the memory location and *buffer_len* to
+   the buffer length.  Returns ``-1`` and sets a :exc:`TypeError` on error.
+
+
+.. cfunction:: int PyObject_CheckReadBuffer(PyObject *o)
+
+   Returns ``1`` if *o* supports the single-segment readable buffer interface.
+   Otherwise returns ``0``.
+
+
+.. cfunction:: int PyObject_AsWriteBuffer(PyObject *obj, void **buffer, Py_ssize_t *buffer_len)
+
+   Returns a pointer to a writable memory location.  The *obj* argument must
+   support the single-segment, character buffer interface.  On success, returns
+   ``0``, sets *buffer* to the memory location and *buffer_len* to the buffer
+   length.  Returns ``-1`` and sets a :exc:`TypeError` on error.

Added: python/branches/py3k/Doc/c-api/object.rst
==============================================================================
--- (empty file)
+++ python/branches/py3k/Doc/c-api/object.rst	Sun Jan 20 10:30:57 2008
@@ -0,0 +1,325 @@
+.. highlightlang:: c
+
+.. _object:
+
+Object Protocol
+===============
+
+
+.. cfunction:: int PyObject_Print(PyObject *o, FILE *fp, int flags)
+
+   Print an object *o*, on file *fp*.  Returns ``-1`` on error.  The flags argument
+   is used to enable certain printing options.  The only option currently supported
+   is :const:`Py_PRINT_RAW`; if given, the :func:`str` of the object is written
+   instead of the :func:`repr`.
+
+
+.. cfunction:: int PyObject_HasAttr(PyObject *o, PyObject *attr_name)
+
+   Returns ``1`` if *o* has the attribute *attr_name*, and ``0`` otherwise.  This
+   is equivalent to the Python expression ``hasattr(o, attr_name)``.  This function
+   always succeeds.
+
+
+.. cfunction:: int PyObject_HasAttrString(PyObject *o, const char *attr_name)
+
+   Returns ``1`` if *o* has the attribute *attr_name*, and ``0`` otherwise.  This
+   is equivalent to the Python expression ``hasattr(o, attr_name)``.  This function
+   always succeeds.
+
+
+.. cfunction:: PyObject* PyObject_GetAttr(PyObject *o, PyObject *attr_name)
+
+   Retrieve an attribute named *attr_name* from object *o*. Returns the attribute
+   value on success, or *NULL* on failure.  This is the equivalent of the Python
+   expression ``o.attr_name``.
+
+
+.. cfunction:: PyObject* PyObject_GetAttrString(PyObject *o, const char *attr_name)
+
+   Retrieve an attribute named *attr_name* from object *o*. Returns the attribute
+   value on success, or *NULL* on failure. This is the equivalent of the Python
+   expression ``o.attr_name``.
+
+
+.. cfunction:: int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v)
+
+   Set the value of the attribute named *attr_name*, for object *o*, to the value
+   *v*. Returns ``-1`` on failure.  This is the equivalent of the Python statement
+   ``o.attr_name = v``.
+
+
+.. cfunction:: int PyObject_SetAttrString(PyObject *o, const char *attr_name, PyObject *v)
+
+   Set the value of the attribute named *attr_name*, for object *o*, to the value
+   *v*. Returns ``-1`` on failure.  This is the equivalent of the Python statement
+   ``o.attr_name = v``.
+
+
+.. cfunction:: int PyObject_DelAttr(PyObject *o, PyObject *attr_name)
+
+   Delete attribute named *attr_name*, for object *o*. Returns ``-1`` on failure.
+   This is the equivalent of the Python statement ``del o.attr_name``.
+
+
+.. cfunction:: int PyObject_DelAttrString(PyObject *o, const char *attr_name)
+
+   Delete attribute named *attr_name*, for object *o*. Returns ``-1`` on failure.
+   This is the equivalent of the Python statement ``del o.attr_name``.
+
+
+.. cfunction:: PyObject* PyObject_RichCompare(PyObject *o1, PyObject *o2, int opid)
+
+   Compare the values of *o1* and *o2* using the operation specified by *opid*,
+   which must be one of :const:`Py_LT`, :const:`Py_LE`, :const:`Py_EQ`,
+   :const:`Py_NE`, :const:`Py_GT`, or :const:`Py_GE`, corresponding to ``<``,
+   ``<=``, ``==``, ``!=``, ``>``, or ``>=`` respectively. This is the equivalent of
+   the Python expression ``o1 op o2``, where ``op`` is the operator corresponding
+   to *opid*. Returns the value of the comparison on success, or *NULL* on failure.
+
+
+.. cfunction:: int PyObject_RichCompareBool(PyObject *o1, PyObject *o2, int opid)
+
+   Compare the values of *o1* and *o2* using the operation specified by *opid*,
+   which must be one of :const:`Py_LT`, :const:`Py_LE`, :const:`Py_EQ`,
+   :const:`Py_NE`, :const:`Py_GT`, or :const:`Py_GE`, corresponding to ``<``,
+   ``<=``, ``==``, ``!=``, ``>``, or ``>=`` respectively. Returns ``-1`` on error,
+   ``0`` if the result is false, ``1`` otherwise. This is the equivalent of the
+   Python expression ``o1 op o2``, where ``op`` is the operator corresponding to
+   *opid*.
+
+
+.. cfunction:: int PyObject_Cmp(PyObject *o1, PyObject *o2, int *result)
+
+   .. index:: builtin: cmp
+
+   Compare the values of *o1* and *o2* using a routine provided by *o1*, if one
+   exists, otherwise with a routine provided by *o2*.  The result of the comparison
+   is returned in *result*.  Returns ``-1`` on failure.  This is the equivalent of
+   the Python statement ``result = cmp(o1, o2)``.
+
+
+.. cfunction:: int PyObject_Compare(PyObject *o1, PyObject *o2)
+
+   .. index:: builtin: cmp
+
+   Compare the values of *o1* and *o2* using a routine provided by *o1*, if one
+   exists, otherwise with a routine provided by *o2*.  Returns the result of the
+   comparison on success.  On error, the value returned is undefined; use
+   :cfunc:`PyErr_Occurred` to detect an error.  This is equivalent to the Python
+   expression ``cmp(o1, o2)``.
+
+
+.. cfunction:: PyObject* PyObject_Repr(PyObject *o)
+
+   .. index:: builtin: repr
+
+   Compute a string representation of object *o*.  Returns the string
+   representation on success, *NULL* on failure.  This is the equivalent of the
+   Python expression ``repr(o)``.  Called by the :func:`repr` built-in function and
+   by reverse quotes.
+
+
+.. cfunction:: PyObject* PyObject_Str(PyObject *o)
+
+   .. index:: builtin: str
+
+   Compute a string representation of object *o*.  Returns the string
+   representation on success, *NULL* on failure.  This is the equivalent of the
+   Python expression ``str(o)``.  Called by the :func:`str` built-in function
+   and, therefore, by the :func:`print` function.
+
+
+.. cfunction:: PyObject* PyObject_Unicode(PyObject *o)
+
+   .. index:: builtin: unicode
+
+   Compute a Unicode string representation of object *o*.  Returns the Unicode
+   string representation on success, *NULL* on failure. This is the equivalent of
+   the Python expression ``unicode(o)``.  Called by the :func:`unicode` built-in
+   function.
+
+
+.. cfunction:: int PyObject_IsInstance(PyObject *inst, PyObject *cls)
+
+   Returns ``1`` if *inst* is an instance of the class *cls* or a subclass of
+   *cls*, or ``0`` if not.  On error, returns ``-1`` and sets an exception.  If
+   *cls* is a type object rather than a class object, :cfunc:`PyObject_IsInstance`
+   returns ``1`` if *inst* is of type *cls*.  If *cls* is a tuple, the check will
+   be done against every entry in *cls*. The result will be ``1`` when at least one
+   of the checks returns ``1``, otherwise it will be ``0``. If *inst* is not a
+   class instance and *cls* is neither a type object, nor a class object, nor a
+   tuple, *inst* must have a :attr:`__class__` attribute --- the class relationship
+   of the value of that attribute with *cls* will be used to determine the result
+   of this function.
+
+
+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 *B* is a subclass of
+*A*, if *A* is *B*, :cfunc:`PyObject_IsSubclass` returns true.  If *A* and *B*
+are different objects, *B*'s :attr:`__bases__` attribute is searched in a
+depth-first fashion for *A* --- the presence of the :attr:`__bases__` attribute
+is considered sufficient for this determination.
+
+
+.. cfunction:: int PyObject_IsSubclass(PyObject *derived, PyObject *cls)
+
+   Returns ``1`` if the class *derived* is identical to or derived from the class
+   *cls*, otherwise returns ``0``.  In case of an error, returns ``-1``. If *cls*
+   is a tuple, the check will be done against every entry in *cls*. The result will
+   be ``1`` when at least one of the checks returns ``1``, otherwise it will be
+   ``0``. If either *derived* or *cls* is not an actual class object (or tuple),
+   this function uses the generic algorithm described above.
+
+
+.. cfunction:: int PyCallable_Check(PyObject *o)
+
+   Determine if the object *o* is callable.  Return ``1`` if the object is callable
+   and ``0`` otherwise.  This function always succeeds.
+
+
+.. cfunction:: PyObject* PyObject_Call(PyObject *callable_object, PyObject *args, PyObject *kw)
+
+   Call a callable Python object *callable_object*, with arguments given by the
+   tuple *args*, and named arguments given by the dictionary *kw*. If no named
+   arguments are needed, *kw* may be *NULL*. *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
+   ``callable_object(*args, **kw)``.
+
+
+.. cfunction:: PyObject* PyObject_CallObject(PyObject *callable_object, PyObject *args)
+
+   Call a callable Python object *callable_object*, with arguments given by the
+   tuple *args*.  If no arguments are needed, then *args* may be *NULL*.  Returns
+   the result of the call on success, or *NULL* on failure.  This is the equivalent
+   of the Python expression ``callable_object(*args)``.
+
+
+.. cfunction:: PyObject* PyObject_CallFunction(PyObject *callable, char *format, ...)
+
+   Call a callable Python object *callable*, with a variable number of C arguments.
+   The C arguments are described using a :cfunc:`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 ``callable(*args)``. Note that if you only
+   pass :ctype:`PyObject \*` args, :cfunc:`PyObject_CallFunctionObjArgs` is a
+   faster alternative.
+
+
+.. cfunction:: PyObject* PyObject_CallMethod(PyObject *o, char *method, char *format, ...)
+
+   Call the method named *method* of object *o* with a variable number of C
+   arguments.  The C arguments are described by a :cfunc:`Py_BuildValue` format
+   string that should  produce a tuple.  The format may be *NULL*, indicating that
+   no arguments are provided. Returns the result of the call on success, or *NULL*
+   on failure.  This is the equivalent of the Python expression ``o.method(args)``.
+   Note that if you only pass :ctype:`PyObject \*` args,
+   :cfunc:`PyObject_CallMethodObjArgs` is a faster alternative.
+
+
+.. cfunction:: PyObject* PyObject_CallFunctionObjArgs(PyObject *callable, ..., NULL)
+
+   Call a callable Python object *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.
+
+
+.. cfunction:: PyObject* PyObject_CallMethodObjArgs(PyObject *o, PyObject *name, ..., NULL)
+
+   Calls a method of the object *o*, where the name of the method is given as a
+   Python string object in *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.
+
+
+.. cfunction:: long PyObject_Hash(PyObject *o)
+
+   .. index:: builtin: hash
+
+   Compute and return the hash value of an object *o*.  On failure, return ``-1``.
+   This is the equivalent of the Python expression ``hash(o)``.
+
+
+.. cfunction:: int PyObject_IsTrue(PyObject *o)
+
+   Returns ``1`` if the object *o* is considered to be true, and ``0`` otherwise.
+   This is equivalent to the Python expression ``not not o``.  On failure, return
+   ``-1``.
+
+
+.. cfunction:: int PyObject_Not(PyObject *o)
+
+   Returns ``0`` if the object *o* is considered to be true, and ``1`` otherwise.
+   This is equivalent to the Python expression ``not o``.  On failure, return
+   ``-1``.
+
+
+.. cfunction:: PyObject* PyObject_Type(PyObject *o)
+
+   .. index:: builtin: type
+
+   When *o* is non-*NULL*, returns a type object corresponding to the object type
+   of object *o*. On failure, raises :exc:`SystemError` and returns *NULL*.  This
+   is equivalent to the Python expression ``type(o)``. This function increments the
+   reference count of the return value. There's really no reason to use this
+   function instead of the common expression ``o->ob_type``, which returns a
+   pointer of type :ctype:`PyTypeObject\*`, except when the incremented reference
+   count is needed.
+
+
+.. cfunction:: int PyObject_TypeCheck(PyObject *o, PyTypeObject *type)
+
+   Return true if the object *o* is of type *type* or a subtype of *type*.  Both
+   parameters must be non-*NULL*.
+
+
+.. cfunction:: Py_ssize_t PyObject_Length(PyObject *o)
+               Py_ssize_t PyObject_Size(PyObject *o)
+
+   .. index:: builtin: len
+
+   Return the length of object *o*.  If the object *o* provides either the sequence
+   and mapping protocols, the sequence length is returned.  On error, ``-1`` is
+   returned.  This is the equivalent to the Python expression ``len(o)``.
+
+
+.. cfunction:: PyObject* PyObject_GetItem(PyObject *o, PyObject *key)
+
+   Return element of *o* corresponding to the object *key* or *NULL* on failure.
+   This is the equivalent of the Python expression ``o[key]``.
+
+
+.. cfunction:: int PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v)
+
+   Map the object *key* to the value *v*.  Returns ``-1`` on failure.  This is the
+   equivalent of the Python statement ``o[key] = v``.
+
+
+.. cfunction:: int PyObject_DelItem(PyObject *o, PyObject *key)
+
+   Delete the mapping for *key* from *o*.  Returns ``-1`` on failure. This is the
+   equivalent of the Python statement ``del o[key]``.
+
+
+.. cfunction:: PyObject* PyObject_Dir(PyObject *o)
+
+   This is equivalent to the Python expression ``dir(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 ``dir()``,
+   returning the names of the current locals; in this case, if no execution frame
+   is active then *NULL* is returned but :cfunc:`PyErr_Occurred` will return false.
+
+
+.. cfunction:: PyObject* PyObject_GetIter(PyObject *o)
+
+   This is equivalent to the Python expression ``iter(o)``. It returns a new
+   iterator for the object argument, or the object  itself if the object is already
+   an iterator.  Raises :exc:`TypeError` and returns *NULL* if the object cannot be
+   iterated.

Added: python/branches/py3k/Doc/c-api/objimpl.rst
==============================================================================
--- (empty file)
+++ python/branches/py3k/Doc/c-api/objimpl.rst	Sun Jan 20 10:30:57 2008
@@ -0,0 +1,17 @@
+.. highlightlang:: c
+
+.. _newtypes:
+
+*****************************
+Object Implementation Support
+*****************************
+
+This chapter describes the functions, types, and macros used when defining new
+object types.
+
+.. toctree::
+
+   allocation.rst
+   structures.rst
+   typeobj.rst
+   gcsupport.rst

Added: python/branches/py3k/Doc/c-api/reflection.rst
==============================================================================
--- (empty file)
+++ python/branches/py3k/Doc/c-api/reflection.rst	Sun Jan 20 10:30:57 2008
@@ -0,0 +1,50 @@
+.. highlightlang:: c
+
+.. _reflection:
+
+Reflection
+==========
+
+.. cfunction:: PyObject* PyEval_GetBuiltins()
+
+   Return a dictionary of the builtins in the current execution frame,
+   or the interpreter of the thread state if no frame is currently executing.
+
+
+.. cfunction:: PyObject* PyEval_GetLocals()
+
+   Return a dictionary of the local variables in the current execution frame,
+   or *NULL* if no frame is currently executing.
+   
+
+.. cfunction:: PyObject* PyEval_GetGlobals()
+
+   Return a dictionary of the global variables in the current execution frame,
+   or *NULL* if no frame is currently executing.
+
+
+.. cfunction:: PyFrameObject* PyEval_GetFrame()
+
+   Return the current thread state's frame, which is *NULL* if no frame is
+   currently executing.
+
+
+.. cfunction:: int PyEval_GetRestricted()
+
+   If there is a current frame and it is executing in restricted mode, return true,
+   otherwise false.
+
+
+.. cfunction:: const char* PyEval_GetFuncName(PyObject *func)
+
+   Return the name of *func* if it is a function, class or instance object, else the
+   name of *func*\s type.
+
+
+.. cfunction:: const char* PyEval_GetFuncDesc(PyObject *func)
+
+   Return a description string, depending on the type of *func*.
+   Return values include "()" for functions and methods, " constructor",
+   " instance", and " object".  Concatenated with the result of
+   :cfunc:`PyEval_GetFuncName`, the result will be a description of
+   *func*.

Added: python/branches/py3k/Doc/c-api/sequence.rst
==============================================================================
--- (empty file)
+++ python/branches/py3k/Doc/c-api/sequence.rst	Sun Jan 20 10:30:57 2008
@@ -0,0 +1,162 @@
+.. highlightlang:: c
+
+.. _sequence:
+
+Sequence Protocol
+=================
+
+
+.. cfunction:: int PySequence_Check(PyObject *o)
+
+   Return ``1`` if the object provides sequence protocol, and ``0`` otherwise.
+   This function always succeeds.
+
+
+.. cfunction:: Py_ssize_t PySequence_Size(PyObject *o)
+
+   .. index:: builtin: len
+
+   Returns the number of objects in sequence *o* on success, and ``-1`` on failure.
+   For objects that do not provide sequence protocol, this is equivalent to the
+   Python expression ``len(o)``.
+
+
+.. cfunction:: Py_ssize_t PySequence_Length(PyObject *o)
+
+   Alternate name for :cfunc:`PySequence_Size`.
+
+
+.. cfunction:: PyObject* PySequence_Concat(PyObject *o1, PyObject *o2)
+
+   Return the concatenation of *o1* and *o2* on success, and *NULL* on failure.
+   This is the equivalent of the Python expression ``o1 + o2``.
+
+
+.. cfunction:: PyObject* PySequence_Repeat(PyObject *o, Py_ssize_t count)
+
+   Return the result of repeating sequence object *o* *count* times, or *NULL* on
+   failure.  This is the equivalent of the Python expression ``o * count``.
+
+
+.. cfunction:: PyObject* PySequence_InPlaceConcat(PyObject *o1, PyObject *o2)
+
+   Return the concatenation of *o1* and *o2* on success, and *NULL* on failure.
+   The operation is done *in-place* when *o1* supports it.  This is the equivalent
+   of the Python expression ``o1 += o2``.
+
+
+.. cfunction:: PyObject* PySequence_InPlaceRepeat(PyObject *o, Py_ssize_t count)
+
+   Return the result of repeating sequence object *o* *count* times, or *NULL* on
+   failure.  The operation is done *in-place* when *o* supports it.  This is the
+   equivalent of the Python expression ``o *= count``.
+
+
+.. cfunction:: PyObject* PySequence_GetItem(PyObject *o, Py_ssize_t i)
+
+   Return the *i*th element of *o*, or *NULL* on failure. This is the equivalent of
+   the Python expression ``o[i]``.
+
+
+.. cfunction:: PyObject* PySequence_GetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2)
+
+   Return the slice of sequence object *o* between *i1* and *i2*, or *NULL* on
+   failure. This is the equivalent of the Python expression ``o[i1:i2]``.
+
+
+.. cfunction:: int PySequence_SetItem(PyObject *o, Py_ssize_t i, PyObject *v)
+
+   Assign object *v* to the *i*th element of *o*.  Returns ``-1`` on failure.  This
+   is the equivalent of the Python statement ``o[i] = v``.  This function *does
+   not* steal a reference to *v*.
+
+
+.. cfunction:: int PySequence_DelItem(PyObject *o, Py_ssize_t i)
+
+   Delete the *i*th element of object *o*.  Returns ``-1`` on failure.  This is the
+   equivalent of the Python statement ``del o[i]``.
+
+
+.. cfunction:: int PySequence_SetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2, PyObject *v)
+
+   Assign the sequence object *v* to the slice in sequence object *o* from *i1* to
+   *i2*.  This is the equivalent of the Python statement ``o[i1:i2] = v``.
+
+
+.. cfunction:: int PySequence_DelSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2)
+
+   Delete the slice in sequence object *o* from *i1* to *i2*.  Returns ``-1`` on
+   failure.  This is the equivalent of the Python statement ``del o[i1:i2]``.
+
+
+.. cfunction:: Py_ssize_t PySequence_Count(PyObject *o, PyObject *value)
+
+   Return the number of occurrences of *value* in *o*, that is, return the number
+   of keys for which ``o[key] == value``.  On failure, return ``-1``.  This is
+   equivalent to the Python expression ``o.count(value)``.
+
+
+.. cfunction:: int PySequence_Contains(PyObject *o, PyObject *value)
+
+   Determine if *o* contains *value*.  If an item in *o* is equal to *value*,
+   return ``1``, otherwise return ``0``. On error, return ``-1``.  This is
+   equivalent to the Python expression ``value in o``.
+
+
+.. cfunction:: Py_ssize_t PySequence_Index(PyObject *o, PyObject *value)
+
+   Return the first index *i* for which ``o[i] == value``.  On error, return
+   ``-1``.    This is equivalent to the Python expression ``o.index(value)``.
+
+
+.. cfunction:: PyObject* PySequence_List(PyObject *o)
+
+   Return a list object with the same contents as the arbitrary sequence *o*.  The
+   returned list is guaranteed to be new.
+
+
+.. cfunction:: PyObject* PySequence_Tuple(PyObject *o)
+
+   .. index:: builtin: tuple
+
+   Return a tuple object with the same contents as the arbitrary sequence *o* or
+   *NULL* on failure.  If *o* is a tuple, a new reference will be returned,
+   otherwise a tuple will be constructed with the appropriate contents.  This is
+   equivalent to the Python expression ``tuple(o)``.
+
+
+.. cfunction:: PyObject* PySequence_Fast(PyObject *o, const char *m)
+
+   Returns the sequence *o* as a tuple, unless it is already a tuple or list, in
+   which case *o* is returned.  Use :cfunc:`PySequence_Fast_GET_ITEM` to access the
+   members of the result.  Returns *NULL* on failure.  If the object is not a
+   sequence, raises :exc:`TypeError` with *m* as the message text.
+
+
+.. cfunction:: PyObject* PySequence_Fast_GET_ITEM(PyObject *o, Py_ssize_t i)
+
+   Return the *i*th element of *o*, assuming that *o* was returned by
+   :cfunc:`PySequence_Fast`, *o* is not *NULL*, and that *i* is within bounds.
+
+
+.. cfunction:: PyObject** PySequence_Fast_ITEMS(PyObject *o)
+
+   Return the underlying array of PyObject pointers.  Assumes that *o* was returned
+   by :cfunc:`PySequence_Fast` and *o* is not *NULL*.
+
+
+.. cfunction:: PyObject* PySequence_ITEM(PyObject *o, Py_ssize_t i)
+
+   Return the *i*th element of *o* or *NULL* on failure. Macro form of
+   :cfunc:`PySequence_GetItem` but without checking that
+   :cfunc:`PySequence_Check(o)` is true and without adjustment for negative
+   indices.
+
+
+.. cfunction:: Py_ssize_t PySequence_Fast_GET_SIZE(PyObject *o)
+
+   Returns the length of *o*, assuming that *o* was returned by
+   :cfunc:`PySequence_Fast` and that *o* is not *NULL*.  The size can also be
+   gotten by calling :cfunc:`PySequence_Size` on *o*, but
+   :cfunc:`PySequence_Fast_GET_SIZE` is faster because it can assume *o* is a list
+   or tuple.

Added: python/branches/py3k/Doc/c-api/set.rst
==============================================================================
--- (empty file)
+++ python/branches/py3k/Doc/c-api/set.rst	Sun Jan 20 10:30:57 2008
@@ -0,0 +1,146 @@
+.. highlightlang:: c
+
+.. _setobjects:
+
+Set Objects
+-----------
+
+.. sectionauthor:: Raymond D. Hettinger <python at rcn.com>
+
+
+.. index::
+   object: set
+   object: frozenset
+
+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 :cfunc:`PyObject_CallMethod`,
+:cfunc:`PyObject_RichCompareBool`, :cfunc:`PyObject_Hash`,
+:cfunc:`PyObject_Repr`, :cfunc:`PyObject_IsTrue`, :cfunc:`PyObject_Print`, and
+:cfunc:`PyObject_GetIter`) or the abstract number protocol (including
+:cfunc:`PyNumber_And`, :cfunc:`PyNumber_Subtract`, :cfunc:`PyNumber_Or`,
+:cfunc:`PyNumber_Xor`, :cfunc:`PyNumber_InPlaceAnd`,
+:cfunc:`PyNumber_InPlaceSubtract`, :cfunc:`PyNumber_InPlaceOr`, and
+:cfunc:`PyNumber_InPlaceXor`).
+
+
+.. ctype:: 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.
+
+
+.. cvar:: PyTypeObject PySet_Type
+
+   This is an instance of :ctype:`PyTypeObject` representing the Python
+   :class:`set` type.
+
+
+.. cvar:: PyTypeObject PyFrozenSet_Type
+
+   This is an instance of :ctype:`PyTypeObject` representing the Python
+   :class:`frozenset` type.
+
+The following type check macros work on pointers to any Python object. Likewise,
+the constructor functions work with any iterable Python object.
+
+
+.. cfunction:: int PyAnySet_Check(PyObject *p)
+
+   Return true if *p* is a :class:`set` object, a :class:`frozenset` object, or an
+   instance of a subtype.
+
+
+.. cfunction:: int PyAnySet_CheckExact(PyObject *p)
+
+   Return true if *p* is a :class:`set` object or a :class:`frozenset` object but
+   not an instance of a subtype.
+
+
+.. cfunction:: int PyFrozenSet_CheckExact(PyObject *p)
+
+   Return true if *p* is a :class:`frozenset` object but not an instance of a
+   subtype.
+
+
+.. cfunction:: PyObject* PySet_New(PyObject *iterable)
+
+   Return a new :class:`set` containing objects returned by the *iterable*.  The
+   *iterable* may be *NULL* to create a new empty set.  Return the new set on
+   success or *NULL* on failure.  Raise :exc:`TypeError` if *iterable* is not
+   actually iterable.  The constructor is also useful for copying a set
+   (``c=set(s)``).
+
+
+.. cfunction:: PyObject* PyFrozenSet_New(PyObject *iterable)
+
+   Return a new :class:`frozenset` containing objects returned by the *iterable*.
+   The *iterable* may be *NULL* to create a new empty frozenset.  Return the new
+   set on success or *NULL* on failure.  Raise :exc:`TypeError` if *iterable* is
+   not actually iterable.
+
+The following functions and macros are available for instances of :class:`set`
+or :class:`frozenset` or instances of their subtypes.
+
+
+.. cfunction:: Py_ssize_t PySet_Size(PyObject *anyset)
+
+   .. index:: builtin: len
+
+   Return the length of a :class:`set` or :class:`frozenset` object. Equivalent to
+   ``len(anyset)``.  Raises a :exc:`PyExc_SystemError` if *anyset* is not a
+   :class:`set`, :class:`frozenset`, or an instance of a subtype.
+
+
+.. cfunction:: Py_ssize_t PySet_GET_SIZE(PyObject *anyset)
+
+   Macro form of :cfunc:`PySet_Size` without error checking.
+
+
+.. cfunction:: 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 :meth:`__contains__` method, this function does not automatically
+   convert unhashable sets into temporary frozensets.  Raise a :exc:`TypeError` if
+   the *key* is unhashable. Raise :exc:`PyExc_SystemError` if *anyset* is not a
+   :class:`set`, :class:`frozenset`, or an instance of a subtype.
+
+The following functions are available for instances of :class:`set` or its
+subtypes but not for instances of :class:`frozenset` or its subtypes.
+
+
+.. cfunction:: int PySet_Add(PyObject *set, PyObject *key)
+
+   Add *key* to a :class:`set` instance.  Does not apply to :class:`frozenset`
+   instances.  Return 0 on success or -1 on failure. Raise a :exc:`TypeError` if
+   the *key* is unhashable. Raise a :exc:`MemoryError` if there is no room to grow.
+   Raise a :exc:`SystemError` if *set* is an not an instance of :class:`set` or its
+   subtype.
+
+
+.. cfunction:: 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 :exc:`KeyError` for missing keys.  Raise a
+   :exc:`TypeError` if the *key* is unhashable.  Unlike the Python :meth:`discard`
+   method, this function does not automatically convert unhashable sets into
+   temporary frozensets. Raise :exc:`PyExc_SystemError` if *set* is an not an
+   instance of :class:`set` or its subtype.
+
+
+.. cfunction:: PyObject* PySet_Pop(PyObject *set)
+
+   Return a new reference to an arbitrary object in the *set*, and removes the
+   object from the *set*.  Return *NULL* on failure.  Raise :exc:`KeyError` if the
+   set is empty. Raise a :exc:`SystemError` if *set* is an not an instance of
+   :class:`set` or its subtype.
+
+
+.. cfunction:: int PySet_Clear(PyObject *set)
+
+   Empty an existing set of all elements.

Added: python/branches/py3k/Doc/c-api/slice.rst
==============================================================================
--- (empty file)
+++ python/branches/py3k/Doc/c-api/slice.rst	Sun Jan 20 10:30:57 2008
@@ -0,0 +1,54 @@
+.. highlightlang:: c
+
+.. _slice-objects:
+
+Slice Objects
+-------------
+
+
+.. cvar:: PyTypeObject PySlice_Type
+
+   .. index:: single: SliceType (in module types)
+
+   The type object for slice objects.  This is the same as ``slice`` and
+   ``types.SliceType``.
+
+
+.. cfunction:: int PySlice_Check(PyObject *ob)
+
+   Return true if *ob* is a slice object; *ob* must not be *NULL*.
+
+
+.. cfunction:: PyObject* PySlice_New(PyObject *start, PyObject *stop, PyObject *step)
+
+   Return a new slice object with the given values.  The *start*, *stop*, and
+   *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 ``None`` will be
+   used for the corresponding attribute.  Return *NULL* if the new object could not
+   be allocated.
+
+
+.. cfunction:: 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 *slice*,
+   assuming a sequence of length *length*. Treats indices greater than *length* as
+   errors.
+
+   Returns 0 on success and -1 on error with no exception set (unless one of the
+   indices was not :const:`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 :cfunc:`PySlice_GetIndicesEx`, suitably renamed, in the source of
+   your extension.
+
+
+.. cfunction:: 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 :cfunc:`PySlice_GetIndices`.  Retrieve the start, stop,
+   and step indices from the slice object *slice* assuming a sequence of length
+   *length*, and store the length of the slice in *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.

Added: python/branches/py3k/Doc/c-api/string.rst
==============================================================================
--- (empty file)
+++ python/branches/py3k/Doc/c-api/string.rst	Sun Jan 20 10:30:57 2008
@@ -0,0 +1,246 @@
+.. highlightlang:: c
+
+.. _stringobjects:
+
+String Objects
+--------------
+
+These functions raise :exc:`TypeError` when expecting a string parameter and are
+called with a non-string parameter.
+
+.. index:: object: string
+
+
+.. ctype:: PyStringObject
+
+   This subtype of :ctype:`PyObject` represents a Python string object.
+
+
+.. cvar:: PyTypeObject PyString_Type
+
+   .. index:: single: StringType (in module types)
+
+   This instance of :ctype:`PyTypeObject` represents the Python string type; it is
+   the same object as ``str`` and ``types.StringType`` in the Python layer. .
+
+
+.. cfunction:: int PyString_Check(PyObject *o)
+
+   Return true if the object *o* is a string object or an instance of a subtype of
+   the string type.
+
+
+.. cfunction:: int PyString_CheckExact(PyObject *o)
+
+   Return true if the object *o* is a string object, but not an instance of a
+   subtype of the string type.
+
+
+.. cfunction:: PyObject* PyString_FromString(const char *v)
+
+   Return a new string object with a copy of the string *v* as value on success,
+   and *NULL* on failure.  The parameter *v* must not be *NULL*; it will not be
+   checked.
+
+
+.. cfunction:: PyObject* PyString_FromStringAndSize(const char *v, Py_ssize_t len)
+
+   Return a new string object with a copy of the string *v* as value and length
+   *len* on success, and *NULL* on failure.  If *v* is *NULL*, the contents of the
+   string are uninitialized.
+
+
+.. cfunction:: PyObject* PyString_FromFormat(const char *format, ...)
+
+   Take a C :cfunc:`printf`\ -style *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 *format* string.  The
+   following format characters are allowed:
+
+   .. % XXX: This should be exactly the same as the table in PyErr_Format.
+   .. % One should just refer to the other.
+   .. % XXX: 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.
+
+   +-------------------+---------------+--------------------------------+
+   | Format Characters | Type          | Comment                        |
+   +===================+===============+================================+
+   | :attr:`%%`        | *n/a*         | The literal % character.       |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%c`        | int           | A single character,            |
+   |                   |               | represented as an C int.       |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%d`        | int           | Exactly equivalent to          |
+   |                   |               | ``printf("%d")``.              |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%u`        | unsigned int  | Exactly equivalent to          |
+   |                   |               | ``printf("%u")``.              |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%ld`       | long          | Exactly equivalent to          |
+   |                   |               | ``printf("%ld")``.             |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%lu`       | unsigned long | Exactly equivalent to          |
+   |                   |               | ``printf("%lu")``.             |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%zd`       | Py_ssize_t    | Exactly equivalent to          |
+   |                   |               | ``printf("%zd")``.             |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%zu`       | size_t        | Exactly equivalent to          |
+   |                   |               | ``printf("%zu")``.             |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%i`        | int           | Exactly equivalent to          |
+   |                   |               | ``printf("%i")``.              |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%x`        | int           | Exactly equivalent to          |
+   |                   |               | ``printf("%x")``.              |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%s`        | char\*        | A null-terminated C character  |
+   |                   |               | array.                         |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%p`        | void\*        | The hex representation of a C  |
+   |                   |               | pointer. Mostly equivalent to  |
+   |                   |               | ``printf("%p")`` except that   |
+   |                   |               | it is guaranteed to start with |
+   |                   |               | the literal ``0x`` regardless  |
+   |                   |               | of what the platform's         |
+   |                   |               | ``printf`` yields.             |
+   +-------------------+---------------+--------------------------------+
+
+   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.
+
+
+.. cfunction:: PyObject* PyString_FromFormatV(const char *format, va_list vargs)
+
+   Identical to :func:`PyString_FromFormat` except that it takes exactly two
+   arguments.
+
+
+.. cfunction:: Py_ssize_t PyString_Size(PyObject *string)
+
+   Return the length of the string in string object *string*.
+
+
+.. cfunction:: Py_ssize_t PyString_GET_SIZE(PyObject *string)
+
+   Macro form of :cfunc:`PyString_Size` but without error checking.
+
+
+.. cfunction:: char* PyString_AsString(PyObject *string)
+
+   Return a NUL-terminated representation of the contents of *string*.  The pointer
+   refers to the internal buffer of *string*, not a copy.  The data must not be
+   modified in any way, unless the string was just created using
+   ``PyString_FromStringAndSize(NULL, size)``. It must not be deallocated.  If
+   *string* is a Unicode object, this function computes the default encoding of
+   *string* and operates on that.  If *string* is not a string object at all,
+   :cfunc:`PyString_AsString` returns *NULL* and raises :exc:`TypeError`.
+
+
+.. cfunction:: char* PyString_AS_STRING(PyObject *string)
+
+   Macro form of :cfunc:`PyString_AsString` but without error checking.  Only
+   string objects are supported; no Unicode objects should be passed.
+
+
+.. cfunction:: int PyString_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length)
+
+   Return a NUL-terminated representation of the contents of the object *obj*
+   through the output variables *buffer* and *length*.
+
+   The function accepts both string and Unicode objects as input. For Unicode
+   objects it returns the default encoded version of the object.  If *length* is
+   *NULL*, the resulting buffer may not contain NUL characters; if it does, the
+   function returns ``-1`` and a :exc:`TypeError` is raised.
+
+   The buffer refers to an internal string buffer of *obj*, not a copy. The data
+   must not be modified in any way, unless the string was just created using
+   ``PyString_FromStringAndSize(NULL, size)``.  It must not be deallocated.  If
+   *string* is a Unicode object, this function computes the default encoding of
+   *string* and operates on that.  If *string* is not a string object at all,
+   :cfunc:`PyString_AsStringAndSize` returns ``-1`` and raises :exc:`TypeError`.
+
+
+.. cfunction:: void PyString_Concat(PyObject **string, PyObject *newpart)
+
+   Create a new string object in *\*string* containing the contents of *newpart*
+   appended to *string*; the caller will own the new reference.  The reference to
+   the old value of *string* will be stolen.  If the new string cannot be created,
+   the old reference to *string* will still be discarded and the value of
+   *\*string* will be set to *NULL*; the appropriate exception will be set.
+
+
+.. cfunction:: void PyString_ConcatAndDel(PyObject **string, PyObject *newpart)
+
+   Create a new string object in *\*string* containing the contents of *newpart*
+   appended to *string*.  This version decrements the reference count of *newpart*.
+
+
+.. cfunction:: 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, *\*string* holds the resized string object and ``0`` is returned;
+   the address in *\*string* may differ from its input value.  If the reallocation
+   fails, the original string object at *\*string* is deallocated, *\*string* is
+   set to *NULL*, a memory exception is set, and ``-1`` is returned.
+
+
+.. cfunction:: PyObject* PyString_Format(PyObject *format, PyObject *args)
+
+   Return a new string object from *format* and *args*. Analogous to ``format %
+   args``.  The *args* argument must be a tuple.
+
+
+.. cfunction:: void PyString_InternInPlace(PyObject **string)
+
+   Intern the argument *\*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 *\*string*, it sets *\*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 *\*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.)
+
+
+.. cfunction:: PyObject* PyString_InternFromString(const char *v)
+
+   A combination of :cfunc:`PyString_FromString` and
+   :cfunc:`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.
+
+
+.. cfunction:: PyObject* PyString_Decode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)
+
+   Create an object by decoding *size* bytes of the encoded buffer *s* using the
+   codec registered for *encoding*.  *encoding* and *errors* have the same meaning
+   as the parameters of the same name in the :func:`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.
+
+
+.. cfunction:: PyObject* PyString_AsDecodedObject(PyObject *str, const char *encoding, const char *errors)
+
+   Decode a string object by passing it to the codec registered for *encoding* and
+   return the result as Python object. *encoding* and *errors* have the same
+   meaning as the parameters of the same name in the string :meth:`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.
+
+
+.. cfunction:: PyObject* PyString_AsEncodedObject(PyObject *str, const char *encoding, const char *errors)
+
+   Encode a string object using the codec registered for *encoding* and return the
+   result as Python object. *encoding* and *errors* have the same meaning as the
+   parameters of the same name in the string :meth:`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.

Added: python/branches/py3k/Doc/c-api/structures.rst
==============================================================================
--- (empty file)
+++ python/branches/py3k/Doc/c-api/structures.rst	Sun Jan 20 10:30:57 2008
@@ -0,0 +1,206 @@
+.. highlightlang:: c
+
+.. _common-structs:
+
+Common Object Structures
+========================
+
+There are a large number of structures which are used in the definition of
+object types for Python.  This section describes these structures and how they
+are used.
+
+All Python objects ultimately share a small number of fields at the beginning of
+the object's representation in memory.  These are represented by the
+:ctype:`PyObject` and :ctype:`PyVarObject` types, which are defined, in turn, by
+the expansions of some macros also used, whether directly or indirectly, in the
+definition of all other Python objects.
+
+
+.. ctype:: PyObject
+
+   All object types are extensions of this type.  This is a type which contains the
+   information Python needs to treat a pointer to an object as an object.  In a
+   normal "release" build, it contains only the objects reference count and a
+   pointer to the corresponding type object.  It corresponds to the fields defined
+   by the expansion of the ``PyObject_HEAD`` macro.
+
+
+.. ctype:: PyVarObject
+
+   This is an extension of :ctype:`PyObject` that adds the :attr:`ob_size` field.
+   This is only used for objects that have some notion of *length*.  This type does
+   not often appear in the Python/C API.  It corresponds to the fields defined by
+   the expansion of the ``PyObject_VAR_HEAD`` macro.
+
+These macros are used in the definition of :ctype:`PyObject` and
+:ctype:`PyVarObject`:
+
+.. XXX need to document PEP 3123 changes here
+
+.. cmacro:: PyObject_HEAD
+
+   This is a macro which expands to the declarations of the fields of the
+   :ctype:`PyObject` type; it is used when declaring new types which represent
+   objects without a varying length.  The specific fields it expands to depend on
+   the definition of :cmacro:`Py_TRACE_REFS`.  By default, that macro is not
+   defined, and :cmacro:`PyObject_HEAD` expands to::
+
+      Py_ssize_t ob_refcnt;
+      PyTypeObject *ob_type;
+
+   When :cmacro:`Py_TRACE_REFS` is defined, it expands to::
+
+      PyObject *_ob_next, *_ob_prev;
+      Py_ssize_t ob_refcnt;
+      PyTypeObject *ob_type;
+
+
+.. cmacro:: PyObject_VAR_HEAD
+
+   This is a macro which expands to the declarations of the fields of the
+   :ctype:`PyVarObject` type; it is used when declaring new types which represent
+   objects with a length that varies from instance to instance.  This macro always
+   expands to::
+
+      PyObject_HEAD
+      Py_ssize_t ob_size;
+
+   Note that :cmacro:`PyObject_HEAD` is part of the expansion, and that its own
+   expansion varies depending on the definition of :cmacro:`Py_TRACE_REFS`.
+
+.. cmacro:: PyObject_HEAD_INIT
+
+
+.. ctype:: PyCFunction
+
+   Type of the functions used to implement most Python callables in C. Functions of
+   this type take two :ctype:`PyObject\*` parameters and return one such value.  If
+   the return value is *NULL*, an exception shall have been set.  If not *NULL*,
+   the return value is interpreted as the return value of the function as exposed
+   in Python.  The function must return a new reference.
+
+
+.. ctype:: PyCFunctionWithKeywords
+
+   Type of the functions used to implement Python callables in C that take
+   keyword arguments: they take three :ctype:`PyObject\*` parameters and return
+   one such value.  See :ctype:`PyCFunction` above for the meaning of the return
+   value.
+
+
+.. ctype:: PyMethodDef
+
+   Structure used to describe a method of an extension type.  This structure has
+   four fields:
+
+   +------------------+-------------+-------------------------------+
+   | Field            | C Type      | Meaning                       |
+   +==================+=============+===============================+
+   | :attr:`ml_name`  | char \*     | name of the method            |
+   +------------------+-------------+-------------------------------+
+   | :attr:`ml_meth`  | PyCFunction | pointer to the C              |
+   |                  |             | implementation                |
+   +------------------+-------------+-------------------------------+
+   | :attr:`ml_flags` | int         | flag bits indicating how the  |
+   |                  |             | call should be constructed    |
+   +------------------+-------------+-------------------------------+
+   | :attr:`ml_doc`   | char \*     | points to the contents of the |
+   |                  |             | docstring                     |
+   +------------------+-------------+-------------------------------+
+
+The :attr:`ml_meth` is a C function pointer.  The functions may be of different
+types, but they always return :ctype:`PyObject\*`.  If the function is not of
+the :ctype:`PyCFunction`, the compiler will require a cast in the method table.
+Even though :ctype:`PyCFunction` defines the first parameter as
+:ctype:`PyObject\*`, it is common that the method implementation uses a the
+specific C type of the *self* object.
+
+The :attr:`ml_flags` field is a bitfield which can include the following flags.
+The individual flags indicate either a calling convention or a binding
+convention.  Of the calling convention flags, only :const:`METH_VARARGS` and
+:const:`METH_KEYWORDS` can be combined (but note that :const:`METH_KEYWORDS`
+alone is equivalent to ``METH_VARARGS | METH_KEYWORDS``). Any of the calling
+convention flags can be combined with a binding flag.
+
+
+.. data:: METH_VARARGS
+
+   This is the typical calling convention, where the methods have the type
+   :ctype:`PyCFunction`. The function expects two :ctype:`PyObject\*` values.  The
+   first one is the *self* object for methods; for module functions, it has the
+   value given to :cfunc:`Py_InitModule4` (or *NULL* if :cfunc:`Py_InitModule` was
+   used).  The second parameter (often called *args*) is a tuple object
+   representing all arguments. This parameter is typically processed using
+   :cfunc:`PyArg_ParseTuple` or :cfunc:`PyArg_UnpackTuple`.
+
+
+.. data:: METH_KEYWORDS
+
+   Methods with these flags must be of type :ctype:`PyCFunctionWithKeywords`.  The
+   function expects three parameters: *self*, *args*, and a dictionary of all the
+   keyword arguments.  The flag is typically combined with :const:`METH_VARARGS`,
+   and the parameters are typically processed using
+   :cfunc:`PyArg_ParseTupleAndKeywords`.
+
+
+.. data:: METH_NOARGS
+
+   Methods without parameters don't need to check whether arguments are given if
+   they are listed with the :const:`METH_NOARGS` flag.  They need to be of type
+   :ctype:`PyCFunction`.  When used with object methods, the first parameter is
+   typically named ``self`` and will hold a reference to the object instance.  In
+   all cases the second parameter will be *NULL*.
+
+
+.. data:: METH_O
+
+   Methods with a single object argument can be listed with the :const:`METH_O`
+   flag, instead of invoking :cfunc:`PyArg_ParseTuple` with a ``"O"`` argument.
+   They have the type :ctype:`PyCFunction`, with the *self* parameter, and a
+   :ctype:`PyObject\*` parameter representing the single argument.
+
+
+These two constants are not used to indicate the calling convention but the
+binding when use with methods of classes.  These may not be used for functions
+defined for modules.  At most one of these flags may be set for any given
+method.
+
+
+.. data:: METH_CLASS
+
+   .. index:: builtin: classmethod
+
+   The method will be passed the type object as the first parameter rather than an
+   instance of the type.  This is used to create *class methods*, similar to what
+   is created when using the :func:`classmethod` built-in function.
+
+
+.. data:: METH_STATIC
+
+   .. index:: builtin: staticmethod
+
+   The method will be passed *NULL* as the first parameter rather than an instance
+   of the type.  This is used to create *static methods*, similar to what is
+   created when using the :func:`staticmethod` built-in function.
+
+One other constant controls whether a method is loaded in place of another
+definition with the same method name.
+
+
+.. data:: METH_COEXIST
+
+   The method will be loaded in place of existing definitions.  Without
+   *METH_COEXIST*, the default is to skip repeated definitions.  Since slot
+   wrappers are loaded before the method table, the existence of a *sq_contains*
+   slot, for example, would generate a wrapped method named :meth:`__contains__`
+   and preclude the loading of a corresponding PyCFunction with the same name.
+   With the flag defined, the PyCFunction will be loaded in place of the wrapper
+   object and will co-exist with the slot.  This is helpful because calls to
+   PyCFunctions are optimized more than wrapper object calls.
+
+
+.. cfunction:: PyObject* Py_FindMethod(PyMethodDef table[], PyObject *ob, char *name)
+
+   Return a bound method object for an extension type implemented in C.  This can
+   be useful in the implementation of a :attr:`tp_getattro` or :attr:`tp_getattr`
+   handler that does not use the :cfunc:`PyObject_GenericGetAttr` function.

Added: python/branches/py3k/Doc/c-api/sys.rst
==============================================================================
--- (empty file)
+++ python/branches/py3k/Doc/c-api/sys.rst	Sun Jan 20 10:30:57 2008
@@ -0,0 +1,158 @@
+.. highlightlang:: c
+
+.. _os:
+
+Operating System Utilities
+==========================
+
+
+.. cfunction:: int Py_FdIsInteractive(FILE *fp, const char *filename)
+
+   Return true (nonzero) if the standard I/O file *fp* with name *filename* is
+   deemed interactive.  This is the case for files for which ``isatty(fileno(fp))``
+   is true.  If the global flag :cdata:`Py_InteractiveFlag` is true, this function
+   also returns true if the *filename* pointer is *NULL* or if the name is equal to
+   one of the strings ``'<stdin>'`` or ``'???'``.
+
+
+.. cfunction:: long PyOS_GetLastModificationTime(char *filename)
+
+   Return the time of last modification of the file *filename*. The result is
+   encoded in the same way as the timestamp returned by the standard C library
+   function :cfunc:`time`.
+
+
+.. cfunction:: void PyOS_AfterFork()
+
+   Function to update some internal state after a process fork; this should be
+   called in the new process if the Python interpreter will continue to be used.
+   If a new executable is loaded into the new process, this function does not need
+   to be called.
+
+
+.. cfunction:: int PyOS_CheckStack()
+
+   Return true when the interpreter runs out of stack space.  This is a reliable
+   check, but is only available when :const:`USE_STACKCHECK` is defined (currently
+   on Windows using the Microsoft Visual C++ compiler).  :const:`USE_STACKCHECK`
+   will be defined automatically; you should never change the definition in your
+   own code.
+
+
+.. cfunction:: PyOS_sighandler_t PyOS_getsig(int i)
+
+   Return the current signal handler for signal *i*.  This is a thin wrapper around
+   either :cfunc:`sigaction` or :cfunc:`signal`.  Do not call those functions
+   directly! :ctype:`PyOS_sighandler_t` is a typedef alias for :ctype:`void
+   (\*)(int)`.
+
+
+.. cfunction:: PyOS_sighandler_t PyOS_setsig(int i, PyOS_sighandler_t h)
+
+   Set the signal handler for signal *i* to be *h*; return the old signal handler.
+   This is a thin wrapper around either :cfunc:`sigaction` or :cfunc:`signal`.  Do
+   not call those functions directly!  :ctype:`PyOS_sighandler_t` is a typedef
+   alias for :ctype:`void (\*)(int)`.
+
+.. _systemfunctions:
+
+System Functions
+================
+
+These are utility functions that make functionality from the :mod:`sys` module
+accessible to C code.  They all work with the current interpreter thread's
+:mod:`sys` module's dict, which is contained in the internal thread state structure.
+
+.. cfunction:: PyObject *PySys_GetObject(char *name)
+
+   Return the object *name* from the :mod:`sys` module or *NULL* if it does
+   not exist, without setting an exception.
+
+.. cfunction:: FILE *PySys_GetFile(char *name, FILE *def)
+
+   Return the :ctype:`FILE*` associated with the object *name* in the
+   :mod:`sys` module, or *def* if *name* is not in the module or is not associated
+   with a :ctype:`FILE*`.
+
+.. cfunction:: int PySys_SetObject(char *name, PyObject *v)
+
+   Set *name* in the :mod:`sys` module to *v* unless *v* is *NULL*, in which
+   case *name* is deleted from the sys module. Returns ``0`` on success, ``-1``
+   on error.
+
+.. cfunction:: void PySys_ResetWarnOptions(void)
+
+   Reset :data:`sys.warnoptions` to an empty list.
+
+.. cfunction:: void PySys_AddWarnOption(char *s)
+
+   Append *s* to :data:`sys.warnoptions`.
+
+.. cfunction:: void PySys_SetPath(char *path)
+
+   Set :data:`sys.path` to a list object of paths found in *path* which should
+   be a list of paths separated with the platform's search path delimiter
+   (``:`` on Unix, ``;`` on Windows).
+
+.. cfunction:: void PySys_WriteStdout(const char *format, ...)
+
+   Write the output string described by *format* to :data:`sys.stdout`.  No
+   exceptions are raised, even if truncation occurs (see below).
+
+   *format* should limit the total size of the formatted output string to
+   1000 bytes or less -- after 1000 bytes, the output string is truncated.
+   In particular, this means that no unrestricted "%s" formats should occur;
+   these should be limited using "%.<N>s" where <N> is a decimal number
+   calculated so that <N> plus the maximum size of other formatted text does not
+   exceed 1000 bytes.  Also watch out for "%f", which can print hundreds of
+   digits for very large numbers.
+
+   If a problem occurs, or :data:`sys.stdout` is unset, the formatted message
+   is written to the real (C level) *stdout*.
+
+.. cfunction:: void PySys_WriteStderr(const char *format, ...)
+
+   As above, but write to :data:`sys.stderr` or *stderr* instead.
+
+
+.. _processcontrol:
+
+Process Control
+===============
+
+
+.. cfunction:: void Py_FatalError(const char *message)
+
+   .. index:: single: abort()
+
+   Print a fatal error message and kill the process.  No cleanup is performed.
+   This function should only be invoked when a condition is detected that would
+   make it dangerous to continue using the Python interpreter; e.g., when the
+   object administration appears to be corrupted.  On Unix, the standard C library
+   function :cfunc:`abort` is called which will attempt to produce a :file:`core`
+   file.
+
+
+.. cfunction:: void Py_Exit(int status)
+
+   .. index::
+      single: Py_Finalize()
+      single: exit()
+
+   Exit the current process.  This calls :cfunc:`Py_Finalize` and then calls the
+   standard C library function ``exit(status)``.
+
+
+.. cfunction:: int Py_AtExit(void (*func) ())
+
+   .. index::
+      single: Py_Finalize()
+      single: cleanup functions
+
+   Register a cleanup function to be called by :cfunc:`Py_Finalize`.  The cleanup
+   function will be called with no arguments and should return no value.  At most
+   32 cleanup functions can be registered.  When the registration is successful,
+   :cfunc:`Py_AtExit` returns ``0``; on failure, it returns ``-1``.  The cleanup
+   function registered last is called first. Each cleanup function will be called
+   at most once.  Since Python's internal finalization will have completed before
+   the cleanup function, no Python APIs should be called by *func*.

Added: python/branches/py3k/Doc/c-api/tuple.rst
==============================================================================
--- (empty file)
+++ python/branches/py3k/Doc/c-api/tuple.rst	Sun Jan 20 10:30:57 2008
@@ -0,0 +1,107 @@
+.. highlightlang:: c
+
+.. _tupleobjects:
+
+Tuple Objects
+-------------
+
+.. index:: object: tuple
+
+
+.. ctype:: PyTupleObject
+
+   This subtype of :ctype:`PyObject` represents a Python tuple object.
+
+
+.. cvar:: PyTypeObject PyTuple_Type
+
+   .. index:: single: TupleType (in module types)
+
+   This instance of :ctype:`PyTypeObject` represents the Python tuple type; it is
+   the same object as ``tuple`` and ``types.TupleType`` in the Python layer..
+
+
+.. cfunction:: int PyTuple_Check(PyObject *p)
+
+   Return true if *p* is a tuple object or an instance of a subtype of the tuple
+   type.
+
+
+.. cfunction:: int PyTuple_CheckExact(PyObject *p)
+
+   Return true if *p* is a tuple object, but not an instance of a subtype of the
+   tuple type.
+
+
+.. cfunction:: PyObject* PyTuple_New(Py_ssize_t len)
+
+   Return a new tuple object of size *len*, or *NULL* on failure.
+
+
+.. cfunction:: PyObject* PyTuple_Pack(Py_ssize_t n, ...)
+
+   Return a new tuple object of size *n*, or *NULL* on failure. The tuple values
+   are initialized to the subsequent *n* C arguments pointing to Python objects.
+   ``PyTuple_Pack(2, a, b)`` is equivalent to ``Py_BuildValue("(OO)", a, b)``.
+
+
+.. cfunction:: Py_ssize_t PyTuple_Size(PyObject *p)
+
+   Take a pointer to a tuple object, and return the size of that tuple.
+
+
+.. cfunction:: Py_ssize_t PyTuple_GET_SIZE(PyObject *p)
+
+   Return the size of the tuple *p*, which must be non-*NULL* and point to a tuple;
+   no error checking is performed.
+
+
+.. cfunction:: PyObject* PyTuple_GetItem(PyObject *p, Py_ssize_t pos)
+
+   Return the object at position *pos* in the tuple pointed to by *p*.  If *pos* is
+   out of bounds, return *NULL* and sets an :exc:`IndexError` exception.
+
+
+.. cfunction:: PyObject* PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos)
+
+   Like :cfunc:`PyTuple_GetItem`, but does no checking of its arguments.
+
+
+.. cfunction:: PyObject* PyTuple_GetSlice(PyObject *p, Py_ssize_t low, Py_ssize_t high)
+
+   Take a slice of the tuple pointed to by *p* from *low* to *high* and return it
+   as a new tuple.
+
+
+.. cfunction:: int PyTuple_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)
+
+   Insert a reference to object *o* at position *pos* of the tuple pointed to by
+   *p*. Return ``0`` on success.
+
+   .. note::
+
+      This function "steals" a reference to *o*.
+
+
+.. cfunction:: void PyTuple_SET_ITEM(PyObject *p, Py_ssize_t pos, PyObject *o)
+
+   Like :cfunc:`PyTuple_SetItem`, but does no error checking, and should *only* be
+   used to fill in brand new tuples.
+
+   .. note::
+
+      This function "steals" a reference to *o*.
+
+
+.. cfunction:: int _PyTuple_Resize(PyObject **p, Py_ssize_t newsize)
+
+   Can be used to resize a tuple.  *newsize* will be the new length of the tuple.
+   Because tuples are *supposed* to be immutable, this should only be used if there
+   is only one reference to the object.  Do *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 ``0`` on success. Client code should never
+   assume that the resulting value of ``*p`` will be the same as before calling
+   this function. If the object referenced by ``*p`` is replaced, the original
+   ``*p`` is destroyed.  On failure, returns ``-1`` and sets ``*p`` to *NULL*, and
+   raises :exc:`MemoryError` or :exc:`SystemError`.

Added: python/branches/py3k/Doc/c-api/type.rst
==============================================================================
--- (empty file)
+++ python/branches/py3k/Doc/c-api/type.rst	Sun Jan 20 10:30:57 2008
@@ -0,0 +1,68 @@
+.. highlightlang:: c
+
+.. _typeobjects:
+
+Type Objects
+------------
+
+.. index:: object: type
+
+
+.. ctype:: PyTypeObject
+
+   The C structure of the objects used to describe built-in types.
+
+
+.. cvar:: PyObject* PyType_Type
+
+   .. index:: single: TypeType (in module types)
+
+   This is the type object for type objects; it is the same object as ``type`` and
+   ``types.TypeType`` in the Python layer.
+
+
+.. cfunction:: int PyType_Check(PyObject *o)
+
+   Return true if the object *o* is a type object, including instances of types
+   derived from the standard type object.  Return false in all other cases.
+
+
+.. cfunction:: int PyType_CheckExact(PyObject *o)
+
+   Return true if the object *o* is a type object, but not a subtype of the
+   standard type object.  Return false in all other cases.
+
+
+.. cfunction:: int PyType_HasFeature(PyObject *o, int feature)
+
+   Return true if the type object *o* sets the feature *feature*.  Type features
+   are denoted by single bit flags.
+
+
+.. cfunction:: int PyType_IS_GC(PyObject *o)
+
+   Return true if the type object includes support for the cycle detector; this
+   tests the type flag :const:`Py_TPFLAGS_HAVE_GC`.
+
+
+.. cfunction:: int PyType_IsSubtype(PyTypeObject *a, PyTypeObject *b)
+
+   Return true if *a* is a subtype of *b*.
+
+
+.. cfunction:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
+
+   XXX: Document.
+
+
+.. cfunction:: PyObject* PyType_GenericNew(PyTypeObject *type, PyObject *args, PyObject *kwds)
+
+   XXX: Document.
+
+
+.. cfunction:: 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 ``0`` on success, or return ``-1`` and sets an
+   exception on error.

Added: python/branches/py3k/Doc/c-api/typeobj.rst
==============================================================================
--- (empty file)
+++ python/branches/py3k/Doc/c-api/typeobj.rst	Sun Jan 20 10:30:57 2008
@@ -0,0 +1,1391 @@
+.. highlightlang:: c
+
+.. _type-structs:
+
+Type Objects
+============
+
+Perhaps one of the most important structures of the Python object system is the
+structure that defines a new type: the :ctype:`PyTypeObject` structure.  Type
+objects can be handled using any of the :cfunc:`PyObject_\*` or
+:cfunc:`PyType_\*` functions, but do not offer much that's interesting to most
+Python applications. These objects are fundamental to how objects behave, so
+they are very important to the interpreter itself and to any extension module
+that implements new types.
+
+Type objects are fairly large compared to most of the standard types. The reason
+for the size is that each type object stores a large number of values, mostly C
+function pointers, each of which implements a small part of the type's
+functionality.  The fields of the type object are examined in detail in this
+section.  The fields will be described in the order in which they occur in the
+structure.
+
+Typedefs: unaryfunc, binaryfunc, ternaryfunc, inquiry, intargfunc,
+intintargfunc, intobjargproc, intintobjargproc, objobjargproc, destructor,
+freefunc, printfunc, getattrfunc, getattrofunc, setattrfunc, setattrofunc,
+cmpfunc, reprfunc, hashfunc
+
+The structure definition for :ctype:`PyTypeObject` can be found in
+:file:`Include/object.h`.  For convenience of reference, this repeats the
+definition found there:
+
+.. literalinclude:: ../includes/typestruct.h
+
+
+The type object structure extends the :ctype:`PyVarObject` structure. The
+:attr:`ob_size` field is used for dynamic types (created by  :func:`type_new`,
+usually called from a class statement). Note that :cdata:`PyType_Type` (the
+metatype) initializes :attr:`tp_itemsize`, which means that its instances (i.e.
+type objects) *must* have the :attr:`ob_size` field.
+
+
+.. cmember:: PyObject* PyObject._ob_next
+             PyObject* PyObject._ob_prev
+
+   These fields are only present when the macro ``Py_TRACE_REFS`` is defined.
+   Their initialization to *NULL* is taken care of by the ``PyObject_HEAD_INIT``
+   macro.  For statically allocated objects, these fields always remain *NULL*.
+   For dynamically allocated objects, these two fields are used to link the object
+   into a doubly-linked list of *all* live objects on the heap.  This could be used
+   for various debugging purposes; currently the only use is to print the objects
+   that are still alive at the end of a run when the environment variable
+   :envvar:`PYTHONDUMPREFS` is set.
+
+   These fields are not inherited by subtypes.
+
+
+.. cmember:: Py_ssize_t PyObject.ob_refcnt
+
+   This is the type object's reference count, initialized to ``1`` by the
+   ``PyObject_HEAD_INIT`` macro.  Note that for statically allocated type objects,
+   the type's instances (objects whose :attr:`ob_type` points back to the type) do
+   *not* count as references.  But for dynamically allocated type objects, the
+   instances *do* count as references.
+
+   This field is not inherited by subtypes.
+
+
+.. cmember:: PyTypeObject* PyObject.ob_type
+
+   This is the type's type, in other words its metatype.  It is initialized by the
+   argument to the ``PyObject_HEAD_INIT`` macro, and its value should normally be
+   ``&PyType_Type``.  However, for dynamically loadable extension modules that must
+   be usable on Windows (at least), the compiler complains that this is not a valid
+   initializer.  Therefore, the convention is to pass *NULL* to the
+   ``PyObject_HEAD_INIT`` macro and to initialize this field explicitly at the
+   start of the module's initialization function, before doing anything else.  This
+   is typically done like this::
+
+      Foo_Type.ob_type = &PyType_Type;
+
+   This should be done before any instances of the type are created.
+   :cfunc:`PyType_Ready` checks if :attr:`ob_type` is *NULL*, and if so,
+   initializes it: in Python 2.2, it is set to ``&PyType_Type``; in Python 2.2.1
+   and later it is initialized to the :attr:`ob_type` field of the base class.
+   :cfunc:`PyType_Ready` will not change this field if it is non-zero.
+
+   In Python 2.2, this field is not inherited by subtypes.  In 2.2.1, and in 2.3
+   and beyond, it is inherited by subtypes.
+
+
+.. cmember:: Py_ssize_t PyVarObject.ob_size
+
+   For statically allocated type objects, this should be initialized to zero.  For
+   dynamically allocated type objects, this field has a special internal meaning.
+
+   This field is not inherited by subtypes.
+
+
+.. cmember:: char* PyTypeObject.tp_name
+
+   Pointer to a NUL-terminated string containing the name of the type. For types
+   that are accessible as module globals, the string should be the full module
+   name, followed by a dot, followed by the type name; for built-in types, it
+   should be just the type name.  If the module is a submodule of a package, the
+   full package name is part of the full module name.  For example, a type named
+   :class:`T` defined in module :mod:`M` in subpackage :mod:`Q` in package :mod:`P`
+   should have the :attr:`tp_name` initializer ``"P.Q.M.T"``.
+
+   For dynamically allocated type objects, this should just be the type name, and
+   the module name explicitly stored in the type dict as the value for key
+   ``'__module__'``.
+
+   For statically allocated type objects, the tp_name field should contain a dot.
+   Everything before the last dot is made accessible as the :attr:`__module__`
+   attribute, and everything after the last dot is made accessible as the
+   :attr:`__name__` attribute.
+
+   If no dot is present, the entire :attr:`tp_name` field is made accessible as the
+   :attr:`__name__` attribute, and the :attr:`__module__` attribute is undefined
+   (unless explicitly set in the dictionary, as explained above).  This means your
+   type will be impossible to pickle.
+
+   This field is not inherited by subtypes.
+
+
+.. cmember:: Py_ssize_t PyTypeObject.tp_basicsize
+             Py_ssize_t PyTypeObject.tp_itemsize
+
+   These fields allow calculating the size in bytes of instances of the type.
+
+   There are two kinds of types: types with fixed-length instances have a zero
+   :attr:`tp_itemsize` field, types with variable-length instances have a non-zero
+   :attr:`tp_itemsize` field.  For a type with fixed-length instances, all
+   instances have the same size, given in :attr:`tp_basicsize`.
+
+   For a type with variable-length instances, the instances must have an
+   :attr:`ob_size` field, and the instance size is :attr:`tp_basicsize` plus N
+   times :attr:`tp_itemsize`, where N is the "length" of the object.  The value of
+   N is typically stored in the instance's :attr:`ob_size` field.  There are
+   exceptions:  for example, long ints use a negative :attr:`ob_size` to indicate a
+   negative number, and N is ``abs(ob_size)`` there.  Also, the presence of an
+   :attr:`ob_size` field in the instance layout doesn't mean that the instance
+   structure is variable-length (for example, the structure for the list type has
+   fixed-length instances, yet those instances have a meaningful :attr:`ob_size`
+   field).
+
+   The basic size includes the fields in the instance declared by the macro
+   :cmacro:`PyObject_HEAD` or :cmacro:`PyObject_VAR_HEAD` (whichever is used to
+   declare the instance struct) and this in turn includes the :attr:`_ob_prev` and
+   :attr:`_ob_next` fields if they are present.  This means that the only correct
+   way to get an initializer for the :attr:`tp_basicsize` is to use the
+   ``sizeof`` operator on the struct used to declare the instance layout.
+   The basic size does not include the GC header size (this is new in Python 2.2;
+   in 2.1 and 2.0, the GC header size was included in :attr:`tp_basicsize`).
+
+   These fields are inherited separately by subtypes.  If the base type has a
+   non-zero :attr:`tp_itemsize`, it is generally not safe to set
+   :attr:`tp_itemsize` to a different non-zero value in a subtype (though this
+   depends on the implementation of the base type).
+
+   A note about alignment: if the variable items require a particular alignment,
+   this should be taken care of by the value of :attr:`tp_basicsize`.  Example:
+   suppose a type implements an array of ``double``. :attr:`tp_itemsize` is
+   ``sizeof(double)``. It is the programmer's responsibility that
+   :attr:`tp_basicsize` is a multiple of ``sizeof(double)`` (assuming this is the
+   alignment requirement for ``double``).
+
+
+.. cmember:: destructor PyTypeObject.tp_dealloc
+
+   A pointer to the instance destructor function.  This function must be defined
+   unless the type guarantees that its instances will never be deallocated (as is
+   the case for the singletons ``None`` and ``Ellipsis``).
+
+   The destructor function is called by the :cfunc:`Py_DECREF` and
+   :cfunc:`Py_XDECREF` macros when the new reference count is zero.  At this point,
+   the instance is still in existence, but there are no references to it.  The
+   destructor function should free all references which the instance owns, free all
+   memory buffers owned by the instance (using the freeing function corresponding
+   to the allocation function used to allocate the buffer), and finally (as its
+   last action) call the type's :attr:`tp_free` function.  If the type is not
+   subtypable (doesn't have the :const:`Py_TPFLAGS_BASETYPE` flag bit set), it is
+   permissible to call the object deallocator directly instead of via
+   :attr:`tp_free`.  The object deallocator should be the one used to allocate the
+   instance; this is normally :cfunc:`PyObject_Del` if the instance was allocated
+   using :cfunc:`PyObject_New` or :cfunc:`PyObject_VarNew`, or
+   :cfunc:`PyObject_GC_Del` if the instance was allocated using
+   :cfunc:`PyObject_GC_New` or :cfunc:`PyObject_GC_VarNew`.
+
+   This field is inherited by subtypes.
+
+
+.. cmember:: printfunc PyTypeObject.tp_print
+
+   An optional pointer to the instance print function.
+
+   The print function is only called when the instance is printed to a *real* file;
+   when it is printed to a pseudo-file (like a :class:`StringIO` instance), the
+   instance's :attr:`tp_repr` or :attr:`tp_str` function is called to convert it to
+   a string.  These are also called when the type's :attr:`tp_print` field is
+   *NULL*.  A type should never implement :attr:`tp_print` in a way that produces
+   different output than :attr:`tp_repr` or :attr:`tp_str` would.
+
+   The print function is called with the same signature as :cfunc:`PyObject_Print`:
+   ``int tp_print(PyObject *self, FILE *file, int flags)``.  The *self* argument is
+   the instance to be printed.  The *file* argument is the stdio file to which it
+   is to be printed.  The *flags* argument is composed of flag bits. The only flag
+   bit currently defined is :const:`Py_PRINT_RAW`. When the :const:`Py_PRINT_RAW`
+   flag bit is set, the instance should be printed the same way as :attr:`tp_str`
+   would format it; when the :const:`Py_PRINT_RAW` flag bit is clear, the instance
+   should be printed the same was as :attr:`tp_repr` would format it. It should
+   return ``-1`` and set an exception condition when an error occurred during the
+   comparison.
+
+   It is possible that the :attr:`tp_print` field will be deprecated. In any case,
+   it is recommended not to define :attr:`tp_print`, but instead to rely on
+   :attr:`tp_repr` and :attr:`tp_str` for printing.
+
+   This field is inherited by subtypes.
+
+
+.. cmember:: getattrfunc PyTypeObject.tp_getattr
+
+   An optional pointer to the get-attribute-string function.
+
+   This field is deprecated.  When it is defined, it should point to a function
+   that acts the same as the :attr:`tp_getattro` function, but taking a C string
+   instead of a Python string object to give the attribute name.  The signature is
+   the same as for :cfunc:`PyObject_GetAttrString`.
+
+   This field is inherited by subtypes together with :attr:`tp_getattro`: a subtype
+   inherits both :attr:`tp_getattr` and :attr:`tp_getattro` from its base type when
+   the subtype's :attr:`tp_getattr` and :attr:`tp_getattro` are both *NULL*.
+
+
+.. cmember:: setattrfunc PyTypeObject.tp_setattr
+
+   An optional pointer to the set-attribute-string function.
+
+   This field is deprecated.  When it is defined, it should point to a function
+   that acts the same as the :attr:`tp_setattro` function, but taking a C string
+   instead of a Python string object to give the attribute name.  The signature is
+   the same as for :cfunc:`PyObject_SetAttrString`.
+
+   This field is inherited by subtypes together with :attr:`tp_setattro`: a subtype
+   inherits both :attr:`tp_setattr` and :attr:`tp_setattro` from its base type when
+   the subtype's :attr:`tp_setattr` and :attr:`tp_setattro` are both *NULL*.
+
+
+.. cmember:: cmpfunc PyTypeObject.tp_compare
+
+   An optional pointer to the three-way comparison function.
+
+   The signature is the same as for :cfunc:`PyObject_Compare`. The function should
+   return ``1`` if *self* greater than *other*, ``0`` if *self* is equal to
+   *other*, and ``-1`` if *self* less than *other*.  It should return ``-1`` and
+   set an exception condition when an error occurred during the comparison.
+
+   This field is inherited by subtypes together with :attr:`tp_richcompare` and
+   :attr:`tp_hash`: a subtypes inherits all three of :attr:`tp_compare`,
+   :attr:`tp_richcompare`, and :attr:`tp_hash` when the subtype's
+   :attr:`tp_compare`, :attr:`tp_richcompare`, and :attr:`tp_hash` are all *NULL*.
+
+
+.. cmember:: reprfunc PyTypeObject.tp_repr
+
+   .. index:: builtin: repr
+
+   An optional pointer to a function that implements the built-in function
+   :func:`repr`.
+
+   The signature is the same as for :cfunc:`PyObject_Repr`; it must return a string
+   or a Unicode object.  Ideally, this function should return a string that, when
+   passed to :func:`eval`, given a suitable environment, returns an object with the
+   same value.  If this is not feasible, it should return a string starting with
+   ``'<'`` and ending with ``'>'`` from which both the type and the value of the
+   object can be deduced.
+
+   When this field is not set, a string of the form ``<%s object at %p>`` is
+   returned, where ``%s`` is replaced by the type name, and ``%p`` by the object's
+   memory address.
+
+   This field is inherited by subtypes.
+
+.. cmember:: PyNumberMethods* tp_as_number
+
+   Pointer to an additional structure that contains fields relevant only to
+   objects which implement the number protocol.  These fields are documented in
+   :ref:`number-structs`.
+
+   The :attr:`tp_as_number` field is not inherited, but the contained fields are
+   inherited individually.
+
+
+.. cmember:: PySequenceMethods* tp_as_sequence
+
+   Pointer to an additional structure that contains fields relevant only to
+   objects which implement the sequence protocol.  These fields are documented
+   in :ref:`sequence-structs`.
+
+   The :attr:`tp_as_sequence` field is not inherited, but the contained fields
+   are inherited individually.
+
+
+.. cmember:: PyMappingMethods* tp_as_mapping
+
+   Pointer to an additional structure that contains fields relevant only to
+   objects which implement the mapping protocol.  These fields are documented in
+   :ref:`mapping-structs`.
+
+   The :attr:`tp_as_mapping` field is not inherited, but the contained fields
+   are inherited individually.
+
+
+.. cmember:: hashfunc PyTypeObject.tp_hash
+
+   .. index:: builtin: hash
+
+   An optional pointer to a function that implements the built-in function
+   :func:`hash`.
+
+   The signature is the same as for :cfunc:`PyObject_Hash`; it must return a C
+   long.  The value ``-1`` should not be returned as a normal return value; when an
+   error occurs during the computation of the hash value, the function should set
+   an exception and return ``-1``.
+
+   When this field is not set, two possibilities exist: if the :attr:`tp_compare`
+   and :attr:`tp_richcompare` fields are both *NULL*, a default hash value based on
+   the object's address is returned; otherwise, a :exc:`TypeError` is raised.
+
+   This field is inherited by subtypes together with :attr:`tp_richcompare` and
+   :attr:`tp_compare`: a subtypes inherits all three of :attr:`tp_compare`,
+   :attr:`tp_richcompare`, and :attr:`tp_hash`, when the subtype's
+   :attr:`tp_compare`, :attr:`tp_richcompare` and :attr:`tp_hash` are all *NULL*.
+
+
+.. cmember:: ternaryfunc PyTypeObject.tp_call
+
+   An optional pointer to a function that implements calling the object.  This
+   should be *NULL* if the object is not callable.  The signature is the same as
+   for :cfunc:`PyObject_Call`.
+
+   This field is inherited by subtypes.
+
+
+.. cmember:: reprfunc PyTypeObject.tp_str
+
+   An optional pointer to a function that implements the built-in operation
+   :func:`str`.  (Note that :class:`str` is a type now, and :func:`str` calls the
+   constructor for that type.  This constructor calls :cfunc:`PyObject_Str` to do
+   the actual work, and :cfunc:`PyObject_Str` will call this handler.)
+
+   The signature is the same as for :cfunc:`PyObject_Str`; it must return a string
+   or a Unicode object.  This function should return a "friendly" string
+   representation of the object, as this is the representation that will be used,
+   among other things, by the :func:`print` function.
+
+   When this field is not set, :cfunc:`PyObject_Repr` is called to return a string
+   representation.
+
+   This field is inherited by subtypes.
+
+
+.. cmember:: getattrofunc PyTypeObject.tp_getattro
+
+   An optional pointer to the get-attribute function.
+
+   The signature is the same as for :cfunc:`PyObject_GetAttr`.  It is usually
+   convenient to set this field to :cfunc:`PyObject_GenericGetAttr`, which
+   implements the normal way of looking for object attributes.
+
+   This field is inherited by subtypes together with :attr:`tp_getattr`: a subtype
+   inherits both :attr:`tp_getattr` and :attr:`tp_getattro` from its base type when
+   the subtype's :attr:`tp_getattr` and :attr:`tp_getattro` are both *NULL*.
+
+
+.. cmember:: setattrofunc PyTypeObject.tp_setattro
+
+   An optional pointer to the set-attribute function.
+
+   The signature is the same as for :cfunc:`PyObject_SetAttr`.  It is usually
+   convenient to set this field to :cfunc:`PyObject_GenericSetAttr`, which
+   implements the normal way of setting object attributes.
+
+   This field is inherited by subtypes together with :attr:`tp_setattr`: a subtype
+   inherits both :attr:`tp_setattr` and :attr:`tp_setattro` from its base type when
+   the subtype's :attr:`tp_setattr` and :attr:`tp_setattro` are both *NULL*.
+
+
+.. cmember:: PyBufferProcs* PyTypeObject.tp_as_buffer
+
+   Pointer to an additional structure that contains fields relevant only to objects
+   which implement the buffer interface.  These fields are documented in
+   :ref:`buffer-structs`.
+
+   The :attr:`tp_as_buffer` field is not inherited, but the contained fields are
+   inherited individually.
+
+
+.. cmember:: long PyTypeObject.tp_flags
+
+   This field is a bit mask of various flags.  Some flags indicate variant
+   semantics for certain situations; others are used to indicate that certain
+   fields in the type object (or in the extension structures referenced via
+   :attr:`tp_as_number`, :attr:`tp_as_sequence`, :attr:`tp_as_mapping`, and
+   :attr:`tp_as_buffer`) that were historically not always present are valid; if
+   such a flag bit is clear, the type fields it guards must not be accessed and
+   must be considered to have a zero or *NULL* value instead.
+
+   Inheritance of this field is complicated.  Most flag bits are inherited
+   individually, i.e. if the base type has a flag bit set, the subtype inherits
+   this flag bit.  The flag bits that pertain to extension structures are strictly
+   inherited if the extension structure is inherited, i.e. the base type's value of
+   the flag bit is copied into the subtype together with a pointer to the extension
+   structure.  The :const:`Py_TPFLAGS_HAVE_GC` flag bit is inherited together with
+   the :attr:`tp_traverse` and :attr:`tp_clear` fields, i.e. if the
+   :const:`Py_TPFLAGS_HAVE_GC` flag bit is clear in the subtype and the
+   :attr:`tp_traverse` and :attr:`tp_clear` fields in the subtype exist (as
+   indicated by the :const:`Py_TPFLAGS_HAVE_RICHCOMPARE` flag bit) and have *NULL*
+   values.
+
+   The following bit masks are currently defined; these can be ORed together using
+   the ``|`` operator to form the value of the :attr:`tp_flags` field.  The macro
+   :cfunc:`PyType_HasFeature` takes a type and a flags value, *tp* and *f*, and
+   checks whether ``tp->tp_flags & f`` is non-zero.
+
+
+   .. data:: Py_TPFLAGS_HAVE_GETCHARBUFFER
+
+      If this bit is set, the :ctype:`PyBufferProcs` struct referenced by
+      :attr:`tp_as_buffer` has the :attr:`bf_getcharbuffer` field.
+
+
+   .. data:: Py_TPFLAGS_HAVE_SEQUENCE_IN
+
+      If this bit is set, the :ctype:`PySequenceMethods` struct referenced by
+      :attr:`tp_as_sequence` has the :attr:`sq_contains` field.
+
+
+   .. data:: Py_TPFLAGS_GC
+
+      This bit is obsolete.  The bit it used to name is no longer in use.  The symbol
+      is now defined as zero.
+
+
+   .. data:: Py_TPFLAGS_HAVE_INPLACEOPS
+
+      If this bit is set, the :ctype:`PySequenceMethods` struct referenced by
+      :attr:`tp_as_sequence` and the :ctype:`PyNumberMethods` structure referenced by
+      :attr:`tp_as_number` contain the fields for in-place operators. In particular,
+      this means that the :ctype:`PyNumberMethods` structure has the fields
+      :attr:`nb_inplace_add`, :attr:`nb_inplace_subtract`,
+      :attr:`nb_inplace_multiply`, :attr:`nb_inplace_divide`,
+      :attr:`nb_inplace_remainder`, :attr:`nb_inplace_power`,
+      :attr:`nb_inplace_lshift`, :attr:`nb_inplace_rshift`, :attr:`nb_inplace_and`,
+      :attr:`nb_inplace_xor`, and :attr:`nb_inplace_or`; and the
+      :ctype:`PySequenceMethods` struct has the fields :attr:`sq_inplace_concat` and
+      :attr:`sq_inplace_repeat`.
+
+
+   .. data:: Py_TPFLAGS_HAVE_RICHCOMPARE
+
+      If this bit is set, the type object has the :attr:`tp_richcompare` field, as
+      well as the :attr:`tp_traverse` and the :attr:`tp_clear` fields.
+
+
+   .. data:: Py_TPFLAGS_HAVE_WEAKREFS
+
+      If this bit is set, the :attr:`tp_weaklistoffset` field is defined.  Instances
+      of a type are weakly referenceable if the type's :attr:`tp_weaklistoffset` field
+      has a value greater than zero.
+
+
+   .. data:: Py_TPFLAGS_HAVE_ITER
+
+      If this bit is set, the type object has the :attr:`tp_iter` and
+      :attr:`tp_iternext` fields.
+
+
+   .. data:: Py_TPFLAGS_HAVE_CLASS
+
+      If this bit is set, the type object has several new fields defined starting in
+      Python 2.2: :attr:`tp_methods`, :attr:`tp_members`, :attr:`tp_getset`,
+      :attr:`tp_base`, :attr:`tp_dict`, :attr:`tp_descr_get`, :attr:`tp_descr_set`,
+      :attr:`tp_dictoffset`, :attr:`tp_init`, :attr:`tp_alloc`, :attr:`tp_new`,
+      :attr:`tp_free`, :attr:`tp_is_gc`, :attr:`tp_bases`, :attr:`tp_mro`,
+      :attr:`tp_cache`, :attr:`tp_subclasses`, and :attr:`tp_weaklist`.
+
+
+   .. data:: Py_TPFLAGS_HEAPTYPE
+
+      This bit is set when the type object itself is allocated on the heap.  In this
+      case, the :attr:`ob_type` field of its instances is considered a reference to
+      the type, and the type object is INCREF'ed when a new instance is created, and
+      DECREF'ed when an instance is destroyed (this does not apply to instances of
+      subtypes; only the type referenced by the instance's ob_type gets INCREF'ed or
+      DECREF'ed).
+
+
+   .. data:: Py_TPFLAGS_BASETYPE
+
+      This bit is set when the type can be used as the base type of another type.  If
+      this bit is clear, the type cannot be subtyped (similar to a "final" class in
+      Java).
+
+
+   .. data:: Py_TPFLAGS_READY
+
+      This bit is set when the type object has been fully initialized by
+      :cfunc:`PyType_Ready`.
+
+
+   .. data:: Py_TPFLAGS_READYING
+
+      This bit is set while :cfunc:`PyType_Ready` is in the process of initializing
+      the type object.
+
+
+   .. data:: Py_TPFLAGS_HAVE_GC
+
+      This bit is set when the object supports garbage collection.  If this bit
+      is set, instances must be created using :cfunc:`PyObject_GC_New` and
+      destroyed using :cfunc:`PyObject_GC_Del`.  More information in section
+      :ref:`supporting-cycle-detection`.  This bit also implies that the
+      GC-related fields :attr:`tp_traverse` and :attr:`tp_clear` are present in
+      the type object; but those fields also exist when
+      :const:`Py_TPFLAGS_HAVE_GC` is clear but
+      :const:`Py_TPFLAGS_HAVE_RICHCOMPARE` is set.
+
+
+   .. data:: Py_TPFLAGS_DEFAULT
+
+      This is a bitmask of all the bits that pertain to the existence of certain
+      fields in the type object and its extension structures. Currently, it includes
+      the following bits: :const:`Py_TPFLAGS_HAVE_GETCHARBUFFER`,
+      :const:`Py_TPFLAGS_HAVE_SEQUENCE_IN`, :const:`Py_TPFLAGS_HAVE_INPLACEOPS`,
+      :const:`Py_TPFLAGS_HAVE_RICHCOMPARE`, :const:`Py_TPFLAGS_HAVE_WEAKREFS`,
+      :const:`Py_TPFLAGS_HAVE_ITER`, and :const:`Py_TPFLAGS_HAVE_CLASS`.
+
+
+.. cmember:: char* PyTypeObject.tp_doc
+
+   An optional pointer to a NUL-terminated C string giving the docstring for this
+   type object.  This is exposed as the :attr:`__doc__` attribute on the type and
+   instances of the type.
+
+   This field is *not* inherited by subtypes.
+
+The following three fields only exist if the
+:const:`Py_TPFLAGS_HAVE_RICHCOMPARE` flag bit is set.
+
+
+.. cmember:: traverseproc PyTypeObject.tp_traverse
+
+   An optional pointer to a traversal function for the garbage collector.  This is
+   only used if the :const:`Py_TPFLAGS_HAVE_GC` flag bit is set.  More information
+   about Python's garbage collection scheme can be found in section
+   :ref:`supporting-cycle-detection`.
+
+   The :attr:`tp_traverse` pointer is used by the garbage collector to detect
+   reference cycles. A typical implementation of a :attr:`tp_traverse` function
+   simply calls :cfunc:`Py_VISIT` on each of the instance's members that are Python
+   objects.  For exampe, this is function :cfunc:`local_traverse` from the
+   :mod:`thread` extension module::
+
+      static int
+      local_traverse(localobject *self, visitproc visit, void *arg)
+      {
+          Py_VISIT(self->args);
+          Py_VISIT(self->kw);
+          Py_VISIT(self->dict);
+          return 0;
+      }
+
+   Note that :cfunc:`Py_VISIT` is called only on those members that can participate
+   in reference cycles.  Although there is also a ``self->key`` member, it can only
+   be *NULL* or a Python string and therefore cannot be part of a reference cycle.
+
+   On the other hand, even if you know a member can never be part of a cycle, as a
+   debugging aid you may want to visit it anyway just so the :mod:`gc` module's
+   :func:`get_referents` function will include it.
+
+   Note that :cfunc:`Py_VISIT` requires the *visit* and *arg* parameters to
+   :cfunc:`local_traverse` to have these specific names; don't name them just
+   anything.
+
+   This field is inherited by subtypes together with :attr:`tp_clear` and the
+   :const:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :attr:`tp_traverse`, and
+   :attr:`tp_clear` are all inherited from the base type if they are all zero in
+   the subtype *and* the subtype has the :const:`Py_TPFLAGS_HAVE_RICHCOMPARE` flag
+   bit set.
+
+
+.. cmember:: inquiry PyTypeObject.tp_clear
+
+   An optional pointer to a clear function for the garbage collector. This is only
+   used if the :const:`Py_TPFLAGS_HAVE_GC` flag bit is set.
+
+   The :attr:`tp_clear` member function is used to break reference cycles in cyclic
+   garbage detected by the garbage collector.  Taken together, all :attr:`tp_clear`
+   functions in the system must combine to break all reference cycles.  This is
+   subtle, and if in any doubt supply a :attr:`tp_clear` function.  For example,
+   the tuple type does not implement a :attr:`tp_clear` function, because it's
+   possible to prove that no reference cycle can be composed entirely of tuples.
+   Therefore the :attr:`tp_clear` functions of other types must be sufficient to
+   break any cycle containing a tuple.  This isn't immediately obvious, and there's
+   rarely a good reason to avoid implementing :attr:`tp_clear`.
+
+   Implementations of :attr:`tp_clear` should drop the instance's references to
+   those of its members that may be Python objects, and set its pointers to those
+   members to *NULL*, as in the following example::
+
+      static int
+      local_clear(localobject *self)
+      {
+          Py_CLEAR(self->key);
+          Py_CLEAR(self->args);
+          Py_CLEAR(self->kw);
+          Py_CLEAR(self->dict);
+          return 0;
+      }
+
+   The :cfunc:`Py_CLEAR` macro should be used, because clearing references is
+   delicate:  the reference to the contained object must not be decremented until
+   after the pointer to the contained object is set to *NULL*.  This is because
+   decrementing the reference count may cause the contained object to become trash,
+   triggering a chain of reclamation activity that may include invoking arbitrary
+   Python code (due to finalizers, or weakref callbacks, associated with the
+   contained object). If it's possible for such code to reference *self* again,
+   it's important that the pointer to the contained object be *NULL* at that time,
+   so that *self* knows the contained object can no longer be used.  The
+   :cfunc:`Py_CLEAR` macro performs the operations in a safe order.
+
+   Because the goal of :attr:`tp_clear` functions is to break reference cycles,
+   it's not necessary to clear contained objects like Python strings or Python
+   integers, which can't participate in reference cycles. On the other hand, it may
+   be convenient to clear all contained Python objects, and write the type's
+   :attr:`tp_dealloc` function to invoke :attr:`tp_clear`.
+
+   More information about Python's garbage collection scheme can be found in
+   section :ref:`supporting-cycle-detection`.
+
+   This field is inherited by subtypes together with :attr:`tp_traverse` and the
+   :const:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :attr:`tp_traverse`, and
+   :attr:`tp_clear` are all inherited from the base type if they are all zero in
+   the subtype *and* the subtype has the :const:`Py_TPFLAGS_HAVE_RICHCOMPARE` flag
+   bit set.
+
+
+.. cmember:: richcmpfunc PyTypeObject.tp_richcompare
+
+   An optional pointer to the rich comparison function.
+
+   The signature is the same as for :cfunc:`PyObject_RichCompare`. The function
+   should return the result of the comparison (usually ``Py_True`` or
+   ``Py_False``).  If the comparison is undefined, it must return
+   ``Py_NotImplemented``, if another error occurred it must return ``NULL`` and set
+   an exception condition.
+
+   This field is inherited by subtypes together with :attr:`tp_compare` and
+   :attr:`tp_hash`: a subtype inherits all three of :attr:`tp_compare`,
+   :attr:`tp_richcompare`, and :attr:`tp_hash`, when the subtype's
+   :attr:`tp_compare`, :attr:`tp_richcompare`, and :attr:`tp_hash` are all *NULL*.
+
+   The following constants are defined to be used as the third argument for
+   :attr:`tp_richcompare` and for :cfunc:`PyObject_RichCompare`:
+
+   +----------------+------------+
+   | Constant       | Comparison |
+   +================+============+
+   | :const:`Py_LT` | ``<``      |
+   +----------------+------------+
+   | :const:`Py_LE` | ``<=``     |
+   +----------------+------------+
+   | :const:`Py_EQ` | ``==``     |
+   +----------------+------------+
+   | :const:`Py_NE` | ``!=``     |
+   +----------------+------------+
+   | :const:`Py_GT` | ``>``      |
+   +----------------+------------+
+   | :const:`Py_GE` | ``>=``     |
+   +----------------+------------+
+
+The next field only exists if the :const:`Py_TPFLAGS_HAVE_WEAKREFS` flag bit is
+set.
+
+
+.. cmember:: long PyTypeObject.tp_weaklistoffset
+
+   If the instances of this type are weakly referenceable, this field is greater
+   than zero and contains the offset in the instance structure of the weak
+   reference list head (ignoring the GC header, if present); this offset is used by
+   :cfunc:`PyObject_ClearWeakRefs` and the :cfunc:`PyWeakref_\*` functions.  The
+   instance structure needs to include a field of type :ctype:`PyObject\*` which is
+   initialized to *NULL*.
+
+   Do not confuse this field with :attr:`tp_weaklist`; that is the list head for
+   weak references to the type object itself.
+
+   This field is inherited by subtypes, but see the rules listed below. A subtype
+   may override this offset; this means that the subtype uses a different weak
+   reference list head than the base type.  Since the list head is always found via
+   :attr:`tp_weaklistoffset`, this should not be a problem.
+
+   When a type defined by a class statement has no :attr:`__slots__` declaration,
+   and none of its base types are weakly referenceable, the type is made weakly
+   referenceable by adding a weak reference list head slot to the instance layout
+   and setting the :attr:`tp_weaklistoffset` of that slot's offset.
+
+   When a type's :attr:`__slots__` declaration contains a slot named
+   :attr:`__weakref__`, that slot becomes the weak reference list head for
+   instances of the type, and the slot's offset is stored in the type's
+   :attr:`tp_weaklistoffset`.
+
+   When a type's :attr:`__slots__` declaration does not contain a slot named
+   :attr:`__weakref__`, the type inherits its :attr:`tp_weaklistoffset` from its
+   base type.
+
+The next two fields only exist if the :const:`Py_TPFLAGS_HAVE_CLASS` flag bit is
+set.
+
+
+.. cmember:: getiterfunc PyTypeObject.tp_iter
+
+   An optional pointer to a function that returns an iterator for the object.  Its
+   presence normally signals that the instances of this type are iterable (although
+   sequences may be iterable without this function, and classic instances always
+   have this function, even if they don't define an :meth:`__iter__` method).
+
+   This function has the same signature as :cfunc:`PyObject_GetIter`.
+
+   This field is inherited by subtypes.
+
+
+.. cmember:: iternextfunc PyTypeObject.tp_iternext
+
+   An optional pointer to a function that returns the next item in an iterator, or
+   raises :exc:`StopIteration` when the iterator is exhausted.  Its presence
+   normally signals that the instances of this type are iterators (although classic
+   instances always have this function, even if they don't define a
+   :meth:`__next__` method).
+
+   Iterator types should also define the :attr:`tp_iter` function, and that
+   function should return the iterator instance itself (not a new iterator
+   instance).
+
+   This function has the same signature as :cfunc:`PyIter_Next`.
+
+   This field is inherited by subtypes.
+
+The next fields, up to and including :attr:`tp_weaklist`, only exist if the
+:const:`Py_TPFLAGS_HAVE_CLASS` flag bit is set.
+
+
+.. cmember:: struct PyMethodDef* PyTypeObject.tp_methods
+
+   An optional pointer to a static *NULL*-terminated array of :ctype:`PyMethodDef`
+   structures, declaring regular methods of this type.
+
+   For each entry in the array, an entry is added to the type's dictionary (see
+   :attr:`tp_dict` below) containing a method descriptor.
+
+   This field is not inherited by subtypes (methods are inherited through a
+   different mechanism).
+
+
+.. cmember:: struct PyMemberDef* PyTypeObject.tp_members
+
+   An optional pointer to a static *NULL*-terminated array of :ctype:`PyMemberDef`
+   structures, declaring regular data members (fields or slots) of instances of
+   this type.
+
+   For each entry in the array, an entry is added to the type's dictionary (see
+   :attr:`tp_dict` below) containing a member descriptor.
+
+   This field is not inherited by subtypes (members are inherited through a
+   different mechanism).
+
+
+.. cmember:: struct PyGetSetDef* PyTypeObject.tp_getset
+
+   An optional pointer to a static *NULL*-terminated array of :ctype:`PyGetSetDef`
+   structures, declaring computed attributes of instances of this type.
+
+   For each entry in the array, an entry is added to the type's dictionary (see
+   :attr:`tp_dict` below) containing a getset descriptor.
+
+   This field is not inherited by subtypes (computed attributes are inherited
+   through a different mechanism).
+
+   Docs for PyGetSetDef (XXX belong elsewhere)::
+
+      typedef PyObject *(*getter)(PyObject *, void *);
+      typedef int (*setter)(PyObject *, PyObject *, void *);
+
+      typedef struct PyGetSetDef {
+          char *name;    /* attribute name */
+          getter get;    /* C function to get the attribute */
+          setter set;    /* C function to set the attribute */
+          char *doc;     /* optional doc string */
+          void *closure; /* optional additional data for getter and setter */
+      } PyGetSetDef;
+
+
+.. cmember:: PyTypeObject* PyTypeObject.tp_base
+
+   An optional pointer to a base type from which type properties are inherited.  At
+   this level, only single inheritance is supported; multiple inheritance require
+   dynamically creating a type object by calling the metatype.
+
+   This field is not inherited by subtypes (obviously), but it defaults to
+   ``&PyBaseObject_Type`` (which to Python programmers is known as the type
+   :class:`object`).
+
+
+.. cmember:: PyObject* PyTypeObject.tp_dict
+
+   The type's dictionary is stored here by :cfunc:`PyType_Ready`.
+
+   This field should normally be initialized to *NULL* before PyType_Ready is
+   called; it may also be initialized to a dictionary containing initial attributes
+   for the type.  Once :cfunc:`PyType_Ready` has initialized the type, extra
+   attributes for the type may be added to this dictionary only if they don't
+   correspond to overloaded operations (like :meth:`__add__`).
+
+   This field is not inherited by subtypes (though the attributes defined in here
+   are inherited through a different mechanism).
+
+
+.. cmember:: descrgetfunc PyTypeObject.tp_descr_get
+
+   An optional pointer to a "descriptor get" function.
+
+   The function signature is ::
+
+      PyObject * tp_descr_get(PyObject *self, PyObject *obj, PyObject *type);
+
+   XXX explain.
+
+   This field is inherited by subtypes.
+
+
+.. cmember:: descrsetfunc PyTypeObject.tp_descr_set
+
+   An optional pointer to a "descriptor set" function.
+
+   The function signature is ::
+
+      int tp_descr_set(PyObject *self, PyObject *obj, PyObject *value);
+
+   This field is inherited by subtypes.
+
+   XXX explain.
+
+
+.. cmember:: long PyTypeObject.tp_dictoffset
+
+   If the instances of this type have a dictionary containing instance variables,
+   this field is non-zero and contains the offset in the instances of the type of
+   the instance variable dictionary; this offset is used by
+   :cfunc:`PyObject_GenericGetAttr`.
+
+   Do not confuse this field with :attr:`tp_dict`; that is the dictionary for
+   attributes of the type object itself.
+
+   If the value of this field is greater than zero, it specifies the offset from
+   the start of the instance structure.  If the value is less than zero, it
+   specifies the offset from the *end* of the instance structure.  A negative
+   offset is more expensive to use, and should only be used when the instance
+   structure contains a variable-length part.  This is used for example to add an
+   instance variable dictionary to subtypes of :class:`str` or :class:`tuple`. Note
+   that the :attr:`tp_basicsize` field should account for the dictionary added to
+   the end in that case, even though the dictionary is not included in the basic
+   object layout.  On a system with a pointer size of 4 bytes,
+   :attr:`tp_dictoffset` should be set to ``-4`` to indicate that the dictionary is
+   at the very end of the structure.
+
+   The real dictionary offset in an instance can be computed from a negative
+   :attr:`tp_dictoffset` as follows::
+
+      dictoffset = tp_basicsize + abs(ob_size)*tp_itemsize + tp_dictoffset
+      if dictoffset is not aligned on sizeof(void*):
+          round up to sizeof(void*)
+
+   where :attr:`tp_basicsize`, :attr:`tp_itemsize` and :attr:`tp_dictoffset` are
+   taken from the type object, and :attr:`ob_size` is taken from the instance.  The
+   absolute value is taken because long ints use the sign of :attr:`ob_size` to
+   store the sign of the number.  (There's never a need to do this calculation
+   yourself; it is done for you by :cfunc:`_PyObject_GetDictPtr`.)
+
+   This field is inherited by subtypes, but see the rules listed below. A subtype
+   may override this offset; this means that the subtype instances store the
+   dictionary at a difference offset than the base type.  Since the dictionary is
+   always found via :attr:`tp_dictoffset`, this should not be a problem.
+
+   When a type defined by a class statement has no :attr:`__slots__` declaration,
+   and none of its base types has an instance variable dictionary, a dictionary
+   slot is added to the instance layout and the :attr:`tp_dictoffset` is set to
+   that slot's offset.
+
+   When a type defined by a class statement has a :attr:`__slots__` declaration,
+   the type inherits its :attr:`tp_dictoffset` from its base type.
+
+   (Adding a slot named :attr:`__dict__` to the :attr:`__slots__` declaration does
+   not have the expected effect, it just causes confusion.  Maybe this should be
+   added as a feature just like :attr:`__weakref__` though.)
+
+
+.. cmember:: initproc PyTypeObject.tp_init
+
+   An optional pointer to an instance initialization function.
+
+   This function corresponds to the :meth:`__init__` method of classes.  Like
+   :meth:`__init__`, it is possible to create an instance without calling
+   :meth:`__init__`, and it is possible to reinitialize an instance by calling its
+   :meth:`__init__` method again.
+
+   The function signature is ::
+
+      int tp_init(PyObject *self, PyObject *args, PyObject *kwds)
+
+   The self argument is the instance to be initialized; the *args* and *kwds*
+   arguments represent positional and keyword arguments of the call to
+   :meth:`__init__`.
+
+   The :attr:`tp_init` function, if not *NULL*, is called when an instance is
+   created normally by calling its type, after the type's :attr:`tp_new` function
+   has returned an instance of the type.  If the :attr:`tp_new` function returns an
+   instance of some other type that is not a subtype of the original type, no
+   :attr:`tp_init` function is called; if :attr:`tp_new` returns an instance of a
+   subtype of the original type, the subtype's :attr:`tp_init` is called.  (VERSION
+   NOTE: described here is what is implemented in Python 2.2.1 and later.  In
+   Python 2.2, the :attr:`tp_init` of the type of the object returned by
+   :attr:`tp_new` was always called, if not *NULL*.)
+
+   This field is inherited by subtypes.
+
+
+.. cmember:: allocfunc PyTypeObject.tp_alloc
+
+   An optional pointer to an instance allocation function.
+
+   The function signature is ::
+
+      PyObject *tp_alloc(PyTypeObject *self, Py_ssize_t nitems)
+
+   The purpose of this function is to separate memory allocation from memory
+   initialization.  It should return a pointer to a block of memory of adequate
+   length for the instance, suitably aligned, and initialized to zeros, but with
+   :attr:`ob_refcnt` set to ``1`` and :attr:`ob_type` set to the type argument.  If
+   the type's :attr:`tp_itemsize` is non-zero, the object's :attr:`ob_size` field
+   should be initialized to *nitems* and the length of the allocated memory block
+   should be ``tp_basicsize + nitems*tp_itemsize``, rounded up to a multiple of
+   ``sizeof(void*)``; otherwise, *nitems* is not used and the length of the block
+   should be :attr:`tp_basicsize`.
+
+   Do not use this function to do any other instance initialization, not even to
+   allocate additional memory; that should be done by :attr:`tp_new`.
+
+   This field is inherited by static subtypes, but not by dynamic subtypes
+   (subtypes created by a class statement); in the latter, this field is always set
+   to :cfunc:`PyType_GenericAlloc`, to force a standard heap allocation strategy.
+   That is also the recommended value for statically defined types.
+
+
+.. cmember:: newfunc PyTypeObject.tp_new
+
+   An optional pointer to an instance creation function.
+
+   If this function is *NULL* for a particular type, that type cannot be called to
+   create new instances; presumably there is some other way to create instances,
+   like a factory function.
+
+   The function signature is ::
+
+      PyObject *tp_new(PyTypeObject *subtype, PyObject *args, PyObject *kwds)
+
+   The subtype argument is the type of the object being created; the *args* and
+   *kwds* arguments represent positional and keyword arguments of the call to the
+   type.  Note that subtype doesn't have to equal the type whose :attr:`tp_new`
+   function is called; it may be a subtype of that type (but not an unrelated
+   type).
+
+   The :attr:`tp_new` function should call ``subtype->tp_alloc(subtype, nitems)``
+   to allocate space for the object, and then do only as much further
+   initialization as is absolutely necessary.  Initialization that can safely be
+   ignored or repeated should be placed in the :attr:`tp_init` handler.  A good
+   rule of thumb is that for immutable types, all initialization should take place
+   in :attr:`tp_new`, while for mutable types, most initialization should be
+   deferred to :attr:`tp_init`.
+
+   This field is inherited by subtypes, except it is not inherited by static types
+   whose :attr:`tp_base` is *NULL* or ``&PyBaseObject_Type``.  The latter exception
+   is a precaution so that old extension types don't become callable simply by
+   being linked with Python 2.2.
+
+
+.. cmember:: destructor PyTypeObject.tp_free
+
+   An optional pointer to an instance deallocation function.
+
+   The signature of this function has changed slightly: in Python 2.2 and 2.2.1,
+   its signature is :ctype:`destructor`::
+
+      void tp_free(PyObject *)
+
+   In Python 2.3 and beyond, its signature is :ctype:`freefunc`::
+
+      void tp_free(void *)
+
+   The only initializer that is compatible with both versions is ``PyObject_Free``,
+   whose definition has suitably adapted in Python 2.3.
+
+   This field is inherited by static subtypes, but not by dynamic subtypes
+   (subtypes created by a class statement); in the latter, this field is set to a
+   deallocator suitable to match :cfunc:`PyType_GenericAlloc` and the value of the
+   :const:`Py_TPFLAGS_HAVE_GC` flag bit.
+
+
+.. cmember:: inquiry PyTypeObject.tp_is_gc
+
+   An optional pointer to a function called by the garbage collector.
+
+   The garbage collector needs to know whether a particular object is collectible
+   or not.  Normally, it is sufficient to look at the object's type's
+   :attr:`tp_flags` field, and check the :const:`Py_TPFLAGS_HAVE_GC` flag bit.  But
+   some types have a mixture of statically and dynamically allocated instances, and
+   the statically allocated instances are not collectible.  Such types should
+   define this function; it should return ``1`` for a collectible instance, and
+   ``0`` for a non-collectible instance. The signature is ::
+
+      int tp_is_gc(PyObject *self)
+
+   (The only example of this are types themselves.  The metatype,
+   :cdata:`PyType_Type`, defines this function to distinguish between statically
+   and dynamically allocated types.)
+
+   This field is inherited by subtypes.  (VERSION NOTE: in Python 2.2, it was not
+   inherited.  It is inherited in 2.2.1 and later versions.)
+
+
+.. cmember:: PyObject* PyTypeObject.tp_bases
+
+   Tuple of base types.
+
+   This is set for types created by a class statement.  It should be *NULL* for
+   statically defined types.
+
+   This field is not inherited.
+
+
+.. cmember:: PyObject* PyTypeObject.tp_mro
+
+   Tuple containing the expanded set of base types, starting with the type itself
+   and ending with :class:`object`, in Method Resolution Order.
+
+   This field is not inherited; it is calculated fresh by :cfunc:`PyType_Ready`.
+
+
+.. cmember:: PyObject* PyTypeObject.tp_cache
+
+   Unused.  Not inherited.  Internal use only.
+
+
+.. cmember:: PyObject* PyTypeObject.tp_subclasses
+
+   List of weak references to subclasses.  Not inherited.  Internal use only.
+
+
+.. cmember:: PyObject* PyTypeObject.tp_weaklist
+
+   Weak reference list head, for weak references to this type object.  Not
+   inherited.  Internal use only.
+
+The remaining fields are only defined if the feature test macro
+:const:`COUNT_ALLOCS` is defined, and are for internal use only. They are
+documented here for completeness.  None of these fields are inherited by
+subtypes.
+
+
+.. cmember:: Py_ssize_t PyTypeObject.tp_allocs
+
+   Number of allocations.
+
+
+.. cmember:: Py_ssize_t PyTypeObject.tp_frees
+
+   Number of frees.
+
+
+.. cmember:: Py_ssize_t PyTypeObject.tp_maxalloc
+
+   Maximum simultaneously allocated objects.
+
+
+.. cmember:: PyTypeObject* PyTypeObject.tp_next
+
+   Pointer to the next type object with a non-zero :attr:`tp_allocs` field.
+
+Also, note that, in a garbage collected Python, tp_dealloc may be called from
+any Python thread, not just the thread which created the object (if the object
+becomes part of a refcount cycle, that cycle might be collected by a garbage
+collection on any thread).  This is not a problem for Python API calls, since
+the thread on which tp_dealloc is called will own the Global Interpreter Lock
+(GIL). However, if the object being destroyed in turn destroys objects from some
+other C or C++ library, care should be taken to ensure that destroying those
+objects on the thread which called tp_dealloc will not violate any assumptions
+of the library.
+
+
+.. _number-structs:
+
+Number Object Structures
+========================
+
+.. sectionauthor:: Amaury Forgeot d'Arc
+
+
+.. ctype:: PyNumberMethods
+
+   This structure holds pointers to the functions which an object uses to
+   implement the number protocol.  Each function is used by the function of
+   similar name documented in the :ref:`number` section.
+
+   Here is the structure definition::
+
+       typedef struct {
+            binaryfunc nb_add;
+            binaryfunc nb_subtract;
+            binaryfunc nb_multiply;
+            binaryfunc nb_remainder;
+            binaryfunc nb_divmod;
+            ternaryfunc nb_power;
+            unaryfunc nb_negative;
+            unaryfunc nb_positive;
+            unaryfunc nb_absolute;
+            inquiry nb_bool;
+            unaryfunc nb_invert;
+            binaryfunc nb_lshift;
+            binaryfunc nb_rshift;
+            binaryfunc nb_and;
+            binaryfunc nb_xor;
+            binaryfunc nb_or;
+            int nb_reserved;  /* unused, must be zero */
+            unaryfunc nb_int;
+            unaryfunc nb_long;
+            unaryfunc nb_float;
+            
+            unaryfunc nb_oct; /* not used anymore, must be zero */
+            unaryfunc nb_hex; /* not used anymore, must be zero */
+
+            binaryfunc nb_inplace_add;
+            binaryfunc nb_inplace_subtract;
+            binaryfunc nb_inplace_multiply;
+            binaryfunc nb_inplace_remainder;
+            ternaryfunc nb_inplace_power;
+            binaryfunc nb_inplace_lshift;
+            binaryfunc nb_inplace_rshift;
+            binaryfunc nb_inplace_and;
+            binaryfunc nb_inplace_xor;
+            binaryfunc nb_inplace_or;
+
+            binaryfunc nb_floor_divide;
+            binaryfunc nb_true_divide;
+            binaryfunc nb_inplace_floor_divide;
+            binaryfunc nb_inplace_true_divide;
+
+            unaryfunc nb_index;
+       } PyNumberMethods;
+
+   .. note::
+
+      Binary and ternary functions must check the type of all their operands,
+      and implement the necessary conversions (at least one of the operands is
+      an instance of the defined type).  If the operation is not defined for the
+      given operands, binary and ternary functions must return
+      ``Py_NotImplemented``, if another error occurred they must return ``NULL``
+      and set an exception.
+
+
+.. _mapping-structs:
+
+Mapping Object Structures
+=========================
+
+.. sectionauthor:: Amaury Forgeot d'Arc
+
+
+.. ctype:: PyMappingMethods
+
+   This structure holds pointers to the functions which an object uses to
+   implement the mapping protocol.  It has three members:
+
+.. cmember:: lenfunc PyMappingMethods.mp_length
+
+   This function is used by :cfunc:`PyMapping_Length` and
+   :cfunc:`PyObject_Size`, and has the same signature.  This slot may be set to
+   *NULL* if the object has no defined length.
+
+.. cmember:: binaryfunc PyMappingMethods.mp_subscript
+
+   This function is used by :cfunc:`PyObject_GetItem` and has the same
+   signature.  This slot must be filled for the :cfunc:`PyMapping_Check`
+   function to return ``1``, it can be *NULL* otherwise.
+
+.. cmember:: objobjargproc PyMappingMethods.mp_ass_subscript
+
+   This function is used by :cfunc:`PyObject_SetItem` and has the same
+   signature.  If this slot is *NULL*, the object does not support item
+   assignment.
+
+
+.. _sequence-structs:
+
+Sequence Object Structures
+==========================
+
+.. sectionauthor:: Amaury Forgeot d'Arc
+
+
+.. ctype:: PySequenceMethods
+
+   This structure holds pointers to the functions which an object uses to
+   implement the sequence protocol.
+
+.. cmember:: lenfunc PySequenceMethods.sq_length
+
+   This function is used by :cfunc:`PySequence_Size` and :cfunc:`PyObject_Size`,
+   and has the same signature.
+
+.. cmember:: binaryfunc PySequenceMethods.sq_concat
+
+   This function is used by :cfunc:`PySequence_Concat` and has the same
+   signature.  It is also used by the ``+`` operator, after trying the numeric
+   addition via the :attr:`tp_as_number.nb_add` slot.
+
+.. cmember:: ssizeargfunc PySequenceMethods.sq_repeat
+
+   This function is used by :cfunc:`PySequence_Repeat` and has the same
+   signature.  It is also used by the ``*`` operator, after trying numeric
+   multiplication via the :attr:`tp_as_number.nb_mul` slot.
+
+.. cmember:: ssizeargfunc PySequenceMethods.sq_item
+
+   This function is used by :cfunc:`PySequence_GetItem` and has the same
+   signature.  This slot must be filled for the :cfunc:`PySequence_Check`
+   function to return ``1``, it can be *NULL* otherwise.
+
+   Negative indexes are handled as follows: if the :attr:`sq_length` slot is
+   filled, it is called and the sequence length is used to compute a positive
+   index which is passed to :attr:`sq_item`.  If :attr:`sq_length` is *NULL*,
+   the index is passed as is to the function.
+
+.. cmember:: ssizeobjargproc PySequenceMethods.sq_ass_item
+
+   This function is used by :cfunc:`PySequence_SetItem` and has the same
+   signature.  This slot may be left to *NULL* if the object does not support
+   item assignment.
+
+.. cmember:: objobjproc PySequenceMethods.sq_contains
+
+   This function may be used by :cfunc:`PySequence_Contains` and has the same
+   signature.  This slot may be left to *NULL*, in this case
+   :cfunc:`PySequence_Contains` simply traverses the sequence until it finds a
+   match.
+
+.. cmember:: binaryfunc PySequenceMethods.sq_inplace_concat
+
+   This function is used by :cfunc:`PySequence_InPlaceConcat` and has the same
+   signature.  It should modify its first operand, and return it.
+
+.. cmember:: ssizeargfunc PySequenceMethods.sq_inplace_repeat
+
+   This function is used by :cfunc:`PySequence_InPlaceRepeat` and has the same
+   signature.  It should modify its first operand, and return it.
+
+.. XXX need to explain precedence between mapping and sequence
+.. XXX explains when to implement the sq_inplace_* slots
+
+
+.. _buffer-structs:
+
+Buffer Object Structures
+========================
+
+.. sectionauthor:: Greg J. Stein <greg at lyra.org>
+
+
+The buffer interface exports a model where an object can expose its internal
+data as a set of chunks of data, where each chunk is specified as a
+pointer/length pair.  These chunks are called :dfn:`segments` and are presumed
+to be non-contiguous in memory.
+
+If an object does not export the buffer interface, then its :attr:`tp_as_buffer`
+member in the :ctype:`PyTypeObject` structure should be *NULL*.  Otherwise, the
+:attr:`tp_as_buffer` will point to a :ctype:`PyBufferProcs` structure.
+
+.. note::
+
+   It is very important that your :ctype:`PyTypeObject` structure uses
+   :const:`Py_TPFLAGS_DEFAULT` for the value of the :attr:`tp_flags` member rather
+   than ``0``.  This tells the Python runtime that your :ctype:`PyBufferProcs`
+   structure contains the :attr:`bf_getcharbuffer` slot. Older versions of Python
+   did not have this member, so a new Python interpreter using an old extension
+   needs to be able to test for its presence before using it.
+
+
+.. ctype:: PyBufferProcs
+
+   Structure used to hold the function pointers which define an implementation of
+   the buffer protocol.
+
+   The first slot is :attr:`bf_getreadbuffer`, of type :ctype:`getreadbufferproc`.
+   If this slot is *NULL*, then the object does not support reading from the
+   internal data.  This is non-sensical, so implementors should fill this in, but
+   callers should test that the slot contains a non-*NULL* value.
+
+   The next slot is :attr:`bf_getwritebuffer` having type
+   :ctype:`getwritebufferproc`.  This slot may be *NULL* if the object does not
+   allow writing into its returned buffers.
+
+   The third slot is :attr:`bf_getsegcount`, with type :ctype:`getsegcountproc`.
+   This slot must not be *NULL* and is used to inform the caller how many segments
+   the object contains.  Simple objects such as :ctype:`PyString_Type` and
+   :ctype:`PyBuffer_Type` objects contain a single segment.
+
+   .. index:: single: PyType_HasFeature()
+
+   The last slot is :attr:`bf_getcharbuffer`, of type :ctype:`getcharbufferproc`.
+   This slot will only be present if the :const:`Py_TPFLAGS_HAVE_GETCHARBUFFER`
+   flag is present in the :attr:`tp_flags` field of the object's
+   :ctype:`PyTypeObject`. Before using this slot, the caller should test whether it
+   is present by using the :cfunc:`PyType_HasFeature` function.  If the flag is
+   present, :attr:`bf_getcharbuffer` may be *NULL*, indicating that the object's
+   contents cannot be used as *8-bit characters*. The slot function may also raise
+   an error if the object's contents cannot be interpreted as 8-bit characters.
+   For example, if the object is an array which is configured to hold floating
+   point values, an exception may be raised if a caller attempts to use
+   :attr:`bf_getcharbuffer` to fetch a sequence of 8-bit characters. This notion of
+   exporting the internal buffers as "text" is used to distinguish between objects
+   that are binary in nature, and those which have character-based content.
+
+   .. note::
+
+      The current policy seems to state that these characters may be multi-byte
+      characters. This implies that a buffer size of *N* does not mean there are *N*
+      characters present.
+
+
+.. data:: Py_TPFLAGS_HAVE_GETCHARBUFFER
+
+   Flag bit set in the type structure to indicate that the :attr:`bf_getcharbuffer`
+   slot is known.  This being set does not indicate that the object supports the
+   buffer interface or that the :attr:`bf_getcharbuffer` slot is non-*NULL*.
+
+
+.. ctype:: Py_ssize_t (*readbufferproc) (PyObject *self, Py_ssize_t segment, void **ptrptr)
+
+   Return a pointer to a readable segment of the buffer in ``*ptrptr``.  This
+   function is allowed to raise an exception, in which case it must return ``-1``.
+   The *segment* which is specified must be zero or positive, and strictly less
+   than the number of segments returned by the :attr:`bf_getsegcount` slot
+   function.  On success, it returns the length of the segment, and sets
+   ``*ptrptr`` to a pointer to that memory.
+
+
+.. ctype:: Py_ssize_t (*writebufferproc) (PyObject *self, Py_ssize_t segment, void **ptrptr)
+
+   Return a pointer to a writable memory buffer in ``*ptrptr``, and the length of
+   that segment as the function return value.  The memory buffer must correspond to
+   buffer segment *segment*.  Must return ``-1`` and set an exception on error.
+   :exc:`TypeError` should be raised if the object only supports read-only buffers,
+   and :exc:`SystemError` should be raised when *segment* specifies a segment that
+   doesn't exist.
+
+   .. Why doesn't it raise ValueError for this one?
+      GJS: because you shouldn't be calling it with an invalid
+      segment. That indicates a blatant programming error in the C code.
+
+
+.. ctype:: Py_ssize_t (*segcountproc) (PyObject *self, Py_ssize_t *lenp)
+
+   Return the number of memory segments which comprise the buffer.  If *lenp* is
+   not *NULL*, the implementation must report the sum of the sizes (in bytes) of
+   all segments in ``*lenp``. The function cannot fail.
+
+
+.. ctype:: Py_ssize_t (*charbufferproc) (PyObject *self, Py_ssize_t segment, const char **ptrptr)
+
+   Return the size of the segment *segment* that *ptrptr*  is set to.  ``*ptrptr``
+   is set to the memory buffer. Returns ``-1`` on error.

Added: python/branches/py3k/Doc/c-api/unicode.rst
==============================================================================
--- (empty file)
+++ python/branches/py3k/Doc/c-api/unicode.rst	Sun Jan 20 10:30:57 2008
@@ -0,0 +1,900 @@
+.. highlightlang:: c
+
+.. _unicodeobjects:
+
+Unicode Objects and Codecs
+--------------------------
+
+.. sectionauthor:: Marc-Andre Lemburg <mal at lemburg.com>
+
+Unicode Objects
+^^^^^^^^^^^^^^^
+
+These are the basic Unicode object types used for the Unicode implementation in
+Python:
+
+.. % --- Unicode Type -------------------------------------------------------
+
+
+.. ctype:: 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).
+
+Note that UCS2 and UCS4 Python builds are not binary compatible. Please keep
+this in mind when writing extensions or interfaces.
+
+
+.. ctype:: PyUnicodeObject
+
+   This subtype of :ctype:`PyObject` represents a Python Unicode object.
+
+
+.. cvar:: PyTypeObject PyUnicode_Type
+
+   This instance of :ctype:`PyTypeObject` represents the Python Unicode type.  It
+   is exposed to Python code as ``str``.
+
+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:
+
+
+.. cfunction:: int PyUnicode_Check(PyObject *o)
+
+   Return true if the object *o* is a Unicode object or an instance of a Unicode
+   subtype.
+
+
+.. cfunction:: int PyUnicode_CheckExact(PyObject *o)
+
+   Return true if the object *o* is a Unicode object, but not an instance of a
+   subtype.
+
+
+.. cfunction:: Py_ssize_t PyUnicode_GET_SIZE(PyObject *o)
+
+   Return the size of the object.  *o* has to be a :ctype:`PyUnicodeObject` (not
+   checked).
+
+
+.. cfunction:: Py_ssize_t PyUnicode_GET_DATA_SIZE(PyObject *o)
+
+   Return the size of the object's internal buffer in bytes.  *o* has to be a
+   :ctype:`PyUnicodeObject` (not checked).
+
+
+.. cfunction:: Py_UNICODE* PyUnicode_AS_UNICODE(PyObject *o)
+
+   Return a pointer to the internal :ctype:`Py_UNICODE` buffer of the object.  *o*
+   has to be a :ctype:`PyUnicodeObject` (not checked).
+
+
+.. cfunction:: const char* PyUnicode_AS_DATA(PyObject *o)
+
+   Return a pointer to the internal buffer of the object. *o* has to be a
+   :ctype:`PyUnicodeObject` (not checked).
+
+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.
+
+.. % --- Unicode character properties ---------------------------------------
+
+
+.. cfunction:: int Py_UNICODE_ISSPACE(Py_UNICODE ch)
+
+   Return 1 or 0 depending on whether *ch* is a whitespace character.
+
+
+.. cfunction:: int Py_UNICODE_ISLOWER(Py_UNICODE ch)
+
+   Return 1 or 0 depending on whether *ch* is a lowercase character.
+
+
+.. cfunction:: int Py_UNICODE_ISUPPER(Py_UNICODE ch)
+
+   Return 1 or 0 depending on whether *ch* is an uppercase character.
+
+
+.. cfunction:: int Py_UNICODE_ISTITLE(Py_UNICODE ch)
+
+   Return 1 or 0 depending on whether *ch* is a titlecase character.
+
+
+.. cfunction:: int Py_UNICODE_ISLINEBREAK(Py_UNICODE ch)
+
+   Return 1 or 0 depending on whether *ch* is a linebreak character.
+
+
+.. cfunction:: int Py_UNICODE_ISDECIMAL(Py_UNICODE ch)
+
+   Return 1 or 0 depending on whether *ch* is a decimal character.
+
+
+.. cfunction:: int Py_UNICODE_ISDIGIT(Py_UNICODE ch)
+
+   Return 1 or 0 depending on whether *ch* is a digit character.
+
+
+.. cfunction:: int Py_UNICODE_ISNUMERIC(Py_UNICODE ch)
+
+   Return 1 or 0 depending on whether *ch* is a numeric character.
+
+
+.. cfunction:: int Py_UNICODE_ISALPHA(Py_UNICODE ch)
+
+   Return 1 or 0 depending on whether *ch* is an alphabetic character.
+
+
+.. cfunction:: int Py_UNICODE_ISALNUM(Py_UNICODE ch)
+
+   Return 1 or 0 depending on whether *ch* is an alphanumeric character.
+
+These APIs can be used for fast direct character conversions:
+
+
+.. cfunction:: Py_UNICODE Py_UNICODE_TOLOWER(Py_UNICODE ch)
+
+   Return the character *ch* converted to lower case.
+
+
+.. cfunction:: Py_UNICODE Py_UNICODE_TOUPPER(Py_UNICODE ch)
+
+   Return the character *ch* converted to upper case.
+
+
+.. cfunction:: Py_UNICODE Py_UNICODE_TOTITLE(Py_UNICODE ch)
+
+   Return the character *ch* converted to title case.
+
+
+.. cfunction:: int Py_UNICODE_TODECIMAL(Py_UNICODE ch)
+
+   Return the character *ch* converted to a decimal positive integer.  Return
+   ``-1`` if this is not possible.  This macro does not raise exceptions.
+
+
+.. cfunction:: int Py_UNICODE_TODIGIT(Py_UNICODE ch)
+
+   Return the character *ch* converted to a single digit integer. Return ``-1`` if
+   this is not possible.  This macro does not raise exceptions.
+
+
+.. cfunction:: double Py_UNICODE_TONUMERIC(Py_UNICODE ch)
+
+   Return the character *ch* converted to a double. Return ``-1.0`` if this is not
+   possible.  This macro does not raise exceptions.
+
+To create Unicode objects and access their basic sequence properties, use these
+APIs:
+
+.. % --- Plain Py_UNICODE ---------------------------------------------------
+
+
+.. cfunction:: PyObject* PyUnicode_FromUnicode(const Py_UNICODE *u, Py_ssize_t size)
+
+   Create a Unicode Object from the Py_UNICODE buffer *u* of the given size. *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 *u*
+   is *NULL*.
+
+
+.. cfunction:: PyObject* PyUnicode_FromStringAndSize(const char *u, Py_ssize_t size)
+
+   Create a Unicode Object from the char buffer *u*.  The bytes will be interpreted
+   as being UTF-8 encoded.  *u* may also 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 *u* is *NULL*.
+
+
+.. cfunction:: PyObject *PyUnicode_FromString(const char *u)
+
+   Create a Unicode object from an UTF-8 encoded null-terminated char buffer
+   *u*.
+
+
+.. cfunction:: PyObject* PyUnicode_FromFormat(const char *format, ...)
+
+   Take a C :cfunc:`printf`\ -style *format* string and a variable number of
+   arguments, calculate the size of the resulting Python unicode 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 *format*
+   string.  The following format characters are allowed:
+
+   .. % 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.
+
+   +-------------------+---------------------+--------------------------------+
+   | Format Characters | Type                | Comment                        |
+   +===================+=====================+================================+
+   | :attr:`%%`        | *n/a*               | The literal % character.       |
+   +-------------------+---------------------+--------------------------------+
+   | :attr:`%c`        | int                 | A single character,            |
+   |                   |                     | represented as an C int.       |
+   +-------------------+---------------------+--------------------------------+
+   | :attr:`%d`        | int                 | Exactly equivalent to          |
+   |                   |                     | ``printf("%d")``.              |
+   +-------------------+---------------------+--------------------------------+
+   | :attr:`%u`        | unsigned int        | Exactly equivalent to          |
+   |                   |                     | ``printf("%u")``.              |
+   +-------------------+---------------------+--------------------------------+
+   | :attr:`%ld`       | long                | Exactly equivalent to          |
+   |                   |                     | ``printf("%ld")``.             |
+   +-------------------+---------------------+--------------------------------+
+   | :attr:`%lu`       | unsigned long       | Exactly equivalent to          |
+   |                   |                     | ``printf("%lu")``.             |
+   +-------------------+---------------------+--------------------------------+
+   | :attr:`%zd`       | Py_ssize_t          | Exactly equivalent to          |
+   |                   |                     | ``printf("%zd")``.             |
+   +-------------------+---------------------+--------------------------------+
+   | :attr:`%zu`       | size_t              | Exactly equivalent to          |
+   |                   |                     | ``printf("%zu")``.             |
+   +-------------------+---------------------+--------------------------------+
+   | :attr:`%i`        | int                 | Exactly equivalent to          |
+   |                   |                     | ``printf("%i")``.              |
+   +-------------------+---------------------+--------------------------------+
+   | :attr:`%x`        | int                 | Exactly equivalent to          |
+   |                   |                     | ``printf("%x")``.              |
+   +-------------------+---------------------+--------------------------------+
+   | :attr:`%s`        | char\*              | A null-terminated C character  |
+   |                   |                     | array.                         |
+   +-------------------+---------------------+--------------------------------+
+   | :attr:`%p`        | void\*              | The hex representation of a C  |
+   |                   |                     | pointer. Mostly equivalent to  |
+   |                   |                     | ``printf("%p")`` except that   |
+   |                   |                     | it is guaranteed to start with |
+   |                   |                     | the literal ``0x`` regardless  |
+   |                   |                     | of what the platform's         |
+   |                   |                     | ``printf`` yields.             |
+   +-------------------+---------------------+--------------------------------+
+   | :attr:`%U`        | PyObject\*          | A unicode object.              |
+   +-------------------+---------------------+--------------------------------+
+   | :attr:`%V`        | PyObject\*, char \* | A unicode object (which may be |
+   |                   |                     | *NULL*) and a null-terminated  |
+   |                   |                     | C character array as a second  |
+   |                   |                     | parameter (which will be used, |
+   |                   |                     | if the first parameter is      |
+   |                   |                     | *NULL*).                       |
+   +-------------------+---------------------+--------------------------------+
+   | :attr:`%S`        | PyObject\*          | The result of calling          |
+   |                   |                     | :func:`PyObject_Unicode`.      |
+   +-------------------+---------------------+--------------------------------+
+   | :attr:`%R`        | PyObject\*          | The result of calling          |
+   |                   |                     | :func:`PyObject_Repr`.         |
+   +-------------------+---------------------+--------------------------------+
+
+   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.
+
+
+.. cfunction:: PyObject* PyUnicode_FromFormatV(const char *format, va_list vargs)
+
+   Identical to :func:`PyUnicode_FromFormat` except that it takes exactly two
+   arguments.
+
+
+.. cfunction:: Py_UNICODE* PyUnicode_AsUnicode(PyObject *unicode)
+
+   Return a read-only pointer to the Unicode object's internal :ctype:`Py_UNICODE`
+   buffer, *NULL* if *unicode* is not a Unicode object.
+
+
+.. cfunction:: Py_ssize_t PyUnicode_GetSize(PyObject *unicode)
+
+   Return the length of the Unicode object.
+
+
+.. cfunction:: PyObject* PyUnicode_FromEncodedObject(PyObject *obj, const char *encoding, const char *errors)
+
+   Coerce an encoded object *obj* to an Unicode object and return a reference with
+   incremented refcount.
+
+   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 :exc:`TypeError` to be
+   set.
+
+   The API returns *NULL* if there was an error.  The caller is responsible for
+   decref'ing the returned objects.
+
+
+.. cfunction:: PyObject* PyUnicode_FromObject(PyObject *obj)
+
+   Shortcut for ``PyUnicode_FromEncodedObject(obj, NULL, "strict")`` which is used
+   throughout the interpreter whenever coercion to Unicode is needed.
+
+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`.
+
+.. % --- wchar_t support for platforms which support it ---------------------
+
+
+.. cfunction:: PyObject* PyUnicode_FromWideChar(const wchar_t *w, Py_ssize_t size)
+
+   Create a Unicode object from the :ctype:`wchar_t` buffer *w* of the given size.
+   Return *NULL* on failure.
+
+
+.. cfunction:: 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 *w*.  At most
+   *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.
+
+
+.. _builtincodecs:
+
+Built-in Codecs
+^^^^^^^^^^^^^^^
+
+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" (:exc:`ValueError` is raised).
+
+The codecs all use a similar interface.  Only deviation from the following
+generic ones are documented for simplicity.
+
+These are the generic codec APIs:
+
+.. % --- Generic Codecs -----------------------------------------------------
+
+
+.. cfunction:: PyObject* PyUnicode_Decode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)
+
+   Create a Unicode object by decoding *size* bytes of the encoded string *s*.
+   *encoding* and *errors* have the same meaning as the parameters of the same name
+   in the :func:`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.
+
+
+.. cfunction:: 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.  *encoding* and *errors* have the same meaning as the parameters
+   of the same name in the Unicode :meth:`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.
+
+
+.. cfunction:: PyObject* PyUnicode_AsEncodedString(PyObject *unicode, const char *encoding, const char *errors)
+
+   Encode a Unicode object and return the result as Python string object.
+   *encoding* and *errors* have the same meaning as the parameters of the same name
+   in the Unicode :meth:`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.
+
+These are the UTF-8 codec APIs:
+
+.. % --- UTF-8 Codecs -------------------------------------------------------
+
+
+.. cfunction:: PyObject* PyUnicode_DecodeUTF8(const char *s, Py_ssize_t size, const char *errors)
+
+   Create a Unicode object by decoding *size* bytes of the UTF-8 encoded string
+   *s*. Return *NULL* if an exception was raised by the codec.
+
+
+.. cfunction:: PyObject* PyUnicode_DecodeUTF8Stateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)
+
+   If *consumed* is *NULL*, behave like :cfunc:`PyUnicode_DecodeUTF8`. If
+   *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 *consumed*.
+
+
+.. cfunction:: 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.
+
+
+.. cfunction:: PyObject* PyUnicode_AsUTF8String(PyObject *unicode)
+
+   Encode a Unicode object 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.
+
+These are the UTF-32 codec APIs:
+
+.. % --- UTF-32 Codecs ------------------------------------------------------ */
+
+
+.. cfunction:: PyObject* PyUnicode_DecodeUTF32(const char *s, Py_ssize_t size, const char *errors, int *byteorder)
+
+   Decode *length* bytes from a UTF-32 encoded buffer string and return the
+   corresponding Unicode object.  *errors* (if non-*NULL*) defines the error
+   handling. It defaults to "strict".
+
+   If *byteorder* is non-*NULL*, the decoder starts decoding using the given byte
+   order::
+
+      *byteorder == -1: little endian
+      *byteorder == 0:  native order
+      *byteorder == 1:  big endian
+
+   and then switches if the first four bytes of the input data are a byte order mark
+   (BOM) and the specified byte order is native order.  This BOM is not copied into
+   the resulting Unicode string.  After completion, *\*byteorder* is set to the
+   current byte order at the end of input data.
+
+   In a narrow build codepoints outside the BMP will be decoded as surrogate pairs.
+
+   If *byteorder* is *NULL*, the codec starts in native order mode.
+
+   Return *NULL* if an exception was raised by the codec.
+
+
+.. cfunction:: PyObject* PyUnicode_DecodeUTF32Stateful(const char *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)
+
+   If *consumed* is *NULL*, behave like :cfunc:`PyUnicode_DecodeUTF32`. If
+   *consumed* is not *NULL*, :cfunc:`PyUnicode_DecodeUTF32Stateful` will not treat
+   trailing incomplete UTF-32 byte sequences (such as a number of bytes not divisible
+   by four) as an error. Those bytes will not be decoded and the number of bytes
+   that have been decoded will be stored in *consumed*.
+
+
+.. cfunction:: PyObject* PyUnicode_EncodeUTF32(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder)
+
+   Return a Python bytes object holding the UTF-32 encoded value of the Unicode
+   data in *s*.  If *byteorder* is not ``0``, output is written according to the
+   following byte order::
+
+      byteorder == -1: little endian
+      byteorder == 0:  native byte order (writes a BOM mark)
+      byteorder == 1:  big endian
+
+   If byteorder is ``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 *Py_UNICODE_WIDE* is not defined, surrogate pairs will be output
+   as a single codepoint.
+
+   Return *NULL* if an exception was raised by the codec.
+
+
+.. cfunction:: PyObject* PyUnicode_AsUTF32String(PyObject *unicode)
+
+   Return a Python string using the UTF-32 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.
+
+
+These are the UTF-16 codec APIs:
+
+.. % --- UTF-16 Codecs ------------------------------------------------------ */
+
+
+.. cfunction:: PyObject* PyUnicode_DecodeUTF16(const char *s, Py_ssize_t size, const char *errors, int *byteorder)
+
+   Decode *length* bytes from a UTF-16 encoded buffer string and return the
+   corresponding Unicode object.  *errors* (if non-*NULL*) defines the error
+   handling. It defaults to "strict".
+
+   If *byteorder* is non-*NULL*, the decoder starts decoding using the given byte
+   order::
+
+      *byteorder == -1: little endian
+      *byteorder == 0:  native order
+      *byteorder == 1:  big endian
+
+   and then switches if the first two bytes of the input data are a byte order mark
+   (BOM) and the specified byte order is native order.  This BOM is not copied into
+   the resulting Unicode string.  After completion, *\*byteorder* is set to the
+   current byte order at the end of input data.
+
+   If *byteorder* is *NULL*, the codec starts in native order mode.
+
+   Return *NULL* if an exception was raised by the codec.
+
+
+.. cfunction:: PyObject* PyUnicode_DecodeUTF16Stateful(const char *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)
+
+   If *consumed* is *NULL*, behave like :cfunc:`PyUnicode_DecodeUTF16`. If
+   *consumed* is not *NULL*, :cfunc:`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 *consumed*.
+
+
+.. cfunction:: 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 *s*.  If *byteorder* is not ``0``, output is written according to the
+   following byte order::
+
+      byteorder == -1: little endian
+      byteorder == 0:  native byte order (writes a BOM mark)
+      byteorder == 1:  big endian
+
+   If byteorder is ``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 *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.
+
+
+.. cfunction:: 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.
+
+These are the "Unicode Escape" codec APIs:
+
+.. % --- Unicode-Escape Codecs ----------------------------------------------
+
+
+.. cfunction:: PyObject* PyUnicode_DecodeUnicodeEscape(const char *s, Py_ssize_t size, const char *errors)
+
+   Create a Unicode object by decoding *size* bytes of the Unicode-Escape encoded
+   string *s*.  Return *NULL* if an exception was raised by the codec.
+
+
+.. cfunction:: 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.
+
+
+.. cfunction:: PyObject* PyUnicode_AsUnicodeEscapeString(PyObject *unicode)
+
+   Encode a Unicode object 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.
+
+These are the "Raw Unicode Escape" codec APIs:
+
+.. % --- Raw-Unicode-Escape Codecs ------------------------------------------
+
+
+.. cfunction:: PyObject* PyUnicode_DecodeRawUnicodeEscape(const char *s, Py_ssize_t size, const char *errors)
+
+   Create a Unicode object by decoding *size* bytes of the Raw-Unicode-Escape
+   encoded string *s*.  Return *NULL* if an exception was raised by the codec.
+
+
+.. cfunction:: 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.
+
+
+.. cfunction:: PyObject* PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)
+
+   Encode a Unicode object 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.
+
+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.
+
+.. % --- Latin-1 Codecs -----------------------------------------------------
+
+
+.. cfunction:: PyObject* PyUnicode_DecodeLatin1(const char *s, Py_ssize_t size, const char *errors)
+
+   Create a Unicode object by decoding *size* bytes of the Latin-1 encoded string
+   *s*.  Return *NULL* if an exception was raised by the codec.
+
+
+.. cfunction:: 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.
+
+
+.. cfunction:: PyObject* PyUnicode_AsLatin1String(PyObject *unicode)
+
+   Encode a Unicode object 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.
+
+These are the ASCII codec APIs.  Only 7-bit ASCII data is accepted. All other
+codes generate errors.
+
+.. % --- ASCII Codecs -------------------------------------------------------
+
+
+.. cfunction:: PyObject* PyUnicode_DecodeASCII(const char *s, Py_ssize_t size, const char *errors)
+
+   Create a Unicode object by decoding *size* bytes of the ASCII encoded string
+   *s*.  Return *NULL* if an exception was raised by the codec.
+
+
+.. cfunction:: 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.
+
+
+.. cfunction:: PyObject* PyUnicode_AsASCIIString(PyObject *unicode)
+
+   Encode a Unicode object using ASCII and return the result as Python string
+   object.  Error handling is "strict".  Return *NULL* if an exception was raised
+   by the codec.
+
+These are the mapping codec APIs:
+
+.. % --- Character Map Codecs -----------------------------------------------
+
+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 :mod:`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.
+
+
+.. cfunction:: PyObject* PyUnicode_DecodeCharmap(const char *s, Py_ssize_t size, PyObject *mapping, const char *errors)
+
+   Create a Unicode object by decoding *size* bytes of the encoded string *s* using
+   the given *mapping* object.  Return *NULL* if an exception was raised by the
+   codec. If *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".
+
+
+.. cfunction:: 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
+   *mapping* object and return a Python string object. Return *NULL* if an
+   exception was raised by the codec.
+
+
+.. cfunction:: PyObject* PyUnicode_AsCharmapString(PyObject *unicode, PyObject *mapping)
+
+   Encode a Unicode object using the given *mapping* object and return the result
+   as Python string object.  Error handling is "strict".  Return *NULL* if an
+   exception was raised by the codec.
+
+The following codec API is special in that maps Unicode to Unicode.
+
+
+.. cfunction:: 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 *table* to it and return the resulting Unicode object.  Return
+   *NULL* when an exception was raised by the codec.
+
+   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 :meth:`__getitem__` interface; dictionaries
+   and sequences work well.  Unmapped character ordinals (ones which cause a
+   :exc:`LookupError`) are left untouched and are copied as-is.
+
+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.
+
+.. % --- MBCS codecs for Windows --------------------------------------------
+
+
+.. cfunction:: PyObject* PyUnicode_DecodeMBCS(const char *s, Py_ssize_t size, const char *errors)
+
+   Create a Unicode object by decoding *size* bytes of the MBCS encoded string *s*.
+   Return *NULL* if an exception was raised by the codec.
+
+
+.. cfunction:: PyObject* PyUnicode_DecodeMBCSStateful(const char *s, int size, const char *errors, int *consumed)
+
+   If *consumed* is *NULL*, behave like :cfunc:`PyUnicode_DecodeMBCS`. If
+   *consumed* is not *NULL*, :cfunc:`PyUnicode_DecodeMBCSStateful` will not decode
+   trailing lead byte and the number of bytes that have been decoded will be stored
+   in *consumed*.
+
+
+.. cfunction:: 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.
+
+
+.. cfunction:: PyObject* PyUnicode_AsMBCSString(PyObject *unicode)
+
+   Encode a Unicode object using MBCS and return the result as Python string
+   object.  Error handling is "strict".  Return *NULL* if an exception was raised
+   by the codec.
+
+.. % --- Methods & Slots ----------------------------------------------------
+
+
+.. _unicodemethodsandslots:
+
+Methods and Slot Functions
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+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 ``-1`` if an exception occurs.
+
+
+.. cfunction:: PyObject* PyUnicode_Concat(PyObject *left, PyObject *right)
+
+   Concat two strings giving a new Unicode string.
+
+
+.. cfunction:: 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 *maxsplit* splits will be done.  If negative, no limit is
+   set.  Separators are not included in the resulting list.
+
+
+.. cfunction:: 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 *keepend* is 0, the Line break
+   characters are not included in the resulting strings.
+
+
+.. cfunction:: 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 :meth:`__getitem__` interface; dictionaries
+   and sequences work well.  Unmapped character ordinals (ones which cause a
+   :exc:`LookupError`) are left untouched and are copied as-is.
+
+   *errors* has the usual meaning for codecs. It may be *NULL* which indicates to
+   use the default error handling.
+
+
+.. cfunction:: PyObject* PyUnicode_Join(PyObject *separator, PyObject *seq)
+
+   Join a sequence of strings using the given separator and return the resulting
+   Unicode string.
+
+
+.. cfunction:: int PyUnicode_Tailmatch(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)
+
+   Return 1 if *substr* matches *str*[*start*:*end*] at the given tail end
+   (*direction* == -1 means to do a prefix match, *direction* == 1 a suffix match),
+   0 otherwise. Return ``-1`` if an error occurred.
+
+
+.. cfunction:: Py_ssize_t PyUnicode_Find(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)
+
+   Return the first position of *substr* in *str*[*start*:*end*] using the given
+   *direction* (*direction* == 1 means to do a forward search, *direction* == -1 a
+   backward search).  The return value is the index of the first match; a value of
+   ``-1`` indicates that no match was found, and ``-2`` indicates that an error
+   occurred and an exception has been set.
+
+
+.. cfunction:: 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 *substr* in
+   ``str[start:end]``.  Return ``-1`` if an error occurred.
+
+
+.. cfunction:: PyObject* PyUnicode_Replace(PyObject *str, PyObject *substr, PyObject *replstr, Py_ssize_t maxcount)
+
+   Replace at most *maxcount* occurrences of *substr* in *str* with *replstr* and
+   return the resulting Unicode object. *maxcount* == -1 means replace all
+   occurrences.
+
+
+.. cfunction:: int PyUnicode_Compare(PyObject *left, PyObject *right)
+
+   Compare two strings and return -1, 0, 1 for less than, equal, and greater than,
+   respectively.
+
+
+.. cfunction:: int PyUnicode_RichCompare(PyObject *left,  PyObject *right,  int op)
+
+   Rich compare two unicode strings and return one of the following:
+
+   * ``NULL`` in case an exception was raised
+   * :const:`Py_True` or :const:`Py_False` for successful comparisons
+   * :const:`Py_NotImplemented` in case the type combination is unknown
+
+   Note that :const:`Py_EQ` and :const:`Py_NE` comparisons can cause a
+   :exc:`UnicodeWarning` in case the conversion of the arguments to Unicode fails
+   with a :exc:`UnicodeDecodeError`.
+
+   Possible values for *op* are :const:`Py_GT`, :const:`Py_GE`, :const:`Py_EQ`,
+   :const:`Py_NE`, :const:`Py_LT`, and :const:`Py_LE`.
+
+
+.. cfunction:: PyObject* PyUnicode_Format(PyObject *format, PyObject *args)
+
+   Return a new string object from *format* and *args*; this is analogous to
+   ``format % args``.  The *args* argument must be a tuple.
+
+
+.. cfunction:: int PyUnicode_Contains(PyObject *container, PyObject *element)
+
+   Check whether *element* is contained in *container* and return true or false
+   accordingly.
+
+   *element* has to coerce to a one element Unicode string. ``-1`` is returned if
+   there was an error.
+
+
+.. cfunction:: void PyUnicode_InternInPlace(PyObject **string)
+
+   Intern the argument *\*string* in place.  The argument must be the address of a
+   pointer variable pointing to a Python unicode string object.  If there is an
+   existing interned string that is the same as *\*string*, it sets *\*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
+   *\*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.)
+
+
+.. cfunction:: PyObject* PyUnicode_InternFromString(const char *v)
+
+   A combination of :cfunc:`PyUnicode_FromString` and
+   :cfunc:`PyUnicode_InternInPlace`, returning either a new unicode string object
+   that has been interned, or a new ("owned") reference to an earlier interned
+   string object with the same value.
+

Modified: python/branches/py3k/Doc/c-api/utilities.rst
==============================================================================
--- python/branches/py3k/Doc/c-api/utilities.rst	(original)
+++ python/branches/py3k/Doc/c-api/utilities.rst	Sun Jan 20 10:30:57 2008
@@ -1,6 +1,5 @@
 .. highlightlang:: c
 
-
 .. _utilities:
 
 *********
@@ -11,1125 +10,11 @@
 helping C code be more portable across platforms, using Python modules from C,
 and parsing function arguments and constructing Python values from C values.
 
+.. toctree::
 
-.. _os:
-
-Operating System Utilities
-==========================
-
-
-.. cfunction:: int Py_FdIsInteractive(FILE *fp, const char *filename)
-
-   Return true (nonzero) if the standard I/O file *fp* with name *filename* is
-   deemed interactive.  This is the case for files for which ``isatty(fileno(fp))``
-   is true.  If the global flag :cdata:`Py_InteractiveFlag` is true, this function
-   also returns true if the *filename* pointer is *NULL* or if the name is equal to
-   one of the strings ``'<stdin>'`` or ``'???'``.
-
-
-.. cfunction:: long PyOS_GetLastModificationTime(char *filename)
-
-   Return the time of last modification of the file *filename*. The result is
-   encoded in the same way as the timestamp returned by the standard C library
-   function :cfunc:`time`.
-
-
-.. cfunction:: void PyOS_AfterFork()
-
-   Function to update some internal state after a process fork; this should be
-   called in the new process if the Python interpreter will continue to be used.
-   If a new executable is loaded into the new process, this function does not need
-   to be called.
-
-
-.. cfunction:: int PyOS_CheckStack()
-
-   Return true when the interpreter runs out of stack space.  This is a reliable
-   check, but is only available when :const:`USE_STACKCHECK` is defined (currently
-   on Windows using the Microsoft Visual C++ compiler).  :const:`USE_STACKCHECK`
-   will be defined automatically; you should never change the definition in your
-   own code.
-
-
-.. cfunction:: PyOS_sighandler_t PyOS_getsig(int i)
-
-   Return the current signal handler for signal *i*.  This is a thin wrapper around
-   either :cfunc:`sigaction` or :cfunc:`signal`.  Do not call those functions
-   directly! :ctype:`PyOS_sighandler_t` is a typedef alias for :ctype:`void
-   (\*)(int)`.
-
-
-.. cfunction:: PyOS_sighandler_t PyOS_setsig(int i, PyOS_sighandler_t h)
-
-   Set the signal handler for signal *i* to be *h*; return the old signal handler.
-   This is a thin wrapper around either :cfunc:`sigaction` or :cfunc:`signal`.  Do
-   not call those functions directly!  :ctype:`PyOS_sighandler_t` is a typedef
-   alias for :ctype:`void (\*)(int)`.
-
-.. _systemfunctions:
-
-System Functions
-================
-
-These are utility functions that make functionality from the :mod:`sys` module
-accessible to C code.  They all work with the current interpreter thread's
-:mod:`sys` module's dict, which is contained in the internal thread state structure.
-
-.. cfunction:: PyObject *PySys_GetObject(char *name)
-
-   Return the object *name* from the :mod:`sys` module or *NULL* if it does
-   not exist, without setting an exception.
-
-.. cfunction:: FILE *PySys_GetFile(char *name, FILE *def)
-
-   Return the :ctype:`FILE*` associated with the object *name* in the
-   :mod:`sys` module, or *def* if *name* is not in the module or is not associated
-   with a :ctype:`FILE*`.
-
-.. cfunction:: int PySys_SetObject(char *name, PyObject *v)
-
-   Set *name* in the :mod:`sys` module to *v* unless *v* is *NULL*, in which
-   case *name* is deleted from the sys module. Returns ``0`` on success, ``-1``
-   on error.
-
-.. cfunction:: void PySys_ResetWarnOptions(void)
-
-   Reset :data:`sys.warnoptions` to an empty list.
-
-.. cfunction:: void PySys_AddWarnOption(char *s)
-
-   Append *s* to :data:`sys.warnoptions`.
-
-.. cfunction:: void PySys_SetPath(char *path)
-
-   Set :data:`sys.path` to a list object of paths found in *path* which should
-   be a list of paths separated with the platform's search path delimiter
-   (``:`` on Unix, ``;`` on Windows).
-
-.. cfunction:: void PySys_WriteStdout(const char *format, ...)
-
-   Write the output string described by *format* to :data:`sys.stdout`.  No
-   exceptions are raised, even if truncation occurs (see below).
-
-   *format* should limit the total size of the formatted output string to
-   1000 bytes or less -- after 1000 bytes, the output string is truncated.
-   In particular, this means that no unrestricted "%s" formats should occur;
-   these should be limited using "%.<N>s" where <N> is a decimal number
-   calculated so that <N> plus the maximum size of other formatted text does not
-   exceed 1000 bytes.  Also watch out for "%f", which can print hundreds of
-   digits for very large numbers.
-
-   If a problem occurs, or :data:`sys.stdout` is unset, the formatted message
-   is written to the real (C level) *stdout*.
-
-.. cfunction:: void PySys_WriteStderr(const char *format, ...)
-
-   As above, but write to :data:`sys.stderr` or *stderr* instead.
-
-
-.. _processcontrol:
-
-Process Control
-===============
-
-
-.. cfunction:: void Py_FatalError(const char *message)
-
-   .. index:: single: abort()
-
-   Print a fatal error message and kill the process.  No cleanup is performed.
-   This function should only be invoked when a condition is detected that would
-   make it dangerous to continue using the Python interpreter; e.g., when the
-   object administration appears to be corrupted.  On Unix, the standard C library
-   function :cfunc:`abort` is called which will attempt to produce a :file:`core`
-   file.
-
-
-.. cfunction:: void Py_Exit(int status)
-
-   .. index::
-      single: Py_Finalize()
-      single: exit()
-
-   Exit the current process.  This calls :cfunc:`Py_Finalize` and then calls the
-   standard C library function ``exit(status)``.
-
-
-.. cfunction:: int Py_AtExit(void (*func) ())
-
-   .. index::
-      single: Py_Finalize()
-      single: cleanup functions
-
-   Register a cleanup function to be called by :cfunc:`Py_Finalize`.  The cleanup
-   function will be called with no arguments and should return no value.  At most
-   32 cleanup functions can be registered.  When the registration is successful,
-   :cfunc:`Py_AtExit` returns ``0``; on failure, it returns ``-1``.  The cleanup
-   function registered last is called first. Each cleanup function will be called
-   at most once.  Since Python's internal finalization will have completed before
-   the cleanup function, no Python APIs should be called by *func*.
-
-
-.. _importing:
-
-Importing Modules
-=================
-
-
-.. cfunction:: PyObject* PyImport_ImportModule(const char *name)
-
-   .. index::
-      single: package variable; __all__
-      single: __all__ (package variable)
-      single: modules (in module sys)
-
-   This is a simplified interface to :cfunc:`PyImport_ImportModuleEx` below,
-   leaving the *globals* and *locals* arguments set to *NULL* and *level* set
-   to 0.  When the *name*
-   argument contains a dot (when it specifies a submodule of a package), the
-   *fromlist* argument is set to the list ``['*']`` so that the return value is the
-   named module rather than the top-level package containing it as would otherwise
-   be the case.  (Unfortunately, this has an additional side effect when *name* in
-   fact specifies a subpackage instead of a submodule: the submodules specified in
-   the package's ``__all__`` variable are  loaded.)  Return a new reference to the
-   imported module, or *NULL* with an exception set on failure.  Before Python 2.4,
-   the module may still be created in the failure case --- examine ``sys.modules``
-   to find out.  Starting with Python 2.4, a failing import of a module no longer
-   leaves the module in ``sys.modules``.
-
-
-.. cfunction:: PyObject* PyImport_ImportModuleNoBlock(const char *name)
-
-   This version of :cfunc:`PyImport_ImportModule` does not block. It's intended
-   to be used in C functions that import other modules to execute a function.
-   The import may block if another thread holds the import lock. The function
-   :cfunc:`PyImport_ImportModuleNoBlock` never blocks. It first tries to fetch
-   the module from sys.modules and falls back to :cfunc:`PyImport_ImportModule`
-   unless the lock is held, in which case the function will raise an
-   :exc:`ImportError`.
-
-
-.. cfunction:: PyObject* PyImport_ImportModuleEx(char *name, PyObject *globals, PyObject *locals, PyObject *fromlist)
-
-   .. index:: builtin: __import__
-
-   Import a module.  This is best described by referring to the built-in Python
-   function :func:`__import__`, as the standard :func:`__import__` function calls
-   this function directly.
-
-   The return value is a new reference to the imported module or top-level package,
-   or *NULL* with an exception set on failure (before Python 2.4, the module may
-   still be created in this case).  Like for :func:`__import__`, the return value
-   when a submodule of a package was requested is normally the top-level package,
-   unless a non-empty *fromlist* was given.
-
-   Failing imports remove incomplete module objects, like with
-   :cfunc:`PyImport_ImportModule`.
-
-
-.. cfunction:: PyObject* PyImport_ImportModuleLevel(char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)
-
-   Import a module.  This is best described by referring to the built-in Python
-   function :func:`__import__`, as the standard :func:`__import__` function calls
-   this function directly.
-
-   The return value is a new reference to the imported module or top-level package,
-   or *NULL* with an exception set on failure.  Like for :func:`__import__`,
-   the return value when a submodule of a package was requested is normally the
-   top-level package, unless a non-empty *fromlist* was given.
-
-
-.. cfunction:: PyObject* PyImport_Import(PyObject *name)
-
-   This is a higher-level interface that calls the current "import hook
-   function" (with an explicit *level* of 0, meaning absolute import).  It
-   invokes the :func:`__import__` function from the ``__builtins__`` of the
-   current globals.  This means that the import is done using whatever import
-   hooks are installed in the current environment.
-
-
-.. cfunction:: PyObject* PyImport_ReloadModule(PyObject *m)
-
-   Reload a module.  Return a new reference to the reloaded module, or *NULL* with
-   an exception set on failure (the module still exists in this case).
-
-
-.. cfunction:: PyObject* PyImport_AddModule(const char *name)
-
-   Return the module object corresponding to a module name.  The *name* argument
-   may be of the form ``package.module``. First check the modules dictionary if
-   there's one there, and if not, create a new one and insert it in the modules
-   dictionary. Return *NULL* with an exception set on failure.
-
-   .. note::
-
-      This function does not load or import the module; if the module wasn't already
-      loaded, you will get an empty module object. Use :cfunc:`PyImport_ImportModule`
-      or one of its variants to import a module.  Package structures implied by a
-      dotted name for *name* are not created if not already present.
-
-
-.. cfunction:: PyObject* PyImport_ExecCodeModule(char *name, PyObject *co)
-
-   .. index:: builtin: compile
-
-   Given a module name (possibly of the form ``package.module``) and a code object
-   read from a Python bytecode file or obtained from the built-in function
-   :func:`compile`, load the module.  Return a new reference to the module object,
-   or *NULL* with an exception set if an error occurred.  Before Python 2.4, the
-   module could still be created in error cases.  Starting with Python 2.4, *name*
-   is removed from :attr:`sys.modules` in error cases, and even if *name* was already
-   in :attr:`sys.modules` on entry to :cfunc:`PyImport_ExecCodeModule`.  Leaving
-   incompletely initialized modules in :attr:`sys.modules` is dangerous, as imports of
-   such modules have no way to know that the module object is an unknown (and
-   probably damaged with respect to the module author's intents) state.
-
-   This function will reload the module if it was already imported.  See
-   :cfunc:`PyImport_ReloadModule` for the intended way to reload a module.
-
-   If *name* points to a dotted name of the form ``package.module``, any package
-   structures not already created will still not be created.
-
-
-.. cfunction:: long PyImport_GetMagicNumber()
-
-   Return the magic number for Python bytecode files (a.k.a. :file:`.pyc` and
-   :file:`.pyo` files).  The magic number should be present in the first four bytes
-   of the bytecode file, in little-endian byte order.
-
-
-.. cfunction:: PyObject* PyImport_GetModuleDict()
-
-   Return the dictionary used for the module administration (a.k.a.
-   ``sys.modules``).  Note that this is a per-interpreter variable.
-
-
-.. cfunction:: void _PyImport_Init()
-
-   Initialize the import mechanism.  For internal use only.
-
-
-.. cfunction:: void PyImport_Cleanup()
-
-   Empty the module table.  For internal use only.
-
-
-.. cfunction:: void _PyImport_Fini()
-
-   Finalize the import mechanism.  For internal use only.
-
-
-.. cfunction:: PyObject* _PyImport_FindExtension(char *, char *)
-
-   For internal use only.
-
-
-.. cfunction:: PyObject* _PyImport_FixupExtension(char *, char *)
-
-   For internal use only.
-
-
-.. cfunction:: int PyImport_ImportFrozenModule(char *name)
-
-   Load a frozen module named *name*.  Return ``1`` for success, ``0`` if the
-   module is not found, and ``-1`` with an exception set if the initialization
-   failed.  To access the imported module on a successful load, use
-   :cfunc:`PyImport_ImportModule`.  (Note the misnomer --- this function would
-   reload the module if it was already imported.)
-
-
-.. ctype:: struct _frozen
-
-   .. index:: single: freeze utility
-
-   This is the structure type definition for frozen module descriptors, as
-   generated by the :program:`freeze` utility (see :file:`Tools/freeze/` in the
-   Python source distribution).  Its definition, found in :file:`Include/import.h`,
-   is::
-
-      struct _frozen {
-          char *name;
-          unsigned char *code;
-          int size;
-      };
-
-
-.. cvar:: struct _frozen* PyImport_FrozenModules
-
-   This pointer is initialized to point to an array of :ctype:`struct _frozen`
-   records, terminated by one whose members are all *NULL* or zero.  When a frozen
-   module is imported, it is searched in this table.  Third-party code could play
-   tricks with this to provide a dynamically created collection of frozen modules.
-
-
-.. cfunction:: int PyImport_AppendInittab(char *name, void (*initfunc)(void))
-
-   Add a single module to the existing table of built-in modules.  This is a
-   convenience wrapper around :cfunc:`PyImport_ExtendInittab`, returning ``-1`` if
-   the table could not be extended.  The new module can be imported by the name
-   *name*, and uses the function *initfunc* as the initialization function called
-   on the first attempted import.  This should be called before
-   :cfunc:`Py_Initialize`.
-
-
-.. ctype:: struct _inittab
-
-   Structure describing a single entry in the list of built-in modules.  Each of
-   these structures gives the name and initialization function for a module built
-   into the interpreter.  Programs which embed Python may use an array of these
-   structures in conjunction with :cfunc:`PyImport_ExtendInittab` to provide
-   additional built-in modules.  The structure is defined in
-   :file:`Include/import.h` as::
-
-      struct _inittab {
-          char *name;
-          void (*initfunc)(void);
-      };
-
-
-.. cfunction:: int PyImport_ExtendInittab(struct _inittab *newtab)
-
-   Add a collection of modules to the table of built-in modules.  The *newtab*
-   array must end with a sentinel entry which contains *NULL* for the :attr:`name`
-   field; failure to provide the sentinel value can result in a memory fault.
-   Returns ``0`` on success or ``-1`` if insufficient memory could be allocated to
-   extend the internal table.  In the event of failure, no modules are added to the
-   internal table.  This should be called before :cfunc:`Py_Initialize`.
-
-
-.. _marshalling-utils:
-
-Data marshalling support
-========================
-
-These routines allow C code to work with serialized objects using the same data
-format as the :mod:`marshal` module.  There are functions to write data into the
-serialization format, and additional functions that can be used to read the data
-back.  Files used to store marshalled data must be opened in binary mode.
-
-Numeric values are stored with the least significant byte first.
-
-The module supports two versions of the data format: version 0 is the historical
-version, version 1 (new in Python 2.4) shares interned strings in the file, and
-upon unmarshalling. *Py_MARSHAL_VERSION* indicates the current file format
-(currently 1).
-
-
-.. cfunction:: void PyMarshal_WriteLongToFile(long value, FILE *file, int version)
-
-   Marshal a :ctype:`long` integer, *value*, to *file*.  This will only write the
-   least-significant 32 bits of *value*; regardless of the size of the native
-   :ctype:`long` type.  *version* indicates the file format.
-
-
-.. cfunction:: void PyMarshal_WriteObjectToFile(PyObject *value, FILE *file, int version)
-
-   Marshal a Python object, *value*, to *file*.
-   *version* indicates the file format.
-
-
-.. cfunction:: PyObject* PyMarshal_WriteObjectToString(PyObject *value, int version)
-
-   Return a string object containing the marshalled representation of *value*.
-   *version* indicates the file format.
-
-
-The following functions allow marshalled values to be read back in.
-
-XXX What about error detection?  It appears that reading past the end of the
-file will always result in a negative numeric value (where that's relevant), but
-it's not clear that negative values won't be handled properly when there's no
-error.  What's the right way to tell? Should only non-negative values be written
-using these routines?
-
-
-.. cfunction:: long PyMarshal_ReadLongFromFile(FILE *file)
-
-   Return a C :ctype:`long` from the data stream in a :ctype:`FILE\*` opened for
-   reading.  Only a 32-bit value can be read in using this function, regardless of
-   the native size of :ctype:`long`.
-
-
-.. cfunction:: int PyMarshal_ReadShortFromFile(FILE *file)
-
-   Return a C :ctype:`short` from the data stream in a :ctype:`FILE\*` opened for
-   reading.  Only a 16-bit value can be read in using this function, regardless of
-   the native size of :ctype:`short`.
-
-
-.. cfunction:: PyObject* PyMarshal_ReadObjectFromFile(FILE *file)
-
-   Return a Python object from the data stream in a :ctype:`FILE\*` opened for
-   reading.  On error, sets the appropriate exception (:exc:`EOFError` or
-   :exc:`TypeError`) and returns *NULL*.
-
-
-.. cfunction:: PyObject* PyMarshal_ReadLastObjectFromFile(FILE *file)
-
-   Return a Python object from the data stream in a :ctype:`FILE\*` opened for
-   reading.  Unlike :cfunc:`PyMarshal_ReadObjectFromFile`, this function assumes
-   that no further objects will be read from the file, allowing it to aggressively
-   load file data into memory so that the de-serialization can operate from data in
-   memory rather than reading a byte at a time from the file.  Only use these
-   variant if you are certain that you won't be reading anything else from the
-   file.  On error, sets the appropriate exception (:exc:`EOFError` or
-   :exc:`TypeError`) and returns *NULL*.
-
-
-.. cfunction:: PyObject* PyMarshal_ReadObjectFromString(char *string, Py_ssize_t len)
-
-   Return a Python object from the data stream in a character buffer containing
-   *len* bytes pointed to by *string*.  On error, sets the appropriate exception
-   (:exc:`EOFError` or :exc:`TypeError`) and returns *NULL*.
-
-
-.. _arg-parsing:
-
-Parsing arguments and building values
-=====================================
-
-These functions are useful when creating your own extensions functions and
-methods.  Additional information and examples are available in
-:ref:`extending-index`.
-
-The first three of these functions described, :cfunc:`PyArg_ParseTuple`,
-:cfunc:`PyArg_ParseTupleAndKeywords`, and :cfunc:`PyArg_Parse`, all use *format
-strings* which are used to tell the function about the expected arguments.  The
-format strings use the same syntax for each of these functions.
-
-A format string consists of zero or more "format units."  A format unit
-describes one Python object; it is usually a single character or a parenthesized
-sequence of format units.  With a few exceptions, a format unit that is not a
-parenthesized sequence normally corresponds to a single address argument to
-these functions.  In the following description, the quoted form is the format
-unit; the entry in (round) parentheses is the Python object type that matches
-the format unit; and the entry in [square] brackets is the type of the C
-variable(s) whose address should be passed.
-
-``s`` (string or Unicode object) [const char \*]
-   Convert a Python string or Unicode object to a C pointer to a character string.
-   You must not provide storage for the string itself; a pointer to an existing
-   string is stored into the character pointer variable whose address you pass.
-   The C string is NUL-terminated.  The Python string must not contain embedded NUL
-   bytes; if it does, a :exc:`TypeError` exception is raised. Unicode objects are
-   converted to C strings using the default encoding.  If this conversion fails, a
-   :exc:`UnicodeError` is raised.
-
-``s#`` (string, Unicode or any read buffer compatible object) [const char \*, int]
-   This variant on ``s`` stores into two C variables, the first one a pointer to a
-   character string, the second one its length.  In this case the Python string may
-   contain embedded null bytes.  Unicode objects pass back a pointer to the default
-   encoded string version of the object if such a conversion is possible.  All
-   other read-buffer compatible objects pass back a reference to the raw internal
-   data representation.
-
-``y`` (bytes object) [const char \*]
-   This variant on ``s`` convert a Python bytes object to a C pointer to a
-   character string. The bytes object must not contain embedded NUL bytes; if it
-   does, a :exc:`TypeError` exception is raised.
-
-``y#`` (bytes object) [const char \*, int]
-   This variant on ``s#`` stores into two C variables, the first one a pointer to a
-   character string, the second one its length.  This only accepts bytes objects.
-
-``z`` (string or ``None``) [const char \*]
-   Like ``s``, but the Python object may also be ``None``, in which case the C
-   pointer is set to *NULL*.
-
-``z#`` (string or ``None`` or any read buffer compatible object) [const char \*, int]
-   This is to ``s#`` as ``z`` is to ``s``.
-
-``u`` (Unicode object) [Py_UNICODE \*]
-   Convert a Python Unicode object to a C pointer to a NUL-terminated buffer of
-   16-bit Unicode (UTF-16) data.  As with ``s``, there is no need to provide
-   storage for the Unicode data buffer; a pointer to the existing Unicode data is
-   stored into the :ctype:`Py_UNICODE` pointer variable whose address you pass.
-
-``u#`` (Unicode object) [Py_UNICODE \*, int]
-   This variant on ``u`` stores into two C variables, the first one a pointer to a
-   Unicode data buffer, the second one its length. Non-Unicode objects are handled
-   by interpreting their read-buffer pointer as pointer to a :ctype:`Py_UNICODE`
-   array.
-
-``Z`` (Unicode or ``None``) [Py_UNICODE \*]
-   Like ``s``, but the Python object may also be ``None``, in which case the C
-   pointer is set to *NULL*.
-
-``Z#`` (Unicode or ``None``) [Py_UNICODE \*, int]
-   This is to ``u#`` as ``Z`` is to ``u``.
-
-``es`` (string, Unicode object or character buffer compatible object) [const char \*encoding, char \*\*buffer]
-   This variant on ``s`` is used for encoding Unicode and objects convertible to
-   Unicode into a character buffer. It only works for encoded data without embedded
-   NUL bytes.
-
-   This format requires two arguments.  The first is only used as input, and
-   must be a :ctype:`const char\*` which points to the name of an encoding as a
-   NUL-terminated string, or *NULL*, in which case the default encoding is used.
-   An exception is raised if the named encoding is not known to Python.  The
-   second argument must be a :ctype:`char\*\*`; the value of the pointer it
-   references will be set to a buffer with the contents of the argument text.
-   The text will be encoded in the encoding specified by the first argument.
-
-   :cfunc:`PyArg_ParseTuple` will allocate a buffer of the needed size, copy the
-   encoded data into this buffer and adjust *\*buffer* to reference the newly
-   allocated storage.  The caller is responsible for calling :cfunc:`PyMem_Free` to
-   free the allocated buffer after use.
-
-``et`` (string, Unicode object or character buffer compatible object) [const char \*encoding, char \*\*buffer]
-   Same as ``es`` except that 8-bit string objects are passed through without
-   recoding them.  Instead, the implementation assumes that the string object uses
-   the encoding passed in as parameter.
-
-``es#`` (string, Unicode object or character buffer compatible object) [const char \*encoding, char \*\*buffer, int \*buffer_length]
-   This variant on ``s#`` is used for encoding Unicode and objects convertible to
-   Unicode into a character buffer.  Unlike the ``es`` format, this variant allows
-   input data which contains NUL characters.
-
-   It requires three arguments.  The first is only used as input, and must be a
-   :ctype:`const char\*` which points to the name of an encoding as a
-   NUL-terminated string, or *NULL*, in which case the default encoding is used.
-   An exception is raised if the named encoding is not known to Python.  The
-   second argument must be a :ctype:`char\*\*`; the value of the pointer it
-   references will be set to a buffer with the contents of the argument text.
-   The text will be encoded in the encoding specified by the first argument.
-   The third argument must be a pointer to an integer; the referenced integer
-   will be set to the number of bytes in the output buffer.
-
-   There are two modes of operation:
-
-   If *\*buffer* points a *NULL* pointer, the function will allocate a buffer of
-   the needed size, copy the encoded data into this buffer and set *\*buffer* to
-   reference the newly allocated storage.  The caller is responsible for calling
-   :cfunc:`PyMem_Free` to free the allocated buffer after usage.
-
-   If *\*buffer* points to a non-*NULL* pointer (an already allocated buffer),
-   :cfunc:`PyArg_ParseTuple` will use this location as the buffer and interpret the
-   initial value of *\*buffer_length* as the buffer size.  It will then copy the
-   encoded data into the buffer and NUL-terminate it.  If the buffer is not large
-   enough, a :exc:`ValueError` will be set.
-
-   In both cases, *\*buffer_length* is set to the length of the encoded data
-   without the trailing NUL byte.
-
-``et#`` (string, Unicode object or character buffer compatible object) [const char \*encoding, char \*\*buffer]
-   Same as ``es#`` except that string objects are passed through without recoding
-   them. Instead, the implementation assumes that the string object uses the
-   encoding passed in as parameter.
-
-``b`` (integer) [char]
-   Convert a Python integer to a tiny int, stored in a C :ctype:`char`.
-
-``B`` (integer) [unsigned char]
-   Convert a Python integer to a tiny int without overflow checking, stored in a C
-   :ctype:`unsigned char`.
-
-``h`` (integer) [short int]
-   Convert a Python integer to a C :ctype:`short int`.
-
-``H`` (integer) [unsigned short int]
-   Convert a Python integer to a C :ctype:`unsigned short int`, without overflow
-   checking.
-
-``i`` (integer) [int]
-   Convert a Python integer to a plain C :ctype:`int`.
-
-``I`` (integer) [unsigned int]
-   Convert a Python integer to a C :ctype:`unsigned int`, without overflow
-   checking.
-
-``l`` (integer) [long int]
-   Convert a Python integer to a C :ctype:`long int`.
-
-``k`` (integer) [unsigned long]
-   Convert a Python integer to a C :ctype:`unsigned long` without
-   overflow checking.
-
-``L`` (integer) [PY_LONG_LONG]
-   Convert a Python integer to a C :ctype:`long long`.  This format is only
-   available on platforms that support :ctype:`long long` (or :ctype:`_int64` on
-   Windows).
-
-``K`` (integer) [unsigned PY_LONG_LONG]
-   Convert a Python integer to a C :ctype:`unsigned long long`
-   without overflow checking.  This format is only available on platforms that
-   support :ctype:`unsigned long long` (or :ctype:`unsigned _int64` on Windows).
-
-``n`` (integer) [Py_ssize_t]
-   Convert a Python integer to a C :ctype:`Py_ssize_t`.
-
-``c`` (string of length 1) [char]
-   Convert a Python character, represented as a string of length 1, to a C
-   :ctype:`char`.
-
-``f`` (float) [float]
-   Convert a Python floating point number to a C :ctype:`float`.
-
-``d`` (float) [double]
-   Convert a Python floating point number to a C :ctype:`double`.
-
-``D`` (complex) [Py_complex]
-   Convert a Python complex number to a C :ctype:`Py_complex` structure.
-
-``O`` (object) [PyObject \*]
-   Store a Python object (without any conversion) in a C object pointer.  The C
-   program thus receives the actual object that was passed.  The object's reference
-   count is not increased.  The pointer stored is not *NULL*.
-
-``O!`` (object) [*typeobject*, PyObject \*]
-   Store a Python object in a C object pointer.  This is similar to ``O``, but
-   takes two C arguments: the first is the address of a Python type object, the
-   second is the address of the C variable (of type :ctype:`PyObject\*`) into which
-   the object pointer is stored.  If the Python object does not have the required
-   type, :exc:`TypeError` is raised.
-
-``O&`` (object) [*converter*, *anything*]
-   Convert a Python object to a C variable through a *converter* function.  This
-   takes two arguments: the first is a function, the second is the address of a C
-   variable (of arbitrary type), converted to :ctype:`void \*`.  The *converter*
-   function in turn is called as follows::
-
-      status = converter(object, address);
-
-   where *object* is the Python object to be converted and *address* is the
-   :ctype:`void\*` argument that was passed to the :cfunc:`PyArg_Parse\*` function.
-   The returned *status* should be ``1`` for a successful conversion and ``0`` if
-   the conversion has failed.  When the conversion fails, the *converter* function
-   should raise an exception.
-
-``S`` (string) [PyStringObject \*]
-   Like ``O`` but requires that the Python object is a string object.  Raises
-   :exc:`TypeError` if the object is not a string object.  The C variable may also
-   be declared as :ctype:`PyObject\*`.
-
-``U`` (Unicode string) [PyUnicodeObject \*]
-   Like ``O`` but requires that the Python object is a Unicode object.  Raises
-   :exc:`TypeError` if the object is not a Unicode object.  The C variable may also
-   be declared as :ctype:`PyObject\*`.
-
-``t#`` (read-only character buffer) [char \*, int]
-   Like ``s#``, but accepts any object which implements the read-only buffer
-   interface.  The :ctype:`char\*` variable is set to point to the first byte of
-   the buffer, and the :ctype:`int` is set to the length of the buffer.  Only
-   single-segment buffer objects are accepted; :exc:`TypeError` is raised for all
-   others.
-
-``w`` (read-write character buffer) [char \*]
-   Similar to ``s``, but accepts any object which implements the read-write buffer
-   interface.  The caller must determine the length of the buffer by other means,
-   or use ``w#`` instead.  Only single-segment buffer objects are accepted;
-   :exc:`TypeError` is raised for all others.
-
-``w#`` (read-write character buffer) [char \*, int]
-   Like ``s#``, but accepts any object which implements the read-write buffer
-   interface.  The :ctype:`char \*` variable is set to point to the first byte of
-   the buffer, and the :ctype:`int` is set to the length of the buffer.  Only
-   single-segment buffer objects are accepted; :exc:`TypeError` is raised for all
-   others.
-
-``(items)`` (tuple) [*matching-items*]
-   The object must be a Python sequence whose length is the number of format units
-   in *items*.  The C arguments must correspond to the individual format units in
-   *items*.  Format units for sequences may be nested.
-
-It is possible to pass "long" integers (integers whose value exceeds the
-platform's :const:`LONG_MAX`) however no proper range checking is done --- the
-most significant bits are silently truncated when the receiving field is too
-small to receive the value (actually, the semantics are inherited from downcasts
-in C --- your mileage may vary).
-
-A few other characters have a meaning in a format string.  These may not occur
-inside nested parentheses.  They are:
-
-``|``
-   Indicates that the remaining arguments in the Python argument list are optional.
-   The C variables corresponding to optional arguments should be initialized to
-   their default value --- when an optional argument is not specified,
-   :cfunc:`PyArg_ParseTuple` does not touch the contents of the corresponding C
-   variable(s).
-
-``:``
-   The list of format units ends here; the string after the colon is used as the
-   function name in error messages (the "associated value" of the exception that
-   :cfunc:`PyArg_ParseTuple` raises).
-
-``;``
-   The list of format units ends here; the string after the semicolon is used as
-   the error message *instead* of the default error message.  Clearly, ``:`` and
-   ``;`` mutually exclude each other.
-
-Note that any Python object references which are provided to the caller are
-*borrowed* references; do not decrement their reference count!
-
-Additional arguments passed to these functions must be addresses of variables
-whose type is determined by the format string; these are used to store values
-from the input tuple.  There are a few cases, as described in the list of format
-units above, where these parameters are used as input values; they should match
-what is specified for the corresponding format unit in that case.
-
-For the conversion to succeed, the *arg* object must match the format and the
-format must be exhausted.  On success, the :cfunc:`PyArg_Parse\*` functions
-return true, otherwise they return false and raise an appropriate exception.
-
-
-.. cfunction:: int PyArg_ParseTuple(PyObject *args, const char *format, ...)
-
-   Parse the parameters of a function that takes only positional parameters into
-   local variables.  Returns true on success; on failure, it returns false and
-   raises the appropriate exception.
-
-
-.. cfunction:: int PyArg_VaParse(PyObject *args, const char *format, va_list vargs)
-
-   Identical to :cfunc:`PyArg_ParseTuple`, except that it accepts a va_list rather
-   than a variable number of arguments.
-
-
-.. cfunction:: int PyArg_ParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], ...)
-
-   Parse the parameters of a function that takes both positional and keyword
-   parameters into local variables.  Returns true on success; on failure, it
-   returns false and raises the appropriate exception.
-
-
-.. cfunction:: int PyArg_VaParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], va_list vargs)
-
-   Identical to :cfunc:`PyArg_ParseTupleAndKeywords`, except that it accepts a
-   va_list rather than a variable number of arguments.
-
-
-.. XXX deprecated, will be removed
-.. cfunction:: int PyArg_Parse(PyObject *args, const char *format, ...)
-
-   Function used to deconstruct the argument lists of "old-style" functions ---
-   these are functions which use the :const:`METH_OLDARGS` parameter parsing
-   method.  This is not recommended for use in parameter parsing in new code, and
-   most code in the standard interpreter has been modified to no longer use this
-   for that purpose.  It does remain a convenient way to decompose other tuples,
-   however, and may continue to be used for that purpose.
-
-
-.. cfunction:: int PyArg_UnpackTuple(PyObject *args, const char *name, Py_ssize_t min, Py_ssize_t max, ...)
-
-   A simpler form of parameter retrieval which does not use a format string to
-   specify the types of the arguments.  Functions which use this method to retrieve
-   their parameters should be declared as :const:`METH_VARARGS` in function or
-   method tables.  The tuple containing the actual parameters should be passed as
-   *args*; it must actually be a tuple.  The length of the tuple must be at least
-   *min* and no more than *max*; *min* and *max* may be equal.  Additional
-   arguments must be passed to the function, each of which should be a pointer to a
-   :ctype:`PyObject\*` variable; these will be filled in with the values from
-   *args*; they will contain borrowed references.  The variables which correspond
-   to optional parameters not given by *args* will not be filled in; these should
-   be initialized by the caller. This function returns true on success and false if
-   *args* is not a tuple or contains the wrong number of elements; an exception
-   will be set if there was a failure.
-
-   This is an example of the use of this function, taken from the sources for the
-   :mod:`_weakref` helper module for weak references::
-
-      static PyObject *
-      weakref_ref(PyObject *self, PyObject *args)
-      {
-          PyObject *object;
-          PyObject *callback = NULL;
-          PyObject *result = NULL;
-
-          if (PyArg_UnpackTuple(args, "ref", 1, 2, &object, &callback)) {
-              result = PyWeakref_NewRef(object, callback);
-          }
-          return result;
-      }
-
-   The call to :cfunc:`PyArg_UnpackTuple` in this example is entirely equivalent to
-   this call to :cfunc:`PyArg_ParseTuple`::
-
-      PyArg_ParseTuple(args, "O|O:ref", &object, &callback)
-
-
-.. cfunction:: PyObject* Py_BuildValue(const char *format, ...)
-
-   Create a new value based on a format string similar to those accepted by the
-   :cfunc:`PyArg_Parse\*` family of functions and a sequence of values.  Returns
-   the value or *NULL* in the case of an error; an exception will be raised if
-   *NULL* is returned.
-
-   :cfunc:`Py_BuildValue` does not always build a tuple.  It builds a tuple only if
-   its format string contains two or more format units.  If the format string is
-   empty, it returns ``None``; if it contains exactly one format unit, it returns
-   whatever object is described by that format unit.  To force it to return a tuple
-   of size 0 or one, parenthesize the format string.
-
-   When memory buffers are passed as parameters to supply data to build objects, as
-   for the ``s`` and ``s#`` formats, the required data is copied.  Buffers provided
-   by the caller are never referenced by the objects created by
-   :cfunc:`Py_BuildValue`.  In other words, if your code invokes :cfunc:`malloc`
-   and passes the allocated memory to :cfunc:`Py_BuildValue`, your code is
-   responsible for calling :cfunc:`free` for that memory once
-   :cfunc:`Py_BuildValue` returns.
-
-   In the following description, the quoted form is the format unit; the entry in
-   (round) parentheses is the Python object type that the format unit will return;
-   and the entry in [square] brackets is the type of the C value(s) to be passed.
-
-   The characters space, tab, colon and comma are ignored in format strings (but
-   not within format units such as ``s#``).  This can be used to make long format
-   strings a tad more readable.
-
-   ``s`` (string) [char \*]
-      Convert a null-terminated C string to a Python object.  If the C string pointer
-      is *NULL*, ``None`` is used.
-
-   ``s#`` (string) [char \*, int]
-      Convert a C string and its length to a Python object.  If the C string pointer
-      is *NULL*, the length is ignored and ``None`` is returned.
-
-   ``z`` (string or ``None``) [char \*]
-      Same as ``s``.
-
-   ``z#`` (string or ``None``) [char \*, int]
-      Same as ``s#``.
-
-   ``u`` (Unicode string) [Py_UNICODE \*]
-      Convert a null-terminated buffer of Unicode (UCS-2 or UCS-4) data to a Python
-      Unicode object.  If the Unicode buffer pointer is *NULL*, ``None`` is returned.
-
-   ``u#`` (Unicode string) [Py_UNICODE \*, int]
-      Convert a Unicode (UCS-2 or UCS-4) data buffer and its length to a Python
-      Unicode object.   If the Unicode buffer pointer is *NULL*, the length is ignored
-      and ``None`` is returned.
-
-   ``U`` (string) [char \*]
-      Convert a null-terminated C string to a Python unicode object. If the C string
-      pointer is *NULL*, ``None`` is used.
-
-   ``U#`` (string) [char \*, int]
-      Convert a C string and its length to a Python unicode object. If the C string
-      pointer is *NULL*, the length is ignored and ``None`` is returned.
-
-   ``i`` (integer) [int]
-      Convert a plain C :ctype:`int` to a Python integer object.
-
-   ``b`` (integer) [char]
-      Convert a plain C :ctype:`char` to a Python integer object.
-
-   ``h`` (integer) [short int]
-      Convert a plain C :ctype:`short int` to a Python integer object.
-
-   ``l`` (integer) [long int]
-      Convert a C :ctype:`long int` to a Python integer object.
-
-   ``B`` (integer) [unsigned char]
-      Convert a C :ctype:`unsigned char` to a Python integer object.
-
-   ``H`` (integer) [unsigned short int]
-      Convert a C :ctype:`unsigned short int` to a Python integer object.
-
-   ``I`` (integer/long) [unsigned int]
-      Convert a C :ctype:`unsigned int` to a Python long integer object.
-
-   ``k`` (integer/long) [unsigned long]
-      Convert a C :ctype:`unsigned long` to a Python long integer object.
-
-   ``L`` (long) [PY_LONG_LONG]
-      Convert a C :ctype:`long long` to a Python integer object. Only available
-      on platforms that support :ctype:`long long`.
-
-   ``K`` (long) [unsigned PY_LONG_LONG]
-      Convert a C :ctype:`unsigned long long` to a Python integer object. Only
-      available on platforms that support :ctype:`unsigned long long`.
-
-   ``n`` (int) [Py_ssize_t]
-      Convert a C :ctype:`Py_ssize_t` to a Python integer.
-
-   ``c`` (string of length 1) [char]
-      Convert a C :ctype:`int` representing a character to a Python string of length
-      1.
-
-   ``d`` (float) [double]
-      Convert a C :ctype:`double` to a Python floating point number.
-
-   ``f`` (float) [float]
-      Same as ``d``.
-
-   ``D`` (complex) [Py_complex \*]
-      Convert a C :ctype:`Py_complex` structure to a Python complex number.
-
-   ``O`` (object) [PyObject \*]
-      Pass a Python object untouched (except for its reference count, which is
-      incremented by one).  If the object passed in is a *NULL* pointer, it is assumed
-      that this was caused because the call producing the argument found an error and
-      set an exception. Therefore, :cfunc:`Py_BuildValue` will return *NULL* but won't
-      raise an exception.  If no exception has been raised yet, :exc:`SystemError` is
-      set.
-
-   ``S`` (object) [PyObject \*]
-      Same as ``O``.
-
-   ``N`` (object) [PyObject \*]
-      Same as ``O``, except it doesn't increment the reference count on the object.
-      Useful when the object is created by a call to an object constructor in the
-      argument list.
-
-   ``O&`` (object) [*converter*, *anything*]
-      Convert *anything* to a Python object through a *converter* function.  The
-      function is called with *anything* (which should be compatible with :ctype:`void
-      \*`) as its argument and should return a "new" Python object, or *NULL* if an
-      error occurred.
-
-   ``(items)`` (tuple) [*matching-items*]
-      Convert a sequence of C values to a Python tuple with the same number of items.
-
-   ``[items]`` (list) [*matching-items*]
-      Convert a sequence of C values to a Python list with the same number of items.
-
-   ``{items}`` (dictionary) [*matching-items*]
-      Convert a sequence of C values to a Python dictionary.  Each pair of consecutive
-      C values adds one item to the dictionary, serving as key and value,
-      respectively.
-
-   If there is an error in the format string, the :exc:`SystemError` exception is
-   set and *NULL* returned.
-
-
-.. _string-conversion:
-
-String conversion and formatting
-================================
-
-Functions for number conversion and formatted string output.
-
-
-.. cfunction:: int PyOS_snprintf(char *str, size_t size,  const char *format, ...)
-
-   Output not more than *size* bytes to *str* according to the format string
-   *format* and the extra arguments. See the Unix man page :manpage:`snprintf(2)`.
-
-
-.. cfunction:: int PyOS_vsnprintf(char *str, size_t size, const char *format, va_list va)
-
-   Output not more than *size* bytes to *str* according to the format string
-   *format* and the variable argument list *va*. Unix man page
-   :manpage:`vsnprintf(2)`.
-
-:cfunc:`PyOS_snprintf` and :cfunc:`PyOS_vsnprintf` wrap the Standard C library
-functions :cfunc:`snprintf` and :cfunc:`vsnprintf`. Their purpose is to
-guarantee consistent behavior in corner cases, which the Standard C functions do
-not.
-
-The wrappers ensure that *str*[*size*-1] is always ``'\0'`` upon return. They
-never write more than *size* bytes (including the trailing ``'\0'``) into str.
-Both functions require that ``str != NULL``, ``size > 0`` and ``format !=
-NULL``.
-
-If the platform doesn't have :cfunc:`vsnprintf` and the buffer size needed to
-avoid truncation exceeds *size* by more than 512 bytes, Python aborts with a
-*Py_FatalError*.
-
-The return value (*rv*) for these functions should be interpreted as follows:
-
-* When ``0 <= rv < size``, the output conversion was successful and *rv*
-  characters were written to *str* (excluding the trailing ``'\0'`` byte at
-  *str*[*rv*]).
-
-* When ``rv >= size``, the output conversion was truncated and a buffer with
-  ``rv + 1`` bytes would have been needed to succeed. *str*[*size*-1] is ``'\0'``
-  in this case.
-
-* When ``rv < 0``, "something bad happened." *str*[*size*-1] is ``'\0'`` in
-  this case too, but the rest of *str* is undefined. The exact cause of the error
-  depends on the underlying platform.
-
-The following functions provide locale-independent string to number conversions.
-
-
-.. cfunction:: double PyOS_ascii_strtod(const char *nptr, char **endptr)
-
-   Convert a string to a :ctype:`double`. This function behaves like the Standard C
-   function :cfunc:`strtod` does in the C locale. It does this without changing the
-   current locale, since that would not be thread-safe.
-
-   :cfunc:`PyOS_ascii_strtod` should typically be used for reading configuration
-   files or other non-user input that should be locale independent.
-
-   See the Unix man page :manpage:`strtod(2)` for details.
-
-
-.. cfunction:: char * PyOS_ascii_formatd(char *buffer, size_t buf_len, const char *format, double d)
-
-   Convert a :ctype:`double` to a string using the ``'.'`` as the decimal
-   separator. *format* is a :cfunc:`printf`\ -style format string specifying the
-   number format. Allowed conversion characters are ``'e'``, ``'E'``, ``'f'``,
-   ``'F'``, ``'g'`` and ``'G'``.
-
-   The return value is a pointer to *buffer* with the converted string or NULL if
-   the conversion failed.
-
-
-.. cfunction:: double PyOS_ascii_atof(const char *nptr)
-
-   Convert a string to a :ctype:`double` in a locale-independent way.
-
-   See the Unix man page :manpage:`atof(2)` for details.
-
-   
-.. cfunction:: char * PyOS_stricmp(char *s1, char *s2)
-
-   Case insensitive comparsion of strings. The functions works almost
-   identical to :cfunc:`strcmp` except that it ignores the case.
-
-
-.. cfunction:: char * PyOS_strnicmp(char *s1, char *s2, Py_ssize_t  size)
-
-   Case insensitive comparsion of strings. The functions works almost
-   identical to :cfunc:`strncmp` except that it ignores the case.
-
-
-.. _reflection:
-
-Reflection
-==========
-
-.. cfunction:: PyObject* PyEval_GetBuiltins()
-
-   Return a dictionary of the builtins in the current execution frame,
-   or the interpreter of the thread state if no frame is currently executing.
-
-
-.. cfunction:: PyObject* PyEval_GetLocals()
-
-   Return a dictionary of the local variables in the current execution frame,
-   or *NULL* if no frame is currently executing.
-   
-
-.. cfunction:: PyObject* PyEval_GetGlobals()
-
-   Return a dictionary of the global variables in the current execution frame,
-   or *NULL* if no frame is currently executing.
-
-
-.. cfunction:: PyFrameObject* PyEval_GetFrame()
-
-   Return the current thread state's frame, which is *NULL* if no frame is
-   currently executing.
-
-
-.. cfunction:: int PyEval_GetRestricted()
-
-   If there is a current frame and it is executing in restricted mode, return true,
-   otherwise false.
-
-
-.. cfunction:: const char* PyEval_GetFuncName(PyObject *func)
-
-   Return the name of *func* if it is a function, class or instance object, else the
-   name of *func*\s type.
-
-
-.. cfunction:: const char* PyEval_GetFuncDesc(PyObject *func)
-
-   Return a description string, depending on the type of *func*.
-   Return values include "()" for functions and methods, " constructor",
-   " instance", and " object".  Concatenated with the result of
-   :cfunc:`PyEval_GetFuncName`, the result will be a description of
-   *func*.
+   sys.rst
+   import.rst
+   marshal.rst
+   arg.rst
+   conversion.rst
+   reflection.rst

Added: python/branches/py3k/Doc/c-api/weakref.rst
==============================================================================
--- (empty file)
+++ python/branches/py3k/Doc/c-api/weakref.rst	Sun Jan 20 10:30:57 2008
@@ -0,0 +1,62 @@
+.. highlightlang:: c
+
+.. _weakrefobjects:
+
+Weak Reference Objects
+----------------------
+
+Python supports *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.
+
+
+.. cfunction:: int PyWeakref_Check(ob)
+
+   Return true if *ob* is either a reference or proxy object.
+
+
+.. cfunction:: int PyWeakref_CheckRef(ob)
+
+   Return true if *ob* is a reference object.
+
+
+.. cfunction:: int PyWeakref_CheckProxy(ob)
+
+   Return true if *ob* is a proxy object.
+
+
+.. cfunction:: PyObject* PyWeakref_NewRef(PyObject *ob, PyObject *callback)
+
+   Return a weak reference object for the object *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, *callback*, can be a
+   callable object that receives notification when *ob* is garbage collected; it
+   should accept a single parameter, which will be the weak reference object
+   itself. *callback* may also be ``None`` or *NULL*.  If *ob* is not a
+   weakly-referencable object, or if *callback* is not callable, ``None``, or
+   *NULL*, this will return *NULL* and raise :exc:`TypeError`.
+
+
+.. cfunction:: PyObject* PyWeakref_NewProxy(PyObject *ob, PyObject *callback)
+
+   Return a weak reference proxy object for the object *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, *callback*, can
+   be a callable object that receives notification when *ob* is garbage
+   collected; it should accept a single parameter, which will be the weak
+   reference object itself. *callback* may also be ``None`` or *NULL*.  If *ob*
+   is not a weakly-referencable object, or if *callback* is not callable,
+   ``None``, or *NULL*, this will return *NULL* and raise :exc:`TypeError`.
+
+
+.. cfunction:: PyObject* PyWeakref_GetObject(PyObject *ref)
+
+   Return the referenced object from a weak reference, *ref*.  If the referent is
+   no longer live, returns ``None``.
+
+
+.. cfunction:: PyObject* PyWeakref_GET_OBJECT(PyObject *ref)
+
+   Similar to :cfunc:`PyWeakref_GetObject`, but implemented as a macro that does no
+   error checking.
