Notational conventions

• t1,t2, etc. andu1,u2, etc. are types. Sometimes we writeti ortj to refer to “any oft1,t2, etc.”
• T,U etc. are type variables (defined withTypeVar(), see below).
• Objects, classes defined with a class statement, and instances aredenoted using standardPEP 8 conventions.
• the symbol== applied to types in the context of this PEP means thattwo expressions represent the same type.
• Note thatPEP 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 clarifythis distinction but avoid unnecessary strictness to allow moreflexibility in the implementation of type checkers.

Subtype relationships

A crucial notion for static type checker is the subtype relationship.It arises from the question: Iffirst_var has typefirst_type, andsecond_var has typesecond_type, is it safe to assignfirst_var=second_var?

A strong criterion for when itshould be safe is:

• every value fromsecond_type is also in the set of valuesoffirst_type; and
• every function fromfirst_type is also in the set of functionsofsecond_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: EveryDog is anAnimal, alsoDoghas more functions, for example it can bark, thereforeDogis a subtype ofAnimal. Conversely,Animal is not a subtype ofDog.

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

lucky_number=3.14# type: floatlucky_number=42# Safelucky_number*2# This workslucky_number<<5# Failsunlucky_number=13# type: intunlucky_number<<5# This worksunlucky_number=2.72# Unsafe

Let us also consider a tricky example: IfList[int] denotes the typeformed by all lists containing only integer numbers,then it isnot a subtype ofList[float], formed by all lists that containonly real numbers. The first condition of subtyping holds,but appending a real number only works withList[float] so thatthe second condition fails:

defappend_pi(lst:List[float])->None:lst+=[3.14]my_list=[1,3,5]# type: List[int]append_pi(my_list)# Naively, this should be safe...my_list[-1]<<5# ... but this fails

There are two widespread approaches todeclare subtype informationto type checker.

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

classBase:answer='42'# type: strclassDerived(Base):answer=5# should be marked as error by type checker

In structural subtyping the subtype relation is deduced from thedeclared methods, i.e.,UserID andint 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 thatstructural information can be used in addition to nominal subtyping.

Types vs. Classes

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

Type concept is described above, types appear in variableand function type annotations, can be constructedfrom 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 representssemantics of a given type, and it is not a goal ofPEP 484.The static types described inPEP 484should not be confused withthe runtime classes. Examples:

• int is a class and a type.
• UserID is a class and a type.
• Union[str,int] is a type but not a proper class:

  classMyUnion(Union[str,int]):...# raises TypeErrorUnion[str,int]()# raises TypeError

Typing interface is implemented with classes, i.e., at runtime it is possibleto evaluate, e.g.,Generic[T].__bases__. But to emphasize the distinctionbetween 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 raiseTypeError.(But non-abstract subclasses ofGeneric can be.)
• No types defined below can be subclassed, except forGeneric andclasses derived from it.
• All of these will raiseTypeError if they appearinisinstance orissubclass (except for unparameterized generics).

Fundamental building blocks

• Any. Every type is consistent withAny; andit is also consistent with every type (see above).
• Union[t1, t2, …]. Types that are subtype of at least one oft1 etc. are subtypes of this.
  • Unions whose components are all subtypes oft1 etc. are subtypesof this.Example:Union[int,str] is a subtype ofUnion[int,float,str].
  • The order of the arguments doesn’t matter.Example:Union[int,str]==Union[str,int].
  • Ifti is itself aUnion the result is flattened.Example:Union[int,Union[float,str]]==Union[int,float,str].
  • Ifti andtj have a subtype relationship,the less specific type survives.Example:Union[Employee,Manager]==Union[Employee].
  • Union[t1] returns justt1.Union[] is illegal,so isUnion[()]
  • Corollary:Union[...,object,...] returnsobject.
