本文介绍一种通过自定义 `__class_getitem__` 实现类型别名 `array[t, n]` 的技巧，使其在类型提示中等价于 `annotated[t, n]`，适用于文档化和静态类型检查场景，但需注意其运行时行为限制。
在 Python 类型系统中，直接使用 type Array = Annotated[tuple[T, ...], int] 会报错，因为 Annotated 不支持在类型别名中以泛型方式参数化（TypeError: Only generic type aliases are subscriptable）。根本原因在于：类型别名（type 语句）仅支持泛型类型构造器（如 list[T]、dict[K, V]），而 Annotated 本身不是泛型类型，其参数必须在运行时静态确定，无法延迟绑定类型变量 T 和整数字面量 N。
不过，若目标仅为提升代码可读性与类型提示的表达力（例如标注“长度为 4 的浮点数数组”），可借助类的 __class_getitem__ 魔术方法实现轻量级伪泛型别名：
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 requires exactly two arguments: Array[dtype, size]")
dtype, size = params
# 返回 Annotated[dtype, size]，供类型检查器识别
return Annotated[dtype, size]
# 使用示例
class MyIp:
ip: Array[float, 4] # 等价于 Annotated[float, 4]
ports: Array[int, 2] # 等价于 Annotated[int, 2]✅ 优势：
- 语法简洁直观，Array[float, 4] 比 Annotated[float, 4] 更具语义；
- 兼容主流类型检查器（如 mypy、pyright），能正确解析并校验类型注解；
- 无需引入第三方库，纯标准库方案。
⚠️ 关键限制（务必注意）：
- Array[float, 4] 在类定义时立即求值，MyIp.__annotations__['ip'] 实际存储的是 Annotated[float, 4]，而非 Array[float, 4]；
- typing.get_type_hints(MyIp) 默认会剥离 Annotated 元数据，返回 {'ip': float} —— 若需保留尺寸信息，须显式传入 include_extras=True：
from typing import get_type_hints hints = get_type_hints(MyIp, include_extras=True) # → {'ip': typing.Annotated[float, 4]} - 此方案不提供运行时数组长度验证（如 len(ip) == 4），纯属类型层面约定，实际数据仍需手动校验。
? 进阶建议：
若需更强的运行时保障，可结合 typing_extensions.TypedDict（固定键名）、numpy.typing.NDArray（数值计算场景）或 Pydantic v2 的 Annotated + Field(..., min_length=4) 实现结构化约束。但对于轻量级类型文档需求，Array 类方案已足够清晰、低侵入且符合 PEP 563/593 规范。
总之，这是一种务实的“类型即文档”实践——用最小代价换取最大可读性，但须始终清醒区分：类型提示 ≠ 运行时契约。
