Dunder Methods

When you use Python’s built-in syntax—like adding two numbers with +, checking length with len(), or printing an object—Python handles the operation by looking for specific methods behind the scenes. These special methods are often called dunder methods because their names begin and end with “double underscores”, such as __init__ or __str__.

By defining dunder methods in your own classes, you can seamlessly integrate your custom objects with Python’s built-in functions and operators. This is what gives Python its distinctive, readable flair.

String Representations

The most common dunder methods you will use dictate how an object is converted into a string. Python provides two distinct string representations: the official representation (__repr__) and the informal representation (__str__).

The Official Representation: __repr__

The __repr__ method computes the “official” string representation of an object. Its goal is to be unambiguous and helpful for developers who are debugging. If at all possible, the string returned by __repr__ should look like a valid Python expression that could be used to recreate the object.

class Point:
    def __init__(self, x, y):
        self.x = x
        self.y = y
    def __repr__(self):
        return f'Point({self.x}, {self.y})'

p = Point(1, 2)
print(repr(p))

Point(1, 2)

The Informal Representation: __str__

While __repr__ is for developers, the __str__ method computes the “informal” or nicely printable string representation of an object. This is what users should see. It is automatically called when you pass your object to print() or str().

class User:
    def __init__(self, username):
        self.username = username
    def __str__(self):
        return f'User: @{self.username}'

u = User('alice123')
print(u)

User: @alice123

If you define __repr__ but omit __str__, Python will fall back to using your __repr__ method for printing. However, if you only define __str__, collections like lists will still use the default memory-address representation when printing their elements. It is generally a best practice to always define __repr__.

Customizing Equality

By default, if you use the == operator on two custom objects, Python simply checks if they are the exact same object in memory (their identity). If you want to compare their actual values, you must override the __eq__ method.

The __eq__ method is part of Python’s “rich comparison” toolkit. When you evaluate x == y, Python secretly calls x.__eq__(y).

class Item:
    def __init__(self, name, price):
        self.name = name
        self.price = price
    def __eq__(self, other):
        if not isinstance(other, Item):
            return False
        return self.name == other.name and self.price == other.price

i1 = Item('Apple', 1.0)
i2 = Item('Apple', 1.0)
print(i1 == i2)

True

Notice that we first check if the other object is actually an instance of Item. Failing to check isinstance() can lead to an AttributeError if your object is accidentally compared to a totally different type, like an integer or a string.

Emulating Containers

If you want your object to behave like a collection (such as a list or a dictionary), you can define methods that Python expects containers to have. For example, the __len__ method allows custom objects to be passed to the built-in len() function.

class Team:
    def __init__(self, members):
        self.members = members
    def __len__(self):
        return len(self.members)

t = Team(['Alice', 'Bob', 'Charlie'])
print(len(t))

3

If __len__ returns a negative number or a non-integer, Python will raise an error.

Operator Overloading

Operator overloading allows your custom objects to use standard mathematical symbols like +, -, or *. You implement this by defining arithmetic dunder methods.

For instance, to evaluate the expression x + y, Python invokes the __add__ method. This allows you to construct intuitive interfaces for mathematical types like Vectors.

class Vector:
    def __init__(self, x, y):
        self.x = x
        self.y = y
    def __add__(self, other):
        return Vector(self.x + other.x, self.y + other.y)
    def __str__(self):
        return f'<{self.x}, {self.y}>'

v1 = Vector(1, 2)
v2 = Vector(3, 4)
print(v1 + v2)

<4, 6>

You can also combine your object with standard Python data types. If we want to multiply a vector by an integer scalar, we can implement the __mul__ method (*).

class Vector:
    def __init__(self, x, y):
        self.x = x
        self.y = y
    def __mul__(self, scalar):
        return Vector(self.x * scalar, self.y * scalar)
    def __str__(self):
        return f'<{self.x}, {self.y}>'

v = Vector(2, 3)
print(v * 4)

<8, 12>

Dunder methods are the secret sauce that makes Python feel cohesive. By hooking into the data model, your custom classes can participate in Python’s ecosystem exactly like the built-in types do.