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