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

[Phillip J. Eby]

At 09:49 PM 8/11/2006 -0700, Talin wrote:
>Phillip J. Eby wrote:
>>Not at all.  A and B need only use overloadable functions, and the 
>>problem is trivially resolved by adding overloads.  The author of C can 
>>add an overload to "A" that will handle objects with 'next' attributes, 
>>or add one to "B" that handles tuples, or both.
>
>
>I'm still not sure what you are talking about - what is being overloaded here?
>
>Let me give you a better example. Suppose I have a 'docstring' annotation 
>and a 'getopt' annotation. The docstring annotation associates a string 
>with each argument, which can be inspected by an external documentation 
>scanner to produce documentation for that argument.
>
>Thus:
>
>    def myfunc( x : "The x coordinate", y : "The y coordinate" )
>       ...
>
>The 'getopt' annotation is used in conjunction with the 'getopt' 
>decorator, which converts from command-line arguments to python method 
>arguments. The idea is that you have a class that is acting as a back end 
>to a command-line shell. Each method in the class corresponds to a single 
>command. The annotations allow you to associate specific flags or switches 
>with particular arguments. So:
>
>class MyHandler( CommandLineHandler ):
>
>    @getopt
>    def list( infile:"i" = sys.stdin, outfile:"o" = sys.stdout ):
>       ...
>
>With the getopt handler in place, I can type the following shell command:
>
>    list -i <infile> -o <outfile>
>
>If either the -i or -o switch is omitted, then the corresponding argument 
>is either stdin or stdout.
>
>Additionally, the getopt module can generate 'usage' information for the 
>function in question:
>
>    Usage: list [-i infile] [-o outfile]
>
>Now, what happens if I want to use both docstrings and the getopt 
>decorator on the same function? The both expect to see annotations that 
>are strings! How does the doc extractor and the getopt decorator know 
>which strings belong to them, and which strings they should ignore?

Each one defines an overloaded function that performs the 
operation.  E.g.  "getArgumentOption(annotation)" and 
"getArgumentDoc(annotation)".

If somebody wants to use both decorators on the same function, they add 
methods to one or both of those functions to define how to handle their own 
type.  For example, I could create a "documented option" class that has 
attributes for the docstring and option character, and register methods 
with both getArgumentOption and getArgumentDoc to extact the right 
attributes from it.