--- rest25/reference/datamodel.rst	2008-12-19 16:58:05.000000000 +0900
+++ rest262/reference/datamodel.rst	2009-04-07 00:06:52.000000000 +0900
@@ -47,30 +47,31 @@
 object's mutability is determined by its type; for instance, numbers, strings
 and tuples are immutable, while dictionaries and lists are mutable.
 
 .. index::
    single: garbage collection
    single: reference counting
    single: unreachable object
 
 Objects are never explicitly destroyed; however, when they become unreachable
 they may be garbage-collected.  An implementation is allowed to postpone garbage
 collection or omit it altogether --- it is a matter of implementation quality
 how garbage collection is implemented, as long as no objects are collected that
-are still reachable.  (Implementation note: the current implementation uses a
+are still reachable.  (Implementation note: CPython currently uses a
 reference-counting scheme with (optional) delayed detection of cyclically linked
 garbage, which collects most objects as soon as they become unreachable, but is
 not guaranteed to collect garbage containing circular references.  See the
-Python Library Reference (XXX reference: ../lib/module-gc.html) for information
-on controlling the collection of cyclic garbage.)
+documentation of the :mod:`gc` module for information on controlling the
+collection of cyclic garbage.  Other implementations act differently and CPython
+may change.)
 
 Note that the use of the implementation's tracing or debugging facilities may
 keep objects alive that would normally be collectable. Also note that catching
 an exception with a ':keyword:`try`...\ :keyword:`except`' statement may keep
 objects alive.
 
 Some objects contain references to "external" resources such as open files or
 windows.  It is understood that these resources are freed when the object is
 garbage-collected, but since garbage collection is not guaranteed to happen,
 such objects also provide an explicit way to release the external resource,
 usually a :meth:`close` method. Programs are strongly recommended to explicitly
 close such objects.  The ':keyword:`try`...\ :keyword:`finally`' statement
@@ -141,129 +142,128 @@
    operation for the operands provided.  (The interpreter will then try the
    reflected operation, or some other fallback, depending on the operator.)  Its
    truth value is true.
 
 Ellipsis
    .. index:: object: Ellipsis
 
    This type has a single value.  There is a single object with this value. This
    object is accessed through the built-in name ``Ellipsis``. It is used to
    indicate the presence of the ``...`` syntax in a slice.  Its truth value is
    true.
 
-Numbers
+:class:`numbers.Number`
    .. index:: object: numeric
 
    These are created by numeric literals and returned as results by arithmetic
    operators and arithmetic built-in functions.  Numeric objects are immutable;
    once created their value never changes.  Python numbers are of course strongly
    related to mathematical numbers, but subject to the limitations of numerical
    representation in computers.
 
    Python distinguishes between integers, floating point numbers, and complex
    numbers:
 
-   Integers
+   :class:`numbers.Integral`
       .. index:: object: integer
 
       These represent elements from the mathematical set of integers (positive and
       negative).
 
       There are three types of integers:
 
       Plain integers
          .. index::
             object: plain integer
             single: OverflowError (built-in exception)
 
-         These represent numbers in the range -2147483648 through 2147483647. (The range
-         may be larger on machines with a larger natural word size, but not smaller.)
-         When the result of an operation would fall outside this range, the result is
-         normally returned as a long integer (in some cases, the exception
-         :exc:`OverflowError` is raised instead). For the purpose of shift and mask
-         operations, integers are assumed to have a binary, 2's complement notation using
-         32 or more bits, and hiding no bits from the user (i.e., all 4294967296
-         different bit patterns correspond to different values).
+         These represent numbers in the range -2147483648 through 2147483647.
+         (The range may be larger on machines with a larger natural word size,
+         but not smaller.)  When the result of an operation would fall outside
+         this range, the result is normally returned as a long integer (in some
+         cases, the exception :exc:`OverflowError` is raised instead).  For the
+         purpose of shift and mask operations, integers are assumed to have a
+         binary, 2's complement notation using 32 or more bits, and hiding no
+         bits from the user (i.e., all 4294967296 different bit patterns
+         correspond to different values).
 
       Long integers
          .. index:: object: long integer
 
-         These represent numbers in an unlimited range, subject to available (virtual)
-         memory only.  For the purpose of shift and mask operations, a binary
-         representation is assumed, and negative numbers are represented in a variant of
-         2's complement which gives the illusion of an infinite string of sign bits
-         extending to the left.
+         These represent numbers in an unlimited range, subject to available
+         (virtual) memory only.  For the purpose of shift and mask operations, a
+         binary representation is assumed, and negative numbers are represented
+         in a variant of 2's complement which gives the illusion of an infinite
+         string of sign bits extending to the left.
 
       Booleans
          .. index::
             object: Boolean
             single: False
             single: True
 
-         These represent the truth values False and True.  The two objects representing
-         the values False and True are the only Boolean objects. The Boolean type is a
-         subtype of plain integers, and Boolean values behave like the values 0 and 1,
-         respectively, in almost all contexts, the exception being that when converted to
-         a string, the strings ``"False"`` or ``"True"`` are returned, respectively.
+         These represent the truth values False and True.  The two objects
+         representing the values False and True are the only Boolean objects.
+         The Boolean type is a subtype of plain integers, and Boolean values
+         behave like the values 0 and 1, respectively, in almost all contexts,
+         the exception being that when converted to a string, the strings
+         ``"False"`` or ``"True"`` are returned, respectively.
 
       .. index:: pair: integer; representation
 
-      The rules for integer representation are intended to give the most meaningful
-      interpretation of shift and mask operations involving negative integers and the
-      least surprises when switching between the plain and long integer domains.  Any
-      operation except left shift, if it yields a result in the plain integer domain
-      without causing overflow, will yield the same result in the long integer domain
-      or when using mixed operands.
+      The rules for integer representation are intended to give the most
+      meaningful interpretation of shift and mask operations involving negative
+      integers and the least surprises when switching between the plain and long
+      integer domains.  Any operation, if it yields a result in the plain
+      integer domain, will yield the same result in the long integer domain or
+      when using mixed operands.  The switch between domains is transparent to
+      the programmer.
 
-      .. % Integers
-
-   Floating point numbers
+   :class:`numbers.Real` (:class:`float`)
       .. index::
          object: floating point
          pair: floating point; number
          pair: C; language
          pair: Java; language
 
-      These represent machine-level double precision floating point numbers.   You are
+      These represent machine-level double precision floating point numbers. You are
       at the mercy of the underlying machine architecture (and C or Java
       implementation) for the accepted range and handling of overflow. Python does not
       support single-precision floating point numbers; the savings in processor and
       memory usage that are usually the reason for using these is dwarfed by the
       overhead of using objects in Python, so there is no reason to complicate the
       language with two kinds of floating point numbers.
 
-   Complex numbers
+   :class:`numbers.Complex`
       .. index::
          object: complex
          pair: complex; number
 
       These represent complex numbers as a pair of machine-level double precision
       floating point numbers.  The same caveats apply as for floating point numbers.
       The real and imaginary parts of a complex number ``z`` can be retrieved through
       the read-only attributes ``z.real`` and ``z.imag``.
 
-   .. % Numbers
-
 Sequences
    .. index::
       builtin: len
       object: sequence
       single: index operation
       single: item selection
       single: subscription
 
-   These represent finite ordered sets indexed by non-negative numbers. The built-
-   in function :func:`len` returns the number of items of a sequence. When the
-   length of a sequence is *n*, the index set contains the numbers 0, 1, ...,
-   *n*-1.  Item *i* of sequence *a* is selected by ``a[i]``.
+   These represent finite ordered sets indexed by non-negative numbers. The
+   built-in function :func:`len` returns the number of items of a sequence. When
+   the length of a sequence is *n*, the index set contains the numbers 0, 1,
+   ..., *n*-1.  Item *i* of sequence *a* is selected by ``a[i]``.
 
    .. index:: single: slicing
 
    Sequences also support slicing: ``a[i:j]`` selects all items with index *k* such
    that *i* ``<=`` *k* ``<`` *j*.  When used as an expression, a slice is a
    sequence of the same type.  This implies that the index set is renumbered so
    that it starts at 0.
 
    .. index:: single: extended slicing
 
    Some sequences also support "extended slicing" with a third "step" parameter:
    ``a[i:j:k]`` selects all items of *a* with index *x* where ``x = i + n*k``, *n*
@@ -337,26 +337,24 @@
       Tuples
          .. index::
             object: tuple
             pair: singleton; tuple
             pair: empty; tuple
 
          The items of a tuple are arbitrary Python objects. Tuples of two or more items
          are formed by comma-separated lists of expressions.  A tuple of one item (a
          'singleton') can be formed by affixing a comma to an expression (an expression
          by itself does not create a tuple, since parentheses must be usable for grouping
          of expressions).  An empty tuple can be formed by an empty pair of parentheses.
 
-      .. % Immutable sequences
-
    Mutable sequences
       .. index::
          object: mutable sequence
          object: mutable
          pair: assignment; statement
          single: delete
          statement: del
          single: subscription
          single: slicing
 
       Mutable sequences can be changed after they are created.  The subscription and
       slicing notations can be used as the target of assignment and :keyword:`del`
@@ -367,27 +365,57 @@
       Lists
          .. index:: object: list
 
          The items of a list are arbitrary Python objects.  Lists are formed by placing a
          comma-separated list of expressions in square brackets. (Note that there are no
          special cases needed to form lists of length 0 or 1.)
 
       .. index:: module: array
 
       The extension module :mod:`array` provides an additional example of a mutable
       sequence type.
 
-      .. % Mutable sequences
+Set types
+   .. index::
+      builtin: len
+      object: set type
 
-   .. % Sequences
+   These represent unordered, finite sets of unique, immutable objects. As such,
+   they cannot be indexed by any subscript. However, they can be iterated over, and
+   the built-in function :func:`len` returns the number of items in a set. Common
+   uses for sets are fast membership testing, removing duplicates from a sequence,
+   and computing mathematical operations such as intersection, union, difference,
+   and symmetric difference.
+
+   For set elements, the same immutability rules apply as for dictionary keys. Note
+   that numeric types obey the normal rules for numeric comparison: if two numbers
+   compare equal (e.g., ``1`` and ``1.0``), only one of them can be contained in a
+   set.
+
+   There are currently two intrinsic set types:
+
+   Sets
+      .. index:: object: set
+
+      These represent a mutable set. They are created by the built-in :func:`set`
+      constructor and can be modified afterwards by several methods, such as
+      :meth:`add`.
+
+   Frozen sets
+      .. index:: object: frozenset
+
+      These represent an immutable set.  They are created by the built-in
+      :func:`frozenset` constructor.  As a frozenset is immutable and
+      :term:`hashable`, it can be used again as an element of another set, or as
+      a dictionary key.
 
 Mappings
    .. index::
       builtin: len
       single: subscription
       object: mapping
 
    These represent finite sets of objects indexed by arbitrary index sets. The
    subscript notation ``a[k]`` selects the item indexed by ``k`` from the mapping
    ``a``; this can be used in expressions and as the target of assignments or
    :keyword:`del` statements. The built-in function :func:`len` returns the number
    of items in a mapping.
