本文讲解如何通过将类声明为泛型（Generic[_R]）来使 __init__ 中绑定的类型变量 _R 在实例方法中可被复用，从而解决 mypy 报出的类型变量作用域错误。
本文讲解如何通过将类声明为泛型（`generic[_r]`）来使 `__init__` 中绑定的类型变量 `_r` 在实例方法中可被复用，从而解决 `mypy` 报出的类型变量作用域错误。
在 Python 类型提示中，TypeVar 的作用域默认仅限于其首次被约束的上下文（如函数签名）。当你在 __init__ 中将 _R 绑定到 slot: Callable[..., _R] 时，该绑定不会自动延续到其他方法——即使它们属于同一实例。因此，_single_shot_wrapper 方法中直接使用 _R 会被 mypy 视为一个全新、未约束的类型变量，导致两个关键报错：
- A function returning TypeVar should receive at least one argument containing the same TypeVar
- Incompatible return value type (got "_R@__init__", expected "_R@_single_shot_wrapper")
根本解法是：将整个类声明为泛型类，使其能承载并传递类型参数 _R。
✅ 正确做法：泛型类声明
只需在类定义中继承 Generic[_R]，即可让 _R 成为类级别的类型参数，并在所有实例方法中保持一致绑定：
import typing as _t
from Qt import QtCore as _QtCore
_R = _t.TypeVar("_R")
class SingleShotConnect(_t.Generic[_R]):
_INSTANCES: _t.ClassVar[_t.Set["SingleShotConnect[_R]"]] = set() # 推荐：标注泛型集合（可选但更严谨）
def __init__(
self,
signal: "_QtCore.SignalInstance",
slot: _t.Callable[..., _R],
) -> None:
self._signal = signal
self._slot = slot
self._signal.connect(self._single_shot_wrapper)
SingleShotConnect._INSTANCES.add(self)
def _single_shot_wrapper(self, *args, **kwargs) -> _R:
self._signal.disconnect(self._single_shot_wrapper)
SingleShotConnect._INSTANCES.remove(self)
return self._slot(*args, **kwargs) # ✅ now type-safe: _R is consistently bound
? 注意：_INSTANCES 的类型注解建议升级为 Set["SingleShotConnect[_R]"]（需 Python ≥ 3.9 或启用 from __future__ import annotations），以准确反映泛型实例集合；若兼容性要求严格，保留原写法亦可，但会丢失部分类型精度。
⚠️ 补充说明与最佳实践
- 无需 ParamSpec：本方案完全兼容 Python 3.7+，不依赖 ParamSpec（该特性需 Python 3.10+），适用于旧版环境（如 PySide2 所在的 Qt5 生态）。
- 避免裸 TypeVar 在方法中独立出现：任何返回或参数含 _R 的方法，都应确保其所属类（或外层函数）已明确约束该 TypeVar。
- 实例化时类型推导自动生效：当用户创建 SingleShotConnect[int](sig, lambda: 42) 时，_R 即被推断为 int，_single_shot_wrapper 的返回类型也随之确定为 int，mypy 可完整验证调用链。
通过泛型类设计，你不仅修复了类型检查错误，还提升了 API 的可预测性与 IDE 支持（如自动补全、跳转定义），真正实现“一次连接、一次执行、类型安全”的 SingleShotConnect 抽象。
