Python 第三方库：typeguard（运行时类型检查工具）

摘要：typeguard 是一个用于运行时类型检查（Runtime Type Checking）的 Python 库。它可以在程序运行期间自动检查函数参数和返回值是否符合类型注解（PEP 484），从而帮助开发者发现类型错误、提高代码健壮性。

typeguard 是一个用于运行时类型检查（Runtime Type Checking）的 Python 库。它可以在程序运行期间自动检查函数参数和返回值是否符合类型注解（PEP 484），从而帮助开发者发现类型错误、提高代码健壮性。

与这类静态类型检查器不同，typeguard 是动态检查工具，可直接嵌入生产代码中运行。

安装：

pip install typeguard

如果你使用 Python 3.12+，推荐安装支持新语法的版本：

pip install "typeguard>=4"

常见应用场景：

（1）检查函数参数是否与类型注解一致（如 str、int、List[float]）。

（2）检查函数的返回值是否符合类型注解。

（3）检查类方法或属性赋值的类型一致性。

（4）与测试工具集成（如）进行测试时的类型约束。

（5）辅助大型团队开发中的类型约定落实。

◆ ◆ ◆

核心概念

1、类型注解 ≠ 类型约束

Python 本身的类型注解不会自动执行类型检查，仅供 IDE 或工具使用。

而 typeguard 则能在运行时实际拦截并验证类型是否正确。

2、运行时检查方式

使用 @typechecked 装饰器或启用自动检查机制，typeguard 会在函数调用时验证：

所有参数是否符合注解类型。

返回值是否符合注解类型。

3、与标准类型系统兼容

兼容 typing 和 Python 的类型提示，如 Optional[str]、List[int]、Union[str, None]、Literal 等。

◆ ◆ ◆

应用举例

例 1：基本函数类型检查

from typeguard import typechecked@typecheckeddef greet(name: str, age: int) -> str:return f"{name} is {age} years old."greet("Alice", 30) # 正常greet("Bob", "thirty") # 报错：TypeError: type of argument "age" must be int

例 2：自动检测所有模块函数（推荐用于开发调试）

在模块入口或测试环境中添加：

from typeguard.importhook import install_import_hookinstall_import_hook('your_module_name') # 自动检查模块中所有函数类型

这样无需手动为每个函数添加装饰器。

例 3：检查返回值类型

from typeguard import typechecked@typecheckeddef square(x: int) -> int:return x * xprint(square(5)) # 正常print(square(5.5)) # 报错：参数类型错误

例 4：类方法检查

from typeguard import typechecked@typecheckedclass User:def __init__(self, name: str, age: int):self.name = nameself.age = agedef birthday(self) -> None:self.age += 1

例 5：pytest 集成

安装：

pip install pytest-typeguard

使用：

pytest --typeguard-packages=my_package

在测试过程中会自动检查函数类型一致性。

◆ ◆ ◆

常用 API 与方法

@typechecked

为函数或类启用类型检查。

@typecheckeddef func(x: int) -> str:...

check_argument_types