@@ -398,55 +426,53 @@
       .. index:: object: dictionary
 
       These represent finite sets of objects indexed by nearly arbitrary values.  The
       only types of values not acceptable as keys are values containing lists or
       dictionaries or other mutable types that are compared by value rather than by
       object identity, the reason being that the efficient implementation of
       dictionaries requires a key's hash value to remain constant. Numeric types used
       for keys obey the normal rules for numeric comparison: if two numbers compare
       equal (e.g., ``1`` and ``1.0``) then they can be used interchangeably to index
       the same dictionary entry.
 
       Dictionaries are mutable; they can be created by the ``{...}`` notation (see
-      section :ref:`dict`, "Dictionary Displays").
+      section :ref:`dict`).
 
       .. index::
          module: dbm
          module: gdbm
          module: bsddb
 
       The extension modules :mod:`dbm`, :mod:`gdbm`, and :mod:`bsddb` provide
       additional examples of mapping types.
 
-   .. % Mapping types
-
 Callable types
    .. index::
       object: callable
       pair: function; call
       single: invocation
       pair: function; argument
 
    These are the types to which the function call operation (see section
-   :ref:`calls`, "Calls") can be applied:
+   :ref:`calls`) can be applied:
 
    User-defined functions
       .. index::
          pair: user-defined; function
          object: function
          object: user-defined function
 
-      A user-defined function object is created by a function definition (see section
-      :ref:`function`, "Function definitions").  It should be called with an argument
-      list containing the same number of items as the function's formal parameter
+      A user-defined function object is created by a function definition (see
+      section :ref:`function`).  It should be called with an argument list
+      containing the same number of items as the function's formal parameter
       list.
 
       Special attributes:
 
       +-----------------------+-------------------------------+-----------+
       | Attribute             | Meaning                       |           |
       +=======================+===============================+===========+
       | :attr:`func_doc`      | The function's documentation  | Writable  |
       |                       | string, or ``None`` if        |           |
       |                       | unavailable                   |           |
       +-----------------------+-------------------------------+-----------+
       | :attr:`__doc__`       | Another way of spelling       | Writable  |
@@ -524,55 +550,59 @@
 
       Special read-only attributes: :attr:`im_self` is the class instance object,
       :attr:`im_func` is the function object; :attr:`im_class` is the class of
       :attr:`im_self` for bound methods or the class that asked for the method for
       unbound methods; :attr:`__doc__` is the method's documentation (same as
       ``im_func.__doc__``); :attr:`__name__` is the method name (same as
       ``im_func.__name__``); :attr:`__module__` is the name of the module the method
       was defined in, or ``None`` if unavailable.
 
       .. versionchanged:: 2.2
          :attr:`im_self` used to refer to the class that defined the method.
 
+      .. versionchanged:: 2.6
+         For 3.0 forward-compatibility, :attr:`im_func` is also available as
+         :attr:`__func__`, and :attr:`im_self` as :attr:`__self__`.
+
       .. index::
          single: __doc__ (method attribute)
          single: __name__ (method attribute)
          single: __module__ (method attribute)
          single: im_func (method attribute)
          single: im_self (method attribute)
 
       Methods also support accessing (but not setting) the arbitrary function
       attributes on the underlying function object.
 
       User-defined method objects may be created when getting an attribute of a class
       (perhaps via an instance of that class), if that attribute is a user-defined
       function object, an unbound user-defined method object, or a class method
       object. When the attribute is a user-defined method object, a new method object
       is only created if the class from which it is being retrieved is the same as, or
       a derived class of, the class stored in the original method object; otherwise,
       the original method object is used as it is.
 
       .. index::
          single: im_class (method attribute)
          single: im_func (method attribute)
          single: im_self (method attribute)
 
       When a user-defined method object is created by retrieving a user-defined
-      function object from a class, its :attr:`im_self` attribute is ``None`` and the
-      method object is said to be unbound. When one is created by retrieving a user-
-      defined function object from a class via one of its instances, its
-      :attr:`im_self` attribute is the instance, and the method object is said to be
-      bound. In either case, the new method's :attr:`im_class` attribute is the class
-      from which the retrieval takes place, and its :attr:`im_func` attribute is the
-      original function object.
+      function object from a class, its :attr:`im_self` attribute is ``None``
+      and the method object is said to be unbound. When one is created by
+      retrieving a user-defined function object from a class via one of its
+      instances, its :attr:`im_self` attribute is the instance, and the method
+      object is said to be bound. In either case, the new method's
+      :attr:`im_class` attribute is the class from which the retrieval takes
+      place, and its :attr:`im_func` attribute is the original function object.
 
       .. index:: single: im_func (method attribute)
 
       When a user-defined method object is created by retrieving another method object
       from a class or instance, the behaviour is the same as for a function object,
       except that the :attr:`im_func` attribute of the new instance is not the
       original method object but its :attr:`im_func` attribute.
 
       .. index::
          single: im_class (method attribute)
          single: im_func (method attribute)
          single: im_self (method attribute)
