--- Python-Docs-2.4/./api/concrete.tex	2004-11-22 22:02:31.000000000 +0900
+++ Python-Docs-2.5/./api/concrete.tex	2006-08-18 22:54:33.000000000 +0900
@@ -31,25 +31,25 @@
 
 \begin{cvardesc}{PyObject*}{PyType_Type}
   This is the type object for type objects; it is the same object as
-  \code{types.TypeType} in the Python layer.
+  \code{type} and \code{types.TypeType} in the Python layer.
   \withsubitem{(in module types)}{\ttindex{TypeType}}
 \end{cvardesc}
 
 \begin{cfuncdesc}{int}{PyType_Check}{PyObject *o}
-  Returns true if the object \var{o} is a type object, including
-  instances of types derived from the standard type object.  Returns
+  Return true if the object \var{o} is a type object, including
+  instances of types derived from the standard type object.  Return
   false in all other cases.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{int}{PyType_CheckExact}{PyObject *o}
-  Returns true if the object \var{o} is a type object, but not a
-  subtype of the standard type object.  Returns false in all other
+  Return true if the object \var{o} is a type object, but not a
+  subtype of the standard type object.  Return false in all other
   cases.
   \versionadded{2.2}
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{int}{PyType_HasFeature}{PyObject *o, int feature}
-  Returns true if the type object \var{o} sets the feature
+  Return true if the type object \var{o} sets the feature
   \var{feature}.  Type features are denoted by single bit flags.
 \end{cfuncdesc}
 
@@ -60,12 +60,12 @@
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{int}{PyType_IsSubtype}{PyTypeObject *a, PyTypeObject *b}
-  Returns true if \var{a} is a subtype of \var{b}.
+  Return true if \var{a} is a subtype of \var{b}.
   \versionadded{2.2}
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyType_GenericAlloc}{PyTypeObject *type,
-                                                  int nitems}
+                                                  Py_ssize_t nitems}
   \versionadded{2.2}
 \end{cfuncdesc}
 
@@ -77,8 +77,8 @@
 \begin{cfuncdesc}{int}{PyType_Ready}{PyTypeObject *type}
   Finalize a type object.  This should be called on all type objects
   to finish their initialization.  This function is responsible for
-  adding inherited slots from a type's base class.  Returns \code{0}
-  on success, or returns \code{-1} and sets an exception on error.
+  adding inherited slots from a type's base class.  Return \code{0}
+  on success, or return \code{-1} and sets an exception on error.
   \versionadded{2.2}
 \end{cfuncdesc}
 
@@ -98,7 +98,7 @@
 \end{cvardesc}
 
 \begin{csimplemacrodesc}{Py_RETURN_NONE}
-  Properly handles returning \cdata{Py_None} from within a C function.
+  Properly handle returning \cdata{Py_None} from within a C function.
 \end{csimplemacrodesc}
 
 
@@ -117,18 +117,19 @@
 
 \begin{cvardesc}{PyTypeObject}{PyInt_Type}
   This instance of \ctype{PyTypeObject} represents the Python plain
-  integer type.  This is the same object as \code{types.IntType}.
+  integer type.  This is the same object as \code{int} and
+  \code{types.IntType}.
   \withsubitem{(in modules types)}{\ttindex{IntType}}
 \end{cvardesc}
 
 \begin{cfuncdesc}{int}{PyInt_Check}{PyObject *o}
-  Returns true if \var{o} is of type \cdata{PyInt_Type} or a subtype
+  Return true if \var{o} is of type \cdata{PyInt_Type} or a subtype
   of \cdata{PyInt_Type}.
   \versionchanged[Allowed subtypes to be accepted]{2.2}
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{int}{PyInt_CheckExact}{PyObject *o}
-  Returns true if \var{o} is of type \cdata{PyInt_Type}, but not a
+  Return true if \var{o} is of type \cdata{PyInt_Type}, but not a
   subtype of \cdata{PyInt_Type}.
   \versionadded{2.2}
 \end{cfuncdesc}
@@ -153,22 +154,33 @@
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyInt_FromLong}{long ival}
-  Creates a new integer object with a value of \var{ival}.
+  Create a new integer object with a value of \var{ival}.
 
   The current implementation keeps an array of integer objects for all
-  integers between \code{-1} and \code{100}, when you create an int in
+  integers between \code{-5} and \code{256}, when you create an int in
   that range you actually just get back a reference to the existing
   object. So it should be possible to change the value of \code{1}.  I
   suspect the behaviour of Python in this case is undefined. :-)
 \end{cfuncdesc}
 
+\begin{cfuncdesc}{PyObject*}{PyInt_FromSsize_t}{Py_ssize_t ival}
+  Create a new integer object with a value of \var{ival}.
+  If the value exceeds \code{LONG_MAX}, a long integer object is
+  returned.
+
+ \versionadded{2.5}
+\end{cfuncdesc}
+
 \begin{cfuncdesc}{long}{PyInt_AsLong}{PyObject *io}
   Will first attempt to cast the object to a \ctype{PyIntObject}, if
-  it is not already one, and then return its value.
+  it is not already one, and then return its value. If there is an
+  error, \code{-1} is returned, and the caller should check
+  \code{PyErr_Occurred()} to find out whether there was an error, or
+  whether the value just happened to be -1.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{long}{PyInt_AS_LONG}{PyObject *io}
-  Returns the value of the object \var{io}.  No error checking is
+  Return the value of the object \var{io}.  No error checking is
   performed.
 \end{cfuncdesc}
 
@@ -179,15 +191,22 @@
   \versionadded{2.3}
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{unsigned long long}{PyInt_AsUnsignedLongLongMask}{PyObject *io}
+\begin{cfuncdesc}{unsigned PY_LONG_LONG}{PyInt_AsUnsignedLongLongMask}{PyObject *io}
   Will first attempt to cast the object to a \ctype{PyIntObject} or
   \ctype{PyLongObject}, if it is not already one, and then return its
   value as unsigned long long, without checking for overflow.
   \versionadded{2.3}
 \end{cfuncdesc}
 
+\begin{cfuncdesc}{Py_ssize_t}{PyInt_AsSsize_t}{PyObject *io}
+  Will first attempt to cast the object to a \ctype{PyIntObject} or
+  \ctype{PyLongObject}, if it is not already one, and then return its
+  value as \ctype{Py_ssize_t}.
+  \versionadded{2.5}
+\end{cfuncdesc}
+
 \begin{cfuncdesc}{long}{PyInt_GetMax}{}
-  Returns the system's idea of the largest integer it can handle
+  Return the system's idea of the largest integer it can handle
   (\constant{LONG_MAX}\ttindex{LONG_MAX}, as defined in the system
   header files).
 \end{cfuncdesc}
@@ -200,7 +219,7 @@
 booleans.  The following macros are available, however.
 
 \begin{cfuncdesc}{int}{PyBool_Check}{PyObject *o}
-  Returns true if \var{o} is of type \cdata{PyBool_Type}.
+  Return true if \var{o} is of type \cdata{PyBool_Type}.
   \versionadded{2.3}
 \end{cfuncdesc}
 
@@ -226,9 +245,9 @@
 \versionadded{2.4}
 \end{csimplemacrodesc}
 
-\begin{cfuncdesc}{int}{PyBool_FromLong}{long v}
-Returns \constant{Py_True} or \constant{Py_False} depending on the
-truth value of \var{v}.
+\begin{cfuncdesc}{PyObject*}{PyBool_FromLong}{long v}
+  Return a new reference to \constant{Py_True} or \constant{Py_False}
+  depending on the truth value of \var{v}.
 \versionadded{2.3}
 \end{cfuncdesc}
 
@@ -242,44 +261,45 @@
 
 \begin{cvardesc}{PyTypeObject}{PyLong_Type}
   This instance of \ctype{PyTypeObject} represents the Python long
-  integer type.  This is the same object as \code{types.LongType}.
+  integer type.  This is the same object as \code{long} and
+  \code{types.LongType}.
   \withsubitem{(in modules types)}{\ttindex{LongType}}
 \end{cvardesc}
 
 \begin{cfuncdesc}{int}{PyLong_Check}{PyObject *p}
-  Returns true if its argument is a \ctype{PyLongObject} or a subtype
+  Return true if its argument is a \ctype{PyLongObject} or a subtype
   of \ctype{PyLongObject}.
   \versionchanged[Allowed subtypes to be accepted]{2.2}
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{int}{PyLong_CheckExact}{PyObject *p}
-  Returns true if its argument is a \ctype{PyLongObject}, but not a
+  Return true if its argument is a \ctype{PyLongObject}, but not a
   subtype of \ctype{PyLongObject}.
   \versionadded{2.2}
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyLong_FromLong}{long v}
-  Returns a new \ctype{PyLongObject} object from \var{v}, or \NULL{}
+  Return a new \ctype{PyLongObject} object from \var{v}, or \NULL{}
   on failure.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyLong_FromUnsignedLong}{unsigned long v}
-  Returns a new \ctype{PyLongObject} object from a C \ctype{unsigned
+  Return a new \ctype{PyLongObject} object from a C \ctype{unsigned
   long}, or \NULL{} on failure.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyObject*}{PyLong_FromLongLong}{long long v}
-  Returns a new \ctype{PyLongObject} object from a C \ctype{long long},
+\begin{cfuncdesc}{PyObject*}{PyLong_FromLongLong}{PY_LONG_LONG v}
+  Return a new \ctype{PyLongObject} object from a C \ctype{long long},
   or \NULL{} on failure.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyObject*}{PyLong_FromUnsignedLongLong}{unsigned long long v}
-  Returns a new \ctype{PyLongObject} object from a C \ctype{unsigned
+\begin{cfuncdesc}{PyObject*}{PyLong_FromUnsignedLongLong}{unsigned PY_LONG_LONG v}
+  Return a new \ctype{PyLongObject} object from a C \ctype{unsigned
   long long}, or \NULL{} on failure.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyLong_FromDouble}{double v}
-  Returns a new \ctype{PyLongObject} object from the integer part of
+  Return a new \ctype{PyLongObject} object from the integer part of
   \var{v}, or \NULL{} on failure.
 \end{cfuncdesc}
 
@@ -300,7 +320,7 @@
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyLong_FromUnicode}{Py_UNICODE *u,
-                                                 int length, int base}
+                                                 Py_ssize_t length, int base}
   Convert a sequence of Unicode digits to a Python long integer
   value.  The first parameter, \var{u}, points to the first character
   of the Unicode string, \var{length} gives the number of characters,
@@ -315,10 +335,12 @@
   The pointer value can be retrieved from the resulting value using
   \cfunction{PyLong_AsVoidPtr()}.
   \versionadded{1.5.2}
-\end{cfuncdesc}
+  \versionchanged[If the integer is larger than LONG_MAX,
+  a positive long integer is returned]{2.5}
+ \end{cfuncdesc}
 
 \begin{cfuncdesc}{long}{PyLong_AsLong}{PyObject *pylong}
-  Returns a C \ctype{long} representation of the contents of
+  Return a C \ctype{long} representation of the contents of
   \var{pylong}.  If \var{pylong} is greater than
   \constant{LONG_MAX}\ttindex{LONG_MAX}, an \exception{OverflowError}
   is raised.
@@ -326,21 +348,21 @@
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{unsigned long}{PyLong_AsUnsignedLong}{PyObject *pylong}
-  Returns a C \ctype{unsigned long} representation of the contents of
+  Return a C \ctype{unsigned long} representation of the contents of
   \var{pylong}.  If \var{pylong} is greater than
   \constant{ULONG_MAX}\ttindex{ULONG_MAX}, an
   \exception{OverflowError} is raised.
   \withsubitem{(built-in exception)}{\ttindex{OverflowError}}
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{long long}{PyLong_AsLongLong}{PyObject *pylong}
+\begin{cfuncdesc}{PY_LONG_LONG}{PyLong_AsLongLong}{PyObject *pylong}
   Return a C \ctype{long long} from a Python long integer.  If
   \var{pylong} cannot be represented as a \ctype{long long}, an
   \exception{OverflowError} will be raised.
   \versionadded{2.2}
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{unsigned long long}{PyLong_AsUnsignedLongLong}{PyObject
+\begin{cfuncdesc}{unsigned PY_LONG_LONG}{PyLong_AsUnsignedLongLong}{PyObject
                                                                  *pylong}
   Return a C \ctype{unsigned long long} from a Python long integer.
   If \var{pylong} cannot be represented as an \ctype{unsigned long
@@ -356,14 +378,14 @@
   \versionadded{2.3}
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{unsigned long}{PyLong_AsUnsignedLongLongMask}{PyObject *io}
+\begin{cfuncdesc}{unsigned PY_LONG_LONG}{PyLong_AsUnsignedLongLongMask}{PyObject *io}
   Return a C \ctype{unsigned long long} from a Python long integer, without
   checking for overflow.
   \versionadded{2.3}
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{double}{PyLong_AsDouble}{PyObject *pylong}
-  Returns a C \ctype{double} representation of the contents of
+  Return a C \ctype{double} representation of the contents of
   \var{pylong}.  If \var{pylong} cannot be approximately represented
   as a \ctype{double}, an \exception{OverflowError} exception is
   raised and \code{-1.0} will be returned.
@@ -376,6 +398,8 @@
   produce a usable \ctype{void} pointer for values created with
   \cfunction{PyLong_FromVoidPtr()}.
   \versionadded{1.5.2}
+  \versionchanged[For values outside 0..LONG_MAX, both signed and
+  unsigned integers are acccepted]{2.5}
 \end{cfuncdesc}
 
 
@@ -389,40 +413,41 @@
 
 \begin{cvardesc}{PyTypeObject}{PyFloat_Type}
   This instance of \ctype{PyTypeObject} represents the Python floating
-  point type.  This is the same object as \code{types.FloatType}.
+  point type.  This is the same object as \code{float} and
+  \code{types.FloatType}.
   \withsubitem{(in modules types)}{\ttindex{FloatType}}
 \end{cvardesc}
 
 \begin{cfuncdesc}{int}{PyFloat_Check}{PyObject *p}
-  Returns true if its argument is a \ctype{PyFloatObject} or a subtype
+  Return true if its argument is a \ctype{PyFloatObject} or a subtype
   of \ctype{PyFloatObject}.
   \versionchanged[Allowed subtypes to be accepted]{2.2}
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{int}{PyFloat_CheckExact}{PyObject *p}
-  Returns true if its argument is a \ctype{PyFloatObject}, but not a
+  Return true if its argument is a \ctype{PyFloatObject}, but not a
   subtype of \ctype{PyFloatObject}.
   \versionadded{2.2}
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyFloat_FromString}{PyObject *str, char **pend}
-  Creates a \ctype{PyFloatObject} object based on the string value in
+  Create a \ctype{PyFloatObject} object based on the string value in
   \var{str}, or \NULL{} on failure.  The \var{pend} argument is ignored.  It
   remains only for backward compatibility.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyFloat_FromDouble}{double v}
-  Creates a \ctype{PyFloatObject} object from \var{v}, or \NULL{} on
+  Create a \ctype{PyFloatObject} object from \var{v}, or \NULL{} on
   failure.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{double}{PyFloat_AsDouble}{PyObject *pyfloat}
-  Returns a C \ctype{double} representation of the contents of
+  Return a C \ctype{double} representation of the contents of
   \var{pyfloat}.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{double}{PyFloat_AS_DOUBLE}{PyObject *pyfloat}
-  Returns a C \ctype{double} representation of the contents of
+  Return a C \ctype{double} representation of the contents of
   \var{pyfloat}, but without error checking.
 \end{cfuncdesc}
 
@@ -498,17 +523,18 @@
 
 \begin{cvardesc}{PyTypeObject}{PyComplex_Type}
   This instance of \ctype{PyTypeObject} represents the Python complex
-  number type.
+  number type. It is the same object as \code{complex} and
+  \code{types.ComplexType}.
 \end{cvardesc}
 
 \begin{cfuncdesc}{int}{PyComplex_Check}{PyObject *p}
-  Returns true if its argument is a \ctype{PyComplexObject} or a
+  Return true if its argument is a \ctype{PyComplexObject} or a
   subtype of \ctype{PyComplexObject}.
   \versionchanged[Allowed subtypes to be accepted]{2.2}
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{int}{PyComplex_CheckExact}{PyObject *p}
-  Returns true if its argument is a \ctype{PyComplexObject}, but not a
+  Return true if its argument is a \ctype{PyComplexObject}, but not a
   subtype of \ctype{PyComplexObject}.
   \versionadded{2.2}
 \end{cfuncdesc}
@@ -519,20 +545,20 @@
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyComplex_FromDoubles}{double real, double imag}
-  Returns a new \ctype{PyComplexObject} object from \var{real} and
+  Return a new \ctype{PyComplexObject} object from \var{real} and
   \var{imag}.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{double}{PyComplex_RealAsDouble}{PyObject *op}
-  Returns the real part of \var{op} as a C \ctype{double}.
+  Return the real part of \var{op} as a C \ctype{double}.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{double}{PyComplex_ImagAsDouble}{PyObject *op}
-  Returns the imaginary part of \var{op} as a C \ctype{double}.
+  Return the imaginary part of \var{op} as a C \ctype{double}.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{Py_complex}{PyComplex_AsCComplex}{PyObject *op}
-  Returns the \ctype{Py_complex} value of the complex number
+  Return the \ctype{Py_complex} value of the complex number
   \var{op}.
 \end{cfuncdesc}
 
@@ -558,49 +584,62 @@
 
 \begin{cvardesc}{PyTypeObject}{PyString_Type}
   This instance of \ctype{PyTypeObject} represents the Python string
-  type; it is the same object as \code{types.TypeType} in the Python
-  layer.
+  type; it is the same object as \code{str} and \code{types.StringType}
+  in the Python layer.
   \withsubitem{(in module types)}{\ttindex{StringType}}.
 \end{cvardesc}
 
 \begin{cfuncdesc}{int}{PyString_Check}{PyObject *o}
-  Returns true if the object \var{o} is a string object or an instance
+  Return true if the object \var{o} is a string object or an instance
   of a subtype of the string type.
   \versionchanged[Allowed subtypes to be accepted]{2.2}
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{int}{PyString_CheckExact}{PyObject *o}
-  Returns true if the object \var{o} is a string object, but not an
+  Return true if the object \var{o} is a string object, but not an
   instance of a subtype of the string type.
   \versionadded{2.2}
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyString_FromString}{const char *v}
-  Returns a new string object with the value \var{v} on success, and
+  Return a new string object with the value \var{v} on success, and
   \NULL{} on failure.  The parameter \var{v} must not be \NULL{}; it
   will not be checked.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyString_FromStringAndSize}{const char *v,
-                                                         int len}
-  Returns a new string object with the value \var{v} and length
+                                                         Py_ssize_t len}
+  Return a new string object with the value \var{v} and length
   \var{len} on success, and \NULL{} on failure.  If \var{v} is
   \NULL{}, the contents of the string are uninitialized.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyString_FromFormat}{const char *format, ...}
-  Takes a C \cfunction{printf()}-style \var{format} string and a
-  variable number of arguments, calculates the size of the resulting
-  Python string and returns a string with the values formatted into
+  Take a C \cfunction{printf()}-style \var{format} string and a
+  variable number of arguments, calculate the size of the resulting
+  Python string and return a string with the values formatted into
   it.  The variable arguments must be C types and must correspond
   exactly to the format characters in the \var{format} string.  The
   following format characters are allowed:
 
+  % This should be exactly the same as the table in PyErr_Format.
+  % One should just refer to the other.
+
+  % The descriptions for %zd and %zu are wrong, but the truth is complicated
+  % because not all compilers support the %z width modifier -- we fake it
+  % when necessary via interpolating PY_FORMAT_SIZE_T.
+
+  % %u, %lu, %zu should have "new in Python 2.5" blurbs.
+
   \begin{tableiii}{l|l|l}{member}{Format Characters}{Type}{Comment}
     \lineiii{\%\%}{\emph{n/a}}{The literal \% character.}
     \lineiii{\%c}{int}{A single character, represented as an C int.}
     \lineiii{\%d}{int}{Exactly equivalent to \code{printf("\%d")}.}
+    \lineiii{\%u}{unsigned int}{Exactly equivalent to \code{printf("\%u")}.}
     \lineiii{\%ld}{long}{Exactly equivalent to \code{printf("\%ld")}.}
+    \lineiii{\%lu}{unsigned long}{Exactly equivalent to \code{printf("\%lu")}.}
+    \lineiii{\%zd}{Py_ssize_t}{Exactly equivalent to \code{printf("\%zd")}.}
+    \lineiii{\%zu}{size_t}{Exactly equivalent to \code{printf("\%zu")}.}
     \lineiii{\%i}{int}{Exactly equivalent to \code{printf("\%i")}.}
     \lineiii{\%x}{int}{Exactly equivalent to \code{printf("\%x")}.}
     \lineiii{\%s}{char*}{A null-terminated C character array.}
@@ -609,6 +648,10 @@
 	guaranteed to start with the literal \code{0x} regardless of
 	what the platform's \code{printf} yields.}
   \end{tableiii}
+
+  An unrecognized format character causes all the rest of the format
+  string to be copied as-is to the result string, and any extra
+  arguments discarded.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyString_FromFormatV}{const char *format,
@@ -617,17 +660,17 @@
   exactly two arguments.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyString_Size}{PyObject *string}
-  Returns the length of the string in string object \var{string}.
+\begin{cfuncdesc}{Py_ssize_t}{PyString_Size}{PyObject *string}
+  Return the length of the string in string object \var{string}.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyString_GET_SIZE}{PyObject *string}
+\begin{cfuncdesc}{Py_ssize_t}{PyString_GET_SIZE}{PyObject *string}
   Macro form of \cfunction{PyString_Size()} but without error
   checking.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{char*}{PyString_AsString}{PyObject *string}
-  Returns a NUL-terminated representation of the contents of
+  Return a NUL-terminated representation of the contents of
   \var{string}.  The pointer refers to the internal buffer of
   \var{string}, not a copy.  The data must not be modified in any way,
   unless the string was just created using
@@ -647,8 +690,8 @@
 
 \begin{cfuncdesc}{int}{PyString_AsStringAndSize}{PyObject *obj,
                                                  char **buffer,
-                                                 int *length}
-  Returns a NUL-terminated representation of the contents of the
+                                                 Py_ssize_t *length}
+  Return a NUL-terminated representation of the contents of the
   object \var{obj} through the output variables \var{buffer} and
   \var{length}.
 
@@ -664,13 +707,13 @@
   \var{size})}.  It must not be deallocated.  If \var{string} is a
   Unicode object, this function computes the default encoding of
   \var{string} and operates on that.  If \var{string} is not a string
-  object at all, \cfunction{PyString_AsString()} returns \NULL{} and
-  raises \exception{TypeError}.
+  object at all, \cfunction{PyString_AsStringAndSize()} returns
+  \code{-1} and raises \exception{TypeError}.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{void}{PyString_Concat}{PyObject **string,
                                          PyObject *newpart}
-  Creates a new string object in \var{*string} containing the contents
+  Create a new string object in \var{*string} containing the contents
   of \var{newpart} appended to \var{string}; the caller will own the
   new reference.  The reference to the old value of \var{string} will
   be stolen.  If the new string cannot be created, the old reference
@@ -681,12 +724,12 @@
 
 \begin{cfuncdesc}{void}{PyString_ConcatAndDel}{PyObject **string,
                                                PyObject *newpart}
-  Creates a new string object in \var{*string} containing the contents
+  Create a new string object in \var{*string} containing the contents
   of \var{newpart} appended to \var{string}.  This version decrements
   the reference count of \var{newpart}.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{_PyString_Resize}{PyObject **string, int newsize}
+\begin{cfuncdesc}{int}{_PyString_Resize}{PyObject **string, Py_ssize_t newsize}
   A way to resize a string object even though it is ``immutable''.
   Only use this to build up a brand new string object; don't use this
   if the string may already be known in other parts of the code.  It
@@ -703,7 +746,7 @@
 
 \begin{cfuncdesc}{PyObject*}{PyString_Format}{PyObject *format,
                                               PyObject *args}
-  Returns a new string object from \var{format} and \var{args}.
+  Return a new string object from \var{format} and \var{args}.
   Analogous to \code{\var{format} \%\ \var{args}}.  The \var{args}
   argument must be a tuple.
 \end{cfuncdesc}
@@ -730,51 +773,51 @@
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyString_Decode}{const char *s,
-                                               int size,
+                                               Py_ssize_t size,
                                                const char *encoding,
                                                const char *errors}
-  Creates an object by decoding \var{size} bytes of the encoded
+  Create an object by decoding \var{size} bytes of the encoded
   buffer \var{s} using the codec registered for
   \var{encoding}.  \var{encoding} and \var{errors} have the same
   meaning as the parameters of the same name in the
   \function{unicode()} built-in function.  The codec to be used is
-  looked up using the Python codec registry.  Returns \NULL{} if
+  looked up using the Python codec registry.  Return \NULL{} if
   an exception was raised by the codec.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyString_AsDecodedObject}{PyObject *str,
                                                const char *encoding,
                                                const char *errors}
-  Decodes a string object by passing it to the codec registered for
-  \var{encoding} and returns the result as Python
+  Decode a string object by passing it to the codec registered for
+  \var{encoding} and return the result as Python
   object. \var{encoding} and \var{errors} have the same meaning as the
   parameters of the same name in the string \method{encode()} method.
   The codec to be used is looked up using the Python codec registry.
-  Returns \NULL{} if an exception was raised by the codec.
+  Return \NULL{} if an exception was raised by the codec.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyString_Encode}{const char *s,
-                                               int size,
+                                               Py_ssize_t size,
                                                const char *encoding,
                                                const char *errors}
-  Encodes the \ctype{char} buffer of the given size by passing it to
-  the codec registered for \var{encoding} and returns a Python object.
+  Encode the \ctype{char} buffer of the given size by passing it to
+  the codec registered for \var{encoding} and return a Python object.
   \var{encoding} and \var{errors} have the same meaning as the
   parameters of the same name in the string \method{encode()} method.
   The codec to be used is looked up using the Python codec
-  registry.  Returns \NULL{} if an exception was raised by the
+  registry.  Return \NULL{} if an exception was raised by the
   codec.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyString_AsEncodedObject}{PyObject *str,
                                                const char *encoding,
                                                const char *errors}
-  Encodes a string object using the codec registered for
-  \var{encoding} and returns the result as Python object.
+  Encode a string object using the codec registered for
+  \var{encoding} and return the result as Python object.
   \var{encoding} and \var{errors} have the same meaning as the
   parameters of the same name in the string \method{encode()} method.
   The codec to be used is looked up using the Python codec registry.
-  Returns \NULL{} if an exception was raised by the codec.
+  Return \NULL{} if an exception was raised by the codec.
 \end{cfuncdesc}
 
 
@@ -787,55 +830,66 @@
 implementation in Python:
 
 \begin{ctypedesc}{Py_UNICODE}
-  This type represents a 16-bit unsigned storage type which is used by
-  Python internally as basis for holding Unicode ordinals.  On
-  platforms where \ctype{wchar_t} is available and also has 16-bits,
-  \ctype{Py_UNICODE} is a typedef alias for \ctype{wchar_t} to enhance
-  native platform compatibility.  On all other platforms,
-  \ctype{Py_UNICODE} is a typedef alias for \ctype{unsigned short}.
+  This type represents the storage type which is used by Python
+  internally as basis for holding Unicode ordinals.  Python's default
+  builds use a 16-bit type for \ctype{Py_UNICODE} and store Unicode
+  values internally as UCS2. It is also possible to build a UCS4
+  version of Python (most recent Linux distributions come with UCS4
+  builds of Python). These builds then use a 32-bit type for
+  \ctype{Py_UNICODE} and store Unicode data internally as UCS4. On
+  platforms where \ctype{wchar_t} is available and compatible with the
+  chosen Python Unicode build variant, \ctype{Py_UNICODE} is a typedef
+  alias for \ctype{wchar_t} to enhance native platform compatibility.
+  On all other platforms, \ctype{Py_UNICODE} is a typedef alias for
+  either \ctype{unsigned short} (UCS2) or \ctype{unsigned long}
+  (UCS4).
 \end{ctypedesc}
 
+Note that UCS2 and UCS4 Python builds are not binary compatible.
+Please keep this in mind when writing extensions or interfaces.
+
 \begin{ctypedesc}{PyUnicodeObject}
   This subtype of \ctype{PyObject} represents a Python Unicode object.
 \end{ctypedesc}
 
 \begin{cvardesc}{PyTypeObject}{PyUnicode_Type}
   This instance of \ctype{PyTypeObject} represents the Python Unicode
-  type.
+  type.  It is exposed to Python code as \code{unicode} and
+  \code{types.UnicodeType}.
 \end{cvardesc}
 
 The following APIs are really C macros and can be used to do fast
 checks and to access internal read-only data of Unicode objects:
 
 \begin{cfuncdesc}{int}{PyUnicode_Check}{PyObject *o}
-  Returns true if the object \var{o} is a Unicode object or an
+  Return true if the object \var{o} is a Unicode object or an
   instance of a Unicode subtype.
   \versionchanged[Allowed subtypes to be accepted]{2.2}
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{int}{PyUnicode_CheckExact}{PyObject *o}
-  Returns true if the object \var{o} is a Unicode object, but not an
+  Return true if the object \var{o} is a Unicode object, but not an
   instance of a subtype.
   \versionadded{2.2}
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyUnicode_GET_SIZE}{PyObject *o}
-  Returns the size of the object.  \var{o} has to be a
+\begin{cfuncdesc}{Py_ssize_t}{PyUnicode_GET_SIZE}{PyObject *o}
+  Return the size of the object.  \var{o} has to be a
   \ctype{PyUnicodeObject} (not checked).
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyUnicode_GET_DATA_SIZE}{PyObject *o}
-  Returns the size of the object's internal buffer in bytes.  \var{o}
+\begin{cfuncdesc}{Py_ssize_t}{PyUnicode_GET_DATA_SIZE}{PyObject *o}
+  Return the size of the object's internal buffer in bytes.  \var{o}
   has to be a \ctype{PyUnicodeObject} (not checked).
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{Py_UNICODE*}{PyUnicode_AS_UNICODE}{PyObject *o}
-  Returns a pointer to the internal \ctype{Py_UNICODE} buffer of the
+  Return a pointer to the internal \ctype{Py_UNICODE} buffer of the
   object.  \var{o} has to be a \ctype{PyUnicodeObject} (not checked).
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{const char*}{PyUnicode_AS_DATA}{PyObject *o}
-  Returns a pointer to the internal buffer of the object.
+  Return a pointer to the internal buffer of the object.
   \var{o} has to be a \ctype{PyUnicodeObject} (not checked).
 \end{cfuncdesc}
 
@@ -846,78 +900,78 @@
 functions depending on the Python configuration.
 
 \begin{cfuncdesc}{int}{Py_UNICODE_ISSPACE}{Py_UNICODE ch}
-  Returns 1/0 depending on whether \var{ch} is a whitespace
+  Return 1 or 0 depending on whether \var{ch} is a whitespace
   character.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{int}{Py_UNICODE_ISLOWER}{Py_UNICODE ch}
-  Returns 1/0 depending on whether \var{ch} is a lowercase character.
+  Return 1 or 0 depending on whether \var{ch} is a lowercase character.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{int}{Py_UNICODE_ISUPPER}{Py_UNICODE ch}
-  Returns 1/0 depending on whether \var{ch} is an uppercase
+  Return 1 or 0 depending on whether \var{ch} is an uppercase
   character.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{int}{Py_UNICODE_ISTITLE}{Py_UNICODE ch}
-  Returns 1/0 depending on whether \var{ch} is a titlecase character.
+  Return 1 or 0 depending on whether \var{ch} is a titlecase character.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{int}{Py_UNICODE_ISLINEBREAK}{Py_UNICODE ch}
-  Returns 1/0 depending on whether \var{ch} is a linebreak character.
+  Return 1 or 0 depending on whether \var{ch} is a linebreak character.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{int}{Py_UNICODE_ISDECIMAL}{Py_UNICODE ch}
-  Returns 1/0 depending on whether \var{ch} is a decimal character.
+  Return 1 or 0 depending on whether \var{ch} is a decimal character.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{int}{Py_UNICODE_ISDIGIT}{Py_UNICODE ch}
-  Returns 1/0 depending on whether \var{ch} is a digit character.
+  Return 1 or 0 depending on whether \var{ch} is a digit character.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{int}{Py_UNICODE_ISNUMERIC}{Py_UNICODE ch}
-  Returns 1/0 depending on whether \var{ch} is a numeric character.
+  Return 1 or 0 depending on whether \var{ch} is a numeric character.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{int}{Py_UNICODE_ISALPHA}{Py_UNICODE ch}
-  Returns 1/0 depending on whether \var{ch} is an alphabetic
+  Return 1 or 0 depending on whether \var{ch} is an alphabetic
   character.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{int}{Py_UNICODE_ISALNUM}{Py_UNICODE ch}
-  Returns 1/0 depending on whether \var{ch} is an alphanumeric
+  Return 1 or 0 depending on whether \var{ch} is an alphanumeric
   character.
 \end{cfuncdesc}
 
 These APIs can be used for fast direct character conversions:
 
 \begin{cfuncdesc}{Py_UNICODE}{Py_UNICODE_TOLOWER}{Py_UNICODE ch}
-  Returns the character \var{ch} converted to lower case.
+  Return the character \var{ch} converted to lower case.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{Py_UNICODE}{Py_UNICODE_TOUPPER}{Py_UNICODE ch}
-  Returns the character \var{ch} converted to upper case.
+  Return the character \var{ch} converted to upper case.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{Py_UNICODE}{Py_UNICODE_TOTITLE}{Py_UNICODE ch}
-  Returns the character \var{ch} converted to title case.
+  Return the character \var{ch} converted to title case.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{int}{Py_UNICODE_TODECIMAL}{Py_UNICODE ch}
-  Returns the character \var{ch} converted to a decimal positive
-  integer.  Returns \code{-1} if this is not possible.  Does not raise
-  exceptions.
+  Return the character \var{ch} converted to a decimal positive
+  integer.  Return \code{-1} if this is not possible.  This macro
+  does not raise exceptions.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{int}{Py_UNICODE_TODIGIT}{Py_UNICODE ch}
-  Returns the character \var{ch} converted to a single digit integer.
-  Returns \code{-1} if this is not possible.  Does not raise
+  Return the character \var{ch} converted to a single digit integer.
+  Return \code{-1} if this is not possible.  This macro does not raise
   exceptions.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{double}{Py_UNICODE_TONUMERIC}{Py_UNICODE ch}
-  Returns the character \var{ch} converted to a (positive) double.
-  Returns \code{-1.0} if this is not possible.  Does not raise
+  Return the character \var{ch} converted to a double.
+  Return \code{-1.0} if this is not possible.  This macro does not raise
   exceptions.
 \end{cfuncdesc}
 
@@ -927,7 +981,7 @@
 use these APIs:
 
 \begin{cfuncdesc}{PyObject*}{PyUnicode_FromUnicode}{const Py_UNICODE *u,
-                                                    int size}
+                                                    Py_ssize_t size}
   Create a Unicode Object from the Py_UNICODE buffer \var{u} of the
   given size. \var{u} may be \NULL{} which causes the contents to be
   undefined. It is the user's responsibility to fill in the needed
@@ -943,7 +997,7 @@
   object.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyUnicode_GetSize}{PyObject *unicode}
+\begin{cfuncdesc}{Py_ssize_t}{PyUnicode_GetSize}{PyObject *unicode}
   Return the length of the Unicode object.
 \end{cfuncdesc}
 
@@ -952,21 +1006,14 @@
                                                       const char *errors}
   Coerce an encoded object \var{obj} to an Unicode object and return a
   reference with incremented refcount.
+  
+  String and other char buffer compatible objects are decoded
+  according to the given encoding and using the error handling
+  defined by errors.  Both can be \NULL{} to have the interface
+  use the default values (see the next section for details).
 
-  Coercion is done in the following way:
-
-\begin{enumerate}
-\item  Unicode objects are passed back as-is with incremented
-       refcount. \note{These cannot be decoded; passing a non-\NULL{}
-       value for encoding will result in a \exception{TypeError}.}
-
-\item String and other char buffer compatible objects are decoded
-      according to the given encoding and using the error handling
-      defined by errors.  Both can be \NULL{} to have the interface
-      use the default values (see the next section for details).
-
-\item All other objects cause an exception.
-\end{enumerate}
+  All other objects, including Unicode objects, cause a
+  \exception{TypeError} to be set.
 
   The API returns \NULL{} if there was an error.  The caller is
   responsible for decref'ing the returned objects.
@@ -986,17 +1033,17 @@
 \ctype{Py_UNICODE} type is identical to the system's \ctype{wchar_t}.
 
 \begin{cfuncdesc}{PyObject*}{PyUnicode_FromWideChar}{const wchar_t *w,
-                                                     int size}
+                                                     Py_ssize_t size}
   Create a Unicode object from the \ctype{wchar_t} buffer \var{w} of
