Magic (Dunder) Methods

Introduction

Have you ever wondered how print(my_list) shows readable content, how len("hello") works, or how 3 + 4 and "a" + "b" both work with the same + symbol? Behind the scenes, Python objects implement special methods with double underscores before and after their names — commonly called "dunder" methods (short for "double underscore"), or sometimes "magic methods."

In this lesson, you will learn what dunder methods are and why they matter, and implement several of the most important ones — __init__, __str__, __repr__, __len__, __eq__, __add__, and a preview of __getitem__ — on your own custom class.

What Are Dunder Methods?

Dunder methods are special methods whose names begin and end with two underscores, such as __init__ or __str__. Python calls these methods automatically in response to specific built-in operations — creating an object, printing it, checking its length, comparing it with ==, or adding it with +.

You never call a dunder method directly by typing obj.__str__() in normal code (though you technically could) — instead, you write ordinary Python syntax like print(obj), and Python looks up and calls the matching dunder method behind the scenes.

__init__: The Constructor (Recap)

You already know __init__ well from earlier lessons — it is itself a dunder method, called automatically whenever a new object is created, used to set up the object's initial attributes.

class Book:
    def __init__(self, title, pages):
        self.title = title
        self.pages = pages


b = Book("Python Basics", 320)
print(b.title, b.pages)

Python Basics 320

__init__ is the first dunder method most Python learners meet, and it sets the pattern for all the others: a special name, surrounded by double underscores, triggered automatically by ordinary syntax (here, calling Book(...)).

__str__ vs __repr__

Without any dunder methods for display, printing an object shows an unhelpful default like <__main__.Book object at 0x000001>. Defining __str__ and/or __repr__ lets you control what that text looks like.

class Book:
    def __init__(self, title, pages):
        self.title = title
        self.pages = pages

    def __str__(self):
        return f"'{self.title}' ({self.pages} pages)"

    def __repr__(self):
        return f"Book(title={self.title!r}, pages={self.pages})"


b = Book("Python Basics", 320)
print(b)        # uses __str__
print(str(b))   # uses __str__ explicitly
print(repr(b))  # uses __repr__ explicitly
b               # in an interactive shell, this would show __repr__

'Python Basics' (320 pages)
'Python Basics' (320 pages)
Book(title='Python Basics', pages=320)

__len__: Custom Length

Defining __len__ lets the built-in len() function work on instances of your own class, just like it works on strings, lists, and dictionaries.

class Playlist:
    def __init__(self, songs):
        self.songs = songs

    def __len__(self):
        return len(self.songs)


p = Playlist(["Song A", "Song B", "Song C"])
print(len(p))   # calls p.__len__() behind the scenes

3

__eq__: Custom Equality

By default, == on two custom objects checks whether they are literally the same object in memory — two separately-created objects with identical data would compare as unequal. Defining __eq__ lets you specify what "equal" should mean for your class instead.

class Point:
    def __init__(self, x, y):
        self.x = x
        self.y = y

    def __eq__(self, other):
        return self.x == other.x and self.y == other.y


p1 = Point(2, 3)
p2 = Point(2, 3)
p3 = Point(5, 9)

print(p1 == p2)   # True: same x and y, thanks to our __eq__
print(p1 == p3)   # False: different coordinates

True
False

__add__: Operator Overloading

You previewed this in the Polymorphism lesson: defining __add__ lets the + operator work sensibly with your own custom objects, following whatever "addition" means for that class.

class Point:
    def __init__(self, x, y):
        self.x = x
        self.y = y

    def __add__(self, other):
        return Point(self.x + other.x, self.y + other.y)

    def __str__(self):
        return f"({self.x}, {self.y})"


p1 = Point(1, 2)
p2 = Point(3, 4)
print(p1 + p2)   # calls p1.__add__(p2) behind the scenes

(4, 6)

__getitem__: A Preview of Indexing

Defining __getitem__ lets your objects support square-bracket indexing, obj[index], just like lists and strings do. This is a small preview of a bigger idea explored fully in the next lesson: implementing __getitem__ (or the related iterator protocol) is part of what makes an object indexable and iterable.

class Playlist:
    def __init__(self, songs):
        self.songs = songs

    def __getitem__(self, index):
        return self.songs[index]


p = Playlist(["Song A", "Song B", "Song C"])
print(p[0])
print(p[2])

Song A
Song C

Why Dunder Methods Matter

Common Mistakes

Best Practices

Frequently Asked Questions

Key Takeaways

Summary

Dunder methods are the bridge between your custom classes and Python's built-in syntax. By implementing methods like __str__, __repr__, __len__, __eq__, and __add__, your objects can be printed, measured, compared, and combined just as naturally as strings, lists, and numbers.

Next, you will build on __getitem__ and explore iterators in depth — the mechanism that powers for loops and lets you create your own custom iterable objects.