Backport from Py3k: Bug #1684991: explain lookup semantics for __special__ methods (new-style classes only).
diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index 18ebe76..de649bb 100644
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -1147,6 +1147,21 @@
``x.__getitem__(i)``. Except where mentioned, attempts to execute an operation
raise an exception when no appropriate method is defined.
+For new-style classes, special methods are only guaranteed to work if defined in
+an object's class, not in the object's instance dictionary. That explains why
+this won't work::
+
+ >>> class C:
+ ... 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()
+
+
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