Special types¶

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

typing.Any¶

Special type indicating an unconstrained type.

• Every type is compatible withAny.

• Any is compatible with every type.

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

typing.AnyStr¶

Aconstrained type variable.

Definition:

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

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

For example:

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

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

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

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

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

typing.LiteralString¶

Special type that includes only literal strings.

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

Example:

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

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

SeePEP 675 for more details.

Added in version 3.11.

typing.Never¶

typing.NoReturn¶

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

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

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

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

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

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

Added in version 3.6.2:AddedNoReturn.

Added in version 3.11:AddedNever.

typing.Self¶

Special type to represent the current enclosed class.

For example:

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

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

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

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

Other common use cases include:

• classmethods that are used as alternative constructors and return instancesof thecls parameter.

• Annotating an__enter__() method which returns self.

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

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

SeePEP 673 for more details.

Added in version 3.11.

typing.TypeAlias¶

Special annotation for explicitly declaring atype alias.

For example:

fromtypingimportTypeAliasFactors:TypeAlias=list[int]

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

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

SeePEP 613 for more details.

Added in version 3.10.

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

Special forms¶

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

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]

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

  typeA=Union[int,str]Union[A,float]!=Union[int,str,float]

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

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

• Redundant arguments are skipped, e.g.:

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

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

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

• You cannot subclass or instantiate aUnion.

• You cannot writeUnion[X][Y].

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

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

typing.Optional¶

Optional[X] is equivalent toX|None (orUnion[X,None]).

Note that this is not the same concept as an optional argument,which is one that has a default. An optional argument with adefault does not require theOptional qualifier on its typeannotation just because it is optional. For example:

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

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

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

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

typing.Concatenate¶

Special form for annotating higher-order functions.

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

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

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

Added in version 3.10.

See also

• PEP 612 – Parameter Specification Variables (the PEP which introducedParamSpec andConcatenate)

• ParamSpec

• Annotating callable objects

typing.Literal¶

Special typing form to define “literal types”.

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

For example:

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

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

Additional details:

• The arguments must be literal values and there must be at least one.

• NestedLiteral types are flattened, e.g.:

  assertLiteral[Literal[1,2],3]==Literal[1,2,3]

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

  typeA=Literal[1,2]assertLiteral[A,3]!=Literal[1,2,3]

• Redundant arguments are skipped, e.g.:

  assertLiteral[1,2,1]==Literal[1,2]

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

  assertLiteral[1,2]==Literal[2,1]

• You cannot subclass or instantiate aLiteral.

• You cannot writeLiteral[X][Y].

Added in version 3.8.

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

typing.ClassVar¶

Special type construct to mark class variables.

As introduced inPEP 526, a variable annotation wrapped in ClassVarindicates that a given attribute is intended to be used as a class variableand should not be set on instances of that class. Usage:

classStarship:stats:ClassVar[dict[str,int]]={}# class variabledamage:int=10# instance variable

ClassVar accepts only types and cannot be further subscribed.

ClassVar is not a class itself, and should notbe used withisinstance() orissubclass().ClassVar does not change Python runtime behavior, butit can be used by third-party type checkers. For example, a type checkermight flag the following code as an error:

enterprise_d=Starship(3000)enterprise_d.stats={}# Error, setting class variable on instanceStarship.stats={}# This is OK

Added in version 3.5.3.

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

typing.Final¶

Special typing construct to indicate final names to type checkers.

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

For example:

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

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

Added in version 3.8.

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

typing.Required¶

Special typing construct to mark aTypedDict key as required.

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

Added in version 3.11.

typing.NotRequired¶

Special typing construct to mark aTypedDict key as potentiallymissing.

SeeTypedDict andPEP 655 for more details.

Added in version 3.11.

typing.ReadOnly¶

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

For example:

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

There is no runtime checking for this property.

SeeTypedDict andPEP 705 for more details.

Added in version 3.13.

typing.Annotated¶

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

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

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

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

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

Annotated[<type>,<metadata>]

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

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

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

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

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

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

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

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

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

Duplicated metadata elements are not removed:

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

Annotated can be used with nested and generic aliases:

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

Annotated cannot be used with an unpackedTypeVarTuple:

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

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

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

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

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

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

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

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

Note that usingget_origin() will returnAnnotated itself:

>>>get_origin(Password)typing.Annotated

See also

