KBEngine 内置 CPython 3.7 的 warnings 模块:警告控制机制、过滤器配置与源码级实现解析

原创2026-10-18 10:31:551,969 阅读
文章标签:游戏开发后端

KBEngine 内置 CPython 3.7 的 warnings 模块:警告控制机制、过滤器配置与源码级实现解析

本文围绕 KBEngine 仓库中内置的 CPython 3.7.3 源码树里随附的官方标准库文档 warnings.rst 展开,系统讲解 Python warnings 模块的完整工作机制:警告类别体系、过滤器(filter)匹配规则、-W 命令行选项与 PYTHONWARNINGS 环境变量的配置语法、catch_warnings 上下文管理器以及全部可用函数。读完本文后,你可以掌握如何精细控制警告的输出、屏蔽与转异常,并能对照仓库中的 Lib/warnings.py 与 Python/_warnings.c 两份实现源码,理解警告从产生到处置的完整调用链。

一、warnings 模块的定位:KBEngine 仓库中的一份标准库文档

KBEngine 作为一个 MMOG 服务端引擎,其工具链与服务端脚本体系大量依赖 Python。仓库在 kbe/src/lib/python 下完整内置了一份 CPython 源码树,版本可由 Include/patchlevel.h 确认为 3.7.3(PY_MAJOR_VERSION 3、PY_MINOR_VERSION 7、PY_MICRO_VERSION 3)。warnings 模块的官方文档正是随这份源码树发布的 Doc/library/warnings.rst,文档中声明的实现源码路径 Lib/warnings.py 对应仓库中的 kbe/src/lib/python/Lib/warnings.py(共 565 行),C 层面加速实现位于 kbe/src/lib/python/Python/_warnings.c(共 1345 行)。

按文档的定义,警告消息(warning message)通常出现在这种场景:程序运行中遇到某个值得提醒用户的状况,但该状况通常不值得抛出异常、终止程序。典型例子是程序使用了某个已过时(obsolete)的模块时发出警告。文档对两个关键事实的表述是:

  • Python 程序员通过调用本模块的 warn 函数发出警告;C 程序员则使用 C API PyErr_WarnEx(这一点可由 Python/_warnings.c 中 PyErr_WarnEx 的实际实现印证)。
  • 警告消息通常写入 sys.stderr,但其处置方式可以灵活改变——从忽略所有警告到把它们变成异常都可以。

二、警告控制的两阶段模型

文档给出的核心架构是两阶段控制(two stages):

  1. 判定阶段:每次发出警告时,先判断该警告消息是否应当发出。这一判定由警告过滤器(warnings filter)完成——它是一组有序匹配规则与动作(matching rules and actions)的序列。可通过调用 filterwarnings 向过滤器中追加规则,调用 resetwarnings 将其重置为默认状态。
  2. 输出阶段:若判定应发出消息,则消息被格式化后打印。打印动作由可被覆盖的 showwarning 函数完成;其默认实现通过调用 formatwarning 对消息进行格式化,formatwarning 也可供自定义实现复用。

从源码结构看,这一模型在 Lib/warnings.py 中体现得非常清晰:warn/warn_explicit 负责收集上下文并遍历 filters 列表做匹配(判定阶段,见 L366-L375 的过滤器搜索循环),命中 "error" 动作时直接 raise message(L385-L386),否则构造 WarningMessage 对象调用 _showwarnmsg(L409-L411)进入输出阶段。此外文档还提示:logging.captureWarnings 可以把所有警告交给标准 logging 基础设施统一处理。

三、警告类别(Warning Categories)

警告类别本质上是一组内建异常类,其价值在于可以按组过滤警告。用户代码可以通过子类化某个标准警告类别来自定义类别,但警告类别必须始终是 Warning 类的子类。文档完整列举了当前定义的全部类别,如下表:

