Python Operator Overloading: Make Classes Work with +, -, ==

The + operator means different things in different contexts. 3 + 5 gives you 8. 'hello' + ' world' gives you 'hello world'. [1, 2] + [3, 4] gives you [1, 2, 3, 4]. Same symbol, completely different behavior.

How does Python know what + should do? It asks the object on the left side by calling its __add__ method. Integers define __add__ to do math. Strings define it to concatenate. Lists define it to merge.

In this tutorial, you'll learn how to define these methods in your own classes. By the end, your custom objects will work with +, -, *, ==, <, +=, and more — just like built-in types.

Each arithmetic operator maps to a specific magic method. When you write a + b, Python calls a.__add__(b). When you write a - b, Python calls a.__sub__(b). Here's the full mapping:

Let's build a Money class where + combines amounts and - finds the difference.

What happens when you write 3 * money? Python first tries (3).__mul__(money). But integers don't know about your Money class, so __mul__ returns NotImplemented. Python then tries the reflected version: money.__rmul__(3).

Reflected operators have an r prefix: __radd__, __rsub__, __rmul__, etc. They handle the case where your object is on the right side of the operator.

Comparison operators follow the same pattern as arithmetic ones. Each operator calls a specific magic method:

In-place operators like +=, -=, and *= are different from regular ones. a += b is not always the same as a = a + b. With __iadd__, you can modify the object in place instead of creating a new one.

This matters for performance when modifying large objects. Lists use this optimization: my_list += [4, 5] modifies the list in place, while my_list = my_list + [4, 5] creates an entirely new list.

If you don't define __iadd__, Python falls back to __add__. So a += b becomes a = a.__add__(b) — creating a new object. This is fine for immutable types, but wasteful for mutable ones.

Let's put everything together by building a 2D Vector class that supports addition, subtraction, multiplication (by a scalar), equality, comparisons (by length), and in-place operations.

Notice how the Vector class uses @property for length (a computed attribute from the previous tutorial) and how __lt__ compares vectors by their length. This is a natural way to define "less than" for vectors.

Here is a quick reference of the most important operator methods you'll use. You don't need to memorize all of them — just know they exist so you can look them up when needed.