• Optional[t1]. Alias forUnion[t1,None], i.e.Union[t1,type(None)].
• Tuple[t1, t2, …, tn]. A tuple whose items are instances oft1,etc. Example:Tuple[int,float] means a tuple of two items, thefirst is anint, the second is afloat; e.g.,(42,3.14).
  • Tuple[u1,u2,...,um] is a subtype ofTuple[t1,t2,...,tn]if they have the same lengthn==m and eachuiis a subtype ofti.
  • To spell the type of the empty tuple, useTuple[()].
  • A variadic homogeneous tuple type can be writtenTuple[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 positionalargument typest1 etc., and return typetr. The argument list may beemptyn==0. There is no way to indicate optional or keywordarguments, nor varargs, but you can say the argument list is entirelyunchecked by writingCallable[...,tr] (again, a literal ellipsis).

We might add:

• Intersection[t1, t2, …]. Types that are subtype ofeach oft1, etc are subtypes of this. (Compare toUnion, which hasatleast one instead ofeach in its definition.)
  • The order of the arguments doesn’t matter. Nested intersectionsare flattened, e.g.Intersection[int,Intersection[float,str]]==Intersection[int,float,str].
  • An intersection of fewer types is a supertype of an intersection ofmore types, e.g.Intersection[int,str] is a supertypeofIntersection[int,float,str].
  • An intersection of one argument is just that argument,e.g.Intersection[int] isint.
  • When argument have a subtype relationship, the more specific typesurvives, e.g.Intersection[str,Employee,Manager] isIntersection[str,Manager].
  • Intersection[] is illegal, so isIntersection[()].
  • Corollary:Any disappears from the argument list, e.g.Intersection[int,str,Any]==Intersection[int,str].Intersection[Any,object] isobject.
  • The interaction betweenIntersection andUnion is complex butshould be no surprise if you understand the interaction betweenintersections and unions of regular sets (note that sets of types can beinfinite in size, since there is no limit on the numberof new subclasses).

Type variables

X=TypeVar('X') declares a unique type variable. The name must matchthe variable name. By default, a type variable rangesover all possible types. Example:

defdo_nothing(one_arg:T,other_arg:T)->None:passdo_nothing(1,2)# OK, T is intdo_nothing('abc',UserID(42))# also OK, T is object

Y=TypeVar('Y',t1,t2,...). Ditto, constrained tot1, etc. Behavessimilar toUnion[t1,t2,...]. A constrained type variable ranges onlyover constrainst1, etc.exactly; subclasses of the constrains arereplaced by the most-derived base class amongt1, etc. Examples:

• Function type annotation with a constrained type variable:

  AnyStr=TypeVar('AnyStr',str,bytes)deflongest(first:AnyStr,second:AnyStr)->AnyStr:returnfirstiflen(first)>=len(second)elsesecondresult=longest('a','abc')# The inferred type for result is strresult=longest('a',b'abc')# Fails static type check

  In this example, both arguments tolongest() must have the same type(str orbytes), and moreover, even if the arguments are instancesof a commonstr subclass, the return type is stillstr, not thatsubclass (see next example).

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

  S=TypeVar('S')deflongest(first:S,second:S)->S:returnfirstiflen(first)>=len(second)elsesecondclassMyStr(str):...result=longest(MyStr('a'),MyStr('abc'))

  The inferred type ofresult isMyStr (whereas in theAnyStr exampleit would bestr).

• Also for comparison, if aUnion is used, the return type also has to beaUnion:

  U=Union[str,bytes]deflongest(first:U,second:U)->U:returnfirstiflen(first)>=len(second)elsesecondresult=longest('a','abc')

  The inferred type ofresult is stillUnion[str,bytes], even thoughboth arguments arestr.

  Note that the type checker will reject this function:

  defconcat(first:U,second:U)->U:returnfirst+second# Error: can't concatenate str and bytes

  For such cases where parameters could change their types only simultaneouslyone should use constrained type variables.

Defining and using generic types

Users can declare their classes as generic types usingthe special building blockGeneric. The definitionclassMyGeneric(Generic[X,Y,...]):... defines a generic typeMyGeneric over type variablesX, etc.MyGeneric itself becomesparameterizable, e.g.MyGeneric[int,str,...] is a specific type withsubstitutionsX->int, etc. Example:

classCustomQueue(Generic[T]):defput(self,task:T)->None:...defget(self)->T:...defcommunicate(queue:CustomQueue[str])->Optional[str]:...

Classes that derive from generic types become generic.A class can subclass multiple generic types. However,classes derived from specific types returned by generics arenot generic. Examples:

classTodoList(Iterable[T],Container[T]):defcheck(self,item:T)->None:...defcheck_all(todo:TodoList[T])->None:# TodoList is generic...classURLList(Iterable[bytes]):defscrape_all(self)->None:...defsearch(urls:URLList)->Optional[bytes]# URLList is not generic...

Subclassing a generic type imposes the subtype relation on the correspondingspecific types, so thatTodoList[t1] is a subtype ofIterable[t1]in the above example.

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

Table=Dict[int,T]# Table is genericMessages=Table[bytes]# Same as Dict[int, bytes]classBaseGeneric(Generic[T,S]):...classDerivedGeneric(BaseGeneric[int,T]):# DerivedGeneric has one parameter...SpecificType=DerivedGeneric[int]# OKclassMyDictView(Generic[S,T,U],Iterable[Tuple[U,T]]):...Example=MyDictView[list,int,str]# S -> list, T -> int, U -> str

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

defcount(seq:Sequence)->int:# Same as Sequence[Any]...classFrameworkBase(Generic[S,T]):...classUserClass:...issubclass(UserClass,FrameworkBase)# This is OKclassNode(Generic[T]):...IntNode=Node[int]my_node=IntNode()# at runtime my_node.__class__ is Node# inferred static type of my_node is Node[int]

Covariance and Contravariance

Ift2 is a subtype oft1, then a generictype constructorGenType is called:

• Covariant, ifGenType[t2] is a subtype ofGenType[t1]for all sucht1 andt2.
• Contravariant, ifGenType[t1] is a subtype ofGenType[t2]for all sucht1 andt2.
• Invariant, if neither of the above is true.

To better understand this definition, let us make an analogy withordinary functions. Assume that we have:

defcov(x:float)->float:return2*xdefcontra(x:float)->float:return-xdefinv(x:float)->float:returnx*x

Ifx1<x2, thenalwayscov(x1)<cov(x2), andcontra(x2)<contra(x1), while nothing could be said aboutinv.Replacing< with is-subtype-of, and functions with generic typeconstructor 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 ofUnion[u1,u2,...], ift1 is a subtype ofu1, etc.
• FrozenSet[T] is also covariant. Let us considerint andfloat in place ofT. First,int is a subtype offloat.Second, set of values ofFrozenSet[int] isclearly a subset of values ofFrozenSet[float], while set of functionsfromFrozenSet[float] is a subset of set of functionsfromFrozenSet[int]. Therefore, by definitionFrozenSet[int]is a subtype ofFrozenSet[float].
• List[T] is invariant. Indeed, although set of values ofList[int]is a subset of values ofList[float], onlyint could be appendedto aList[int], as discussed in section “Background”. Therefore,List[int] is not a subtype ofList[float]. This is a typicalsituation 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 thearguments. For two callable types thatdiffer only in the return type, the subtype relationship for thecallable types follows that of the return types. Examples:

• Callable[[],int] is a subtype ofCallable[[],float].
• Callable[[],Manager] is a subtype ofCallable[[],Employee].

While for two callable types that differonly in the type of one argument, the subtype relationship for thecallable types goesin the opposite direction as for the argumenttypes. Examples:

• Callable[[float],None] is a subtype ofCallable[[int],None].
• Callable[[Employee],None] is a subtype ofCallable[[Manager],None].

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

defcalculate_all(lst:List[Manager],salary:Callable[[Manager],Decimal]):...

thenCallable[[Employee],Decimal] that can calculate a salary for anyemployee is also acceptable.

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

It is possible todeclare the variance for user defined generic types byusing special keywordscovariant andcontravariant in thedefinition of type variables used as parameters.Types are invariant by default. Examples:

T=TypeVar('T')T_co=TypeVar('T_co',covariant=True)T_contra=TypeVar('T_contra',contravariant=True)classLinkedList(Generic[T]):# invariant by default...defappend(self,element:T)->None:...classBox(Generic[T_co]):#  this type is declared covariantdef__init__(self,content:T_co)->None:self._content=contentdefget_content(self)->T_co:returnself._contentclassSink(Generic[T_contra]):# this type is declared contravariantdefsend_to_nowhere(self,data:T_contra)->None:withopen(os.devnull,'w')asdevnull:print(data,file=devnull)

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

T_co=TypeVar('T_co',Employee,Manager,covariant=True)T_contra=TypeVar('T_contra',Employee,Manager,contravariant=True)classBase(Generic[T_contra]):...classDerived(Base[T_co]):...

A type checker finds from the second declaration thatDerived[Manager]is a subtype ofDerived[Employee], andDerived[t1]is a subtype ofBase[t1].If we denote the is-subtype-of relationship with<, then thefull diagram of subtyping for this case will be:

Base[Manager]>Base[Employee]vvDerived[Manager]<Derived[Employee]

so that a type checker will also find that, e.g.,Derived[Manager] isa subtype ofBase[Employee].

For more information on type variables, generic types, and variance,seePEP 484, themypy docs ongenerics,andWikipedia.

Predefined generic types and Protocols in typing.py

(See also thetyping.py module.)

• Everything fromcollections.abc (butSet renamed toAbstractSet).
• Dict,List,Set,FrozenSet, a few more.
• re.Pattern[AnyStr],re.Match[AnyStr].
• io.IO[AnyStr],io.TextIO~io.IO[str],io.BinaryIO~io.IO[bytes].