Python Dunder (Magic) Methods

3Python Dunder Methods: explained step by step

You have already written __init__, and in the classes lesson you met __str__ and __repr__. Those are dunder methods (short for double underscore, also called magic or special methods). You never call them yourself; Python calls them for you at particular moments. The surprise is how many everyday operations work this way.

Python's syntax is a set of hooks

Every familiar operation is quietly a method call. len(x) runs x.__len__(), a + b runs a.__add__(b), and x[0] runs x.__getitem__(0). Built-in types already define these methods, which is why len("hi") and [1] + [2] work. When you define the same methods in your own class, your objects start behaving like built-in ones.

You will almost never type a dunder name in normal code. You write the method once inside the class, then use the normal syntax and let Python call it.

len() with __len__

Return a whole number and len(obj) works:

class Playlist:
    def __init__(self, songs):
        self.songs = list(songs)

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

mix = Playlist(["Havana", "Levitating", "Sunflower"])
print(len(mix))
print(mix.__len__())     # what Python really calls

Indexing and loops with __getitem__

mix[0] calls mix.__getitem__(0). There is a bonus: if a class has __getitem__ but no __iter__, a for loop still works. Python simply asks for item 0, then 1, then 2, and so on, until the method raises IndexError. Delegating to the list inside means that negative indexes and the end of the loop come for free.

class Playlist:
    def __init__(self, songs):
        self.songs = list(songs)

    def __getitem__(self, index):
        return self.songs[index]

mix = Playlist(["Havana", "Levitating", "Sunflower"])
print(mix[0], mix[-1])
for song in mix:
    print("Now playing:", song)

Equality with __eq__

By default == on your own objects only asks "is this the very same object?". Two separate Point(1, 2) objects are not equal. Define __eq__ to compare what the objects contain.

class Point:
    def __init__(self, x, y):
        self.x = x
        self.y = y

    def __eq__(self, other):
        if not isinstance(other, Point):
            return NotImplemented
        return (self.x, self.y) == (other.x, other.y)

print(Point(1, 2) == Point(1, 2))
print(Point(1, 2) == Point(3, 4))
print(Point(1, 2) == "hello")
try:
    print({Point(1, 2)})
except TypeError as err:
    print("TypeError:", err)

The last lines show a side effect worth knowing: once a class defines __eq__ without __hash__, Python marks its objects as unhashable, so they cannot go into a set or be dictionary keys. The reason is a safety rule: objects that are equal must have equal hashes, and Python can no longer promise that. If you need hashing, add a __hash__ that uses the same fields you compare, for example hash((self.x, self.y)).

Ordering with __lt__

sorted() and min()/max() compare objects with <. Define __lt__ ("less than") and your objects can be sorted:

class Runner:
    def __init__(self, name, seconds):
        self.name = name
        self.seconds = seconds

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

    def __repr__(self):
        return f"{self.name}({self.seconds}s)"

field = [Runner("Asha", 312), Runner("Ben", 287), Runner("Chen", 301)]
print(sorted(field))
print(min(field))

Python can flip a > b into b < a on its own, but it cannot turn < into <=. For all six comparison operators from one __lt__ plus __eq__, put @functools.total_ordering above the class (see the examples page).

Arithmetic with __add__, __sub__, __mul__

When Python sees a + b it really runs a.__add__(b). Return a new object, and leave a and b unchanged, just as 1 + 2 does not change the 1.

class Vector:
    def __init__(self, x, y):
        self.x = x
        self.y = y

    def __add__(self, other):
        if not isinstance(other, Vector):
            return NotImplemented
        return Vector(self.x + other.x, self.y + other.y)

    def __sub__(self, other):
        if not isinstance(other, Vector):
            return NotImplemented
        return Vector(self.x - other.x, self.y - other.y)

    def __mul__(self, factor):
        if not isinstance(factor, (int, float)):
            return NotImplemented
        return Vector(self.x * factor, self.y * factor)

    def __repr__(self):
        return f"Vector({self.x}, {self.y})"

a = Vector(1, 2)
b = Vector(4, 6)
print(a + b)
print(b - a)
print(a * 3)
print(a.__add__(b))          # exactly what a + b does
try:
    a + "oops"
except TypeError as err:
    print("TypeError:", err)

Returning NotImplemented

When your method receives a type it does not understand, return NotImplemented (do not raise it). It is a special value meaning "I can't do this with that type, ask the other side". Python then tries the other object's reflected method (__radd__ for +), and only when nobody knows what to do does it raise the clear TypeError: unsupported operand type(s)... you saw above. If you skip the check, a wrong type usually crashes with a confusing AttributeError from deep inside your method instead.

Membership with __contains__

item in obj calls obj.__contains__(item). Without it Python falls back to looping over the object, so define it when you can answer faster or want a custom rule, such as ignoring upper and lower case.

Truthiness with __bool__

if obj: and bool(obj) call __bool__. If a class has no __bool__, Python tries __len__ (zero means false). If it has neither, the object is always true.

class Inbox:
    def __init__(self, messages):
        self.messages = messages

    def __contains__(self, word):
        return any(word.lower() in text.lower() for text in self.messages)

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

class Wallet:
    def __init__(self, cash):
        self.cash = cash

    def __bool__(self):
        return self.cash > 0

inbox = Inbox(["Meeting at 10", "Invoice attached"])
print("invoice" in inbox, "lunch" in inbox)
print(bool(inbox), bool(Inbox([])))
print(bool(Wallet(0)), bool(Wallet(5)))

Objects that behave like functions: __call__

Define __call__ and you can put parentheses after an object: obj(arguments) runs obj.__call__(arguments). It is handy when a "function" also needs to remember settings or a running total.

class Discount:
    def __init__(self, percent):
        self.percent = percent

    def __call__(self, price):
        return round(price * (1 - self.percent / 100), 2)

summer = Discount(20)
print(summer(50))
print([summer(p) for p in [10, 25.5]])
print(callable(summer))

Use them with restraint

Implement an operator only when its meaning is obvious. Vector + Vector is natural; User + User is not, and a plain method such as merge() is clearer. Dunder methods make your classes feel like part of the language, but only when they behave the way a reader would guess.