-  the given size.  Returns \NULL{} on failure.
+  the given size.  Return \NULL{} on failure.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyUnicode_AsWideChar}{PyUnicodeObject *unicode,
+\begin{cfuncdesc}{Py_ssize_t}{PyUnicode_AsWideChar}{PyUnicodeObject *unicode,
                                              wchar_t *w,
-                                             int size}
-  Copies the Unicode object contents into the \ctype{wchar_t} buffer
+                                             Py_ssize_t size}
+  Copy the Unicode object contents into the \ctype{wchar_t} buffer
   \var{w}.  At most \var{size} \ctype{wchar_t} characters are copied
-  (excluding a possibly trailing 0-termination character).  Returns
+  (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
@@ -1035,37 +1082,37 @@
 These are the generic codec APIs:
 
 \begin{cfuncdesc}{PyObject*}{PyUnicode_Decode}{const char *s,
-                                               int size,
+                                               Py_ssize_t size,
                                                const char *encoding,
                                                const char *errors}
   Create a Unicode object by decoding \var{size} bytes of the encoded
   string \var{s}.  \var{encoding} and \var{errors} have the same
   meaning as the parameters of the same name in the
   \function{unicode()} builtin function.  The codec to be used is
-  looked up using the Python codec registry.  Returns \NULL{} if an
+  looked up using the Python codec registry.  Return \NULL{} if an
   exception was raised by the codec.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyUnicode_Encode}{const Py_UNICODE *s,
-                                               int size,
+                                               Py_ssize_t size,
                                                const char *encoding,
                                                const char *errors}
-  Encodes the \ctype{Py_UNICODE} buffer of the given size and returns
+  Encode the \ctype{Py_UNICODE} buffer of the given size and return
   a Python string object.  \var{encoding} and \var{errors} have the
   same meaning as the parameters of the same name in the Unicode
   \method{encode()} method.  The codec to be used is looked up using
-  the Python codec registry.  Returns \NULL{} if an exception was
+  the Python codec registry.  Return \NULL{} if an exception was
   raised by the codec.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyUnicode_AsEncodedString}{PyObject *unicode,
                                                const char *encoding,
                                                const char *errors}
-  Encodes a Unicode object and returns the result as Python string
+  Encode a Unicode object and return the result as Python string
   object. \var{encoding} and \var{errors} have the same meaning as the
   parameters of the same name in the Unicode \method{encode()} method.
   The codec to be used is looked up using the Python codec registry.
-  Returns \NULL{} if an exception was raised by the codec.
+  Return \NULL{} if an exception was raised by the codec.
 \end{cfuncdesc}
 
 % --- UTF-8 Codecs -------------------------------------------------------
@@ -1073,18 +1120,18 @@
 These are the UTF-8 codec APIs:
 
 \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF8}{const char *s,
-                                               int size,
+                                               Py_ssize_t size,
                                                const char *errors}
-  Creates a Unicode object by decoding \var{size} bytes of the UTF-8
-  encoded string \var{s}. Returns \NULL{} if an exception was raised
+  Create a Unicode object by decoding \var{size} bytes of the UTF-8
+  encoded string \var{s}. Return \NULL{} if an exception was raised
   by the codec.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF8Stateful}{const char *s,
-                                               int size,
+                                               Py_ssize_t size,
                                                const char *errors,
-                                               int *consumed}
-  If \var{consumed} is \NULL{}, behaves like \cfunction{PyUnicode_DecodeUTF8()}.
+                                               Py_ssize_t *consumed}
+  If \var{consumed} is \NULL{}, behave like \cfunction{PyUnicode_DecodeUTF8()}.
   If \var{consumed} is not \NULL{}, trailing incomplete UTF-8 byte sequences
   will not be treated as an error. Those bytes will not be decoded and the
   number of bytes that have been decoded will be stored in \var{consumed}.
@@ -1092,16 +1139,16 @@
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeUTF8}{const Py_UNICODE *s,
-                                               int size,
+                                               Py_ssize_t size,
                                                const char *errors}
-  Encodes the \ctype{Py_UNICODE} buffer of the given size using UTF-8
-  and returns a Python string object.  Returns \NULL{} if an exception
+  Encode the \ctype{Py_UNICODE} buffer of the given size using UTF-8
+  and return a Python string object.  Return \NULL{} if an exception
   was raised by the codec.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyUnicode_AsUTF8String}{PyObject *unicode}
-  Encodes a Unicode objects using UTF-8 and returns the result as
-  Python string object.  Error handling is ``strict''.  Returns
+  Encode a Unicode objects using UTF-8 and return the result as
+  Python string object.  Error handling is ``strict''.  Return
   \NULL{} if an exception was raised by the codec.
 \end{cfuncdesc}
 
@@ -1110,11 +1157,11 @@
 These are the UTF-16 codec APIs:
 
 \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF16}{const char *s,
-                                               int size,
+                                               Py_ssize_t size,
                                                const char *errors,
                                                int *byteorder}
-  Decodes \var{length} bytes from a UTF-16 encoded buffer string and
-  returns the corresponding Unicode object.  \var{errors} (if
+  Decode \var{length} bytes from a UTF-16 encoded buffer string and
+  return the corresponding Unicode object.  \var{errors} (if
   non-\NULL{}) defines the error handling. It defaults to ``strict''.
 
   If \var{byteorder} is non-\NULL{}, the decoder starts decoding using
@@ -1133,28 +1180,28 @@
 
   If \var{byteorder} is \NULL{}, the codec starts in native order mode.
 
-  Returns \NULL{} if an exception was raised by the codec.
+  Return \NULL{} if an exception was raised by the codec.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF16Stateful}{const char *s,
-                                               int size,
+                                               Py_ssize_t size,
                                                const char *errors,
                                                int *byteorder,
-                                               int *consumed}
-  If \var{consumed} is \NULL{}, behaves like
+                                               Py_ssize_t *consumed}
+  If \var{consumed} is \NULL{}, behave like
   \cfunction{PyUnicode_DecodeUTF16()}. If \var{consumed} is not \NULL{},
   \cfunction{PyUnicode_DecodeUTF16Stateful()} will not treat trailing incomplete
-  UTF-16 byte sequences (i.e. an odd number of bytes or a split surrogate pair)
+  UTF-16 byte sequences (such as an odd number of bytes or a split surrogate pair)
   as an error. Those bytes will not be decoded and the number of bytes that
   have been decoded will be stored in \var{consumed}.
   \versionadded{2.4}
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeUTF16}{const Py_UNICODE *s,
-                                               int size,
+                                               Py_ssize_t size,
                                                const char *errors,
                                                int byteorder}
-  Returns a Python string object holding the UTF-16 encoded value of
+  Return a Python string object holding the UTF-16 encoded value of
   the Unicode data in \var{s}.  If \var{byteorder} is not \code{0},
   output is written according to the following byte order:
 
@@ -1173,13 +1220,13 @@
   defined, each \ctype{Py_UNICODE} values is interpreted as an
   UCS-2 character.
 
-  Returns \NULL{} if an exception was raised by the codec.
+  Return \NULL{} if an exception was raised by the codec.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyUnicode_AsUTF16String}{PyObject *unicode}
-  Returns a Python string using the UTF-16 encoding in native byte
+  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''.  Returns \NULL{} if an exception was raised by the
+  ``strict''.  Return \NULL{} if an exception was raised by the
   codec.
 \end{cfuncdesc}
 
@@ -1188,25 +1235,24 @@
 These are the ``Unicode Escape'' codec APIs:
 
 \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUnicodeEscape}{const char *s,
-                                               int size,
+                                               Py_ssize_t size,
                                                const char *errors}
-  Creates a Unicode object by decoding \var{size} bytes of the
-  Unicode-Escape encoded string \var{s}.  Returns \NULL{} if an
+  Create a Unicode object by decoding \var{size} bytes of the
+  Unicode-Escape encoded string \var{s}.  Return \NULL{} if an
   exception was raised by the codec.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeUnicodeEscape}{const Py_UNICODE *s,
-                                               int size,
-                                               const char *errors}
-  Encodes the \ctype{Py_UNICODE} buffer of the given size using
-  Unicode-Escape and returns a Python string object.  Returns \NULL{}
+                                               Py_ssize_t size}
+  Encode the \ctype{Py_UNICODE} buffer of the given size using
+  Unicode-Escape and return a Python string object.  Return \NULL{}
   if an exception was raised by the codec.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyUnicode_AsUnicodeEscapeString}{PyObject *unicode}
-  Encodes a Unicode objects using Unicode-Escape and returns the
+  Encode a Unicode objects using Unicode-Escape and return the
   result as Python string object.  Error handling is ``strict''.
-  Returns \NULL{} if an exception was raised by the codec.
+  Return \NULL{} if an exception was raised by the codec.
 \end{cfuncdesc}
 
 % --- Raw-Unicode-Escape Codecs ------------------------------------------
@@ -1214,25 +1260,25 @@
 These are the ``Raw Unicode Escape'' codec APIs:
 
 \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeRawUnicodeEscape}{const char *s,
-                                               int size,
+                                               Py_ssize_t size,
                                                const char *errors}
-  Creates a Unicode object by decoding \var{size} bytes of the
-  Raw-Unicode-Escape encoded string \var{s}.  Returns \NULL{} if an
+  Create a Unicode object by decoding \var{size} bytes of the
+  Raw-Unicode-Escape encoded string \var{s}.  Return \NULL{} if an
   exception was raised by the codec.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeRawUnicodeEscape}{const Py_UNICODE *s,
-                                               int size,
+                                               Py_ssize_t size,
                                                const char *errors}
-  Encodes the \ctype{Py_UNICODE} buffer of the given size using
-  Raw-Unicode-Escape and returns a Python string object.  Returns
+  Encode the \ctype{Py_UNICODE} buffer of the given size using
+  Raw-Unicode-Escape and return a Python string object.  Return
   \NULL{} if an exception was raised by the codec.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyUnicode_AsRawUnicodeEscapeString}{PyObject *unicode}
-  Encodes a Unicode objects using Raw-Unicode-Escape and returns the
+  Encode a Unicode objects using Raw-Unicode-Escape and return the
   result as Python string object. Error handling is ``strict''.
-  Returns \NULL{} if an exception was raised by the codec.
+  Return \NULL{} if an exception was raised by the codec.
 \end{cfuncdesc}
 
 % --- Latin-1 Codecs -----------------------------------------------------
@@ -1242,24 +1288,24 @@
 are accepted by the codecs during encoding.
 
 \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeLatin1}{const char *s,
-                                                     int size,
+                                                     Py_ssize_t size,
                                                      const char *errors}
-  Creates a Unicode object by decoding \var{size} bytes of the Latin-1
-  encoded string \var{s}.  Returns \NULL{} if an exception was raised
+  Create a Unicode object by decoding \var{size} bytes of the Latin-1
+  encoded string \var{s}.  Return \NULL{} if an exception was raised
   by the codec.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeLatin1}{const Py_UNICODE *s,
-                                                     int size,
+                                                     Py_ssize_t size,
                                                      const char *errors}
-  Encodes the \ctype{Py_UNICODE} buffer of the given size using
-  Latin-1 and returns a Python string object.  Returns \NULL{} if an
+  Encode the \ctype{Py_UNICODE} buffer of the given size using
+  Latin-1 and return a Python string object.  Return \NULL{} if an
   exception was raised by the codec.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyUnicode_AsLatin1String}{PyObject *unicode}
-  Encodes a Unicode objects using Latin-1 and returns the result as
-  Python string object.  Error handling is ``strict''.  Returns
+  Encode a Unicode objects using Latin-1 and return the result as
+  Python string object.  Error handling is ``strict''.  Return
   \NULL{} if an exception was raised by the codec.
 \end{cfuncdesc}
 
@@ -1269,24 +1315,24 @@
 accepted. All other codes generate errors.
 
 \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeASCII}{const char *s,
-                                                    int size,
+                                                    Py_ssize_t size,
                                                     const char *errors}
-  Creates a Unicode object by decoding \var{size} bytes of the
-  \ASCII{} encoded string \var{s}.  Returns \NULL{} if an exception
+  Create a Unicode object by decoding \var{size} bytes of the
+  \ASCII{} encoded string \var{s}.  Return \NULL{} if an exception
   was raised by the codec.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeASCII}{const Py_UNICODE *s,
-                                                    int size,
+                                                    Py_ssize_t size,
                                                     const char *errors}
-  Encodes the \ctype{Py_UNICODE} buffer of the given size using
-  \ASCII{} and returns a Python string object.  Returns \NULL{} if an
+  Encode the \ctype{Py_UNICODE} buffer of the given size using
+  \ASCII{} and return a Python string object.  Return \NULL{} if an
   exception was raised by the codec.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyUnicode_AsASCIIString}{PyObject *unicode}
-  Encodes a Unicode objects using \ASCII{} and returns the result as
-  Python string object.  Error handling is ``strict''.  Returns
+  Encode a Unicode objects using \ASCII{} and return the result as
+  Python string object.  Error handling is ``strict''.  Return
   \NULL{} if an exception was raised by the codec.
 \end{cfuncdesc}
 
@@ -1317,46 +1363,51 @@
 points.
 
 \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeCharmap}{const char *s,
-                                               int size,
+                                               Py_ssize_t size,
                                                PyObject *mapping,
                                                const char *errors}
-  Creates a Unicode object by decoding \var{size} bytes of the encoded
-  string \var{s} using the given \var{mapping} object.  Returns
-  \NULL{} if an exception was raised by the codec.
+  Create a Unicode object by decoding \var{size} bytes of the encoded
+  string \var{s} using the given \var{mapping} object.  Return
+  \NULL{} if an exception was raised by the codec. If \var{mapping} is \NULL{}
+  latin-1 decoding will be done. Else it can be a dictionary mapping byte or a
+  unicode string, which is treated as a lookup table. Byte values greater
+  that the length of the string and U+FFFE "characters" are treated as
+  "undefined mapping".
+  \versionchanged[Allowed unicode string as mapping argument]{2.4}
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeCharmap}{const Py_UNICODE *s,
-                                               int size,
+                                               Py_ssize_t size,
                                                PyObject *mapping,
                                                const char *errors}
-  Encodes the \ctype{Py_UNICODE} buffer of the given size using the
-  given \var{mapping} object and returns a Python string object.
-  Returns \NULL{} if an exception was raised by the codec.
+  Encode the \ctype{Py_UNICODE} buffer of the given size using the
+  given \var{mapping} object and return a Python string object.
+  Return \NULL{} if an exception was raised by the codec.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyUnicode_AsCharmapString}{PyObject *unicode,
                                                         PyObject *mapping}
-  Encodes a Unicode objects using the given \var{mapping} object and
-  returns the result as Python string object.  Error handling is
-  ``strict''.  Returns \NULL{} if an exception was raised by the
+  Encode a Unicode objects using the given \var{mapping} object and
+  return the result as Python string object.  Error handling is
+  ``strict''.  Return \NULL{} if an exception was raised by the
   codec.
 \end{cfuncdesc}
 
 The following codec API is special in that maps Unicode to Unicode.
 
 \begin{cfuncdesc}{PyObject*}{PyUnicode_TranslateCharmap}{const Py_UNICODE *s,
-                                               int size,
+                                               Py_ssize_t size,
                                                PyObject *table,
                                                const char *errors}
-  Translates a \ctype{Py_UNICODE} buffer of the given length by
-  applying a character mapping \var{table} to it and returns the
-  resulting Unicode object.  Returns \NULL{} when an exception was
+  Translate a \ctype{Py_UNICODE} buffer of the given length by
+  applying a character mapping \var{table} to it and return the
+  resulting Unicode object.  Return \NULL{} when an exception was
   raised by the codec.
 
   The \var{mapping} table must map Unicode ordinal integers to Unicode
   ordinal integers or None (causing deletion of the character).
 
-  Mapping tables need only provide the method{__getitem__()}
+  Mapping tables need only provide the \method{__getitem__()}
   interface; dictionaries and sequences work well.  Unmapped character
   ordinals (ones which cause a \exception{LookupError}) are left
   untouched and are copied as-is.
@@ -1371,24 +1422,36 @@
 machine running the codec.
 
 \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeMBCS}{const char *s,
-                                               int size,
+                                               Py_ssize_t size,
                                                const char *errors}
-  Creates a Unicode object by decoding \var{size} bytes of the MBCS
-  encoded string \var{s}.  Returns \NULL{} if an exception was
+  Create a Unicode object by decoding \var{size} bytes of the MBCS
+  encoded string \var{s}.  Return \NULL{} if an exception was
   raised by the codec.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeMBCS}{const Py_UNICODE *s,
+\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeMBCSStateful}{const char *s,
                                                int size,
+                                               const char *errors,
+                                               int *consumed}
+  If \var{consumed} is \NULL{}, behave like
+  \cfunction{PyUnicode_DecodeMBCS()}. If \var{consumed} is not \NULL{},
+  \cfunction{PyUnicode_DecodeMBCSStateful()} will not decode trailing lead
+  byte and the number of bytes that have been decoded will be stored in
+  \var{consumed}.
+  \versionadded{2.5}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeMBCS}{const Py_UNICODE *s,
+                                               Py_ssize_t size,
                                                const char *errors}
-  Encodes the \ctype{Py_UNICODE} buffer of the given size using MBCS
-  and returns a Python string object.  Returns \NULL{} if an exception
+  Encode the \ctype{Py_UNICODE} buffer of the given size using MBCS
+  and return a Python string object.  Return \NULL{} if an exception
   was raised by the codec.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyUnicode_AsMBCSString}{PyObject *unicode}
-  Encodes a Unicode objects using MBCS and returns the result as
-  Python string object.  Error handling is ``strict''.  Returns
+  Encode a Unicode objects using MBCS and return the result as
+  Python string object.  Error handling is ``strict''.  Return
   \NULL{} if an exception was raised by the codec.
 \end{cfuncdesc}
 
@@ -1409,7 +1472,7 @@
 
 \begin{cfuncdesc}{PyObject*}{PyUnicode_Split}{PyObject *s,
                                               PyObject *sep,
-                                              int maxsplit}
+                                              Py_ssize_t maxsplit}
   Split a string giving a list of Unicode strings.  If sep is \NULL{},
   splitting will be done at all whitespace substrings.  Otherwise,
   splits occur at the given separator.  At most \var{maxsplit} splits
@@ -1449,20 +1512,21 @@
   resulting Unicode string.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyObject*}{PyUnicode_Tailmatch}{PyObject *str,
+\begin{cfuncdesc}{int}{PyUnicode_Tailmatch}{PyObject *str,
                                                   PyObject *substr,
-                                                  int start,
-                                                  int end,
+                                                  Py_ssize_t start,
+                                                  Py_ssize_t end,
                                                   int direction}
   Return 1 if \var{substr} matches \var{str}[\var{start}:\var{end}] at
   the given tail end (\var{direction} == -1 means to do a prefix
   match, \var{direction} == 1 a suffix match), 0 otherwise.
+  Return \code{-1} if an error occurred.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyUnicode_Find}{PyObject *str,
+\begin{cfuncdesc}{Py_ssize_t}{PyUnicode_Find}{PyObject *str,
                                        PyObject *substr,
-                                       int start,
-                                       int end,
+                                       Py_ssize_t start,
+                                       Py_ssize_t end,
                                        int direction}
   Return the first position of \var{substr} in
   \var{str}[\var{start}:\var{end}] using the given \var{direction}
@@ -1473,19 +1537,19 @@
   an exception has been set.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyUnicode_Count}{PyObject *str,
+\begin{cfuncdesc}{Py_ssize_t}{PyUnicode_Count}{PyObject *str,
                                         PyObject *substr,
-                                        int start,
-                                        int end}
+                                        Py_ssize_t start,
+                                        Py_ssize_t end}
   Return the number of non-overlapping occurrences of \var{substr} in
-  \code{\var{str}[\var{start}:\var{end}]}.  Returns \code{-1} if an
+  \code{\var{str}[\var{start}:\var{end}]}.  Return \code{-1} if an
   error occurred.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyUnicode_Replace}{PyObject *str,
                                                 PyObject *substr,
                                                 PyObject *replstr,
-                                                int maxcount}
+                                                Py_ssize_t maxcount}
   Replace at most \var{maxcount} occurrences of \var{substr} in
   \var{str} with \var{replstr} and return the resulting Unicode object.
   \var{maxcount} == -1 means replace all occurrences.
@@ -1496,17 +1560,37 @@
   greater than, respectively.
 \end{cfuncdesc}
 
+\begin{cfuncdesc}{int}{PyUnicode_RichCompare}{PyObject *left, 
+                                              PyObject *right, 
+                                              int op}
+
+  Rich compare two unicode strings and return one of the following:
+  \begin{itemize}
+    \item \code{NULL} in case an exception was raised
+    \item \constant{Py_True} or \constant{Py_False} for successful comparisons
+    \item \constant{Py_NotImplemented} in case the type combination is unknown
+  \end{itemize}
+
+   Note that \constant{Py_EQ} and \constant{Py_NE} comparisons can cause a
+   \exception{UnicodeWarning} in case the conversion of the arguments to
+   Unicode fails with a \exception{UnicodeDecodeError}.
+
+   Possible values for \var{op} are
+   \constant{Py_GT}, \constant{Py_GE}, \constant{Py_EQ},
+   \constant{Py_NE}, \constant{Py_LT}, and \constant{Py_LE}.
+\end{cfuncdesc}
+
 \begin{cfuncdesc}{PyObject*}{PyUnicode_Format}{PyObject *format,
                                               PyObject *args}
-  Returns a new string object from \var{format} and \var{args}; this
+  Return a new string object from \var{format} and \var{args}; this
   is analogous to \code{\var{format} \%\ \var{args}}.  The
   \var{args} argument must be a tuple.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{int}{PyUnicode_Contains}{PyObject *container,
                                            PyObject *element}
-  Checks whether \var{element} is contained in \var{container} and
-  returns true or false accordingly.
+  Check whether \var{element} is contained in \var{container} and
+  return true or false accordingly.
 
   \var{element} has to coerce to a one element Unicode
   string. \code{-1} is returned if there was an error.
@@ -1564,8 +1648,9 @@
 
 \begin{cvardesc}{PyTypeObject}{PyBuffer_Type}
   The instance of \ctype{PyTypeObject} which represents the Python
-  buffer type; it is the same object as \code{types.BufferType} in the
-  Python layer.\withsubitem{(in module types)}{\ttindex{BufferType}}.
+  buffer type; it is the same object as \code{buffer} and 
+  \code{types.BufferType} in the Python layer.
+  \withsubitem{(in module types)}{\ttindex{BufferType}}.
 \end{cvardesc}
 
 \begin{cvardesc}{int}{Py_END_OF_BUFFER}
@@ -1583,7 +1668,7 @@
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyBuffer_FromObject}{PyObject *base,
-                                                  int offset, int size}
+                                                  Py_ssize_t offset, Py_ssize_t size}
   Return a new read-only buffer object.  This raises
   \exception{TypeError} if \var{base} doesn't support the read-only
   buffer protocol or doesn't provide exactly one buffer segment, or it
@@ -1597,15 +1682,15 @@
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyBuffer_FromReadWriteObject}{PyObject *base,
-                                                           int offset,
-                                                           int size}
+                                                           Py_ssize_t offset,
+                                                           Py_ssize_t size}
   Return a new writable buffer object.  Parameters and exceptions are
   similar to those for \cfunction{PyBuffer_FromObject()}.  If the
   \var{base} object does not export the writeable buffer protocol,
   then \exception{TypeError} is raised.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyObject*}{PyBuffer_FromMemory}{void *ptr, int size}
+\begin{cfuncdesc}{PyObject*}{PyBuffer_FromMemory}{void *ptr, Py_ssize_t size}
   Return a new read-only buffer object that reads from a specified
   location in memory, with a specified size.  The caller is
   responsible for ensuring that the memory buffer, passed in as
@@ -1616,13 +1701,13 @@
   raised in that case.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyObject*}{PyBuffer_FromReadWriteMemory}{void *ptr, int size}
+\begin{cfuncdesc}{PyObject*}{PyBuffer_FromReadWriteMemory}{void *ptr, Py_ssize_t size}
   Similar to \cfunction{PyBuffer_FromMemory()}, but the returned
   buffer is writable.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyObject*}{PyBuffer_New}{int size}
-  Returns a new writable buffer object that maintains its own memory
+\begin{cfuncdesc}{PyObject*}{PyBuffer_New}{Py_ssize_t size}
+  Return a new writable buffer object that maintains its own memory
   buffer of \var{size} bytes.  \exception{ValueError} is returned if
   \var{size} is not zero or positive.  Note that the memory buffer (as
   returned by \cfunction{PyObject_AsWriteBuffer()}) is not specifically
@@ -1639,8 +1724,8 @@
 
 \begin{cvardesc}{PyTypeObject}{PyTuple_Type}
   This instance of \ctype{PyTypeObject} represents the Python tuple
