如何精确控制集合长度annotated-types Len/MinLen/MaxLen 完整用法与 v0.4.0 破坏性变更解析【免费下载链接】annotated-typesReusable constraint types to use with typing.Annotated项目地址: https://gitcode.com/gh_mirrors/an/annotated-typesannotated-types 是什么给类型加上长度约束annotated-types是一个轻量级 Python 库它提供了一组可复用的约束类型配合typing.Annotated使用让你在类型注解中直接声明数据规则。对于需要控制集合长度的场景它提供了三个核心约束Len、MinLen、MaxLen能精确表达列表最少 3 个元素、字符串最长 10 个字符这类要求而无需手写验证逻辑。一句话总结用类型注解声明长度约束让 Pydantic、Hypothesis 等库自动帮你校验数据pip install annotated-types安装非常简单一条命令即可无运行时依赖开销当前版本为 0.8.0支持 Python 3.10 ~ 3.14。Len / MinLen / MaxLen 快速入门三个约束的语义非常直观约束类型含义等价判断MinLen(x)最小长度含边界len(value) xMaxLen(y)最大长度含边界len(value) yLen(a, b)长度区间上下限都含边界a len(value) b其中MinLen(x)等价于Len(min_lengthx)MaxLen(y)等价于Len(max_lengthy)。上界可以省略或设为None表示不限长度。使用示例来自 README.mdfrom typing import Annotated from annotated_types import Len, MaxLen, MinLen class Order: items: Annotated[list[int], Len(4, 6)] # 列表长度必须为 4、5 或 6 code: Annotated[str, MaxLen(10)] # 字符串最长 10 个字符 tags: Annotated[list[str], MinLen(1)] # 至少包含 1 个标签技巧Annotated[list[int], Len(8, 8)]这种上下限相同的写法就等价于长度必须恰好为 8。这三个约束适用于任何支持len()的类型——列表、元组、字典、字符串、集合都可以。Len 的隐藏机制GroupedMetadata 自动解包深入源码 annotated_types/init.py 可以发现一个精妙设计Len实际上是一个GroupedMetadata可解包的分组元数据它会在运行时自动展开为MinLen和MaxLendataclass(frozenTrue, slotsTrue) class Len(GroupedMetadata): min_length: Annotated[int, Ge(0)] 0 max_length: Annotated[int, Ge(0)] | None None def __iter__(self) - Iterator[BaseMetadata]: if self.min_length 0: yield MinLen(self.min_length) if self.max_length is not None: yield MaxLen(self.max_length)这意味着下游库如 Pydantic只需认识MinLen和MaxLen就能同时兼容Len(4, 6)的写法——一个对象两种消费方式这正是GroupedMetadata协议的价值所在协议定义见 annotated_types/init.py。v0.4.0 破坏性变更解析升级必知的 3 个改动如果你从 0.3.x 升级v0.4.0 引入了不兼容变更见 README.md 的 Changed in v0.4.0 章节请务必核对以下三点改动一参数min_inclusive重命名为min_length# ❌ 旧写法v0.3.x Len(min_inclusive3) # ✅ 新写法v0.4.0 Len(min_length3)含义完全不变但直接按关键字传参的代码会抛出TypeError。改动二max_exclusive重命名为max_length且边界语义反转 ⚠️这是最危险的变更——上界从不含变成了含# ❌ 旧写法长度必须 10最多 9 Len(max_exclusive10) # ✅ 新写法长度必须 10最多 10 Len(max_length10)如果你在旧代码中把max_exclusive10机械改成max_length10实际允许的长度会多出 1属于静默行为变化建议逐处审查。改动三取消切片当作 Len 使用的推荐早期版本曾建议用slice对象如slice(3, 7)表达长度区间但由于切片的上界是不含的与Len的含边界语义冲突官方已移除该建议。现在请统一使用Len/MinLen/MaxLen避免歧义。与其他约束组合更强大的类型表达annotated-types 不只管长度。你可以把长度约束与数值边界、谓词自由组合例如from annotated_types import Gt, Len, Predicate class Profile: age: Annotated[int, Gt(18)] # 大于 18 factors: list[Annotated[int, Predicate(is_prime)]] # 素数列表 my_list: Annotated[list[int], Len(0, 10)] # 0 到 10 个元素官方文档还提示Interval可以类似Len地用单个对象表达多个边界gt/ge/lt/le设计思路一脉相承源码示例见 annotated_types/init.py。常见误区与最佳实践清单不要把 Len 用在int上Annotated[int, Len(3)]没有意义——int没有长度官方明确提醒避免此类无效组合边界都是含的inclusiveLen(4, 6)允许 4、5、6 三个值升级时特别注意上界语义运行时不做校验annotated-types 只负责声明真正的校验由 Pydantic 等下游库完成追求性能零运行时开销测试用例可直接参考官方在 annotated_types/test_cases.py 中提供了大量约束的合法/非法取值示例tests/test_main.py 还展示了如何遍历Annotated参数提取约束并执行校验是理解元数据消费方式的绝佳范例需要文档字符串可以用doc()给注解附加说明PEP 727适合生成 API 文档时使用。总结Len(a, b)一条注解搞定长度区间且作为GroupedMetadata可自动解包为MinLenMaxLenv0.4.0 三大变更min_inclusive→min_length、max_exclusive→max_length上界变含、弃用切片写法约束只做声明、校验交给下游零性能开销地让类型注解真正说话是 Pydantic 生态中约束声明的事实标准 无论是 API 入参校验、配置解析还是测试数据生成掌握Len/MinLen/MaxLen都能让你写出更精确、更易维护的 Python 类型注解。【免费下载链接】annotated-typesReusable constraint types to use with typing.Annotated项目地址: https://gitcode.com/gh_mirrors/an/annotated-types创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
