Abstract

Type aliases are user-specified types which may be as complex as any type hint, and are specified with a simple variable assignment on a module top level.

This PEP formalizes a way to explicitly declare an assignment as a type alias.

Motivation

Type aliases are declared as top level variable assignments. In PEP 484, the distinction between a valid type alias and a global variable was implicitly determined: if a top level assignment is unannotated, and the assigned value is a valid type, then the name being assigned to is a valid type alias. Otherwise, that name is simply a global value that cannot be used as a type hint.

These implicit type alias declaration rules create confusion when type aliases involve forward references, invalid types, or violate other restrictions enforced on type alias declaration. Because the distinction between an unannotated value and a type alias is implicit, ambiguous or incorrect type alias declarations implicitly default to a valid value assignment. This creates expressions that are impossible to express as type aliases and punts error diagnosis of malformed type aliases downstream.

The following examples each include an illustration of some of the suboptimal or confusing behaviors resulting from existing implicit alias declarations. We also introduce explicit aliases of the format TypeName: TypeAlias = Expression here for the sake of comparison, but the syntax is discussed in further detail in later sections.

MyType = "ClassName"
def foo() -> MyType: ...

MyType: TypeAlias = "ClassName"
def foo() -> MyType: ...

MyType1 = InvalidType
MyType2 = MyGeneric(int)  # i.e., intention was MyGeneric[int]

MyType1: TypeAlias = InvalidType
MyType2: TypeAlias = MyGeneric(int)

class Foo:
  x = ClassName
  y: TypeAlias = ClassName
  z: Type[ClassName] = ClassName

x = ClassName
def foo() -> None:
  x = ClassName

x: TypeAlias = ClassName
def foo() -> None:
  x = ClassName
def bar() -> None:
  x: TypeAlias = ClassName

Specification

The explicit alias declaration syntax clearly differentiates between the three possible kinds of assignments: typed global expressions, untyped global expressions, and type aliases. This avoids the existence of assignments that break type checking when an annotation is added, and avoids classifying the nature of the assignment based on the type of the value.

Implicit syntax (pre-existing):

x = 1  # untyped global expression
x: int = 1  # typed global expression

x = int  # type alias
x: Type[int] = int  # typed global expression

Explicit syntax:

x = 1  # untyped global expression
x: int = 1  # typed global expression

x = int  # untyped global expression (see note below)
x: Type[int] = int  # typed global expression

x: TypeAlias = int  # type alias
x: TypeAlias = "MyClass"  # type alias

Note: The examples above illustrate implicit and explicit alias declarations in isolation. For the sake of backwards compatibility, type checkers should support both simultaneously, meaning an untyped global expression x = int will still be considered a valid type alias.

Backwards Compatibility

Explicit aliases provide an alternative way to declare type aliases, but all pre-existing code and old alias declarations will work as before.

Reference Implementation

The Pyre type checker supports explicit type alias declarations.

Rejected Ideas

Some alternative syntaxes were considered for explicit aliases:

MyType: TypeAlias[int]

This looks a lot like an uninitialized variable.

MyType = TypeAlias[int]

Along with the option above, this format potentially adds confusion around what the runtime value of MyType is.

In comparison, the chosen syntax option MyType: TypeAlias = int is appealing because it still sticks with the MyType = int assignment syntax, and adds some information for the type checker purely as an annotation.

Version History

• 2021-11-16
  • Allow TypeAlias inside class scope

Copyright

This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive.