# PEP 613 type aliases

PEP 613 type aliases are simple assignment statements, annotated with `typing.TypeAlias` to mark
them as a type alias. At runtime, they behave the same as implicit type aliases. Our support for
them is currently the same as for implicit type aliases, but we don't reproduce the full
implicit-type-alias test suite here, just some particularly interesting cases.

## Basic

### as `TypeAlias`

```py
from typing import TypeAlias

IntOrStr: TypeAlias = int | str

def _(x: IntOrStr):
    reveal_type(x)  # revealed: int | str
```

### as `typing.TypeAlias`

```py
import typing

IntOrStr: typing.TypeAlias = int | str

def _(x: IntOrStr):
    reveal_type(x)  # revealed: int | str
```

## Can be used as value

Because PEP 613 type aliases are just annotated assignments, they can be used as values, like a
legacy type expression (and unlike a PEP 695 type alias). We might prefer this wasn't allowed, but
people do use it.

```py
from typing import TypeAlias

MyExc: TypeAlias = Exception

try:
    raise MyExc("error")
except MyExc as e:
    reveal_type(e)  # revealed: Exception
```

## Can be (partially) stringified

```py
from typing import TypeAlias, Optional, TypeVar, Generic

class A: ...

OptionalA1: TypeAlias = Optional[A]
OptionalA2: TypeAlias = Optional["A"]
OptionalA3: TypeAlias = "Optional[A]"

def _(a: OptionalA1, b: OptionalA2, c: OptionalA3) -> None:
    reveal_type(a)  # revealed: A | None
    reveal_type(b)  # revealed: A | None
    reveal_type(c)  # revealed: A | None

T = TypeVar("T")

class MyGenericClass(Generic[T]): ...

MyGenericAlias1: TypeAlias = MyGenericClass[A]
MyGenericAlias2: TypeAlias = MyGenericClass["A"]
MyGenericAlias3: TypeAlias = "MyGenericClass[A]"

def _(a: MyGenericAlias1, b: MyGenericAlias2, c: MyGenericAlias3) -> None:
    reveal_type(a)  # revealed: MyGenericClass[A]
    reveal_type(b)  # revealed: MyGenericClass[A]
    reveal_type(c)  # revealed: MyGenericClass[A]
```

## Can inherit from an alias

```py
from typing import TypeAlias
from ty_extensions import is_subtype_of, static_assert

MyList: TypeAlias = list["int"]

class Foo(MyList): ...

static_assert(is_subtype_of(Foo, list[int]))
```

## Cannot inherit from a stringified alias

```py
from typing import TypeAlias

MyList: TypeAlias = "list[int]"

# error: [invalid-base] "Invalid class base with type `str`"
class Foo(MyList): ...
```

## Unknown type in PEP 604 union

If we run into an unknown type in a PEP 604 union in the right-hand side of a PEP 613 type alias, we
still understand it as a union type, just with an unknown element.

```py
from typing import TypeAlias
from nonexistent import unknown_type  # error: [unresolved-import]

MyAlias: TypeAlias = int | unknown_type | str

def _(x: MyAlias):
    reveal_type(x)  # revealed: int | Unknown | str
```

## Callable type in union

```py
from typing import TypeAlias, Callable

MyAlias: TypeAlias = int | Callable[[str], int]

def _(x: MyAlias):
    reveal_type(x)  # revealed: int | ((str, /) -> int)
```

## Generic aliases

A more comprehensive set of tests can be found in
[`implicit_type_aliases.md`](./implicit_type_aliases.md). If the implementations ever diverge, we
may need to duplicate more tests here.

### Basic

```py
from typing import TypeAlias, TypeVar

T = TypeVar("T")

MyList: TypeAlias = list[T]
ListOrSet: TypeAlias = list[T] | set[T]

reveal_type(MyList)  # revealed: <class 'list[T]'>
reveal_type(ListOrSet)  # revealed: <types.UnionType special-form 'list[T] | set[T]'>

def _(list_of_int: MyList[int], list_or_set_of_str: ListOrSet[str]):
    reveal_type(list_of_int)  # revealed: list[int]
    reveal_type(list_or_set_of_str)  # revealed: list[str] | set[str]
```

