Repository navigation
Adressing the object.__eq__ dilemma. #15345
Description
The Dilemma
# current annotation in typeshed
class object:
def __eq__(self, value: object, /) -> bool: ...This is too strict, because everything subclasses object and some classes may to wish to:
- Narrow the range of allowed objects.
- Use a return type other than
bool(e.g. numpy array element-wise comparison, symbolic computation, etc.)
On the other hand, many APIs (incorrectly) assume that a == b always return a bool, so changing the return type away from bool can lead to problems.
Solving the Dilemma
Satisfying (1) is easy enough by changing value: object to value: Any. (one could maybe explore using Never also)
Satisfying (2) can be achieved in several ways, specifically I tested: (a) -> object, (b) -> Any and (c) -> Any | bool
-
Option (a) leads to very bad primer result as per the dilemma explained above.
-
Option (b) triggers a lot of
no-any-returnwarnings withmypywhen a function does somethign likereturn a==b. -
Option (c) is essentially a cheat code that avoids the
no-any-returnwarnings from option (b)
In particular, for (c) the primer actually looks really good. We have ~50 fixed Unused "type: ignore" comment errors, and 16 suprious [override] errors eliminated, without any new errors.
References
- https://discuss.python.org/t/make-type-hints-for-eq-of-primitives-less-strict/34240
- https://discuss.python.org/t/method-eq-overrides-class-object-in-an-incompatible-manner-well-not-always/42878
- https://discuss.python.org/t/hash-eq-and-lsp/68138
Appendix: How python's a==b works internally
This cannot be properly annotated with the current type system, so all type checkers need to special case it.
def eq(left, right):
left_type = type(left)
right_type = type(right)
# if RHS is proper subtype of LHS, try RHS's equality method
if left_type != right_type and issubclass(right_type, left_type):
result = right.__eq__(left)
if result is not NotImplemented:
return result
# try LHS's equality method
result = left.__eq__(right)
if result is not NotImplemented:
return result
# try RHS's equality method
result = right.__eq__(left)
if result is not NotImplemented:
return result
return False # fallback if all methods return NotImplemented
Activity
srittau commentedon Jan 30, 2026
Previous (partial) discussion: #3685. I still believe that implementations that intentionally violate the contract of
__eq__(which makes sense when building a DSL) should explicitly use# type: ignore.AlexWaygood commentedon Jan 30, 2026
I agree, I think it's an important soundness check, and I wouldn't want to hinder type checkers' ability to provide that soundness check. While there are some established libraries that do this, and it might make sense in certain very narrow situations in new code, I think these are the exceptions rather than the rule. I think it's overall very desirable for type checkers to complain about
__eq__methods that accept a narrower type thanobjector return a non-bool. That's usually a mistake that will have bad consequences and mean that type checkers are unable to spot bugs in your code elsewhere.randolf-scholz commentedon Jan 30, 2026
What about at least allowing
Anyfor the argument type, and leaving the return type as-is?As far as I understand it, type-checkers have more or less settled for interpreting the argument annotation of
__eq__as the types for which the method will not returnNotImplemented.So for instance if my class only supports
__eq__withSelf | floatand otherwise would returnNotImplemented, I'd like to annotate it as such, but this will triggeroverride, even if th return isbool.AlexWaygood commentedon Jan 30, 2026
But I think having an incorrect argument type is usually the way that most people write unsound
__eq__methods. If we made this change, type checkers wouldn't emit any errors on this snippet, even though it fails at runtime:randolf-scholz commentedon Feb 2, 2026
The last example by @AlexWaygood is instructive, this makes me think that there's nothing that typeshed currently can do about the situation.
However, I do want to point out that many DSLs, like for example
polars.Seriesalready break this.Moreover, I think it is likely that people who make this mistake in the first place will likely either:
use a bad
type: igore[override]break the design of operators by doing
rather than