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 the typing module (but not custom subclasses thereof).

If type_ is not a type as defined by is_type() and raising is True, a TypeError 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 and raising is True

introspection.typing.is_generic(type_, raising=True)¶

Returns whether type_ is any kind of generic type, for example List, List[T] or even List[Tuple[T]]. This includes “special” types like Union, Tuple and Literal - anything that’s subscriptable is considered generic, except for typing.Generic itself.

If type_ is not a type as defined by is_type() and raising is True, a TypeError is raised. (Otherwise, False is returned.)

Parameters

type_ – The object to examine
raising – Whether to throw a TypeError if type_ is not a type

Returns

Whether the object is a generic type

Raises

TypeError – If type_ is not a type and raising is True

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 by is_type() and raising is True, a TypeError is raised. (Otherwise, False is returned.)

Parameters

type_ – The object to examine
raising – Whether to throw a TypeError if type_ is not a type

Returns

Whether the object is a variadic generic type

Raises

TypeError – If type_ is not a type and raising is True

introspection.typing.is_generic_base_class(type_, raising=True)¶

Returns whether type_ is a generic base class, for example List (but not List[int] or List[T]).

If type_ is not a type as defined by is_type() and raising is True, a TypeError 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 and raising is True

introspection.typing.is_qualified_generic(type_, raising=True)¶

Returns whether type_ is a generic type with some type arguments supplied, for example List[int] or List[T] (but not List).

If type_ is not a type as defined by is_type() and raising is True, a TypeError 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 and raising is True

introspection.typing.is_fully_qualified_generic(type_, raising=True)¶

Returns whether type_ is a generic type with all type arguments supplied, for example List[int] (but not List[T] or List[Tuple[T]]).

If type_ is not a type as defined by is_type() and raising is True, a TypeError 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 and raising is True

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. If type_ is a fully qualified generic class (like ByteString), 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. Calling get_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 and raising is True

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 with eval. Otherwise, they must be identifiers and will be resolved with getattr.
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 and object 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

Introspecting the typing module¶

Introspecting the `typing` module¶