类 说明
Warning 所有警告类别类的基类,是 Exception 的子类
UserWarning warn 的默认类别
DeprecationWarning 面向其他 Python 开发者的弃用功能警告基类(默认被忽略,除非由 __main__ 中的代码触发)
SyntaxWarning 可疑语法特性的警告基类
RuntimeWarning 可疑运行时特性的警告基类
FutureWarning 面向 Python 应用最终用户的弃用功能警告基类
PendingDeprecationWarning 将来将被弃用的功能警告基类(默认被忽略)
ImportWarning 导入模块过程中触发的警告基类(默认被忽略)
UnicodeWarning 与 Unicode 相关的警告基类
BytesWarning 与 bytes 和 bytearray 相关的警告基类
ResourceWarning 与资源使用相关的警告基类

文档还给出了重要的版本演进说明:在 3.7 之前,DeprecationWarning 与 FutureWarning 的区分依据是"功能是否被整体移除或仅改变行为";3.7 起,二者改按目标受众以及默认警告过滤器的处理方式区分。这一演进在源码中也有对应痕迹:_warnings.c 中 C 层发警告时若 category 为 NULL 会回退到 PyExc_RuntimeWarning(见 L987-L994 的 warn_unicode),而 L1038-L1054 专门提供了 PyErr_ResourceWarning 入口,与上表中的 ResourceWarning 类别一一对应。

四、警告过滤器:五种 action 与五元组匹配规则

过滤器控制警告是被忽略、显示还是转成异常。概念上它维护一个有序的过滤器规格(filter specification)列表:每条警告按顺序与列表中的每条规格匹配,直到找到第一个命中项,由命中的规格决定处置方式。每条规格是一个五元组 (*action*, *message*, *category*, *module*, *lineno*):

action 取值及其处置语义(原文档的核心表格,完整继承):

值 处置
"default" 对警告发生位置(模块 + 行号)的首次出现打印匹配警告
"error" 将匹配的警告转换为异常
"ignore" 永不打印匹配的警告
"always" 总是打印匹配的警告
"module" 对每个模块中警告的首次出现打印(不关心行号)
"once" 无论出现在何处,只打印匹配警告的第一次

其余三个匹配字段的规则:

  • message:字符串形式的正则表达式,警告消息的开头必须匹配;该表达式编译时始终忽略大小写;
  • category:一个类(Warning 的子类),警告类别必须是它的子类才能匹配;
  • module:字符串形式的正则表达式,模块名必须匹配;编译时区分大小写;
  • lineno:整数,警告发生的行号必须与之相等,取 0 表示匹配所有行号。

由于 Warning 派生自内建 Exception,"把警告转成错误"的实现极其直接——就是 raise category(message)。若一条警告没有匹配到任何已注册过滤器,则应用 "default" 动作(这也是其名称的由来)。

源码中的匹配逻辑

上述规则在 Lib/warnings.py 的纯 Python 后备实现中逐行可查。warn_explicit 中的过滤器搜索循环(L366-L375)完整实现了四条件匹配:

for item in filters:
    action, msg, cat, mod, ln = item
    if ((msg is None or msg.match(text)) and
        issubclass(category, cat) and
        (mod is None or mod.match(module)) and
        (ln == 0 or lineno == ln)):
        break
else:
    action = defaultaction

