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) 使用。
“点赞有美意，赞赏是鼓励”
热门跟贴