如何创建可被mypy认可的Qt5队列信号连接？

问题场景 #

常规的PyQt5信号连接代码可以正常运行：

def clicked() -> None:
    print("clicked")
btn = QtWidgets.QPushButton("Button", window)
btn.clicked.connect(clicked)

但当使用QtCore.Qt.QueuedConnection创建队列连接时：

btn.clicked.connect(clicked, QtCore.Qt.QueuedConnection)

代码功能正常，但mypy会抛出错误：Too many arguments for "connect" of "pyqtBoundSignal"。

问题原因 #

官方PyQt5-stubs中的pyqtBoundSignal类的connect方法仅定义了单参数重载，未包含接收连接类型参数的重载版本，导致mypy无法识别合法的双参数调用。

解决方案 #

方案1：自定义Stub并配置mypy加载 #

创建自定义stub文件补充connect方法的双参数重载，确保mypy优先加载自定义stub而非官方版本：

1. 在项目中创建stub目录结构，比如./stubs/PyQt5/QtCore.pyi
2. 在该文件中补充pyqtBoundSignal的重载定义：

from typing import Callable, overload, Any

class pyqtBoundSignal:
    @overload
    def connect(self, slot: Callable[..., Any]) -> None: ...
    @overload
    def connect(self, slot: Callable[..., Any], type: int) -> None: ...
    def disconnect(self, slot: Callable[..., Any] = ...) -> None: ...
    def emit(self, *args: Any) -> None: ...

3. 配置mypy加载自定义stub：
   • 在项目根目录创建mypy.ini，添加：

     [mypy]
     mypy_path = ./stubs
     

   • 或在pyproject.toml中添加：

     [tool.mypy]
     mypy_path = ["stubs"]
     

方案2：临时忽略类型检查 #

如果不想修改stub，可在报错行添加类型忽略注释，快速绕过检查：

btn.clicked.connect(clicked, QtCore.Qt.QueuedConnection)  # type: ignore[call-arg]

该方法适合临时场景或小型项目，但会跳过该行的类型校验。

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