annotated-types 完全指南3步为 typing.Annotated 添加类型约束告别无效数据【免费下载链接】annotated-typesReusable constraint types to use with typing.Annotated项目地址: https://gitcode.com/gh_mirrors/an/annotated-typesPython 项目里age -5这样的无效数据还能畅通无阻annotated-types是一个专为typing.AnnotatedPEP 593声明类型约束的轻量 Python 库。3 步即可给数据加上清晰的边界年龄必须大于 18、列表长度不超过 10、字符串必须是纯数字。本篇完整指南从安装到全部常用约束类型一次讲清新手也能快速上手。为什么需要类型约束普通的类型标注x: int只能告诉工具这是个整数却无法表达是多大范围的整数。想声明年龄必须大于 18以前要么自己手写运行时断言要么依赖各验证框架的私有语法。annotated-types提供的是一组现成的约束元数据类型Gt、Ge、Lt、Le、Len、Predicate 等与typing.Annotated搭配使用可被 Pydantic 等下游库统一理解。两个值得先了解的设计点极度轻量库本身不做运行时校验只负责声明约束几乎没有性能开销生态标准由 Pydantic 与 Hypothesis 维护者在 PyCon 2022 冲刺周共同设计目标是成为整个 Python 生态的通用约束语言3步快速上手第1步一键安装 annotated-types要求 Python 3.10 及以上直接用 pip 安装pip install annotated-types如果想阅读源码可以克隆仓库git clone https://gitcode.com/gh_mirrors/an/annotated-types所有核心约束类型都实现在annotated_types/__init__.py这一个文件里打开扫一遍就能对整体有个印象。第2步添加数值与长度约束导入需要的约束类写在Annotated的类型之后即可from typing import Annotated from annotated_types import Gt, Len class User: age: Annotated[int, Gt(18)] # 必须大于 18 scores: Annotated[list[int], Len(0, 10)] # 列表长度为 0~10Gt(18)表示大于 18Len(0, 10)表示长度介于 0 到 10含两端。同类的还有Ge≥、Lt、Le≤也可以用Interval一次性给出上下界。第3步用 Predicate 写自定义校验对于上下界表达不了的约束比如质数或纯数字字符串Predicate可以把任意函数包装成约束——函数返回值真值时数据才合法from annotated_types import Predicate factors: list[Annotated[int, Predicate(is_prime)]] # 每个元素都必须是质数库内还内置了IsDigit纯数字、IsFinite有限浮点数等现成的泛型别名可以直接写x: IsFinite[float]无需自己再包一层Predicate。常用约束类型速查表约束类型含义典型用法Gt(x)/Ge(x)大于 / 大于等于 xAnnotated[int, Gt(18)]Lt(x)/Le(x)小于 / 小于等于 xAnnotated[int, Le(100)]Interval一次性指定上下界可组合上面四种Interval(ge1, le10)MultipleOf(x)必须是 x 的倍数Annotated[int, MultipleOf(4)]MinLen/MaxLen/Len最小/最大长度均含端点Annotated[str, Len(2, 8)]Timezone限定允许的时区Annotated[datetime, Timezone(None)]Unit声明数值的物理单位Annotated[float, Unit(m/s)]Predicate(func)func(value) 为真即通过Predicate(is_prime)Not谓词的取反仍可被内省识别Not(math.isfinite)doc(...)为参数附加文档说明Annotated[int, doc(用户ID)] 小细节约束可以和可比类型自由搭配例如Annotated[int, Gt(1.5)]表示大于 1.5 的整数边界值不要求和被标注类型同类型。常见问题 FAQQ1annotated-types 会自动校验数据吗不会。它只携带约束描述真正的校验由 Pydantic 等下游库读取元数据后执行——这正是它几乎零性能开销的原因。如何解析约束元数据可以参考tests/test_main.py中的官方示例。Q2同一个字段能叠加多个约束吗可以。在Annotated中依次列出即可例如Annotated[int, Ge(0), Le(100)]。对库作者而言GroupedMetadata提供了把多条约束打包成一个对象的机制Interval和Len本身就是分组元数据相关测试见tests/test_grouped_metadata.py。Q3想要更多约束怎么办项目刻意保持最小化只覆盖最常见的场景。官方建议如果你有额外需求在下游库中自定义并文档化自己的约束类型即可。设计思路详见README.md项目构建配置见pyproject.toml。写在最后annotated-types把数据边界从口头约定变成了声明式标注三步走完全程✅pip install annotated-types一键安装✅ 用Gt/Ge/Lt/Le/Len添加常用数值与长度约束✅ 用Predicate表达任意自定义校验掌握这个轻量库后你的类型标注就不再是标签而会成为真正的数据契约。搭配 Pydantic 等验证框架从此对无效数据说再见【免费下载链接】annotated-typesReusable constraint types to use with typing.Annotated项目地址: https://gitcode.com/gh_mirrors/an/annotated-types创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考