=== modified file 'Doc/c-api/typeobj.rst'
--- Doc/c-api/typeobj.rst	2008-01-19 22:08:21 +0000
+++ Doc/c-api/typeobj.rst	2010-11-17 12:18:12 +0000
@@ -51,32 +51,36 @@
    that are still alive at the end of a run when the environment variable
    :envvar:`PYTHONDUMPREFS` is set.
 
    These fields are not inherited by subtypes.
 
 
 .. cmember:: Py_ssize_t PyObject.ob_refcnt
 
    This is the type object's reference count, initialized to ``1`` by the
    ``PyObject_HEAD_INIT`` macro.  Note that for statically allocated type objects,
    the type's instances (objects whose :attr:`ob_type` points back to the type) do
    *not* count as references.  But for dynamically allocated type objects, the
    instances *do* count as references.
 
    This field is not inherited by subtypes.
 
+   .. versionchanged:: 2.5
+      This field used to be an :ctype:`int` type. This might require changes
+      in your code for properly supporting 64-bit systems.
+
 
 .. cmember:: PyTypeObject* PyObject.ob_type
 
    This is the type's type, in other words its metatype.  It is initialized by the
    argument to the ``PyObject_HEAD_INIT`` macro, and its value should normally be
    ``&PyType_Type``.  However, for dynamically loadable extension modules that must
    be usable on Windows (at least), the compiler complains that this is not a valid
    initializer.  Therefore, the convention is to pass *NULL* to the
    ``PyObject_HEAD_INIT`` macro and to initialize this field explicitly at the
    start of the module's initialization function, before doing anything else.  This
    is typically done like this::
 
       Foo_Type.ob_type = &PyType_Type;
 
    This should be done before any instances of the type are created.
    :cfunc:`PyType_Ready` checks if :attr:`ob_type` is *NULL*, and if so,