-  type; it is the same object as \code{types.TupleType} in the Python
-  layer.\withsubitem{(in module types)}{\ttindex{TupleType}}.
+  type; it is the same object as \code{tuple} and \code{types.TupleType}
+  in the Python layer.\withsubitem{(in module types)}{\ttindex{TupleType}}.
 \end{cvardesc}
 
 \begin{cfuncdesc}{int}{PyTuple_Check}{PyObject *p}
@@ -1655,11 +1740,11 @@
   \versionadded{2.2}
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyObject*}{PyTuple_New}{int len}
+\begin{cfuncdesc}{PyObject*}{PyTuple_New}{Py_ssize_t len}
   Return a new tuple object of size \var{len}, or \NULL{} on failure.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyObject*}{PyTuple_Pack}{int n, \moreargs}
+\begin{cfuncdesc}{PyObject*}{PyTuple_Pack}{Py_ssize_t n, \moreargs}
   Return a new tuple object of size \var{n}, or \NULL{} on failure.
   The tuple values are initialized to the subsequent \var{n} C arguments
   pointing to Python objects.  \samp{PyTuple_Pack(2, \var{a}, \var{b})}
@@ -1668,7 +1753,7 @@
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{int}{PyTuple_Size}{PyObject *p}
-  Takes a pointer to a tuple object, and returns the size of that
+  Take a pointer to a tuple object, and return the size of that
   tuple.
 \end{cfuncdesc}
 
@@ -1677,38 +1762,38 @@
   point to a tuple; no error checking is performed.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyObject*}{PyTuple_GetItem}{PyObject *p, int pos}
-  Returns the object at position \var{pos} in the tuple pointed to by
-  \var{p}.  If \var{pos} is out of bounds, returns \NULL{} and sets an
+\begin{cfuncdesc}{PyObject*}{PyTuple_GetItem}{PyObject *p, Py_ssize_t pos}
+  Return the object at position \var{pos} in the tuple pointed to by
+  \var{p}.  If \var{pos} is out of bounds, return \NULL{} and sets an
   \exception{IndexError} exception.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyObject*}{PyTuple_GET_ITEM}{PyObject *p, int pos}
+\begin{cfuncdesc}{PyObject*}{PyTuple_GET_ITEM}{PyObject *p, Py_ssize_t pos}
   Like \cfunction{PyTuple_GetItem()}, but does no checking of its
   arguments.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyTuple_GetSlice}{PyObject *p,
-                                               int low, int high}
-  Takes a slice of the tuple pointed to by \var{p} from \var{low} to
-  \var{high} and returns it as a new tuple.
+                                               Py_ssize_t low, Py_ssize_t high}
+  Take a slice of the tuple pointed to by \var{p} from \var{low} to
+  \var{high} and return it as a new tuple.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{int}{PyTuple_SetItem}{PyObject *p,
-                                        int pos, PyObject *o}
-  Inserts a reference to object \var{o} at position \var{pos} of the
-  tuple pointed to by \var{p}. It returns \code{0} on success.
+                                        Py_ssize_t pos, PyObject *o}
+  Insert a reference to object \var{o} at position \var{pos} of the
+  tuple pointed to by \var{p}. Return \code{0} on success.
   \note{This function ``steals'' a reference to \var{o}.}
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{void}{PyTuple_SET_ITEM}{PyObject *p,
-                                          int pos, PyObject *o}
+                                          Py_ssize_t pos, PyObject *o}
   Like \cfunction{PyTuple_SetItem()}, but does no error checking, and
   should \emph{only} be used to fill in brand new tuples.  \note{This
   function ``steals'' a reference to \var{o}.}
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{_PyTuple_Resize}{PyObject **p, int newsize}
+\begin{cfuncdesc}{int}{_PyTuple_Resize}{PyObject **p, Py_ssize_t newsize}
   Can be used to resize a tuple.  \var{newsize} will be the new length
   of the tuple.  Because tuples are \emph{supposed} to be immutable,
   this should only be used if there is only one reference to the
@@ -1736,12 +1821,12 @@
 
 \begin{cvardesc}{PyTypeObject}{PyList_Type}
   This instance of \ctype{PyTypeObject} represents the Python list
-  type.  This is the same object as \code{types.ListType}.
-  \withsubitem{(in module types)}{\ttindex{ListType}}
+  type.  This is the same object as \code{list} and \code{types.ListType}
+  in the Python layer.\withsubitem{(in module types)}{\ttindex{ListType}}
 \end{cvardesc}
 
 \begin{cfuncdesc}{int}{PyList_Check}{PyObject *p}
-  Returns true if \var{p} is a list object or an instance of a
+  Return true if \var{p} is a list object or an instance of a
   subtype of the list type.
   \versionchanged[Allowed subtypes to be accepted]{2.2}
 \end{cfuncdesc}
@@ -1752,40 +1837,46 @@
   \versionadded{2.2}
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyObject*}{PyList_New}{int len}
-  Returns a new list of length \var{len} on success, or \NULL{} on
+\begin{cfuncdesc}{PyObject*}{PyList_New}{Py_ssize_t len}
+  Return a new list of length \var{len} on success, or \NULL{} on
   failure.
+  \note{If \var{length} is greater than zero, the returned list object's
+        items are set to \code{NULL}.  Thus you cannot use abstract
+        API functions such as \cfunction{PySequence_SetItem()} 
+        or expose the object to Python code before setting all items to a
+        real object with \cfunction{PyList_SetItem()}.}
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyList_Size}{PyObject *list}
-  Returns the length of the list object in \var{list}; this is
+\begin{cfuncdesc}{Py_ssize_t}{PyList_Size}{PyObject *list}
+  Return the length of the list object in \var{list}; this is
   equivalent to \samp{len(\var{list})} on a list object.
   \bifuncindex{len}
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyList_GET_SIZE}{PyObject *list}
+\begin{cfuncdesc}{Py_ssize_t}{PyList_GET_SIZE}{PyObject *list}
   Macro form of \cfunction{PyList_Size()} without error checking.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyObject*}{PyList_GetItem}{PyObject *list, int index}
-  Returns the object at position \var{pos} in the list pointed to by
-  \var{p}.  If \var{pos} is out of bounds, returns \NULL{} and sets an
-  \exception{IndexError} exception.
+\begin{cfuncdesc}{PyObject*}{PyList_GetItem}{PyObject *list, Py_ssize_t index}
+  Return the object at position \var{pos} in the list pointed to by
+  \var{p}.  The position must be positive, indexing from the end of the
+  list is not supported.  If \var{pos} is out of bounds, return \NULL{}
+  and set an \exception{IndexError} exception.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyObject*}{PyList_GET_ITEM}{PyObject *list, int i}
+\begin{cfuncdesc}{PyObject*}{PyList_GET_ITEM}{PyObject *list, Py_ssize_t i}
   Macro form of \cfunction{PyList_GetItem()} without error checking.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyList_SetItem}{PyObject *list, int index,
+\begin{cfuncdesc}{int}{PyList_SetItem}{PyObject *list, Py_ssize_t index,
                                        PyObject *item}
-  Sets the item at index \var{index} in list to \var{item}.  Returns
+  Set the item at index \var{index} in list to \var{item}.  Return
   \code{0} on success or \code{-1} on failure.  \note{This function
   ``steals'' a reference to \var{item} and discards a reference to an
   item already in the list at the affected position.}
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{void}{PyList_SET_ITEM}{PyObject *list, int i,
+\begin{cfuncdesc}{void}{PyList_SET_ITEM}{PyObject *list, Py_ssize_t i,
                                               PyObject *o}
   Macro form of \cfunction{PyList_SetItem()} without error checking.
   This is normally only used to fill in new lists where there is no
@@ -1796,54 +1887,54 @@
   \var{list} at position \var{i} will be leaked.}
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyList_Insert}{PyObject *list, int index,
+\begin{cfuncdesc}{int}{PyList_Insert}{PyObject *list, Py_ssize_t index,
                                       PyObject *item}
-  Inserts the item \var{item} into list \var{list} in front of index
-  \var{index}.  Returns \code{0} if successful; returns \code{-1} and
-  raises an exception if unsuccessful.  Analogous to
+  Insert the item \var{item} into list \var{list} in front of index
+  \var{index}.  Return \code{0} if successful; return \code{-1} and
+  set an exception if unsuccessful.  Analogous to
   \code{\var{list}.insert(\var{index}, \var{item})}.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{int}{PyList_Append}{PyObject *list, PyObject *item}
-  Appends the object \var{item} at the end of list \var{list}.
-  Returns \code{0} if successful; returns \code{-1} and sets an
+  Append the object \var{item} at the end of list \var{list}.
+  Return \code{0} if successful; return \code{-1} and set an
   exception if unsuccessful.  Analogous to
   \code{\var{list}.append(\var{item})}.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyList_GetSlice}{PyObject *list,
-                                              int low, int high}
-  Returns a list of the objects in \var{list} containing the objects
-  \emph{between} \var{low} and \var{high}.  Returns \NULL{} and sets
+                                              Py_ssize_t low, Py_ssize_t high}
+  Return a list of the objects in \var{list} containing the objects
+  \emph{between} \var{low} and \var{high}.  Return \NULL{} and set
   an exception if unsuccessful.
   Analogous to \code{\var{list}[\var{low}:\var{high}]}.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{int}{PyList_SetSlice}{PyObject *list,
-                                        int low, int high,
+                                        Py_ssize_t low, Py_ssize_t high,
                                         PyObject *itemlist}
-  Sets the slice of \var{list} between \var{low} and \var{high} to the
+  Set the slice of \var{list} between \var{low} and \var{high} to the
   contents of \var{itemlist}.  Analogous to
   \code{\var{list}[\var{low}:\var{high}] = \var{itemlist}}.
   The \var{itemlist} may be \NULL{}, indicating the assignment
   of an empty list (slice deletion).
-  Returns \code{0} on success, \code{-1} on failure.
+  Return \code{0} on success, \code{-1} on failure.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{int}{PyList_Sort}{PyObject *list}
-  Sorts the items of \var{list} in place.  Returns \code{0} on
+  Sort the items of \var{list} in place.  Return \code{0} on
   success, \code{-1} on failure.  This is equivalent to
   \samp{\var{list}.sort()}.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{int}{PyList_Reverse}{PyObject *list}
-  Reverses the items of \var{list} in place.  Returns \code{0} on
+  Reverse the items of \var{list} in place.  Return \code{0} on
   success, \code{-1} on failure.  This is the equivalent of
   \samp{\var{list}.reverse()}.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyList_AsTuple}{PyObject *list}
-  Returns a new tuple object containing the contents of \var{list};
+  Return a new tuple object containing the contents of \var{list};
   equivalent to \samp{tuple(\var{list})}.\bifuncindex{tuple}
 \end{cfuncdesc}
 
@@ -1864,12 +1955,12 @@
 \begin{cvardesc}{PyTypeObject}{PyDict_Type}
   This instance of \ctype{PyTypeObject} represents the Python
   dictionary type.  This is exposed to Python programs as
-  \code{types.DictType} and \code{types.DictionaryType}.
+  \code{dict} and \code{types.DictType}.
   \withsubitem{(in module types)}{\ttindex{DictType}\ttindex{DictionaryType}}
 \end{cvardesc}
 
 \begin{cfuncdesc}{int}{PyDict_Check}{PyObject *p}
-  Returns true if \var{p} is a dict object or an instance of a
+  Return true if \var{p} is a dict object or an instance of a
   subtype of the dict type.
   \versionchanged[Allowed subtypes to be accepted]{2.2}
 \end{cfuncdesc}
@@ -1881,7 +1972,7 @@
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyDict_New}{}
-  Returns a new empty dictionary, or \NULL{} on failure.
+  Return a new empty dictionary, or \NULL{} on failure.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyDictProxy_New}{PyObject *dict}
@@ -1892,7 +1983,7 @@
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{void}{PyDict_Clear}{PyObject *p}
-  Empties an existing dictionary of all key-value pairs.
+  Empty an existing dictionary of all key-value pairs.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{int}{PyDict_Contains}{PyObject *p, PyObject *key}
@@ -1904,76 +1995,76 @@
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyDict_Copy}{PyObject *p}
-  Returns a new dictionary that contains the same key-value pairs as
+  Return a new dictionary that contains the same key-value pairs as
   \var{p}.
   \versionadded{1.6}
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{int}{PyDict_SetItem}{PyObject *p, PyObject *key,
                                        PyObject *val}
