Python typing 怎样用 TypeIs 缩小类型

如果一个函数的参数可能是字符串、整数或某个基类对象，直接在每个调用点重复 isinstance()，很快就会出现判断逻辑不一致的问题。Python 的 typing.TypeIs 可以把这种判断封装成可复用函数：返回 True 时缩小到目标类型，返回 False 时排除目标类型。

官方文档入口：https://docs.python.org/3.14/library/typing.html

下面只围绕一个边界展开：如何让类型检查器理解“这个布尔函数判断了什么”，以及怎样避免把写得不完整的判断函数变成错误的类型承诺。

先把 TypeIs 的两条分支说清楚

最小例子是判断一个对象是否为字符串。输入类型是 object，目标类型是 str；两者兼容，所以适合用 TypeIs[str] 表达。

from typing import TypeIs


def is_text(value: object) -> TypeIs[str]:
    # 判断必须覆盖所有字符串；其他对象返回 False。
    return isinstance(value, str)


def render(value: str | int) -> str:
    # True 分支中，检查器可把 value 当作 str。
    if is_text(value):
        return value.strip()

    # False 分支排除 str；对这个联合类型来说只剩 int。
    return str(value + 1)

运行时它仍然只是一个返回布尔值的普通函数，Python 不会因为返回类型写成 TypeIs 就自动检查对象。变化发生在静态分析阶段：在已知输入为 str | int 时，if 分支可以按字符串处理，else 分支可以按整数处理。

这里的“排除”依赖调用点原来已知的类型。如果调用参数只是 object，False 分支不可能凭空变成某个具体剩余类型；它只能比调用前更准确地排除目标类型。

把判断函数写成“完整的类型断言”

TypeIs 最重要的约束不是语法，而是函数的真假含义。返回 True 时，参数必须确实兼容目标类型；返回 False 时，不能把仍然可能属于目标类型的值排除掉。

例如，下面的函数把“正整数”误写成了 TypeIs[int]：

from typing import TypeIs


def is_positive_number(value: object) -> TypeIs[int]:
    # 这个条件会把 0 和负整数错误地判成 False。
    return isinstance(value, int) and value > 0

它的返回值虽然是布尔值，但类型承诺不完整：0 明明是 int，函数却返回 False。类型检查器通常不会替你证明函数体与 TypeIs 之间的逻辑等价关系，调用方可能因此得到不可靠的窄化结论。

如果业务真正需要的是“是否为正整数”，可以把目标概念建模成单独的值对象，或者保留普通的 bool 返回值，再在分支内部显式做值校验。不要为了让编辑器提示更具体，就把值域条件伪装成类型判断。

按 Python 版本选择导入路径

TypeIs 是 Python 3.13 引入的标准类型构造。面向 Python 3.13 及更高版本时，可以直接从 typing 导入；需要兼容更早版本时，项目通常会从 typing_extensions 获取兼容实现，具体还要看静态检查器和依赖版本。

import sys

if sys.version_info >= (3, 13):
    from typing import TypeIs
else:
    # 旧解释器使用兼容包，项目需把它写入依赖声明。
    from typing_extensions import TypeIs


def is_mapping(value: object) -> TypeIs[dict[str, object]]:
    # 只检查运行时可表达的结构；不要声称已验证每个值的业务格式。
    return isinstance(value, dict)

版本分支只解决“名字从哪里来”，不会替你解决类型检查器是否支持 TypeIs。团队应在目标 Python 版本、检查器版本和 CI 配置中统一约定，避免本地编辑器能收窄、CI 却把同一注解当成未知类型。

TypeIs 和 TypeGuard 不是同一个开关

两者都可以把用户定义的布尔函数接入类型收窄，但语义不同。TypeIs 要求目标类型与输入类型兼容，并且在 False 分支也能排除目标类型；TypeGuard 可以表达更宽松的“通过后把它看成某个类型”，False 分支通常不会获得同样的排除效果。

from typing import TypeGuard, TypeIs


def is_text_with_typeis(value: object) -> TypeIs[str]:
    # 完整判断字符串，正反分支都具有清晰含义。
    return isinstance(value, str)


def looks_like_int_list(value: list[object]) -> TypeGuard[list[int]]:
    # list 具有不变性；这里表达的是“检查通过后按 int 列表使用”。
    return all(isinstance(item, int) for item in value)


def choose(value: str | int) -> str:
    # TypeIs 的 False 分支可排除 str，剩下 int。
    if is_text_with_typeis(value):
        return value
    return str(value)


def accept(values: list[object]) -> int:
    # TypeGuard 的目标是不可直接用 TypeIs 表达的列表元素收窄。
    if looks_like_int_list(values):
        return sum(values)
    return 0

这里不是说 TypeGuard 更强，而是它允许的场景不同。list[object] 到 list[int] 涉及可变容器的不变性，不能简单套用 TypeIs 的兼容要求；如果只是把 object、str | int 这样的联合类型拆开，TypeIs 通常更接近 isinstance() 的直觉。

用 assert_type 和测试守住调用边界

类型收窄是静态分析结果，不是运行时验证。对关键的公共函数，可以在类型检查专用测试中使用 assert_type() 或 reveal_type()，同时为判断函数补充边界值测试。

from typing import assert_type, TypeIs


def is_str(value: object) -> TypeIs[str]:
    # 返回值只表达运行时类型判断，不检查字符串业务内容。
    return isinstance(value, str)


def handle(value: str | int) -> None:
    if is_str(value):
        # 静态检查器应把这里识别为 str。
        assert_type(value, str)
        print(value.casefold())
    else:
        # 对 str | int，排除 str 后应剩下 int。
        assert_type(value, int)
        print(value + 1)

测试时至少覆盖目标类型、其他联合成员、None、空容器和自定义子类等输入。若判断函数读取了可变对象的状态，还要考虑“检查之后对象被修改”的时间间隔；类型检查器不会替你锁住运行时对象。

为什么 False 分支没有缩小？先看调用点的原始类型是否足够具体。如果输入只是 object，排除 str 后仍然有大量可能类型；这不是 TypeIs 失效。

TypeIs 能把 list[object] 直接变成 list[int] 吗？通常不能按 TypeIs 的兼容要求直接表达。可变列表的不变性是关键边界，应该重新设计输入抽象或评估 TypeGuard 的适用性。

TypeIs 会在运行时阻止错误对象进入函数吗？不会。它提供给类型检查器的是一个由开发者负责兑现的逻辑承诺，运行时仍需由函数体和测试保证行为正确。

落地时可以按这个顺序判断：先确认目标是不是完整的类型判断，再确认目标类型是否兼容输入，最后决定是否需要 TypeIs 的反向收窄。只要条件其实是在检查“值是否满足某个范围”，就不要把它包装成过度承诺的 TypeIs。