Reading the documentation

[Peter Otten]

Stefan Ram wrote:

>   This is a transcript:
> 
>>>> from math import floor
>>>> floor( "2.3" )
> Traceback (most recent call last):
>   File "<stdin>", line 1, in <module>
> TypeError: must be real number, not str
>>>> help(floor)
> Help on built-in function floor in module math:
> 
> floor(...)
>     floor(x)
> 
>     Return the floor of x as an Integral.
>     This is the largest integer <= x.
> 
>   Is the output of »help(floor)« supposed to be a kind of
>   normative documentation, i.e., /the/ authoritative
>   documentation of »floor«?

You should consult the documentation

https://docs.python.org/dev/library/math.html#math.floor

which has usually more details. The docstring (i. e. what help() shows) is 
most helpful when you already have an idea about what a function does.

>   Is there any hint in the documentation about the type
>   expected of arguments in a call?

Yes. Everything that features a __floor__() method:

>>> import math
>>> class Foo:
...     def __floor__(self): return "yadda"
... 
>>> math.floor(Foo())
'yadda'

So the current implementation doesn't even mandate an int as the result...

>   Is a parameter name »x« (as used above) described
>   somewhere to express the requirement of a real number?
> 
>   It seems, »real« means »int or float«. Is this meaning
>   of »real« documented somewhere?

I don't know if there is something more direct than 

https://docs.python.org/dev/library/numbers.html

and the PEP linked from there.

> 
>   Thanks in advance!
>