为含pd.Series的函数签名添加泛型类型提示时触发下标不可用错误

问题原因 #

Mypy依赖pandas-stubs提供的类型信息，会要求pd.Series添加泛型参数，但运行时pandas的Series类本身并不是泛型类型，直接写pd.Series[Any]会触发TypeError——Python解释器会尝试对Series这个类执行下标操作，而它本身不支持该操作。

解决办法 #

方法1：启用字符串类型标注（推荐）

在文件顶部添加from __future__ import annotations，Python 3.7+会将类型标注视为字符串，运行时不会解析泛型下标，同时完全不影响Mypy的静态检查：

from __future__ import annotations
from typing import Any
import pandas as pd

def foo(x: pd.Series[Any]) -> None:
    pass

方法2：直接用字符串包裹标注

如果不想导入__future__模块，可直接将标注用双引号包裹，同样能让运行时跳过解析逻辑：

from typing import Any
import pandas as pd

def foo(x: "pd.Series[Any]") -> None:
    pass

方法3：导入pandas内部泛型类型

从pandas._typing模块导入专门的泛型Series类型（注意：这是内部模块，后续pandas版本更新可能存在兼容性风险）：

from typing import Any
from pandas._typing import Series

def foo(x: Series[Any]) -> None:
    pass

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