Python标准库warnings——警告信息的控制

暂时禁止警告¶

如果明知正在使用会引起警告的代码，比如某个废弃函数，但不想看到警告（即便警告已经通过命令行作了显式配置），那么可以使用 catch_warnings 上下文管理器来抑制警告。

importwarnings
deffxn():
warnings.warn("deprecated",DeprecationWarning)
withwarnings.catch_warnings():
warnings.simplefilter("ignore")
fxn()

在上下文管理器中，所有的警告将被简单地忽略。这样就能使用已知的过时代码而又不必看到警告，同时也不会限制警告其他可能不知过时的代码。注意：只能保证在单线程应用程序中生效。如果两个以上的线程同时使用 catch_warnings 上下文管理器，行为不可预知。

测试警告¶

要测试由代码引发的警告，请采用 catch_warnings 上下文管理器。有了它，就可以临时改变警告过滤器以方便测试。例如，以下代码可捕获所有的警告以便查看：

importwarnings
deffxn():
warnings.warn("deprecated",DeprecationWarning)
withwarnings.catch_warnings(record=True)asw:
# Cause all warnings to always be triggered.
warnings.simplefilter("always")
# Trigger a warning.
fxn()
# Verify some things
assertlen(w)==1
assertissubclass(w[-1].category,DeprecationWarning)
assert"deprecated"instr(w[-1].message)

也可以用 error 取代 always ，让所有的警告都成为异常。需要注意的是，如果某条警告已经因为 once / default 规则而被引发，那么无论设置什么过滤器，该条警告都不会再出现，除非该警告有关的注册数据被清除。

一旦上下文管理器退出，警告过滤器将恢复到刚进此上下文时的状态。这样在多次测试时可防止意外改变警告过滤器，从而导致不确定的测试结果。模块中的 showwarning() 函数也被恢复到初始值。注意：这只能在单线程应用程序中得到保证。如果两个以上的线程同时使用 catch_warnings 上下文管理器，行为未定义。

当测试多项操作会引发同类警告时，重点是要确保每次操作都会触发新的警告（比如，将警告设置为异常并检查操作是否触发异常，检查每次操作后警告列表的长度是否有增加，否则就在每次新操作前将以前的警告列表项删除）。

为新版本的依赖关系更新代码¶

在默认情况下，主要针对 Python 开发者（而不是 Python 应用程序的最终用户）的警告类别，会被忽略。

值得注意的是，这个“默认忽略”的列表包含 DeprecationWarning （适用于每个模块，除了 __main__），这意味着开发人员应该确保在测试代码时应将通常忽略的警告显示出来，以便未来破坏性 API 变化时及时收到通知（无论是在标准库还是第三方包）。

理想情况下，代码会有一个合适的测试套件，在运行测试时会隐含地启用所有警告（由 unittest 模块提供的测试运行程序就是如此）。

在不太理想的情况下，可以通过向 Python 解释器传入 -Wd (这是 -Wdefault 的简写) 或设置环境变量 PYTHONWARNINGS=default 来检查应用程序是否用到了已弃用的接口。 这样可以启用对所有警告的默认处理操作，包括那些默认忽略的警告。 要改变遇到警告后执行的动作，可以改变传给 -W 的参数 (例如 -Werror)。 请参阅 -W 旗标来了解更多的细节。

可用的函数¶

warnings.warn(message, category=None, stacklevel=1, source=None)¶

引发警告，或者忽略或引发异常。 如果给出 category 参数，则必须是警告类别类（见上文）；默认为 UserWarning。 或者 message 可为 Warning 的实例，这时 category 将被忽略，转而采用 message.__class__。 在这种情况下，错误信息文本将是 str(message)。 如果某条警告被警告过滤器改成了错误，本函数将触发一条异常。 参数 stacklevel 可供 Python 包装函数使用，比如:

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

这会让警告指向 deprecation() 的调用者，而不是 deprecation() 本身的来源（因为后者会破坏引发警告的目的）。

source 是发出 ResourceWarning 的被销毁对象。

在 3.6 版更改: 加入 source  参数。

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

这是 warn() 函数的底层接口，显式传入消息、类别、文件名和行号，以及可选的模块名和注册表（应为模块的 __warningregistry__ 字典）。 模块名称默认为去除了 .py 的文件名；如果未传递注册表，警告就不会被抑制。 message 必须是个字符串，category 是 Warning 的子类；或者*message* 可为 Warning 的实例，且 category 将被忽略。

module_globals 应为发出警告的代码所用的全局命名空间。（该参数用于从 zip 文件或其他非文件系统导入模块时显式源码）。

source 是发出 ResourceWarning 的被销毁对象。

在 3.6 版更改: 加入 source 参数。

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

Write a warning to a file. The default implementation calls

formatwarning(message,category,filename,lineno,line) and writes the

resulting string to file, which defaults to sys.stderr. You may replace

this function with any callable by assigning to warnings.showwarning.

line is a line of source code to be included in the warning

message; if line is not supplied, showwarning() will

try to read the line specified by filename and lineno.

warnings.formatwarning(message, category, filename, lineno, line=None)¶

以标准方式格式化一条警告信息。将返回一个字符串，可能包含内嵌的换行符，并以换行符结束。如果未提供 line，formatwarning() 将尝试读取由 filename 和 lineno 指定的行。

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

在 警告过滤器种类 列表中插入一条数据项。默认情况下，该数据项将被插到前面；如果 append 为 True，则会插到后面。这里会检查参数的类型，编译 message 和 module 正则表达式，并将他们作为一个元组插入警告过滤器的列表中。如果两者都与某种警告匹配，那么靠近列表前面的数据项就会覆盖后面的项。省略的参数默认匹配任意值。

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

在 警告过滤器种类 列表中插入一条简单数据项。函数参数的含义与 filterwarnings() 相同，但不需要正则表达式，因为插入的过滤器总是匹配任何模块中的任何信息，只要类别和行号匹配即可。

warnings.resetwarnings()¶

重置警告过滤器。这将丢弃之前对 filterwarnings() 的所有调用，包括 -W 命令行选项和对 simplefilter() 的调用效果。

可用的上下文管理器¶

class warnings.catch_warnings(*, record=False, module=None)¶

该上下文管理器会复制警告过滤器和 showwarning() 函数，并在退出时恢复。 如果 record 参数是 False (默认)，则在进入时会返回 None。 如果 record 为 True，则返回一个列表，列表由自定义 showwarning() 函数所用对象逐步填充（该函数还会抑制 sys.stdout 的输出）。 列表中每个对象的属性与 showwarning() 的参数名称相同。

module 参数代表一个模块，当导入 warnings 时，将被用于代替返回的模块，其过滤器将被保护。该参数主要是为了测试 warnings 模块自身。

注解

catch_warnings 管理器的工作方式，是替换并随后恢复模块的 showwarning() 函数和内部的过滤器种类列表。这意味着上下文管理器将会修改全局状态，因此不是线程安全的。