The following code:

--------------------------------
class X(list):

    def __contains__(self, key):
        print('X contains:', key)


class Y():

    def __init__(self, x):
        self.x = x

    def __getattr__(self, key):
        return getattr(self.x, key)

    def __iter__(self):
        print('Y iter')
        return iter([1,2])

x = X()
y = Y(x)

print('res:', 1 in y)
-----------------------------

prints True.  It has been explained to me that this is because of:

http://docs.python.org/reference/datamodel.html#special-method-lookup-for-new-style-classes

However, there is no way in the world that I would guess the behavior above from the documentation provided (and I find it surprising...I expected x's __contains__ to get called because Y (a class, not an instance) doesn't have a __contains__ method).

Can anyone explain it more clearly and update the documentation?

In 2.7 I get the following (if Y does not inherit from object):

>>> print('res:', 1 in y)
('X contains:', 1)
('res:', False)

This makes sense with old style classes.  With Y(object):

>>> print('res:', 1 in y)
Y iter
('res:', True)

Not sure I understand your issue here.  How should "1 in y" get at X.__contains__ given the special method lookup rules?  The __getattr__ is not called since y.__contains__ isn't looked up.

Well, then I suppose my question is why isn't __contains__ looked up?  Other special methods that don't exist on Y do cause __getattr__ to be called.  Why is __contains__ special?  The docs for __getattr__ don't hint at this possibility either.

I think the people that understand this must have a mental model of how the interpreter looks up methods that has some pieces that are missing from mine.  I guess I'd like those bits to be made explicit in the special method lookup docs, or if they are already documented somewhere, for there to be a pointer to them in the special method lookup docs.

Ah, that's what my problem is.  My test example was poorly conceived (I used __del__!) so I *thought* the other special methods were triggering getattr.

I'd have figured it out if I hadn't screwed up my test :(