符号约定

• t1, t2 等以及 u1, u2 等是类型。有时我们写 ti 或 tj 来指代“t1, t2 等中的任何一个”。
• T, U 等是类型变量（使用 TypeVar() 定义，见下文）。
• 对象、使用 class 语句定义的类和实例使用标准 PEP 8 约定表示。
• 在本 PEP 的上下文中，应用于类型的符号 == 意味着两个表达式表示相同的类型。
• 请注意，PEP 484 对类型和类进行了区分（类型是类型检查器的概念，而类是运行时概念）。在本 PEP 中，我们澄清了这种区别，但避免不必要的严格性，以允许类型检查器实现更大的灵活性。

子类型关系

对于静态类型检查器来说，一个关键概念是子类型关系。它源于这个问题：如果 first_var 的类型是 first_type，并且 second_var 的类型是 second_type，那么赋值 first_var = second_var 是否安全？

一个关于何时*应该*安全的强标准是

• second_type 中的每个值也都属于 first_type 的值集合；并且
• first_type 中的每个函数也都属于 second_type 的函数集合。

由此定义的关系称为子类型关系。

根据此定义

• 每个类型都是其自身的子类型。
• 在子类型化过程中，值集合变小，而函数集合变大。

一个直观的例子：每只 Dog 都是一个 Animal，同时 Dog 拥有更多函数，例如它可以吠叫，因此 Dog 是 Animal 的子类型。反之，Animal 不是 Dog 的子类型。

一个更正式的例子：整数是实数的子类型。事实上，每个整数当然也是一个实数，并且整数支持更多的操作，例如位移 << 和 >>。

lucky_number = 3.14    # type: float
lucky_number = 42      # Safe
lucky_number * 2       # This works
lucky_number << 5      # Fails

unlucky_number = 13    # type: int
unlucky_number << 5    # This works
unlucky_number = 2.72  # Unsafe

我们再考虑一个棘手的例子：如果 List[int] 表示由所有只包含整数的列表构成的类型，那么它*不是* List[float] 的子类型，后者由所有只包含实数的列表构成。子类型化的第一个条件成立，但附加实数只适用于 List[float]，因此第二个条件失败。

def append_pi(lst: List[float]) -> None:
    lst += [3.14]

my_list = [1, 3, 5]  # type: List[int]

append_pi(my_list)   # Naively, this should be safe...

my_list[-1] << 5     # ... but this fails

有两种广泛使用的方法向类型检查器*声明*子类型信息。

在名义子类型化中，类型树基于类树，即 UserID 被认为是 int 的子类型。这种方法应在类型检查器的控制下使用，因为在 Python 中可以以不兼容的方式覆盖属性

class Base:
    answer = '42' # type: str

class Derived(Base):
    answer = 5 # should be marked as error by type checker

在结构子类型化中，子类型关系是从声明的方法推导出来的，即 UserID 和 int 将被视为相同的类型。虽然这偶尔会引起混淆，但结构子类型化被认为更灵活。我们力求同时支持这两种方法，以便除了名义子类型化之外，还可以使用结构信息。

类型与类

在 Python 中，类是由 class 语句定义的对象工厂，并由内置函数 type(obj) 返回。类是一个动态的运行时概念。

类型概念如上所述，类型出现在变量和函数的类型注解中，可以由下面描述的构建块构成，并由静态类型检查器使用。

正如上面讨论的，每个类都是一个类型。但实现一个精确表示给定类型语义的类是棘手且容易出错的，这不是 PEP 484 的目标。PEP 484 中描述的静态类型不应与运行时类混淆。 示例

• int 是一个类，也是一个类型。
• UserID 是一个类，也是一个类型。
• Union[str, int] 是一种类型，但不是一个 proper 类

  class MyUnion(Union[str, int]): ...  # raises TypeError
  
  Union[str, int]()  # raises TypeError
  

类型接口是用类实现的，即在运行时可以评估，例如 Generic[T].__bases__。但为了强调类和类型之间的区别，以下通用规则适用

• 下面定义的任何类型（即 Any, Union 等）都不能被实例化，尝试这样做会引发 TypeError。（但 Generic 的非抽象子类可以。）
• 下面定义的任何类型都不能被子类化，除了 Generic 及其派生类。
• 所有这些在 isinstance 或 issubclass 中出现时都会引发 TypeError（未参数化的泛型除外）。

基本构成要素

