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

[Phillip J. Eby]

At 14:47 8/10/2006 +1200, Greg Ewing <greg.ewing at canterbury.ac.nz> wrote:
>And what are you supposed to do if you want to write
>a function that has improved help messages *and*
>type checking?

Create a type annotation object that wraps multiple objects -- or better 
yet, use a list or tuple of annotations.  (See below.)


> >    The difficulty inherent in writing annotation interpreting
> >    libraries will keep their number low and their authorship in the
> >    hands of people who, frankly, know what they're doing.
>
>Even if there are only two of them, they can still
>conflict.
>
>I think the idea of having totally undefined
>annotations is fundamentally flawed.

No, your assumption is fundamentally flawed.  ;-)  This is a trivial 
application of overloaded functions.

In PEAK, there is a similar concept called "attribute metadata" that can be 
applied to the attributes of a class.  A single overloaded function called 
"declareAttribute" is used to "declare" the metadata.  These metadata 
annotations can be anything you want.  Certain PEAK frameworks use them for 
security declarations.  Others use them to mark an attribute as providing a 
certain interface for child components, to describe the attribute's syntax 
for parsing or formatting, and so on.

There is no predefined semantics for these metadata objects -- none 
whatsoever.  Each framework that needs a new kind of metadata object simply 
defines a class that holds whatever metadata is desired, and adds a method 
to the "declareAttribute" function to handle objects of that type.  The 
added method can do anything: modify the class or descriptor in some way, 
register something in a registry, or whatever else you want it to do.

In addition, the declareAttribute function comes with predefined methods 
for processing tuples and lists by iterating over them and calling 
declareAttribute recursively.  This makes it easy to combine groups of 
metadata objects and reuse them.

So I see no problems with this concept that overloaded functions don't 
trivially solve.  Any operation you want to perform on function annotations 
need only be implemented as an overloaded function, and there is then no 
conflict to worry about.

For example, if you are writing a documentation tool that needs to generate 
a short HTML string for an annotation, you just create an overloaded 
function for that.  Then somebody using the documentation tool with 
arbitrary type annotation frameworks (e.g. their own) can just add methods 
to the documentation tool's overloaded functions to support that.

Indeed, many a time I've wished that epydoc was written using overloaded 
functions, as it then would've been easy to extend it to gracefully handle 
PEAK's more esoteric descriptors and metaclasses.