This document lays out the theory of the new type hinting proposal for
Python 3.5. It's not quite a full proposal or specification because
there are many details that need to be worked out, but it lays out the
theory without which it is hard to discuss more detailed specifications.
We start by recalling basic concepts of type theory; then we explain
gradual typing; then we state some general rules and
define the new special types (such as Union) that can be used
in annotations; and finally we define the approach to generic types
and pragmatic aspects of type hinting.

t1, t2, etc. and u1, u2, etc. are types. Sometimes we write
ti or tj to refer to "any of t1, t2, etc."

T, U etc. are type variables (defined with TypeVar(), see below).

Objects, classes defined with a class statement, and instances are
denoted using standard PEP 8 conventions.

the symbol == applied to types in the context of this PEP means that
two expressions represent the same type.

Note that PEP 484 makes a distinction between types and classes
(a type is a concept for the type checker,
while a class is a runtime concept). In this PEP we clarify
this distinction but avoid unnecessary strictness to allow more
flexibility in the implementation of type checkers.

There are many definitions of the concept of type in the literature.
Here we assume that type is a set of values and a set of functions that
one can apply to these values.

There are several ways to define a particular type:

By explicitly listing all values. E.g., True and False
form the type bool.

By specifying functions which can be used with variables of
a type. E.g. all objects that have a __len__ method form
the type Sized. Both [1, 2, 3] and 'abc' belong to
this type, since one can call len on them:

len([1, 2, 3]) # OK
len('abc') # also OK
len(42) # not a member of Sized

By a simple class definition, for example if one defines a class:

class UserID(int):
pass

then all instances of this class also form a type.

There are also more complex types. E.g., one can define the type
FancyList as all lists containing only instances of int, str
or their subclasses. The value [1, 'abc', UserID(42)] has this type.

It is important for the user to be able to define types in a form
that can be understood by type checkers.
The goal of this PEP is to propose such a systematic way of defining types
for type annotations of variables and functions using PEP 3107 syntax.
These annotations can be used to avoid many kind of bugs, for documentation
purposes, or maybe even to increase speed of program execution.
Here we only focus on avoiding bugs by using a static type checker.

A crucial notion for static type checker is the subtype relationship.
It arises from the question: If first_var has type first_type, and
second_var has type second_type, is it safe to assign
first_var = second_var?

A strong criterion for when it should be safe is:

every value from second_type is also in the set of values
of first_type; and

every function from first_type is also in the set of functions
of second_type.

The relation defined thus is called a subtype relation.

By this definition:

Every type is a subtype of itself.

The set of values becomes smaller in the process of subtyping,
while the set of functions becomes larger.

An intuitive example: Every Dog is an Animal, also Dog
has more functions, for example it can bark, therefore Dog
is a subtype of Animal. Conversely, Animal is not a subtype of Dog.

A more formal example: Integers are subtype of real numbers.
Indeed, every integer is of course also a real number, and integers
support more operations, such as, e.g., bitwise shifts << and >>:

Let us also consider a tricky example: If List[int] denotes the type
formed by all lists containing only integer numbers,
then it is not a subtype of List[float], formed by all lists that contain
only real numbers. The first condition of subtyping holds,
but appending a real number only works with List[float] so that
the second condition fails:

There are two widespread approaches to declare subtype information
to type checker.

In nominal subtyping, the type tree is based on the class tree,
i.e., UserID is considered a subtype of int.
This approach should be used under control of the type checker,
because in Python one can override attributes in an incompatible way:

In structural subtyping the subtype relation is deduced from the
declared methods, i.e., UserID and int would be considered the same type.
While this may occasionally cause confusion,
structural subtyping is considered more flexible.
We strive to provide support for both approaches, so that
structural information can be used in addition to nominal subtyping.

Gradual typing allows one to annotate only part of a program,
thus leverage desirable aspects of both dynamic and static typing.

We define a new relationship, is-consistent-with, which is similar to
is-subtype-of, except it is not transitive when the new type Any is
involved. (Neither relationship is symmetric.) Assigning a_value
to a_variable is OK if the type of a_value is consistent with
the type of a_variable. (Compare this to "... if the type of a_value
is a subtype of the type of a_variable", which states one of the
fundamentals of OO programming.) The is-consistent-with relationship is
defined by three rules:

A type t1 is consistent with a type t2 if t1 is a
subtype of t2. (But not the other way around.)

Any is consistent with every type. (But Any is not a subtype
of every type.)

Every type is consistent with Any. (But every type is not a subtype
of Any.)