• Any。所有类型都与 Any 一致；它也与所有类型一致（见上文）。
• Union[t1, t2, …]。是 t1 等中至少一个子类型的类型，都是它的子类型。
  • 其所有组件都是 t1 等子类型的 Union，是此类型的子类型。例如：Union[int, str] 是 Union[int, float, str] 的子类型。
  • 参数的顺序无关紧要。例如：Union[int, str] == Union[str, int]。
  • 如果 ti 本身是一个 Union，则结果会被展平。例如：Union[int, Union[float, str]] == Union[int, float, str]。
  • 如果 ti 和 tj 具有子类型关系，则不那么特定的类型会保留。例如：Union[Employee, Manager] == Union[Employee]。
  • Union[t1] 只返回 t1。Union[] 是非法的，Union[()] 也是。
  • 推论：Union[..., object, ...] 返回 object。
• Optional[t1]。是 Union[t1, None] 的别名，即 Union[t1, type(None)]。
• Tuple[t1, t2, …, tn]。一个元组，其项目是 t1 等的实例。例如：Tuple[int, float] 表示一个包含两个项目的元组，第一个是 int，第二个是 float；例如 (42, 3.14)。
  • 如果 Tuple[u1, u2, ..., um] 与 Tuple[t1, t2, ..., tn] 长度相同 n==m，并且每个 ui 都是 ti 的子类型，则它是其子类型。
  • 要表示空元组的类型，请使用 Tuple[()]。
  • 一个可变长同质元组类型可以写成 Tuple[t1, ...]。（那是三个点，一个字面省略号；是的，那在 Python 语法中是一个有效的标记。）
• Callable[[t1, t2, …, tn], tr]。一个函数，其位置参数类型为 t1 等，返回类型为 tr。参数列表可以为空 n==0。无法指示可选参数或关键字参数，也无法指示可变参数，但可以通过写入 Callable[..., tr]（同样是字面省略号）来表示参数列表完全不进行检查。

我们可以添加

• Intersection[t1, t2, …]。是 t1 等中*每个*类型的子类型的类型，都是它的子类型。（与 Union 进行比较，Union 的定义中是*至少一个*而不是*每个*。）
  • 参数的顺序无关紧要。嵌套的交集被展平，例如 Intersection[int, Intersection[float, str]] == Intersection[int, float, str]。
  • 更少类型的交集是更多类型的交集的超类型，例如 Intersection[int, str] 是 Intersection[int, float, str] 的超类型。
  • 一个参数的交集就是那个参数，例如 Intersection[int] 就是 int。
  • 当参数具有子类型关系时，更具体的类型会保留，例如 Intersection[str, Employee, Manager] 是 Intersection[str, Manager]。
  • Intersection[] 是非法的，Intersection[()] 也是。
  • 推论：Any 从参数列表中消失，例如 Intersection[int, str, Any] == Intersection[int, str]。Intersection[Any, object] 是 object。
  • Intersection 和 Union 之间的交互很复杂，但如果您了解常规集合的交集和并集之间的交互（请注意，类型集合的大小可以是无限的，因为新子类的数量没有限制），则不会感到意外。

类型变量

X = TypeVar('X') 声明了一个唯一的类型变量。名称必须与变量名匹配。默认情况下，类型变量涵盖所有可能的类型。示例

def do_nothing(one_arg: T, other_arg: T) -> None:
    pass

do_nothing(1, 2)               # OK, T is int
do_nothing('abc', UserID(42))  # also OK, T is object

Y = TypeVar('Y', t1, t2, ...)。同上，但受限于 t1 等。行为类似于 Union[t1, t2, ...]。受限类型变量只在限制 t1 等的范围内*精确*地取值；限制的子类会被 t1 等中最派生的基类替换。示例

• 带有受限类型变量的函数类型注解

  AnyStr = TypeVar('AnyStr', str, bytes)
  
  def longest(first: AnyStr, second: AnyStr) -> AnyStr:
      return first if len(first) >= len(second) else second
  
  result = longest('a', 'abc')  # The inferred type for result is str
  
  result = longest('a', b'abc')  # Fails static type check
  

  在这个例子中，longest() 的两个参数必须具有相同的类型（str 或 bytes），而且，即使参数是共同 str 子类的实例，返回类型仍然是 str，而不是那个子类（参见下一个例子）。

