Special Methods (Dunder)

Intermediate ~30 min read

Special methods (also called "dunder" methods for "double underscore") let you define how your objects behave with Python's built-in operations. Implement __str__ for print(), __eq__ for ==, __add__ for +, and make your classes feel like native Python types.

What Are Dunder Methods?

Dunder methods have double underscores on both sides: __init__, __str__, __add__. Python calls these automatically when you use operators, built-in functions, or certain syntax on your objects. They're the hook into Python's data model.

String Representation: str and repr

Control how your objects appear when printed or displayed. __str__ is for end users, __repr__ is for developers and debugging.

# String Representation: __str__ and __repr__

print("=== __str__ and __repr__ ===\n")

# 1. The problem without them
print("1. Without __str__ or __repr__:")

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

p = PointBad(3, 4)
print(f"   print(p): {p}")  # Ugly: <__main__.PointBad object at 0x...>
print()

# 2. __str__ - for users
print("2. __str__ - human-readable output:")

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

def __str__(self):
        """User-friendly string representation."""
        return f"({self.x}, {self.y})"

p = Point(3, 4)
print(f"   print(p): {p}")           # Calls __str__
print(f"   str(p): {str(p)}")        # Calls __str__
print(f"   f-string: Point is {p}")  # Calls __str__
print()

# 3. __repr__ - for developers
print("3. __repr__ - developer/debugging output:")

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

def __repr__(self):
        """Developer-friendly, ideally valid Python code."""
        return f"Vector({self.x}, {self.y})"

v = Vector(3, 4)
print(f"   repr(v): {repr(v)}")
print(f"   In list: {[v]}")  # Lists use __repr__ for items
print()

# 4. Both __str__ and __repr__
print("4. Best practice - implement both:")

class Person:
    def __init__(self, name, age):
        self.name = name
        self.age = age

def __str__(self):
        """For end users - nice and readable."""
        return f"{self.name}, {self.age} years old"

def __repr__(self):
        """For developers - shows how to recreate."""
        return f"Person('{self.name}', {self.age})"

alice = Person("Alice", 30)
print(f"   str:  {str(alice)}")    # Alice, 30 years old
print(f"   repr: {repr(alice)}")   # Person('Alice', 30)
print(f"   In list: {[alice]}")    # Uses repr
print()

# 5. The golden rule for __repr__
print("5. The golden rule:")
print("""
   __repr__ should ideally be valid Python code that recreates the object:

>>> p = Person('Bob', 25)
   >>> repr(p)
   "Person('Bob', 25)"
   >>> eval(repr(p))  # Recreates the object!
   Person('Bob', 25)
""")

# 6. If only __repr__ is defined
print("6. If only __repr__ is defined:")

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

def __repr__(self):
        return f"Book('{self.title}')"
    # No __str__ defined!

book = Book("Python Guide")
print(f"   str(book): {str(book)}")   # Falls back to __repr__
print(f"   repr(book): {repr(book)}")
print()
print("   Tip: If you only implement one, implement __repr__!")
print("   Python uses __repr__ as fallback for __str__")

Output

Click Run to execute your code

The Golden Rule for repr

Make __repr__ return valid Python code that could recreate the object: eval(repr(obj)) should give you an equivalent object. If you only implement one, implement __repr__ - Python uses it as a fallback for __str__.

Comparison Methods

Make your objects comparable with ==, <, >, and enable sorting. Use @total_ordering to only define __eq__ and __lt__.

# Comparison Methods: __eq__, __lt__, __gt__, etc.

print("=== Comparison Methods ===\n")

# 1. __eq__ - equality (==)
print("1. __eq__ for equality (==):")

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

def __eq__(self, other):
        """Compare equality based on coordinates."""
        if not isinstance(other, Point):
            return NotImplemented
        return self.x == other.x and self.y == other.y

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

p1 = Point(3, 4)
p2 = Point(3, 4)
p3 = Point(5, 6)

print(f"   p1 == p2: {p1 == p2}")  # True (same coordinates)
print(f"   p1 == p3: {p1 == p3}")  # False
print(f"   p1 is p2: {p1 is p2}")  # False (different objects)
print()

