[Python-ideas] Conventions for function annotations

[Daniel Wong]

This proposal looks great. The only thing is that I don't understand the 
point of annotations in the first place, since Python has decorators. As 
the last part of your post describes, decorators can be used to do the same 
thing. With decorators, it is even possible to use annotation-like syntax:

def defaults_as_parameter_metadata(f):
  names, args_name, kwargs_name, defaults = inspect.getargspec(f) 
  assert len(names) == len(defaults)  # To keep this example simple...

  f.parameter_metadata = {}
  for name, meta in zip(names, defaults):
    f.parameter_metadata[name] = meta
  f.__defaults__ = ()  # Again, for simplicity.
  return f


@defaults_as_parameter_metadata
def make_ice_cream(flavor=(options('vanilla', 'chocolate', ...),
                           str, "What kind of delicious do you want?"),
                   quantity=(positive, double,
                             "How much (in pounds) do you want?")):
  ...


I know this addresses a different issue, but I was directed to this thread 
from an answer that I got on StackOverflow<http://stackoverflow.com/questions/13784713/what-good-are-python-function-annotations/13785381#13785381>, 
and this thread seems related enough. Sorry if I'm going off the rails here.

On Saturday, December 1, 2012 4:28:50 AM UTC-8, Thomas Kluyver wrote:
>
> Function annotations (PEP 3107) are a very interesting new feature, but so 
> far have gone largely unused. The only project I've seen using them is 
> plac, a command-line option parser. One reason for this is that because 
> function annotations can be used to mean anything, we're wary of doing 
> anything in case we interfere with some other use case. A recent thread on 
> ipython-dev touched on this [1], and we'd like to suggest some conventions 
> to make annotations useful for everyone.
>
> 1. Code inspecting annotations should be prepared to ignore annotations it 
> can't understand.
>
> 2. Code creating annotations should use wrapper classes to indicate what 
> the annotation means. For instance, we are contemplating a way to specify 
> options for a parameter, to be used in tab completion, so we would do 
> something like this:
>
> from IPython.core.completer import options
> def my_io(filename, mode: options('read','write') ='read'):
>     ...
>
> 3. There are a couple of important exceptions to 2:
> - Annotations that are simply a string can be used like a docstring, to be 
> displayed to the user. Inspecting code should not expect to be able to 
> parse any machine-readable information out of these strings.
> - Annotations that are a built-in type (int, str, etc.) indicate that the 
> value should always be an instance of that type. Inspecting code may use 
> these for type checking, introspection, optimisation, or other such 
> purposes. Note that for now, I have limited this to built-in types, so 
> other types can be used for other purposes, but this could be extended. For 
> instance, the ABCs from collections (collections.Mapping et al.) could well 
> be added to this category.
>
> 4. There should be a convention for attaching multiple annotations to one 
> value. I propose that all code using annotations expects to handle 
> tuples/lists of annotations. (We also considered dictionaries, but the 
> result is long and ugly). So in this definition:
>
> def my_io(filename, mode: (options('read','write'), str, 'The mode in 
> which to open the file') ='read'):
>     ...
>
> the mode parameter has a set of options (ignored by frameworks that don't 
> recognise it), should always be a string, and has a description.
>
> Any thoughts and suggestions are welcome.
>
> As an aside, we may also create a couple of decorators to fill in 
> __annotations__ on Python 2, something like:
>
> @return_annotation('A file obect')
> @annotations(mode=(options('read','write'), str, 'The mode in which to 
> open the file'))
> def my_io(filename, mode='read'):
>     ...
>
> [1] http://mail.scipy.org/pipermail/ipython-dev/2012-November/010697.html
>
>
> Thanks,
> Thomas
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-ideas/attachments/20121209/1f0d0782/attachment.html>