• 作为对比，如果类型变量不受限制，则会将共同子类选为返回类型，例如

  S = TypeVar('S')
  
  def longest(first: S, second: S) -> S:
      return first if len(first) >= len(second) else second
  
  class MyStr(str): ...
  
  result = longest(MyStr('a'), MyStr('abc'))
  

  result 的推断类型是 MyStr（而在 AnyStr 示例中，它将是 str）。

• 另外作为对比，如果使用了 Union，则返回类型也必须是 Union

  U = Union[str, bytes]
  
  def longest(first: U, second: U) -> U:
      return first if len(first) >= len(second) else second
  
  result = longest('a', 'abc')
  

  即使两个参数都是 str，result 的推断类型仍然是 Union[str, bytes]。

  注意，类型检查器将拒绝此函数

  def concat(first: U, second: U) -> U:
      return first + second  # Error: can't concatenate str and bytes
  

  对于参数只能同时改变类型的情况，应使用受限类型变量。

定义和使用泛型类型

用户可以使用特殊构建块 Generic 将其类声明为泛型类型。定义 class MyGeneric(Generic[X, Y, ...]): ... 定义了一个泛型类型 MyGeneric，其类型变量为 X 等。MyGeneric 本身变得可参数化，例如 MyGeneric[int, str, ...] 是一个特定类型，其替换为 X -> int 等。示例

class CustomQueue(Generic[T]):

    def put(self, task: T) -> None:
        ...
    def get(self) -> T:
        ...

def communicate(queue: CustomQueue[str]) -> Optional[str]:
    ...

从泛型类型派生的类也成为泛型类。一个类可以子类化多个泛型类型。然而，从泛型返回的特定类型派生的类不是泛型类。示例

class TodoList(Iterable[T], Container[T]):
    def check(self, item: T) -> None:
        ...

def check_all(todo: TodoList[T]) -> None:  # TodoList is generic
    ...

class URLList(Iterable[bytes]):
    def scrape_all(self) -> None:
        ...

def search(urls: URLList) -> Optional[bytes]  # URLList is not generic
    ...

子类化泛型类型会在相应的特定类型上施加子类型关系，因此在上面的示例中 TodoList[t1] 是 Iterable[t1] 的子类型。

泛型类型可以分几步进行专业化（索引）。每个类型变量都可以被一个特定类型或另一个泛型类型替换。如果 Generic 出现在基类列表中，那么它应该包含所有类型变量，并且类型参数的顺序由它们在 Generic 中出现的顺序决定。示例

Table = Dict[int, T]     # Table is generic
Messages = Table[bytes]  # Same as Dict[int, bytes]

class BaseGeneric(Generic[T, S]):
    ...

class DerivedGeneric(BaseGeneric[int, T]): # DerivedGeneric has one parameter
    ...

SpecificType = DerivedGeneric[int]         # OK

class MyDictView(Generic[S, T, U], Iterable[Tuple[U, T]]):
    ...

Example = MyDictView[list, int, str]       # S -> list, T -> int, U -> str

如果在类型注解中省略了类型变量，则泛型类型假定为 Any。这种形式可以作为动态类型化的备用，并允许与 issubclass 和 isinstance 一起使用。实例中的所有类型信息在运行时都会被擦除。示例

def count(seq: Sequence) -> int:      # Same as Sequence[Any]
    ...

class FrameworkBase(Generic[S, T]):
    ...

class UserClass:
    ...

issubclass(UserClass, FrameworkBase)  # This is OK

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

IntNode = Node[int]
my_node = IntNode()  # at runtime my_node.__class__ is Node
                     # inferred static type of my_node is Node[int]

协变与逆变

如果 t2 是 t1 的子类型，则调用泛型类型构造函数 GenType

• 协变（Covariant），如果对于所有这样的 t1 和 t2，GenType[t2] 是 GenType[t1] 的子类型。
• 逆变（Contravariant），如果对于所有这样的 t1 和 t2，GenType[t1] 是 GenType[t2] 的子类型。
• 不变（Invariant），如果以上都不是真的。

为了更好地理解这个定义，让我们类比普通函数。假设我们有

def cov(x: float) -> float:
    return 2*x

def contra(x: float) -> float:
    return -x

def inv(x: float) -> float:
    return x*x

如果 x1 < x2，那么总是 cov(x1) < cov(x2)，并且 contra(x2) < contra(x1)，而对 inv 则无法说明。将 < 替换为 is-subtype-of，将函数替换为泛型类型构造函数，我们就得到了协变、逆变和不变行为的例子。现在我们考虑实际例子

