Python OOP — Operator Overloading

The Story That Explains Operator Overloading ➕Operator Overloading समझाने वाली कहानी ➕一个讲清运算符重载的故事 ➕

Here is the story as real code. The last two lines call the dunder methods directly — and give the same answers:

यही कहानी असली code में। आख़िरी दो lines dunder methods को सीधे बुलाती हैं — और वही जवाब देती हैं:

下面是这个故事的真实代码。最后两行直接调用 dunder 方法 — 结果完全相同：

from datetime import date, timedelta

print(5 + 3)
print("hello" + "world")
print([1, 2] + [3, 4])
print(date(2026, 1, 1) + timedelta(days=7))

# The same calls, written as dunder methods
print((5).__add__(3))            # brackets needed: 5.__add__ is a SyntaxError
print("hello".__add__("world"))

How + Becomes a Method Call 🔁+ एक Method Call कैसे बनता है 🔁+ 如何变成一次方法调用 🔁

Every time Python sees a + b, it does not magically know how to add. It looks up a.__add__(b) and runs it. Built-in types already have these methods. For your own class, you write them.

जब भी Python a + b देखता है, उसे जादू से जोड़ना नहीं आता। वह a.__add__(b) ढूँढ़ता है और उसे चलाता है। Built-in types में ये methods पहले से हैं। अपनी class के लिए आप इन्हें लिखते हैं।

每当 Python 看到 a + b，它并不会凭空知道怎么相加。它查找 a.__add__(b) 并运行它。内置类型已经有这些方法；对于你自己的类，由你来编写。

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

    # -- Define what + means for two Vectors --
    def __add__(self, other):
        return Vector(self.x + other.x, self.y + other.y)

    # -- Define how a Vector prints --
    def __repr__(self):
        return f"Vector({self.x}, {self.y})"


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

# These two lines are IDENTICAL to Python
print(v1 + v2)             # Vector(6, 8)
print(v1.__add__(v2))      # Vector(6, 8)   <- same call under the hood

Arithmetic Operators 🧮Arithmetic Operators 🧮算术运算符 🧮

Each common arithmetic operator has a matching dunder. Define only the ones you need — no rule says every class must support every operator.

हर आम arithmetic operator का एक मिलता-जुलता dunder है। सिर्फ़ वही define करें जो चाहिए — कोई नियम नहीं कहता कि हर class हर operator सँभाले।

每个常用算术运算符都有对应的 dunder。只定义你需要的 — 没有规定每个类都必须支持所有运算符。

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

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

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

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

    def __mul__(self, scalar):
        # Scalar multiplication: Vector * number
        return Vector(self.x * scalar, self.y * scalar)

    def __neg__(self):
        return Vector(-self.x, -self.y)

    def __abs__(self):
        # Magnitude - Euclidean length
        return (self.x ** 2 + self.y ** 2) ** 0.5


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

print(v1 + v2)     # Vector(4, 6)
print(v1 - v2)     # Vector(2, 2)
print(v1 * 3)      # Vector(9, 12)
print(-v1)         # Vector(-3, -4)
print(abs(v1))     # 5.0  (magnitude of a 3-4-5 triangle)

🎯 Simulator: Vector Playground🎯 Simulator: Vector Playground🎯 模拟器：向量游乐场

Drag the heads of a and b on the grid. Every expression on the right runs a different dunder of the complete Vector class from Section 08. Checked against Python on 400 random cases.

Grid पर a और b के सिरों को खींचिए। दाईं ओर का हर expression Section 08 की पूरी Vector class का एक अलग dunder चलाता है। 400 random cases पर Python से जाँचा गया।

在网格上拖动 a 和 b 的箭头。右侧每个表达式都会运行第 08 节完整 Vector 类中的一个不同 dunder。已在 400 个随机用例上与 Python 对照。

Comparison Operators ⚖️Comparison Operators ⚖️比较运算符 ⚖️

The six comparison operators map one-to-one to dunder methods. If you define __eq__, Python works out != for you. Define __lt__ and __eq__, add @functools.total_ordering, and you get the other comparisons for free.

छह comparison operators सीधे dunder methods से जुड़े हैं। __eq__ define करें तो Python != ख़ुद निकाल लेता है। __lt__ और __eq__ define करें, @functools.total_ordering लगाएँ, और बाक़ी comparisons मुफ़्त मिलते हैं।

六个比较运算符与 dunder 方法一一对应。定义了 __eq__，Python 会自动推出 !=。定义 __lt__ 和 __eq__，再加上 @functools.total_ordering，其余比较就免费得到了。

from functools import total_ordering

@total_ordering                       # fills in <=, >, >= from __lt__ + __eq__
class Vector:
    def __init__(self, x, y):
        self.x, self.y = x, y

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

    def __abs__(self):
        return (self.x ** 2 + self.y ** 2) ** 0.5

    # -- Two vectors are equal if both components match --
    def __eq__(self, other):
        if not isinstance(other, Vector):
            return NotImplemented
        return self.x == other.x and self.y == other.y

    # -- Order by magnitude --
    def __lt__(self, other):
        if not isinstance(other, Vector):
            return NotImplemented
        return abs(self) < abs(other)


a = Vector(3, 4)   # magnitude 5
b = Vector(3, 4)   # magnitude 5 - equal
c = Vector(6, 8)   # magnitude 10

print(a == b)          # True
print(a != c)          # True   (Python derives this from __eq__)
print(a < c)           # True   (magnitude 5 < 10)
print(a >= b)          # True   (@total_ordering filled this in)

# Because __lt__ exists, sorted() works
print(sorted([c, a, Vector(0, 1)]))

__str__ vs __repr__ — Customising Display 🪞__str__ बनाम __repr__ — Display बदलना 🪞__str__ vs __repr__ — 自定义显示 🪞

These two dunders control how your object is shown. They serve different readers: __str__ is for end users (used by print() and str()); __repr__ is for developers (used by repr(), the interactive prompt, debuggers and error messages). If you define only one, define __repr__ — str() falls back to it automatically.

ये दो dunders तय करते हैं कि आपका object कैसा दिखेगा। ये अलग पाठकों के लिए हैं: __str__ end users के लिए (print() और str() इस्तेमाल करते हैं); __repr__ developers के लिए (repr(), interactive prompt, debuggers और error messages)। अगर एक ही define करें, तो __repr__ करें — str() अपने आप उस पर लौट आता है।

这两个 dunder 控制对象如何显示，面向不同的读者：__str__ 面向最终用户（print() 和 str() 使用它）；__repr__ 面向开发者（repr()、交互式提示符、调试器和错误信息使用它）。如果只定义一个，就定义 __repr__ — str() 会自动退回使用它。

class Money:
    def __init__(self, amount, currency="USD"):
        self.amount   = amount
        self.currency = currency

    # -- Developer-facing: clear, ideally could rebuild the object --
    def __repr__(self):
        return f"Money({self.amount!r}, {self.currency!r})"

    # -- End-user-facing: pretty, readable --
    def __str__(self):
        return f"{self.currency} {self.amount:,.2f}"


m = Money(1234.5, "INR")

print(m)            # INR 1,234.50            <- calls __str__
print(str(m))       # INR 1,234.50            <- calls __str__
print(repr(m))      # Money(1234.5, 'INR')    <- calls __repr__

# Inside a list, print shows each item's repr - that's why it looks "debuggy"
print([m])          # [Money(1234.5, 'INR')]

🪞 Simulator: str / repr Mirror🪞 Simulator: str / repr Mirror🪞 模拟器：str / repr 镜子

Keep both methods, or remove one. Six ways of showing the same object tell you which method Python picked. Try 0.1 + 0.2: __str__ rounds it nicely, __repr__ shows the exact float. All 30 combinations are real Python outputs (memory addresses shortened to 0x7f…).

दोनों methods रखिए, या एक हटाइए। एक ही object को दिखाने के छह तरीक़े बताते हैं कि Python ने कौन-सा method चुना। 0.1 + 0.2 आज़माइए: __str__ इसे सुंदर तरह से round करता है, __repr__ असली float दिखाता है। सभी 30 combinations असली Python outputs हैं (memory addresses को 0x7f… तक छोटा किया गया)।

