如何在Python中合规重写PySide6的QComboBox.addItem重载函数？

问题背景 #

PySide6的QComboBox.addItem在类型定义文件QtWidgets.pyi中有两个重载签名：

@overload
def addItem(self, icon: Union[PySide6.QtGui.QIcon, PySide6.QtGui.QPixmap], text: str, userData: Any = ...) -> None: ...
@overload
def addItem(self, text: str, userData: Any = ...) -> None: ...

由于text参数的位置不同，直接用@override重写时无法写出同时兼容两个签名的实现，以下是几种可行的处理方案：

1. 显式实现两个重载版本 #

利用typing.overload分别定义两个重载的签名，配合@override装饰器，同时提供一个兜底的实际实现函数，让类型检查器和运行时都能正常工作：

from typing import overload, Any, Union
from PySide6.QtWidgets import QComboBox
from PySide6.QtGui import QIcon, QPixmap
from overrides import override

class MyComboBox(QComboBox):
    @override
    @overload
    def addItem(self, icon: Union[QIcon, QPixmap], text: str, userData: Any = ...) -> None:
        # 带图标的自定义逻辑
        super().addItem(icon, text, userData)
    
    @override
    @overload
    def addItem(self, text: str, userData: Any = ...) -> None:
        # 仅文本的自定义逻辑
        super().addItem(text, userData)
    
    # 运行时实际调用的兜底函数
    def addItem(self, *args, **kwargs) -> None:
        super().addItem(*args, **kwargs)

这种方式完全符合类型检查要求，每个重载的签名都能被正确识别，适合需要对不同重载做差异化处理的场景。

2. 用参数展开兼容所有签名 #

通过*args和**kwargs接收任意参数，内部根据参数的数量、类型判断应该调用父类的哪个重载版本，同时用@override标记：

from typing import Any, Union
from PySide6.QtWidgets import QComboBox
from PySide6.QtGui import QIcon, QPixmap
from overrides import override

class MyComboBox(QComboBox):
    @override
    def addItem(self, *args: Union[QIcon, QPixmap, str, Any], **kwargs: Any) -> None:
        # 根据第一个参数的类型分发逻辑
        if args and isinstance(args[0], (QIcon, QPixmap)):
            super().addItem(*args, **kwargs)
        else:
            super().addItem(*args, **kwargs)

这种写法牺牲了部分静态类型检查的精确性，但实现简单，适合不需要对参数做精细校验的场景。

3. 临时忽略不兼容的重载检查 #

如果只需要重写其中一个重载版本，可以用# type: ignore跳过类型检查器对另一个重载的校验，这是妥协方案，不推荐长期使用：

from typing import Any, Union
from PySide6.QtWidgets import QComboBox
from PySide6.QtGui import QIcon, QPixmap
from overrides import override

class MyComboBox(QComboBox):
    @override
    def addItem(self, text: str, userData: Any = ...) -> None:
        # 仅重写文本版本的逻辑
        super().addItem(text, userData)
    
    # 忽略带图标重载的类型检查
    def addItem(self, icon: Union[QIcon, QPixmap], text: str, userData: Any = ...) -> None: # type: ignore
        super().addItem(icon, text, userData)

这种方式会绕过类型检查，可能隐藏潜在的类型错误，仅适合临时快速实现的场景。

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