Python TypeIs 为什么比 TypeGuard 更适合否定分支

如果一个用户自定义谓词的重点是“不是某种类型时，剩下的联合类型就可以继续处理”，TypeIs 通常比 TypeGuard 更合适。两者在运行时都只是返回布尔值，差别发生在静态类型检查器理解 if/else 的方式：TypeGuard 主要承诺真分支，而 TypeIs 同时描述真分支和否定分支。

记住一个实用判断：输入是 A，谓词返回 TypeIs[B]，那么 True 分支按“A 且 B”收窄，False 分支按“A 但不是 B”收窄。若 B 不是输入类型的可赋值子类型，就不要硬套 TypeIs。

先看同一个谓词的两个分支

下面把一个字符串判断分别写成 TypeGuard 和 TypeIs。示例中的 reveal_type 是给静态检查器看的标记，不能把它当成 Python 运行时的类型转换。

from typing import TypeGuard, TypeIs, reveal_type


def is_text_guard(value: object) -> TypeGuard[str]:
    # TypeGuard 只声明：返回 True 时，value 可以按 str 使用。
    return isinstance(value, str)


def is_text(value: object) -> TypeIs[str]:
    # TypeIs 要求 str 能够赋给输入类型 object。
    return isinstance(value, str)


def handle(value: str | int) -> None:
    if is_text_guard(value):
        reveal_type(value)  # 类型检查器通常显示 str。
        print(value.upper())
    else:
        reveal_type(value)  # TypeGuard 的否定分支仍可能是 str | int。

    if is_text(value):
        reveal_type(value)  # TypeIs 的真分支是 str。
        print(value.upper())
    else:
        reveal_type(value)  # TypeIs 排除了 str，这里可以按 int 处理。
        print(value + 1)

这就是标题中“更适合否定分支”的具体含义。不是说 TypeIs 的运行速度更快，也不是说它会在运行时替你检查所有注解，而是它把谓词的逻辑补集也交给了类型检查器。

TypeGuard 的假分支为什么不自动变窄

TypeGuard[T] 的设计允许一种很有用、但不一定是传统子类型关系的判断。类型检查器只需要相信：函数返回 True 时，传入的第一个参数可以当成 T。函数返回 False 时，检查器不能仅凭这个结果断定参数一定不属于 T，所以通常保留原来的类型。

这在“验证成功后进入专门处理路径”的场景很自然。例如，列表元素都经过检查后，可以在真分支里使用更具体的元素类型；但验证失败后，列表仍然可能包含各种对象，不能随意把它缩成另一个精确类型。

from typing import TypeGuard, reveal_type


def is_text_list(values: list[object]) -> TypeGuard[list[str]]:
    # 只有所有元素都是字符串时，才承诺真分支可按 list[str] 使用。
    return all(isinstance(item, str) for item in values)


def print_values(values: list[object]) -> None:
    if is_text_list(values):
        reveal_type(values)  # 类型检查器可将这里收窄为 list[str]。
        print(" / ".join(values))
    else:
        reveal_type(values)  # 否定分支仍是 list[object]，不能假定全部为数字。
        print(f"混合列表，共 {len(values)} 项")

这里的 list[str] 不是 list[object] 的普通子类型，因为可变列表具有不变性。正是这类“真分支需要一个并非输入子类型的结果”的场景，TypeGuard 仍然有价值。

TypeIs 的关键是“排除目标类型”

TypeIs 的规范模型可以简化成两个集合运算：输入变量当前类型是 A，返回标注是 TypeIs[B]。True 分支接近 A ∩ B，False 分支接近 A ∩ ¬B。在 Python 现有类型表达能力有限时，具体检查器会采用可行的近似，但方向就是同时处理正、负两面。

因此，下面这种代码更适合用 TypeIs：调用者本来就有一个封闭的联合类型，并且 else 分支要处理“排除目标后的剩余类型”。

from typing import TypeIs, reveal_type


def is_retryable(value: str | int) -> TypeIs[str]:
    # 这里的约定是：字符串代表可重试标签，整数代表重试次数。
    return isinstance(value, str)