@@ -605,47 +635,47 @@
       happens for user-defined functions; other callable objects (and all non-callable
       objects) are retrieved without transformation.  It is also important to note
       that user-defined functions which are attributes of a class instance are not
       converted to bound methods; this *only* happens when the function is an
       attribute of the class.
 
    Generator functions
       .. index::
          single: generator; function
          single: generator; iterator
 
       A function or method which uses the :keyword:`yield` statement (see section
-      :ref:`yield`, "The :keyword:`yield` statement") is called a :dfn:`generator
+      :ref:`yield`) is called a :dfn:`generator
       function`.  Such a function, when called, always returns an iterator object
       which can be used to execute the body of the function:  calling the iterator's
       :meth:`next` method will cause the function to execute until it provides a value
       using the :keyword:`yield` statement.  When the function executes a
       :keyword:`return` statement or falls off the end, a :exc:`StopIteration`
       exception is raised and the iterator will have reached the end of the set of
       values to be returned.
 
    Built-in functions
       .. index::
          object: built-in function
          object: function
          pair: C; language
 
-      A built-in function object is a wrapper around a C function.  Examples of built-
-      in functions are :func:`len` and :func:`math.sin` (:mod:`math` is a standard
-      built-in module). The number and type of the arguments are determined by the C
-      function. Special read-only attributes: :attr:`__doc__` is the function's
-      documentation string, or ``None`` if unavailable; :attr:`__name__` is the
-      function's name; :attr:`__self__` is set to ``None`` (but see the next item);
-      :attr:`__module__` is the name of the module the function was defined in or
-      ``None`` if unavailable.
+      A built-in function object is a wrapper around a C function.  Examples of
+      built-in functions are :func:`len` and :func:`math.sin` (:mod:`math` is a
+      standard built-in module). The number and type of the arguments are
+      determined by the C function. Special read-only attributes:
+      :attr:`__doc__` is the function's documentation string, or ``None`` if
+      unavailable; :attr:`__name__` is the function's name; :attr:`__self__` is
+      set to ``None`` (but see the next item); :attr:`__module__` is the name of
+      the module the function was defined in or ``None`` if unavailable.
 
    Built-in methods
       .. index::
          object: built-in method
          object: method
          pair: built-in; method
 
       This is really a different disguise of a built-in function, this time containing
       an object passed to the C function as an implicit extra argument.  An example of
       a built-in method is ``alist.append()``, assuming *alist* is a list object. In
       this case, the special read-only attribute :attr:`__self__` is set to the object
       denoted by *list*.
@@ -673,84 +703,93 @@
 
    Class instances
       Class instances are described below.  Class instances are callable only when the
       class has a :meth:`__call__` method; ``x(arguments)`` is a shorthand for
       ``x.__call__(arguments)``.
 
 Modules
    .. index::
       statement: import
       object: module
 
    Modules are imported by the :keyword:`import` statement (see section
-   :ref:`import`, "The :keyword:`import` statement"). A module object has a
+   :ref:`import`). A module object has a
    namespace implemented by a dictionary object (this is the dictionary referenced
    by the func_globals attribute of functions defined in the module).  Attribute
    references are translated to lookups in this dictionary, e.g., ``m.x`` is
    equivalent to ``m.__dict__["x"]``. A module object does not contain the code
    object used to initialize the module (since it isn't needed once the
    initialization is done).
 
-   .. % 
-
    Attribute assignment updates the module's namespace dictionary, e.g., ``m.x =
    1`` is equivalent to ``m.__dict__["x"] = 1``.
 
    .. index:: single: __dict__ (module attribute)
 
    Special read-only attribute: :attr:`__dict__` is the module's namespace as a
    dictionary object.
 
    .. index::
       single: __name__ (module attribute)
       single: __doc__ (module attribute)
       single: __file__ (module attribute)
       pair: module; namespace
 
    Predefined (writable) attributes: :attr:`__name__` is the module's name;
    :attr:`__doc__` is the module's documentation string, or ``None`` if
    unavailable; :attr:`__file__` is the pathname of the file from which the module
    was loaded, if it was loaded from a file. The :attr:`__file__` attribute is not
    present for C modules that are statically linked into the interpreter; for
    extension modules loaded dynamically from a shared library, it is the pathname
    of the shared library file.
 
 Classes
-   Class objects are created by class definitions (see section :ref:`class`, "Class
-   definitions"). A class has a namespace implemented by a dictionary object. Class
-   attribute references are translated to lookups in this dictionary, e.g., ``C.x``
-   is translated to ``C.__dict__["x"]``. When the attribute name is not found
-   there, the attribute search continues in the base classes.  The search is depth-
-   first, left-to-right in the order of occurrence in the base class list.
+   Both class types (new-style classes) and class objects (old-style/classic
+   classes) are typically created by class definitions (see section
+   :ref:`class`).  A class has a namespace implemented by a dictionary object.
+   Class attribute references are translated to lookups in this dictionary, e.g.,
+   ``C.x`` is translated to ``C.__dict__["x"]`` (although for new-style classes
+   in particular there are a number of hooks which allow for other means of
+   locating attributes). When the attribute name is not found there, the
+   attribute search continues in the base classes.  For old-style classes, the
+   search is depth-first, left-to-right in the order of occurrence in the base
+   class list. New-style classes use the more complex C3 method resolution
+   order which behaves correctly even in the presence of 'diamond'
+   inheritance structures where there are multiple inheritance paths
+   leading back to a common ancestor. Additional details on the C3 MRO used by
+   new-style classes can be found in the documentation accompanying the
+   2.3 release at http://www.python.org/download/releases/2.3/mro/.
+
+   .. XXX: Could we add that MRO doc as an appendix to the language ref?
 
    .. index::
       object: class
       object: class instance
       object: instance
       pair: class object; call
       single: container
       object: dictionary
       pair: class; attribute
 
-   When a class attribute reference (for class :class:`C`, say) would yield a user-
-   defined function object or an unbound user-defined method object whose
+   When a class attribute reference (for class :class:`C`, say) would yield a
+   user-defined function object or an unbound user-defined method object whose
    associated class is either :class:`C` or one of its base classes, it is
    transformed into an unbound user-defined method object whose :attr:`im_class`
    attribute is :class:`C`. When it would yield a class method object, it is
-   transformed into a bound user-defined method object whose :attr:`im_class` and
-   :attr:`im_self` attributes are both :class:`C`.  When it would yield a static
-   method object, it is transformed into the object wrapped by the static method
-   object. See section :ref:`descriptors` for another way in which attributes
-   retrieved from a class may differ from those actually contained in its
-   :attr:`__dict__`.
+   transformed into a bound user-defined method object whose :attr:`im_class`
+   and :attr:`im_self` attributes are both :class:`C`.  When it would yield a
+   static method object, it is transformed into the object wrapped by the static
+   method object. See section :ref:`descriptors` for another way in which
+   attributes retrieved from a class may differ from those actually contained in
+   its :attr:`__dict__` (note that only new-style classes support descriptors).
 
    .. index:: triple: class; attribute; assignment
 
    Class attribute assignments update the class's dictionary, never the dictionary
    of a base class.
 
    .. index:: pair: class object; call
 
    A class object can be called (see above) to yield a class instance (see below).
 
    .. index::
       single: __name__ (class attribute)
@@ -794,93 +833,92 @@
 
    Attribute assignments and deletions update the instance's dictionary, never a
    class's dictionary.  If the class has a :meth:`__setattr__` or
    :meth:`__delattr__` method, this is called instead of updating the instance
    dictionary directly.
 
    .. index::
       object: numeric
       object: sequence
       object: mapping
 
    Class instances can pretend to be numbers, sequences, or mappings if they have
-   methods with certain special names.  See section :ref:`specialnames`, "Special
-   method names."
+   methods with certain special names.  See section :ref:`specialnames`.
 
    .. index::
       single: __dict__ (instance attribute)
       single: __class__ (instance attribute)
 
    Special attributes: :attr:`__dict__` is the attribute dictionary;
    :attr:`__class__` is the instance's class.
 
 Files
    .. index::
       object: file
       builtin: open
       single: popen() (in module os)
       single: makefile() (socket method)
       single: sys.stdin
       single: sys.stdout
       single: sys.stderr
       single: stdio
       single: stdin (in module sys)
       single: stdout (in module sys)
       single: stderr (in module sys)
 
    A file object represents an open file.  File objects are created by the
-   :func:`open` built-in function, and also by :func:`os.popen`, :func:`os.fdopen`,
-   and the :meth:`makefile` method of socket objects (and perhaps by other
-   functions or methods provided by extension modules).  The objects ``sys.stdin``,
-   ``sys.stdout`` and ``sys.stderr`` are initialized to file objects corresponding
-   to the interpreter's standard input, output and error streams.  See the Python
-   Library Reference (XXX reference: ../lib/lib.html) for complete documentation of
+   :func:`open` built-in function, and also by :func:`os.popen`,
+   :func:`os.fdopen`, and the :meth:`makefile` method of socket objects (and
+   perhaps by other functions or methods provided by extension modules).  The
+   objects ``sys.stdin``, ``sys.stdout`` and ``sys.stderr`` are initialized to
+   file objects corresponding to the interpreter's standard input, output and
+   error streams.  See :ref:`bltin-file-objects` for complete documentation of
    file objects.
 
 Internal types
    .. index::
       single: internal type
       single: types, internal
 
    A few types used internally by the interpreter are exposed to the user. Their
    definitions may change with future versions of the interpreter, but they are
    mentioned here for completeness.
 
    Code objects
       .. index::
          single: bytecode
          object: code
 
-      Code objects represent *byte-compiled* executable Python code, or  *bytecode*.
+      Code objects represent *byte-compiled* executable Python code, or :term:`bytecode`.
       The difference between a code object and a function object is that the function
       object contains an explicit reference to the function's globals (the module in
-      which it was defined), while a code object contains no context;  also the
-      default argument values are stored in the function object, not in the code
-      object (because they represent values calculated at run-time).  Unlike function
+      which it was defined), while a code object contains no context; also the default
+      argument values are stored in the function object, not in the code object
+      (because they represent values calculated at run-time).  Unlike function
       objects, code objects are immutable and contain no references (directly or
       indirectly) to mutable objects.
 
       Special read-only attributes: :attr:`co_name` gives the function name;
       :attr:`co_argcount` is the number of positional arguments (including arguments
       with default values); :attr:`co_nlocals` is the number of local variables used
       by the function (including arguments); :attr:`co_varnames` is a tuple containing
       the names of the local variables (starting with the argument names);
       :attr:`co_cellvars` is a tuple containing the names of local variables that are
       referenced by nested functions; :attr:`co_freevars` is a tuple containing the
       names of free variables; :attr:`co_code` is a string representing the sequence
       of bytecode instructions; :attr:`co_consts` is a tuple containing the literals
       used by the bytecode; :attr:`co_names` is a tuple containing the names used by
       the bytecode; :attr:`co_filename` is the filename from which the code was
       compiled; :attr:`co_firstlineno` is the first line number of the function;
-      :attr:`co_lnotab` is a string encoding the mapping from byte code offsets to
+      :attr:`co_lnotab` is a string encoding the mapping from bytecode offsets to
       line numbers (for details see the source code of the interpreter);
       :attr:`co_stacksize` is the required stack size (including local variables);
       :attr:`co_flags` is an integer encoding a number of flags for the interpreter.
 
       .. index::
          single: co_argcount (code object attribute)
          single: co_code (code object attribute)
          single: co_consts (code object attribute)
          single: co_filename (code object attribute)
          single: co_firstlineno (code object attribute)
          single: co_flags (code object attribute)
          single: co_lnotab (code object attribute)
@@ -945,44 +983,42 @@
          single: f_lineno (frame attribute)
 
       Special writable attributes: :attr:`f_trace`, if not ``None``, is a function
       called at the start of each source code line (this is used by the debugger);
       :attr:`f_exc_type`, :attr:`f_exc_value`, :attr:`f_exc_traceback` represent the
       last exception raised in the parent frame provided another exception was ever
       raised in the current frame (in all other cases they are None); :attr:`f_lineno`
       is the current line number of the frame --- writing to this from within a trace
       function jumps to the given line (only for the bottom-most frame).  A debugger
       can implement a Jump command (aka Set Next Statement) by writing to f_lineno.
 
    Traceback objects
-      .. _traceback:
-
       .. index::
          object: traceback
          pair: stack; trace
          pair: exception; handler
          pair: execution; stack
          single: exc_info (in module sys)
          single: exc_traceback (in module sys)
          single: last_traceback (in module sys)
          single: sys.exc_info
          single: sys.exc_traceback
          single: sys.last_traceback
 
       Traceback objects represent a stack trace of an exception.  A traceback object
       is created when an exception occurs.  When the search for an exception handler
       unwinds the execution stack, at each unwound level a traceback object is
       inserted in front of the current traceback.  When an exception handler is
       entered, the stack trace is made available to the program. (See section
-      :ref:`try`, "The ``try`` statement.") It is accessible as ``sys.exc_traceback``,
+      :ref:`try`.) It is accessible as ``sys.exc_traceback``,
       and also as the third item of the tuple returned by ``sys.exc_info()``.  The
       latter is the preferred interface, since it works correctly when the program is
       using multiple threads. When the program contains no suitable handler, the stack
       trace is written (nicely formatted) to the standard error stream; if the
       interpreter is interactive, it is also made available to the user as
       ``sys.last_traceback``.
 
       .. index::
          single: tb_next (traceback attribute)
          single: tb_frame (traceback attribute)
          single: tb_lineno (traceback attribute)
          single: tb_lasti (traceback attribute)
@@ -1036,131 +1072,133 @@
       returned is the wrapped object, which is not subject to any further
       transformation. Static method objects are not themselves callable, although the
       objects they wrap usually are. Static method objects are created by the built-in
       :func:`staticmethod` constructor.
 
    Class method objects
       A class method object, like a static method object, is a wrapper around another
       object that alters the way in which that object is retrieved from classes and
       class instances. The behaviour of class method objects upon such retrieval is
       described above, under "User-defined methods". Class method objects are created
       by the built-in :func:`classmethod` constructor.
 
-   .. % Internal types
-
-.. % Types
-.. % =========================================================================
 
+.. _newstyle:
 
 New-style and classic classes
 =============================
 
-Classes and instances come in two flavors: old-style or classic, and new-style.
+Classes and instances come in two flavors: old-style (or classic) and new-style.
 
 Up to Python 2.1, old-style classes were the only flavour available to the user.
 The concept of (old-style) class is unrelated to the concept of type: if *x* is
 an instance of an old-style class, then ``x.__class__`` designates the class of
 *x*, but ``type(x)`` is always ``<type 'instance'>``.  This reflects the fact
 that all old-style instances, independently of their class, are implemented with
 a single built-in type, called ``instance``.
 
 New-style classes were introduced in Python 2.2 to unify classes and types.  A
-new-style class neither more nor less than a user-defined type.  If *x* is an
-instance of a new-style class, then ``type(x)`` is the same as ``x.__class__``.
+new-style class is neither more nor less than a user-defined type.  If *x* is an
+instance of a new-style class, then ``type(x)`` is typically the same as
+``x.__class__`` (although this is not guaranteed - a new-style class instance is
+permitted to override the value returned for ``x.__class__``).
 
 The major motivation for introducing new-style classes is to provide a unified
-object model with a full meta-model.  It also has a number of immediate
+object model with a full meta-model.  It also has a number of practical
 benefits, like the ability to subclass most built-in types, or the introduction
 of "descriptors", which enable computed properties.
 
 For compatibility reasons, classes are still old-style by default.  New-style
 classes are created by specifying another new-style class (i.e. a type) as a
 parent class, or the "top-level type" :class:`object` if no other parent is
 needed.  The behaviour of new-style classes differs from that of old-style
 classes in a number of important details in addition to what :func:`type`
 returns.  Some of these changes are fundamental to the new object model, like
 the way special methods are invoked.  Others are "fixes" that could not be
 implemented before for compatibility concerns, like the method resolution order
 in case of multiple inheritance.
 
-This manual is not up-to-date with respect to new-style classes.  For now,
-please see `<http://www.python.org/doc/newstyle.html>`_ for more information.
+While this manual aims to provide comprehensive coverage of Python's class
+mechanics, it may still be lacking in some areas when it comes to its coverage
+of new-style classes. Please see http://www.python.org/doc/newstyle/ for
+sources of additional information.
 
 .. index::
-   single: class
-   single: class
-   single: class
-
-The plan is to eventually drop old-style classes, leaving only the semantics of
-new-style classes.  This change will probably only be feasible in Python 3.0.
-new-style classic old-style
+   single: class; new-style
+   single: class; classic
+   single: class; old-style
 
-.. % =========================================================================
+Old-style classes are removed in Python 3.0, leaving only the semantics of
+new-style classes.
 
 
 .. _specialnames:
 
 Special method names
 ====================
 
 .. index::
    pair: operator; overloading
    single: __getitem__() (mapping object method)
 
 A class can implement certain operations that are invoked by special syntax
 (such as arithmetic operations or subscripting and slicing) by defining methods
 with special names. This is Python's approach to :dfn:`operator overloading`,
 allowing classes to define their own behavior with respect to language
 operators.  For instance, if a class defines a method named :meth:`__getitem__`,
