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

[Steven D'Aprano]

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.


-- 
Steven