Make your classes feel built in

Ordering, adding and sum()

functools.total_ordering writes <=, > and >= for you from __eq__ and __lt__. Arithmetic works the same way: __add__ handles a + b. sum() starts from the number 0, so it computes 0 + first. That's why __radd__ matters: it's called when the left side doesn't know how to add your object.

from functools import total_ordering

@total_ordering
class Money:
    def __init__(self, cents):
        self.cents = int(cents)

    def __repr__(self):
        return f"Money({self.cents})"

    def __eq__(self, other):
        return isinstance(other, Money) and self.cents == other.cents

    def __hash__(self):
        return hash(self.cents)

    def __lt__(self, other):
        if not isinstance(other, Money):
            return NotImplemented
        return self.cents < other.cents

    def __add__(self, other):
        if isinstance(other, Money):
            return Money(self.cents + other.cents)
        return NotImplemented

    def __radd__(self, other):
        return self if other == 0 else self.__add__(other)

    def __mul__(self, factor):
        return Money(round(self.cents * factor))

    __rmul__ = __mul__

basket = [Money(2000), Money(450), Money(12999)]
print(sorted(basket), max(basket))
print(sum(basket), Money(450) * 3, 2 * Money(450))
print(Money(450) >= Money(450))

Multiplying by a number makes sense (three mugs), but adding a plain number doesn't (is 5 dollars or cents?). So __add__ accepts only Money, and __radd__ makes the single exception for sum()'s 0. Designing a type means deciding which operations are meaningful.

class Money:
    def __init__(self, cents):
        self.cents = int(cents)

    def __repr__(self):
        return f"Money({self.cents})"


paid, price = Money(2000), Money(1450)
change = paid - price
print(change, bool(Money(0)), bool(change))

Containers: len, in, for and [ ]

A class that holds things can behave like a collection. __len__ answers len(), __contains__ answers in, __iter__ makes it work in a for loop (and in list(), sum() and sorted()), and __getitem__ answers square brackets:

class Cart:
    def __init__(self):
        self._lines = {}

    def add(self, sku, qty=1):
        self._lines[sku] = self._lines.get(sku, 0) + qty

    def __len__(self):
        return sum(self._lines.values())

    def __contains__(self, sku):
        return sku in self._lines

    def __iter__(self):
        return iter(self._lines.items())

    def __getitem__(self, sku):
        return self._lines[sku]

    def __call__(self, sku):
        self.add(sku)

cart = Cart()
cart.add("TE-101")
cart("PA-108")
cart("PA-108")
print(len(cart), "TE-101" in cart, cart["PA-108"])
for sku, qty in cart:
    print(sku, qty)
print(bool(Cart()))

__iter__ here hands back an iterator over the dictionary's items; the next lesson shows how to write iterators of your own. Inheriting from collections.abc.Mapping or Sequence instead fills in the rest of a container's methods (get, keys, index and so on) from the few you write. An empty cart is falsy with no __bool__ needed, because Python falls back to __len__. __call__ makes the object callable like a function, handy for objects that are mostly one action, but use it sparingly: cart.add(sku) says more than cart(sku).

Designing a value type

Special methods are powerful, which is a reason to use them with restraint. A few guidelines keep a class pleasant rather than surprising:

• Only add operations that have one obvious meaning. Money plus Money is clear; Money times a number is clear; Money plus a plain number isn't (dollars or cents?), so it's refused. If two people could read a + b differently, use a named method instead.
• Keep value types immutable. Anything you hash must not change afterwards. A frozen dataclass gives you __eq__, __hash__ and __repr__ for free, and refuses accidental changes.
• Return new objects from arithmetic rather than changing self. a + b shouldn't alter a.
• Return NotImplemented, don't raise, when you can't handle the other type. Python then gives the other object a chance, and raises a clear TypeError if neither can.
• Write __repr__ first. It's the one you'll read in every debugging session, test failure and log line. A good repr like Money(1250) can be pasted straight back into code to recreate the object.

This is how NumPy, pandas and PyTorch feel natural: arrays add with +, compare with <, slice with [ ] and report their size with len(), all through the same special methods you just wrote.

from dataclasses import dataclass
from functools import total_ordering

@total_ordering
@dataclass(frozen=True)
class Money:
    cents: int

    def __str__(self):
        return f"${self.cents / 100:,.2f}"

    def __lt__(self, other):
        return self.cents < other.cents

    def __add__(self, other):
        return Money(self.cents + other.cents) if isinstance(other, Money) else NotImplemented

    def __radd__(self, other):
        return self if other == 0 else NotImplemented

class PriceList:
    def __init__(self, prices):
        self._prices = dict(prices)

    def __getitem__(self, sku):
        return self._prices[sku]

    def __contains__(self, sku):
        return sku in self._prices

    def __len__(self):
        return len(self._prices)

    def __iter__(self):
        return iter(sorted(self._prices, key=self._prices.get))

prices = PriceList({"TE-101": Money(20000), "CA-132": Money(500), "PA-108": Money(5500)})
print(len(prices), "products; cheapest first:", list(prices))
order = ["TE-101", "PA-108", "PA-108"]
print("total:", sum(prices[s] for s in order))
print("XX-000" in prices, max(prices[s] for s in prices))