Python 3.15 的 TypeIs 和 TypeGuard 有什么区别

如果你在 Python 3.15 项目里给“类型判断函数”补注解，TypeIs 和 TypeGuard 都能让类型检查器理解 if 分支，但两者的含义并不一样。简单记：输入类型与目标类型兼容、而且希望 else 也能排除一部分类型时，用 TypeIs；需要把一个容器精确替换成不兼容的目标类型时，保留 TypeGuard。

TypeIs 更像带类型信息的 isinstance()：真分支收窄到交集，假分支排除目标类型；TypeGuard 只保证真分支使用声明的目标类型，假分支不额外收窄。

先用一个联合类型看清两种收窄方向

先做一个最小的工单对象判断。这个例子不依赖框架，重点是观察检查器如何处理同一个变量的两个分支：

from typing import TypeIs, reveal_type

class Ticket:
    # 工单只保留一个演示字段，避免把例子变成业务模型
    def __init__(self, title: str) -> None:
        self.title = title

def is_ticket(value: object) -> TypeIs[Ticket]:
    # 返回值必须是可靠的布尔类型判断
    return isinstance(value, Ticket)

def show(value: Ticket | str) -> None:
    if is_ticket(value):
        reveal_type(value)  # Ticket
        print(value.title)
    else:
        reveal_type(value)  # str
        print(value.upper())

这里的关键不是函数名，而是返回注解。TypeIs[Ticket] 告诉检查器：当结果为真，输入可以收窄为 Ticket；当结果为假，原来的 Ticket | str 可以排除 Ticket，留下 str。这就是 TypeIs 与普通 bool 返回值的区别。

用 TypeIs 表达与输入类型兼容的判断

PEP 742 把 TypeIs 定义为一种更接近 isinstance() 的用户自定义类型判断。目标类型要和函数的输入类型保持一致的兼容关系，否则检查器应报错。例如，object -> TypeIs[Ticket] 合理，int -> TypeIs[str] 就不合理。

兼容关系带来的好处，是检查器不会丢掉变量原先已经知道的类型。若输入是 Child | Unrelated，判断目标是 Base，真分支可以保留更精确的 Child，假分支则排除 Base 后留下 Unrelated。这比简单地把变量替换成一个宽泛目标类型更稳。

在需要不兼容替换时保留 TypeGuard

TypeGuard 并没有过时，它解决的是 TypeIs 明确禁止的一类问题：目标类型可以与输入类型不兼容。典型例子是把可变的 list[object] 判断为 list[int]：

from typing import TypeGuard

def is_int_list(value: list[object]) -> TypeGuard[list[int]]:
    # 只有每个元素都是 int 时才允许走精确列表分支
    return all(isinstance(item, int) for item in value)

def total(value: list[object]) -> int:
    if is_int_list(value):
        # TypeGuard 在这里把目标视为 list[int]
        return sum(value)
    return 0

这个能力很有用，但也更容易被误用。列表是可变对象，判断通过后如果还有别的代码把非整数写进去，静态类型承诺就可能失真。若你的目标只是判断某个联合类型的成员，优先写成 TypeIs；只有确实需要这种不兼容替换，并且能控制对象的后续修改时，才使用 TypeGuard。

把类型检查器和 Python 版本纳入验收

TypeIs 的运行时表现仍然只是一个布尔值，真正的分支类型来自 mypy、Pyright 等静态检查器。因此验收要分两层：先运行测试确认判断函数没有写错，再运行项目实际使用的检查器确认 reveal_type 结果符合预期。

try:
    from typing import TypeIs
except ImportError:
    # 兼容尚未把 TypeIs 放入 typing 的旧 Python 版本
    from typing_extensions import TypeIs

def is_non_empty_text(value: object) -> TypeIs[str]:
    # TypeIs 必须覆盖所有合法 str，而不是只接受非空字符串
    return isinstance(value, str)

不要把“返回了 True”当成类型设计正确。TypeIs 函数如果漏掉一部分目标类型，或把目标类型之外的值判成真，检查器通常无法替你发现。最后检查三件事：导入路径与运行版本匹配；真、假分支都写一个最小调用；类型检查器版本支持 PEP 742 的 TypeIs 语义。Python 3.15 预发布说明也提醒，预发布解释器不应直接承担生产环境风险，线上升级要单独做兼容性验证。

相关问题

TypeIs 是 Python 3.15 才新增的吗？

不是。PEP 742 标注的 Python 版本是 3.13，Python 3.15 项目只是可以直接使用它。更老的解释器可以通过 typing_extensions 评估兼容方案。

TypeGuard 的假分支为什么没有变窄？

这是 TypeGuard 的既定语义：真分支采用声明的目标类型，假分支不根据这个判断追加排除信息。需要双向收窄时，应评估 TypeIs。

TypeIs 能替代所有 TypeGuard 吗？

不能。TypeIs 要求输入类型与目标类型兼容；涉及不兼容的容器类型替换时，TypeGuard 仍然是合适工具。