Python枚举子类回调协议的Pyright类型检查适配问题

我正在为代码更新类型注解以适配Python 3.12，同时在VS Code中启用Pyright严格类型检查。定义了一个无成员的枚举子类：

class P(enum.Enum):
    ...

P包含事件驱动系统的基础方法，实际事件系统是P的子类，包含具体事件成员：

class P1(P):
    P1Event_1 = enum.auto()
    P1Event_2 = enum.auto()

class P2(P):
    P2Event_1 = enum.auto()
    P2Event_2 = enum.auto()

P中定义了action属性，允许为P1或P2的特定事件绑定回调函数；还定义了类方法actOnEvent，可解析事件字符串并触发对应事件的action回调。

回调需符合签名：

F(event: X, *args: str) -> returnCode

其中X代表P子类的成员类型（如P1.P1Event_1），这样同一个函数可作为多个事件的回调。

尝试将X定义为type[P]并声明协议：

from typing import Protocol, runtime_checkable

@runtime_checkable
class ActionProtocol(Protocol):
    def __call__(self, event: type[P], *args: str) -> int: ...  # 假设returnCode是int

但在P.actOnEvent内部及外部定义回调时均出现类型违规，无法实现预期效果。

核心问题是混淆了枚举类本身的类型和枚举成员的类型：type[P]指的是P类的类型，而枚举成员是P类的实例（包括子类实例），正确类型应为P或其子类类型。以下是具体修正方案：

1. 修正回调协议的基础类型 #

直接将回调的event参数指定为基类P，这样可以兼容所有P子类的成员：

from enum import Enum
from typing import Protocol, runtime_checkable

# 根据实际业务定义returnCode类型，这里以int为例
returnCode = int

@runtime_checkable
class ActionProtocol(Protocol):
    def __call__(self, event: P, *args: str) -> returnCode: ...

2. 用泛型实现严格的子类类型约束 #

如果需要回调只能接收特定子类的成员，可以引入泛型类型变量，让Pyright做更精准的类型检查：

from typing import TypeVar, Generic

T = TypeVar('T', bound=P)

@runtime_checkable
class ActionProtocol(Generic[T], Protocol):
    def __call__(self, event: T, *args: str) -> returnCode: ...

3. 修正P类的类型注解 #

在P类中，给actions属性和actOnEvent方法添加正确的类型注解：

class P(Enum):
    # 类级别的回调映射：键为P子类成员，值为符合协议的回调
    actions: dict['P', ActionProtocol] = {}

    @classmethod
    def actOnEvent(cls, event_str: str, *args: str) -> returnCode:
        # 解析字符串到枚举成员
        event = cls[event_str]
        callback = cls.actions.get(event)
        if callback:
            return callback(event, *args)
        # 无回调时的默认返回
        return -1

4. 外部回调定义示例 #

兼容所有事件的通用回调 #

def common_callback(event: P, *args: str) -> returnCode:
    print(f"处理事件: {event.name}, 参数: {args}")
    return 0

# 绑定到不同子类的事件
P1.actions[P1.P1Event_1] = common_callback
P2.actions[P2.P2Event_2] = common_callback

仅支持特定子类的回调（泛型版本） #

def p1_specific_callback(event: P1, *args: str) -> returnCode:
    print(f"处理P1专属事件: {event.name}, 参数: {args}")
    return 0

# Pyright会自动验证event类型与回调匹配
P1.actions[P1.P1Event_2] = p1_specific_callback

关键注意点 #

• 枚举成员的类型是枚举类的实例类型（如P1），而非类类型（type[P1]），这是之前类型违规的核心原因。
• 若不需要区分子类，直接用基类P作为回调参数类型即可；若需要严格约束，使用泛型可以让Pyright精准检查类型匹配。
• Pyright严格模式下会自动校验回调参数与绑定的枚举成员类型是否一致，避免类型不兼容的问题。

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