Special types¶

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

typing.Any¶

Special type indicating an unconstrained type.

• Every type is compatible withAny.

• Any is compatible with every type.

typing.NoReturn¶

Special type indicating that a function never returns.For example:

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

New in version 3.5.4.

New in version 3.6.2.

Special forms¶

These can be used as types in annotations using[], each having a unique syntax.

typing.Tuple¶

Tuple type;Tuple[X,Y] is the type of a tuple of two itemswith the first item of type X and the second of type Y. The type ofthe empty tuple can be written asTuple[()].

Example:Tuple[T1,T2] is a tuple of two elements correspondingto type variables T1 and T2.Tuple[int,float,str] is a tupleof an int, a float and a string.

To specify a variable-length tuple of homogeneous type,use literal ellipsis, e.g.Tuple[int,...]. A plainTupleis equivalent toTuple[Any,...], and in turn totuple.

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

typing.Union¶

Union type;Union[X,Y] means either X or Y.

To define a union, use e.g.Union[int,str]. Details:

• The arguments must be types and there must be at least one.

• Unions of unions are flattened, e.g.:

  Union[Union[int,str],float]==Union[int,str,float]

• Unions of a single argument vanish, e.g.:

  Union[int]==int# The constructor actually returns int

• Redundant arguments are skipped, e.g.:

  Union[int,str,int]==Union[int,str]

• When comparing unions, the argument order is ignored, e.g.:

  Union[int,str]==Union[str,int]

• You cannot subclass or instantiate a union.

• You cannot writeUnion[X][Y].

• You can useOptional[X] as a shorthand forUnion[X,None].

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

typing.Optional¶

Optional type.

Optional[X] is equivalent toUnion[X,None].

Note that this is not the same concept as an optional argument,which is one that has a default. An optional argument with adefault does not require 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:...

typing.Callable¶

Callable type;Callable[[int],str] is a function of (int) -> str.

The subscription syntax must always be used with exactly twovalues: the argument list and the return type. The argument listmust be a list of types or an ellipsis; the return type must bea single type.

There is no syntax to indicate optional or keyword arguments;such function types are rarely used as callback types.Callable[...,ReturnType] (literal ellipsis) can be used totype hint a callable taking any number of arguments and returningReturnType. A plainCallable is equivalent toCallable[...,Any], and in turn tocollections.abc.Callable.

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

classtyping.Type(Generic[CT_co])¶

A variable annotated withC may accept a value of typeC. Incontrast, a variable annotated withType[C] may accept values that areclasses themselves – specifically, it will accept theclass object ofC. For example:

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

Note thatType[C] is covariant:

classUser:...classBasicUser(User):...classProUser(User):...classTeamUser(User):...# Accepts User, BasicUser, ProUser, TeamUser, ...defmake_new_user(user_class:Type[User])->User:# ...returnuser_class()

The fact thatType[C] is covariant implies that all subclasses ofC should implement the same constructor signature and class methodsignatures asC. The type checker should flag violations of this,but should also allow constructor calls in subclasses that match theconstructor calls in the indicated base class. How the type checker isrequired to handle this particular case may change in future revisions ofPEP 484.

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

defnew_non_team_user(user_class:Type[Union[BasicUser,ProUser]]):...

Type[Any] is equivalent toType which in turn is equivalenttotype, which is the root of Python’s metaclass hierarchy.

New in version 3.5.2.

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

typing.Literal¶

A type that can be used to indicate to type checkers that thecorresponding variable or function parameter has a value equivalent tothe provided literal (or one of several literals). For example:

defvalidate_simple(data:Any)->Literal[True]:# always returns True...MODE=Literal['r','rb','w','wb']defopen_helper(file:str,mode:MODE)->str:...open_helper('/some/path','r')# Passes type checkopen_helper('/other/path','typo')# Error in type checker

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

New in version 3.8.

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¶

A special typing construct to indicate to type checkers that a namecannot be re-assigned or overridden in a subclass. For example:

MAX_SIZE:Final=9000MAX_SIZE+=1# Error reported by type checkerclassConnection:TIMEOUT:Final[int]=10classFastConnector(Connection):TIMEOUT=1# Error reported by type checker

There is no runtime checking of these properties. SeePEP 591 formore details.

New in version 3.8.

typing.Annotated¶

A type, introduced inPEP 593 (Flexiblefunctionandvariableannotations), to decorate existing types with context-specific metadata(possibly multiple pieces of it, asAnnotated is variadic).Specifically, a typeT can be annotated with metadatax via thetypehintAnnotated[T,x]. This metadata can be used for either staticanalysis or at runtime. If a library (or tool) encounters a typehintAnnotated[T,x] and has no special logic for metadatax, itshould ignore it and simply treat the type asT. Unlike theno_type_check functionality that currently exists in thetypingmodule which completely disables typechecking annotations on a functionor a class, theAnnotated type allows for both static typecheckingofT (which can safely ignorex)together with runtime access tox within a specific application.

Ultimately, the responsibility of how to interpret the annotations (ifat all) is the responsibility of the tool or library encountering theAnnotated type. A tool or library encountering anAnnotated typecan scan through the annotations to determine if they are of interest(e.g., usingisinstance()).

When a tool or a library does not support annotations or encounters anunknown annotation it should just ignore it and treat annotated type asthe underlying type.

It’s up to the tool consuming the annotations to decide whether theclient is allowed to have several annotations on one type and how tomerge those annotations.

Since theAnnotated type allows you to put several annotations ofthe same (or different) type(s) on any node, the tools or librariesconsuming those annotations are in charge of dealing with potentialduplicates. For example, if you are doing value range analysis you mightallow this:

T1=Annotated[int,ValueRange(-10,5)]T2=Annotated[T1,ValueRange(-20,3)]

Passinginclude_extras=True toget_type_hints() lets oneaccess the extra annotations at runtime.

The details of the syntax:

• The first argument toAnnotated must be a valid type

• Multiple type annotations are supported (Annotated supports variadicarguments):

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

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

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

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

• NestedAnnotated types are flattened, with metadata orderedstarting with the innermost annotation:

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

• Duplicated annotations are not removed:

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

• Annotated can be used with nested and generic aliases:

  T=TypeVar('T')Vec=Annotated[list[tuple[T,T]],MaxLen(10)]V=Vec[int]V==Annotated[list[tuple[int,int]],MaxLen(10)]

New in version 3.9.

Building generic types¶

These are not used in annotations. They are building blocks for 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¶

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

Constrained type variables and bound type variables have differentsemantics in several important ways. Using aconstrained type variablemeans that theTypeVar can only ever be solved as being exactly one ofthe constraints given:

a=concatenate('one','two')# Ok, variable 'a' has type 'str'b=concatenate(StringSubclass('one'),StringSubclass('two'))# Inferred type of variable 'b' 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

Using abound type variable, however, means that theTypeVar will besolved using the most specific type possible:

print_capitalized('a string')# Ok, output has type 'str'classStringSubclass(str):passprint_capitalized(StringSubclass('another string'))# Ok, output has type 'StringSubclass'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

Bound type variables are particularly useful for annotatingclassmethods that serve as alternative constructors.In the following example (©Raymond Hettinger), thetype variableC is bound to theCircle class through the use of aforward reference. Using this type variable to annotate thewith_circumference classmethod, rather than hardcoding the return typeasCircle, means that a type checker can correctly infer the returntype even if the method is called on a subclass:

importmathC=TypeVar('C',bound='Circle')classCircle:"""An abstract circle"""def__init__(self,radius:float)->None:self.radius=radius# Use a type variable to show that the return type# will always be an instance of whatever ``cls`` is@classmethoddefwith_circumference(cls:type[C],circumference:float)->C:"""Create a circle with the specified circumference"""radius=circumference/(math.pi*2)returncls(radius)classTire(Circle):"""A specialised circle (made out of rubber)"""MATERIAL='rubber'c=Circle.with_circumference(3)# Ok, variable 'c' has type 'Circle't=Tire.with_circumference(4)# Ok, variable 't' has type 'Tire' (not 'Circle')

At runtime,isinstance(x,T) will raiseTypeError. In general,isinstance() andissubclass() should not be used with types.

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

typing.AnyStr¶

AnyStr is aconstrainedtypevariable defined asAnyStr=TypeVar('AnyStr',str,bytes).

It is meant to be used for functions that may accept any kind of stringwithout allowing different kinds of strings to mix. For example:

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

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

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)

Note

runtime_checkable() will check only the presence of the required methods,not their type signatures! For example,builtins.compleximplements__float__(), therefore it passes anissubclass() checkagainstSupportsFloat. However, thecomplex.__float__ methodexists only to raise aTypeError with a more informative message.

New in version 3.8.

Other special directives¶

These are not used in annotations. They are building blocks for declaring types.

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

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.

typing.NewType(name,tp)¶

A helper function to indicate a distinct type to a typechecker,seeNewType. At runtime it returns a function that returnsits argument. Usage:

UserId=NewType('UserId',int)first_user=UserId(1)

New in version 3.5.2.

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)

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 tooverride this by specifying totality.Usage:

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.

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,notably includingGeneric. For example:

classX(TypedDict):x:intclassY(TypedDict):y:intclassZ(object):pass# A non-TypedDict classclassXY(X,Y):pass# OKclassXZ(X,Z):pass# raises TypeErrorT=TypeVar('T')classXT(X,Generic[T]):pass# raises TypeError

ATypedDict can be introspected via__annotations__,__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

__required_keys__¶

__optional_keys__¶

Point2D.__required_keys__ andPoint2D.__optional_keys__ returnfrozenset objects containing required and non-required keys, respectively.Currently the only way to declare both required and non-required keys in thesameTypedDict is mixed inheritance, declaring aTypedDict with one valuefor thetotal argument and then inheriting it from anotherTypedDict witha different value fortotal.Usage:

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

SeePEP 589 for more examples and detailed rules of usingTypedDict.

New in version 3.8.

Corresponding to built-in types¶

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

A generic version ofdict.Useful for annotating return types. To annotate arguments it is preferredto use an abstract collection type such asMapping.

This type can be used as follows:

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

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

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

Generic version oflist.Useful for annotating return types. To annotate arguments it is preferredto use an abstract collection type such asSequence orIterable.

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[]. SeePEP 585 andGeneric Alias Type.

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

A generic version ofbuiltins.set.Useful for annotating return types. To annotate arguments it is preferredto use an abstract collection type such asAbstractSet.

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

classtyping.FrozenSet(frozenset, AbstractSet[T_co])¶

A generic version ofbuiltins.frozenset.

Deprecated since version 3.9:builtins.frozenset now supports[]. SeePEP 585 andGeneric Alias Type.

Corresponding to types incollections¶

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

A generic version ofcollections.defaultdict.

New in version 3.5.2.

Deprecated since version 3.9:collections.defaultdict now supports[]. SeePEP 585 andGeneric Alias Type.

classtyping.OrderedDict(collections.OrderedDict, MutableMapping[KT, VT])¶

A generic version ofcollections.OrderedDict.

New in version 3.7.2.

Deprecated since version 3.9:collections.OrderedDict now supports[]. SeePEP 585 andGeneric Alias Type.

classtyping.ChainMap(collections.ChainMap, MutableMapping[KT, VT])¶

A generic version ofcollections.ChainMap.

New in version 3.5.4.

New in version 3.6.1.

Deprecated since version 3.9:collections.ChainMap now supports[]. SeePEP 585 andGeneric Alias Type.

classtyping.Counter(collections.Counter, Dict[T, int])¶

A generic version ofcollections.Counter.

New in version 3.5.4.

New in version 3.6.1.

Deprecated since version 3.9:collections.Counter now supports[]. SeePEP 585 andGeneric Alias Type.

classtyping.Deque(deque, MutableSequence[T])¶

A generic version ofcollections.deque.

New in version 3.5.4.

New in version 3.6.1.

Deprecated since version 3.9:collections.deque now supports[]. SeePEP 585 andGeneric Alias Type.

Other concrete types¶

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

Deprecated since version 3.8, will be removed in version 3.12:These types are also in thetyping.io namespace, which wasnever supported by type checkers and will be removed.

classtyping.Pattern¶

classtyping.Match¶

These type aliasescorrespond to the return types fromre.compile() andre.match(). These types (and the corresponding functions)are generic inAnyStr and can be made specific by writingPattern[str],Pattern[bytes],Match[str], orMatch[bytes].

Deprecated since version 3.8, will be removed in version 3.12:These types are also in thetyping.re namespace, which wasnever supported by type checkers and will be removed.

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

classtyping.Text¶

Text is an alias forstr. It 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.

Corresponding to collections incollections.abc¶

classtyping.AbstractSet(Sized, Collection[T_co])¶

A generic version ofcollections.abc.Set.

Deprecated since version 3.9:collections.abc.Set now supports[]. SeePEP 585 andGeneric Alias Type.

classtyping.ByteString(Sequence[int])¶

A generic version ofcollections.abc.ByteString.

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

As a shorthand for this type,bytes can be used toannotate arguments of any of the types mentioned above.

Deprecated since version 3.9:collections.abc.ByteString now supports[]. SeePEP 585andGeneric Alias Type.

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

A generic version ofcollections.abc.Collection

New in version 3.6.0.

Deprecated since version 3.9:collections.abc.Collection now supports[]. SeePEP 585andGeneric Alias Type.

classtyping.Container(Generic[T_co])¶

A generic version ofcollections.abc.Container.

Deprecated since version 3.9:collections.abc.Container now supports[]. SeePEP 585andGeneric Alias Type.

classtyping.ItemsView(MappingView, Generic[KT_co, VT_co])¶

A generic version ofcollections.abc.ItemsView.

Deprecated since version 3.9:collections.abc.ItemsView now supports[]. SeePEP 585andGeneric Alias Type.

classtyping.KeysView(MappingView[KT_co], AbstractSet[KT_co])¶

A generic version ofcollections.abc.KeysView.

Deprecated since version 3.9:collections.abc.KeysView now supports[]. SeePEP 585andGeneric Alias Type.

classtyping.Mapping(Sized, Collection[KT], Generic[VT_co])¶

A generic version ofcollections.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[]. SeePEP 585andGeneric Alias Type.

classtyping.MappingView(Sized, Iterable[T_co])¶

A generic version ofcollections.abc.MappingView.

Deprecated since version 3.9:collections.abc.MappingView now supports[]. SeePEP 585andGeneric Alias Type.

classtyping.MutableMapping(Mapping[KT, VT])¶

A generic version ofcollections.abc.MutableMapping.

Deprecated since version 3.9:collections.abc.MutableMapping now supports[]. SeePEP 585 andGeneric Alias Type.

classtyping.MutableSequence(Sequence[T])¶

A generic version ofcollections.abc.MutableSequence.

Deprecated since version 3.9:collections.abc.MutableSequence now supports[]. SeePEP 585 andGeneric Alias Type.

classtyping.MutableSet(AbstractSet[T])¶

A generic version ofcollections.abc.MutableSet.

Deprecated since version 3.9:collections.abc.MutableSet now supports[]. SeePEP 585andGeneric Alias Type.

classtyping.Sequence(Reversible[T_co], Collection[T_co])¶

A generic version ofcollections.abc.Sequence.

Deprecated since version 3.9:collections.abc.Sequence now supports[]. SeePEP 585andGeneric Alias Type.

classtyping.ValuesView(MappingView[VT_co])¶

A generic version ofcollections.abc.ValuesView.

Deprecated since version 3.9:collections.abc.ValuesView now supports[]. SeePEP 585andGeneric Alias Type.

Corresponding to other types incollections.abc¶

classtyping.Iterable(Generic[T_co])¶

A generic version ofcollections.abc.Iterable.

Deprecated since version 3.9:collections.abc.Iterable now supports[]. SeePEP 585andGeneric Alias Type.

classtyping.Iterator(Iterable[T_co])¶

A generic version ofcollections.abc.Iterator.

Deprecated since version 3.9:collections.abc.Iterator now supports[]. SeePEP 585andGeneric Alias Type.

classtyping.Generator(Iterator[T_co], Generic[T_co, T_contra, V_co])¶

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[]. SeePEP 585andGeneric Alias Type.

classtyping.Hashable¶

An alias tocollections.abc.Hashable.

classtyping.Reversible(Iterable[T_co])¶

A generic version ofcollections.abc.Reversible.

Deprecated since version 3.9:collections.abc.Reversible now supports[]. SeePEP 585andGeneric Alias Type.

classtyping.Sized¶

An alias tocollections.abc.Sized.

Asynchronous programming¶

classtyping.Coroutine(Awaitable[V_co], Generic[T_co, T_contra, V_co])¶

A generic version ofcollections.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[]. SeePEP 585andGeneric Alias Type.

classtyping.AsyncGenerator(AsyncIterator[T_co], Generic[T_co, T_contra])¶

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.AsyncGenerator now supports[]. SeePEP 585 andGeneric Alias Type.

classtyping.AsyncIterable(Generic[T_co])¶

A generic version ofcollections.abc.AsyncIterable.

New in version 3.5.2.

Deprecated since version 3.9:collections.abc.AsyncIterable now supports[]. SeePEP 585andGeneric Alias Type.

classtyping.AsyncIterator(AsyncIterable[T_co])¶

A generic version ofcollections.abc.AsyncIterator.

New in version 3.5.2.

Deprecated since version 3.9:collections.abc.AsyncIterator now supports[]. SeePEP 585andGeneric Alias Type.

classtyping.Awaitable(Generic[T_co])¶

A generic version ofcollections.abc.Awaitable.

New in version 3.5.2.

Deprecated since version 3.9:collections.abc.Awaitable now supports[]. SeePEP 585andGeneric Alias Type.

Context manager types¶

classtyping.ContextManager(Generic[T_co])¶

A generic version ofcontextlib.AbstractContextManager.

New in version 3.5.4.

New in version 3.6.0.

Deprecated since version 3.9:contextlib.AbstractContextManager now supports[]. SeePEP 585 andGeneric Alias Type.

classtyping.AsyncContextManager(Generic[T_co])¶

A generic version ofcontextlib.AbstractAsyncContextManager.

New in version 3.5.4.

New in version 3.6.2.

Deprecated since version 3.9:contextlib.AbstractAsyncContextManager now supports[]. SeePEP 585 andGeneric Alias Type.