摘要

在Python 2.7和Python 3.2中，默认警告过滤器已更新为默认隐藏 DeprecationWarning，这样，用Python编写的开发工具（例如linter、静态分析器、测试运行器、代码生成器）中的弃用警告，以及任何其他碰巧用Python编写的应用程序，就不会对其用户可见，除非这些用户明确选择查看它们。

然而，这一改变产生了一个不幸的副作用，即使得 DeprecationWarning 在其主要预期目的上明显降低了效果：提前通知API（无论是CPython、标准库还是第三方库）中的重大更改给这些API的用户。

为了改善这种情况，本PEP提议对默认警告过滤器进行单一调整：默认显示归因于主模块的弃用警告。

这一改变意味着在交互式提示符下输入的代码和单文件脚本中的代码将默认报告这些警告，而对于作为可导入模块一部分分发的打包代码，它们将继续默认静默。

本PEP还提议对参考解释器和标准库文档进行一些小的调整，以帮助新的Python开发人员更容易地接触警告子系统。

作为文档更新的一部分，将更清楚地说明 unittest 测试运行器在执行测试用例时默认显示所有警告，并建议其他测试运行器效仿。

规范

ignore::DeprecationWarning
ignore::PendingDeprecationWarning
ignore::ImportWarning
ignore::BytesWarning
ignore::ResourceWarning

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

if not sys.warnoptions:
    warnings.simplefilter("default")

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

参考实现

参考实现可在与此PEP相关的跟踪器问题 [5] 中链接的PR [4] 中找到。

作为实现此PEP的副作用，内部警告过滤器列表将开始允许在过滤器定义中使用纯字符串（除了现有使用已编译的正则表达式）。当存在时，纯字符串将仅用于精确匹配比较。这种方法允许在解释器启动期间添加新的默认过滤器，而无需提前访问 re 模块。

动机

正如 [1] 中讨论并 [2] 中提及的，Python 2.7 和 Python 3.2 改变了 DeprecationWarning 的默认处理方式，使得

• 在正常代码执行期间默认隐藏警告
• unittest 测试运行器已更新，以便在运行测试时重新启用它

其目的是为了避免以下工具输出情况

$ devtool mycode/
/usr/lib/python3.6/site-packages/devtool/cli.py:1: DeprecationWarning: 'async' and 'await' will become reserved keywords in Python 3.7
  async = True
... actual tool output ...

即使 devtool 是专门为Python程序员设计的工具，这也不是一个特别有用的警告，因为它会在每次调用时显示，尽管最终用户可以采取的主要有用步骤是向 devtool 的开发人员报告错误。

对于跨多种语言而不仅仅是Python使用的通用开发工具，该警告的帮助性甚至更低，而对于仅仅碰巧用Python编写，并且不一定面向开发人员受众的应用程序，则几乎完全*无*用。

然而，这一改变对以下受众产生了意想不到的后果

• 任何使用 unittest 中内置的默认测试运行器以外的测试运行器的人（从未明确要求第三方测试运行器更改其默认警告过滤器，因此它们中的许多仍然依赖于为部署的应用程序设计的解释器默认设置）
• 任何使用默认 unittest 测试运行器在子进程中测试其Python代码的人（因为即使 unittest 也只调整当前进程中的警告设置）
• 任何在交互式提示符下或作为直接执行脚本的一部分编写Python代码，但根本没有Python级别测试套件的人

在这些情况下，DeprecationWarning 最终几乎完全等同于 PendingDeprecationWarning：它根本从未被看到过。

PEP范围的限制

本PEP的存在，特别是为了解释针对3.7版默认警告过滤器的拟议添加，*以及*更清楚地阐明在Python 2.7和3.2中改变 DeprecationWarning 处理方式的最初理由。

本PEP并未解决当前处理弃用警告方法的所有已知问题。最值得注意的是

• 默认的 unittest 测试运行器目前不报告在模块导入时发出的弃用警告，因为警告过滤器覆盖仅在测试执行期间设置，而不是在测试发现和加载期间。
• 默认的 unittest 测试运行器目前不报告子进程中的弃用警告，因为警告过滤器覆盖直接应用于已加载的 warnings 模块，而不是 PYTHONWARNINGS 环境变量。
• 标准库没有提供一种直接的方法来选择查看在升级特定依赖项之前*由*该依赖项发出的所有警告（第三方 warn 模块 [3] 确实提供了此功能，但启用它涉及对标准库的 warnings 模块进行猴子补丁）。
• 当软件被分解为支持模块，但这些模块几乎没有或没有自动化测试覆盖时，在 __main__ 中默认重新启用弃用警告不太可能有助于发现API兼容性问题。短期内，目前最好的可用解决方案是使用 PYTHONWARNINGS=default::DeprecationWarning 或 python -W default::DeprecationWarning 运行受影响的应用程序，并注意其 stderr 输出。长期来看，这实际上是一个针对从事Python代码静态分析研究人员的问题：如何可靠地发现已弃用API的使用，以及如何在不实际运行提供API的代码或访问API的代码的情况下，根据 warnings.warn 调用推断API或参数已弃用。

虽然这些是现状的真实问题，但它们被排除在本PEP的考虑范围之外，因为它们需要比默认警告过滤器中一个额外条目更复杂的解决方案，并且解决它们至少可能不需要通过PEP流程。

对于有兴趣进一步研究它们的人来说，前两个将是 unittest 模块增强请求，第三个将是 warnings 模块增强请求，而最后一个只有在从其内容推断API弃用被认为是难以处理的代码分析问题，并且提出了注释中明确的函数和参数标记语法时才需要PEP。

CPython参考实现还将包含3.7中的以下相关更改

• 一个新的 -X dev 命令行选项，它将几个以开发人员为中心的设置（包括 -Wd）组合成一个命令行标志：https://github.com/python/cpython/issues/76224
• 改变调试构建的行为，以显示在常规解释器构建中默认关闭的更多警告：https://github.com/python/cpython/issues/76269

独立于本PEP中提议的默认过滤器更改，问题32229 [7] 是一个提议添加 warnings.hide_warnings API，以使应用程序开发人员在正常操作期间更容易隐藏警告，同时在测试时轻松使其可见。

参考资料

• 第一次 python-dev 讨论线程
• 第二次 python-dev 讨论线程

版权

本文档已置于公共领域。