• Union 在其所有参数中都表现出协变。确实，如上所述，如果 t1 是 u1 的子类型等，那么 Union[t1, t2, ...] 是 Union[u1, u2, ...] 的子类型。
• FrozenSet[T] 也是协变的。让我们用 int 和 float 来代替 T。首先，int 是 float 的子类型。其次，FrozenSet[int] 的值集合显然是 FrozenSet[float] 的值集合的子集，而 FrozenSet[float] 的函数集合是 FrozenSet[int] 的函数集合的子集。因此，根据定义，FrozenSet[int] 是 FrozenSet[float] 的子类型。
• List[T] 是不变的。确实，尽管 List[int] 的值集合是 List[float] 的值集合的子集，但正如“背景”一节中所讨论的，只有 int 可以添加到 List[int] 中。因此，List[int] 不是 List[float] 的子类型。这是可变类型中的典型情况，它们通常是不变的。

说明（有点反直觉的）逆变行为的最佳例子之一是可调用类型。它在返回类型上是协变的，但在参数上是逆变的。对于仅在返回类型上不同的两个可调用类型，可调用类型的子类型关系遵循返回类型的子类型关系。示例

• Callable[[], int] 是 Callable[[], float] 的子类型。
• Callable[[], Manager] 是 Callable[[], Employee] 的子类型。

而对于两个仅在一个参数类型上不同的可调用类型，可调用类型的子类型关系与参数类型*方向相反*。例如

• Callable[[float], None] 是 Callable[[int], None] 的子类型。
• Callable[[Employee], None] 是 Callable[[Manager], None] 的子类型。

是的，你没看错。事实上，如果期望一个可以计算经理薪水的函数

def calculate_all(lst: List[Manager], salary: Callable[[Manager], Decimal]):
    ...

那么 Callable[[Employee], Decimal]，它可以计算任何员工的薪水，也是可以接受的。

Callable 的例子展示了如何为函数创建更精确的类型注解：为每个参数选择最通用的类型，为返回值选择最具体的类型。

可以使用在作为参数的类型变量定义中，使用特殊关键字 covariant 和 contravariant 来*声明*用户定义泛型类型的变体。类型默认为不变。示例

T = TypeVar('T')
T_co = TypeVar('T_co', covariant=True)
T_contra = TypeVar('T_contra', contravariant=True)

class LinkedList(Generic[T]):  # invariant by default
    ...
    def append(self, element: T) -> None:
        ...

class Box(Generic[T_co]):      #  this type is declared covariant
    def __init__(self, content: T_co) -> None:
        self._content = content
    def get_content(self) -> T_co:
        return self._content

class Sink(Generic[T_contra]): # this type is declared contravariant
    def send_to_nowhere(self, data: T_contra) -> None:
        with open(os.devnull, 'w') as devnull:
            print(data, file=devnull)

注意，尽管变体是通过类型变量定义的，但它不是类型变量的属性，而是泛型类型的属性。在派生泛型的复杂定义中，变体*仅*由使用的类型变量确定。一个复杂的例子

T_co = TypeVar('T_co', Employee, Manager, covariant=True)
T_contra = TypeVar('T_contra', Employee, Manager, contravariant=True)

class Base(Generic[T_contra]):
    ...

class Derived(Base[T_co]):
    ...

类型检查器从第二个声明中发现 Derived[Manager] 是 Derived[Employee] 的子类型，并且 Derived[t1] 是 Base[t1] 的子类型。如果我们将 is-subtype-of 关系表示为 <，那么此情况的子类型化完整图表将是

Base[Manager]    >  Base[Employee]
    v                   v
Derived[Manager] <  Derived[Employee]

因此，类型检查器还会发现，例如，Derived[Manager] 是 Base[Employee] 的子类型。

有关类型变量、泛型类型和变体的更多信息，请参阅 PEP 484、mypy 泛型文档 和 维基百科。

typing.py 中预定义的泛型类型和协议

（另请参阅 typing.py 模块。）

• collections.abc 中的所有内容（但 Set 重命名为 AbstractSet）。
• Dict, List, Set, FrozenSet，还有一些。
• re.Pattern[AnyStr], re.Match[AnyStr]。
• io.IO[AnyStr], io.TextIO ~ io.IO[str], io.BinaryIO ~ io.IO[bytes]。