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

[Gregory P. Smith]

On Thu Aug 14 2014 at 9:02:54 AM Sunjay Varma <varma.sunjay at gmail.com>
wrote:

> I am strongly opposed to this entire proposal. As Juancarlo points out,
> Python programs are small, but very understandable. I think this syntax
> detracts from that. I'll suggest an alternative further down in my reply.
>

Small? I've got tens of millions of lines of Python code to wrangle that
says otherwise. We're trying to create an analyzer and type inferencer so
that we can actually make sense of it all to make it easier to both (a)
maintain and (b) migrate to Python 3. :)


> One benefit of Python that makes it so attractive for new programmers and
> even old programmers alike is that you can usually pick out any piece of
> Python code and begin to understand it immediately. Even if you come from a
> different programming language, Python is written in
> english explicitly using words like "and" and "or". Those constructs, as
> opposed to "&&" or "||" make the language less scary for new developers and
> in general easier to read as well. It's also easier to type regular english
> words (no need to use the shift key). Using the annotation syntax this
> heavily will detract very much from the readability of Python and from the
> overall usability as well. Programs are read more times than they are
> written.
>
> Several years ago, before I had any programming experience in any language
> at all, I needed to edit some Python code to make something I was doing
> work. Without any experience at all, I was able to look through the (small)
> program I was editing and figure out exactly what I needed to adjust.
> Without Python being such a clean, almost English language, that would have
> been impossible.
>
> Though the annotation syntax is already present in Python 3, I would argue
> that using this for type annotations will get very messy very quickly. If
> I'm understanding the syntax correctly, writing any function using a large
> library with many nested subpackages could result in code like this:
>
>     import twisted.protocols.mice.mouseman
>
>     def
> process_mouseman(inputMouseMan: twisted.protocols.mice.mouseman.MouseMan)
> -> twisted.protocols.mice.mouseman.MouseMan:
>         pass
>
> That function definition is 122 characters long. Far more than what PEP8
> recommends. Though this example was crafted to illustrate my point (I don't
> think most people would really write code like this), it is easy to see
> that this kind of code is possible and may sometimes be written by some
> less experienced programmers. It demonstrates how messy things can get even
> with just one parameter.
>
> It is also easy to see that it is very difficult to parse out what is
> going on in that function. Adding type annotations inline makes it very
> difficult to quickly get an idea of what arguments a function takes and in
> what order. It detracts from the overall readability of a program and can
> also lead to very poorly formatted programs that break the guidelines in
> PEP8. Though I have only demonstrated this for function declarations, the
> example could also be extended to inline statement comments as well. Things
> get too messy too quickly.
>
> My Alternative Proposal:
> As an alternative, I would like to propose a syntax that Pycharm already
> supports:
> http://www.jetbrains.com/pycharm/webhelp/using-docstrings-to-specify-types.html
>
> Since this type information isn't going to be used at runtime in the
> regular Python interpreter anyway, why not have it in the function
> docstring instead? This provides both readability and type checking.
> Standardizing that syntax or at least adding it as an optional way to check
> your program would in my opinion be a much better addition to the language.
> This approach needs no new syntax, keeps readability and allows the
> programmer to add additional documentation without going over the 80
> character limit.
>

Without commenting on the specific format of the docstring, there is an
added benefit to using docstrings for parameter and return value type
information: It encourages people to write documentation.

(the exact format of types in a docstring could turn into its own bikeshed
even grander than this thread already is)

JavaScript successfully uses this approach for type annotations. (sure, its
in comments, but that's because they don't _have_ docstrings).

In a way, using docstrings is similar to what argument clinic does for
extension modules. We could provide a standard way to do it and have the
language runtime parse them and turn them into actual annotation objects
when the __annotations__ attribute is first accessed on anything. If
someone really wanted to they could have it hide the information from the
docstring at the same time (I don't recommend that. Argument clinic is
"special" and had a real a need for this).

That laziness *mostly* avoids the forward referencing or forward
declaration mess that you'd otherwise have.

-gps
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-ideas/attachments/20140815/5203b8f5/attachment-0001.html>