Python: Special (Dunder) Methods

What Are Dunder Methods?

Dunder is short for double underscore. Every method whose name is wrapped in double underscores, such as __init__ or __len__, is a dunder method. They are also called magic methods or special methods, though the Python documentation prefers "special methods."

You do not call these methods directly most of the time. Instead, Python calls them automatically in response to specific syntax or built-in function calls. When you writelen(my_obj), Python calls my_obj.__len__() behind the scenes. When you write a + b, Python calls a.__add__(b). This is what gives Python its clean, expressive syntax: everything is consistent because the same protocol applies to built-in types and to your own classes alike.

__init__ and __del__

__init__ is the initializer. Python calls it immediately after creating a new instance, passing any arguments you provided to the class call. Its job is to set up the object's initial state by assigning instance variables. Note that __init__does not create the object; that is handled by __new__, which you rarely need to override.

__del__ is the finalizer, called when an object is about to be garbage collected. It is the right place to release resources that Python's garbage collector cannot handle automatically, such as database connections or file locks. That said, keep __del__ as a last resort. Context managers (covered later) are the cleaner, more predictable way to manage resources.

__str__ and __repr__

Every object in Python has two string representations. __str__ is for end users: it should be readable and descriptive. __repr__ is for developers: it should be unambiguous, and ideally should be a valid Python expression that could recreate the object. When you call print(obj), Python uses __str__. When you inspect an object in the REPL or inside a list or dictionary, Python uses __repr__.

If you only define one, define __repr__. Python falls back to it for both purposes if __str__ is not defined.

__len__ and __getitem__

__len__ is called by the built-in len() function. It must return a non-negative integer. Implementing it also makes your object behave truthily in boolean contexts: an object with a length of zero is considered falsy (unless you also define__bool__, which takes precedence).

__getitem__ enables subscript access: obj[key]. When you implement both__len__ and __getitem__, Python gives you iteration support for free, without needing __iter__. Python will call __getitem__ with increasing integer indices starting from 0 until an IndexError is raised.

__setitem__ and __delitem__

These two complete the subscript interface. __setitem__ is triggered by assignment: obj[key] = value. __delitem__ is triggered by thedel statement: del obj[key]. Together with __getitem__, they let you build objects that feel exactly like dictionaries or lists from the outside, while storing or validating data however you choose internally.

__contains__ and the "in" Operator

The in membership operator calls __contains__. It should returnTrue or False. If you do not define __contains__ but you do define __iter__, Python falls back to iterating through all elements looking for a match. If you define neither, Python falls back to __getitem__. Defining __contains__ explicitly is best when you can provide a more efficient lookup than a full scan.

__iter__ and __next__

To make an object iterable (usable in a for loop, list(), tuple(), unpacking, etc.), you implement the iterator protocol. This requires two methods. __iter__ must return the iterator object itself. __next__must return the next value in the sequence, or raise StopIteration when there are no more values left.

A common pattern is to make the class both iterable and its own iterator by returning self from __iter__. Note that once an iterator is exhausted, it stays exhausted. If you need to restart from the beginning, you need a fresh instance.

__call__: Callable Objects

Defining __call__ lets you invoke an instance as if it were a function. This is useful when you need an object that behaves like a function but also needs to carry persistent state between calls. A common real-world use is building configurable function-like objects, counters, memoization wrappers, or machine learning models (PyTorch's nn.Module relies heavily on this).

You can check whether any object is callable with the built-incallable(obj) function, which returns True if the object has a__call__ method.

__enter__ and __exit__: Context Managers

The with statement is Python's standard way to handle setup and teardown around a block of code. To support it, your class needs two methods. __enter__ is called at the start of the with block; whatever it returns is bound to theas variable. __exit__ is called at the end, even if an exception occurs inside the block.

__exit__ receives three arguments: the exception type, the exception value, and the traceback. If no exception occurred, all three are None. If__exit__ returns a truthy value, the exception is suppressed. If it returnsNone or False, the exception propagates normally.

Comparison Dunder Methods

Python has six comparison operators, each backed by a dunder method: __eq__(==), __ne__ (!=), __lt__ (<), __le__ (<=),__gt__ (>), and __ge__ (>=). By default, __eq__ compares by identity (same as is). Overriding it lets you define what "equal" means for your class.

A useful shortcut: if you decorate your class with@functools.total_ordering, you only need to implement __eq__ and one of the ordering methods. Python derives the other four automatically.

Arithmetic Dunder Methods

The arithmetic operators are each tied to a dunder method: __add__ (+),__sub__ (-), __mul__ (*), and __truediv__ (/). There are also reflected variants like __radd__, which Python calls on the right operand when the left operand does not know how to handle the operation. And in-place variants like __iadd__ for +=.

A well-designed arithmetic dunder should return a new object of the same type, leaving self unchanged. This mirrors how Python's built-in numbers behave.

__hash__

__hash__ returns an integer that Python uses to place your object in a hash table. This is what allows objects to be used as dictionary keys or stored in sets. The hash value must be stable for the lifetime of the object, and two objects that compare equal with == must have the same hash value.

This last rule is why Python automatically sets __hash__ to Nonewhenever you define __eq__ without also defining __hash__. Objects in that state are no longer hashable. If you want them to be usable as dictionary keys, you need to explicitly define __hash__ to be consistent with__eq__.

__bool__

__bool__ determines the truthiness of an object in boolean contexts: if obj,while obj, not obj, and so on. It must return True or False. If __bool__ is not defined, Python falls back to __len__: an object with length zero is falsy. If neither is defined, the object is always truthy (since it exists and is not None).

__sizeof__

__sizeof__ returns the size of the object in bytes, not counting the memory consumed by objects it references. It is called by sys.getsizeof(), which adds the garbage collector overhead on top of what __sizeof__ returns. This is mostly used for profiling memory usage in performance-sensitive code.

You rarely need to override this. The default implementation from objectworks correctly for most classes. If you implement __slots__ or otherwise change how attributes are stored, overriding __sizeof__ gives you accurate size reporting.

Putting It All Together: A Full Example

The real power of dunder methods shows when you combine several of them. The class below implements a simple ordered bag (a collection that tracks how many times each item appears). It supports length, subscripting, iteration, membership testing, addition, truthiness, and clean string representations.

Quiz - Test Your Knowledge

Ten questions covering the full scope of Python's special methods. Some questions test the mechanics of specific dunders; others test the rules and interactions between them. Think carefully before selecting an answer.