What are good uses for Python3's "Function Annotations"?

Function annotations are what you make of them.

They can be used for documentation:

def kinetic_energy(mass: 'in kilograms', velocity: 'in meters per second'):     ...

They can be used for pre-condition checking:

def validate(func, locals):    for var, test in func.__annotations__.items():        value = locals[var]        msg = 'Var: {0}\tValue: {1}\tTest: {2.__name__}'.format(var, value, test)        assert test(value), msgdef is_int(x):    return isinstance(x, int)def between(lo, hi):    def _between(x):            return lo <= x <= hi    return _betweendef f(x: between(3, 10), y: is_int):    validate(f, locals())    print(x, y)>>> f(0, 31.1)Traceback (most recent call last):   ... AssertionError: Var: y  Value: 31.1 Test: is_int

Also see http://www.python.org/dev/peps/pep-0362/ for a way to implement type checking.

I think this is actually great.

Coming from an academic background, I can tell you that annotations have proved themselves invaluable for enabling smart static analyzers for languages like Java. For instance, you could define semantics like state restrictions, threads that are allowed to access, architecture limitations, etc., and there are quite a few tools that can then read these and process them to provide assurances beyond what you get from the compilers. You could even write things that check preconditions/postconditions.

I feel something like this is especially needed in Python because of its weaker typing, but there were really no constructs that made this straightforward and part of the official syntax.

There are other uses for annotations beyond assurance. I can see how I could apply my Java-based tools to Python. For instance, I have a tool that lets you assign special warnings to methods, and gives you indications when you call them that you should read their documentation (E.g., imagine you have a method that must not be invoked with a negative value, but it's not intuitive from the name). With annotations, I could technically write something like this for Python. Similarly, a tool that organizes methods in a large class based on tags can be written if there is an official syntax.

This is a way late answer, but AFAICT, the best current use of function annotations is PEP-0484 and MyPy.

Mypy is an optional static type checker for Python. You can add type hints to your Python programs using the upcoming standard for type annotations introduced in Python 3.5 beta 1 (PEP 484), and use mypy to type check them statically.

Used like so:

from typing import Iteratordef fib(n: int) -> Iterator[int]:    a, b = 0, 1    while a < n:        yield a        a, b = b, a + b