### Stringified generic alias

```py
from typing import TypeAlias, TypeVar

T = TypeVar("T")
U = TypeVar("U")

TotallyStringifiedPEP613: TypeAlias = "dict[T, U]"
TotallyStringifiedPartiallySpecialized: TypeAlias = "TotallyStringifiedPEP613[U, int]"

def f(x: "TotallyStringifiedPartiallySpecialized[str]"):
    reveal_type(x)  # revealed: @Todo(Generic stringified PEP-613 type alias)
```

## Subscripted generic alias in union

```py
from typing import TypeAlias, TypeVar

T = TypeVar("T")

Alias1: TypeAlias = list[T] | set[T]
MyAlias: TypeAlias = int | Alias1[str]

def _(x: MyAlias):
    reveal_type(x)  # revealed: int | list[str] | set[str]
```

## Typevar-specialized dynamic types

We still recognize type aliases as being generic if a symbol of a dynamic type is explicitly
specialized with a type variable:

```py
from typing import TypeVar, TypeAlias

from unknown_module import UnknownClass  # type: ignore

T = TypeVar("T")

MyAlias1: TypeAlias = UnknownClass[T] | None

def _(a: MyAlias1[int]):
    reveal_type(a)  # revealed: Unknown | None
```

This also works with multiple type arguments:

```py
U = TypeVar("U")
V = TypeVar("V")

MyAlias2: TypeAlias = UnknownClass[T, U, V] | int

def _(a: MyAlias2[int, str, bytes]):
    reveal_type(a)  # revealed: Unknown | int
```

If we specialize with fewer or more type arguments than expected, we emit an error:

```py
def _(
    # error: [invalid-type-arguments] "No type argument provided for required type variable `V`"
    too_few: MyAlias2[int, str],
    # error: [invalid-type-arguments] "Too many type arguments: expected 3, got 4"
    too_many: MyAlias2[int, str, bytes, float],
): ...
```

We can also reference these type aliases from other type aliases:

```py
MyAlias3: TypeAlias = MyAlias1[str] | MyAlias2[int, str, bytes]

def _(c: MyAlias3):
    reveal_type(c)  # revealed: Unknown | None | int
```

Here, we test some other cases that might involve `@Todo` types, which also need special handling:

```py
from typing_extensions import Callable, Concatenate, TypeAliasType

MyAlias4: TypeAlias = Callable[Concatenate[dict[str, T], ...], list[U]]

def _(c: MyAlias4[int, str]):
    reveal_type(c)  # revealed: (dict[str, int], /, *args: Any, **kwargs: Any) -> list[str]

T = TypeVar("T")

MyList = TypeAliasType("MyList", list[T], type_params=(T,))

MyAlias5 = Callable[[MyList[T]], int]

def _(c: MyAlias5[int]):
    # TODO: should be (list[int], /) -> int
    reveal_type(c)  # revealed: (Unknown, /) -> int

K = TypeVar("K")
V = TypeVar("V")

MyDict = TypeAliasType("MyDict", dict[K, V], type_params=(K, V))

MyAlias6 = Callable[[MyDict[K, V]], int]

def _(c: MyAlias6[str, bytes]):
    # TODO: should be (dict[str, bytes], /) -> int
    reveal_type(c)  # revealed: (Unknown, /) -> int

ListOrDict: TypeAlias = MyList[T] | dict[str, T]

def _(x: ListOrDict[int]):
    # TODO: should be list[int] | dict[str, int]
    reveal_type(x)  # revealed: Unknown | dict[str, int]

MyAlias7: TypeAlias = Callable[Concatenate[T, ...], None]

def _(c: MyAlias7[int]):
    reveal_type(c)  # revealed: (int, /, *args: Any, **kwargs: Any) -> None
```

## Imported

`alias.py`:

```py
from typing import TypeAlias

MyAlias: TypeAlias = int | str
```

`main.py`:

```py
from alias import MyAlias

def _(x: MyAlias):
    reveal_type(x)  # revealed: int | str
```

## String literal in right-hand side

```py
from typing import TypeAlias

IntOrStr: TypeAlias = "int | str"

def _(x: IntOrStr):
    reveal_type(x)  # revealed: int | str
```

## Cyclic

```py
from typing import TypeAlias, TypeVar, Union
from types import UnionType

RecursiveTuple: TypeAlias = tuple["int | RecursiveTuple", str]

def _(rec: RecursiveTuple):
    # TODO should be `tuple[int | RecursiveTuple, str]`
    reveal_type(rec)  # revealed: tuple[Divergent, str]

RecursiveHomogeneousTuple: TypeAlias = tuple["int | RecursiveHomogeneousTuple", ...]

def _(rec: RecursiveHomogeneousTuple):
    # TODO should be `tuple[int | RecursiveHomogeneousTuple, ...]`
    reveal_type(rec)  # revealed: tuple[Divergent, ...]

ClassInfo: TypeAlias = type | UnionType | tuple["ClassInfo", ...]
reveal_type(ClassInfo)  # revealed: <types.UnionType special-form 'type | UnionType | tuple[Divergent, ...]'>

def my_isinstance(obj: object, classinfo: ClassInfo) -> bool:
    # TODO should be `type | UnionType | tuple[ClassInfo, ...]`
    reveal_type(classinfo)  # revealed: type | UnionType | tuple[Divergent, ...]
    return isinstance(obj, classinfo)

K = TypeVar("K")
V = TypeVar("V")
NestedDict: TypeAlias = dict[K, Union[V, "NestedDict[K, V]"]]

def _(nested: NestedDict[str, int]):
    # TODO should be `dict[str, int | NestedDict[str, int]]`
    reveal_type(nested)  # revealed: dict[@Todo(specialized recursive generic type alias), Divergent]

my_isinstance(1, int)
my_isinstance(1, int | str)
my_isinstance(1, (int, str))
my_isinstance(1, (int, (str, float)))
my_isinstance(1, (int, (str | float)))
# error: [invalid-argument-type]
my_isinstance(1, 1)
# TODO should be an invalid-argument-type error
my_isinstance(1, (int, (str, 1)))
```

## Materialization of self-referential generic PEP 613 type aliases

```py
from typing import TypeAlias, TypeVar, Union
from ty_extensions import Bottom, Top, is_subtype_of, static_assert

K = TypeVar("K")
V = TypeVar("V")

NestedDict: TypeAlias = dict[K, Union[V, "NestedDict[K, V]"]]

static_assert(is_subtype_of(Bottom[NestedDict[str, int]], Top[NestedDict[str, int]]))
```

## Conditionally imported on Python < 3.10

```toml
[environment]
python-version = "3.9"
```

```py
try:
    # error: [unresolved-import]
    from typing import TypeAlias
except ImportError:
    from typing_extensions import TypeAlias

MyAlias: TypeAlias = int

def _(x: MyAlias):
    reveal_type(x)  # revealed: int
```

## PEP-613 aliases in stubs are deferred

Although the right-hand side of a PEP-613 alias is a value expression, inference of this value is
deferred in a stub file, allowing for forward references:

`stub.pyi`:

```pyi
from typing import TypeAlias

MyAlias: TypeAlias = A | B

class A: ...
class B: ...
```

`module.py`:

```py
import stub

def f(x: stub.MyAlias): ...

f(stub.A())
f(stub.B())

class Unrelated: ...

# error: [invalid-argument-type]
f(Unrelated())
```

## Invalid position

`typing.TypeAlias` must be used as the sole annotation in an annotated assignment. Use in any other
context is an error.

```py
from typing import TypeAlias

# error: [invalid-type-form]
def _(x: TypeAlias):
    reveal_type(x)  # revealed: Unknown

# error: [invalid-type-form]
y: list[TypeAlias] = []
```

## Right-hand side is required

```py
from typing import TypeAlias

# error: [invalid-type-form]
Empty: TypeAlias
```

## Simple syntactic validation

We don't yet do full validation for the right-hand side of a `TypeAlias` assignment, but we do
simple syntactic validation:

```toml
[environment]
python-version = "3.11"
```

```py
from typing_extensions import Annotated, Literal, TypeAlias

GoodTypeAlias: TypeAlias = Annotated[int, (1, 3.14, lambda x: x)]
GoodTypeAlias: TypeAlias = tuple[int, *tuple[str, ...]]

BadTypeAlias1: TypeAlias = eval("".join(map(chr, [105, 110, 116])))  # error: [invalid-type-form]
BadTypeAlias2: TypeAlias = [int, str]  # error: [invalid-type-form]
BadTypeAlias3: TypeAlias = ((int, str),)  # error: [invalid-type-form]
BadTypeAlias4: TypeAlias = [int for i in range(1)]  # error: [invalid-type-form]
BadTypeAlias5: TypeAlias = {"a": "b"}  # error: [invalid-type-form]
BadTypeAlias6: TypeAlias = (lambda: int)()  # error: [invalid-type-form]
BadTypeAlias7: TypeAlias = [int][0]  # error: [invalid-type-form]
BadTypeAlias8: TypeAlias = int if 1 < 3 else str  # error: [invalid-type-form]
BadTypeAlias10: TypeAlias = True  # error: [invalid-type-form]
BadTypeAlias11: TypeAlias = 1  # error: [invalid-type-form]
BadTypeAlias12: TypeAlias = list or set  # error: [invalid-type-form]
BadTypeAlias13: TypeAlias = f"{'int'}"  # error: [invalid-type-form]
BadTypeAlias14: TypeAlias = Literal[-3.14]  # error: [invalid-type-form]

# error: [invalid-type-form]
# error: [invalid-type-form]
BadTypeAlias14: TypeAlias = Literal[3.14]
```

## No type qualifiers

The right-hand side of a type alias definition is a [type expression], not an annotation expression.
Type qualifiers like `ClassVar` and `Final` are only valid in annotation expressions, so they cannot
appear in type alias definitions:

```py
from typing_extensions import ClassVar, Final, Required, NotRequired, ReadOnly, TypeAlias, Unpack
from dataclasses import InitVar

bad1: TypeAlias = ClassVar[str]  # error: [invalid-type-form]
bad2: TypeAlias = ClassVar  # error: [invalid-type-form]
bad3: TypeAlias = Final[int]  # error: [invalid-type-form]
bad4: TypeAlias = Final  # error: [invalid-type-form]
bad5: TypeAlias = Required[int]  # error: [invalid-type-form]
bad6: TypeAlias = NotRequired[int]  # error: [invalid-type-form]
bad7: TypeAlias = ReadOnly[int]  # error: [invalid-type-form]
bad9: TypeAlias = InitVar[int]  # error: [invalid-type-form]
bad10: TypeAlias = InitVar  # error: [invalid-type-form]

# TODO: this should cause us to emit an error (`Unpack` is not valid at the
# top level in this context), but for different reasons to the above cases:
# `Unpack` is not a type qualifier, and so the error message in our diagnostic
# shouldn't say that it is.
differently_bad: TypeAlias = Unpack[tuple[int, ...]]
```

## Recursive `TypeIs` and `TypeGuard` aliases don't stack overflow

```py
from typing import TypeAlias
from typing_extensions import TypeGuard, TypeIs

RecursiveIs: TypeAlias = TypeIs["RecursiveIs"]
RecursiveGuard: TypeAlias = TypeGuard["RecursiveGuard"]

AliasIs: TypeAlias = RecursiveIs
AliasGuard: TypeAlias = RecursiveGuard
```

[type expression]: https://typing.python.org/en/latest/spec/annotations.html#type-and-annotation-expressions
