I have looked at PEP 3141, the history of the documentation in question, and the documentation of the functions in the “math” module. It seems that trunc(), floor() and ceil() were all intended to return a numbers.Integral type, but then PEP 3141’s floor() and ceil() were reverted from Python 2 due to compatibility concerns, where they only accept and return float objects. So it would be correct to clarify that Integral means numbers.Integral.

The term “integral float” was added by revision 94eeaeeb3ce9, to mean a Python float() object that represents an integer. This is correct (but hard to understand) for Python 2, but the change is not appropriate for Python 3, where floor() and ceil() follow PEP 3141 instead and do return integers (numbers.Integral).

I propose to just point to the proper math.trunc(), round() etc documentation and remove the table (originally added in revision 4f9723d9ca32). Julien: do you think the definitions in <https://docs.python.org/3.5/library/math.html#number-theoretic-and-representation-functions> are understandable?

Also I noticed Python 3’s floor() and ceil() doc strings say int not numbers.Integral. That should probably also be fixed.

Julien, if you agree with my suggestion, do you still want to do a patch for this? Otherwise, I could have a go when I get a chance.