-and ``x`` is an instance of this class, then ``x[i]`` is equivalent [#]_ to
-``x.__getitem__(i)``.  Except where mentioned, attempts to execute an operation
-raise an exception when no appropriate method is defined.
+and ``x`` is an instance of this class, then ``x[i]`` is roughly equivalent
+to ``x.__getitem__(i)`` for old-style classes and ``type(x).__getitem__(x, i)``
+for new-style classes.  Except where mentioned, attempts to execute an
+operation raise an exception when no appropriate method is defined (typically
+:exc:`AttributeError` or :exc:`TypeError`).
 
 When implementing a class that emulates any built-in type, it is important that
 the emulation only be implemented to the degree that it makes sense for the
 object being modelled.  For example, some sequences may work well with retrieval
 of individual elements, but extracting a slice may not make sense.  (One example
 of this is the :class:`NodeList` interface in the W3C's Document Object Model.)
 
 
 .. _customization:
 
 Basic customization
 -------------------
 
-
 .. method:: object.__new__(cls[, ...])
 
+   .. index:: pair: subclassing; immutable types
+
    Called to create a new instance of class *cls*.  :meth:`__new__` is a static
    method (special-cased so you need not declare it as such) that takes the class
    of which an instance was requested as its first argument.  The remaining
    arguments are those passed to the object constructor expression (the call to the
    class).  The return value of :meth:`__new__` should be the new object instance
    (usually an instance of *cls*).
 
    Typical implementations create a new instance of the class by invoking the
    superclass's :meth:`__new__` method using ``super(currentclass,
    cls).__new__(cls[, ...])`` with appropriate arguments and then modifying the
    newly-created instance as necessary before returning it.
 
    If :meth:`__new__` returns an instance of *cls*, then the new instance's
    :meth:`__init__` method will be invoked like ``__init__(self[, ...])``, where
    *self* is the new instance and the remaining arguments are the same as were
    passed to :meth:`__new__`.
 
    If :meth:`__new__` does not return an instance of *cls*, then the new instance's
    :meth:`__init__` method will not be invoked.
 
    :meth:`__new__` is intended mainly to allow subclasses of immutable types (like
-   int, str, or tuple) to customize instance creation.
+   int, str, or tuple) to customize instance creation.  It is also commonly
+   overridden in custom metaclasses in order to customize class creation.
 
 
 .. method:: object.__init__(self[, ...])
 
    .. index:: pair: class; constructor
 
    Called when the instance is created.  The arguments are those passed to the
    class constructor expression.  If a base class has an :meth:`__init__` method,
    the derived class's :meth:`__init__` method, if any, must explicitly call it to
    ensure proper initialization of the base class part of the instance; for
    example: ``BaseClass.__init__(self, [args...])``.  As a special constraint on
    constructors, no value may be returned; doing so will cause a :exc:`TypeError`
@@ -1176,51 +1214,54 @@
    Called when the instance is about to be destroyed.  This is also called a
    destructor.  If a base class has a :meth:`__del__` method, the derived class's
    :meth:`__del__` method, if any, must explicitly call it to ensure proper
    deletion of the base class part of the instance.  Note that it is possible
    (though not recommended!) for the :meth:`__del__` method to postpone destruction
    of the instance by creating a new reference to it.  It may then be called at a
    later time when this new reference is deleted.  It is not guaranteed that
    :meth:`__del__` methods are called for objects that still exist when the
    interpreter exits.
 
    .. note::
 
-      ``del x`` doesn't directly call ``x.__del__()`` --- the former decrements the
-      reference count for ``x`` by one, and the latter is only called when ``x``'s
-      reference count reaches zero.  Some common situations that may prevent the
-      reference count of an object from going to zero include: circular references
-      between objects (e.g., a doubly-linked list or a tree data structure with parent
-      and child pointers); a reference to the object on the stack frame of a function
-      that caught an exception (the traceback stored in ``sys.exc_traceback`` keeps
-      the stack frame alive); or a reference to the object on the stack frame that
-      raised an unhandled exception in interactive mode (the traceback stored in
-      ``sys.last_traceback`` keeps the stack frame alive).  The first situation can
-      only be remedied by explicitly breaking the cycles; the latter two situations
-      can be resolved by storing ``None`` in ``sys.exc_traceback`` or
-      ``sys.last_traceback``.  Circular references which are garbage are detected when
-      the option cycle detector is enabled (it's on by default), but can only be
-      cleaned up if there are no Python-level :meth:`__del__` methods involved. Refer
-      to the documentation for the :mod:`gc` module (XXX reference: ../lib/module-
-      gc.html) for more information about how :meth:`__del__` methods are handled by
-      the cycle detector, particularly the description of the ``garbage`` value.
+      ``del x`` doesn't directly call ``x.__del__()`` --- the former decrements
+      the reference count for ``x`` by one, and the latter is only called when
+      ``x``'s reference count reaches zero.  Some common situations that may
+      prevent the reference count of an object from going to zero include:
+      circular references between objects (e.g., a doubly-linked list or a tree
+      data structure with parent and child pointers); a reference to the object
+      on the stack frame of a function that caught an exception (the traceback
+      stored in ``sys.exc_traceback`` keeps the stack frame alive); or a
+      reference to the object on the stack frame that raised an unhandled
+      exception in interactive mode (the traceback stored in
+      ``sys.last_traceback`` keeps the stack frame alive).  The first situation
+      can only be remedied by explicitly breaking the cycles; the latter two
+      situations can be resolved by storing ``None`` in ``sys.exc_traceback`` or
+      ``sys.last_traceback``.  Circular references which are garbage are
+      detected when the option cycle detector is enabled (it's on by default),
+      but can only be cleaned up if there are no Python-level :meth:`__del__`
+      methods involved. Refer to the documentation for the :mod:`gc` module for
+      more information about how :meth:`__del__` methods are handled by the
+      cycle detector, particularly the description of the ``garbage`` value.
 
    .. warning::
 
       Due to the precarious circumstances under which :meth:`__del__` methods are
       invoked, exceptions that occur during their execution are ignored, and a warning
       is printed to ``sys.stderr`` instead.  Also, when :meth:`__del__` is invoked in
       response to a module being deleted (e.g., when execution of the program is
       done), other globals referenced by the :meth:`__del__` method may already have
-      been deleted.  For this reason, :meth:`__del__` methods should do the absolute
+      been deleted or in the process of being torn down (e.g. the import
+      machinery shutting down).  For this reason, :meth:`__del__` methods
+      should do the absolute
       minimum needed to maintain external invariants.  Starting with version 1.5,
       Python guarantees that globals whose name begins with a single underscore are
       deleted from their module before other globals are deleted; if no other
       references to such globals exist, this may help in assuring that imported
       modules are still available at the time when the :meth:`__del__` method is
       called.
 
 
 .. method:: object.__repr__(self)
 
    .. index:: builtin: repr
 
@@ -1257,108 +1298,137 @@
    The return value must be a string object.
 
 
 .. method:: object.__lt__(self, other)
             object.__le__(self, other)
             object.__eq__(self, other)
             object.__ne__(self, other)
             object.__gt__(self, other)
             object.__ge__(self, other)
 
    .. versionadded:: 2.1
 
+   .. index::
+      single: comparisons
+
    These are the so-called "rich comparison" methods, and are called for comparison
    operators in preference to :meth:`__cmp__` below. The correspondence between
    operator symbols and method names is as follows: ``x<y`` calls ``x.__lt__(y)``,
    ``x<=y`` calls ``x.__le__(y)``, ``x==y`` calls ``x.__eq__(y)``, ``x!=y`` and
    ``x<>y`` call ``x.__ne__(y)``, ``x>y`` calls ``x.__gt__(y)``, and ``x>=y`` calls
-   ``x.__ge__(y)``. These methods can return any value, but if the comparison
-   operator is used in a Boolean context, the return value should be interpretable
-   as a Boolean value, else a :exc:`TypeError` will be raised. By convention,
-   ``False`` is used for false and ``True`` for true.
-
-   There are no implied relationships among the comparison operators. The truth of
-   ``x==y`` does not imply that ``x!=y`` is false.  Accordingly, when defining
-   :meth:`__eq__`, one should also define :meth:`__ne__` so that the operators will
-   behave as expected.
-
-   There are no reflected (swapped-argument) versions of these methods (to be used
-   when the left argument does not support the operation but the right argument
-   does); rather, :meth:`__lt__` and :meth:`__gt__` are each other's reflection,
+   ``x.__ge__(y)``.
+
+   A rich comparison method may return the singleton ``NotImplemented`` if it does
+   not implement the operation for a given pair of arguments. By convention,
+   ``False`` and ``True`` are returned for a successful comparison. However, these
+   methods can return any value, so if the comparison operator is used in a Boolean
+   context (e.g., in the condition of an ``if`` statement), Python will call
+   :func:`bool` on the value to determine if the result is true or false.
+
+   There are no implied relationships among the comparison operators. The truth
+   of ``x==y`` does not imply that ``x!=y`` is false.  Accordingly, when
+   defining :meth:`__eq__`, one should also define :meth:`__ne__` so that the
+   operators will behave as expected.  See the paragraph on :meth:`__hash__` for
+   some important notes on creating :term:`hashable` objects which support
+   custom comparison operations and are usable as dictionary keys.
+
+   There are no swapped-argument versions of these methods (to be used when the
+   left argument does not support the operation but the right argument does);
+   rather, :meth:`__lt__` and :meth:`__gt__` are each other's reflection,
    :meth:`__le__` and :meth:`__ge__` are each other's reflection, and
    :meth:`__eq__` and :meth:`__ne__` are their own reflection.
 
-   Arguments to rich comparison methods are never coerced.  A rich comparison
-   method may return ``NotImplemented`` if it does not implement the operation for
-   a given pair of arguments.
+   Arguments to rich comparison methods are never coerced.
 
 
 .. method:: object.__cmp__(self, other)
 
    .. index::
       builtin: cmp
       single: comparisons
 
-   Called by comparison operations if rich comparison (see above) is not defined.
-   Should return a negative integer if ``self < other``, zero if ``self == other``,
-   a positive integer if ``self > other``.  If no :meth:`__cmp__`, :meth:`__eq__`
-   or :meth:`__ne__` operation is defined, class instances are compared by object
-   identity ("address").  See also the description of :meth:`__hash__` for some
-   important notes on creating objects which support custom comparison operations
-   and are usable as dictionary keys. (Note: the restriction that exceptions are
-   not propagated by :meth:`__cmp__` has been removed since Python 1.5.)
+   Called by comparison operations if rich comparison (see above) is not
+   defined.  Should return a negative integer if ``self < other``, zero if
+   ``self == other``, a positive integer if ``self > other``.  If no
+   :meth:`__cmp__`, :meth:`__eq__` or :meth:`__ne__` operation is defined, class
+   instances are compared by object identity ("address").  See also the
+   description of :meth:`__hash__` for some important notes on creating
+   :term:`hashable` objects which support custom comparison operations and are
+   usable as dictionary keys. (Note: the restriction that exceptions are not
+   propagated by :meth:`__cmp__` has been removed since Python 1.5.)
 
 
 .. method:: object.__rcmp__(self, other)
 
    .. versionchanged:: 2.1
       No longer supported.
 
 
 .. method:: object.__hash__(self)
 
    .. index::
       object: dictionary
       builtin: hash
 
-   Called for the key object for dictionary  operations, and by the built-in
-   function :func:`hash`.  Should return a 32-bit integer usable as a hash value
-   for dictionary operations.  The only required property is that objects which
-   compare equal have the same hash value; it is advised to somehow mix together
-   (e.g., using exclusive or) the hash values for the components of the object that
-   also play a part in comparison of objects.  If a class does not define a
-   :meth:`__cmp__` method it should not define a :meth:`__hash__` operation either;
-   if it defines :meth:`__cmp__` or :meth:`__eq__` but not :meth:`__hash__`, its
-   instances will not be usable as dictionary keys.  If a class defines mutable
-   objects and implements a :meth:`__cmp__` or :meth:`__eq__` method, it should not
-   implement :meth:`__hash__`, since the dictionary implementation requires that a
-   key's hash value is immutable (if the object's hash value changes, it will be in
-   the wrong hash bucket).
+   Called by built-in function :func:`hash` and for operations on members of
+   hashed collections including :class:`set`, :class:`frozenset`, and
+   :class:`dict`.  :meth:`__hash__` should return an integer.  The only required
+   property is that objects which compare equal have the same hash value; it is
+   advised to somehow mix together (e.g. using exclusive or) the hash values for
+   the components of the object that also play a part in comparison of objects.
+
+   If a class does not define a :meth:`__cmp__` or :meth:`__eq__` method it
+   should not define a :meth:`__hash__` operation either; if it defines
+   :meth:`__cmp__` or :meth:`__eq__` but not :meth:`__hash__`, its instances
+   will not be usable in hashed collections.  If a class defines mutable objects
+   and implements a :meth:`__cmp__` or :meth:`__eq__` method, it should not
+   implement :meth:`__hash__`, since hashable collection implementations require
+   that a object's hash value is immutable (if the object's hash value changes,
+   it will be in the wrong hash bucket).
+
+   User-defined classes have :meth:`__cmp__` and :meth:`__hash__` methods
+   by default; with them, all objects compare unequal (except with themselves)
+   and ``x.__hash__()`` returns ``id(x)``.
+
+   Classes which inherit a :meth:`__hash__` method from a parent class but
+   change the meaning of :meth:`__cmp__` or :meth:`__eq__` such that the hash
+   value returned is no longer appropriate (e.g. by switching to a value-based
+   concept of equality instead of the default identity based equality) can
+   explicitly flag themselves as being unhashable by setting ``__hash__ = None``
+   in the class definition. Doing so means that not only will instances of the
+   class raise an appropriate :exc:`TypeError` when a program attempts to
+   retrieve their hash value, but they will also be correctly identified as
+   unhashable when checking ``isinstance(obj, collections.Hashable)`` (unlike
+   classes which define their own :meth:`__hash__` to explicitly raise
+   :exc:`TypeError`).
 
    .. versionchanged:: 2.5
