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

[Donald Stufft]

> On Aug 16, 2014, at 1:16 AM, Steven D'Aprano <steve at pearwood.info> wrote:
> 
> On Fri, Aug 15, 2014 at 06:49:09PM -0400, Barry Warsaw wrote:
> 
>> Docstring annotations almost by definition can contain more information useful
>> to the human reader than type annotations can, especially if you carefully use
>> the reST-ish epydoc convention of both :param: and :type:.  The latter
>> contains the type annotation (which an automated system could utilize) while
>> the former contains the exposition (for the benefit of the human reader).
>> It's the explanations that are missing from any type annotations.
>> 
>> I suppose you could intersperse comments with your type annotations, resulting
>> in a long multiline function signature.  I doubt that would be a readability
>> improvement.
> 
> I'm sorry, I missed the part of Guido's proposal where he said that 
> docstrings would cease to be used for documentation :-)
> 
> I don't think that it is a serious risk that docstrings will disappear, 
> or that people will try to shove usage comments inside the parameter 
> list:
> 
> def frobnicate(
>    # this is the thing to be frobnicated
>    obj:int,
>    # pass a truthy object to use the blue frob instead of red frob
>    blue:object=False,
>    # an extra helping of spam
>    yes_please_more_spam:list[Spam]
>    ):
> 
> any more than they already do. (I think I've written a comment inside a 
> parameter list maybe twice in the last decade.) I don't think there's 
> much risk of that changing.
> 
> A more exciting outcome would be for documentation tools to start using 
> the type annotations directly, without needing the writer to include the 
> type annotation in two places (the parameter list and the docstring). 
> But before the doc tools can do that, there needs to be a standard for 
> annotations.
> 


Couldn’t the documentation tools also just pull that information from the
annotations?

---
Donald Stufft
PGP: 7C6B 7C5D 5E2B 6356 A926 F04F 6E3C BCE9 3372 DCFA

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-ideas/attachments/20140816/419a23e9/attachment.html>