[Python-ideas] Proposal: Use mypy syntax for function annotations

[Brett Cannon]

On Sat Aug 16 2014 at 1:05:16 AM Steven D'Aprano <steve at pearwood.info>
wrote:

> Some people like the epydoc-style convention of putting type annotations
> in docstrings:
>
> [...]
> > >>         def demo(self, a, b, c):
> > >>             """
> > >>             This function returns the product of a, b and c
> > >>             @type self: SimpleEquation
> > >>             :param a: int - The first number
> > >>             :param b: int
> > >>             :param c: int - The third number should not be zero and
> should
> > >> also
> > >>                 only be -1 if you enjoy carrots (this comment spans 2
> lines)
> > >>             :return: int
> > >>             """
>
> One issue I haven't see raised is that annotations are available at
> runtime, whereas docstrings may not be. (The -OO switch removes
> docstrings.) A linter may be able to parse the docstrings at compile
> time before the docstrings are discarded, or it may not, but using
> docstrings means the information is not always available for
> introspection at runtime. I think that's a major disadvantage.
>
> Although I admit I don't always remember to test my code using -O and
> -OO, I do try very hard to do this and I have found bugs in my code from
> doing so. I think anything which makes testing -O and -OO modes harder
> is a bad thing.
>
> [Quoting Barry Warsaw]
> > docstrings
> > naturally live right after the function signature (indeed, or it
> wouldn't get
> > stuffed into __doc__), so it's always close to the source.  That makes it
> > quite easy for the third party human reader, but also for the author to
> keep
> > up-to-date.
>
> *Close to the source* is not the same as *part of the source*. In the
> example above, the difference is as high as eight lines, compared to
> zero:
>
>     # Function annotations
>     def demo(self, a:int, b:int, c:int)->int:
>
>
> Using docstring annotations splits the information about parameters into
> two places. Those two places might be close, but there are still two
> sources of ultimate truth instead of one. You have the name of the
> parameter in the parameter list, and the type of the parameter inside
> the docstring separated by some arbitrary number of lines of code.
>

I'm with Steven on this. I actively hate docstrings that list every
parameter, their expected interface, etc. The parameter list exists for a
reason and a majority of the time I don't need an explanation of what a
parameter does. In those rare instances where I need clarification I can
write a quick sentence in the docstring explaining the special case.

"""Returns the product of a, b, and c.

The 'c' parameter should not be zero. If you like carrots, set it to -1
(this comment spans two lines).
"""

That's 4 lines compared to 7 (which was missing a blank line to begin with
so it really should be 8). We're all adults and properly worded parameter
names tell you a lot. What we are trying to do here is help programmatic
tools know things that we know to be true.

Now that is not to say whatever comes out of typing.py shouldn't be legible
and not noisy. I'm sure the reason it uses CapWords for e.g. Dict is so you
can do `from typing import *` which makes `def demo(a: Int, b: Int, c: Int)
-> Int` read just as cleanly as if you used 'int' itself (this might become
the one time I promote using import * so enjoy it while you can =).

And as others have pointed out, if you really like the docstring approach
you can always set up a decorator to do the translation for you, but you
can't go the other way from annotation to docstring when examining source.
So while you can promote and use your docstring approach and even argue for
the inclusion of such a decorator in typing.py, you can't promote
docstrings exclusively without completely cutting off the function
annotation approach. And I think enough of us like the function annotation
approach that cutting it off entirely isn't acceptable.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-ideas/attachments/20140816/82ce28f6/attachment.html>