Pyright为何在此处抛出类型不兼容错误？

示例代码 #

from pandas import DataFrame, Series

# This function prunes the dataframe rows to those meeting specified criteria
def prune_to_wanted_rows(st_df: DataFrame, recency_date: str) -> DataFrame:
    st_df = st_df[ # pyright error message (see below) here
        (st_df["assetType"] == "ore")
        & (st_df["priceCurrency"] == "USD")
        & (st_df["endDate"] >= recency_date)
        # other boolean expressions omitted for brevity
    ]
    return st_df

对应的Pyright错误信息 #

Expression of type "Series | Unknown | DataFrame" is incompatible with declared type "DataFrame"------Type "Series | Unknown | DataFrame" is incompatible with type "DataFrame"------Type "Series" is incompatible with "DataFrame"

报错合理性分析 #

这个报错是合理的，核心原因在于Pyright是静态类型检查工具，无法像运行代码那样直接确认索引操作的返回类型：

• Pandas中用布尔索引df[mask]筛选行时，实际运行会返回DataFrame，但Pyright只能基于语法和类型注解做静态推断。如果它无法100%确定布尔表达式返回的是标准布尔Series，就会采取保守策略，将df[]的返回类型标记为Series | Unknown | DataFrame——毕竟df[]在其他场景下（比如取单列）确实会返回Series。
• 你的代码实际运行正常，是因为运行时布尔逻辑生成了合法的布尔掩码，但静态检查阶段Pyright无法验证这一点，因此抛出类型不兼容警告。

替代解决方式（无需忽略错误） #

如果不想用# pyright: ignore抑制错误，可以通过以下方式让Pyright准确识别类型：

• 显式标注布尔掩码的类型：

def prune_to_wanted_rows(st_df: DataFrame, recency_date: str) -> DataFrame:
    mask: Series[bool] = (
        (st_df["assetType"] == "ore")
        & (st_df["priceCurrency"] == "USD")
        & (st_df["endDate"] >= recency_date)
    )
    st_df = st_df[mask]
    return st_df

• 改用query()方法，Pyright对该方法的类型推断更精准：

def prune_to_wanted_rows(st_df: DataFrame, recency_date: str) -> DataFrame:
    st_df = st_df.query('assetType == "ore" and priceCurrency == "USD" and endDate >= @recency_date')
    return st_df

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