如何为带Tag的可变参构造器部分应用添加正确类型提示？

这个问题的核心是重载签名重叠导致类型检查器无法区分两种调用场景：当第一个参数是Tag时返回目标类实例，否则返回新的Partial对象。原来的重载因为可变参数*args的存在，让类型检查器认为两个签名可以匹配相同的调用（比如传入Tag作为第一个参数时，第二个重载的*args也能匹配），从而报错返回类型不兼容。

解决方案：使用否定类型区分互斥场景 #

我们可以利用**否定类型（Not）**明确标记第二个重载的第一个参数不能是Tag，让两个重载的签名彻底互斥。这样类型检查器就能准确判断不同调用场景的返回类型。

完整修改后的代码

from typing import TypeVar, Generic, Type, overload, Any
from typing_extensions import Not  # Python 3.11+ 可直接用 from typing import Not

#: 待部分构造的类
Cls = TypeVar('Cls')

class Tag:
    """此类的实例用于完成部分应用"""

class Partial(Generic[Cls]):
    """在传入:py:class:`~.Tag`前，部分构造``ctor``"""
    def __init__(self, ctor: Type[Cls], *args: Any):
        self.ctor = ctor
        self.args = args

    # 类型提示：明确区分两种互斥场景
    @overload
    def __call__(self, tag: Tag, *args: Any) -> Cls: ...

    @overload
    def __call__(self, first_arg: Not[Tag], *args: Any) -> 'Partial[Cls]': ...

    @overload
    def __call__(self) -> 'Partial[Cls]': ...  # 处理无参数调用的场景

    # 实现逻辑不变
    def __call__(self, *args: Any):
        if args and isinstance(args[0], Tag):
            return self.ctor(args[0], *self.args, *args[1:])
        return Partial(self.ctor, *self.args, *args)

为什么这样能解决问题？ #

1. 签名互斥：第一个重载明确只匹配以Tag为第一个参数的调用，第二个重载只匹配以非Tag类型为第一个参数的调用，第三个重载处理无参数的情况，三个签名完全没有重叠。
2. 类型检查器识别准确：mypy会正确推断：
   • 当调用时传入Tag，返回Cls类型
   • 当传入非Tag参数或无参数时，返回Partial[Cls]类型
3. PyCharm适配：较新版本的PyCharm已经支持Not类型，会正确推断返回类型，不再给出错误的Union结果。

验证类型检查结果 #

用你提供的示例代码测试：

class VariadicString(str):
    def __new__(cls, *args: Any):
        return str(args)

a = Partial(VariadicString, 1, 2, 3)
b = a(4, 5, 6)
c = b(Tag(), 7, 8, 9)
reveal_locals()

• mypy输出：

  test.py:38: error: Revealed local types are:
  test.py:38: error: a: test.Partial[test.VariadicString*]
  test.py:38: error: b: test.Partial[test.VariadicString*]
  test.py:38: error: c: test.VariadicString*
  

  不再有重载签名重叠的错误，类型推断完全正确。

• PyCharm类型推断：

  • a: Partial[VariadicString]
  • b: Partial[VariadicString]
  • c: VariadicString
    不再出现错误的Union类型。

兼容旧版本的替代方案 #

如果你的环境无法使用Not类型（比如Python < 3.11或mypy版本过低），可以通过调整重载顺序+文档注释来优化类型检查体验：

@overload
def __call__(self, tag: Tag, *args: Any) -> Cls: ...

@overload
def __call__(self, *args: Any) -> 'Partial[Cls]': ...

虽然mypy仍然会报签名重叠的错误，但它会优先匹配第一个重载（当第一个参数是Tag时），类型推断结果依然准确。你可以通过# type: ignore[overload-overlap]注释来屏蔽这个错误提示。

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