Python __truediv__: Implementing True Division
Learn how to implement Python's __truediv__ method to control true division behavior in custom classes, handle edge cases, and integrate with operator overloading.

The __truediv__ method controls how the / operator behaves on your objects. In Python 3, / is true division. For two integers, it returns a float; for custom classes, __truediv__ controls what / returns. To support / on your instances, define __truediv__, or rely on a reflected __rtruediv__ on the other operand. Without either, using / raises TypeError when no other method handles the operation. This article explains how to implement __truediv__ correctly, handle edge cases, and understand its interaction with other division operators.
What Is truediv and Why It Matters
Python's operator dispatch for arithmetic operations relies on special methods. When you write a / b, Python looks for type(a).__truediv__(a, b) first. If that method is not defined or returns NotImplemented, it tries the reflected method __rtruediv__ on type(b). For built-in numeric types, these methods are already implemented. For custom classes, you need to define __truediv__ to make instances compatible with /.
Understanding __truediv__ is essential when you build numeric types, vector classes, or domain-specific objects that should behave like a number. A well-designed implementation gives you control over the result type, precision, and error handling.
Implementing truediv in a Custom Class
To implement true division, define a method named __truediv__ that accepts one argument (the divisor) and returns the result. The simplest implementation assumes both operands are of the same class and returns a new instance of that class:
class Quantity:
def __init__(self, value):
self.value = value
def __truediv__(self, other):
return Quantity(self.value / other.value)This works when other is also a Quantity. If you want to divide by a plain number, you need to check the type of other and handle it accordingly:
class Quantity:
def __init__(self, value):
self.value = value
def __truediv__(self, other):
if isinstance(other, Quantity):
return Quantity(self.value / other.value)
if isinstance(other, (int, float)):
return Quantity(self.value / other)
return NotImplementedReturning NotImplemented tells Python to try the reflected operation on the right operand. This is a common pattern that makes your class interoperable with other numeric types.
Handling Division by Zero and Type Errors
Division by zero raises ZeroDivisionError automatically when the divisor is zero. You can let that propagate, or you can catch it and raise a more domain-specific error. The important part is to not silently return a meaningless value.
Type errors are more subtle. If other is an incompatible type, returning NotImplemented is better than raising TypeError immediately, because it gives Python a chance to call __rtruediv__ on the other operand. If no method handles the operation, Python raises TypeError with a message like "unsupported operand type(s) for /: 'Quantity' and 'str'".
Consider this example:
class Vector:
def __init__(self, x, y):
self.x = x
self.y = y
def __truediv__(self, scalar):
if isinstance(scalar, (int, float)):
return Vector(self.x / scalar, self.y / scalar)
return NotImplementedIf you divide a Vector by a string, __truediv__ returns NotImplemented, and Python eventually raises a TypeError. This is the correct behavior.
How truediv Interacts with Other Division Methods
Python has two division operators: / (true division) and // (floor division). They are controlled by __truediv__ and __floordiv__ respectively. For each, there is a reflected version: __rtruediv__ and __rfloordiv__. The reflected methods are called when the left operand does not support the operation but the right operand does.
Here is a summary of the dispatch order for a / b:
| Order | Method Called | Condition |
|---|---|---|
| 1 | type(a).__truediv__(a, b) | a has the method |
| 2 | type(b).__rtruediv__(b, a) | a returned NotImplemented or lacks the method |
This interaction matters when you define both __truediv__ and __rtruediv__ in a class that appears on either side of the operator. For example, if you want 5 / vector to work, you must define __rtruediv__ on the vector class, because int does not know how to divide by a vector.
Performance and Operational Considerations
Implementing __truediv__ adds a Python-level method call to every division operation. For performance-critical numeric code, this overhead can be significant. If you are building a numeric type that is used in tight loops, consider using __slots__ to reduce memory and attribute lookup time, or delegate to built-in types internally. For instance, a wrapper around float can simply call float.__truediv__ on the underlying value.
Another operational concern is precision. In Python 3, the default / behavior for integer operands returns a float, which may lose precision for very large integers or exact rational values. If your domain requires exact arithmetic, return a Fraction or Decimal from __truediv__ instead. This changes the result type, so ensure your class's contract is clear to users.
Using truediv with Operator Overloading in Realistic Scenarios
In practice, you rarely implement __truediv__ in isolation. A complete numeric type typically defines several arithmetic special methods: __add__, __sub__, __mul__, __truediv__, and possibly their reflected counterparts. The key is to keep the result type consistent and handle edge cases explicitly.
Consider a ScaledValue class that represents a value with a unit. Division by a scalar should produce a new ScaledValue with the same unit, while division by another ScaledValue might produce a plain number (the ratio). The implementation must decide which behavior is appropriate for the domain.
class ScaledValue:
def __init__(self, magnitude, unit):
self.magnitude = magnitude
self.unit = unit
def __truediv__(self, other):
if isinstance(other, ScaledValue):
if self.unit != other.unit:
raise ValueError("Cannot divide values with different units")
return self.magnitude / other.magnitude
if isinstance(other, (int, float)):
return ScaledValue(self.magnitude / other, self.unit)
return NotImplementedThis example shows how __truediv__ can enforce domain rules (unit compatibility) while still supporting scalar division. The method returns different types depending on the operand, which is a deliberate design choice. Documenting these behaviors is crucial for maintainability.
A final consideration is the reflected method. If you want scalar / scaled_value to work, you must define __rtruediv__ on ScaledValue. That method should handle the case where the left operand is a number and the right operand is a ScaledValue. Without it, the operation fails even though a mathematically valid result exists. Defining both methods makes your class robust and intuitive to use.
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.