如何为支持异构返回值的多参数协程函数添加正确Typehint？

你遇到的核心问题是单一泛型T无法描述多个不同类型的协程返回值，导致类型检查器只能把所有参数和返回值统一成第一个参数的类型。asyncio.gather()之所以能正确推断，是因为它用了可变泛型来支持任意数量、任意类型的协程输入，并返回对应顺序的类型元组。

解决方案 #

从Python 3.12开始，标准库typing模块原生支持可变泛型（TypeVarTuple + Unpack）；Python 3.11及以下版本可通过typing_extensions库兼容。

Python 3.12+ 原生实现 #

from typing import TypeVarTuple, Unpack, Coroutine, Any, Tuple
from functools import partial
import asyncio

# 定义可变类型元组，用于接收任意数量的不同类型
Ts = TypeVarTuple('Ts')

type PartialCoroutine[T] = partial[Coroutine[Any, Any, T]]

async def runPartialCoroutines(*args: Unpack[Tuple[PartialCoroutine[t] for t in Ts]]) -> Tuple[Unpack[Ts]]:
    # 执行所有partial包装的协程，按顺序收集结果
    tasks = [coro() for coro in args]
    results = await asyncio.gather(*tasks)
    return results

Python 3.11及以下兼容实现 #

先安装依赖：pip install typing_extensions，再编写代码：

from typing_extensions import TypeVarTuple, Unpack
from typing import Coroutine, Any, Tuple
from functools import partial
import asyncio

Ts = TypeVarTuple('Ts')

type PartialCoroutine[T] = partial[Coroutine[Any, Any, T]]

async def runPartialCoroutines(*args: Unpack[Tuple[PartialCoroutine[t] for t in Ts]]) -> Tuple[Unpack[Ts]]:
    tasks = [coro() for coro in args]
    results = await asyncio.gather(*tasks)
    return results

调用示例与类型推断验证 #

async def f1() -> int:
    return 1

async def f2() -> str:
    return "hello"

async def f3() -> bool:
    return True

async def main():
    # 类型检查器可正确推断：a=int, b=str, c=bool
    a, b, c = await runPartialCoroutines(partial(f1), partial(f2), partial(f3))
    print(a, b, c)

asyncio.run(main())

注意：原代码中直接传入f1()会得到Coroutine对象，而非PartialCoroutine类型，正确传参应为partial(f1)这类partial包装的函数。

原理说明 #

• TypeVarTuple('Ts')：定义一组可变的类型变量，可理解为类型列表[T1, T2, T3, ...]
• Unpack[Tuple[PartialCoroutine[t] for t in Ts]]：表示函数接受任意数量的PartialCoroutine参数，每个参数的返回类型对应Ts中的一个元素
• Tuple[Unpack[Ts]]：返回元组的元素类型和顺序与输入参数的返回类型完全对应，让类型检查器能精准推断每个变量的类型

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