类内被装饰器修饰的方法类型提示失效，如何修复？

问题场景 #

现有Message类：

class Message:
    def __init__(self, id_: int, text: str):
        self.id = id_
        self.text = text

Account类的send_message方法返回Message实例，未被装饰时，IDE可正常提供Message属性提示及参数缺失检测：

class Account:
    def __init__(self):
        ...

    def send_message(self, chat_id: int, text: str) -> Message:
        message_id = ...  # 发送请求并从响应中获取消息ID
        return Message(message_id, text)

但使用自定义装饰器my_wrapper修饰该类方法后，类型提示完全失效：IDE无法识别Message的属性和方法，也无法检测参数问题：

from typing import Callable, TypeVar, ParamSpec

PARAMS = ParamSpec("PARAMS")
RETURN_VAL = TypeVar("RETURN_VAL")

def my_wrapper(func: Callable[PARAMS, RETURN_VAL]) -> Callable[PARAMS, RETURN_VAL]:
    def wrapper(*args: PARAMS.args, **kwargs: PARAMS.kwargs) -> RETURN_VAL:
        # 执行一些操作
        return func(*args, **kwargs)
    return wrapper

class Account:
    def __init__(self):
        ...
    
    @my_wrapper
    def send_message(self, chat_id: int, text: str) -> Message:
        message_id = ...  # 发送请求并从响应中获取消息ID
        return Message(message_id, text)

修复方案 #

核心问题是装饰器返回的wrapper函数未保留原类方法的元数据（包括类型注解），导致类型检查器无法关联原方法的类型定义。以下是两种有效修复方式：

方法1：用functools.wraps保留原函数元数据 #

导入functools模块，在内部wrapper函数上添加@functools.wraps(func)装饰器。它会将原函数的名称、文档字符串、类型注解等元数据复制到wrapper上，让类型检查器能正确识别原方法的类型信息：

from typing import Callable, TypeVar, ParamSpec
import functools

PARAMS = ParamSpec("PARAMS")
RETURN_VAL = TypeVar("RETURN_VAL")

def my_wrapper(func: Callable[PARAMS, RETURN_VAL]) -> Callable[PARAMS, RETURN_VAL]:
    @functools.wraps(func)
    def wrapper(*args: PARAMS.args, **kwargs: PARAMS.kwargs) -> RETURN_VAL:
        # 执行一些操作
        return func(*args, **kwargs)
    return wrapper

class Account:
    def __init__(self):
        ...
    
    @my_wrapper
    def send_message(self, chat_id: int, text: str) -> Message:
        message_id = ...  # 发送请求并从响应中获取消息ID
        return Message(message_id, text)

方法2：显式标注self类型（可选增强） #

如果需要更精准的类型约束，可以在send_message方法的self参数上显式标注Account类型，配合functools.wraps使用，能进一步提升类型检查的准确性：

class Account:
    def __init__(self):
        ...
    
    @my_wrapper
    def send_message(self: "Account", chat_id: int, text: str) -> Message:
        message_id = ...  # 发送请求并从响应中获取消息ID
        return Message(message_id, text)

原理说明 #

functools.wraps会修改wrapper函数的__annotations__、__name__等核心属性，使其与原函数完全一致。对于类方法而言，这能让类型检查器识别到self对应的类上下文，从而正确关联返回值Message的属性提示，同时保留参数的类型校验能力。

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