如何为Python泛型类添加类型提示以支持PyCharm自动补全

针对开发通用FSM库时遇到的类型提示问题，通过Python的泛型（typing.Generic）可模拟C++模板的特化效果，让PyCharm自动补全正常工作。以下是具体修改方案：

修改后的库代码 #

from typing import Generic, TypeVar, Type

# 定义泛型类型变量：OwnerType表示状态所有者类型，StateType表示状态基类类型
OwnerType = TypeVar('OwnerType')
StateType = TypeVar('StateType', bound='BaseState[OwnerType]')

class BaseState(Generic[OwnerType]):
    def __init__(self, owner: OwnerType, state_mgr: "StateManager[OwnerType, StateType]"):
        self.owner: OwnerType = owner
        self.state_mgr: StateManager[OwnerType, StateType] = state_mgr

class StateManager(Generic[OwnerType, StateType]):
    def __init__(self, owner: OwnerType, base_state_type: Type[StateType]):
        self.__owner: OwnerType = owner
        self.__base_state_type: Type[StateType] = base_state_type
        self.current_state: StateType = base_state_type(self.__owner, self)

    def transition_to(self, next_state_type: Type[StateType]) -> None:
        assert issubclass(next_state_type, self.__base_state_type), "状态类型不匹配"
        self.current_state = next_state_type(self.__owner, self)

修改后的使用代码 #

# 假设库代码在fsm模块中
import fsm

class FileSender_BaseState(fsm.BaseState["FileSender"]):
    def on_event(self, msg) -> None:
        pass

class FileSender_Idle(FileSender_BaseState):
    def on_event(self, msg) -> None:
        self.owner.foo()  # PyCharm将自动提示foo()方法

class FileSender_Sending(FileSender_BaseState):
    def on_event(self, msg) -> None:
        pass

class FileSender:
    def __init__(self):
        # 明确指定StateManager的泛型参数：所有者类型为FileSender，状态基类为FileSender_BaseState
        self._state_mgr: fsm.StateManager[FileSender, FileSender_BaseState] = fsm.StateManager(self, FileSender_BaseState)
        self._state_mgr.transition_to(FileSender_Idle)
        self._state_mgr.current_state.on_event(None)  # 自动提示on_event()方法

    def foo(self) -> None:
        pass

问题解决说明 #

1. BaseState的owner类型提示：
   给BaseState添加泛型参数OwnerType，子类FileSender_BaseState继承时指定OwnerType为FileSender，类型检查器可识别self.owner的具体类型，从而提供foo()的补全。

2. StateManager的current_state类型提示：
   StateManager通过泛型参数StateType绑定具体状态基类（如FileSender_BaseState），current_state直接标注为StateType，PyCharm可识别其类型并提示on_event()方法。

3. transition_to的参数类型限制：
   将transition_to的参数标注为Type[StateType]，结合泛型绑定，自动限制传入状态必须是StateType的子类，同时提供类型补全，原assert可保留做运行时验证。

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