Arithmetic overloading#

Python allows for some very fancy overloading of just about every operation. We’ll briefly show you how to do overloading for numeric operations.

Suppose we want to design a class that lets us work with three-dimensional vectors. There are a number of operations we might want to define:

vector addition (add the components together)
scalar addition (add a value to every component)
scalar multiplication (multiply every component by a value)
equality (return True on equal vectors)

Python lets us define these operations so that we can use existing Python + and * and == operators. Let’s see how. Here’s the code:

We put some print statements at overloaded methods to clarify what’s getting called when. Here’s an example interaction:

>>> origin = Vector(0, 0, 0)
>>> v1 = Vector(1, 1, 1)
>>> x = Vector(1, 0, 0)
>>> origin + 1
Vector.__add__((0, 0, 0), 1)
Vector(1, 1, 1)
>>> 1 + origin
Vector.__radd__((0, 0, 0), 1)
Vector(1, 1, 1)
>>> origin + 1 == v1
Vector.__add__((0, 0, 0), 1)
Vector.__eq__((1, 1, 1), (1, 1, 1))
True
>>> origin + v1
Vector.__add__((0, 0, 0), (1, 1, 1))
Vector(1, 1, 1)
>>> v1 + origin
Vector.__add__((1, 1, 1), (0, 0, 0))
Vector(1, 1, 1)
>>> x * 3
Vector.__mul__((1, 0, 0), 3)
Vector(3, 0, 0)
>>> x * 3 + v1
Vector.__mul__((1, 0, 0), 3)
Vector.__add__((3, 0, 0), (1, 1, 1))
Vector(4, 1, 1)

From the sample interactions, we can see that __add__ gets called on the object on the left and __radd__ gets called on the object on the right. But why does the call to __radd__ happen when we write 1 + origin? The key is in the NotImplemented return value.

Overloaded operations tend to take the form of:

Test isinstance against the current class, and then return the right answer.
Test isinstance against other types that could work, and then return the right answer.
Give up and return NotImplemented (or raise NotImplementedError).

Given e1 + e2, Python will first try calling e1.__add__(e2). If that doesn’t work (e.g., NotImplemented), then it will try e2.__radd__(e1). Since int.__add__ doesn’t know about Vector, it gave back a NotImplemented, so 1 + origin called origin.__radd__(1).

We also overloaded __eq__… and __hash__. Overloading __eq__ lets us define a notion of equality—very convenient! It is very important that if you overload __eq__, you overload __hash__. The __hash__ function takes an arbitrary value and produces a number. If two values are __eq__ to each other (i.e., they are equal according to ==), then they must have the same hash. Values with the same hash need not be equal, though.

You’ll learn more about hashing in a data structures course. For now, it suffices to take any relevant state/members and hash the tuple of them, as our __hash__ here does.