[Python-3000] Function annotations considered obfuscatory (Re: Conventions for annotation consumers)

[Guido van Rossum]

On 8/16/06, Josiah Carlson <jcarlson at uci.edu> wrote:
>
> "Guido van Rossum" <guido at python.org> wrote:
> > On 8/16/06, Jim Jewett <jimjjewett at gmail.com> wrote:
> > > That is one reason I wonder whether all annotations/modifications have
> > > to actually be part of the prologue, or whether they could be applied
> > > to the Signature afterwards.
> >
> > And how would that reduce the clutter? The information still has to be
> > entered by the user, presumably with the same disambiguating tags, and
> > some punctuation.
>
> I'd say that pulling out annotations from the function signature, which
> was argued to be the most important piece of information about a
> function during the decorator discussion, could do at least as much to
> reduce clutter and increase readability and understandability, as
> anything else discussed with regards to the PEP so far.
>
> To pull back out that 9 line function...
>
> > @docstring
> > @typechecker
> > @constrain_values
> > def foo(a: {'doc': "Frobnication count",
> >            'type': Number,
> >            'constrain_values': range(3, 9)},
> >        b: {'type': Number,
> >             # This can be only 4, 8 or 12
> >            'constrain_values': [4, 8, 12]}) -> {'type': Number}
>
> First cleaning up the annotations to not use a dictionary:
>
>
> @docstring
> @typechecker
> @constrain_values
> def foo(a: [doc("frobination count"),
>             type(Number),
>             constrain_values(range(3,9))],
>         b: [type(Number),
>             # This can be only 4, 8 or 12
>             constrain_values([4,8,12])]) -> type(Number):
>
> Now lets pull those annotations out of the signature...
>
> @docstring
> @typechecker
> @constrain_values
> @__signature__([doc("frobination count"),
>                 type(Number),
>                 constrain_values(range(3,9))],
>                [type(Number),
>                 # This can be only 4, 8 or 12
>                 constrain_values((4,8,12))], returns=type(Number))
> def foo(a, b):

I think you just have disproved your point. Apart from losing a few
string quotes this is just as unreadable as the example you started
with, and those string quotes were due to a different convention for
multiple annotations, not due to moving the information into a
descriptor.

> Ultimately the full function definition (including decorators) is just
> as cluttered, but now we can see that we have a function that takes two
> arguments, without having to scan for 'name:' .  If it is necessary for
> somone to know what kinds of values, types, docs, etc., then they can
> use the documentation-producing tool that will hopefully come with their
> annotation consumer(s).

The whole point of putting decorators up front was so that they share
prime real estate ("above the fold" if you will :-) with the function
signature. Claiming that what's in the decorators doesn't distract
from the def itself doesn't make it true.

But, as I said 15 minutes ago, please stop worrying about this so
much. Try to implement Collin's PEP (which doesn't have any
constraints on the semantics or use of annotations). There's a Py3k
sprint at Google (MV and NY) next week -- perhaps we can work on it
there!

-- 
--Guido van Rossum (home page: http://www.python.org/~guido/)