TypeGuard 是向类型检查器声明“若函数返回 True，则参数必为指定类型”的机制，区别于普通类型断言：它不改变运行时行为，仅支持 if 分支内变量类型收窄，要求返回 bool 且注解为 TypeGuard[T]，参数宜用 object。
什么是 TypeGuard，它和普通类型断言有什么区别？
TypeGuard 不是告诉 Python “我相信这是某种类型”，而是向类型检查器（如 mypy、pyright）声明：“如果这个函数返回 True，那么传入参数一定满足指定类型”。它不改变运行时行为，只影响静态类型推导。
普通 assert isinstance(x, str) 或 cast(str, x) 无法让后续代码块自动获得更精确的类型；而 TypeGuard 函数能让 if 分支里的变量类型被真正收窄。
关键点：
- 必须返回
bool - 返回类型注解必须是
TypeGuard[T]，不能是bool或Union[bool, TypeGuard[T]] - 只能在函数定义层面使用，不能用于 lambda 或嵌套内部函数（mypy 当前不支持）
如何写一个合法的 TypeGuard 函数？
最简可用模板如下：
立即学习“Python免费学习笔记（深入）”；
from typing import TypeGuard <p>def is_nonempty_str(obj: object) -> TypeGuard[str]: return isinstance(obj, str) and len(obj) > 0
注意：
- 参数类型建议用
object（而非Any），否则类型检查器可能跳过收窄逻辑 - 不要加多余逻辑：比如在函数里修改全局状态、抛异常、或调用未标注类型的函数，这些不影响类型推导，但会让检查器困惑甚至报错
- mypy 0.990+ 和 pyright 1.1.300+ 才稳定支持
TypeGuard；旧版本会直接忽略该注解，且不报错，容易误以为生效了
为什么 if 分支里类型没变窄？常见失效场景
典型失效原因包括：
- 使用了错误的返回类型注解：
-> bool或-> TypeGuard[Any]都不会触发收窄 - 参数用了泛型或联合类型却没覆盖所有分支，例如：
def is_int_or_str(obj: int | str) -> TypeGuard[int]: # ❌ 错误：参数类型太窄，检查器无法反推 return isinstance(obj, int)
正确写法应是obj: object，再靠函数体逻辑判断 - 在类型检查器不支持的上下文中使用：比如作为字典 value 的 callable、赋值给变量后再调用（
guard = is_nonempty_str; if guard(x): ...），此时 mypy 无法跟踪类型守卫语义
配合 match 和协议类型时要注意什么？
Python 3.10 的 match 本身不理解 TypeGuard，所以不能指望模式匹配自动触发收窄。你仍需显式调用守卫函数：
def handle_data(data: object) -> str:
if is_nonempty_str(data):
return data.upper() # ✅ data 被推导为 str
elif isinstance(data, bytes):
return data.decode()
else:
return "unknown"
另外，TypeGuard 与 Protocol 组合没问题，但协议字段访问必须在守卫返回 True 后才安全：
class HasName(Protocol):
name: str
<p>def has_name_attr(obj: object) -> TypeGuard[HasName]:
return hasattr(obj, "name") and isinstance(getattr(obj, "name"), str)
这里要注意：仅靠 hasattr 不足以保证属性可读且类型正确，最好加上 getattr 类型检查，否则 pyright 可能仍报 HasName 访问不安全。
类型守卫真正起效的地方很具体：它只在紧邻的 if/elif 块中改变变量类型，跨作用域、异步回调、闭包引用都不可靠。别把它当成运行时类型转换工具——它只是给类型检查器递一张“可信凭证”。
