摘要

本 PEP 提出了一种使用typing.Annotated类型进行类型检查元数据的机制。实现新__supports_type__协议的元数据对象将由静态类型检查器进行类型检查，以确保元数据对于给定类型有效。

动机

PEP 593 引入了Annotated作为一种将运行时元数据附加到类型的方法。通常，元数据不适用于静态类型检查器，但即使如此，能够检查元数据对于给定类型是否有意义通常也很有用。

以PEP 593中的第一个示例为例，它使用Annotated将序列化信息附加到字段

class Student(struct2.Packed):
    name: Annotated[str, struct2.ctype("<10s")]

这里，struct2.ctype("<10s")元数据旨在由序列化库用于序列化字段。此类库只能序列化一部分类型：例如，编写Annotated[list[str], struct2.ctype("<10s")]是没有意义的。然而，类型系统无法强制执行此操作。元数据被类型检查器完全忽略。

此用例出现在pydantic和msgspec等库中，这些库使用Annotated将验证和转换信息附加到字段，或者fastapi，它使用Annotated将参数标记为从标头、查询字符串或依赖项注入中提取。

规范

本 PEP 引入了一种协议，静态和运行时类型检查器可以使用该协议来验证Annotated元数据与给定类型之间的一致性。实现此协议的对象具有一个名为__supports_type__的属性，该属性指定元数据对于给定类型是否有效

class Int64:
    __supports_type__: int

该属性也可以标记为ClassVar以避免与数据类交互

from dataclasses import dataclass
from typing import ClassVar

@dataclass
class Gt:
    value: int
    __supports_type__: ClassVar[int]

当静态类型检查器遇到Annotated[T, M1, M2, ...]形式的类型表达式时，它应强制执行以下条件之一对于M1, M2, ...中的每个元数据元素：

• 元数据元素计算结果为一个没有__supports_type__属性的对象；或者
• 元数据元素计算结果为一个具有__supports_type__属性的对象M；并且T可分配给M.__supports_type__的类型。

为了支持泛型Gt元数据，可以编写

from typing import Protocol

class SupportsGt[T](Protocol):
    def __gt__(self, __other: T) -> bool:
        ...

class Gt[T]:
    __supports_type__: ClassVar[SupportsGt[T]]

    def __init__(self, value: T) -> None:
        self.value = value

x1: Annotated[int, Gt(0)] = 1  # OK
x2: Annotated[str, Gt(0)] = 0  # type checker error: str is not assignable to SupportsGt[int]
x3: Annotated[int, Gt(1)] = 0  # OK for static type checkers; runtime type checkers may flag this

向后兼容性

不实现该协议的元数据将被认为对所有类型都有效，因此不会对现有代码引入重大更改。新的检查仅适用于明确实现本 PEP 指定的协议的元数据对象。

安全影响

无。

如何教授

此协议主要用于提供Annotated元数据的库；这些库的最终用户不太可能需要自己实现该协议。应在typing.Annotated的文档和类型规范中提及该协议。

参考实现

目前还没有。

被拒绝的想法

致谢

感谢 Eric Traut 建议使用协议并从 Pyright 中实现临时支持。感谢 Jelle Zijlstra 赞助本 PEP。

版权

本文档已进入公有领域。