为混合类与子类组合添加类型提示引发类型错误

问题背景 #

通过PySide6实现数据类与GUI类绑定，使用混合类HasDataobject为QGraphicsItem子类添加dataobject属性和update_visibility()方法。代码运行正常，但Pyright等静态校验工具会报错setVisible是未知方法：

• 让HasDataobject直接继承QGraphicsItem会触发初始化重复的RuntimeError
• 继承自定义的QGraphicsItemProtocol会引发元类冲突的TypeError
  需要找到既能通过Pyright校验，又能保留Qt子类化特性的类型提示方案。

可行解决方案 #

方案1：为方法的self添加联合类型注解 #

利用Self类型与协议类型的联合注解，明确self同时具备混合类和QGraphicsItem的方法特性，让Pyright识别setVisible方法：

from typing import TypeVar, Generic, Protocol, Self

from PySide6.QtWidgets import QGraphicsItem, QGraphicsEllipseItem

### 数据对象定义 ###
class VisibleData:
    def is_visible(self) -> bool:
        return True

class MyNode(VisibleData):
    pass

VisibleDataType = TypeVar('VisibleDataType', bound=VisibleData)

### 可视化对象定义 ###
class QGraphicsItemProtocol(Protocol):
    """定义HasDataobject需要用到的QGraphicsItem方法"""
    def setVisible(self, visible: bool, /):
        ...

class HasDataobject(Generic[VisibleDataType]):
    """混合类：为QGraphicsItem子类添加dataobject属性和可见性更新方法"""
    dataobject: VisibleDataType
    def update_visibility(self: Self & QGraphicsItemProtocol):
        self.setVisible(self.dataobject.is_visible())

class Circle(QGraphicsEllipseItem, HasDataobject[MyNode]):
    def __init__(self):
        super().__init__()

方案2：使用typing.cast强制类型转换 #

在update_visibility方法中，将self强制转换为QGraphicsItemProtocol类型，快速消除Pyright的报错提示：

from typing import TypeVar, Generic, Protocol, cast

# 其余代码与方案1一致

class HasDataobject(Generic[VisibleDataType]):
    dataobject: VisibleDataType
    def update_visibility(self):
        # 强制转换self类型，让Pyright识别setVisible方法
        cast(QGraphicsItemProtocol, self).setVisible(self.dataobject.is_visible())

方案3：通过协议约束子类类型 #

扩展协议定义，将混合类的属性和方法纳入协议，再通过self注解约束类型：

from typing import TypeVar, Generic, Protocol

# 其余代码与方案1一致

class HasDataobjectProtocol(Protocol, Generic[VisibleDataType]):
    dataobject: VisibleDataType
    def setVisible(self, visible: bool, /):
        ...

class HasDataobject(Generic[VisibleDataType]):
    dataobject: VisibleDataType
    def update_visibility(self: HasDataobjectProtocol[VisibleDataType]):
        self.setVisible(self.dataobject.is_visible())

方案说明 #

• 方案1是最优雅的实现方式，通过类型注解明确self的双重身份，无需额外转换操作
• 方案2代码侵入性最小，适合快速修复现有代码的校验问题
• 所有方案均不影响代码运行逻辑，仅为静态校验工具提供类型信息，完全保留Qt子类化的特性

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