-  Inserts \var{value} into the dictionary \var{p} with a key of
+  Insert \var{value} into the dictionary \var{p} with a key of
   \var{key}.  \var{key} must be hashable; if it isn't,
   \exception{TypeError} will be raised.
-  Returns \code{0} on success or \code{-1} on failure.
+  Return \code{0} on success or \code{-1} on failure.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{int}{PyDict_SetItemString}{PyObject *p,
-            char *key,
+            const char *key,
             PyObject *val}
-  Inserts \var{value} into the dictionary \var{p} using \var{key} as a
+  Insert \var{value} into the dictionary \var{p} using \var{key} as a
   key. \var{key} should be a \ctype{char*}.  The key object is created
-  using \code{PyString_FromString(\var{key})}. Returns \code{0} on
+  using \code{PyString_FromString(\var{key})}. Return \code{0} on
   success or \code{-1} on failure.
   \ttindex{PyString_FromString()}
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{int}{PyDict_DelItem}{PyObject *p, PyObject *key}
-  Removes the entry in dictionary \var{p} with key \var{key}.
+  Remove the entry in dictionary \var{p} with key \var{key}.
   \var{key} must be hashable; if it isn't, \exception{TypeError} is
-  raised.  Returns \code{0} on success or \code{-1} on failure.
+  raised.  Return \code{0} on success or \code{-1} on failure.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{int}{PyDict_DelItemString}{PyObject *p, char *key}
-  Removes the entry in dictionary \var{p} which has a key specified by
-  the string \var{key}.  Returns \code{0} on success or \code{-1} on
+  Remove the entry in dictionary \var{p} which has a key specified by
+  the string \var{key}.  Return \code{0} on success or \code{-1} on
   failure.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyDict_GetItem}{PyObject *p, PyObject *key}
-  Returns the object from dictionary \var{p} which has a key
-  \var{key}.  Returns \NULL{} if the key \var{key} is not present, but
+  Return the object from dictionary \var{p} which has a key
+  \var{key}.  Return \NULL{} if the key \var{key} is not present, but
   \emph{without} setting an exception.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyObject*}{PyDict_GetItemString}{PyObject *p, char *key}
+\begin{cfuncdesc}{PyObject*}{PyDict_GetItemString}{PyObject *p, const char *key}
   This is the same as \cfunction{PyDict_GetItem()}, but \var{key} is
   specified as a \ctype{char*}, rather than a \ctype{PyObject*}.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyDict_Items}{PyObject *p}
-  Returns a \ctype{PyListObject} containing all the items from the
+  Return a \ctype{PyListObject} containing all the items from the
   dictionary, as in the dictionary method \method{items()} (see the
   \citetitle[../lib/lib.html]{Python Library Reference}).
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyDict_Keys}{PyObject *p}
-  Returns a \ctype{PyListObject} containing all the keys from the
+  Return a \ctype{PyListObject} containing all the keys from the
   dictionary, as in the dictionary method \method{keys()} (see the
   \citetitle[../lib/lib.html]{Python Library Reference}).
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyDict_Values}{PyObject *p}
-  Returns a \ctype{PyListObject} containing all the values from the
+  Return a \ctype{PyListObject} containing all the values from the
   dictionary \var{p}, as in the dictionary method \method{values()}
   (see the \citetitle[../lib/lib.html]{Python Library Reference}).
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyDict_Size}{PyObject *p}
-  Returns the number of items in the dictionary.  This is equivalent
+\begin{cfuncdesc}{Py_ssize_t}{PyDict_Size}{PyObject *p}
+  Return the number of items in the dictionary.  This is equivalent
   to \samp{len(\var{p})} on a dictionary.\bifuncindex{len}
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyDict_Next}{PyObject *p, int *ppos,
+\begin{cfuncdesc}{int}{PyDict_Next}{PyObject *p, Py_ssize_t *ppos,
                                     PyObject **pkey, PyObject **pvalue}
   Iterate over all key-value pairs in the dictionary \var{p}.  The
   \ctype{int} referred to by \var{ppos} must be initialized to
@@ -2079,39 +2170,40 @@
 
 \begin{cvardesc}{PyTypeObject}{PyFile_Type}
   This instance of \ctype{PyTypeObject} represents the Python file
-  type.  This is exposed to Python programs as \code{types.FileType}.
+  type.  This is exposed to Python programs as \code{file} and
+  \code{types.FileType}.
   \withsubitem{(in module types)}{\ttindex{FileType}}
 \end{cvardesc}
 
 \begin{cfuncdesc}{int}{PyFile_Check}{PyObject *p}
-  Returns true if its argument is a \ctype{PyFileObject} or a subtype
+  Return true if its argument is a \ctype{PyFileObject} or a subtype
   of \ctype{PyFileObject}.
   \versionchanged[Allowed subtypes to be accepted]{2.2}
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{int}{PyFile_CheckExact}{PyObject *p}
-  Returns true if its argument is a \ctype{PyFileObject}, but not a
+  Return true if its argument is a \ctype{PyFileObject}, but not a
   subtype of \ctype{PyFileObject}.
   \versionadded{2.2}
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyFile_FromString}{char *filename, char *mode}
-  On success, returns a new file object that is opened on the file
+  On success, return a new file object that is opened on the file
   given by \var{filename}, with a file mode given by \var{mode}, where
   \var{mode} has the same semantics as the standard C routine
-  \cfunction{fopen()}\ttindex{fopen()}.  On failure, returns \NULL{}.
+  \cfunction{fopen()}\ttindex{fopen()}.  On failure, return \NULL{}.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyFile_FromFile}{FILE *fp,
                                               char *name, char *mode,
                                               int (*close)(FILE*)}
-  Creates a new \ctype{PyFileObject} from the already-open standard C
+  Create a new \ctype{PyFileObject} from the already-open standard C
   file pointer, \var{fp}.  The function \var{close} will be called
-  when the file should be closed.  Returns \NULL{} on failure.
+  when the file should be closed.  Return \NULL{} on failure.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{FILE*}{PyFile_AsFile}{PyFileObject *p}
-  Returns the file object associated with \var{p} as a \ctype{FILE*}.
+\begin{cfuncdesc}{FILE*}{PyFile_AsFile}{PyObject *p}
+  Return the file object associated with \var{p} as a \ctype{FILE*}.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyFile_GetLine}{PyObject *p, int n}
@@ -2130,7 +2222,7 @@
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyFile_Name}{PyObject *p}
-  Returns the name of the file specified by \var{p} as a string
+  Return the name of the file specified by \var{p} as a string
   object.
 \end{cfuncdesc}
 
@@ -2147,9 +2239,9 @@
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{int}{PyFile_SoftSpace}{PyObject *p, int newflag}
-  This function exists for internal use by the interpreter.  Sets the
+  This function exists for internal use by the interpreter.  Set the
   \member{softspace} attribute of \var{p} to \var{newflag} and
-  \withsubitem{(file attribute)}{\ttindex{softspace}}returns the
+  \withsubitem{(file attribute)}{\ttindex{softspace}}return the
   previous value.  \var{p} does not have to be a file object for this
   function to work properly; any object is supported (thought its only
   interesting if the \member{softspace} attribute can be set).  This
@@ -2159,18 +2251,18 @@
   function, but doing so should not be needed.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyFile_WriteObject}{PyObject *obj, PyFileObject *p,
+\begin{cfuncdesc}{int}{PyFile_WriteObject}{PyObject *obj, PyObject *p,
                                            int flags}
-  Writes object \var{obj} to file object \var{p}.  The only supported
+  Write object \var{obj} to file object \var{p}.  The only supported
   flag for \var{flags} is
   \constant{Py_PRINT_RAW}\ttindex{Py_PRINT_RAW}; if given, the
   \function{str()} of the object is written instead of the
-  \function{repr()}.  Returns \code{0} on success or \code{-1} on
+  \function{repr()}.  Return \code{0} on success or \code{-1} on
   failure; the appropriate exception will be set.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyFile_WriteString}{const char *s, PyFileObject *p}
-  Writes string \var{s} to file object \var{p}.  Returns \code{0} on
+\begin{cfuncdesc}{int}{PyFile_WriteString}{const char *s, PyObject *p}
+  Write string \var{s} to file object \var{p}.  Return \code{0} on
   success or \code{-1} on failure; the appropriate exception will be
   set.
 \end{cfuncdesc}
@@ -2186,7 +2278,7 @@
 \end{cvardesc}
 
 \begin{cfuncdesc}{int}{PyInstance_Check}{PyObject *obj}
-  Returns true if \var{obj} is an instance.
+  Return true if \var{obj} is an instance.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyInstance_New}{PyObject *class,
@@ -2199,13 +2291,87 @@
 
 \begin{cfuncdesc}{PyObject*}{PyInstance_NewRaw}{PyObject *class,
                                                 PyObject *dict}
-  Create a new instance of a specific class without calling it's
+  Create a new instance of a specific class without calling its
   constructor.  \var{class} is the class of new object.  The
   \var{dict} parameter will be used as the object's \member{__dict__};
   if \NULL{}, a new dictionary will be created for the instance.
 \end{cfuncdesc}
 
 
+\subsection{Function Objects \label{function-objects}}
+
+\obindex{function}
+There are a few functions specific to Python functions.
+
+\begin{ctypedesc}{PyFunctionObject}
+  The C structure used for functions.
+\end{ctypedesc}
+
+\begin{cvardesc}{PyTypeObject}{PyFunction_Type}
+  This is an instance of \ctype{PyTypeObject} and represents the
+  Python function type.  It is exposed to Python programmers as
+  \code{types.FunctionType}.
+  \withsubitem{(in module types)}{\ttindex{MethodType}}
+\end{cvardesc}
+
+\begin{cfuncdesc}{int}{PyFunction_Check}{PyObject *o}
+  Return true if \var{o} is a function object (has type
+  \cdata{PyFunction_Type}).  The parameter must not be \NULL{}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyFunction_New}{PyObject *code,
+                                             PyObject *globals}
+  Return a new function object associated with the code object
+  \var{code}. \var{globals} must be a dictionary with the global
+  variables accessible to the function.
+
+  The function's docstring, name and \var{__module__} are retrieved
+  from the code object, the argument defaults and closure are set to
+  \NULL{}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyFunction_GetCode}{PyObject *op}
+  Return the code object associated with the function object \var{op}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyFunction_GetGlobals}{PyObject *op}
+  Return the globals dictionary associated with the function object
+  \var{op}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyFunction_GetModule}{PyObject *op}
+  Return the \var{__module__} attribute of the function object \var{op}.
+  This is normally a string containing the module name, but can be set
+  to any other object by Python code.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyFunction_GetDefaults}{PyObject *op}
+  Return the argument default values of the function object \var{op}.
+  This can be a tuple of arguments or \NULL{}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyFunction_SetDefaults}{PyObject *op,
+                                               PyObject *defaults}
+  Set the argument default values for the function object \var{op}.
+  \var{defaults} must be \var{Py_None} or a tuple.
+
+  Raises \exception{SystemError} and returns \code{-1} on failure.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyFunction_GetClosure}{PyObject *op}
+  Return the closure associated with the function object \var{op}.
+  This can be \NULL{} or a tuple of cell objects.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyFunction_SetClosure}{PyObject *op,
+                                              PyObject *closure}
+  Set the closure associated with the function object \var{op}.
+  \var{closure} must be \var{Py_None} or a tuple of cell objects.
+
+  Raises \exception{SystemError} and returns \code{-1} on failure.
+\end{cfuncdesc}
+
+
 \subsection{Method Objects \label{method-objects}}
 
 \obindex{method}
@@ -2223,7 +2389,7 @@
   \cdata{PyMethod_Type}).  The parameter must not be \NULL{}.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyObject*}{PyMethod_New}{PyObject *func.
+\begin{cfuncdesc}{PyObject*}{PyMethod_New}{PyObject *func,
                                            PyObject *self, PyObject *class}
   Return a new method object, with \var{func} being any callable
   object; this is the function that will be called when the method is
@@ -2277,18 +2443,18 @@
 \end{cvardesc}
 
 \begin{cfuncdesc}{int}{PyModule_Check}{PyObject *p}
-  Returns true if \var{p} is a module object, or a subtype of a module
+  Return true if \var{p} is a module object, or a subtype of a module
   object.
   \versionchanged[Allowed subtypes to be accepted]{2.2}
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{int}{PyModule_CheckExact}{PyObject *p}
-  Returns true if \var{p} is a module object, but not a subtype of
+  Return true if \var{p} is a module object, but not a subtype of
   \cdata{PyModule_Type}.
   \versionadded{2.2}
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyObject*}{PyModule_New}{char *name}
+\begin{cfuncdesc}{PyObject*}{PyModule_New}{const char *name}
   Return a new module object with the \member{__name__} attribute set
   to \var{name}.  Only the module's \member{__doc__} and
   \member{__name__} attributes are filled in; the caller is
