[Python-3000] Draft pre-PEP: function annotations

[Phillip J. Eby]

At 09:16 PM 8/12/2006 -0700, Josiah Carlson wrote:
>"Phillip J. Eby" <pje at telecommunity.com> wrote:
> > However, if you have:
> >
> >     def myfunc( x : doc("The x coordinate"), y : doc("The y coordinate") )
> >
> > There is no ambiguity.  Likewise:
> >
> >     def cat( infile:opt("i") = sys.stdin, outfile:opt("o") = sys.stdout ):
> >
> > is unambiguous.  And the interpetation of:
> >
> >     def cat(infile: [doc("input stream"), opt("i")] = sys.stdin,
> >             outfile: [doc("output stream"), opt("o")] = sys.stdout
> >     ):
> >
> > is likewise unambiguous, unless the creator of the documentation or option
> > features has defined some other interpretation for a list than 
> "recursively
> > apply to contained items".  In which case, you need only do something like:
> >
> >     def cat(infile: docopt("input stream", "i") = sys.stdin,
> >             outfile: docopt("output stream", "o") = sys.stdout
> >     ):
>
>I now understand where you were coming from with regards to this being
>equivalent to pickle (at least pickle + copy_reg).  I think that if you
>would have posted this particular sample a couple days ago, there
>wouldn't have been the discussion (argument?) about incompatible
>mechanisms for annotation processing.

Well, it just seemed to me that that was the One Obvious Way To Do It; more 
specifically, I couldn't conceive of any *other* way to do it!


>With that said, the above is a protocol.  Just like __len__, __str__,
>copy_reg, __reduce__, __setstate__, etc., are protocols.  It may not be
>fully specified (when annotations are to be processed, if at all, by
>whom, where the annotation registry is, etc.), but it is still a
>protocol.

Actually, it's a family of *patterns* for creating protocols.  It's not a 
protocol, incompletely specified or otherwise.  Note that the actual 
implementation of the tell-don't-ask pattern can be via:

1. duck typing (i.e., prearranged method names)
2. adaptation
3. overloaded functions (any of several implementations)
4. ad hoc type-based registries

So it isn't even a *meta*-protocol, just a pattern family.


>Do we need any more specification for the PEP and 2.6/3k?  I don't know,
>maybe. You claim no, with the history of PEAK and other languages as
>proof that doing anything more is unnecessary.  And I can understand why
>you would resist any further specification: PEAK has been doing
>annotations for quite a while, and additional specifications could make
>transitioning to these annotations a pain in the ass for you and your
>users.

Not really; PEAK's annotations are currently only on *attributes* and 
*classes*, not functions, arguments, or return values.  I was merely using 
it as an example of how overloaded functions allow heterogeneous 
annotations to coexist without needing any prearranged common semantics.

But I don't believe we know enough *today* to be able to safely define a 
rigid specification without ruling out possibly-valid uses.  By making a 
less-rigid specification, we force annotation consumers to code 
defensively...  which is really the right thing to do in a heterogeneous 
environment anyway.


>I'm personally not convinced that no further specification is desired or
>necessary (provided we include a variant of the above example
>annotations),

As I said, I'd prefer to see the tell-don't-ask pattern specifically cited 
and recommended, perhaps with examples.

I'll note, however, that the only consequence of *not* following that 
pattern is that you create a non-extensible, non-interoperable framework -- 
of which Python has huge numbers already.  This is not so damaging an 
outcome as to be worrisome, any more than we worry about people creating 
incompatible metaclasses today!


>but I also cannot convince myself that specifying anything
>further would be flexible enough to not be a mistake.

Right - that's the bit I'm concerned about.  Python also usually doesn't 
impose such policy constraints on mechanism.  For example, function 
attributes can be or contain anything, and nobody has argued that there 
need to be prespecified combination semantics, despite the fact that 
multiple tools can be consumers of the attributes.