Python TypeIs 和 TypeGuard 怎么选：类型收窄、运行时判断与静态检查边界

接口层有一个“只接受字符串”的输入校验函数，运行时返回值一直没问题，真正让人困惑的是：同样写成 is_text(value)，换成 TypeIs[str] 后，类型检查器在两个分支里都能继续推理；换成 TypeGuard[str]，通常只有成功分支会变窄。选择并不是新旧写法之争，而是要看目标类型是否真的是输入类型的子类型，以及失败分支有没有排除信息。

先把“返回布尔值”和“类型收窄”分开

TypeIs 和 TypeGuard 不会替你做运行时校验。它们是返回值标注，告诉静态分析工具：这个函数返回 True 时，调用方可以把参数当成什么类型处理。下面的判断仍由代码自己完成。

from typing import TypeIs

def is_text(value: object) -> TypeIs[str]:
    return isinstance(value, str)

value: str | int = 42
if is_text(value):
    print(value.upper())
else:
    print(value + 1)

在这个例子里，输入是 str | int，目标是 str。True 分支可以看作字符串，False 分支则排除了字符串，只剩整数。这个“反向也有信息”的特性，正是 TypeIs 和普通 bool 函数最明显的差别。

TypeIs 的边界：目标类型必须和输入类型相容

TypeIs 的目标类型需要是输入类型的子类型，静态检查器才有依据把它理解成交集。更重要的是，函数必须对每一个目标类型实例都返回 True；如果谓词漏掉了其中一部分，标注就会把错误信息传给后续代码。

例如输入是 str | bytes | None，下面的写法能让两个分支都得到合理结论：

from typing import TypeIs

def is_text(value: str | bytes | None) -> TypeIs[str]:
    return isinstance(value, str)

payload: str | bytes | None = get_payload()
if is_text(payload):
    print(payload.strip())       # str
else:
    print(payload is None)       # bytes | None

这里别急着把所有旧的 TypeGuard 都替换掉。若输入声明为 object，目标是 str，通常也符合子类型关系；但如果谓词的真实逻辑只覆盖了带某种字段的字符串，返回类型就不能简单写成全部 str。

为什么 list[object] 到 list[str] 仍然要用 TypeGuard

Python 的泛型容器通常具有不变性。虽然 str 是 object 的子类型，但 list[str] 不是 list[object] 的子类型：如果允许这种替换，调用方就可能把整数写进原本只允许字符串的列表。

这时 TypeGuard 的表达能力更合适：

from typing import TypeGuard

def is_text_list(value: list[object]) -> TypeGuard[list[str]]:
    return all(isinstance(item, str) for item in value)

items: list[object] = ["a", "b"]
if is_text_list(items):
    print("-".join(items))

TypeGuard 告诉检查器：True 时可以把变量当成标注里的完整类型。它不要求目标类型是输入类型的子类型，因此能覆盖这种“运行时确认元素类型、静态类型却不协变”的场景。代价是 False 分支不会自动变成“不是 list[str]”，因为这对不变容器并不安全。

从旧标注迁移时，按三个问题做判断

1. 目标是不是输入的子类型？ 是，优先评估 TypeIs；不是，保留 TypeGuard。
2. False 是否能证明排除目标类型？ 如果函数只做部分检查，不能为了获得反向收窄而硬改成 TypeIs。
3. 项目运行环境能否导入它？ TypeIs 在 Python 3.13 加入标准库，较老版本需要评估 typing_extensions 和检查器版本。

让静态检查结果成为迁移验收的一部分

先在代码中替换一处小谓词，再分别运行项目已经使用的检查器。不要只看编辑器是否出现红线：把 True 和 False 两条路径都保留一个会触发类型错误的操作，才能确认收窄方向真的符合预期。运行时测试则继续覆盖空值、错误元素和混合列表，类型标注不能代替这些测试。

# 例如在项目虚拟环境中执行
python -m mypy src
python -m pytest tests/test_predicates.py

如果项目仍支持 Python 3.12 及更早版本，先确认兼容导入策略，再提交批量改动。迁移的安全边界不是“能不能 import”，而是开发机、CI 和生产环境的解释器与静态检查器是否一致。

相关问题

TypeIs 会在运行时自动检查返回值吗？

不会。它只是类型标注，函数仍应返回布尔值，参数检查和异常处理必须由函数实现。

TypeGuard 的 False 分支为什么不收窄？

因为目标类型可能不是输入类型的子类型，尤其是泛型不变时，False 并不能安全推出一个可用的排除类型。

只用 isinstance 时还需要 TypeIs 吗？

如果判断只出现一次，直接使用 isinstance 已经足够；当同一谓词跨函数复用并希望检查器理解两个分支时，TypeIs 才更有价值。

迁移清单

• 确认谓词的 True/False 语义覆盖完整目标类型。
• 确认目标类型与输入类型的子类型关系，特别是 list 等不变容器。
• 同时跑静态检查和运行时测试，并固定 CI 使用的 Python 与检查器版本。