使用Python装饰器修改参数注解并被类型检查器识别的实现问题

首先明确核心前提：所有主流Python类型检查器（mypy、pyright、pytype等）均为静态分析工具，不会执行任何运行时代码。你当前在装饰器内部通过inspect模块修改参数签名、或者直接修改__annotations__属性的操作都是运行时逻辑，静态分析阶段完全无法感知，因此不可能被类型检查器识别。

基于PEP 612的静态适配方案 #

PEP 612引入的ParamSpec和Concatenate就是为了解决装饰器的参数类型透传问题，你只需要给装饰器本身加上正确的泛型类型注解，让类型检查器可以静态推导装饰后的函数签名即可，不需要依赖运行时修改逻辑。

以下是适配后的代码示例：

from typing import (
    Callable,
    Literal,
    TypeVar,
    Generic,
    ParamSpec,
    Concatenate
)
import functools

from discord import Member

T = TypeVar('T')
V = TypeVar('V')
# 定义ParamSpec捕获原函数的剩余参数类型
P = ParamSpec('P')
# 定义返回值泛型
R = TypeVar('R')

class Option(Generic[T, V]):
    pass


# 装饰器的类型注解明确声明：接收第一个参数为Option[Member, Any]的函数，返回第一个参数为Member的函数
def change_decorator_func(f: Callable[Concatenate[Option[Member, Any], P], R]) -> Callable[Concatenate[Member, P], R]:
    @functools.wraps(f)
    def wrapped(this: Member, *args: P.args, **kwargs: P.kwargs) -> R:
        # 这里写你的实际业务逻辑，比如从Option实例中解包出Member对象
        # 示例逻辑仅供参考
        return f(*args, **kwargs)
    return wrapped


@change_decorator_func
def foo(this: Option[Member, Literal['This is a test']]) -> None:
    # 此时类型检查器会识别到this的类型为Member，访问display_name不会报错
    this.display_name

其他场景适配说明 #

• 如果你的参数修改逻辑更复杂，可以通过typing.overload定义多组装饰器的输入输出类型匹配规则，覆盖不同的原函数签名场景
• 运行时修改__annotations__的操作仅对运行时依赖注解的逻辑生效（比如数据校验、自动文档生成），对静态类型检查没有任何作用
• 如果需要实现完全动态的注解修改推导，需要对应类型检查器的自定义插件支持，通用Python类型体系目前不支持任意动态修改的静态推导

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