Abstract

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

Rationale

Because Python’s 2.x series lacks a standard way of annotating a
function’s parameters and return values (e.g., with information about
what type a function’s return value should be), a variety of tools
and libraries have appeared to fill this gap [2]. Some
utilise the decorators introduced in "PEP 318", while others parse a
function’s docstring, looking for annotations there.

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

Fundamentals of Function Annotations

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

1. Function annotations, both for parameters and return values, are
   completely optional.

2. Function annotations are nothing more than a way of associating
   arbitrary Python expressions with various parts of a function at
   compile-time.

   By itself, Python does not attach any particular meaning or
   significance to annotations. Left to its own, Python simply makes
   these expressions available as described in Accessing Function
   Annotations below.

   The only way that annotations take on meaning is when they are
   interpreted by third-party libraries. These annotation consumers
   can do anything they want with a function’s annotations. For
   example, one library might use string-based annotations to provide
   improved help messages, like so:

   def compile(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 Python
   functions and methods. This library could use annotations to
   indicate the function’s expected input and return types, possibly
   something like:

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

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

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

   There is no worry that these libraries will assign semantics at
   random, or that a variety of libraries will appear, each with
   varying semantics and interpretations of what, say, a tuple of
   strings means. The difficulty inherent in writing annotation
   interpreting libraries will keep their number low and their
   authorship in the hands of people who, frankly, know what they’re
   doing.

Syntax

def foo(a: int, b: dict, c: int = 5):
    ...

def foo(*args: int, **kwargs: str):
    ...

def foo(*args: [int], **kwargs: {str: str}):
    ...

def sum(*args: int) -> int:
    ...

decorator: '@' dotted_name [ '(' [arglist] ')' ] NEWLINE
decorators: decorator+
funcdef: [decorators] 'def' NAME parameters ['->' test] ':' suite
parameters: '(' [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 the
function’s func_annotations attribute. This attribute is
a dictionary, mapping parameter names to an object representing
the evaluated annotation expression

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

For example, the following annotation:

def foo(a: 'x', b: 5 + 6, c: list) -> str:
    ...

would result in a func_annotation mapping of

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

The return key was chosen because it cannot conflict with the name
of a parameter; any attempt to use return as a parameter name
would result in a SyntaxError.

func_annotations is an empty dictionary if no there are no
annotations on the function. func_annotations is always an empty
dictionary for functions created from lambda expressions.

Standard Library

Relation to Other PEPs

Implementation

A sample implementation for the syntax changes has been provided
[10] by Tony Lownds.

Rejected Proposals

• The BDFL rejected the author’s idea for a special syntax for adding
  annotations to generators as being "too ugly" [4].
• Though discussed early on ([5], [6]), including
  special objects in the stdlib for annotating generator functions and
  higher-order functions was ultimately rejected as being more
  appropriate for third-party libraries; including them in the
  standard library raised too many thorny issues.
• Despite considerable discussion about a standard type
  parameterisation syntax, it was decided that this should also be
  left to third-party libraries. ([7],
  [8], [9])

References and Footnotes

Copyright

This document has been placed in the public domain.