Python Magic Methods

Each magic method connects your class to a specific piece of syntax or built-in function:

You don't call these methods directly; you use the normal syntax and Python looks them up on the class. Only the names Python defines have special meaning. Inventing __colour__ creates an ordinary method with an awkward name, and PEP 8 reserves the double-underscore-both-sides style for Python's own names.

__str__ returns the readable text shown to users by print(), str() and f-strings. It must return a string:

class Station:
    def __init__(self, code, name):
        self.code, self.name = code, name

    def __str__(self):
        return f"{self.name} ({self.code})"

riverside = Station("RIV", "Riverside")
print(riverside)            # Riverside (RIV)
print(f"Reading from {riverside}")

A common mistake is to print() inside __str__ instead of returning. That prints the text once, then Python complains TypeError: __str__ returned non-string (type NoneType). If a class defines no __str__, Python falls back to __repr__.

__repr__ returns an unambiguous description for developers. It's what the interactive shell shows, what appears when the object is inside a list or dictionary, and what debuggers and logs display. The convention is to make it look like the code that would recreate the object:

    def __repr__(self):
        return f"Station(code={self.code!r}, name={self.name!r})"

print([riverside])   # [Station(code='RIV', name='Riverside')]

The !r conversion adds quotes around strings, so 'RIV' can't be mistaken for a variable name or a number. If you write only one of the two methods, write __repr__, since str() falls back to it but not the other way round.

Keep secrets out of representations. A repr that includes an API key or password will end up in log files and error reports; show a masked value or leave the field out.

By default, == on objects compares identity: two separate Station("RIV") objects are not equal. Define __eq__ to compare by value:

    def __eq__(self, other):
        if not isinstance(other, Station):
            return NotImplemented
        return self.code == other.code

Returning NotImplemented (a special constant, not an exception) tells Python "I don't know how to compare with that type", so it can try the other object's method and finally fall back to False for ==. Don't raise an error or return False directly.

Defining __eq__ sets __hash__ to None, making instances unusable in sets and as dictionary keys, because equal objects must have equal hashes. If your objects are effectively immutable, add def __hash__(self): return hash(self.code). For ordering (<, >, sorted()), define __lt__, and use functools.total_ordering to generate the rest from __eq__ and __lt__. A @dataclass can generate all of this for you.

Task: add friendly and diagnostic station representations and compare equal station values.

class Station:
    def __init__(self, code, name):
        self.code, self.name = code, name
    def __str__(self):
        return f"{self.name} station"
    def __repr__(self):
        return f"Station({self.code!r}, {self.name!r})"
    def __eq__(self, other):
        if not isinstance(other, Station):
            return NotImplemented
        return self.code == other.code
    def __hash__(self):
        return hash(self.code)

a, b = Station("RIV", "Riverside"), Station("RIV", "River Side")
print(a)               # Riverside station
print(repr(b))         # Station('RIV', 'River Side')
print(a == b, a is b)  # True False
print(len({a, b}))     # 1

Equal codes make the two objects equal and give them the same hash, so the set keeps only one. For the worked check, the method intended for diagnostic representation is __repr__.

The data model chapter of the language reference lists every special method name. Continue with class methods and properties and type hints and dataclasses. Practise with the Python exercises and Python quiz.