@@ -2325,27 +2491,27 @@
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{int}{PyModule_AddObject}{PyObject *module,
-                                           char *name, PyObject *value}
+                                           const char *name, PyObject *value}
   Add an object to \var{module} as \var{name}.  This is a convenience
   function which can be used from the module's initialization
-  function.  This steals a reference to \var{value}.  Returns
+  function.  This steals a reference to \var{value}.  Return
   \code{-1} on error, \code{0} on success.
   \versionadded{2.0}
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{int}{PyModule_AddIntConstant}{PyObject *module,
-                                                char *name, long value}
+                                                const char *name, long value}
   Add an integer constant to \var{module} as \var{name}.  This
   convenience function can be used from the module's initialization
-  function. Returns \code{-1} on error, \code{0} on success.
+  function. Return \code{-1} on error, \code{0} on success.
   \versionadded{2.0}
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{int}{PyModule_AddStringConstant}{PyObject *module,
-                                                   char *name, char *value}
+                                                   const char *name, const char *value}
   Add a string constant to \var{module} as \var{name}.  This
   convenience function can be used from the module's initialization
-  function.  The string \var{value} must be null-terminated.  Returns
+  function.  The string \var{value} must be null-terminated.  Return
   \code{-1} on error, \code{0} on success.
   \versionadded{2.0}
 \end{cfuncdesc}
@@ -2413,17 +2579,17 @@
 \end{cvardesc}
 
 \begin{cfuncdesc}{PyObject*}{PyDescr_NewGetSet}{PyTypeObject *type,
-					        PyGetSetDef *getset}
+					        struct PyGetSetDef *getset}
   \versionadded{2.2}
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyDescr_NewMember}{PyTypeObject *type,
-					        PyMemberDef *meth}
+					        struct PyMemberDef *meth}
   \versionadded{2.2}
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyDescr_NewMethod}{PyTypeObject *type,
-                                                PyMethodDef *meth}
+                                                struct PyMethodDef *meth}
   \versionadded{2.2}
 \end{cfuncdesc}
 
@@ -2439,7 +2605,7 @@
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{int}{PyDescr_IsData}{PyObject *descr}
-  Returns true if the descriptor objects \var{descr} describes a data
+  Return true if the descriptor objects \var{descr} describes a data
   attribute, or false if it describes a method.  \var{descr} must be a
   descriptor object; there is no error checking.
   \versionadded{2.2}
@@ -2454,12 +2620,12 @@
 
 \begin{cvardesc}{PyTypeObject}{PySlice_Type}
   The type object for slice objects.  This is the same as
-  \code{types.SliceType}.
+  \code{slice} and \code{types.SliceType}.
   \withsubitem{(in module types)}{\ttindex{SliceType}}
 \end{cvardesc}
 
 \begin{cfuncdesc}{int}{PySlice_Check}{PyObject *ob}
-  Returns true if \var{ob} is a slice object; \var{ob} must not be
+  Return true if \var{ob} is a slice object; \var{ob} must not be
   \NULL{}.
 \end{cfuncdesc}
 
@@ -2469,12 +2635,12 @@
   \var{stop}, and \var{step} parameters are used as the values of the
   slice object attributes of the same names.  Any of the values may be
   \NULL{}, in which case the \code{None} will be used for the
-  corresponding attribute.  Returns \NULL{} if the new object could
+  corresponding attribute.  Return \NULL{} if the new object could
   not be allocated.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PySlice_GetIndices}{PySliceObject *slice, int length,
-                                           int *start, int *stop, int *step}
+\begin{cfuncdesc}{int}{PySlice_GetIndices}{PySliceObject *slice, Py_ssize_t length,
+                                           Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step}
 Retrieve the start, stop and step indices from the slice object
 \var{slice}, assuming a sequence of length \var{length}. Treats
 indices greater than \var{length} as errors.
@@ -2489,9 +2655,9 @@
 suitably renamed, in the source of your extension.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PySlice_GetIndicesEx}{PySliceObject *slice, int length,
-                                             int *start, int *stop, int *step,
-                                             int *slicelength}
+\begin{cfuncdesc}{int}{PySlice_GetIndicesEx}{PySliceObject *slice, Py_ssize_t length,
+                                             Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step,
+                                             Py_ssize_t *slicelength}
 Usable replacement for \cfunction{PySlice_GetIndices}.  Retrieve the
 start, stop, and step indices from the slice object \var{slice}
 assuming a sequence of length \var{length}, and store the length of
@@ -2557,7 +2723,7 @@
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyWeakref_GetObject}{PyObject *ref}
-  Returns the referenced object from a weak reference, \var{ref}.  If
+  Return the referenced object from a weak reference, \var{ref}.  If
   the referent is no longer live, returns \code{None}.
   \versionadded{2.2}
 \end{cfuncdesc}
@@ -2639,7 +2805,7 @@
 \end{ctypedesc}
 
 \begin{cvardesc}{PyTypeObject}{PyCell_Type}
-  The type object corresponding to cell objects
+  The type object corresponding to cell objects.
 \end{cvardesc}
 
 \begin{cfuncdesc}{int}{PyCell_Check}{ob}
@@ -2703,6 +2869,7 @@
 
 \begin{cfuncdesc}{PyObject*}{PyGen_New}{PyFrameObject *frame}
   Create and return a new generator object based on the \var{frame} object.
+  A reference to \var{frame} is stolen by this function.
   The parameter must not be \NULL{}.
 \end{cfuncdesc}
 
@@ -2792,7 +2959,7 @@
   \versionadded{2.4}
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyObject*}{PyDate_FromDateAndTime}{int year, int month,
+\begin{cfuncdesc}{PyObject*}{PyDateTime_FromDateAndTime}{int year, int month,
         int day, int hour, int minute, int second, int usecond}
   Return a \code{datetime.datetime} object with the specified year, month,
   day, hour, minute, second and microsecond.
@@ -2896,3 +3063,141 @@
   tuple suitable for passing to \code{datetime.date.fromtimestamp()}.
   \versionadded{2.4}
 \end{cfuncdesc}
+
+
+\subsection{Set Objects \label{setObjects}}
+\sectionauthor{Raymond D. Hettinger}{python@rcn.com}
+
+\obindex{set}
+\obindex{frozenset}
+\versionadded{2.5}
+
+This section details the public API for \class{set} and \class{frozenset}
+objects.  Any functionality not listed below is best accessed using the
+either the abstract object protocol (including
+\cfunction{PyObject_CallMethod()}, \cfunction{PyObject_RichCompareBool()},
+\cfunction{PyObject_Hash()}, \cfunction{PyObject_Repr()},
+\cfunction{PyObject_IsTrue()}, \cfunction{PyObject_Print()}, and
+\cfunction{PyObject_GetIter()})
+or the abstract number protocol (including
+\cfunction{PyNumber_Add()}, \cfunction{PyNumber_Subtract()},
+\cfunction{PyNumber_Or()}, \cfunction{PyNumber_Xor()},
+\cfunction{PyNumber_InPlaceAdd()}, \cfunction{PyNumber_InPlaceSubtract()},
+\cfunction{PyNumber_InPlaceOr()}, and \cfunction{PyNumber_InPlaceXor()}).
+
+\begin{ctypedesc}{PySetObject}
+  This subtype of \ctype{PyObject} is used to hold the internal data for
+  both \class{set} and \class{frozenset} objects.  It is like a
+  \ctype{PyDictObject} in that it is a fixed size for small sets
+  (much like tuple storage) and will point to a separate, variable sized
+  block of memory for medium and large sized sets (much like list storage).
+  None of the fields of this structure should be considered public and
+  are subject to change.  All access should be done through the
+  documented API rather than by manipulating the values in the structure.
+
+\end{ctypedesc}
+
+\begin{cvardesc}{PyTypeObject}{PySet_Type}
+  This is an instance of \ctype{PyTypeObject} representing the Python
+  \class{set} type.
+\end{cvardesc}
+
+\begin{cvardesc}{PyTypeObject}{PyFrozenSet_Type}
+  This is an instance of \ctype{PyTypeObject} representing the Python
+  \class{frozenset} type.
+\end{cvardesc}
+
+
+The following type check macros work on pointers to any Python object.
+Likewise, the constructor functions work with any iterable Python object.
+
+\begin{cfuncdesc}{int}{PyAnySet_Check}{PyObject *p}
+  Return true if \var{p} is a \class{set} object, a \class{frozenset}
+  object, or an instance of a subtype.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyAnySet_CheckExact}{PyObject *p}
+  Return true if \var{p} is a \class{set} object or a \class{frozenset}
+  object but not an instance of a subtype.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyFrozenSet_CheckExact}{PyObject *p}
+  Return true if \var{p} is a \class{frozenset} object
+  but not an instance of a subtype.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PySet_New}{PyObject *iterable}
+  Return a new \class{set} containing objects returned by the
+  \var{iterable}.  The \var{iterable} may be \NULL{} to create a
+  new empty set.  Return the new set on success or \NULL{} on
+  failure.  Raise \exception{TypeError} if \var{iterable} is
+  not actually iterable.  The constructor is also useful for
+  copying a set (\code{c=set(s)}).
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyFrozenSet_New}{PyObject *iterable}
+  Return a new \class{frozenset} containing objects returned by the
+  \var{iterable}.  The \var{iterable} may be \NULL{} to create a
+  new empty frozenset.  Return the new set on success or \NULL{} on
+  failure.  Raise \exception{TypeError} if \var{iterable} is
+  not actually iterable.
+\end{cfuncdesc}
+
+
+The following functions and macros are available for instances of
+\class{set} or \class{frozenset} or instances of their subtypes.
+
+\begin{cfuncdesc}{int}{PySet_Size}{PyObject *anyset}
+  Return the length of a \class{set} or \class{frozenset} object.
+  Equivalent to \samp{len(\var{anyset})}.  Raises a
+  \exception{PyExc_SystemError} if \var{anyset} is not a \class{set},
+  \class{frozenset}, or an instance of a subtype.
+  \bifuncindex{len}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PySet_GET_SIZE}{PyObject *anyset}
+  Macro form of \cfunction{PySet_Size()} without error checking.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PySet_Contains}{PyObject *anyset, PyObject *key}
+  Return 1 if found, 0 if not found, and -1 if an error is
+  encountered.  Unlike the Python \method{__contains__()} method, this
+  function does not automatically convert unhashable sets into temporary
+  frozensets.  Raise a \exception{TypeError} if the \var{key} is unhashable.
+  Raise \exception{PyExc_SystemError} if \var{anyset} is not a \class{set},
+  \class{frozenset}, or an instance of a subtype.
+\end{cfuncdesc}
+
+The following functions are available for instances of \class{set} or
+its subtypes but not for instances of \class{frozenset} or its subtypes.
+
+\begin{cfuncdesc}{int}{PySet_Add}{PyObject *set, PyObject *key}
+  Add \var{key} to a \class{set} instance.  Does not apply to
+  \class{frozenset} instances.  Return 0 on success or -1 on failure.
+  Raise a \exception{TypeError} if the \var{key} is unhashable.
+  Raise a \exception{MemoryError} if there is no room to grow.
+  Raise a \exception{SystemError} if \var{set} is an not an instance
+  of \class{set} or its subtype.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PySet_Discard}{PyObject *set, PyObject *key}
+  Return 1 if found and removed, 0 if not found (no action taken),
+  and -1 if an error is encountered.  Does not raise \exception{KeyError}
+  for missing keys.  Raise a \exception{TypeError} if the \var{key} is
+  unhashable.  Unlike the Python \method{discard()} method, this function
+  does not automatically convert unhashable sets into temporary frozensets.
+  Raise \exception{PyExc_SystemError} if \var{set} is an not an instance
+  of \class{set} or its subtype.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PySet_Pop}{PyObject *set}
+  Return a new reference to an arbitrary object in the \var{set},
+  and removes the object from the \var{set}.  Return \NULL{} on
+  failure.  Raise \exception{KeyError} if the set is empty.
+  Raise a \exception{SystemError} if \var{set} is an not an instance
+  of \class{set} or its subtype.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PySet_Clear}{PyObject *set}
+  Empty an existing set of all elements.
+\end{cfuncdesc}