-      :meth:`__hash__` may now also return a long integer object; the 32-bit integer
-      is then derived from the hash of that object.
+      :meth:`__hash__` may now also return a long integer object; the 32-bit
+      integer is then derived from the hash of that object.
 
-   .. index:: single: __cmp__() (object method)
+   .. versionchanged:: 2.6
+      :attr:`__hash__` may now be set to :const:`None` to explicitly flag
+      instances of a class as unhashable.
 
 
 .. method:: object.__nonzero__(self)
 
    .. index:: single: __len__() (mapping object method)
 
-   Called to implement truth value testing, and the built-in operation ``bool()``;
+   Called to implement truth value testing and the built-in operation ``bool()``;
    should return ``False`` or ``True``, or their integer equivalents ``0`` or
-   ``1``. When this method is not defined, :meth:`__len__` is called, if it is
-   defined (see below).  If a class defines neither :meth:`__len__` nor
-   :meth:`__nonzero__`, all its instances are considered true.
+   ``1``.  When this method is not defined, :meth:`__len__` is called, if it is
+   defined, and the object is considered true if its result is nonzero.
+   If a class defines neither :meth:`__len__` nor :meth:`__nonzero__`, all its
+   instances are considered true.
 
 
 .. method:: object.__unicode__(self)
 
    .. index:: builtin: unicode
 
    Called to implement :func:`unicode` builtin; should return a Unicode object.
    When this method is not defined, string conversion is attempted, and the result
    of string conversion is converted to Unicode using the system default encoding.
 
 
 .. _attribute-access:
@@ -1373,41 +1443,41 @@
 .. method:: object.__getattr__(self, name)
 
    Called when an attribute lookup has not found the attribute in the usual places
    (i.e. it is not an instance attribute nor is it found in the class tree for
    ``self``).  ``name`` is the attribute name. This method should return the
    (computed) attribute value or raise an :exc:`AttributeError` exception.
 
    .. index:: single: __setattr__() (object method)
 
    Note that if the attribute is found through the normal mechanism,
    :meth:`__getattr__` is not called.  (This is an intentional asymmetry between
    :meth:`__getattr__` and :meth:`__setattr__`.) This is done both for efficiency
-   reasons and because otherwise :meth:`__setattr__` would have no way to access
+   reasons and because otherwise :meth:`__getattr__` would have no way to access
    other attributes of the instance.  Note that at least for instance variables,
    you can fake total control by not inserting any values in the instance attribute
    dictionary (but instead inserting them in another object).  See the
    :meth:`__getattribute__` method below for a way to actually get total control in
    new-style classes.
 
 
 .. method:: object.__setattr__(self, name, value)
 
    Called when an attribute assignment is attempted.  This is called instead of the
    normal mechanism (i.e. store the value in the instance dictionary).  *name* is
    the attribute name, *value* is the value to be assigned to it.
 
    .. index:: single: __dict__ (instance attribute)
 
-   If :meth:`__setattr__` wants to assign to an instance attribute, it  should not
+   If :meth:`__setattr__` wants to assign to an instance attribute, it should not
    simply execute ``self.name = value`` --- this would cause a recursive call to
    itself.  Instead, it should insert the value in the dictionary of instance
    attributes, e.g., ``self.__dict__[name] = value``.  For new-style classes,
    rather than accessing the instance dictionary, it should call the base class
    method with the same name, for example, ``object.__setattr__(self, name,
    value)``.
 
 
 .. method:: object.__delattr__(self, name)
 
    Like :meth:`__setattr__` but for attribute deletion instead of assignment.  This
    should only be implemented if ``del obj.name`` is meaningful for the object.
@@ -1415,32 +1485,38 @@
 
 .. _new-style-attribute-access:
 
 More attribute access for new-style classes
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The following methods only apply to new-style classes.
 
 
 .. method:: object.__getattribute__(self, name)
 
    Called unconditionally to implement attribute accesses for instances of the
-   class. If the class also defines :meth:`__getattr__`, the latter  will not be
-   called unless :meth:`__getattribute__` either calls it  explicitly or raises an
+   class. If the class also defines :meth:`__getattr__`, the latter will not be
+   called unless :meth:`__getattribute__` either calls it explicitly or raises an
    :exc:`AttributeError`. This method should return the (computed) attribute value
    or raise an :exc:`AttributeError` exception. In order to avoid infinite
    recursion in this method, its implementation should always call the base class
    method with the same name to access any attributes it needs, for example,
    ``object.__getattribute__(self, name)``.
 
+   .. note::
+
+      This method may still be bypassed when looking up special methods as the
+      result of implicit invocation via language syntax or builtin functions.
+      See :ref:`new-style-special-lookup`.
+
 
 .. _descriptors:
 
 Implementing Descriptors
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
 The following methods only apply when an instance of the class containing the
 method (a so-called *descriptor* class) appears in the class dictionary of
 another new-style class, known as the *owner* class. In the examples below, "the
 attribute" refers to the attribute whose name is the key of the property in the
 owner class' ``__dict__``.  Descriptors can only be implemented as new-style
 classes themselves.
@@ -1471,25 +1547,25 @@
 
 Invoking Descriptors
 ^^^^^^^^^^^^^^^^^^^^
 
 In general, a descriptor is an object attribute with "binding behavior", one
 whose attribute access has been overridden by methods in the descriptor
 protocol:  :meth:`__get__`, :meth:`__set__`, and :meth:`__delete__`. If any of
 those methods are defined for an object, it is said to be a descriptor.
 
 The default behavior for attribute access is to get, set, or delete the
 attribute from an object's dictionary. For instance, ``a.x`` has a lookup chain
 starting with ``a.__dict__['x']``, then ``type(a).__dict__['x']``, and
-continuing  through the base classes of ``type(a)`` excluding metaclasses.
+continuing through the base classes of ``type(a)`` excluding metaclasses.
 
 However, if the looked-up value is an object defining one of the descriptor
 methods, then Python may override the default behavior and invoke the descriptor
 method instead.  Where this occurs in the precedence chain depends on which
 descriptor methods were defined and how they were called.  Note that descriptors
 are only invoked for new style objects or classes (ones that subclass
 :class:`object()` or :class:`type()`).
 
 The starting point for descriptor invocation is a binding, ``a.x``. How the
 arguments are assembled depends on ``a``:
 
 Direct Call
@@ -1502,29 +1578,29 @@
 
 Class Binding
    If binding to a new-style class, ``A.x`` is transformed into the call:
    ``A.__dict__['x'].__get__(None, A)``.
 
 Super Binding
    If ``a`` is an instance of :class:`super`, then the binding ``super(B,
    obj).m()`` searches ``obj.__class__.__mro__`` for the base class ``A``
    immediately preceding ``B`` and then invokes the descriptor with the call:
    ``A.__dict__['m'].__get__(obj, A)``.
 
 For instance bindings, the precedence of descriptor invocation depends on the
-which descriptor methods are defined.  Data descriptors define both
-:meth:`__get__` and :meth:`__set__`.  Non-data descriptors have just the
+which descriptor methods are defined.  Normally, data descriptors define both
+:meth:`__get__` and :meth:`__set__`, while non-data descriptors have just the
 :meth:`__get__` method.  Data descriptors always override a redefinition in an
 instance dictionary.  In contrast, non-data descriptors can be overridden by