PEP 593 - Flexible function and variable annotations

The PEP introducingAnnotated to the standard library.

Added in version 3.9.

typing.TypeIs¶

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

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

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

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

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

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

1. The return value is a boolean.

2. If the return value isTrue, the type of its argumentis the intersection of the argument’s original type andNarrowedType.

3. If the return value isFalse, the type of its argumentis narrowed to excludeNarrowedType.

For example:

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

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

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

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

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

Added in version 3.13.

typing.TypeGuard¶

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

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

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

1. The return value is a boolean.

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

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

For example:

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

TypeIs andTypeGuard differ in the following ways:

• TypeIs requires the narrowed type to be a subtype of the input type, whileTypeGuard does not. The main reason is to allow for things likenarrowinglist[object] tolist[str] even though the latteris not a subtype of the former, sincelist is invariant.

• When aTypeGuard function returnsTrue, type checkers narrow the type of thevariable to exactly theTypeGuard type. When aTypeIs function returnsTrue,type checkers can infer a more precise type combining the previously known type of thevariable with theTypeIs type. (Technically, this is known as an intersection type.)

• When aTypeGuard function returnsFalse, type checkers cannot narrow the type ofthe variable at all. When aTypeIs function returnsFalse, type checkers can narrowthe type of the variable to exclude theTypeIs type.

Added in version 3.10.

typing.Unpack¶

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

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

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

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

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

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

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

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

Added in version 3.11.

Building generic types and type aliases¶

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

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

classtyping.Generic¶

Abstract base class for generic types.

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

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

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

This class can then be used as follows:

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

Here the brackets after the function name indicate ageneric function.

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

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

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

Type variable.

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

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

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

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

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

T=TypeVar('T')# Can be anythingS=TypeVar('S',bound=str)# Can be any subtype of strA=TypeVar('A',str,bytes)# Must be exactly str or bytes

Type variables exist primarily for the benefit of static typecheckers. They serve as the parameters for generic types as wellas for generic function and type alias definitions.SeeGeneric for moreinformation on generic types. Generic functions work as follows:

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

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

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

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

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

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

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

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

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

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

__name__¶

The name of the type variable.

__covariant__¶

Whether the type var has been explicitly marked as covariant.

__contravariant__¶

Whether the type var has been explicitly marked as contravariant.

__infer_variance__¶

Whether the type variable’s variance should be inferred by type checkers.

Added in version 3.12.

__bound__¶

The upper bound of the type variable, if any.

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

__constraints__¶

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

Changed in version 3.12:For type variables created throughtype parameter syntax,the constraints are evaluated only when the attribute is accessed, not whenthe type variable is created (seeLazy evaluation).

__default__¶

The default value of the type variable, ortyping.NoDefault if ithas no default.

Added in version 3.13.

has_default()¶

Return whether or not the type variable has a default value. This is equivalentto checking whether__default__ is not thetyping.NoDefaultsingleton, except that it does not force evaluation of thelazily evaluated default value.

Added in version 3.13.

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

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

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

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

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

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

Or by explicitly invoking theTypeVarTuple constructor:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

SeePEP 646 for more details on type variable tuples.

__name__¶

The name of the type variable tuple.

__default__¶

The default value of the type variable tuple, ortyping.NoDefault if ithas no default.

Added in version 3.13.

has_default()¶

Return whether or not the type variable tuple has a default value. This is equivalentto checking whether__default__ is not thetyping.NoDefaultsingleton, except that it does not force evaluation of thelazily evaluated default value.

Added in version 3.13.

Added in version 3.11.

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

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

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

Parameter specification variable. A specialized version oftype variables.

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

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

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

P=ParamSpec('P')

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

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

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

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

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.

__default__¶

The default value of the parameter specification, ortyping.NoDefault if ithas no default.

Added in version 3.13.

has_default()¶

Return whether or not the parameter specification has a default value. This is equivalentto checking whether__default__ is not thetyping.NoDefaultsingleton, except that it does not force evaluation of thelazily evaluated default value.

Added in version 3.13.

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

Added in version 3.10.

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

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

Note

Only parameter specification variables defined in global scope canbe pickled.

See also

• PEP 612 – Parameter Specification Variables (the PEP which introducedParamSpec andConcatenate)

• Concatenate

• Annotating callable objects

typing.ParamSpecArgs¶

