Python Magic Methods: Make Objects Feel Built-in
What you’ll learn
Section titled “What you’ll learn”- What special (“magic” or “dunder”) methods are and how Python finds them.
- How to write
__repr__,__str__and__format__for objects that log and print well. - The
__eq__/__hash__contract and why defining one affects the other. - How binary operators dispatch through
NotImplementedand reflected methods such as__radd__. - Container protocols,
__new__,__call__, and the Python 3.14 changes toint()andNotImplemented.
Summary
Section titled “Summary”Special methods are methods with double-underscore names, such as __len__ or __add__, that Python calls implicitly to implement syntax and built-in functions: len(x) calls type(x).__len__(x), and a + b tries type(a).__add__(a, b). Defining them lets your classes work with operators, print(), f-strings, sorted(), in, for loops and with blocks. The mechanism is as old as Python’s classes and is current in Python 3.14, which removed two old fallbacks covered below.
The problem it solves
Section titled “The problem it solves”Without special methods, a class can only expose behavior through named methods, and every built-in treats it as an opaque object. In the OrdersPortal app, a Money class written that way logs as a memory address, needs .add() instead of +, and compares by identity.
The samples on this page are plain scripts: save each as a .py file and run it with python3 file.py. They were run on CPython 3.14.6 and the output shown is from that run.
from decimal import Decimal
class MoneyV1: def __init__(self, amount, currency): self.amount, self.currency = Decimal(amount), currency
def add(self, other): return MoneyV1(self.amount + other.amount, self.currency)
def to_string(self): return f"{self.amount:.2f} {self.currency}"
a = MoneyV1("19.99", "EUR")print(a) # default repr: useless in logsprint(a.add(MoneyV1("5.01", "EUR")).to_string())print(a == MoneyV1("19.99", "EUR")) # identity comparison by default
class Money: def __init__(self, amount, currency): self.amount, self.currency = Decimal(amount), currency
def __repr__(self): return f"Money({str(self.amount)!r}, {self.currency!r})"
def __str__(self): return f"{self.amount:.2f} {self.currency}"
def __eq__(self, other): if not isinstance(other, Money): return NotImplemented return (self.amount, self.currency) == (other.amount, other.currency)
def __hash__(self): return hash((self.amount, self.currency))
def __add__(self, other): if not isinstance(other, Money) or other.currency != self.currency: return NotImplemented return Money(self.amount + other.amount, self.currency)
b = Money("19.99", "EUR")print(repr(b), "|", b, "|", b + Money("5.01", "EUR"))print(b == Money("19.99", "EUR"), len({b, Money("19.99", "EUR")}))Output (the memory address varies):
<__main__.MoneyV1 object at 0x7f...>25.00 EURFalseMoney('19.99', 'EUR') | 19.99 EUR | 25.00 EURTrue 1The second class reads like a built-in type: readable logs, +, value equality and set membership.
How it works
Section titled “How it works”Lookup happens on the type
Section titled “Lookup happens on the type”For implicit calls, Python looks special methods up on the object’s type and skips the instance dictionary (and even __getattribute__). Assigning a special method to an instance therefore has no effect on built-ins:
# Special methods are looked up on the type, not the instance.class Cart: pass
cart = Cart()cart.__len__ = lambda: 3try: len(cart)except TypeError as exc: print("TypeError:", exc)
# Defining __eq__ without __hash__ makes instances unhashable.class Sku: def __init__(self, code): self.code = code def __eq__(self, other): return isinstance(other, Sku) and self.code == other.code
print(Sku.__hash__)try: {Sku("SKU-1")}except TypeError as exc: print("TypeError:", exc)
# __str__ falls back to __repr__, not the other way round.class OnlyRepr: def __repr__(self): return "OnlyRepr()"class OnlyStr: def __str__(self): return "nice"print(str(OnlyRepr()), repr(OnlyStr()).startswith("<__main__.OnlyStr object"))
# Python 3.14: NotImplemented in a boolean context is a TypeError.try: if NotImplemented: passexcept TypeError as exc: print("TypeError:", exc)
# Python 3.14: int() no longer falls back to __trunc__.class Qty: def __trunc__(self): return 3try: int(Qty())except TypeError as exc: print("TypeError:", exc)Output:
TypeError: object of type 'Cart' has no len()NoneTypeError: cannot use 'Sku' as a set element (unhashable type: 'Sku')OnlyRepr() TrueTypeError: NotImplemented should not be used in a boolean contextTypeError: int() argument must be a string, a bytes-like object or a real number, not 'Qty'That one sample shows five rules worth memorizing:
- Define special methods on the class.
cart.__len__ = ...is ignored bylen(). __eq__without__hash__makes instances unhashable. Python sets__hash__toNoneso equal objects can never hash differently. If the object is immutable, define__hash__from the same fields that__eq__compares; if it is mutable, leave it unhashable.str()falls back to__repr__, not the other way round. Always write__repr__first; add__str__only when users need a different, friendlier text.- Python 3.14:
NotImplementedis not a boolean. Evaluating it in anifraised aDeprecationWarningsince Python 3.9 and is now aTypeError, which catches code that returned it from a helper and tested the result. - Python 3.14:
int()no longer uses__trunc__. Implement__int__or__index__for integer conversion.
The main families
Section titled “The main families”| Purpose | Methods | Triggered by |
|---|---|---|
| Creation | __new__, __init__ |
Cls(...) |
| Text | __repr__, __str__, __format__ |
repr(), str()/print(), f-strings and format() |
| Comparison | __eq__, __lt__, __le__, __gt__, __ge__, __ne__, __hash__ |
==, <, sorted(), set, dict keys |
| Truth and size | __bool__, __len__ |
if obj:, len() |
| Arithmetic | __add__, __radd__, __iadd__, __mul__, … |
+, +=, *, sum() |
| Containers | __iter__, __contains__, __getitem__, __setitem__ |
for, in, obj[key] |
| Calling | __call__ |
obj(...) |
| Context managers | __enter__, __exit__ |
with |
| Attributes | __getattr__, __getattribute__, __setattr__ |
Attribute access |
Operators and NotImplemented
Section titled “Operators and NotImplemented”For a + b, Python calls type(a).__add__(a, b). If that returns the singleton NotImplemented, and b is of a different type, Python tries type(b).__radd__(b, a). If the right operand’s type is a subclass of the left operand’s type and overrides the reflected method, the reflected method goes first. If nothing handles the pair, Python raises TypeError: unsupported operand type(s). Returning NotImplemented, rather than raising, is what lets another type step in.
Comparisons work the same way, with __lt__ and __gt__ as each other’s reflection. __ne__ inverts __eq__ by default, and == falls back to identity when both sides return NotImplemented. There is no other implied relationship: defining __lt__ and __eq__ does not give you <=. functools.total_ordering fills in the rest.
In-place operators (+=) call __iadd__ first and fall back to __add__; implement __iadd__ only for mutable types.
Realistic example
Section titled “Realistic example”OrdersPortal needs a Money value object that sums order totals, sorts, formats in reports, and refuses to mix currencies, plus an Order container that behaves like a read-only mapping of order lines.
from decimal import Decimal, ROUND_HALF_UPfrom functools import total_ordering
@total_orderingclass Money: __slots__ = ("amount", "currency")
def __init__(self, amount, currency="EUR"): self.amount = Decimal(amount).quantize(Decimal("0.01"), ROUND_HALF_UP) self.currency = currency
# Representation def __repr__(self): return f"Money('{self.amount}', '{self.currency}')"
def __str__(self): return f"{self.amount} {self.currency}"
def __format__(self, spec): # Delegate the numeric part to Decimal so f"{m:>10}" works. return f"{format(self.amount, spec or '')} {self.currency}"
# Equality, hashing, ordering def __eq__(self, other): if not isinstance(other, Money): return NotImplemented return (self.amount, self.currency) == (other.amount, other.currency)
def __hash__(self): return hash((self.amount, self.currency))
def __lt__(self, other): if not isinstance(other, Money) or other.currency != self.currency: return NotImplemented return self.amount < other.amount
# Arithmetic def __add__(self, other): if isinstance(other, Money) and other.currency == self.currency: return Money(self.amount + other.amount, self.currency) return NotImplemented
def __radd__(self, other): if other == 0: # lets sum() start from 0 return self return self.__add__(other)
def __mul__(self, qty): if isinstance(qty, int): return Money(self.amount * qty, self.currency) return NotImplemented
__rmul__ = __mul__
def __bool__(self): return self.amount != 0
class Order: def __init__(self, order_id, lines): self.order_id = order_id self._lines = dict(lines) # sku -> (qty, unit price)
def __repr__(self): return f"Order({self.order_id!r}, {len(self)} lines)"
def __len__(self): return len(self._lines)
def __iter__(self): return iter(self._lines.items())
def __contains__(self, sku): return sku in self._lines
def __getitem__(self, sku): return self._lines[sku]
@property def total(self): return sum(qty * price for _, (qty, price) in self)
order = Order("ORD-1001", { "SKU-KEYBOARD": (1, Money("49.90")), "SKU-CABLE": (3, Money("4.99")),})
print(order, "SKU-CABLE" in order, order["SKU-CABLE"])print(f"total: {order.total:>10}")print(sorted([Money("5"), Money("0.5"), Money("12")]))print(Money("49.90") >= Money("4.99"), bool(Money(0)))print(len({Money("1.0"), Money("1.00")}))try: Money("1", "EUR") + Money("1", "USD")except TypeError as exc: print("TypeError:", exc)try: Money("1") < Money("1", "USD")except TypeError as exc: print("TypeError:", exc)Output:
Order('ORD-1001', 2 lines) True (3, Money('4.99', 'EUR'))total: 64.87 EUR[Money('0.50', 'EUR'), Money('5.00', 'EUR'), Money('12.00', 'EUR')]True False1TypeError: unsupported operand type(s) for +: 'Money' and 'Money'TypeError: '<' not supported between instances of 'Money' and 'Money'Details that matter:
__radd__handles0 + Money(...), which is howsum()starts, sosum(...)works without astart=argument.__format__delegates the numeric part toDecimal, so width and alignment specs in f-strings work.Money("1.0")andMoney("1.00")compare equal and hash equal, so the set holds one element. Equal objects must always have equal hashes.- Mixing currencies returns
NotImplemented, and Python turns that into a clearTypeErrorinstead of a wrong total. Orderdefines__iter__,__contains__,__len__and__getitem__, sofor,in,len()and indexing all work, andtotalis computed through the class’s own iteration protocol.
__new__ and __call__
Section titled “__new__ and __call__”__new__ creates the object and __init__ initializes it. Override __new__ when the value must be fixed at creation, as with subclasses of immutable types such as str, int and tuple. __call__ makes an instance callable while it keeps state.
# __new__ creates the object; __init__ only initializes it.class OrderId(str): def __new__(cls, raw): value = raw.strip().upper() if not value.startswith("ORD-"): raise ValueError(f"not an order id: {raw!r}") return super().__new__(cls, value) # immutable: set the value here
oid = OrderId(" ord-1001 ")print(repr(oid), isinstance(oid, str), oid.endswith("1001"))
# __call__ makes an instance usable wherever a function is expected.class PercentOff: def __init__(self, percent): self.percent = percent self.calls = 0
def __call__(self, amount): self.calls += 1 return round(amount * (100 - self.percent) / 100, 2)
def __repr__(self): return f"PercentOff({self.percent})"
black_friday = PercentOff(20)print(list(map(black_friday, [49.90, 14.97])), black_friday.calls, callable(black_friday))Output:
'ORD-1001' True True[39.92, 11.98] 2 TrueA common singleton recipe caches one instance in __new__. It works, but Python still calls __init__ on the returned object every time the class is called, which can reset its state; a module-level instance or a factory function is simpler.
Common mistakes
Section titled “Common mistakes”- Raising
TypeErrorinstead of returningNotImplemented. Raising blocks the other operand’s reflected method. ReturnNotImplementedfor unsupported types and let Python raise. - Defining
__eq__and forgetting__hash__. Instances become unhashable. Defining__hash__on a mutable object is worse: changing a field after insertion “loses” the object in sets and dicts. - A
__repr__that hides the type or raises. Loggers and debuggers call it in error paths. Keep it cheap, never raise, and include the class name and key fields. - Assigning special methods to instances. They must be on the class.
- Implementing a few comparison methods and expecting the rest. Use
functools.total_orderingor define all four ordering methods. __bool__and__len__disagreeing.if obj:uses__bool__if present, otherwise__len__; make sure an empty container is falsy.- Relying on
__trunc__forint(). Python 3.14 removed that fallback.
When to use it and when not to
Section titled “When to use it and when not to”| Goal | Use special methods? | Better alternative |
|---|---|---|
| Value objects (money, quantities, IDs) | Yes: __repr__, __eq__, __hash__, arithmetic |
@dataclass(frozen=True) generates many for you |
| Custom containers | Yes: __len__, __iter__, __contains__, __getitem__ |
Inherit from collections.abc.Mapping or Sequence to get mixin methods |
| Plain records with no behavior | Rarely | @dataclass, NamedTuple |
Clever operator overloading (order >> warehouse) |
No | A named method that says what it does |
| Resource cleanup | __enter__/__exit__ |
contextlib.contextmanager for simple cases |
Compatibility
Section titled “Compatibility”Special methods exist in every Python 3 release. Recent changes: Python 3.14 makes NotImplemented in a boolean context a TypeError (deprecated since 3.9), stops int() from delegating to __trunc__, and lets three-argument pow() call __rpow__. functools.total_ordering has been available since Python 3.2.
Interview questions
Section titled “Interview questions”1. Why does obj.__len__ = lambda: 3 not make len(obj) work?
Implicit special method calls look up the method on type(obj), bypassing the instance dictionary and __getattribute__. This keeps lookups fast and avoids confusion between methods of a class and of its metaclass.
2. What is the difference between returning NotImplemented and raising NotImplementedError from __add__?
NotImplemented is a signal to the interpreter to try the other operand’s reflected method and, if that also fails, raise TypeError. NotImplementedError is an exception meant for abstract methods; raising it from __add__ stops dispatch immediately.
3. When must you define __hash__, and what must it satisfy?
When you define __eq__ and want instances in sets or as dict keys. Objects that compare equal must have equal hashes, and the hash must not change while the object is in a hash-based collection, so hash only immutable fields.
4. Senior scenario: OrdersPortal’s Money class supports + with plain floats, and finance reports small rounding drifts in invoice totals. How do you redesign it?
Store amounts as Decimal (or integer minor units) and quantize on construction. Make __add__ and __radd__ accept only Money of the same currency and return NotImplemented otherwise, with __radd__ special-casing 0 for sum(). Allow __mul__ only by int quantities, and make conversions explicit with named methods such as Money.from_float() that state their rounding. Make the class immutable with a consistent __eq__/__hash__, add property-based tests for associativity of addition, and log repr() values that include the currency.
Key takeaways
Section titled “Key takeaways”- Special methods connect your classes to operators, built-ins and statements; Python looks them up on the type.
- Write
__repr__first;str()falls back to it. - Define
__eq__and__hash__together, from the same immutable fields. - Return
NotImplementedfor unsupported operands so reflected methods and clear errors work. - Python 3.14 turns
NotImplementedin boolean context into aTypeErrorand dropsint()’s__trunc__fallback.
Related pages
Section titled “Related pages”- dataclasses: generated
__init__,__repr__,__eq__and ordering. - Context managers: the
__enter__/__exit__protocol in depth. - Descriptors:
__get__,__set__and__set_name__. - slots: compact value objects like
Money. - Metaclasses: special methods defined on classes of classes.
- Generators: the simplest way to implement
__iter__. - Operators: the operators these methods implement.