Pyright容器间联合类型传播问题：如何保留序列同质性？

问题场景 #

Pyright无法自动推导同构序列联合类型的转换关系，比如无法将Union[tuple[A, ...], tuple[B, ...]]映射为Union[list[A], list[B]]。以下示例中，函数接收Iterable[int]或Iterable[str]输入，尝试将其转为同构列表，但Pyright会错误推断出list[Union[int, str]]，触发类型错误：

from typing import Union, TypeAlias
from collections.abc import Iterable

Items: TypeAlias = Union[Iterable[int], Iterable[str]]

def process_items(items: Items) -> None:
    item_sequence: Union[list[int], list[str]] = list(items)

类型错误信息 #

Type "list[int | str]" is not assignable to declared type "list[int] | list[str]"
  Type "list[int | str]" is not assignable to type "list[int] | list[str]"
    "list[int | str]" is not assignable to "list[int]"
      Type parameter "_T@list" is invariant, but "int | str" is not the same as "int"

解决方案 #

可以通过以下几种方式实现转换并保留序列的同质性类型信息：

1. 使用函数重载 #

通过@overload为函数定义明确的输入输出类型对应关系，让类型检查器精准匹配每种情况：

from typing import Union, TypeAlias, overload
from collections.abc import Iterable

Items: TypeAlias = Union[Iterable[int], Iterable[str]]

@overload
def process_items(items: Iterable[int]) -> None: ...

@overload
def process_items(items: Iterable[str]) -> None: ...

def process_items(items: Items) -> None:
    item_sequence: Union[list[int], list[str]] = list(items)

2. 使用泛型与绑定TypeVar #

通过绑定TypeVar到目标类型集合，让类型检查器跟踪元素的具体同构类型，实现更简洁的类型约束：

from typing import TypeVar, Iterable

# 限定TypeVar只能是int或str
T = TypeVar("T", int, str)

def process_items(items: Iterable[T]) -> None:
    item_sequence: list[T] = list(items)

3. 显式类型转换（谨慎使用） #

如果上述方法不适用，可使用cast强制指定目标类型，但这会跳过类型检查，可能隐藏潜在错误：

from typing import Union, TypeAlias, cast
from collections.abc import Iterable

Items: TypeAlias = Union[Iterable[int], Iterable[str]]

def process_items(items: Items) -> None:
    item_sequence: Union[list[int], list[str]] = cast(Union[list[int], list[str]], list(items))

关于类型系统局限性的说明 #

这并非绝对的类型系统局限性，而是类型系统的设计选择。Python的容器类型（如list）的类型参数是**不变（invariant）**的，意味着list[Union[int, str]]与Union[list[int], list[str]]是完全不同的类型：前者允许列表同时包含int和str元素，后者要求列表元素必须全为同一类型。

Pyright默认将输入的联合类型“扁平化”到容器内部，是因为它无法在没有额外类型提示的前提下，确定输入的Iterable是同构的。通过重载、泛型等方式提供明确的类型信息，就能引导类型检查器正确识别序列的同质性。

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