而各 action 的去重注册逻辑紧随其后(L388-L408):"once" 用全局 onceregistry 记录 (消息文本, 类别);"module" 用模块级 __warningregistry__ 同时记录精确行号 key 与"行号置 0"的 altkey;"default" 只记录精确 key。这解释了为什么文档在"测试警告"一节特别强调:一旦某条警告已因 once/default 规则被触发过,无论过滤器怎么改,只要相关 registry 没被清空,该警告都不会再次出现。此外 _add_filter(L181-L193)在插入新过滤器时会先移除重复项并调用 _filters_mutated() 递增过滤器版本号——源码中 warn_explicit 开头正是靠比较 registry<a href="https://link.gitcode.com/i/338882d4bc2b050baa5ee4dfaa999af7" target="_blank">'version'] 与 _filters_version 来使过期缓存失效的([L353-L355)。

五、过滤器描述语法:-W 选项与 PYTHONWARNINGS

过滤器由 Python 解释器命令行传入的 -W 选项和环境变量 PYTHONWARNINGS 初始化。解释器不做解析地原样保存所有条目到 sys.warnoptions;warnings 模块在首次被导入时才解析这些条目(无效选项被忽略,并向 sys.stderr 打印一条消息)。

单个过滤器是冒号分隔的字段序列:

action:message:category:module:line

各字段含义即上节所述。在单行中列出多个过滤器(如 PYTHONWARNINGS 的做法)时,过滤器之间用逗号分隔,靠后列出的过滤器优先于靠前列出的(因为规则从左到右依次应用,最新应用的过滤器优先于更早的)。

文档给出的常用过滤器示例(完整保留,可直接复制使用):

default                      # 显示所有警告(包括默认被忽略的)
ignore                       # 忽略所有警告
error                        # 把所有警告转为错误
error::ResourceWarning       # 把 ResourceWarning 消息当作错误处理
default::DeprecationWarning  # 显示 DeprecationWarning 消息
ignore,default:::mymodule    # 只报告由 "mymodule" 触发的警告
error:::mymodule[.*]         # 把 "mymodule" 及其任何子包中的警告转为错误

从源码看,命令行选项的解析由 _processoptions/_setoption 完成(Lib/warnings.py L205-L237),其中几个值得注意的实现细节:

  • action 字段允许前缀缩写,_getaction 用 startswith 匹配合法动作,且 all 是 always 的别名(L240-L247);
  • 命令行来源的 message 与 module 会先经过 re.escape 转义再匹配,且 module 匹配会追加 $ 锚定结尾(L223-L227),因此 -W 语法里的"正则"实际是按字面量处理的——例如 mymodule[.*] 之所以有效,是因为模块名正则本身支持通配,而这正是文档示例中 error:::mymodule[.*] 能覆盖子包的原因;
  • category 字段支持裸类名(eval 解析)或 模块名.类名 形式,解析失败即视为无效选项(L250-L273);
  • 模块初始化入口是 _processoptions(sys.warnoptions),位于 Lib/warnings.py L554,与文档"首次导入时解析"的描述完全一致。

默认警告过滤器

在常规发布构建(regular release build)中,Python 安装的默认过滤器按优先级排序为:

default::DeprecationWarning:__main__
ignore::DeprecationWarning
ignore::PendingDeprecationWarning
ignore::ImportWarning
ignore::ResourceWarning

调试构建(debug build)中该列表为空。版本演进:3.2 起 DeprecationWarning 与 PendingDeprecationWarning 一样默认被忽略;3.7 起 __main__ 中直接触发的 DeprecationWarning 恢复为默认可见;3.7 起 BytesWarning 不再出现在默认过滤器列表中,改由指定两次 -b 选项时通过 sys.warnoptions 配置。

这份默认过滤器列表同样可以在源码中找到对应实现:当 _warnings_defaults 为假(即 C 层扩展未提供默认值)时,模块初始化代码在 Lib/warnings.py L555-L563 逐条安装上述五条过滤器(filterwarnings("default", category=DeprecationWarning, module="__main__", append=1) 对应第一行,其余用 simplefilter("ignore", ...) 追加),且仅在非 debug 构建(sys 无 gettotalrefcount 属性时)才安装。

覆盖默认过滤器的三种推荐模式

1. 应用开发者隐藏所有警告:应用开发者可能希望默认对最终用户隐藏所有 Python 级警告,只在跑测试或开发时显示。sys.warnoptions 可作为"用户是否显式配置过"的标记:

import sys

if not sys.warnoptions:
    import warnings
    warnings.simplefilter("ignore")

2. 测试运行器显示全部警告:测试运行器应确保被测代码的所有警告默认可见:

import sys

if not sys.warnoptions:
    import os, warnings
    warnings.simplefilter("default") # 改变本进程的过滤器
    os.environ["PYTHONWARNINGS"] = "default" # 同时影响子进程

3. 交互式 Shell 显示 DeprecationWarning:在 __main__ 之外的命名空间执行用户代码的交互式 shell,应确保 DeprecationWarning 默认可见(user_ns 为执行交互输入代码的模块):

import warnings
warnings.filterwarnings("default", category=DeprecationWarning,
                                   module=user_ns.get("__name__"))

这三种模式本质上是同一思想的变体:以 sys.warnoptions 为空作为"用户未干预"的信号,再由程序按自身角色(应用/测试器/Shell)选择性地收紧或放宽过滤器。

六、临时抑制警告:catch_warnings 上下文管理器

当你使用一段已知会触发警告的代码(如弃用函数),又不希望看到警告——即使警告已通过命令行显式配置——可以用 catch_warnings 上下文管理器抑制警告:

import warnings

def fxn():
    warnings.warn("deprecated", DeprecationWarning)

with warnings.catch_warnings():
    warnings.simplefilter("ignore")
    fxn()

进入上下文后所有警告被忽略。这样你可以在不影响其他未知代码的前提下,安全地调用已知弃用的接口。注意文档的限定:该保证仅在单线程应用中成立——两个或多个线程同时使用 catch_warnings 时行为未定义。

从源码看这一限定并非空话:catch_warnings.__enter__ 会替换模块级 filters 与 showwarning(Lib/warnings.py L474-L491 中 self._module.filters = self._filters<a href="https://link.gitcode.com/i/a8c269b68abbdd1aea6e3f6b908b362f" target="_blank">:] 并调用 _filters_mutated()),__exit__ 再还原([L493-L499)。由于保护对象是模块级全局状态,跨线程并发进入时互不隔离,文档脚注中"修改全局状态、因此非线程安全"的表述与实现完全吻合。

七、测试警告:记录与断言

测试代码发出的警告,同样使用 catch_warnings。传入 record=True 后,可以临时改变过滤器以便测试,例如捕获所有触发的警告来断言:

import warnings

def fxn():
    warnings.warn("deprecated", DeprecationWarning)

with warnings.catch_warnings(record=True) as w:
    # 让所有警告总是触发
    warnings.simplefilter("always")
    # 触发一个警告
    fxn()
    # 验证若干属性
    assert len(w) == 1
    assert issubclass(w[-1].category, DeprecationWarning)
    assert "deprecated" in str(w[-1].message)

也可以把 always 换成 error,使所有警告直接成为异常。需要留意的坑(文档原样强调):如果某警告此前已因 once/default 规则触发过,那么无论怎么设置过滤器,除非清空与该警告相关的 registry,否则它不会再出现——对应源码即 L353-L355 的 version 失效机制与 registry<a href="https://link.gitcode.com/i/898badae4a416812ae6e8fb0477e8a5e" target="_blank">key] 快速去重([L362-L365)。

上下文退出后,警告过滤器与 showwarning 函数都会恢复到进入时的状态,防止测试之间以意外方式改变过滤器、导致测试结果不确定。同样是单线程保证,多线程并发使用行为未定义。

当测试多个都会发出同类警告的操作时,必须以能确认每个操作各自发出新警告的方式测试:例如把警告设为异常并检查每个操作都抛异常;或检查警告列表长度在每次操作后持续增加;或在每次新操作前删除列表中的旧条目。

record=True 的实现路径:__enter__ 将 _showwarnmsg_impl 临时替换为日志列表的 append,并把 showwarning 复位为原始实现,从而保证 _showwarnmsg() 仍走统一入口(L483-L489);列表中的每个对象即 WarningMessage 实例(L414-L433),其属性名与 showwarning 的形参一致:message、category、filename、lineno、file、line、source。

八、面向新依赖版本更新代码:让默认忽略的警告可见

主要面向 Python 开发者(而非应用最终用户)的警告类别默认被忽略。尤其 DeprecationWarning 对除 __main__ 外的每个模块都默认忽略——这意味着开发者应确保在"通常被忽略的警告可见"的条件下测试自己的代码,以便及时获得未来破坏性 API 变更的通知(无论是标准库还是第三方包)。

理想情况下,代码拥有合适的测试套件,而测试运行器会在运行测试时隐式开启全部警告(unittest 模块自带的测试运行器会这样做)。

较不理想的情况下,可以通过给解释器传 -Wd(等价于 -W default)或在环境中设置 PYTHONWARNINGS=default 来检查应用是否使用了弃用接口。这会对所有警告(包括默认被忽略的)启用默认处理。要改变遇到警告时的动作,只需改变传给 -W 的参数(例如 -W error)。

九、可用函数与上下文管理器全解

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

发出一个警告,或者忽略它,或者抛出异常。category 参数(若给出)必须是警告类别类,默认 UserWarning;也可以直接把 message 传为 Warning 实例,此时 category 被忽略、改用 message.__class__,消息文本取 str(message)。若过滤器把该警告转为错误,本函数会抛出异常。stacklevel 供 Python 编写的包装函数使用:

def deprecation(message):
    warnings.warn(message, DeprecationWarning, stacklevel=2)

这样警告指向的是 deprecation 的调用者,而不是 deprecation 自身(后者会使警告消息失去意义)。source(3.6 新增)是发出 ResourceWarning 的已销毁对象。

源码层面,warn 的核心工作是采集调用上下文(Lib/warnings.py L291-L341):用 sys._getframe 沿栈回溯 stacklevel 层,期间 _next_external_frame(L282-L287)会跳过 importlib _bootstrap 之类的内部帧,随后从帧的 f_globals 提取模块名、文件名与 __warningregistry__(没有则创建,L339),最终委托给 warn_explicit。

warn_explicit(message, category, filename, lineno, module=None, registry=None, module_globals=None, source=None)

warn 的底层接口:显式传入消息、类别、文件名与行号,可选模块名与 registry(应为该模块的 __warningregistry__ 字典)。模块名默认为去掉 .py 后缀的文件名;若未传 registry,警告永不被抑制。message 必须是字符串、category 必须是 Warning 子类(或 message 为 Warning 实例)。module_globals(若提供)应是发出警告代码正在使用的全局命名空间——该参数用于支持显示来自 zipfile 或其他非文件系统导入源的模块源码。source 同样指发出 ResourceWarning 的已销毁对象(3.6 新增)。

从源码看,C 层扩展实现 Python/_warnings.c 中的 warnings_warn_explicit(L936-L975)在解析参数后,若提供了 module_globals,会先从中读取 __file__ 对应文件、取出 lineno 行源码(get_source_line),再交给 C 版 warn_explicit——这正是 module_globals 参数"支持 zip 内模块源码显示"的实现载体。

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

把警告写入文件。默认实现调用 formatwarning(message, category, filename, lineno, line) 并把结果字符串写入 file(默认 sys.stderr)。给 warnings.showwarning 赋任意可调用对象即可替换该函数。line 是要包含在警告消息中的一行源码;未提供时 showwarning 会尝试按 filename 和 lineno 读取该行。实现侧 _showwarnmsg_impl(Lib/warnings.py L20-L33)还处理了两个边界:file 为 None 时回退 sys.stderr(pythonw.exe 下 sys.stderr 本身为 None,警告被丢弃),以及写文件发生 OSError 时静默吞掉("警告丢失")。_showwarnmsg(L96-L112)则始终保留 _showwarning_orig 引用,以检测用户是否替换过 showwarning,替换后按新签名转发。

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

以标准方式格式化警告,返回可能包含内嵌换行、以换行结尾的字符串。_formatwarnmsg_impl(L35-L91)的实际输出形如 filename:lineno: Category: message,未提供 line 时通过 linecache 读取;若提供了 source(ResourceWarning 场景),且 tracemalloc 可用且正在追踪,还会追加 "Object allocated at (most recent call last):" 的对象分配回溯,否则提示 "Enable tracemalloc to get the object allocation traceback"——这也是 warn/warn_explicit 的 source 参数的意义所在。

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

向过滤器列表插入一条规格。默认插入在列表前端;append=True 时插入到末尾。本函数会校验参数类型、编译 message 与 module 正则,然后以五元组形式插入。越靠近列表前端的条目越优先(当两条都能匹配同一条警告时)。省略的参数默认取"匹配一切"的值。实现上的正则编译规则(message 忽略大小写、module 区分大小写)见 L151-L161。

simplefilter(action, category=Warning, lineno=0, append=False)

插入一条"简单"过滤器规格。参数含义同 filterwarnings,但插入的过滤器不需要正则——只要类别与行号匹配,它就匹配任何模块的任何消息。实现即 _add_filter(action, None, category, None, lineno, ...)(L165-L179),None 的 message/module 在匹配阶段等价于"匹配一切"。

resetwarnings()

重置警告过滤器:丢弃此前所有 filterwarnings 调用的效果,包括 -W 命令行选项与 simplefilter 调用。实现即清空模块级 filters 并触发版本号递增(L195-L198)。

catch_warnings(*, record=False, module=None)

上下文管理器:复制过滤器列表与 showwarning 函数,并在退出时还原。record=False(默认)时进入时返回 None;record=True 时返回一个列表,由自定义 showwarning 逐步填充(同时抑制对 sys.stdout 的输出),每个列表项具有与 showwarning 形参同名的属性。module 参数可指定一个替代模块(其过滤器受保护),主要用于测试 warnings 模块本身。文档脚注再次强调:它通过替换再还原模块级 showwarning 与内部过滤器列表工作,因此修改全局状态、非线程安全。

十、纯 Python 后备与 C 扩展的双轨实现

Lib/warnings.py 的文档注释写着 "Python part of the warnings subsystem",文件末尾(L533-L550)有一段关键的 try/except ImportError:

try:
    from _warnings import (filters, _defaultaction, _onceregistry,
                           warn, warn_explicit, _filters_mutated)
    defaultaction = _defaultaction
    ...
    _warnings_defaults = True
except ImportError:
    filters = []
    defaultaction = "default"
    onceregistry = {}
    ...
    _warnings_defaults = False

也就是说,常规构建下 warn/warn_explicit/filters 等核心对象来自 C 扩展 _warnings(即 Python/_warnings.c),纯 Python 版本是同签名后备实现;filters 是五元组序列,其语义在文件尾部注释(L525-L532)中有权威描述:action、消息匹配正则、类别类、模块匹配正则、行号(0 表示任意行),两个正则为 None 时匹配一切。C 扩展同时提供了 Python 层文档引用的整套 C API:PyErr_WarnEx(L1058-L1067)、PyErr_Warn(其向后兼容包装,L1074-L1078)、PyErr_WarnExplicit/PyErr_WarnExplicitObject(L1082-L1123)、PyErr_WarnExplicitFormat、PyErr_WarnFormat 以及 PyErr_ResourceWarning(L1038-L1054)。这些入口内部统一汇入 warn_unicode → do_warn / warn_explicit,与文档"C 程序员使用 PyErr_WarnEx"的说法互相印证。

此外,模块中还可见一个典型的 C 层发起的警告实例:_warn_unawaited_coroutine(L503-L522)——协程从未被 await 时,Python 运行时通过它发出带创建位置回溯的 RuntimeWarning,并传入 source=coro 以配合 tracemalloc 显示分配回溯。

测试侧,仓库随附 CPython 3.7 的官方测试包 Lib/test/test_warnings(含 __init__.py、__main__.py 与 data/ 子目录),覆盖警告子系统各路径,可在本地按 CPython 测试框架方式运行以验证上述行为。

小结

warnings 模块的设计可以用一句话概括:类别决定"这是什么",过滤器决定"要不要说",showwarning/formatwarning 决定"怎么说",registry 决定"重复的说一遍还是闭嘴"。文档中 -W/PYTHONWARNINGS 语法、五种 action 语义、默认过滤器列表、sys.warnoptions 三种覆盖模式、catch_warnings 抑制与 record=True 测试范式,构成了完整的操作面;而 Lib/warnings.py 的纯 Python 后备实现与 Python/_warnings.c 的 C 扩展实现,则让上述每一条行为都可以在 KBEngine 内置的这份 CPython 3.7.3 源码树中找到逐行对应的依据。对维护 KBEngine 服务端脚本与工具链的开发者而言,掌握这套机制意味着:能在启动命令里精确控制警告噪音(如 -W error:::kbe.* 将特定模块警告升级为异常),能在测试中可靠捕获与断言警告,也能理解为什么"某条警告只出现一次"以及如何让它在测试中每次都出现。

登录后查看全文
kbengine