Bug #1684991: explain __special__ lookup semantics.

diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index 9e847cc74e49859cdd378344549fb658a7629302..29e6220fe04605979b69d7c59cc46a4ea1556ec8 100644 (file)
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -1060,6 +1060,20 @@ raise an exception when no appropriate method is defined.
 
 .. XXX above translation is not correct 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