typing — Support for type hints¶
New in version 3.5.
Source code:Lib/typing.py
Note
The Python runtime does not enforce function and variable type annotations.They can be used by third party tools such as type checkers, IDEs, linters,etc.
This module provides runtime support for type hints as specified byPEP 484,PEP 526,PEP 544,PEP 586,PEP 589, andPEP 591.The most fundamental support consists of the typesAny,Union,Tuple,Callable,TypeVar, andGeneric. For full specification please seePEP 484. Fora simplified introduction to type hints seePEP 483.
The function below takes and returns a string and is annotated as follows:
defgreeting(name:str)->str:return'Hello '+name
In the functiongreeting, the argumentname is expected to be of typestr and the return typestr. Subtypes are accepted asarguments.
Type aliases¶
A type alias is defined by assigning the type to the alias. In this example,Vector andList[float] will be treated as interchangeable synonyms:
fromtypingimportListVector=List[float]defscale(scalar:float,vector:Vector)->Vector:return[scalar*numfornuminvector]# typechecks; a list of floats qualifies as a Vector.new_vector=scale(2.0,[1.0,-4.2,5.4])
Type aliases are useful for simplifying complex type signatures. For example:
fromtypingimportDict,Tuple,SequenceConnectionOptions=Dict[str,str]Address=Tuple[str,int]Server=Tuple[Address,ConnectionOptions]defbroadcast_message(message:str,servers:Sequence[Server])->None:...# The static type checker will treat the previous type signature as# being exactly equivalent to this one.defbroadcast_message(message:str,servers:Sequence[Tuple[Tuple[str,int],Dict[str,str]]])->None:...
Note thatNone as a type hint is a special case and is replaced bytype(None).
NewType¶
Use theNewType() helper function to create distinct types:
fromtypingimportNewTypeUserId=NewType('UserId',int)some_id=UserId(524313)
The static type checker will treat the new type as if it were a subclassof the original type. This is useful in helping catch logical errors:
defget_user_name(user_id:UserId)->str:...# typechecksuser_a=get_user_name(UserId(42351))# does not typecheck; an int is not a UserIduser_b=get_user_name(-1)
You may still perform allint operations on a variable of typeUserId,but the result will always be of typeint. This lets you pass in aUserId wherever anint might be expected, but will prevent you fromaccidentally creating aUserId in an invalid way:
# 'output' is of type 'int', not 'UserId'output=UserId(23413)+UserId(54341)
Note that these checks are enforced only by the static type checker. At runtime,the statementDerived=NewType('Derived',Base) will makeDerived afunction that immediately returns whatever parameter you pass it. That meansthe expressionDerived(some_value) does not create a new class or introduceany overhead beyond that of a regular function call.
More precisely, the expressionsome_valueisDerived(some_value) is alwaystrue at runtime.
This also means that it is not possible to create a subtype ofDerivedsince it is an identity function at runtime, not an actual type:
fromtypingimportNewTypeUserId=NewType('UserId',int)# Fails at runtime and does not typecheckclassAdminUserId(UserId):pass
However, it is possible to create aNewType() based on a ‘derived’NewType:
fromtypingimportNewTypeUserId=NewType('UserId',int)ProUserId=NewType('ProUserId',UserId)
and typechecking forProUserId will work as expected.
SeePEP 484 for more details.
Note
Recall that the use of a type alias declares two types to beequivalent toone another. DoingAlias=Original will make the static type checkertreatAlias as beingexactly equivalent toOriginal in all cases.This is useful when you want to simplify complex type signatures.
In contrast,NewType declares one type to be asubtype of another.DoingDerived=NewType('Derived',Original) will make the static typechecker treatDerived as asubclass ofOriginal, which means avalue of typeOriginal cannot be used in places where a value of typeDerived is expected. This is useful when you want to prevent logicerrors with minimal runtime cost.
New in version 3.5.2.
Callable¶
Frameworks expecting callback functions of specific signatures might betype hinted usingCallable[[Arg1Type,Arg2Type],ReturnType].
For example:
fromtypingimportCallabledeffeeder(get_next_item:Callable[[],str])->None:# Bodydefasync_query(on_success:Callable[[int],None],on_error:Callable[[int,Exception],None])->None:# Body
It is possible to declare the return type of a callable without specifyingthe call signature by substituting a literal ellipsisfor the list of arguments in the type hint:Callable[...,ReturnType].
Generics¶
Since type information about objects kept in containers cannot be staticallyinferred in a generic way, abstract base classes have been extended to supportsubscription to denote expected types for container elements.
fromtypingimportMapping,Sequencedefnotify_by_email(employees:Sequence[Employee],overrides:Mapping[str,str])->None:...
Generics can be parameterized by using a new factory available in typingcalledTypeVar.
fromtypingimportSequence,TypeVarT=TypeVar('T')# Declare type variabledeffirst(l:Sequence[T])->T:# Generic functionreturnl[0]
User-defined generic types¶
A user-defined class can be defined as a generic class.
fromtypingimportTypeVar,GenericfromloggingimportLoggerT=TypeVar('T')classLoggedVar(Generic[T]):def__init__(self,value:T,name:str,logger:Logger)->None:self.name=nameself.logger=loggerself.value=valuedefset(self,new:T)->None:self.log('Set '+repr(self.value))self.value=newdefget(self)->T:self.log('Get '+repr(self.value))returnself.valuedeflog(self,message:str)->None:self.logger.info('%s:%s',self.name,message)
Generic[T] as a base class defines that the classLoggedVar takes asingle type parameterT . This also makesT valid as a type within theclass body.
TheGeneric base class defines__class_getitem__() so thatLoggedVar[t] is valid as a type:
fromtypingimportIterabledefzero_all_vars(vars:Iterable[LoggedVar[int]])->None:forvarinvars:var.set(0)
A generic type can have any number of type variables, and type variables maybe constrained:
fromtypingimportTypeVar,Generic...T=TypeVar('T')S=TypeVar('S',int,str)classStrangePair(Generic[T,S]):...
Each type variable argument toGeneric must be distinct.This is thus invalid:
fromtypingimportTypeVar,Generic...T=TypeVar('T')classPair(Generic[T,T]):# INVALID...
You can use multiple inheritance withGeneric:
fromtypingimportTypeVar,Generic,SizedT=TypeVar('T')classLinkedList(Sized,Generic[T]):...
When inheriting from generic classes, some type variables could be fixed:
fromtypingimportTypeVar,MappingT=TypeVar('T')classMyDict(Mapping[str,T]):...
In this caseMyDict has a single parameter,T.
Using a generic class without specifying type parameters assumesAny for each position. In the following example,MyIterable isnot generic but implicitly inherits fromIterable[Any]:
fromtypingimportIterableclassMyIterable(Iterable):# Same as Iterable[Any]
User defined generic type aliases are also supported. Examples:
fromtypingimportTypeVar,Iterable,Tuple,UnionS=TypeVar('S')Response=Union[Iterable[S],int]# Return type here is same as Union[Iterable[str], int]defresponse(query:str)->Response[str]:...T=TypeVar('T',int,float,complex)Vec=Iterable[Tuple[T,T]]definproduct(v:Vec[T])->T:# Same as Iterable[Tuple[T, T]]returnsum(x*yforx,yinv)
Changed in version 3.7:Generic no longer has a custom metaclass.
A user-defined generic class can have ABCs as base classes without a metaclassconflict. Generic metaclasses are not supported. The outcome of parameterizinggenerics is cached, and most types in the typing module are hashable andcomparable for equality.
TheAny type¶
A special kind of type isAny. A static type checker will treatevery type as being compatible withAny andAny as beingcompatible with every type.
This means that it is possible to perform any operation or method call on avalue of type onAny and assign it to any variable:
fromtypingimportAnya=None# type: Anya=[]# OKa=2# OKs=''# type: strs=a# OKdeffoo(item:Any)->int:# Typechecks; 'item' could be any type,# and that type might have a 'bar' methoditem.bar()...
Notice that no typechecking is performed when assigning a value of typeAny to a more precise type. For example, the static type checker didnot report an error when assigninga tos even thoughs wasdeclared to be of typestr and receives anint value atruntime!
Furthermore, all functions without a return type or parameter types willimplicitly default to usingAny:
deflegacy_parser(text):...returndata# A static type checker will treat the above# as having the same signature as:deflegacy_parser(text:Any)->Any:...returndata
This behavior allowsAny to be used as anescape hatch when youneed to mix dynamically and statically typed code.
Contrast the behavior ofAny with the behavior ofobject.Similar toAny, every type is a subtype ofobject. However,unlikeAny, the reverse is not true:object isnot asubtype of every other type.
That means when the type of a value isobject, a type checker willreject almost all operations on it, and assigning it to a variable (or usingit as a return value) of a more specialized type is a type error. For example:
defhash_a(item:object)->int:# Fails; an object does not have a 'magic' method.item.magic()...defhash_b(item:Any)->int:# Typechecksitem.magic()...# Typechecks, since ints and strs are subclasses of objecthash_a(42)hash_a("foo")# Typechecks, since Any is compatible with all typeshash_b(42)hash_b("foo")
Useobject to indicate that a value could be any type in a typesafemanner. UseAny to indicate that a value is dynamically typed.
Nominal vs structural subtyping¶
InitiallyPEP 484 defined Python static type system as usingnominal subtyping. This means that a classA is allowed wherea classB is expected if and only ifA is a subclass ofB.
This requirement previously also applied to abstract base classes, such asIterable. The problem with this approach is that a class hadto be explicitly marked to support them, which is unpythonic and unlikewhat one would normally do in idiomatic dynamically typed Python code.For example, this conforms to thePEP 484:
fromtypingimportSized,Iterable,IteratorclassBucket(Sized,Iterable[int]):...def__len__(self)->int:...def__iter__(self)->Iterator[int]:...
PEP 544 allows to solve this problem by allowing users to writethe above code without explicit base classes in the class definition,allowingBucket to be implicitly considered a subtype of bothSizedandIterable[int] by static type checkers. This is known asstructural subtyping (or static duck-typing):
fromtypingimportIterator,IterableclassBucket:# Note: no base classes...def__len__(self)->int:...def__iter__(self)->Iterator[int]:...defcollect(items:Iterable[int])->int:...result=collect(Bucket())# Passes type check
Moreover, by subclassing a special classProtocol, a usercan define new custom protocols to fully enjoy structural subtyping(see examples below).
Classes, functions, and decorators¶
The module defines the following classes, functions and decorators:
- class
typing.TypeVar¶ Type variable.
Usage:
T=TypeVar('T')# Can be anythingA=TypeVar('A',str,bytes)# Must be str or bytes
Type variables exist primarily for the benefit of static typecheckers. They serve as the parameters for generic types as wellas for generic function definitions. See class Generic for moreinformation on generic types. Generic functions work as follows:
defrepeat(x:T,n:int)->Sequence[T]:"""Return a list containing n references to x."""return[x]*ndeflongest(x:A,y:A)->A:"""Return the longest of two strings."""returnxiflen(x)>=len(y)elsey
The latter example’s signature is essentially the overloadingof
(str,str)->strand(bytes,bytes)->bytes. Also notethat if the arguments are instances of some subclass ofstr,the return type is still plainstr.At runtime,
isinstance(x,T)will raiseTypeError. In general,isinstance()andissubclass()should not be used with types.Type variables may be marked covariant or contravariant by passing
covariant=Trueorcontravariant=True. SeePEP 484 for moredetails. By default type variables are invariant. Alternatively,a type variable may specify an upper bound usingbound=<type>.This means that an actual type substituted (explicitly or implicitly)for the type variable must be a subclass of the boundary type,seePEP 484.
- class
typing.Generic¶ Abstract base class for generic types.
A generic type is typically declared by inheriting from aninstantiation of this class with one or more type variables.For example, a generic mapping type might be defined as:
classMapping(Generic[KT,VT]):def__getitem__(self,key:KT)->VT:...# Etc.
This class can then be used as follows:
X=TypeVar('X')Y=TypeVar('Y')deflookup_name(mapping:Mapping[X,Y],key:X,default:Y)->Y:try:returnmapping[key]exceptKeyError:returndefault
- class
typing.Protocol(Generic)¶ Base class for protocol classes. Protocol classes are defined like this:
classProto(Protocol):defmeth(self)->int:...
Such classes are primarily used with static type checkers that recognizestructural subtyping (static duck-typing), for example:
classC:defmeth(self)->int:return0deffunc(x:Proto)->int:returnx.meth()func(C())# Passes static type check
SeePEP 544 for details. Protocol classes decorated with
runtime_checkable()(described later) act as simple-minded runtimeprotocols that check only the presence of given attributes, ignoring theirtype signatures.Protocol classes can be generic, for example:
classGenProto(Protocol[T]):defmeth(self)->T:...
New in version 3.8.
- class
typing.Type(Generic[CT_co])¶ A variable annotated with
Cmay accept a value of typeC. Incontrast, a variable annotated withType[C]may accept values that areclasses themselves – specifically, it will accept theclass object ofC. For example:a=3# Has type 'int'b=int# Has type 'Type[int]'c=type(a)# Also has type 'Type[int]'
Note that
Type[C]is covariant:classUser:...classBasicUser(User):...classProUser(User):...classTeamUser(User):...# Accepts User, BasicUser, ProUser, TeamUser, ...defmake_new_user(user_class:Type[User])->User:# ...returnuser_class()
The fact that
Type[C]is covariant implies that all subclasses ofCshould implement the same constructor signature and class methodsignatures asC. The type checker should flag violations of this,but should also allow constructor calls in subclasses that match theconstructor calls in the indicated base class. How the type checker isrequired to handle this particular case may change in future revisions ofPEP 484.The only legal parameters for
Typeare classes,Any,type variables, and unions of any of these types.For example:defnew_non_team_user(user_class:Type[Union[BaseUser,ProUser]]):...
Type[Any]is equivalent toTypewhich in turn is equivalenttotype, which is the root of Python’s metaclass hierarchy.New in version 3.5.2.
- class
typing.Iterable(Generic[T_co])¶ A generic version of
collections.abc.Iterable.
- class
typing.Iterator(Iterable[T_co])¶ A generic version of
collections.abc.Iterator.
- class
typing.Reversible(Iterable[T_co])¶ A generic version of
collections.abc.Reversible.
- class
typing.SupportsInt¶ An ABC with one abstract method
__int__.
- class
typing.SupportsFloat¶ An ABC with one abstract method
__float__.
- class
typing.SupportsComplex¶ An ABC with one abstract method
__complex__.
- class
typing.SupportsBytes¶ An ABC with one abstract method
__bytes__.
- class
typing.SupportsIndex¶ An ABC with one abstract method
__index__.New in version 3.8.
- class
typing.SupportsAbs¶ An ABC with one abstract method
__abs__that is covariantin its return type.
- class
typing.SupportsRound¶ An ABC with one abstract method
__round__that is covariant in its return type.
- class
typing.Container(Generic[T_co])¶ A generic version of
collections.abc.Container.
- class
typing.Hashable¶ An alias to
collections.abc.Hashable
- class
typing.Sized¶ An alias to
collections.abc.Sized
- class
typing.Collection(Sized, Iterable[T_co], Container[T_co])¶ A generic version of
collections.abc.CollectionNew in version 3.6.0.
- class
typing.AbstractSet(Sized, Collection[T_co])¶ A generic version of
collections.abc.Set.
- class
typing.MutableSet(AbstractSet[T])¶ A generic version of
collections.abc.MutableSet.
- class
typing.Mapping(Sized, Collection[KT], Generic[VT_co])¶ A generic version of
collections.abc.Mapping.This type can be used as follows:defget_position_in_index(word_list:Mapping[str,int],word:str)->int:returnword_list[word]
- class
typing.MutableMapping(Mapping[KT, VT])¶ A generic version of
collections.abc.MutableMapping.
- class
typing.Sequence(Reversible[T_co], Collection[T_co])¶ A generic version of
collections.abc.Sequence.
- class
typing.MutableSequence(Sequence[T])¶ A generic version of
collections.abc.MutableSequence.
- class
typing.ByteString(Sequence[int])¶ A generic version of
collections.abc.ByteString.This type represents the types
bytes,bytearray,andmemoryview.As a shorthand for this type,
bytescan be used toannotate arguments of any of the types mentioned above.
- class
typing.Deque(deque, MutableSequence[T])¶ A generic version of
collections.deque.New in version 3.5.4.
New in version 3.6.1.
- class
typing.List(list, MutableSequence[T])¶ Generic version of
list.Useful for annotating return types. To annotate arguments it is preferredto use an abstract collection type such asSequenceorIterable.This type may be used as follows:
T=TypeVar('T',int,float)defvec2(x:T,y:T)->List[T]:return[x,y]defkeep_positives(vector:Sequence[T])->List[T]:return[itemforiteminvectorifitem>0]
- class
typing.Set(set, MutableSet[T])¶ A generic version of
builtins.set.Useful for annotating return types. To annotate arguments it is preferredto use an abstract collection type such asAbstractSet.
- class
typing.FrozenSet(frozenset, AbstractSet[T_co])¶ A generic version of
builtins.frozenset.
- class
typing.MappingView(Sized, Iterable[T_co])¶ A generic version of
collections.abc.MappingView.
- class
typing.KeysView(MappingView[KT_co], AbstractSet[KT_co])¶ A generic version of
collections.abc.KeysView.
- class
typing.ItemsView(MappingView, Generic[KT_co, VT_co])¶ A generic version of
collections.abc.ItemsView.
- class
typing.ValuesView(MappingView[VT_co])¶ A generic version of
collections.abc.ValuesView.
- class
typing.Awaitable(Generic[T_co])¶ A generic version of
collections.abc.Awaitable.New in version 3.5.2.
- class
typing.Coroutine(Awaitable[V_co], Generic[T_co T_contra, V_co])¶ A generic version of
collections.abc.Coroutine.The variance and order of type variablescorrespond to those ofGenerator, for example:fromtypingimportList,Coroutinec=None# type: Coroutine[List[str], str, int]...x=c.send('hi')# type: List[str]asyncdefbar()->None:x=awaitc# type: int
New in version 3.5.3.
- class
typing.AsyncIterable(Generic[T_co])¶ A generic version of
collections.abc.AsyncIterable.New in version 3.5.2.
- class
typing.AsyncIterator(AsyncIterable[T_co])¶ A generic version of
collections.abc.AsyncIterator.New in version 3.5.2.
- class
typing.ContextManager(Generic[T_co])¶ A generic version of
contextlib.AbstractContextManager.New in version 3.5.4.
New in version 3.6.0.
- class
typing.AsyncContextManager(Generic[T_co])¶ A generic version of
contextlib.AbstractAsyncContextManager.New in version 3.5.4.
New in version 3.6.2.
- class
typing.Dict(dict, MutableMapping[KT, VT])¶ A generic version of
dict.Useful for annotating return types. To annotate arguments it is preferredto use an abstract collection type such asMapping.This type can be used as follows:
defcount_words(text:str)->Dict[str,int]:...
- class
typing.DefaultDict(collections.defaultdict, MutableMapping[KT, VT])¶ A generic version of
collections.defaultdict.New in version 3.5.2.
- class
typing.OrderedDict(collections.OrderedDict, MutableMapping[KT, VT])¶ A generic version of
collections.OrderedDict.New in version 3.7.2.
- class
typing.Counter(collections.Counter, Dict[T, int])¶ A generic version of
collections.Counter.New in version 3.5.4.
New in version 3.6.1.
- class
typing.ChainMap(collections.ChainMap, MutableMapping[KT, VT])¶ A generic version of
collections.ChainMap.New in version 3.5.4.
New in version 3.6.1.
- class
typing.Generator(Iterator[T_co], Generic[T_co, T_contra, V_co])¶ A generator can be annotated by the generic type
Generator[YieldType,SendType,ReturnType]. For example:defecho_round()->Generator[int,float,str]:sent=yield0whilesent>=0:sent=yieldround(sent)return'Done'
Note that unlike many other generics in the typing module, the
SendTypeofGeneratorbehaves contravariantly, not covariantly orinvariantly.If your generator will only yield values, set the
SendTypeandReturnTypetoNone:definfinite_stream(start:int)->Generator[int,None,None]:whileTrue:yieldstartstart+=1
Alternatively, annotate your generator as having a return type ofeither
Iterable[YieldType]orIterator[YieldType]:definfinite_stream(start:int)->Iterator[int]:whileTrue:yieldstartstart+=1
- class
typing.AsyncGenerator(AsyncIterator[T_co], Generic[T_co, T_contra])¶ An async generator can be annotated by the generic type
AsyncGenerator[YieldType,SendType]. For example:asyncdefecho_round()->AsyncGenerator[int,float]:sent=yield0whilesent>=0.0:rounded=awaitround(sent)sent=yieldrounded
Unlike normal generators, async generators cannot return a value, so thereis no
ReturnTypetype parameter. As withGenerator, theSendTypebehaves contravariantly.If your generator will only yield values, set the
SendTypetoNone:asyncdefinfinite_stream(start:int)->AsyncGenerator[int,None]:whileTrue:yieldstartstart=awaitincrement(start)
Alternatively, annotate your generator as having a return type ofeither
AsyncIterable[YieldType]orAsyncIterator[YieldType]:asyncdefinfinite_stream(start:int)->AsyncIterator[int]:whileTrue:yieldstartstart=awaitincrement(start)
New in version 3.6.1.
- class
typing.Text¶ Textis an alias forstr. It is provided to supply a forwardcompatible path for Python 2 code: in Python 2,Textis an alias forunicode.Use
Textto indicate that a value must contain a unicode string ina manner that is compatible with both Python 2 and Python 3:defadd_unicode_checkmark(text:Text)->Text:returntext+u'\u2713'
New in version 3.5.2.
- class
typing.IO¶ - class
typing.TextIO¶ - class
typing.BinaryIO¶ Generic type
IO[AnyStr]and its subclassesTextIO(IO[str])andBinaryIO(IO[bytes])represent the types of I/O streams such as returned byopen().
- class
typing.Pattern¶ - class
typing.Match¶ These type aliasescorrespond to the return types from
re.compile()andre.match(). These types (and the corresponding functions)are generic inAnyStrand can be made specific by writingPattern[str],Pattern[bytes],Match[str], orMatch[bytes].
- class
typing.NamedTuple¶ Typed version of
collections.namedtuple().Usage:
classEmployee(NamedTuple):name:strid:int
This is equivalent to:
Employee=collections.namedtuple('Employee',['name','id'])
To give a field a default value, you can assign to it in the class body:
classEmployee(NamedTuple):name:strid:int=3employee=Employee('Guido')assertemployee.id==3
Fields with a default value must come after any fields without a default.
The resulting class has an extra attribute
__annotations__giving adict that maps the field names to the field types. (The field names are inthe_fieldsattribute and the default values are in the_field_defaultsattribute both of which are part of the namedtupleAPI.)NamedTuplesubclasses can also have docstrings and methods:classEmployee(NamedTuple):"""Represents an employee."""name:strid:int=3def__repr__(self)->str:returnf'<Employee{self.name}, id={self.id}>'
Backward-compatible usage:
Employee=NamedTuple('Employee',[('name',str),('id',int)])
Changed in version 3.6:Added support forPEP 526 variable annotation syntax.
Changed in version 3.6.1:Added support for default values, methods, and docstrings.
Changed in version 3.8:Deprecated the
_field_typesattribute in favor of the morestandard__annotations__attribute which has the same information.Changed in version 3.8:The
_field_typesand__annotations__attributes arenow regular dictionaries instead of instances ofOrderedDict.
- class
typing.TypedDict(dict)¶ A simple typed namespace. At runtime it is equivalent toa plain
dict.TypedDictcreates a dictionary type that expects all of itsinstances to have a certain set of keys, where each key isassociated with a value of a consistent type. This expectationis not checked at runtime but is only enforced by type checkers.Usage:classPoint2D(TypedDict):x:inty:intlabel:stra:Point2D={'x':1,'y':2,'label':'good'}# OKb:Point2D={'z':3,'label':'bad'}# Fails type checkassertPoint2D(x=1,y=2,label='first')==dict(x=1,y=2,label='first')
The type info for introspection can be accessed via
Point2D.__annotations__andPoint2D.__total__. To allow using this feature with older versionsof Python that do not supportPEP 526,TypedDictsupports two additionalequivalent syntactic forms:Point2D=TypedDict('Point2D',x=int,y=int,label=str)Point2D=TypedDict('Point2D',{'x':int,'y':int,'label':str})
By default, all keys must be present in a TypedDict. It is possibleto override this by specifying totality.Usage:
classpoint2D(TypedDict,total=False):x:inty:int
This means that a point2D TypedDict can have any of the keys omitted.A typechecker is only expected to support a literal False or True as the value ofthe total argument. True is the default, and makes all items defined in theclass body be required.
SeePEP 589 for more examples and detailed rules of using
TypedDict.New in version 3.8.
- class
typing.ForwardRef¶ A class used for internal typing representation of string forward references.For example,
List["SomeClass"]is implicitly transformed intoList[ForwardRef("SomeClass")]. This class should not be instantiated bya user, but may be used by introspection tools.
typing.NewType(typ)¶A helper function to indicate a distinct types to a typechecker,seeNewType. At runtime it returns a function that returnsits argument. Usage:
UserId=NewType('UserId',int)first_user=UserId(1)
New in version 3.5.2.
typing.cast(typ,val)¶Cast a value to a type.
This returns the value unchanged. To the type checker thissignals that the return value has the designated type, but atruntime we intentionally don’t check anything (we want thisto be as fast as possible).
typing.get_type_hints(obj[,globals[,locals]])¶Return a dictionary containing type hints for a function, method, moduleor class object.
This is often the same as
obj.__annotations__. In addition,forward references encoded as string literals are handled by evaluatingthem inglobalsandlocalsnamespaces. If necessary,Optional[t]is added for function and method annotations if a defaultvalue equal toNoneis set. For a classC, returna dictionary constructed by merging all the__annotations__alongC.__mro__in reverse order.
typing.get_origin(tp)¶
typing.get_args(tp)¶Provide basic introspection for generic types and special typing forms.
For a typing object of the form
X[Y,Z,...]these functions returnXand(Y,Z,...). IfXis a generic alias for a builtin orcollectionsclass, it gets normalized to the original class.For unsupported objects returnNoneand()correspondingly.Examples:assertget_origin(Dict[str,int])isdictassertget_args(Dict[int,str])==(int,str)assertget_origin(Union[int,str])isUnionassertget_args(Union[int,str])==(int,str)
New in version 3.8.
@typing.overload¶The
@overloaddecorator allows describing functions and methodsthat support multiple different combinations of argument types. A seriesof@overload-decorated definitions must be followed by exactly onenon-@overload-decorated definition (for the same function/method).The@overload-decorated definitions are for the benefit of thetype checker only, since they will be overwritten by thenon-@overload-decorated definition, while the latter is used atruntime but should be ignored by a type checker. At runtime, callinga@overload-decorated function directly will raiseNotImplementedError. An example of overload that gives a moreprecise type than can be expressed using a union or a type variable:@overloaddefprocess(response:None)->None:...@overloaddefprocess(response:int)->Tuple[int,str]:...@overloaddefprocess(response:bytes)->str:...defprocess(response):<actualimplementation>
SeePEP 484 for details and comparison with other typing semantics.
@typing.final¶A decorator to indicate to type checkers that the decorated methodcannot be overridden, and the decorated class cannot be subclassed.For example:
classBase:@finaldefdone(self)->None:...classSub(Base):defdone(self)->None:# Error reported by type checker...@finalclassLeaf:...classOther(Leaf):# Error reported by type checker...
There is no runtime checking of these properties. SeePEP 591 formore details.
New in version 3.8.
@typing.no_type_check¶Decorator to indicate that annotations are not type hints.
This works as class or functiondecorator. With a class, itapplies recursively to all methods defined in that class (but notto methods defined in its superclasses or subclasses).
This mutates the function(s) in place.
@typing.no_type_check_decorator¶Decorator to give another decorator the
no_type_check()effect.This wraps the decorator with something that wraps the decoratedfunction in
no_type_check().
@typing.type_check_only¶Decorator to mark a class or function to be unavailable at runtime.
This decorator is itself not available at runtime. It is mainlyintended to mark classes that are defined in type stub files ifan implementation returns an instance of a private class:
@type_check_onlyclassResponse:# private or not available at runtimecode:intdefget_header(self,name:str)->str:...deffetch_response()->Response:...
Note that returning instances of private classes is not recommended.It is usually preferable to make such classes public.
@typing.runtime_checkable¶Mark a protocol class as a runtime protocol.
Such a protocol can be used with
isinstance()andissubclass().This raisesTypeErrorwhen applied to a non-protocol class. Thisallows a simple-minded structural check, very similar to “one trick ponies”incollections.abcsuch asIterable. For example:@runtime_checkableclassClosable(Protocol):defclose(self):...assertisinstance(open('/some/file'),Closable)
Warning: this will check only the presence of the required methods,not their type signatures!
New in version 3.8.
typing.Any¶Special type indicating an unconstrained type.
typing.NoReturn¶Special type indicating that a function never returns.For example:
fromtypingimportNoReturndefstop()->NoReturn:raiseRuntimeError('no way')
New in version 3.5.4.
New in version 3.6.2.
typing.Union¶Union type;
Union[X,Y]means either X or Y.To define a union, use e.g.
Union[int,str]. Details:The arguments must be types and there must be at least one.
Unions of unions are flattened, e.g.:
Union[Union[int,str],float]==Union[int,str,float]
Unions of a single argument vanish, e.g.:
Union[int]==int# The constructor actually returns int
Redundant arguments are skipped, e.g.:
Union[int,str,int]==Union[int,str]
When comparing unions, the argument order is ignored, e.g.:
Union[int,str]==Union[str,int]
You cannot subclass or instantiate a union.
You cannot write
Union[X][Y].You can use
Optional[X]as a shorthand forUnion[X,None].
Changed in version 3.7:Don’t remove explicit subclasses from unions at runtime.
typing.Optional¶Optional type.
Optional[X]is equivalent toUnion[X,None].Note that this is not the same concept as an optional argument,which is one that has a default. An optional argument with adefault does not require the
Optionalqualifier on its typeannotation just because it is optional. For example:deffoo(arg:int=0)->None:...
On the other hand, if an explicit value of
Noneis allowed, theuse ofOptionalis appropriate, whether the argument is optionalor not. For example:deffoo(arg:Optional[int]=None)->None:...
typing.Tuple¶Tuple type;
Tuple[X,Y]is the type of a tuple of two itemswith the first item of type X and the second of type Y. The type ofthe empty tuple can be written asTuple[()].Example:
Tuple[T1,T2]is a tuple of two elements correspondingto type variables T1 and T2.Tuple[int,float,str]is a tupleof an int, a float and a string.To specify a variable-length tuple of homogeneous type,use literal ellipsis, e.g.
Tuple[int,...]. A plainTupleis equivalent toTuple[Any,...], and in turn totuple.
typing.Callable¶Callable type;
Callable[[int],str]is a function of (int) -> str.The subscription syntax must always be used with exactly twovalues: the argument list and the return type. The argument listmust be a list of types or an ellipsis; the return type must bea single type.
There is no syntax to indicate optional or keyword arguments;such function types are rarely used as callback types.
Callable[...,ReturnType](literal ellipsis) can be used totype hint a callable taking any number of arguments and returningReturnType. A plainCallableis equivalent toCallable[...,Any], and in turn tocollections.abc.Callable.
typing.Literal¶A type that can be used to indicate to type checkers that thecorresponding variable or function parameter has a value equivalent tothe provided literal (or one of several literals). For example:
defvalidate_simple(data:Any)->Literal[True]:# always returns True...MODE=Literal['r','rb','w','wb']defopen_helper(file:str,mode:MODE)->str:...open_helper('/some/path','r')# Passes type checkopen_helper('/other/path','typo')# Error in type checker
Literal[...]cannot be subclassed. At runtime, an arbitrary valueis allowed as type argument toLiteral[...], but type checkers mayimpose restrictions. SeePEP 586 for more details about literal types.New in version 3.8.
typing.ClassVar¶Special type construct to mark class variables.
As introduced inPEP 526, a variable annotation wrapped in ClassVarindicates that a given attribute is intended to be used as a class variableand should not be set on instances of that class. Usage:
classStarship:stats:ClassVar[Dict[str,int]]={}# class variabledamage:int=10# instance variable
ClassVaraccepts only types and cannot be further subscribed.ClassVaris not a class itself, and should notbe used withisinstance()orissubclass().ClassVardoes not change Python runtime behavior, butit can be used by third-party type checkers. For example, a type checkermight flag the following code as an error:enterprise_d=Starship(3000)enterprise_d.stats={}# Error, setting class variable on instanceStarship.stats={}# This is OK
New in version 3.5.3.
typing.Final¶A special typing construct to indicate to type checkers that a namecannot be re-assigned or overridden in a subclass. For example:
MAX_SIZE:Final=9000MAX_SIZE+=1# Error reported by type checkerclassConnection:TIMEOUT:Final[int]=10classFastConnector(Connection):TIMEOUT=1# Error reported by type checker
There is no runtime checking of these properties. SeePEP 591 formore details.
New in version 3.8.
typing.AnyStr¶AnyStris a type variable defined asAnyStr=TypeVar('AnyStr',str,bytes).It is meant to be used for functions that may accept any kind of stringwithout allowing different kinds of strings to mix. For example:
defconcat(a:AnyStr,b:AnyStr)->AnyStr:returna+bconcat(u"foo",u"bar")# Ok, output has type 'unicode'concat(b"foo",b"bar")# Ok, output has type 'bytes'concat(u"foo",b"bar")# Error, cannot mix unicode and bytes
typing.TYPE_CHECKING¶A special constant that is assumed to be
Trueby 3rd party statictype checkers. It isFalseat runtime. Usage:ifTYPE_CHECKING:importexpensive_moddeffun(arg:'expensive_mod.SomeType')->None:local_var:expensive_mod.AnotherType=other_fun()
Note that the first type annotation must be enclosed in quotes, making it a“forward reference”, to hide the
expensive_modreference from theinterpreter runtime. Type annotations for local variables are notevaluated, so the second annotation does not need to be enclosed in quotes.New in version 3.5.2.