`typing` — Support for type hints¶

Added in version 3.5.

Note

The Python runtime does not enforce function and variable type annotations.They can be used by third party tools such astype checkers,IDEs, linters, etc.

This module provides runtime support for type hints.

Consider the function below:

defsurface_area_of_cube(edge_length:float)->str:returnf"The surface area of the cube is{6*edge_length**2}."

The functionsurface_area_of_cube takes an argument expected tobe an instance offloat, as indicated by thetype hintedge_length:float. The function is expected to return an instanceofstr, as indicated by the->str hint.

While type hints can be simple classes likefloat orstr,they can also be more complex. Thetyping module provides a vocabulary ofmore advanced type hints.

New features are frequently added to thetyping module.Thetyping_extensions packageprovides backports of these new features to older versions of Python.

See also

Typing cheat sheet: A quick overview of type hints (hosted at the mypy docs)
Type System Reference section ofthe mypy docs: The Python typing system is standardised via PEPs, so this referenceshould broadly apply to most Python type checkers. (Some parts may stillbe specific to mypy.)
Static Typing with Python: Type-checker-agnostic documentation written by the community detailingtype system features, useful typing related tools and typing bestpractices.

Specification for the Python Type System¶

The canonical, up-to-date specification of the Python type system can befound atSpecification for the Python type system.

Type aliases¶

A type alias is defined using thetype statement, which createsan instance ofTypeAliasType. In this example,Vector andlist[float] will be treated equivalently by static typecheckers:

typeVector=list[float]defscale(scalar:float,vector:Vector)->Vector:return[scalar*numfornuminvector]# passes type checking; 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:

fromcollections.abcimportSequencetypeConnectionOptions=dict[str,str]typeAddress=tuple[str,int]typeServer=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:...

Thetype statement is new in Python 3.12. For backwardscompatibility, type aliases can also be created through simple assignment:

Vector=list[float]

Or marked withTypeAlias to make it explicit that this is a type alias,not a normal variable assignment:

fromtypingimportTypeAliasVector:TypeAlias=list[float]

NewType¶

Use theNewType helper 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:...# passes type checkinguser_a=get_user_name(UserId(42351))# fails type checking; 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 acallable that immediately returns whatever parameter you pass it. That meansthe expressionDerived(some_value) does not create a new class or introducemuch overhead beyond that of a regular function call.

More precisely, the expressionsome_valueisDerived(some_value) is alwaystrue at runtime.

It is invalid to create a subtype ofDerived:

fromtypingimportNewTypeUserId=NewType('UserId',int)# Fails at runtime and does not pass type checkingclassAdminUserId(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. DoingtypeAlias=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.

Added in version 3.5.2.

Changed in version 3.10:NewType is now a class rather than a function. As a result, there issome additional runtime cost when callingNewType over a regularfunction.

Changed in version 3.11:The performance of callingNewType has been restored to its level inPython 3.9.

Annotating callable objects¶

Functions – or othercallable objects – can be annotated usingcollections.abc.Callable or deprecatedtyping.Callable.Callable[[int],str] signifies a function that takes a single parameterof typeint and returns astr.

For example:

fromcollections.abcimportCallable,Awaitabledeffeeder(get_next_item:Callable[[],str])->None:...# Bodydefasync_query(on_success:Callable[[int],None],on_error:Callable[[int,Exception],None])->None:...# Bodyasyncdefon_update(value:str)->None:...# Bodycallback:Callable[[str],Awaitable[None]]=on_update

The subscription syntax must always be used with exactly two values: theargument list and the return type. The argument list must be a list of types,aParamSpec,Concatenate, or an ellipsis (...). The return type mustbe a single type.

If a literal ellipsis... is given as the argument list, it indicates thata callable with any arbitrary parameter list would be acceptable:

defconcat(x:str,y:str)->str:returnx+yx:Callable[...,str]x=str# OKx=concat# Also OK

Callable cannot express complex signatures such as functions that take avariadic number of arguments,overloaded functions, orfunctions that have keyword-only parameters. However, these signatures can beexpressed by defining aProtocol class with a__call__() method:

fromcollections.abcimportIterablefromtypingimportProtocolclassCombiner(Protocol):def__call__(self,*vals:bytes,maxlen:int|None=None)->list[bytes]:...defbatch_proc(data:Iterable[bytes],cb_results:Combiner)->bytes:foritemindata:...defgood_cb(*vals:bytes,maxlen:int|None=None)->list[bytes]:...defbad_cb(*vals:bytes,maxitems:int|None)->list[bytes]:...batch_proc([],good_cb)# OKbatch_proc([],bad_cb)# Error! Argument 2 has incompatible type because of# different name and kind in the callback

Callables which take other callables as arguments may indicate that theirparameter types are dependent on each other usingParamSpec.Additionally, if that callable adds or removes arguments from othercallables, theConcatenate operator may be used. Theytake the formCallable[ParamSpecVariable,ReturnType] andCallable[Concatenate[Arg1Type,Arg2Type,...,ParamSpecVariable],ReturnType]respectively.

Changed in version 3.10:Callable now supportsParamSpec andConcatenate.SeePEP 612 for more details.

See also

The documentation forParamSpec andConcatenate providesexamples of usage inCallable.

Generics¶

Since type information about objects kept in containers cannot be staticallyinferred in a generic way, many container classes in the standard library supportsubscription to denote the expected types of container elements.

fromcollections.abcimportMapping,SequenceclassEmployee:...# Sequence[Employee] indicates that all elements in the sequence# must be instances of "Employee".# Mapping[str, str] indicates that all keys and all values in the mapping# must be strings.defnotify_by_email(employees:Sequence[Employee],overrides:Mapping[str,str])->None:...

Generic functions and classes can be parameterized by usingtype parameter syntax:

fromcollections.abcimportSequencedeffirst[T](l:Sequence[T])->T:# Function is generic over the TypeVar "T"returnl[0]

Or by using theTypeVar factory directly:

fromcollections.abcimportSequencefromtypingimportTypeVarU=TypeVar('U')# Declare type variable "U"defsecond(l:Sequence[U])->U:# Function is generic over the TypeVar "U"returnl[1]

Changed in version 3.12:Syntactic support for generics is new in Python 3.12.

Annotating tuples¶

For most containers in Python, the typing system assumes that all elements inthe container will be of the same type. For example:

fromcollections.abcimportMapping# Type checker will infer that all elements in ``x`` are meant to be intsx:list[int]=[]# Type checker error: ``list`` only accepts a single type argument:y:list[int,str]=[1,'foo']# Type checker will infer that all keys in ``z`` are meant to be strings,# and that all values in ``z`` are meant to be either strings or intsz:Mapping[str,str|int]={}

list only accepts one type argument, so a type checker would emit anerror on they assignment above. Similarly,Mapping only accepts two type arguments: the firstindicates the type of the keys, and the second indicates the type of thevalues.

Unlike most other Python containers, however, it is common in idiomatic Pythoncode for tuples to have elements which are not all of the same type. For thisreason, tuples are special-cased in Python’s typing system.tupleacceptsany number of type arguments:

# OK: ``x`` is assigned to a tuple of length 1 where the sole element is an intx:tuple[int]=(5,)# OK: ``y`` is assigned to a tuple of length 2;# element 1 is an int, element 2 is a stry:tuple[int,str]=(5,"foo")# Error: the type annotation indicates a tuple of length 1,# but ``z`` has been assigned to a tuple of length 3z:tuple[int]=(1,2,3)

To denote a tuple which could be ofany length, and in which all elements areof the same typeT, use the literal ellipsis...:tuple[T,...].To denote an empty tuple, usetuple[()]. Using plaintuple as an annotation is equivalent to usingtuple[Any,...]:

x:tuple[int,...]=(1,2)# These reassignments are OK: ``tuple[int, ...]`` indicates x can be of any lengthx=(1,2,3)x=()# This reassignment is an error: all elements in ``x`` must be intsx=("foo","bar")# ``y`` can only ever be assigned to an empty tupley:tuple[()]=()z:tuple=("foo","bar")# These reassignments are OK: plain ``tuple`` is equivalent to ``tuple[Any, ...]``z=(1,2,3)z=()

The type of class objects¶

A variable annotated withC may accept a value of typeC. Incontrast, a variable annotated withtype[C] (or deprecatedtyping.Type[C]) may accept values that are classesthemselves – specifically, it will accept theclass object ofC. Forexample:

a=3# Has type ``int``b=int# Has type ``type[int]``c=type(a)# Also has type ``type[int]``

Note thattype[C] is covariant:

classUser:...classProUser(User):...classTeamUser(User):...defmake_new_user(user_class:type[User])->User:# ...returnuser_class()make_new_user(User)# OKmake_new_user(ProUser)# Also OK: ``type[ProUser]`` is a subtype of ``type[User]``make_new_user(TeamUser)# Still finemake_new_user(User())# Error: expected ``type[User]`` but got ``User``make_new_user(int)# Error: ``type[int]`` is not a subtype of ``type[User]``

The only legal parameters fortype are classes,Any,type variables, and unions of any of these types.For example:

defnew_non_team_user(user_class:type[BasicUser|ProUser]):...new_non_team_user(BasicUser)# OKnew_non_team_user(ProUser)# OKnew_non_team_user(TeamUser)# Error: ``type[TeamUser]`` is not a subtype# of ``type[BasicUser | ProUser]``new_non_team_user(User)# Also an error

type[Any] is equivalent totype, which is the root of Python’smetaclass hierarchy.

Annotating generators and coroutines¶

A generator can be annotated using the generic typeGenerator[YieldType,SendType,ReturnType].For example:

defecho_round()->Generator[int,float,str]:sent=yield0whilesent>=0:sent=yieldround(sent)return'Done'

Note that unlike many other generic classes in the standard library,theSendType ofGenerator behavescontravariantly, not covariantly or invariantly.

TheSendType andReturnType parameters default toNone:

definfinite_stream(start:int)->Generator[int]:whileTrue:yieldstartstart+=1

It is also possible to set these types explicitly:

definfinite_stream(start:int)->Generator[int,None,None]:whileTrue:yieldstartstart+=1

Simple generators that only ever yield values can also be annotatedas having a return type of eitherIterable[YieldType]orIterator[YieldType]:

definfinite_stream(start:int)->Iterator[int]:whileTrue:yieldstartstart+=1

Async generators are handled in a similar fashion, but don’texpect aReturnType type argument(AsyncGenerator[YieldType,SendType]).TheSendType argument defaults toNone, so the following definitionsare equivalent:

asyncdefinfinite_stream(start:int)->AsyncGenerator[int]:whileTrue:yieldstartstart=awaitincrement(start)asyncdefinfinite_stream(start:int)->AsyncGenerator[int,None]:whileTrue:yieldstartstart=awaitincrement(start)

As in the synchronous case,AsyncIterable[YieldType]andAsyncIterator[YieldType] areavailable as well:

asyncdefinfinite_stream(start:int)->AsyncIterator[int]:whileTrue:yieldstartstart=awaitincrement(start)

Coroutines can be annotated usingCoroutine[YieldType,SendType,ReturnType].Generic arguments correspond to those ofGenerator,for example:

fromcollections.abcimportCoroutinec:Coroutine[list[str],str,int]# Some coroutine defined elsewherex=c.send('hi')# Inferred type of 'x' is list[str]asyncdefbar()->None:y=awaitc# Inferred type of 'y' is int

User-defined generic types¶

A user-defined class can be defined as a generic class.

fromloggingimportLoggerclassLoggedVar[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)

This syntax indicates that the classLoggedVar is parameterised around asingletype variableT . This also makesT valid asa type within the class body.

Generic classes implicitly inherit fromGeneric. For compatibilitywith Python 3.11 and lower, it is also possible to inherit explicitly fromGeneric to indicate a generic class:

fromtypingimportTypeVar,GenericT=TypeVar('T')classLoggedVar(Generic[T]):...

Generic classes have__class_getitem__() methods, meaning theycan be parameterised at runtime (e.g.LoggedVar[int] below):

fromcollections.abcimportIterabledefzero_all_vars(vars:Iterable[LoggedVar[int]])->None:forvarinvars:var.set(0)

A generic type can have any number of type variables. All varieties ofTypeVar are permissible as parameters for a generic type:

fromtypingimportTypeVar,Generic,SequenceclassWeirdTrio[T,B:Sequence[bytes],S:(int,str)]:...OldT=TypeVar('OldT',contravariant=True)OldB=TypeVar('OldB',bound=Sequence[bytes],covariant=True)OldS=TypeVar('OldS',int,str)classOldWeirdTrio(Generic[OldT,OldB,OldS]):...

Each type variable argument toGeneric must be distinct.This is thus invalid:

fromtypingimportTypeVar,Generic...classPair[M,M]:# SyntaxError...T=TypeVar('T')classPair(Generic[T,T]):# INVALID...

Generic classes can also inherit from other classes:

fromcollections.abcimportSizedclassLinkedList[T](Sized):...

When inheriting from generic classes, some type parameters could be fixed:

fromcollections.abcimportMappingclassMyDict[T](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]:

fromcollections.abcimportIterableclassMyIterable(Iterable):# Same as Iterable[Any]...

User-defined generic type aliases are also supported. Examples:

fromcollections.abcimportIterabletypeResponse[S]=Iterable[S]|int# Return type here is same as Iterable[str] | intdefresponse(query:str)->Response[str]:...typeVec[T]=Iterable[tuple[T,T]]definproduct[T:(int,float,complex)](v:Vec[T])->T:# Same as Iterable[tuple[T, T]]returnsum(x*yforx,yinv)

For backward compatibility, generic type aliases can also be createdthrough a simple assignment:

fromcollections.abcimportIterablefromtypingimportTypeVarS=TypeVar("S")Response=Iterable[S]|int

Changed in version 3.7:Generic no longer has a custom metaclass.

Changed in version 3.12:Syntactic support for generics and type aliases is new in version 3.12.Previously, generic classes had to explicitly inherit fromGenericor contain a type variable in one of their bases.

User-defined generics for parameter expressions are also supported via parameterspecification variables in the form[**P]. The behavior is consistentwith type variables’ described above as parameter specification variables aretreated by thetyping module as a specialized type variable. The one exceptionto this is that a list of types can be used to substitute aParamSpec:

>>>classZ[T,**P]:...# T is a TypeVar; P is a ParamSpec...>>>Z[int,[dict,float]]__main__.Z[int, [dict, float]]

Classes generic over aParamSpec can also be created using explicitinheritance fromGeneric. In this case,** is not used:

fromtypingimportParamSpec,GenericP=ParamSpec('P')classZ(Generic[P]):...

Another difference betweenTypeVar andParamSpec is that ageneric with only one parameter specification variable will acceptparameter lists in the formsX[[Type1,Type2,...]] and alsoX[Type1,Type2,...] for aesthetic reasons. Internally, the latter is convertedto the former, so the following are equivalent:

>>>classX[**P]:......>>>X[int,str]__main__.X[[int, str]]>>>X[[int,str]]__main__.X[[int, str]]

Note that generics withParamSpec may not have correct__parameters__ after substitution in some cases because theyare intended primarily for static type checking.

Changed in version 3.10:Generic can now be parameterized over parameter expressions.SeeParamSpec andPEP 612 for more details.

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 thetyping module arehashable andcomparable for equality.

The`Any` 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 typeAny and assign it to any variable:

fromtypingimportAnya:Any=Nonea=[]# OKa=2# OKs:str=''s=a# OKdeffoo(item:Any)->int:# Passes type checking; 'item' could be any type,# and that type might have a 'bar' methoditem.bar()...

Notice that no type checking 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 type checking; an object does not have a 'magic' method.item.magic()...defhash_b(item:Any)->int:# Passes type checkingitem.magic()...# Passes type checking, since ints and strs are subclasses of objecthash_a(42)hash_a("foo")# Passes type checking, 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 the 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 toPEP 484:

fromcollections.abcimportSized,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):

fromcollections.abcimportIterator,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).

Module contents¶

Thetyping module defines the following classes, functions and decorators.

Special typing primitives¶

Special types¶

These can be used as types in annotations. They do not support subscriptionusing[].

typing.Any¶

Special type indicating an unconstrained type.

Every type is compatible withAny.
Any is compatible with every type.

Changed in version 3.11:Any can now be used as a base class. This can be useful foravoiding type checker errors with classes that can duck type anywhere orare highly dynamic.

typing.AnyStr¶

Aconstrained type variable.

Definition:

AnyStr=TypeVar('AnyStr',str,bytes)

AnyStr is meant to be used for functions that may acceptstr orbytes arguments but cannot allow the two to mix.

For example:

defconcat(a:AnyStr,b:AnyStr)->AnyStr:returna+bconcat("foo","bar")# OK, output has type 'str'concat(b"foo",b"bar")# OK, output has type 'bytes'concat("foo",b"bar")# Error, cannot mix str and bytes

Note that, despite its name,AnyStr has nothing to do with theAny type, nor does it mean “any string”. In particular,AnyStrandstr|bytes are different from each other and have different usecases:

# Invalid use of AnyStr:# The type variable is used only once in the function signature,# so cannot be "solved" by the type checkerdefgreet_bad(cond:bool)->AnyStr:return"hi there!"ifcondelseb"greetings!"# The better way of annotating this function:defgreet_proper(cond:bool)->str|bytes:return"hi there!"ifcondelseb"greetings!"

Deprecated since version 3.13, will be removed in version 3.18:Deprecated in favor of the newtype parameter syntax.UseclassA[T:(str,bytes)]:... instead of importingAnyStr. SeePEP 695 for more details.

In Python 3.16,AnyStr will be removed fromtyping.__all__, anddeprecation warnings will be emitted at runtime when it is accessed orimported fromtyping.AnyStr will be removed fromtypingin Python 3.18.

typing.LiteralString¶

Special type that includes only literal strings.

Any stringliteral is compatible withLiteralString, as is anotherLiteralString. However, an object typed as juststr is not.A string created by composingLiteralString-typed objectsis also acceptable as aLiteralString.

Example:

defrun_query(sql:LiteralString)->None:...defcaller(arbitrary_string:str,literal_string:LiteralString)->None:run_query("SELECT * FROM students")# OKrun_query(literal_string)# OKrun_query("SELECT * FROM "+literal_string)# OKrun_query(arbitrary_string)# type checker errorrun_query(# type checker errorf"SELECT * FROM students WHERE name ={arbitrary_string}")

LiteralString is useful for sensitive APIs where arbitrary user-generatedstrings could generate problems. For example, the two cases abovethat generate type checker errors could be vulnerable to an SQLinjection attack.

SeePEP 675 for more details.

Added in version 3.11.

typing.Never¶

typing.NoReturn¶

Never andNoReturn represent thebottom type,a type that has no members.

They can be used to indicate that a function never returns,such assys.exit():

fromtypingimportNever# or NoReturndefstop()->Never:raiseRuntimeError('no way')

Or to define a function that should never becalled, as there are no valid arguments, such asassert_never():

fromtypingimportNever# or NoReturndefnever_call_me(arg:Never)->None:passdefint_or_str(arg:int|str)->None:never_call_me(arg)# type checker errormatcharg:caseint():print("It's an int")casestr():print("It's a str")case_:never_call_me(arg)# OK, arg is of type Never (or NoReturn)

Never andNoReturn have the same meaning in the type systemand static type checkers treat both equivalently.

Added in version 3.6.2:AddedNoReturn.

Added in version 3.11:AddedNever.

typing.Self¶

Special type to represent the current enclosed class.

For example:

fromtypingimportSelf,reveal_typeclassFoo:defreturn_self(self)->Self:...returnselfclassSubclassOfFoo(Foo):passreveal_type(Foo().return_self())# Revealed type is "Foo"reveal_type(SubclassOfFoo().return_self())# Revealed type is "SubclassOfFoo"

This annotation is semantically equivalent to the following,albeit in a more succinct fashion:

fromtypingimportTypeVarSelf=TypeVar("Self",bound="Foo")classFoo:defreturn_self(self:Self)->Self:...returnself

In general, if something returnsself, as in the above examples, youshould useSelf as the return annotation. IfFoo.return_self wasannotated as returning"Foo", then the type checker would infer theobject returned fromSubclassOfFoo.return_self as being of typeFoorather thanSubclassOfFoo.

Other common use cases include:

classmethods that are used as alternative constructors and return instancesof thecls parameter.
Annotating an__enter__() method which returns self.

You should not useSelf as the return annotation if the method is notguaranteed to return an instance of a subclass when the class issubclassed:

classEggs:# Self would be an incorrect return annotation here,# as the object returned is always an instance of Eggs,# even in subclassesdefreturns_eggs(self)->"Eggs":returnEggs()

SeePEP 673 for more details.

Added in version 3.11.

typing.TypeAlias¶

Special annotation for explicitly declaring atype alias.

For example:

fromtypingimportTypeAliasFactors:TypeAlias=list[int]

TypeAlias is particularly useful on older Python versions for annotatingaliases that make use of forward references, as it can be hard for typecheckers to distinguish these from normal variable assignments:

fromtypingimportGeneric,TypeAlias,TypeVarT=TypeVar("T")# "Box" does not exist yet,# so we have to use quotes for the forward reference on Python <3.12.# Using ``TypeAlias`` tells the type checker that this is a type alias declaration,# not a variable assignment to a string.BoxOfStrings:TypeAlias="Box[str]"classBox(Generic[T]):@classmethoddefmake_box_of_strings(cls)->BoxOfStrings:...

SeePEP 613 for more details.

Added in version 3.10.

Deprecated since version 3.12:TypeAlias is deprecated in favor of thetype statement,which creates instances ofTypeAliasTypeand which natively supports forward references.Note that whileTypeAlias andTypeAliasType servesimilar purposes and have similar names, they are distinct and thelatter is not the type of the former.Removal ofTypeAlias is not currently planned, but usersare encouraged to migrate totype statements.

Special forms¶

These can be used as types in annotations. They all support subscription using[], but each has a unique syntax.

classtyping.Union¶

Union type;Union[X,Y] is equivalent toX|Y and means either X or Y.

To define a union, use e.g.Union[int,str] or the shorthandint|str. Using that shorthand is recommended. 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]
```
However, this does not apply to unions referenced through a typealias, to avoid forcing evaluation of the underlyingTypeAliasType:
```
typeA=Union[int,str]Union[A,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]==int|str

When comparing unions, the argument order is ignored, e.g.:
```
Union[int,str]==Union[str,int]
```
You cannot subclass or instantiate aUnion.
You cannot writeUnion[X][Y].

Changed in version 3.7:Don’t remove explicit subclasses from unions at runtime.

Changed in version 3.10:Unions can now be written asX|Y. Seeunion type expressions.

Changed in version 3.14:types.UnionType is now an alias forUnion, and bothUnion[int,str] andint|str create instances of the same class.To check whether an object is aUnion at runtime, useisinstance(obj,Union). For compatibility with earlier versions ofPython, useget_origin(obj)istyping.Unionorget_origin(obj)istypes.UnionType.

typing.Optional¶

Optional[X] is equivalent toX|None (orUnion[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 theOptional qualifier on its typeannotation just because it is optional. For example:

deffoo(arg:int=0)->None:...

On the other hand, if an explicit value ofNone is allowed, theuse ofOptional is appropriate, whether the argument is optionalor not. For example:

deffoo(arg:Optional[int]=None)->None:...

Changed in version 3.10:Optional can now be written asX|None. Seeunion type expressions.

typing.Concatenate¶

Special form for annotating higher-order functions.

Concatenate can be used in conjunction withCallable andParamSpec to annotate a higher-order callable which adds, removes,or transforms parameters of anothercallable. Usage is in the formConcatenate[Arg1Type,Arg2Type,...,ParamSpecVariable].Concatenateis currently only valid when used as the first argument to aCallable.The last parameter toConcatenate must be aParamSpec orellipsis (...).

For example, to annotate a decoratorwith_lock which provides athreading.Lock to the decorated function,Concatenate can beused to indicate thatwith_lock expects a callable which takes in aLock as the first argument, and returns a callable with a different typesignature. In this case, theParamSpec indicates that the returnedcallable’s parameter types are dependent on the parameter types of thecallable being passed in:

fromcollections.abcimportCallablefromthreadingimportLockfromtypingimportConcatenate# Use this lock to ensure that only one thread is executing a function# at any time.my_lock=Lock()defwith_lock[**P,R](f:Callable[Concatenate[Lock,P],R])->Callable[P,R]:'''A type-safe decorator which provides a lock.'''definner(*args:P.args,**kwargs:P.kwargs)->R:# Provide the lock as the first argument.returnf(my_lock,*args,**kwargs)returninner@with_lockdefsum_threadsafe(lock:Lock,numbers:list[float])->float:'''Add a list of numbers together in a thread-safe manner.'''withlock:returnsum(numbers)# We don't need to pass in the lock ourselves thanks to the decorator.sum_threadsafe([1.1,2.2,3.3])

Added in version 3.10.

See also

PEP 612 – Parameter Specification Variables (the PEP which introducedParamSpec andConcatenate)
ParamSpec
Annotating callable objects

typing.Literal¶

Special typing form to define “literal types”.

Literal can be used to indicate to type checkers that theannotated object has a value equivalent to one of theprovided literals.

For example:

defvalidate_simple(data:Any)->Literal[True]:# always returns True...typeMode=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.

Additional details:

The arguments must be literal values and there must be at least one.
NestedLiteral types are flattened, e.g.:
```
assertLiteral[Literal[1,2],3]==Literal[1,2,3]
```
However, this does not apply toLiteral types referenced through a typealias, to avoid forcing evaluation of the underlyingTypeAliasType:
```
typeA=Literal[1,2]assertLiteral[A,3]!=Literal[1,2,3]
```
Redundant arguments are skipped, e.g.:
```
assertLiteral[1,2,1]==Literal[1,2]
```
When comparing literals, the argument order is ignored, e.g.:
```
assertLiteral[1,2]==Literal[2,1]
```
You cannot subclass or instantiate aLiteral.
You cannot writeLiteral[X][Y].

Added in version 3.8.

Changed in version 3.9.1:Literal now de-duplicates parameters. Equality comparisons ofLiteral objects are no longer order dependent.Literal objectswill now raise aTypeError exception during equality comparisonsif one of their parameters are nothashable.

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

ClassVar accepts only types and cannot be further subscribed.

ClassVar is not a class itself, and should notbe used withisinstance() orissubclass().ClassVar does 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

Added in version 3.5.3.

Changed in version 3.13:ClassVar can now be nested inFinal and vice versa.

typing.Final¶

Special typing construct to indicate final names to type checkers.

Final names cannot be reassigned in any scope. Final names declared in classscopes cannot be overridden in subclasses.

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.

Added in version 3.8.

Changed in version 3.13:Final can now be nested inClassVar and vice versa.

typing.Required¶

Special typing construct to mark aTypedDict key as required.

This is mainly useful fortotal=False TypedDicts. SeeTypedDictandPEP 655 for more details.

Added in version 3.11.

typing.NotRequired¶

Special typing construct to mark aTypedDict key as potentiallymissing.

SeeTypedDict andPEP 655 for more details.

Added in version 3.11.

typing.ReadOnly¶

A special typing construct to mark an item of aTypedDict as read-only.

For example:

classMovie(TypedDict):title:ReadOnly[str]year:intdefmutate_movie(m:Movie)->None:m["year"]=1999# allowedm["title"]="The Matrix"# typechecker error

There is no runtime checking for this property.

SeeTypedDict andPEP 705 for more details.

Added in version 3.13.

typing.Annotated¶

Special typing form to add context-specific metadata to an annotation.

Add metadatax to a given typeT by using the annotationAnnotated[T,x]. Metadata added usingAnnotated can be used bystatic analysis tools or at runtime. At runtime, the metadata is storedin a__metadata__ attribute.

If a library or tool encounters an annotationAnnotated[T,x] and hasno special logic for the metadata, it should ignore the metadata and simplytreat the annotation asT. As such,Annotated can be useful for codethat wants to use annotations for purposes outside Python’s static typingsystem.

UsingAnnotated[T,x] as an annotation still allows for statictypechecking ofT, as type checkers will simply ignore the metadatax.In this way,Annotated differs from the@no_type_check decorator, which can also be used foradding annotations outside the scope of the typing system, butcompletely disables typechecking for a function or class.

The responsibility of how to interpret the metadatalies with the tool or library encountering anAnnotated annotation. A tool or library encountering anAnnotated typecan scan through the metadata elements to determine if they are of interest(e.g., usingisinstance()).

Annotated[<type>,<metadata>]

Here is an example of how you might useAnnotated to add metadata totype annotations if you were doing range analysis:

@dataclassclassValueRange:lo:inthi:intT1=Annotated[int,ValueRange(-10,5)]T2=Annotated[T1,ValueRange(-20,3)]

The first argument toAnnotated must be a valid type. Multiple metadataelements can be supplied asAnnotated supports variadic arguments. Theorder of the metadata elements is preserved and matters for equality checks:

@dataclassclassctype:kind:stra1=Annotated[int,ValueRange(3,10),ctype("char")]a2=Annotated[int,ctype("char"),ValueRange(3,10)]asserta1!=a2# Order matters

It is up to the tool consuming the annotations to decide whether theclient is allowed to add multiple metadata elements to one annotation and how tomerge those annotations.

NestedAnnotated types are flattened. The order of the metadata elementsstarts with the innermost annotation:

assertAnnotated[Annotated[int,ValueRange(3,10)],ctype("char")]==Annotated[int,ValueRange(3,10),ctype("char")]

However, this does not apply toAnnotated types referenced through a typealias, to avoid forcing evaluation of the underlyingTypeAliasType:

typeFrom3To10[T]=Annotated[T,ValueRange(3,10)]assertAnnotated[From3To10[int],ctype("char")]!=Annotated[int,ValueRange(3,10),ctype("char")]

Duplicated metadata elements are not removed:

assertAnnotated[int,ValueRange(3,10)]!=Annotated[int,ValueRange(3,10),ValueRange(3,10)]

Annotated can be used with nested and generic aliases:

@dataclassclassMaxLen:value:inttypeVec[T]=Annotated[list[tuple[T,T]],MaxLen(10)]# When used in a type annotation, a type checker will treat "V" the same as# ``Annotated[list[tuple[int, int]], MaxLen(10)]``:typeV=Vec[int]

Annotated cannot be used with an unpackedTypeVarTuple:

typeVariadic[*Ts]=Annotated[*Ts,Ann1]=Annotated[T1,T2,T3,...,Ann1]# NOT valid

whereT1,T2, … areTypeVars. This is invalid asonly one type should be passed to Annotated.

By default,get_type_hints() strips the metadata from annotations.Passinclude_extras=True to have the metadata preserved:

>>>fromtypingimportAnnotated,get_type_hints>>>deffunc(x:Annotated[int,"metadata"])->None:pass...>>>get_type_hints(func){'x': <class 'int'>, 'return': <class 'NoneType'>}>>>get_type_hints(func,include_extras=True){'x': typing.Annotated[int, 'metadata'], 'return': <class 'NoneType'>}

At runtime, the metadata associated with anAnnotated type can beretrieved via the__metadata__ attribute:

>>>fromtypingimportAnnotated>>>X=Annotated[int,"very","important","metadata"]>>>Xtyping.Annotated[int, 'very', 'important', 'metadata']>>>X.__metadata__('very', 'important', 'metadata')

If you want to retrieve the original type wrapped byAnnotated, use the__origin__ attribute:

>>>fromtypingimportAnnotated,get_origin>>>Password=Annotated[str,"secret"]>>>Password.__origin__<class 'str'>

Note that usingget_origin() will returnAnnotated itself:

>>>get_origin(Password)typing.Annotated

See also

PEP 593 - Flexible function and variable annotations: The PEP introducingAnnotated to the standard library.

Added in version 3.9.

typing.TypeIs¶

Special typing construct for marking user-defined type predicate functions.

TypeIs can be used to annotate the return type of a user-definedtype predicate function.TypeIs only accepts a single type argument.At runtime, functions marked this way should return a boolean and take atleast one positional argument.

TypeIs aims to benefittype narrowing – a technique used by statictype checkers to determine a more precise type of an expression within aprogram’s code flow. Usually type narrowing is done by analyzingconditional code flow and applying the narrowing to a block of code. Theconditional expression here is sometimes referred to as a “type predicate”:

defis_str(val:str|float):# "isinstance" type predicateifisinstance(val,str):# Type of ``val`` is narrowed to ``str``...else:# Else, type of ``val`` is narrowed to ``float``....

Sometimes it would be convenient to use a user-defined boolean functionas a type predicate. Such a function should useTypeIs[...] orTypeGuard as its return type to alert static type checkers tothis intention.TypeIs usually has more intuitive behavior thanTypeGuard, but it cannot be used when the input and output typesare incompatible (e.g.,list[object] tolist[int]) or when thefunction does not returnTrue for all instances of the narrowed type.

Using->TypeIs[NarrowedType] tells the static type checker that for a givenfunction:

The return value is a boolean.
If the return value isTrue, the type of its argumentis the intersection of the argument’s original type andNarrowedType.
If the return value isFalse, the type of its argumentis narrowed to excludeNarrowedType.

For example:

fromtypingimportassert_type,final,TypeIsclassParent:passclassChild(Parent):pass@finalclassUnrelated:passdefis_parent(val:object)->TypeIs[Parent]:returnisinstance(val,Parent)defrun(arg:Child|Unrelated):ifis_parent(arg):# Type of ``arg`` is narrowed to the intersection# of ``Parent`` and ``Child``, which is equivalent to# ``Child``.assert_type(arg,Child)else:# Type of ``arg`` is narrowed to exclude ``Parent``,# so only ``Unrelated`` is left.assert_type(arg,Unrelated)

The type insideTypeIs must be consistent with the type of thefunction’s argument; if it is not, static type checkers will raisean error. An incorrectly writtenTypeIs function can lead tounsound behavior in the type system; it is the user’s responsibilityto write such functions in a type-safe manner.

If aTypeIs function is a class or instance method, then the type inTypeIs maps to the type of the second parameter (aftercls orself).

In short, the formdeffoo(arg:TypeA)->TypeIs[TypeB]:...,means that iffoo(arg) returnsTrue, thenarg is an instanceofTypeB, and if it returnsFalse, it is not an instance ofTypeB.

TypeIs also works with type variables. For more information, seePEP 742 (Narrowing types withTypeIs).

Added in version 3.13.

typing.TypeGuard¶

Special typing construct for marking user-defined type predicate functions.

Type predicate functions are user-defined functions that return whether theirargument is an instance of a particular type.TypeGuard works similarly toTypeIs, but has subtly differenteffects on type checking behavior (see below).

Using->TypeGuard tells the static type checker that for a givenfunction:

The return value is a boolean.
If the return value isTrue, the type of its argumentis the type insideTypeGuard.

TypeGuard also works with type variables. SeePEP 647 for more details.

For example:

defis_str_list(val:list[object])->TypeGuard[list[str]]:'''Determines whether all objects in the list are strings'''returnall(isinstance(x,str)forxinval)deffunc1(val:list[object]):ifis_str_list(val):# Type of ``val`` is narrowed to ``list[str]``.print(" ".join(val))else:# Type of ``val`` remains as ``list[object]``.print("Not a list of strings!")

TypeIs andTypeGuard differ in the following ways:

TypeIs requires the narrowed type to be a subtype of the input type, whileTypeGuard does not. The main reason is to allow for things likenarrowinglist[object] tolist[str] even though the latteris not a subtype of the former, sincelist is invariant.
When aTypeGuard function returnsTrue, type checkers narrow the type of thevariable to exactly theTypeGuard type. When aTypeIs function returnsTrue,type checkers can infer a more precise type combining the previously known type of thevariable with theTypeIs type. (Technically, this is known as an intersection type.)
When aTypeGuard function returnsFalse, type checkers cannot narrow the type ofthe variable at all. When aTypeIs function returnsFalse, type checkers can narrowthe type of the variable to exclude theTypeIs type.

Added in version 3.10.

typing.Unpack¶

Typing operator to conceptually mark an object as having been unpacked.

For example, using the unpack operator* on atype variable tuple is equivalent to usingUnpackto mark the type variable tuple as having been unpacked:

Ts=TypeVarTuple('Ts')tup:tuple[*Ts]# Effectively does:tup:tuple[Unpack[Ts]]

In fact,Unpack can be used interchangeably with* in the contextoftyping.TypeVarTuple andbuiltins.tuple types. You might seeUnpack being usedexplicitly in older versions of Python, where* couldn’t be used incertain places:

# In older versions of Python, TypeVarTuple and Unpack# are located in the `typing_extensions` backports package.fromtyping_extensionsimportTypeVarTuple,UnpackTs=TypeVarTuple('Ts')tup:tuple[*Ts]# Syntax error on Python <= 3.10!tup:tuple[Unpack[Ts]]# Semantically equivalent, and backwards-compatible

Unpack can also be used along withtyping.TypedDict for typing**kwargs in a function signature:

fromtypingimportTypedDict,UnpackclassMovie(TypedDict):name:stryear:int# This function expects two keyword arguments - `name` of type `str`# and `year` of type `int`.deffoo(**kwargs:Unpack[Movie]):...

SeePEP 692 for more details on usingUnpack for**kwargs typing.

Added in version 3.11.

Building generic types and type aliases¶

The following classes should not be used directly as annotations.Their intended purpose is to be building blocksfor creating generic types and type aliases.

These objects can be created through special syntax(type parameter lists and thetype statement).For compatibility with Python 3.11 and earlier, they can also be createdwithout the dedicated syntax, as documented below.

classtyping.Generic¶

Abstract base class for generic types.

A generic type is typically declared by adding a list of type parametersafter the class name:

classMapping[KT,VT]:def__getitem__(self,key:KT)->VT:...# Etc.

Such a class implicitly inherits fromGeneric.The runtime semantics of this syntax are discussed in theLanguage Reference.

This class can then be used as follows:

deflookup_name[X,Y](mapping:Mapping[X,Y],key:X,default:Y)->Y:try:returnmapping[key]exceptKeyError:returndefault

Here the brackets after the function name indicate ageneric function.

For backwards compatibility, generic classes can also bedeclared by explicitly inheriting fromGeneric. In this case, the type parameters must be declaredseparately:

KT=TypeVar('KT')VT=TypeVar('VT')classMapping(Generic[KT,VT]):def__getitem__(self,key:KT)->VT:...# Etc.

classtyping.TypeVar(name,*constraints,bound=None,covariant=False,contravariant=False,infer_variance=False,default=typing.NoDefault)¶

Type variable.

The preferred way to construct a type variable is via the dedicated syntaxforgeneric functions,generic classes, andgeneric type aliases:

classSequence[T]:# T is a TypeVar...

This syntax can also be used to create bounded and constrained typevariables:

classStrSequence[S:str]:# S is a TypeVar with a `str` upper bound;...# we can say that S is "bounded by `str`"classStrOrBytesSequence[A:(str,bytes)]:# A is a TypeVar constrained to str or bytes...

However, if desired, reusable type variables can also be constructed manually, like so:

T=TypeVar('T')# Can be anythingS=TypeVar('S',bound=str)# Can be any subtype of strA=TypeVar('A',str,bytes)# Must be exactly 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 and type alias definitions.SeeGeneric for moreinformation on generic types. Generic functions work as follows:

defrepeat[T](x:T,n:int)->Sequence[T]:"""Return a list containing n references to x."""return[x]*ndefprint_capitalized[S:str](x:S)->S:"""Print x capitalized, and return x."""print(x.capitalize())returnxdefconcatenate[A:(str,bytes)](x:A,y:A)->A:"""Add two strings or bytes objects together."""returnx+y

Note that type variables can bebounded,constrained, or neither, butcannot be both boundedand constrained.

The variance of type variables is inferred by type checkers when they are createdthrough thetype parameter syntax or wheninfer_variance=True is passed.Manually created type variables may be explicitly marked covariant or contravariant by passingcovariant=True orcontravariant=True.By default, manually created type variables are invariant.SeePEP 484 andPEP 695 for more details.

Bounded type variables and constrained type variables have differentsemantics in several important ways. Using abounded type variable meansthat theTypeVar will be solved using the most specific type possible:

x=print_capitalized('a string')reveal_type(x)# revealed type is strclassStringSubclass(str):passy=print_capitalized(StringSubclass('another string'))reveal_type(y)# revealed type is StringSubclassz=print_capitalized(45)# error: int is not a subtype of str

The upper bound of a type variable can be a concrete type, abstract type(ABC or Protocol), or even a union of types:

# Can be anything with an __abs__ methoddefprint_abs[T:SupportsAbs](arg:T)->None:print("Absolute value:",abs(arg))U=TypeVar('U',bound=str|bytes)# Can be any subtype of the union str|bytesV=TypeVar('V',bound=SupportsAbs)# Can be anything with an __abs__ method

Using aconstrained type variable, however, means that theTypeVarcan only ever be solved as being exactly one of the constraints given:

a=concatenate('one','two')reveal_type(a)# revealed type is strb=concatenate(StringSubclass('one'),StringSubclass('two'))reveal_type(b)# revealed type is str, despite StringSubclass being passed inc=concatenate('one',b'two')# error: type variable 'A' can be either str or bytes in a function call, but not both

At runtime,isinstance(x,T) will raiseTypeError.

__name__¶: The name of the type variable.

__covariant__¶: Whether the type var has been explicitly marked as covariant.

__contravariant__¶: Whether the type var has been explicitly marked as contravariant.

__infer_variance__¶: Whether the type variable’s variance should be inferred by type checkers.
Added in version 3.12.

__bound__¶: The upper bound of the type variable, if any.
Changed in version 3.12:For type variables created throughtype parameter syntax,the bound is evaluated only when the attribute is accessed, not whenthe type variable is created (seeLazy evaluation).

evaluate_bound()¶: Anevaluate function corresponding to the__bound__ attribute.When called directly, this method supports only theVALUEformat, which is equivalent to accessing the__bound__ attribute directly,but the method object can be passed toannotationlib.call_evaluate_function()to evaluate the value in a different format.
Added in version 3.14.

__constraints__¶: A tuple containing the constraints of the type variable, if any.
Changed in version 3.12:For type variables created throughtype parameter syntax,the constraints are evaluated only when the attribute is accessed, not whenthe type variable is created (seeLazy evaluation).

evaluate_constraints()¶: Anevaluate function corresponding to the__constraints__ attribute.When called directly, this method supports only theVALUEformat, which is equivalent to accessing the__constraints__ attribute directly,but the method object can be passed toannotationlib.call_evaluate_function()to evaluate the value in a different format.
Added in version 3.14.

__default__¶: The default value of the type variable, ortyping.NoDefault if ithas no default.
Added in version 3.13.

evaluate_default()¶: Anevaluate function corresponding to the__default__ attribute.When called directly, this method supports only theVALUEformat, which is equivalent to accessing the__default__ attribute directly,but the method object can be passed toannotationlib.call_evaluate_function()to evaluate the value in a different format.
Added in version 3.14.

has_default()¶: Return whether or not the type variable has a default value. This is equivalentto checking whether__default__ is not thetyping.NoDefaultsingleton, except that it does not force evaluation of thelazily evaluated default value.
Added in version 3.13.

Changed in version 3.12:Type variables can now be declared using thetype parameter syntax introduced byPEP 695.Theinfer_variance parameter was added.

Changed in version 3.13:Support for default values was added.

classtyping.TypeVarTuple(name,*,default=typing.NoDefault)¶

Type variable tuple. A specialized form oftype variablethat enablesvariadic generics.

Type variable tuples can be declared intype parameter listsusing a single asterisk (*) before the name:

defmove_first_element_to_last[T,*Ts](tup:tuple[T,*Ts])->tuple[*Ts,T]:return(*tup[1:],tup[0])

Or by explicitly invoking theTypeVarTuple constructor:

T=TypeVar("T")Ts=TypeVarTuple("Ts")defmove_first_element_to_last(tup:tuple[T,*Ts])->tuple[*Ts,T]:return(*tup[1:],tup[0])

A normal type variable enables parameterization with a single type. A typevariable tuple, in contrast, allows parameterization with anarbitrary number of types by acting like anarbitrary number of typevariables wrapped in a tuple. For example:

# T is bound to int, Ts is bound to ()# Return value is (1,), which has type tuple[int]move_first_element_to_last(tup=(1,))# T is bound to int, Ts is bound to (str,)# Return value is ('spam', 1), which has type tuple[str, int]move_first_element_to_last(tup=(1,'spam'))# T is bound to int, Ts is bound to (str, float)# Return value is ('spam', 3.0, 1), which has type tuple[str, float, int]move_first_element_to_last(tup=(1,'spam',3.0))# This fails to type check (and fails at runtime)# because tuple[()] is not compatible with tuple[T, *Ts]# (at least one element is required)move_first_element_to_last(tup=())

Note the use of the unpacking operator* intuple[T,*Ts].Conceptually, you can think ofTs as a tuple of type variables(T1,T2,...).tuple[T,*Ts] would then becometuple[T,*(T1,T2,...)], which is equivalent totuple[T,T1,T2,...]. (Note that in older versions of Python, you mightsee this written usingUnpack instead, asUnpack[Ts].)

Type variable tuples mustalways be unpacked. This helps distinguish typevariable tuples from normal type variables:

x:Ts# Not validx:tuple[Ts]# Not validx:tuple[*Ts]# The correct way to do it

Type variable tuples can be used in the same contexts as normal typevariables. For example, in class definitions, arguments, and return types:

classArray[*Shape]:def__getitem__(self,key:tuple[*Shape])->float:...def__abs__(self)->"Array[*Shape]":...defget_shape(self)->tuple[*Shape]:...

Type variable tuples can be happily combined with normal type variables:

classArray[DType,*Shape]:# This is finepassclassArray2[*Shape,DType]:# This would also be finepassclassHeight:...classWidth:...float_array_1d:Array[float,Height]=Array()# Totally fineint_array_2d:Array[int,Height,Width]=Array()# Yup, fine too

However, note that at most one type variable tuple may appear in a singlelist of type arguments or type parameters:

x:tuple[*Ts,*Ts]# Not validclassArray[*Shape,*Shape]:# Not validpass

Finally, an unpacked type variable tuple can be used as the type annotationof*args:

defcall_soon[*Ts](callback:Callable[[*Ts],None],*args:*Ts)->None:...callback(*args)

In contrast to non-unpacked annotations of*args - e.g.*args:int,which would specify thatall arguments areint -*args:*Tsenables reference to the types of theindividual arguments in*args.Here, this allows us to ensure the types of the*args passedtocall_soon match the types of the (positional) arguments ofcallback.

SeePEP 646 for more details on type variable tuples.

__name__¶: The name of the type variable tuple.

__default__¶: The default value of the type variable tuple, ortyping.NoDefault if ithas no default.
Added in version 3.13.

evaluate_default()¶: Anevaluate function corresponding to the__default__ attribute.When called directly, this method supports only theVALUEformat, which is equivalent to accessing the__default__ attribute directly,but the method object can be passed toannotationlib.call_evaluate_function()to evaluate the value in a different format.
Added in version 3.14.

has_default()¶: Return whether or not the type variable tuple has a default value. This is equivalentto checking whether__default__ is not thetyping.NoDefaultsingleton, except that it does not force evaluation of thelazily evaluated default value.
Added in version 3.13.

Added in version 3.11.

Changed in version 3.12:Type variable tuples can now be declared using thetype parameter syntax introduced byPEP 695.

Changed in version 3.13:Support for default values was added.

classtyping.ParamSpec(name,*,bound=None,covariant=False,contravariant=False,default=typing.NoDefault)¶

Parameter specification variable. A specialized version oftype variables.

Intype parameter lists, parameter specificationscan be declared with two asterisks (**):

typeIntFunc[**P]=Callable[P,int]

For compatibility with Python 3.11 and earlier,ParamSpec objectscan also be created as follows:

P=ParamSpec('P')

Parameter specification variables exist primarily for the benefit of statictype checkers. They are used to forward the parameter types of onecallable to another callable – a pattern commonly found in higher orderfunctions and decorators. They are only valid when used inConcatenate,or as the first argument toCallable, or as parameters for user-definedGenerics. SeeGeneric for more information on generic types.

For example, to add basic logging to a function, one can create a decoratoradd_logging to log function calls. The parameter specification variabletells the type checker that the callable passed into the decorator and thenew callable returned by it have inter-dependent type parameters:

fromcollections.abcimportCallableimportloggingdefadd_logging[T,**P](f:Callable[P,T])->Callable[P,T]:'''A type-safe decorator to add logging to a function.'''definner(*args:P.args,**kwargs:P.kwargs)->T:logging.info(f'{f.__name__} was called')returnf(*args,**kwargs)returninner@add_loggingdefadd_two(x:float,y:float)->float:'''Add two numbers together.'''returnx+y

WithoutParamSpec, the simplest way to annotate this previously was touse aTypeVar with upper boundCallable[...,Any]. However thiscauses two problems:

The type checker can’t type check theinner function because*args and**kwargs have to be typedAny.
cast() may be required in the body of theadd_loggingdecorator when returning theinner function, or the static typechecker must be told to ignore thereturninner.

args¶

kwargs¶: SinceParamSpec captures both positional and keyword parameters,P.args andP.kwargs can be used to split aParamSpec into itscomponents.P.args represents the tuple of positional parameters in agiven call and should only be used to annotate*args.P.kwargsrepresents the mapping of keyword parameters to their values in a given call,and should be only be used to annotate**kwargs. Bothattributes require the annotated parameter to be in scope. At runtime,P.args andP.kwargs are instances respectively ofParamSpecArgs andParamSpecKwargs.

__name__¶: The name of the parameter specification.

__default__¶: The default value of the parameter specification, ortyping.NoDefault if ithas no default.
Added in version 3.13.

evaluate_default()¶: Anevaluate function corresponding to the__default__ attribute.When called directly, this method supports only theVALUEformat, which is equivalent to accessing the__default__ attribute directly,but the method object can be passed toannotationlib.call_evaluate_function()to evaluate the value in a different format.
Added in version 3.14.

has_default()¶: Return whether or not the parameter specification has a default value. This is equivalentto checking whether__default__ is not thetyping.NoDefaultsingleton, except that it does not force evaluation of thelazily evaluated default value.
Added in version 3.13.

Parameter specification variables created withcovariant=True orcontravariant=True can be used to declare covariant or contravariantgeneric types. Thebound argument is also accepted, similar toTypeVar. However the actual semantics of these keywords are yet tobe decided.

Added in version 3.10.

Changed in version 3.12:Parameter specifications can now be declared using thetype parameter syntax introduced byPEP 695.

Changed in version 3.13:Support for default values was added.

Note

Only parameter specification variables defined in global scope canbe pickled.

See also

PEP 612 – Parameter Specification Variables (the PEP which introducedParamSpec andConcatenate)
Concatenate
Annotating callable objects

typing.ParamSpecArgs¶

typing.ParamSpecKwargs¶

Arguments and keyword arguments attributes of aParamSpec. TheP.args attribute of aParamSpec is an instance ofParamSpecArgs,andP.kwargs is an instance ofParamSpecKwargs. They are intendedfor runtime introspection and have no special meaning to static type checkers.

Callingget_origin() on either of these objects will return theoriginalParamSpec:

>>>fromtypingimportParamSpec,get_origin>>>P=ParamSpec("P")>>>get_origin(P.args)isPTrue>>>get_origin(P.kwargs)isPTrue

Added in version 3.10.

classtyping.TypeAliasType(name,value,*,type_params=())¶

The type of type aliases created through thetype statement.

Example:

>>>typeAlias=int>>>type(Alias)<class 'typing.TypeAliasType'>

Added in version 3.12.

__name__¶

The name of the type alias:

>>>typeAlias=int>>>Alias.__name__'Alias'

__module__¶

The name of the module in which the type alias was defined:

>>>typeAlias=int>>>Alias.__module__'__main__'

__type_params__¶

The type parameters of the type alias, or an empty tuple if the alias isnot generic:

>>>typeListOrSet[T]=list[T]|set[T]>>>ListOrSet.__type_params__(T,)>>>typeNotGeneric=int>>>NotGeneric.__type_params__()

__value__¶

The type alias’s value. This islazily evaluated,so names used in the definition of the alias are not resolved until the__value__ attribute is accessed:

>>>typeMutually=Recursive>>>typeRecursive=Mutually>>>MutuallyMutually>>>RecursiveRecursive>>>Mutually.__value__Recursive>>>Recursive.__value__Mutually

evaluate_value()¶

Anevaluate function corresponding to the__value__ attribute.When called directly, this method supports only theVALUEformat, which is equivalent to accessing the__value__ attribute directly,but the method object can be passed toannotationlib.call_evaluate_function()to evaluate the value in a different format:

>>>typeAlias=undefined>>>Alias.__value__Traceback (most recent call last):...NameError:name 'undefined' is not defined>>>fromannotationlibimportFormat,call_evaluate_function>>>Alias.evaluate_value(Format.VALUE)Traceback (most recent call last):...NameError:name 'undefined' is not defined>>>call_evaluate_function(Alias.evaluate_value,Format.FORWARDREF)ForwardRef('undefined')

Added in version 3.14.

Unpacking

Type aliases support star unpacking using the*Alias syntax.This is equivalent to usingUnpack[Alias] directly:

>>>typeAlias=tuple[int,str]>>>typeUnpacked=tuple[bool,*Alias]>>>Unpacked.__value__tuple[bool, typing.Unpack[Alias]]

Added in version 3.14.

Other special directives¶

These functions and classes should not be used directly as annotations.Their intended purpose is to be building blocks for creating and declaringtypes.

classtyping.NamedTuple¶

Typed version ofcollections.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_fields attribute and the default values are in the_field_defaults attribute, both of which are part of thenamedtuple()API.)

NamedTuple subclasses 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}>'

