Why not type[C]?

One might think that type[C] would suffice for these use cases. However, only class objects (instances of the builtins.type class) are assignable to type[C]. Many type form objects do not meet this requirement:

def trycast[T](typx: type[T], value: object) -> T | None: ...

trycast(str, 'hi')  # OK
trycast(Literal['hi'], 'hi')  # Type violation
trycast(str | None, 'hi')  # Type violation
trycast(MyProtocolClass, obj)  # Type violation

TypeForm use cases

A survey of Python libraries reveals several categories of functions that would benefit from TypeForm:

• Assignability checkers:
  • Determines whether a value is assignable to a specified type
  • Pattern 1: def is_assignable[T](value: object, typx: TypeForm[T]) -> TypeIs[T]
  • Pattern 2: def is_match[T](value: object, typx: TypeForm[T]) -> TypeGuard[T]
  • Examples: beartype.is_bearable, trycast.isassignable, typeguard.check_type, xdsl.isa

• Converters:
  • If a value is assignable to (or coercible to) a specified type, a converter returns the value narrowed to (or coerced to) that type. Otherwise, an exception is raised.
  • Pattern 1:

    def convert[T](value: object, typx: TypeForm[T]) -> T
    

    • Examples: cattrs.BaseConverter.structure, trycast.checkcast, typedload.load
  • Pattern 2:

    class Converter[T]:
        def __init__(self, typx: TypeForm[T]) -> None: ...
        def convert(self, value: object) -> T: ...
    

    • Examples: pydantic.TypeAdapter(T).validate_python, mashumaro.JSONDecoder(T).decode

• Typed field definitions:
  • Pattern:

    class Field[T]:
        value_type: TypeForm[T]
    

  • Examples: attrs.make_class, dataclasses.make_dataclass [3], openapify

The survey also identified some introspection functions that accept runtime type forms as input. Today, these functions are annotated with object:

• General introspection operations:
  • Pattern: def get_annotation_info(typx: object) -> object
  • Examples: typing.{get_origin, get_args}, typing_inspect.{is_*_type, get_origin, get_parameters}

These functions accept values evaluated from arbitrary annotation expressions, not just type expressions, so they cannot be altered to use TypeForm.

Implicit TypeForm Evaluation

When a static type checker encounters an expression that follows all of the syntactic, semantic and contextual rules for a type expression as detailed in the typing spec, the evaluated type of this expression should be assignable to TypeForm[T] if the type it describes is assignable to T.

For example, if a static type checker encounters the expression str | None, it may normally evaluate its type as UnionType because it produces a runtime value that is an instance of types.UnionType. However, because this expression is a valid type expression, it is also assignable to the type TypeForm[str | None]:

v1_actual: UnionType = str | None  # OK
v1_type_form: TypeForm[str | None] = str | None  # OK

v2_actual: type = list[int]  # OK
v2_type_form: TypeForm = list[int]  # OK

The Annotated special form is allowed in type expressions, so it can also appear in an expression that is assignable to TypeForm. Consistent with the typing spec’s rules for Annotated, a static type checker may choose to ignore any Annotated metadata that it does not understand:

v3: TypeForm[int | str] = Annotated[int | str, "metadata"]  # OK
v4: TypeForm[Annotated[int | str, "metadata"]] = int | str  # OK

A string literal expression containing a valid type expression should likewise be assignable to TypeForm:

v5: TypeForm[set[str]] = "set[str]"  # OK

Expressions that violate one or more of the syntactic, semantic, or contextual rules for type expressions should not evaluate to a TypeForm type. The rules for type expression validity are explained in detail within the typing spec, so they are not repeated here:

bad1: TypeForm = tuple()  # Error: Call expression not allowed in type expression
bad2: TypeForm = (1, 2)  # Error: Tuple expression not allowed in type expression
bad3: TypeForm = 1  # Non-class object not allowed in type expression
bad4: TypeForm = Self  # Error: Self not allowed outside of a class
bad5: TypeForm = Literal[var]  # Error: Variable not allowed in type expression
bad6: TypeForm = Literal[f""]  # Error: f-strings not allowed in type expression
bad7: TypeForm = ClassVar[int]  # Error: ClassVar not allowed in type expression
bad8: TypeForm = Required[int]  # Error: Required not allowed in type expression
bad9: TypeForm = Final[int]  # Error: Final not allowed in type expression
bad10: TypeForm = Unpack[Ts]  # Error: Unpack not allowed in this context
bad11: TypeForm = Optional  # Error: Invalid use of Optional special form
bad12: TypeForm = T  # Error if T is an out-of-scope TypeVar
bad13: TypeForm = "int + str"  # Error: invalid quoted type expression

Explicit TypeForm Evaluation

TypeForm also acts as a function that can be called with a single argument. Type checkers should validate that this argument is a valid type expression:

x1 = TypeForm(str | None)
reveal_type(v1)  # Revealed type is "TypeForm[str | None]"

x2 = TypeForm("list[int]")
revealed_type(v2)  # Revealed type is "TypeForm[list[int]]"

x3 = TypeForm('type(1)')  # Error: invalid type expression

At runtime the TypeForm(...) callable simply returns the value passed to it.

This explicit syntax serves two purposes. First, it documents the developer’s intent to use the value as a type form object. Second, static type checkers validate that all rules for type expressions are followed:

x4 = type(int)  # No error, evaluates to "type[int]"

x5 = TypeForm(type(int))  # Error: call not allowed in type expression

Assignability

