Python typing.TypeGuard 处理复杂容器类型收窄

在处理 JSON、插件参数或配置文件时，一个容器经常同时装着字符串、数字和空值。运行时我们可以遍历元素做检查，但类型检查器并不会因为看见一个普通的 all() 就自动把 list[object] 变成 list[str]。这正是 typing.TypeGuard 适合解决的问题：把“某个布尔谓词为真时，参数可以按什么类型使用”写进函数签名。

TypeGuard 只改变类型检查器在正向分支中的类型视图，不会转换容器里的运行时对象。对可变的 list，收窄到不兼容的元素类型尤其要谨慎；能使用只读抽象时，优先考虑 Sequence 或 Iterable。

问题现场：检查过列表，字符串操作仍然报类型错误

假设配置入口接收的是 list[object]。我们希望只有当每一个元素都是字符串时，才把它交给需要字符串列表的函数。

from collections.abc import Sequence


def join_names(names: Sequence[str]) -> str:
    # 这里只读访问序列，调用方不需要暴露可变列表的写入能力。
    return ", ".join(names)


def print_names(values: list[object]) -> None:
    # 普通的 all 检查不会自动改变 values 的静态类型。
    if all(isinstance(value, str) for value in values):
        # 某些类型检查器仍会把这里看成 list[object]。
        print(join_names(values))

这里的运行时判断没有问题，问题在于静态分析需要一个可复用、可声明的谓词。TypeGuard 的返回值看起来仍是布尔值，但它额外告诉类型检查器：返回 True 时，第一个位置参数应当按指定的目标类型处理。

第一步：让谓词完整检查复杂容器

最小实现可以把参数写成 list[object]，把返回类型写成 TypeGuard[list[str]]。关键是谓词必须真的验证它承诺的条件，不能只检查第一个元素。

from typing import TypeGuard


def is_str_list(value: list[object]) -> TypeGuard[list[str]]:
    # 空列表没有反例；这里选择把它视为合法的字符串列表。
    return all(isinstance(item, str) for item in value)


def render_values(value: list[object]) -> str:
    if is_str_list(value):
        # True 分支中，类型检查器按 list[str] 处理 value。
        return " / ".join(value)
    # False 分支仍是 list[object]，不能直接当成字符串列表使用。
    return " / ".join(str(item) for item in value)

这个例子有三个容易被忽略的决定：

• 检查全部元素。如果只检查 value[0]，混合列表会被错误地承诺为 list[str]。
• 明确空列表策略。all() 对空迭代器返回 True，这通常符合“没有反例”的类型谓词语义；如果业务不接受空列表，要额外写 bool(value)。
• 不要把 TypeGuard 当作转换器。它不创建新列表、不复制元素，也不会把数字转成字符串。

第二步：确认收窄发生在哪个分支

用户定义的 TypeGuard 有一个很具体的规则：当函数返回 True 时，类型检查器把传入的第一个位置参数视为 TypeGuard[...] 中写出的目标类型；返回 False 时，不会自动从原类型里排除目标类型。

from typing import assert_type


def use_values(values: list[object]) -> None:
    if is_str_list(values):
        # 正向分支得到声明的具体类型。
        assert_type(values, list[str])
        print(values[0].upper())
    else:
        # 负向分支不会自动变成“含有非字符串的列表”。
        assert_type(values, list[object])
        print("发现混合元素")

    if not is_str_list(values):
        # 把条件写成 not 也不会让负向分支获得排除式收窄。
        assert_type(values, list[object])

assert_type() 是给类型检查器看的辅助断言，实际运行时不会替你完成类型转换。不同检查器对某些复杂表达式的展示文字可能不同，但这几个分支的设计边界是一样的：TypeGuard 只承诺正向结果。

第三步：把容器不变性纳入设计

很多“为什么 TypeGuard 能把 list[object] 收窄为 list[str]”的疑问，都和 list 的不变性有关。若类型系统允许把 list[str] 当成 list[object]，接收方就可能向其中写入整数，破坏原列表的字符串约束。

TypeGuard 特意允许目标类型不是输入类型的子类型，因此可以表达上面的收窄；代价是类型检查器相信你的谓词和后续代码。如果收窄后的对象仍然可以被其他代码通过别名修改，静态结论就可能在运行时失效。

from collections.abc import Sequence
from typing import TypeGuard


def is_str_sequence(value: Sequence[object]) -> TypeGuard[Sequence[str]]:
    # Sequence 只读，避免把收窄后的对象暴露出 append 等写入操作。
    return all(isinstance(item, str) for item in value)


