使用imbalanced-learn的RandomUnderSampler解包时为何出现元组不匹配错误？

问题背景 #

使用imbalanced-learn 0.12.3版本的RandomUnderSampler进行欠采样时，代码可正常运行，但Pylance持续抛出元组尺寸不匹配的类型错误提示。

涉事代码 #

from imblearn.under_sampling import RandomUnderSampler

# df = some pandas DataFrame

X_train, y_train = RandomUnderSampler(
    sampling_strategy=0.1,
    random_state=1234,
    replacement=False,
).fit_resample(df.drop("target", axis=1), df["target"])

Pylance错误提示 #

Expression with type "tuple[Unknown | DataFrame | ... | Series[Unknown], Unknown | DataFrame | ... | Series[Unknown]] | tuple[Unknown | DataFrame | ... | Series[Unknown], Unknown | DataFrame | ... | Series[Unknown], Unknown]" cannot be assigned to target tuple
  Type "tuple[Unknown | DataFrame | ... | Series[Unknown], Unknown | DataFrame | ... | Series[Unknown], Unknown]" is incompatible with target tuple
    Tuple size mismatch; expected 2 but received 3 Pylance(reportAssignmentType)

问题原因 #

这是Pylance的类型提示误报。imbalanced-learn 0.12.3的类型定义文件中，fit_resample方法的返回值被标注为可能返回2元组或3元组，但实际当仅传入特征矩阵X和标签y两个参数时，方法只会返回(X_resampled, y_resampled)的2元组，不存在返回3元组的情况。

解决方法 #

1. 添加类型断言 #

明确指定返回值的类型，让Pylance识别正确的元组结构：

from typing import Tuple
import pandas as pd
from imblearn.under_sampling import RandomUnderSampler

# df = some pandas DataFrame

X_train, y_train = RandomUnderSampler(
    sampling_strategy=0.1,
    random_state=1234,
    replacement=False,
).fit_resample(df.drop("target", axis=1), df["target"])  # type: Tuple[pd.DataFrame, pd.Series]

2. 跳过该条提示 #

在代码行末尾添加注释，让Pylance忽略该类型检查：

from imblearn.under_sampling import RandomUnderSampler

# df = some pandas DataFrame

X_train, y_train = RandomUnderSampler(
    sampling_strategy=0.1,
    random_state=1234,
    replacement=False,
).fit_resample(df.drop("target", axis=1), df["target"])  # noqa: reportAssignmentType

3. 升级imbalanced-learn版本 #

后续版本（如>=0.13.0）的imbalanced-learn已修复了该类型定义问题，升级后即可消除错误提示。

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