typing TypeIs 怎样标注类型收窄

我第一次把一个复杂的 isinstance() 判断抽成公共函数时，函数本身返回的是 bool，但类型检查器并不知道这个布尔值代表什么。调用方进入分支后仍然只能看到原来的联合类型。这个场景正适合 typing.TypeIs：它把“这个判断函数在什么条件下成立”写进返回注解。

官方文档：https://docs.python.org/3/library/typing.html#typing.TypeIs

TypeIs 的关键写法是 def predicate(value: Input) -> TypeIs[Narrowed]: ...。函数运行时仍应返回真正的布尔值，收窄只由静态类型检查器根据这个契约推导；Python 运行时不会替你检查注解是否写对。

先把类型谓词的契约写完整

下面的例子把输入声明成 object，因为调用方可能传入任何对象；谓词只承诺“返回 True 时，它是 Payload”。为了让这个承诺可信，函数体里的运行时判断也要和返回注解一致。

from typing import TypeIs


class Payload:
    # 业务载荷只保留示例所需的字段。
    def __init__(self, body: str) -> None:
        self.body = body


def is_payload(value: object) -> TypeIs[Payload]:
    # isinstance 同时承担运行时检查和类型谓词的事实来源。
    return isinstance(value, Payload)


def consume(value: object) -> str:
    if is_payload(value):
        # True 分支中，检查器可把 value 收窄为 Payload。
        return value.body
    # 未通过检查时不能访问 Payload 专属字段。
    return "忽略非载荷对象"

这里最容易漏掉的是输入类型。TypeIs[Payload] 不是“把任意值强制转换成 Payload”，而是声明一个可被检查器利用的事实。函数仍要返回 True 或 False，也不应在函数体里为了让检查器满意而使用不安全的强制转换。

True 分支得到的是交集，而不是盲目替换

TypeIs 的 True 语义可以理解为“原来已知的类型”与“谓词声明的类型”取交集。对于 Child | Unrelated 这样的联合类型，如果谓词判断目标是 Parent，而 Child 继承自 Parent，True 分支最终仍可精确到 Child，因为它同时满足两个条件。

from typing import TypeIs, assert_type


class Parent:
    # 父类作为收窄目标的共同边界。
    pass


class Child(Parent):
    # Child 继承 Parent，便于观察交集收窄。
    pass


class Unrelated:
    # 与 Parent 无关的类型留在 False 分支。
    pass


def is_parent(value: object) -> TypeIs[Parent]:
    # 只有真实的 Parent 实例才报告 True。
    return isinstance(value, Parent)


def handle(value: Child | Unrelated) -> None:
    if is_parent(value):
        # 原类型 Child 与 Parent 的交集仍然是 Child。
        assert_type(value, Child)
    else:
        # False 分支排除 Parent，剩下 Unrelated。
        assert_type(value, Unrelated)

这也是 TypeIs 比“返回普通 bool”更有价值的地方：调用者不需要在每个位置重复同一套类型判断，分支信息可以沿着控制流继续传递。但谓词返回值代表的是静态契约，不是运行时转换；对象不会因为注解改变类层次。

False 分支也会排除目标类型

使用 TypeGuard 时，通常只有 True 分支获得特殊收窄，False 分支仍保留原类型。TypeIs 的另一个重要语义是：如果结果为 False，检查器可以从原类型中排除 NarrowedType。因此它适合表达“是/不是同一类型层次中的成员”这种双向判断。

这个语义要求谓词足够可靠：如果函数在某些真正属于 Payload 的对象上错误返回 False，调用方就可能得到不 sound 的静态结论。复杂业务条件要谨慎命名，最好让返回 True 的条件确实覆盖目标类型，而不是只检查一个偶然字段。

什么时候不能直接写 TypeIs

官方规则要求 TypeIs 中的收窄类型与函数参数类型保持一致，通常意味着目标类型应是输入类型的子类型。比如把 list[object] 判断成 list[str] 时，列表是不变的，list[str] 不是 list[object] 的子类型，这类“结构更具体但并非子类型”的场景更适合 TypeGuard。

from typing import TypeGuard


def is_string_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_string_list(value):
        # TypeGuard 允许从 list[object] 直接得到 list[str]。
        return ",".join(value)
    # 检查失败时保留原始列表类型。
    return "存在非字符串元素"

可以用三个问题做收尾检查：函数是否在运行时返回布尔值；True 时目标类型是否确实与输入类型相容；False 时是否真的能排除目标类型。如果第二个问题答不上来，不要为了获得更窄的提示而硬套 TypeIs。

常见问题

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

不会。它是给静态类型检查器看的返回注解，函数体仍要自行完成运行时判断。

TypeIs 和 TypeGuard 最核心的区别是什么？

TypeIs 要求收窄类型与输入类型兼容，并支持 True 取交集、False 排除；TypeGuard 对输入和目标类型的关系更宽松，但 False 分支通常不会因此变窄。

对我来说，TypeIs 最值得保留的不是少写几行 isinstance()，而是把公共判断函数的安全边界显式交给类型系统。只要谓词事实可靠、输入输出类型相容，它就能让调用方的两个分支都保持清晰；遇到不满足子类型关系的容器检查，再退回 TypeGuard 会更稳妥。