NamedTuple subclasses can be generic:

classGroup[T](NamedTuple):key:Tgroup:list[T]

Backward-compatible usage:

# For creating a generic NamedTuple on Python 3.11T=TypeVar("T")classGroup(NamedTuple,Generic[T]):key:Tgroup:list[T]# A functional syntax is also supportedEmployee=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:The_field_types and__annotations__ attributes arenow regular dictionaries instead of instances ofOrderedDict.

Changed in version 3.9:Removed the_field_types attribute in favor of the morestandard__annotations__ attribute which has the same information.

Changed in version 3.11:Added support for generic namedtuples.

Changed in version 3.14:Usingsuper() (and the__class__closure variable) in methods ofNamedTuple subclassesis unsupported and causes aTypeError.

Deprecated since version 3.13, will be removed in version 3.15:The undocumented keyword argument syntax for creating NamedTuple classes(NT=NamedTuple("NT",x=int)) is deprecated, and will be disallowedin 3.15. Use the class-based syntax or the functional syntax instead.

Deprecated since version 3.13, will be removed in version 3.15:When using the functional syntax to create a NamedTuple class, failing topass a value to the ‘fields’ parameter (NT=NamedTuple("NT")) isdeprecated. PassingNone to the ‘fields’ parameter(NT=NamedTuple("NT",None)) is also deprecated. Both will bedisallowed in Python 3.15. To create a NamedTuple class with 0 fields,useclassNT(NamedTuple):pass orNT=NamedTuple("NT",[]).

