Pydantic 类型检查测试套件解析用 Mypy、Pyright 与 Pyrefly 守护类型提示的正确性【免费下载链接】pydanticData validation using Python type hints项目地址: https://gitcode.com/GitHub_Trending/py/pydantic导读Pydantic 的核心卖点是基于 Python 类型提示做数据校验这意味着它对类型提示的依赖不仅体现在运行时还体现在静态分析层面IDE 补全、mypy、pyright等工具能否正确理解BaseModel派生类、装饰器与TypeAdapter的签名直接影响开发者体验。tests/typechecking/目录正是为守护这一承诺而存在的专项测试套件——它在 CI 中同时跑通 Mypy、Pyright 和 Pyrefly用assert_type与各类ignore注释断言类型检查器的行为。读完本文你将掌握该套件的设计动机、断言写法、配置文件含义、CI 运行命令以及每个测试文件所覆盖的 Pydantic API 类型面。测试套件的定位断言类型提示本身的正确行为Pydantic 仓库中的测试体系是分层设计的理解tests/typechecking/的定位首先要厘清它与周边目录的边界。依据 tests/typechecking/README.md该套件的目标是断言 Pydantic 代码中使用的类型提示的正确行为assert the correct behavior of the type hints we use in the Pydantic code。也就是说它验证的是类型标注与类型检查器之间的契约当用户写出TypeAdapter(int)时pyright能否推断出TypeAdapter[int]当用户漏掉必填字段时mypy能否报出call-arg错误。它不负责验证运行时校验逻辑那是tests/根目录下各测试文件的职责也不负责验证pydantic.mypy插件的行为。README 特别强调了一个容易混淆的点这些测试与 Mypy 插件无关。Pydantic 的 Mypy 插件提供pydantic.mypy这类为BaseModel合成__init__签名的插件逻辑有自己独立的测试目录 tests/mypy/其中包含plugin_success.py、plugin_fail.py、fail_defaults.py等用例及对应输出文件。两者分工如下测试目录验证对象侧重点tests/typechecking/Pydantic 自身暴露的类型提示与重载类型检查器Mypy / Pyright / Pyrefly对标准 API 的推断tests/mypy/pydantic.mypy插件插件对BaseModel派生类的自定义类型行为如合成__init__从仓库结构看tests/typechecking/下的每个文件都围绕一类 Pydantic API 展开并刻意在同一文件中混入合法用例与非法用例前者靠assert_type验证推断结果后者靠ignore注释验证报错行为——这正是类型提示正确行为的完整含义。断言机制之一用assert_type验证类型推断结果套件的核心断言手段是typing.assert_type来自typing_extensions是 PEP 646/typing 标准库在 Python 3.11 后引入的能力。它的语义是在静态检查阶段强制要求表达式类型与给定类型完全一致类型不匹配即报错而运行时它只是一个近似无操作的内联函数。以 tests/typechecking/type_adapter.py 中的经典用例为例from typing_extensions import assert_type from pydantic import TypeAdapter ta1 TypeAdapter(int) assert_type(ta1, TypeAdapter[int]) assert_type(ta1.validate_python(1), int) ta1.dump_python(1) ta1.dump_python(1) # type: ignore[arg-type] # pyright: ignore[reportArgumentType]这段代码验证了三件事TypeAdapter(int)的推断结果是TypeAdapter[int]Pydantic 为TypeAdapter的__init__提供了泛型重载ta1.validate_python(1)的返回类型是int尽管入参是字符串字面量校验结果类型由泛型参数决定dump_python接受与泛型参数匹配的类型传入1属于非法调用因此用双份ignore注释标记。同文件后半部分还覆盖了Annotated[int, ...]与int | str等进阶用例。由于Annotated元数据在TypeAdapter泛型推断上的局限部分assert_type断言本身也需要type: ignore[assert-type]与pyright: ignore[reportAssertTypeFailure]标记并注释说明这些用例需要 PEP 747TypeExpr支持。这类带 ignore 的 assert_type在套件中同样是有价值的信号——它记录了类型检查器当前的能力边界。断言机制之二用ignore注释标记非法用例对于应当报错的代码套件要求同时给出 Mypy 与 Pyright 两套错误码注释且Mypy 的type: ignore必须写在前面。README 给出的模板from pydantic import BaseModel class Model(BaseModel): a: int Model() # type: ignore[call-arg] # pyright: ignore[reportCallIssue]Model的必填字段a未被传入运行时 Pydantic 会抛ValidationError而静态层面要求 Mypy 报call-arg调用缺少参数、Pyright 报reportCallIssue。这套双注释约定的价值在于错误码本身就是断言的一部分。如果未来某次重构让错误码发生变化例如签名改成了可选参数pyproject.toml中的reportUnnecessaryTypeIgnoreComment true/warn_unused_ignores true会立即把多余的 ignore当作错误暴露出来从而防止类型检查契约在无人察觉时被破坏。在真实测试文件中常见的错误码组合还包括type: ignore[arg-type]pyright: ignore[reportArgumentType]参数类型不匹配如IntRootModel(1)type: ignore[assignment]pyright: ignore[reportAssignmentType]赋值类型不匹配如Field(default1)赋给int字段type: ignore[operator]pyright: ignore[reportOperatorIssue]运算符类型错误type: ignore[attr-defined]pyright: ignore[reportAttributeAccessIssue]访问不存在的属性type: ignore[deprecated]pyright: ignore[reportDeprecated]调用已弃用 APItype: ignore[call-overload]/[type-var]/[misc]等重载匹配失败、泛型类型变量绑定问题。类型检查配置一份pyproject.toml同时服务 Pyright 与 Mypypyproject.toml 是套件的单一配置入口它同时包含[tool.pyright]与[tool.mypy]两段配置[tool.pyright] extraPaths [../..] pythonVersion 3.10 enableExperimentalFeatures true enableTypeIgnoreComments false reportUnnecessaryTypeIgnoreComment true reportDeprecated true reportUnusedExpression false [tool.mypy] python_version 3.10 disable_error_code [empty-body] enable_error_code [deprecated] warn_unused_ignores true各配置项的含义与作用工具配置项值含义PyrightextraPaths[../..]将仓库根目录加入模块搜索路径使测试文件能直接import pydantic源码而非已安装包PyrightpythonVersion3.10按 Python 3.10 语法/类型语义分析PyrightenableExperimentalFeaturestrue开启实验性特性与泛型推断、TypeAdapter重载解析相关PyrightenableTypeIgnoreCommentsfalse关闭裸# type: ignore强制要求带错误码的显式 ignore避免掩盖真实错误PyrightreportUnnecessaryTypeIgnoreCommenttrue多余的 ignore 注释本身报错防止错误码漂移不被发现PyrightreportDeprecatedtrue对已弃用 API 的使用报错PyrightreportUnusedExpressionfalse允许无副作用的孤立表达式如仅调用dump_python不接收返回值Mypypython_version3.10与 Pyright 对齐的 Python 版本Mypydisable_error_code[empty-body]测试文件大量使用...占位函数体关闭空函数体报错Mypyenable_error_code[deprecated]与 Pyright 对齐对弃用 API 报错Mypywarn_unused_ignorestrue多余的 ignore 报错与 Pyright 的reportUnnecessaryTypeIgnoreComment语义一致值得注意的是enableTypeIgnoreComments false与warn_unused_ignores true的组合前者禁止无理由的忽略后者惩罚过期的忽略一进一出确保每个 ignore 注释都必须精确对应一个真实存在的类型错误。这正是该套件能长期有效防止类型契约退化的关键设计。在 CI 中运行三套类型检查器的一键命令虽然 README 提到 CI 中运行 Mypy 与 Pyright但当前仓库的 Makefile 实际上为三种类型检查器都提供了目标.PHONY: test-typechecking-pyright ## Typechecking integration tests (Pyright) test-typechecking-pyright: .uv uv run bash -c cd tests/typechecking pyright --version pyright -p pyproject.toml .PHONY: test-typechecking-mypy ## Typechecking integration tests (Mypy). Not to be confused with test-mypy. test-typechecking-mypy: .uv uv run bash -c cd tests/typechecking mypy --version mypy --cache-dir/dev/null --config-file pyproject.toml . .PHONY: test-typechecking-pyrefly ## Typechecking integration tests (Pyrefly). test-typechecking-pyrefly: .uv uv run bash -c cd tests/typechecking pyrefly --version pyrefly check三条命令的要点Pyrightpyright -p pyproject.toml显式指定配置Pyright 不需要缓存目录参数Mypy--cache-dir/dev/null禁用磁盘缓存保证每次从零分析--config-file pyproject.toml .显式加载配置并检查当前目录全部文件。Makefile 注释特意提醒它Not to be confused withtest-mypy——后者才是运行 tests/mypy/ 插件测试的目标Pyreflypyrefly check使用项目自身的配置发现机制无需额外参数。三个目标都依赖.uv即通过uv管理虚拟环境README 中提到的 CI 运行场景即对应这些 Makefile 目标。如果你在本地复现可以分别执行make test-typechecking-mypy、make test-typechecking-pyright、make test-typechecking-pyrefly来验证三种类型检查器对同一批文件的分析结果是否一致。各测试文件的覆盖范围一份 Pydantic API 的类型契约清单套件由一组按 API 维度拆分的测试文件组成每个文件聚焦一类类型契约。下面按主题逐一梳理以下均引用仓库内实际文件BaseModel 基础合成__init__与类级属性base_model.py 验证BaseModel最核心的类型能力——根据字段声明合成__init__签名class MyModel(BaseModel): x: str y: list[int] z: int 1 m1 MyModel(xhello, y[1, 2, 3]) m2 MyModel(xhello) # type: ignore[call-arg] # pyright: ignore[reportCallIssue] m3 MyModel(xhello, y[1, 2, b3]) # type: ignore[list-item] # pyright: ignore[reportArgumentType] m1.z not an int # type: ignore[operator] # pyright: ignore[reportOperatorIssue] m1.foobar # type: ignore[attr-defined] # pyright: ignore[reportAttributeAccessIssue]合法调用x、y均为必填类型匹配非法调用缺少必填参数报call-arg/reportCallIssue列表元素类型不符报list-item/reportArgumentType实例属性类型对int字段做字符串加法报operator/reportOperatorIssue访问不存在的foobar报attr-defined/reportAttributeAccessIssue。文件还覆盖了类级属性的类型断言assert_type(Knight.model_fields, dict[str, FieldInfo]) assert_type(Knight.model_computed_fields, dict[str, ComputedFieldInfo])model_fields与model_computed_fields分别被断言为dict[str, FieldInfo]与dict[str, ComputedFieldInfo]。注意其中对实例访问k.model_fields的两行断言带有type: ignore[deprecated]/pyright: ignore[reportDeprecated]——这印证了实例级访问model_fields在 Pydantic 中已被标记为弃用类型检查器配合配置中的reportDeprecated/deprecated错误码会对此告警。字段声明Field与PrivateAttr的参数约束fields.py 系统性地验证Field(default...)、Field(default_factory...)、PrivateAttr与字段注解的类型一致性class Model(BaseModel): f1: int Field(default1, default_factoryint) # type: ignore[call-overload] # pyright: ignore[reportCallIssue] f2: int Field(default1) # type: ignore[assignment] # pyright: ignore[reportAssignmentType] f3: int Field(default_factorystr) # type: ignore[assignment] # pyright: ignore[reportAssignmentType] f6: list[str] Field(default_factorylist) f13: int Field(...) f14: int Field(default1, validate_defaultTrue)这里蕴含了几条重要的类型契约互斥约束default与default_factory同时给出会触发重载匹配失败call-overload/reportCallIssue类型一致性默认值/工厂与注解类型不符时报assignment/reportAssignmentType工厂返回类型推断default_factorylist能正确推断为list[str]匹配注解default_factorynew_list返回list[int]的具名函数也可通过而list[str]注解配new_list返回list[int]则报arg-type/reportAssignmentType...占位Field(...)表示必填不应触发任何错误validate_default的影响当validate_defaultTrue时默认值会在运行时被校验因此类型检查器不再对Field(default1, validate_defaultTrue)报错只有validate_defaultFalse时才报assignment/reportAssignmentType。这体现了运行时是否校验与静态类型是否约束的一致设计。同文件还验证了PrivateAttr的默认值类型约束以及私有属性不会进入合成__init__class ModelWithPrivateAttr(BaseModel): _private_field: str PrivateAttr() m ModelWithPrivateAttr()装饰器validator 与 serializer 的签名契约decorators.py 是套件中信息量最大的文件之一覆盖model_validator、field_validator、model_serializer、field_serializer四种装饰器在各种mode下的合法/非法签名组合。模型校验器model_validator——以modebefore为例model_validator(modebefore) def valid_method_info(self, value: Any, info: ValidationInfo[int]) - Any: assert_type(info.context, int)ValidationInfo[int]的泛型参数被断言为info.context的类型intmodewrap则要求 handler 参数并返回Selfmodel_validator(modewrap) classmethod def valid_no_info(cls, value: Any, handler: ModelWrapValidatorHandler[Self]) - Self: rv handler(value) assert_type(rv, Self) return rv注意handler(value)的返回值类型rv被断言为Self这验证了ModelWrapValidatorHandler[_ModelType]的__call__返回类型与模型类型绑定。文件中也标注了几处TODO 当前不应合法的用例——例如modebefore的非 classmethod 方法、modewrap缺少 handler 参数等这些是 Pydantic 已知的类型检查覆盖缺口注释里说明了运行时与静态检查的不一致之处。字段校验器field_validator——区分before/after/wrap三种模式并验证json_schema_input_type参数的许可范围仅在before与wrap模式允许after模式传该参数会报call-overload/reportCallIssue。模型序列化器model_serializer——modeplain不允许多余参数modewrap要求 handler 参数model_serializer(modewrap) def valid_no_info(self, handler: SerializerFunctionWrapHandler) - Any: value handler(self) return value字段序列化器field_serializer——覆盖普通方法、staticmethod、classmethod三种形态以及partial/partialmethod的适配partial_ field_serializer(a, modeplain)(partial(lambda v, x: v, x1)) def partial_method(self, value: Any, x: Any) - Any: ... partial_method_ field_serializer(a, modeplain)(partialmethod(partial_method))同时field_serializer的info参数类型应为FieldSerializationInfo而非SerializationInfo文件注释解释了这一区分——现有的AnyFieldPlainSerializer类型别名过于宽泛导致无法拦截该误用属于记录在案的已知局限。计算属性computed_field与 property 的组合computed_field.py 验证computed_field同时支持property与cached_propertyclass Square(BaseModel): side: float computed_field # type: ignore[prop-decorator] property def area(self) - float: return self.side**2 computed_field # type: ignore[prop-decorator] cached_property def area_cached(self) - float: return self.side**2两处type: ignore[prop-decorator]是因为 Mypy 对装饰器位于 property 之前的写法存在已知限制prop-decorator错误码Pyright 侧则不需要 ignore——这是两套类型检查器行为差异的直观体现。计算属性参与普通运算12.4 sq.area是合法的而字符串拼接x sq.area则需双份operator/reportOperatorIssue注释。RootModel、Secret 与类型别名root_model.py 验证RootModel[T]的泛型直接泛型化IntRootModel RootModel[int]与继承式StrRootModel(RootModel[str])两种用法assert_type(int_root_model.root, int)断言.root属性类型为Tint_root_model IntRootModel(1) bad_root_model IntRootModel(1) # type: ignore[arg-type] # pyright: ignore[reportArgumentType] str_root_model StrRootModel(roota) assert_type(str_root_model.root, str)secret.py 验证Secret的协变/赋值兼容性Secret[str]可以传给接受Secret[str | int | float | bool]的函数参数说明Secret[T]的泛型声明允许窄类型向宽联合类型赋值。TypeAdapter、validate_call 与实验性 Pipeline APItype_adapter.py 已在第二节详述其核心是TypeAdapter(T)到TypeAdapter[T]的泛型推断以及validate_python/dump_python/dump_json的入参与返回类型Annotated[int, ...]与int | str等用例如注释所述依赖 PEP 747TypeExpr才能获得完美推断当前以assert_type加 ignore 的形式记录其现状。validate_call.py 验证validate_call装饰后的函数保留原始签名foo(1, ca)返回str非法调用foo(, c1)报arg-type/reportArgumentType同时验证带config参数的非裸装饰器用法也可正常类型检查。文件还记录了一个已知缺口foo.raw_function无法被类型检查对应 issue 提及因此需要attr-defined/reportFunctionMemberAccess注释。pipeline_api.py 覆盖实验性的pydantic.experimental.pipeline.validate_as流水线 API验证validate_as(...).transform(...).validate_as(...)链式调用的类型流转以及Annotated[Path, validate_as(NewPath)]这类 Annotated 类型作为validate_as参数的可接受性该行为对应修复过的 issue #12845。杂项model_dump的 include 过滤器类型misc.py 验证model_dump(include...)的过滤器结构类型model.model_dump(include{a: {1: True}}) model.model_dump(include{a: {__all__: True}}) model.model_dump(include{a: {1, 2}}){a: {1: False}}这类列表索引配布尔值的形态本应报错但文件注释说明由于 Mypy 的限制内部的IncEx类型别名退化为使用bool因此目前无法在静态层面拦截只能作为运行时校验处理。弃用与实验性 API 的类型标记json_schema_examples.py 与 with_config_decorator.py 分别验证Examples({})传字典是已弃用用法需deprecated/reportDeprecated注释而Examples([])合法with_config装饰器配合BaseModel的正常类型检查。这些文件共同印证了类型层面同样要跟着弃用策略走的工程实践。套件的工程价值把类型契约变成可回归的测试综合来看tests/typechecking/是一套元测试——它不测 Pydantic 的运行时行为而是测 Pydantic 暴露给类型检查器的静态接口。它的工程价值体现在三个层面契约固化TypeAdapter[int]的推断、合成__init__的必填参数、装饰器签名的合法组合都被assert_type和成对的ignore错误码固化成可回归断言任何破坏推断的重构都会在 CI 中失败双/三检查器对齐同一批文件同时被 Pyright-p pyproject.toml、Mypy--config-file pyproject.toml与 Pyreflypyrefly check检查配置项如enableTypeIgnoreComments false与warn_unused_ignores true保证了 ignore 注释的精确性也把两种工具的错误码差异如prop-decorator仅 Mypy 需要显式记录下来能力边界留痕文件中大量带解释性注释的type: ignore本身就是已知类型检查局限的活文档——例如IncEx的 bool 退化、field_serializer的 info 类型别名过宽、TypeAdapter对Annotated的推断受限于 PEP 747 等为后续类型系统改进如 PEP 747 落地提供了明确的验收清单。如果你希望深入理解某条断言背后的实现可以顺着对应 API 追踪源码例如TypeAdapter的泛型重载在 pydantic/type_adapter.py装饰器类型别名ModelWrapValidatorHandler、SerializerFunctionWrapHandler等在 pydantic/functional_validators.py 与 pydantic/functional_serializers.py字段元数据FieldInfo/ComputedFieldInfo在 pydantic/fields.py。测试文件中的每一行 ignore 注释最终都能在对应源码的类型标注中找到依据。【免费下载链接】pydanticData validation using Python type hints项目地址: https://gitcode.com/GitHub_Trending/py/pydantic创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考