def format_names(value: Sequence[object]) -> str:
    if is_str_sequence(value):
        # 目标仍是只读序列，收窄后的别名不应修改原始容器。
        return "、".join(value)
    return "、".join(str(item) for item in value)

这不是说所有场景都必须把 list 换成 Sequence。如果后续确实需要追加元素，可以在收窄后创建一个新的、受控的 list[str]；如果只是读取和格式化，使用只读接口更能让 TypeGuard 的承诺保持稳定。

第四步：对泛型容器保留元素类型

当目标不是固定的字符串，而是“容器中所有元素都属于调用者传入的某个类型”时，可以用 TypeVar 把检查函数泛化。运行时的 type[T] 参数负责检查，TypeGuard[set[T]] 负责把结果传回静态类型系统。

from typing import Any, TypeGuard, TypeVar

T = TypeVar("T")


def is_set_of(values: set[Any], expected: type[T]) -> TypeGuard[set[T]]:
    # 空集合没有不匹配元素；非空集合的每个元素都必须通过同一类型检查。
    return all(isinstance(value, expected) for value in values)


def consume_ids(values: set[Any]) -> None:
    if is_set_of(values, int):
        # 调用点传入 int 后，类型检查器可将 values 看成 set[int]。
        print(sum(values))

泛型谓词的边界是“声明必须和实现同步”。如果 expected 实际没有参与检查，或者函数内部为了方便使用了 Any 绕过判断，TypeGuard 仍然会把错误承诺传播给调用方。

第五步：需要双向收窄时比较 TypeIs

TypeGuard 和 TypeIs 都可以用来写用户定义的类型谓词，但适用边界不同：

例如，输入本来就是 str | bytes 时，想在 else 中得到“不是字符串”的结果，TypeIs 往往更贴近需求。如果目标是把可变的 list[object] 直接声明为 list[str]，则要先评估这种跨不变容器收窄是否真的安全，而不是只因为类型检查器接受就认为设计完成。

第六步：用测试约束谓词，而不是只测试调用方

类型检查器不会验证 TypeGuard 函数的实现是否真的满足返回类型。一个永远返回 True 的谓词也可能通过静态分析，直到调用方执行了不适合的操作才暴露问题。因此测试至少覆盖空容器、全匹配、混合元素和别名修改等情况。

def test_is_str_list() -> None:
    # 这些断言验证谓词的运行时承诺，不能被静态标注取代。
    assert is_str_list([])
    assert is_str_list(["alice", "bob"])
    assert not is_str_list(["alice", 42])
    assert not is_str_list([None])

如果项目把类型检查作为 CI 步骤，还应在调用点放置少量 assert_type()，用项目实际采用的检查器确认关键分支结果。这样能同时约束“运行时谓词有没有说真话”和“静态类型视图是不是团队预期”。

排查清单：TypeGuard 收窄不符合预期时看什么

1. 谓词是否把 TypeGuard 写在返回类型位置，而不是只返回普通 bool？
2. 调用对象是否是第一个位置参数？额外参数不会被一起收窄。
3. True 分支是否确实经过了该谓词调用？False 和 not 分支不要期待自动排除。
4. 目标类型是否和可变容器的写入能力冲突？只读使用优先考虑 Sequence 或 Iterable。
5. 谓词是否检查了全部元素、空容器策略是否明确、泛型参数是否真正参与运行时检查？
6. 运行时测试与静态 assert_type() 是否分别覆盖了实现和调用契约？

总结

TypeGuard 最有价值的地方，是把一个复杂的运行时判断变成可复用的静态类型入口。处理容器时，先让谓词完整验证元素，再记住它只在 True 分支收窄；面对 list 的不变性，尽量缩小写入权限，必要时改用只读抽象或复制出新容器。若问题需要 False 分支的排除式信息，并且目标类型满足子类型约束，再比较 TypeIs。

官方资料：https://docs.python.org/3/library/typing.html、https://typing.python.org/en/latest/spec/narrowing.html、https://typing.python.org/en/latest/guides/type_narrowing.html

相关问题

TypeGuard 会把列表元素自动转换成目标类型吗？不会。它只影响静态检查器的判断，运行时对象和元素值保持不变。

为什么 TypeGuard 的 False 分支没有变成排除后的类型？用户定义的 TypeGuard 只承诺 True 分支的目标类型；需要双向排除时，应评估 TypeIs 是否更合适。

空列表应该让 TypeGuard 返回 True 还是 False？取决于业务契约。若“没有发现反例”就算通过，all() 的 True 结果自然；若业务要求至少一个元素，需要显式增加非空判断。