# 2. __lt__ and __gt__ - less than, greater than
print("2. __lt__ for sorting (<, >, sorted()):")

class Student:
    def __init__(self, name, grade):
        self.name = name
        self.grade = grade

def __lt__(self, other):
        """Compare by grade."""
        return self.grade < other.grade

def __eq__(self, other):
        return self.grade == other.grade

def __repr__(self):
        return f"{self.name}:{self.grade}"

students = [
    Student("Alice", 85),
    Student("Bob", 92),
    Student("Carol", 78)
]

print(f"   Unsorted: {students}")
print(f"   Sorted: {sorted(students)}")  # Uses __lt__
print(f"   Max: {max(students)}")        # Uses __lt__
print()

# 3. Using functools.total_ordering
print("3. @total_ordering - define only __eq__ and __lt__:")

from functools import total_ordering

@total_ordering
class Version:
    """Only define __eq__ and __lt__, get the rest free!"""

def __init__(self, major, minor, patch):
        self.major = major
        self.minor = minor
        self.patch = patch

def __eq__(self, other):
        return (self.major, self.minor, self.patch) == \
               (other.major, other.minor, other.patch)

def __lt__(self, other):
        return (self.major, self.minor, self.patch) < \
               (other.major, other.minor, other.patch)

def __repr__(self):
        return f"v{self.major}.{self.minor}.{self.patch}"

v1 = Version(1, 0, 0)
v2 = Version(1, 2, 0)
v3 = Version(2, 0, 0)

print(f"   {v1} < {v2}: {v1 < v2}")   # True
print(f"   {v1} <= {v2}: {v1 <= v2}") # True (from @total_ordering)
print(f"   {v3} > {v2}: {v3 > v2}")   # True (from @total_ordering)
print(f"   {v2} >= {v1}: {v2 >= v1}") # True (from @total_ordering)
print()

# 4. __hash__ - for use in sets and dict keys
print("4. __hash__ - required for sets/dict keys:")

class Color:
    def __init__(self, r, g, b):
        self.r = r
        self.g = g
        self.b = b

def __eq__(self, other):
        return (self.r, self.g, self.b) == (other.r, other.g, other.b)

def __hash__(self):
        """Must be consistent with __eq__."""
        return hash((self.r, self.g, self.b))

def __repr__(self):
        return f"RGB({self.r},{self.g},{self.b})"

# Now can use in sets and as dict keys!
colors = {Color(255, 0, 0), Color(0, 255, 0), Color(255, 0, 0)}
print(f"   Color set: {colors}")  # Duplicates removed!

color_names = {Color(255, 0, 0): "Red", Color(0, 255, 0): "Green"}
print(f"   Color names: {color_names}")
print()

# 5. Important rules
print("5. Important rules:")
print("""
   - If you define __eq__, also define __hash__ (or set __hash__ = None)
   - Objects that compare equal MUST have the same hash
   - Mutable objects shouldn't be hashable (can't be dict keys)
   - Use @total_ordering to avoid implementing all 6 comparison methods
""")

Output

Click Run to execute your code

eq and hash Are Linked

If you define __eq__, you should also define __hash__ (or set __hash__ = None to make objects unhashable). Objects that compare equal must have the same hash value - this is required for sets and dict keys.

Arithmetic Operators

Implement +, -, *, and other operators for your objects. This is called operator overloading.

# Arithmetic Operators: __add__, __sub__, __mul__, etc.

print("=== Arithmetic Operators ===\n")

# 1. Basic arithmetic operators
print("1. Basic arithmetic (__add__, __sub__, __mul__):")

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

def __add__(self, other):
        """v1 + v2"""
        return Vector(self.x + other.x, self.y + other.y)

def __sub__(self, other):
        """v1 - v2"""
        return Vector(self.x - other.x, self.y - other.y)

def __mul__(self, scalar):
        """v * 3 (scalar multiplication)"""
        return Vector(self.x * scalar, self.y * scalar)

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

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

print(f"   v1 + v2 = {v1 + v2}")
print(f"   v1 - v2 = {v1 - v2}")
print(f"   v1 * 3 = {v1 * 3}")
print()

