[Python-ideas] Conventions for Function Annotations

[dag.odenhall at gmail.com]

On 7 August 2011 16:26, Devin Jeanpierre <jeanpierreda at gmail.com> wrote:
>> Neither does return support multiple values, and yet we can do "return x, y". :)
>
> That's neither here nor there. That is a single return value, a tuple.
> Not different kinds of return values, such as returning something that
> might be annotated as a "sequence" as well as, in other circumstances,
> returning something that might be annotated as a "dict".

That was exactly the point I was trying to demonstrate. It doesn't
make sense to put any sort of special support for multiple values in
annotations, because you're really just reimplementing conventional
use of tuples.

>
> Since few to no sanely written functions return incompatible types,
> there isn't as much reason to complain about this.
>
> On the other hand, almost every single function in the stdlib can
> raise multiple different exceptions. A "raises" annotation is not very
> useful unless you can annotate multiple exceptions that may be raised.
>
>> I think annotations should be used sparingly: there's little need for
>> any sort of interoperability between multiple unrelated uses of
>> annotations. It would be rather complicated and unwieldy to say, both
>> put type hints and argument documentation strings in annotations.
>> Decorators are better suited for composability, as are docstrings for
>> documentation. If you're doing something like mapping a view function
>> to a template with the return annotation, it is unlikely that you need
>> to annotate it with type hints as well, for example.
>
> The decorator you have provided is _not_ composable. In fact, that was
> my complaint. I never said anything about docstrings or mixing and
> matching annotations.

Actually I (quite intentionally) didn't provide any decorator. If
really desired, the fictional @raises decorator could check if 'raise'
is already set and then combine them into a tuple. I'd argue that this
would be inconsistent with syntactical annotations, and @raises should
either override, fail, or silently do nothing, in case of the key
already being set. More consistently, if you wanted to set a tuple,
well then you pass a tuple to the decorator. This could perhaps work
via unpacking as well: @raises(ValueError, ArithmeticError).

My intent with this thread was to consider conventions for mimicing
syntactical annotations in the cases not covered by syntax. If you
want to do something more domain-specific using annotations, then by
all means go right ahead, but consider that you might be better of
using a custom function attribute as well.

>
> Devin
>
> On Sun, Aug 7, 2011 at 10:18 AM, dag.odenhall at gmail.com
> <dag.odenhall at gmail.com> wrote:
>> On 7 August 2011 14:59, Devin Jeanpierre <jeanpierreda at gmail.com> wrote:
>>> What if you want to say that it raises both ValueError and ArithmeticError?
>>>
>>> Annotations never did support multiple annotations, it's a big
>>> drawback. This is a decorator though, you can do what you want. How
>>> about making __annotations__['raise'] a list?
>>>
>>> Otherwise sounds fine to me. The use of keywords in __annotations__ is
>>> pretty clever. :)
>>
>> Neither does return support multiple values, and yet we can do "return x, y". :)
>>
>> Annotations are bound to the evaluation of an expression and you're
>> free to put anything in them. I expect a convention of special-casing
>> tuples will emerge, especially as annotations are particularly
>> suitable for different sorts of "type hints" where tuples are already
>> used for issubclass/isinstance, in "except" clauses and for listing
>> base classes with type() etc.
>>
>> I think annotations should be used sparingly: there's little need for
>> any sort of interoperability between multiple unrelated uses of
>> annotations. It would be rather complicated and unwieldy to say, both
>> put type hints and argument documentation strings in annotations.
>> Decorators are better suited for composability, as are docstrings for
>> documentation. If you're doing something like mapping a view function
>> to a template with the return annotation, it is unlikely that you need
>> to annotate it with type hints as well, for example.
>>
>