Python typing.TypeGuard 怎么让检查函数收窄集合类型

你可能已经写了一个函数，运行时用 isinstance 检查列表里的每个元素都是字符串，但 mypy 或 pyright 仍把它看成 list[object]。原因不在检查逻辑，而在返回值只写成了普通 bool：类型检查器不知道“返回 True”还代表输入集合满足了什么类型条件。把返回值改成 TypeGuard[list[str]]，就能把这个运行时事实传递给静态分析。

一、先看问题现场：bool 不会替类型检查器收窄

先看一个看似足够清楚的普通函数。它的运行时结果没问题，但调用方得到的只是一个布尔值。

from collections.abc import Iterable

def is_text_list(value: list[object]) -> bool:
    # 运行时逐项确认，结果只暴露为普通 bool
    return all(isinstance(item, str) for item in value)

def join_names(value: list[object]) -> str:
    if is_text_list(value):
        # 类型检查器仍可能认为 value 是 list[object]
        return ", ".join(value)
    return ""

str.join 需要字符串元素，而 object 可能是任意对象。普通 bool 函数没有告诉检查器成功条件对应的目标类型，所以它不会替你修改 value 的静态类型。

二、最小 TypeGuard 配方：把承诺写在返回值

把返回注解换成 TypeGuard[list[str]]。这里的重点不是给函数加一个更复杂的装饰器，而是把“检查成功后，首个参数可当作什么类型”写成类型契约。

from typing import TypeGuard

def is_text_list(value: list[object]) -> TypeGuard[list[str]]:
    # 所有元素都通过检查，才承诺这是字符串列表
    return all(isinstance(item, str) for item in value)

def join_names(value: list[object]) -> str:
    if is_text_list(value):
        # True 分支中，检查器按 list[str] 处理 value
        return ", ".join(value)
    return "未通过字符串列表检查"

PEP 647 规定，类型检查器会把 TypeGuard 调用的第一个位置参数应用这个收窄类型；方法则对应去掉 self 或 cls 后的第一个业务参数。函数仍然需要在运行时返回真正的布尔值，TypeGuard 不是运行时转换器。

三、集合收窄的边界：真分支精确替换，假分支不反推

这个例子有一个容易被忽略的类型学细节：list 默认是不变的，list[str] 不是 list[object] 的子类型。TypeGuard 允许检查器在 True 分支直接采用返回类型，因此能表达“逐元素验证后，这个具体列表可以按字符串列表使用”。

因此，不要在 else 中写“既然不是字符串列表，那每个元素就一定不是字符串”。列表可能只是混合类型，也可能因为某个元素不符合条件而失败。检查器保留原类型，是为了避免这种错误推断。

四、把检查函数放进真实数据入口

TypeGuard 最适合放在不可信数据进入业务函数的边界，例如 JSON 配置解析后、表单字段整理后或插件返回值进入核心逻辑前。空集合尤其要先定规则：数学上的 all([]) 为真，但业务上可能要求至少有一个名称。

from typing import TypeGuard

def is_non_empty_text_list(value: object) -> TypeGuard[list[str]]:
    # 先检查容器，再检查每个元素；同时拒绝空列表
    return (
        isinstance(value, list)
        and bool(value)
        and all(isinstance(item, str) for item in value)
    )

def render_labels(raw: object) -> str:
    if not is_non_empty_text_list(raw):
        # 失败路径保留兜底，不把未知数据强行当成字符串列表
        return "暂无可展示标签"
    return " / ".join(raw)

如果数据在检查后还会被别的代码原地修改，类型承诺的有效期就会变短。对配置或外部输入，可以在边界处复制后再传递；对共享可变列表，则应把“检查”和“消费”安排在相近位置，不要把 TypeGuard 当成永久不变的运行时证明。

五、常见问题：TypeGuard、TypeIs 与普通 bool 怎么选

TypeGuard 和 TypeIs 最大的区别是什么？

TypeGuard 在 True 分支把参数精确看作括号里的类型，而且这个类型不必是输入类型的子类型；TypeIs 要求更严格的一致性，并能在 False 分支排除目标类型。处理 list[object] 到 list[str] 这类不变容器时，TypeGuard 更贴合这个需求。

检查函数可以接收多个参数吗？

可以，但默认只有第一个位置参数会被收窄，其他参数只是辅助条件。把关键待收窄对象放在第一个参数，并让返回注解准确描述它。

为什么不直接返回 bool 再写注释？

注释只能帮助人阅读，不能稳定地成为类型检查器的控制流契约。若函数确实承担“判断后提供更具体类型”的职责，直接用 TypeGuard 表达意图更清楚；如果只关心真假，不需要收窄，就继续使用普通 bool。