Type annotations¶
The meaning of annotations¶
The type system leverages PEP 3107-style annotations with a number of extensions described in sections below. In its basic form, type hinting is used by filling function annotation slots with classes:
def greeting(name: str) -> str:
return 'Hello ' + name
This states that the expected type of the name argument is
str. Analogically, the expected return type is str.
Expressions whose type is a subtype of a specific argument type are also accepted for that argument.
Any function without annotations should be treated as having the most general type possible, or ignored, by any type checker.
It is recommended but not required that checked functions have
annotations for all arguments and the return type. For a checked
function, the default annotation for arguments and for the return type
is Any. An exception is the first argument of instance and
class methods. If it is not annotated, then it is assumed to have the
type of the containing class for instance methods, and a type object
type corresponding to the containing class object for class methods.
For example, in class A the first argument of an instance method
has the implicit type A. In a class method, the precise type of
the first argument cannot be represented using the available type
notation.
(Note that the return type of __init__ ought to be annotated with
-> None. The reason for this is subtle. If __init__ assumed
a return annotation of -> None, would that mean that an
argument-less, un-annotated __init__ method should still be
type-checked? Rather than leaving this ambiguous or introducing an
exception to the exception, we simply say that __init__ ought to
have a return annotation; the default behavior is thus the same as for
other methods.)
A type checker is expected to check the body of a checked function for consistency with the given annotations. The annotations may also be used to check correctness of calls appearing in other checked functions.
Type checkers are expected to attempt to infer as much information as
necessary. The minimum requirement is to handle the builtin
decorators @property, @staticmethod and @classmethod.
Valid type expression forms¶
Type hints may be built-in classes (including those defined in
standard library or third-party extension modules), abstract base
classes, types available in the types module, and user-defined
classes (including those defined in the standard library or
third-party modules).
While annotations are normally the best format for type hints, there are times when it is more appropriate to represent them by a special comment, or in a separately distributed stub file. (See below for examples.)
Annotations must be valid expressions that evaluate without raising exceptions at the time the function is defined (but see below for forward references).
Annotations should be kept simple or static analysis tools may not be able to interpret the values. For example, dynamically computed types are unlikely to be understood. (This is an intentionally somewhat vague requirement; specific inclusions and exclusions may be added in the future as warranted by the discussion.)
In addition to the above, the following special constructs defined
below may be used: None, Any, Union, Tuple,
Callable, all ABCs and stand-ins for concrete classes exported
from typing (e.g. Sequence and Dict), type variables, and
type aliases.
Forward references¶
When a type hint contains names that have not been defined yet, that definition may be expressed as a string literal, to be resolved later.
A situation where this occurs commonly is the definition of a container class, where the class being defined occurs in the signature of some of the methods. For example, the following code (the start of a simple binary tree implementation) does not work:
class Tree:
def __init__(self, left: Tree, right: Tree):
self.left = left
self.right = right
To address this, we write:
class Tree:
def __init__(self, left: 'Tree', right: 'Tree'):
self.left = left
self.right = right
The string literal should contain a valid Python expression (i.e.,
compile(lit, '', 'eval') should be a valid code object) and it
should evaluate without errors once the module has been fully loaded.
The local and global namespace in which it is evaluated should be the
same namespaces in which default arguments to the same function would
be evaluated.
Moreover, the expression should be parseable as a valid type hint, i.e., it is constrained by the rules from the section on Valid type expression forms.
If a triple quote is used, the string should be parsed as though it is implicitly surrounded by parentheses. This allows newline characters to be used within the string literal:
value: """
int |
str |
list[Any]
"""
It is allowable to use string literals as part of a type hint, for example:
class Tree:
...
def leaves(self) -> list['Tree']:
...
A common use for forward references is when e.g. Django models are needed in the signatures. Typically, each model is in a separate file, and has methods taking arguments whose type involves other models. Because of the way circular imports work in Python, it is often not possible to import all the needed models directly:
# File models/a.py
from models.b import B
class A(Model):
def foo(self, b: B): ...
# File models/b.py
from models.a import A
class B(Model):
def bar(self, a: A): ...
# File main.py
from models.a import A
from models.b import B
Assuming main is imported first, this will fail with an ImportError at
the line from models.a import A in models/b.py, which is being
imported from models/a.py before a has defined class A. The solution
is to switch to module-only imports and reference the models by their
_module_._class_ name:
# File models/a.py
from models import b
class A(Model):
def foo(self, b: 'b.B'): ...
# File models/b.py
from models import a
class B(Model):
def bar(self, a: 'a.A'): ...
# File main.py
from models.a import A
from models.b import B
Annotating generator functions and coroutines¶
The return type of generator functions can be annotated by
the generic type Generator[yield_type, send_type,
return_type] provided by typing.py module:
def echo_round() -> Generator[int, float, str]:
res = yield
while res:
res = yield round(res)
return 'OK'
Coroutines introduced in PEP 492 are annotated with the same syntax as
ordinary functions. However, the return type annotation corresponds to the
type of await expression, not to the coroutine type:
async def spam(ignored: int) -> str:
return 'spam'
async def foo() -> None:
bar = await spam(42) # type is str
The generic ABC collections.abc.Coroutine can be used
to specify awaitables that also support
send() and throw() methods. The variance and order of type variables
correspond to those of Generator, namely Coroutine[T_co, T_contra, V_co],
for example:
from collections.abc import Coroutine
c: Coroutine[list[str], str, int]
...
x = c.send('hi') # type is list[str]
async def bar() -> None:
x = await c # type is int
The generic ABCs Awaitable,
AsyncIterable, and AsyncIterator can be used for situations where more precise
types cannot be specified:
def op() -> collections.abc.Awaitable[str]:
if cond:
return spam(42)
else:
return asyncio.Future(...)
Annotating instance and class methods¶
In most cases the first argument of class and instance methods does not need to be annotated, and it is assumed to have the type of the containing class for instance methods, and a type object type corresponding to the containing class object for class methods. In addition, the first argument in an instance method can be annotated with a type variable. In this case the return type may use the same type variable, thus making that method a generic function. For example:
T = TypeVar('T', bound='Copyable')
class Copyable:
def copy(self: T) -> T:
# return a copy of self
class C(Copyable): ...
c = C()
c2 = c.copy() # type here should be C
The same applies to class methods using type[] in an annotation
of the first argument:
T = TypeVar('T', bound='C')
class C:
@classmethod
def factory(cls: type[T]) -> T:
# make a new instance of cls
class D(C): ...
d = D.factory() # type here should be D
Note that some type checkers may apply restrictions on this use, such as requiring an appropriate upper bound for the type variable used (see examples).