如何为装饰器添加类型注解以支持方法重写？

问题场景 #

在VSCode Pylance严格模式中，为类方法添加带@wraps的装饰器后，子类重写父类方法时会触发reportIncompatibleMethodOverride类型错误。以下是最小复现示例（Python3.8+）：

from datetime import datetime
from functools import wraps
from typing import Any

_persistent_file = open("./persistent.log", "a")

def to_json(obj: Any) -> str:
    ...

def persistent(class_method: ...):
    @wraps(class_method)
    async def _class_method(ref: Any, *args: Any):
        rst = await class_method(ref, *args)
        print(f'{ datetime.now().strftime("%Y-%m-%d %H:%M:%S") } { to_json(args) } { to_json(rst) }', file=_persistent_file)
        return rst
    return _class_method

class A:
    async def f(self, x: int):
        return x

class B (A):
    @persistent
    async def f(self, x: int):
        return x + 1

触发的错误提示：

"f" overrides method of same name in class "A" with incompatible type "_Wrapped[(...), Any, (ref: Any, *args: Any), Coroutine[Any, Any, ...]]"
Pylance (reportIncompatibleMethodOverride)

移除@wraps可以规避错误，但会丢失函数元数据（如__name__），需要在保留元数据的前提下解决类型问题。

解决方案：为装饰器添加精确类型注解 #

问题根源是装饰器persistent缺少正确的类型注解，导致Pylance无法识别装饰后的方法与原方法类型一致。通过ParamSpec和TypeVar（Python3.10+内置，3.8/3.9需安装typing_extensions）可以给装饰器添加精确的类型约束，同时保留@wraps的元数据功能。

步骤1：导入必要的类型工具 #

• Python3.10+：

  from typing import Callable, Coroutine, ParamSpec, TypeVar, Any
  

• Python3.8/3.9：先安装typing_extensions（pip install typing_extensions），再导入：

  from typing import Callable, Coroutine, Any
  from typing_extensions import ParamSpec, TypeVar
  

步骤2：定义类型变量 #

P = ParamSpec("P")  # 捕获原函数的参数签名
R = TypeVar("R")    # 捕获原函数的返回值类型

步骤3：修改装饰器的类型注解和内部实现 #

def persistent(class_method: Callable[P, Coroutine[Any, Any, R]]) -> Callable[P, Coroutine[Any, Any, R]]:
    @wraps(class_method)
    async def _class_method(*args: P.args, **kwargs: P.kwargs) -> R:
        rst = await class_method(*args, **kwargs)
        print(f'{ datetime.now().strftime("%Y-%m-%d %H:%M:%S") } { to_json(args) } { to_json(rst) }', file=_persistent_file)
        return rst
    return _class_method

说明 #

• ParamSpec("P")会完整捕获原类方法的参数签名（包括self参数），TypeVar("R")捕获异步方法的返回值类型。
• 装饰器的返回类型与输入类型完全一致，Pylance会识别到装饰后的B.f与A.f的类型兼容。
• 内部的_class_method改用*args: P.args, **kwargs: P.kwargs替代宽泛的ref: Any, *args: Any，让参数类型更精确，进一步提升类型推断的准确性。

修改后的代码可正常通过Pylance的类型检查，同时保留@wraps带来的函数元数据。

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