typing.ParamSpecKwargs¶

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

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

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

Added in version 3.10.

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

The type of type aliases created through thetype statement.

Example:

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

Added in version 3.12.

__name__¶

The name of the type alias:

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

__module__¶

The module in which the type alias was defined:

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

__type_params__¶

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

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

__value__¶

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

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

Other special directives¶

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

classtyping.NamedTuple¶

Typed version ofcollections.namedtuple().

Usage:

classEmployee(NamedTuple):name:strid:int

This is equivalent to:

Employee=collections.namedtuple('Employee',['name','id'])

To give a field a default value, you can assign to it in the class body:

classEmployee(NamedTuple):name:strid:int=3employee=Employee('Guido')assertemployee.id==3

Fields with a default value must come after any fields without a default.

The resulting class has an extra attribute__annotations__ giving adict that maps the field names to the field types. (The field names are inthe_fields attribute and the default values are in the_field_defaults attribute, both of which are part of thenamedtuple()API.)

NamedTuple subclasses can also have docstrings and methods:

classEmployee(NamedTuple):"""Represents an employee."""name:strid:int=3def__repr__(self)->str:returnf'<Employee{self.name}, id={self.id}>'

NamedTuple subclasses can be generic:

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

Backward-compatible usage:

# For creating a generic NamedTuple on Python 3.11T=TypeVar("T")classGroup(NamedTuple,Generic[T]):key:Tgroup:list[T]# A functional syntax is also supportedEmployee=NamedTuple('Employee',[('name',str),('id',int)])

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

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

Changed in version 3.8:The_field_types and__annotations__ attributes arenow regular dictionaries instead of instances ofOrderedDict.

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

Changed in version 3.11:Added support for generic namedtuples.

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

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

classtyping.NewType(name,tp)¶

Helper class to create low-overheaddistinct types.

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

Usage:

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

__module__¶

The module in which the new type is defined.

__name__¶

The name of the new type.

__supertype__¶

The type that the new type is based on.

Added in version 3.5.2.

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

classtyping.Protocol(Generic)¶

Base class for protocol classes.

Protocol classes are defined like this:

classProto(Protocol):defmeth(self)->int:...

Such classes are primarily used with static type checkers that recognizestructural subtyping (static duck-typing), for example:

classC:defmeth(self)->int:return0deffunc(x:Proto)->int:returnx.meth()func(C())# Passes static type check

SeePEP 544 for more details. Protocol classes decorated withruntime_checkable() (described later) act as simple-minded runtimeprotocols that check only the presence of given attributes, ignoring theirtype signatures. Protocol classes without this decorator cannot be usedas the second argument toisinstance() orissubclass().

Protocol classes can be generic, for example:

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

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

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

Added in version 3.8.

@typing.runtime_checkable¶

Mark a protocol class as a runtime protocol.

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

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

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

Note

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

Note

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

Added in version 3.8.

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

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

classtyping.TypedDict(dict)¶

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

TypedDict declares a dictionary type that expects all of itsinstances to have a certain set of keys, where each key isassociated with a value of a consistent type. This expectationis not checked at runtime but is only enforced by type checkers.Usage:

classPoint2D(TypedDict):x:inty:intlabel:stra:Point2D={'x':1,'y':2,'label':'good'}# OKb:Point2D={'z':3,'label':'bad'}# Fails type checkassertPoint2D(x=1,y=2,label='first')==dict(x=1,y=2,label='first')

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

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

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

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

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

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

This means that aPoint2DTypedDict can have thelabelkey omitted.

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

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

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

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

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

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

classPoint3D(Point2D):z:int

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

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

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

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

ATypedDict can be generic:

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

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

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

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

__total__¶

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

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

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

__required_keys__¶

Added in version 3.9.

__optional_keys__¶

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

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

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

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

Added in version 3.9.

Note

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

Support forReadOnly is reflected in the following attributes:

__readonly_keys__¶

Afrozenset containing the names of all read-only keys. Keysare read-only if they carry theReadOnly qualifier.

Added in version 3.13.

__mutable_keys__¶

Afrozenset containing the names of all mutable keys. Keysare mutable if they do not carry theReadOnly qualifier.

Added in version 3.13.

SeePEP 589 for more examples and detailed rules of usingTypedDict.

Added in version 3.8.

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

Changed in version 3.11:Added support for genericTypedDicts.

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

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

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