title: Why/When in Python does `x==y` call `y.__eq__(x)`?
body: <p>The Python docs clearly state that <code>x==y</code> calls <code>x.__eq__(y)</code>.  However it seems that under many circumstances, the opposite is true.  Where is it documented when or why this happens, and how can I work out for sure whether my object's <code>__cmp__</code> or <code>__eq__</code> methods are going to get called.</p>
  
  <p>Edit: Just to clarify, I know that <code>__eq__</code> is called in preferecne to <code>__cmp__</code>, but I'm not clear why <code>y.__eq__(x)</code> is called in preference to <code>x.__eq__(y)</code>, when the latter is what the docs state will happen.</p>
  
  <pre><code>&gt;&gt;&gt; class TestCmp(object):
  ...     def __cmp__(self, other):
  ...         print "__cmp__ got called"
  ...         return 0
  ... 
  &gt;&gt;&gt; class TestEq(object):
  ...     def __eq__(self, other):
  ...         print "__eq__ got called"
  ...         return True
  ... 
  &gt;&gt;&gt; tc = TestCmp()
  &gt;&gt;&gt; te = TestEq()
  &gt;&gt;&gt; 
  &gt;&gt;&gt; 1 == tc
  __cmp__ got called
  True
  &gt;&gt;&gt; tc == 1
  __cmp__ got called
  True
  &gt;&gt;&gt; 
  &gt;&gt;&gt; 1 == te
  __eq__ got called
  True
  &gt;&gt;&gt; te == 1
  __eq__ got called
  True
  &gt;&gt;&gt; 
  &gt;&gt;&gt; class TestStrCmp(str):
  ...     def __new__(cls, value):
  ...         return str.__new__(cls, value)
  ...     
  ...     def __cmp__(self, other):
  ...         print "__cmp__ got called"
  ...         return 0
  ... 
  &gt;&gt;&gt; class TestStrEq(str):
  ...     def __new__(cls, value):
  ...         return str.__new__(cls, value)
  ...     
  ...     def __eq__(self, other):
  ...         print "__eq__ got called"
  ...         return True
  ... 
  &gt;&gt;&gt; tsc = TestStrCmp("a")
  &gt;&gt;&gt; tse = TestStrEq("a")
  &gt;&gt;&gt; 
  &gt;&gt;&gt; "b" == tsc
  False
  &gt;&gt;&gt; tsc == "b"
  False
  &gt;&gt;&gt; 
  &gt;&gt;&gt; "b" == tse
  __eq__ got called
  True
  &gt;&gt;&gt; tse == "b"
  __eq__ got called
  True
  </code></pre>
  
  <p>Edit: From Mark Dickinson's answer and comment it would appear that:</p>
  
  <ol>
  <li>Rich comparison overrides <code>__cmp__</code></li>
  <li><code>__eq__</code> is it's own <code>__rop__</code> to it's <code>__op__</code> (and similar for <code>__lt__</code>, <code>__ge__</code>, etc)</li>
  <li>If the left object is a builtin or new-style class, and the right is a subclass of it, the right object's <code>__rop__</code> is tried before the left object's <code>__op__</code></li>
  </ol>
  
  <p>This explains the behaviour in the<code>TestStrCmp</code> examples.  <code>TestStrCmp</code> is a subclass of <code>str</code> but doesn't implement its own <code>__eq__</code> so the <code>__eq__</code> of <code>str</code> takes precedence in both cases (ie <code>tsc == "b"</code> calls <code>b.__eq__(tsc)</code> as an <code>__rop__</code> because of rule 1).</p>
  
  <p>In the <code>TestStrEq</code> examples, <code>tse.__eq__</code> is called in both instances because <code>TestStrEq</code> is a subclass of <code>str</code> and so it is called in preference.</p>
  
  <p>In the <code>TestEq</code> examples, <code>TestEq</code> implements <code>__eq__</code> and <code>int</code> doesn't so <code>__eq__</code> gets called both times (rule 1).</p>
  
  <p>But I still don't understand the very first example with <code>TestCmp</code>.  <code>tc</code> is not a subclass on <code>int</code> so AFAICT <code>1.__cmp__(tc)</code> should be called, but isn't.</p>