592 lines
60 KiB
HTML
592 lines
60 KiB
HTML
|
||
<!DOCTYPE html>
|
||
|
||
<html xmlns="http://www.w3.org/1999/xhtml" lang="zh_CN">
|
||
<head>
|
||
<meta charset="utf-8" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
|
||
|
||
<title>warnings ——控制警告信息 — Python 3.8.20 文档</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
|
||
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
|
||
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
|
||
|
||
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
|
||
<script src="../_static/jquery.js"></script>
|
||
<script src="../_static/underscore.js"></script>
|
||
<script src="../_static/doctools.js"></script>
|
||
<script src="../_static/language_data.js"></script>
|
||
<script src="../_static/translations.js"></script>
|
||
|
||
<script src="../_static/sidebar.js"></script>
|
||
|
||
<link rel="search" type="application/opensearchdescription+xml"
|
||
title="在 Python 3.8.20 文档 中搜索"
|
||
href="../_static/opensearch.xml"/>
|
||
<link rel="author" title="关于这些文档" href="../about.html" />
|
||
<link rel="index" title="索引" href="../genindex.html" />
|
||
<link rel="search" title="搜索" href="../search.html" />
|
||
<link rel="copyright" title="版权所有" href="../copyright.html" />
|
||
<link rel="next" title="dataclasses --- 数据类" href="dataclasses.html" />
|
||
<link rel="prev" title="__main__ --- 顶层脚本环境" href="__main__.html" />
|
||
<link rel="canonical" href="https://docs.python.org/3/library/warnings.html" />
|
||
|
||
|
||
|
||
|
||
|
||
<style>
|
||
@media only screen {
|
||
table.full-width-table {
|
||
width: 100%;
|
||
}
|
||
}
|
||
</style>
|
||
<link rel="shortcut icon" type="image/png" href="../_static/py.svg" />
|
||
<script type="text/javascript" src="../_static/copybutton.js"></script>
|
||
<script type="text/javascript" src="../_static/menu.js"></script>
|
||
|
||
</head>
|
||
<body>
|
||
<div class="mobile-nav">
|
||
<input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"
|
||
aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu" />
|
||
<label for="menuToggler" class="toggler__label">
|
||
<span></span>
|
||
</label>
|
||
<nav class="nav-content" role="navigation">
|
||
<a href="https://www.python.org/" class="nav-logo">
|
||
<img src="../_static/py.svg" alt="Logo"/>
|
||
</a>
|
||
<div class="version_switcher_placeholder"></div>
|
||
<form role="search" class="search" action="../search.html" method="get">
|
||
<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">
|
||
<path fill-rule="nonzero"
|
||
d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z" fill="#444"></path>
|
||
</svg>
|
||
<input type="text" name="q" aria-label="快速搜索"/>
|
||
<input type="submit" value="转向"/>
|
||
</form>
|
||
</nav>
|
||
<div class="menu-wrapper">
|
||
<nav class="menu" role="navigation" aria-label="main navigation">
|
||
<div class="language_switcher_placeholder"></div>
|
||
<h3><a href="../contents.html">目录</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">warnings</span></code> ——控制警告信息</a><ul>
|
||
<li><a class="reference internal" href="#warning-categories">警告类别</a></li>
|
||
<li><a class="reference internal" href="#the-warnings-filter">警告过滤器</a><ul>
|
||
<li><a class="reference internal" href="#describing-warning-filters">警告过滤器的介绍</a></li>
|
||
<li><a class="reference internal" href="#default-warning-filter">默认警告过滤器</a></li>
|
||
<li><a class="reference internal" href="#overriding-the-default-filter">重写默认的过滤器</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#temporarily-suppressing-warnings">暂时禁止警告</a></li>
|
||
<li><a class="reference internal" href="#testing-warnings">测试警告</a></li>
|
||
<li><a class="reference internal" href="#updating-code-for-new-versions-of-dependencies">为新版本的依赖关系更新代码</a></li>
|
||
<li><a class="reference internal" href="#available-functions">可用的函数</a></li>
|
||
<li><a class="reference internal" href="#available-context-managers">可用的上下文管理器</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
<h4>上一个主题</h4>
|
||
<p class="topless"><a href="__main__.html"
|
||
title="上一章"><code class="xref py py-mod docutils literal notranslate"><span class="pre">__main__</span></code> --- 顶层脚本环境</a></p>
|
||
<h4>下一个主题</h4>
|
||
<p class="topless"><a href="dataclasses.html"
|
||
title="下一章"><code class="xref py py-mod docutils literal notranslate"><span class="pre">dataclasses</span></code> --- 数据类</a></p>
|
||
<div role="note" aria-label="source link">
|
||
<h3>本页</h3>
|
||
<ul class="this-page-menu">
|
||
<li><a href="../bugs.html">报告 Bug</a></li>
|
||
<li>
|
||
<a href="https://github.com/python/cpython/blob/3.8/Doc/library/warnings.rst"
|
||
rel="nofollow">显示源代码
|
||
</a>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</nav>
|
||
</div>
|
||
</div>
|
||
|
||
<div id="outdated-warning" style="padding: .5em; text-align: center; background-color: #FFBABA; color: #6A0E0E;">
|
||
这个文档所针对的是一个已不再受支持的 Python 旧版本。
|
||
你应当升级版本，并阅读
|
||
<a href="/3/library/warnings.html"> Python 当前稳定版本的文档</a>.
|
||
</div>
|
||
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<h3>导航</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="总目录"
|
||
accesskey="I">索引</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python 模块索引"
|
||
>模块</a> |</li>
|
||
<li class="right" >
|
||
<a href="dataclasses.html" title="dataclasses --- 数据类"
|
||
accesskey="N">下一页</a> |</li>
|
||
<li class="right" >
|
||
<a href="__main__.html" title="__main__ --- 顶层脚本环境"
|
||
accesskey="P">上一页</a> |</li>
|
||
|
||
<li><img src="../_static/py.svg" alt="python logo" style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li class="switchers">
|
||
<div class="language_switcher_placeholder"></div>
|
||
<div class="version_switcher_placeholder"></div>
|
||
</li>
|
||
<li>
|
||
|
||
</li>
|
||
<li id="cpython-language-and-version">
|
||
<a href="../index.html">3.8.20 Documentation</a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >Python 标准库</a> »</li>
|
||
<li class="nav-item nav-item-2"><a href="python.html" accesskey="U">Python 运行时服务</a> »</li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="快速搜索" aria-label="快速搜索" type="text" name="q" />
|
||
<input type="submit" value="转向" />
|
||
<input type="hidden" name="check_keywords" value="yes" />
|
||
<input type="hidden" name="area" value="default" />
|
||
</form>
|
||
</div>
|
||
|
|
||
</li>
|
||
|
||
</ul>
|
||
</div>
|
||
|
||
<div class="document">
|
||
<div class="documentwrapper">
|
||
<div class="bodywrapper">
|
||
<div class="body" role="main">
|
||
|
||
<section id="module-warnings">
|
||
<span id="warnings-warning-control"></span><h1><a class="reference internal" href="#module-warnings" title="warnings: Issue warning messages and control their disposition."><code class="xref py py-mod docutils literal notranslate"><span class="pre">warnings</span></code></a> ——控制警告信息<a class="headerlink" href="#module-warnings" title="永久链接至标题">¶</a></h1>
|
||
<p><strong>源代码：</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.8/Lib/warnings.py">Lib/warnings.py</a></p>
|
||
<hr class="docutils" id="index-0" />
|
||
<p>通常以下情况会引发警告：提醒用户注意程序中的某些情况，而这些情况（通常）还不值得触发异常并终止程序。例如，当程序用到了某个过时的模块时，就可能需要发出一条警告。</p>
|
||
<p>Python 程序员可调用本模块中定义的 <a class="reference internal" href="#warnings.warn" title="warnings.warn"><code class="xref py py-func docutils literal notranslate"><span class="pre">warn()</span></code></a> 函数来发布警告。（C 语言程序员则用 <a class="reference internal" href="../c-api/exceptions.html#c.PyErr_WarnEx" title="PyErr_WarnEx"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyErr_WarnEx()</span></code></a> ； 详见 <a class="reference internal" href="../c-api/exceptions.html#exceptionhandling"><span class="std std-ref">异常处理</span></a> ）。</p>
|
||
<p>警告信息通常会写入 <a class="reference internal" href="sys.html#sys.stderr" title="sys.stderr"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.stderr</span></code></a> ，但可以灵活改变，从忽略所有警告到变成异常都可以。警告的处理方式可以依据 <a class="reference internal" href="#warning-categories"><span class="std std-ref">警告类型</span></a> 、警告信息的文本和发出警告的源位置而进行变化。同一源位置重复出现的警告通常会被抑制。</p>
|
||
<p>控制警告信息有两个阶段：首先，每次引发警告时，决定信息是否要发出；然后，如果要发出信息，就用可由用户设置的钩子进行格式化并打印输出。</p>
|
||
<p><a class="reference internal" href="#warning-filter"><span class="std std-ref">警告过滤器</span></a> 控制着是否发出警告信息，也即一系列的匹配规则和动作。调用 <a class="reference internal" href="#warnings.filterwarnings" title="warnings.filterwarnings"><code class="xref py py-func docutils literal notranslate"><span class="pre">filterwarnings()</span></code></a> 可将规则加入过滤器，调用 <a class="reference internal" href="#warnings.resetwarnings" title="warnings.resetwarnings"><code class="xref py py-func docutils literal notranslate"><span class="pre">resetwarnings()</span></code></a> 则可重置为默认状态。</p>
|
||
<p>警告信息的打印输出是通过调用 <a class="reference internal" href="#warnings.showwarning" title="warnings.showwarning"><code class="xref py py-func docutils literal notranslate"><span class="pre">showwarning()</span></code></a> 完成的，该函数可被重写；默认的实现代码是调用 <a class="reference internal" href="#warnings.formatwarning" title="warnings.formatwarning"><code class="xref py py-func docutils literal notranslate"><span class="pre">formatwarning()</span></code></a> 进行格式化，自己编写的代码也可以调用此格式化函数。</p>
|
||
<div class="admonition seealso">
|
||
<p class="admonition-title">参见</p>
|
||
<p>利用 <a class="reference internal" href="logging.html#logging.captureWarnings" title="logging.captureWarnings"><code class="xref py py-func docutils literal notranslate"><span class="pre">logging.captureWarnings()</span></code></a> 可以采用标准的日志架构处理所有警告。</p>
|
||
</div>
|
||
<section id="warning-categories">
|
||
<span id="id1"></span><h2>警告类别<a class="headerlink" href="#warning-categories" title="永久链接至标题">¶</a></h2>
|
||
<p>警告的类别由一些内置的异常表示。这种分类有助于对警告信息进行分组过滤。</p>
|
||
<p>虽然在技术上警告类别属于 <a class="reference internal" href="exceptions.html#warning-categories-as-exceptions"><span class="std std-ref">内置异常</span></a>，但也只是在此记录一下而已，因为在概念上他们属于警告机制的一部分。</p>
|
||
<p>通过对某个标准的警告类别进行派生，用户代码可以定义其他的警告类别。 警告类别必须是 <a class="reference internal" href="exceptions.html#Warning" title="Warning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">Warning</span></code></a> 类的子类。</p>
|
||
<p>目前已定义了以下警告类别的类：</p>
|
||
<table class="docutils align-default">
|
||
<colgroup>
|
||
<col style="width: 42%" />
|
||
<col style="width: 58%" />
|
||
</colgroup>
|
||
<thead>
|
||
<tr class="row-odd"><th class="head"><p>类</p></th>
|
||
<th class="head"><p>描述</p></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="row-even"><td><p><a class="reference internal" href="exceptions.html#Warning" title="Warning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">Warning</span></code></a></p></td>
|
||
<td><p>这是所有警告类别的基类。它是 <a class="reference internal" href="exceptions.html#Exception" title="Exception"><code class="xref py py-exc docutils literal notranslate"><span class="pre">Exception</span></code></a> 的子类。</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><a class="reference internal" href="exceptions.html#UserWarning" title="UserWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">UserWarning</span></code></a></p></td>
|
||
<td><p>The default category for <a class="reference internal" href="#warnings.warn" title="warnings.warn"><code class="xref py py-func docutils literal notranslate"><span class="pre">warn()</span></code></a>.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><a class="reference internal" href="exceptions.html#DeprecationWarning" title="DeprecationWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">DeprecationWarning</span></code></a></p></td>
|
||
<td><p>已废弃特性警告的基类，这些警告是为其他 Python 开发者准备的（默认会忽略，除非在 <code class="docutils literal notranslate"><span class="pre">__main__</span></code> 中用代码触发）。</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><a class="reference internal" href="exceptions.html#SyntaxWarning" title="SyntaxWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SyntaxWarning</span></code></a></p></td>
|
||
<td><p>用于警告可疑语法的基类。</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><a class="reference internal" href="exceptions.html#RuntimeWarning" title="RuntimeWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">RuntimeWarning</span></code></a></p></td>
|
||
<td><p>用于警告可疑运行时特性的基类。</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><a class="reference internal" href="exceptions.html#FutureWarning" title="FutureWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">FutureWarning</span></code></a></p></td>
|
||
<td><p>用于警告已废弃特性的基类，这些警告是为 Python 应用程序的最终用户准备的。</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><a class="reference internal" href="exceptions.html#PendingDeprecationWarning" title="PendingDeprecationWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">PendingDeprecationWarning</span></code></a></p></td>
|
||
<td><p>用于警告即将废弃功能的基类（默认忽略）。</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><a class="reference internal" href="exceptions.html#ImportWarning" title="ImportWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ImportWarning</span></code></a></p></td>
|
||
<td><p>导入模块时触发的警告的基类（默认忽略）。</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><a class="reference internal" href="exceptions.html#UnicodeWarning" title="UnicodeWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">UnicodeWarning</span></code></a></p></td>
|
||
<td><p>用于 Unicode 相关警告的基类。</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><a class="reference internal" href="exceptions.html#BytesWarning" title="BytesWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">BytesWarning</span></code></a></p></td>
|
||
<td><p><a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> 和 <a class="reference internal" href="stdtypes.html#bytearray" title="bytearray"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytearray</span></code></a> 相关警告的基类。</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><a class="reference internal" href="exceptions.html#ResourceWarning" title="ResourceWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ResourceWarning</span></code></a></p></td>
|
||
<td><p>资源利用相关警告的基类。</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.7 版更改: </span>以前 <a class="reference internal" href="exceptions.html#DeprecationWarning" title="DeprecationWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">DeprecationWarning</span></code></a> 和 <a class="reference internal" href="exceptions.html#FutureWarning" title="FutureWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">FutureWarning</span></code></a> 是根据某个功能是否完全删除或改变其行为来区分的。现在是根据受众和默认警告过滤器的处理方式来区分的。</p>
|
||
</div>
|
||
</section>
|
||
<section id="the-warnings-filter">
|
||
<span id="warning-filter"></span><h2>警告过滤器<a class="headerlink" href="#the-warnings-filter" title="永久链接至标题">¶</a></h2>
|
||
<p>警告过滤器控制着警告是否被忽略、显示或转为错误（触发异常）。</p>
|
||
<p>从概念上讲，警告过滤器维护着一个经过排序的过滤器类别列表；任何具体的警告都会依次与列表中的每种过滤器进行匹配，直到找到一个匹配项；过滤器决定了匹配项的处理方式。每个列表项均为 ( <em>action</em> , <em>message</em> , <em>category</em> , <em>module</em> , <em>lineno</em> ) 格式的元组，其中：</p>
|
||
<ul>
|
||
<li><p><em>action</em> 是以下字符串之一：</p>
|
||
<table class="docutils align-default">
|
||
<colgroup>
|
||
<col style="width: 25%" />
|
||
<col style="width: 75%" />
|
||
</colgroup>
|
||
<thead>
|
||
<tr class="row-odd"><th class="head"><p>值</p></th>
|
||
<th class="head"><p>处置</p></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">"default"</span></code></p></td>
|
||
<td><p>为发出警告的每个位置（模块+行号）打印第一个匹配警告</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">"error"</span></code></p></td>
|
||
<td><p>将匹配警告转换为异常</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">"ignore"</span></code></p></td>
|
||
<td><p>从不打印匹配的警告</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">"always"</span></code></p></td>
|
||
<td><p>总是打印匹配的警告</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">"module"</span></code></p></td>
|
||
<td><p>为发出警告的每个模块打印第一次匹配警告（无论行号如何）</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">"once"</span></code></p></td>
|
||
<td><p>无论位置如何，仅打印第一次出现的匹配警告</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</li>
|
||
<li><p><em>message</em> 是包含正则表达式的字符串，警告信息的开头必须与之匹配。该表达式编译时不区分大小写。</p></li>
|
||
<li><p><em>category</em> 是警告类别的类（<a class="reference internal" href="exceptions.html#Warning" title="Warning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">Warning</span></code></a> 的子类），警告类别必须是其子类，才能匹配。</p></li>
|
||
<li><p><em>module</em> 是个字符串，包含了模块名称必须匹配的正则表达式。该表达式编译时大小写敏感。</p></li>
|
||
<li><p><em>lineno</em> 是个整数，发生警告的行号必须与之匹配，或为 <code class="docutils literal notranslate"><span class="pre">0</span></code> 表示与所有行号匹配。</p></li>
|
||
</ul>
|
||
<p>由于 <a class="reference internal" href="exceptions.html#Warning" title="Warning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">Warning</span></code></a> 类是由内置类 <a class="reference internal" href="exceptions.html#Exception" title="Exception"><code class="xref py py-exc docutils literal notranslate"><span class="pre">Exception</span></code></a> 派生出来的，要把某个警告变成错误，只要触发 <code class="docutils literal notranslate"><span class="pre">category(message)</span></code> 即可。</p>
|
||
<p>如果警告不匹配所有已注册的过滤器，那就会应用 “default” 动作（正如其名）。</p>
|
||
<section id="describing-warning-filters">
|
||
<span id="id2"></span><h3>警告过滤器的介绍<a class="headerlink" href="#describing-warning-filters" title="永久链接至标题">¶</a></h3>
|
||
<p>警告过滤器由传给 Python 解释器的命令行 <a class="reference internal" href="../using/cmdline.html#cmdoption-w"><code class="xref std std-option docutils literal notranslate"><span class="pre">-W</span></code></a> 选项和 <span class="target" id="index-7"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONWARNINGS"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONWARNINGS</span></code></a> 环境变量初始化。解释器在 <code class="xref py py-data docutils literal notranslate"><span class="pre">sys.warningoptions</span></code> 中保存了所有给出的参数，但不作解释；<a class="reference internal" href="#module-warnings" title="warnings: Issue warning messages and control their disposition."><code class="xref py py-mod docutils literal notranslate"><span class="pre">warnings</span></code></a> 模块在第一次导入时会解析这些参数（无效的选项被忽略，并会先向 <a class="reference internal" href="sys.html#sys.stderr" title="sys.stderr"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.stderr</span></code></a> 打印一条信息）。</p>
|
||
<p>每个警告过滤器的设定格式为冒号分隔的字段序列：</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">action</span><span class="p">:</span><span class="n">message</span><span class="p">:</span><span class="n">category</span><span class="p">:</span><span class="n">module</span><span class="p">:</span><span class="n">line</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>这些字段的含义在 <a class="reference internal" href="#warning-filter"><span class="std std-ref">警告过滤器</span></a> 中描述。当一行中列出多个过滤器时（如 <span class="target" id="index-8"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONWARNINGS"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONWARNINGS</span></code></a>），过滤器间用逗号隔开，后面的优先于前面的（因为是从左到右应用的，最近应用的过滤器优先于前面的）。</p>
|
||
<p>常用的警告过滤器适用于所有的警告、特定类别的警告、由特定模块和包引发的警告。下面是一些例子：</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">default</span> <span class="c1"># Show all warnings (even those ignored by default)</span>
|
||
<span class="n">ignore</span> <span class="c1"># Ignore all warnings</span>
|
||
<span class="n">error</span> <span class="c1"># Convert all warnings to errors</span>
|
||
<span class="n">error</span><span class="p">::</span><span class="ne">ResourceWarning</span> <span class="c1"># Treat ResourceWarning messages as errors</span>
|
||
<span class="n">default</span><span class="p">::</span><span class="ne">DeprecationWarning</span> <span class="c1"># Show DeprecationWarning messages</span>
|
||
<span class="n">ignore</span><span class="p">,</span><span class="n">default</span><span class="p">:::</span><span class="n">mymodule</span> <span class="c1"># Only report warnings triggered by "mymodule"</span>
|
||
<span class="n">error</span><span class="p">:::</span><span class="n">mymodule</span><span class="p">[</span><span class="o">.*</span><span class="p">]</span> <span class="c1"># Convert warnings to errors in "mymodule"</span>
|
||
<span class="c1"># and any subpackages of "mymodule"</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="default-warning-filter">
|
||
<span id="id3"></span><h3>默认警告过滤器<a class="headerlink" href="#default-warning-filter" title="永久链接至标题">¶</a></h3>
|
||
<p>Python 默认安装了几个警告过滤器，可以通过 <a class="reference internal" href="../using/cmdline.html#cmdoption-w"><code class="xref std std-option docutils literal notranslate"><span class="pre">-W</span></code></a> 命令行参数、 <span class="target" id="index-9"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONWARNINGS"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONWARNINGS</span></code></a> 环境变量及调用 <a class="reference internal" href="#warnings.filterwarnings" title="warnings.filterwarnings"><code class="xref py py-func docutils literal notranslate"><span class="pre">filterwarnings()</span></code></a> 进行覆盖。</p>
|
||
<p>在常规发布的版本中，默认的警告过滤器包括（按优先顺序排列）：</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">default</span><span class="p">::</span><span class="ne">DeprecationWarning</span><span class="p">:</span><span class="n">__main__</span>
|
||
<span class="n">ignore</span><span class="p">::</span><span class="ne">DeprecationWarning</span>
|
||
<span class="n">ignore</span><span class="p">::</span><span class="ne">PendingDeprecationWarning</span>
|
||
<span class="n">ignore</span><span class="p">::</span><span class="ne">ImportWarning</span>
|
||
<span class="n">ignore</span><span class="p">::</span><span class="ne">ResourceWarning</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>在调试版本中，默认警告过滤器的列表是空的。</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.2 版更改: </span>除了 <a class="reference internal" href="exceptions.html#PendingDeprecationWarning" title="PendingDeprecationWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">PendingDeprecationWarning</span></code></a> 之外，<a class="reference internal" href="exceptions.html#DeprecationWarning" title="DeprecationWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">DeprecationWarning</span></code></a> 现在默认会被忽略。</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.7 版更改: </span><a class="reference internal" href="exceptions.html#DeprecationWarning" title="DeprecationWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">DeprecationWarning</span></code></a> 在被 <code class="docutils literal notranslate"><span class="pre">__main__</span></code> 中的代码直接触发时，默认会再次显示。</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.7 版更改: </span>如果指定两次 <a class="reference internal" href="../using/cmdline.html#cmdoption-b"><code class="xref std std-option docutils literal notranslate"><span class="pre">-b</span></code></a>，则 <a class="reference internal" href="exceptions.html#BytesWarning" title="BytesWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">BytesWarning</span></code></a> 不再出现在默认的过滤器列表中，而是通过 <code class="xref py py-data docutils literal notranslate"><span class="pre">sys.warningoptions</span></code> 进行配置。</p>
|
||
</div>
|
||
</section>
|
||
<section id="overriding-the-default-filter">
|
||
<span id="warning-disable"></span><h3>重写默认的过滤器<a class="headerlink" href="#overriding-the-default-filter" title="永久链接至标题">¶</a></h3>
|
||
<p>Python 应用程序的开发人员可能希望在默认情况下向用户隐藏 <em>所有</em> Python级别的警告，而只在运行测试或其他调试时显示这些警告。用于向解释器传递过滤器配置的 <code class="xref py py-data docutils literal notranslate"><span class="pre">sys.warningoptions</span></code> 属性可以作为一个标记，表示是否应该禁用警告：</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">sys</span>
|
||
|
||
<span class="k">if</span> <span class="ow">not</span> <span class="n">sys</span><span class="o">.</span><span class="n">warnoptions</span><span class="p">:</span>
|
||
<span class="kn">import</span> <span class="nn">warnings</span>
|
||
<span class="n">warnings</span><span class="o">.</span><span class="n">simplefilter</span><span class="p">(</span><span class="s2">"ignore"</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>建议 Python 代码测试的开发者使用如下代码，以确保被测代码默认显示 <em>所有</em> 警告：</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">sys</span>
|
||
|
||
<span class="k">if</span> <span class="ow">not</span> <span class="n">sys</span><span class="o">.</span><span class="n">warnoptions</span><span class="p">:</span>
|
||
<span class="kn">import</span> <span class="nn">os</span><span class="o">,</span> <span class="nn">warnings</span>
|
||
<span class="n">warnings</span><span class="o">.</span><span class="n">simplefilter</span><span class="p">(</span><span class="s2">"default"</span><span class="p">)</span> <span class="c1"># Change the filter in this process</span>
|
||
<span class="n">os</span><span class="o">.</span><span class="n">environ</span><span class="p">[</span><span class="s2">"PYTHONWARNINGS"</span><span class="p">]</span> <span class="o">=</span> <span class="s2">"default"</span> <span class="c1"># Also affect subprocesses</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>最后，建议在 <code class="docutils literal notranslate"><span class="pre">__main__</span></code> 以外的命名空间运行用户代码的交互式开发者，请确保 <a class="reference internal" href="exceptions.html#DeprecationWarning" title="DeprecationWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">DeprecationWarning</span></code></a> 在默认情况下是可见的，可采用如下代码（这里 <code class="docutils literal notranslate"><span class="pre">user_ns</span></code> 是用于执行交互式输入代码的模块）：</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">warnings</span>
|
||
<span class="n">warnings</span><span class="o">.</span><span class="n">filterwarnings</span><span class="p">(</span><span class="s2">"default"</span><span class="p">,</span> <span class="n">category</span><span class="o">=</span><span class="ne">DeprecationWarning</span><span class="p">,</span>
|
||
<span class="n">module</span><span class="o">=</span><span class="n">user_ns</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">"__name__"</span><span class="p">))</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
</section>
|
||
<section id="temporarily-suppressing-warnings">
|
||
<span id="warning-suppress"></span><h2>暂时禁止警告<a class="headerlink" href="#temporarily-suppressing-warnings" title="永久链接至标题">¶</a></h2>
|
||
<p>如果明知正在使用会引起警告的代码，比如某个废弃函数，但不想看到警告（即便警告已经通过命令行作了显式配置），那么可以使用 <a class="reference internal" href="#warnings.catch_warnings" title="warnings.catch_warnings"><code class="xref py py-class docutils literal notranslate"><span class="pre">catch_warnings</span></code></a> 上下文管理器来抑制警告。</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">warnings</span>
|
||
|
||
<span class="k">def</span> <span class="nf">fxn</span><span class="p">():</span>
|
||
<span class="n">warnings</span><span class="o">.</span><span class="n">warn</span><span class="p">(</span><span class="s2">"deprecated"</span><span class="p">,</span> <span class="ne">DeprecationWarning</span><span class="p">)</span>
|
||
|
||
<span class="k">with</span> <span class="n">warnings</span><span class="o">.</span><span class="n">catch_warnings</span><span class="p">():</span>
|
||
<span class="n">warnings</span><span class="o">.</span><span class="n">simplefilter</span><span class="p">(</span><span class="s2">"ignore"</span><span class="p">)</span>
|
||
<span class="n">fxn</span><span class="p">()</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>在上下文管理器中，所有的警告将被简单地忽略。这样就能使用已知的过时代码而又不必看到警告，同时也不会限制警告其他可能不知过时的代码。注意：只能保证在单线程应用程序中生效。如果两个以上的线程同时使用 <a class="reference internal" href="#warnings.catch_warnings" title="warnings.catch_warnings"><code class="xref py py-class docutils literal notranslate"><span class="pre">catch_warnings</span></code></a> 上下文管理器，行为不可预知。</p>
|
||
</section>
|
||
<section id="testing-warnings">
|
||
<span id="warning-testing"></span><h2>测试警告<a class="headerlink" href="#testing-warnings" title="永久链接至标题">¶</a></h2>
|
||
<p>要测试由代码引发的警告，请采用 <a class="reference internal" href="#warnings.catch_warnings" title="warnings.catch_warnings"><code class="xref py py-class docutils literal notranslate"><span class="pre">catch_warnings</span></code></a> 上下文管理器。有了它，就可以临时改变警告过滤器以方便测试。例如，以下代码可捕获所有的警告以便查看：</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">warnings</span>
|
||
|
||
<span class="k">def</span> <span class="nf">fxn</span><span class="p">():</span>
|
||
<span class="n">warnings</span><span class="o">.</span><span class="n">warn</span><span class="p">(</span><span class="s2">"deprecated"</span><span class="p">,</span> <span class="ne">DeprecationWarning</span><span class="p">)</span>
|
||
|
||
<span class="k">with</span> <span class="n">warnings</span><span class="o">.</span><span class="n">catch_warnings</span><span class="p">(</span><span class="n">record</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span> <span class="k">as</span> <span class="n">w</span><span class="p">:</span>
|
||
<span class="c1"># Cause all warnings to always be triggered.</span>
|
||
<span class="n">warnings</span><span class="o">.</span><span class="n">simplefilter</span><span class="p">(</span><span class="s2">"always"</span><span class="p">)</span>
|
||
<span class="c1"># Trigger a warning.</span>
|
||
<span class="n">fxn</span><span class="p">()</span>
|
||
<span class="c1"># Verify some things</span>
|
||
<span class="k">assert</span> <span class="nb">len</span><span class="p">(</span><span class="n">w</span><span class="p">)</span> <span class="o">==</span> <span class="mi">1</span>
|
||
<span class="k">assert</span> <span class="nb">issubclass</span><span class="p">(</span><span class="n">w</span><span class="p">[</span><span class="o">-</span><span class="mi">1</span><span class="p">]</span><span class="o">.</span><span class="n">category</span><span class="p">,</span> <span class="ne">DeprecationWarning</span><span class="p">)</span>
|
||
<span class="k">assert</span> <span class="s2">"deprecated"</span> <span class="ow">in</span> <span class="nb">str</span><span class="p">(</span><span class="n">w</span><span class="p">[</span><span class="o">-</span><span class="mi">1</span><span class="p">]</span><span class="o">.</span><span class="n">message</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>也可以用 <code class="docutils literal notranslate"><span class="pre">error</span></code> 取代 <code class="docutils literal notranslate"><span class="pre">always</span></code> ，让所有的警告都成为异常。需要注意的是，如果某条警告已经因为 <code class="docutils literal notranslate"><span class="pre">once</span></code> / <code class="docutils literal notranslate"><span class="pre">default</span></code> 规则而被引发，那么无论设置什么过滤器，该条警告都不会再出现，除非该警告有关的注册数据被清除。</p>
|
||
<p>一旦上下文管理器退出，警告过滤器将恢复到刚进此上下文时的状态。这样在多次测试时可防止意外改变警告过滤器，从而导致不确定的测试结果。模块中的 <a class="reference internal" href="#warnings.showwarning" title="warnings.showwarning"><code class="xref py py-func docutils literal notranslate"><span class="pre">showwarning()</span></code></a> 函数也被恢复到初始值。注意：这只能在单线程应用程序中得到保证。如果两个以上的线程同时使用 <a class="reference internal" href="#warnings.catch_warnings" title="warnings.catch_warnings"><code class="xref py py-class docutils literal notranslate"><span class="pre">catch_warnings</span></code></a> 上下文管理器，行为未定义。</p>
|
||
<p>当测试多项操作会引发同类警告时，重点是要确保每次操作都会触发新的警告（比如，将警告设置为异常并检查操作是否触发异常，检查每次操作后警告列表的长度是否有增加，否则就在每次新操作前将以前的警告列表项删除）。</p>
|
||
</section>
|
||
<section id="updating-code-for-new-versions-of-dependencies">
|
||
<span id="warning-ignored"></span><h2>为新版本的依赖关系更新代码<a class="headerlink" href="#updating-code-for-new-versions-of-dependencies" title="永久链接至标题">¶</a></h2>
|
||
<p>在默认情况下，主要针对 Python 开发者（而不是 Python 应用程序的最终用户）的警告类别，会被忽略。</p>
|
||
<p>值得注意的是，这个“默认忽略”的列表包含 <a class="reference internal" href="exceptions.html#DeprecationWarning" title="DeprecationWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">DeprecationWarning</span></code></a> （适用于每个模块，除了 <code class="docutils literal notranslate"><span class="pre">__main__</span></code>），这意味着开发人员应该确保在测试代码时应将通常忽略的警告显示出来，以便未来破坏性 API 变化时及时收到通知（无论是在标准库还是第三方包）。</p>
|
||
<p>理想情况下，代码会有一个合适的测试套件，在运行测试时会隐含地启用所有警告（由 <a class="reference internal" href="unittest.html#module-unittest" title="unittest: Unit testing framework for Python."><code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest</span></code></a> 模块提供的测试运行程序就是如此）。</p>
|
||
<p>在不太理想的情况下，可以通过向 Python 解释器传入 <a class="reference internal" href="../using/cmdline.html#cmdoption-w"><code class="xref std std-option docutils literal notranslate"><span class="pre">-Wd</span></code></a> (这是 <code class="xref std std-option docutils literal notranslate"><span class="pre">-W</span> <span class="pre">default</span></code> 的简写) 或设置环境变量 <code class="docutils literal notranslate"><span class="pre">PYTHONWARNINGS=default</span></code> 来检查应用程序是否用到了已弃用的接口。 这样可以启用对所有警告的默认处理操作，包括那些默认忽略的警告。 要改变遇到警告后执行的动作，可以改变传给 <a class="reference internal" href="../using/cmdline.html#cmdoption-w"><code class="xref std std-option docutils literal notranslate"><span class="pre">-W</span></code></a> 的参数 (例如 <code class="xref std std-option docutils literal notranslate"><span class="pre">-W</span> <span class="pre">error</span></code>)。 请参阅 <a class="reference internal" href="../using/cmdline.html#cmdoption-w"><code class="xref std std-option docutils literal notranslate"><span class="pre">-W</span></code></a> 旗标来了解更多的细节。</p>
|
||
</section>
|
||
<section id="available-functions">
|
||
<span id="warning-functions"></span><h2>可用的函数<a class="headerlink" href="#available-functions" title="永久链接至标题">¶</a></h2>
|
||
<dl class="function">
|
||
<dt id="warnings.warn">
|
||
<code class="sig-prename descclassname">warnings.</code><code class="sig-name descname">warn</code><span class="sig-paren">(</span><em class="sig-param">message</em>, <em class="sig-param">category=None</em>, <em class="sig-param">stacklevel=1</em>, <em class="sig-param">source=None</em><span class="sig-paren">)</span><a class="headerlink" href="#warnings.warn" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>引发警告、忽略或者触发异常。 如果给出 <em>category</em> 参数，则必须是 <a class="reference internal" href="#warning-categories"><span class="std std-ref">警告类别类</span></a> ；默认为 <a class="reference internal" href="exceptions.html#UserWarning" title="UserWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">UserWarning</span></code></a>。 或者 <em>message</em> 可为 <a class="reference internal" href="exceptions.html#Warning" title="Warning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">Warning</span></code></a> 的实例，这时 <em>category</em> 将被忽略，转而采用 <code class="docutils literal notranslate"><span class="pre">message.__class__</span></code>。 在这种情况下，错误信息文本将是 <code class="docutils literal notranslate"><span class="pre">str(message)</span></code>。 如果某条警告被 <a class="reference internal" href="#warning-filter"><span class="std std-ref">警告过滤器</span></a> 改成了错误，本函数将触发一条异常。 参数 <em>stacklevel</em> 可供 Python 包装函数使用，比如:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">deprecation</span><span class="p">(</span><span class="n">message</span><span class="p">):</span>
|
||
<span class="n">warnings</span><span class="o">.</span><span class="n">warn</span><span class="p">(</span><span class="n">message</span><span class="p">,</span> <span class="ne">DeprecationWarning</span><span class="p">,</span> <span class="n">stacklevel</span><span class="o">=</span><span class="mi">2</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>这会让警告指向 <code class="xref py py-func docutils literal notranslate"><span class="pre">deprecation()</span></code> 的调用者，而不是 <code class="xref py py-func docutils literal notranslate"><span class="pre">deprecation()</span></code> 本身的来源（因为后者会破坏引发警告的目的）。</p>
|
||
<p><em>source</em> 是发出 <a class="reference internal" href="exceptions.html#ResourceWarning" title="ResourceWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ResourceWarning</span></code></a> 的被销毁对象。</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.6 版更改: </span>加入 <em>source</em> 参数。</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="warnings.warn_explicit">
|
||
<code class="sig-prename descclassname">warnings.</code><code class="sig-name descname">warn_explicit</code><span class="sig-paren">(</span><em class="sig-param">message</em>, <em class="sig-param">category</em>, <em class="sig-param">filename</em>, <em class="sig-param">lineno</em>, <em class="sig-param">module=None</em>, <em class="sig-param">registry=None</em>, <em class="sig-param">module_globals=None</em>, <em class="sig-param">source=None</em><span class="sig-paren">)</span><a class="headerlink" href="#warnings.warn_explicit" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>这是 <a class="reference internal" href="#warnings.warn" title="warnings.warn"><code class="xref py py-func docutils literal notranslate"><span class="pre">warn()</span></code></a> 函数的底层接口，显式传入消息、类别、文件名和行号，以及可选的模块名和注册表（应为模块的 <code class="docutils literal notranslate"><span class="pre">__warningregistry__</span></code> 字典）。 模块名称默认为去除了 <code class="docutils literal notranslate"><span class="pre">.py</span></code> 的文件名；如果未传递注册表，警告就不会被抑制。 <em>message</em> 必须是个字符串，<em>category</em> 是 <a class="reference internal" href="exceptions.html#Warning" title="Warning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">Warning</span></code></a> 的子类；或者*message* 可为 <a class="reference internal" href="exceptions.html#Warning" title="Warning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">Warning</span></code></a> 的实例，且 <em>category</em> 将被忽略。</p>
|
||
<p><em>module_globals</em> 应为发出警告的代码所用的全局命名空间。（该参数用于从 zip 文件或其他非文件系统导入模块时显式源码）。</p>
|
||
<p><em>source</em> 是发出 <a class="reference internal" href="exceptions.html#ResourceWarning" title="ResourceWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ResourceWarning</span></code></a> 的被销毁对象。</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.6 版更改: </span>加入 <em>source</em> 参数。</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="warnings.showwarning">
|
||
<code class="sig-prename descclassname">warnings.</code><code class="sig-name descname">showwarning</code><span class="sig-paren">(</span><em class="sig-param">message</em>, <em class="sig-param">category</em>, <em class="sig-param">filename</em>, <em class="sig-param">lineno</em>, <em class="sig-param">file=None</em>, <em class="sig-param">line=None</em><span class="sig-paren">)</span><a class="headerlink" href="#warnings.showwarning" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>将警告信息写入文件。默认的实现代码是调用 <code class="docutils literal notranslate"><span class="pre">formatwarning(message,</span> <span class="pre">category,</span> <span class="pre">filename,</span> <span class="pre">lineno,</span> <span class="pre">line)</span></code> 并将结果字符串写入 <em>file</em> ，默认文件为 <a class="reference internal" href="sys.html#sys.stderr" title="sys.stderr"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.stderr</span></code></a>。通过将任何可调用对象赋给 <code class="docutils literal notranslate"><span class="pre">warnings.showwarning</span></code> 可替换掉该函数。<em>line</em> 是要包含在警告信息中的一行源代码；如果未提供 <em>line</em>，<a class="reference internal" href="#warnings.showwarning" title="warnings.showwarning"><code class="xref py py-func docutils literal notranslate"><span class="pre">showwarning()</span></code></a> 将尝试读取由*filename* 和 <em>lineno</em> 指定的行。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="warnings.formatwarning">
|
||
<code class="sig-prename descclassname">warnings.</code><code class="sig-name descname">formatwarning</code><span class="sig-paren">(</span><em class="sig-param">message</em>, <em class="sig-param">category</em>, <em class="sig-param">filename</em>, <em class="sig-param">lineno</em>, <em class="sig-param">line=None</em><span class="sig-paren">)</span><a class="headerlink" href="#warnings.formatwarning" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>以标准方式格式化一条警告信息。将返回一个字符串，可能包含内嵌的换行符，并以换行符结束。如果未提供 <em>line</em>，<a class="reference internal" href="#warnings.formatwarning" title="warnings.formatwarning"><code class="xref py py-func docutils literal notranslate"><span class="pre">formatwarning()</span></code></a> 将尝试读取由 <em>filename</em> 和 <em>lineno</em> 指定的行。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="warnings.filterwarnings">
|
||
<code class="sig-prename descclassname">warnings.</code><code class="sig-name descname">filterwarnings</code><span class="sig-paren">(</span><em class="sig-param">action</em>, <em class="sig-param">message=''</em>, <em class="sig-param">category=Warning</em>, <em class="sig-param">module=''</em>, <em class="sig-param">lineno=0</em>, <em class="sig-param">append=False</em><span class="sig-paren">)</span><a class="headerlink" href="#warnings.filterwarnings" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>在 <a class="reference internal" href="#warning-filter"><span class="std std-ref">警告过滤器种类</span></a> 列表中插入一条数据项。默认情况下，该数据项将被插到前面；如果 <em>append</em> 为 True，则会插到后面。这里会检查参数的类型，编译 <em>message</em> 和 <em>module</em> 正则表达式，并将他们作为一个元组插入警告过滤器的列表中。如果两者都与某种警告匹配，那么靠近列表前面的数据项就会覆盖后面的项。省略的参数默认匹配任意值。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="warnings.simplefilter">
|
||
<code class="sig-prename descclassname">warnings.</code><code class="sig-name descname">simplefilter</code><span class="sig-paren">(</span><em class="sig-param">action</em>, <em class="sig-param">category=Warning</em>, <em class="sig-param">lineno=0</em>, <em class="sig-param">append=False</em><span class="sig-paren">)</span><a class="headerlink" href="#warnings.simplefilter" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>在 <a class="reference internal" href="#warning-filter"><span class="std std-ref">警告过滤器种类</span></a> 列表中插入一条简单数据项。函数参数的含义与 <a class="reference internal" href="#warnings.filterwarnings" title="warnings.filterwarnings"><code class="xref py py-func docutils literal notranslate"><span class="pre">filterwarnings()</span></code></a> 相同，但不需要正则表达式，因为插入的过滤器总是匹配任何模块中的任何信息，只要类别和行号匹配即可。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="warnings.resetwarnings">
|
||
<code class="sig-prename descclassname">warnings.</code><code class="sig-name descname">resetwarnings</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#warnings.resetwarnings" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>重置警告过滤器。这将丢弃之前对 <a class="reference internal" href="#warnings.filterwarnings" title="warnings.filterwarnings"><code class="xref py py-func docutils literal notranslate"><span class="pre">filterwarnings()</span></code></a> 的所有调用，包括 <a class="reference internal" href="../using/cmdline.html#cmdoption-w"><code class="xref std std-option docutils literal notranslate"><span class="pre">-W</span></code></a> 命令行选项和对 <a class="reference internal" href="#warnings.simplefilter" title="warnings.simplefilter"><code class="xref py py-func docutils literal notranslate"><span class="pre">simplefilter()</span></code></a> 的调用效果。</p>
|
||
</dd></dl>
|
||
|
||
</section>
|
||
<section id="available-context-managers">
|
||
<h2>可用的上下文管理器<a class="headerlink" href="#available-context-managers" title="永久链接至标题">¶</a></h2>
|
||
<dl class="class">
|
||
<dt id="warnings.catch_warnings">
|
||
<em class="property">class </em><code class="sig-prename descclassname">warnings.</code><code class="sig-name descname">catch_warnings</code><span class="sig-paren">(</span><em class="sig-param">*</em>, <em class="sig-param">record=False</em>, <em class="sig-param">module=None</em><span class="sig-paren">)</span><a class="headerlink" href="#warnings.catch_warnings" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>该上下文管理器会复制警告过滤器和 <a class="reference internal" href="#warnings.showwarning" title="warnings.showwarning"><code class="xref py py-func docutils literal notranslate"><span class="pre">showwarning()</span></code></a> 函数，并在退出时恢复。 如果 <em>record</em> 参数是 <a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a> (默认)，则在进入时会返回 <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-class docutils literal notranslate"><span class="pre">None</span></code></a>。 如果 <em>record</em> 为 <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a>，则返回一个列表，列表由自定义 <a class="reference internal" href="#warnings.showwarning" title="warnings.showwarning"><code class="xref py py-func docutils literal notranslate"><span class="pre">showwarning()</span></code></a> 函数所用对象逐步填充（该函数还会抑制 <code class="docutils literal notranslate"><span class="pre">sys.stdout</span></code> 的输出）。 列表中每个对象的属性与 <a class="reference internal" href="#warnings.showwarning" title="warnings.showwarning"><code class="xref py py-func docutils literal notranslate"><span class="pre">showwarning()</span></code></a> 的参数名称相同。</p>
|
||
<p><em>module</em> 参数代表一个模块，当导入 <a class="reference internal" href="#module-warnings" title="warnings: Issue warning messages and control their disposition."><code class="xref py py-mod docutils literal notranslate"><span class="pre">warnings</span></code></a> 时，将被用于代替返回的模块，其过滤器将被保护。该参数主要是为了测试 <a class="reference internal" href="#module-warnings" title="warnings: Issue warning messages and control their disposition."><code class="xref py py-mod docutils literal notranslate"><span class="pre">warnings</span></code></a> 模块自身。</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">注解</p>
|
||
<p><a class="reference internal" href="#warnings.catch_warnings" title="warnings.catch_warnings"><code class="xref py py-class docutils literal notranslate"><span class="pre">catch_warnings</span></code></a> 管理器的工作方式，是替换并随后恢复模块的 <a class="reference internal" href="#warnings.showwarning" title="warnings.showwarning"><code class="xref py py-func docutils literal notranslate"><span class="pre">showwarning()</span></code></a> 函数和内部的过滤器种类列表。这意味着上下文管理器将会修改全局状态，因此不是线程安全的。</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
</section>
|
||
</section>
|
||
|
||
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
||
<div class="sphinxsidebarwrapper">
|
||
<h3><a href="../contents.html">目录</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">warnings</span></code> ——控制警告信息</a><ul>
|
||
<li><a class="reference internal" href="#warning-categories">警告类别</a></li>
|
||
<li><a class="reference internal" href="#the-warnings-filter">警告过滤器</a><ul>
|
||
<li><a class="reference internal" href="#describing-warning-filters">警告过滤器的介绍</a></li>
|
||
<li><a class="reference internal" href="#default-warning-filter">默认警告过滤器</a></li>
|
||
<li><a class="reference internal" href="#overriding-the-default-filter">重写默认的过滤器</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#temporarily-suppressing-warnings">暂时禁止警告</a></li>
|
||
<li><a class="reference internal" href="#testing-warnings">测试警告</a></li>
|
||
<li><a class="reference internal" href="#updating-code-for-new-versions-of-dependencies">为新版本的依赖关系更新代码</a></li>
|
||
<li><a class="reference internal" href="#available-functions">可用的函数</a></li>
|
||
<li><a class="reference internal" href="#available-context-managers">可用的上下文管理器</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
<h4>上一个主题</h4>
|
||
<p class="topless"><a href="__main__.html"
|
||
title="上一章"><code class="xref py py-mod docutils literal notranslate"><span class="pre">__main__</span></code> --- 顶层脚本环境</a></p>
|
||
<h4>下一个主题</h4>
|
||
<p class="topless"><a href="dataclasses.html"
|
||
title="下一章"><code class="xref py py-mod docutils literal notranslate"><span class="pre">dataclasses</span></code> --- 数据类</a></p>
|
||
<div role="note" aria-label="source link">
|
||
<h3>本页</h3>
|
||
<ul class="this-page-menu">
|
||
<li><a href="../bugs.html">报告 Bug</a></li>
|
||
<li>
|
||
<a href="https://github.com/python/cpython/blob/3.8/Doc/library/warnings.rst"
|
||
rel="nofollow">显示源代码
|
||
</a>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="clearer"></div>
|
||
</div>
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<h3>导航</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="总目录"
|
||
>索引</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python 模块索引"
|
||
>模块</a> |</li>
|
||
<li class="right" >
|
||
<a href="dataclasses.html" title="dataclasses --- 数据类"
|
||
>下一页</a> |</li>
|
||
<li class="right" >
|
||
<a href="__main__.html" title="__main__ --- 顶层脚本环境"
|
||
>上一页</a> |</li>
|
||
|
||
<li><img src="../_static/py.svg" alt="python logo" style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li class="switchers">
|
||
<div class="language_switcher_placeholder"></div>
|
||
<div class="version_switcher_placeholder"></div>
|
||
</li>
|
||
<li>
|
||
|
||
</li>
|
||
<li id="cpython-language-and-version">
|
||
<a href="../index.html">3.8.20 Documentation</a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >Python 标准库</a> »</li>
|
||
<li class="nav-item nav-item-2"><a href="python.html" >Python 运行时服务</a> »</li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="快速搜索" aria-label="快速搜索" type="text" name="q" />
|
||
<input type="submit" value="转向" />
|
||
<input type="hidden" name="check_keywords" value="yes" />
|
||
<input type="hidden" name="area" value="default" />
|
||
</form>
|
||
</div>
|
||
|
|
||
</li>
|
||
|
||
</ul>
|
||
</div>
|
||
<div class="footer">
|
||
© <a href="../copyright.html">版权所有</a> 2001-2024, Python Software Foundation.
|
||
<br />
|
||
This page is licensed under the Python Software Foundation License Version 2.
|
||
<br />
|
||
Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.
|
||
<br />
|
||
|
||
<br />
|
||
|
||
The Python Software Foundation is a non-profit corporation.
|
||
<a href="https://www.python.org/psf/donations/">Please donate.</a>
|
||
<br />
|
||
<br />
|
||
|
||
最后更新于 12月 09, 2024.
|
||
<a href="https://docs.python.org/3/bugs.html">Found a bug</a>?
|
||
<br />
|
||
|
||
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 2.4.4.
|
||
</div>
|
||
|
||
</body>
|
||
</html> |