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

[Josiah Carlson]

"Phillip J. Eby" <pje at telecommunity.com> wrote:
> 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!

Perhaps, but it was also obvious that very few people knew what the heck
you were talking about (hence the "how" and "what do you mean" queries).

Try to remember that while you may be old-hat at annotations, perhaps
not everyone discussing them at the moment has your particular
experience and assumptions.  Also, when you hand-wave with "it's trivial",
it's more than a little frustrating, because while it may be "trivial"
to you, it's certainly not trivial to the asker (why would they be
asking otherwise?)


> >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:

Here's my take: Protocol in this context is a set of rules for the
definition of the annotations and their interaction with the handler for
the annotations.  For what we seem to have agreed upon, the definition
is via a base class or instance, and the annotation handling is left up
to the user to define (via the four methods you offered, or even others).

If you want to call it a 'pattern', 'protocol', 'meta-protocol', or
whatever, they are all effectively the same thing in this context; a way
of writing annotations that can later be seen as having a (hopefully
unambiguous) meaning.


> 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.

Right.  I'm in no way suggesting that a 'rigid' specification be
developed, and I'm generally on the fence about whether *any*
specification should be done.  But really, the more I think about it,
the more I believe that *something* should be offered as a starting
point. Whether it is in the Python cookbook, a 3rd party module or
package, etc. As long as it includes a link from the standard Python
documentation where annotations are discussed, I think that would be
satisfactory.


> >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.

Ahh, but function decorators *do* have a specified combination semantic;
specifically an order of application and chaining (the return from the
first decorator will be passed to the second decorator, etc.).

If we were to specify anything, I would suggest we define an order of
annotation calling, which would also define a chaining order if
applicable.  Maybe it is completely obvious, but one should never
underestimate what kinds of silly things users will do.


You responded to Jim Jewett
> [Meanwhile, I'm not going to respond to the rest of your message, since it 
> contained some things that appeared to me to be a mixture of ad hominem 
> attack and straw man argument.  I hope that was not actually your intent.]

As a point of reference, even after you linked the documentation about
PEAK, I still had *no idea* what the heck you meant about PEAK
annotations or their implications to function argument annotations. I
like to believe that I'm not stupid, but maybe I'm wrong, or maybe the
documentation could be better (this isn't an insult, I'm quite
experienced at writing poor documentation)?

 - Josiah