1207 lines
139 KiB
HTML
1207 lines
139 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>logging --- Python 的日志记录工具 — 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="logging.config --- 日志记录配置" href="logging.config.html" />
|
||
<link rel="prev" title="getopt --- C 风格的命令行选项解析器" href="getopt.html" />
|
||
<link rel="canonical" href="https://docs.python.org/3/library/logging.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">logging</span></code> --- Python 的日志记录工具</a><ul>
|
||
<li><a class="reference internal" href="#logger-objects">记录器对象</a></li>
|
||
<li><a class="reference internal" href="#logging-levels">日志级别</a></li>
|
||
<li><a class="reference internal" href="#handler-objects">处理器对象</a></li>
|
||
<li><a class="reference internal" href="#formatter-objects">格式器对象</a></li>
|
||
<li><a class="reference internal" href="#filter-objects">过滤器对象</a></li>
|
||
<li><a class="reference internal" href="#logrecord-objects">LogRecord 属性</a></li>
|
||
<li><a class="reference internal" href="#logrecord-attributes">LogRecord 属性</a></li>
|
||
<li><a class="reference internal" href="#loggeradapter-objects">LoggerAdapter 对象</a></li>
|
||
<li><a class="reference internal" href="#thread-safety">线程安全</a></li>
|
||
<li><a class="reference internal" href="#module-level-functions">模块级函数</a></li>
|
||
<li><a class="reference internal" href="#module-level-attributes">模块级属性</a></li>
|
||
<li><a class="reference internal" href="#integration-with-the-warnings-module">与警告模块集成</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
<h4>上一个主题</h4>
|
||
<p class="topless"><a href="getopt.html"
|
||
title="上一章"><code class="xref py py-mod docutils literal notranslate"><span class="pre">getopt</span></code> --- C 风格的命令行选项解析器</a></p>
|
||
<h4>下一个主题</h4>
|
||
<p class="topless"><a href="logging.config.html"
|
||
title="下一章"><code class="xref py py-mod docutils literal notranslate"><span class="pre">logging.config</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/logging.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/logging.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="logging.config.html" title="logging.config --- 日志记录配置"
|
||
accesskey="N">下一页</a> |</li>
|
||
<li class="right" >
|
||
<a href="getopt.html" title="getopt --- C 风格的命令行选项解析器"
|
||
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="allos.html" accesskey="U">通用操作系统服务</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-logging">
|
||
<span id="logging-logging-facility-for-python"></span><h1><a class="reference internal" href="#module-logging" title="logging: Flexible event logging system for applications."><code class="xref py py-mod docutils literal notranslate"><span class="pre">logging</span></code></a> --- Python 的日志记录工具<a class="headerlink" href="#module-logging" title="永久链接至标题">¶</a></h1>
|
||
<p><strong>源代码：</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.8/Lib/logging/__init__.py">Lib/logging/__init__.py</a></p>
|
||
<aside class="sidebar" id="index-0">
|
||
<p class="sidebar-title">Important</p>
|
||
<p>此页面仅包含 API 参考信息。教程信息和更多高级用法的讨论，请参阅</p>
|
||
<ul class="simple">
|
||
<li><p><a class="reference internal" href="../howto/logging.html#logging-basic-tutorial"><span class="std std-ref">基础教程</span></a></p></li>
|
||
<li><p><a class="reference internal" href="../howto/logging.html#logging-advanced-tutorial"><span class="std std-ref">进阶教程</span></a></p></li>
|
||
<li><p><a class="reference internal" href="../howto/logging-cookbook.html#logging-cookbook"><span class="std std-ref">日志记录操作手册</span></a></p></li>
|
||
</ul>
|
||
</aside>
|
||
<hr class="docutils" />
|
||
<p>这个模块为应用与库实现了灵活的事件日志系统的函数与类。</p>
|
||
<p>使用标准库提供的 logging API 最主要的好处是，所有的 Python 模块都可能参与日志输出，包括你自己的日志消息和第三方模块的日志消息。</p>
|
||
<p>这个模块提供许多强大而灵活的功能。如果对 logging 不太熟悉， 掌握它最好的方式就是查看它对应的教程（详见右侧的链接）。</p>
|
||
<p>该模块定义的基础类和函数都列在下面。</p>
|
||
<ul class="simple">
|
||
<li><p>记录器暴露了应用程序代码直接使用的接口。</p></li>
|
||
<li><p>处理器将日志记录（由记录器创建）发送到适当的目标。</p></li>
|
||
<li><p>过滤器提供了更细粒度的功能，用于确定要输出的日志记录。</p></li>
|
||
<li><p>格式器指定最终输出中日志记录的样式。</p></li>
|
||
</ul>
|
||
<section id="logger-objects">
|
||
<span id="logger"></span><h2>记录器对象<a class="headerlink" href="#logger-objects" title="永久链接至标题">¶</a></h2>
|
||
<p>记录器有以下的属性和方法。注意 <em>永远</em> 不要直接实例化记录器，应当通过模块级别的函数 <code class="docutils literal notranslate"><span class="pre">logging.getLogger(name)</span></code> 。多次使用相同的名字调用 <a class="reference internal" href="#logging.getLogger" title="logging.getLogger"><code class="xref py py-func docutils literal notranslate"><span class="pre">getLogger()</span></code></a> 会一直返回相同的 Logger 对象的引用。</p>
|
||
<p><code class="docutils literal notranslate"><span class="pre">name</span></code> 一般是句点分割的层级值, 像 <code class="docutils literal notranslate"><span class="pre">foo.bar.baz</span></code> (尽管也可以只是普通的 <code class="docutils literal notranslate"><span class="pre">foo</span></code>)。层次结构列表中位于下方的记录器是列表中较高位置的记录器的子级。例如，有个名叫 <code class="docutils literal notranslate"><span class="pre">foo</span></code> 的记录器，而名字是 <code class="docutils literal notranslate"><span class="pre">foo.bar</span></code>， <code class="docutils literal notranslate"><span class="pre">foo.bar.baz</span></code>，和 <code class="docutils literal notranslate"><span class="pre">foo.bam</span></code> 的记录器都是 <code class="docutils literal notranslate"><span class="pre">foo</span></code> 的子级。记录器的名字分级类似 Python 包的层级，如果您使用建议的结构 <code class="docutils literal notranslate"><span class="pre">logging.getLogger(__name__)</span></code> 在每个模块的基础上组织记录器，则与之完全相同。这是因为在模块里， <code class="docutils literal notranslate"><span class="pre">__name__</span></code> 是该模块在 Python 包命名空间中的名字。</p>
|
||
<dl class="class">
|
||
<dt id="logging.Logger">
|
||
<em class="property">class </em><code class="sig-prename descclassname">logging.</code><code class="sig-name descname">Logger</code><a class="headerlink" href="#logging.Logger" title="永久链接至目标">¶</a></dt>
|
||
<dd><dl class="attribute">
|
||
<dt id="logging.Logger.propagate">
|
||
<code class="sig-name descname">propagate</code><a class="headerlink" href="#logging.Logger.propagate" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>如果这个属性为真，记录到这个记录器的事件除了会发送到此记录器的所有处理程序外，还会传递给更高级别（祖先）记录器的处理器，此外任何关联到这个记录器的处理器。消息会直接传递给祖先记录器的处理器 —— 不考虑祖先记录器的级别和过滤器。</p>
|
||
<p>如果为假，记录消息将不会传递给当前记录器的祖先记录器的处理器。</p>
|
||
<p>构造器将这个属性初始化为 <code class="docutils literal notranslate"><span class="pre">True</span></code>。</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">注解</p>
|
||
<p>如果你将一个处理器附加到一个记录器 <em>和</em> 其一个或多个祖先记录器，它可能发出多次相同的记录。通常，您不需要将一个处理器附加到一个以上的记录器上 —— 如果您将它附加到记录器层次结构中最高的适当记录器上，则它将看到所有后代记录器记录的所有事件，前提是它们的传播设置保留为 <code class="docutils literal notranslate"><span class="pre">True</span></code>。一种常见的方案是仅将处理器附加到根记录器，通过传播来处理其余部分。</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="logging.Logger.setLevel">
|
||
<code class="sig-name descname">setLevel</code><span class="sig-paren">(</span><em class="sig-param">level</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.Logger.setLevel" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>给记录器设置阈值为 <em>level</em> 。日志等级小于 <em>level</em> 会被忽略。严重性为 <em>level</em> 或更高的日志消息将由该记录器的任何一个或多个处理器发出，除非将处理器的级别设置为比 <em>level</em> 更高的级别。</p>
|
||
<p>创建记录器时，级别默认设置为 <code class="xref py py-const docutils literal notranslate"><span class="pre">NOTSET</span></code> （当记录器是根记录器时，将处理所有消息；如果记录器不是根记录器，则将委托给父级）。请注意，根记录器的默认级别为 <code class="xref py py-const docutils literal notranslate"><span class="pre">WARNING</span></code> 。</p>
|
||
<p>委派给父级的意思是如果一个记录器的级别设置为 NOTSET，将遍历其祖先记录器，直到找到级别不是 NOTSET 的记录器，或者到根记录器为止。</p>
|
||
<p>如果发现某个父级的级别不是 NOTSET ，那么该父级的级别将被视为发起搜索的记录器的有效级别，并用于确定如何处理日志事件。</p>
|
||
<p>如果搜索到达根记录器，并且其级别为 NOTSET，则将处理所有消息。否则，将使用根记录器的级别作为有效级别。</p>
|
||
<p>参见 <a class="reference internal" href="#levels"><span class="std std-ref">日志级别</span></a> 级别列表。</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.2 版更改: </span>现在 <em>level</em> 参数可以接受形如 'INFO' 的级别字符串表示形式，以代替形如 <code class="xref py py-const docutils literal notranslate"><span class="pre">INFO</span></code> 的整数常量。 但是请注意，级别在内部存储为整数，并且 <a class="reference internal" href="#logging.Logger.getEffectiveLevel" title="logging.Logger.getEffectiveLevel"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getEffectiveLevel()</span></code></a> 和 <a class="reference internal" href="#logging.Logger.isEnabledFor" title="logging.Logger.isEnabledFor"><code class="xref py py-meth docutils literal notranslate"><span class="pre">isEnabledFor()</span></code></a> 等方法的传入/返回值也为整数。</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="logging.Logger.isEnabledFor">
|
||
<code class="sig-name descname">isEnabledFor</code><span class="sig-paren">(</span><em class="sig-param">level</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.Logger.isEnabledFor" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>指示此记录器是否将处理级别为 <em>level</em> 的消息。此方法首先检查由 <code class="docutils literal notranslate"><span class="pre">logging.disable(level)</span></code> 设置的模块级的级别，然后检查由 <a class="reference internal" href="#logging.Logger.getEffectiveLevel" title="logging.Logger.getEffectiveLevel"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getEffectiveLevel()</span></code></a> 确定的记录器的有效级别。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="logging.Logger.getEffectiveLevel">
|
||
<code class="sig-name descname">getEffectiveLevel</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#logging.Logger.getEffectiveLevel" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>指示此记录器的有效级别。如果通过 <a class="reference internal" href="#logging.Logger.setLevel" title="logging.Logger.setLevel"><code class="xref py py-meth docutils literal notranslate"><span class="pre">setLevel()</span></code></a> 设置了除 <code class="xref py py-const docutils literal notranslate"><span class="pre">NOTSET</span></code> 以外的值，则返回该值。否则，将层次结构遍历到根，直到找到除 <code class="xref py py-const docutils literal notranslate"><span class="pre">NOTSET</span></code> 以外的其他值，然后返回该值。返回的值是一个整数，通常为 <code class="xref py py-const docutils literal notranslate"><span class="pre">logging.DEBUG</span></code>、 <code class="xref py py-const docutils literal notranslate"><span class="pre">logging.INFO</span></code> 等等。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="logging.Logger.getChild">
|
||
<code class="sig-name descname">getChild</code><span class="sig-paren">(</span><em class="sig-param">suffix</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.Logger.getChild" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>返回由后缀确定的该记录器的后代记录器。 因此，<code class="docutils literal notranslate"><span class="pre">logging.getLogger('abc').getChild('def.ghi')</span></code> 与 <code class="docutils literal notranslate"><span class="pre">logging.getLogger('abc.def.ghi')</span></code> 将返回相同的记录器。 这是一个便捷方法，当使用如 <code class="docutils literal notranslate"><span class="pre">__name__</span></code> 而不是字符串字面值命名父记录器时很有用。</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">3.2 新版功能.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="logging.Logger.debug">
|
||
<code class="sig-name descname">debug</code><span class="sig-paren">(</span><em class="sig-param">msg</em>, <em class="sig-param">*args</em>, <em class="sig-param">**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.Logger.debug" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>在此记录器上记录 <code class="xref py py-const docutils literal notranslate"><span class="pre">DEBUG</span></code> 级别的消息。 <em>msg</em> 是消息格式字符串，而 <em>args</em> 是用于字符串格式化操作合并到 <em>msg</em> 的参数。（请注意，这意味着您可以在格式字符串中使用关键字以及单个字典参数。）当未提供 <em>args</em> 时，不会对 <em>msg</em> 执行 ％ 格式化操作。</p>
|
||
<p>在 <em>kwargs</em> 中会检查四个关键字参数： <em>exc_info</em> ，<em>stack_info</em> ，<em>stacklevel</em> 和 <em>extra</em> 。</p>
|
||
<p>如果 <em>exc_info</em> 的求值结果不为 false ，则它将异常信息添加到日志消息中。如果提供了一个异常元组（按照 <a class="reference internal" href="sys.html#sys.exc_info" title="sys.exc_info"><code class="xref py py-func docutils literal notranslate"><span class="pre">sys.exc_info()</span></code></a> 返回的格式）或一个异常实例，则它将被使用；否则，调用 <a class="reference internal" href="sys.html#sys.exc_info" title="sys.exc_info"><code class="xref py py-func docutils literal notranslate"><span class="pre">sys.exc_info()</span></code></a> 以获取异常信息。</p>
|
||
<p>第二个可选关键字参数是 <em>stack_info</em>，默认为 <code class="docutils literal notranslate"><span class="pre">False</span></code>。如果为 True，则将堆栈信息添加到日志消息中，包括实际的日志调用。请注意，这与通过指定 <em>exc_info</em> 显示的堆栈信息不同：前者是从堆栈底部到当前线程中的日志记录调用的堆栈帧，而后者是在搜索异常处理程序时，跟踪异常而打开的堆栈帧的信息。</p>
|
||
<p>您可以独立于 <em>exc_info</em> 来指定 <em>stack_info</em>，例如，即使在未引发任何异常的情况下，也可以显示如何到达代码中的特定点。堆栈帧在标题行之后打印：</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>Stack (most recent call last):
|
||
</pre></div>
|
||
</div>
|
||
<p>这模仿了显示异常帧时所使用的 <code class="docutils literal notranslate"><span class="pre">Traceback</span> <span class="pre">(most</span> <span class="pre">recent</span> <span class="pre">call</span> <span class="pre">last):</span></code> 。</p>
|
||
<p>第三个可选关键字参数是 <em>stacklevel</em> ，默认为 <code class="docutils literal notranslate"><span class="pre">1</span></code> 。如果大于 1 ，则在为日志记录事件创建的 <a class="reference internal" href="#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a> 中计算行号和函数名时，将跳过相应数量的堆栈帧。可以在记录帮助器时使用它，以便记录的函数名称，文件名和行号不是帮助器的函数/方法的信息，而是其调用方的信息。此参数是 <a class="reference internal" href="warnings.html#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>
|
||
<p>第四个关键字参数是 <em>extra</em> ，传递一个字典，该字典用于填充为日志记录事件创建的、带有用户自定义属性的 <a class="reference internal" href="#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a> 中的 __dict__ 。然后可以按照需求使用这些自定义属性。例如，可以将它们合并到已记录的消息中：</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">FORMAT</span> <span class="o">=</span> <span class="s1">'</span><span class="si">%(asctime)-15s</span><span class="s1"> </span><span class="si">%(clientip)s</span><span class="s1"> </span><span class="si">%(user)-8s</span><span class="s1"> </span><span class="si">%(message)s</span><span class="s1">'</span>
|
||
<span class="n">logging</span><span class="o">.</span><span class="n">basicConfig</span><span class="p">(</span><span class="nb">format</span><span class="o">=</span><span class="n">FORMAT</span><span class="p">)</span>
|
||
<span class="n">d</span> <span class="o">=</span> <span class="p">{</span><span class="s1">'clientip'</span><span class="p">:</span> <span class="s1">'192.168.0.1'</span><span class="p">,</span> <span class="s1">'user'</span><span class="p">:</span> <span class="s1">'fbloggs'</span><span class="p">}</span>
|
||
<span class="n">logger</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="s1">'tcpserver'</span><span class="p">)</span>
|
||
<span class="n">logger</span><span class="o">.</span><span class="n">warning</span><span class="p">(</span><span class="s1">'Protocol problem: </span><span class="si">%s</span><span class="s1">'</span><span class="p">,</span> <span class="s1">'connection reset'</span><span class="p">,</span> <span class="n">extra</span><span class="o">=</span><span class="n">d</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>输出类似于</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>2006-02-08 22:20:02,165 192.168.0.1 fbloggs Protocol problem: connection reset
|
||
</pre></div>
|
||
</div>
|
||
<p><em>extra</em> 中传入的字典的键不应与日志系统使用的键冲突。（有关日志系统使用哪些键的更多信息，请参见 <a class="reference internal" href="#logging.Formatter" title="logging.Formatter"><code class="xref py py-class docutils literal notranslate"><span class="pre">Formatter</span></code></a> 的文档。）</p>
|
||
<p>如果在已记录的消息中使用这些属性，则需要格外小心。例如，在上面的示例中，<a class="reference internal" href="#logging.Formatter" title="logging.Formatter"><code class="xref py py-class docutils literal notranslate"><span class="pre">Formatter</span></code></a> 已设置了格式字符串，其在 <a class="reference internal" href="#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a> 的属性字典中键值为 “clientip” 和 “user”。如果缺少这些内容，则将不会记录该消息，因为会引发字符串格式化异常。因此，在这种情况下，您始终需要使用 <em>extra</em> 字典传递这些键。</p>
|
||
<p>尽管这可能很烦人，但此功能旨在用于特殊情况，例如在多个上下文中执行相同代码的多线程服务器，并且出现的有趣条件取决于此上下文（例如在上面的示例中就是远程客户端IP地址和已验证用户名）。在这种情况下，很可能将专门的 <a class="reference internal" href="#logging.Formatter" title="logging.Formatter"><code class="xref py py-class docutils literal notranslate"><span class="pre">Formatter</span></code></a> 与特定的 <a class="reference internal" href="#logging.Handler" title="logging.Handler"><code class="xref py py-class docutils literal notranslate"><span class="pre">Handler</span></code></a> 一起使用。</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.2 版更改: </span>增加了 <em>stack_info</em> 参数。</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.5 版更改: </span><em>exc_info</em> 参数现在可以接受异常实例。</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.8 版更改: </span>增加了 <em>stacklevel</em> 参数。</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="logging.Logger.info">
|
||
<code class="sig-name descname">info</code><span class="sig-paren">(</span><em class="sig-param">msg</em>, <em class="sig-param">*args</em>, <em class="sig-param">**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.Logger.info" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>在此记录器上记录 <code class="xref py py-const docutils literal notranslate"><span class="pre">INFO</span></code> 级别的消息。参数解释同 <a class="reference internal" href="#logging.debug" title="logging.debug"><code class="xref py py-meth docutils literal notranslate"><span class="pre">debug()</span></code></a>。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="logging.Logger.warning">
|
||
<code class="sig-name descname">warning</code><span class="sig-paren">(</span><em class="sig-param">msg</em>, <em class="sig-param">*args</em>, <em class="sig-param">**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.Logger.warning" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>在此记录器上记录 <code class="xref py py-const docutils literal notranslate"><span class="pre">WARNING</span></code> 级别的消息。参数解释同 <a class="reference internal" href="#logging.debug" title="logging.debug"><code class="xref py py-meth docutils literal notranslate"><span class="pre">debug()</span></code></a>。</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">注解</p>
|
||
<p>有一个功能上与 <code class="docutils literal notranslate"><span class="pre">warning</span></code> 一致的方法 <code class="docutils literal notranslate"><span class="pre">warn</span></code>。由于 <code class="docutils literal notranslate"><span class="pre">warn</span></code> 已被弃用，请不要使用它 —— 改为使用 <code class="docutils literal notranslate"><span class="pre">warning</span></code>。</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="logging.Logger.error">
|
||
<code class="sig-name descname">error</code><span class="sig-paren">(</span><em class="sig-param">msg</em>, <em class="sig-param">*args</em>, <em class="sig-param">**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.Logger.error" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>在此记录器上记录 <code class="xref py py-const docutils literal notranslate"><span class="pre">ERROR</span></code> 级别的消息。参数解释同 <a class="reference internal" href="#logging.debug" title="logging.debug"><code class="xref py py-meth docutils literal notranslate"><span class="pre">debug()</span></code></a>。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="logging.Logger.critical">
|
||
<code class="sig-name descname">critical</code><span class="sig-paren">(</span><em class="sig-param">msg</em>, <em class="sig-param">*args</em>, <em class="sig-param">**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.Logger.critical" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>在此记录器上记录 <code class="xref py py-const docutils literal notranslate"><span class="pre">CRITICAL</span></code> 级别的消息。参数解释同 <a class="reference internal" href="#logging.debug" title="logging.debug"><code class="xref py py-meth docutils literal notranslate"><span class="pre">debug()</span></code></a>。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="logging.Logger.log">
|
||
<code class="sig-name descname">log</code><span class="sig-paren">(</span><em class="sig-param">level</em>, <em class="sig-param">msg</em>, <em class="sig-param">*args</em>, <em class="sig-param">**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.Logger.log" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>在此记录器上记录 <em>level</em> 整数代表的级别的消息。参数解释同 <a class="reference internal" href="#logging.debug" title="logging.debug"><code class="xref py py-meth docutils literal notranslate"><span class="pre">debug()</span></code></a>。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="logging.Logger.exception">
|
||
<code class="sig-name descname">exception</code><span class="sig-paren">(</span><em class="sig-param">msg</em>, <em class="sig-param">*args</em>, <em class="sig-param">**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.Logger.exception" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>在此记录器上记录 <code class="xref py py-const docutils literal notranslate"><span class="pre">ERROR</span></code> 级别的消息。参数解释同 <a class="reference internal" href="#logging.debug" title="logging.debug"><code class="xref py py-meth docutils literal notranslate"><span class="pre">debug()</span></code></a>。异常信息将添加到日志消息中。仅应从异常处理程序中调用此方法。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="logging.Logger.addFilter">
|
||
<code class="sig-name descname">addFilter</code><span class="sig-paren">(</span><em class="sig-param">filter</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.Logger.addFilter" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>将指定的过滤器 <em>filter</em> 添加到此记录器。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="logging.Logger.removeFilter">
|
||
<code class="sig-name descname">removeFilter</code><span class="sig-paren">(</span><em class="sig-param">filter</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.Logger.removeFilter" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>从此记录器中删除指定的过滤器 <em>filter</em>。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="logging.Logger.filter">
|
||
<code class="sig-name descname">filter</code><span class="sig-paren">(</span><em class="sig-param">record</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.Logger.filter" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>将此记录器的过滤器应用于记录，如果记录能被处理则返回 <code class="docutils literal notranslate"><span class="pre">True</span></code>。过滤器会被依次使用，直到其中一个返回假值为止。如果它们都不返回假值，则记录将被处理（传递给处理器）。如果返回任一为假值，则不会对该记录做进一步处理。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="logging.Logger.addHandler">
|
||
<code class="sig-name descname">addHandler</code><span class="sig-paren">(</span><em class="sig-param">hdlr</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.Logger.addHandler" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>将指定的处理器 <em>hdlr</em> 添加到此记录器。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="logging.Logger.removeHandler">
|
||
<code class="sig-name descname">removeHandler</code><span class="sig-paren">(</span><em class="sig-param">hdlr</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.Logger.removeHandler" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>从此记录器中删除指定的处理器 <em>hdlr</em>。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="logging.Logger.findCaller">
|
||
<code class="sig-name descname">findCaller</code><span class="sig-paren">(</span><em class="sig-param">stack_info=False</em>, <em class="sig-param">stacklevel=1</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.Logger.findCaller" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>查找调用源的文件名和行号，以 文件名，行号，函数名称和堆栈信息 4元素元组的形式返回。堆栈信息将返回 <code class="docutils literal notranslate"><span class="pre">None</span></code>，除非 <em>stack_info</em> 为 <code class="docutils literal notranslate"><span class="pre">True</span></code>。</p>
|
||
<p><em>stacklevel</em> 参数用于调用 <a class="reference internal" href="#logging.debug" title="logging.debug"><code class="xref py py-meth docutils literal notranslate"><span class="pre">debug()</span></code></a> 和其他 API。如果大于 1，则多余部分将用于跳过堆栈帧，然后再确定要返回的值。当从帮助器/包装器代码调用日志记录 API 时，这通常很有用，以便事件日志中的信息不是来自帮助器/包装器代码，而是来自调用它的代码。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="logging.Logger.handle">
|
||
<code class="sig-name descname">handle</code><span class="sig-paren">(</span><em class="sig-param">record</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.Logger.handle" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>通过将记录传递给与此记录器及其祖先关联的所有处理器来处理（直到某个 <em>propagate</em> 值为 false）。此方法用于从套接字接收的未序列化的以及在本地创建的记录。使用 <a class="reference internal" href="#logging.Logger.filter" title="logging.Logger.filter"><code class="xref py py-meth docutils literal notranslate"><span class="pre">filter()</span></code></a> 进行记录器级别过滤。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="logging.Logger.makeRecord">
|
||
<code class="sig-name descname">makeRecord</code><span class="sig-paren">(</span><em class="sig-param">name</em>, <em class="sig-param">level</em>, <em class="sig-param">fn</em>, <em class="sig-param">lno</em>, <em class="sig-param">msg</em>, <em class="sig-param">args</em>, <em class="sig-param">exc_info</em>, <em class="sig-param">func=None</em>, <em class="sig-param">extra=None</em>, <em class="sig-param">sinfo=None</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.Logger.makeRecord" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>这是一种工厂方法，可以在子类中对其进行重写以创建专门的 <a class="reference internal" href="#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a> 实例。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="logging.Logger.hasHandlers">
|
||
<code class="sig-name descname">hasHandlers</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#logging.Logger.hasHandlers" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>检查此记录器是否配置了任何处理器。通过在此记录器及其记录器层次结构中的父级中查找处理器完成此操作。如果找到处理器则返回 <code class="docutils literal notranslate"><span class="pre">True</span></code>，否则返回 <code class="docutils literal notranslate"><span class="pre">False</span></code>。只要找到 “propagate” 属性设置为假值的记录器，该方法就会停止搜索层次结构 —— 其将是最后一个检查处理器是否存在的记录器。</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">3.2 新版功能.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.7 版更改: </span>现在可以对处理器进行序列化和反序列化。</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
</section>
|
||
<section id="logging-levels">
|
||
<span id="levels"></span><h2>日志级别<a class="headerlink" href="#logging-levels" title="永久链接至标题">¶</a></h2>
|
||
<p>日志记录级别的数值在下表中给出。如果你想要定义自己的级别，并且需要它们具有相对于预定义级别的特定值，那么这你可能对以下内容感兴趣。如果你定义具有相同数值的级别，它将覆盖预定义的值；预定义的名称将失效。</p>
|
||
<table class="docutils align-default">
|
||
<colgroup>
|
||
<col style="width: 48%" />
|
||
<col style="width: 52%" />
|
||
</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">CRITICAL</span></code></p></td>
|
||
<td><p>50</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">ERROR</span></code></p></td>
|
||
<td><p>40</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">WARNING</span></code></p></td>
|
||
<td><p>30</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">INFO</span></code></p></td>
|
||
<td><p>20</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">DEBUG</span></code></p></td>
|
||
<td><p>10</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">NOTSET</span></code></p></td>
|
||
<td><p>0</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</section>
|
||
<section id="handler-objects">
|
||
<span id="handler"></span><h2>处理器对象<a class="headerlink" href="#handler-objects" title="永久链接至标题">¶</a></h2>
|
||
<p>Handler 有以下属性和方法。注意不要直接实例化 <a class="reference internal" href="#logging.Handler" title="logging.Handler"><code class="xref py py-class docutils literal notranslate"><span class="pre">Handler</span></code></a> ；这个类用来派生其他更有用的子类。但是，子类的 <a class="reference internal" href="../reference/datamodel.html#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code></a> 方法需要调用 <a class="reference internal" href="#logging.Handler.__init__" title="logging.Handler.__init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Handler.__init__()</span></code></a> 。</p>
|
||
<dl class="class">
|
||
<dt id="logging.Handler">
|
||
<em class="property">class </em><code class="sig-prename descclassname">logging.</code><code class="sig-name descname">Handler</code><a class="headerlink" href="#logging.Handler" title="永久链接至目标">¶</a></dt>
|
||
<dd><dl class="method">
|
||
<dt id="logging.Handler.__init__">
|
||
<code class="sig-name descname">__init__</code><span class="sig-paren">(</span><em class="sig-param">level=NOTSET</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.Handler.__init__" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>初始化 <a class="reference internal" href="#logging.Handler" title="logging.Handler"><code class="xref py py-class docutils literal notranslate"><span class="pre">Handler</span></code></a> 实例时，需要设置它的级别，将过滤列表置为空，并且创建锁（通过 <a class="reference internal" href="#logging.Handler.createLock" title="logging.Handler.createLock"><code class="xref py py-meth docutils literal notranslate"><span class="pre">createLock()</span></code></a> ）来序列化对 I/O 的访问。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="logging.Handler.createLock">
|
||
<code class="sig-name descname">createLock</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#logging.Handler.createLock" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>初始化一个线程锁，用来序列化对底层的 I/O 功能的访问，底层的 I/O 功能可能不是线程安全的。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="logging.Handler.acquire">
|
||
<code class="sig-name descname">acquire</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#logging.Handler.acquire" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>获取由 <a class="reference internal" href="#logging.Handler.createLock" title="logging.Handler.createLock"><code class="xref py py-meth docutils literal notranslate"><span class="pre">createLock()</span></code></a> 创建的线程锁。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="logging.Handler.release">
|
||
<code class="sig-name descname">release</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#logging.Handler.release" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>释放由 <a class="reference internal" href="#logging.Handler.acquire" title="logging.Handler.acquire"><code class="xref py py-meth docutils literal notranslate"><span class="pre">acquire()</span></code></a> 获取的线程锁。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="logging.Handler.setLevel">
|
||
<code class="sig-name descname">setLevel</code><span class="sig-paren">(</span><em class="sig-param">level</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.Handler.setLevel" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>给处理器设置阈值为 <em>level</em> 。日志级别小于 <em>level</em> 将被忽略。创建处理器时，日志级别被设置为 <code class="xref py py-const docutils literal notranslate"><span class="pre">NOTSET</span></code> （所有的消息都会被处理）。</p>
|
||
<p>参见 <a class="reference internal" href="#levels"><span class="std std-ref">日志级别</span></a> 级别列表。</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.2 版更改: </span><em>level</em> 形参现在接受像 'INFO' 这样的字符串形式的级别表达方式，也可以使用像 <code class="xref py py-const docutils literal notranslate"><span class="pre">INFO</span></code> 这样的整数常量。</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="logging.Handler.setFormatter">
|
||
<code class="sig-name descname">setFormatter</code><span class="sig-paren">(</span><em class="sig-param">fmt</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.Handler.setFormatter" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>将此处理器的 <a class="reference internal" href="#logging.Formatter" title="logging.Formatter"><code class="xref py py-class docutils literal notranslate"><span class="pre">Formatter</span></code></a> 设置为 <em>fmt</em>。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="logging.Handler.addFilter">
|
||
<code class="sig-name descname">addFilter</code><span class="sig-paren">(</span><em class="sig-param">filter</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.Handler.addFilter" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>将指定的过滤器 <em>filter</em> 添加到此处理器。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="logging.Handler.removeFilter">
|
||
<code class="sig-name descname">removeFilter</code><span class="sig-paren">(</span><em class="sig-param">filter</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.Handler.removeFilter" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>从此处理器中删除指定的过滤器 <em>filter</em> 。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="logging.Handler.filter">
|
||
<code class="sig-name descname">filter</code><span class="sig-paren">(</span><em class="sig-param">record</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.Handler.filter" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>将此处理器的过滤器应用于记录，在要处理记录时返回 <code class="docutils literal notranslate"><span class="pre">True</span></code> 。依次查询过滤器，直到其中一个返回假值为止。如果它们都不返回假值，则将发出记录。如果返回一个假值，则处理器将不会发出记录。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="logging.Handler.flush">
|
||
<code class="sig-name descname">flush</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#logging.Handler.flush" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>确保所有日志记录从缓存输出。此版本不执行任何操作，并且应由子类实现。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="logging.Handler.close">
|
||
<code class="sig-name descname">close</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#logging.Handler.close" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>回收处理器使用的所有资源。此版本不输出，但从内部处理器列表中删除处理器，内部处理器在 <a class="reference internal" href="#logging.shutdown" title="logging.shutdown"><code class="xref py py-func docutils literal notranslate"><span class="pre">shutdown()</span></code></a> 被调用时关闭 。子类应确保从重写的 <a class="reference internal" href="#logging.Handler.close" title="logging.Handler.close"><code class="xref py py-meth docutils literal notranslate"><span class="pre">close()</span></code></a> 方法中调用此方法。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="logging.Handler.handle">
|
||
<code class="sig-name descname">handle</code><span class="sig-paren">(</span><em class="sig-param">record</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.Handler.handle" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>经已添加到处理器的过滤器过滤后，有条件地发出指定的日志记录。用获取/释放 I/O 线程锁包装了记录的实际发出行为。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="logging.Handler.handleError">
|
||
<code class="sig-name descname">handleError</code><span class="sig-paren">(</span><em class="sig-param">record</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.Handler.handleError" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>调用 <a class="reference internal" href="#logging.Handler.emit" title="logging.Handler.emit"><code class="xref py py-meth docutils literal notranslate"><span class="pre">emit()</span></code></a> 期间遇到异常时，应从处理器中调用此方法。如果模块级属性 <code class="docutils literal notranslate"><span class="pre">raiseExceptions</span></code> 是 <code class="docutils literal notranslate"><span class="pre">False</span></code>，则异常将被静默忽略。这是大多数情况下日志系统需要的 —— 大多数用户不会关心日志系统中的错误，他们对应用程序错误更感兴趣。但是，你可以根据需要将其替换为自定义处理器。指定的记录是发生异常时正在处理的记录。（<code class="docutils literal notranslate"><span class="pre">raiseExceptions</span></code> 的默认值是 <code class="docutils literal notranslate"><span class="pre">True</span></code>，因为这在开发过程中是比较有用的）。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="logging.Handler.format">
|
||
<code class="sig-name descname">format</code><span class="sig-paren">(</span><em class="sig-param">record</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.Handler.format" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>如果设置了格式器则用其对记录进行格式化。否则，使用模块的默认格式器。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="logging.Handler.emit">
|
||
<code class="sig-name descname">emit</code><span class="sig-paren">(</span><em class="sig-param">record</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.Handler.emit" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>执行实际记录给定日志记录所需的操作。这个版本应由子类实现，因此这里直接引发 <a class="reference internal" href="exceptions.html#NotImplementedError" title="NotImplementedError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">NotImplementedError</span></code></a> 异常。</p>
|
||
</dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
<p>有关作为标准随附的处理器列表，请参见 <a class="reference internal" href="logging.handlers.html#module-logging.handlers" title="logging.handlers: Handlers for the logging module."><code class="xref py py-mod docutils literal notranslate"><span class="pre">logging.handlers</span></code></a>。</p>
|
||
</section>
|
||
<section id="formatter-objects">
|
||
<span id="id1"></span><h2>格式器对象<a class="headerlink" href="#formatter-objects" title="永久链接至标题">¶</a></h2>
|
||
<p><a class="reference internal" href="#logging.Formatter" title="logging.Formatter"><code class="xref py py-class docutils literal notranslate"><span class="pre">Formatter</span></code></a> 对象拥有以下的属性和方法。一般情况下，它们负责将 <a class="reference internal" href="#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a> 转换为可由人或外部系统解释的字符串。基础的 <a class="reference internal" href="#logging.Formatter" title="logging.Formatter"><code class="xref py py-class docutils literal notranslate"><span class="pre">Formatter</span></code></a> 允许指定格式字符串。如果未提供任何值，则使用默认值 <code class="docutils literal notranslate"><span class="pre">'%(message)s'</span></code> ，它仅将消息包括在日志记录调用中。要在格式化输出中包含其他信息（如时间戳），请阅读下文。</p>
|
||
<p>格式器可以使用格式化字符串来初始化，该字符串利用 <a class="reference internal" href="#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a> 的属性 —— 例如上述默认值，用户的消息和参数预先格式化为 <a class="reference internal" href="#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a> 的 <em>message</em> 属性后被使用。此格式字符串包含标准的 Python %-s 样式映射键。有关字符串格式的更多信息，请参见 <a class="reference internal" href="stdtypes.html#old-string-formatting"><span class="std std-ref">printf 风格的字符串格式化</span></a>。</p>
|
||
<p><a class="reference internal" href="#logrecord-attributes"><span class="std std-ref">LogRecord 属性</span></a> 一节中给出了 <a class="reference internal" href="#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a> 中有用的映射键。</p>
|
||
<dl class="class">
|
||
<dt id="logging.Formatter">
|
||
<em class="property">class </em><code class="sig-prename descclassname">logging.</code><code class="sig-name descname">Formatter</code><span class="sig-paren">(</span><em class="sig-param">fmt=None</em>, <em class="sig-param">datefmt=None</em>, <em class="sig-param">style='%'</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.Formatter" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>返回 <a class="reference internal" href="#logging.Formatter" title="logging.Formatter"><code class="xref py py-class docutils literal notranslate"><span class="pre">Formatter</span></code></a> 类的新实例。实例将使用整个消息的格式字符串以及消息的日期/时间部分的格式字符串进行初始化。如果未指定 <em>fmt</em> ，则使用 <code class="docutils literal notranslate"><span class="pre">'%(message)s'</span></code>。如果未指定 <em>datefmt</em>，则使用 <a class="reference internal" href="#logging.Formatter.formatTime" title="logging.Formatter.formatTime"><code class="xref py py-meth docutils literal notranslate"><span class="pre">formatTime()</span></code></a> 文档中描述的格式。</p>
|
||
<p><em>style</em> 形参可以是 '%', '{' 或 '$' 之一，它决定格式字符串如何与数据进行合并：使用 %-formatting, <a class="reference internal" href="stdtypes.html#str.format" title="str.format"><code class="xref py py-meth docutils literal notranslate"><span class="pre">str.format()</span></code></a> 或 <a class="reference internal" href="string.html#string.Template" title="string.Template"><code class="xref py py-class docutils literal notranslate"><span class="pre">string.Template</span></code></a> 之一。 请参阅 <a class="reference internal" href="../howto/logging-cookbook.html#formatting-styles"><span class="std std-ref">生效于整个应用程序的格式化样式</span></a> 了解有关在日志消息中使用 {- 和 $-formatting 的更多信息。</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.2 版更改: </span>加入了 <em>style</em> 形参。</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.8 版更改: </span>加入*validate* 参数。不正确或不匹配的样式和格式将引发 <code class="docutils literal notranslate"><span class="pre">ValueError</span></code> 错误。例如: <code class="docutils literal notranslate"><span class="pre">logging.Formatter('%(asctime)s</span> <span class="pre">-</span> <span class="pre">%(message)s',</span> <span class="pre">style='{')</span></code>。</p>
|
||
</div>
|
||
<dl class="method">
|
||
<dt id="logging.Formatter.format">
|
||
<code class="sig-name descname">format</code><span class="sig-paren">(</span><em class="sig-param">record</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.Formatter.format" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>记录的属性字典用作字符串格式化操作的参数。返回结果字符串。在格式化字典之前，需要执行几个准备步骤。 使用 <em>msg</em> % <em>args</em> 计算记录的 <em>message</em> 属性。如果格式化字符串包含 <code class="docutils literal notranslate"><span class="pre">'(asctime)'</span></code>，则调用 <a class="reference internal" href="#logging.Formatter.formatTime" title="logging.Formatter.formatTime"><code class="xref py py-meth docutils literal notranslate"><span class="pre">formatTime()</span></code></a> 来格式化事件时间。如果有异常信息，则使用 <a class="reference internal" href="#logging.Formatter.formatException" title="logging.Formatter.formatException"><code class="xref py py-meth docutils literal notranslate"><span class="pre">formatException()</span></code></a> 将其格式化并附加到消息中。请注意，格式化的异常信息缓存在属性 <em>exc_text</em> 中。这很有用，因为可以对异常信息进行序列化并通过网络发送，但是如果您有不止一个定制了异常信息格式的 <a class="reference internal" href="#logging.Formatter" title="logging.Formatter"><code class="xref py py-class docutils literal notranslate"><span class="pre">Formatter</span></code></a> 子类，则应格外小心。在这种情况下，您必须在格式器完成格式化后清除缓存的值，以便下一个处理事件的格式器不使用缓存的值，而是重新计算它。</p>
|
||
<p>如果栈信息可用，它将被添加在异常信息之后，如有必要请使用 <a class="reference internal" href="#logging.Formatter.formatStack" title="logging.Formatter.formatStack"><code class="xref py py-meth docutils literal notranslate"><span class="pre">formatStack()</span></code></a> 来转换它。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="logging.Formatter.formatTime">
|
||
<code class="sig-name descname">formatTime</code><span class="sig-paren">(</span><em class="sig-param">record</em>, <em class="sig-param">datefmt=None</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.Formatter.formatTime" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>此方法应由想要使用格式化时间的格式器中的 <a class="reference internal" href="functions.html#format" title="format"><code class="xref py py-meth docutils literal notranslate"><span class="pre">format()</span></code></a> 调用。可以在格式器中重写此方法以提供任何特定要求，但是基本行为如下：如果指定了 <em>datefmt</em> （字符串），则将其用于 <a class="reference internal" href="time.html#time.strftime" title="time.strftime"><code class="xref py py-func docutils literal notranslate"><span class="pre">time.strftime()</span></code></a> 来格式化记录的创建时间。否则，使用格式 '%Y-%m-%d %H:%M:%S,uuu'，其中 uuu 部分是毫秒值，其他字母根据 <a class="reference internal" href="time.html#time.strftime" title="time.strftime"><code class="xref py py-func docutils literal notranslate"><span class="pre">time.strftime()</span></code></a> 文档。这种时间格式的示例为 <code class="docutils literal notranslate"><span class="pre">2003-01-23</span> <span class="pre">00:29:50,411</span></code>。返回结果字符串。</p>
|
||
<p>此函数使用一个用户可配置函数将创建时间转换为元组。 默认情况下，使用 <a class="reference internal" href="time.html#time.localtime" title="time.localtime"><code class="xref py py-func docutils literal notranslate"><span class="pre">time.localtime()</span></code></a>；要为特定格式化程序实例更改此项，请将实例的 <code class="docutils literal notranslate"><span class="pre">converter</span></code> 属性设为具有与 <a class="reference internal" href="time.html#time.localtime" title="time.localtime"><code class="xref py py-func docutils literal notranslate"><span class="pre">time.localtime()</span></code></a> 或 <a class="reference internal" href="time.html#time.gmtime" title="time.gmtime"><code class="xref py py-func docutils literal notranslate"><span class="pre">time.gmtime()</span></code></a> 相同签名的函数。 要为所有格式化程序更改此项，例如当你希望所有日志时间都显示为 GMT，请在 <code class="docutils literal notranslate"><span class="pre">Formatter</span></code> 类中设置 <code class="docutils literal notranslate"><span class="pre">converter</span></code> 属性。</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.3 版更改: </span>在之前版本中，默认格式是被硬编码的，例如这个例子: <code class="docutils literal notranslate"><span class="pre">2010-09-06</span> <span class="pre">22:38:15,292</span></code> 其中逗号之前的部分由 strptime 格式字符串 (<code class="docutils literal notranslate"><span class="pre">'%Y-%m-%d</span> <span class="pre">%H:%M:%S'</span></code>) 处理，而逗号之后的部分为毫秒值。 因为 strptime 没有表示毫秒的占位符，毫秒值使用了另外的格式字符串来添加 <code class="docutils literal notranslate"><span class="pre">'%s,%03d'</span></code> --- 这两个格式字符串代码都是硬编码在该方法中的。 经过修改，这些字符串被定义为类层级的属性，当需要时可以在实例层级上被重写。 属性的名称为 <code class="docutils literal notranslate"><span class="pre">default_time_format</span></code> (用于 strptime 格式字符串) 和 <code class="docutils literal notranslate"><span class="pre">default_msec_format</span></code> (用于添加毫秒值)。</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="logging.Formatter.formatException">
|
||
<code class="sig-name descname">formatException</code><span class="sig-paren">(</span><em class="sig-param">exc_info</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.Formatter.formatException" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>将指定的异常信息（由 <a class="reference internal" href="sys.html#sys.exc_info" title="sys.exc_info"><code class="xref py py-func docutils literal notranslate"><span class="pre">sys.exc_info()</span></code></a> 返回的标准异常元组）格式化为字符串。默认实现只是使用了 <a class="reference internal" href="traceback.html#traceback.print_exception" title="traceback.print_exception"><code class="xref py py-func docutils literal notranslate"><span class="pre">traceback.print_exception()</span></code></a>。 结果字符串将被返回。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="logging.Formatter.formatStack">
|
||
<code class="sig-name descname">formatStack</code><span class="sig-paren">(</span><em class="sig-param">stack_info</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.Formatter.formatStack" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>将指定的堆栈信息（由 <a class="reference internal" href="traceback.html#traceback.print_stack" title="traceback.print_stack"><code class="xref py py-func docutils literal notranslate"><span class="pre">traceback.print_stack()</span></code></a> 返回的字符串，但移除末尾的换行符）格式化为字符串。 默认实现只是返回输入值。</p>
|
||
</dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
</section>
|
||
<section id="filter-objects">
|
||
<span id="filter"></span><h2>过滤器对象<a class="headerlink" href="#filter-objects" title="永久链接至标题">¶</a></h2>
|
||
<p><code class="docutils literal notranslate"><span class="pre">Filters</span></code> 可被 <code class="docutils literal notranslate"><span class="pre">Handlers</span></code> 和 <code class="docutils literal notranslate"><span class="pre">Loggers</span></code> 用来实现比按层级提供更复杂的过滤操作。 基本过滤器类只允许低于日志记录器层级结构中低于特定层级的事件。 例如，一个用 'A.B' 初始化的过滤器将允许 'A.B', 'A.B.C', 'A.B.C.D', 'A.B.D' 等日志记录器所记录的事件。 但 'A.BB', 'B.A.B' 等则不允许。 如果用空字符串初始化，则所有事件都会通过。</p>
|
||
<dl class="class">
|
||
<dt id="logging.Filter">
|
||
<em class="property">class </em><code class="sig-prename descclassname">logging.</code><code class="sig-name descname">Filter</code><span class="sig-paren">(</span><em class="sig-param">name=''</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.Filter" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>返回一个 <a class="reference internal" href="#logging.Filter" title="logging.Filter"><code class="xref py py-class docutils literal notranslate"><span class="pre">Filter</span></code></a> 类的实例。 如果指定了 <em>name</em>，则它将被用来为日志记录器命名，该类及其子类将通过该过滤器允许指定事件通过。 如果 <em>name</em> 为空字符串，则允许所有事件通过。</p>
|
||
<dl class="method">
|
||
<dt id="logging.Filter.filter">
|
||
<code class="sig-name descname">filter</code><span class="sig-paren">(</span><em class="sig-param">record</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.Filter.filter" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>是否要记录指定的记录？返回零表示否，非零表示是。如果认为合适，则可以通过此方法就地修改记录。</p>
|
||
</dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
<p>请注意关联到处理器的过滤器会在事件由处理器发出之前被查询，而关联到日志记录器的过滤器则会在有事件被记录的的任何时候（使用 <a class="reference internal" href="#logging.debug" title="logging.debug"><code class="xref py py-meth docutils literal notranslate"><span class="pre">debug()</span></code></a>, <a class="reference internal" href="#logging.info" title="logging.info"><code class="xref py py-meth docutils literal notranslate"><span class="pre">info()</span></code></a> 等等）在将事件发送给处理器之前被查询。 这意味着由后代日志记录器生成的事件将不会被父代日志记录器的过滤器设置所过滤，除非该过滤器也已被应用于后代日志记录器。</p>
|
||
<p>你实际上不需要子类化 <code class="docutils literal notranslate"><span class="pre">Filter</span></code> ：你可以传入任何一个包含有相同语义的 <code class="docutils literal notranslate"><span class="pre">filter</span></code> 方法的实例。</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.2 版更改: </span>你不需要创建专门的 <code class="docutils literal notranslate"><span class="pre">Filter</span></code> 类，或使用具有 <code class="docutils literal notranslate"><span class="pre">filter</span></code> 方法的其他类：你可以使用一个函数（或其他可调用对象）作为过滤器。 过滤逻辑将检查过滤器对象是否具有 <code class="docutils literal notranslate"><span class="pre">filter</span></code> 属性：如果有，就会将它当作是 <code class="docutils literal notranslate"><span class="pre">Filter</span></code> 并调用它的 <a class="reference internal" href="#logging.Filter.filter" title="logging.Filter.filter"><code class="xref py py-meth docutils literal notranslate"><span class="pre">filter()</span></code></a> 方法。 在其他情况下，则会将它当作是可调用对象并将记录作为唯一的形参进行调用。 返回值应当与 <a class="reference internal" href="#logging.Filter.filter" title="logging.Filter.filter"><code class="xref py py-meth docutils literal notranslate"><span class="pre">filter()</span></code></a> 的返回值相一致。</p>
|
||
</div>
|
||
<p>尽管过滤器主要被用来构造比层级更复杂的规则以过滤记录，但它们可以查看由它们关联的处理器或记录器所处理的每条记录：当你想要执行统计特定记录器或处理器共处理了多少条记录，或是在所处理的 <a class="reference internal" href="#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a> 中添加、修改或移除属性这样的任务时该特性将很有用处。 显然改变 LogRecord 时需要相当小心，但将上下文信息注入日志确实是被允许的 (参见 <a class="reference internal" href="../howto/logging-cookbook.html#filters-contextual"><span class="std std-ref">使用过滤器传递上下文信息</span></a>)。</p>
|
||
</section>
|
||
<section id="logrecord-objects">
|
||
<span id="log-record"></span><h2>LogRecord 属性<a class="headerlink" href="#logrecord-objects" title="永久链接至标题">¶</a></h2>
|
||
<p><a class="reference internal" href="#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a> 实例是每当有日志被记录时由 <a class="reference internal" href="#logging.Logger" title="logging.Logger"><code class="xref py py-class docutils literal notranslate"><span class="pre">Logger</span></code></a> 自动创建的，并且可通过 <a class="reference internal" href="#logging.makeLogRecord" title="logging.makeLogRecord"><code class="xref py py-func docutils literal notranslate"><span class="pre">makeLogRecord()</span></code></a> 手动创建（例如根据从网络接收的已封存事件创建）。</p>
|
||
<dl class="class">
|
||
<dt id="logging.LogRecord">
|
||
<em class="property">class </em><code class="sig-prename descclassname">logging.</code><code class="sig-name descname">LogRecord</code><span class="sig-paren">(</span><em class="sig-param">name</em>, <em class="sig-param">level</em>, <em class="sig-param">pathname</em>, <em class="sig-param">lineno</em>, <em class="sig-param">msg</em>, <em class="sig-param">args</em>, <em class="sig-param">exc_info</em>, <em class="sig-param">func=None</em>, <em class="sig-param">sinfo=None</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.LogRecord" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>包含与被记录的事件相关的所有信息。</p>
|
||
<p>主要信息是在 <code class="xref py py-attr docutils literal notranslate"><span class="pre">msg</span></code> 和 <code class="xref py py-attr docutils literal notranslate"><span class="pre">args</span></code> 中传递的，它们使用 <code class="docutils literal notranslate"><span class="pre">msg</span> <span class="pre">%</span> <span class="pre">args</span></code> 组合到一起以创建记录的 <code class="xref py py-attr docutils literal notranslate"><span class="pre">message</span></code> 字段。</p>
|
||
<dl class="field-list simple">
|
||
<dt class="field-odd">参数</dt>
|
||
<dd class="field-odd"><ul class="simple">
|
||
<li><p><strong>name</strong> -- 用于记录由此 LogRecord 所表示事件的记录器名称。 请注意此名称将始终为该值，即使它可能是由附加到不同（祖先）日志记录器的处理器所发出的。</p></li>
|
||
<li><p><strong>level</strong> -- 以数字表示的日志记录事件层级（如 DEBUG, INFO 等）。 请注意这会转换为 LogRecord 的 <em>两个</em> 属性: <code class="docutils literal notranslate"><span class="pre">levelno</span></code> 为数字值而 <code class="docutils literal notranslate"><span class="pre">levelname</span></code> 为对应的层级名称。</p></li>
|
||
<li><p><strong>pathname</strong> -- 进行日志记录调用的文件的完整路径名。</p></li>
|
||
<li><p><strong>lineno</strong> -- 记录调用所在源文件中的行号。</p></li>
|
||
<li><p><strong>msg</strong> -- 事件描述消息，可能为带有可变数据占位符的格式字符串。</p></li>
|
||
<li><p><strong>args</strong> -- 要合并到 <em>msg</em> 参数以获得事件描述的可变数据。</p></li>
|
||
<li><p><strong>exc_info</strong> -- 包含当前异常信息的异常元组，或者如果没有可用异常信息则为 <code class="docutils literal notranslate"><span class="pre">None</span></code>。</p></li>
|
||
<li><p><strong>func</strong> -- 发起调用日志记录调用的函数或方法名称。</p></li>
|
||
<li><p><strong>sinfo</strong> -- 一个文本字符串，表示当前线程中从堆栈底部直到日志记录调用的堆栈信息。</p></li>
|
||
</ul>
|
||
</dd>
|
||
</dl>
|
||
<dl class="method">
|
||
<dt id="logging.LogRecord.getMessage">
|
||
<code class="sig-name descname">getMessage</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#logging.LogRecord.getMessage" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>在将 <a class="reference internal" href="#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a> 实例与任何用户提供的参数合并之后，返回此实例的消息。 如果用户提供给日志记录调用的消息参数不是字符串，则会在其上调用 <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-func docutils literal notranslate"><span class="pre">str()</span></code></a> 以将它转换为字符串。 此方法允许将用户定义的类用作消息，类的 <code class="docutils literal notranslate"><span class="pre">__str__</span></code> 方法可以返回要使用的实际格式字符串。</p>
|
||
</dd></dl>
|
||
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.2 版更改: </span>通过提供用于创建记录的工厂方法已使得 <a class="reference internal" href="#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a> 的创建更易于配置。 该工厂方法可使用 <a class="reference internal" href="#logging.getLogRecordFactory" title="logging.getLogRecordFactory"><code class="xref py py-func docutils literal notranslate"><span class="pre">getLogRecordFactory()</span></code></a> 和 <a class="reference internal" href="#logging.setLogRecordFactory" title="logging.setLogRecordFactory"><code class="xref py py-func docutils literal notranslate"><span class="pre">setLogRecordFactory()</span></code></a> （在此可查看工厂方法的签名）来设置。</p>
|
||
</div>
|
||
<p>在创建时可使用此功能将你自己的值注入 <a class="reference internal" href="#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a>。 你可以使用以下模式:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">old_factory</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogRecordFactory</span><span class="p">()</span>
|
||
|
||
<span class="k">def</span> <span class="nf">record_factory</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
|
||
<span class="n">record</span> <span class="o">=</span> <span class="n">old_factory</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
|
||
<span class="n">record</span><span class="o">.</span><span class="n">custom_attribute</span> <span class="o">=</span> <span class="mh">0xdecafbad</span>
|
||
<span class="k">return</span> <span class="n">record</span>
|
||
|
||
<span class="n">logging</span><span class="o">.</span><span class="n">setLogRecordFactory</span><span class="p">(</span><span class="n">record_factory</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>通过此模式，多个工厂方法可以被链接起来，并且只要它们不重写彼此的属性或是在无意中覆盖了上面列出的标准属性，就不会发生意外。</p>
|
||
</dd></dl>
|
||
|
||
</section>
|
||
<section id="logrecord-attributes">
|
||
<span id="id2"></span><h2>LogRecord 属性<a class="headerlink" href="#logrecord-attributes" title="永久链接至标题">¶</a></h2>
|
||
<p>LogRecord 具有许多属性，它们大多数来自于传递给构造器的形参。 （请注意 LogRecord 构造器形参与 LogRecord 属性的名称并不总是完全彼此对应的。） 这些属性可被用于将来自记录的数据合并到格式字符串中。 下面的表格（按字母顺序）列出了属性名称、它们的含义以及相应的 %-style 格式字符串内占位符。</p>
|
||
<p>如果是使用 {}-格式化（<a class="reference internal" href="stdtypes.html#str.format" title="str.format"><code class="xref py py-func docutils literal notranslate"><span class="pre">str.format()</span></code></a>），你可以将 <code class="docutils literal notranslate"><span class="pre">{attrname}</span></code> 用作格式字符串内的占位符。 如果是使用 $-格式化（<a class="reference internal" href="string.html#string.Template" title="string.Template"><code class="xref py py-class docutils literal notranslate"><span class="pre">string.Template</span></code></a>），则会使用 <code class="docutils literal notranslate"><span class="pre">${attrname}</span></code> 的形式。 当然在这两种情况下，都应当将 <code class="docutils literal notranslate"><span class="pre">attrname</span></code> 替换为你想要使用的实际属性名称。</p>
|
||
<p>在 {}-格式化的情况下，你可以在属性名称之后放置指定的格式化旗标，并用冒号来分隔两者。 例如，占位符 <code class="docutils literal notranslate"><span class="pre">{msecs:03d}</span></code> 会将毫秒值 <code class="docutils literal notranslate"><span class="pre">4</span></code> 格式化为 <code class="docutils literal notranslate"><span class="pre">004</span></code>。 请参看 <a class="reference internal" href="stdtypes.html#str.format" title="str.format"><code class="xref py py-meth docutils literal notranslate"><span class="pre">str.format()</span></code></a> 文档了解你所能使用的选项的完整细节。</p>
|
||
<table class="docutils align-default">
|
||
<colgroup>
|
||
<col style="width: 18%" />
|
||
<col style="width: 28%" />
|
||
<col style="width: 53%" />
|
||
</colgroup>
|
||
<thead>
|
||
<tr class="row-odd"><th class="head"><p>属性名称</p></th>
|
||
<th class="head"><p>格式</p></th>
|
||
<th class="head"><p>描述</p></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="row-even"><td><p>args</p></td>
|
||
<td><p>此属性不需要用户进行格式化。</p></td>
|
||
<td><p>合并到 <code class="docutils literal notranslate"><span class="pre">msg</span></code> 以产生 <code class="docutils literal notranslate"><span class="pre">message</span></code> 的包含参数的元组，或是其中的值将被用于合并的字典（当只有一个参数且其类型为字典时）。</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>asctime</p></td>
|
||
<td><p><code class="docutils literal notranslate"><span class="pre">%(asctime)s</span></code></p></td>
|
||
<td><p>表示人类易读的 <a class="reference internal" href="#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a> 生成时间。 默认形式为 '2003-07-08 16:49:45,896' （逗号之后的数字为时间的毫秒部分）。</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>created</p></td>
|
||
<td><p><code class="docutils literal notranslate"><span class="pre">%(created)f</span></code></p></td>
|
||
<td><p><a class="reference internal" href="#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a> 被创建的时间（即 <a class="reference internal" href="time.html#time.time" title="time.time"><code class="xref py py-func docutils literal notranslate"><span class="pre">time.time()</span></code></a> 的返回值）。</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>exc_info</p></td>
|
||
<td><p>此属性不需要用户进行格式化。</p></td>
|
||
<td><p>异常元组（例如 <code class="docutils literal notranslate"><span class="pre">sys.exc_info</span></code>）或者如未发生异常则为 <code class="docutils literal notranslate"><span class="pre">None</span></code>。</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>文件名</p></td>
|
||
<td><p><code class="docutils literal notranslate"><span class="pre">%(filename)s</span></code></p></td>
|
||
<td><p><code class="docutils literal notranslate"><span class="pre">pathname</span></code> 的文件名部分。</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>funcName</p></td>
|
||
<td><p><code class="docutils literal notranslate"><span class="pre">%(funcName)s</span></code></p></td>
|
||
<td><p>函数名包括调用日志记录.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>levelname</p></td>
|
||
<td><p><code class="docutils literal notranslate"><span class="pre">%(levelname)s</span></code></p></td>
|
||
<td><p>消息文本记录级别（<code class="docutils literal notranslate"><span class="pre">'DEBUG'</span></code>，<code class="docutils literal notranslate"><span class="pre">'INFO'</span></code>，<code class="docutils literal notranslate"><span class="pre">'WARNING'</span></code>，<code class="docutils literal notranslate"><span class="pre">'ERROR'</span></code>，<code class="docutils literal notranslate"><span class="pre">'CRITICAL'</span></code>）。</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>levelno</p></td>
|
||
<td><p><code class="docutils literal notranslate"><span class="pre">%(levelno)s</span></code></p></td>
|
||
<td><p>消息数字的记录级别 (<code class="xref py py-const docutils literal notranslate"><span class="pre">DEBUG</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">INFO</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">WARNING</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">ERROR</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">CRITICAL</span></code>).</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>lineno</p></td>
|
||
<td><p><code class="docutils literal notranslate"><span class="pre">%(lineno)d</span></code></p></td>
|
||
<td><p>发出日志记录调用所在的源行号（如果可用）。</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>message</p></td>
|
||
<td><p><code class="docutils literal notranslate"><span class="pre">%(message)s</span></code></p></td>
|
||
<td><p>记入日志的消息，即 <code class="docutils literal notranslate"><span class="pre">msg</span> <span class="pre">%</span> <span class="pre">args</span></code> 的结果。 这是在发起调用 <a class="reference internal" href="#logging.Formatter.format" title="logging.Formatter.format"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Formatter.format()</span></code></a> 时设置的。</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>module</p></td>
|
||
<td><p><code class="docutils literal notranslate"><span class="pre">%(module)s</span></code></p></td>
|
||
<td><p>模块 (<code class="docutils literal notranslate"><span class="pre">filename</span></code> 的名称部分)。</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>msecs</p></td>
|
||
<td><p><code class="docutils literal notranslate"><span class="pre">%(msecs)d</span></code></p></td>
|
||
<td><p><a class="reference internal" href="#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a> 被创建的时间的毫秒部分。</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>msg</p></td>
|
||
<td><p>此属性不需要用户进行格式化。</p></td>
|
||
<td><p>在原始日志记录调用中传入的格式字符串。 与 <code class="docutils literal notranslate"><span class="pre">args</span></code> 合并以产生 <code class="docutils literal notranslate"><span class="pre">message</span></code>，或是一个任意对象 (参见 <a class="reference internal" href="../howto/logging.html#arbitrary-object-messages"><span class="std std-ref">使用任意对象作为消息</span></a>)。</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>name</p></td>
|
||
<td><p><code class="docutils literal notranslate"><span class="pre">%(name)s</span></code></p></td>
|
||
<td><p>用于记录调用的日志记录器名称。</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>pathname</p></td>
|
||
<td><p><code class="docutils literal notranslate"><span class="pre">%(pathname)s</span></code></p></td>
|
||
<td><p>发出日志记录调用的源文件的完整路径名（如果可用）。</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>process</p></td>
|
||
<td><p><code class="docutils literal notranslate"><span class="pre">%(process)d</span></code></p></td>
|
||
<td><p>进程ID（如果可用）</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>processName</p></td>
|
||
<td><p><code class="docutils literal notranslate"><span class="pre">%(processName)s</span></code></p></td>
|
||
<td><p>进程名（如果可用）</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>relativeCreated</p></td>
|
||
<td><p><code class="docutils literal notranslate"><span class="pre">%(relativeCreated)d</span></code></p></td>
|
||
<td><p>以毫秒数表示的 LogRecord 被创建的时间，即相对于 logging 模块被加载时间的差值。</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>stack_info</p></td>
|
||
<td><p>此属性不需要用户进行格式化。</p></td>
|
||
<td><p>当前线程中从堆栈底部起向上直到包括日志记录调用并引发创建当前记录堆栈帧创建的堆栈帧信息（如果可用）。</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>thread</p></td>
|
||
<td><p><code class="docutils literal notranslate"><span class="pre">%(thread)d</span></code></p></td>
|
||
<td><p>线程ID（如果可用）</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>threadName</p></td>
|
||
<td><p><code class="docutils literal notranslate"><span class="pre">%(threadName)s</span></code></p></td>
|
||
<td><p>线程名（如果可用）</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.1 版更改: </span>添加了 <em>processName</em></p>
|
||
</div>
|
||
</section>
|
||
<section id="loggeradapter-objects">
|
||
<span id="logger-adapter"></span><h2>LoggerAdapter 对象<a class="headerlink" href="#loggeradapter-objects" title="永久链接至标题">¶</a></h2>
|
||
<p><a class="reference internal" href="#logging.LoggerAdapter" title="logging.LoggerAdapter"><code class="xref py py-class docutils literal notranslate"><span class="pre">LoggerAdapter</span></code></a> 实例会被用来方便地将上下文信息传入日志记录调用。 要获取用法示例，请参阅 <a class="reference internal" href="../howto/logging-cookbook.html#context-info"><span class="std std-ref">添加上下文信息到你的日志记录输出</span></a> 部分。</p>
|
||
<dl class="class">
|
||
<dt id="logging.LoggerAdapter">
|
||
<em class="property">class </em><code class="sig-prename descclassname">logging.</code><code class="sig-name descname">LoggerAdapter</code><span class="sig-paren">(</span><em class="sig-param">logger</em>, <em class="sig-param">extra</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.LoggerAdapter" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>返回一个 <a class="reference internal" href="#logging.LoggerAdapter" title="logging.LoggerAdapter"><code class="xref py py-class docutils literal notranslate"><span class="pre">LoggerAdapter</span></code></a> 的实例，该实例的初始化使用了下层的 <a class="reference internal" href="#logging.Logger" title="logging.Logger"><code class="xref py py-class docutils literal notranslate"><span class="pre">Logger</span></code></a> 实例和一个字典类对象。</p>
|
||
<dl class="method">
|
||
<dt id="logging.LoggerAdapter.process">
|
||
<code class="sig-name descname">process</code><span class="sig-paren">(</span><em class="sig-param">msg</em>, <em class="sig-param">kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.LoggerAdapter.process" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>修改传递给日志记录调用的消息和/或关键字参数以便插入上下文信息。 此实现接受以 <em>extra</em> 形式传给构造器的对象并使用 'extra' 键名将其加入 <em>kwargs</em>。 返回值为一个 (<em>msg</em>, <em>kwargs</em>) 元组，其包含（可能经过修改的）传入参数。</p>
|
||
</dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
<p>在上述方法之外，<a class="reference internal" href="#logging.LoggerAdapter" title="logging.LoggerAdapter"><code class="xref py py-class docutils literal notranslate"><span class="pre">LoggerAdapter</span></code></a> 还支持 <a class="reference internal" href="#logging.Logger" title="logging.Logger"><code class="xref py py-class docutils literal notranslate"><span class="pre">Logger</span></code></a> 的下列方法: <a class="reference internal" href="#logging.Logger.debug" title="logging.Logger.debug"><code class="xref py py-meth docutils literal notranslate"><span class="pre">debug()</span></code></a>, <a class="reference internal" href="#logging.Logger.info" title="logging.Logger.info"><code class="xref py py-meth docutils literal notranslate"><span class="pre">info()</span></code></a>，<a class="reference internal" href="#logging.Logger.warning" title="logging.Logger.warning"><code class="xref py py-meth docutils literal notranslate"><span class="pre">warning()</span></code></a>，<a class="reference internal" href="#logging.Logger.error" title="logging.Logger.error"><code class="xref py py-meth docutils literal notranslate"><span class="pre">error()</span></code></a>, <a class="reference internal" href="#logging.Logger.exception" title="logging.Logger.exception"><code class="xref py py-meth docutils literal notranslate"><span class="pre">exception()</span></code></a>, <a class="reference internal" href="#logging.Logger.critical" title="logging.Logger.critical"><code class="xref py py-meth docutils literal notranslate"><span class="pre">critical()</span></code></a>，<a class="reference internal" href="#logging.Logger.log" title="logging.Logger.log"><code class="xref py py-meth docutils literal notranslate"><span class="pre">log()</span></code></a>，<a class="reference internal" href="#logging.Logger.isEnabledFor" title="logging.Logger.isEnabledFor"><code class="xref py py-meth docutils literal notranslate"><span class="pre">isEnabledFor()</span></code></a>，<a class="reference internal" href="#logging.Logger.getEffectiveLevel" title="logging.Logger.getEffectiveLevel"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getEffectiveLevel()</span></code></a>，<a class="reference internal" href="#logging.Logger.setLevel" title="logging.Logger.setLevel"><code class="xref py py-meth docutils literal notranslate"><span class="pre">setLevel()</span></code></a> 以及 <a class="reference internal" href="#logging.Logger.hasHandlers" title="logging.Logger.hasHandlers"><code class="xref py py-meth docutils literal notranslate"><span class="pre">hasHandlers()</span></code></a>。 这些方法具有与它们在 <a class="reference internal" href="#logging.Logger" title="logging.Logger"><code class="xref py py-class docutils literal notranslate"><span class="pre">Logger</span></code></a> 中的对应方法相同的签名，因此你可以互换使用这两种类型的实例。</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.2 版更改: </span><a class="reference internal" href="#logging.Logger.isEnabledFor" title="logging.Logger.isEnabledFor"><code class="xref py py-meth docutils literal notranslate"><span class="pre">isEnabledFor()</span></code></a>, <a class="reference internal" href="#logging.Logger.getEffectiveLevel" title="logging.Logger.getEffectiveLevel"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getEffectiveLevel()</span></code></a>, <a class="reference internal" href="#logging.Logger.setLevel" title="logging.Logger.setLevel"><code class="xref py py-meth docutils literal notranslate"><span class="pre">setLevel()</span></code></a> 和 <a class="reference internal" href="#logging.Logger.hasHandlers" title="logging.Logger.hasHandlers"><code class="xref py py-meth docutils literal notranslate"><span class="pre">hasHandlers()</span></code></a> 方法已被添加到 <a class="reference internal" href="#logging.LoggerAdapter" title="logging.LoggerAdapter"><code class="xref py py-class docutils literal notranslate"><span class="pre">LoggerAdapter</span></code></a>。 这些方法会委托给下层的日志记录器。</p>
|
||
</div>
|
||
</section>
|
||
<section id="thread-safety">
|
||
<h2>线程安全<a class="headerlink" href="#thread-safety" title="永久链接至标题">¶</a></h2>
|
||
<p>logging 模块的目标是使客户端不必执行任何特殊操作即可确保线程安全。 它通过使用线程锁来达成这个目标；用一个锁来序列化对模块共享数据的访问，并且每个处理程序也会创建一个锁来序列化对其下层 I/O 的访问。</p>
|
||
<p>如果你要使用 <a class="reference internal" href="signal.html#module-signal" title="signal: Set handlers for asynchronous events."><code class="xref py py-mod docutils literal notranslate"><span class="pre">signal</span></code></a> 模块来实现异步信号处理程序，则可能无法在这些处理程序中使用 logging。 这是因为 <a class="reference internal" href="threading.html#module-threading" title="threading: Thread-based parallelism."><code class="xref py py-mod docutils literal notranslate"><span class="pre">threading</span></code></a> 模块中的锁实现并非总是可重入的，所以无法从此类信号处理程序发起调用。</p>
|
||
</section>
|
||
<section id="module-level-functions">
|
||
<h2>模块级函数<a class="headerlink" href="#module-level-functions" title="永久链接至标题">¶</a></h2>
|
||
<p>在上述的类之外，还有一些模块级的函数。</p>
|
||
<dl class="function">
|
||
<dt id="logging.getLogger">
|
||
<code class="sig-prename descclassname">logging.</code><code class="sig-name descname">getLogger</code><span class="sig-paren">(</span><em class="sig-param">name=None</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.getLogger" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>返回具有指定 name 的日志记录器，或者当 name 为 <code class="docutils literal notranslate"><span class="pre">None</span></code> 时返回层级结构中的根日志记录器。 如果指定了 name，它通常是以点号分隔的带层级结构的名称，如 <em>'a'</em>、<em>'a.b'</em> 或 <em>'a.b.c.d'</em>。 这些名称的选择完全取决于使用 logging 的开发者。</p>
|
||
<p>所有用给定的 name 对该函数的调用都将返回相同的日志记录器实例。 这意味着日志记录器实例不需要在应用的各部分间传递。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="logging.getLoggerClass">
|
||
<code class="sig-prename descclassname">logging.</code><code class="sig-name descname">getLoggerClass</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#logging.getLoggerClass" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>返回标准的 <a class="reference internal" href="#logging.Logger" title="logging.Logger"><code class="xref py py-class docutils literal notranslate"><span class="pre">Logger</span></code></a> 类，或是最近传给 <a class="reference internal" href="#logging.setLoggerClass" title="logging.setLoggerClass"><code class="xref py py-func docutils literal notranslate"><span class="pre">setLoggerClass()</span></code></a> 的类。 此函数可以从一个新的类定义中调用，以确保安装自定义的 <a class="reference internal" href="#logging.Logger" title="logging.Logger"><code class="xref py py-class docutils literal notranslate"><span class="pre">Logger</span></code></a> 类不会撤销其他代码已经应用的自定义操作。 例如:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">MyLogger</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">getLoggerClass</span><span class="p">()):</span>
|
||
<span class="c1"># ... override behaviour here</span>
|
||
</pre></div>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="logging.getLogRecordFactory">
|
||
<code class="sig-prename descclassname">logging.</code><code class="sig-name descname">getLogRecordFactory</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#logging.getLogRecordFactory" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>返回一个被用来创建 <a class="reference internal" href="#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a> 的可调用对象。</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">3.2 新版功能: </span>此函数与 <a class="reference internal" href="#logging.setLogRecordFactory" title="logging.setLogRecordFactory"><code class="xref py py-func docutils literal notranslate"><span class="pre">setLogRecordFactory()</span></code></a> 一起提供，以允许开发者对表示日志记录事件的 <a class="reference internal" href="#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a> 的构造有更好的控制。</p>
|
||
</div>
|
||
<p>请参阅 <a class="reference internal" href="#logging.setLogRecordFactory" title="logging.setLogRecordFactory"><code class="xref py py-func docutils literal notranslate"><span class="pre">setLogRecordFactory()</span></code></a> 了解有关如何调用该工厂方法的更多信息。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="logging.debug">
|
||
<code class="sig-prename descclassname">logging.</code><code class="sig-name descname">debug</code><span class="sig-paren">(</span><em class="sig-param">msg</em>, <em class="sig-param">*args</em>, <em class="sig-param">**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.debug" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>在根日志记录器上记录一条 <code class="xref py py-const docutils literal notranslate"><span class="pre">DEBUG</span></code> 级别的消息。 <em>msg</em> 是消息格式字符串，而 <em>args</em> 是要使用字符串格式化运算符合并到 <em>msg</em> 的参数。 （请注意这意味着你可以在格式字符串中使用关键字以及单个字典参数。）</p>
|
||
<p>在 <em>kwargs</em> 中有三个关键字参数会被检查: <em>exc_info</em> 参数如果不为假值则会将异常信息添加到日志记录消息。 如果提供了异常元组（为 <a class="reference internal" href="sys.html#sys.exc_info" title="sys.exc_info"><code class="xref py py-func docutils literal notranslate"><span class="pre">sys.exc_info()</span></code></a> 的返回值格式）或异常实例则它会被使用；在其他情况下，会调用 <a class="reference internal" href="sys.html#sys.exc_info" title="sys.exc_info"><code class="xref py py-func docutils literal notranslate"><span class="pre">sys.exc_info()</span></code></a> 以获取异常信息。</p>
|
||
<p>第二个可选关键字参数是 <em>stack_info</em>，默认为 <code class="docutils literal notranslate"><span class="pre">False</span></code>。如果为 True，则将堆栈信息添加到日志消息中，包括实际的日志调用。请注意，这与通过指定 <em>exc_info</em> 显示的堆栈信息不同：前者是从堆栈底部到当前线程中的日志记录调用的堆栈帧，而后者是在搜索异常处理程序时，跟踪异常而打开的堆栈帧的信息。</p>
|
||
<p>您可以独立于 <em>exc_info</em> 来指定 <em>stack_info</em>，例如，即使在未引发任何异常的情况下，也可以显示如何到达代码中的特定点。堆栈帧在标题行之后打印：</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>Stack (most recent call last):
|
||
</pre></div>
|
||
</div>
|
||
<p>这模仿了显示异常帧时所使用的 <code class="docutils literal notranslate"><span class="pre">Traceback</span> <span class="pre">(most</span> <span class="pre">recent</span> <span class="pre">call</span> <span class="pre">last):</span></code> 。</p>
|
||
<p>第三个可选关键字参数是 <em>extra</em>，它可被用来传递一个字典，该字典会被用来填充为日志记录事件创建并附带用户自定义属性的 LogRecord 的 __dict__。 之后将可按你的需要使用这些自定义属性。 例如，可以将它们合并到已记录的消息中。 举例来说:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">FORMAT</span> <span class="o">=</span> <span class="s1">'</span><span class="si">%(asctime)-15s</span><span class="s1"> </span><span class="si">%(clientip)s</span><span class="s1"> </span><span class="si">%(user)-8s</span><span class="s1"> </span><span class="si">%(message)s</span><span class="s1">'</span>
|
||
<span class="n">logging</span><span class="o">.</span><span class="n">basicConfig</span><span class="p">(</span><span class="nb">format</span><span class="o">=</span><span class="n">FORMAT</span><span class="p">)</span>
|
||
<span class="n">d</span> <span class="o">=</span> <span class="p">{</span><span class="s1">'clientip'</span><span class="p">:</span> <span class="s1">'192.168.0.1'</span><span class="p">,</span> <span class="s1">'user'</span><span class="p">:</span> <span class="s1">'fbloggs'</span><span class="p">}</span>
|
||
<span class="n">logging</span><span class="o">.</span><span class="n">warning</span><span class="p">(</span><span class="s1">'Protocol problem: </span><span class="si">%s</span><span class="s1">'</span><span class="p">,</span> <span class="s1">'connection reset'</span><span class="p">,</span> <span class="n">extra</span><span class="o">=</span><span class="n">d</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>应当会打印出这样的内容:</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>2006-02-08 22:20:02,165 192.168.0.1 fbloggs Protocol problem: connection reset
|
||
</pre></div>
|
||
</div>
|
||
<p><em>extra</em> 中传入的字典的键不应与日志系统使用的键冲突。（有关日志系统使用哪些键的更多信息，请参见 <a class="reference internal" href="#logging.Formatter" title="logging.Formatter"><code class="xref py py-class docutils literal notranslate"><span class="pre">Formatter</span></code></a> 的文档。）</p>
|
||
<p>如果你选择在已记录的消息中使用这些属性，则需要格外小心。 例如在上面的示例中，<a class="reference internal" href="#logging.Formatter" title="logging.Formatter"><code class="xref py py-class docutils literal notranslate"><span class="pre">Formatter</span></code></a> 已设置了格式字符串，其在 LogRecord 的属性字典中应有 'clientip' 和 'user'。 如果缺少这些属性，消息将不被记录，因为会引发字符串格式化异常，你始终需要传入带有这些键的 <em>extra</em> 字典。</p>
|
||
<p>尽管这可能很烦人，但此功能旨在用于特殊情况，例如在多个上下文中执行相同代码的多线程服务器，并且出现的有趣条件取决于此上下文（例如在上面的示例中就是远程客户端IP地址和已验证用户名）。在这种情况下，很可能将专门的 <a class="reference internal" href="#logging.Formatter" title="logging.Formatter"><code class="xref py py-class docutils literal notranslate"><span class="pre">Formatter</span></code></a> 与特定的 <a class="reference internal" href="#logging.Handler" title="logging.Handler"><code class="xref py py-class docutils literal notranslate"><span class="pre">Handler</span></code></a> 一起使用。</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.2 版更改: </span>增加了 <em>stack_info</em> 参数。</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="logging.info">
|
||
<code class="sig-prename descclassname">logging.</code><code class="sig-name descname">info</code><span class="sig-paren">(</span><em class="sig-param">msg</em>, <em class="sig-param">*args</em>, <em class="sig-param">**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.info" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>在根日志记录器上记录一条 <code class="xref py py-const docutils literal notranslate"><span class="pre">INFO</span></code> 级别的消息。 参数解释同 <a class="reference internal" href="#logging.debug" title="logging.debug"><code class="xref py py-func docutils literal notranslate"><span class="pre">debug()</span></code></a>。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="logging.warning">
|
||
<code class="sig-prename descclassname">logging.</code><code class="sig-name descname">warning</code><span class="sig-paren">(</span><em class="sig-param">msg</em>, <em class="sig-param">*args</em>, <em class="sig-param">**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.warning" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>在根日志记录器上记录一条 <code class="xref py py-const docutils literal notranslate"><span class="pre">WARNING</span></code> 级别的消息。 参数解释同 <a class="reference internal" href="#logging.debug" title="logging.debug"><code class="xref py py-func docutils literal notranslate"><span class="pre">debug()</span></code></a>。</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">注解</p>
|
||
<p>有一个已过时方法 <code class="docutils literal notranslate"><span class="pre">warn</span></code> 其功能与 <code class="docutils literal notranslate"><span class="pre">warning</span></code> 一致。 由于 <code class="docutils literal notranslate"><span class="pre">warn</span></code> 已被弃用，请不要使用它 —— 而是改用 <code class="docutils literal notranslate"><span class="pre">warning</span></code>。</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="logging.error">
|
||
<code class="sig-prename descclassname">logging.</code><code class="sig-name descname">error</code><span class="sig-paren">(</span><em class="sig-param">msg</em>, <em class="sig-param">*args</em>, <em class="sig-param">**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.error" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>在根日志记录器上记录一条 <code class="xref py py-const docutils literal notranslate"><span class="pre">ERROR</span></code> 级别的消息。 参数解释同 <a class="reference internal" href="#logging.debug" title="logging.debug"><code class="xref py py-func docutils literal notranslate"><span class="pre">debug()</span></code></a>。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="logging.critical">
|
||
<code class="sig-prename descclassname">logging.</code><code class="sig-name descname">critical</code><span class="sig-paren">(</span><em class="sig-param">msg</em>, <em class="sig-param">*args</em>, <em class="sig-param">**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.critical" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>在根日志记录器上记录一条 <code class="xref py py-const docutils literal notranslate"><span class="pre">CRITICAL</span></code> 级别的消息。 参数解释同 <a class="reference internal" href="#logging.debug" title="logging.debug"><code class="xref py py-func docutils literal notranslate"><span class="pre">debug()</span></code></a>。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="logging.exception">
|
||
<code class="sig-prename descclassname">logging.</code><code class="sig-name descname">exception</code><span class="sig-paren">(</span><em class="sig-param">msg</em>, <em class="sig-param">*args</em>, <em class="sig-param">**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.exception" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>在根日志记录器上记录一条 <code class="xref py py-const docutils literal notranslate"><span class="pre">ERROR</span></code> 级别的消息。 参数解释同 <a class="reference internal" href="#logging.debug" title="logging.debug"><code class="xref py py-func docutils literal notranslate"><span class="pre">debug()</span></code></a>。 异常信息将被添加到日志消息中。 此函数应当仅从异常处理程序中调用。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="logging.log">
|
||
<code class="sig-prename descclassname">logging.</code><code class="sig-name descname">log</code><span class="sig-paren">(</span><em class="sig-param">level</em>, <em class="sig-param">msg</em>, <em class="sig-param">*args</em>, <em class="sig-param">**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.log" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>在根日志记录器上记录一条 <em>level</em> 级别的消息。 其他参数解释同 <a class="reference internal" href="#logging.debug" title="logging.debug"><code class="xref py py-func docutils literal notranslate"><span class="pre">debug()</span></code></a>。</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">注解</p>
|
||
<p>上述模块层级的便捷函数均委托给根日志记录器，它们会调用 <a class="reference internal" href="#logging.basicConfig" title="logging.basicConfig"><code class="xref py py-func docutils literal notranslate"><span class="pre">basicConfig()</span></code></a> 以确保至少有一个处理程序可用。 因此，它们 <em>不应</em> 在线程中使用，在 Python 2.7.1 和 3.2 之前的版本中，除非线程启动 <em>之前</em> 已向根日志记录器添加了至少一个处理程序方可使用。 在较早的 Python 版本中，由于 <a class="reference internal" href="#logging.basicConfig" title="logging.basicConfig"><code class="xref py py-func docutils literal notranslate"><span class="pre">basicConfig()</span></code></a> 中存在线程安全性的不足，这（在少数情况下）可能导致处理程序被多次加入根日志记录器，这会进一步导致同一事件出现多条消息。</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="logging.disable">
|
||
<code class="sig-prename descclassname">logging.</code><code class="sig-name descname">disable</code><span class="sig-paren">(</span><em class="sig-param">level=CRITICAL</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.disable" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>为所有日志记录器提供重写的级别 <em>level</em>，其优先级高于日志记录器自己的级别。 当需要临时限制整个应用程序中的日志记录输出时，此功能会很有用。 它的效果是禁用所有重要程度为 <em>level</em> 及以下的日志记录调用，因此如果你附带 INFO 值调用它，则所有 INFO 和 DEBUG 事件就会被丢弃，而重要程度为 WARNING 以及上的事件将根据日志记录器的当前有效级别来处理。 如果 <code class="docutils literal notranslate"><span class="pre">logging.disable(logging.NOTSET)</span></code> 被调用，它将移除这个重写的级别，因此日志记录输出会再次取决于单个日志记录器的有效级别。</p>
|
||
<p>请注意如果你定义了任何高于 <code class="docutils literal notranslate"><span class="pre">CRITICAL</span></code> 的自定义日志级别（并不建议这样做），你就将无法沿用 <em>level</em> 形参的默认值，而必须显式地提供适当的值。</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.7 版更改: </span><em>level</em> 形参默认级别为 <code class="docutils literal notranslate"><span class="pre">CRITICAL</span></code>。 请参阅 <a class="reference external" href="https://bugs.python.org/issue?@action=redirect&bpo=28524">bpo-28524</a> 了解此项改变的更多细节。</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="logging.addLevelName">
|
||
<code class="sig-prename descclassname">logging.</code><code class="sig-name descname">addLevelName</code><span class="sig-paren">(</span><em class="sig-param">level</em>, <em class="sig-param">levelName</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.addLevelName" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>在一个内部字典中关联级别 <em>level</em> 与文本 <em>levelName</em>，该字典会被用来将数字级别映射为文本表示形式，例如在 <a class="reference internal" href="#logging.Formatter" title="logging.Formatter"><code class="xref py py-class docutils literal notranslate"><span class="pre">Formatter</span></code></a> 格式化消息的时候。 此函数也可被用来定义你自己的级别。 唯一的限制是自定义的所有级别必须使用此函数来注册，级别值必须为正整数并且其应随严重程度而递增。</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">注解</p>
|
||
<p>如果你考虑要定义你自己的级别，请参阅 <a class="reference internal" href="../howto/logging.html#custom-levels"><span class="std std-ref">自定义级别</span></a> 部分。</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="logging.getLevelName">
|
||
<code class="sig-prename descclassname">logging.</code><code class="sig-name descname">getLevelName</code><span class="sig-paren">(</span><em class="sig-param">level</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.getLevelName" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>返回日志记录级别 <em>level</em> 的字符串表示。</p>
|
||
<p>如果 <em>level</em> 为预定义的级别 <code class="xref py py-const docutils literal notranslate"><span class="pre">CRITICAL</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">ERROR</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">WARNING</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">INFO</span></code> 或 <code class="xref py py-const docutils literal notranslate"><span class="pre">DEBUG</span></code> 之一则你会得到相应的字符串。 如果你使用 <a class="reference internal" href="#logging.addLevelName" title="logging.addLevelName"><code class="xref py py-func docutils literal notranslate"><span class="pre">addLevelName()</span></code></a> 将级别关联到名称则返回你为 <em>level</em> 所关联的名称。 如果传入了与已定义级别相对应的数字值，则返回对应的字符串表示。</p>
|
||
<p><em>level</em> 形参也接受级别的字符串表示例如 'INFO'。 在这种情况下，此函数将返回级别所对应的数字值。</p>
|
||
<p>如果未传入可匹配的数字或字符串值，则返回字符串 'Level %s' % level。</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">注解</p>
|
||
<p>级别在内部以整数表示（因为它们在日志记录逻辑中需要进行比较）。 此函数被用于在整数级别与通过 <code class="docutils literal notranslate"><span class="pre">%(levelname)s</span></code> 格式描述符方式在格式化日志输出中显示的级别名称之间进行相互的转换 (参见 <a class="reference internal" href="#logrecord-attributes"><span class="std std-ref">LogRecord 属性</span></a>)。</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.4 版更改: </span>在早于 3.4 的 Python 版本中，此函数也可传入一个字符串形式的级别名称，并将返回对应的级别数字值。 此未记入文档的行为被视为是一个错误，并在 Python 3.4 中被移除，但又在 3.4.2 中被恢复以保持向下兼容性。</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="logging.makeLogRecord">
|
||
<code class="sig-prename descclassname">logging.</code><code class="sig-name descname">makeLogRecord</code><span class="sig-paren">(</span><em class="sig-param">attrdict</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.makeLogRecord" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>创建并返回一个新的 <a class="reference internal" href="#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a> 实例，实例属性由 <em>attrdict</em> 定义。 此函数适用于接受一个通过套接字传输的封存好的 <a class="reference internal" href="#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a> 属性字典，并在接收端将其重建为一个 <a class="reference internal" href="#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a> 实例。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="logging.basicConfig">
|
||
<code class="sig-prename descclassname">logging.</code><code class="sig-name descname">basicConfig</code><span class="sig-paren">(</span><em class="sig-param">**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.basicConfig" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>通过使用默认的 <a class="reference internal" href="#logging.Formatter" title="logging.Formatter"><code class="xref py py-class docutils literal notranslate"><span class="pre">Formatter</span></code></a> 创建一个 <a class="reference internal" href="logging.handlers.html#logging.StreamHandler" title="logging.StreamHandler"><code class="xref py py-class docutils literal notranslate"><span class="pre">StreamHandler</span></code></a> 并将其加入根日志记录器来为日志记录系统执行基本配置。 如果没有为根日志记录器定义处理器则 <a class="reference internal" href="#logging.debug" title="logging.debug"><code class="xref py py-func docutils literal notranslate"><span class="pre">debug()</span></code></a>, <a class="reference internal" href="#logging.info" title="logging.info"><code class="xref py py-func docutils literal notranslate"><span class="pre">info()</span></code></a>, <a class="reference internal" href="#logging.warning" title="logging.warning"><code class="xref py py-func docutils literal notranslate"><span class="pre">warning()</span></code></a>, <a class="reference internal" href="#logging.error" title="logging.error"><code class="xref py py-func docutils literal notranslate"><span class="pre">error()</span></code></a> 和 <a class="reference internal" href="#logging.critical" title="logging.critical"><code class="xref py py-func docutils literal notranslate"><span class="pre">critical()</span></code></a> 等函数将自动调用 <a class="reference internal" href="#logging.basicConfig" title="logging.basicConfig"><code class="xref py py-func docutils literal notranslate"><span class="pre">basicConfig()</span></code></a>。</p>
|
||
<p>如果根日志记录器已配置了处理器则此函数将不执行任何操作，除非关键字参数 <em>force</em> 被设为 <code class="docutils literal notranslate"><span class="pre">True</span></code>。</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">注解</p>
|
||
<p>此函数应当在其他线程启动之前从主线程被调用。 在 2.7.1 和 3.2 之前的 Python 版本中，如果此函数从多个线程被调用，一个处理器（在极少的情况下）有可能被多次加入根日志记录器，导致非预期的结果例如日志中的消息出现重复。</p>
|
||
</div>
|
||
<p>支持以下关键字参数。</p>
|
||
<table class="docutils align-default">
|
||
<colgroup>
|
||
<col style="width: 24%" />
|
||
<col style="width: 76%" />
|
||
</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><em>filename</em></p></td>
|
||
<td><p>使用指定的文件名而不是 StreamHandler 创建 FileHandler。</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><em>filemode</em></p></td>
|
||
<td><p>如果指定了 <em>filename</em>，则用此 <a class="reference internal" href="functions.html#filemodes"><span class="std std-ref">模式</span></a> 打开该文件。 默认模式为 <code class="docutils literal notranslate"><span class="pre">'a'</span></code>。</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><em>format</em></p></td>
|
||
<td><p>使用指定的格式字符串作为处理器。 默认为属性以冒号分隔的 <code class="docutils literal notranslate"><span class="pre">levelname</span></code>, <code class="docutils literal notranslate"><span class="pre">name</span></code> 和 <code class="docutils literal notranslate"><span class="pre">message</span></code>。</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><em>datefmt</em></p></td>
|
||
<td><p>使用指定的日期/时间格式，与 <a class="reference internal" href="time.html#time.strftime" title="time.strftime"><code class="xref py py-func docutils literal notranslate"><span class="pre">time.strftime()</span></code></a> 所接受的格式相同。</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><em>style</em></p></td>
|
||
<td><p>如果指定了 <em>format</em>，将为格式字符串使用此风格。 <code class="docutils literal notranslate"><span class="pre">'%'</span></code>, <code class="docutils literal notranslate"><span class="pre">'{'</span></code> 或 <code class="docutils literal notranslate"><span class="pre">'$'</span></code> 分别对应于 <a class="reference internal" href="stdtypes.html#old-string-formatting"><span class="std std-ref">printf 风格</span></a>, <a class="reference internal" href="stdtypes.html#str.format" title="str.format"><code class="xref py py-meth docutils literal notranslate"><span class="pre">str.format()</span></code></a> 或 <a class="reference internal" href="string.html#string.Template" title="string.Template"><code class="xref py py-class docutils literal notranslate"><span class="pre">string.Template</span></code></a>。 默认为 <code class="docutils literal notranslate"><span class="pre">'%'</span></code>。</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><em>level</em></p></td>
|
||
<td><p>设置根记录器级别为指定的 <a class="reference internal" href="#levels"><span class="std std-ref">level</span></a>.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><em>stream</em></p></td>
|
||
<td><p>使用指定的流初始化 StreamHandler。 请注意此参数与 <em>filename</em> 是不兼容的 - 如果两者同时存在，则会引发 <code class="docutils literal notranslate"><span class="pre">ValueError</span></code>。</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><em>handlers</em></p></td>
|
||
<td><p>如果指定，这应为一个包含要加入根日志记录器的已创建处理器的可迭代对象。 任何尚未设置格式描述符的处理器将被设置为在此函数中创建的默认格式描述符。 请注意此参数与 <em>filename</em> 或 <em>stream</em> 不兼容 —— 如果两者同时存在，则会引发 <code class="docutils literal notranslate"><span class="pre">ValueError</span></code>。</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><em>force</em></p></td>
|
||
<td><p>如果将此关键字参数指定为 true，则在执行其他参数指定的配置之前，将移除并关闭附加到根记录器的所有现有处理器。</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.2 版更改: </span>增加了 <em>style</em> 参数。</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.3 版更改: </span>增加了 <em>handlers</em> 参数。 增加了额外的检查来捕获指定不兼容参数的情况 (例如同时指定 <em>handlers</em> 与 <em>stream</em> 或 <em>filename</em>，或者同时指定 <em>stream</em> 与 <em>filename</em>)。</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.8 版更改: </span>增加了 <em>force</em> 参数。</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="logging.shutdown">
|
||
<code class="sig-prename descclassname">logging.</code><code class="sig-name descname">shutdown</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#logging.shutdown" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>通过刷新和关闭所有处理程序来通知日志记录系统执行有序停止。 此函数应当在应用退出时被调用并且在此调用之后不应再使用日志记录系统。</p>
|
||
<p>当 logging 模块被导入时，它会将此函数注册为退出处理程序 (参见 <a class="reference internal" href="atexit.html#module-atexit" title="atexit: Register and execute cleanup functions."><code class="xref py py-mod docutils literal notranslate"><span class="pre">atexit</span></code></a>)，因此通常不需要手动执行该操作。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="logging.setLoggerClass">
|
||
<code class="sig-prename descclassname">logging.</code><code class="sig-name descname">setLoggerClass</code><span class="sig-paren">(</span><em class="sig-param">klass</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.setLoggerClass" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>通知日志记录系统在实例化日志记录器时使用 <em>klass</em> 类。 该类应当定义 <a class="reference internal" href="../reference/datamodel.html#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code></a> 使其只要求一个 name 参数，并且 <a class="reference internal" href="../reference/datamodel.html#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code></a> 应当调用 <code class="xref py py-meth docutils literal notranslate"><span class="pre">Logger.__init__()</span></code>。 此函数通常会在需要使用自定义日志记录器行为的应用程序实例化任何日志记录器之前被调用。 在此调用之后，在任何其他时刻都不要使用该子类来直接实例化日志记录器：请继续使用 <a class="reference internal" href="#logging.getLogger" title="logging.getLogger"><code class="xref py py-func docutils literal notranslate"><span class="pre">logging.getLogger()</span></code></a> API 来获取你的日志记录器。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="logging.setLogRecordFactory">
|
||
<code class="sig-prename descclassname">logging.</code><code class="sig-name descname">setLogRecordFactory</code><span class="sig-paren">(</span><em class="sig-param">factory</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.setLogRecordFactory" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>设置一个用来创建 <a class="reference internal" href="#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a> 的可调用对象。</p>
|
||
<dl class="field-list simple">
|
||
<dt class="field-odd">参数</dt>
|
||
<dd class="field-odd"><p><strong>factory</strong> -- 用来实例化日志记录的工厂可调用对象。</p>
|
||
</dd>
|
||
</dl>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">3.2 新版功能: </span>此函数与 <a class="reference internal" href="#logging.getLogRecordFactory" title="logging.getLogRecordFactory"><code class="xref py py-func docutils literal notranslate"><span class="pre">getLogRecordFactory()</span></code></a> 一起提供，以便允许开发者对如何构造表示日志记录事件的 <a class="reference internal" href="#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a> 有更好的控制。</p>
|
||
</div>
|
||
<p>可调用对象 factory 具有如下签名:</p>
|
||
<p><code class="docutils literal notranslate"><span class="pre">factory(name,</span> <span class="pre">level,</span> <span class="pre">fn,</span> <span class="pre">lno,</span> <span class="pre">msg,</span> <span class="pre">args,</span> <span class="pre">exc_info,</span> <span class="pre">func=None,</span> <span class="pre">sinfo=None,</span> <span class="pre">**kwargs)</span></code></p>
|
||
<blockquote>
|
||
<div><dl class="field-list simple">
|
||
<dt class="field-odd">name</dt>
|
||
<dd class="field-odd"><p>日志记录器名称</p>
|
||
</dd>
|
||
<dt class="field-even">level</dt>
|
||
<dd class="field-even"><p>日志记录级别（数字）。</p>
|
||
</dd>
|
||
<dt class="field-odd">fn</dt>
|
||
<dd class="field-odd"><p>进行日志记录调用的文件的完整路径名。</p>
|
||
</dd>
|
||
<dt class="field-even">lno</dt>
|
||
<dd class="field-even"><p>记录调用所在文件中的行号。</p>
|
||
</dd>
|
||
<dt class="field-odd">msg</dt>
|
||
<dd class="field-odd"><p>日志消息。</p>
|
||
</dd>
|
||
<dt class="field-even">args</dt>
|
||
<dd class="field-even"><p>日志记录消息的参数。</p>
|
||
</dd>
|
||
<dt class="field-odd">exc_info</dt>
|
||
<dd class="field-odd"><p>异常元组，或 <code class="docutils literal notranslate"><span class="pre">None</span></code> 。</p>
|
||
</dd>
|
||
<dt class="field-even">func</dt>
|
||
<dd class="field-even"><p>调用日志记录调用的函数或方法的名称。</p>
|
||
</dd>
|
||
<dt class="field-odd">sinfo</dt>
|
||
<dd class="field-odd"><p>与 <a class="reference internal" href="traceback.html#traceback.print_stack" title="traceback.print_stack"><code class="xref py py-func docutils literal notranslate"><span class="pre">traceback.print_stack()</span></code></a> 所提供的类似的栈回溯信息，显示调用的层级结构。</p>
|
||
</dd>
|
||
<dt class="field-even">kwargs</dt>
|
||
<dd class="field-even"><p>其他关键字参数。</p>
|
||
</dd>
|
||
</dl>
|
||
</div></blockquote>
|
||
</dd></dl>
|
||
|
||
</section>
|
||
<section id="module-level-attributes">
|
||
<h2>模块级属性<a class="headerlink" href="#module-level-attributes" title="永久链接至标题">¶</a></h2>
|
||
<dl class="attribute">
|
||
<dt id="logging.lastResort">
|
||
<code class="sig-prename descclassname">logging.</code><code class="sig-name descname">lastResort</code><a class="headerlink" href="#logging.lastResort" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>通过此属性提供的“最后处理者”。 这是一个以 <code class="docutils literal notranslate"><span class="pre">WARNING</span></code> 级别写入到 <code class="docutils literal notranslate"><span class="pre">sys.stderr</span></code> 的 <a class="reference internal" href="logging.handlers.html#logging.StreamHandler" title="logging.StreamHandler"><code class="xref py py-class docutils literal notranslate"><span class="pre">StreamHandler</span></code></a>，用于在没有任何日志记录配置的情况下处理日志记录事件。 最终结果就是将消息打印到 <code class="docutils literal notranslate"><span class="pre">sys.stderr</span></code>，这会替代先前形式为 "no handlers could be found for logger XYZ" 的错误消息。 如果出于某种原因你需要先前的行为，可将 <code class="docutils literal notranslate"><span class="pre">lastResort</span></code> 设为 <code class="docutils literal notranslate"><span class="pre">None</span></code>。</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">3.2 新版功能.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
</section>
|
||
<section id="integration-with-the-warnings-module">
|
||
<h2>与警告模块集成<a class="headerlink" href="#integration-with-the-warnings-module" title="永久链接至标题">¶</a></h2>
|
||
<p><a class="reference internal" href="#logging.captureWarnings" title="logging.captureWarnings"><code class="xref py py-func docutils literal notranslate"><span class="pre">captureWarnings()</span></code></a> 函数可用来将 <a class="reference internal" href="#module-logging" title="logging: Flexible event logging system for applications."><code class="xref py py-mod docutils literal notranslate"><span class="pre">logging</span></code></a> 和 <a class="reference internal" href="warnings.html#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>
|
||
<dl class="function">
|
||
<dt id="logging.captureWarnings">
|
||
<code class="sig-prename descclassname">logging.</code><code class="sig-name descname">captureWarnings</code><span class="sig-paren">(</span><em class="sig-param">capture</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.captureWarnings" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>此函数用于打开和关闭日志系统对警告的捕获。</p>
|
||
<p>如果 <em>capture</em> 是 <code class="docutils literal notranslate"><span class="pre">True</span></code>，则 <a class="reference internal" href="warnings.html#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="warnings.html#warnings.formatwarning" title="warnings.formatwarning"><code class="xref py py-func docutils literal notranslate"><span class="pre">warnings.formatwarning()</span></code></a> 格式化警告信息，并将结果字符串使用 <code class="xref py py-const docutils literal notranslate"><span class="pre">WARNING</span></code> 等级记录到名为 <code class="docutils literal notranslate"><span class="pre">'py.warnings'</span></code> 的记录器中。</p>
|
||
<p>如果 <em>capture</em> 是 <code class="docutils literal notranslate"><span class="pre">False</span></code>，则将停止将警告重定向到日志记录系统，并且将警告重定向到其原始目标（即在 <code class="docutils literal notranslate"><span class="pre">captureWarnings(True)</span></code> 调用之前的有效目标）。</p>
|
||
</dd></dl>
|
||
|
||
<div class="admonition seealso">
|
||
<p class="admonition-title">参见</p>
|
||
<dl class="simple">
|
||
<dt><a class="reference internal" href="logging.config.html#module-logging.config" title="logging.config: Configuration of the logging module."><code class="xref py py-mod docutils literal notranslate"><span class="pre">logging.config</span></code></a> 模块</dt><dd><p>日志记录模块的配置 API 。</p>
|
||
</dd>
|
||
<dt><a class="reference internal" href="logging.handlers.html#module-logging.handlers" title="logging.handlers: Handlers for the logging module."><code class="xref py py-mod docutils literal notranslate"><span class="pre">logging.handlers</span></code></a> 模块</dt><dd><p>日志记录模块附带的有用处理器。</p>
|
||
</dd>
|
||
<dt><span class="target" id="index-3"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0282"><strong>PEP 282</strong></a> - Logging 系统</dt><dd><p>该提案描述了Python标准库中包含的这个特性。</p>
|
||
</dd>
|
||
<dt><a class="reference external" href="https://www.red-dove.com/python_logging.html">Original Python logging package</a></dt><dd><p>这是该 <a class="reference internal" href="#module-logging" title="logging: Flexible event logging system for applications."><code class="xref py py-mod docutils literal notranslate"><span class="pre">logging</span></code></a> 包的原始来源。该站点提供的软件包版本适用于 Python 1.5.2、2.1.x 和 2.2.x，它们不被 <a class="reference internal" href="#module-logging" title="logging: Flexible event logging system for applications."><code class="xref py py-mod docutils literal notranslate"><span class="pre">logging</span></code></a> 包含在标准库中。</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
</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">logging</span></code> --- Python 的日志记录工具</a><ul>
|
||
<li><a class="reference internal" href="#logger-objects">记录器对象</a></li>
|
||
<li><a class="reference internal" href="#logging-levels">日志级别</a></li>
|
||
<li><a class="reference internal" href="#handler-objects">处理器对象</a></li>
|
||
<li><a class="reference internal" href="#formatter-objects">格式器对象</a></li>
|
||
<li><a class="reference internal" href="#filter-objects">过滤器对象</a></li>
|
||
<li><a class="reference internal" href="#logrecord-objects">LogRecord 属性</a></li>
|
||
<li><a class="reference internal" href="#logrecord-attributes">LogRecord 属性</a></li>
|
||
<li><a class="reference internal" href="#loggeradapter-objects">LoggerAdapter 对象</a></li>
|
||
<li><a class="reference internal" href="#thread-safety">线程安全</a></li>
|
||
<li><a class="reference internal" href="#module-level-functions">模块级函数</a></li>
|
||
<li><a class="reference internal" href="#module-level-attributes">模块级属性</a></li>
|
||
<li><a class="reference internal" href="#integration-with-the-warnings-module">与警告模块集成</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
<h4>上一个主题</h4>
|
||
<p class="topless"><a href="getopt.html"
|
||
title="上一章"><code class="xref py py-mod docutils literal notranslate"><span class="pre">getopt</span></code> --- C 风格的命令行选项解析器</a></p>
|
||
<h4>下一个主题</h4>
|
||
<p class="topless"><a href="logging.config.html"
|
||
title="下一章"><code class="xref py py-mod docutils literal notranslate"><span class="pre">logging.config</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/logging.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="logging.config.html" title="logging.config --- 日志记录配置"
|
||
>下一页</a> |</li>
|
||
<li class="right" >
|
||
<a href="getopt.html" title="getopt --- C 风格的命令行选项解析器"
|
||
>上一页</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="allos.html" >通用操作系统服务</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> |