保留两个方法，或删掉其中一个。用六种方式显示同一个对象，看看 Python 选了哪个方法。试试 0.1 + 0.2：__str__ 会漂亮地四舍五入，__repr__ 显示精确的浮点数。全部 30 种组合都是真实的 Python 输出（内存地址缩写为 0x7f…）。

Reflected Operators — Your Object on the Right 🔄Reflected Operators — आपका Object दाईं ओर 🔄反射运算符 — 你的对象在右边 🔄

Think about 4 * v. Python first tries int.__mul__(4, v). int has no idea what a Vector is, so it returns NotImplemented. Then Python asks the right-hand object: "do you have a reflected version of this operator?" That is __rmul__. Every arithmetic operator has an r-version for exactly this case.

4 * v के बारे में सोचिए। Python पहले int.__mul__(4, v) आज़माता है। int को पता नहीं कि Vector क्या है, इसलिए वह NotImplemented लौटाता है। फिर Python दाईं ओर वाले object से पूछता है: "क्या तुम्हारे पास इस operator का reflected version है?" वह __rmul__ है। हर arithmetic operator का ठीक इसी काम के लिए एक r-version होता है।

想想 4 * v。Python 先尝试 int.__mul__(4, v)。int 不知道 Vector 是什么，于是返回 NotImplemented。接着 Python 问 右边 的对象："你有这个运算符的 反射 版本吗？"那就是 __rmul__。每个算术运算符都有一个 r 版本，正是为这种情况准备的。

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

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

    def __mul__(self, scalar):
        print("  [__mul__ called]")
        return Vector(self.x * scalar, self.y * scalar)

    def __rmul__(self, scalar):
        # Called when the vector is on the RIGHT of the *
        print("  [__rmul__ called]")
        return self.__mul__(scalar)


v = Vector(2, 3)

print(v * 4)              # uses __mul__ -> Vector(8, 12)
print()
print(4 * v)              # uses __rmul__ -> Vector(8, 12)

🔬 Simulator: Dispatch Lab🔬 Simulator: Dispatch Lab🔬 模拟器：分派实验室

Pick a left operand, an operator and a right operand. Watch Python ask the left side, then the right side, then give up. It uses the complete Vector class (Section 08) or the Money class (Section 09). Every one of the 221 results was checked against the real operator.

बायाँ operand, operator और दायाँ operand चुनिए। देखिए Python पहले बाईं ओर से पूछता है, फिर दाईं ओर से, फिर हार मान लेता है। इसमें पूरी Vector class (Section 08) या Money class (Section 09) है। सभी 221 नतीजे असली operator से जाँचे गए।

选择左操作数、运算符和右操作数。观察 Python 先问左边、再问右边、最后放弃的过程。它使用完整的 Vector 类（第 08 节）或 Money 类（第 09 节）。全部 221 个结果都已与真实运算符核对。

In-place Operators — +=, -=, *= ♻️In-place Operators — +=, -=, *= ♻️原地运算符 — +=、-=、*= ♻️

When you write v += w, Python first tries v.__iadd__(w). If the class has no __iadd__, Python falls back to v = v + w. The difference matters: an in-place operator should change the object itself and return self. Immutable classes (like Money or a math Vector) should not define these — the fallback makes a new object, which is the right behaviour for them.

जब आप v += w लिखते हैं, Python पहले v.__iadd__(w) आज़माता है। अगर class में __iadd__ नहीं है, तो Python v = v + w पर लौट आता है। यह फ़र्क़ अहम है: in-place operator को object को ही बदलना चाहिए और return self करना चाहिए। Immutable classes (जैसे Money या गणित वाला Vector) को ये define नहीं करने चाहिए — fallback नया object बनाता है, जो उनके लिए सही व्यवहार है।

当你写 v += w 时，Python 先尝试 v.__iadd__(w)。如果类里没有 __iadd__，Python 退回到 v = v + w。区别很重要：原地运算符应该 修改对象本身 并 return self。不可变的类（如 Money 或数学上的 Vector）不 应定义这些方法 — 退回机制会创建新对象，这对它们才是正确的行为。

class Playlist:
    """Mutable - in-place operations modify self."""
    def __init__(self, songs=None):
        self.songs = songs or []

    def __repr__(self):
        return f"Playlist({self.songs})"

    def __iadd__(self, song):
        # Mutate in place, return self
        self.songs.append(song)
        return self