-instances.
+instances. [#]_
 
 Python methods (including :func:`staticmethod` and :func:`classmethod`) are
 implemented as non-data descriptors.  Accordingly, instances can redefine and
 override methods.  This allows individual instances to acquire behaviors that
 differ from other instances of the same class.
 
 The :func:`property` function is implemented as a data descriptor. Accordingly,
 instances cannot override the behavior of a property.
 
 
 .. _slots:
 
@@ -1544,24 +1620,28 @@
 
 .. data:: __slots__
 
    This class variable can be assigned a string, iterable, or sequence of strings
    with variable names used by instances.  If defined in a new-style class,
    *__slots__* reserves space for the declared variables and prevents the automatic
    creation of *__dict__* and *__weakref__* for each instance.
 
    .. versionadded:: 2.2
 
 Notes on using *__slots__*
 
+* When inheriting from a class without *__slots__*, the *__dict__* attribute of
+  that class will always be accessible, so a *__slots__* definition in the
+  subclass is meaningless.
+
 * Without a *__dict__* variable, instances cannot be assigned new variables not
   listed in the *__slots__* definition.  Attempts to assign to an unlisted
   variable name raises :exc:`AttributeError`. If dynamic assignment of new
   variables is desired, then add ``'__dict__'`` to the sequence of strings in the
   *__slots__* declaration.
 
   .. versionchanged:: 2.3
      Previously, adding ``'__dict__'`` to the *__slots__* declaration would not
      enable the assignment of new attributes not specifically listed in the sequence
      of instance variable names.
 
 * Without a *__weakref__* variable for each instance, classes defining
@@ -1579,51 +1659,71 @@
   *__slots__*; otherwise, the class attribute would overwrite the descriptor
   assignment.
 
 * If a class defines a slot also defined in a base class, the instance variable
   defined by the base class slot is inaccessible (except by retrieving its
   descriptor directly from the base class). This renders the meaning of the
   program undefined.  In the future, a check may be added to prevent this.
 
 * The action of a *__slots__* declaration is limited to the class where it is
   defined.  As a result, subclasses will have a *__dict__* unless they also define
   *__slots__*.
 
-* *__slots__* do not work for classes derived from "variable-length" built-in
-  types such as :class:`long`, :class:`str` and :class:`tuple`.
+* Nonempty *__slots__* does not work for classes derived from "variable-length"
+  built-in types such as :class:`long`, :class:`str` and :class:`tuple`.
 
 * Any non-string iterable may be assigned to *__slots__*. Mappings may also be
   used; however, in the future, special meaning may be assigned to the values
   corresponding to each key.
 
+* *__class__* assignment works only if both classes have the same *__slots__*.
+
+  .. versionchanged:: 2.6
+     Previously, *__class__* assignment raised an error if either new or old class
+     had *__slots__*.
+
 
 .. _metaclasses:
 
 Customizing class creation
 --------------------------
 
 By default, new-style classes are constructed using :func:`type`. A class
 definition is read into a separate namespace and the value of class name is
 bound to the result of ``type(name, bases, dict)``.
 
 When the class definition is read, if *__metaclass__* is defined then the
-callable assigned to it will be called instead of :func:`type`. The allows
+callable assigned to it will be called instead of :func:`type`. This allows
 classes or functions to be written which monitor or alter the class creation
 process:
 
 * Modifying the class dictionary prior to the class being created.
 
 * Returning an instance of another class -- essentially performing the role of a
   factory function.
 
+These steps will have to be performed in the metaclass's :meth:`__new__` method
+-- :meth:`type.__new__` can then be called from this method to create a class
+with different properties.  This example adds a new element to the class
+dictionary before creating the class::
+
+  class metacls(type):
+      def __new__(mcs, name, bases, dict):
+          dict['foo'] = 'metacls was here'
+          return type.__new__(mcs, name, bases, dict)
+
+You can of course also override other class methods (or add new methods); for
+example defining a custom :meth:`__call__` method in the metaclass allows custom
+behavior when the class is called, e.g. not always creating a new instance.
+
 
 .. data:: __metaclass__
 
    This variable can be any callable accepting arguments for ``name``, ``bases``,
    and ``dict``.  Upon class creation, the callable is used instead of the built-in
    :func:`type`.
 
    .. versionadded:: 2.2
 
 The appropriate metaclass is determined by the following precedence rules:
 
 * If ``dict['__metaclass__']`` exists, it is used.
@@ -1651,203 +1751,184 @@
 
    .. index:: pair: call; instance
 
    Called when the instance is "called" as a function; if this method is defined,
    ``x(arg1, arg2, ...)`` is a shorthand for ``x.__call__(arg1, arg2, ...)``.
 
 
 .. _sequence-types:
 
 Emulating container types
 -------------------------
 
-.. index::
-   single: keys() (mapping object method)
-   single: values() (mapping object method)
-   single: items() (mapping object method)
-   single: iterkeys() (mapping object method)
-   single: itervalues() (mapping object method)
-   single: iteritems() (mapping object method)
-   single: has_key() (mapping object method)
-   single: get() (mapping object method)
-   single: setdefault() (mapping object method)
-   single: pop() (mapping object method)
-   single: popitem() (mapping object method)
-   single: clear() (mapping object method)
-   single: copy() (mapping object method)
-   single: update() (mapping object method)
-   single: __contains__() (mapping object method)
-   single: append() (sequence object method)
-   single: count() (sequence object method)
-   single: extend() (sequence object method)
-   single: index() (sequence object method)
-   single: insert() (sequence object method)
-   single: pop() (sequence object method)
-   single: remove() (sequence object method)
-   single: reverse() (sequence object method)
-   single: sort() (sequence object method)
-   single: __add__() (sequence object method)
-   single: __radd__() (sequence object method)
-   single: __iadd__() (sequence object method)
-   single: __mul__() (sequence object method)
-   single: __rmul__() (sequence object method)
-   single: __imul__() (sequence object method)
-   single: __contains__() (sequence object method)
-   single: __iter__() (sequence object method)
-   single: __coerce__() (numeric object method)
-
 The following methods can be defined to implement container objects.  Containers
 usually are sequences (such as lists or tuples) or mappings (like dictionaries),
 but can represent other containers as well.  The first set of methods is used
 either to emulate a sequence or to emulate a mapping; the difference is that for
 a sequence, the allowable keys should be the integers *k* for which ``0 <= k <
 N`` where *N* is the length of the sequence, or slice objects, which define a
 range of items. (For backwards compatibility, the method :meth:`__getslice__`
 (see below) can also be defined to handle simple, but not extended slices.) It
 is also recommended that mappings provide the methods :meth:`keys`,
 :meth:`values`, :meth:`items`, :meth:`has_key`, :meth:`get`, :meth:`clear`,
 :meth:`setdefault`, :meth:`iterkeys`, :meth:`itervalues`, :meth:`iteritems`,
-:meth:`pop`, :meth:`popitem`,                 :meth:`copy`, and :meth:`update`
-behaving similar to those for Python's standard dictionary objects.  The
-:mod:`UserDict` module provides a :class:`DictMixin` class to help create those
-methods from a base set of :meth:`__getitem__`, :meth:`__setitem__`,
-:meth:`__delitem__`, and :meth:`keys`.                   Mutable sequences
-should provide methods :meth:`append`, :meth:`count`, :meth:`index`,
-:meth:`extend`,                  :meth:`insert`, :meth:`pop`, :meth:`remove`,
-:meth:`reverse` and :meth:`sort`, like Python standard list objects.  Finally,
-sequence types should implement addition (meaning concatenation) and
-multiplication (meaning repetition) by defining the methods :meth:`__add__`,
-:meth:`__radd__`, :meth:`__iadd__`, :meth:`__mul__`, :meth:`__rmul__` and
-:meth:`__imul__` described below; they should not define :meth:`__coerce__` or
-other numerical operators.  It is recommended that both mappings and sequences
-implement the :meth:`__contains__` method to allow efficient use of the ``in``
-operator; for mappings, ``in`` should be equivalent of :meth:`has_key`; for
-sequences, it should search through the values.  It is further recommended that
-both mappings and sequences implement the :meth:`__iter__` method to allow
-efficient iteration through the container; for mappings, :meth:`__iter__` should
-be the same as :meth:`iterkeys`; for sequences, it should iterate through the
-values.
+:meth:`pop`, :meth:`popitem`, :meth:`copy`, and :meth:`update` behaving similar
+to those for Python's standard dictionary objects.  The :mod:`UserDict` module
+provides a :class:`DictMixin` class to help create those methods from a base set
+of :meth:`__getitem__`, :meth:`__setitem__`, :meth:`__delitem__`, and
+:meth:`keys`. Mutable sequences should provide methods :meth:`append`,
+:meth:`count`, :meth:`index`, :meth:`extend`, :meth:`insert`, :meth:`pop`,
+:meth:`remove`, :meth:`reverse` and :meth:`sort`, like Python standard list
+objects.  Finally, sequence types should implement addition (meaning
+concatenation) and multiplication (meaning repetition) by defining the methods
+:meth:`__add__`, :meth:`__radd__`, :meth:`__iadd__`, :meth:`__mul__`,
+:meth:`__rmul__` and :meth:`__imul__` described below; they should not define
+:meth:`__coerce__` or other numerical operators.  It is recommended that both
+mappings and sequences implement the :meth:`__contains__` method to allow
+efficient use of the ``in`` operator; for mappings, ``in`` should be equivalent
+of :meth:`has_key`; for sequences, it should search through the values.  It is
+further recommended that both mappings and sequences implement the
+:meth:`__iter__` method to allow efficient iteration through the container; for
+mappings, :meth:`__iter__` should be the same as :meth:`iterkeys`; for
+sequences, it should iterate through the values.
 
 
-.. method:: container object.__len__(self)
+.. method:: object.__len__(self)
 
    .. index::
       builtin: len
       single: __nonzero__() (object method)
 
    Called to implement the built-in function :func:`len`.  Should return the length
    of the object, an integer ``>=`` 0.  Also, an object that doesn't define a
    :meth:`__nonzero__` method and whose :meth:`__len__` method returns zero is
    considered to be false in a Boolean context.
 
 
-.. method:: container object.__getitem__(self, key)
+.. method:: object.__getitem__(self, key)
 
    .. index:: object: slice
 
    Called to implement evaluation of ``self[key]``. For sequence types, the
    accepted keys should be integers and slice objects.  Note that the special
    interpretation of negative indexes (if the class wishes to emulate a sequence
    type) is up to the :meth:`__getitem__` method. If *key* is of an inappropriate
    type, :exc:`TypeError` may be raised; if of a value outside the set of indexes
    for the sequence (after any special interpretation of negative values),
    :exc:`IndexError` should be raised. For mapping types, if *key* is missing (not
    in the container), :exc:`KeyError` should be raised.
 
    .. note::
 
       :keyword:`for` loops expect that an :exc:`IndexError` will be raised for illegal
       indexes to allow proper detection of the end of the sequence.
 
 
-.. method:: container object.__setitem__(self, key, value)
+.. method:: object.__setitem__(self, key, value)
 
    Called to implement assignment to ``self[key]``.  Same note as for
    :meth:`__getitem__`.  This should only be implemented for mappings if the
    objects support changes to the values for keys, or if new keys can be added, or
    for sequences if elements can be replaced.  The same exceptions should be raised
    for improper *key* values as for the :meth:`__getitem__` method.
 
 
-.. method:: container object.__delitem__(self, key)
+.. method:: object.__delitem__(self, key)
 
    Called to implement deletion of ``self[key]``.  Same note as for
    :meth:`__getitem__`.  This should only be implemented for mappings if the
    objects support removal of keys, or for sequences if elements can be removed
    from the sequence.  The same exceptions should be raised for improper *key*
    values as for the :meth:`__getitem__` method.
 
 
-.. method:: container object.__iter__(self)
+.. method:: object.__iter__(self)
 
    This method is called when an iterator is required for a container. This method
    should return a new iterator object that can iterate over all the objects in the
    container.  For mappings, it should iterate over the keys of the container, and
    should also be made available as the method :meth:`iterkeys`.
 
    Iterator objects also need to implement this method; they are required to return
-   themselves.  For more information on iterator objects, see "Iterator Types (XXX
-   reference: ../lib/typeiter.html)" in the Python Library Reference (XXX
-   reference: ../lib/lib.html).
+   themselves.  For more information on iterator objects, see :ref:`typeiter`.
+
+
+.. method:: object.__reversed__(self)
+
+   Called (if present) by the :func:`reversed` builtin to implement
+   reverse iteration.  It should return a new iterator object that iterates
+   over all the objects in the container in reverse order.
+
+   If the :meth:`__reversed__` method is not provided, the
+   :func:`reversed` builtin will fall back to using the sequence protocol
+   (:meth:`__len__` and :meth:`__getitem__`).  Objects should normally
+   only provide :meth:`__reversed__` if they do not support the sequence
+   protocol and an efficient implementation of reverse iteration is possible.
+
+   .. versionadded:: 2.6
+
 
 The membership test operators (:keyword:`in` and :keyword:`not in`) are normally
 implemented as an iteration through a sequence.  However, container objects can
 supply the following special method with a more efficient implementation, which
 also does not require the object be a sequence.
 
 
