[Python-ideas] Conventions for function annotations

[Nick Coghlan]

On Mon, Dec 3, 2012 at 6:09 PM, Raymond Hettinger <
raymond.hettinger at gmail.com> wrote:

>
> On Dec 2, 2012, at 3:43 AM, Nick Coghlan <ncoghlan at gmail.com> wrote:
>
>  Admittedly this was long enough ago that I don't remember the details,
> just the obvious consequence that PEP 8 remains largely silent on the
> matter, aside from declaring that function annotations are off-limits for
> standard library modules:
>
>
> PEP 8 is not "largely silent" on the subject:
>

It's effectively silent on the matters at hand, which are:

* the advisability of using annotations without an associated decorator
that makes the interpretation currently in play explicit (while the
examples given do illustrate why *not* doing this is a bad idea, it doesn't
explicitly state that conclusion, merely "we're not going to use them in
the standard library at this point")
* the advisability of providing a pure annotations API, without any
fallback to an explicit decorator factory
* the advisability of handling composition within the annotations
themselves, rather than by falling back to explicit decorator factories
* the advisability of using the __annotations__ dictionary for long-term
introspection, rather than using the decorator to move the information to a
purpose-specific location in a separate function attribute

I would be *quite delighted* if people are open to the idea of making a
much stronger recommendation along the following lines explicit in PEP 8:

==================

* If function annotations are used, it is recommended that:
    * the annotation details should be designed with a specific practical
use case in mind
    * the annotations are used solely as a form of syntactic sugar for
passing arguments to a decorator factory that would otherwise accept
explicit per-parameter arguments
    * the decorator factory name should provide the reader of the code with
a strong hint as to the intended meaning of the parameter annotations (or
at least a convenient reference point to look up in the documentation)
    * in simple cases, using parameter and return type annotations will
then allow the per-parameter details to be mapped easily by both the code
author and later readers without requiring repetition of parameter names or
careful alignment of factory arguments with parameter positions.
    * the explicit form remains available to handle more complex situations
(such as applying multiple decorators to the same function) without
requiring complicated conventions for composing independent annotations on
a single function

==================

In relation to the last point, I consider composing annotations to be
analogous to composing function arguments. Writing:

    @g
    @f
    def annotated(arg1: (a, x), arg2: (b, y), arg3: (c, z)):
        ...

instead of the much simpler:

    @g(x, y, z)
    @f(a, b, c)
    def annotated(arg1, arg2, arg3):
        ...

is analagous to writing:

    args = [(a, x), (b, y), (c, z)]
    f(*(x[0] for x in args))
    g(*(x[1] for x in args))

instead of the more obvious:

    f(a, b, c)
    g(x, y, z)

Cheers,
Nick.

-- 
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-ideas/attachments/20121203/f62cd443/attachment.html>