Skip to content

Python Magic Methods: Make Objects Feel Built-in

  • 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 NotImplemented and reflected methods such as __radd__.
  • Container protocols, __new__, __call__, and the Python 3.14 changes to int() and NotImplemented.

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.

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 logs
print(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 EUR
False
Money('19.99', 'EUR') | 19.99 EUR | 25.00 EUR
True 1

The second class reads like a built-in type: readable logs, +, value equality and set membership.

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: 3
try:
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:
pass
except TypeError as exc:
print("TypeError:", exc)
# Python 3.14: int() no longer falls back to __trunc__.
class Qty:
def __trunc__(self):
return 3
try:
int(Qty())
except TypeError as exc:
print("TypeError:", exc)

Output:

TypeError: object of type 'Cart' has no len()
None
TypeError: cannot use 'Sku' as a set element (unhashable type: 'Sku')
OnlyRepr() True
TypeError: NotImplemented should not be used in a boolean context
TypeError: 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 by len().
  • __eq__ without __hash__ makes instances unhashable. Python sets __hash__ to None so 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: NotImplemented is not a boolean. Evaluating it in an if raised a DeprecationWarning since Python 3.9 and is now a TypeError, 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.
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

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.

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_UP
from functools import total_ordering
@total_ordering
class 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 False
1
TypeError: unsupported operand type(s) for +: 'Money' and 'Money'
TypeError: '<' not supported between instances of 'Money' and 'Money'

Details that matter:

  • __radd__ handles 0 + Money(...), which is how sum() starts, so sum(...) works without a start= argument.
  • __format__ delegates the numeric part to Decimal, so width and alignment specs in f-strings work.
  • Money("1.0") and Money("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 clear TypeError instead of a wrong total.
  • Order defines __iter__, __contains__, __len__ and __getitem__, so for, in, len() and indexing all work, and total is computed through the class’s own iteration protocol.

__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 True

A 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.

  • Raising TypeError instead of returning NotImplemented. Raising blocks the other operand’s reflected method. Return NotImplemented for 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_ordering or 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__ for int(). Python 3.14 removed that fallback.
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

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.

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.

  • 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 NotImplemented for unsupported operands so reflected methods and clear errors work.
  • Python 3.14 turns NotImplemented in boolean context into a TypeError and drops int()’s __trunc__ fallback.
  • 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.