Package: typeapi
typeapiCompatibility: Python 3.6.3+Thetypeapipackage provides an object-oriented interface for introspectingPEP484type hints at runtime,
including forward references that make use of the more recentPEP585andPEP604type hint features in
Python versions that don't natively support them.The main API of this module is comprised of:typeapi.TypeHint()– A class to parse low-level type hints and present them in a consistent, object-oriented API.typeapi.get_annotations()– Retrieve an object's__annotations__with support for evaluating future type hints (PEP585,PEP604).The following kinds of type hints are currently supported:Concrete typeDescriptionAdded inClassTypeHintFor any normal or generic type as well astyping.Any. Provides access to the underlying type, the type arguments and parameters, if any.1.0.0UnionTypeHintRepresentsUniontype hint and gives access to the union members.1.0.0LiteralTypeHintRepresents aLiteraltype hint and gives access to the literal values.1.0.0AnnotatedTypeHintRepresents anAnnotatedtype hint and gives access to the annotated type as well as the metadata.1.0.0TypeVarTypeHintRepresents aTypeVartype hint and gives an interface to access the variable's metadata (such as constarints, variance, ...).1.0.0ForwardRefTypeHintRepresents a forward reference. Can be evaluated in Python 3.6+ even if it containsPEP585andPEP604expressions.1)1.0.0, future support in 1.3.0TupleTypeHintReperesents aTupletype hint, allowing you to differentiate between repeated and explicitly sized tuples.1.2.01)New-style type union evaluation will continue to return atyping.Union, even if the same syntax
evaluated natively by Python 3.10+ results in atypes.UnionType.ExamplesInspect aList[int]type hint:# cat <<EOF | python -fromtypeapiimportClassTypeHint,TypeHintfromtypingimportListhint=TypeHint(List[int])assertisinstance(hint,ClassTypeHint)asserthint.typeislistitem_hint=hint[0]assertisinstance(item_hint,ClassTypeHint)assertitem_hint.typeisintRetrieve the metadata from anAnnotated[...]type hint:# cat <<EOF | python -fromtypeapiimportAnnotatedTypeHint,ClassTypeHint,TypeHintfromtyping_extensionsimportAnnotatedhint=TypeHint(Annotated[int,42])assertisinstance(hint,AnnotatedTypeHint)asserthint.typeisintasserthint.metadata==(42,)sub_hint=hint[0]assertisinstance(sub_hint,ClassTypeHint)assertsub_hint.typeisintParameterize one type hint with the parameterization of a generic alias:# cat <<EOF | python -fromdataclassesimportdataclassfromtypeapiimportClassTypeHint,TypeHintfromtypingimportGeneric,TypeVarfromtyping_extensionsimportAnnotatedT=TypeVar("T")@dataclassclassMyGeneric(Generic[T]):value:Thint=TypeHint(MyGeneric[int])assertisinstance(hint,ClassTypeHint)asserthint.get_parameter_map()=={T:int}member_hint=TypeHint(T).parameterize(hint.get_parameter_map())assertisinstance(member_hint,ClassTypeHint)assertmember_hint.typeisintEvaluate forward references withget_annotations():# cat <<EOF | python -fromtypeapiimportget_annotationsfromtypingimportOptionalfromsysimportversion_infoclassMyType:a:"str | None"annotations=get_annotations(MyType)ifversion_info[:2]<(3,10):assertannotations=={"a":Optional[str]}else:assertannotations=={"a":str|None}Evaluating forward references with theTypeHintAPI:# cat <<EOF | python -fromtypeapiimportClassTypeHint,ForwardRefTypeHint,TypeHintMyVector="list[MyType]"classMyType:passhint=TypeHint(MyVector).evaluate(globals())print(hint)# TypeHint(typing.List[__main__.MyType])assertisinstance(hint,ClassTypeHint)asserthint.typeislistitem_hint=hint[0]assertisinstance(item_hint,ClassTypeHint)assertitem_hint.typeisMyType