ZetCode

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.

basic_floordiv.py
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.

notimplemented.py
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.

reflected.py
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.

result_types.py
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.

timeslots.py
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.

negative.py
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:

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

I am Jan Bodnar, a programmer and technical writer. I have been writing programming tutorials at ZetCode since 2007 and have published eight e-books. See about the author.

List all Python tutorials.