Pyright检测df.astype('string')时出现类型不匹配错误的问询

我在项目中使用Pyright 1.1.357做类型检查时，遇到了代码运行正常但Pyright报类型错误的问题。代码是处理Pandas DataFrame的常规操作，具体细节如下：

代码示例 #

import pandas as pd

# Define the cleanup function
def cleanup(df: pd.DataFrame) -> pd.DataFrame:
    df['col_name_1'] = df['col_name_1'].astype('string')
    df = df.drop_duplicates(subset=['col_name_2'])
    return df

# Create a sample DataFrame
data = {'col_name_1': [1, 2, 3, 4, 5],
        'col_name_2': ['A', 'B', 'C', 'A', 'D']}
df = pd.DataFrame(data)
cleanup(df)

报错信息 #

error: "astype" is not a known member of "None" (reportOptionalMemberAccess)
error: Expression of type "DataFrame | None" cannot be assigned to declared type "DataFrame"

复现步骤 #

• 将上述代码保存为pandas_testing.py文件
• 在命令行执行：pyright pandas_testing.py

注：Pandas功能正常，仅Pyright检测存在误报。

解决方案 #

1. 升级Pyright到最新版本 #

Pyright旧版本（如1.1.357）对Pandas的类型标注支持存在不完善的地方，后续版本修复了大量Pandas相关的类型推断问题。执行以下命令升级：

pip install --upgrade pyright

升级后重新运行类型检查，这类误报通常会自动消失。

2. 添加显式类型断言（临时兼容方案） #

如果暂时无法升级Pyright，可以通过类型断言明确告诉Pyright变量的实际类型，避免误报：

import pandas as pd
from typing import cast

def cleanup(df: pd.DataFrame) -> pd.DataFrame:
    # 明确标注df['col_name_1']为Series类型
    col_series = cast(pd.Series, df['col_name_1'])
    df['col_name_1'] = col_series.astype('string')
    
    # 明确标注drop_duplicates返回的是DataFrame而非可选类型
    df = cast(pd.DataFrame, df.drop_duplicates(subset=['col_name_2']))
    return df

3. 调整Pyright配置（不推荐，仅临时应急） #

可以在项目的pyrightconfig.json中禁用对应的警告规则，但这会降低类型检查的严谨性，仅建议作为临时应急手段：

{
  "reportOptionalMemberAccess": false,
  "reportAssignmentTypeMismatch": false
}

原因说明 #

Pyright 1.1.357对Pandas的DataFrame.__getitem__返回类型推断不够精准，错误地认为访问DataFrame列可能返回None；同时对drop_duplicates方法的返回类型识别有误，将其标记为DataFrame | None，但实际上该方法在正常调用时始终返回DataFrame。这些问题在Pyright的后续版本中已被修复。

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