Introspecting the typing module — Introspection documentation

# 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