Operator Overloading in Python0%

Operator Overloading in Python

Advanced10 min read•Updated: 2026-10-01

Operator Overloading

Operator overloading allows user-defined classes to intercept and define custom semantics for Python's built-in operators—such as arithmetic symbols (+, -, *, /), matrix multiplication (@), augmented assignment (+=, -=), and rich comparison operators (==, <, >=).

Through operator overloading, your custom classes can behave as intuitive, first-class mathematical entities, domain models, or fluent query builders.

1. The Operator Dispatch Architecture & `NotImplemented`

When Python encounters a binary expression like a + b, it dispatches the operation through a multi-stage protocol:

                            Expression: a + b
                                    │
                                    ▼
                    Try: type(a).__add__(a, b)
                                    │
                 ┌──────────────────┴──────────────────┐
                 ▼                                     ▼
    Returns a Valid Result                   Returns NotImplemented
    (Operation finishes)                               │
                                                       ▼
                                           Try: type(b).__radd__(b, a)
                                                       │
                                    ┌──────────────────┴──────────────────┐
                                    ▼                                     ▼
                       Returns a Valid Result                   Returns NotImplemented
                       (Operation finishes)                               │
                                                                          ▼
                                                                Raise TypeError:
                                                    unsupported operand type(s) for +

The Difference: `NotImplemented` vs `NotImplementedError`

Critical Rule: In binary operator dunder methods (__add__, __eq__, __mul__), if your class does not support the type of the operand, you must return the singleton NotImplemented, NOT raise NotImplementedError.

Returning NotImplemented: Tells the Python runtime, "I don't know how to handle this operand. Please check the right-hand operand's reflected method (e.g., __radd__) or fallback comparison."
Raising NotImplementedError: Immediately terminates the expression with an uncaught exception, preventing the other operand from handling the operation.

2. Arithmetic and Reflected Operators

Arithmetic operators come in two primary flavors: normal (left-hand) and reflected/reverse (right-hand, prefixed with r).

Operator	Left-hand Method	Reflected Method	In-place Method
`+`	`__add__(self, other)`	`__radd__(self, other)`	`__iadd__(self, other)`
`-`	`__sub__(self, other)`	`__rsub__(self, other)`	`__isub__(self, other)`
`*`	`__mul__(self, other)`	`__rmul__(self, other)`	`__imul__(self, other)`
`/`	`__truediv__(self, other)`	`__rtruediv__(self, other)`	`__itruediv__(self, other)`
`//`	`__floordiv__(self, other)`	`__rfloordiv__(self, other)`	`__ifloordiv__(self, other)`
`%`	`__mod__(self, other)`	`__rmod__(self, other)`	`__imod__(self, other)`
`**`	`__pow__(self, other)`	`__rpow__(self, other)`	`__ipow__(self, other)`
`@`	`__matmul__(self, other)`	`__rmatmul__(self, other)`	`__imatmul__(self, other)`

Implementing Arithmetic with Scalars and Objects

Visual Architecture & Process Flow

How data and code flow step-by-step

Flowchart

Step 1

def __init__

self, amount: float, currency: str = "USD"

Step 2

None:

3. In-Place Augmented Assignment (`+=`, `-=`, `*=`)

When you define methods like __iadd__, Python invokes them during a += b.

Mutable objects (like list): __iadd__ modifies self in-place and returns self.
Immutable objects (like int, str): If __iadd__ is omitted, Python falls back to a = a + b, allocating a new instance.

1class MutableVector:
2    def __init__(self, x: float, y: float) -> None:
3        self.x = x
4        self.y = y
5 
6    def __iadd__(self, other: "MutableVector") -> "MutableVector":
7        """Mutates the existing vector in place."""
8        if not isinstance(other, MutableVector):
9            return NotImplemented
10        self.x += other.x
11        self.y += other.y
12        return self  # CRITICAL: Always return self for in-place methods
13 
14    def __repr__(self) -> str:
15        return f"MutableVector({self.x}, {self.y})"
16 
17vec = MutableVector(10, 20)
18old_id = id(vec)
19vec += MutableVector(5, 5)
20 
21print("Updated vector:", vec)
22print(f"Preserved exact memory identity: {id(vec) == old_id}")  # True

