typing — Support for type hints

New in version 3.5.

Source code:Lib/typing.py

Note

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

This module provides runtime support for type hints. For the originalspecification of the typing system, seePEP 484. For a simplifiedintroduction to type hints, seePEP 483.

The function below takes and returns a string and is annotated as follows:

defgreeting(name:str)->str:return'Hello '+name

In the functiongreeting, the argumentname is expected to be of typestr and the return typestr. Subtypes are accepted asarguments.

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

For a summary of deprecated features and a deprecation timeline, please seeDeprecation Timeline of Major Features.

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.

Relevant PEPs

Since the initial introduction of type hints inPEP 484 andPEP 483, anumber of PEPs have modified and enhanced Python’s framework for typeannotations:

The full list of PEPs

Type aliases

A type alias is defined by assigning the type to the alias. In this example,Vector andlist[float] will be treated as interchangeable synonyms:

Vector=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.abcimportSequenceConnectionOptions=dict[str,str]Address=tuple[str,int]Server=tuple[Address,ConnectionOptions]defbroadcast_message(message:str,servers:Sequence[Server])->None:...# The static type checker will treat the previous type signature as# being exactly equivalent to this one.defbroadcast_message(message:str,servers:Sequence[tuple[tuple[str,int],dict[str,str]]])->None:...

Type aliases may be marked withTypeAlias to make it explicit thatthe statement is a type alias declaration, 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. DoingAlias=Original will make the static type checkertreatAlias as beingexactly equivalent toOriginal in all cases.This is useful when you want to simplify complex type signatures.

In contrast,NewType declares one type to be asubtype of another.DoingDerived=NewType('Derived',Original) will make the static typechecker treatDerived as asubclass ofOriginal, which means avalue of typeOriginal cannot be used in places where a value of typeDerived is expected. This is useful when you want to prevent logicerrors with minimal runtime cost.

New in version 3.5.2.

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 ortyping.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:...

Generics can be parameterized by using a factory available in typingcalledTypeVar.

fromcollections.abcimportSequencefromtypingimportTypeVarT=TypeVar('T')# Declare type variable "T"deffirst(l:Sequence[T])->T:# Function is generic over the TypeVar "T"returnl[0]

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, usetuple[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] (ortyping.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.

User-defined generic types

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

fromtypingimportTypeVar,GenericfromloggingimportLoggerT=TypeVar('T')classLoggedVar(Generic[T]):def__init__(self,value:T,name:str,logger:Logger)->None:self.name=nameself.logger=loggerself.value=valuedefset(self,new:T)->None:self.log('Set '+repr(self.value))self.value=newdefget(self)->T:self.log('Get '+repr(self.value))returnself.valuedeflog(self,message:str)->None:self.logger.info('%s:%s',self.name,message)

Generic[T] as a base class defines that the classLoggedVar takes asingle type parameterT . This also makesT valid as a type within theclass body.

TheGeneric base class defines__class_getitem__() sothatLoggedVar[T] is valid as a type:

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,SequenceT=TypeVar('T',contravariant=True)B=TypeVar('B',bound=Sequence[bytes],covariant=True)S=TypeVar('S',int,str)classWeirdTrio(Generic[T,B,S]):...

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

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

You can use multiple inheritance withGeneric:

fromcollections.abcimportSizedfromtypingimportTypeVar,GenericT=TypeVar('T')classLinkedList(Sized,Generic[T]):...

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

fromcollections.abcimportMappingfromtypingimportTypeVarT=TypeVar('T')classMyDict(Mapping[str,T]):...

In this caseMyDict has a single parameter,T.

Using a generic class without specifying type parameters assumesAny for each position. In the following example,MyIterable isnot generic but implicitly inherits fromIterable[Any]:

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

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

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

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

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

>>>fromtypingimportGeneric,ParamSpec,TypeVar>>>T=TypeVar('T')>>>P=ParamSpec('P')>>>classZ(Generic[T,P]):......>>>Z[int,[dict,float]]__main__.Z[int, (<class 'dict'>, <class 'float'>)]

Furthermore, a generic 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(Generic[P]):......>>>X[int,str]__main__.X[(<class 'int'>, <class 'str'>)]>>>X[[int,str]]__main__.X[(<class 'int'>, <class '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 the typing module arehashable andcomparable for equality.

TheAny type

A special kind of type isAny. A static type checker will treatevery type as being compatible withAny andAny as beingcompatible with every type.

This means that it is possible to perform any operation or method call on avalue of 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!"
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.

New in version 3.11.

typing.Never

Thebottom type,a type that has no members.

This can be used to define a function that should never becalled, or a function that never returns:

fromtypingimportNeverdefnever_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

New in version 3.11:On older Python versions,NoReturn may be used to express thesame concept.Never was added to make the intended meaning more explicit.

typing.NoReturn

Special type indicating that a function never returns.

For example:

fromtypingimportNoReturndefstop()->NoReturn:raiseRuntimeError('no way')

NoReturn can also be used as abottom type, a type thathas no values. Starting in Python 3.11, theNever type shouldbe used for this concept instead. Type checkers should treat the twoequivalently.

New in version 3.6.2.

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.

New in version 3.11.

typing.TypeAlias

Special annotation for explicitly declaring atype alias.

For example:

fromtypingimportTypeAliasFactors:TypeAlias=list[int]

TypeAlias is particularly useful 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.# 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.

New in version 3.10.

Special forms

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

typing.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]

  • 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.

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,ParamSpec,TypeVarP=ParamSpec('P')R=TypeVar('R')# Use this lock to ensure that only one thread is executing a function# at any time.my_lock=Lock()defwith_lock(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])

New in version 3.10.

See also

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...Mode:TypeAlias=Literal['r','rb','w','wb']defopen_helper(file:str,mode:Mode)->str:...open_helper('/some/path','r')# Passes type checkopen_helper('/other/path','typo')# Error in type checker

Literal[...] cannot be subclassed. At runtime, an arbitrary valueis allowed as type argument toLiteral[...], but type checkers mayimpose restrictions. SeePEP 586 for more details about literal types.

New in version 3.8.

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

New in version 3.5.3.

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.

New in version 3.8.

typing.Required

Special typing construct to mark aTypedDict key as required.

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

New in version 3.11.

typing.NotRequired

Special typing construct to mark aTypedDict key as potentiallymissing.

SeeTypedDict andPEP 655 for more details.

New in version 3.11.

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)]

