Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Python __radd__: Reverse Addition Explained

Understand Python's __radd__ method: when it's called, how to implement it, and common pitfalls when overloading addition for custom types.

~4 min readPython
#dunder methods#operator overloading#Python internals#numeric types
Diagram showing two objects and the plus operator with a reversed arrow indicating the __radd__ method call

When you write a + b in Python, the interpreter does not simply add two values. It first attempts a.__add__(b). If a does not define __add__, or if that method returns NotImplemented, Python then tries b.__radd__(a). This reverse addition method is what allows your custom class to participate in addition even when it appears on the right-hand side of the operator. Understanding __radd__ is essential for building numeric types, vector classes, or any object that should behave like a number.

When Python Calls radd

The dispatch mechanism for the + operator follows a fixed order in the general case. For an expression left + right, Python first checks left.__add__(right). If that method is absent or returns NotImplemented, Python then checks right.__radd__(left). The reverse method is called with the left operand as its argument. This is why __radd__ is often described as the "reflected" or "reverse" addition.

Consider a simple example. Suppose you have a class Number that defines __radd__ but not __add__. When you write 2 + Number(3), Python first tries (2).__add__(Number(3)), which returns NotImplemented because the built-in int does not know how to handle a Number instance. Python then calls Number(3).__radd__(2), which can return a meaningful result.

A Minimal radd Implementation

Here is a basic implementation of __radd__ for a custom numeric wrapper:

python
class Number: def __init__(self, value): self.value = value def __radd__(self, other): return Number(self.value + other) def __repr__(self): return f"Number({self.value})"

Now you can write:

python
result = 5 + Number(3) print(result) # Number(8)

Note that __radd__ receives the left operand (other) and returns a new object or a value. In this example, it returns a Number instance, preserving the type. Defining only __radd__ lets 5 + Number(3) work. If you also want Number(3) + 5 to work when Number is on the left, define __add__ as well; like any reflected method, __radd__ is only consulted after the left operand has failed.

Returning NotImplemented vs Raising TypeError

A common mistake is to raise TypeError directly from __radd__ when the operation is not supported. The correct approach is to return the special value NotImplemented. This tells Python that this method cannot handle the operation; if no other method in the dispatch chain handles it, Python will raise a TypeError with the standard unsupported-operand message.

python
class Number: def __radd__(self, other): if isinstance(other, (int, float)): return Number(self.value + other) return NotImplemented

Returning NotImplemented instead of raising an exception lets the operator dispatch work correctly. For __add__, returning NotImplemented is the signal for Python to try the right operand's __radd__. For __radd__, returning NotImplemented tells Python that the reflected attempt did not handle the operation; if no other overload succeeds, Python raises the standard TypeError. It also makes your class cooperate better with subclasses and multiple dispatch.

Interaction with Subclasses and Type Hierarchies

The order of method resolution changes when subclasses are involved. Python gives priority to the subclass's implementation over the base class's. If the subclass is on the right side, its __radd__ can be called before the base class's __add__; if it is on the left side, its __add__ is called first. This rule prevents a base class from silently overriding a subclass's behavior.

Consider this scenario:

python
class Base: def __add__(self, other): return "Base add" def __radd__(self, other): return "Base radd" class Sub(Base): def __add__(self, other): return "Sub add" def __radd__(self, other): return "Sub radd"

When you evaluate Base() + Sub(), Python calls Sub.__radd__ before Base.__add__ because Sub is a subclass of Base. The result is "Sub radd". This behavior is defined in the Python data model and is important to remember when designing class hierarchies.

Practical Use: Custom Numeric Types

A realistic use case for __radd__ is building a class that represents a measurement with units. For instance, a Distance class that stores meters should support adding a plain number (interpreted as meters) from either side.

python
class Distance: def __init__(self, meters): self.meters = meters def __add__(self, other): if isinstance(other, Distance): return Distance(self.meters + other.meters) if isinstance(other, (int, float)): return Distance(self.meters + other) return NotImplemented def __radd__(self, other): return self.__add__(other)

Here, __radd__ simply delegates to __add__ because addition is commutative for this type. This pattern is common and avoids duplicating logic. However, if your operation is not commutative, you must implement __radd__ separately to handle the reversed operand order.

Common Pitfalls and Edge Cases

One pitfall is forgetting that, for unrelated types, __radd__ is only called when the left operand's __add__ fails. If your class defines __add__ but it returns NotImplemented for certain types, __radd__ will be invoked only if the right operand supports it. If neither returns a valid result, Python raises TypeError.

Another edge case involves mutation. A + implementation should normally return a new object rather than mutate its operands; the same applies to __radd__, whose self is the right operand. If __radd__ mutates self, then 10 + obj changes obj as a side effect. For augmented assignment, total += value first tries total.__iadd__(value); if that is missing or returns NotImplemented, it falls back to the ordinary + operation, which tries total.__add__(value) and then value.__radd__(total) as needed. Returning NotImplemented is still the correct way to decline unsupported operand types.

Design and Maintainability Considerations

Implementing __radd__ correctly requires thinking about type contracts and the semantics of your operation. For commutative operations, delegating to __add__ keeps the code DRY. For non-commutative operations, you must carefully document which operand is which. Overloading operators can make code more readable, but it also adds a layer of indirection that can confuse maintainers if the behavior is not intuitive. Always include docstrings and type hints to clarify the expected types and return values.

Performance is rarely a concern with __radd__ itself, but the dispatch mechanism involves a few extra attribute lookups. In performance-critical loops, you might prefer explicit method calls over operator overloading. However, for most application code, the readability benefits outweigh the negligible overhead. The key is to ensure that your __radd__ returns NotImplemented quickly for unsupported types, avoiding expensive type checks or conversions that could slow down the common path.

Try matching browser tools

All tools

Small utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Python guides

More in Python

All Python guides

The guides filed next to this one in Python, in library order.