Fluent Python - Chapter 1

Why Special Methods?

The advantage of using special methods (dunder methods) boils down to one word: Protocols.

Unified Interface

Users don’t need to learn a new API for your specific class. If they want to know the size of your object, they use len(). If they want to print it, they use print().

• Without Special Methods: my_matrix.get_rows(), my_matrix.display_string().
• With Special Methods: len(my_matrix), str(my_matrix).

Leveraging the Standard Library

This is arguably the biggest win. By implementing just two methods, __len__ and __getitem__, your object suddenly becomes compatible with hundreds of existing Python functions.

• Sorting: sorted(your_object) just works.
• Randomization: random.choice(your_object) works instantly.
• Iteration: for item in your_object: and list(your_object) work without writing a loop.

Efficient Internal Implementation

The Python interpreter often skips the method lookup for built-in types. When you call len(x) on a built-in list, Python doesn’t look up a method; it reads a field directly from a C struct.

More Use Cases

Mathematical Protocols: __abs__, __add__, and __mul__

Implementing these methods fulfills the Numeric Protocol, allowing custom objects to behave like native numbers.

• __add__ and __mul__ enable infix operators (+, *), turning verbose calls like v1.add(v2) into clean math: v1 + v2. To support commutativity (e.g., 3 * v as well as v * 3), you must also implement __rmul__.

• __abs__ binds the built-in abs() function to a physical meaning, ensuring your class integrates seamlessly with Python’s mathematical ecosystem.

String Representation: __repr__ vs __str__ and !r

This pair separates debugging from displaying.

• __repr__ is for developers; it should be unambiguous and ideally look like the code needed to recreate the object (Vector(3, 4)).
• __str__ is for end-users, focusing on readability ((3, 4)).
• The !r converter in f-strings forces the use of an attribute’s __repr__, preserving type clarity (e.g., distinguishing the string '4' from the integer 4).

Truthiness: __bool__ or __len__

Python determines an object’s “truthiness” via __bool__, falling back to __len__ if the former is missing (where a length of zero is False).

Collection API

Most collections are built on three “top-level” interfaces that define basic behavior:

• Iterable: Enables for loops via __iter__.
• Sized: Enables len() via __len__.
• Container: Enables the in operator via __contains__.

From these, Python derives specialized categories for different data organization needs:

• Sequence: Ordered data with integer indexing (e.g., list, tuple, str).
• Mapping: Key-value associations for fast lookups (e.g., dict).
• Set: Unordered, unique elements for membership testing (e.g., set, frozenset).

Overview of Special Methods

To provide a comprehensive view of the Python Data Model, here is a combined reference table organizing the special methods from the provided charts by their functional categories.

Category	Method Names	Related Operators/Symbols
String / Bytes Representation	__repr__, __str__, __format__, __bytes__, __fspath__	repr(), str(), format(), f-strings, bytes()
Conversion to Number	__bool__, __complex__, __int__, __float__, __hash__, __index__	bool(), complex(), int(), float(), hash(), bin()
Arithmetic	__add__, __sub__, __mul__, __truediv__, __floordiv__, __mod__, __matmul__, __divmod__, __pow__, __round__	+, -, *, /, //, %, @, divmod(), **, round()
Reversed Arithmetic	__radd__, __rsub__, __rmul__, __rtruediv__, __rfloordiv__, __rmod__, __rmatmul__, __rdivmod__, __rpow__	Swapped operands (e.g., 3 + obj)
Augmented Assignment	__iadd__, __isub__, __imul__, __itruediv__, __ifloordiv__, __imod__, __imatmul__, __ipow__	+=, -=, *=, /=, //=, %=, @=, **=
Rich Comparison	__lt__, __le__, __eq__, __ne__, __gt__, __ge__	<, <=, ==, !=, >, >=
Unary Numeric	__neg__, __pos__, __abs__	-, +, abs()
Emulating Collections	__len__, __getitem__, __setitem__, __delitem__, __contains__	len(), obj[i], del obj[i], in
Iteration	__iter__, __aiter__, __next__, __anext__, __reversed__	for, async for, next(), reversed()
Bitwise	__and__, __or__, __xor__, __lshift__, __rshift__, __invert__ (plus their __r and __i variants)	&, |, ^, <<, >>, ~
Attribute Management	__getattr__, __getattribute__, __setattr__, __delattr__, __dir__	obj.attr, setattr(), delattr(), dir()
Context Management	__enter__, __exit__, __aenter__, __aexit__	with, async with
Instance Creation / Destruction	__new__, __init__, __del__	Object instantiation and garbage collection
Callable / Coroutine	__call__, __await__	obj(), await obj
Class Metaprogramming	__prepare__, __init_subclass__, __class_getitem__, __mro_entries__	Metaclasses and generic types
Abstract Base Classes	__instancecheck__, __subclasscheck__	isinstance(), issubclass()