classtyping.NewType(name,tp)¶

Helper class to create low-overheaddistinct types.

ANewType is considered a distinct type by a typechecker. At runtime,however, calling aNewType returns its argument unchanged.

Usage:

UserId=NewType('UserId',int)# Declare the NewType "UserId"first_user=UserId(1)# "UserId" returns the argument unchanged at runtime

__module__¶: The name of the module in which the new type is defined.

__name__¶: The name of the new type.

__supertype__¶: The type that the new type is based on.

Added in version 3.5.2.

Changed in version 3.10:NewType is now a class rather than a function.

classtyping.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 more details. Protocol classes decorated withruntime_checkable() (described later) act as simple-minded runtimeprotocols that check only the presence of given attributes, ignoring theirtype signatures. Protocol classes without this decorator cannot be usedas the second argument toisinstance() orissubclass().

Protocol classes can be generic, for example:

classGenProto[T](Protocol):defmeth(self)->T:...

In code that needs to be compatible with Python 3.11 or older, genericProtocols can be written as follows:

T=TypeVar("T")classGenProto(Protocol[T]):defmeth(self)->T:...

Added in version 3.8.

@typing.runtime_checkable¶

Mark a protocol class as a runtime protocol.

Such a protocol can be used withisinstance() andissubclass().This allows a simple-minded structural check, very similar to “one trick ponies”incollections.abc such asIterable. For example:

@runtime_checkableclassClosable(Protocol):defclose(self):...assertisinstance(open('/some/file'),Closable)@runtime_checkableclassNamed(Protocol):name:strimportthreadingassertisinstance(threading.Thread(name='Bob'),Named)

This decorator raisesTypeError when applied to a non-protocol class.

Note

runtime_checkable() will check only the presence of the requiredmethods or attributes, not their type signatures or types.For example,ssl.SSLObjectis a class, therefore it passes anissubclass()check againstCallable. However, thessl.SSLObject.__init__ method exists only to raise aTypeError with a more informative message, therefore makingit impossible to call (instantiate)ssl.SSLObject.

Note

Anisinstance() check against a runtime-checkable protocol can besurprisingly slow compared to anisinstance() check againsta non-protocol class. Consider using alternative idioms such ashasattr() calls for structural checks in performance-sensitivecode.

Added in version 3.8.

Changed in version 3.12:The internal implementation ofisinstance() checks againstruntime-checkable protocols now usesinspect.getattr_static()to look up attributes (previously,hasattr() was used).As a result, some objects which used to be considered instancesof a runtime-checkable protocol may no longer be considered instancesof that protocol on Python 3.12+, and vice versa.Most users are unlikely to be affected by this change.

Changed in version 3.12:The members of a runtime-checkable protocol are now considered “frozen”at runtime as soon as the class has been created. Monkey-patchingattributes onto a runtime-checkable protocol will still work, but willhave no impact onisinstance() checks comparing objects to theprotocol. SeeWhat’s new in Python 3.12for more details.

classtyping.TypedDict(dict)¶

Special construct to add type hints to a dictionary.At runtime it is a plaindict.

TypedDict declares 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')

An alternative way to create aTypedDict is by usingfunction-call syntax. The second argument must be a literaldict:

Point2D=TypedDict('Point2D',{'x':int,'y':int,'label':str})

This functional syntax allows defining keys which are not valididentifiers, for example because they arekeywords or contain hyphens, or when key names must not bemangled like regular private names:

# raises SyntaxErrorclassPoint2D(TypedDict):in:int# 'in' is a keywordx-y:int# name with hyphensclassDefinition(TypedDict):__schema:str# mangled to `_Definition__schema`# OK, functional syntaxPoint2D=TypedDict('Point2D',{'in':int,'x-y':int})Definition=TypedDict('Definition',{'__schema':str})# not mangled

By default, all keys must be present in aTypedDict. It is possible tomark individual keys as non-required usingNotRequired:

classPoint2D(TypedDict):x:inty:intlabel:NotRequired[str]# Alternative syntaxPoint2D=TypedDict('Point2D',{'x':int,'y':int,'label':NotRequired[str]})

This means that aPoint2DTypedDict can have thelabelkey omitted.

It is also possible to mark all keys as non-required by defaultby specifying a totality ofFalse:

classPoint2D(TypedDict,total=False):x:inty:int# Alternative syntaxPoint2D=TypedDict('Point2D',{'x':int,'y':int},total=False)

This means that aPoint2DTypedDict can have any of the keysomitted. A type checker is only expected to support a literalFalse orTrue as the value of thetotal argument.True is the default,and makes all items defined in the class body required.

Individual keys of atotal=FalseTypedDict can be marked asrequired usingRequired:

classPoint2D(TypedDict,total=False):x:Required[int]y:Required[int]label:str# Alternative syntaxPoint2D=TypedDict('Point2D',{'x':Required[int],'y':Required[int],'label':str},total=False)

It is possible for aTypedDict type to inherit from one or more otherTypedDict typesusing the class-based syntax.Usage:

classPoint3D(Point2D):z:int

Point3D has three items:x,y andz. It is equivalent to thisdefinition:

classPoint3D(TypedDict):x:inty:intz:int

ATypedDict cannot inherit from a non-TypedDict class,except forGeneric. For example:

classX(TypedDict):x:intclassY(TypedDict):y:intclassZ(object):pass# A non-TypedDict classclassXY(X,Y):pass# OKclassXZ(X,Z):pass# raises TypeError

ATypedDict can be generic:

classGroup[T](TypedDict):key:Tgroup:list[T]

To create a genericTypedDict that is compatible with Python 3.11or lower, inherit fromGeneric explicitly:

T=TypeVar("T")classGroup(TypedDict,Generic[T]):key:Tgroup:list[T]

