结合注解的运行时和静态使用

库在运行时利用类型注解（例如：dataclasses）的趋势正在兴起；能够使用外部数据扩展类型注解将对这些库大有裨益。

以下是如何使用注解读取c结构体的假设模块的示例

UnsignedShort = Annotated[int, struct2.ctype('H')]
SignedChar = Annotated[int, struct2.ctype('b')]

class Student(struct2.Packed):
    # mypy typechecks 'name' field as 'str'
    name: Annotated[str, struct2.ctype("<10s")]
    serialnum: UnsignedShort
    school: SignedChar

# 'unpack' only uses the metadata within the type annotations
Student.unpack(record)
# Student(name=b'raymond   ', serialnum=4658, school=264)

降低开发新类型构造的障碍

通常，在添加新类型时，开发人员需要将该类型上游到typing模块并更改mypy、PyCharm、Pyre、pytype等。这在处理使用这些类型的开源代码时尤其重要，因为如果没有额外的逻辑，代码将无法立即移植到其他开发人员的工具中。因此，在代码库中开发和尝试新类型的成本很高。理想情况下，作者应该能够以一种允许优雅降级的方式引入新类型（例如：当客户端没有自定义mypy插件时），这将降低开发障碍并确保一定程度的后向兼容性。

例如，假设作者想要为Python添加对标记联合的支持。一种实现方法是使用Python中的注解TypedDict，以便只允许设置一个字段

Currency = Annotated[
    TypedDict('Currency', {'dollars': float, 'pounds': float}, total=False),
    TaggedUnion,
]

这是一种稍微繁琐的语法，但它允许我们迭代此概念证明，并让人们使用类型检查器（或其他工具）在带有标记联合的代码库中工作，而这些类型检查器（或其他工具）尚不支持此功能。作者可以轻松地测试此提案并解决问题，然后再尝试将标记联合上游到typing、mypy等。此外，不支持解析TaggedUnion注解的工具仍然能够将Currency视为TypedDict，这仍然是一个近似值（稍微不严格）。

语法

Annotated用类型和表示注解的任意Python值列表进行参数化。以下是语法的具体细节

• Annotated的第一个参数必须是有效的类型
• 支持多个类型注解（Annotated支持可变参数）

  Annotated[int, ValueRange(3, 10), ctype("char")]
  

• Annotated必须至少用两个参数调用（Annotated[int]无效）
• 注解的顺序保持不变，并且对于相等性检查很重要

  Annotated[int, ValueRange(3, 10), ctype("char")] != Annotated[
      int, ctype("char"), ValueRange(3, 10)
  ]
  

• 嵌套的Annotated类型被展平，元数据按从内到外的顺序排列

  Annotated[Annotated[int, ValueRange(3, 10)], ctype("char")] == Annotated[
      int, ValueRange(3, 10), ctype("char")
  ]
  

• 不会删除重复的注解

  Annotated[int, ValueRange(3, 10)] != Annotated[
      int, ValueRange(3, 10), ValueRange(3, 10)
  ]
  

• Annotated可用于嵌套和泛型别名

  Typevar T = ...
  Vec = Annotated[List[Tuple[T, T]], MaxLen(10)]
  V = Vec[int]
  
  V == Annotated[List[Tuple[int, int]], MaxLen(10)]
  

使用注解

最终，如何解释注解（如果需要）的责任在于遇到Annotated类型的工具或库。遇到Annotated类型的工具或库可以扫描注解以确定它们是否感兴趣（例如，使用isinstance()）。

**未知注解：**当工具或库不支持注解或遇到未知注解时，它应该忽略它并将注解类型视为底层类型。例如，当遇到不是struct2.ctype实例的名称注解时（例如，Annotated[str, 'foo', struct2.ctype("<10s")]），解包方法应忽略它。

**注解命名空间：**注解不需要命名空间，因为注解使用的类充当命名空间。

**多个注解：**使用注解的工具需要决定客户端是否允许在一个类型上有多个注解以及如何合并这些注解。

由于Annotated类型允许您在任何节点上放置相同（或不同）类型的一个或多个注解，因此使用这些注解的工具或库负责处理潜在的重复。例如，如果您正在执行值范围分析，则可能允许以下操作

T1 = Annotated[int, ValueRange(-10, 5)]
T2 = Annotated[T1, ValueRange(-20, 3)]

展平嵌套注解，这转换为

T2 = Annotated[int, ValueRange(-10, 5), ValueRange(-20, 3)]

与get_type_hints()的交互

typing.get_type_hints()将采用一个新的参数include_extras，默认为False以保持向后兼容性。当include_extras为False时，额外的注解将从返回值中剥离。否则，注解将保持不变

@struct2.packed
class Student(NamedTuple):
    name: Annotated[str, struct.ctype("<10s")]

get_type_hints(Student) == {'name': str}
get_type_hints(Student, include_extras=False) == {'name': str}
get_type_hints(Student, include_extras=True) == {
    'name': Annotated[str, struct.ctype("<10s")]
}

别名 & 关于冗长的担忧

在任何地方编写typing.Annotated可能会非常冗长；幸运的是，能够为注解设置别名意味着在实践中我们不希望客户端不得不编写大量的样板代码

T = TypeVar('T')
Const = Annotated[T, my_annotations.CONST]

class C:
    def const_method(self: Const[List[int]]) -> int:
        ...