[Python-3000] What's the point of annotations?

[Collin Winter]

I was explaining function annotations to a friend this past weekend
and found that, even though I had written the PEP and spent months
debating the little details of how annotations were to work, I was
hard-pressed to answer the question of "why are we doing this?"

The biggest problem I faced then and now is justifying the use-cases
for annotations. Here's what I could come up with off the top of my
head: information for typecheckers; doc strings for parameters; extra
information for IDEs; extra information for static analysis tools like
pylint. These can all be addressed together:

Are the users clamoring for these things? Do these address real
problems that users are having? Not to my knowledge.


1) Information for typecheckers -- in
http://mail.python.org/pipermail/python-ideas/2007-January/000035.html,
Guido said that "Collin's existing type annotation library ... could
be made more elegant by attaching the types directly to the
arguments". As far as I can tell, the only gains in elegance are that
you don't have to repeat the names of a function's parameters in the
typechecking decorator. None of my users have ever complained about
this tiny bit of repetition, and I've never felt it an undue burden in
my own usage.

It could even be considered an advantage, since including the
"annotations" in the typechecking decorator means all I have to do to
remove typechecking from a function is delete a single line, rather
than pick through a function's declaration, removing the relevant
bits.


2) Doc strings for parameters --

def foo(a: "the object to be frobnicated",
             b=7: "this controls the level of frobnication",
             c="Rojo": "the name of a color, in Spanish, that should
be applied to the \
                   frobnicated thing") -> "Returns an integer between
9 and 13":
    """ Frobnicate an object in a spanish way """
    ...

What does this accomplish that can't be achieved with any of the
standard documentation syntaxes in existence today?


3) Type information for IDEs -- I can see it being genuinely useful to
be able to get parameter/return type information in a tooltip message.
But IDLE can do this already, without annotations:
http://www.python.org/idle/doc/idle2.html#Tips


4) Type information for static analysis tools -- Quoting Nick Coghlan
(http://mail.python.org/pipermail/python-3000/2006-August/003043.html):
"annotations wouldn't be useful for tools like pychecker ... to be
really useful for a tool like pychecker they'd have to be ubiquitous,
and that's really not Python any more". Agreed.


I could say You Aren't Going to Need It, but that gets the tense
wrong; we're getting along without annotations quite nicely here in
the present. In short: I'd like to request that PEP 3107 be rejected
as an overly-specific, unnecessary addition to the language.

Basking-in-the-irony-ly,
Collin Winter