Dunder protocols: __repr__, the eq/hash contract, truthiness, and NotImplemented

In ten minutes you will know exactly which dunder broke the nightly job — and why fixing it requires touching two methods, not one.

repr and str: the debugging contract

repr(x) calls x.__repr__() and targets developers: unambiguous, ideally eval-able or at least identifying (Order(id=42, total=Decimal('19.90'))). str(x) calls __str__ and targets users; if you don’t define it, str falls back to __repr__ — so define __repr__ first and __str__ only when you need a friendlier form. The default __repr__ is <Order object at 0x7f...>, which is what your logs and tracebacks show at 3 a.m. when you skipped this. Containers always use repr for their elements — print([order]) shows the repr even though you called print — which is exactly the behavior you want when reading a dumped list of 200 orders.

from decimal import Decimal

class Order:
    def __init__(self, id: int, total: Decimal):
        self.id, self.total = id, total

    def __repr__(self) -> str:
        # !r recursively uses repr of the fields — Decimal('19.90'), not 19.90
        return f"Order(id={self.id!r}, total={self.total!r})"

print(repr(Order(42, Decimal("19.90"))))  # Order(id=42, total=Decimal('19.90'))

The eq/hash contract

The rule the interpreter enforces: if a == b then hash(a) == hash(b) must hold, because dicts and sets locate objects by hash bucket first, equality second. Default __eq__ is identity (is), default __hash__ is derived from id() — consistent. The moment you define __eq__, Python sets __hash__ = None on that class: your objects become unhashable until you supply a __hash__ that agrees with your equality (hash the same tuple of fields you compare). The trap from the Hook is the silent half of this: nothing fails at class definition time, only at the first set/dict use. And a second-order trap: hashable objects must be effectively immutable in their hashed fields — mutate order.id after inserting into a set and the object is now in the wrong bucket, present but unfindable. x in s returns False while x sits in s.

class Order:
    def __init__(self, id: int):
        self.id = id

    def __eq__(self, other):
        if not isinstance(other, Order):
            return NotImplemented   # not False — see below
        return self.id == other.id

    def __hash__(self):
        return hash(self.id)        # same fields as __eq__, or the contract breaks

Truthiness and length: the bool/len chain

When you write if response: on your own collection class, does Python call __eq__, __bool__, or something else entirely? The answer determines whether an empty collection is falsy — or whether every instance silently passes the check.

if x: never calls __eq__. It calls bool(x), which tries __bool__ first; if absent, it falls back to __len__ (nonzero length is truthy); if both are absent, every instance is truthy. This chain is why if response: on a custom collection does the right thing for free once you define __len__ — and why it backfires on objects where emptiness is not falseness. The classic production bite: an ORM query object or a datetime.time of midnight ending up in if value: and being treated as “no value”. If your class has a length but “empty” is still meaningful data, either define __bool__ returning True explicitly or make call sites use if value is not None:.

Operator dunders and NotImplemented

a + b runs type(a).__add__(a, b); if that returns the sentinel NotImplemented, Python tries the reflected type(b).__radd__(b, a); only if both decline does it raise TypeError. (One refinement: if type(b) is a subclass of type(a), the reflected method gets the first try, so subclasses can override behavior in mixed expressions.) NotImplemented is a return value meaning “I don’t know this operand type, ask the other side” — it is not the exception NotImplementedError, which is what abstract methods raise to mean “subclass forgot to implement me”. Returning False from __eq__ for unknown types is the subtle version of this bug: you make Order(1) == 1 definitively false instead of letting int have a say, and you break symmetric behavior for someone else’s wrapper type. This is also why protocols beat inheritance in Python: len(), in, iteration, arithmetic all dispatch on dunders, so any class implementing the methods participates — no base class required. Duck typing is dunder dispatch.