为何类型检查拒绝将list[str]传入ScalarOrList[str|int]参数？

核心问题分析 #

1. 第一个报错原因：Python标准库的list是不变泛型类型，list[str]无法被视为list[str | int]的子类型，即便str是str | int的子类型。你定义的ScalarOrList[T] = T | list[T]默认是不变的，导致list[str]无法匹配ScalarOrList[str | int]。
2. 改用Sequence后的问题：Sequence是协变类型，但范围过宽（包含str、Enum等你想当作标量的类型），且类型检查器无法准确推断排除Sequence后xs的具体类型，引发返回值类型不匹配。

解决方案 #

1. 让ScalarOrList支持协变 #

给泛型参数添加+标记，将ScalarOrList声明为协变类型别名，这样ScalarOrList[str]可以隐式转换为ScalarOrList[str | int]：

from typing import Optional, TypeVar

# 声明协变泛型参数
type ScalarOrList[+T] = T | list[T]

2. 精准实现as_list函数 #

直接检查xs是否为list（而非宽泛的Sequence），既符合你不想处理str/Enum等序列的需求，又能让类型检查器准确推断分支类型：

from typing import Optional, TypeVar, cast

type ScalarOrList[+T] = T | list[T]

# 用协变类型变量定义函数泛型
T_co = TypeVar("T_co", covariant=True)

def as_list[T_co](xs: Optional[ScalarOrList[T_co]], length: int = 1) -> list[T_co]:
    if isinstance(xs, list):
        return list(xs)  # 直接返回list拷贝，避免生成器冗余
    elif xs is not None:
        # 用cast明确类型，辅助类型检查器推断
        return [cast(T_co, xs) for _ in range(length)]
    else:
        return []

3. 验证调用场景 #

修改后，list[str]可以正常传递给接受ScalarOrList[str | int]的函数：

def f(xs: ScalarOrList[str | int]):
    print(xs)

only_strs: list[str] = ["hello", "world"]
f(only_strs)  # 类型检查通过

替代方案（显式类型转换） #

如果不想修改ScalarOrList的协变性，可以在调用时显式转换类型，但这种方式不够优雅：

from typing import cast

f(cast(ScalarOrList[str | int], only_strs))

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