According to the object.__eq__() documentation, the default (that is, in the object class) implementation for == is as follows:
True if x is y else NotImplemented
Still following the documentation for NotImplemented, I inferred that NotImplemented implies that the Python runtime will try the comparison the other way around. That is try y.__eq__(x) if x.__eq__(y) returns NotImplemented (in the case of the == operator).
Now, the following code prints False and True in python 3.9:
class A:
pass
print(A() == A())
print(bool(NotImplemented))
So my question is the following: where does the documentation mention the special behavior of NotImplemented in the context of __eq__ ?
PS : I found an answer in CPython source code but I guess that this must/should be somewhere in the documentation.
According to the object.__eq__() documentation, the default (that is, in the object class) implementation for == is as follows
No; that is the default implementation of __eq__. ==, being an operator, cannot be implemented in classes.
Python's implementation of operators is cooperative. There is hard-coded logic that uses the dunder methods to figure out what should happen, and possibly falls back on a default. This logic is outside of any class.
You can see another example with the built-in len: a class can return whatever it likes from its __len__ method, and you can in principle call it directly and get a value of any type. However, this does not properly implement the protocol, and len will complain when it doesn't get a positive integer back. There is not any class which contains that type-checking and value-checking logic. It is external.
Still following the documentation for NotImplemented, I inferred that NotImplemented implies that the Python runtime will try the comparison the other way around. That is try y.__eq__(x) if x.__eq__(y) returns NotImplemented (in the case of the == operator).
NotImplemented is just an object. It is not syntax. It does not have any special behavior, and in Python, simply returning a value does not trigger special behavior besides that the value is returned.
The external code for binary operators will try to look for the matching __op__, and try to look for the matching __rop__ if __op__ didn't work. At this point, NotImplemented is not an acceptable answer (it is a sentinel that exists specifically for this purpose, because None is an acceptable answer). In general, if the answer so far is still NotImplemented, then the external code will raise NotImplementedError.
As a special case, objects that don't provide their own comparison (i.e., the default from object is used for __eq__ or __ne__) will compare as "not equal" unless they are identical. The C implementation repeats the identity check (in case a class explicitly defines __eq__ or __ne__ to return NotImplemented directly, I guess). This is because it is considered sensible to give this result, and obnoxious to make == fail all the time when there is a sensible default.
However, the two objects are still not orderable without explicit logic, since there isn't a reasonable default. (You could compare the pointer values, but they're arbitrary and don't have anything to do with the Python logic that got you to that point; so ordering things that way isn't realistically useful for writing Python code.) So, for example, x < y will raise a TypeError if the comparison logic isn't provided. (It does this even if x is y; you could reasonably say that <= and >= should be true in this case, and < and > should be false, but it makes things too complicated and is not very useful.)
[Observation: print(bool(NotImplemented)) prints True]
Well, yes; NotImplemented is an object, so it's truthy by default; and it doesn't represent a numeric value, and isn't a container, so there's no reason for it to be falsy.
However, that also doesn't tell us anything useful. We don't care about the truthiness of NotImplemented here, and it isn't used that way in the Python implementation. It is just a sentinel value.
where does the documentation mention the special behavior of NotImplemented in the context of __eq__ ?
Nowhere, because it isn't a behavior of NotImplemented, as explained above.
Okay, but that leaves underlying question: where does the documentation explain what the == operator does by default?
Answer: because we are talking about an operator, and not about a method, it's not in the section about dunder methods. It's in section 6, which talks about expressions. Specifically, 6.10.1. Value comparisons:
The default behavior for equality comparison (== and !=) is based on the identity of the objects. Hence, equality comparison of instances with the same identity results in equality, and equality comparison of instances with different identities results in inequality. A motivation for this default behavior is the desire that all objects should be reflexive (i.e. x is y implies x == y).
Related
The docs.python.org page on the Python "Data Model" states that when both sides in a literal comparison operation implement magic methods for the operation, the method of the left operand gets used with the right operand as its argument:
x<y calls x.__lt__(y), x<=y calls x.__le__(y), x==y calls x.__eq__(y), x!=y calls x.__ne__(y), x>y calls x.__gt__(y), and x>=y calls x.__ge__(y).
The following class wraps the builtin tuple and implements a magic method for one of these comparison operators to demonstrate this:
class eqtest(tuple):
def __eq__(self, other):
print('Equivalence!')
When using instances of this class on the left side of a comparison operator, it behaves as expected:
>>> eqtest((1,2,3)) == (1,2,3)
Equivalence!
However, the comparison operator of the custom class seems to get called even when only using its instance on the right:
>>> (1,2,3) == eqtest((1,2,3))
Equivalence!
The result is also demonstrably different when the magic method of the left operand is explicitly called:
>>> (1,2,3).__eq__(eqtest2((1,2,3)))
True
It's easy to understand why this might be a deliberate design choice, especially with subclasses, in order to return the result most likely to be useful from the type that was defined later. However, since it deviates quite explicitly from the basic documented behaviour, it's quite hard to know how and why it works this way confidently enough to account for and use it in production.
In what cases do the Python language and the CPython reference implementation reverse the order of comparison operators even if both sides provide valid results, and where is this documented?
The rules on comparisons state that tuples don't know how to compare to other types. tuplerichcompare does Py_RETURN_NOTIMPLEMENTED. However, the PyObject richcompare checks for subtypes, such as your inherited class, and swaps the comparison order (applying the symmetry rule).
This is documented in the page you linked as well:
If the operands are of different types, and right operand’s type is a direct or indirect subclass of the left operand’s type, the reflected method of the right operand has priority, otherwise the left operand’s method has priority. Virtual subclassing is not considered.
This enables subclasses to implement more specific behaviours that work with the comparison written either way.
I recently found out that python has a special value NotImpemented to be used with respect to binary special methods to indicate that some operation has not been implemented.
The peculiar about this is that when checked in a binary situation it is always equivalent to True.
For example using io.BytesIO (which is a case where __eq__ in not implemented for example) for two objects in comparison will virtually return True. As in this example (encoded_jpg_io1 and encoded_jpg_io2 are objects of the io.BytesIO class):
if encoded_jpg_io1.__ne__(encoded_jpg_io2):
print('Equal')
else:
print('Unequal')
Equal
if encoded_jpg_io1.__eq__(encoded_jpg_io2) == True:
print('Equal')
else:
print('Unequal')
Unequal
Since the second style is a bit too verbose and normally not prefered (even my pyCharm suggests to remove the explicit comparison with True) isn't a bit tricky behavior? I wouldn't have noticed it if I haven't explicitly print the result of the Boolean operation (which is not Boolean in this case at all).
I guess suggesting to be considered False would cause the same problem with __ne__ so we arew back to step one.
So, the only way to check out for these cases is by doing an exact comparison with True or False in the opposite case.
I know that NotImpemented is preferred over NotImplementedError for various reasons so I am not asking for any explanation over why this matter.
Per convention, objects that do not define a __bool__ method are considered truthy. From the docs:
By default, an object is considered true unless its class defines either a __bool__() method that returns False or a __len__() method that returns zero
This means that most classes, functions, and other builtin singletons are considered true, since they don't go out of their way to specify different behavior. (An exception is None, which is one of the few built-in singletons that does specifically signal it should be considered false):
>>> bool(int) # the class, not an integer object
True
>>> bool(min)
True
>>> bool(object())
True
>>> bool(...) # that's the Ellipsis object
True
>>> bool(NotImplemented)
True
There is no real reason for the NotImplemented object to break this convention. The problem with your code isn't that NotImplemented is considered truthy; the real problem is that x.__eq__(y) is not equivalent to x == y.
If you want to compare two objects for equality, doing it with x.__eq__(y) is incorrect. Using x.__eq__(y) == True instead is still incorrect.
The correct solution is to do comparison with the == operator. If, for whatever reason, you can't use the == operator directly, you should use the operator.eq function instead.
This problem arose from a failing test that refused to fail locally, and would only fail on our CI server.
It turned out some rather dodgy object comparison was being unintentionally done.
I'm now rather curious as to why the behavior is so different between two installations of the same Python version (2.7.9).
This test case could probably be simplified further, but this is what I've got:
import operator
class Thing(dict):
def __int__(self, number):
return self['number']
def __gt__(self, other):
return self['number'] > other
thing = Thing({'number': 2})
for o in [
operator.lt,
operator.le,
operator.eq,
operator.ne,
operator.ge,
operator.gt]:
print o
print o(0.01, thing)
print o(thing, 0.01)
And the result of running it locally is:
<built-in function lt>
True
False
<built-in function le>
True
False
<built-in function eq>
False
False
<built-in function ne>
True
True
<built-in function ge>
False
True
<built-in function gt>
False
True
But on the Travis CI server it is:
<built-in function lt>
True
True
<built-in function le>
False
True
<built-in function eq>
False
False
<built-in function ne>
True
True
<built-in function ge>
True
False
<built-in function gt>
True
True
What kind of comparison behavior is Python falling back to, and why would it exhibit such different behavior on two installations of the same version?
My initial thought was some kind of id based comparison, but from looking at the value of the id, they don't correlate at all with the results of the comparisons.
Update:
This differing behavior only happens when the class inherits from dict. When it inherits from object, the comparisons behave the same on both installations, and give the same results as the local result above.
Update 2:
I've just found that I can simplify the test case even further with just the __int__ and the __gt__ methods, but if I remove either of those methods then the strange behavior disappears.
As mentioned in comments, dict already defines all the comparison operators. The documented behavior is:
Objects of different types, except different numeric types and different string types, never compare equal; such objects are ordered consistently but arbitrarily
In other words, dicts are specifically defined to allow comparisons with other types, but for the result of such comparisons to be undefined. (This was changed in Python 3 so that these sorts of inter-type comparisons are no longer allowed.)
When you override just some of the comparison operators for your type, you complicate things even more. Since your type defines __gt__ but not __lt__, thing > 0.01 will use your custom __gt__, but thing < 0.01 will use the default (undefined) comparison behavior. So you get a type that sometimes uses a deterministic rule, and sometimes gives undefined behavior, depending on which comparison operators you use. I don't know why you see the precise pattern of results you're seeing, but the bottom line is that your class relies on undefined behavior, so you can't expect any consistency in comparisons using this type. The two implementations of Python could be doing something differently at some arcane implementation level that produces different undefined behavior. The point of undefined behavior is you aren't supposed to know how it works (or you might start relying on it).
Incidentally, total_ordering here is a no-op, and the behavior should be the same if you remove it. total_ordering only adds comparison operators that aren't already defined, but dict already defines all of them, so total_ordering won't do anything. If you want to make your own ordering relation on a subclass of a type that already defines its own comparison behavior (like dict), then you need to manually override every individual comparison operator.
After further investigation, and based on #BrenBarn's fantastic answer I've found the root of the strange behaviour.
The last resort step of the "undefined" comparison is to compare the memory location of the object types. After comparing id(type(thing)) and id(type(0.02)) locally and on the CI server, I see that Thing's id is always higher locally, and always lower on the CI server!
What's the suggested Python semantics for ordering of objects of distinct types? In other words, what behavior should one implement when a custom-written comparison method (using rich comparisons like e.g. __lt__, but perhaps also when using the ‘poor’ comparison __cmp__ in Python 2) encounters an object of a different type than self?
Should one invent an order, e.g. “all unexpected objects compare as less than my own type”?
Should one throw a TypeError?
Is there some easy way to let the other object have a try, i.e. if one does foo < bar and foo.__lt__ doesn't know about bar's type, can it fall back to bar.__gt__?
Are there any guidelines at all about how to achieve sane ordering of objects of distinct types, preferrably a total order but perhaps less?
Is there any part in the documentation which explains why 3 < "3"?
PEP 207 apparently leaves a lot of freedom of how things can be implemented, but nevertheless I expect there might be some guidelines how things should be implemented to help interoperability.
While writing the question, the “similar questions” list made me aware of this post. It mentions NotImplemented as a return value (not exception) of rich comparisons. Searching for this keyword in the docs turned up relevant parts as well:
Python 2 data model:
NotImplemented – This type has a single value. There is a single object with this value. This object is accessed through the built-in name NotImplemented. Numeric methods and rich comparison methods may return this value if they do not implement the operation for the operands provided. (The interpreter will then try the reflected operation, or some other fallback, depending on the operator.) Its truth value is true.
And later on:
A rich comparison method may return the singleton NotImplemented if it does not implement the operation for a given pair of arguments. By convention, False and True are returned for a successful comparison. However, these methods can return any value, so if the comparison operator is used in a Boolean context (e.g., in the condition of an if statement), Python will call bool() on the value to determine if the result is true or false.
PEP 207:
If the function cannot compare the particular combination of objects, it should return a new reference to Py_NotImplemented.
This answers points 2. and 3. of my original question, at least for the rich comparison scenario. The docs for __cmp__ don't mention NotImplemented at all, which might be the reason why I missed that at first. So this is one more reason to switch to rich comparisons.
I'm still not sure whether returning that value is to be preferred to inventing an order. I guess a lot depends on what ideas the other object might have. And I fear that for a mix of types to achieve any kind of sane orderings, a lot of cooperation might be needed. But perhaps someone else can shed more light on the other parts of my question.
How does Python 3 compare a built-in object (on the lhs) to a user-defined object (on the rhs)?
Does the built-in __eq__ method simply delegate the comparison to the rhs (rhs.__eq__(self))?
I didn't find any statement about this in the docs. The docs state:
Objects of different types, except different numeric types, never compare equal.
It's quite misleading because:
class X:
def __eq__(self, rhs)
return True
x = X()
'abc' == x # True
I think the doc statement should be rephrased as follows:
Objects of different built-in types, except different numeric types, never compare equal.
and should furthermore clarify how the comparison to user-defined class instances is performed.
To answer the questions:
How does Python 3 compare a built-in object (on the lhs) to a user-defined object (on the rhs)?
The same way as with any other object comparisons (including None!).
Does the built-in __eq__ method simply delegate the comparison to the rhs (rhs.__eq__(self))?
No. The built-in __eq__ does not delegate like this. There is a higher-construct at work that covers the behavior of == in Python.
Given a == b, where a.__eq__(b) returns NotImplemented then b.__eq__(a) will be invoked and the result of the used as the result of the equality test. (False is returned if both __eq__ implementations return NotImplemented.)
Thus, given x (of class X), and given that "abc".__eq__(x) returns NotImplemented, then x.__eq__("abc") is invoked (and evaluates to True per the question).
The same applies to the other standard comparison operators.
While I don't care to speculate too much on the documentation (or possible mis-wording), I believe it is entirely accurate if taken in context of stdObj.__eq__(obj) as opposed to stdObj == obj.
See also:
The documentation on the __eq__ protocol which briefly mentions NotImplemented
Why return NotImplemented instead of raising NotImplementedError