Open Source Project Examples Using Python 3 Feature Annotations

Question

Can someone give me some sample Python open source projects using function annotations introduced in Python 3?

I want to see some practical applications of this function and see if I can use it in my own project.

Answer 1

I have never seen this feature used in the wild. However, one potential use of function annotations, which I studied in a Python 3 article that I wrote for USENIX; Login: to enforce contracts. For example, you can do this:

from functools import wraps def positive(x): 'must be positive' return x > 0 def negative(x): 'must be negative' return x < 0 def ensure(func): 'Decorator that enforces contracts on function arguments (if present)' return_check = func.__annotations__.get('return',None) arg_checks = [(name,func.__annotations__.get(name)) for name in func.__code__.co_varnames] @wraps(func) def assert_call(*args): for (name,check),value in zip(arg_checks,args): if check: assert check(value),"%s %s" % (name, check.__doc__) result = func(*args) if return_check: assert return_check(result),"return %s" % (return_check.__doc__) return result return assert_call # Example use @ensure def foo(a:positive, b:negative) -> positive: return ab 

If you do this, you will see the following:

 >>> foo(2,-3) 5 >>> foo(2,3) Traceback (most recent call last): File "<stdin>", line 1, in <module> File "ensure.py", line 22, in assert_call assert check(value),"%s %s" % (name, check.__doc__) AssertionError: b must be negative 

I should note that the above example should be more detailed in order to work correctly with default arguments, keyword arguments, and other details. This is just a sketch of an idea.

Now, whether this is really a good idea or not, I just don't know. I tend to agree with Brandon that the lack of compositional ability is a problem, especially if annotations start being used by different libraries for different purposes. I also wonder if it's possible to do something like this contract idea through decorators. For example, creating a decorator that was used in this way (the implementation is left as an exercise):

 @ensure(a=positive,b=negative) def foo(a,b): return ab 

Historical note. I have always believed that function annotations are the result of discussions about the “optional static typing” that the Python community had over 10 years ago. Whether this is an original motivation or not, I just don't know.

Answer 2

I will play an idol and do not recommend using this feature. Hope this will be removed someday. Python still has done a great job deploying attractive, orthogonal functions that can be stacked - function decorators are a great example: if I use three different libraries that everyone wants me to decorate my function, the result looks pretty clean

 @lru_cache(max_items=5) @require_basic_auth @view('index.html') def index(…): ⋮ 

But this new-fangled awkward “annotation” function takes Python in the opposite direction: because you can annotate a given function only once, it completely destroys the ability to make decisions from different parts. If you had two libraries, each of which wanted you to annotate the same function on their behalf, then from what I see, you would be completely drowned.