本文介绍在 python 中通过自定义 `__class_getitem__` 实现类似 `Array[t, n]` 的类型别名，使其在类型注解中语法简洁、语义清晰，同时兼容 `annotated` 的元数据能力。
在 python 类型系统中，直接使用 type Array = Annotated[tuple[T, …], int] 会报错，因为 Annotated 不支持泛型参数化（即不能作为可下标类型别名），且 type 语句仅支持泛型类型别名（如 type ListOfInt = list[int]），不支持含字面量参数（如 4）或运行时值的动态构造。
一种实用且符合 PEP 563 和类型检查器（如 mypy、pyright）约定的解决方案是：定义一个轻量级类，并重写其 __class_getitem__ 方法，使其在类型注解中被调用时返回所需的 Annotated 类型。
以下是完整实现：
from typing import Annotated, TypeVar, Tuple T = TypeVar("T") class Array: def __class_getitem__(cls, params): if not isinstance(params, tuple) or len(params) != 2: raise TypeError("Array expects exactly two arguments: Array[dtype, size]") dtype, size = params # 可选：校验 size 是否为正整数（仅用于文档/开发提示，不影响运行时） if not isinstance(size, int) or size <= 0: raise ValueError("Array size must be a positive integer") return Annotated[Tuple[dtype, ...], size] # 使用示例 class MyIp: ip: Array[Float, 4] # ✅ 合法注解 ports: Array[int, 2] # ✅⚠️ 重要注意事项：
-
此方案纯属类型注解层面的“语法糖”，Array[float, 4] 在运行时立即求值为 Annotated[Tuple[float, ...], 4]，因此 MyIp.__annotations__['ip'] 将是 Annotated[...]，而非 Array[...]；
-
typing.get_type_hints(MyIp) 默认忽略 Annotated 的元数据，只返回 float（或 Tuple[float, ...]，取决于 Python 版本和 include_extras=False/True 设置），因此不可用于运行时反射解析尺寸信息；
-
若需在运行时读取尺寸（如序列化/验证），应结合 __metadata__ 属性手动提取：
from typing import get_args, get_origin def get_array_size(tp): if get_origin(tp) is Annotated: args = get_args(tp) if len(args) >= 2: return args[1] # 元数据中的 size return None print(get_array_size(MyIp.__annotations__['ip'])) # 输出: 4
✅ 总结：该模式适合强调类型意图与文档表达力的场景（如 API Schema 注释、ide 提示），但不替代运行时约束；如需强校验，建议配合 Pydantic v2 的 Annotated + Field(..., min_items=4, max_items=4) 或自定义 @dataclass_transform 工具链。