PyCharm提示带默认参数的装饰器函数参数未填充问题排查

问题根源 #

PyCharm的静态代码分析依赖函数的元数据（包括参数签名、默认值等），如果重试装饰器没有正确保留原异步函数的元数据，就会导致IDE无法识别默认参数，出现「未填充」的错误提示。

修复方案 #

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

这是最基础的修复方式，wraps会把原函数的名称、文档字符串、参数签名等元数据复制到装饰后的包装函数上。

示例代码：

import asyncio
from functools import wraps
from typing import Optional, TypeVar, Callable, Awaitable

# 定义类型变量，关联原函数的返回值类型
T = TypeVar('T')

def retry(max_attempts: int = 3):
    def decorator(func: Callable[..., Awaitable[T]]) -> Callable[..., Awaitable[T]]:
        # 关键：用wraps装饰包装函数，保留原函数元数据
        @wraps(func)
        async def wrapper(*args, **kwargs) -> T:
            for attempt in range(max_attempts):
                try:
                    return await func(*args, **kwargs)
                except Exception as e:
                    if attempt == max_attempts - 1:
                        # 最后一次重试失败，抛出原异常
                        raise e
                    await asyncio.sleep(1)
        return wrapper
    return decorator

# 使用装饰器的示例函数
@retry(max_attempts=2)
async def test_function(a: int, b: Optional[str] = 'hi'):
    print(f"执行：a={a}, b={b}")
    if a == 1:
        raise ValueError("模拟执行错误")

# 调用时PyCharm会识别b的默认值，不会提示未填充
asyncio.run(test_function(2))

2. 补充精确的类型注解 #

给装饰器添加明确的类型注解（比如用TypeVar关联原函数的返回类型），能帮助PyCharm的静态分析更准确地识别函数签名。

3. 清除PyCharm缓存 #

如果修改后问题仍存在，可尝试清除IDE缓存：

• 点击菜单栏 File -> Invalidate Caches...
• 选择「Invalidate and Restart」，重启PyCharm后重新分析代码

边缘场景检查 #

如果你的装饰器存在以下情况，可能仍会出现识别问题：

• 装饰器修改了原函数的参数（比如新增/删除参数、改变参数顺序）
• 原函数使用*args/**kwargs作为唯一参数，没有明确的参数定义
• 装饰器的包装函数没有正确传递*args和**kwargs给原函数

只要重试逻辑仅做重复执行、不修改原函数的参数结构，按上述方案修复后，PyCharm就能正确识别默认参数。

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