如何在Python存根文件中为带可变参数的函数编写正确类型注解？

问题根源 #

原函数def foo(*args, bar="bar")中，bar是关键字-only参数（位于*args之后），存根必须严格匹配这一特性，否则stubtest会报错“stub argument 'bar' is not keyword-only”。之前的重载写法未正确标记bar为关键字-only，导致校验失败。

正确的存根实现（foo.pyi） #

from typing import Any, TypeVar, overload

_P = TypeVar("_P")

@overload
def foo(*, bar: str = "bar") -> Any:
    ...

@overload
def foo(arg: _P, *, bar: str = "bar") -> _P:
    ...

@overload
def foo(*args: _P, bar: str = "bar") -> tuple[_P, ...]:
    ...

def foo(*args: object, bar: str = "bar") -> Any:
    ...

代码说明 #

• 第一个重载：用*标记无位置参数，仅允许通过关键字传递bar，对应“未传入args时返回Any”的需求。
• 第二个重载：接收单个位置参数arg（类型_P），bar为关键字参数，返回同类型_P，满足“传入一个类型为_P的args时返回_P”的规则。
• 第三个重载：接收任意多个同类型_P的位置参数，bar为关键字参数，返回tuple[_P, ...]，对应“传入多个同类型_P的args时返回元组”的场景。
• 兜底签名：最后一个非重载的函数签名用于静态类型检查的兜底，参数类型和返回值采用宽泛的object和Any即可。

验证 #

运行python -m mypy.stubtest foo，此时存根的参数特性与原函数完全匹配，不会再出现关键字参数相关的报错。

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