Python 库手册：warnings 警告信息模块

Python 的 warnings 模块用于发出警告信息而不中断程序运行，是一种比异常（raise）更温和的提示方式。通过它，开发者可以提示用户潜在问题、不推荐使用的接口（deprecated）、未来将移除的特性等，同时保留程序的正常执行流程。

常见应用场景：

（1）提醒用户注意代码中的非致命问题。

（2）标记已废弃但仍可用的函数或方法。

（3）替代调试语句（如 print）发出开发提示。

（4）运行时检测配置不当、参数不规范等问题。

（5）框架/库开发者用于发出 API 使用警告。

◆ ◆ ◆

核心概念

1、警告类型（Warning Classes）

所有警告均继承自 Warning 类，常见的子类包括：

Warning：所有警告的基类。

UserWarning：用户代码触发的通用警告。

DeprecationWarning：表示某功能已弃用，将来会删除。

SyntaxWarning：语法层面的问题。

RuntimeWarning：运行时可疑行为。

FutureWarning：表示未来行为会更改。

ImportWarning：模块导入相关警告。

ResourceWarning：资源使用（如文件、socket）相关问题。

2. 警告过滤器（Warning Filter）

警告信息的输出行为（是否显示、忽略、提升为异常）由过滤器规则控制，可通过：

代码设置（如 warnings.filterwarnings(...)）

环境变量（如 PYTHONWARNINGS=ignore）

命令行参数（如 python -W ignore script.py）

◆ ◆ ◆

应用举例

例 1：基本用法，发出一条用户警告

import warnings

def unsafe_func():
    warnings.warn("这是一个不建议使用的函数", UserWarning)

unsafe_func()

例 2：标记函数为已弃用（DeprecationWarning）

import warnings

def old_function():
    warnings.warn("该函数已弃用，请改用 new_function()", DeprecationWarning)

old_function()  # 默认不会显示 DeprecationWarning

注意：DeprecationWarning 默认不会在普通用户代码中显示，建议开发时通过如下方式强制显示。

import warnings
warnings.simplefilter("always", DeprecationWarning)

例 3：将警告提升为异常（调试用）

import warnings

warnings.simplefilter("error")  # 所有警告都变为异常

try:
    warnings.warn("将警告作为异常处理")
except Warning as e:
    print("捕获到异常：", e)

例 4：临时抑制警告（上下文管理器）

import warnings

with warnings.catch_warnings():
    warnings.simplefilter("ignore")  # 忽略本块内的警告
    warnings.warn("这条警告不会显示")

例 5：查看当前的警告过滤规则

import warnings

print(warnings.filters)

◆ ◆ ◆

常用函数速览

catch_warnings(record=False)

上下文管理器，用于临时更改警告行为。

参数：

record：若为 True，返回警告记录列表

返回：上下文管理器对象

filterwarnings(action, category=Warning, module='', lineno=0, append=False)

添加或更新一个警告过滤规则。

参数：

action：控制行为（如 "ignore", "always", "error"）

category：警告类型（如 UserWarning）

module：过滤指定模块

lineno：过滤指定代码行

append：是否将规则追加（默认插入到最前）

返回：无

formatwarning(message, category, filename, lineno, line=None)

格式化警告信息为字符串（用于自定义输出）。

参数：警告内容、类型、文件、行号等

返回：格式化字符串

resetwarnings()

清空所有用户设置的警告过滤器

返回：无

showwarning(message, category, filename, lineno, file=None, line=None)

输出警告（可重定义以重定向输出）。

返回：无

备注：可重写该函数来自定义打印行为

simplefilter(action, category=Warning)

设置全局过滤器（简单快捷）。

参数：

action："ignore"、"default"、"always"、"error" 等

category：警告类型

返回：无

warn(message, category=None, stacklevel=1, source=None)

触发一条警告。

参数：

message：警告信息

category：指定类型（默认 UserWarning）

stacklevel：指定源头的调用栈层级

返回：无

◆ ◆ ◆

补充说明

1、建议在库/框架开发中使用 warnings.warn() 替代 print() 以告知用户正确用法。

2、使用 stacklevel=2 可将警告定位到调用者，而非内部函数。

3、若需将警告写入日志文件，可重写 warnings.showwarning() 或结合 logging.captureWarnings(True) 使用。

“点赞有美意，赞赏是鼓励”