如何让代码同时通过mypy与typeguard类型检查？

根因 #

mypy通过pandas-stubs识别pd.Series[float]这类泛型注解，但typeguard在运行时直接调用真实的pandas.Series类——这个类在运行时不支持下标语法（Series[float]），因此抛出TypeError: 'type' object is not subscriptable。

可行方案 #

方案1：使用字符串注解+from __future__ import annotations #

在代码文件顶部启用延迟注解解析，让注解以字符串形式保留，typeguard会在检查时正确解析泛型：

from __future__ import annotations
import pandas as pd

def col_sum(data: pd.Series[float]) -> pd.Series[float]:
    return data.sum()

• 静态检查：mypy通过pandas-stubs正常识别pd.Series[float]
• 运行时检查：typeguard解析字符串注解，不会触发下标错误；若需要验证元素类型，可在函数内手动补充检查逻辑

方案2：自定义typeguard类型检查器 #

注册一个自定义检查器，让typeguard能正确处理pd.Series[T]这种泛型：

from typeguard import register_type_guard
import pandas as pd
from typing import TypeVar, Generic

T = TypeVar('T')

# 定义泛型占位类，用于绑定静态注解与运行时检查逻辑
class TypedSeries(Generic[T]):
    pass

# 注册检查逻辑：验证是Series且元素类型匹配
@register_type_guard(TypedSeries)
def is_typed_series(value, expected_type) -> bool:
    if not isinstance(value, pd.Series):
        return False
    
    expected_dtype = expected_type.__args__[0]
    # 可扩展更多类型判断，比如int、str等
    if expected_dtype is float:
        return pd.api.types.is_float_dtype(value)
    return False

# 使用自定义泛型类做注解
def col_sum(data: TypedSeries[float]) -> TypedSeries[float]:
    return data.sum()

• 静态检查：在mypy.ini中添加配置，将TypedSeries[T]映射为pd.Series[T]：

  [mypy]
  plugins = pandas-stubs
  typevar_substitutions = TypedSeries[T]: pandas.Series[T]
  

• 运行时检查：typeguard通过自定义检查器验证pd.Series及其元素类型

方案3：拆分静态注解与运行时检查 #

保留静态的pd.Series[float]注解供mypy检查，运行时用typeguard检查基础pd.Series类型，手动验证元素类型：

from __future__ import annotations
from typeguard import typechecked
import pandas as pd

@typechecked
def col_sum(data: pd.Series[float]) -> pd.Series[float]:
    # 手动验证元素类型
    if not pd.api.types.is_float_dtype(data):
        raise TypeError("输入必须是float类型的Series")
    return data.sum()

• 依赖from __future__ import annotations避免运行时下标错误，同时兼顾静态检查的精确性

验证 #

以上方案均可同时满足：

• mypy通过pandas-stubs完成静态类型检查
• pytest + typeguard运行时检查不报错，且保证类型正确性

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