mix = Playlist(["Track 1"])
mix += "Track 2"                # calls __iadd__
mix += "Track 3"
print(mix)                      # Playlist(['Track 1', 'Track 2', 'Track 3'])

♻️ Simulator: In-place Lab♻️ Simulator: In-place Lab♻️ 模拟器：原地运算实验室

Two names, mix and alias, start on the same playlist. Step through three versions of the class and watch where each name points after +=. Every step is recorded from a real run.

दो नाम, mix और alias, एक ही playlist से शुरू होते हैं। Class के तीन versions में क़दम-दर-क़दम चलिए और देखिए += के बाद हर नाम कहाँ इशारा करता है। हर क़दम असली run से रिकॉर्ड है।

两个名字 mix 和 alias 一开始指向同一个播放列表。逐步运行类的三个版本，观察 += 之后每个名字指向哪里。每一步都来自真实运行的记录。

Complete Practical Example — Vector Class 📐पूरा Practical Example — Vector Class 📐完整实战示例 — Vector 类 📐

Everything together: arithmetic, the reflected __rmul__, unary operators, comparisons with @total_ordering, and __hash__ so vectors work in sets.

सब कुछ एक साथ: arithmetic, reflected __rmul__, unary operators, @total_ordering के साथ comparisons, और __hash__ ताकि vectors sets में चल सकें।

全部放在一起：算术运算、反射的 __rmul__、一元运算符、配合 @total_ordering 的比较，以及让向量能放进集合的 __hash__。

from functools import total_ordering


@total_ordering
class Vector:
    """An immutable 2D vector with a full operator suite."""

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

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

    # -- Arithmetic ------------------------------------------
    def __add__(self, other):
        if isinstance(other, Vector):
            return Vector(self.x + other.x, self.y + other.y)
        return NotImplemented

    def __sub__(self, other):
        if isinstance(other, Vector):
            return Vector(self.x - other.x, self.y - other.y)
        return NotImplemented

    def __mul__(self, scalar):
        if isinstance(scalar, (int, float)):
            return Vector(self.x * scalar, self.y * scalar)
        return NotImplemented

    def __rmul__(self, scalar):
        # Handles: number * Vector
        return self.__mul__(scalar)

    def __truediv__(self, scalar):
        if isinstance(scalar, (int, float)):
            return Vector(self.x / scalar, self.y / scalar)
        return NotImplemented

    # -- Unary -----------------------------------------------
    def __neg__(self):
        return Vector(-self.x, -self.y)

    def __abs__(self):
        # Euclidean magnitude
        return (self.x ** 2 + self.y ** 2) ** 0.5

    # -- Comparison (total_ordering fills the rest from these two) --
    def __eq__(self, other):
        if not isinstance(other, Vector):
            return NotImplemented
        return self.x == other.x and self.y == other.y

    def __lt__(self, other):
        # Compare by magnitude
        if not isinstance(other, Vector):
            return NotImplemented
        return abs(self) < abs(other)

    # -- Hashable, so it works in sets/dicts (immutable class) --
    def __hash__(self):
        return hash((self.x, self.y))


# -- Every operator you defined is now usable --------------
v1 = Vector(3, 4)
v2 = Vector(1, 2)

print(v1 + v2)      # Vector(4, 6)
print(v1 - v2)      # Vector(2, 2)
print(v1 * 3)       # Vector(9, 12)
print(3 * v1)       # Vector(9, 12)   <- via __rmul__
print(v1 / 2)       # Vector(1.5, 2.0)
print(-v1)          # Vector(-3, -4)
print(abs(v1))      # 5.0

print(v1 == Vector(3, 4))     # True
print(v1 > v2)                # True (magnitude 5 > magnitude ~2.24)

# Sortable - because __lt__ is defined
vectors = [Vector(6, 8), v1, v2, Vector(0, 1)]
print(sorted(vectors))

# Hashable - usable in sets and dicts
print({Vector(1, 2), Vector(1, 2), Vector(3, 4)})   # duplicates removed

Complete Practical Example — Money Class 💰पूरा Practical Example — Money Class 💰完整实战示例 — Money 类 💰

