[issue38333] add type signatures to library function docs

[paul rubin]

paul rubin <phr-pythonbugs at nightsong.com> added the comment:

abs takes any value that understands the __abs__ method and returns something of the same type.  In fact there is already a type protocol for it:

https://mypy.readthedocs.io/en/stable/protocols.html#supportsabs-t

So abs's signature would be (x : Abs[T]) -> T where T is a type parameter.  

I'm sure there are some examples where no good signature is possible, but lots of others are fine.  Someone did a Smalltalk study long ago and found that most functions were monomorphic in practice even though Smalltalk is dynamically typed like Python.  As a matter of style, Python code tends to be typed even when it doesn't have to be.  Not all the time of course.

I'm still getting used to types and mypy (I was a py2 holdout til quite recently, and mypy has been a more attractive reason to change than any of the other stuff) and I do keep noticing cases that don't work as I hoped, but it's still a good move in general.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue38333>
_______________________________________