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

[Barry Warsaw]

On Aug 15, 2014, at 04:15 AM, Steven D'Aprano wrote:

>> Here's a taste of what that looks like:
>>     class SimpleEquation(object):
>> 
>>         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
>>             """
>>             return a * b * c
>
>I really dislike that syntax. I dislike adding cruft like "@type" and
>":param" into docstrings, which should be written for human readers, not
>linters.

For me, the whole point of using syntax like this is for the human reader,
especially because I don't have a linter that parses this... yet. <wink>  Used
judiciously, this syntax could benefit both the human reader *and* automated
tools.

>I dislike that you have documented that self is a SimpleEquation. (What else
>could it be?)

FWIW, I never document 'self'.

>I dislike that the syntax clashes with ReST syntax.

It needn't.  http://epydoc.sourceforge.net/manual-fields.html

>I dislike that it isn't obvious to me why the first parameter uses @type
>while the second parameter uses :param.

It needn't.

>I like the annotation syntax. I'm not completely convinced that the mypy
>syntax is mature enough to bless, but the basic idea of type annotations is
>pretty common in dozens of languages. I think you are in a tiny minority if
>you think that putting the type declaration right next to the parameter make
>it *less* clear that putting the type declaration in a completely different
>part of the code.

Of course, it's not a completely different part of the code.  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.

Plus, you can *always* fit these reST-ish epydoc field descriptions in PEP 8
line lengths.  It always bugs me to see multiline function signatures.
Currently those are pretty rare (and IMHO are a code smell), but with type
annotations, I suspect they'll be the norm.

Cheers,
-Barry
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 819 bytes
Desc: not available
URL: <http://mail.python.org/pipermail/python-ideas/attachments/20140815/6665bd3b/attachment.sig>