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.

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:
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:
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.
class Number:
def __radd__(self, other):
if isinstance(other, (int, float)):
return Number(self.value + other)
return NotImplementedReturning 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:
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.
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 toolsSmall utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Python guides
All Python guidesPython iter(): How the Built-in Function Works
Explains Python's iter() built-in: how it creates iterators, the two-argument sentinel form, custom iterator classes, and common edge cases.
Python Pika: Queues, Exchanges, Routing Keys, and Acknowledgements
Learn how to use Python's Pika client with RabbitMQ: declare queues and exchanges, publish with routing keys, consume messages, and handle acknowledgements reliably.
Python Kafka: kafka-python vs Confluent Client
python kafka python vs confluent kafka: Compare kafka-python and Confluent Kafka Python clients: API differences, performance, feature coverage, and when to choose eac...
Python Kafka Offsets, Partitions, and Manual Commits
Learn how Kafka offsets and partitions work and how to manually commit offsets in Python consumers with kafka-python and confluent-kafka. Covers sync vs async commits, rebalances, and seeking.
More in Python
All Python guidesThe guides filed next to this one in Python, in library order.