# 2. Reverse operators (__radd__, __rmul__)
print("2. Reverse operators (3 * v instead of v * 3):")

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

def __mul__(self, scalar):
        """v * 3"""
        return Vector2(self.x * scalar, self.y * scalar)

def __rmul__(self, scalar):
        """3 * v - called when left operand doesn't support *"""
        return self.__mul__(scalar)

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

v = Vector2(2, 3)
print(f"   v * 5 = {v * 5}")
print(f"   5 * v = {5 * v}")  # Uses __rmul__
print()

# 3. In-place operators (__iadd__, __imul__)
print("3. In-place operators (+=, *=):")

class Counter:
    def __init__(self, value=0):
        self.value = value

def __add__(self, other):
        """Creates new object"""
        return Counter(self.value + other)

def __iadd__(self, other):
        """Modifies in place (optional but efficient)"""
        self.value += other
        return self  # Must return self!

def __repr__(self):
        return f"Counter({self.value})"

c = Counter(10)
print(f"   Initial: {c}")
c += 5
print(f"   After += 5: {c}")
print()

# 4. Unary operators
print("4. Unary operators (__neg__, __abs__):")

class Temperature:
    def __init__(self, celsius):
        self.celsius = celsius

def __neg__(self):
        """-temp (negative)"""
        return Temperature(-self.celsius)

def __abs__(self):
        """abs(temp)"""
        return Temperature(abs(self.celsius))

def __repr__(self):
        return f"Temperature({self.celsius}°C)"

t = Temperature(-15)
print(f"   t = {t}")
print(f"   -t = {-t}")
print(f"   abs(t) = {abs(t)}")
print()

# 5. Complete operator table
print("5. Common arithmetic methods:")
print("""
   Method        Operator    Example
   ------        --------    -------
   __add__       +           a + b
   __sub__       -           a - b
   __mul__       *           a * b
   __truediv__   /           a / b
   __floordiv__  //          a // b
   __mod__       %           a % b
   __pow__       **          a ** b

__radd__      +           b + a (reverse)
   __iadd__      +=          a += b (in-place)

__neg__       -           -a (unary)
   __pos__       +           +a
   __abs__       abs()       abs(a)
""")

# 6. Practical example: Money class
print("6. Practical example - Money class:")

class Money:
    def __init__(self, dollars, cents=0):
        self.cents = dollars * 100 + cents

def __add__(self, other):
        return Money(0, self.cents + other.cents)

def __sub__(self, other):
        return Money(0, self.cents - other.cents)

def __mul__(self, factor):
        return Money(0, int(self.cents * factor))

def __repr__(self):
        return f"${self.cents // 100}.{self.cents % 100:02d}"

price = Money(19, 99)
tax = Money(1, 60)
total = price + tax
discounted = total * 0.9

print(f"   Price: {price}")
print(f"   Tax: {tax}")
print(f"   Total: {total}")
print(f"   10% off: {discounted}")

Output

Click Run to execute your code

Regular vs Reverse vs In-place

__add__: a + b - called on the left operand
__radd__: b + a - called if left doesn't support the operation
__iadd__: a += b - in-place, should return self

Container Methods

Make your objects behave like lists, dicts, or other containers. Implement __len__, __getitem__, __iter__, and more.

# Container Methods: __len__, __getitem__, __iter__, etc.

print("=== Container Methods ===\n")

# 1. __len__ - length
print("1. __len__ - make len() work:")

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

def add(self, song):
        self.songs.append(song)

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

playlist = Playlist("My Mix")
playlist.add("Song 1")
playlist.add("Song 2")
playlist.add("Song 3")

print(f"   len(playlist): {len(playlist)}")
print(f"   bool(playlist): {bool(playlist)}")  # True if len > 0
print()

# 2. __getitem__ - indexing
print("2. __getitem__ - indexing and slicing:")

class Sentence:
    def __init__(self, text):
        self.words = text.split()

def __getitem__(self, index):
        """sentence[0], sentence[1:3], etc."""
        return self.words[index]

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

s = Sentence("Hello World from Python")
print(f"   s[0]: {s[0]}")
print(f"   s[-1]: {s[-1]}")
print(f"   s[1:3]: {s[1:3]}")  # Slicing works too!
print()

# 3. __setitem__ and __delitem__
print("3. __setitem__ and __delitem__ - assignment and deletion:")

class MyList:
    def __init__(self):
        self._data = []

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

def __setitem__(self, index, value):
        """mylist[0] = 'x'"""
        self._data[index] = value

def __delitem__(self, index):
        """del mylist[0]"""
        del self._data[index]

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

def append(self, value):
        self._data.append(value)

def __repr__(self):
        return f"MyList({self._data})"

ml = MyList()
ml.append(1)
ml.append(2)
ml.append(3)
print(f"   Initial: {ml}")
ml[1] = 99
print(f"   After ml[1] = 99: {ml}")
del ml[0]
print(f"   After del ml[0]: {ml}")
print()

# 4. __contains__ - membership testing
print("4. __contains__ - the 'in' operator:")

class Group:
    def __init__(self, members):
        self.members = set(members)

def __contains__(self, person):
        """person in group"""
        return person in self.members

team = Group(["Alice", "Bob", "Carol"])
print(f"   'Alice' in team: {'Alice' in team}")
print(f"   'David' in team: {'David' in team}")
print()

# 5. __iter__ and __next__ - iteration
print("5. __iter__ - make object iterable:")

class Countdown:
    def __init__(self, start):
        self.start = start

def __iter__(self):
        """Return an iterator object."""
        self.current = self.start
        return self

def __next__(self):
        """Return next value."""
        if self.current <= 0:
            raise StopIteration
        value = self.current
        self.current -= 1
        return value

print("   Countdown from 5:", end=" ")
for n in Countdown(5):
    print(n, end=" ")
print()
print()

# 6. Complete example - custom collection
print("6. Complete example - StudentGrades:")

class StudentGrades:
    """A collection that combines multiple container protocols."""

def __init__(self):
        self._grades = {}

def add_grade(self, student, grade):
        self._grades[student] = grade

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

def __getitem__(self, student):
        return self._grades[student]

def __setitem__(self, student, grade):
        self._grades[student] = grade

def __delitem__(self, student):
        del self._grades[student]

def __contains__(self, student):
        return student in self._grades

def __iter__(self):
        return iter(self._grades.items())

def __repr__(self):
        return f"StudentGrades({dict(self._grades)})"

grades = StudentGrades()
grades.add_grade("Alice", 95)
grades["Bob"] = 87
grades["Carol"] = 92

print(f"   Grades: {grades}")
print(f"   Length: {len(grades)}")
print(f"   Alice's grade: {grades['Alice']}")
print(f"   'Bob' in grades: {'Bob' in grades}")
print("   All grades:")
for student, grade in grades:
    print(f"      {student}: {grade}")

Output

Click Run to execute your code

Iterator vs Iterable

An iterable has __iter__ and returns an iterator. An iterator has both __iter__ (returns self) and __next__. For simple cases, __iter__ can return iter(self.data) and skip __next__.

Common Mistakes

1. Forgetting to return in str / repr

# Wrong - prints instead of returning
class Person:
    def __str__(self):
        print(f"Person: {self.name}")  # Returns None!

# Correct - return a string
class Person:
    def __str__(self):
        return f"Person: {self.name}"

2. Forgetting hash when defining eq

# Problem - objects become unhashable
class Point:
    def __eq__(self, other):
        return self.x == other.x and self.y == other.y
    # No __hash__!

p = Point(1, 2)
{p}  # TypeError: unhashable type: 'Point'

# Solution 1 - implement __hash__
def __hash__(self):
    return hash((self.x, self.y))

# Solution 2 - explicitly unhashable
__hash__ = None  # Can't be in sets/dict keys

3. Not returning self from iadd

# Wrong - doesn't return self
class Counter:
    def __iadd__(self, other):
        self.value += other
        # Missing return self!

c = Counter(5)
c += 3  # c becomes None!

# Correct - always return self
def __iadd__(self, other):
    self.value += other
    return self  # Required!

