如何修改list[str]类型注解使其兼容list[LiteralString]？

问题场景 #

我有一个接收list[str]类型输入的函数：

def function(names: list[str]) -> None:
    for name in names:
        print(name)

当使用split()生成列表时，得到的是list[LiteralString]类型对象，mypy会标记类型错误：

names = "Jürgen Klopp".split()
function(names)  # Argument of type "list[LiteralString]" cannot be assigned to parameter "names" of type "list[str]" in function "function"

但非列表场景下无需额外处理就能正常运行，比如：

def fn(name: str):
    print(name)

names = "Jürgen Klopp".split()
given_name: LiteralString = names[0]
fn(given_name)  # 无类型错误

我想了解LiteralString与列表结合的正确用法，目前用自定义类型StrListType = list[str] | list[LiteralString]作为临时方案，但不够优雅。

原因解析 #

LiteralString是str的子类型，但Python的泛型列表list是不变类型——也就是说list[LiteralString]并不被视为list[str]的子类型，因此无法直接赋值。而单个LiteralString实例可以隐式向上转型为str，所以非列表场景不会触发类型错误。

正确处理方式 #

1. 改用协变的序列类型作为参数类型 #

将函数参数的list[str]替换为Sequence[str]或Iterable[str]，这两个泛型是协变的，list[LiteralString]可以兼容赋值给它们：

from typing import Sequence

def function(names: Sequence[str]) -> None:
    for name in names:
        print(name)

names = "Jürgen Klopp".split()
function(names)  # 类型检查通过

2. 显式转换或注解列表类型 #

可以通过cast强制转换类型，或者直接给变量标注list[str]类型，让mypy认可这个赋值：

from typing import cast

# 方式1：使用cast
names = cast(list[str], "Jürgen Klopp".split())
function(names)

# 方式2：直接注解变量类型
names: list[str] = "Jürgen Klopp".split()
function(names)

3. 声明协变的泛型类型 #

如果必须严格使用list作为参数类型，可以通过TypeVar声明协变的类型变量，让函数接受str及其子类型的列表：

from typing import TypeVar, List

T = TypeVar("T", bound=str, covariant=True)

def function(names: List[T]) -> None:
    for name in names:
        print(name)

names = "Jürgen Klopp".split()
function(names)  # 类型检查通过

临时方案的不足 #

自定义StrListType = list[str] | list[LiteralString]虽然能解决当前问题，但会导致类型定义冗余，后续如果遇到str的其他子类型，还需要不断扩展这个联合类型，维护成本更高，不如上述方法简洁通用。

内容的提问来源于stack exchange，提问作者Paweł Wójcik