Python warnings.catch_warnings 怎么把指定警告临时升级为异常

把指定警告临时升级为异常，可以在 with warnings.catch_warnings(): 中调用 warnings.filterwarnings("error", ...)，按类别、消息和模块限定目标，再执行可能产生警告的代码。匹配的警告会以对应警告类作为异常抛出；离开上下文后，过滤策略恢复为进入前的状态。

这里的“临时”描述过滤策略的生命周期，不代表数据库或文件操作会回滚，也不保证所有 Python 版本中的并发任务互相隔离。下面先按串行调用说明，再解释并发差异。

官方地址：https://docs.python.org/3.14/library/warnings.html

项目目标：只拒绝一个旧模式提示

我会把这样的检查封装在调用边界，而不是在模块导入时全局设置“所有警告都失败”。这样做的取舍很明确：关键路径可以对旧接口更严格，其他调用继续使用已有策略。

这个练习包含 compat_reader.py 与 check_compat.py 两个同目录文件，只用标准库，适合 Python 3.10+ 的串行程序。它模拟一个读取计数的函数：现代模式返回整数，旧模式先发出特定弃用警告。示例为本文原创，没有真实依赖升级事故，也未在本文执行。

先让警告有可识别的类别和来源

# compat_reader.py
import warnings


class LegacyModeWarning(DeprecationWarning):
    """仅表示此模块旧读取模式的弃用提示。"""


def read_count(text, *, mode="modern"):
    if mode == "legacy":
        # 警告归属本模块，便于演示 module 正则；未重定向到调用者。
        warnings.warn(
            "legacy mode is deprecated; use modern mode",
            LegacyModeWarning,
            stacklevel=1,
        )
    elif mode != "modern":
        raise ValueError("不支持的读取模式")

    # 仅做整数解析，没有文件写入等需要回滚的副作用。
    return int(text.strip())

LegacyModeWarning 是 DeprecationWarning 的子类，让捕获范围更具体。这里特意保留 stacklevel=1，使警告来源模块为 compat_reader。真实库可能使用 stacklevel=2 或其他归属机制，届时筛选的模块应对应警告实际归属位置，而不是想当然地填写函数定义所在模块。

read_count 在发出警告之前没有修改外部数据；若警告升级成异常，就不会继续执行后面的解析。换成真实业务函数时，应查看警告出现前是否已经产生副作用，不能仅凭 catch_warnings 的存在认定整个调用具有事务性质。

在调用边界增加 error 规则

# check_compat.py
import warnings
from compat_reader import LegacyModeWarning, read_count


def checked_read(text, *, mode):
    # error 规则只在上下文中增加，退出时恢复进入前的过滤策略。
    with warnings.catch_warnings():
        warnings.filterwarnings(
            "error",
            message=r"^legacy mode is deprecated;",
            category=LegacyModeWarning,
            module=r"^compat_reader$",
        )
        return read_count(text, mode=mode)


def main():
    try:
        checked_read("125", mode="legacy")
    except LegacyModeWarning as exc:
        # 在 with 外捕获，确保处理分支执行时上下文已经退出。
        print("旧模式被兼容检查拒绝：" + str(exc))

    # 正常路径继续返回整数，不把原本的数据错误吞成零。
    value = checked_read("125", mode="modern")
    print("现代模式读取值：", value)


if __name__ == "__main__":
    main()

把两个文件放在同一目录，并以 check_compat.py 作为入口。按代码设计，旧模式在 warn 处抛出 LegacyModeWarning，控制流离开 with 后交给外层 except；现代模式不发出这条警告，正常返回整数。这里描述的是预期行为，不是本地执行回执。

单独的 except LegacyModeWarning 不会让普通警告自动变为异常，真正改变处理方式的是 action 为 error 的过滤规则。反过来，catch_warnings 也不会自动吞掉异常，它负责上下文管理，异常仍按 Python 正常传播。

消息、类别、模块必须一起看

filterwarnings 默认把新规则插到前面，匹配时前面的规则先决定动作。不要在精确规则后又添加一条更宽泛的 ignore 并以为“后写的只是兜底”；默认插入行为可能让那条 ignore 反而优先。append=True 则会放到末尾，已有规则可能先匹配。

未匹配这条规则的警告继续交给已有策略。它们不一定显示，也不一定不会成为异常：外部启动参数或框架本来就可能设置其他规则。这段代码保证的是只新增这一条精确 error 规则，而不是重新定义整个进程的所有警告行为。

把小检查集成进现有入口

在真实程序中，替换 read_count 的调用即可保留这个结构。若依赖在导入阶段发出警告，应让相应导入发生在上下文内；但已经导入并缓存的模块通常不会因为再次 import 就重新执行模块代码。不要为演示警告重复性随意重载生产依赖。

上下文退出会恢复过滤策略，并不重置所有业务状态或警告注册历史，也不把之前忽略的输出重新播放。对 default、once 等重复抑制策略，要把“本次是否重新触发警告”和“当前采取什么动作”分开理解，不能把没有输出直接认定为接口没有弃用。

例子只捕获目标警告，ValueError 等正常数据错误继续传播。若应用需要把不同失败转换成状态，应在更外层分别处理，不要用宽泛 except Exception 然后返回零掩盖坏数据。

并发版本差异不能省略

Python 3.14 增加 sys.flags.context_aware_warnings。官方说明，该标志为真时 catch_warnings 使用上下文变量保存过滤状态；为假时会修改 warnings 模块的全局属性，并发使用不安全。free-threaded 构建默认真，其他构建默认假；3.14 以前按后者行为理解。

因此，“退出后恢复”与“执行期间不影响其他线程或异步任务”不是同一句保证。若服务中有并发工作，应依据实际解释器版本和标志选择隔离方式；不要在一个协程的上下文里跨 await 长时间保留临时过滤规则，却默认其他协程完全不受影响。本文示例按串行使用，不更改解释器启动配置。

常见问题

record=True 能让警告变成异常吗？

不能。record 用于记录走警告展示通道的消息；error 是让匹配警告抛异常的动作。已经抛出的目标警告不应期待又作为普通记录自动收集，选择记录还是失败，要按任务目的决定。

为什么 category 匹配，module 却没匹配？

先看真实归属模块，尤其是库是否通过 stacklevel 把提示归属到调用者。message 和 module 是不同条件，只要其中一项不匹配，这条精确规则就不会生效。

with 外也继续报错，是恢复失败吗？

不一定。退出是恢复进入前的策略；如果外部原本配置了某类警告为 error，恢复后仍会报错。不要把恢复理解成强制切回忽略或默认显示。

参考资料：Python 警告筛选规则、catch_warnings 上下文、并发安全说明。