ATypedDict can be introspected via annotations dicts(seeAnnotations Best Practices for more information on annotations best practices),__total__,__required_keys__, and__optional_keys__.

__total__¶

Point2D.__total__ gives the value of thetotal argument.Example:

>>>fromtypingimportTypedDict>>>classPoint2D(TypedDict):pass>>>Point2D.__total__True>>>classPoint2D(TypedDict,total=False):pass>>>Point2D.__total__False>>>classPoint3D(Point2D):pass>>>Point3D.__total__True

This attribute reflectsonly the value of thetotal argumentto the currentTypedDict class, not whether the class is semanticallytotal. For example, aTypedDict with__total__ set toTrue mayhave keys marked withNotRequired, or it may inherit from anotherTypedDict withtotal=False. Therefore, it is generally better to use__required_keys__ and__optional_keys__ for introspection.

__required_keys__¶: Added in version 3.9.

__optional_keys__¶

Point2D.__required_keys__ andPoint2D.__optional_keys__ returnfrozenset objects containing required and non-required keys, respectively.

Keys marked withRequired will always appear in__required_keys__and keys marked withNotRequired will always appear in__optional_keys__.

For backwards compatibility with Python 3.10 and below,it is also possible to use inheritance to declare both required andnon-required keys in the sameTypedDict . This is done by declaring aTypedDict with one value for thetotal argument and theninheriting from it in anotherTypedDict with a different value fortotal:

>>>classPoint2D(TypedDict,total=False):...x:int...y:int...>>>classPoint3D(Point2D):...z:int...>>>Point3D.__required_keys__==frozenset({'z'})True>>>Point3D.__optional_keys__==frozenset({'x','y'})True

Added in version 3.9.

Note

Iffrom__future__importannotations is used or if annotationsare given as strings, annotations are not evaluated when theTypedDict is defined. Therefore, the runtime introspection that__required_keys__ and__optional_keys__ rely on may not workproperly, and the values of the attributes may be incorrect.

Support forReadOnly is reflected in the following attributes:

__readonly_keys__¶: Afrozenset containing the names of all read-only keys. Keysare read-only if they carry theReadOnly qualifier.
Added in version 3.13.

__mutable_keys__¶: Afrozenset containing the names of all mutable keys. Keysare mutable if they do not carry theReadOnly qualifier.
Added in version 3.13.

See theTypedDict section in the typing documentation for more examples and detailed rules.

Added in version 3.8.

Changed in version 3.11:Added support for marking individual keys asRequired orNotRequired.SeePEP 655.

Changed in version 3.11:Added support for genericTypedDicts.

Changed in version 3.13:Removed support for the keyword-argument method of creatingTypedDicts.

Changed in version 3.13:Support for theReadOnly qualifier was added.

Deprecated since version 3.13, will be removed in version 3.15:When using the functional syntax to create a TypedDict class, failing topass a value to the ‘fields’ parameter (TD=TypedDict("TD")) isdeprecated. PassingNone to the ‘fields’ parameter(TD=TypedDict("TD",None)) is also deprecated. Both will bedisallowed in Python 3.15. To create a TypedDict class with 0 fields,useclassTD(TypedDict):pass orTD=TypedDict("TD",{}).

Protocols¶

The following protocols are provided by thetyping module. All are decoratedwith@runtime_checkable.

classtyping.SupportsAbs¶: An ABC with one abstract method__abs__ that is covariantin its return type.

classtyping.SupportsBytes¶: An ABC with one abstract method__bytes__.

classtyping.SupportsComplex¶: An ABC with one abstract method__complex__.

classtyping.SupportsFloat¶: An ABC with one abstract method__float__.

classtyping.SupportsIndex¶: An ABC with one abstract method__index__.
Added in version 3.8.

classtyping.SupportsInt¶: An ABC with one abstract method__int__.

classtyping.SupportsRound¶: An ABC with one abstract method__round__that is covariant in its return type.

ABCs and Protocols for working with I/O¶

classtyping.IO[AnyStr]¶
classtyping.TextIO[AnyStr]¶
classtyping.BinaryIO[AnyStr]¶: Generic classIO[AnyStr] and its subclassesTextIO(IO[str])andBinaryIO(IO[bytes])represent the types of I/O streams such as returned byopen(). Please note that these classes are not protocols, andtheir interface is fairly broad.

The protocolsio.Reader andio.Writer offer a simpleralternative for argument types, when only theread() orwrite()methods are accessed, respectively:

defread_and_write(reader:Reader[str],writer:Writer[bytes]):data=reader.read()writer.write(data.encode())

Also consider usingcollections.abc.Iterable for iterating overthe lines of an input stream:

defread_config(stream:Iterable[str]):forlineinstream:...

Functions and decorators¶

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.assert_type(val,typ,/)¶

Ask a static type checker to confirm thatval has an inferred type oftyp.

At runtime this does nothing: it returns the first argument unchanged with nochecks or side effects, no matter the actual type of the argument.

When a static type checker encounters a call toassert_type(), itemits an error if the value is not of the specified type:

defgreet(name:str)->None:assert_type(name,str)# OK, inferred type of `name` is `str`assert_type(name,int)# type checker error

This function is useful for ensuring the type checker’s understanding of ascript is in line with the developer’s intentions:

defcomplex_function(arg:object):# Do some complex type-narrowing logic,# after which we hope the inferred type will be `int`...# Test whether the type checker correctly understands our functionassert_type(arg,int)

Added in version 3.11.

typing.assert_never(arg,/)¶

Ask a static type checker to confirm that a line of code is unreachable.

Example:

defint_or_str(arg:int|str)->None:matcharg:caseint():print("It's an int")casestr():print("It's a str")case_asunreachable:assert_never(unreachable)

Here, the annotations allow the type checker to infer that thelast case can never execute, becausearg is eitheranint or astr, and both options are covered byearlier cases.

If a type checker finds that a call toassert_never() isreachable, it will emit an error. For example, if the type annotationforarg was insteadint|str|float, the type checker wouldemit an error pointing out thatunreachable is of typefloat.For a call toassert_never to pass type checking, the inferred type ofthe argument passed in must be the bottom type,Never, and nothingelse.

At runtime, this throws an exception when called.

See also

Unreachable Code and Exhaustiveness Checking has moreinformation about exhaustiveness checking with static typing.

Added in version 3.11.

typing.reveal_type(obj,/)¶

Ask a static type checker to reveal the inferred type of an expression.

When a static type checker encounters a call to this function,it emits a diagnostic with the inferred type of the argument. For example:

x:int=1reveal_type(x)# Revealed type is "builtins.int"

This can be useful when you want to debug how your type checkerhandles a particular piece of code.

At runtime, this function prints the runtime type of its argument tosys.stderr and returns the argument unchanged (allowing the call tobe used within an expression):

x=reveal_type(1)# prints "Runtime type is int"print(x)# prints "1"

Note that the runtime type may be different from (more or less specificthan) the type statically inferred by a type checker.

Most type checkers supportreveal_type() anywhere, even if thename is not imported fromtyping. Importing the name fromtyping, however, allows your code to run without runtime errors andcommunicates intent more clearly.

Added in version 3.11.

@typing.dataclass_transform(*,eq_default=True,order_default=False,kw_only_default=False,frozen_default=False,field_specifiers=(),**kwargs)¶

Decorator to mark an object as providingdataclass-like behavior.

dataclass_transform may be used todecorate a class, metaclass, or a function that is itself a decorator.The presence of@dataclass_transform() tells a static type checker that thedecorated object performs runtime “magic” thattransforms a class in a similar way to@dataclasses.dataclass.

Example usage with a decorator function:

@dataclass_transform()defcreate_model[T](cls:type[T])->type[T]:...returncls@create_modelclassCustomerModel:id:intname:str

On a base class:

@dataclass_transform()classModelBase:...classCustomerModel(ModelBase):id:intname:str

On a metaclass:

@dataclass_transform()classModelMeta(type):...classModelBase(metaclass=ModelMeta):...classCustomerModel(ModelBase):id:intname:str

TheCustomerModel classes defined above willbe treated by type checkers similarly to classes created with@dataclasses.dataclass.For example, type checkers will assume these classes have__init__ methods that acceptid andname.

The decorated class, metaclass, or function may accept the following boolarguments which type checkers will assume have the same effect as theywould have on the@dataclasses.dataclass decorator:init,eq,order,unsafe_hash,frozen,match_args,kw_only, andslots. It must be possible for the value of thesearguments (True orFalse) to be statically evaluated.

The arguments to thedataclass_transform decorator can be used tocustomize the default behaviors of the decorated class, metaclass, orfunction:

Parameters:

eq_default (bool) – Indicates whether theeq parameter is assumed to beTrue orFalse if it is omitted by the caller.Defaults toTrue.
order_default (bool) – Indicates whether theorder parameter isassumed to beTrue orFalse if it is omitted by the caller.Defaults toFalse.
kw_only_default (bool) – Indicates whether thekw_only parameter isassumed to beTrue orFalse if it is omitted by the caller.Defaults toFalse.
frozen_default (bool) –
Indicates whether thefrozen parameter isassumed to beTrue orFalse if it is omitted by the caller.Defaults toFalse.
Added in version 3.12.
field_specifiers (tuple[Callable[...,Any],...]) – Specifies a static list of supported classesor functions that describe fields, similar todataclasses.field().Defaults to().
**kwargs (Any) – Arbitrary other keyword arguments are accepted in order to allow forpossible future extensions.

Type checkers recognize the following optional parameters on fieldspecifiers:

**Recognised parameters for field specifiers**¶
Parameter name	Description
`init`	Indicates whether the field should be included in thesynthesized`__init__` method. If unspecified,`init` defaults to`True`.
`default`	Provides the default value for the field.
`default_factory`	Provides a runtime callback that returns thedefault value for the field. If neither`default` nor`default_factory` are specified, the field is assumed to have nodefault value and must be provided a value when the class isinstantiated.
`factory`	An alias for the`default_factory` parameter on field specifiers.
`kw_only`	Indicates whether the field should be marked askeyword-only. If`True`, the field will be keyword-only. If`False`, it will not be keyword-only. If unspecified, the value ofthe`kw_only` parameter on the object decorated with`dataclass_transform` will be used, or if that is unspecified, thevalue of`kw_only_default` on`dataclass_transform` will be used.
`alias`	Provides an alternative name for the field. This alternativename is used in the synthesized`__init__` method.

At runtime, this decorator records its arguments in the__dataclass_transform__ attribute on the decorated object.It has no other runtime effect.

SeePEP 681 for more details.

Added in version 3.11.

@typing.overload¶

Decorator for creating overloaded functions and methods.

The@overload decorator 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).

@overload-decorated definitions are for the benefit of thetype checker only, since they will be overwritten by thenon-@overload-decorated definition. The non-@overload-decorateddefinition, meanwhile, will be used atruntime but should be ignored by a type checker. At runtime, callingan@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):...# actual implementation goes here

SeePEP 484 for more details and comparison with other typing semantics.

Changed in version 3.11:Overloaded functions can now be introspected at runtime usingget_overloads().

typing.get_overloads(func)¶

Return a sequence of@overload-decorated definitions forfunc.

func is the function object for the implementation of theoverloaded function. For example, given the definition ofprocess inthe documentation for@overload,get_overloads(process) will return a sequence of three function objectsfor the three defined overloads. If called on a function with no overloads,get_overloads() returns an empty sequence.

get_overloads() can be used for introspecting an overloaded function atruntime.

Added in version 3.11.

typing.clear_overloads()¶

Clear all registered overloads in the internal registry.

This can be used to reclaim the memory used by the registry.

Added in version 3.11.

@typing.final¶

Decorator to indicate final methods and final classes.

Decorating a method with@final indicates to a type checker that themethod cannot be overridden in a subclass. Decorating a class with@finalindicates that it 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.

Added in version 3.8.

Changed in version 3.11:The decorator will now attempt to set a__final__ attribute toTrueon the decorated object. Thus, a check likeifgetattr(obj,"__final__",False) can be used at runtimeto determine whether an objectobj has been marked as final.If the decorated object does not support setting attributes,the decorator returns the object unchanged without raising an exception.

@typing.no_type_check¶

Decorator to indicate that annotations are not type hints.