@@ -172,33 +176,33 @@
    unless the type guarantees that its instances will never be deallocated (as is
    the case for the singletons ``None`` and ``Ellipsis``).
 
    The destructor function is called by the :cfunc:`Py_DECREF` and
    :cfunc:`Py_XDECREF` macros when the new reference count is zero.  At this point,
    the instance is still in existence, but there are no references to it.  The
    destructor function should free all references which the instance owns, free all
    memory buffers owned by the instance (using the freeing function corresponding
    to the allocation function used to allocate the buffer), and finally (as its
    last action) call the type's :attr:`tp_free` function.  If the type is not
    subtypable (doesn't have the :const:`Py_TPFLAGS_BASETYPE` flag bit set), it is
    permissible to call the object deallocator directly instead of via
    :attr:`tp_free`.  The object deallocator should be the one used to allocate the
    instance; this is normally :cfunc:`PyObject_Del` if the instance was allocated
    using :cfunc:`PyObject_New` or :cfunc:`PyObject_VarNew`, or
    :cfunc:`PyObject_GC_Del` if the instance was allocated using
-   :cfunc:`PyObject_GC_New` or :cfunc:`PyObject_GC_VarNew`.
+   :cfunc:`PyObject_GC_New` or :cfunc:`PyObject_GC_NewVar`.
 
    This field is inherited by subtypes.
 
 
 .. cmember:: printfunc PyTypeObject.tp_print
 
    An optional pointer to the instance print function.
 
    The print function is only called when the instance is printed to a *real* file;
    when it is printed to a pseudo-file (like a :class:`StringIO` instance), the
    instance's :attr:`tp_repr` or :attr:`tp_str` function is called to convert it to
    a string.  These are also called when the type's :attr:`tp_print` field is
    *NULL*.  A type should never implement :attr:`tp_print` in a way that produces
    different output than :attr:`tp_repr` or :attr:`tp_str` would.
 
    The print function is called with the same signature as :cfunc:`PyObject_Print`:
@@ -311,32 +315,40 @@
    The :attr:`tp_as_mapping` field is not inherited, but the contained fields
    are inherited individually.
 
 
 .. cmember:: hashfunc PyTypeObject.tp_hash
 
    .. index:: builtin: hash
 
    An optional pointer to a function that implements the built-in function
    :func:`hash`.
 
    The signature is the same as for :cfunc:`PyObject_Hash`; it must return a C
    long.  The value ``-1`` should not be returned as a normal return value; when an
    error occurs during the computation of the hash value, the function should set
    an exception and return ``-1``.
 
+   This field can be set explicitly to :cfunc:`PyObject_HashNotImplemented` to
+   block inheritance of the hash method from a parent type. This is interpreted
+   as the equivalent of ``__hash__ = None`` at the Python level, causing
+   ``isinstance(o, collections.Hashable)`` to correctly return ``False``. Note
+   that the converse is also true - setting ``__hash__ = None`` on a class at
+   the Python level will result in the ``tp_hash`` slot being set to
+   :cfunc:`PyObject_HashNotImplemented`.
+
    When this field is not set, two possibilities exist: if the :attr:`tp_compare`
    and :attr:`tp_richcompare` fields are both *NULL*, a default hash value based on
    the object's address is returned; otherwise, a :exc:`TypeError` is raised.
 
    This field is inherited by subtypes together with :attr:`tp_richcompare` and
    :attr:`tp_compare`: a subtypes inherits all three of :attr:`tp_compare`,
    :attr:`tp_richcompare`, and :attr:`tp_hash`, when the subtype's
    :attr:`tp_compare`, :attr:`tp_richcompare` and :attr:`tp_hash` are all *NULL*.
 
 
 .. cmember:: ternaryfunc PyTypeObject.tp_call
 
    An optional pointer to a function that implements calling the object.  This
    should be *NULL* if the object is not callable.  The signature is the same as
    for :cfunc:`PyObject_Call`.
 
@@ -560,33 +572,33 @@
    This field is *not* inherited by subtypes.
 
 The following three fields only exist if the
 :const:`Py_TPFLAGS_HAVE_RICHCOMPARE` flag bit is set.
 
 
 .. cmember:: traverseproc PyTypeObject.tp_traverse
 
    An optional pointer to a traversal function for the garbage collector.  This is
    only used if the :const:`Py_TPFLAGS_HAVE_GC` flag bit is set.  More information
    about Python's garbage collection scheme can be found in section
    :ref:`supporting-cycle-detection`.
 
    The :attr:`tp_traverse` pointer is used by the garbage collector to detect
    reference cycles. A typical implementation of a :attr:`tp_traverse` function
    simply calls :cfunc:`Py_VISIT` on each of the instance's members that are Python
-   objects.  For exampe, this is function :cfunc:`local_traverse` from the
+   objects.  For example, this is function :cfunc:`local_traverse` from the
    :mod:`thread` extension module::
 
       static int
       local_traverse(localobject *self, visitproc visit, void *arg)
       {
           Py_VISIT(self->args);
           Py_VISIT(self->kw);
           Py_VISIT(self->dict);
           return 0;
       }
 
    Note that :cfunc:`Py_VISIT` is called only on those members that can participate
    in reference cycles.  Although there is also a ``self->key`` member, it can only
    be *NULL* or a Python string and therefore cannot be part of a reference cycle.
 
    On the other hand, even if you know a member can never be part of a cycle, as a
@@ -649,122 +661,129 @@
    integers, which can't participate in reference cycles. On the other hand, it may
    be convenient to clear all contained Python objects, and write the type's
    :attr:`tp_dealloc` function to invoke :attr:`tp_clear`.
 
    More information about Python's garbage collection scheme can be found in
    section :ref:`supporting-cycle-detection`.
 
    This field is inherited by subtypes together with :attr:`tp_traverse` and the
    :const:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :attr:`tp_traverse`, and
    :attr:`tp_clear` are all inherited from the base type if they are all zero in
    the subtype *and* the subtype has the :const:`Py_TPFLAGS_HAVE_RICHCOMPARE` flag
    bit set.
 
 
 .. cmember:: richcmpfunc PyTypeObject.tp_richcompare
 
-   An optional pointer to the rich comparison function.
+   An optional pointer to the rich comparison function, whose signature is
+   ``PyObject *tp_richcompare(PyObject *a, PyObject *b, int op)``.
 
-   The signature is the same as for :cfunc:`PyObject_RichCompare`. The function
-   should return the result of the comparison (usually ``Py_True`` or
-   ``Py_False``).  If the comparison is undefined, it must return
-   ``Py_NotImplemented``, if another error occurred it must return ``NULL`` and set
-   an exception condition.
+   The function should return the result of the comparison (usually ``Py_True``
+   or ``Py_False``).  If the comparison is undefined, it must return
+   ``Py_NotImplemented``, if another error occurred it must return ``NULL`` and
+   set an exception condition.
+
+   .. note::
+
+      If you want to implement a type for which only a limited set of
+      comparisons makes sense (e.g. ``==`` and ``!=``, but not ``<`` and
+      friends), directly raise :exc:`TypeError` in the rich comparison function.
 
    This field is inherited by subtypes together with :attr:`tp_compare` and
    :attr:`tp_hash`: a subtype inherits all three of :attr:`tp_compare`,
    :attr:`tp_richcompare`, and :attr:`tp_hash`, when the subtype's
    :attr:`tp_compare`, :attr:`tp_richcompare`, and :attr:`tp_hash` are all *NULL*.
 
    The following constants are defined to be used as the third argument for
    :attr:`tp_richcompare` and for :cfunc:`PyObject_RichCompare`:
 
    +----------------+------------+
    | Constant       | Comparison |
    +================+============+
    | :const:`Py_LT` | ``<``      |
    +----------------+------------+
    | :const:`Py_LE` | ``<=``     |
    +----------------+------------+
    | :const:`Py_EQ` | ``==``     |
    +----------------+------------+
    | :const:`Py_NE` | ``!=``     |
    +----------------+------------+
    | :const:`Py_GT` | ``>``      |
    +----------------+------------+
    | :const:`Py_GE` | ``>=``     |
    +----------------+------------+
 
+
 The next field only exists if the :const:`Py_TPFLAGS_HAVE_WEAKREFS` flag bit is
 set.
 
-
 .. cmember:: long PyTypeObject.tp_weaklistoffset
 
    If the instances of this type are weakly referenceable, this field is greater
    than zero and contains the offset in the instance structure of the weak
    reference list head (ignoring the GC header, if present); this offset is used by
    :cfunc:`PyObject_ClearWeakRefs` and the :cfunc:`PyWeakref_\*` functions.  The
    instance structure needs to include a field of type :ctype:`PyObject\*` which is
    initialized to *NULL*.
 
    Do not confuse this field with :attr:`tp_weaklist`; that is the list head for
    weak references to the type object itself.
 
    This field is inherited by subtypes, but see the rules listed below. A subtype
    may override this offset; this means that the subtype uses a different weak
    reference list head than the base type.  Since the list head is always found via
    :attr:`tp_weaklistoffset`, this should not be a problem.
 
    When a type defined by a class statement has no :attr:`__slots__` declaration,
    and none of its base types are weakly referenceable, the type is made weakly
    referenceable by adding a weak reference list head slot to the instance layout
    and setting the :attr:`tp_weaklistoffset` of that slot's offset.
 
    When a type's :attr:`__slots__` declaration contains a slot named
    :attr:`__weakref__`, that slot becomes the weak reference list head for
    instances of the type, and the slot's offset is stored in the type's
    :attr:`tp_weaklistoffset`.
 
    When a type's :attr:`__slots__` declaration does not contain a slot named
    :attr:`__weakref__`, the type inherits its :attr:`tp_weaklistoffset` from its
    base type.
 
-The next two fields only exist if the :const:`Py_TPFLAGS_HAVE_CLASS` flag bit is
+The next two fields only exist if the :const:`Py_TPFLAGS_HAVE_ITER` flag bit is
 set.
 
 
 .. cmember:: getiterfunc PyTypeObject.tp_iter
 
    An optional pointer to a function that returns an iterator for the object.  Its
    presence normally signals that the instances of this type are iterable (although
    sequences may be iterable without this function, and classic instances always
    have this function, even if they don't define an :meth:`__iter__` method).
 
    This function has the same signature as :cfunc:`PyObject_GetIter`.
 
    This field is inherited by subtypes.
 
 
 .. cmember:: iternextfunc PyTypeObject.tp_iternext
 
-   An optional pointer to a function that returns the next item in an iterator, or
-   raises :exc:`StopIteration` when the iterator is exhausted.  Its presence
-   normally signals that the instances of this type are iterators (although classic
-   instances always have this function, even if they don't define a :meth:`next`
-   method).
+   An optional pointer to a function that returns the next item in an iterator.
+   When the iterator is exhausted, it must return *NULL*; a :exc:`StopIteration`
+   exception may or may not be set.  When another error occurs, it must return
+   *NULL* too.  Its presence normally signals that the instances of this type
+   are iterators (although classic instances always have this function, even if
+   they don't define a :meth:`next` method).
 
    Iterator types should also define the :attr:`tp_iter` function, and that
    function should return the iterator instance itself (not a new iterator
    instance).
 
    This function has the same signature as :cfunc:`PyIter_Next`.
 
    This field is inherited by subtypes.
 
 The next fields, up to and including :attr:`tp_weaklist`, only exist if the
 :const:`Py_TPFLAGS_HAVE_CLASS` flag bit is set.
 
 
 .. cmember:: struct PyMethodDef* PyTypeObject.tp_methods
 
    An optional pointer to a static *NULL*-terminated array of :ctype:`PyMethodDef`
@@ -1128,56 +1147,58 @@
 
 .. sectionauthor:: Amaury Forgeot d'Arc
 
 
 .. ctype:: PyNumberMethods
 
    This structure holds pointers to the functions which an object uses to
    implement the number protocol.  Almost every function below is used by the
    function of similar name documented in the :ref:`number` section.
 
    Here is the structure definition::
 
        typedef struct {
             binaryfunc nb_add;
             binaryfunc nb_subtract;
             binaryfunc nb_multiply;
+            binaryfunc nb_divide;
             binaryfunc nb_remainder;
             binaryfunc nb_divmod;
             ternaryfunc nb_power;
             unaryfunc nb_negative;
             unaryfunc nb_positive;
             unaryfunc nb_absolute;
             inquiry nb_nonzero;       /* Used by PyObject_IsTrue */
             unaryfunc nb_invert;
             binaryfunc nb_lshift;
             binaryfunc nb_rshift;
             binaryfunc nb_and;
             binaryfunc nb_xor;
             binaryfunc nb_or;
-            coercion nb_coerce;       /* Used by the coerce() funtion */
+            coercion nb_coerce;       /* Used by the coerce() function */
             unaryfunc nb_int;
             unaryfunc nb_long;
             unaryfunc nb_float;
             unaryfunc nb_oct;
             unaryfunc nb_hex;
 
             /* Added in release 2.0 */
             binaryfunc nb_inplace_add;
             binaryfunc nb_inplace_subtract;
             binaryfunc nb_inplace_multiply;
+            binaryfunc nb_inplace_divide;
             binaryfunc nb_inplace_remainder;
             ternaryfunc nb_inplace_power;
             binaryfunc nb_inplace_lshift;
             binaryfunc nb_inplace_rshift;
             binaryfunc nb_inplace_and;
             binaryfunc nb_inplace_xor;
             binaryfunc nb_inplace_or;
 
             /* Added in release 2.2 */
             binaryfunc nb_floor_divide;
             binaryfunc nb_true_divide;
             binaryfunc nb_inplace_floor_divide;
             binaryfunc nb_inplace_true_divide;
 
             /* Added in release 2.5 */
             unaryfunc nb_index;