4. Rich Comparison Operators and `total_ordering`

Python defines 6 rich comparison dunder methods:

Comparison	Method
`==`	`__eq__(self, other)`
`!=`	`__ne__(self, other)`
`<`	`__lt__(self, other)`
`<=`	`__le__(self, other)`
`>`	`__gt__(self, other)`
`>=`	`__ge__(self, other)`

Instead of manually implementing all 6 operators, the standard library provides @functools.total_ordering. You only need to define __eq__ and one ordering method (__lt__, __le__, __gt__, or __ge__), and Python automatically synthesizes the remaining 4 operators.

Visual Architecture & Process Flow

How data and code flow step-by-step

Flowchart

Step 1

def __init__

self, hostname: str, cpu_cores: int, ram_gb: int

Step 2

None:

5. Summary and Architectural Rules

1
Always return NotImplemented on unknown operand types: This allows Python to query the other operand or produce clear, standardized error messages.
2
In-place methods must return self: Failing to return self from __iadd__ will cause variables using += to silently become None.
3
Use total_ordering cautiously in performance-critical paths: While @functools.total_ordering saves boilerplate, explicit implementations of comparison methods execute slightly faster by avoiding dynamic method wrapper lookups.

⚠️ Common Advanced Mistakes & Gotchas

1. In-Place Mutation in Binary Operators

Binary arithmetic operators like __add__(self, other) must return a new instance rather than mutating self. Mutating self violates mathematical immutability expectations.

2. Forgetting Reflected Operators (`radd`)

If the left operand does not support the operation with the right operand, Python falls back to the right operand's reflected method (__radd__). Implementing reflected operators allows operations like 5 + my_vector.

💻 Try It Yourself: Overloading Currency Addition and Comparison

Scenario

Build a Rupee monetary class that supports addition with another Rupee instance or integer, proper string representation, and comparison operators.

Complete Solution

1class Rupee:
2    def __init__(self, amount: float):
3        self.amount = round(float(amount), 2)
4 
5    def __add__(self, other):
6        if isinstance(other, Rupee):
7            return Rupee(self.amount + other.amount)
8        elif isinstance(other, (int, float)):
9            return Rupee(self.amount + other)
10        return NotImplemented
11 
12    def __radd__(self, other):
13        return self.__add__(other)
14 
15    def __lt__(self, other):
16        if isinstance(other, Rupee):
17            return self.amount < other.amount
18        return self.amount < other
19 
20    def __repr__(self):
21        return f"₹{self.amount:,.2f}"
22 
23wallet1 = Rupee(450.50)
24wallet2 = Rupee(120.00)
25total = wallet1 + wallet2
26augmented = 50 + wallet1
27 
28print("Total Wallet:", total)
29print("Augmented with raw number:", augmented)
30print("Is wallet2 < wallet1?", wallet2 < wallet1)

Expected Output

1Total Wallet: ₹570.50
2Augmented with raw number: ₹500.50
3Is wallet2 < wallet1? True

Interactive Quiz• Knowledge Check

Practice Quiz

1.

What should a binary operator dunder method like __add__(self, other) return when it encounters an unsupported type for other? A. raise TypeError B. raise NotImplementedError C. return NotImplemented D. return None

Answer: C

Explanation:Returning the singleton NotImplemented signals the Python runtime to attempt the operation using the right-hand operand's reflected method (__radd__). Raising an error immediately halts evaluation.

2.

Given the expression result = 10 + custom_obj, where 10 is an int that does not know how to add custom_obj, which method is invoked on custom_obj? A. custom_obj.__add__(10) B. custom_obj.__radd__(10) C. custom_obj.__iadd__(10) D. custom_obj.__call__(10)

Answer: B

Explanation:When the left operand fails or returns NotImplemented, Python attempts the reflected (reverse) operator method on the right operand, which is __radd__.

3.

What critical value must an in-place operator like __iadd__(self, other) return when mutating a mutable object? A. None B. True C. self D. The previous value of self

Answer: C

Explanation:In Python, the statement a += b assigns the return value of __iadd__ back to a. If __iadd__ returns None (or omits a return statement), a is reassigned to None.

4.

Which standard library decorator allows a class defining only __eq__ and __lt__ to automatically support all six rich comparison operators (<=, >, >=, !=)? A. @functools.lru_cache B. @functools.total_ordering C. @dataclasses.dataclass D. @operator.rich_comparison

Answer: B

Explanation:@functools.total_ordering takes a class that defines __eq__ and any one of __lt__, __le__, __gt__, or __ge__, and programmatically supplies the remaining comparison methods.

5.

Which operator corresponds to the special method __matmul__(self, other) introduced in Python 3.5? A. Regular matrix exponentiation (**) B. Matrix multiplication (@) C. Bitwise AND (&) D. Decorator application (@property)

Answer: B

Explanation:The @ binary operator was introduced in Python 3.5 (PEP 465) specifically for matrix multiplication and corresponds to the __matmul__ and __rmatmul__ dunder methods.

🚀 What's Next?

In the next lesson, we will continue your advanced Python journey with Customizing Classes with Magic Methods (2: Magic Methods & Operator Overloading).

👉 Continue to Next Lesson: Customizing Classes with Magic Methods →

Next Lesson

Customizing Classes with Magic Methods

Continue learning with hands-on practice, examples, and exercises in the upcoming topic.

Related Lessons

Previous Lesson	Next Lesson
__str__, __repr__, __len__	Customizing Classes with Magic Methods

Practice Quiz

Test your understanding of this lesson with 5 questions. Each question has one correct answer.

Previous Next

PreviousPrevNext

MSK Institute • Shikohabad

Loading Page Content...

Preparing courses, live labs, and learning resources.सामग्री लोड हो रही है, कृपया प्रतीक्षा करें...

Connecting serverPlease wait...

💻 Practical Labs🚀 Free Demo📜 Verified Certificates

Customizing Classes with Magic Methods

Operator Overloading in Python

Advanced10 min read•Updated: 2026-10-01

Study Materials Cheatsheet

Operator Overloading

Through operator overloading, your custom classes can behave as intuitive, first-class mathematical entities, domain models, or fluent query builders.

1. The Operator Dispatch Architecture & `NotImplemented`

When Python encounters a binary expression like a + b, it dispatches the operation through a multi-stage protocol:

                            Expression: a + b
                                    │
                                    ▼
                    Try: type(a).__add__(a, b)
                                    │
                 ┌──────────────────┴──────────────────┐
                 ▼                                     ▼
    Returns a Valid Result                   Returns NotImplemented
    (Operation finishes)                               │
                                                       ▼
                                           Try: type(b).__radd__(b, a)
                                                       │
                                    ┌──────────────────┴──────────────────┐
                                    ▼                                     ▼
                       Returns a Valid Result                   Returns NotImplemented
                       (Operation finishes)                               │
                                                                          ▼
                                                                Raise TypeError:
                                                    unsupported operand type(s) for +

The Difference: `NotImplemented` vs `NotImplementedError`

Returning NotImplemented: Tells the Python runtime, "I don't know how to handle this operand. Please check the right-hand operand's reflected method (e.g., __radd__) or fallback comparison."
Raising NotImplementedError: Immediately terminates the expression with an uncaught exception, preventing the other operand from handling the operation.

2. Arithmetic and Reflected Operators

Arithmetic operators come in two primary flavors: normal (left-hand) and reflected/reverse (right-hand, prefixed with r).

Operator	Left-hand Method	Reflected Method	In-place Method
`+`	`__add__(self, other)`	`__radd__(self, other)`	`__iadd__(self, other)`
`-`	`__sub__(self, other)`	`__rsub__(self, other)`	`__isub__(self, other)`
`*`	`__mul__(self, other)`	`__rmul__(self, other)`	`__imul__(self, other)`
`/`	`__truediv__(self, other)`	`__rtruediv__(self, other)`	`__itruediv__(self, other)`
`//`	`__floordiv__(self, other)`	`__rfloordiv__(self, other)`	`__ifloordiv__(self, other)`
`%`	`__mod__(self, other)`	`__rmod__(self, other)`	`__imod__(self, other)`
`**`	`__pow__(self, other)`	`__rpow__(self, other)`	`__ipow__(self, other)`
`@`	`__matmul__(self, other)`	`__rmatmul__(self, other)`	`__imatmul__(self, other)`

Implementing Arithmetic with Scalars and Objects

Visual Architecture & Process Flow

How data and code flow step-by-step

Flowchart

Step 1

def __init__

self, amount: float, currency: str = "USD"

Step 2

None:

3. In-Place Augmented Assignment (`+=`, `-=`, `*=`)

When you define methods like __iadd__, Python invokes them during a += b.

Mutable objects (like list): __iadd__ modifies self in-place and returns self.
Immutable objects (like int, str): If __iadd__ is omitted, Python falls back to a = a + b, allocating a new instance.

1class MutableVector:
2    def __init__(self, x: float, y: float) -> None:
3        self.x = x
4        self.y = y
5 
6    def __iadd__(self, other: "MutableVector") -> "MutableVector":
7        """Mutates the existing vector in place."""
8        if not isinstance(other, MutableVector):
9            return NotImplemented
10        self.x += other.x
11        self.y += other.y
12        return self  # CRITICAL: Always return self for in-place methods
13 
14    def __repr__(self) -> str:
15        return f"MutableVector({self.x}, {self.y})"
16 
17vec = MutableVector(10, 20)
18old_id = id(vec)
19vec += MutableVector(5, 5)
20 
21print("Updated vector:", vec)
22print(f"Preserved exact memory identity: {id(vec) == old_id}")  # True

4. Rich Comparison Operators and `total_ordering`

Python defines 6 rich comparison dunder methods:

Comparison	Method
`==`	`__eq__(self, other)`
`!=`	`__ne__(self, other)`
`<`	`__lt__(self, other)`
`<=`	`__le__(self, other)`
`>`	`__gt__(self, other)`
`>=`	`__ge__(self, other)`

Visual Architecture & Process Flow

How data and code flow step-by-step

Flowchart

Step 1

def __init__

self, hostname: str, cpu_cores: int, ram_gb: int

Step 2

None:

5. Summary and Architectural Rules

1
Always return NotImplemented on unknown operand types: This allows Python to query the other operand or produce clear, standardized error messages.
2
In-place methods must return self: Failing to return self from __iadd__ will cause variables using += to silently become None.
3
Use total_ordering cautiously in performance-critical paths: While @functools.total_ordering saves boilerplate, explicit implementations of comparison methods execute slightly faster by avoiding dynamic method wrapper lookups.

⚠️ Common Advanced Mistakes & Gotchas

1. In-Place Mutation in Binary Operators

Binary arithmetic operators like __add__(self, other) must return a new instance rather than mutating self. Mutating self violates mathematical immutability expectations.

2. Forgetting Reflected Operators (`radd`)

💻 Try It Yourself: Overloading Currency Addition and Comparison

Scenario

Build a Rupee monetary class that supports addition with another Rupee instance or integer, proper string representation, and comparison operators.

Complete Solution

1class Rupee:
2    def __init__(self, amount: float):
3        self.amount = round(float(amount), 2)
4 
5    def __add__(self, other):
6        if isinstance(other, Rupee):
7            return Rupee(self.amount + other.amount)
8        elif isinstance(other, (int, float)):
9            return Rupee(self.amount + other)
10        return NotImplemented
11 
12    def __radd__(self, other):
13        return self.__add__(other)
14 
15    def __lt__(self, other):
16        if isinstance(other, Rupee):
17            return self.amount < other.amount
18        return self.amount < other
19 
20    def __repr__(self):
21        return f"₹{self.amount:,.2f}"
22 
23wallet1 = Rupee(450.50)
24wallet2 = Rupee(120.00)
25total = wallet1 + wallet2
26augmented = 50 + wallet1
27 
28print("Total Wallet:", total)
29print("Augmented with raw number:", augmented)
30print("Is wallet2 < wallet1?", wallet2 < wallet1)

Expected Output

1Total Wallet: ₹570.50
2Augmented with raw number: ₹500.50
3Is wallet2 < wallet1? True

Interactive Quiz• Knowledge Check

Practice Quiz

1.

Answer: C

2.

Answer: B

Explanation:When the left operand fails or returns NotImplemented, Python attempts the reflected (reverse) operator method on the right operand, which is __radd__.

3.

What critical value must an in-place operator like __iadd__(self, other) return when mutating a mutable object? A. None B. True C. self D. The previous value of self

Answer: C

Explanation:In Python, the statement a += b assigns the return value of __iadd__ back to a. If __iadd__ returns None (or omits a return statement), a is reassigned to None.

4.

Answer: B

Explanation:@functools.total_ordering takes a class that defines __eq__ and any one of __lt__, __le__, __gt__, or __ge__, and programmatically supplies the remaining comparison methods.

5.

Answer: B

Explanation:The @ binary operator was introduced in Python 3.5 (PEP 465) specifically for matrix multiplication and corresponds to the __matmul__ and __rmatmul__ dunder methods.

🚀 What's Next?

In the next lesson, we will continue your advanced Python journey with Customizing Classes with Magic Methods (2: Magic Methods & Operator Overloading).

👉 Continue to Next Lesson: Customizing Classes with Magic Methods →

Next Lesson

Customizing Classes with Magic Methods

Continue learning with hands-on practice, examples, and exercises in the upcoming topic.

Related Lessons

Previous Lesson	Next Lesson
__str__, __repr__, __len__	Customizing Classes with Magic Methods

Practice Quiz

Test your understanding of this lesson with 5 questions. Each question has one correct answer.

Previous Next

Operator Overloading

1. The Operator Dispatch Architecture & NotImplemented

The Difference: NotImplemented vs NotImplementedError

2. Arithmetic and Reflected Operators

Implementing Arithmetic with Scalars and Objects

Visual Architecture & Process Flow

3. In-Place Augmented Assignment (+=, -=, *=)

4. Rich Comparison Operators and total_ordering

Visual Architecture & Process Flow

5. Summary and Architectural Rules

⚠️ Common Advanced Mistakes & Gotchas

1. In-Place Mutation in Binary Operators

2. Forgetting Reflected Operators (__radd__)

💻 Try It Yourself: Overloading Currency Addition and Comparison

Scenario

Complete Solution

Expected Output

Practice Quiz

1.

2.

3.

4.

5.

🚀 What's Next?

Customizing Classes with Magic Methods

Related Lessons

Practice Quiz

Loading Page Content...

Operator Overloading

1. The Operator Dispatch Architecture & NotImplemented

The Difference: NotImplemented vs NotImplementedError

2. Arithmetic and Reflected Operators

Implementing Arithmetic with Scalars and Objects

Visual Architecture & Process Flow

3. In-Place Augmented Assignment (+=, -=, *=)

4. Rich Comparison Operators and total_ordering

Visual Architecture & Process Flow

5. Summary and Architectural Rules

⚠️ Common Advanced Mistakes & Gotchas

1. In-Place Mutation in Binary Operators

2. Forgetting Reflected Operators (__radd__)

💻 Try It Yourself: Overloading Currency Addition and Comparison

Scenario

Complete Solution

Expected Output

Practice Quiz

1.

2.

3.

4.

5.

🚀 What's Next?

Customizing Classes with Magic Methods

Related Lessons

Practice Quiz

1. The Operator Dispatch Architecture & `NotImplemented`

The Difference: `NotImplemented` vs `NotImplementedError`

3. In-Place Augmented Assignment (`+=`, `-=`, `*=`)

4. Rich Comparison Operators and `total_ordering`

2. Forgetting Reflected Operators (`radd`)

1. The Operator Dispatch Architecture & `NotImplemented`

The Difference: `NotImplemented` vs `NotImplementedError`

3. In-Place Augmented Assignment (`+=`, `-=`, `*=`)

4. Rich Comparison Operators and `total_ordering`

2. Forgetting Reflected Operators (`radd`)