This works as a class or functiondecorator. With a class, itapplies recursively to all methods and classes defined in that class(but not to methods defined in its superclasses or subclasses). Typecheckers will ignore all annotations in a function or class with thisdecorator.

@no_type_check mutates the decorated object in place.

@typing.no_type_check_decorator¶

Decorator to give another decorator theno_type_check() effect.

This wraps the decorator with something that wraps the decoratedfunction inno_type_check().

Deprecated since version 3.13, will be removed in version 3.15:No type checker ever added support for@no_type_check_decorator. Itis therefore deprecated, and will be removed in Python 3.15.

@typing.override¶

Decorator to indicate that a method in a subclass is intended to override amethod or attribute in a superclass.

Type checkers should emit an error if a method decorated with@overridedoes not, in fact, override anything.This helps prevent bugs that may occur when a base class is changed withoutan equivalent change to a child class.

For example:

classBase:deflog_status(self)->None:...classSub(Base):@overridedeflog_status(self)->None:# Okay: overrides Base.log_status...@overridedefdone(self)->None:# Error reported by type checker...

There is no runtime checking of this property.

The decorator will attempt to set an__override__ attribute toTrue onthe decorated object. Thus, a check likeifgetattr(obj,"__override__",False) can be used at runtime to determinewhether an objectobj has been marked as an override. If the decorated objectdoes not support setting attributes, the decorator returns the object unchangedwithout raising an exception.

SeePEP 698 for more details.

Added in version 3.12.

@typing.type_check_only¶

Decorator to mark a class or function as 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.

Introspection helpers¶

typing.get_type_hints(obj,globalns=None,localns=None,include_extras=False)¶

Return a dictionary containing type hints for a function, method, moduleor class object.

This is often the same asobj.__annotations__, but this function makesthe following changes to the annotations dictionary:

Forward references encoded as string literals orForwardRefobjects are handled by evaluating them inglobalns,localns, and(where applicable)obj’stype parameter namespace.Ifglobalns orlocalns is not given, appropriate namespacedictionaries are inferred fromobj.
None is replaced withtypes.NoneType.
If@no_type_check has been applied toobj, anempty dictionary is returned.
Ifobj is a classC, the function returns a dictionary that mergesannotations fromC’s base classes with those onC directly. Thisis done by traversingC.__mro__ and iterativelycombining__annotations__ dictionaries. Annotations on classes appearingearlier in themethod resolution order always take precedence overannotations on classes appearing later in the method resolution order.
The function recursively replaces all occurrences ofAnnotated[T,...],Required[T],NotRequired[T], andReadOnly[T]withT, unlessinclude_extras is set toTrue (seeAnnotated for more information).

See alsoannotationlib.get_annotations(), a lower-level function thatreturns annotations more directly.

Caution

This function may execute arbitrary code contained in annotations.SeeSecurity implications of introspecting annotations for more information.

Note

If any forward references in the annotations ofobj are not resolvableor are not valid Python code, this function will raise an exceptionsuch asNameError. For example, this can happen with importedtype aliases that include forward references,or with names imported underifTYPE_CHECKING.

Changed in version 3.9:Addedinclude_extras parameter as part ofPEP 593.See the documentation onAnnotated for more information.

Changed in version 3.11:Previously,Optional[t] was added for function and method annotationsif a default value equal toNone was set.Now the annotation is returned unchanged.

typing.get_origin(tp)¶

Get the unsubscripted version of a type: for a typing object of the formX[Y,Z,...] returnX.

IfX is a typing-module alias for a builtin orcollections class, it will be normalized to the original class.IfX is an instance ofParamSpecArgs orParamSpecKwargs,return the underlyingParamSpec.ReturnNone for unsupported objects.

Examples:

assertget_origin(str)isNoneassertget_origin(Dict[str,int])isdictassertget_origin(Union[int,str])isUnionassertget_origin(Annotated[str,"metadata"])isAnnotatedP=ParamSpec('P')assertget_origin(P.args)isPassertget_origin(P.kwargs)isP

Added in version 3.8.

typing.get_args(tp)¶

Get type arguments with all substitutions performed: for a typing objectof the formX[Y,Z,...] return(Y,Z,...).

IfX is a union orLiteral contained in anothergeneric type, the order of(Y,Z,...) may be different from the orderof the original arguments[Y,Z,...] due to type caching.Return() for unsupported objects.

Examples:

assertget_args(int)==()assertget_args(Dict[int,str])==(int,str)assertget_args(Union[int,str])==(int,str)

Added in version 3.8.

typing.get_protocol_members(tp)¶

Return the set of members defined in aProtocol.

>>>fromtypingimportProtocol,get_protocol_members>>>classP(Protocol):...defa(self)->str:......b:int>>>get_protocol_members(P)==frozenset({'a','b'})True

RaiseTypeError for arguments that are not Protocols.

Added in version 3.13.

typing.is_protocol(tp)¶

Determine if a type is aProtocol.

For example:

classP(Protocol):defa(self)->str:...b:intis_protocol(P)# => Trueis_protocol(int)# => False

Added in version 3.13.

typing.is_typeddict(tp)¶

Check if a type is aTypedDict.

For example:

classFilm(TypedDict):title:stryear:intassertis_typeddict(Film)assertnotis_typeddict(list|str)# TypedDict is a factory for creating typed dicts,# not a typed dict itselfassertnotis_typeddict(TypedDict)

Added in version 3.10.

classtyping.ForwardRef¶

Class used for internal typing representation of string forward references.

For example,List["SomeClass"] is implicitly transformed intoList[ForwardRef("SomeClass")].ForwardRef should not be instantiated bya user, but may be used by introspection tools.

Note

PEP 585 generic types such aslist["SomeClass"] will not beimplicitly transformed intolist[ForwardRef("SomeClass")] and thuswill not automatically resolve tolist[SomeClass].

Added in version 3.7.4.

Changed in version 3.14:This is now an alias forannotationlib.ForwardRef. Several undocumentedbehaviors of this class have been changed; for example, after aForwardRef hasbeen evaluated, the evaluated value is no longer cached.

typing.evaluate_forward_ref(forward_ref,*,owner=None,globals=None,locals=None,type_params=None,format=annotationlib.Format.VALUE)¶

Evaluate anannotationlib.ForwardRef as atype hint.

This is similar to callingannotationlib.ForwardRef.evaluate(),but unlike that method,evaluate_forward_ref() alsorecursively evaluates forward references nested within the type hint.

See the documentation forannotationlib.ForwardRef.evaluate() forthe meaning of theowner,globals,locals,type_params, andformat parameters.

Caution

This function may execute arbitrary code contained in annotations.SeeSecurity implications of introspecting annotations for more information.

Added in version 3.14.

typing.NoDefault¶

A sentinel object used to indicate that a type parameter has no defaultvalue. For example:

>>>T=TypeVar("T")>>>T.__default__istyping.NoDefaultTrue>>>S=TypeVar("S",default=None)>>>S.__default__isNoneTrue

Added in version 3.13.

Constant¶

typing.TYPE_CHECKING¶

A special constant that is assumed to beTrue by 3rd party statictype checkers. It’sFalse at runtime.

A module which is expensive to import, and which only contain typesused for typing annotations, can be safely imported inside anifTYPE_CHECKING: block. This prevents the module from actuallybeing imported at runtime; annotations aren’t eagerly evaluated(seePEP 649) so using undefined symbols in annotations isharmless–as long as you don’t later examine them.Your static type analysis tool will setTYPE_CHECKING toTrue during static type analysis, which means the module willbe imported and the types will be checked properly during such analysis.

Usage:

ifTYPE_CHECKING:importexpensive_moddeffun(arg:expensive_mod.SomeType)->None:local_var:expensive_mod.AnotherType=other_fun()

If you occasionally need to examine type annotations at runtimewhich may contain undefined symbols, useannotationlib.get_annotations() with aformat parameterofannotationlib.Format.STRING orannotationlib.Format.FORWARDREF to safely retrieve theannotations without raisingNameError.

Added in version 3.5.2.

Deprecated aliases¶

This module defines several deprecated aliases to pre-existingstandard library classes. These were originally included in thetypingmodule in order to support parameterizing these generic classes using[].However, the aliases became redundant in Python 3.9 when thecorresponding pre-existing classes were enhanced to support[] (seePEP 585).

The redundant types are deprecated as of Python 3.9. However, while the aliasesmay be removed at some point, removal of these aliases is not currentlyplanned. As such, no deprecation warnings are currently issued by theinterpreter for these aliases.

If at some point it is decided to remove these deprecated aliases, adeprecation warning will be issued by the interpreter for at least two releasesprior to removal. The aliases are guaranteed to remain in thetyping modulewithout deprecation warnings until at least Python 3.14.

Type checkers are encouraged to flag uses of the deprecated types if theprogram they are checking targets a minimum Python version of 3.9 or newer.

Aliases to built-in types¶

classtyping.Dict(dict,MutableMapping[KT,VT])¶

Deprecated alias todict.

Note that to annotate arguments, it is preferredto use an abstract collection type such asMappingrather than to usedict ortyping.Dict.

Deprecated since version 3.9:builtins.dict now supports subscripting ([]).SeePEP 585 andGeneric Alias Type.

classtyping.List(list,MutableSequence[T])¶

Deprecated alias tolist.

Note that to annotate arguments, it is preferredto use an abstract collection type such asSequence orIterablerather than to uselist ortyping.List.

Deprecated since version 3.9:builtins.list now supports subscripting ([]).SeePEP 585 andGeneric Alias Type.

classtyping.Set(set,MutableSet[T])¶

Deprecated alias tobuiltins.set.

Note that to annotate arguments, it is preferredto use an abstract collection type such ascollections.abc.Setrather than to useset ortyping.Set.

Deprecated since version 3.9:builtins.set now supports subscripting ([]).SeePEP 585 andGeneric Alias Type.

classtyping.FrozenSet(frozenset,AbstractSet[T_co])¶: Deprecated alias tobuiltins.frozenset.
Deprecated since version 3.9:builtins.frozensetnow supports subscripting ([]).SeePEP 585 andGeneric Alias Type.

typing.Tuple¶

Deprecated alias fortuple.

tuple andTuple are special-cased in the type system; seeAnnotating tuples for more details.

Deprecated since version 3.9:builtins.tuple now supports subscripting ([]).SeePEP 585 andGeneric Alias Type.

classtyping.Type(Generic[CT_co])¶

Deprecated alias totype.

SeeThe type of class objects for details on usingtype ortyping.Type in type annotations.

Added in version 3.5.2.

Deprecated since version 3.9:builtins.type now supports subscripting ([]).SeePEP 585 andGeneric Alias Type.

Aliases to types in`collections`¶

classtyping.DefaultDict(collections.defaultdict,MutableMapping[KT,VT])¶: Deprecated alias tocollections.defaultdict.
Added in version 3.5.2.
Deprecated since version 3.9:collections.defaultdict now supports subscripting ([]).SeePEP 585 andGeneric Alias Type.

classtyping.OrderedDict(collections.OrderedDict,MutableMapping[KT,VT])¶: Deprecated alias tocollections.OrderedDict.
Added in version 3.7.2.
Deprecated since version 3.9:collections.OrderedDict now supports subscripting ([]).SeePEP 585 andGeneric Alias Type.

classtyping.ChainMap(collections.ChainMap,MutableMapping[KT,VT])¶: Deprecated alias tocollections.ChainMap.
Added in version 3.6.1.
Deprecated since version 3.9:collections.ChainMap now supports subscripting ([]).SeePEP 585 andGeneric Alias Type.

classtyping.Counter(collections.Counter,Dict[T,int])¶: Deprecated alias tocollections.Counter.
Added in version 3.6.1.
Deprecated since version 3.9:collections.Counter now supports subscripting ([]).SeePEP 585 andGeneric Alias Type.

classtyping.Deque(deque,MutableSequence[T])¶: Deprecated alias tocollections.deque.
Added in version 3.6.1.
Deprecated since version 3.9:collections.deque now supports subscripting ([]).SeePEP 585 andGeneric Alias Type.

Aliases to other concrete types¶

classtyping.Pattern¶

classtyping.Match¶

Deprecated aliases corresponding to the return types fromre.compile() andre.match().

These types (and the corresponding functions) are generic overAnyStr.Pattern can be specialised asPattern[str] orPattern[bytes];Match can be specialised asMatch[str] orMatch[bytes].

