Python typing.TypeIs 怎样表达更精确的类型收窄

如果一个判断函数只是返回 bool，静态类型检查器通常不知道它对参数做了什么。Python 3.13 起，可以用 typing.TypeIs 把这个判断声明成类型谓词：返回 True 时，参数按“原类型与目标类型的交集”收窄；返回 False 时，参数会排除目标类型。关键是让函数的实际判断和标注保持一致。

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

最稳妥的写法是：参数先标成一个包含候选类型的联合类型，函数体用可靠的运行时判断返回布尔值，再用 TypeIs[目标类型] 描述这次判断。目标类型必须与输入类型相容，否则类型检查器可能报错，甚至得到不可靠的结论。

• True 分支：保留原来已知的信息，再与 TypeIs 的目标类型求交集。
• False 分支：从原类型中排除目标类型，适合继续处理剩余分支。
• 选择边界：如果目标类型不是输入类型的子类型，或 False 无法证明排除关系，应考虑 TypeGuard。

先确认 TypeIs 的输入与返回契约

TypeIs[T] 不是运行时转换器，也不会把对象变成 T。它只告诉静态类型检查器：这个函数至少接收一个位置参数，运行时应返回布尔值，返回值的真假对应一条类型谓词规则。Python 本身不会强制执行注解，所以错误的谓词实现仍然可能运行，但会误导后续类型分析。

因此，输入参数应该先覆盖所有可能值，目标类型则应该是输入类型中可以被可靠识别的一部分。比如 object 到 str 很自然；而把互不相容的输入和目标类型硬写在一起，就不适合用 TypeIs。

用 isinstance 实现一个安全的 TypeIs 谓词

下面的例子把一条消息先看作 str | bytes，再封装一个判断字符串的函数。代码中的 TypeIs[str] 表达的是“如果返回 True，调用方可以把原参数中的字符串部分拿出来继续使用”。

from typing import TypeIs, assert_type

def is_text(value: str | bytes) -> TypeIs[str]:
    # isinstance 同时承担运行时判断和类型谓词的事实来源
    return isinstance(value, str)

def consume(value: str | bytes) -> None:
    if is_text(value):
        # True 分支中，value 被收窄为 str
        assert_type(value, str)
        print(value.casefold())
    else:
        # False 分支中，value 被排除 str，只剩 bytes
        assert_type(value, bytes)
        print(value.decode("utf-8"))

这里没有做转换，也没有依赖断言改变运行时对象。is_text 只负责给出事实，assert_type 用于让类型检查器明确检查推断结果；生产代码可以保留判断函数而不保留断言。

分别观察 True 和 False 分支

TypeIs 的价值不只在于 True 分支。假设参数原本是 Child | Unrelated，谓词判断它是否属于 Parent。如果 Child 继承 Parent，True 分支的交集仍然是 Child；False 分支则排除了 Parent，剩下的就是 Unrelated。

这种“正向识别 + 反向排除”适合拆分消息处理、解析结果或对象分派逻辑。排查收窄不生效时，按三项检查：谓词是否真的返回布尔值；目标类型是否与参数类型相容；False 分支是否确实意味着目标类型不存在。如果任一项不成立，静态结论就不应写得过强。

TypeIs 和 TypeGuard 怎么选

两者都用于用户自定义类型谓词，但规则不同。TypeIs 要求被收窄类型是输入类型的子类型，并且 False 分支可以排除该类型；它会结合原先已知类型做交集。TypeGuard 在 True 分支直接把变量视为标注的目标类型，允许例如 list[object] 判断成 list[str] 这种并非子类型的关系，但 False 分支不会进一步收窄。

可以把选择规则记成一句话：判断的是同一个对象在原类型集合中的更窄成员，用 TypeIs；需要把一个容器或结构按自定义规则解释成不具备子类型关系的目标类型，用 TypeGuard，并承担实现正确性的责任。

常见问题

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

不会。它只是返回类型标注，运行时仍由函数体决定结果；真正的转换要显式写在业务代码中。

为什么 TypeIs 的目标类型不能随便写？

因为静态检查器会据此推断 True 与 False 两条路径。目标类型与参数类型不相容，或者函数并不能覆盖目标类型的全部实例，就可能产生不可靠的类型结论。

Python 3.12 及更早版本怎么办？

TypeIs 在标准库中自 Python 3.13 加入。需要兼容更早版本时，应根据项目的类型检查器和依赖策略评估 typing_extensions 的回移实现，并在支持范围内测试实际推断行为。