TypeGuard仅用于静态类型检查，不执行运行时验证；必须手动实现运行时校验逻辑，或借助pydantic、beartype等第三方库。

如何在python 3.10中利用typeguard增强模块的类型检查_编写运行时验证函数

TypeGuard 不是运行时验证函数，它只是告诉类型检查器“这个值满足某个类型条件”——仅影响静态类型检查，不执行任何实际校验。想做运行时验证，必须额外写代码或借助第三方库。

为什么 `TypeGuard` 本身不做运行时检查

TypeGuard 是一个类型提示工具，定义在 typing 模块中（Python 3.10+），本质是 Callable[..., bool] 的子类型。它的唯一作用是让类型检查器（如 mypy、pyright）在 if 分支中收窄变量类型。

调用一个标注了 TypeGuard[T] 的函数，返回 True，类型检查器就认为当前作用域中的参数变量是 T
函数体内部不做强制约束：你可以 return True 即使数据根本不合法
运行时完全忽略 TypeGuard —— 它不抛异常、不打印警告、不修改输入

如何正确组合 `TypeGuard` 和运行时验证

典型做法是：写一个普通函数做真实校验，再用 TypeGuard 标注它，让类型检查器和运行时行为保持一致。

from typing import TypeGuard, Any
<p>def is_positive_int(obj: Any) -> TypeGuard[int]:</p><div class="aritcle_card flexRow artxards">
											<div class="artcardd flexRow">
												<a class="aritcle_card_img" rel="nofollow" href="/xiazai/skill6591" title="Li Python Sec Check"><img
														src="https://img.php.cn/upload/skill/000/000/081/179102166033725.jpg" alt="Li Python Sec Check" onerror="this.onerror='';this.src='/static/lhimages/moren/morentu.png'" ></a>
												<div class="aritcle_card_info flexColumn">
													<a rel="nofollow" href="/xiazai/skill6591" title="Li Python Sec Check" class="overflowclass">Li Python Sec Check</a>
													<p class="overflowclass">Python 安全规范检查工具：基于 CloudBase 规范、腾讯安全指南，LLM 智能分析（默认禁用，优先本地执行）</p>
												</div>
												<a rel="nofollow" href="/xiazai/skill6591" title="Li Python Sec Check" class="aritcle_card_btn flexRow flexcenter"><b></b><span>下载</span>
												</a>
											</div>
										</div><h1>这里必须手动实现运行时判断</h1><pre class="brush:php;toolbar:false;">if isinstance(obj, int) and obj > 0:
    return True
return False

使用示例

def process_count(x: Any) -> str: if is_positive_int(x): # 类型检查器此时认为 x 是 int return f"got {x * 2}" # ✅ 不报错 return "invalid"

函数名要体现语义（如 is_...、is_valid_...），避免误导
务必在函数体内做完整运行时判断，不能只靠 TypeGuard 注解“假装安全”
注意 Any 输入类型：若用更窄类型（如 object 或 Union[int, str]），可能限制调用灵活性

常见错误：把 `TypeGuard` 当成断言或装饰器

以下写法看似简洁，实则危险：

# ❌ 错误：TypeGuard 不会触发运行时检查
def bad_is_list_of_str(obj: Any) -> TypeGuard[list[str]]:
    return isinstance(obj, list)
<h1>❌ 更糟：用装饰器包装 TypeGuard？无效且易混淆</h1><p>from typing import TypeGuard, Callable, Any
def runtime_check(f: Callable[..., bool]) -> Callable[..., TypeGuard[Any]]:
return f  # 这个装饰器对类型检查器和运行时都无实质作用
</p>