Deprecated since version 3.9:ClassesPattern andMatch fromre now support[].SeePEP 585 andGeneric Alias Type.

classtyping.Text¶

Deprecated alias forstr.

Text is provided to supply a forwardcompatible path for Python 2 code: in Python 2,Text is an alias forunicode.

UseText to 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'

Added in version 3.5.2.

Deprecated since version 3.11:Python 2 is no longer supported, and most type checkers also no longersupport type checking Python 2 code. Removal of the alias is notcurrently planned, but users are encouraged to usestr instead ofText.

Aliases to container ABCs in`collections.abc`¶

classtyping.AbstractSet(Collection[T_co])¶: Deprecated alias tocollections.abc.Set.
Deprecated since version 3.9:collections.abc.Set now supports subscripting ([]).SeePEP 585 andGeneric Alias Type.

classtyping.ByteString(Sequence[int])¶

Deprecated alias tocollections.abc.ByteString.

Useisinstance(obj,collections.abc.Buffer) to test ifobjimplements thebuffer protocol at runtime. For use intype annotations, either useBuffer or a unionthat explicitly specifies the types your code supports (e.g.,bytes|bytearray|memoryview).

ByteString was originally intended to be an abstract class thatwould serve as a supertype of bothbytes andbytearray.However, since the ABC never had any methods, knowing that an object was aninstance ofByteString never actually told you anything usefulabout the object. Other common buffer types such asmemoryview werealso never understood as subtypes ofByteString (either at runtimeor by static type checkers).

SeePEP 688 for more details.

Deprecated since version 3.9, will be removed in version 3.17.

classtyping.Collection(Sized,Iterable[T_co],Container[T_co])¶: Deprecated alias tocollections.abc.Collection.
Added in version 3.6.
Deprecated since version 3.9:collections.abc.Collection now supports subscripting ([]).SeePEP 585 andGeneric Alias Type.

classtyping.Container(Generic[T_co])¶: Deprecated alias tocollections.abc.Container.
Deprecated since version 3.9:collections.abc.Container now supports subscripting ([]).SeePEP 585 andGeneric Alias Type.

classtyping.ItemsView(MappingView,AbstractSet[tuple[KT_co,VT_co]])¶: Deprecated alias tocollections.abc.ItemsView.
Deprecated since version 3.9:collections.abc.ItemsView now supports subscripting ([]).SeePEP 585 andGeneric Alias Type.

classtyping.KeysView(MappingView,AbstractSet[KT_co])¶: Deprecated alias tocollections.abc.KeysView.
Deprecated since version 3.9:collections.abc.KeysView now supports subscripting ([]).SeePEP 585 andGeneric Alias Type.

classtyping.Mapping(Collection[KT],Generic[KT,VT_co])¶: Deprecated alias tocollections.abc.Mapping.
Deprecated since version 3.9:collections.abc.Mapping now supports subscripting ([]).SeePEP 585 andGeneric Alias Type.

classtyping.MappingView(Sized)¶: Deprecated alias tocollections.abc.MappingView.
Deprecated since version 3.9:collections.abc.MappingView now supports subscripting ([]).SeePEP 585 andGeneric Alias Type.

classtyping.MutableMapping(Mapping[KT,VT])¶: Deprecated alias tocollections.abc.MutableMapping.
Deprecated since version 3.9:collections.abc.MutableMappingnow supports subscripting ([]).SeePEP 585 andGeneric Alias Type.

classtyping.MutableSequence(Sequence[T])¶: Deprecated alias tocollections.abc.MutableSequence.
Deprecated since version 3.9:collections.abc.MutableSequencenow supports subscripting ([]).SeePEP 585 andGeneric Alias Type.

classtyping.MutableSet(AbstractSet[T])¶: Deprecated alias tocollections.abc.MutableSet.
Deprecated since version 3.9:collections.abc.MutableSet now supports subscripting ([]).SeePEP 585 andGeneric Alias Type.

classtyping.Sequence(Reversible[T_co],Collection[T_co])¶: Deprecated alias tocollections.abc.Sequence.
Deprecated since version 3.9:collections.abc.Sequence now supports subscripting ([]).SeePEP 585 andGeneric Alias Type.

classtyping.ValuesView(MappingView,Collection[_VT_co])¶: Deprecated alias tocollections.abc.ValuesView.
Deprecated since version 3.9:collections.abc.ValuesView now supports subscripting ([]).SeePEP 585 andGeneric Alias Type.

Aliases to asynchronous ABCs in`collections.abc`¶

classtyping.Coroutine(Awaitable[ReturnType],Generic[YieldType,SendType,ReturnType])¶

Deprecated alias tocollections.abc.Coroutine.

SeeAnnotating generators and coroutinesfor details on usingcollections.abc.Coroutineandtyping.Coroutine in type annotations.

Added in version 3.5.3.

Deprecated since version 3.9:collections.abc.Coroutine now supports subscripting ([]).SeePEP 585 andGeneric Alias Type.

classtyping.AsyncGenerator(AsyncIterator[YieldType],Generic[YieldType,SendType])¶

Deprecated alias tocollections.abc.AsyncGenerator.

SeeAnnotating generators and coroutinesfor details on usingcollections.abc.AsyncGeneratorandtyping.AsyncGenerator in type annotations.

Added in version 3.6.1.

Deprecated since version 3.9:collections.abc.AsyncGeneratornow supports subscripting ([]).SeePEP 585 andGeneric Alias Type.

Changed in version 3.13:TheSendType parameter now has a default.

classtyping.AsyncIterable(Generic[T_co])¶: Deprecated alias tocollections.abc.AsyncIterable.
Added in version 3.5.2.
Deprecated since version 3.9:collections.abc.AsyncIterable now supports subscripting ([]).SeePEP 585 andGeneric Alias Type.

classtyping.AsyncIterator(AsyncIterable[T_co])¶: Deprecated alias tocollections.abc.AsyncIterator.
Added in version 3.5.2.
Deprecated since version 3.9:collections.abc.AsyncIterator now supports subscripting ([]).SeePEP 585 andGeneric Alias Type.

classtyping.Awaitable(Generic[T_co])¶: Deprecated alias tocollections.abc.Awaitable.
Added in version 3.5.2.
Deprecated since version 3.9:collections.abc.Awaitable now supports subscripting ([]).SeePEP 585 andGeneric Alias Type.

Aliases to other ABCs in`collections.abc`¶

classtyping.Iterable(Generic[T_co])¶: Deprecated alias tocollections.abc.Iterable.
Deprecated since version 3.9:collections.abc.Iterable now supports subscripting ([]).SeePEP 585 andGeneric Alias Type.

classtyping.Iterator(Iterable[T_co])¶: Deprecated alias tocollections.abc.Iterator.
Deprecated since version 3.9:collections.abc.Iterator now supports subscripting ([]).SeePEP 585 andGeneric Alias Type.

typing.Callable¶

Deprecated alias tocollections.abc.Callable.

SeeAnnotating callable objects for details on how to usecollections.abc.Callable andtyping.Callable in type annotations.

Deprecated since version 3.9:collections.abc.Callable now supports subscripting ([]).SeePEP 585 andGeneric Alias Type.

Changed in version 3.10:Callable now supportsParamSpec andConcatenate.SeePEP 612 for more details.

classtyping.Generator(Iterator[YieldType],Generic[YieldType,SendType,ReturnType])¶

Deprecated alias tocollections.abc.Generator.

SeeAnnotating generators and coroutinesfor details on usingcollections.abc.Generatorandtyping.Generator in type annotations.

Deprecated since version 3.9:collections.abc.Generator now supports subscripting ([]).SeePEP 585 andGeneric Alias Type.

Changed in version 3.13:Default values for the send and return types were added.

classtyping.Hashable¶: Deprecated alias tocollections.abc.Hashable.
Deprecated since version 3.12:Usecollections.abc.Hashable directly instead.

classtyping.Reversible(Iterable[T_co])¶: Deprecated alias tocollections.abc.Reversible.
Deprecated since version 3.9:collections.abc.Reversible now supports subscripting ([]).SeePEP 585 andGeneric Alias Type.

classtyping.Sized¶: Deprecated alias tocollections.abc.Sized.
Deprecated since version 3.12:Usecollections.abc.Sized directly instead.

Aliases to`contextlib` ABCs¶

classtyping.ContextManager(Generic[T_co,ExitT_co])¶

Deprecated alias tocontextlib.AbstractContextManager.

The first type parameter,T_co, represents the type returned bythe__enter__() method. The optional second type parameter,ExitT_co,which defaults tobool|None, represents the type returned by the__exit__() method.

Added in version 3.5.4.

Deprecated since version 3.9:contextlib.AbstractContextManagernow supports subscripting ([]).SeePEP 585 andGeneric Alias Type.

Changed in version 3.13:Added the optional second type parameter,ExitT_co.

classtyping.AsyncContextManager(Generic[T_co,AExitT_co])¶

Deprecated alias tocontextlib.AbstractAsyncContextManager.

The first type parameter,T_co, represents the type returned bythe__aenter__() method. The optional second type parameter,AExitT_co,which defaults tobool|None, represents the type returned by the__aexit__() method.

Added in version 3.6.2.

Deprecated since version 3.9:contextlib.AbstractAsyncContextManagernow supports subscripting ([]).SeePEP 585 andGeneric Alias Type.

Changed in version 3.13:Added the optional second type parameter,AExitT_co.

Deprecation Timeline of Major Features¶

Certain features intyping are deprecated and may be removed in a futureversion of Python. The following table summarizes major deprecations for yourconvenience. This is subject to change, and not all deprecations are listed.

Feature	Deprecated in	Projected removal	PEP/issue
`typing` versions of standard collections	3.9	Undecided (seeDeprecated aliases for more information)	PEP 585
`typing.ByteString`	3.9	3.17	gh-91896
`typing.Text`	3.11	Undecided	gh-92332
`typing.Hashable` and`typing.Sized`	3.12	Undecided	gh-94309
`typing.TypeAlias`	3.12	Undecided	PEP 695
`@typing.no_type_check_decorator`	3.13	3.15	gh-106309
`typing.AnyStr`	3.13	3.18	gh-105578

Movatterモバイル変換

Navigation

`typing` — Support for type hints¶

Specification for the Python Type System¶

Type aliases¶

NewType¶

Annotating callable objects¶

Generics¶

Annotating tuples¶

The type of class objects¶

Annotating generators and coroutines¶

User-defined generic types¶

The`Any` type¶

Nominal vs structural subtyping¶

Module contents¶

Special typing primitives¶

Special types¶

Special forms¶

Building generic types and type aliases¶

Other special directives¶

Protocols¶

ABCs and Protocols for working with I/O¶

Functions and decorators¶

Introspection helpers¶

Constant¶

Deprecated aliases¶

Aliases to built-in types¶

Aliases to types in`collections`¶

Aliases to other concrete types¶

Aliases to container ABCs in`collections.abc`¶

Aliases to asynchronous ABCs in`collections.abc`¶

Aliases to other ABCs in`collections.abc`¶

Aliases to`contextlib` ABCs¶

Deprecation Timeline of Major Features¶

Table of Contents

Previous topic

Next topic

This page

Navigation

Movatterモバイル変換

typing — Support for type hints¶

Specification for the Python Type System¶

Type aliases¶

NewType¶

Annotating callable objects¶

Generics¶

Annotating tuples¶

The type of class objects¶

Annotating generators and coroutines¶

User-defined generic types¶

TheAny type¶

Nominal vs structural subtyping¶

Module contents¶

Special typing primitives¶

Special types¶

Special forms¶

Building generic types and type aliases¶

Other special directives¶

Protocols¶

ABCs and Protocols for working with I/O¶

Functions and decorators¶

Introspection helpers¶

Constant¶

Deprecated aliases¶

Aliases to built-in types¶

Aliases to types incollections¶

Aliases to other concrete types¶

Aliases to container ABCs incollections.abc¶

Aliases to asynchronous ABCs incollections.abc¶

Aliases to other ABCs incollections.abc¶

Aliases tocontextlib ABCs¶

Deprecation Timeline of Major Features¶

`typing` — Support for type hints¶

The`Any` type¶

Aliases to types in`collections`¶

Aliases to container ABCs in`collections.abc`¶

Aliases to asynchronous ABCs in`collections.abc`¶

Aliases to other ABCs in`collections.abc`¶

Aliases to`contextlib` ABCs¶