TypeForm has a single type parameter, which is covariant. That means TypeForm[B] is assignable to TypeForm[A] if B is assignable to A:

def get_type_form() -> TypeForm[int]: ...

t1: TypeForm[int | str] = get_type_form()  # OK
t2: TypeForm[str] = get_type_form()  # Error

type[T] is a subtype of TypeForm[T], which means that type[B] is assignable to TypeForm[A] if B is assignable to A:

def get_type() -> type[int]: ...

t3: TypeForm[int | str] = get_type()  # OK
t4: TypeForm[str] = get_type()  # Error

TypeForm is a subtype of object and is assumed to have all of the attributes and methods of object.

Introspecting type form objects

Functions like typing.get_origin and typing.get_args can be used to extract components of some type form objects.

import typing

def strip_annotated_metadata(typx: TypeForm[T]) -> TypeForm[T]:
    if typing.get_origin(typx) is typing.Annotated:
        typx = cast(TypeForm[T], typing.get_args(typx)[0])
    return typx

isinstance and is can also be used to distinguish between different kinds of type form objects:

import types
import typing

def split_union(typx: TypeForm) -> tuple[TypeForm, ...]:
    if isinstance(typ, types.UnionType):  # X | Y
        return cast(tuple[TypeForm, ...], typing.get_args(typ))
    if typing.get_origin(typ) is typing.Union:  # Union[X, Y]
        return cast(tuple[TypeForm, ...], typing.get_args(typ))
    if typ in (typing.Never, typing.NoReturn,):
        return ()
    return (typ,)

Combining with a type variable

TypeForm can be parameterized by a type variable that is used elsewhere within the same function definition:

def as_instance[T](typx: TypeForm[T]) -> T | None:
    return typ() if isinstance(typ, type) else None

Combining with type

Both TypeForm and type can be parameterized by the same type variable within the same function definition:

def as_type[T](typx: TypeForm[T]) -> type[T] | None:
    return typ if isinstance(typ, type) else None

Combining with TypeIs and TypeGuard

A type variable can also be used by a TypeIs or TypeGuard return type:

def isassignable[T](value: object, typx: TypeForm[T]) -> TypeIs[T]: ...

count: int | str = ...
if isassignable(count, int):
    assert_type(count, int)
else:
    assert_type(count, str)

Challenges When Accepting All TypeForms

A function that takes an arbitrary TypeForm as input must support a variety of possible type form objects. Such functions are not easy to write.

• New special forms are introduced with each new Python version, and special handling may be required for each one.
• Quoted annotations [5] (like 'list[str]') must be parsed (to something like list[str]).
• Resolving quoted forward references inside type expressions is typically done with eval(), which is difficult to use in a safe way.
• Recursive types like IntTree = list[int | 'IntTree'] are difficult to resolve.
• User-defined generic types (like Django’s QuerySet[User]) can introduce non-standard behaviors that require runtime support.

Alternative names

Alternate names were considered for TypeForm. TypeObject and TypeType were deemed too generic. TypeExpression and TypeExpr were also considered, but these were considered confusing because these objects are not themselves “expressions” but rather the result of evaluating a type expression.

Widen type[C] to support all type expressions

type was designed to describe class objects, subclasses of the type class. A value with the type type is assumed to be instantiable through a constructor call. Widening the meaning of type to represent arbitrary type form objects would present backward compatibility problems and would eliminate a way to describe the set of values limited to subclasses of type.

Accept arbitrary annotation expressions

Certain special forms act as type qualifiers and can be used in some but not all annotation contexts:

For example. the type qualifier Final can be used as a variable type but not as a parameter type or a return type:

some_const: Final[str] = ...  # OK

def foo(not_reassignable: Final[object]): ...  # Error: Final not allowed here

def nonsense() -> Final[object]: ...  # Error: Final not alowed here

With the exception of Annotated, type qualifiers are not allowed in type expressions. TypeForm is limited to type expressions because its assignability rules are based on the assignability rules for types. It is nonsensical to ask whether Final[int] is assignable to int because the former is not a valid type expression.

Functions that wish to operate on objects that are evaluated from annotation expressions can continue to accept such inputs as object parameters.

Pattern matching on type forms

It was asserted that some functions may wish to pattern match on the interior of type expressions in their signatures.

One use case is to allow a function to explicitly enumerate all the specific kinds of type expressions it supports as input. Consider the following possible pattern matching syntax:

@overload
def checkcast(typx: TypeForm[AT=Annotated[T, *A]], value: str) -> T: ...
@overload
def checkcast(typx: TypeForm[UT=Union[*Ts]], value: str) -> Union[*Ts]: ...
@overload
def checkcast(typx: type[C], value: str) -> C: ...
# ... (more)

All functions observed in the wild that conceptually accept type form objects generally try to support all kinds of type expressions, so it doesn’t seem valuable to enumerate a particular subset.

Additionally, the above syntax isn’t precise enough to fully describe the input constraints for a typical function in the wild. For example, many functions do not support type expressions with quoted subexpressions like list['Movie'].

A second use case for pattern matching is to explicitly match an Annotated form to extract the interior type argument and strip away any metadata:

def checkcast(
    typx: TypeForm[T] | TypeForm[AT=Annotated[T, *A]],
    value: object
) -> T:

However, Annotated[T, metadata] is already treated equivalent to T by static type checkers. There’s no additional value in being explicit about this behavior. The example above could more simply be written as the equivalent:

def checkcast(typx: TypeForm[T], value: object) -> T: