如何针对第三方包版本敏感代码运行mypy类型检查

核心问题 #

编写兼容pydantic v1/v2这类多版本依赖的代码时，版本分支逻辑会被mypy全量静态检查，导致CI中针对不同版本运行mypy时，触发另一版本分支的类型错误（比如v1环境下检查到v2特有的API不存在）。

实用解决方案 #

方案1：mypy自定义常量+TYPE_CHECKING隔离分支 #

这是最通用的可靠方案，让mypy在不同版本检查时只处理对应分支：

1. 代码实现：分离运行时和类型检查时的版本判断逻辑，利用typing.TYPE_CHECKING（仅类型检查时为True）和环境变量：

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    import os
    # 读取mypy启动时传入的自定义常量
    PYDANTIC_V2 = os.getenv("MYPY_PYDANTIC_V2") == "1"
else:
    import packaging.version
    import pydantic
    # 运行时实际判断安装的pydantic版本
    PYDANTIC_V2 = packaging.version.parse(pydantic.__version__).major == 2

# 版本专属逻辑
if PYDANTIC_V2:
    # pydantic v2 代码
    from pydantic import field_validator
else:
    # pydantic v1 代码
    from pydantic import validator

2. CI配置：针对不同版本的pydantic，启动mypy时传入对应常量：

• 检查v2：mypy --define MYPY_PYDANTIC_V2=1 your_package/
• 检查v1：mypy your_package/（不定义该变量即可）

mypy会根据常量值静态忽略不符合条件的分支，避免跨版本类型报错。

方案2：拆分版本实现到独立模块 #

适合版本差异大、代码量多的场景，逻辑更清晰：

1. 创建版本专属模块：

   • your_package/v1_impl.py：存放pydantic v1的所有实现
   • your_package/v2_impl.py：存放pydantic v2的所有实现

2. 主模块动态导入：

import packaging.version
import pydantic

PYDANTIC_VERSION = packaging.version.parse(pydantic.__version__)

if PYDANTIC_VERSION.major == 1:
    from .v1_impl import *  # type: ignore[import]
else:
    from .v2_impl import *  # type: ignore[import]

3. CI配置：检查对应版本时，用--exclude忽略另一版本的模块：

• 检查v1：mypy --exclude v2_impl.py your_package/
• 检查v2：mypy --exclude v1_impl.py your_package/

方案3：利用pydantic官方兼容层（专属方案） #

pydantic v2内置了pydantic.v1兼容模块，可直接兼容v1 API，减少分支逻辑：

# 优先导入v2兼容层，失败则用v1原生API
try:
    from pydantic.v1 import BaseModel, validator, Field
except ImportError:
    from pydantic import BaseModel, validator, Field

这种写法下，mypy会自动识别对应版本的有效分支，无需额外配置即可通过检查。

兜底方案：精准添加type: ignore #

如果上述方案无法覆盖，可针对明确的跨版本类型错误添加精准注释，避免全局忽略：

if PYDANTIC_VERSION.major == 1:
    validator_func = validator("field_name")  # type: ignore[attr-defined]
else:
    validator_func = field_validator("field_name")

仅针对mypy在对应版本下会触发的错误添加注释，保留其他类型检查能力。

内容的提问来源于stack exchange，提问作者ddluke