Money reads like plain numbers, but every operation checks the currency first. Try it in the Dispatch Lab (Section 06): switch to Money and pick m1 + m3 or m1 < m3.

Money सादे नंबरों जैसा पढ़ा जाता है, पर हर operation पहले currency जाँचता है। Dispatch Lab (Section 06) में आज़माइए: Money चुनिए और m1 + m3 या m1 < m3 लीजिए।

Money 读起来就像普通数字，但每个运算都会先检查货币。到分派实验室（第 06 节）里试试：切换到 Money，选择 m1 + m3 或 m1 < m3。

class Money:
    """Immutable currency-aware amount."""

    def __init__(self, amount, currency="USD"):
        self.amount   = float(amount)
        self.currency = currency

    # -- Display ---------------------------------------------
    def __repr__(self):
        return f"Money({self.amount!r}, {self.currency!r})"

    def __str__(self):
        return f"{self.currency} {self.amount:,.2f}"

    # -- Same-currency arithmetic ----------------------------
    def _check_currency(self, other):
        if self.currency != other.currency:
            raise ValueError(
                f"Cannot combine {self.currency} and {other.currency} directly"
            )

    def __add__(self, other):
        if isinstance(other, Money):
            self._check_currency(other)
            return Money(self.amount + other.amount, self.currency)
        return NotImplemented

    def __sub__(self, other):
        if isinstance(other, Money):
            self._check_currency(other)
            return Money(self.amount - other.amount, self.currency)
        return NotImplemented

    # -- Scalar multiplication (interest, tax, discount) -----
    def __mul__(self, factor):
        if isinstance(factor, (int, float)):
            return Money(self.amount * factor, self.currency)
        return NotImplemented

    def __rmul__(self, factor):
        return self.__mul__(factor)

    # -- Comparison - only within the same currency ----------
    def __eq__(self, other):
        if not isinstance(other, Money):
            return NotImplemented
        return self.amount == other.amount and self.currency == other.currency

    def __lt__(self, other):
        if not isinstance(other, Money):
            return NotImplemented
        self._check_currency(other)
        return self.amount < other.amount


# -- Use it naturally, like a built-in numeric type --------
salary = Money(50000, "INR")
bonus  = Money(10000, "INR")
rent   = Money(15000, "INR")

total     = salary + bonus                # uses __add__
remaining = total - rent                  # uses __sub__
with_tax  = remaining * 1.05              # uses __mul__
with_tax2 = 1.05 * remaining              # uses __rmul__ (same result)

print("Total:     ", total)         # INR 60,000.00
print("Remaining: ", remaining)     # INR 45,000.00
print("With tax:  ", with_tax)      # INR 47,250.00

print("Equal? ", with_tax == with_tax2)   # True
print("Bonus < Rent?", bonus < rent)      # True

# Adding two currencies is caught at the arithmetic layer
try:
    Money(100, "USD") + Money(100, "INR")
except ValueError as e:
    print("Blocked:", e)

Operator → Dunder Reference 📋Operator → Dunder Reference 📋运算符 → Dunder 速查表 📋

Rows marked upcoming tutorial are listed here for completeness; they get their own lessons later.

आने वाला tutorial वाली rows यहाँ पूरी सूची के लिए हैं; उनके अपने पाठ बाद में आएँगे।

标有 后续教程 的行只是为了完整列出；它们会在之后的课程中单独讲解。

Common Mistakes (and Fixes) 🩹आम ग़लतियाँ (और उनके हल) 🩹常见错误（及修正）🩹

🩺 Simulator: Bug Doctor🩺 Simulator: Bug Doctor🩺 模拟器：Bug 医生

Six of these mistakes, run for real. Buggy code on the left, fixed code on the right, changed lines marked.

इनमें से छह ग़लतियाँ, असली run में। बाईं ओर buggy code, दाईं ओर ठीक किया हुआ, बदली lines चिह्नित।

其中六个错误的真实运行。左边是有 bug 的代码，右边是修正后的代码，改动的行已标出。

Golden Rules and Quiz 🏆सुनहरे नियम और Quiz 🏆黄金法则与小测验 🏆

Quick Quiz — 8 Questionsछोटा Quiz — 8 सवाल小测验 — 8 道题