This is not true for all __special__ methods, e.g. __enter__ and __exit__: >>> class C(object): ... pass ... >>> def enter(*args): ... print 'enter', args ... >>> def exit(*args): ... print 'exit', args ... >>> c = C() >>> c.__enter__ = enter >>> c.__exit__ = exit >>> with c: ... print 'hi' ... enter () hi exit (None, None, None) The documentation should say something like "When interpreting syntax that invokes a __special__ method, Python looks for the __special__ method on the instance's class. As an implementation detail, the lookup for some __special__ methods may also check the instance first, but this behavior should not be relied upon." This should probably go into the Reference Manual section 3.4: http://docs.python.org/ref/specialnames.html
When writing docs, always cover the general case first and thoroughly. Keep the recommendations constructive, positive and useful (as opposed to wording like "this behavior should not be relied upon". A doc patch needs to add clarity -- if it doesn't, leave it out.
Not sure exactly what you're proposing Raymond, but you could cut mine to "When interpreting syntax that invokes a __special__ method, Python looks for the __special__ method on the instance's class" if that's what you want.
