Python TypeGuard 类型收窄 怎样处理

Python 的 TypeGuard 适合解决“运行时已经检查过，但类型检查器还不知道”的问题。处理这类类型收窄时，关键不是把返回值写成更具体的类型，而是让函数的第一个参数和检查逻辑保持一致：判断函数返回 True 后，类型检查器才把这个参数视为 TypeGuard[...] 中的目标类型。

官方资料入口：https://docs.python.org/3/library/typing.html

实战上可以先记住三条：TypeGuard 的 True 分支按目标类型精确收窄，False 分支通常保留原类型；当目标类型本来就是输入类型的子类型时，优先考虑 TypeIs；如果输入是可变容器，收窄后不要让其他代码通过别名修改它。

先把 TypeGuard 的收窄边界说清楚

TypeGuard[T] 是用户自定义类型判断函数的返回注解。类型检查器会把它当作一种特殊的布尔结果：函数返回 True 时，第一个位置参数被收窄到 T。它只描述静态类型关系，不会替你执行运行时检查，也不会自动证明函数实现是正确的。

因此下面这个函数的价值在于把“逐项检查”与“后续可用的类型”绑定起来，而不是让 Python 运行时多出一种检查机制。

from typing import TypeGuard

def is_str_list(value: list[object]) -> TypeGuard[list[str]]:
    # 逐项确认内容确实都是字符串，再承诺更具体的静态类型。
    return all(isinstance(item, str) for item in value)

def join_values(value: list[object]) -> str:
    if is_str_list(value):
        # 这一分支中，类型检查器把 value 看作 list[str]。
        return ", ".join(value)
    # False 分支仍按原来的 list[object] 处理。
    return "输入包含非字符串值"

如果守卫函数接受多个参数，类型收窄针对的是第一个位置参数；后续参数不会因为同一次调用自动获得对应的收窄。写函数时最好让第一个参数就是要判断的对象，避免调用者误以为多个参数会同时被证明。

逐项检查时，返回类型要和证据一致

类型守卫最容易出错的地方，是函数签名承诺了 list[str]，实现却只检查了列表本身，或者遗漏了空列表和混合元素。返回类型越具体，运行时的判定就越应该覆盖这个具体类型的全部必要条件。

例如，判断字典对象是否包含两个字符串字段时，可以把运行时证据限制在字段和值的检查上：

from typing import TypeGuard

def is_text_record(value: object) -> TypeGuard[dict[str, str]]:
    # 先确认容器类型，再确认键和值都满足字符串约束。
    if not isinstance(value, dict):
        return False
    return all(
        isinstance(key, str) and isinstance(item, str)
        for key, item in value.items()
    )

def render_record(value: object) -> str:
    if not is_text_record(value):
        return "记录格式不符合预期"
    # 此处可以按 dict[str, str] 读取键和值。
    return "；".join(f"{key}={item}" for key, item in value.items())

这里的重点是“证据覆盖承诺”：如果还要求必须存在 name 和 status 两个键，就应在守卫内部检查键是否存在，而不能只因为所有现有值都是字符串就返回 True。类型注解不会替代业务条件。

TypeGuard 和 TypeIs 怎么选

两者都能帮助类型检查器理解用户自定义的类型判断，但约束不同。TypeIs[T] 要求 T 是输入类型的子类型；TypeGuard[T] 没有这个限制，所以可以处理不满足普通泛型子类型关系的场景，例如把不变的 list[object] 判断为 list[str]。

from collections.abc import Sequence
from typing import TypeGuard, TypeIs

def is_str_sequence(value: Sequence[object]) -> TypeIs[Sequence[str]]:
    # Sequence[str] 是 Sequence[object] 的更具体视图，适合用 TypeIs。
    return all(isinstance(item, str) for item in value)

def is_str_list(value: list[object]) -> TypeGuard[list[str]]:
    # list 具有不变性，目标类型关系不满足 TypeIs 的子类型要求。
    return all(isinstance(item, str) for item in value)

选择顺序可以很简单：先问“目标类型是否确实是输入类型的子类型”，是就优先用 TypeIs；如果需要表达更宽输入到不满足子类型关系的目标类型，再使用 TypeGuard，并把可变性风险写进接口设计。

可变列表为什么会让收窄后的假设失效

TypeGuard 只记录某一时刻的判断结果。列表是可变对象，同一个列表可能同时被多个变量引用。一个函数刚判断完列表元素都是整数，另一个函数就可能通过别名追加布尔值或其他对象；类型检查器通常不会自动追踪这种跨调用、跨协程的修改。

from typing import Any, TypeGuard

def is_int_list(value: list[Any]) -> TypeGuard[list[int]]:
    # 这个判断只对当前时刻负责，不会冻结列表内容。
    return all(isinstance(item, int) for item in value)

def maybe_mutate(value: list[Any]) -> None:
    if is_int_list(value):
        # 收窄后继续修改共享列表，可能破坏其他调用方的类型假设。
        value.append(0)

更稳妥的做法是把输入声明为 Sequence 或 Iterable 等只读语义更强的接口；如果确实需要返回可变列表，就在守卫后复制出新的容器，把后续修改与原对象隔离。对于并发代码，还要避免在收窄后跨越可能修改共享对象的等待点。

落地时按这张清单收尾

• 守卫函数的第一个参数是否就是被收窄的对象。
• 返回 True 前，运行时检查是否覆盖目标类型的必要条件。
• 目标类型是输入类型的子类型时，是否可以改用 TypeIs。
• 输入是否为可变容器，收窄后是否还会被别名、回调或协程修改。
• 是否需要使用 Sequence 等更宽且偏只读的接口，或复制后再变更。

所以，Python TypeGuard 类型收窄的处理重点不是“把注解写得更具体”，而是让运行时证据、静态目标类型和对象生命周期三者保持一致。能用 TypeIs 表达子类型关系时优先使用它；必须用 TypeGuard 时，则把可变性和别名风险一起纳入设计。

相关问题

TypeGuard 会在运行时自动检查类型吗？

不会。它只是给类型检查器的返回值语义，实际检查逻辑仍然由函数体负责。

TypeGuard 的 False 分支会自动得到排除后的类型吗？

不能把它当成 TypeIs 的对称排除规则。TypeGuard 的核心保证是 True 分支按目标类型收窄，False 分支应结合具体类型检查器和原始类型理解。

为什么 list[object] 不能直接当作 list[str]？

list 是可变且不变的泛型容器。若允许任意把 list[object] 当作 list[str]，就可能通过后者写入非字符串对象，因此 TypeGuard 才能表达这类额外判断，但也需要承担相应的可变性风险。