Python __floordiv__ Method
Last modified November 17, 2026 Python 3.15
The // operator calls __floordiv__ on its
left operand and __rfloordiv__ on the right when needed. A custom
numeric type should follow Python's rounding rules, return
NotImplemented for unknown types, and document what it returns.
This article covers the dispatch, the reflected hook, result types, and
negative operands.
How // calls __floordiv__
a // b is evaluated as
type(a).__floordiv__(a, b). The hook receives the right operand
directly and may inspect its type. Returning NotImplemented gives
the other operand a chance to handle the operation.
class Number:
def __init__(self, value):
self.value = value
def __floordiv__(self, other):
print("__floordiv__ called")
if isinstance(other, Number):
return Number(self.value // other.value)
if isinstance(other, (int, float)):
return Number(self.value // other)
return NotImplemented
def __repr__(self):
return f"Number({self.value})"
a = Number(10)
b = Number(3)
print(a // b)
print(a // 4)
print(Number.__floordiv__(a, b))
The class accepts another Number or a plain number and
returns a new Number. The direct type-level call gives the same
result, confirming the dispatch. The printed messages show how many times the
hook runs.
$ python basic_floordiv.py __floordiv__ called Number(3) __floordiv__ called Number(2) __floordiv__ called Number(3)
Returning NotImplemented
For an unrecognised right operand, return
NotImplemented instead of raising. Python then tries
__rfloordiv__ on the right operand and raises
TypeError only if neither side supports the operation.
class Number:
def __init__(self, value):
self.value = value
def __floordiv__(self, other):
if isinstance(other, Number):
return Number(self.value // other.value)
return NotImplemented
def __repr__(self):
return f"Number({self.value})"
class Reflected:
def __init__(self, value):
self.value = value
def __rfloordiv__(self, other):
print("Reflected.__rfloordiv__ called")
return other.value // self.value
print(Number(10) // Reflected(3))
try:
Number(10) // "3"
except TypeError as e:
print(type(e).__name__, e)
The Reflected object supplies
__rfloordiv__, so Number(10) // Reflected(3) succeeds
even though Number does not recognise it. Dividing by a string
fails with the usual TypeError.
$ python notimplemented.py Reflected.__rfloordiv__ called 3 TypeError unsupported operand type(s) for //: 'Number' and 'str'
The reflected __rfloordiv__
The reflected hook implements the operation with the operands swapped. It is called when the left operand does not support division by the right one, which is common for built-in numbers on the left and a custom type on the right.
class Fraction:
def __init__(self, n, d):
self.n = n
self.d = d
def __floordiv__(self, other):
if isinstance(other, Fraction):
return (self.n * other.d) // (self.d * other.n)
if isinstance(other, (int, float)):
return self.n // (self.d * other)
return NotImplemented
def __rfloordiv__(self, other):
if isinstance(other, (int, float)):
return (other * self.d) // self.n
return NotImplemented
half = Fraction(1, 2)
print(10 // half)
print(half // 0.1)
print(half // Fraction(3, 4))
10 // half calls
half.__rfloordiv__(10), because int does not know
about Fraction. The other two lines use the forward hook,
including one with a float divisor; the results follow ordinary numeric
rules.
$ python reflected.py 20 4.0 0
Choosing the result type
The hook may return a scalar when dividing two like quantities and
a new instance when dividing by a plain number. Adding __repr__
makes such results readable.
class Distance:
def __init__(self, meters):
self.meters = meters
def __floordiv__(self, other):
if isinstance(other, Distance):
return self.meters // other.meters
if isinstance(other, (int, float)):
return Distance(self.meters // other)
return NotImplemented
def __repr__(self):
return f"Distance({self.meters})"
d = Distance(100)
print(d // Distance(30))
print(d // 4)
Dividing two distances gives how many times one fits into the
other, so the result is an integer. Dividing by a number keeps the unit, so
the result is a new Distance. Document this choice for users of
the class.
$ python result_types.py 3 Distance(25)
Domain-specific division
Nothing requires the result to be a number of the same kind. A
container or a domain object can define its own meaning for //,
provided the behaviour is documented.
class TimeSlot:
def __init__(self, minutes):
self.minutes = minutes
def __floordiv__(self, other):
if isinstance(other, TimeSlot):
return self.minutes // other.minutes
if isinstance(other, int):
size = self.minutes // other
return [TimeSlot(size) for _ in range(other)]
return NotImplemented
def __repr__(self):
return f"TimeSlot({self.minutes})"
meeting = TimeSlot(90)
print(meeting // 3)
print(meeting // TimeSlot(30))
Dividing a slot by an integer returns a list of equal slots, while
dividing by another slot returns the count. The __repr__ method
gives a clear output instead of memory addresses.
$ python timeslots.py [TimeSlot(30), TimeSlot(30), TimeSlot(30)] 3
Negative operands and zero
Python's floor division rounds toward negative infinity, so the
result for negative operands differs from truncation toward zero. A zero
divisor raises ZeroDivisionError, as with built-in numbers.
class Signed:
def __init__(self, value):
self.value = value
def __floordiv__(self, other):
if isinstance(other, Signed):
other = other.value
return self.value // other
def __repr__(self):
return f"Signed({self.value})"
a = Signed(-7)
print(a // 3)
print(a // -3)
try:
a // 0
except ZeroDivisionError as e:
print(type(e).__name__, e)
-7 // 3 is -3, not -2, and
-7 // -3 is 2. A custom type that delegates to
// inherits these rules automatically, and also inherits the
error for a zero divisor.
$ python negative.py -3 2 ZeroDivisionError division by zero
Best practices
A floor-division hook should feel like the built-in operator:
- Return
NotImplementedfor unsupported operand types. - Implement
__rfloordiv__so the type works on the right of//. - Follow Python's floor semantics and leave zero-division errors intact.
- Decide and document whether the result is a scalar or a new instance.
- Note that
//does not use__divmod__; implement__floordiv__explicitly.
Source
object.__floordiv__ - Python documentation
object.__rfloordiv__ - Python documentation
Emulating numeric types - Python documentation
In this article we have implemented the __floordiv__
method. We have covered the // dispatch,
NotImplemented, the reflected hook, result types, and negative
operands. For related topics, see
Python __divmod__ method,
Python __mod__ method, and
Python __truediv__ method.
Author
List all Python tutorials.