def schedule(value: str | int) -> None:
    if is_retryable(value):
        reveal_type(value)  # 这里是 str，可交给标签分支。
        print(f"按标签调度：{value}")
    else:
        reveal_type(value)  # 这里排除了 str，剩下 int。
        print(f"按次数调度：{value + 1}")

相比在 else 里再次写一遍 isinstance(value, int)，TypeIs 让“谓词为假代表什么”成为函数契约的一部分。团队里维护这类函数时，真正要审查的是这个契约是否始终成立，而不是标注名字是否新颖。

先检查 TypeIs 的输入与返回关系

TypeIs 有一个不能绕过的边界：返回类型必须可以赋给谓词的输入类型。如果输入是 object，返回 str 没问题；如果输入是 int，却声明返回 TypeIs[str]，静态检查器应当报错。否则 False 分支就可能被错误地理解成“不是 str”，但输入本来就不允许是 str。

from typing import TypeIs


def is_text(value: object) -> TypeIs[str]:
    # str 是 object 的可赋值子类型，False 分支可以排除 str。
    return isinstance(value, str)


def invalid_predicate(value: int) -> TypeIs[str]:
    # 这是错误示范：str 不是 int 的可赋值子类型。
    return isinstance(value, str)

实际项目中可以把这条边界当成代码审查清单：第一，谓词至少接收一个位置参数；第二，运行时所有返回路径都返回布尔值；第三，目标类型确实是输入类型的可赋值收窄；第四，函数实现返回 True 的条件与标注一致。

什么时候仍然选 TypeGuard

TypeIs 不是 TypeGuard 的全面替代。遇到下面几种情况，TypeGuard 往往更合适：

• 验证成功后要把可变容器从 list[object] 视为 list[str]，但目标容器类型不是输入容器的子类型。
• 函数只想表达“成功路径具备某种更具体能力”，并不想对失败路径作排除承诺。
• 输入类型很宽，失败后仍需要保留原始对象，调用方会继续做其他独立判断。

反过来，如果输入是 Shape，目标是它的一个明确子类型，并且失败分支要处理“不是该子类型的 Shape”，优先考虑 TypeIs。命名也应反映真实语义：不要把一个只验证部分属性的函数标成 TypeIs，然后让调用方误以为目标类型已经完全成立。

用静态检查器检查谓词契约

类型注解主要服务于静态工具，Python 运行时不会自动执行这些收窄。可以在类型检查配置中启用更严格的检查，并用 reveal_type 或 assert_type 观察每个分支的推断结果。示例只展示检查点，不把工具输出伪装成运行结果。

from typing import TypeIs, assert_type


def is_name(value: object) -> TypeIs[str]:
    # 返回值来自真实运行时判断，注解负责描述分支契约。
    return isinstance(value, str)


def consume(value: str | int) -> None:
    if is_name(value):
        assert_type(value, str)  # 用断言记录真分支的预期类型。
        print(value.strip())
    else:
        assert_type(value, int)  # 用断言记录排除 str 后的预期类型。
        print(value.bit_length())

如果项目还要支持没有内置 TypeIs 的 Python 版本，可以根据项目的兼容策略使用 typing_extensions 的回移版本；不要为了兼容性把 TypeIs 改写成没有契约含义的普通 bool，否则否定分支的收窄信息会丢失。

最后的选择表

常见追问

TypeIs 会在运行时自动转换对象吗？

不会。它通常只是返回一个布尔值，运行时行为来自函数体；类型收窄是静态检查器对分支的理解。

TypeGuard 的 else 分支一定完全不能收窄吗？

用户自定义 TypeGuard 的标准语义只保证真分支收窄。else 里仍可能因为其他条件、字面量或内置判断发生额外收窄，但不能把这种额外信息归因于 TypeGuard 本身。

TypeIs 是否只能接收一个参数？

函数至少要有一个位置参数，收窄作用在第一个位置参数上；可以有其他参数，但它们不会因此被收窄。

把所有类型判断都改成 TypeIs 可以吗？

不建议。先确认返回目标是输入类型的可赋值收窄，并确认失败分支确实代表排除目标类型；对可变容器等非子类型验证，TypeGuard 仍然是更准确的表达。