Special methods: objects that behave like Python values

What you will be able to do

After this lesson you can

• give your objects a clear text with __str__ and __repr__,
• say when two objects are equal with __eq__,
• let sorted, min and max order your objects with __lt__, and
• make +, len, in and loops work on your objects.

Python calls them for you

You have seen __init__, which Python calls when an object is made. There are many more special methods, all with two underscores on each side. You do not call them yourself. Python calls them when an object meets a certain syntax.

When you write print(p), Python calls p.__str__(). When you write p1 == p2, it calls p1.__eq__(p2). When you write len(p), it calls p.__len__(). By writing these methods, you teach your objects how to behave like the built-in values.

Showing an object: __str__ and __repr__

Predict first. What does print(Plain(3)) show? Then run it.

• Without __str__, print shows something like <__main__.Plain object at 0x7f...>: the class and a memory address. It tells a human nothing.
• __str__ returns the text that print and str() show. It is for users: friendly and short.
• __repr__ returns the text that the shell shows and that a list uses for its items. It is for programmers: unambiguous, and often looks like the code that makes the object. That is why print([Nice(1), Nice(2)]) shows Nice(x=1) in the list.
• If only one is written, write __repr__, because print falls back to it when there is no __str__.

Both must return a text. A common mistake is to print inside __str__ instead of returning.

Equal and ordered: __eq__ and __lt__

A warning: if you write __eq__, a class stops being usable as a dictionary key or in a set unless you also write __hash__. That is a topic for later.

Operators, length and loops

__add__ returns a new object. It does not change a or b. This is how + works for numbers and lists too.

The line for item in both works only because __getitem__ exists: Python tries positions 0, 1, 2, ... until it gets an IndexError. That is why __getitem__ was enough, without writing a loop method.

Python calls the special methods for you: + calls __add__, abs() calls __abs__, and print() uses __repr__ when there is no __str__.

A fuller example: vectors

Common mistakes

• __str__ that prints and does not return. print then shows None or an error.
• __eq__ that fails for another type. Money(5) == 5 raises an AttributeError. A careful __eq__ checks isinstance(other, Money) first.
• Changing the object in __add__. It should return a new one.
• Writing __lt__ but expecting > to work. Python can try the other way round for >, but do not rely on it for every operator.
• Misspelling a special method. __str or _str_ is just an ordinary method that nobody calls.

Practice

Start with two quick questions. Each New numbers gives you a fresh one, so you can practise as long as you like.

Then the labs and the problems:

1. Warm-up. Open the lab Show a Point. You write __str__ and __eq__, and the checker tries them.
2. Build. Open the lab A Vector class and the problem Order the notes.
3. Stretch. Open the problem What does Python call? and match the lines of code to the special methods.

Remember these

• Special methods have two underscores on each side, and Python calls them for you.
• __str__ is for print, __repr__ is for programmers and lists. Both return text.
• __eq__ defines ==. __lt__ lets sorted, min and max work.
• __add__, __len__, __contains__ and __getitem__ make +, len, in and loops work.
• __add__ returns a new object.

Check yourself

Try each one on your own first. If you are stuck, open a hint. Then check with Show the answer.

1. Which special method does print(p) call?

2. Why is Money(50) == Money(50) False without __eq__?

3. Which method do sorted and min need?