study/uTools-Manuals
1
0
Fork 0
mirror of https://github.com/fofolee/uTools-Manuals.git synced 2025-06-08 15:04:05 +08:00
Code Issues Packages Projects Releases Wiki Activity
uTools-Manuals/docs/python/logging.html
fofolee 38dcd51d8a v0.0.2
2019-04-21 11:50:48 +08:00

24 lines
134 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<div class="body" role="main"><div class="section" id="module-logging"><h1><span class="yiyi-st" id="yiyi-10">16.6. <a class="reference internal" href="#module-logging" title="logging: Flexible event logging system for applications."><code class="xref py py-mod docutils literal"><span class="pre">logging</span></code></a> — Logging facility for Python</span></h1><p><span class="yiyi-st" id="yiyi-11"><strong>源代码:</strong> <a class="reference external" href="https://hg.python.org/cpython/file/3.5/Lib/logging/__init__.py">Lib/logging/__init__.py</a></span></p><div class="sidebar" id="index-0"><p class="first sidebar-title"><span class="yiyi-st" id="yiyi-12">Important</span></p><p><span class="yiyi-st" id="yiyi-13">此页面包含API参考信息。</span><span class="yiyi-st" id="yiyi-14">有关更多高级主题的教程信息和讨论，请参阅</span></p><ul class="last simple"><li><span class="yiyi-st" id="yiyi-15"><a class="reference internal" href="../howto/logging.html#logging-basic-tutorial"><span>基础教程</span></a></span></li><li><span class="yiyi-st" id="yiyi-16"><a class="reference internal" href="../howto/logging.html#logging-advanced-tutorial"><span>进阶教程</span></a></span></li><li><span class="yiyi-st" id="yiyi-17"><a class="reference internal" href="../howto/logging-cookbook.html#logging-cookbook"><span>Logging Cookbook</span></a></span></li></ul></div><p><span class="yiyi-st" id="yiyi-18">该模块定义了为应用程序和库实现灵活事件记录系统的函数和类。</span></p><p><span class="yiyi-st" id="yiyi-19">The key benefit of having the logging API provided by a standard library module is that all Python modules can participate in logging, so your application log can include your own messages integrated with messages from third-party modules.</span></p><p><span class="yiyi-st" id="yiyi-20">The module provides a lot of functionality and flexibility. </span><span class="yiyi-st" id="yiyi-21">If you are unfamiliar with logging, the best way to get to grips with it is to see the tutorials (see the links on the right).</span></p><p><span class="yiyi-st" id="yiyi-22">The basic classes defined by the module, together with their functions, are listed below.</span></p><ul class="simple"><li><span class="yiyi-st" id="yiyi-23">Loggers expose the interface that application code directly uses.</span></li><li><span class="yiyi-st" id="yiyi-24">Handlers send the log records (created by loggers) to the appropriate destination.</span></li><li><span class="yiyi-st" id="yiyi-25">Filters provide a finer grained facility for determining which log records to output.</span></li><li><span class="yiyi-st" id="yiyi-26">Formatters specify the layout of log records in the final output.</span></li></ul><div class="section" id="logger-objects"><h2><span class="yiyi-st" id="yiyi-27">16.6.1. </span><span class="yiyi-st" id="yiyi-28">Logger Objects</span></h2><p><span class="yiyi-st" id="yiyi-29">Loggers have the following attributes and methods. </span><span class="yiyi-st" id="yiyi-30">Logger对象一般不会直接实例化得到，而是通过模块级别的函数<code class="docutils literal"><span class="pre">logging.getLogger(name)</span></code>得到。</span><span class="yiyi-st" id="yiyi-31">Multiple calls to <a class="reference internal" href="#logging.getLogger" title="logging.getLogger"><code class="xref py py-func docutils literal"><span class="pre">getLogger()</span></code></a> with the same name will always return a reference to the same Logger object.</span></p><p><span class="yiyi-st" id="yiyi-32">The <code class="docutils literal"><span class="pre">name</span></code> is potentially a period-separated hierarchical value, like <code class="docutils literal"><span class="pre">foo.bar.baz</span></code> (though it could also be just plain <code class="docutils literal"><span class="pre">foo</span></code>, for example). </span><span class="yiyi-st" id="yiyi-33">Loggers that are further down in the hierarchical list are children of loggers higher up in the list. </span><span class="yiyi-st" id="yiyi-34">例如，对于给定的一个logger对象 <code class="docutils literal"><span class="pre">foo</span></code>，其它logger对象<code class="docutils literal"><span class="pre">foo.bar</span></code>, <code class="docutils literal"><span class="pre">foo.bar.baz</span></code>, <code class="docutils literal"><span class="pre">foo.bam</span></code>，它们都是<code class="docutils literal"><span class="pre">foo</span></code>的子辈。</span><span class="yiyi-st" id="yiyi-35">logger对象名字的层级和python包的层级是相似的,并且如果你使用推荐的结构<code class="docutils literal"><span class="pre">logging.getLogger(__name__)</span></code>来管理你的loggers对象的话，那就与python包的层级结构是一模一样的。</span><span class="yiyi-st" id="yiyi-36">因为在一个模块中<code class="docutils literal"><span class="pre">__name__</span></code>是一个在python包中名字空间的模块的名称。</span></p><dl class="class"><dt id="logging.Logger"><span class="yiyi-st" id="yiyi-37"> <em class="property">class </em><code class="descclassname">logging.</code><code class="descname">Logger</code></span></dt><dd></dd></dl><dl class="attribute"><dt id="logging.Logger.propagate"><span class="yiyi-st" id="yiyi-38"> <code class="descclassname">Logger.</code><code class="descname">propagate</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-39">If this evaluates to true, events logged to this logger will be passed to the handlers of higher level (ancestor) loggers, in addition to any handlers attached to this logger. </span><span class="yiyi-st" id="yiyi-40">Messages are passed directly to the ancestor loggers’ handlers - neither the level nor filters of the ancestor loggers in question are considered.</span></p><p><span class="yiyi-st" id="yiyi-41">If this evaluates to false, logging messages are not passed to the handlers of ancestor loggers.</span></p><p><span class="yiyi-st" id="yiyi-42">The constructor sets this attribute to <code class="docutils literal"><span class="pre">True</span></code>.</span></p><div class="admonition note"><p class="first admonition-title"><span class="yiyi-st" id="yiyi-43">Note</span></p><p class="last"><span class="yiyi-st" id="yiyi-44">如果将处理程序附加到记录器<em>和</em>其一个或多个祖先，它可能会多次发出相同的记录。</span><span class="yiyi-st" id="yiyi-45">In general, you should not need to attach a handler to more than one logger - if you just attach it to the appropriate logger which is highest in the logger hierarchy, then it will see all events logged by all descendant loggers, provided that their propagate setting is left set to <code class="docutils literal"><span class="pre">True</span></code>. </span><span class="yiyi-st" id="yiyi-46">A common scenario is to attach handlers only to the root logger, and to let propagation take care of the rest.</span></p></div></dd></dl><dl class="method"><dt id="logging.Logger.setLevel"><span class="yiyi-st" id="yiyi-47"> <code class="descclassname">Logger.</code><code class="descname">setLevel</code><span class="sig-paren">(</span><em>lvl</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-48">Sets the threshold for this logger to <em>lvl</em>. </span><span class="yiyi-st" id="yiyi-49">Logging messages which are less severe than <em>lvl</em> will be ignored. </span><span class="yiyi-st" id="yiyi-50">When a logger is created, the level is set to <code class="xref py py-const docutils literal"><span class="pre">NOTSET</span></code> (which causes all messages to be processed when the logger is the root logger, or delegation to the parent when the logger is a non-root logger). </span><span class="yiyi-st" id="yiyi-51">Note that the root logger is created with level <code class="xref py py-const docutils literal"><span class="pre">WARNING</span></code>.</span></p><p><span class="yiyi-st" id="yiyi-52">The term ‘delegation to the parent’ means that if a logger has a level of NOTSET, its chain of ancestor loggers is traversed until either an ancestor with a level other than NOTSET is found, or the root is reached.</span></p><p><span class="yiyi-st" id="yiyi-53">If an ancestor is found with a level other than NOTSET, then that ancestor’s level is treated as the effective level of the logger where the ancestor search began, and is used to determine how a logging event is handled.</span></p><p><span class="yiyi-st" id="yiyi-54">If the root is reached, and it has a level of NOTSET, then all messages will be processed. </span><span class="yiyi-st" id="yiyi-55">Otherwise, the root’s level will be used as the effective level.</span></p><p><span class="yiyi-st" id="yiyi-56">See <a class="reference internal" href="#levels"><span>Logging Levels</span></a> for a list of levels.</span></p><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-57"><span class="versionmodified">Changed in version 3.2: </span>The <em>lvl</em> parameter now accepts a string representation of the level such as ‘INFO’ as an alternative to the integer constants such as <code class="xref py py-const docutils literal"><span class="pre">INFO</span></code>. </span><span class="yiyi-st" id="yiyi-58">然而，注意，级别在内部存储为整数，并且方法例如</span><span class="yiyi-st" id="yiyi-59"><a class="reference internal" href="#logging.Logger.getEffectiveLevel" title="logging.Logger.getEffectiveLevel"><code class="xref py py-meth docutils literal"><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"><span class="pre">isEnabledFor()</span></code></a>将返回/期望被传递的整数。</span></p></div></dd></dl><dl class="method"><dt id="logging.Logger.isEnabledFor"><span class="yiyi-st" id="yiyi-60"> <code class="descclassname">Logger.</code><code class="descname">isEnabledFor</code><span class="sig-paren">(</span><em>lvl</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-61">Indicates if a message of severity <em>lvl</em> would be processed by this logger. </span><span class="yiyi-st" id="yiyi-62">This method checks first the module-level level set by <code class="docutils literal"><span class="pre">logging.disable(lvl)</span></code> and then the logger’s effective level as determined by <a class="reference internal" href="#logging.Logger.getEffectiveLevel" title="logging.Logger.getEffectiveLevel"><code class="xref py py-meth docutils literal"><span class="pre">getEffectiveLevel()</span></code></a>.</span></p></dd></dl><dl class="method"><dt id="logging.Logger.getEffectiveLevel"><span class="yiyi-st" id="yiyi-63"> <code class="descclassname">Logger.</code><code class="descname">getEffectiveLevel</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-64">Indicates the effective level for this logger. </span><span class="yiyi-st" id="yiyi-65">If a value other than <code class="xref py py-const docutils literal"><span class="pre">NOTSET</span></code> has been set using <a class="reference internal" href="#logging.Logger.setLevel" title="logging.Logger.setLevel"><code class="xref py py-meth docutils literal"><span class="pre">setLevel()</span></code></a>, it is returned. </span><span class="yiyi-st" id="yiyi-66">否则，将向根向前遍历层次结构，直到找到除<code class="xref py py-const docutils literal"><span class="pre">NOTSET</span></code>之外的值，并返回该值。</span><span class="yiyi-st" id="yiyi-67">返回的值是一个整数，通常为<code class="xref py py-const docutils literal"><span class="pre">logging.DEBUG</span></code>，<code class="xref py py-const docutils literal"><span class="pre">logging.INFO</span></code>等。</span></p></dd></dl><dl class="method"><dt id="logging.Logger.getChild"><span class="yiyi-st" id="yiyi-68"> <code class="descclassname">Logger.</code><code class="descname">getChild</code><span class="sig-paren">(</span><em>suffix</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-69">Returns a logger which is a descendant to this logger, as determined by the suffix. </span><span class="yiyi-st" id="yiyi-70">Thus, <code class="docutils literal"><span class="pre">logging.getLogger('abc').getChild('def.ghi')</span></code> would return the same logger as would be returned by <code class="docutils literal"><span class="pre">logging.getLogger('abc.def.ghi')</span></code>. </span><span class="yiyi-st" id="yiyi-71">这是一个方便的方法，当父记录器使用例如</span><span class="yiyi-st" id="yiyi-72"><code class="docutils literal"><span class="pre">__ name __</span></code>而不是字面值字符串。</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-73"><span class="versionmodified">版本3.2中的新功能。</span></span></p></div></dd></dl><dl class="method"><dt id="logging.Logger.debug"><span class="yiyi-st" id="yiyi-74"> <code class="descclassname">Logger.</code><code class="descname">debug</code><span class="sig-paren">(</span><em>msg</em>, <em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-75">Logs a message with level <code class="xref py py-const docutils literal"><span class="pre">DEBUG</span></code> on this logger. </span><span class="yiyi-st" id="yiyi-76">The <em>msg</em> is the message format string, and the <em>args</em> are the arguments which are merged into <em>msg</em> using the string formatting operator. </span><span class="yiyi-st" id="yiyi-77">(Note that this means that you can use keywords in the format string, together with a single dictionary argument.)</span></p><p><span class="yiyi-st" id="yiyi-78">在<em>kwargs</em>中有三个关键字参数，它们被检查：<em>exc_info</em>，<em>stack_info</em>和<em>extra</em>。</span></p><p><span class="yiyi-st" id="yiyi-79">如果<em>exc_info</em>不计算为假，则会导致将异常信息添加到日志记录消息中。</span><span class="yiyi-st" id="yiyi-80">如果提供了异常元组（以<a class="reference internal" href="sys.html#sys.exc_info" title="sys.exc_info"><code class="xref py py-func docutils literal"><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"><span class="pre">sys.exc_info()</span></code></a>以获取异常信息。</span></p><p><span class="yiyi-st" id="yiyi-81">第二个可选的关键字参数是<em>stack_info</em>，默认为<code class="docutils literal"><span class="pre">False</span></code>。</span><span class="yiyi-st" id="yiyi-82">如果为true，则将堆栈信息添加到日志记录消息中，包括实际的日志调用。</span><span class="yiyi-st" id="yiyi-83">注意，这不是通过指定<em>exc_info</em>显示的堆栈信息：前者是从堆栈底部到当前线程中的日志调用的堆栈帧，而后者是有关堆栈帧，它们在寻找异常处理程序时例外之后被解开。</span></p><p><span class="yiyi-st" id="yiyi-84">您可以独立于<em>exc_info</em>指定<em>stack_info</em>，例如</span><span class="yiyi-st" id="yiyi-85">只是展示你如何到达代码中的某一点，即使没有引发异常。</span><span class="yiyi-st" id="yiyi-86">堆栈帧打印在标题行后面，说：</span></p><pre><code class="language-python"><span></span><span class="n">Stack</span> <span class="p">(</span><span class="n">most</span> <span class="n">recent</span> <span class="n">call</span> <span class="n">last</span><span class="p">):</span>
</code></pre><p><span class="yiyi-st" id="yiyi-87">This mimics the <code class="docutils literal"><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> which is used when displaying exception frames.</span></p><p><span class="yiyi-st" id="yiyi-88">第三个关键字参数是<em>extra</em>，可用于传递一个字典，用于填充为具有用户定义属性的日志记录事件创建的LogRecord的__dict__。</span><span class="yiyi-st" id="yiyi-89">These custom attributes can then be used as you like. </span><span class="yiyi-st" id="yiyi-90">For example, they could be incorporated into logged messages. </span><span class="yiyi-st" id="yiyi-91">For example:</span></p><pre><code class="language-python"><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>
</code></pre><p><span class="yiyi-st" id="yiyi-92">would print something like</span></p><pre><code class="language-python"><span></span><span class="mi">2006</span><span class="o">-</span><span class="mi">02</span><span class="o">-</span><span class="mi">08</span> <span class="mi">22</span><span class="p">:</span><span class="mi">20</span><span class="p">:</span><span class="mi">02</span><span class="p">,</span><span class="mi">165</span> <span class="mf">192.168</span><span class="o">.</span><span class="mf">0.1</span> <span class="n">fbloggs</span> <span class="n">Protocol</span> <span class="n">problem</span><span class="p">:</span> <span class="n">connection</span> <span class="n">reset</span>
</code></pre><p><span class="yiyi-st" id="yiyi-93">The keys in the dictionary passed in <em>extra</em> should not clash with the keys used by the logging system. </span><span class="yiyi-st" id="yiyi-94">(See the <a class="reference internal" href="#logging.Formatter" title="logging.Formatter"><code class="xref py py-class docutils literal"><span class="pre">Formatter</span></code></a> documentation for more information on which keys are used by the logging system.)</span></p><p><span class="yiyi-st" id="yiyi-95">If you choose to use these attributes in logged messages, you need to exercise some care. </span><span class="yiyi-st" id="yiyi-96">In the above example, for instance, the <a class="reference internal" href="#logging.Formatter" title="logging.Formatter"><code class="xref py py-class docutils literal"><span class="pre">Formatter</span></code></a> has been set up with a format string which expects ‘clientip’ and ‘user’ in the attribute dictionary of the LogRecord. </span><span class="yiyi-st" id="yiyi-97">If these are missing, the message will not be logged because a string formatting exception will occur. </span><span class="yiyi-st" id="yiyi-98">So in this case, you always need to pass the <em>extra</em> dictionary with these keys.</span></p><p><span class="yiyi-st" id="yiyi-99">While this might be annoying, this feature is intended for use in specialized circumstances, such as multi-threaded servers where the same code executes in many contexts, and interesting conditions which arise are dependent on this context (such as remote client IP address and authenticated user name, in the above example). </span><span class="yiyi-st" id="yiyi-100">In such circumstances, it is likely that specialized <a class="reference internal" href="#logging.Formatter" title="logging.Formatter"><code class="xref py py-class docutils literal"><span class="pre">Formatter</span></code></a>s would be used with particular <code class="xref py py-class docutils literal"><span class="pre">Handler</span></code>s.</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-101"><span class="versionmodified">New in version 3.2: </span>The <em>stack_info</em> parameter was added.</span></p></div><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-102"><span class="versionmodified">Changed in version 3.5: </span>The <em>exc_info</em> parameter can now accept exception instances.</span></p></div></dd></dl><dl class="method"><dt id="logging.Logger.info"><span class="yiyi-st" id="yiyi-103"> <code class="descclassname">Logger.</code><code class="descname">info</code><span class="sig-paren">(</span><em>msg</em>, <em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-104">Logs a message with level <code class="xref py py-const docutils literal"><span class="pre">INFO</span></code> on this logger. </span><span class="yiyi-st" id="yiyi-105">The arguments are interpreted as for <a class="reference internal" href="#logging.debug" title="logging.debug"><code class="xref py py-meth docutils literal"><span class="pre">debug()</span></code></a>.</span></p></dd></dl><dl class="method"><dt id="logging.Logger.warning"><span class="yiyi-st" id="yiyi-106"> <code class="descclassname">Logger.</code><code class="descname">warning</code><span class="sig-paren">(</span><em>msg</em>, <em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-107">Logs a message with level <code class="xref py py-const docutils literal"><span class="pre">WARNING</span></code> on this logger. </span><span class="yiyi-st" id="yiyi-108">The arguments are interpreted as for <a class="reference internal" href="#logging.debug" title="logging.debug"><code class="xref py py-meth docutils literal"><span class="pre">debug()</span></code></a>.</span></p><div class="admonition note"><p class="first admonition-title"><span class="yiyi-st" id="yiyi-109">Note</span></p><p class="last"><span class="yiyi-st" id="yiyi-110">有一个过时的方法<code class="docutils literal"><span class="pre">warn</span></code>，其功能与<code class="docutils literal"><span class="pre">warning</span></code>相同。</span><span class="yiyi-st" id="yiyi-111">由于<code class="docutils literal"><span class="pre">warn</span></code>已弃用，请不要使用它 - 请改用<code class="docutils literal"><span class="pre">warning</span></code>。</span></p></div></dd></dl><dl class="method"><dt id="logging.Logger.error"><span class="yiyi-st" id="yiyi-112"> <code class="descclassname">Logger.</code><code class="descname">error</code><span class="sig-paren">(</span><em>msg</em>, <em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-113">Logs a message with level <code class="xref py py-const docutils literal"><span class="pre">ERROR</span></code> on this logger. </span><span class="yiyi-st" id="yiyi-114">The arguments are interpreted as for <a class="reference internal" href="#logging.debug" title="logging.debug"><code class="xref py py-meth docutils literal"><span class="pre">debug()</span></code></a>.</span></p></dd></dl><dl class="method"><dt id="logging.Logger.critical"><span class="yiyi-st" id="yiyi-115"> <code class="descclassname">Logger.</code><code class="descname">critical</code><span class="sig-paren">(</span><em>msg</em>, <em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-116">Logs a message with level <code class="xref py py-const docutils literal"><span class="pre">CRITICAL</span></code> on this logger. </span><span class="yiyi-st" id="yiyi-117">The arguments are interpreted as for <a class="reference internal" href="#logging.debug" title="logging.debug"><code class="xref py py-meth docutils literal"><span class="pre">debug()</span></code></a>.</span></p></dd></dl><dl class="method"><dt id="logging.Logger.log"><span class="yiyi-st" id="yiyi-118"> <code class="descclassname">Logger.</code><code class="descname">log</code><span class="sig-paren">(</span><em>lvl</em>, <em>msg</em>, <em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-119">Logs a message with integer level <em>lvl</em> on this logger. </span><span class="yiyi-st" id="yiyi-120">The other arguments are interpreted as for <a class="reference internal" href="#logging.debug" title="logging.debug"><code class="xref py py-meth docutils literal"><span class="pre">debug()</span></code></a>.</span></p></dd></dl><dl class="method"><dt id="logging.Logger.exception"><span class="yiyi-st" id="yiyi-121"> <code class="descclassname">Logger.</code><code class="descname">exception</code><span class="sig-paren">(</span><em>msg</em>, <em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-122">Logs a message with level <code class="xref py py-const docutils literal"><span class="pre">ERROR</span></code> on this logger. </span><span class="yiyi-st" id="yiyi-123">The arguments are interpreted as for <a class="reference internal" href="#logging.debug" title="logging.debug"><code class="xref py py-meth docutils literal"><span class="pre">debug()</span></code></a>. </span><span class="yiyi-st" id="yiyi-124">Exception info is added to the logging message. </span><span class="yiyi-st" id="yiyi-125">This method should only be called from an exception handler.</span></p></dd></dl><dl class="method"><dt id="logging.Logger.addFilter"><span class="yiyi-st" id="yiyi-126"> <code class="descclassname">Logger.</code><code class="descname">addFilter</code><span class="sig-paren">(</span><em>filt</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-127">Adds the specified filter <em>filt</em> to this logger.</span></p></dd></dl><dl class="method"><dt id="logging.Logger.removeFilter"><span class="yiyi-st" id="yiyi-128"> <code class="descclassname">Logger.</code><code class="descname">removeFilter</code><span class="sig-paren">(</span><em>filt</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-129">Removes the specified filter <em>filt</em> from this logger.</span></p></dd></dl><dl class="method"><dt id="logging.Logger.filter"><span class="yiyi-st" id="yiyi-130"> <code class="descclassname">Logger.</code><code class="descname">filter</code><span class="sig-paren">(</span><em>record</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-131">Applies this logger’s filters to the record and returns a true value if the record is to be processed. </span><span class="yiyi-st" id="yiyi-132">The filters are consulted in turn, until one of them returns a false value. </span><span class="yiyi-st" id="yiyi-133">If none of them return a false value, the record will be processed (passed to handlers). </span><span class="yiyi-st" id="yiyi-134">If one returns a false value, no further processing of the record occurs.</span></p></dd></dl><dl class="method"><dt id="logging.Logger.addHandler"><span class="yiyi-st" id="yiyi-135"> <code class="descclassname">Logger.</code><code class="descname">addHandler</code><span class="sig-paren">(</span><em>hdlr</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-136">Adds the specified handler <em>hdlr</em> to this logger.</span></p></dd></dl><dl class="method"><dt id="logging.Logger.removeHandler"><span class="yiyi-st" id="yiyi-137"> <code class="descclassname">Logger.</code><code class="descname">removeHandler</code><span class="sig-paren">(</span><em>hdlr</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-138">Removes the specified handler <em>hdlr</em> from this logger.</span></p></dd></dl><dl class="method"><dt id="logging.Logger.findCaller"><span class="yiyi-st" id="yiyi-139"> <code class="descclassname">Logger.</code><code class="descname">findCaller</code><span class="sig-paren">(</span><em>stack_info=False</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-140">Finds the caller’s source filename and line number. </span><span class="yiyi-st" id="yiyi-141">将文件名，行号，函数名和堆栈信息作为4元素元组返回。</span><span class="yiyi-st" id="yiyi-142">除非<em>stack_info</em>为<em>True</em>，否则堆栈信息将作为<em>无</em>返回。</span></p></dd></dl><dl class="method"><dt id="logging.Logger.handle"><span class="yiyi-st" id="yiyi-143"> <code class="descclassname">Logger.</code><code class="descname">handle</code><span class="sig-paren">(</span><em>record</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-144">Handles a record by passing it to all handlers associated with this logger and its ancestors (until a false value of <em>propagate</em> is found). </span><span class="yiyi-st" id="yiyi-145">This method is used for unpickled records received from a socket, as well as those created locally. </span><span class="yiyi-st" id="yiyi-146">Logger-level filtering is applied using <a class="reference internal" href="#logging.Logger.filter" title="logging.Logger.filter"><code class="xref py py-meth docutils literal"><span class="pre">filter()</span></code></a>.</span></p></dd></dl><dl class="method"><dt id="logging.Logger.makeRecord"><span class="yiyi-st" id="yiyi-147"> <code class="descclassname">Logger.</code><code class="descname">makeRecord</code><span class="sig-paren">(</span><em>name</em>, <em>lvl</em>, <em>fn</em>, <em>lno</em>, <em>msg</em>, <em>args</em>, <em>exc_info</em>, <em>func=None</em>, <em>extra=None</em>, <em>sinfo=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-148">This is a factory method which can be overridden in subclasses to create specialized <a class="reference internal" href="#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal"><span class="pre">LogRecord</span></code></a> instances.</span></p></dd></dl><dl class="method"><dt id="logging.Logger.hasHandlers"><span class="yiyi-st" id="yiyi-149"> <code class="descclassname">Logger.</code><code class="descname">hasHandlers</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-150">检查此记录器是否已配置任何处理程序。</span><span class="yiyi-st" id="yiyi-151">这是通过在记录器层次结构中查找此记录器及其父节点中的处理程序来完成的。</span><span class="yiyi-st" id="yiyi-152">如果找到处理程序，则返回<code class="docutils literal"><span class="pre">True</span></code>，否则<code class="docutils literal"><span class="pre">False</span></code>。</span><span class="yiyi-st" id="yiyi-153">当找到具有“propagate”属性设置为False的记录器时，该方法停止搜索层次结构 - 这将是检查处理程序是否存在的最后一个记录器。</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-154"><span class="versionmodified">New in version 3.2.</span></span></p></div></dd></dl></div><div class="section" id="logging-levels"><h2><span class="yiyi-st" id="yiyi-155">16.6.2. </span><span class="yiyi-st" id="yiyi-156">Logging Levels</span></h2><p><span class="yiyi-st" id="yiyi-157">The numeric values of logging levels are given in the following table. </span><span class="yiyi-st" id="yiyi-158">These are primarily of interest if you want to define your own levels, and need them to have specific values relative to the predefined levels. </span><span class="yiyi-st" id="yiyi-159">如果定义具有相同数值的级别，它将覆盖预定义值；预定义的名称将丢失。</span></p><table border="1" class="docutils"><thead valign="bottom"><tr class="row-odd"><th class="head"><span class="yiyi-st" id="yiyi-160">Level</span></th><th class="head"><span class="yiyi-st" id="yiyi-161">Numeric value</span></th></tr></thead><tbody valign="top"><tr class="row-even"><td><span class="yiyi-st" id="yiyi-162"><code class="docutils literal"><span class="pre">CRITICAL</span></code></span></td><td><span class="yiyi-st" id="yiyi-163">50</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-164"><code class="docutils literal"><span class="pre">ERROR</span></code></span></td><td><span class="yiyi-st" id="yiyi-165">40</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-166"><code class="docutils literal"><span class="pre">WARNING</span></code></span></td><td><span class="yiyi-st" id="yiyi-167">30</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-168"><code class="docutils literal"><span class="pre">INFO</span></code></span></td><td><span class="yiyi-st" id="yiyi-169">20</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-170"><code class="docutils literal"><span class="pre">DEBUG</span></code></span></td><td><span class="yiyi-st" id="yiyi-171">10</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-172"><code class="docutils literal"><span class="pre">NOTSET</span></code></span></td><td><span class="yiyi-st" id="yiyi-173">0</span></td></tr></tbody></table></div><div class="section" id="handler-objects"><h2><span class="yiyi-st" id="yiyi-174">16.6.3. </span><span class="yiyi-st" id="yiyi-175">Handler Objects</span></h2><p><span class="yiyi-st" id="yiyi-176">Handlers have the following attributes and methods. </span><span class="yiyi-st" id="yiyi-177">注意：<code class="xref py py-class docutils literal"><span class="pre">Handler</span></code>不应该直接被实例化，此类应该作为基类来子类化出一些有用的类。</span><span class="yiyi-st" id="yiyi-178">然而，<a class="reference internal" href="../reference/datamodel.html#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal"><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"><span class="pre">Handler.__init__()</span></code></a>来调用。</span></p><dl class="method"><dt id="logging.Handler.__init__"><span class="yiyi-st" id="yiyi-179"> <code class="descclassname">Handler.</code><code class="descname">__init__</code><span class="sig-paren">(</span><em>level=NOTSET</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-180">Initializes the <code class="xref py py-class docutils literal"><span class="pre">Handler</span></code> instance by setting its level, setting the list of filters to the empty list and creating a lock (using <a class="reference internal" href="#logging.Handler.createLock" title="logging.Handler.createLock"><code class="xref py py-meth docutils literal"><span class="pre">createLock()</span></code></a>) for serializing access to an I/O mechanism.</span></p></dd></dl><dl class="method"><dt id="logging.Handler.createLock"><span class="yiyi-st" id="yiyi-181"> <code class="descclassname">Handler.</code><code class="descname">createLock</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-182">Initializes a thread lock which can be used to serialize access to underlying I/O functionality which may not be threadsafe.</span></p></dd></dl><dl class="method"><dt id="logging.Handler.acquire"><span class="yiyi-st" id="yiyi-183"> <code class="descclassname">Handler.</code><code class="descname">acquire</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-184">Acquires the thread lock created with <a class="reference internal" href="#logging.Handler.createLock" title="logging.Handler.createLock"><code class="xref py py-meth docutils literal"><span class="pre">createLock()</span></code></a>.</span></p></dd></dl><dl class="method"><dt id="logging.Handler.release"><span class="yiyi-st" id="yiyi-185"> <code class="descclassname">Handler.</code><code class="descname">release</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-186">Releases the thread lock acquired with <a class="reference internal" href="#logging.Handler.acquire" title="logging.Handler.acquire"><code class="xref py py-meth docutils literal"><span class="pre">acquire()</span></code></a>.</span></p></dd></dl><dl class="method"><dt id="logging.Handler.setLevel"><span class="yiyi-st" id="yiyi-187"> <code class="descclassname">Handler.</code><code class="descname">setLevel</code><span class="sig-paren">(</span><em>lvl</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-188">Sets the threshold for this handler to <em>lvl</em>. </span><span class="yiyi-st" id="yiyi-189">Logging messages which are less severe than <em>lvl</em> will be ignored. </span><span class="yiyi-st" id="yiyi-190">When a handler is created, the level is set to <code class="xref py py-const docutils literal"><span class="pre">NOTSET</span></code> (which causes all messages to be processed).</span></p><p><span class="yiyi-st" id="yiyi-191">See <a class="reference internal" href="#levels"><span>Logging Levels</span></a> for a list of levels.</span></p><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-192"><span class="versionmodified">在版本3.2中更改：</span> <em>lvl</em>参数现在接受级别的字符串表示形式，如“INFO”，作为整数常量的替代，如<code class="xref py py-const docutils literal"><span class="pre">INFO </span></code>。</span></p></div></dd></dl><dl class="method"><dt id="logging.Handler.setFormatter"><span class="yiyi-st" id="yiyi-193"> <code class="descclassname">Handler.</code><code class="descname">setFormatter</code><span class="sig-paren">(</span><em>form</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-194">Sets the <a class="reference internal" href="#logging.Formatter" title="logging.Formatter"><code class="xref py py-class docutils literal"><span class="pre">Formatter</span></code></a> for this handler to <em>form</em>.</span></p></dd></dl><dl class="method"><dt id="logging.Handler.addFilter"><span class="yiyi-st" id="yiyi-195"> <code class="descclassname">Handler.</code><code class="descname">addFilter</code><span class="sig-paren">(</span><em>filt</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-196">Adds the specified filter <em>filt</em> to this handler.</span></p></dd></dl><dl class="method"><dt id="logging.Handler.removeFilter"><span class="yiyi-st" id="yiyi-197"> <code class="descclassname">Handler.</code><code class="descname">removeFilter</code><span class="sig-paren">(</span><em>filt</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-198">Removes the specified filter <em>filt</em> from this handler.</span></p></dd></dl><dl class="method"><dt id="logging.Handler.filter"><span class="yiyi-st" id="yiyi-199"> <code class="descclassname">Handler.</code><code class="descname">filter</code><span class="sig-paren">(</span><em>record</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-200">Applies this handler’s filters to the record and returns a true value if the record is to be processed. </span><span class="yiyi-st" id="yiyi-201">The filters are consulted in turn, until one of them returns a false value. </span><span class="yiyi-st" id="yiyi-202">If none of them return a false value, the record will be emitted. </span><span class="yiyi-st" id="yiyi-203">If one returns a false value, the handler will not emit the record.</span></p></dd></dl><dl class="method"><dt id="logging.Handler.flush"><span class="yiyi-st" id="yiyi-204"> <code class="descclassname">Handler.</code><code class="descname">flush</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-205">Ensure all logging output has been flushed. </span><span class="yiyi-st" id="yiyi-206">This version does nothing and is intended to be implemented by subclasses.</span></p></dd></dl><dl class="method"><dt id="logging.Handler.close"><span class="yiyi-st" id="yiyi-207"> <code class="descclassname">Handler.</code><code class="descname">close</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-208">Tidy up any resources used by the handler. </span><span class="yiyi-st" id="yiyi-209">This version does no output but removes the handler from an internal list of handlers which is closed when <a class="reference internal" href="#logging.shutdown" title="logging.shutdown"><code class="xref py py-func docutils literal"><span class="pre">shutdown()</span></code></a> is called. </span><span class="yiyi-st" id="yiyi-210">Subclasses should ensure that this gets called from overridden <a class="reference internal" href="#logging.Handler.close" title="logging.Handler.close"><code class="xref py py-meth docutils literal"><span class="pre">close()</span></code></a> methods.</span></p></dd></dl><dl class="method"><dt id="logging.Handler.handle"><span class="yiyi-st" id="yiyi-211"> <code class="descclassname">Handler.</code><code class="descname">handle</code><span class="sig-paren">(</span><em>record</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-212">Conditionally emits the specified logging record, depending on filters which may have been added to the handler. </span><span class="yiyi-st" id="yiyi-213">Wraps the actual emission of the record with acquisition/release of the I/O thread lock.</span></p></dd></dl><dl class="method"><dt id="logging.Handler.handleError"><span class="yiyi-st" id="yiyi-214"> <code class="descclassname">Handler.</code><code class="descname">handleError</code><span class="sig-paren">(</span><em>record</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-215">此方法应该在调用<a class="reference internal" href="#logging.Handler.emit" title="logging.Handler.emit"><code class="xref py py-meth docutils literal"><span class="pre">emit()</span></code></a>时遇到异常后从handlers被调用。</span><span class="yiyi-st" id="yiyi-216">If the module-level attribute <code class="docutils literal"><span class="pre">raiseExceptions</span></code> is <code class="docutils literal"><span class="pre">False</span></code>, exceptions get silently ignored. </span><span class="yiyi-st" id="yiyi-217">This is what is mostly wanted for a logging system - most users will not care about errors in the logging system, they are more interested in application errors. </span><span class="yiyi-st" id="yiyi-218">You could, however, replace this with a custom handler if you wish. </span><span class="yiyi-st" id="yiyi-219">The specified record is the one which was being processed when the exception occurred. </span><span class="yiyi-st" id="yiyi-220">(The default value of <code class="docutils literal"><span class="pre">raiseExceptions</span></code> is <code class="docutils literal"><span class="pre">True</span></code>, as that is more useful during development).</span></p></dd></dl><dl class="method"><dt id="logging.Handler.format"><span class="yiyi-st" id="yiyi-221"> <code class="descclassname">Handler.</code><code class="descname">format</code><span class="sig-paren">(</span><em>record</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-222">Do formatting for a record - if a formatter is set, use it. </span><span class="yiyi-st" id="yiyi-223">Otherwise, use the default formatter for the module.</span></p></dd></dl><dl class="method"><dt id="logging.Handler.emit"><span class="yiyi-st" id="yiyi-224"> <code class="descclassname">Handler.</code><code class="descname">emit</code><span class="sig-paren">(</span><em>record</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-225">Do whatever it takes to actually log the specified logging record. </span><span class="yiyi-st" id="yiyi-226">This version is intended to be implemented by subclasses and so raises a <a class="reference internal" href="exceptions.html#NotImplementedError" title="NotImplementedError"><code class="xref py py-exc docutils literal"><span class="pre">NotImplementedError</span></code></a>.</span></p></dd></dl><p><span class="yiyi-st" id="yiyi-227">For a list of handlers included as standard, see <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"><span class="pre">logging.handlers</span></code></a>.</span></p></div><div class="section" id="formatter-objects"><h2><span class="yiyi-st" id="yiyi-228">16.6.4. </span><span class="yiyi-st" id="yiyi-229">Formatter Objects</span></h2><p><span class="yiyi-st" id="yiyi-230"><a class="reference internal" href="#logging.Formatter" title="logging.Formatter"><code class="xref py py-class docutils literal"><span class="pre">Formatter</span></code></a>对象有以下属性和方法。</span><span class="yiyi-st" id="yiyi-231">它负责将<a class="reference internal" href="#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal"><span class="pre">LogRecord</span></code></a>转换（通常）成人类和其它系统可以理解的字符串。</span><span class="yiyi-st" id="yiyi-232">基类<a class="reference internal" href="#logging.Formatter" title="logging.Formatter"><code class="xref py py-class docutils literal"><span class="pre">Formatter</span></code></a>允许指定某个格式的字符串。</span><span class="yiyi-st" id="yiyi-233">如果提供None，那么<code class="docutils literal"><span class="pre">'%(message)s'</span></code>将会作为默认值，它仅仅包括日志调用中的信息。</span><span class="yiyi-st" id="yiyi-234">如果想加入一些额外的格式输出（例如时间戳）信息项，请继续阅读下去。</span></p><p><span class="yiyi-st" id="yiyi-235">Formatter对象可以用一个使<a class="reference internal" href="#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal"><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"><span class="pre">LogRecord</span></code></a>对象的 <em>message</em>属性有效的默认值。</span><span class="yiyi-st" id="yiyi-236">This format string contains standard Python %-style mapping keys. </span><span class="yiyi-st" id="yiyi-237">欲了解更多关于字符串格式化的信息，请参见<a class="reference internal" href="stdtypes.html#old-string-formatting"><span>printf-style String Formatting</span></a>。</span></p><p><span class="yiyi-st" id="yiyi-238">在<a class="reference internal" href="#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal"><span class="pre">LogRecord</span></code></a>对象中，有效的映射键存在于<a class="reference internal" href="#logrecord-attributes"><span>LogRecord attributes</span></a>属性中。</span></p><dl class="class"><dt id="logging.Formatter"><span class="yiyi-st" id="yiyi-239"> <em class="property">class </em><code class="descclassname">logging.</code><code class="descname">Formatter</code><span class="sig-paren">(</span><em>fmt=None</em>, <em>datefmt=None</em>, <em>style='%'</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-240">返回一个<a class="reference internal" href="#logging.Formatter" title="logging.Formatter"><code class="xref py py-class docutils literal"><span class="pre">Formatter</span></code></a>类的新实例。</span><span class="yiyi-st" id="yiyi-241">The instance is initialized with a format string for the message as a whole, as well as a format string for the date/time portion of a message. </span><span class="yiyi-st" id="yiyi-242">如果<em>fmt</em>不被指定, <code class="docutils literal"><span class="pre">'%(message)s'</span></code>将会被使用。</span><span class="yiyi-st" id="yiyi-243">If no <em>datefmt</em> is specified, the ISO8601 date format is used.</span></p><p><span class="yiyi-st" id="yiyi-244"><em>style</em>可以是 ‘%’, ‘{‘ or ‘$’中的任何一个，并且它决定格式化字符串将会怎样与它的数据融合: 使用%格式化的更多信息参考<a class="reference internal" href="stdtypes.html#str.format" title="str.format"><code class="xref py py-meth docutils literal"><span class="pre">str.format()</span></code></a> or <a class="reference internal" href="string.html#string.Template" title="string.Template"><code class="xref py py-class docutils literal"><span class="pre">string.Template</span></code></a>.</span><span class="yiyi-st" id="yiyi-245">有关使用{ - 和$ - 格式化日志消息的详细信息，请参阅<a class="reference internal" href="../howto/logging-cookbook.html#formatting-styles"><span>在应用程序中使用特定格式样式</span></a>。</span></p><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-246"><span class="versionmodified">在版本3.2中已更改：</span>添加了<em>样式</em>参数。</span></p></div><dl class="method"><dt id="logging.Formatter.format"><span class="yiyi-st" id="yiyi-247"> <code class="descname">format</code><span class="sig-paren">(</span><em>record</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-248">The record’s attribute dictionary is used as the operand to a string formatting operation. </span><span class="yiyi-st" id="yiyi-249">Returns the resulting string. </span><span class="yiyi-st" id="yiyi-250">Before formatting the dictionary, a couple of preparatory steps are carried out. </span><span class="yiyi-st" id="yiyi-251">The <em>message</em> attribute of the record is computed using <em>msg</em> % <em>args</em>. </span><span class="yiyi-st" id="yiyi-252">If the formatting string contains <code class="docutils literal"><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"><span class="pre">formatTime()</span></code></a> is called to format the event time. </span><span class="yiyi-st" id="yiyi-253">If there is exception information, it is formatted using <a class="reference internal" href="#logging.Formatter.formatException" title="logging.Formatter.formatException"><code class="xref py py-meth docutils literal"><span class="pre">formatException()</span></code></a> and appended to the message. </span><span class="yiyi-st" id="yiyi-254">Note that the formatted exception information is cached in attribute <em>exc_text</em>. </span><span class="yiyi-st" id="yiyi-255">This is useful because the exception information can be pickled and sent across the wire, but you should be careful if you have more than one <a class="reference internal" href="#logging.Formatter" title="logging.Formatter"><code class="xref py py-class docutils literal"><span class="pre">Formatter</span></code></a> subclass which customizes the formatting of exception information. </span><span class="yiyi-st" id="yiyi-256">In this case, you will have to clear the cached value after a formatter has done its formatting, so that the next formatter to handle the event doesn’t use the cached value but recalculates it afresh.</span></p><p><span class="yiyi-st" id="yiyi-257">If stack information is available, it’s appended after the exception information, using <a class="reference internal" href="#logging.Formatter.formatStack" title="logging.Formatter.formatStack"><code class="xref py py-meth docutils literal"><span class="pre">formatStack()</span></code></a> to transform it if necessary.</span></p></dd></dl><dl class="method"><dt id="logging.Formatter.formatTime"><span class="yiyi-st" id="yiyi-258"> <code class="descname">formatTime</code><span class="sig-paren">(</span><em>record</em>, <em>datefmt=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-259">此方法应该被从想使用格式化时间的formatter对象的<a class="reference internal" href="functions.html#format" title="format"><code class="xref py py-meth docutils literal"><span class="pre">format()</span></code></a>调用。</span><span class="yiyi-st" id="yiyi-260">This method can be overridden in formatters to provide for any specific requirement, but the basic behavior is as follows: if <em>datefmt</em> (a string) is specified, it is used with <a class="reference internal" href="time.html#time.strftime" title="time.strftime"><code class="xref py py-func docutils literal"><span class="pre">time.strftime()</span></code></a> to format the creation time of the record. </span><span class="yiyi-st" id="yiyi-261">Otherwise, the ISO8601 format is used. </span><span class="yiyi-st" id="yiyi-262">The resulting string is returned.</span></p><p><span class="yiyi-st" id="yiyi-263">This function uses a user-configurable function to convert the creation time to a tuple. </span><span class="yiyi-st" id="yiyi-264">默认情况下，使用<a class="reference internal" href="time.html#time.localtime" title="time.localtime"><code class="xref py py-func docutils literal"><span class="pre">time.localtime()</span></code></a>；为特定格式化程序更改此属性实例，将<code class="docutils literal"><span class="pre">转换器</span></code>属性设置为具有与<a class="reference internal" href="time.html#time.localtime" title="time.localtime"><code class="xref py py-func docutils literal"><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"><span class="pre">time.gmtime()</span></code></a>。</span><span class="yiyi-st" id="yiyi-265">To change it for all formatters, for example if you want all logging times to be shown in GMT, set the <code class="docutils literal"><span class="pre">converter</span></code> attribute in the <code class="docutils literal"><span class="pre">Formatter</span></code> class.</span></p><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-266"><span class="versionmodified">在版本3.3中更改：</span>以前，默认的ISO 8601格式是硬编码的，如在此示例中：<code class="docutils literal"><span class="pre">2010-09-06</span> <span class="pre">22:38： 15,292</span></code>其中逗号之前的部分由strptime格式字符串处理（<code class="docutils literal"><span class="pre">'％Y-％m-％d</span> <span class="pre">％H：％M ：％S'</span></code>），逗号后面的部分是毫秒值。</span><span class="yiyi-st" id="yiyi-267">因为strptime没有毫秒的格式占位符，所以使用另一个格式字符串<code class="docutils literal"><span class="pre">'％s，％03d'</span></code>附加毫秒值，并且这两个格式字符串都已硬编码到此方法中。</span><span class="yiyi-st" id="yiyi-268">随着改变，这些字符串被定义为类级别的属性，在需要时可以在实例级别被覆盖。</span><span class="yiyi-st" id="yiyi-269">属性的名称为<code class="docutils literal"><span class="pre">default_time_format</span></code>（对于strptime格式字符串）和<code class="docutils literal"><span class="pre">default_msec_format</span></code>（用于追加毫秒值）。</span></p></div></dd></dl><dl class="method"><dt id="logging.Formatter.formatException"><span class="yiyi-st" id="yiyi-270"> <code class="descname">formatException</code><span class="sig-paren">(</span><em>exc_info</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-271">Formats the specified exception information (a standard exception tuple as returned by <a class="reference internal" href="sys.html#sys.exc_info" title="sys.exc_info"><code class="xref py py-func docutils literal"><span class="pre">sys.exc_info()</span></code></a>) as a string. </span><span class="yiyi-st" id="yiyi-272">This default implementation just uses <a class="reference internal" href="traceback.html#traceback.print_exception" title="traceback.print_exception"><code class="xref py py-func docutils literal"><span class="pre">traceback.print_exception()</span></code></a>. </span><span class="yiyi-st" id="yiyi-273">The resulting string is returned.</span></p></dd></dl><dl class="method"><dt id="logging.Formatter.formatStack"><span class="yiyi-st" id="yiyi-274"> <code class="descname">formatStack</code><span class="sig-paren">(</span><em>stack_info</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-275">格式化指定的堆栈信息（由<a class="reference internal" href="traceback.html#traceback.print_stack" title="traceback.print_stack"><code class="xref py py-func docutils literal"><span class="pre">traceback.print_stack()</span></code></a>返回的字符串，但删除了最后一个换行符）作为字符串。</span><span class="yiyi-st" id="yiyi-276">这个默认实现只返回输入值。</span></p></dd></dl></dd></dl></div><div class="section" id="filter-objects"><h2><span class="yiyi-st" id="yiyi-277">16.6.5. </span><span class="yiyi-st" id="yiyi-278">Filter Objects</span></h2><p><span class="yiyi-st" id="yiyi-279"><code class="docutils literal"><span class="pre">Filters</span></code> can be used by <code class="docutils literal"><span class="pre">Handlers</span></code> and <code class="docutils literal"><span class="pre">Loggers</span></code> for more sophisticated filtering than is provided by levels. </span><span class="yiyi-st" id="yiyi-280">The base filter class only allows events which are below a certain point in the logger hierarchy. </span><span class="yiyi-st" id="yiyi-281">例如，用“A.B”初始化的过滤器将允许由记录器“A.B”，“A.B.C”，“A.B.C.D”，“A.B.D”等记录的事件。</span><span class="yiyi-st" id="yiyi-282">但是,不接受“A.BB”，“B.A.B”等的格式。</span><span class="yiyi-st" id="yiyi-283">If initialized with the empty string, all events are passed.</span></p><dl class="class"><dt id="logging.Filter"><span class="yiyi-st" id="yiyi-284"> <em class="property">class </em><code class="descclassname">logging.</code><code class="descname">Filter</code><span class="sig-paren">(</span><em>name=''</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-285">Returns an instance of the <a class="reference internal" href="#logging.Filter" title="logging.Filter"><code class="xref py py-class docutils literal"><span class="pre">Filter</span></code></a> class. </span><span class="yiyi-st" id="yiyi-286">If <em>name</em> is specified, it names a logger which, together with its children, will have its events allowed through the filter. </span><span class="yiyi-st" id="yiyi-287">If <em>name</em> is the empty string, allows every event.</span></p><dl class="method"><dt id="logging.Filter.filter"><span class="yiyi-st" id="yiyi-288"> <code class="descname">filter</code><span class="sig-paren">(</span><em>record</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-289">Is the specified record to be logged? </span><span class="yiyi-st" id="yiyi-290">Returns zero for no, nonzero for yes. </span><span class="yiyi-st" id="yiyi-291">If deemed appropriate, the record may be modified in-place by this method.</span></p></dd></dl></dd></dl><p><span class="yiyi-st" id="yiyi-292">注意，在处理程序发出事件之前，请参考处理程序附带的过滤器，而记录事件时会查询附加到日志记录器的过滤器（使用<a class="reference internal" href="#logging.debug" title="logging.debug"><code class="xref py py-meth docutils literal"><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"><span class="pre">info </span></code></a>等。</span><span class="yiyi-st" id="yiyi-293">), before sending an event to handlers. </span><span class="yiyi-st" id="yiyi-294">This means that events which have been generated by descendant loggers will not be filtered by a logger’s filter setting, unless the filter has also been applied to those descendant loggers.</span></p><p><span class="yiyi-st" id="yiyi-295">You don’t actually need to subclass <code class="docutils literal"><span class="pre">Filter</span></code>: you can pass any instance which has a <code class="docutils literal"><span class="pre">filter</span></code> method with the same semantics.</span></p><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-296"><span class="versionmodified">Changed in version 3.2: </span>You don’t need to create specialized <code class="docutils literal"><span class="pre">Filter</span></code> classes, or use other classes with a <code class="docutils literal"><span class="pre">filter</span></code> method: you can use a function (or other callable) as a filter. </span><span class="yiyi-st" id="yiyi-297">The filtering logic will check to see if the filter object has a <code class="docutils literal"><span class="pre">filter</span></code> attribute: if it does, it’s assumed to be a <code class="docutils literal"><span class="pre">Filter</span></code> and its <a class="reference internal" href="#logging.Filter.filter" title="logging.Filter.filter"><code class="xref py py-meth docutils literal"><span class="pre">filter()</span></code></a> method is called. </span><span class="yiyi-st" id="yiyi-298">Otherwise, it’s assumed to be a callable and called with the record as the single parameter. </span><span class="yiyi-st" id="yiyi-299">The returned value should conform to that returned by <a class="reference internal" href="#logging.Filter.filter" title="logging.Filter.filter"><code class="xref py py-meth docutils literal"><span class="pre">filter()</span></code></a>.</span></p></div><p><span class="yiyi-st" id="yiyi-300">Although filters are used primarily to filter records based on more sophisticated criteria than levels, they get to see every record which is processed by the handler or logger they’re attached to: this can be useful if you want to do things like counting how many records were processed by a particular logger or handler, or adding, changing or removing attributes in the LogRecord being processed. </span><span class="yiyi-st" id="yiyi-301">Obviously changing the LogRecord needs to be done with some care, but it does allow the injection of contextual information into logs (see <a class="reference internal" href="../howto/logging-cookbook.html#filters-contextual"><span>Using Filters to impart contextual information</span></a>).</span></p></div><div class="section" id="logrecord-objects"><h2><span class="yiyi-st" id="yiyi-302">16.6.6. </span><span class="yiyi-st" id="yiyi-303">LogRecord Objects</span></h2><p><span class="yiyi-st" id="yiyi-304">每次某个事件被日志记录时<a class="reference internal" href="#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal"><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"><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"><span class="pre">makeLogRecord()</span></code></a> (例如，一个网络序列化事件).</span></p><dl class="class"><dt id="logging.LogRecord"><span class="yiyi-st" id="yiyi-305"> <em class="property">class </em><code class="descclassname">logging.</code><code class="descname">LogRecord</code><span class="sig-paren">(</span><em>name</em>, <em>level</em>, <em>pathname</em>, <em>lineno</em>, <em>msg</em>, <em>args</em>, <em>exc_info</em>, <em>func=None</em>, <em>sinfo=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-306">Contains all the information pertinent to the event being logged.</span></p><p><span class="yiyi-st" id="yiyi-307">主要信息由<code class="xref py py-attr docutils literal"><span class="pre">msg</span></code>和<code class="xref py py-attr docutils literal"><span class="pre">args</span></code>传入，which are combined using <code class="docutils literal"><span class="pre">msg</span> <span class="pre">%</span> <span class="pre">args</span></code> to create the <code class="xref py py-attr docutils literal"><span class="pre">message</span></code> field of the record.</span></p><table class="docutils field-list" frame="void" rules="none"><tbody valign="top"><tr class="field-odd field"><th class="field-name"><span class="yiyi-st" id="yiyi-308">Parameters:</span></th><td class="field-body"><ul class="first last simple"><li><span class="yiyi-st" id="yiyi-309"><strong>name</strong> - 用于记录由此LogRecord表示的事件的记录器的名称。</span><span class="yiyi-st" id="yiyi-310">Note that this name will always have this value, even though it may be emitted by a handler attached to a different (ancestor) logger.</span></li><li><span class="yiyi-st" id="yiyi-311"><strong>level</strong> - 记录事件的数字级别（DEBUG，INFO等之一）</span><span class="yiyi-st" id="yiyi-312">请注意，将其转换为LogRecord的<em>两个</em>属性：<code class="docutils literal"><span class="pre">levelno</span></code>表示数字值，<code class="docutils literal"><span class="pre">levelname</span></code>表示相应的级别名称。</span></li><li><span class="yiyi-st" id="yiyi-313"><strong>pathname</strong> - 进行记录调用的源文件的完整路径名。</span></li><li><span class="yiyi-st" id="yiyi-314"><strong>lineno</strong> - 进行日志调用的源文件中的行号。</span></li><li><span class="yiyi-st" id="yiyi-315"><strong>msg</strong> - 事件描述消息，可能是带有变量数据占位符的格式字符串。</span></li><li><span class="yiyi-st" id="yiyi-316"><strong>args</strong> - 要合并到<em>msg</em>参数中的变量数据，以获取事件描述。</span></li><li><span class="yiyi-st" id="yiyi-317"><strong>exc_info</strong> - 当前异常信息的异常元组，如果没有异常信息，则为<em>None</em>。</span></li><li><span class="yiyi-st" id="yiyi-318"><strong>func</strong> - 调用日志记录调用的函数或方法的名称。</span></li><li><span class="yiyi-st" id="yiyi-319"><strong>sinfo</strong> - 表示当前线程中堆栈基址的堆栈信息的文本字符串，直到日志调用。</span></li></ul></td></tr></tbody></table><dl class="method"><dt id="logging.LogRecord.getMessage"><span class="yiyi-st" id="yiyi-320"> <code class="descname">getMessage</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-321"><a class="reference internal" href="#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal"><span class="pre">LogRecord</span></code></a>实例在融合用户提供的参数后返回一条message。</span><span class="yiyi-st" id="yiyi-322">If the user-supplied message argument to the logging call is not a string, <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-func docutils literal"><span class="pre">str()</span></code></a> is called on it to convert it to a string. </span><span class="yiyi-st" id="yiyi-323">This allows use of user-defined classes as messages, whose <code class="docutils literal"><span class="pre">__str__</span></code> method can return the actual format string to be used.</span></p></dd></dl><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-324"><span class="versionmodified">在版本3.2中已更改：</span>通过提供用于创建记录的工厂，可以更轻松地创建<code class="docutils literal"><span class="pre">LogRecord</span></code>。</span><span class="yiyi-st" id="yiyi-325">可以使用<a class="reference internal" href="#logging.getLogRecordFactory" title="logging.getLogRecordFactory"><code class="xref py py-func docutils literal"><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"><span class="pre">setLogRecordFactory()</span></code></a>来设置工厂（参见工厂的签名）。</span></p></div><p><span class="yiyi-st" id="yiyi-326">此功能可用于在创建时将自己的值注入LogRecord。</span><span class="yiyi-st" id="yiyi-327">您可以使用以下模式：</span></p><pre><code class="language-python"><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>
</code></pre><p><span class="yiyi-st" id="yiyi-328">使用这种模式，多个工厂可以链接，并且只要它们不会覆盖彼此的属性或无意地覆盖上面列出的标准属性，就不会有任何意外。</span></p></dd></dl></div><div class="section" id="logrecord-attributes"><h2><span class="yiyi-st" id="yiyi-329">16.6.7. </span><span class="yiyi-st" id="yiyi-330">LogRecord attributes</span></h2><p><span class="yiyi-st" id="yiyi-331">The LogRecord has a number of attributes, most of which are derived from the parameters to the constructor. </span><span class="yiyi-st" id="yiyi-332">(Note that the names do not always correspond exactly between the LogRecord constructor parameters and the LogRecord attributes.) </span><span class="yiyi-st" id="yiyi-333">These attributes can be used to merge data from the record into the format string. </span><span class="yiyi-st" id="yiyi-334">The following table lists (in alphabetical order) the attribute names, their meanings and the corresponding placeholder in a %-style format string.</span></p><p><span class="yiyi-st" id="yiyi-335">如果使用{} -formatting（<a class="reference internal" href="stdtypes.html#str.format" title="str.format"><code class="xref py py-func docutils literal"><span class="pre">str.format()</span></code></a>），则可以使用<code class="docutils literal"><span class="pre">{attrname}</span></code>作为格式字符串中的占位符。</span><span class="yiyi-st" id="yiyi-336">如果您使用$ -formatting（<a class="reference internal" href="string.html#string.Template" title="string.Template"><code class="xref py py-class docutils literal"><span class="pre">string.Template</span></code></a>），请使用形式<code class="docutils literal"><span class="pre">$ {attrname}</span></code>。</span><span class="yiyi-st" id="yiyi-337">在这两种情况下，当然，将<code class="docutils literal"><span class="pre">attrname</span></code>替换为要使用的实际属性名称。</span></p><p><span class="yiyi-st" id="yiyi-338">在{}格式化的情况下，您可以通过将属性名称放在属性名称后面指定格式化标记，并用冒号分隔。</span><span class="yiyi-st" id="yiyi-339">例如：<code class="docutils literal"><span class="pre">{msecs：03d}</span></code>的占位符会将<code class="docutils literal"><span class="pre">4</span></code>的毫秒值格式化为<code class="docutils literal"><span class="pre">004</span></code>。</span><span class="yiyi-st" id="yiyi-340">有关可用选项的完整详细信息，请参阅<a class="reference internal" href="stdtypes.html#str.format" title="str.format"><code class="xref py py-meth docutils literal"><span class="pre">str.format()</span></code></a>文档。</span></p><table border="1" class="docutils"><thead valign="bottom"><tr class="row-odd"><th class="head"><span class="yiyi-st" id="yiyi-341">Attribute name</span></th><th class="head"><span class="yiyi-st" id="yiyi-342">Format</span></th><th class="head"><span class="yiyi-st" id="yiyi-343">Description</span></th></tr></thead><tbody valign="top"><tr class="row-even"><td><span class="yiyi-st" id="yiyi-344">args</span></td><td><span class="yiyi-st" id="yiyi-345">You shouldn’t need to format this yourself.</span></td><td><span class="yiyi-st" id="yiyi-346">The tuple of arguments merged into <code class="docutils literal"><span class="pre">msg</span></code> to produce <code class="docutils literal"><span class="pre">message</span></code>, or a dict whose values are used for the merge (when there is only one argument, and it is a dictionary).</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-347">asctime</span></td><td><span class="yiyi-st" id="yiyi-348"><code class="docutils literal"><span class="pre">%(asctime)s</span></code></span></td><td><span class="yiyi-st" id="yiyi-349">Human-readable time when the <a class="reference internal" href="#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal"><span class="pre">LogRecord</span></code></a> was created. </span><span class="yiyi-st" id="yiyi-350">By default this is of the form ‘2003-07-08 16:49:45,896’ (the numbers after the comma are millisecond portion of the time).</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-351">created</span></td><td><span class="yiyi-st" id="yiyi-352"><code class="docutils literal"><span class="pre">%(created)f</span></code></span></td><td><span class="yiyi-st" id="yiyi-353">Time when the <a class="reference internal" href="#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal"><span class="pre">LogRecord</span></code></a> was created (as returned by <a class="reference internal" href="time.html#time.time" title="time.time"><code class="xref py py-func docutils literal"><span class="pre">time.time()</span></code></a>).</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-354">exc_info</span></td><td><span class="yiyi-st" id="yiyi-355">You shouldn’t need to format this yourself.</span></td><td><span class="yiyi-st" id="yiyi-356">Exception tuple (à la <code class="docutils literal"><span class="pre">sys.exc_info</span></code>) or, if no exception has occurred, <em>None</em>.</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-357">filename</span></td><td><span class="yiyi-st" id="yiyi-358"><code class="docutils literal"><span class="pre">%(filename)s</span></code></span></td><td><span class="yiyi-st" id="yiyi-359">Filename portion of <code class="docutils literal"><span class="pre">pathname</span></code>.</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-360">funcName</span></td><td><span class="yiyi-st" id="yiyi-361"><code class="docutils literal"><span class="pre">%(funcName)s</span></code></span></td><td><span class="yiyi-st" id="yiyi-362">Name of function containing the logging call.</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-363">levelname</span></td><td><span class="yiyi-st" id="yiyi-364"><code class="docutils literal"><span class="pre">%(levelname)s</span></code></span></td><td><span class="yiyi-st" id="yiyi-365">Text logging level for the message (<code class="docutils literal"><span class="pre">'DEBUG'</span></code>, <code class="docutils literal"><span class="pre">'INFO'</span></code>, <code class="docutils literal"><span class="pre">'WARNING'</span></code>, <code class="docutils literal"><span class="pre">'ERROR'</span></code>, <code class="docutils literal"><span class="pre">'CRITICAL'</span></code>).</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-366">levelno</span></td><td><span class="yiyi-st" id="yiyi-367"><code class="docutils literal"><span class="pre">%(levelno)s</span></code></span></td><td><span class="yiyi-st" id="yiyi-368">Numeric logging level for the message (<code class="xref py py-const docutils literal"><span class="pre">DEBUG</span></code>, <code class="xref py py-const docutils literal"><span class="pre">INFO</span></code>, <code class="xref py py-const docutils literal"><span class="pre">WARNING</span></code>, <code class="xref py py-const docutils literal"><span class="pre">ERROR</span></code>, <code class="xref py py-const docutils literal"><span class="pre">CRITICAL</span></code>).</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-369">行号</span></td><td><span class="yiyi-st" id="yiyi-370"><code class="docutils literal"><span class="pre">%(lineno)d</span></code></span></td><td><span class="yiyi-st" id="yiyi-371">Source line number where the logging call was issued (if available).</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-372">module</span></td><td><span class="yiyi-st" id="yiyi-373"><code class="docutils literal"><span class="pre">%(module)s</span></code></span></td><td><span class="yiyi-st" id="yiyi-374">Module (name portion of <code class="docutils literal"><span class="pre">filename</span></code>).</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-375">msecs</span></td><td><span class="yiyi-st" id="yiyi-376"><code class="docutils literal"><span class="pre">%(msecs)d</span></code></span></td><td><span class="yiyi-st" id="yiyi-377">Millisecond portion of the time when the <a class="reference internal" href="#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal"><span class="pre">LogRecord</span></code></a> was created.</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-378">message</span></td><td><span class="yiyi-st" id="yiyi-379"><code class="docutils literal"><span class="pre">%(message)s</span></code></span></td><td><span class="yiyi-st" id="yiyi-380">The logged message, computed as <code class="docutils literal"><span class="pre">msg</span> <span class="pre">%</span> <span class="pre">args</span></code>. </span><span class="yiyi-st" id="yiyi-381">This is set when <a class="reference internal" href="#logging.Formatter.format" title="logging.Formatter.format"><code class="xref py py-meth docutils literal"><span class="pre">Formatter.format()</span></code></a> is invoked.</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-382">msg</span></td><td><span class="yiyi-st" id="yiyi-383">You shouldn’t need to format this yourself.</span></td><td><span class="yiyi-st" id="yiyi-384">The format string passed in the original logging call. </span><span class="yiyi-st" id="yiyi-385">Merged with <code class="docutils literal"><span class="pre">args</span></code> to produce <code class="docutils literal"><span class="pre">message</span></code>, or an arbitrary object (see <a class="reference internal" href="../howto/logging.html#arbitrary-object-messages"><span>Using arbitrary objects as messages</span></a>).</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-386">name</span></td><td><span class="yiyi-st" id="yiyi-387"><code class="docutils literal"><span class="pre">%(name)s</span></code></span></td><td><span class="yiyi-st" id="yiyi-388">Name of the logger used to log the call.</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-389">pathname</span></td><td><span class="yiyi-st" id="yiyi-390"><code class="docutils literal"><span class="pre">%(pathname)s</span></code></span></td><td><span class="yiyi-st" id="yiyi-391">Full pathname of the source file where the logging call was issued (if available).</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-392">process</span></td><td><span class="yiyi-st" id="yiyi-393"><code class="docutils literal"><span class="pre">%(process)d</span></code></span></td><td><span class="yiyi-st" id="yiyi-394">Process ID (if available).</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-395">processName</span></td><td><span class="yiyi-st" id="yiyi-396"><code class="docutils literal"><span class="pre">%(processName)s</span></code></span></td><td><span class="yiyi-st" id="yiyi-397">Process name (if available).</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-398">relativeCreated</span></td><td><span class="yiyi-st" id="yiyi-399"><code class="docutils literal"><span class="pre">%(relativeCreated)d</span></code></span></td><td><span class="yiyi-st" id="yiyi-400">Time in milliseconds when the LogRecord was created, relative to the time the logging module was loaded.</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-401">stack_info</span></td><td><span class="yiyi-st" id="yiyi-402">You shouldn’t need to format this yourself.</span></td><td><span class="yiyi-st" id="yiyi-403">Stack frame information (where available) from the bottom of the stack in the current thread, up to and including the stack frame of the logging call which resulted in the creation of this record.</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-404">thread</span></td><td><span class="yiyi-st" id="yiyi-405"><code class="docutils literal"><span class="pre">%(thread)d</span></code></span></td><td><span class="yiyi-st" id="yiyi-406">Thread ID (if available).</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-407">threadName</span></td><td><span class="yiyi-st" id="yiyi-408"><code class="docutils literal"><span class="pre">%(threadName)s</span></code></span></td><td><span class="yiyi-st" id="yiyi-409">Thread name (if available).</span></td></tr></tbody></table><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-410"><span class="versionmodified">Changed in version 3.1: </span><em>processName</em> was added.</span></p></div></div><div class="section" id="loggeradapter-objects"><h2><span class="yiyi-st" id="yiyi-411">16.6.8. </span><span class="yiyi-st" id="yiyi-412">LoggerAdapter Objects</span></h2><p><span class="yiyi-st" id="yiyi-413"><a class="reference internal" href="#logging.LoggerAdapter" title="logging.LoggerAdapter"><code class="xref py py-class docutils literal"><span class="pre">LoggerAdapter</span></code></a>实例用来方便的传递文本信息给logging调用。</span><span class="yiyi-st" id="yiyi-414">For a usage example, see the section on <a class="reference internal" href="../howto/logging-cookbook.html#context-info"><span>adding contextual information to your logging output</span></a>.</span></p><dl class="class"><dt id="logging.LoggerAdapter"><span class="yiyi-st" id="yiyi-415"> <em class="property">class </em><code class="descclassname">logging.</code><code class="descname">LoggerAdapter</code><span class="sig-paren">(</span><em>logger</em>, <em>extra</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-416">Returns an instance of <a class="reference internal" href="#logging.LoggerAdapter" title="logging.LoggerAdapter"><code class="xref py py-class docutils literal"><span class="pre">LoggerAdapter</span></code></a> initialized with an underlying <a class="reference internal" href="#logging.Logger" title="logging.Logger"><code class="xref py py-class docutils literal"><span class="pre">Logger</span></code></a> instance and a dict-like object.</span></p><dl class="method"><dt id="logging.LoggerAdapter.process"><span class="yiyi-st" id="yiyi-417"> <code class="descname">process</code><span class="sig-paren">(</span><em>msg</em>, <em>kwargs</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-418">Modifies the message and/or keyword arguments passed to a logging call in order to insert contextual information. </span><span class="yiyi-st" id="yiyi-419">This implementation takes the object passed as <em>extra</em> to the constructor and adds it to <em>kwargs</em> using key ‘extra’. </span><span class="yiyi-st" id="yiyi-420">The return value is a (<em>msg</em>, <em>kwargs</em>) tuple which has the (possibly modified) versions of the arguments passed in.</span></p></dd></dl></dd></dl><p><span class="yiyi-st" id="yiyi-421">In addition to the above, <a class="reference internal" href="#logging.LoggerAdapter" title="logging.LoggerAdapter"><code class="xref py py-class docutils literal"><span class="pre">LoggerAdapter</span></code></a> supports the following methods of <a class="reference internal" href="#logging.Logger" title="logging.Logger"><code class="xref py py-class docutils literal"><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"><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"><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"><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"><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"><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"><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"><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"><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"><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"><span class="pre">setLevel()</span></code></a> and <a class="reference internal" href="#logging.Logger.hasHandlers" title="logging.Logger.hasHandlers"><code class="xref py py-meth docutils literal"><span class="pre">hasHandlers()</span></code></a>. </span><span class="yiyi-st" id="yiyi-422">These methods have the same signatures as their counterparts in <a class="reference internal" href="#logging.Logger" title="logging.Logger"><code class="xref py py-class docutils literal"><span class="pre">Logger</span></code></a>, so you can use the two types of instances interchangeably.</span></p><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-423"><span class="versionmodified">Changed in version 3.2: </span>The <a class="reference internal" href="#logging.Logger.isEnabledFor" title="logging.Logger.isEnabledFor"><code class="xref py py-meth docutils literal"><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"><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"><span class="pre">setLevel()</span></code></a> and <a class="reference internal" href="#logging.Logger.hasHandlers" title="logging.Logger.hasHandlers"><code class="xref py py-meth docutils literal"><span class="pre">hasHandlers()</span></code></a> methods were added to <a class="reference internal" href="#logging.LoggerAdapter" title="logging.LoggerAdapter"><code class="xref py py-class docutils literal"><span class="pre">LoggerAdapter</span></code></a>. </span><span class="yiyi-st" id="yiyi-424">These methods delegate to the underlying logger.</span></p></div></div><div class="section" id="thread-safety"><h2><span class="yiyi-st" id="yiyi-425">16.6.9. </span><span class="yiyi-st" id="yiyi-426">Thread Safety</span></h2><p><span class="yiyi-st" id="yiyi-427">The logging module is intended to be thread-safe without any special work needing to be done by its clients. </span><span class="yiyi-st" id="yiyi-428">它实现了这一点，虽然使用线程锁；有一个锁来串行访问模块的共享数据，并且每个处理程序还创建一个锁以串行化对其底层I / O的访问。</span></p><p><span class="yiyi-st" id="yiyi-429">If you are implementing asynchronous signal handlers using the <a class="reference internal" href="signal.html#module-signal" title="signal: Set handlers for asynchronous events."><code class="xref py py-mod docutils literal"><span class="pre">signal</span></code></a> module, you may not be able to use logging from within such handlers. </span><span class="yiyi-st" id="yiyi-430">This is because lock implementations in the <a class="reference internal" href="threading.html#module-threading" title="threading: Thread-based parallelism."><code class="xref py py-mod docutils literal"><span class="pre">threading</span></code></a> module are not always re-entrant, and so cannot be invoked from such signal handlers.</span></p></div><div class="section" id="module-level-functions"><h2><span class="yiyi-st" id="yiyi-431">16.6.10. </span><span class="yiyi-st" id="yiyi-432">Module-Level Functions</span></h2><p><span class="yiyi-st" id="yiyi-433">In addition to the classes described above, there are a number of module- level functions.</span></p><dl class="function"><dt id="logging.getLogger"><span class="yiyi-st" id="yiyi-434"> <code class="descclassname">logging.</code><code class="descname">getLogger</code><span class="sig-paren">(</span><em>name=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-435">返回具有指定名称的记录器，如果名称为<code class="docutils literal"><span class="pre">无</span></code>，则返回一个记录器，它是层次结构的根记录器。</span><span class="yiyi-st" id="yiyi-436">如果指定，名称通常是点分隔的分层名称，如<em>'a'</em>，<em>'a.b'</em>或<em>'a.b.c.d'</em>。</span><span class="yiyi-st" id="yiyi-437">Choice of these names is entirely up to the developer who is using logging.</span></p><p><span class="yiyi-st" id="yiyi-438">All calls to this function with a given name return the same logger instance. </span><span class="yiyi-st" id="yiyi-439">This means that logger instances never need to be passed between different parts of an application.</span></p></dd></dl><dl class="function"><dt id="logging.getLoggerClass"><span class="yiyi-st" id="yiyi-440"> <code class="descclassname">logging.</code><code class="descname">getLoggerClass</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-441">Return either the standard <a class="reference internal" href="#logging.Logger" title="logging.Logger"><code class="xref py py-class docutils literal"><span class="pre">Logger</span></code></a> class, or the last class passed to <a class="reference internal" href="#logging.setLoggerClass" title="logging.setLoggerClass"><code class="xref py py-func docutils literal"><span class="pre">setLoggerClass()</span></code></a>. </span><span class="yiyi-st" id="yiyi-442">This function may be called from within a new class definition, to ensure that installing a customized <a class="reference internal" href="#logging.Logger" title="logging.Logger"><code class="xref py py-class docutils literal"><span class="pre">Logger</span></code></a> class will not undo customizations already applied by other code. </span><span class="yiyi-st" id="yiyi-443">For example:</span></p><pre><code class="language-python"><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>
</code></pre></dd></dl><dl class="function"><dt id="logging.getLogRecordFactory"><span class="yiyi-st" id="yiyi-444"> <code class="descclassname">logging.</code><code class="descname">getLogRecordFactory</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-445">Return a callable which is used to create a <a class="reference internal" href="#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal"><span class="pre">LogRecord</span></code></a>.</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-446"><span class="versionmodified">New in version 3.2: </span>This function has been provided, along with <a class="reference internal" href="#logging.setLogRecordFactory" title="logging.setLogRecordFactory"><code class="xref py py-func docutils literal"><span class="pre">setLogRecordFactory()</span></code></a>, to allow developers more control over how the <a class="reference internal" href="#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal"><span class="pre">LogRecord</span></code></a> representing a logging event is constructed.</span></p></div><p><span class="yiyi-st" id="yiyi-447">See <a class="reference internal" href="#logging.setLogRecordFactory" title="logging.setLogRecordFactory"><code class="xref py py-func docutils literal"><span class="pre">setLogRecordFactory()</span></code></a> for more information about the how the factory is called.</span></p></dd></dl><dl class="function"><dt id="logging.debug"><span class="yiyi-st" id="yiyi-448"> <code class="descclassname">logging.</code><code class="descname">debug</code><span class="sig-paren">(</span><em>msg</em>, <em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-449">Logs a message with level <code class="xref py py-const docutils literal"><span class="pre">DEBUG</span></code> on the root logger. </span><span class="yiyi-st" id="yiyi-450">The <em>msg</em> is the message format string, and the <em>args</em> are the arguments which are merged into <em>msg</em> using the string formatting operator. </span><span class="yiyi-st" id="yiyi-451">(Note that this means that you can use keywords in the format string, together with a single dictionary argument.)</span></p><p><span class="yiyi-st" id="yiyi-452">There are three keyword arguments in <em>kwargs</em> which are inspected: <em>exc_info</em> which, if it does not evaluate as false, causes exception information to be added to the logging message. </span><span class="yiyi-st" id="yiyi-453">If an exception tuple (in the format returned by <a class="reference internal" href="sys.html#sys.exc_info" title="sys.exc_info"><code class="xref py py-func docutils literal"><span class="pre">sys.exc_info()</span></code></a>) is provided, it is used; otherwise, <a class="reference internal" href="sys.html#sys.exc_info" title="sys.exc_info"><code class="xref py py-func docutils literal"><span class="pre">sys.exc_info()</span></code></a> is called to get the exception information.</span></p><p><span class="yiyi-st" id="yiyi-454">The second optional keyword argument is <em>stack_info</em>, which defaults to <code class="docutils literal"><span class="pre">False</span></code>. </span><span class="yiyi-st" id="yiyi-455">If true, stack information is added to the logging message, including the actual logging call. </span><span class="yiyi-st" id="yiyi-456">Note that this is not the same stack information as that displayed through specifying <em>exc_info</em>: The former is stack frames from the bottom of the stack up to the logging call in the current thread, whereas the latter is information about stack frames which have been unwound, following an exception, while searching for exception handlers.</span></p><p><span class="yiyi-st" id="yiyi-457">You can specify <em>stack_info</em> independently of <em>exc_info</em>, e.g. </span><span class="yiyi-st" id="yiyi-458">to just show how you got to a certain point in your code, even when no exceptions were raised. </span><span class="yiyi-st" id="yiyi-459">The stack frames are printed following a header line which says:</span></p><pre><code class="language-python"><span></span><span class="n">Stack</span> <span class="p">(</span><span class="n">most</span> <span class="n">recent</span> <span class="n">call</span> <span class="n">last</span><span class="p">):</span>
</code></pre><p><span class="yiyi-st" id="yiyi-460">This mimics the <code class="docutils literal"><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> which is used when displaying exception frames.</span></p><p><span class="yiyi-st" id="yiyi-461">The third optional keyword argument is <em>extra</em> which can be used to pass a dictionary which is used to populate the __dict__ of the LogRecord created for the logging event with user-defined attributes. </span><span class="yiyi-st" id="yiyi-462">These custom attributes can then be used as you like. </span><span class="yiyi-st" id="yiyi-463">For example, they could be incorporated into logged messages. </span><span class="yiyi-st" id="yiyi-464">For example:</span></p><pre><code class="language-python"><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>
</code></pre><p><span class="yiyi-st" id="yiyi-465">would print something like:</span></p><pre><code class="language-python"><span></span><span class="mi">2006</span><span class="o">-</span><span class="mi">02</span><span class="o">-</span><span class="mi">08</span> <span class="mi">22</span><span class="p">:</span><span class="mi">20</span><span class="p">:</span><span class="mi">02</span><span class="p">,</span><span class="mi">165</span> <span class="mf">192.168</span><span class="o">.</span><span class="mf">0.1</span> <span class="n">fbloggs</span> <span class="n">Protocol</span> <span class="n">problem</span><span class="p">:</span> <span class="n">connection</span> <span class="n">reset</span>
</code></pre><p><span class="yiyi-st" id="yiyi-466">The keys in the dictionary passed in <em>extra</em> should not clash with the keys used by the logging system. </span><span class="yiyi-st" id="yiyi-467">(See the <a class="reference internal" href="#logging.Formatter" title="logging.Formatter"><code class="xref py py-class docutils literal"><span class="pre">Formatter</span></code></a> documentation for more information on which keys are used by the logging system.)</span></p><p><span class="yiyi-st" id="yiyi-468">If you choose to use these attributes in logged messages, you need to exercise some care. </span><span class="yiyi-st" id="yiyi-469">In the above example, for instance, the <a class="reference internal" href="#logging.Formatter" title="logging.Formatter"><code class="xref py py-class docutils literal"><span class="pre">Formatter</span></code></a> has been set up with a format string which expects ‘clientip’ and ‘user’ in the attribute dictionary of the LogRecord. </span><span class="yiyi-st" id="yiyi-470">If these are missing, the message will not be logged because a string formatting exception will occur. </span><span class="yiyi-st" id="yiyi-471">So in this case, you always need to pass the <em>extra</em> dictionary with these keys.</span></p><p><span class="yiyi-st" id="yiyi-472">While this might be annoying, this feature is intended for use in specialized circumstances, such as multi-threaded servers where the same code executes in many contexts, and interesting conditions which arise are dependent on this context (such as remote client IP address and authenticated user name, in the above example). </span><span class="yiyi-st" id="yiyi-473">In such circumstances, it is likely that specialized <a class="reference internal" href="#logging.Formatter" title="logging.Formatter"><code class="xref py py-class docutils literal"><span class="pre">Formatter</span></code></a>s would be used with particular <code class="xref py py-class docutils literal"><span class="pre">Handler</span></code>s.</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-474"><span class="versionmodified">New in version 3.2: </span>The <em>stack_info</em> parameter was added.</span></p></div></dd></dl><dl class="function"><dt id="logging.info"><span class="yiyi-st" id="yiyi-475"> <code class="descclassname">logging.</code><code class="descname">info</code><span class="sig-paren">(</span><em>msg</em>, <em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-476">Logs a message with level <code class="xref py py-const docutils literal"><span class="pre">INFO</span></code> on the root logger. </span><span class="yiyi-st" id="yiyi-477">The arguments are interpreted as for <a class="reference internal" href="#logging.debug" title="logging.debug"><code class="xref py py-func docutils literal"><span class="pre">debug()</span></code></a>.</span></p></dd></dl><dl class="function"><dt id="logging.warning"><span class="yiyi-st" id="yiyi-478"> <code class="descclassname">logging.</code><code class="descname">warning</code><span class="sig-paren">(</span><em>msg</em>, <em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-479">Logs a message with level <code class="xref py py-const docutils literal"><span class="pre">WARNING</span></code> on the root logger. </span><span class="yiyi-st" id="yiyi-480">The arguments are interpreted as for <a class="reference internal" href="#logging.debug" title="logging.debug"><code class="xref py py-func docutils literal"><span class="pre">debug()</span></code></a>.</span></p><div class="admonition note"><p class="first admonition-title"><span class="yiyi-st" id="yiyi-481">Note</span></p><p class="last"><span class="yiyi-st" id="yiyi-482">There is an obsolete function <code class="docutils literal"><span class="pre">warn</span></code> which is functionally identical to <code class="docutils literal"><span class="pre">warning</span></code>. </span><span class="yiyi-st" id="yiyi-483">As <code class="docutils literal"><span class="pre">warn</span></code> is deprecated, please do not use it - use <code class="docutils literal"><span class="pre">warning</span></code> instead.</span></p></div></dd></dl><dl class="function"><dt id="logging.error"><span class="yiyi-st" id="yiyi-484"> <code class="descclassname">logging.</code><code class="descname">error</code><span class="sig-paren">(</span><em>msg</em>, <em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-485">Logs a message with level <code class="xref py py-const docutils literal"><span class="pre">ERROR</span></code> on the root logger. </span><span class="yiyi-st" id="yiyi-486">The arguments are interpreted as for <a class="reference internal" href="#logging.debug" title="logging.debug"><code class="xref py py-func docutils literal"><span class="pre">debug()</span></code></a>.</span></p></dd></dl><dl class="function"><dt id="logging.critical"><span class="yiyi-st" id="yiyi-487"> <code class="descclassname">logging.</code><code class="descname">critical</code><span class="sig-paren">(</span><em>msg</em>, <em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-488">Logs a message with level <code class="xref py py-const docutils literal"><span class="pre">CRITICAL</span></code> on the root logger. </span><span class="yiyi-st" id="yiyi-489">The arguments are interpreted as for <a class="reference internal" href="#logging.debug" title="logging.debug"><code class="xref py py-func docutils literal"><span class="pre">debug()</span></code></a>.</span></p></dd></dl><dl class="function"><dt id="logging.exception"><span class="yiyi-st" id="yiyi-490"> <code class="descclassname">logging.</code><code class="descname">exception</code><span class="sig-paren">(</span><em>msg</em>, <em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-491">Logs a message with level <code class="xref py py-const docutils literal"><span class="pre">ERROR</span></code> on the root logger. </span><span class="yiyi-st" id="yiyi-492">The arguments are interpreted as for <a class="reference internal" href="#logging.debug" title="logging.debug"><code class="xref py py-func docutils literal"><span class="pre">debug()</span></code></a>. </span><span class="yiyi-st" id="yiyi-493">Exception info is added to the logging message. </span><span class="yiyi-st" id="yiyi-494">This function should only be called from an exception handler.</span></p></dd></dl><dl class="function"><dt id="logging.log"><span class="yiyi-st" id="yiyi-495"> <code class="descclassname">logging.</code><code class="descname">log</code><span class="sig-paren">(</span><em>level</em>, <em>msg</em>, <em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-496">Logs a message with level <em>level</em> on the root logger. </span><span class="yiyi-st" id="yiyi-497">The other arguments are interpreted as for <a class="reference internal" href="#logging.debug" title="logging.debug"><code class="xref py py-func docutils literal"><span class="pre">debug()</span></code></a>.</span></p><div class="admonition note"><p class="first admonition-title"><span class="yiyi-st" id="yiyi-498">Note</span></p><p class="last"><span class="yiyi-st" id="yiyi-499">The above module-level convenience functions, which delegate to the root logger, call <a class="reference internal" href="#logging.basicConfig" title="logging.basicConfig"><code class="xref py py-func docutils literal"><span class="pre">basicConfig()</span></code></a> to ensure that at least one handler is available. </span><span class="yiyi-st" id="yiyi-500">Because of this, they should <em>not</em> be used in threads, in versions of Python earlier than 2.7.1 and 3.2, unless at least one handler has been added to the root logger <em>before</em> the threads are started. </span><span class="yiyi-st" id="yiyi-501">In earlier versions of Python, due to a thread safety shortcoming in <a class="reference internal" href="#logging.basicConfig" title="logging.basicConfig"><code class="xref py py-func docutils literal"><span class="pre">basicConfig()</span></code></a>, this can (under rare circumstances) lead to handlers being added multiple times to the root logger, which can in turn lead to multiple messages for the same event.</span></p></div></dd></dl><dl class="function"><dt id="logging.disable"><span class="yiyi-st" id="yiyi-502"> <code class="descclassname">logging.</code><code class="descname">disable</code><span class="sig-paren">(</span><em>lvl</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-503">Provides an overriding level <em>lvl</em> for all loggers which takes precedence over the logger’s own level. </span><span class="yiyi-st" id="yiyi-504">When the need arises to temporarily throttle logging output down across the whole application, this function can be useful. </span><span class="yiyi-st" id="yiyi-505">Its effect is to disable all logging calls of severity <em>lvl</em> and below, so that if you call it with a value of INFO, then all INFO and DEBUG events would be discarded, whereas those of severity WARNING and above would be processed according to the logger’s effective level. </span><span class="yiyi-st" id="yiyi-506">If <code class="docutils literal"><span class="pre">logging.disable(logging.NOTSET)</span></code> is called, it effectively removes this overriding level, so that logging output again depends on the effective levels of individual loggers.</span></p></dd></dl><dl class="function"><dt id="logging.addLevelName"><span class="yiyi-st" id="yiyi-507"> <code class="descclassname">logging.</code><code class="descname">addLevelName</code><span class="sig-paren">(</span><em>lvl</em>, <em>levelName</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-508">Associates level <em>lvl</em> with text <em>levelName</em> in an internal dictionary, which is used to map numeric levels to a textual representation, for example when a <a class="reference internal" href="#logging.Formatter" title="logging.Formatter"><code class="xref py py-class docutils literal"><span class="pre">Formatter</span></code></a> formats a message. </span><span class="yiyi-st" id="yiyi-509">This function can also be used to define your own levels. </span><span class="yiyi-st" id="yiyi-510">The only constraints are that all levels used must be registered using this function, levels should be positive integers and they should increase in increasing order of severity.</span></p><div class="admonition note"><p class="first admonition-title"><span class="yiyi-st" id="yiyi-511">Note</span></p><p class="last"><span class="yiyi-st" id="yiyi-512">If you are thinking of defining your own levels, please see the section on <a class="reference internal" href="../howto/logging.html#custom-levels"><span>Custom Levels</span></a>.</span></p></div></dd></dl><dl class="function"><dt id="logging.getLevelName"><span class="yiyi-st" id="yiyi-513"> <code class="descclassname">logging.</code><code class="descname">getLevelName</code><span class="sig-paren">(</span><em>lvl</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-514">Returns the textual representation of logging level <em>lvl</em>. </span><span class="yiyi-st" id="yiyi-515">If the level is one of the predefined levels <code class="xref py py-const docutils literal"><span class="pre">CRITICAL</span></code>, <code class="xref py py-const docutils literal"><span class="pre">ERROR</span></code>, <code class="xref py py-const docutils literal"><span class="pre">WARNING</span></code>, <code class="xref py py-const docutils literal"><span class="pre">INFO</span></code> or <code class="xref py py-const docutils literal"><span class="pre">DEBUG</span></code> then you get the corresponding string. </span><span class="yiyi-st" id="yiyi-516">If you have associated levels with names using <a class="reference internal" href="#logging.addLevelName" title="logging.addLevelName"><code class="xref py py-func docutils literal"><span class="pre">addLevelName()</span></code></a> then the name you have associated with <em>lvl</em> is returned. </span><span class="yiyi-st" id="yiyi-517">If a numeric value corresponding to one of the defined levels is passed in, the corresponding string representation is returned. </span><span class="yiyi-st" id="yiyi-518">Otherwise, the string ‘Level %s’ % lvl is returned.</span></p><div class="admonition note"><p class="first admonition-title"><span class="yiyi-st" id="yiyi-519">Note</span></p><p class="last"><span class="yiyi-st" id="yiyi-520">Levels are internally integers (as they need to be compared in the logging logic). </span><span class="yiyi-st" id="yiyi-521">This function is used to convert between an integer level and the level name displayed in the formatted log output by means of the <code class="docutils literal"><span class="pre">%(levelname)s</span></code> format specifier (see <a class="reference internal" href="#logrecord-attributes"><span>LogRecord attributes</span></a>).</span></p></div><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-522"><span class="versionmodified">Changed in version 3.4: </span>In Python versions earlier than 3.4, this function could also be passed a text level, and would return the corresponding numeric value of the level. </span><span class="yiyi-st" id="yiyi-523">This undocumented behaviour was considered a mistake, and was removed in Python 3.4, but reinstated in 3.4.2 due to retain backward compatibility.</span></p></div></dd></dl><dl class="function"><dt id="logging.makeLogRecord"><span class="yiyi-st" id="yiyi-524"> <code class="descclassname">logging.</code><code class="descname">makeLogRecord</code><span class="sig-paren">(</span><em>attrdict</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-525">Creates and returns a new <a class="reference internal" href="#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal"><span class="pre">LogRecord</span></code></a> instance whose attributes are defined by <em>attrdict</em>. </span><span class="yiyi-st" id="yiyi-526">This function is useful for taking a pickled <a class="reference internal" href="#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal"><span class="pre">LogRecord</span></code></a> attribute dictionary, sent over a socket, and reconstituting it as a <a class="reference internal" href="#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal"><span class="pre">LogRecord</span></code></a> instance at the receiving end.</span></p></dd></dl><dl class="function"><dt id="logging.basicConfig"><span class="yiyi-st" id="yiyi-527"> <code class="descclassname">logging.</code><code class="descname">basicConfig</code><span class="sig-paren">(</span><em>**kwargs</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-528">Does basic configuration for the logging system by creating a <a class="reference internal" href="logging.handlers.html#logging.StreamHandler" title="logging.StreamHandler"><code class="xref py py-class docutils literal"><span class="pre">StreamHandler</span></code></a> with a default <a class="reference internal" href="#logging.Formatter" title="logging.Formatter"><code class="xref py py-class docutils literal"><span class="pre">Formatter</span></code></a> and adding it to the root logger. </span><span class="yiyi-st" id="yiyi-529">The functions <a class="reference internal" href="#logging.debug" title="logging.debug"><code class="xref py py-func docutils literal"><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"><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"><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"><span class="pre">error()</span></code></a> and <a class="reference internal" href="#logging.critical" title="logging.critical"><code class="xref py py-func docutils literal"><span class="pre">critical()</span></code></a> will call <a class="reference internal" href="#logging.basicConfig" title="logging.basicConfig"><code class="xref py py-func docutils literal"><span class="pre">basicConfig()</span></code></a> automatically if no handlers are defined for the root logger.</span></p><p><span class="yiyi-st" id="yiyi-530">This function does nothing if the root logger already has handlers configured for it.</span></p><div class="admonition note"><p class="first admonition-title"><span class="yiyi-st" id="yiyi-531">Note</span></p><p class="last"><span class="yiyi-st" id="yiyi-532">This function should be called from the main thread before other threads are started. </span><span class="yiyi-st" id="yiyi-533">In versions of Python prior to 2.7.1 and 3.2, if this function is called from multiple threads, it is possible (in rare circumstances) that a handler will be added to the root logger more than once, leading to unexpected results such as messages being duplicated in the log.</span></p></div><p><span class="yiyi-st" id="yiyi-534">The following keyword arguments are supported.</span></p><table border="1" class="docutils"><thead valign="bottom"><tr class="row-odd"><th class="head"><span class="yiyi-st" id="yiyi-535">Format</span></th><th class="head"><span class="yiyi-st" id="yiyi-536">Description</span></th></tr></thead><tbody valign="top"><tr class="row-even"><td><span class="yiyi-st" id="yiyi-537"><code class="docutils literal"><span class="pre">filename</span></code></span></td><td><span class="yiyi-st" id="yiyi-538">Specifies that a FileHandler be created, using the specified filename, rather than a StreamHandler.</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-539"><code class="docutils literal"><span class="pre">filemode</span></code></span></td><td><span class="yiyi-st" id="yiyi-540">Specifies the mode to open the file, if filename is specified (if filemode is unspecified, it defaults to ‘a’).</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-541"><code class="docutils literal"><span class="pre">format</span></code></span></td><td><span class="yiyi-st" id="yiyi-542">Use the specified format string for the handler.</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-543"><code class="docutils literal"><span class="pre">datefmt</span></code></span></td><td><span class="yiyi-st" id="yiyi-544">Use the specified date/time format.</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-545"><code class="docutils literal"><span class="pre">style</span></code></span></td><td><span class="yiyi-st" id="yiyi-546">If <code class="docutils literal"><span class="pre">format</span></code> is specified, use this style for the format string. </span><span class="yiyi-st" id="yiyi-547">One of ‘%’, ‘{‘ or ‘$’ for %-formatting, <a class="reference internal" href="stdtypes.html#str.format" title="str.format"><code class="xref py py-meth docutils literal"><span class="pre">str.format()</span></code></a> or <a class="reference internal" href="string.html#string.Template" title="string.Template"><code class="xref py py-class docutils literal"><span class="pre">string.Template</span></code></a> respectively, and defaulting to ‘%’ if not specified.</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-548"><code class="docutils literal"><span class="pre">level</span></code></span></td><td><span class="yiyi-st" id="yiyi-549">Set the root logger level to the specified level.</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-550"><code class="docutils literal"><span class="pre">stream</span></code></span></td><td><span class="yiyi-st" id="yiyi-551">Use the specified stream to initialize the StreamHandler. </span><span class="yiyi-st" id="yiyi-552">Note that this argument is incompatible with ‘filename’ - if both are present, a <code class="docutils literal"><span class="pre">ValueError</span></code> is raised.</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-553"><code class="docutils literal"><span class="pre">handlers</span></code></span></td><td><span class="yiyi-st" id="yiyi-554">If specified, this should be an iterable of already created handlers to add to the root logger. </span><span class="yiyi-st" id="yiyi-555">Any handlers which don’t already have a formatter set will be assigned the default formatter created in this function. </span><span class="yiyi-st" id="yiyi-556">Note that this argument is incompatible with ‘filename’ or ‘stream’ - if both are present, a <code class="docutils literal"><span class="pre">ValueError</span></code> is raised.</span></td></tr></tbody></table><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-557"><span class="versionmodified">Changed in version 3.2: </span>The <code class="docutils literal"><span class="pre">style</span></code> argument was added.</span></p></div><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-558"><span class="versionmodified">Changed in version 3.3: </span>The <code class="docutils literal"><span class="pre">handlers</span></code> argument was added. </span><span class="yiyi-st" id="yiyi-559">Additional checks were added to catch situations where incompatible arguments are specified (e.g. </span><span class="yiyi-st" id="yiyi-560"><code class="docutils literal"><span class="pre">handlers</span></code> together with <code class="docutils literal"><span class="pre">stream</span></code> or <code class="docutils literal"><span class="pre">filename</span></code>, or <code class="docutils literal"><span class="pre">stream</span></code> together with <code class="docutils literal"><span class="pre">filename</span></code>).</span></p></div></dd></dl><dl class="function"><dt id="logging.shutdown"><span class="yiyi-st" id="yiyi-561"> <code class="descclassname">logging.</code><code class="descname">shutdown</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-562">Informs the logging system to perform an orderly shutdown by flushing and closing all handlers. </span><span class="yiyi-st" id="yiyi-563">This should be called at application exit and no further use of the logging system should be made after this call.</span></p></dd></dl><dl class="function"><dt id="logging.setLoggerClass"><span class="yiyi-st" id="yiyi-564"> <code class="descclassname">logging.</code><code class="descname">setLoggerClass</code><span class="sig-paren">(</span><em>klass</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-565">Tells the logging system to use the class <em>klass</em> when instantiating a logger. </span><span class="yiyi-st" id="yiyi-566">The class should define <a class="reference internal" href="../reference/datamodel.html#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal"><span class="pre">__init__()</span></code></a> such that only a name argument is required, and the <a class="reference internal" href="../reference/datamodel.html#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal"><span class="pre">__init__()</span></code></a> should call <code class="xref py py-meth docutils literal"><span class="pre">Logger.__init__()</span></code>. </span><span class="yiyi-st" id="yiyi-567">This function is typically called before any loggers are instantiated by applications which need to use custom logger behavior.</span></p></dd></dl><dl class="function"><dt id="logging.setLogRecordFactory"><span class="yiyi-st" id="yiyi-568"> <code class="descclassname">logging.</code><code class="descname">setLogRecordFactory</code><span class="sig-paren">(</span><em>factory</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-569">Set a callable which is used to create a <a class="reference internal" href="#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal"><span class="pre">LogRecord</span></code></a>.</span></p><table class="docutils field-list" frame="void" rules="none"><tbody valign="top"><tr class="field-odd field"><th class="field-name"><span class="yiyi-st" id="yiyi-570">Parameters:</span></th><td class="field-body"><span class="yiyi-st" id="yiyi-571"><strong>factory</strong> – The factory callable to be used to instantiate a log record.</span></td></tr></tbody></table><div class="versionadded"><p><span class="yiyi-st" id="yiyi-572"><span class="versionmodified">New in version 3.2: </span>This function has been provided, along with <a class="reference internal" href="#logging.getLogRecordFactory" title="logging.getLogRecordFactory"><code class="xref py py-func docutils literal"><span class="pre">getLogRecordFactory()</span></code></a>, to allow developers more control over how the <a class="reference internal" href="#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal"><span class="pre">LogRecord</span></code></a> representing a logging event is constructed.</span></p></div><p><span class="yiyi-st" id="yiyi-573">The factory has the following signature:</span></p><p><span class="yiyi-st" id="yiyi-574"><code class="docutils literal"><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></span></p><span class="yiyi-st" id="yiyi-575"> <blockquote> <div><table class="docutils field-list" frame="void" rules="none"> <col class="field-name"/> <col class="field-body"/> <tbody valign="top"> <tr class="field-odd field"><th class="field-name">name:</th><td class="field-body">The logger name.</td> </tr> <tr class="field-even field"><th class="field-name">level:</th><td class="field-body">The logging level (numeric).</td> </tr> <tr class="field-odd field"><th class="field-name">fn:</th><td class="field-body">The full pathname of the file where the logging call was made.</td> </tr> <tr class="field-even field"><th class="field-name">lno:</th><td class="field-body">The line number in the file where the logging call was made.</td> </tr> <tr class="field-odd field"><th class="field-name">msg:</th><td class="field-body">The logging message.</td> </tr> <tr class="field-even field"><th class="field-name">args:</th><td class="field-body">The arguments for the logging message.</td> </tr> <tr class="field-odd field"><th class="field-name">exc_info:</th><td class="field-body">An exception tuple, or None.</td> </tr> <tr class="field-even field"><th class="field-name">func:</th><td class="field-body">The name of the function or method which invoked the logging call.</td> </tr> <tr class="field-odd field"><th class="field-name">sinfo:</th><td class="field-body">A stack traceback such as is provided by <a class="reference internal" href="traceback.html#traceback.print_stack" title="traceback.print_stack"><code class="xref py py-func docutils literal"><span class="pre">traceback.print_stack()</span></code></a>, showing the call hierarchy.</td> </tr> <tr class="field-even field"><th class="field-name">kwargs:</th><td class="field-body">Additional keyword arguments.</td> </tr> </tbody> </table> </div></blockquote></span></dd></dl></div><div class="section" id="module-level-attributes"><h2><span class="yiyi-st" id="yiyi-576">16.6.11. </span><span class="yiyi-st" id="yiyi-577">Module-Level Attributes</span></h2><dl class="attribute"><dt id="logging.lastResort"><span class="yiyi-st" id="yiyi-578"> <code class="descclassname">logging.</code><code class="descname">lastResort</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-579">A “handler of last resort” is available through this attribute. </span><span class="yiyi-st" id="yiyi-580">This is a <a class="reference internal" href="logging.handlers.html#logging.StreamHandler" title="logging.StreamHandler"><code class="xref py py-class docutils literal"><span class="pre">StreamHandler</span></code></a> writing to <code class="docutils literal"><span class="pre">sys.stderr</span></code> with a level of <code class="docutils literal"><span class="pre">WARNING</span></code>, and is used to handle logging events in the absence of any logging configuration. </span><span class="yiyi-st" id="yiyi-581">The end result is to just print the message to <code class="docutils literal"><span class="pre">sys.stderr</span></code>. </span><span class="yiyi-st" id="yiyi-582">This replaces the earlier error message saying that “no handlers could be found for logger XYZ”. </span><span class="yiyi-st" id="yiyi-583">If you need the earlier behaviour for some reason, <code class="docutils literal"><span class="pre">lastResort</span></code> can be set to <code class="docutils literal"><span class="pre">None</span></code>.</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-584"><span class="versionmodified">New in version 3.2.</span></span></p></div></dd></dl></div><div class="section" id="integration-with-the-warnings-module"><h2><span class="yiyi-st" id="yiyi-585">16.6.12. </span><span class="yiyi-st" id="yiyi-586">Integration with the warnings module</span></h2><p><span class="yiyi-st" id="yiyi-587">The <a class="reference internal" href="#logging.captureWarnings" title="logging.captureWarnings"><code class="xref py py-func docutils literal"><span class="pre">captureWarnings()</span></code></a> function can be used to integrate <a class="reference internal" href="#module-logging" title="logging: Flexible event logging system for applications."><code class="xref py py-mod docutils literal"><span class="pre">logging</span></code></a> with the <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"><span class="pre">warnings</span></code></a> module.</span></p><dl class="function"><dt id="logging.captureWarnings"><span class="yiyi-st" id="yiyi-588"> <code class="descclassname">logging.</code><code class="descname">captureWarnings</code><span class="sig-paren">(</span><em>capture</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-589">This function is used to turn the capture of warnings by logging on and off.</span></p><p><span class="yiyi-st" id="yiyi-590">If <em>capture</em> is <code class="docutils literal"><span class="pre">True</span></code>, warnings issued by the <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"><span class="pre">warnings</span></code></a> module will be redirected to the logging system. </span><span class="yiyi-st" id="yiyi-591">Specifically, a warning will be formatted using <a class="reference internal" href="warnings.html#warnings.formatwarning" title="warnings.formatwarning"><code class="xref py py-func docutils literal"><span class="pre">warnings.formatwarning()</span></code></a> and the resulting string logged to a logger named <code class="docutils literal"><span class="pre">'py.warnings'</span></code> with a severity of <code class="xref py py-const docutils literal"><span class="pre">WARNING</span></code>.</span></p><p><span class="yiyi-st" id="yiyi-592">If <em>capture</em> is <code class="docutils literal"><span class="pre">False</span></code>, the redirection of warnings to the logging system will stop, and warnings will be redirected to their original destinations (i.e. </span><span class="yiyi-st" id="yiyi-593">those in effect before <code class="docutils literal"><span class="pre">captureWarnings(True)</span></code> was called).</span></p></dd></dl><div class="admonition seealso"><p class="first admonition-title"><span class="yiyi-st" id="yiyi-594">See also</span></p><dl class="last docutils"><dt><span class="yiyi-st" id="yiyi-595">Module <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"><span class="pre">logging.config</span></code></a></span></dt><dd><span class="yiyi-st" id="yiyi-596">Configuration API for the logging module.</span></dd><dt><span class="yiyi-st" id="yiyi-597">Module <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"><span class="pre">logging.handlers</span></code></a></span></dt><dd><span class="yiyi-st" id="yiyi-598">Useful handlers included with the logging module.</span></dd><dt><span class="yiyi-st" id="yiyi-599"><span class="target" id="index-1"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0282"><strong>PEP 282</strong></a> - A Logging System</span></dt><dd><span class="yiyi-st" id="yiyi-600">The proposal which described this feature for inclusion in the Python standard library.</span></dd><dt><span class="yiyi-st" id="yiyi-601"><a class="reference external" href="https://www.red-dove.com/python_logging.html">Original Python logging package</a></span></dt><dd><span class="yiyi-st" id="yiyi-602">This is the original source for the <a class="reference internal" href="#module-logging" title="logging: Flexible event logging system for applications."><code class="xref py py-mod docutils literal"><span class="pre">logging</span></code></a> package. </span><span class="yiyi-st" id="yiyi-603">该站点此版本的包适用与Python 1.5.2, 2.1.x 和 2.2.x，在这些版本的Python标准库中并不包括<a class="reference internal" href="#module-logging" title="logging: Flexible event logging system for applications."><code class="xref py py-mod docutils literal"><span class="pre">logging</span></code></a>包。</span></dd></dl></div></div></div></div>
Reference in New Issue View Git Blame Copy Permalink