4. Not handling different types in eq

# Wrong - crashes on type mismatch
class Point:
    def __eq__(self, other):
        return self.x == other.x  # AttributeError if other isn't Point!

# Correct - check type or return NotImplemented
class Point:
    def __eq__(self, other):
        if not isinstance(other, Point):
            return NotImplemented  # Let Python try other.__eq__
        return self.x == other.x and self.y == other.y

5. Inconsistent lt and eq

# Problem - sorting may give unexpected results
class Score:
    def __lt__(self, other):
        return self.value < other.value

    def __eq__(self, other):
        return self.name == other.name  # Different criterion!

# Both should use the same comparison logic
# Or use @total_ordering and be explicit

Exercise: Fraction Class

Task: Create a Fraction class with dunder methods for arithmetic and comparison.

Requirements:

__str__: Return "numerator/denominator" (e.g., "3/4")
__repr__: Return "Fraction(num, denom)"
__eq__: Check equality (1/2 should equal 2/4)
__lt__: Enable sorting
__add__: Add fractions (a/b + c/d = (ad + cb) / bd)
__mul__: Multiply fractions (a/b * c/d = ac / bd)

Output

Click Run to execute your code

Show Solution

class Fraction:
    def __init__(self, numerator, denominator):
        # Simplify fraction
        gcd = self._gcd(abs(numerator), abs(denominator))
        self.num = numerator // gcd
        self.denom = denominator // gcd

    @staticmethod
    def _gcd(a, b):
        while b:
            a, b = b, a % b
        return a

    def __str__(self):
        return f"{self.num}/{self.denom}"

    def __repr__(self):
        return f"Fraction({self.num}, {self.denom})"

    def __eq__(self, other):
        # Works because fractions are simplified
        return self.num == other.num and self.denom == other.denom

    def __lt__(self, other):
        # Compare by cross multiplication
        return self.num * other.denom < other.num * self.denom

    def __add__(self, other):
        new_num = self.num * other.denom + other.num * self.denom
        new_denom = self.denom * other.denom
        return Fraction(new_num, new_denom)

    def __mul__(self, other):
        return Fraction(self.num * other.num, self.denom * other.denom)


# Test
f1 = Fraction(1, 2)
f2 = Fraction(1, 4)
f3 = Fraction(2, 4)

print(f"f1: {f1}, repr: {repr(f1)}")
print(f"f1 == f3: {f1 == f3}")  # True
print(f"f1 + f2: {f1 + f2}")    # 3/4
print(f"f1 * f2: {f1 * f2}")    # 1/8
print(f"Sorted: {sorted([Fraction(3,4), f1, f2])}")

Summary

__str__ for users, __repr__ for developers (implement __repr__ first)
__eq__ + __hash__ for equality and set/dict usage
@total_ordering: Define __eq__ + __lt__, get all comparisons
__add__, __radd__, __iadd__ for +, reverse, and in-place
__len__, __getitem__, __iter__ for container behavior
Return NotImplemented (not raise NotImplementedError) from operators on type mismatch

What's Next?

Now that you know about dunder methods, learn about Properties - using @property decorator to create getters and setters that look like attribute access, providing cleaner syntax than explicit getter/setter methods.

Previous Polymorphism

Next Properties

What Are Dunder Methods?

String Representation: __str__ and __repr__

The Golden Rule for __repr__

Comparison Methods

__eq__ and __hash__ Are Linked

Arithmetic Operators

Regular vs Reverse vs In-place

Container Methods

Iterator vs Iterable

Common Mistakes

1. Forgetting to return in __str__ / __repr__

2. Forgetting __hash__ when defining __eq__

3. Not returning self from __iadd__

4. Not handling different types in __eq__

5. Inconsistent __lt__ and __eq__

Exercise: Fraction Class

Summary

What's Next?

Enjoying these tutorials?

String Representation: str and repr

The Golden Rule for repr

eq and hash Are Linked

1. Forgetting to return in str / repr

2. Forgetting hash when defining eq

3. Not returning self from iadd

4. Not handling different types in eq

5. Inconsistent lt and eq