Python typing.TypeIs 如何帮助类型检查器收窄类型

如果一个函数只是返回 True 或 False，类型检查器通常不会自动知道它还承担了“类型判断”的职责。typing.TypeIs 就是为这个场景准备的：把函数返回值标记为类型谓词后，if 分支会取原类型与目标类型的交集，else 分支则排除目标类型。Python 3.13 起可从标准库 typing 导入；需要兼容更早版本时，可使用 typing_extensions 的对应回移实现。

从 TypeGuard 迁移到 TypeIs，先看兼容范围

TypeIs 是类型系统提示，不会在运行时替你检查类型，也不会把普通布尔函数变成运行时验证器。它的价值在于告诉 mypy、pyright 等检查器：这个布尔结果与第一个参数的类型有关。

from typing import TypeIs

class Message:
    pass

class TextMessage(Message):
    def __init__(self, text: str) -> None:
        self.text = text

def is_text_message(value: Message) -> TypeIs[TextMessage]:
    # 返回值必须是 bool；这里的运行时判断仍由 isinstance 完成
    return isinstance(value, TextMessage)

def render(value: Message) -> str:
    if is_text_message(value):
        # 类型检查器可把 value 当成 TextMessage
        return value.text
    # 这里仍是 Message，但已经排除了 TextMessage
    return "其他消息"

迁移前先检查三件事：项目解释器是否为 Python 3.13 或更高、所用检查器是否支持 PEP 742 语义、目标类型是否是输入类型的兼容收窄。只升级导入语句而不升级检查器，编辑器可能仍不显示预期结果。

正向与反向分支为什么都能收窄

假设参数是 TextMessage | ImageMessage，谓词返回 TypeIs[TextMessage]。调用结果为真时，变量留下 TextMessage；结果为假时，检查器可以把 TextMessage 从联合类型中排除，留下 ImageMessage。这正是它比只保证正向分支的 TypeGuard 更直观的地方。

from typing import TypeIs

class ImageMessage(Message):
    width: int

def show(value: TextMessage | ImageMessage) -> str:
    if is_text_message(value):
        # 真分支只保留 TextMessage
        return value.text
    # 假分支排除 TextMessage，剩下 ImageMessage
    return f"{value.width}px 图片"

自定义谓词要对自己的返回结果负责：如果函数错误地返回了 True，静态检查器仍会相信标注。类型谓词不是权限校验或数据清洗的替代品，外部输入仍要做真实的运行时验证。

列表场景不要把 TypeIs 当成 TypeGuard

最容易误迁移的是容器类型。list 通常具有不变性，list[str] 并不是 list[object] 的子类型。因此下面这种“检查列表内每个元素，再把容器改看成字符串列表”的函数，不适合直接写成 TypeIs[list[str]]：

from typing import TypeGuard

def is_string_list(value: list[object]) -> TypeGuard[list[str]]:
    # TypeGuard 允许目标类型不是输入类型的子类型
    return all(isinstance(item, str) for item in value)

如果目标类型确实是输入类型的兼容子类型，再考虑 TypeIs；否则继续用 TypeGuard，不要为了让否定分支也收窄而牺牲类型安全。

回归检查和迁移清单

迁移完成后，用项目实际检查器验证推断，而不是只看代码能否运行。可以在小范围示例里加入 assert_type，或使用检查器的 reveal_type 输出确认真、假两个分支。

• 导入路径：Python 3.13+ 使用 typing.TypeIs，旧解释器锁定 typing_extensions 版本。
• 签名关系：输入参数至少有一个位置参数，目标类型与参数类型兼容。
• 返回契约：所有路径返回真正的 bool，不要返回 truthy 对象。
• 分支回归：同时检查正向、反向和 if not 三种写法。

常见问题

TypeIs 会在运行时自动把对象转换成目标类型吗？

不会。它只帮助静态类型检查器收窄表达式；实际判断仍由函数体执行，数据转换也必须显式完成。

TypeIs 和 TypeGuard 可以互换吗？

不能。TypeIs 要求目标类型与输入类型兼容，并能利用假分支排除信息；容器不变性等场景仍适合 TypeGuard。

为什么编辑器没有显示收窄结果？

先检查 Python 解释器、检查器版本和导入来源，再用最小示例查看 reveal_type。运行时版本正确不等于编辑器已经支持对应类型规范。