Introspecting the typing
module¶
New in version 1.1.
The introspection.typing
submodule provides functions for the purpose
of dissecting typing
types. It is recommended to familiarize yourself
with the typing
module’s core concepts by reading PEP 0483 before
working with its internals.
-
introspection.typing.
is_type
(type_)¶ Returns whether
type_
is a valid type annotation.Examples:
>>> is_type(int) True >>> is_type(None) True >>> is_type(typing.List) True >>> is_type(typing.List[str]) True >>> is_type('Foo') # this is a forward reference True >>> is_type(3) False
- Parameters
type_ – The object to examine
- Returns
Whether the object is a class or type
-
introspection.typing.
is_typing_type
(type_, raising=True)¶ Returns whether
type_
is a type added by PEP 0484. This includes qualified generics and all types defined in thetyping
module (but not custom subclasses thereof).If
type_
is not a type as defined byis_type()
andraising
isTrue
, aTypeError
is raised. (Otherwise,False
is returned.)- Parameters
type_ – The object to examine
raising – Whether to throw a
TypeError
on invalid input
- Returns
Whether the object is a
typing
type- Raises
TypeError – If
type_
is not a type andraising
isTrue
-
introspection.typing.
is_generic
(type_, raising=True)¶ Returns whether
type_
is any kind of generic type, for exampleList
,List[T]
or evenList[Tuple[T]]
. This includes “special” types likeUnion
,Tuple
andLiteral
- anything that’s subscriptable is considered generic, except fortyping.Generic
itself.If
type_
is not a type as defined byis_type()
andraising
isTrue
, aTypeError
is raised. (Otherwise,False
is returned.)- Parameters
type_ – The object to examine
raising – Whether to throw a
TypeError
iftype_
is not a type
- Returns
Whether the object is a generic type
- Raises
TypeError – If
type_
is not a type andraising
isTrue
-
introspection.typing.
is_variadic_generic
(type_, raising=True)¶ Returns whether
type_
is a generic type that accepts an arbitrary number of type arguments. (e.g.Union
,Tuple
,Literal
, etc.)If
type_
is not a type as defined byis_type()
andraising
isTrue
, aTypeError
is raised. (Otherwise,False
is returned.)- Parameters
type_ – The object to examine
raising – Whether to throw a
TypeError
iftype_
is not a type
- Returns
Whether the object is a variadic generic type
- Raises
TypeError – If
type_
is not a type andraising
isTrue
-
introspection.typing.
is_generic_base_class
(type_, raising=True)¶ Returns whether
type_
is a generic base class, for exampleList
(but notList[int]
orList[T]
).If
type_
is not a type as defined byis_type()
andraising
isTrue
, aTypeError
is raised. (Otherwise,False
is returned.)- Parameters
type_ – The object to examine
raising – Whether to throw a
TypeError
on invalid input
- Returns
Whether the object is a generic class with no type arguments
- Raises
TypeError – If
type_
is not a type andraising
isTrue
-
introspection.typing.
is_qualified_generic
(type_, raising=True)¶ Returns whether
type_
is a generic type with some type arguments supplied, for exampleList[int]
orList[T]
(but notList
).If
type_
is not a type as defined byis_type()
andraising
isTrue
, aTypeError
is raised. (Otherwise,False
is returned.)- Parameters
type_ – The object to examine
raising – Whether to throw a
TypeError
on invalid input
- Returns
Whether the object is a generic type with type arguments
- Raises
TypeError – If
type_
is not a type andraising
isTrue
-
introspection.typing.
is_fully_qualified_generic
(type_, raising=True)¶ Returns whether
type_
is a generic type with all type arguments supplied, for exampleList[int]
(but notList[T]
orList[Tuple[T]]
).If
type_
is not a type as defined byis_type()
andraising
isTrue
, aTypeError
is raised. (Otherwise,False
is returned.)- Parameters
type_ – The object to examine
raising – Whether to throw a
TypeError
on invalid input
- Returns
Whether the object is a generic type with type arguments
- Raises
TypeError – If
type_
is not a type andraising
isTrue
-
introspection.typing.
get_generic_base_class
(type_)¶ Given a qualified generic type as input, returns the corresponding generic base class.
Example:
>>> get_generic_base_class(typing.List[int]) typing.List
- Parameters
type_ – A qualified generic type
- Returns
The input type without its type arguments
-
introspection.typing.
get_type_args
(type_)¶ Given a qualified generic type as input, returns a tuple of its type arguments.
Example:
>>> get_type_args(typing.List[int]) (<class 'int'>,) >>> get_type_args(typing.Callable[[str], None]) ([<class 'str'>], None)
- Parameters
type_ – A qualified generic type
- Returns
The input type’s type arguments
-
introspection.typing.
get_type_params
(type_)¶ Returns the TypeVars of a generic type.
If
type_
is not a generic type,TypeError
is raised. Iftype_
is a fully qualified generic class (likeByteString
), an empty tuple is returned.Examples:
>>> get_type_params(List) (~T,) >>> get_type_params(Generator) (+T_co, -T_contra, +V_co) >>> get_type_params(List[Tuple[T, int, T]]) (~T,) >>> get_type_params(ByteString) ()
In most cases, the returned TypeVars correspond directly to the type parameters the type accepts. However, some special cases exist. Firstly, there are generics which accept any number of type arguments, like
Tuple
. Callingget_type_params
on these will only return a single TypeVar:>>> get_type_params(Union) (+T_co,) >>> get_type_params(Tuple) (+T_co,)
Secondly, there are special generic types that the
typing
module internally doesn’t implement with TypeVars. Despite this,get_type_params
still supports them:>>> get_type_params(Optional) (+T_co,) >>> get_type_params(ClassVar) (+T_co,) >>> get_type_params(Callable) (-A_contra, +R_co)
- Raises
TypeError – If
type_
is not a generic type andraising
isTrue
-
introspection.typing.
get_type_name
(type_)¶ Returns the name of a type.
Examples:
>>> get_type_name(list) 'list' >>> get_type_name(typing.List) 'List'
- Parameters
type_ – The type whose name to retrieve
- Returns
The type’s name
- Raises
TypeError – If
type_
isn’t a type or is a qualified generic type
-
introspection.typing.
resolve_forward_refs
(annotation, module=None, eval_=True, strict=True)¶ Resolves forward references in a type annotation.
Examples:
>>> resolve_forward_refs(List['int']) typing.List[int] >>> resolve_forward_refs('ellipsis') <class 'ellipsis'>
- Parameters
annotation – The annotation in which forward references should be resolved
module – The module in which forward references will be evaluated
eval_ – If
True
, references may contain arbitrary code that will be evaluated witheval
. Otherwise, they must be identifiers and will be resolved withgetattr
.strict – Whether to raise an exception if a forward reference can’t be resolved
- Returns
A new annotation with no forward references
-
introspection.typing.
annotation_to_string
(annotation, implicit_typing=True)¶ Converts a type annotation to string. The result is valid python code.
Examples:
>>> annotation_to_string(int) 'int' >>> annotation_to_string(None) 'None' >>> annotation_to_string(typing.List[int]) 'List[int]'
- Parameters
annotation – A class or type annotation
implicit_typing – Whether to omit the “typing.” prefix from
typing
types’ names
- Returns
A string that, when evaluated, returns
annotation
-
introspection.typing.
to_python
(type_, strict=False)¶ Given a
typing
type as input, returns the corresponding “regular” python class.Examples:
>>> to_python(typing.List) <class 'list'> >>> to_python(typing.Iterable) <class 'collections.abc.Iterable'>
Note that
typing.Any
andobject
are two distinct types:>>> to_python(typing.Any) typing.Any >>> to_python(object) <class 'object'>
Generics qualified with
typing.Any
or other pointless constraints are converted to their regular python counterparts:>>> to_python(typing.List[typing.Any]) <class 'list'> >>> to_python(typing.Callable[..., typing.Any]) <class 'collections.abc.Callable'> >>> to_python(typing.Type[object]) <class 'type'>
The function recurses on the type arguments of qualified generics:
>>> to_python(typing.List[typing.Set], strict=False) typing.List[set]
Forward references are handled, as well:
>>> to_python(typing.List['Set'], strict=False) typing.List[set]
- Parameters
type_ – The type to convert to a python class
strict – Whether to raise an exception if the input type has no python equivalent
- Returns
The class corresponding to the input type
-
introspection.typing.
to_typing
(type_, strict=False)¶ Given a python class as input, returns the corresponding
typing
annotation.Examples:
>>> to_typing(list) typing.List >>> to_typing(typing.List[tuple]) typing.List[typing.Tuple] >>> to_typing(typing.List['tuple']) typing.List[typing.Tuple]
- Parameters
type_ – The class to convert to a typing annotation
strict – Whether to raise an exception if the input class has no
typing
equivalent
- Returns
The corresponding annotation from the
typing
module