That's all! See Jeremy Siek's blog post What is Gradual
Typing
for a longer explanation and motivation. Any can be considered a type
that has all values and all methods. Combined with the definition of
subtyping above, this places Any partially at the top (it has all values)
and bottom (it has all methods) of the type hierarchy. Contrast this to
object -- it is not consistent with
most types (e.g. you can't use an object() instance where an
int is expected). IOW both Any and object mean
"any type is allowed" when used to annotate an argument, but only Any
can be passed no matter what type is expected (in essence, Any
declares a fallback to dynamic typing and shuts up complaints
from the static checker).

Here's an example showing how these rules work out in practice:

Say we have an Employee class, and a subclass Manager:

class Employee: ...
class Manager(Employee): ...

Let's say variable worker is declared with type Employee:

worker = Employee() # type: Employee

Now it's okay to assign a Manager instance to worker (rule 1):

worker = Manager()

It's not okay to assign an Employee instance to a variable declared with
type Manager:

In Python, classes are object factories defined by the class statement,
and returned by the type(obj) built-in function. Class is a dynamic,
runtime concept.

Type concept is described above, types appear in variable
and function type annotations, can be constructed
from building blocks described below, and are used by static type checkers.

Every class is a type as discussed above.
But it is tricky and error prone to implement a class that exactly represents
semantics of a given type, and it is not a goal of PEP 484.
The static types described in PEP 484, should not be confused with
the runtime classes. Examples:

Typing interface is implemented with classes, i.e., at runtime it is possible
to evaluate, e.g., Generic[T].__bases__. But to emphasize the distinction
between classes and types the following general rules apply:

No types defined below (i.e. Any, Union, etc.) can be instantiated,
an attempt to do so will raise TypeError.
(But non-abstract subclasses of Generic can be.)

No types defined below can be subclassed, except for Generic and
classes derived from it.

All of these will raise TypeError if they appear
in isinstance or issubclass (except for unparametrized generics).

Any. Every type is consistent with Any; and
it is also consistent with every type (see above).

Union[t1, t2, ...]. Types that are subtype of at least one of
t1 etc. are subtypes of this.

Unions whose components are all subtypes of t1 etc. are subtypes
of this.
Example: Union[int, str] is a subtype of Union[int, float, str].

The order of the arguments doesn't matter.
Example: Union[int, str] == Union[str, int].

If ti is itself a Union the result is flattened.
Example: Union[int, Union[float, str]] == Union[int, float, str].

If ti and tj have a subtype relationship,
the less specific type survives.
Example: Union[Employee, Manager] == Union[Employee].

Union[t1] returns just t1. Union[] is illegal,
so is Union[()]

Corollary: Union[..., object, ...] returns object.

Optional[t1]. Alias for Union[t1, None], i.e. Union[t1,
type(None)].

Tuple[t1, t2, ..., tn]. A tuple whose items are instances of t1,
etc. Example: Tuple[int, float] means a tuple of two items, the
first is an int, the second is a float; e.g., (42, 3.14).

Tuple[u1, u2, ..., um] is a subtype of Tuple[t1, t2, ..., tn]
if they have the same length n==m and each ui
is a subtype of ti.

To spell the type of the empty tuple, use Tuple[()].

A variadic homogeneous tuple type can be written Tuple[t1, ...].
(That's three dots, a literal ellipsis;
and yes, that's a valid token in Python's syntax.)

Callable[[t1, t2, ..., tn], tr]. A function with positional
argument types t1 etc., and return type tr. The argument list may be
empty n==0. There is no way to indicate optional or keyword
arguments, nor varargs, but you can say the argument list is entirely
unchecked by writing Callable[..., tr] (again, a literal ellipsis).

We might add:

Intersection[t1, t2, ...]. Types that are subtype of each of
t1, etc are subtypes of this. (Compare to Union, which has at
least one instead of each in its definition.)

The interaction between Intersection and Union is complex but
should be no surprise if you understand the interaction between
intersections and unions of regular sets (note that sets of types can be
infinite in size, since there is no limit on the number
of new subclasses).

The fundamental building blocks defined above allow to construct new types
in a generic manner. For example, Tuple can take a concrete type float
and make a concrete type Vector = Tuple[float, ...], or it can take
another type UserID and make another concrete type
Registry = Tuple[UserID, ...]. Such semantics is known as generic type
constructor, it is similar to semantics of functions, but a function takes
a value and returns a value, while generic type constructor takes a type and
"returns" a type.

It is common when a particular class or a function behaves in such a type
generic manner. Consider two examples:

Container classes, such as list or dict, typically contain only
values of a particular type. Therefore, a user might want to type annotate
them as such:

To allow type annotations in situations from the first example, built-in
containers and container abstract base classes are extended with type
parameters, so that they behave as generic type constructors.
Classes, that behave as generic type constructors are called generic types.
Example:

Here Iterable is a generic type that takes a concrete type Task
and returns a concrete type Iterable[Task].

Functions that behave in the type generic manner (as in second example)
are called generic functions.
Type annotations of generic functions are allowed by type variables.
Their semantics with respect to generic types is somewhat similar
to semantics of parameters in functions. But one does not assign
concrete types to type variables, it is the task of a static type checker
to find their possible values and warn the user if it cannot find.
Example:

In this example, both arguments to longest() must have the same type
(str or bytes), and moreover, even if the arguments are instances
of a common str subclass, the return type is still str, not that
subclass (see next example).

For comparison, if the type variable was unconstrained, the common
subclass would be chosen as the return type, e.g.:

Subclassing a generic type imposes the subtype relation on the corresponding
specific types, so that TodoList[t1] is a subtype of Iterable[t1]
in the above example.

Generic types can be specialized (indexed) in several steps.
Every type variable could be substituted by a specific type
or by another generic type. If Generic appears in the base class list,
then it should contain all type variables, and the order of type parameters is
determined by the order in which they appear in Generic. Examples:

If a generic type appears in a type annotation with a type variable omitted,
it is assumed to be Any. Such form could be used as a fallback
to dynamic typing and is allowed for use with issubclass
and isinstance. All type information in instances is erased at runtime.
Examples:

If x1 < x2, then alwayscov(x1) < cov(x2), and
contra(x2) < contra(x1), while nothing could be said about inv.
Replacing < with is-subtype-of, and functions with generic type
constructor we get examples of covariant, contravariant,
and invariant behavior. Let us now consider practical examples:

Union behaves covariantly in all its arguments.
Indeed, as discussed above, Union[t1, t2, ...] is a subtype of
Union[u1, u2, ...], if t1 is a subtype of u1, etc.

FrozenSet[T] is also covariant. Let us consider int and
float in place of T. First, int is a subtype of float.
Second, set of values of FrozenSet[int] is
clearly a subset of values of FrozenSet[float], while set of functions
from FrozenSet[float] is a subset of set of functions
from FrozenSet[int]. Therefore, by definition FrozenSet[int]
is a subtype of FrozenSet[float].

List[T] is invariant. Indeed, although set of values of List[int]
is a subset of values of List[float], only int could be appended
to a List[int], as discussed in section "Background". Therefore,
List[int] is not a subtype of List[float]. This is a typical
situation with mutable types, they are typically invariant.

One of the best examples to illustrate (somewhat counterintuitive)
contravariant behavior is the callable type.
It is covariant in the return type, but contravariant in the
arguments. For two callable types that
differ only in the return type, the subtype relationship for the
callable types follows that of the return types. Examples:

Callable[[], int] is a subtype of Callable[[], float].

Callable[[], Manager] is a subtype of Callable[[], Employee].

While for two callable types that differ
only in the type of one argument, the subtype relationship for the
callable types goes in the opposite direction as for the argument
types. Examples:

Callable[[float], None] is a subtype of Callable[[int], None].

Callable[[Employee], None] is a subtype of Callable[[Manager], None].

Yes, you read that right. Indeed, if
a function that can calculate the salary for a manager is expected:

then Callable[[Employee], Decimal] that can calculate a salary for any
employee is also acceptable.

The example with Callable shows how to make more precise type annotations
for functions: choose the most general type for every argument,
and the most specific type for the return value.

It is possible to declare the variance for user defined generic types by
using special keywords covariant and contravariant in the
definition of type variables used as parameters.
Types are invariant by default. Examples:

Note, that although the variance is defined via type variables, it is not
a property of type variables, but a property of generic types.
In complex definitions of derived generics, variance only
determined from type variables used. A complex example:

A type checker finds from the second declaration that Derived[Manager]
is a subtype of Derived[Employee], and Derived[t1]
is a subtype of Base[t1].
If we denote the is-subtype-of relationship with <, then the
full diagram of subtyping for this case will be:

If a default of None is specified, the type is implicitly
Optional, e.g.:

def get(key: KT, default: VT = None) -> VT: ...

Type variables can be declared in unconstrained, constrained,
or bounded form. The variance of a generic type can also
be indicated using a type variable declared with special keyword
arguments, thus avoiding any special syntax, e.g.: