Python3中如何为类包装器/方法外置类添加类型提示？

要让IDE同时识别原类属性和注入的新方法，核心是利用Protocol（协议）和交集类型来描述返回的类类型，以下是具体实现：

核心思路 #

1. 定义一个Protocol，声明要注入的新方法；
2. 使用TypeVar表示输入的原类类型；
3. 让装饰器/包装器的返回类型为原类类型与Protocol的交集，这样类型检查器会认为返回的类同时具备原类和新方法的特性。

装饰器实现（Python 3.10+） #

from typing import TypeVar, Protocol, Type

# 定义包含注入方法的协议
class InjectedProtocol(Protocol):
    def new_method(self) -> None:
        """新增的注入方法"""

T = TypeVar("T")

def decorator(cls: Type[T]) -> Type[T & InjectedProtocol]:
    def new_method(self) -> None:
        print("执行注入的方法")
    
    # 给原类绑定新方法，忽略类型检查器的属性未定义警告
    cls.new_method = new_method  # type: ignore[attr-defined]
    return cls

# 使用示例
class Base:
    def original_method(self) -> None:
        print("执行原类方法")

@decorator
class DecoratedBase(Base):
    pass

# 测试类型提示：IDE会同时提示original_method和new_method
obj = DecoratedBase()
obj.original_method()
obj.new_method()

包装器实现（子类继承方式） #

包装器的类型提示逻辑和装饰器一致，只是实现方式改为子类继承：

from typing import TypeVar, Protocol, Type

class InjectedProtocol(Protocol):
    def new_method(self) -> None:
        """新增的注入方法"""

T = TypeVar("T")

def wrapper(cls: Type[T]) -> Type[T & InjectedProtocol]:
    class WrappedClass(cls):
        def new_method(self) -> None:
            print("执行注入的方法")
    return WrappedClass

# 使用示例
class Base:
    def original_method(self) -> None:
        print("执行原类方法")

WrappedBase = wrapper(Base)
obj = WrappedBase()
obj.original_method()  # IDE提示原方法
obj.new_method()       # IDE提示新增方法

兼容Python 3.9及以下版本 #

如果使用Python 3.9或更早版本，需要借助typing_extensions的Intersection来实现交集类型：

from typing import TypeVar, Protocol, Type
from typing_extensions import Intersection

class InjectedProtocol(Protocol):
    def new_method(self) -> None:
        """新增的注入方法"""

T = TypeVar("T")

def decorator(cls: Type[T]) -> Type[Intersection[T, InjectedProtocol]]:
    def new_method(self) -> None:
        print("执行注入的方法")
    
    cls.new_method = new_method  # type: ignore[attr-defined]
    return cls

为什么之前的方案无效？ #

• 返回原类型：仅返回T时，类型检查器无法感知新增的方法，自然不会给出提示；
• 单纯继承Generic：仅定义Injected[T]无法让类型检查器将原类属性与新方法关联，因此没有任何提示。

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