-.. method:: container object.__contains__(self, item)
+.. method:: object.__contains__(self, item)
 
    Called to implement membership test operators.  Should return true if *item* is
    in *self*, false otherwise.  For mapping objects, this should consider the keys
    of the mapping rather than the values or the key-item pairs.
 
 
 .. _sequence-methods:
 
 Additional methods for emulation of sequence types
 --------------------------------------------------
 
 The following optional methods can be defined to further emulate sequence
 objects.  Immutable sequences methods should at most only define
 :meth:`__getslice__`; mutable sequences might define all three methods.
 
 
-.. method:: sequence object.__getslice__(self, i, j)
+.. method:: object.__getslice__(self, i, j)
 
    .. deprecated:: 2.0
       Support slice objects as parameters to the :meth:`__getitem__` method.
+      (However, built-in types in CPython currently still implement
+      :meth:`__getslice__`.  Therefore, you have to override it in derived
+      classes when implementing slicing.)
 
    Called to implement evaluation of ``self[i:j]``. The returned object should be
    of the same type as *self*.  Note that missing *i* or *j* in the slice
    expression are replaced by zero or ``sys.maxint``, respectively.  If negative
    indexes are used in the slice, the length of the sequence is added to that
    index. If the instance does not implement the :meth:`__len__` method, an
    :exc:`AttributeError` is raised. No guarantee is made that indexes adjusted this
    way are not still negative.  Indexes which are greater than the length of the
    sequence are not modified. If no :meth:`__getslice__` is found, a slice object
    is created instead, and passed to :meth:`__getitem__` instead.
 
 
-.. method:: sequence object.__setslice__(self, i, j, sequence)
+.. method:: object.__setslice__(self, i, j, sequence)
 
    Called to implement assignment to ``self[i:j]``. Same notes for *i* and *j* as
    for :meth:`__getslice__`.
 
    This method is deprecated. If no :meth:`__setslice__` is found, or for extended
    slicing of the form ``self[i:j:k]``, a slice object is created, and passed to
    :meth:`__setitem__`, instead of :meth:`__setslice__` being called.
 
 
-.. method:: sequence object.__delslice__(self, i, j)
+.. method:: object.__delslice__(self, i, j)
 
    Called to implement deletion of ``self[i:j]``. Same notes for *i* and *j* as for
    :meth:`__getslice__`. This method is deprecated. If no :meth:`__delslice__` is
    found, or for extended slicing of the form ``self[i:j:k]``, a slice object is
    created, and passed to :meth:`__delitem__`, instead of :meth:`__delslice__`
    being called.
 
 Notice that these methods are only invoked when a single slice with a single
 colon is used, and the slice method is available.  For slice operations
 involving extended slice notation, or in absence of the slice methods,
 :meth:`__getitem__`, :meth:`__setitem__` or :meth:`__delitem__` is called with a
 slice object as argument.
@@ -1893,179 +1974,179 @@
 
 .. _numeric-types:
 
 Emulating numeric types
 -----------------------
 
 The following methods can be defined to emulate numeric objects. Methods
 corresponding to operations that are not supported by the particular kind of
 number implemented (e.g., bitwise operations for non-integral numbers) should be
 left undefined.
 
 
-.. method:: numeric object.__add__(self, other)
-            numeric object.__sub__(self, other)
-            numeric object.__mul__(self, other)
-            numeric object.__floordiv__(self, other)
-            numeric object.__mod__(self, other)
-            numeric object.__divmod__(self, other)
-            numeric object.__pow__(self, other[, modulo])
-            numeric object.__lshift__(self, other)
-            numeric object.__rshift__(self, other)
-            numeric object.__and__(self, other)
-            numeric object.__xor__(self, other)
-            numeric object.__or__(self, other)
+.. method:: object.__add__(self, other)
+            object.__sub__(self, other)
+            object.__mul__(self, other)
+            object.__floordiv__(self, other)
+            object.__mod__(self, other)
+            object.__divmod__(self, other)
+            object.__pow__(self, other[, modulo])
+            object.__lshift__(self, other)
+            object.__rshift__(self, other)
+            object.__and__(self, other)
+            object.__xor__(self, other)
+            object.__or__(self, other)
 
    .. index::
       builtin: divmod
       builtin: pow
       builtin: pow
 
    These methods are called to implement the binary arithmetic operations (``+``,
    ``-``, ``*``, ``//``, ``%``, :func:`divmod`, :func:`pow`, ``**``, ``<<``,
    ``>>``, ``&``, ``^``, ``|``).  For instance, to evaluate the expression
-   *x*``+``*y*, where *x* is an instance of a class that has an :meth:`__add__`
+   ``x + y``, where *x* is an instance of a class that has an :meth:`__add__`
    method, ``x.__add__(y)`` is called.  The :meth:`__divmod__` method should be the
    equivalent to using :meth:`__floordiv__` and :meth:`__mod__`; it should not be
    related to :meth:`__truediv__` (described below).  Note that :meth:`__pow__`
    should be defined to accept an optional third argument if the ternary version of
    the built-in :func:`pow` function is to be supported.
 
    If one of those methods does not support the operation with the supplied
    arguments, it should return ``NotImplemented``.
 
 
-.. method:: numeric object.__div__(self, other)
-            numeric object.__truediv__(self, other)
+.. method:: object.__div__(self, other)
+            object.__truediv__(self, other)
 
    The division operator (``/``) is implemented by these methods.  The
    :meth:`__truediv__` method is used when ``__future__.division`` is in effect,
    otherwise :meth:`__div__` is used.  If only one of these two methods is defined,
    the object will not support division in the alternate context; :exc:`TypeError`
    will be raised instead.
 
 
-.. method:: numeric object.__radd__(self, other)
-            numeric object.__rsub__(self, other)
-            numeric object.__rmul__(self, other)
-            numeric object.__rdiv__(self, other)
-            numeric object.__rtruediv__(self, other)
-            numeric object.__rfloordiv__(self, other)
-            numeric object.__rmod__(self, other)
-            numeric object.__rdivmod__(self, other)
-            numeric object.__rpow__(self, other)
-            numeric object.__rlshift__(self, other)
-            numeric object.__rrshift__(self, other)
-            numeric object.__rand__(self, other)
-            numeric object.__rxor__(self, other)
-            numeric object.__ror__(self, other)
+.. method:: object.__radd__(self, other)
+            object.__rsub__(self, other)
+            object.__rmul__(self, other)
+            object.__rdiv__(self, other)
+            object.__rtruediv__(self, other)
+            object.__rfloordiv__(self, other)
+            object.__rmod__(self, other)
+            object.__rdivmod__(self, other)
+            object.__rpow__(self, other)
+            object.__rlshift__(self, other)
+            object.__rrshift__(self, other)
+            object.__rand__(self, other)
+            object.__rxor__(self, other)
+            object.__ror__(self, other)
 
    .. index::
       builtin: divmod
       builtin: pow
 
    These methods are called to implement the binary arithmetic operations (``+``,
    ``-``, ``*``, ``/``, ``%``, :func:`divmod`, :func:`pow`, ``**``, ``<<``, ``>>``,
    ``&``, ``^``, ``|``) with reflected (swapped) operands.  These functions are
    only called if the left operand does not support the corresponding operation and
