VS Code/PyCharm中如何让装饰器包装器的文档串显示在悬停提示中？

针对VS Code（PyLance）的解决方法 #

方法1：移除functools.wraps并手动配置元信息 #

若你的装饰器原本使用@functools.wraps(func)同步原函数元信息，直接移除该装饰器，手动设置包装器的名称、限定名，并赋值合并后的文档串。PyLance会因包装器无__wrapped__属性，直接读取包装器的__doc__：

def magic(func):
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs)
    
    # 保持函数名与原函数一致
    wrapper.__name__ = func.__name__
    wrapper.__qualname__ = func.__qualname__
    # 合并原函数文档与装饰器额外内容
    wrapper.__doc__ = (func.__doc__ or "") + "\n\n额外说明：这是装饰器添加的文档内容"
    
    return wrapper

@magic
def sayHello():
    """原函数文档：打招呼函数"""
    print("Hello!")

方法2：用functools.update_wrapper排除__wrapped__ #

若需保留原函数的模块名、注解等元信息，但不想让PyLance追踪原函数文档，可使用update_wrapper并指定不设置__wrapped__属性：

import functools

def magic(func):
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs)
    
    # 复制指定元信息，不创建__wrapped__属性
    functools.update_wrapper(
        wrapper, 
        func, 
        assigned=('__module__', '__name__', '__qualname__', '__annotations__'),
        wrapped=()
    )
    # 设置合并后的文档串
    wrapper.__doc__ = (func.__doc__ or "") + "\n\n额外说明：装饰器添加的内容"
    
    return wrapper

方法3：临时关闭PyLance类型检查（不推荐） #

打开VS Code设置，搜索Python > Analysis: Type Checking Mode，改为off。此方法会关闭PyLance的类型检查功能，仅作临时应急方案。

针对PyCharm的解决方法 #

PyCharm的文档提示逻辑与PyLance一致，上述两种代码修改方法完全适用。此外，还有一个专属小技巧：

方法：给包装器添加@staticmethod（场景受限） #

若装饰的是普通函数，可在包装器上添加@staticmethod（不影响函数功能），让PyCharm优先读取包装器的文档串：

def magic(func):
    @staticmethod
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs)
    
    wrapper.__name__ = func.__name__
    wrapper.__doc__ = (func.__doc__ or "") + "\n\n额外说明：PyCharm专属适配"
    
    return wrapper

注意：此方法不适用于实例方法，会导致调用错误。

同时确保PyCharm文档提示开启：依次打开File > Settings > Editor > General > Code Completion，勾选Show the documentation popup in，并设置合适的弹出延迟。

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