Document that float // float returns a float

[mdickinson]

PEP 238 states clearly that the result of x // y is a float, when x and y both have type float.

For floating point inputs, the result is a float. For example:

3.5//2.0 == 1.0

And indeed this is the behaviour that's been in place since Python 2.2. However, we seem to be missing a clear statement of this in the official docs. It would be good to fix that.

Motivated by the thread https://discuss.python.org/t/make-float-floordiv-and-rfloordiv-return-an-int/24959, where it's been asserted that this behaviour is an 'implementation detail'.

Linked PRs

• gh-102823: Document return type of floor division on floats #102824
• [3.12] gh-102823: Document return type of floor division on floats (GH-102824) #109092
• [3.11] gh-102823: Document return type of floor division on floats (GH-102824) #109093

[rhettinger]

+1

Note that Decimal(n) // Decimal(d) returns a Decimal, so it is consistent about returning the input type.

While you're at it, perhaps take a look at the docstring in numbers.py because it could be taken to mean that the built-in floor function is called and would return an int. I think the second sentence should be expressed in English rather that with Python expressions that aren't actually used. We want to communicate the concept of floor division rather that suggesting that it is literally floor(self/other) which is inaccurate.

    @abstractmethod
    def __floordiv__(self, other):
        """self // other: The floor() of self/other."""
        raise NotImplementedError

[skirpichev]

Also note that Decimal(n) // Decimal(d) returns a float.

IOW, a Decimal.

[hugovk]

Fixed via #102824 and backports to 3.11, thanks!