-   the operands are of different types. [#]_  For instance, to evaluate the
-   expression *x*``-``*y*, where *y* is an instance of a class that has an
+   the operands are of different types. [#]_ For instance, to evaluate the
+   expression ``x - y``, where *y* is an instance of a class that has an
    :meth:`__rsub__` method, ``y.__rsub__(x)`` is called if ``x.__sub__(y)`` returns
    *NotImplemented*.
 
    .. index:: builtin: pow
 
    Note that ternary :func:`pow` will not try calling :meth:`__rpow__` (the
    coercion rules would become too complicated).
 
    .. note::
 
       If the right operand's type is a subclass of the left operand's type and that
       subclass provides the reflected method for the operation, this method will be
       called before the left operand's non-reflected method.  This behavior allows
       subclasses to override their ancestors' operations.
 
 
-.. method:: numeric object.__iadd__(self, other)
-            numeric object.__isub__(self, other)
-            numeric object.__imul__(self, other)
-            numeric object.__idiv__(self, other)
-            numeric object.__itruediv__(self, other)
-            numeric object.__ifloordiv__(self, other)
-            numeric object.__imod__(self, other)
-            numeric object.__ipow__(self, other[, modulo])
-            numeric object.__ilshift__(self, other)
-            numeric object.__irshift__(self, other)
-            numeric object.__iand__(self, other)
-            numeric object.__ixor__(self, other)
-            numeric object.__ior__(self, other)
-
-   These methods are called to implement the augmented arithmetic operations
-   (``+=``, ``-=``, ``*=``, ``/=``, ``%=``, ``**=``, ``<<=``, ``>>=``, ``&=``,
-   ``^=``, ``|=``).  These methods should attempt to do the operation in-place
-   (modifying *self*) and return the result (which could be, but does not have to
-   be, *self*).  If a specific method is not defined, the augmented operation falls
-   back to the normal methods.  For instance, to evaluate the expression
-   *x*``+=``*y*, where *x* is an instance of a class that has an :meth:`__iadd__`
-   method, ``x.__iadd__(y)`` is called.  If *x* is an instance of a class that does
-   not define a :meth:`__iadd__` method, ``x.__add__(y)`` and ``y.__radd__(x)`` are
-   considered, as with the evaluation of *x*``+``*y*.
-
-
-.. method:: numeric object.__neg__(self)
-            numeric object.__pos__(self)
-            numeric object.__abs__(self)
-            numeric object.__invert__(self)
+.. method:: object.__iadd__(self, other)
+            object.__isub__(self, other)
+            object.__imul__(self, other)
+            object.__idiv__(self, other)
+            object.__itruediv__(self, other)
+            object.__ifloordiv__(self, other)
+            object.__imod__(self, other)
+            object.__ipow__(self, other[, modulo])
+            object.__ilshift__(self, other)
+            object.__irshift__(self, other)
+            object.__iand__(self, other)
+            object.__ixor__(self, other)
+            object.__ior__(self, other)
+
+   These methods are called to implement the augmented arithmetic assignments
+   (``+=``, ``-=``, ``*=``, ``/=``, ``//=``, ``%=``, ``**=``, ``<<=``, ``>>=``,
+   ``&=``, ``^=``, ``|=``).  These methods should attempt to do the operation
+   in-place (modifying *self*) and return the result (which could be, but does
+   not have to be, *self*).  If a specific method is not defined, the augmented
+   assignment falls back to the normal methods.  For instance, to execute the
+   statement ``x += y``, where *x* is an instance of a class that has an
+   :meth:`__iadd__` method, ``x.__iadd__(y)`` is called.  If *x* is an instance
+   of a class that does not define a :meth:`__iadd__` method, ``x.__add__(y)``
+   and ``y.__radd__(x)`` are considered, as with the evaluation of ``x + y``.
+
+
+.. method:: object.__neg__(self)
+            object.__pos__(self)
+            object.__abs__(self)
+            object.__invert__(self)
 
    .. index:: builtin: abs
 
    Called to implement the unary arithmetic operations (``-``, ``+``, :func:`abs`
    and ``~``).
 
 
-.. method:: numeric object.__complex__(self)
-            numeric object.__int__(self)
-            numeric object.__long__(self)
-            numeric object.__float__(self)
+.. method:: object.__complex__(self)
+            object.__int__(self)
+            object.__long__(self)
+            object.__float__(self)
 
    .. index::
       builtin: complex
       builtin: int
       builtin: long
       builtin: float
 
    Called to implement the built-in functions :func:`complex`, :func:`int`,
    :func:`long`, and :func:`float`.  Should return a value of the appropriate type.
 
 
-.. method:: numeric object.__oct__(self)
-            numeric object.__hex__(self)
+.. method:: object.__oct__(self)
+            object.__hex__(self)
 
    .. index::
       builtin: oct
       builtin: hex
 
    Called to implement the built-in functions :func:`oct` and :func:`hex`.  Should
    return a string value.
 
 
-.. method:: numeric object.__index__(self)
+.. method:: object.__index__(self)
 
    Called to implement :func:`operator.index`.  Also called whenever Python needs
    an integer object (such as in slicing).  Must return an integer (int or long).
 
    .. versionadded:: 2.5
 
 
-.. method:: numeric object.__coerce__(self, other)
+.. method:: object.__coerce__(self, other)
 
    Called to implement "mixed-mode" numeric arithmetic.  Should either return a
    2-tuple containing *self* and *other* converted to a common numeric type, or
    ``None`` if conversion is impossible.  When the common type would be the type of
    ``other``, it is sufficient to return ``None``, since the interpreter will also
    ask the other object to attempt a coercion (but sometimes, if the implementation
    of the other type cannot be changed, it is useful to do the conversion to the
    other type here).  A return value of ``NotImplemented`` is equivalent to
    returning ``None``.
 
 
 .. _coercion-rules:
@@ -2137,44 +2218,45 @@
   the coercion returns an object of a different type for the operand whose
   coercion is invoked, part of the process is redone using the new object.
 
 *
 
   When an in-place operator (like '``+=``') is used, if the left operand
   implements :meth:`__iop__`, it is invoked without any coercion.  When the
   operation falls back to :meth:`__op__` and/or :meth:`__rop__`, the normal
   coercion rules apply.
 
 *
 
-  In *x*``+``*y*, if *x* is a sequence that implements sequence concatenation,
+  In ``x + y``, if *x* is a sequence that implements sequence concatenation,
   sequence concatenation is invoked.
 
 *
 
-  In *x*``*``*y*, if one operator is a sequence that implements sequence
+  In ``x * y``, if one operator is a sequence that implements sequence
   repetition, and the other is an integer (:class:`int` or :class:`long`),
   sequence repetition is invoked.
 
 *
 
   Rich comparisons (implemented by methods :meth:`__eq__` and so on) never use
   coercion.  Three-way comparison (implemented by :meth:`__cmp__`) does use
   coercion under the same conditions as other binary operations use it.
 
 *
 
   In the current implementation, the built-in numeric types :class:`int`,
   :class:`long` and :class:`float` do not use coercion; the type :class:`complex`
-  however does use it.  The difference can become apparent when subclassing these
+  however does use coercion for binary operators and rich comparisons, despite
+  the above rules.  The difference can become apparent when subclassing these
   types.  Over time, the type :class:`complex` may be fixed to avoid coercion.
   All these types implement a :meth:`__coerce__` method, for use by the built-in
   :func:`coerce` function.
 
 
 .. _context-managers:
 
 With Statement Context Managers
 -------------------------------
 
 .. versionadded:: 2.5
 
@@ -2183,62 +2265,163 @@
 handles the entry into, and the exit from, the desired runtime context for the
 execution of the block of code.  Context managers are normally invoked using the
 :keyword:`with` statement (described in section :ref:`with`), but can also be
 used by directly invoking their methods.
 
 .. index::
    statement: with
    single: context manager
 
 Typical uses of context managers include saving and restoring various kinds of
 global state, locking and unlocking resources, closing opened files, etc.
 
-For more information on context managers, see "Context Types (XXX reference:
-../lib/typecontextmanager.html)" in the Python Library Reference (XXX reference:
-../lib/lib.html).
+For more information on context managers, see :ref:`typecontextmanager`.
 
 
-.. method:: context manager.__enter__(self)
+.. method:: object.__enter__(self)
 
    Enter the runtime context related to this object. The :keyword:`with` statement
    will bind this method's return value to the target(s) specified in the
    :keyword:`as` clause of the statement, if any.
 
 
-.. method:: context manager.__exit__(self, exc_type, exc_value, traceback)
+.. method:: object.__exit__(self, exc_type, exc_value, traceback)
 
    Exit the runtime context related to this object. The parameters describe the
    exception that caused the context to be exited. If the context was exited
    without an exception, all three arguments will be :const:`None`.
 
    If an exception is supplied, and the method wishes to suppress the exception
    (i.e., prevent it from being propagated), it should return a true value.
    Otherwise, the exception will be processed normally upon exit from this method.
 
    Note that :meth:`__exit__` methods should not reraise the passed-in exception;
    this is the caller's responsibility.
 
 
 .. seealso::
 
    :pep:`0343` - The "with" statement
       The specification, background, and examples for the Python :keyword:`with`
       statement.
 
-.. rubric:: Footnotes
 
-.. [#] Since Python 2.2, a gradual merging of types and classes has been started that
-   makes this and a few other assertions made in this manual not 100% accurate and
-   complete: for example, it *is* now possible in some cases to change an object's
-   type, under certain controlled conditions.  Until this manual undergoes
-   extensive revision, it must now be taken as authoritative only regarding
-   "classic classes", that are still the default, for compatibility purposes, in
-   Python 2.2 and 2.3.  For more information, see
-   `<http://www.python.org/doc/newstyle.html>`_.
+.. _old-style-special-lookup:
+
+Special method lookup for old-style classes
+-------------------------------------------
+
+For old-style classes, special methods are always looked up in exactly the
+same way as any other method or attribute. This is the case regardless of
+whether the method is being looked up explicitly as in ``x.__getitem__(i)``
+or implicitly as in ``x[i]``.
+
+This behaviour means that special methods may exhibit different behaviour
+for different instances of a single old-style class if the appropriate
+special attributes are set differently::
+
+   >>> class C:
+   ...     pass
+   ...
+   >>> c1 = C()
+   >>> c2 = C()
+   >>> c1.__len__ = lambda: 5
+   >>> c2.__len__ = lambda: 9
+   >>> len(c1)
+   5
+   >>> len(c2)
+   9
+
+
+.. _new-style-special-lookup:
+
+Special method lookup for new-style classes
+-------------------------------------------
+
+For new-style classes, implicit invocations of special methods are only guaranteed
+to work correctly if defined on an object's type, not in the object's instance
+dictionary.  That behaviour is the reason why the following code raises an
+exception (unlike the equivalent example with old-style classes)::
+
+   >>> class C(object):
+   ...     pass
+   ...
+   >>> c = C()
+   >>> c.__len__ = lambda: 5
+   >>> len(c)
+   Traceback (most recent call last):
+     File "<stdin>", line 1, in <module>
+   TypeError: object of type 'C' has no len()
+
+The rationale behind this behaviour lies with a number of special methods such
+as :meth:`__hash__` and :meth:`__repr__` that are implemented by all objects,
+including type objects. If the implicit lookup of these methods used the
+conventional lookup process, they would fail when invoked on the type object
+itself::
+
+   >>> 1 .__hash__() == hash(1)
+   True
+   >>> int.__hash__() == hash(int)
+   Traceback (most recent call last):
+     File "<stdin>", line 1, in <module>
+   TypeError: descriptor '__hash__' of 'int' object needs an argument
+
+Incorrectly attempting to invoke an unbound method of a class in this way is
+sometimes referred to as 'metaclass confusion', and is avoided by bypassing
+the instance when looking up special methods::
+
+   >>> type(1).__hash__(1) == hash(1)
+   True
+   >>> type(int).__hash__(int) == hash(int)
+   True
+
+In addition to bypassing any instance attributes in the interest of
+correctness, implicit special method lookup generally also bypasses the
+:meth:`__getattribute__` method even of the object's metaclass::
+
+   >>> class Meta(type):
+   ...    def __getattribute__(*args):
+   ...       print "Metaclass getattribute invoked"
+   ...       return type.__getattribute__(*args)
+   ...
+   >>> class C(object):
+   ...     __metaclass__ = Meta
+   ...     def __len__(self):
+   ...         return 10
+   ...     def __getattribute__(*args):
+   ...         print "Class getattribute invoked"
+   ...         return object.__getattribute__(*args)
+   ...
+   >>> c = C()
+   >>> c.__len__()                 # Explicit lookup via instance
+   Class getattribute invoked
+   10
+   >>> type(c).__len__(c)          # Explicit lookup via type
+   Metaclass getattribute invoked
+   10
+   >>> len(c)                      # Implicit lookup
+   10
+
+Bypassing the :meth:`__getattribute__` machinery in this fashion
+provides significant scope for speed optimisations within the
+interpreter, at the cost of some flexibility in the handling of
+special methods (the special method *must* be set on the class
+object itself in order to be consistently invoked by the interpreter).
+
+
+.. rubric:: Footnotes
 
-.. [#] This, and other statements, are only roughly true for instances of new-style
-   classes.
+.. [#] It *is* possible in some cases to change an object's type, under certain
+   controlled conditions. It generally isn't a good idea though, since it can
+   lead to some very strange behaviour if it is handled incorrectly.
+
+.. [#] A descriptor can define any combination of :meth:`__get__`,
+   :meth:`__set__` and :meth:`__delete__`.  If it does not define :meth:`__get__`,
+   then accessing the attribute even on an instance will return the descriptor
+   object itself.  If the descriptor defines :meth:`__set__` and/or
+   :meth:`__delete__`, it is a data descriptor; if it defines neither, it is a
+   non-data descriptor.
 
 .. [#] For operands of the same type, it is assumed that if the non-reflected method
    (such as :meth:`__add__`) fails the operation is not supported, which is why the
    reflected method is not called.
 