Details of the syntax:

  • The first argument toAnnotated must be a valid type

  • Multiple metadata elements can be supplied (Annotated supports variadicarguments):

    @dataclassclassctype:kind:strAnnotated[int,ValueRange(3,10),ctype("char")]

    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.

  • Annotated must be subscripted with at least two arguments (Annotated[int] is not valid)

  • The order of the metadata elements is preserved and matters for equalitychecks:

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

  • 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")]

  • 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:intT=TypeVar("T")Vec:TypeAlias=Annotated[list[tuple[T,T]],MaxLen(10)]assertVec[int]==Annotated[list[tuple[int,int]],MaxLen(10)]

  • Annotated cannot be used with an unpackedTypeVarTuple:

    Variadic:TypeAlias=Annotated[*Ts,Ann1]# NOT valid

    This would be equivalent to:

    Annotated[T1,T2,T3,...,Ann1]

    whereT1,T2, etc. areTypeVars. This would beinvalid: only 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')

See also

PEP 593 - Flexible function and variable annotations

The PEP introducingAnnotated to the standard library.

New in version 3.9.

typing.TypeGuard

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

TypeGuard can be used to annotate the return type of a user-definedtype guard function.TypeGuard only accepts a single type argument.At runtime, functions marked this way should return a boolean.

TypeGuard 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 guard”:

defis_str(val:str|float):# "isinstance" type guardifisinstance(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 guard. Such a function should useTypeGuard[...] as itsreturn type to alert static type checkers to this intention.

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

  1. The return value is a boolean.

  2. If the return value isTrue, the type of its argumentis the type insideTypeGuard.

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!")

Ifis_str_list is a class or instance method, then the type inTypeGuard maps to the type of the second parameter aftercls orself.

In short, the formdeffoo(arg:TypeA)->TypeGuard[TypeB]:...,means that iffoo(arg) returnsTrue, thenarg narrows fromTypeA toTypeB.

Note

TypeB need not be a narrower form ofTypeA – it can even be awider form. 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.The responsibility of writing type-safe type guards is left to the user.

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

New 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

New in version 3.11.

Building generic types

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

classtyping.Generic

Abstract base class for generic types.

A generic type is typically declared by inheriting from aninstantiation of this class with one or more type variables.For example, a generic mapping type might be defined as:

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

This class can then be used as follows:

X=TypeVar('X')Y=TypeVar('Y')deflookup_name(mapping:Mapping[X,Y],key:X,default:Y)->Y:try:returnmapping[key]exceptKeyError:returndefault
classtyping.TypeVar(name,*constraints,bound=None,covariant=False,contravariant=False)

Type variable.

Usage:

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

Note that type variables can bebound,constrained, or neither, butcannot be both boundand constrained.

Type variables may be marked covariant or contravariant by passingcovariant=True orcontravariant=True. SeePEP 484 for moredetails. By default, type variables are invariant.

Bound type variables and constrained type variables have differentsemantics in several important ways. Using abound 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

Type variables can be bound to concrete types, abstract types (ABCs orprotocols), and even unions of types:

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 marked as covariant.

__contravariant__

Whether the type var has been marked as contravariant.

__bound__

The bound of the type variable, if any.

__constraints__

A tuple containing the constraints of the type variable, if any.

classtyping.TypeVarTuple(name)

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

Usage:

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:

Shape=TypeVarTuple("Shape")classArray(Generic[*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:

DType=TypeVar('DType')Shape=TypeVarTuple('Shape')classArray(Generic[DType,*Shape]):# This is finepassclassArray2(Generic[*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(Generic[*Shape,*Shape]):# Not validpass

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

defcall_soon(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.

New in version 3.11.

classtyping.ParamSpec(name,*,bound=None,covariant=False,contravariant=False)

Parameter specification variable. A specialized version oftype variables.

Usage:

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.abcimportCallablefromtypingimportTypeVar,ParamSpecimportloggingT=TypeVar('T')P=ParamSpec('P')defadd_logging(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 boundCallable[...,Any]. However thiscauses two problems:

  1. The type checker can’t type check theinner function because*args and**kwargs have to be typedAny.

  2. 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.

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.

New in version 3.10.

Note

Only parameter specification variables defined in global scope canbe pickled.

See also

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

New in version 3.10.

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(NamedTuple,Generic[T]):key:Tgroup:list[T]

Backward-compatible usage:

Employee=NamedTuple('Employee',[('name',str),('id',int)])

Changed in version 3.6:Added support forPEP 526 variable annotation syntax.

Changed in version 3.6.1:Added support for default values, methods, and docstrings.

Changed in version 3.8: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.

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 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.

New 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 can be generic, for example:

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

New in version 3.8.

@typing.runtime_checkable

Mark a protocol class as a runtime protocol.

Such a protocol can be used withisinstance() andissubclass().This raisesTypeError when applied to a non-protocol class. Thisallows 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)

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.

New in version 3.8.

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

To allow using this feature with older versions of Python that do notsupportPEP 526,TypedDict supports two additional equivalentsyntactic forms:

  • Using a literaldict as the second argument:

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

  • Using keyword arguments:

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

Deprecated since version 3.11, will be removed in version 3.13:The keyword-argument syntax is deprecated in 3.11 and will be removedin 3.13. It may also be unsupported by static type checkers.

The functional syntax should also be used when any of the keys are not valididentifiers, for example because they are keywords or contain hyphens.Example:

# raises SyntaxErrorclassPoint2D(TypedDict):in:int# 'in' is a keywordx-y:int# name with hyphens# OK, functional syntaxPoint2D=TypedDict('Point2D',{'in':int,'x-y':int})

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:

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 to True 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__

New 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

New 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.

SeePEP 589 for more examples and detailed rules of usingTypedDict.

New 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.

Protocols

The following protocols are provided by the typing 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__.

New 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 for working with IO

classtyping.IO
classtyping.TextIO
classtyping.BinaryIO

Generic typeIO[AnyStr] and its subclassesTextIO(IO[str])andBinaryIO(IO[bytes])represent the types of I/O streams such as returned byopen().

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)

New 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.

New 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.

New in version 3.11.

@typing.dataclass_transform(*,eq_default=True,order_default=False,kw_only_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:

T=TypeVar("T")@dataclass_transform()defcreate_model(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.

  • 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 toTrue.

default

Provides the default value for the field.

default_factory

Provides a runtime callback that returns thedefault value for the field. If neitherdefault nordefault_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 thedefault_factory parameter on field specifiers.

kw_only

Indicates whether the field should be marked askeyword-only. IfTrue, the field will be keyword-only. IfFalse, it will not be keyword-only. If unspecified, the value ofthekw_only parameter on the object decorated withdataclass_transform will be used, or if that is unspecified, thevalue ofkw_only_default ondataclass_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.

New 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.

New 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.

New 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.

New 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().

@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__. In addition,forward references encoded as string literals are handled by evaluatingthem inglobals andlocals namespaces. For a classC, returna dictionary constructed by merging all the__annotations__ alongC.__mro__ in reverse order.

The function recursively replaces allAnnotated[T,...] withT,unlessinclude_extras is set toTrue (seeAnnotated formore information). For example:

classStudent(NamedTuple):name:Annotated[str,'some marker']assertget_type_hints(Student)=={'name':str}assertget_type_hints(Student,include_extras=False)=={'name':str}assertget_type_hints(Student,include_extras=True)=={'name':Annotated[str,'some marker']}

Note

get_type_hints() does not work with importedtype aliases that include forward references.Enabling postponed evaluation of annotations (PEP 563) may removethe need for most forward references.

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])isUnionP=ParamSpec('P')assertget_origin(P.args)isPassertget_origin(P.kwargs)isP

New 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)

New in version 3.8.

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)

New 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].

New in version 3.7.4.

Constant

typing.TYPE_CHECKING

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

Usage:

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

The first type annotation must be enclosed in quotes, making it a“forward reference”, to hide theexpensive_mod reference from theinterpreter runtime. Type annotations for local variables are notevaluated, so the second annotation does not need to be enclosed in quotes.

Note

Iffrom__future__importannotations is used,annotations are not evaluated at function definition time.Instead, they are stored as strings in__annotations__.This makes it unnecessary to use quotes around the annotation(seePEP 563).

New in version 3.5.2.

Deprecated aliases

This module defines several deprecated aliases to pre-existingstandard library classes. These were originally included in the typingmodule 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 the typing 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.

This type can be used as follows:

defcount_words(text:str)->Dict[str,int]:...

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 orIterable rather than to uselist ortyping.List.

This type may be used as follows:

T=TypeVar('T',int,float)defvec2(x:T,y:T)->List[T]:return[x,y]defkeep_positives(vector:Sequence[T])->List[T]:return[itemforiteminvectorifitem>0]

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 asAbstractSetrather 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.

New in version 3.5.2.

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

Aliases to types incollections

classtyping.DefaultDict(collections.defaultdict,MutableMapping[KT,VT])

Deprecated alias tocollections.defaultdict.

New 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.

New 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.

New 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.

New 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.

New 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.8, will be removed in version 3.13:Thetyping.re namespace is deprecated and will be removed.These types should be directly imported fromtyping instead.

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'

New 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 incollections.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])

This type represents the typesbytes,bytearray,andmemoryview of byte sequences.

Deprecated since version 3.9, will be removed in version 3.14:Prefertyping_extensions.Buffer, or a union likebytes|bytearray|memoryview.

classtyping.Collection(Sized,Iterable[T_co],Container[T_co])

Deprecated alias tocollections.abc.Collection.

New 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.

This type can be used as follows:

defget_position_in_index(word_list:Mapping[str,int],word:str)->int:returnword_list[word]

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 incollections.abc

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

Deprecated alias tocollections.abc.Coroutine.

The variance and order of type variablescorrespond 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

New 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.

An async generator can be annotated by the generic typeAsyncGenerator[YieldType,SendType]. For example:

asyncdefecho_round()->AsyncGenerator[int,float]:sent=yield0whilesent>=0.0:rounded=awaitround(sent)sent=yieldrounded

Unlike normal generators, async generators cannot return a value, so thereis noReturnType type parameter. As withGenerator, theSendType behaves contravariantly.

If your generator will only yield values, set theSendType toNone:

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

Alternatively, annotate your generator as having a return type ofeitherAsyncIterable[YieldType] orAsyncIterator[YieldType]:

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

New in version 3.6.1.

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

classtyping.AsyncIterable(Generic[T_co])

Deprecated alias tocollections.abc.AsyncIterable.

New 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.

New 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.

New 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 incollections.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.

A generator can be annotated by 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 generics in the typing module, theSendTypeofGenerator behaves contravariantly, not covariantly orinvariantly.

If your generator will only yield values, set theSendType andReturnType toNone:

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

Alternatively, annotate your generator as having a return type ofeitherIterable[YieldType] orIterator[YieldType]:

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

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

classtyping.Hashable

Alias tocollections.abc.Hashable.

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

Alias tocollections.abc.Sized.

Aliases tocontextlib ABCs

classtyping.ContextManager(Generic[T_co])

Deprecated alias tocontextlib.AbstractContextManager.

New in version 3.5.4.

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

classtyping.AsyncContextManager(Generic[T_co])

Deprecated alias tocontextlib.AbstractAsyncContextManager.

New in version 3.6.2.

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

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.io andtyping.re submodules

3.8

3.13

bpo-38291

typing versions of standard collections

3.9

Undecided (seeDeprecated aliases for more information)

PEP 585

typing.ByteString

3.9

3.14

gh-91896

typing.Text

3.11

Undecided

gh-92332