Python Rich Comparison Methods Explained

Python rich comparison methods let you define how custom objects behave with operators like ==, <, <=, >, >=, and !=. Instead of relying on identity comparisons, you can implement __eq__, __lt__, and the rest to give your classes meaningful equality and ordering semantics. This article explains how to implement these methods correctly, avoid common pitfalls, and keep your code maintainable.

The Six Rich Comparison Methods

Python defines six special methods that correspond to the six comparison operators. Each method takes self and other and returns a boolean (or sometimes NotImplemented).

By default, these methods compare object identity (self is other). Overriding them changes the behavior of the operators for instances of your class.

Implementing Comparison Operators Manually

Consider a Person class with name and age attributes. If you want to sort a list of people by age, you need to define at least __lt__ and __eq__. The other methods can be derived from those two, but Python does not automatically do that for you. Here is a manual implementation:

class Person:
    def __init__(self, name, age):
        self.name = name
        self.age = age

    def __eq__(self, other):
        if not isinstance(other, Person):
            return NotImplemented
        return self.age == other.age

    def __lt__(self, other):
        if not isinstance(other, Person):
            return NotImplemented
        return self.age < other.age

With these two methods, == and < work. But <=, >, >=, and != will still fall back to identity comparisons unless you define them. For example, p1 <= p2 would raise TypeError because __le__ is not implemented. To make the class fully comparable, you must implement all six methods or use a helper.

Using functools.total_ordering to Reduce Boilerplate

The functools.total_ordering class decorator lets you define only __eq__ and one other comparison method (e.g., __lt__), and it fills in the remaining five methods for you. The decorator inspects the class and adds the missing methods based on the ones you provide.

from functools import total_ordering

@total_ordering
class Person:
    def __init__(self, name, age):
        self.name = name
        self.age = age

    def __eq__(self, other):
        if not isinstance(other, Person):
            return NotImplemented
        return self.age == other.age

    def __lt__(self, other):
        if not isinstance(other, Person):
            return NotImplemented
        return self.age < other.age

Now <=, >, >=, and != work automatically. The decorator uses the provided methods to derive the others. For example, __le__ is implemented as self < other or self == other. This reduces boilerplate and keeps the logic in one place.

However, total_ordering has a performance cost: the derived methods call the provided ones, adding an extra layer of indirection. For most applications this is negligible, but if you are comparing millions of objects in a tight loop, you might prefer manual implementations to avoid the overhead.

Equality, Hashing, and the hash Contract

When you override __eq__ in a class, Python automatically sets __hash__ to None unless you explicitly define it. This makes instances unhashable, which breaks their use in sets and as dictionary keys. The reason is that equal objects must have the same hash value. If you define equality based on mutable attributes, the hash could change, making the object unusable in hash-based collections.

If your objects are immutable or you ensure the hash is based on the same attributes used for equality, you can define __hash__.

class Person:
    def __init__(self, name, age):
        self.name = name
        self.age = age

    def __eq__(self, other):
        if not isinstance(other, Person):
            return NotImplemented
        return self.name == other.name and self.age == other.age

    def __hash__(self):
        return hash((self.name, self.age))

Here, equality is based on name and age, and the hash uses the same tuple. This satisfies the contract. If you only need ordering and not hashing, leaving __hash__ as None is acceptable, but be aware that the objects cannot be placed in sets or used as dict keys.

Common Mistakes When Overriding Comparison Methods

One frequent mistake is returning False when comparing to an unrelated type instead of returning NotImplemented. Returning NotImplemented tells Python to try the reflected operation on the other operand, which is the correct way to handle mixed-type comparisons.

def __eq__(self, other):
    if not isinstance(other, Person):
        return NotImplemented  # correct
    return self.age == other.age

If you return False for an incompatible type, you may get misleading behavior. For example, person == 42 would silently return False instead of raising a clear error or deferring to the other type.

Another mistake is forgetting to implement __ne__ when using manual methods. In Python 3, != is not automatically derived from __eq__; you must define __ne__ explicitly or rely on total_ordering. Without it, != falls back to identity, which can produce incorrect results.

Performance and Maintainability Considerations

When you implement comparison methods, keep the logic simple and avoid expensive operations inside them. Sorting a list calls __lt__ many times, so a method that does heavy computation can slow down the sort significantly. If the comparison depends on a computed value, consider caching that value as an attribute.

Using total_ordering adds a small overhead because derived methods call the provided ones. In performance-critical code, you might implement all six methods manually. The trade-off is more code to maintain, but you have full control over the behavior.

Another maintainability concern is consistency. If you change the equality criteria, you must also update the hash function and any other comparison methods that rely on the same attributes. Keeping the logic centralized, for example by using a single _key() method, can reduce the risk of inconsistency.

class Person:
    def _key(self):
        return (self.name, self.age)

    def __eq__(self, other):
        if not isinstance(other, Person):
            return NotImplemented
        return self._key() == other._key()

    def __lt__(self, other):
        if not isinstance(other, Person):
            return NotImplemented
        return self._key() < other._key()

This pattern makes it clear which attributes participate in comparisons and keeps the logic in one place.

Using Dataclasses for Automatic Comparison

If your class primarily stores data, the @dataclass decorator can generate comparison methods for you. By default, dataclasses implement __eq__ and __repr__, and you can enable ordering with order=True.

from dataclasses import dataclass

@dataclass(order=True)
class Person:
    name: str
    age: int

This generates all six comparison methods based on the fields in declaration order. The generated __lt__ compares name first, then age. If you need a different ordering, you can set order=False and implement the methods manually, or use a field that sorts correctly.

Dataclasses also handle __hash__ in a specific way: if eq=True and frozen=False, the class is unhashable. If you set frozen=True, it becomes hashable. This aligns with the hash contract and saves you from writing boilerplate.

For simple data containers, dataclasses are often the most maintainable option. They reduce the amount of code you need to write and make the intent clear. For classes with more complex behavior, manual implementation or total_ordering gives you finer control.