为何使用多参数装饰器重写方法时Pyright报不兼容错误？

我在使用装饰器重写父类方法时遇到了Pyright类型检查错误：仅当方法包含self和另一个参数时会触发错误，仅保留self参数时错误消失。

报错的代码 #

from functools import wraps
from typing import Callable, Concatenate, ParamSpec, TypeVar

T = TypeVar("T")
P = ParamSpec("P")
R = TypeVar("R")


# 装饰器显式声明了channel参数
def use_channel(
    func: Callable[Concatenate[T, str, P], R]
) -> Callable[Concatenate[T, str, P], R]:
    @wraps(func)
    def wrapper(self: T, channel: str, *args: P.args, **kwargs: P.kwargs) -> R:
        print(f"[Decorator] self={self}, channel={channel}")
        return func(self, channel, *args, **kwargs)
    return wrapper


class A:
    def set_channel(self, channel: str):
        pass


class B(A):
    @use_channel
    # 触发Pyright错误
    def set_channel(self, channel: str):
        pass

无错误的代码 #

from functools import wraps
from typing import Callable, Concatenate, ParamSpec, TypeVar

T = TypeVar("T")
P = ParamSpec("P")
R = TypeVar("R")

# 装饰器仅用*args接收额外参数
def use_channel(
    func: Callable[Concatenate[T, P], R]
) -> Callable[Concatenate[T, P], R]:
    @wraps(func)
    def wrapper(self: T, *args: P.args, **kwargs: P.kwargs) -> R:
        print(f"[Decorator] self={self}")
        return func(self, *args, **kwargs)
    return wrapper


class A:
    def set_channel(self, channel: str):
        pass


class B(A):
    @use_channel
    # 无错误
    def set_channel(self, channel: str):
        pass

错误信息 #

Method "set_channel" overrides class "A" in an incompatible manner
Parameter 2 mismatch: base parameter "channel" is keyword parameter, override parameter is position-only

原因分析 #

这确实和Pyright的方法兼容性检查机制直接相关：

• 当装饰器显式声明channel参数时，Pyright会解析出装饰后的方法将channel标记为位置-only参数（因为channel在*args之前，没有默认值也没有*分隔符），但父类A中的channel是普通关键字参数（支持位置+关键字传递），两者参数传递方式不匹配，触发兼容性错误。
• 当装饰器用*args接收所有额外参数时，functools.wraps会保留原方法的参数元信息，Pyright能识别出子类方法的参数签名和父类完全一致，因此不会报错。

简单来说：显式拆解参数会破坏原方法的参数属性，让Pyright误判参数传递方式；而用*args/**kwargs转发参数则能保留原签名的完整性。

修复方案 #

如果需要在装饰器中获取channel参数，同时避免类型检查错误，推荐保留*args/**kwargs的转发方式，在装饰器内部提取参数：

from functools import wraps
from typing import Callable, Concatenate, ParamSpec, TypeVar

T = TypeVar("T")
P = ParamSpec("P")
R = TypeVar("R")

def use_channel(func: Callable[Concatenate[T, P], R]) -> Callable[Concatenate[T, P], R]:
    @wraps(func)
    def wrapper(self: T, *args: P.args, **kwargs: P.kwargs) -> R:
        # 从参数中提取channel，兼容位置和关键字传递
        channel = args[0] if args else kwargs["channel"]
        print(f"[Decorator] self={self}, channel={channel}")
        return func(self, *args, **kwargs)
    return wrapper

这种写法既满足装饰器的功能需求，又能让Pyright正确识别子类方法与父类的签名兼容性。

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