Python typing.TypeGuard 和 TypeIs 的收窄差异

我第一次把自定义类型判断从 TypeGuard 换成 TypeIs 时，真正容易出错的不是导入路径，而是把两个分支想成了一回事。结论很简单：TypeGuard[T] 只承诺判断为真时把参数收窄为 T；TypeIs[T] 更像带类型信息的 isinstance()，真分支取交集，假分支排除 T。但 TypeIs 要求目标类型与输入类型保持一致，不能无条件替代 TypeGuard。

TypeGuard 与 TypeIs 的分支结果为什么不同

先看同一个判断函数在两种标注下的差别。下面的函数体都只是运行时布尔判断，真正改变的是静态类型检查器对调用点的解释。

from typing import TypeGuard, TypeIs, assert_type

def is_text_guard(value: object) -> TypeGuard[str]:
    # 运行时只负责回答“是不是字符串”。
    return isinstance(value, str)

def is_text(value: object) -> TypeIs[str]:
    # TypeIs 还把 False 分支的排除信息交给类型检查器。
    return isinstance(value, str)

def check(value: str | int) -> None:
    if is_text_guard(value):
        assert_type(value, str)
    else:
        # TypeGuard 的 False 分支仍可能是 str | int。
        assert_type(value, str | int)

    if is_text(value):
        assert_type(value, str)
    else:
        # TypeIs 能排除 str，因此这里得到 int。
        assert_type(value, int)

这也是很多“明明判断过了，else 里为什么还报错”的根因。TypeGuard 的设计允许目标类型不是输入类型的严格子类型，所以检查器不能安全地从返回 False 推导出补集。TypeIs 则按输入类型与目标类型的交集、差集近似处理两个分支。

把联合类型写进检查函数

如果目标只是判断一个值是不是字符串，输入写成 object、返回 TypeIs[str] 很直观。调用方的输入若已经是 str | int，TypeIs 会保留这份已知信息，正分支是 str，负分支是 int。这比“无论原来是什么，真分支都强行改成 T”更稳妥。

不过，TypeIs 不是运行时转换，也不会替你校验函数体是否真的可靠。判断函数返回值写错，静态类型就会被错误承诺。建议把判断逻辑保持得足够窄，并让函数名、参数类型和返回标注指向同一个事实：

from typing import TypeIs

def is_number_text(value: object) -> TypeIs[str]:
    # 这里的“字符串”判断不等于“内容可转成数字”。
    return isinstance(value, str)

def handle(value: int | str) -> int:
    if is_number_text(value):
        # 这里只能调用 str 的操作，不能把内容事实当成类型事实。
        return len(value)
    # False 分支排除了 str，剩下 int。
    return value + 1

一个常见误区是把业务条件写进类型谓词，例如“长度大于 3”却标成 TypeIs[str]。它虽然可能在类型上成立，但读者容易误解为函数在判断更具体的类型。类型谓词应表达类型事实，业务筛选留在普通 bool 函数里。

list 不变性会决定能不能换成 TypeIs

TypeGuard 最有价值的场景之一，是把 list[object] 检查成 list[str]。由于可变 list 是不变容器，list[str] 并不是 list[object] 的子类型；这正是 TypeGuard 可以表达、TypeIs 通常不能直接表达的边界。

from typing import TypeGuard

def is_string_list(values: list[object]) -> TypeGuard[list[str]]:
    # 只有逐项检查后，才承诺调用方可以按 list[str] 使用。
    return all(isinstance(item, str) for item in values)

def join_if_possible(values: list[object]) -> str:
    if is_string_list(values):
        # True 分支可按 list[str] 访问；这是 TypeGuard 的典型用途。
        return ",".join(values)
    return ""

如果把输入改成协变的只读抽象，例如合适的 Sequence[object]，再考虑 TypeIs[Sequence[str]] 会更自然。但不要为了“统一写法”强行替换：先问自己目标类型是否真的是输入类型的子类型，以及 False 分支是否有排除价值。

实际项目里怎么选并验证收窄

验证时不要只看编辑器有没有红线。给每个关键分支加一个 assert_type() 或临时 reveal_type()，让 mypy、pyright 等检查器明确报告结果；运行时仍然只验证函数返回的布尔值。TypeGuard 从 Python 3.10 开始可用，TypeIs 在 Python 3.13 进入标准库；旧运行时需要按项目支持范围使用 typing_extensions 的对应回移实现。

常见问题

TypeIs 能完全替代 TypeGuard 吗？

不能。只要目标类型不是输入类型的子类型，或你确实需要表达容器不变性带来的窄化，TypeGuard 仍然更合适。

为什么 TypeGuard 的 else 分支没有变成剩余类型？

这是 PEP 647 规定的语义：TypeGuard 只对 True 分支承诺目标类型，False 不提供补集信息。

TypeIs 的函数体需要返回特殊对象吗？

不需要，运行时返回普通布尔值即可；TypeIs 只是在返回标注中告诉静态检查器如何解释调用点。

把选择标准记成一句话：要表达“这个值可以按更宽松的目标类型使用”，先考虑 TypeGuard；要表达“它是这个输入联合类型中的哪一支”，优先考虑 TypeIs。最后用静态检查器逐个确认两个分支，收窄才真正可维护。