Abstract

This PEP introduces a syntax for adding arbitrary metadata annotationsto Python functions[1].

Rationale

Because Python’s 2.x series lacks a standard way of annotating afunction’s parameters and return values, a variety of toolsand libraries have appeared to fill this gap. Someutilise the decorators introduced inPEP 318, while others parse afunction’s docstring, looking for annotations there.

This PEP aims to provide a single, standard way of specifying thisinformation, reducing the confusion caused by the wide variation inmechanism and syntax that has existed until this point.

Fundamentals of Function Annotations

Before launching into a discussion of the precise ins and outs ofPython 3.0’s function annotations, let’s first talk broadly aboutwhat annotations are and are not:

1. Function annotations, both for parameters and return values, arecompletely optional.
2. Function annotations are nothing more than a way of associatingarbitrary Python expressions with various parts of a function atcompile-time.

   By itself, Python does not attach any particular meaning orsignificance to annotations. Left to its own, Python simply makesthese expressions available as described inAccessing FunctionAnnotations below.

   The only way that annotations take on meaning is when they areinterpreted by third-party libraries. These annotation consumerscan do anything they want with a function’s annotations. Forexample, one library might use string-based annotations to provideimproved help messages, like so:

   defcompile(source:"something compilable",filename:"where the compilable thing comes from",mode:"is this a single statement or a suite?"):...

   Another library might be used to provide typechecking for Pythonfunctions and methods. This library could use annotations toindicate the function’s expected input and return types, possiblysomething like:

   defhaul(item:Haulable,*vargs:PackAnimal)->Distance:...

   However, neither the strings in the first example nor thetype information in the second example have any meaning on theirown; meaning comes from third-party libraries alone.

3. Following from point 2, this PEP makes no attempt to introduceany kind of standard semantics, even for the built-in types.This work will be left to third-party libraries.

Syntax

deffoo(a:expression,b:expression=5):...

deffoo(*args:expression,**kwargs:expression):...

deffoo((x1,y1:expression),(x2:expression,y2:expression)=(None,None)):...

defsum()->expression:...

decorator:'@'dotted_name['('[arglist]')']NEWLINEdecorators:decorator+funcdef:[decorators]'def'NAMEparameters['->'test]':'suiteparameters:'('[typedargslist]')'typedargslist:((tfpdef['='test]',')*('*'[tname](','tname['='test])*[',''**'tname]|'**'tname)|tfpdef['='test](','tfpdef['='test])*[','])tname:NAME[':'test]tfpdef:tname|'('tfplist')'tfplist:tfpdef(','tfpdef)*[',']

Accessing Function Annotations

Once compiled, a function’s annotations are available via thefunction’s__annotations__ attribute. This attribute isa mutable dictionary, mapping parameter names to an objectrepresenting the evaluated annotation expression

There is a special key in the__annotations__ mapping,"return". This key is present only if an annotation was suppliedfor the function’s return value.

For example, the following annotation:

deffoo(a:'x',b:5+6,c:list)->max(2,9):...

would result in an__annotations__ mapping of

{'a':'x','b':11,'c':list,'return':9}

Thereturn key was chosen because it cannot conflict with the nameof a parameter; any attempt to usereturn as a parameter namewould result in aSyntaxError.

__annotations__ is an empty, mutable dictionary if there are noannotations on the function or if the functions was created fromalambda expression.

Use Cases

In the course of discussing annotations, a number of use-cases havebeen raised. Some of these are presented here, grouped by what kindof information they convey. Also included are examples of existingproducts and packages that could make use of annotations.

• Providing typing information
  • Type checking ([3],[4])
  • Let IDEs show what types a function expects and returns ([16])
  • Function overloading / generic functions ([21])
  • Foreign-language bridges ([17],[18])
  • Adaptation ([20],[19])
  • Predicate logic functions
  • Database query mapping
  • RPC parameter marshaling ([22])
• Other information
  • Documentation for parameters and return values ([23])

Standard Library

Relation to Other PEPs

Implementation

A reference implementation has been checked into the py3k (formerly“p3yk”) branch as revision 53170[10].

Rejected Proposals

• The BDFL rejected the author’s idea for a special syntax for addingannotations to generators as being “too ugly”[2].
• Though discussed early on ([5],[6]), includingspecial objects in the stdlib for annotating generator functions andhigher-order functions was ultimately rejected as being moreappropriate for third-party libraries; including them in thestandard library raised too many thorny issues.
• Despite considerable discussion about a standard typeparameterisation syntax, it was decided that this should also beleft to third-party libraries. ([7],[8],[9]).
• Despite yet more discussion, it was decided not to standardizea mechanism for annotation interoperability. Standardizinginteroperability conventions at this point would be premature.We would rather let these conventions develop organically, basedon real-world usage and necessity, than try to force all usersinto some contrived scheme. ([13],[14],[15]).

References and Footnotes

Copyright

This document has been placed in the public domain.