klarkxy/hustoj
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
hustoj/web/python-docs/library/contextlib.html
klarkxy 723430cade 增加python文档
2025-03-09 17:10:56 +08:00

961 lines
102 KiB
HTML
Raw Permalink Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
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.
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="zh_CN">
<head>
<meta charset="utf-8" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>contextlib --- 为 with语句上下文提供的工具 &#8212; Python 3.8.20 文档</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<script src="../_static/translations.js"></script>
<script src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="在 Python 3.8.20 文档 中搜索"
href="../_static/opensearch.xml"/>
<link rel="author" title="关于这些文档" href="../about.html" />
<link rel="index" title="索引" href="../genindex.html" />
<link rel="search" title="搜索" href="../search.html" />
<link rel="copyright" title="版权所有" href="../copyright.html" />
<link rel="next" title="abc --- 抽象基类" href="abc.html" />
<link rel="prev" title="dataclasses --- 数据类" href="dataclasses.html" />
<link rel="canonical" href="https://docs.python.org/3/library/contextlib.html" />
<style>
@media only screen {
table.full-width-table {
width: 100%;
}
}
</style>
<link rel="shortcut icon" type="image/png" href="../_static/py.svg" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
<script type="text/javascript" src="../_static/menu.js"></script>
</head>
<body>
<div class="mobile-nav">
<input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"
aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu" />
<label for="menuToggler" class="toggler__label">
<span></span>
</label>
<nav class="nav-content" role="navigation">
<a href="https://www.python.org/" class="nav-logo">
<img src="../_static/py.svg" alt="Logo"/>
</a>
<div class="version_switcher_placeholder"></div>
<form role="search" class="search" action="../search.html" method="get">
<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">
<path fill-rule="nonzero"
d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z" fill="#444"></path>
</svg>
<input type="text" name="q" aria-label="快速搜索"/>
<input type="submit" value="转向"/>
</form>
</nav>
<div class="menu-wrapper">
<nav class="menu" role="navigation" aria-label="main navigation">
<div class="language_switcher_placeholder"></div>
<h3><a href="../contents.html">目录</a></h3>
<ul>
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">contextlib</span></code> --- 为 <code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code>语句上下文提供的工具</a><ul>
<li><a class="reference internal" href="#utilities">工具</a></li>
<li><a class="reference internal" href="#examples-and-recipes">例子和配方</a><ul>
<li><a class="reference internal" href="#supporting-a-variable-number-of-context-managers">支持可变数量的上下文管理器</a></li>
<li><a class="reference internal" href="#catching-exceptions-from-enter-methods">捕获 <code class="docutils literal notranslate"><span class="pre">__enter__</span></code> 方法产生的异常</a></li>
<li><a class="reference internal" href="#cleaning-up-in-an-enter-implementation">在一个 <code class="docutils literal notranslate"><span class="pre">__enter__</span></code> 方法的实现中进行清理</a></li>
<li><a class="reference internal" href="#replacing-any-use-of-try-finally-and-flag-variables">替换任何对 <code class="docutils literal notranslate"><span class="pre">try-finally</span></code> 和旗标变量的使用</a></li>
<li><a class="reference internal" href="#using-a-context-manager-as-a-function-decorator">将上下文管理器作为函数装饰器使用</a></li>
</ul>
</li>
<li><a class="reference internal" href="#single-use-reusable-and-reentrant-context-managers">单独使用，可重用并可重进入的上下文管理器</a><ul>
<li><a class="reference internal" href="#reentrant-context-managers">重进入上下文管理器</a></li>
<li><a class="reference internal" href="#reusable-context-managers">可重用的上下文管理器</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>上一个主题</h4>
<p class="topless"><a href="dataclasses.html"
title="上一章"><code class="xref py py-mod docutils literal notranslate"><span class="pre">dataclasses</span></code> --- 数据类</a></p>
<h4>下一个主题</h4>
<p class="topless"><a href="abc.html"
title="下一章"><code class="xref py py-mod docutils literal notranslate"><span class="pre">abc</span></code> --- 抽象基类</a></p>
<div role="note" aria-label="source link">
<h3>本页</h3>
<ul class="this-page-menu">
<li><a href="../bugs.html">报告 Bug</a></li>
<li>
<a href="https://github.com/python/cpython/blob/3.8/Doc/library/contextlib.rst"
rel="nofollow">显示源代码
</a>
</li>
</ul>
</div>
</nav>
</div>
</div>
<div id="outdated-warning" style="padding: .5em; text-align: center; background-color: #FFBABA; color: #6A0E0E;">
这个文档所针对的是一个已不再受支持的 Python 旧版本。
你应当升级版本，并阅读
<a href="/3/library/contextlib.html"> Python 当前稳定版本的文档</a>.
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>导航</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="总目录"
accesskey="I">索引</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python 模块索引"
>模块</a> |</li>
<li class="right" >
<a href="abc.html" title="abc --- 抽象基类"
accesskey="N">下一页</a> |</li>
<li class="right" >
<a href="dataclasses.html" title="dataclasses --- 数据类"
accesskey="P">上一页</a> |</li>
<li><img src="../_static/py.svg" alt="python logo" style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> &#187;</li>
<li class="switchers">
<div class="language_switcher_placeholder"></div>
<div class="version_switcher_placeholder"></div>
</li>
<li>
</li>
<li id="cpython-language-and-version">
<a href="../index.html">3.8.20 Documentation</a> &#187;
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python 标准库</a> &#187;</li>
<li class="nav-item nav-item-2"><a href="python.html" accesskey="U">Python 运行时服务</a> &#187;</li>
<li class="right">
<div class="inline-search" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="快速搜索" aria-label="快速搜索" type="text" name="q" />
<input type="submit" value="转向" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
|
</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="module-contextlib">
<span id="contextlib-utilities-for-with-statement-contexts"></span><h1><code class="xref py py-mod docutils literal notranslate"><span class="pre">contextlib</span></code> --- 为 <code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code>语句上下文提供的工具<a class="headerlink" href="#module-contextlib" title="永久链接至标题"></a></h1>
<p><strong>源代码</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.8/Lib/contextlib.py">Lib/contextlib.py</a></p>
<hr class="docutils" />
<p>此模块为涉及 <a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a> 语句的常见任务提供了实用的程序。更多信息请参见 <a class="reference internal" href="stdtypes.html#typecontextmanager"><span class="std std-ref">上下文管理器类型</span></a> 和 <a class="reference internal" href="../reference/datamodel.html#context-managers"><span class="std std-ref">with 语句上下文管理器</span></a>。</p>
<section id="utilities">
<h2>工具<a class="headerlink" href="#utilities" title="永久链接至标题"></a></h2>
<p>提供的函数和类：</p>
<dl class="class">
<dt id="contextlib.AbstractContextManager">
<em class="property">class </em><code class="sig-prename descclassname">contextlib.</code><code class="sig-name descname">AbstractContextManager</code><a class="headerlink" href="#contextlib.AbstractContextManager" title="永久链接至目标"></a></dt>
<dd><p>一个为实现了 <a class="reference internal" href="../reference/datamodel.html#object.__enter__" title="object.__enter__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">object.__enter__()</span></code></a> 与 <a class="reference internal" href="../reference/datamodel.html#object.__exit__" title="object.__exit__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">object.__exit__()</span></code></a> 的类提供的 <a class="reference internal" href="../glossary.html#term-abstract-base-class"><span class="xref std std-term">abstract base class</span></a>。为 <a class="reference internal" href="../reference/datamodel.html#object.__enter__" title="object.__enter__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">object.__enter__()</span></code></a> 提供的一个默认实现是返回 <code class="docutils literal notranslate"><span class="pre">self</span></code> 而 <a class="reference internal" href="../reference/datamodel.html#object.__exit__" title="object.__exit__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">object.__exit__()</span></code></a> 是一个默认返回 <code class="docutils literal notranslate"><span class="pre">None</span></code> 的抽象方法。 参见 <a class="reference internal" href="stdtypes.html#typecontextmanager"><span class="std std-ref">上下文管理器类型</span></a> 的定义。</p>
<div class="versionadded">
<p><span class="versionmodified added">3.6 新版功能.</span></p>
</div>
</dd></dl>
<dl class="class">
<dt id="contextlib.AbstractAsyncContextManager">
<em class="property">class </em><code class="sig-prename descclassname">contextlib.</code><code class="sig-name descname">AbstractAsyncContextManager</code><a class="headerlink" href="#contextlib.AbstractAsyncContextManager" title="永久链接至目标"></a></dt>
<dd><p>一个为实现了 <a class="reference internal" href="../reference/datamodel.html#object.__aenter__" title="object.__aenter__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">object.__aenter__()</span></code></a> 与 <a class="reference internal" href="../reference/datamodel.html#object.__aexit__" title="object.__aexit__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">object.__aexit__()</span></code></a> 的类提供的 <a class="reference internal" href="../glossary.html#term-abstract-base-class"><span class="xref std std-term">abstract base class</span></a>。 为 <a class="reference internal" href="../reference/datamodel.html#object.__aenter__" title="object.__aenter__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">object.__aenter__()</span></code></a> 提供的一个默认实现是返回 <code class="docutils literal notranslate"><span class="pre">self</span></code> 而 <a class="reference internal" href="../reference/datamodel.html#object.__aexit__" title="object.__aexit__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">object.__aexit__()</span></code></a> 是一个默认返回 <code class="docutils literal notranslate"><span class="pre">None</span></code> 的抽象方法。 参见 <a class="reference internal" href="../reference/datamodel.html#async-context-managers"><span class="std std-ref">异步上下文管理器</span></a> 的定义。</p>
<div class="versionadded">
<p><span class="versionmodified added">3.7 新版功能.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="contextlib.contextmanager">
<code class="sig-prename descclassname">&#64;</code><code class="sig-prename descclassname">contextlib.</code><code class="sig-name descname">contextmanager</code><a class="headerlink" href="#contextlib.contextmanager" title="永久链接至目标"></a></dt>
<dd><p>这个函数是一个 <a class="reference internal" href="../glossary.html#term-decorator"><span class="xref std std-term">decorator</span></a> ，它可以定义一个支持 <a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a> 语句上下文的工厂函数， 而不需要创建一个类或区 <a class="reference internal" href="../reference/datamodel.html#object.__enter__" title="object.__enter__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__enter__()</span></code></a> 与 <a class="reference internal" href="../reference/datamodel.html#object.__exit__" title="object.__exit__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__exit__()</span></code></a> 方法。</p>
<p>尽管许多对象原生支持使用 with 语句，但有些需要被管理的资源并不是上下文管理器，并且没有实现 <code class="docutils literal notranslate"><span class="pre">close()</span></code> 方法而不能使用 <code class="docutils literal notranslate"><span class="pre">contextlib.closing</span></code> 。</p>
<p>下面是一个抽象的示例，展示如何确保正确的资源管理：</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">contextlib</span> <span class="kn">import</span> <span class="n">contextmanager</span>
<span class="nd">@contextmanager</span>
<span class="k">def</span> <span class="nf">managed_resource</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">kwds</span><span class="p">):</span>
<span class="c1"># Code to acquire resource, e.g.:</span>
<span class="n">resource</span> <span class="o">=</span> <span class="n">acquire_resource</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">kwds</span><span class="p">)</span>
<span class="k">try</span><span class="p">:</span>
<span class="k">yield</span> <span class="n">resource</span>
<span class="k">finally</span><span class="p">:</span>
<span class="c1"># Code to release resource, e.g.:</span>
<span class="n">release_resource</span><span class="p">(</span><span class="n">resource</span><span class="p">)</span>
<span class="o">&gt;&gt;&gt;</span> <span class="k">with</span> <span class="n">managed_resource</span><span class="p">(</span><span class="n">timeout</span><span class="o">=</span><span class="mi">3600</span><span class="p">)</span> <span class="k">as</span> <span class="n">resource</span><span class="p">:</span>
<span class="o">...</span> <span class="c1"># Resource is released at the end of this block,</span>
<span class="o">...</span> <span class="c1"># even if code in the block raises an exception</span>
</pre></div>
</div>
<p>被装饰的函数在被调用时，必须返回一个 <a class="reference internal" href="../glossary.html#term-generator"><span class="xref std std-term">generator</span></a>-iterator。这个迭代器必须只 yield 一个值出来，这个值会被用在 <a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a> 语句中，绑定到 <code class="xref std std-keyword docutils literal notranslate"><span class="pre">as</span></code> 后面的变量，如果给定了的话。</p>
<p>当生成器发生 yield 时，嵌套在 <a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a> 语句中的语句体会被执行。 语句体执行完毕离开之后，该生成器将被恢复执行。 如果在该语句体中发生了未处理的异常，则该异常会在生成器发生 yield 时重新被引发。 因此，你可以使用 <a class="reference internal" href="../reference/compound_stmts.html#try"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">try</span></code></a>...<a class="reference internal" href="../reference/compound_stmts.html#except"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">except</span></code></a>...<a class="reference internal" href="../reference/compound_stmts.html#finally"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">finally</span></code></a> 语句来捕获该异常（如果有的话），或确保进行了一些清理。 如果仅出于记录日志或执行某些操作（而非完全抑制异常）的目的捕获了异常，生成器必须重新引发该异常。 否则生成器的上下文管理器将向 <code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code> 语句指示该异常已经被处理，程序将立即在 <code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code> 语句之后恢复并继续执行。</p>
<p><a class="reference internal" href="#contextlib.contextmanager" title="contextlib.contextmanager"><code class="xref py py-func docutils literal notranslate"><span class="pre">contextmanager()</span></code></a> 使用 <a class="reference internal" href="#contextlib.ContextDecorator" title="contextlib.ContextDecorator"><code class="xref py py-class docutils literal notranslate"><span class="pre">ContextDecorator</span></code></a> 因此它创建的上下文管理器不仅可以用在 <a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a> 语句中，还可以用作一个装饰器。当它用作一个装饰器时，每一次函数调用时都会隐式创建一个新的生成器实例（这使得 <a class="reference internal" href="#contextlib.contextmanager" title="contextlib.contextmanager"><code class="xref py py-func docutils literal notranslate"><span class="pre">contextmanager()</span></code></a> 创建的上下文管理器满足了支持多次调用以用作装饰器的需求，而非“一次性”的上下文管理器）。</p>
<div class="versionchanged">
<p><span class="versionmodified changed">在 3.2 版更改: </span><a class="reference internal" href="#contextlib.ContextDecorator" title="contextlib.ContextDecorator"><code class="xref py py-class docutils literal notranslate"><span class="pre">ContextDecorator</span></code></a> 的使用。</p>
</div>
</dd></dl>
<dl class="function">
<dt id="contextlib.asynccontextmanager">
<code class="sig-prename descclassname">&#64;</code><code class="sig-prename descclassname">contextlib.</code><code class="sig-name descname">asynccontextmanager</code><a class="headerlink" href="#contextlib.asynccontextmanager" title="永久链接至目标"></a></dt>
<dd><p>与 <a class="reference internal" href="#contextlib.contextmanager" title="contextlib.contextmanager"><code class="xref py py-func docutils literal notranslate"><span class="pre">contextmanager()</span></code></a> 类似，但创建的是一个 <a class="reference internal" href="../reference/datamodel.html#async-context-managers"><span class="std std-ref">异步上下文管理器</span></a>。</p>
<p>这个函数是一个 <a class="reference internal" href="../glossary.html#term-decorator"><span class="xref std std-term">decorator</span></a> ，它可以定义一个支持 <a class="reference internal" href="../reference/compound_stmts.html#async-with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">async</span> <span class="pre">with</span></code></a> 语句的异步上下文管理器的工厂函数， 而不需要创建一个类或区分 <a class="reference internal" href="../reference/datamodel.html#object.__aenter__" title="object.__aenter__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__aenter__()</span></code></a> 与 <a class="reference internal" href="../reference/datamodel.html#object.__aexit__" title="object.__aexit__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__aexit__()</span></code></a> 方法。它必须被作用在一个 <a class="reference internal" href="../glossary.html#term-asynchronous-generator"><span class="xref std std-term">asynchronous generator</span></a> 函数上</p>
<p>一个简单的示例：</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">contextlib</span> <span class="kn">import</span> <span class="n">asynccontextmanager</span>
<span class="nd">@asynccontextmanager</span>
<span class="k">async</span> <span class="k">def</span> <span class="nf">get_connection</span><span class="p">():</span>
<span class="n">conn</span> <span class="o">=</span> <span class="k">await</span> <span class="n">acquire_db_connection</span><span class="p">()</span>
<span class="k">try</span><span class="p">:</span>
<span class="k">yield</span> <span class="n">conn</span>
<span class="k">finally</span><span class="p">:</span>
<span class="k">await</span> <span class="n">release_db_connection</span><span class="p">(</span><span class="n">conn</span><span class="p">)</span>
<span class="k">async</span> <span class="k">def</span> <span class="nf">get_all_users</span><span class="p">():</span>
<span class="k">async</span> <span class="k">with</span> <span class="n">get_connection</span><span class="p">()</span> <span class="k">as</span> <span class="n">conn</span><span class="p">:</span>
<span class="k">return</span> <span class="n">conn</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="s1">&#39;SELECT ...&#39;</span><span class="p">)</span>
</pre></div>
</div>
<div class="versionadded">
<p><span class="versionmodified added">3.7 新版功能.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="contextlib.closing">
<code class="sig-prename descclassname">contextlib.</code><code class="sig-name descname">closing</code><span class="sig-paren">(</span><em class="sig-param">thing</em><span class="sig-paren">)</span><a class="headerlink" href="#contextlib.closing" title="永久链接至目标"></a></dt>
<dd><p>返回一个在语句块执行完成时关闭 <em>things</em> 的上下文管理器。这基本上等价于</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">contextlib</span> <span class="kn">import</span> <span class="n">contextmanager</span>
<span class="nd">@contextmanager</span>
<span class="k">def</span> <span class="nf">closing</span><span class="p">(</span><span class="n">thing</span><span class="p">):</span>
<span class="k">try</span><span class="p">:</span>
<span class="k">yield</span> <span class="n">thing</span>
<span class="k">finally</span><span class="p">:</span>
<span class="n">thing</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
</pre></div>
</div>
<p>并允许你编写这样的代码</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">contextlib</span> <span class="kn">import</span> <span class="n">closing</span>
<span class="kn">from</span> <span class="nn">urllib.request</span> <span class="kn">import</span> <span class="n">urlopen</span>
<span class="k">with</span> <span class="n">closing</span><span class="p">(</span><span class="n">urlopen</span><span class="p">(</span><span class="s1">&#39;http://www.python.org&#39;</span><span class="p">))</span> <span class="k">as</span> <span class="n">page</span><span class="p">:</span>
<span class="k">for</span> <span class="n">line</span> <span class="ow">in</span> <span class="n">page</span><span class="p">:</span>
<span class="nb">print</span><span class="p">(</span><span class="n">line</span><span class="p">)</span>
</pre></div>
</div>
<p>而无需显式地关闭 <code class="docutils literal notranslate"><span class="pre">page</span></code> 。 即使发生错误，在退出 <a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a> 语句块时， <code class="docutils literal notranslate"><span class="pre">page.close()</span></code> 也同样会被调用。</p>
</dd></dl>
<span class="target" id="simplifying-support-for-single-optional-context-managers"></span><dl class="function">
<dt id="contextlib.nullcontext">
<code class="sig-prename descclassname">contextlib.</code><code class="sig-name descname">nullcontext</code><span class="sig-paren">(</span><em class="sig-param">enter_result=None</em><span class="sig-paren">)</span><a class="headerlink" href="#contextlib.nullcontext" title="永久链接至目标"></a></dt>
<dd><p>返回一个从 <em>__enter__</em> 返回 <em>enter_result</em> 的上下文管理器，除此之外不执行任何操作。它旨在用于可选上下文管理器的一种替代，例如：:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">myfunction</span><span class="p">(</span><span class="n">arg</span><span class="p">,</span> <span class="n">ignore_exceptions</span><span class="o">=</span><span class="kc">False</span><span class="p">):</span>
<span class="k">if</span> <span class="n">ignore_exceptions</span><span class="p">:</span>
<span class="c1"># Use suppress to ignore all exceptions.</span>
<span class="n">cm</span> <span class="o">=</span> <span class="n">contextlib</span><span class="o">.</span><span class="n">suppress</span><span class="p">(</span><span class="ne">Exception</span><span class="p">)</span>
<span class="k">else</span><span class="p">:</span>
<span class="c1"># Do not ignore any exceptions, cm has no effect.</span>
<span class="n">cm</span> <span class="o">=</span> <span class="n">contextlib</span><span class="o">.</span><span class="n">nullcontext</span><span class="p">()</span>
<span class="k">with</span> <span class="n">cm</span><span class="p">:</span>
<span class="c1"># Do something</span>
</pre></div>
</div>
<p>一个使用 <em>enter_result</em> 的例子：</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">process_file</span><span class="p">(</span><span class="n">file_or_path</span><span class="p">):</span>
<span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">file_or_path</span><span class="p">,</span> <span class="nb">str</span><span class="p">):</span>
<span class="c1"># If string, open file</span>
<span class="n">cm</span> <span class="o">=</span> <span class="nb">open</span><span class="p">(</span><span class="n">file_or_path</span><span class="p">)</span>
<span class="k">else</span><span class="p">:</span>
<span class="c1"># Caller is responsible for closing file</span>
<span class="n">cm</span> <span class="o">=</span> <span class="n">nullcontext</span><span class="p">(</span><span class="n">file_or_path</span><span class="p">)</span>
<span class="k">with</span> <span class="n">cm</span> <span class="k">as</span> <span class="n">file</span><span class="p">:</span>
<span class="c1"># Perform processing on the file</span>
</pre></div>
</div>
<div class="versionadded">
<p><span class="versionmodified added">3.7 新版功能.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="contextlib.suppress">
<code class="sig-prename descclassname">contextlib.</code><code class="sig-name descname">suppress</code><span class="sig-paren">(</span><em class="sig-param">*exceptions</em><span class="sig-paren">)</span><a class="headerlink" href="#contextlib.suppress" title="永久链接至目标"></a></dt>
<dd><p>返回一个上下文管理器，如果任何一个指定的异常发生在使用该上下文管理器的 with 语句中，该异常将被它抑制，然后程序将从 with 语句结束后的第一个语句开始恢复执行。</p>
<p>与完全抑制异常的任何其他机制一样，该上下文管理器应当只用来抑制非常具体的错误，并确保该场景下静默地继续执行程序是通用的正确做法。</p>
<p>例如</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">contextlib</span> <span class="kn">import</span> <span class="n">suppress</span>
<span class="k">with</span> <span class="n">suppress</span><span class="p">(</span><span class="ne">FileNotFoundError</span><span class="p">):</span>
<span class="n">os</span><span class="o">.</span><span class="n">remove</span><span class="p">(</span><span class="s1">&#39;somefile.tmp&#39;</span><span class="p">)</span>
<span class="k">with</span> <span class="n">suppress</span><span class="p">(</span><span class="ne">FileNotFoundError</span><span class="p">):</span>
<span class="n">os</span><span class="o">.</span><span class="n">remove</span><span class="p">(</span><span class="s1">&#39;someotherfile.tmp&#39;</span><span class="p">)</span>
</pre></div>
</div>
<p>这段代码等价于：</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">try</span><span class="p">:</span>
<span class="n">os</span><span class="o">.</span><span class="n">remove</span><span class="p">(</span><span class="s1">&#39;somefile.tmp&#39;</span><span class="p">)</span>
<span class="k">except</span> <span class="ne">FileNotFoundError</span><span class="p">:</span>
<span class="k">pass</span>
<span class="k">try</span><span class="p">:</span>
<span class="n">os</span><span class="o">.</span><span class="n">remove</span><span class="p">(</span><span class="s1">&#39;someotherfile.tmp&#39;</span><span class="p">)</span>
<span class="k">except</span> <span class="ne">FileNotFoundError</span><span class="p">:</span>
<span class="k">pass</span>
</pre></div>
</div>
<p>该上下文管理器是 <a class="reference internal" href="#reentrant-cms"><span class="std std-ref">reentrant</span></a> 。</p>
<div class="versionadded">
<p><span class="versionmodified added">3.4 新版功能.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="contextlib.redirect_stdout">
<code class="sig-prename descclassname">contextlib.</code><code class="sig-name descname">redirect_stdout</code><span class="sig-paren">(</span><em class="sig-param">new_target</em><span class="sig-paren">)</span><a class="headerlink" href="#contextlib.redirect_stdout" title="永久链接至目标"></a></dt>
<dd><p>用于将 <a class="reference internal" href="sys.html#sys.stdout" title="sys.stdout"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.stdout</span></code></a> 临时重定向到一个文件或类文件对象的上下文管理器。</p>
<p>该工具给已有的将输出硬编码写到 stdout 的函数或类提供了额外的灵活性。</p>
<p>例如， <a class="reference internal" href="functions.html#help" title="help"><code class="xref py py-func docutils literal notranslate"><span class="pre">help()</span></code></a> 通常把输出写到 <em>sys.stdout</em> 。你可以通过重定向到一个 <a class="reference internal" href="io.html#io.StringIO" title="io.StringIO"><code class="xref py py-class docutils literal notranslate"><span class="pre">io.StringIO</span></code></a> 来捕获该输出到一个字符串中。</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">f</span> <span class="o">=</span> <span class="n">io</span><span class="o">.</span><span class="n">StringIO</span><span class="p">()</span>
<span class="k">with</span> <span class="n">redirect_stdout</span><span class="p">(</span><span class="n">f</span><span class="p">):</span>
<span class="n">help</span><span class="p">(</span><span class="nb">pow</span><span class="p">)</span>
<span class="n">s</span> <span class="o">=</span> <span class="n">f</span><span class="o">.</span><span class="n">getvalue</span><span class="p">()</span>
</pre></div>
</div>
<p>如果要把 <a class="reference internal" href="functions.html#help" title="help"><code class="xref py py-func docutils literal notranslate"><span class="pre">help()</span></code></a> 的输出写到磁盘上的一个文件，重定向该输出到一个常规文件：</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s1">&#39;help.txt&#39;</span><span class="p">,</span> <span class="s1">&#39;w&#39;</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>
<span class="k">with</span> <span class="n">redirect_stdout</span><span class="p">(</span><span class="n">f</span><span class="p">):</span>
<span class="n">help</span><span class="p">(</span><span class="nb">pow</span><span class="p">)</span>
</pre></div>
</div>
<p>如果要把 <a class="reference internal" href="functions.html#help" title="help"><code class="xref py py-func docutils literal notranslate"><span class="pre">help()</span></code></a> 的输出写到 <em>sys.stderr</em> ：</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="n">redirect_stdout</span><span class="p">(</span><span class="n">sys</span><span class="o">.</span><span class="n">stderr</span><span class="p">):</span>
<span class="n">help</span><span class="p">(</span><span class="nb">pow</span><span class="p">)</span>
</pre></div>
</div>
<p>需要注意的点在于， <a class="reference internal" href="sys.html#sys.stdout" title="sys.stdout"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.stdout</span></code></a> 的全局副作用意味着此上下文管理器不适合在库代码和大多数多线程应用程序中使用。它对子进程的输出没有影响。不过对于许多工具脚本而言，它仍然是一个有用的方法。</p>
<p>该上下文管理器是 <a class="reference internal" href="#reentrant-cms"><span class="std std-ref">reentrant</span></a> 。</p>
<div class="versionadded">
<p><span class="versionmodified added">3.4 新版功能.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="contextlib.redirect_stderr">
<code class="sig-prename descclassname">contextlib.</code><code class="sig-name descname">redirect_stderr</code><span class="sig-paren">(</span><em class="sig-param">new_target</em><span class="sig-paren">)</span><a class="headerlink" href="#contextlib.redirect_stderr" title="永久链接至目标"></a></dt>
<dd><p>与 <a class="reference internal" href="#contextlib.redirect_stdout" title="contextlib.redirect_stdout"><code class="xref py py-func docutils literal notranslate"><span class="pre">redirect_stdout()</span></code></a> 类似，不过是将 <a class="reference internal" href="sys.html#sys.stderr" title="sys.stderr"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.stderr</span></code></a> 重定向到一个文件或类文件对象。</p>
<p>该上下文管理器是 <a class="reference internal" href="#reentrant-cms"><span class="std std-ref">reentrant</span></a> 。</p>
<div class="versionadded">
<p><span class="versionmodified added">3.5 新版功能.</span></p>
</div>
</dd></dl>
<dl class="class">
<dt id="contextlib.ContextDecorator">
<em class="property">class </em><code class="sig-prename descclassname">contextlib.</code><code class="sig-name descname">ContextDecorator</code><a class="headerlink" href="#contextlib.ContextDecorator" title="永久链接至目标"></a></dt>
<dd><p>一个使上下文管理器能用作装饰器的基类。</p>
<p>与往常一样，继承自 <code class="docutils literal notranslate"><span class="pre">ContextDecorator</span></code>  的上下文管理器必须实现 <code class="docutils literal notranslate"><span class="pre">__enter__</span></code> 与 <code class="docutils literal notranslate"><span class="pre">__exit__</span></code> 。即使用作装饰器， <code class="docutils literal notranslate"><span class="pre">__exit__</span></code> 依旧会保持可能的异常处理。</p>
<p><code class="docutils literal notranslate"><span class="pre">ContextDecorator</span></code> 被用在 <a class="reference internal" href="#contextlib.contextmanager" title="contextlib.contextmanager"><code class="xref py py-func docutils literal notranslate"><span class="pre">contextmanager()</span></code></a> 中，因此你自然获得了这项功能。</p>
<p><code class="docutils literal notranslate"><span class="pre">ContextDecorator</span></code> 的示例:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">contextlib</span> <span class="kn">import</span> <span class="n">ContextDecorator</span>
<span class="k">class</span> <span class="nc">mycontext</span><span class="p">(</span><span class="n">ContextDecorator</span><span class="p">):</span>
<span class="k">def</span> <span class="fm">__enter__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="nb">print</span><span class="p">(</span><span class="s1">&#39;Starting&#39;</span><span class="p">)</span>
<span class="k">return</span> <span class="bp">self</span>
<span class="k">def</span> <span class="fm">__exit__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="o">*</span><span class="n">exc</span><span class="p">):</span>
<span class="nb">print</span><span class="p">(</span><span class="s1">&#39;Finishing&#39;</span><span class="p">)</span>
<span class="k">return</span> <span class="kc">False</span>
<span class="o">&gt;&gt;&gt;</span> <span class="nd">@mycontext</span><span class="p">()</span>
<span class="o">...</span> <span class="k">def</span> <span class="nf">function</span><span class="p">():</span>
<span class="o">...</span> <span class="nb">print</span><span class="p">(</span><span class="s1">&#39;The bit in the middle&#39;</span><span class="p">)</span>
<span class="o">...</span>
<span class="o">&gt;&gt;&gt;</span> <span class="n">function</span><span class="p">()</span>
<span class="n">Starting</span>
<span class="n">The</span> <span class="n">bit</span> <span class="ow">in</span> <span class="n">the</span> <span class="n">middle</span>
<span class="n">Finishing</span>
<span class="o">&gt;&gt;&gt;</span> <span class="k">with</span> <span class="n">mycontext</span><span class="p">():</span>
<span class="o">...</span> <span class="nb">print</span><span class="p">(</span><span class="s1">&#39;The bit in the middle&#39;</span><span class="p">)</span>
<span class="o">...</span>
<span class="n">Starting</span>
<span class="n">The</span> <span class="n">bit</span> <span class="ow">in</span> <span class="n">the</span> <span class="n">middle</span>
<span class="n">Finishing</span>
</pre></div>
</div>
<p>这个改动只是针对如下形式的一个语法糖：</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">f</span><span class="p">():</span>
<span class="k">with</span> <span class="n">cm</span><span class="p">():</span>
<span class="c1"># Do stuff</span>
</pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre">ContextDecorator</span></code> 使得你可以这样改写：</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nd">@cm</span><span class="p">()</span>
<span class="k">def</span> <span class="nf">f</span><span class="p">():</span>
<span class="c1"># Do stuff</span>
</pre></div>
</div>
<p>这能清楚地表明， <code class="docutils literal notranslate"><span class="pre">cm</span></code> 作用于整个函数，而不仅仅是函数的一部分（同时也能保持不错的缩进层级）。</p>
<p>现有的上下文管理器即使已经有基类，也可以使用 <code class="docutils literal notranslate"><span class="pre">ContextDecorator</span></code> 作为混合类进行扩展：</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">contextlib</span> <span class="kn">import</span> <span class="n">ContextDecorator</span>
<span class="k">class</span> <span class="nc">mycontext</span><span class="p">(</span><span class="n">ContextBaseClass</span><span class="p">,</span> <span class="n">ContextDecorator</span><span class="p">):</span>
<span class="k">def</span> <span class="fm">__enter__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="k">return</span> <span class="bp">self</span>
<span class="k">def</span> <span class="fm">__exit__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="o">*</span><span class="n">exc</span><span class="p">):</span>
<span class="k">return</span> <span class="kc">False</span>
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">注解</p>
<p>由于被装饰的函数必须能够被多次调用，因此对应的上下文管理器必须支持在多个 <a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a> 语句中使用。如果不是这样，则应当使用原来的具有显式 <code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code> 语句的形式使用该上下文管理器。</p>
</div>
<div class="versionadded">
<p><span class="versionmodified added">3.2 新版功能.</span></p>
</div>
</dd></dl>
<dl class="class">
<dt id="contextlib.ExitStack">
<em class="property">class </em><code class="sig-prename descclassname">contextlib.</code><code class="sig-name descname">ExitStack</code><a class="headerlink" href="#contextlib.ExitStack" title="永久链接至目标"></a></dt>
<dd><p>该上下文管理器的设计目标是使得在编码中组合其他上下文管理器和清理函数更加容易，尤其是那些可选的或由输入数据驱动的上下文管理器。</p>
<p>例如，通过一个如下的 with 语句可以很容易处理一组文件：</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="n">ExitStack</span><span class="p">()</span> <span class="k">as</span> <span class="n">stack</span><span class="p">:</span>
<span class="n">files</span> <span class="o">=</span> <span class="p">[</span><span class="n">stack</span><span class="o">.</span><span class="n">enter_context</span><span class="p">(</span><span class="nb">open</span><span class="p">(</span><span class="n">fname</span><span class="p">))</span> <span class="k">for</span> <span class="n">fname</span> <span class="ow">in</span> <span class="n">filenames</span><span class="p">]</span>
<span class="c1"># All opened files will automatically be closed at the end of</span>
<span class="c1"># the with statement, even if attempts to open files later</span>
<span class="c1"># in the list raise an exception</span>
</pre></div>
</div>
<p>每个实例维护一个注册了一组回调的栈，这些回调在实例关闭时以相反的顺序被调用（显式或隐式地在 <a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a> 语句的末尾）。请注意，当一个栈实例被垃圾回收时，这些回调将 <em>不会</em> 被隐式调用。</p>
<p>通过使用这个基于栈的模型，那些通过 <code class="docutils literal notranslate"><span class="pre">__init__</span></code> 方法获取资源的上下文管理器（如文件对象）能够被正确处理。</p>
<p>由于注册的回调函数是按照与注册相反的顺序调用的，因此最终的行为就像多个嵌套的 <a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a> 语句用在这些注册的回调函数上。这个行为甚至扩展到了异常处理：如果内部的回调函数抑制或替换了异常，则外部回调收到的参数是基于该更新后的状态得到的。</p>
<p>这是一个相对底层的 API，它负责正确处理栈里回调退出时依次展开的细节。它为相对高层的上下文管理器提供了一个合适的基础，使得它能根据应用程序的需求使用特定方式操作栈。</p>
<div class="versionadded">
<p><span class="versionmodified added">3.3 新版功能.</span></p>
</div>
<dl class="method">
<dt id="contextlib.ExitStack.enter_context">
<code class="sig-name descname">enter_context</code><span class="sig-paren">(</span><em class="sig-param">cm</em><span class="sig-paren">)</span><a class="headerlink" href="#contextlib.ExitStack.enter_context" title="永久链接至目标"></a></dt>
<dd><p>进入一个新的上下文管理器并将其 <a class="reference internal" href="../reference/datamodel.html#object.__exit__" title="object.__exit__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__exit__()</span></code></a> 方法添加到回调栈中。 返回值是该上下文管理器自己的 <a class="reference internal" href="../reference/datamodel.html#object.__enter__" title="object.__enter__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__enter__()</span></code></a> 方法的输出结果。</p>
<p>这些上下文管理器可能会屏蔽异常就如当它们作为 <a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a> 语句的一部分直接使用时通常表现的行为一样。</p>
</dd></dl>
<dl class="method">
<dt id="contextlib.ExitStack.push">
<code class="sig-name descname">push</code><span class="sig-paren">(</span><em class="sig-param">exit</em><span class="sig-paren">)</span><a class="headerlink" href="#contextlib.ExitStack.push" title="永久链接至目标"></a></dt>
<dd><p>将一个上下文管理器的 <a class="reference internal" href="../reference/datamodel.html#object.__exit__" title="object.__exit__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__exit__()</span></code></a> 方法添加到回调栈。</p>
<p>由于 <code class="docutils literal notranslate"><span class="pre">__enter__</span></code> <em>没有</em> 被发起调用，此方法可以被用来通过一个上下文管理器自己的 <a class="reference internal" href="../reference/datamodel.html#object.__exit__" title="object.__exit__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__exit__()</span></code></a> 覆盖 <a class="reference internal" href="../reference/datamodel.html#object.__enter__" title="object.__enter__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__enter__()</span></code></a> 的部分实现。</p>
<p>如果传递了一个不是上下文管理器的对象，此方法将假定它是一个回调 具有与上下文管理器的 <a class="reference internal" href="../reference/datamodel.html#object.__exit__" title="object.__exit__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__exit__()</span></code></a> 方法相同的签名的回调并会直接将其添加到回调栈中。</p>
<p>通过返回真值，这些回调可以通过与上下文管理器 <a class="reference internal" href="../reference/datamodel.html#object.__exit__" title="object.__exit__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__exit__()</span></code></a> 方法相同的方式屏蔽异常。</p>
<p>传入的对象将被该函数返回，允许此方法作为函数装饰器使用。</p>
</dd></dl>
<dl class="method">
<dt id="contextlib.ExitStack.callback">
<code class="sig-name descname">callback</code><span class="sig-paren">(</span><em class="sig-param">callback</em>, <em class="sig-param">*args</em>, <em class="sig-param">**kwds</em><span class="sig-paren">)</span><a class="headerlink" href="#contextlib.ExitStack.callback" title="永久链接至目标"></a></dt>
<dd><p>接受一个任意的回调函数和参数并将其添加到回调栈。</p>
<p>与其他方法不同，通过此方式添加的回调无法屏蔽异常（因为异常的细节不会被传递给它们）。</p>
<p>传入的回调将被该函数返回，允许此方法作为函数装饰器使用。</p>
</dd></dl>
<dl class="method">
<dt id="contextlib.ExitStack.pop_all">
<code class="sig-name descname">pop_all</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#contextlib.ExitStack.pop_all" title="永久链接至目标"></a></dt>
<dd><p>将回调栈传输到一个新的 <a class="reference internal" href="#contextlib.ExitStack" title="contextlib.ExitStack"><code class="xref py py-class docutils literal notranslate"><span class="pre">ExitStack</span></code></a> 实例并返回它。 此操作不会发起调用任何回调 —— 作为替代，现在当新栈被关闭时它们将（显式地或是在一条 <a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a> 语句结束时隐式地）被发起调用。</p>
<p>例如，一组文件可以像下面这样以“一个都不能少”的操作方式被打开:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="n">ExitStack</span><span class="p">()</span> <span class="k">as</span> <span class="n">stack</span><span class="p">:</span>
<span class="n">files</span> <span class="o">=</span> <span class="p">[</span><span class="n">stack</span><span class="o">.</span><span class="n">enter_context</span><span class="p">(</span><span class="nb">open</span><span class="p">(</span><span class="n">fname</span><span class="p">))</span> <span class="k">for</span> <span class="n">fname</span> <span class="ow">in</span> <span class="n">filenames</span><span class="p">]</span>
<span class="c1"># Hold onto the close method, but don&#39;t call it yet.</span>
<span class="n">close_files</span> <span class="o">=</span> <span class="n">stack</span><span class="o">.</span><span class="n">pop_all</span><span class="p">()</span><span class="o">.</span><span class="n">close</span>
<span class="c1"># If opening any file fails, all previously opened files will be</span>
<span class="c1"># closed automatically. If all files are opened successfully,</span>
<span class="c1"># they will remain open even after the with statement ends.</span>
<span class="c1"># close_files() can then be invoked explicitly to close them all.</span>
</pre></div>
</div>
</dd></dl>
<dl class="method">
<dt id="contextlib.ExitStack.close">
<code class="sig-name descname">close</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#contextlib.ExitStack.close" title="永久链接至目标"></a></dt>
<dd><p>立即展开回调栈，按注册时的相反顺序发起调用其中的回调。 对于任何已注册的上下文管理器和退出回调，传入的参数将表明没有发生异常。</p>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="contextlib.AsyncExitStack">
<em class="property">class </em><code class="sig-prename descclassname">contextlib.</code><code class="sig-name descname">AsyncExitStack</code><a class="headerlink" href="#contextlib.AsyncExitStack" title="永久链接至目标"></a></dt>
<dd><p>一个 <a class="reference internal" href="../reference/datamodel.html#async-context-managers"><span class="std std-ref">异步上下文管理器</span></a>，类似于 <a class="reference internal" href="#contextlib.ExitStack" title="contextlib.ExitStack"><code class="xref py py-class docutils literal notranslate"><span class="pre">ExitStack</span></code></a>，它支持组合同步和异步上下文管理器，并拥有针对清理逻辑的协程。</p>
<p><code class="xref py py-meth docutils literal notranslate"><span class="pre">close()</span></code> 方法没有被实现，使用 <a class="reference internal" href="#contextlib.AsyncExitStack.aclose" title="contextlib.AsyncExitStack.aclose"><code class="xref py py-meth docutils literal notranslate"><span class="pre">aclose()</span></code></a> 替代。</p>
<dl class="method">
<dt id="contextlib.AsyncExitStack.enter_async_context">
<code class="sig-name descname">enter_async_context</code><span class="sig-paren">(</span><em class="sig-param">cm</em><span class="sig-paren">)</span><a class="headerlink" href="#contextlib.AsyncExitStack.enter_async_context" title="永久链接至目标"></a></dt>
<dd><p>与 <code class="xref py py-meth docutils literal notranslate"><span class="pre">enter_context()</span></code> 相近，但是需要一个异步上下文管理器。</p>
</dd></dl>
<dl class="method">
<dt id="contextlib.AsyncExitStack.push_async_exit">
<code class="sig-name descname">push_async_exit</code><span class="sig-paren">(</span><em class="sig-param">exit</em><span class="sig-paren">)</span><a class="headerlink" href="#contextlib.AsyncExitStack.push_async_exit" title="永久链接至目标"></a></dt>
<dd><p>与 <code class="xref py py-meth docutils literal notranslate"><span class="pre">push()</span></code> 相近，但是需要一个异步上下文管理器或协程函数。</p>
</dd></dl>
<dl class="method">
<dt id="contextlib.AsyncExitStack.push_async_callback">
<code class="sig-name descname">push_async_callback</code><span class="sig-paren">(</span><em class="sig-param">callback</em>, <em class="sig-param">*args</em>, <em class="sig-param">**kwds</em><span class="sig-paren">)</span><a class="headerlink" href="#contextlib.AsyncExitStack.push_async_callback" title="永久链接至目标"></a></dt>
<dd><p>与 <code class="xref py py-meth docutils literal notranslate"><span class="pre">callback()</span></code> 相近，但是需要一个协程函数。</p>
</dd></dl>
<dl class="method">
<dt id="contextlib.AsyncExitStack.aclose">
<code class="sig-name descname">aclose</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#contextlib.AsyncExitStack.aclose" title="永久链接至目标"></a></dt>
<dd><p>和 <code class="xref py py-meth docutils literal notranslate"><span class="pre">close()</span></code> 相近，但是它正确处理了可等待对象。</p>
</dd></dl>
<p>从 <a class="reference internal" href="#contextlib.asynccontextmanager" title="contextlib.asynccontextmanager"><code class="xref py py-func docutils literal notranslate"><span class="pre">asynccontextmanager()</span></code></a> 的例子继续：</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">async</span> <span class="k">with</span> <span class="n">AsyncExitStack</span><span class="p">()</span> <span class="k">as</span> <span class="n">stack</span><span class="p">:</span>
<span class="n">connections</span> <span class="o">=</span> <span class="p">[</span><span class="k">await</span> <span class="n">stack</span><span class="o">.</span><span class="n">enter_async_context</span><span class="p">(</span><span class="n">get_connection</span><span class="p">())</span>
<span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">5</span><span class="p">)]</span>
<span class="c1"># All opened connections will automatically be released at the end of</span>
<span class="c1"># the async with statement, even if attempts to open a connection</span>
<span class="c1"># later in the list raise an exception.</span>
</pre></div>
</div>
<div class="versionadded">
<p><span class="versionmodified added">3.7 新版功能.</span></p>
</div>
</dd></dl>
</section>
<section id="examples-and-recipes">
<h2>例子和配方<a class="headerlink" href="#examples-and-recipes" title="永久链接至标题"></a></h2>
<p>本节描述了一些用于有效利用 <a class="reference internal" href="#module-contextlib" title="contextlib: Utilities for with-statement contexts."><code class="xref py py-mod docutils literal notranslate"><span class="pre">contextlib</span></code></a> 所提供的工具的示例和步骤。</p>
<section id="supporting-a-variable-number-of-context-managers">
<h3>支持可变数量的上下文管理器<a class="headerlink" href="#supporting-a-variable-number-of-context-managers" title="永久链接至标题"></a></h3>
<p><a class="reference internal" href="#contextlib.ExitStack" title="contextlib.ExitStack"><code class="xref py py-class docutils literal notranslate"><span class="pre">ExitStack</span></code></a> 的主要应用场景已在该类的文档中给出：在单个 <a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a> 语句中支持可变数量的上下文管理器和其他清理操作。 这个可变性可以来自通过用户输入驱动所需的上下文管理器数量（例如打开用户所指定的文件集），或者来自将某些上下文管理器作为可选项。</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="n">ExitStack</span><span class="p">()</span> <span class="k">as</span> <span class="n">stack</span><span class="p">:</span>
<span class="k">for</span> <span class="n">resource</span> <span class="ow">in</span> <span class="n">resources</span><span class="p">:</span>
<span class="n">stack</span><span class="o">.</span><span class="n">enter_context</span><span class="p">(</span><span class="n">resource</span><span class="p">)</span>
<span class="k">if</span> <span class="n">need_special_resource</span><span class="p">():</span>
<span class="n">special</span> <span class="o">=</span> <span class="n">acquire_special_resource</span><span class="p">()</span>
<span class="n">stack</span><span class="o">.</span><span class="n">callback</span><span class="p">(</span><span class="n">release_special_resource</span><span class="p">,</span> <span class="n">special</span><span class="p">)</span>
<span class="c1"># Perform operations that use the acquired resources</span>
</pre></div>
</div>
<p>如上所示，<a class="reference internal" href="#contextlib.ExitStack" title="contextlib.ExitStack"><code class="xref py py-class docutils literal notranslate"><span class="pre">ExitStack</span></code></a> 还让使用 <a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a> 语句来管理任意非原生支持上下文管理器协议的资源变得相当容易。</p>
</section>
<section id="catching-exceptions-from-enter-methods">
<h3>捕获 <code class="docutils literal notranslate"><span class="pre">__enter__</span></code> 方法产生的异常<a class="headerlink" href="#catching-exceptions-from-enter-methods" title="永久链接至标题"></a></h3>
<p>有时人们会想要从 <code class="docutils literal notranslate"><span class="pre">__enter__</span></code> 方法的实现中捕获异常，而 <em>不会</em> 无意中捕获来自 <a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a> 语句体或上下文管理器的 <code class="docutils literal notranslate"><span class="pre">__exit__</span></code> 方法的异常。 通过使用 <a class="reference internal" href="#contextlib.ExitStack" title="contextlib.ExitStack"><code class="xref py py-class docutils literal notranslate"><span class="pre">ExitStack</span></code></a> 可以将上下文管理协议中的步骤稍微分开以允许这样做:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">stack</span> <span class="o">=</span> <span class="n">ExitStack</span><span class="p">()</span>
<span class="k">try</span><span class="p">:</span>
<span class="n">x</span> <span class="o">=</span> <span class="n">stack</span><span class="o">.</span><span class="n">enter_context</span><span class="p">(</span><span class="n">cm</span><span class="p">)</span>
<span class="k">except</span> <span class="ne">Exception</span><span class="p">:</span>
<span class="c1"># handle __enter__ exception</span>
<span class="k">else</span><span class="p">:</span>
<span class="k">with</span> <span class="n">stack</span><span class="p">:</span>
<span class="c1"># Handle normal case</span>
</pre></div>
</div>
<p>实际上需要这样做很可能表明下层的 API 应该提供一个直接的资源管理接口以便与 <a class="reference internal" href="../reference/compound_stmts.html#try"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">try</span></code></a>/<a class="reference internal" href="../reference/compound_stmts.html#except"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">except</span></code></a>/<a class="reference internal" href="../reference/compound_stmts.html#finally"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">finally</span></code></a> 语句配合使用，但并不是所有的 API 在这方面都设计得很好。 当上下文管理器是所提供的唯一资源管理 API 时，则 <a class="reference internal" href="#contextlib.ExitStack" title="contextlib.ExitStack"><code class="xref py py-class docutils literal notranslate"><span class="pre">ExitStack</span></code></a> 可以让处理各种无法在 <a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a> 语句中直接处理的情况变得更为容易。</p>
</section>
<section id="cleaning-up-in-an-enter-implementation">
<h3>在一个 <code class="docutils literal notranslate"><span class="pre">__enter__</span></code> 方法的实现中进行清理<a class="headerlink" href="#cleaning-up-in-an-enter-implementation" title="永久链接至标题"></a></h3>
<p>正如 <a class="reference internal" href="#contextlib.ExitStack.push" title="contextlib.ExitStack.push"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ExitStack.push()</span></code></a> 的文档中所指出，如果在 <a class="reference internal" href="../reference/datamodel.html#object.__enter__" title="object.__enter__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__enter__()</span></code></a> 实现中的后续步骤失败则此方法在清理已分配的资源时将很有用处。</p>
<p>下面是为一个上下文管理器做这件事的例子，该上下文管理器可接受资源获取和释放函数，以及可选的验证函数，并将它们映射到上下文管理协议:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">contextlib</span> <span class="kn">import</span> <span class="n">contextmanager</span><span class="p">,</span> <span class="n">AbstractContextManager</span><span class="p">,</span> <span class="n">ExitStack</span>
<span class="k">class</span> <span class="nc">ResourceManager</span><span class="p">(</span><span class="n">AbstractContextManager</span><span class="p">):</span>
<span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">acquire_resource</span><span class="p">,</span> <span class="n">release_resource</span><span class="p">,</span> <span class="n">check_resource_ok</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
<span class="bp">self</span><span class="o">.</span><span class="n">acquire_resource</span> <span class="o">=</span> <span class="n">acquire_resource</span>
<span class="bp">self</span><span class="o">.</span><span class="n">release_resource</span> <span class="o">=</span> <span class="n">release_resource</span>
<span class="k">if</span> <span class="n">check_resource_ok</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
<span class="k">def</span> <span class="nf">check_resource_ok</span><span class="p">(</span><span class="n">resource</span><span class="p">):</span>
<span class="k">return</span> <span class="kc">True</span>
<span class="bp">self</span><span class="o">.</span><span class="n">check_resource_ok</span> <span class="o">=</span> <span class="n">check_resource_ok</span>
<span class="nd">@contextmanager</span>
<span class="k">def</span> <span class="nf">_cleanup_on_error</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="k">with</span> <span class="n">ExitStack</span><span class="p">()</span> <span class="k">as</span> <span class="n">stack</span><span class="p">:</span>
<span class="n">stack</span><span class="o">.</span><span class="n">push</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span>
<span class="k">yield</span>
<span class="c1"># The validation check passed and didn&#39;t raise an exception</span>
<span class="c1"># Accordingly, we want to keep the resource, and pass it</span>
<span class="c1"># back to our caller</span>
<span class="n">stack</span><span class="o">.</span><span class="n">pop_all</span><span class="p">()</span>
<span class="k">def</span> <span class="fm">__enter__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="n">resource</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">acquire_resource</span><span class="p">()</span>
<span class="k">with</span> <span class="bp">self</span><span class="o">.</span><span class="n">_cleanup_on_error</span><span class="p">():</span>
<span class="k">if</span> <span class="ow">not</span> <span class="bp">self</span><span class="o">.</span><span class="n">check_resource_ok</span><span class="p">(</span><span class="n">resource</span><span class="p">):</span>
<span class="n">msg</span> <span class="o">=</span> <span class="s2">&quot;Failed validation for </span><span class="si">{!r}</span><span class="s2">&quot;</span>
<span class="k">raise</span> <span class="ne">RuntimeError</span><span class="p">(</span><span class="n">msg</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">resource</span><span class="p">))</span>
<span class="k">return</span> <span class="n">resource</span>
<span class="k">def</span> <span class="fm">__exit__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="o">*</span><span class="n">exc_details</span><span class="p">):</span>
<span class="c1"># We don&#39;t need to duplicate any of our resource release logic</span>
<span class="bp">self</span><span class="o">.</span><span class="n">release_resource</span><span class="p">()</span>
</pre></div>
</div>
</section>
<section id="replacing-any-use-of-try-finally-and-flag-variables">
<h3>替换任何对 <code class="docutils literal notranslate"><span class="pre">try-finally</span></code> 和旗标变量的使用<a class="headerlink" href="#replacing-any-use-of-try-finally-and-flag-variables" title="永久链接至标题"></a></h3>
<p>一种你有时将看到的模式是 <code class="docutils literal notranslate"><span class="pre">try-finally</span></code> 语句附带一个变量来指明 <code class="docutils literal notranslate"><span class="pre">finally</span></code> 子句体是否要被执行。 在其最简单的形式中（它无法仅仅通过改用一条 <code class="docutils literal notranslate"><span class="pre">except</span></code> 子句来预先处理），看起来会是这样:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">cleanup_needed</span> <span class="o">=</span> <span class="kc">True</span>
<span class="k">try</span><span class="p">:</span>
<span class="n">result</span> <span class="o">=</span> <span class="n">perform_operation</span><span class="p">()</span>
<span class="k">if</span> <span class="n">result</span><span class="p">:</span>
<span class="n">cleanup_needed</span> <span class="o">=</span> <span class="kc">False</span>
<span class="k">finally</span><span class="p">:</span>
<span class="k">if</span> <span class="n">cleanup_needed</span><span class="p">:</span>
<span class="n">cleanup_resources</span><span class="p">()</span>
</pre></div>
</div>
<p>就如任何基于 <code class="docutils literal notranslate"><span class="pre">try</span></code> 语句的代码一样，这可能会导致开发和审查方面的问题，因为设置代码和清理代码最终可能会被任意长的代码部分所分隔。</p>
<p><a class="reference internal" href="#contextlib.ExitStack" title="contextlib.ExitStack"><code class="xref py py-class docutils literal notranslate"><span class="pre">ExitStack</span></code></a> 将允许选择在一条 <code class="docutils literal notranslate"><span class="pre">with</span></code> 语句末尾注册一个用于执行的回调的替代方式，等以后再决定是否跳过该回调的执行:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">contextlib</span> <span class="kn">import</span> <span class="n">ExitStack</span>
<span class="k">with</span> <span class="n">ExitStack</span><span class="p">()</span> <span class="k">as</span> <span class="n">stack</span><span class="p">:</span>
<span class="n">stack</span><span class="o">.</span><span class="n">callback</span><span class="p">(</span><span class="n">cleanup_resources</span><span class="p">)</span>
<span class="n">result</span> <span class="o">=</span> <span class="n">perform_operation</span><span class="p">()</span>
<span class="k">if</span> <span class="n">result</span><span class="p">:</span>
<span class="n">stack</span><span class="o">.</span><span class="n">pop_all</span><span class="p">()</span>
</pre></div>
</div>
<p>这允许在事先显式地指明预期的清理行为，而不需要一个单独的旗标变量。</p>
<p>如果某个应用程序大量使用此模式，则可以通过使用一个较小的辅助类来进一步地简化它:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">contextlib</span> <span class="kn">import</span> <span class="n">ExitStack</span>
<span class="k">class</span> <span class="nc">Callback</span><span class="p">(</span><span class="n">ExitStack</span><span class="p">):</span>
<span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">callback</span><span class="p">,</span> <span class="o">/</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">kwds</span><span class="p">):</span>
<span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__init__</span><span class="p">()</span>
<span class="bp">self</span><span class="o">.</span><span class="n">callback</span><span class="p">(</span><span class="n">callback</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">kwds</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">cancel</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="bp">self</span><span class="o">.</span><span class="n">pop_all</span><span class="p">()</span>
<span class="k">with</span> <span class="n">Callback</span><span class="p">(</span><span class="n">cleanup_resources</span><span class="p">)</span> <span class="k">as</span> <span class="n">cb</span><span class="p">:</span>
<span class="n">result</span> <span class="o">=</span> <span class="n">perform_operation</span><span class="p">()</span>
<span class="k">if</span> <span class="n">result</span><span class="p">:</span>
<span class="n">cb</span><span class="o">.</span><span class="n">cancel</span><span class="p">()</span>
</pre></div>
</div>
<p>如果资源清理操作尚未完善地捆绑到一个独立的函数中，则仍然可以使用 <a class="reference internal" href="#contextlib.ExitStack.callback" title="contextlib.ExitStack.callback"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ExitStack.callback()</span></code></a> 的装饰器形式来提前声明资源清理:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">contextlib</span> <span class="kn">import</span> <span class="n">ExitStack</span>
<span class="k">with</span> <span class="n">ExitStack</span><span class="p">()</span> <span class="k">as</span> <span class="n">stack</span><span class="p">:</span>
<span class="nd">@stack</span><span class="o">.</span><span class="n">callback</span>
<span class="k">def</span> <span class="nf">cleanup_resources</span><span class="p">():</span>
<span class="o">...</span>
<span class="n">result</span> <span class="o">=</span> <span class="n">perform_operation</span><span class="p">()</span>
<span class="k">if</span> <span class="n">result</span><span class="p">:</span>
<span class="n">stack</span><span class="o">.</span><span class="n">pop_all</span><span class="p">()</span>
</pre></div>
</div>
<p>受装饰器协议工作方式的影响，以此方式声明的回调函数无法接受任何形参。 作为替代，任何要释放的资源必须作为闭包变量来访问。</p>
</section>
<section id="using-a-context-manager-as-a-function-decorator">
<h3>将上下文管理器作为函数装饰器使用<a class="headerlink" href="#using-a-context-manager-as-a-function-decorator" title="永久链接至标题"></a></h3>
<p><a class="reference internal" href="#contextlib.ContextDecorator" title="contextlib.ContextDecorator"><code class="xref py py-class docutils literal notranslate"><span class="pre">ContextDecorator</span></code></a> 类允许将上下文管理器作为函数装饰器使用，而不仅在 <code class="docutils literal notranslate"><span class="pre">with</span></code> 语句块中使用。</p>
<p>例如，有时将函数或语句组包装在一个可以跟踪进入和退出时间的记录器中是很有用的。 与其为任务同时编写函数装饰器和上下文管理器，不如继承 <a class="reference internal" href="#contextlib.ContextDecorator" title="contextlib.ContextDecorator"><code class="xref py py-class docutils literal notranslate"><span class="pre">ContextDecorator</span></code></a> 在一个定义中同时提供这两种能力:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">contextlib</span> <span class="kn">import</span> <span class="n">ContextDecorator</span>
<span class="kn">import</span> <span class="nn">logging</span>
<span class="n">logging</span><span class="o">.</span><span class="n">basicConfig</span><span class="p">(</span><span class="n">level</span><span class="o">=</span><span class="n">logging</span><span class="o">.</span><span class="n">INFO</span><span class="p">)</span>
<span class="k">class</span> <span class="nc">track_entry_and_exit</span><span class="p">(</span><span class="n">ContextDecorator</span><span class="p">):</span>
<span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">):</span>
<span class="bp">self</span><span class="o">.</span><span class="n">name</span> <span class="o">=</span> <span class="n">name</span>
<span class="k">def</span> <span class="fm">__enter__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="n">logging</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">&#39;Entering: </span><span class="si">%s</span><span class="s1">&#39;</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">name</span><span class="p">)</span>
<span class="k">def</span> <span class="fm">__exit__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">exc_type</span><span class="p">,</span> <span class="n">exc</span><span class="p">,</span> <span class="n">exc_tb</span><span class="p">):</span>
<span class="n">logging</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">&#39;Exiting: </span><span class="si">%s</span><span class="s1">&#39;</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">name</span><span class="p">)</span>
</pre></div>
</div>
<p>这个类的实例既可以被用作上下文管理器：</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="n">track_entry_and_exit</span><span class="p">(</span><span class="s1">&#39;widget loader&#39;</span><span class="p">):</span>
<span class="nb">print</span><span class="p">(</span><span class="s1">&#39;Some time consuming activity goes here&#39;</span><span class="p">)</span>
<span class="n">load_widget</span><span class="p">()</span>
</pre></div>
</div>
<p>也可以被用作函数装饰器：</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nd">@track_entry_and_exit</span><span class="p">(</span><span class="s1">&#39;widget loader&#39;</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">activity</span><span class="p">():</span>
<span class="nb">print</span><span class="p">(</span><span class="s1">&#39;Some time consuming activity goes here&#39;</span><span class="p">)</span>
<span class="n">load_widget</span><span class="p">()</span>
</pre></div>
</div>
<p>使用上下文管理器作为函数装饰器时，有一个额外限制：没有办法得到 <a class="reference internal" href="../reference/datamodel.html#object.__enter__" title="object.__enter__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__enter__()</span></code></a> 的返回值。如果需要返回值，你仍然需要显式使用 <code class="docutils literal notranslate"><span class="pre">with</span></code> 语句。</p>
<div class="admonition seealso">
<p class="admonition-title">参见</p>
<dl class="simple">
<dt><span class="target" id="index-2"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0343"><strong>PEP 343</strong></a> - &quot;with&quot; 语句</dt><dd><p>Python <a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a> 语句的规范描述、背景和示例。</p>
</dd>
</dl>
</div>
</section>
</section>
<section id="single-use-reusable-and-reentrant-context-managers">
<span id="single-use-reusable-and-reentrant-cms"></span><h2>单独使用，可重用并可重进入的上下文管理器<a class="headerlink" href="#single-use-reusable-and-reentrant-context-managers" title="永久链接至标题"></a></h2>
<p>大多数上下文管理器的编写方式意味着它们只能在一个 <a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a> 语句中被有效使用一次。 这些一次性使用的上下文管理器必须在每次被使用时重新创建 —— 试图第二次使用它们将会触发异常或是不能正确工作。</p>
<p>这个常见的限制意味着通常来说都建议在 <a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a> 语句开头上下文管理器被使用的位置直接创建它们（如下面所有的使用示例所显示的）。</p>
<p>文件是一个高效的单独使用上下文管理器的例子，因为第一个 <a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a> 语句将关闭文件，防止任何后续的使用该文件对象的 IO 操作。</p>
<p>使用 <a class="reference internal" href="#contextlib.contextmanager" title="contextlib.contextmanager"><code class="xref py py-func docutils literal notranslate"><span class="pre">contextmanager()</span></code></a> 创建的上下文管理器也是单次使用的上下文管理器，并会在试图第二次使用它们时报告下层生成器无法执行产生操作:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">contextlib</span> <span class="kn">import</span> <span class="n">contextmanager</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nd">@contextmanager</span>
<span class="gp">... </span><span class="k">def</span> <span class="nf">singleuse</span><span class="p">():</span>
<span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Before&quot;</span><span class="p">)</span>
<span class="gp">... </span> <span class="k">yield</span>
<span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;After&quot;</span><span class="p">)</span>
<span class="gp">...</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">cm</span> <span class="o">=</span> <span class="n">singleuse</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">with</span> <span class="n">cm</span><span class="p">:</span>
<span class="gp">... </span> <span class="k">pass</span>
<span class="gp">...</span>
<span class="go">Before</span>
<span class="go">After</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">with</span> <span class="n">cm</span><span class="p">:</span>
<span class="gp">... </span> <span class="k">pass</span>
<span class="gp">...</span>
<span class="gt">Traceback (most recent call last):</span>
<span class="w"> </span><span class="o">...</span>
<span class="gr">RuntimeError</span>: <span class="n">generator didn&#39;t yield</span>
</pre></div>
</div>
<section id="reentrant-context-managers">
<span id="reentrant-cms"></span><h3>重进入上下文管理器<a class="headerlink" href="#reentrant-context-managers" title="永久链接至标题"></a></h3>
<p>更复杂的上下文管理器可以“重进入”。 这些上下文管理器不但可以被用于多个 <a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a> 语句中，还可以被用于已经在使用同一个上下文管理器的 <code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code> 语句 <em>内部</em>。</p>
<p><a class="reference internal" href="threading.html#threading.RLock" title="threading.RLock"><code class="xref py py-class docutils literal notranslate"><span class="pre">threading.RLock</span></code></a> 是一个可重入上下管理器的例子，<a class="reference internal" href="#contextlib.suppress" title="contextlib.suppress"><code class="xref py py-func docutils literal notranslate"><span class="pre">suppress()</span></code></a> 和 <a class="reference internal" href="#contextlib.redirect_stdout" title="contextlib.redirect_stdout"><code class="xref py py-func docutils literal notranslate"><span class="pre">redirect_stdout()</span></code></a> 也是如此。 下面是一个非常简单的可重入使用的示例:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">contextlib</span> <span class="kn">import</span> <span class="n">redirect_stdout</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">io</span> <span class="kn">import</span> <span class="n">StringIO</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">stream</span> <span class="o">=</span> <span class="n">StringIO</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">write_to_stream</span> <span class="o">=</span> <span class="n">redirect_stdout</span><span class="p">(</span><span class="n">stream</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">with</span> <span class="n">write_to_stream</span><span class="p">:</span>
<span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;This is written to the stream rather than stdout&quot;</span><span class="p">)</span>
<span class="gp">... </span> <span class="k">with</span> <span class="n">write_to_stream</span><span class="p">:</span>
<span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;This is also written to the stream&quot;</span><span class="p">)</span>
<span class="gp">...</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="s2">&quot;This is written directly to stdout&quot;</span><span class="p">)</span>
<span class="go">This is written directly to stdout</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">stream</span><span class="o">.</span><span class="n">getvalue</span><span class="p">())</span>
<span class="go">This is written to the stream rather than stdout</span>
<span class="go">This is also written to the stream</span>
</pre></div>
</div>
<p>现实世界的可重入例子更可能涉及到多个函数的相互调用因此会比这个例子要复杂得多。</p>
<p>还要注意可重入与线程安全 <em>不是</em> 一回事。 举例来说，<a class="reference internal" href="#contextlib.redirect_stdout" title="contextlib.redirect_stdout"><code class="xref py py-func docutils literal notranslate"><span class="pre">redirect_stdout()</span></code></a> 肯定不是线程安全的，因为它会通过将 <a class="reference internal" href="sys.html#sys.stdout" title="sys.stdout"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.stdout</span></code></a> 绑定到一个不同的流对系统状态做了全局性的修改。</p>
</section>
<section id="reusable-context-managers">
<span id="reusable-cms"></span><h3>可重用的上下文管理器<a class="headerlink" href="#reusable-context-managers" title="永久链接至标题"></a></h3>
<p>与单次使用和可重入上下文管理器都不同的还有“可重用”上下文管理器（或者，使用完全显式的表达应为“可重用，但不可重入”上下文管理器，因为可重入上下文管理器也会是可重用的）。 这些上下文管理器支持多次使用，但如果特定的上下文管理器实例已经在包含它的 with 语句中被使用过则将失败（或者不能正确工作）。</p>
<p><a class="reference internal" href="threading.html#threading.Lock" title="threading.Lock"><code class="xref py py-class docutils literal notranslate"><span class="pre">threading.Lock</span></code></a> 是一个可重用，但是不可重入的上下文管理器的例子（对于可重入锁，则有必要使用 <a class="reference internal" href="threading.html#threading.RLock" title="threading.RLock"><code class="xref py py-class docutils literal notranslate"><span class="pre">threading.RLock</span></code></a> 来代替）。</p>
<p>另一个可重用，但不可重入的上下文管理器的例子是 <a class="reference internal" href="#contextlib.ExitStack" title="contextlib.ExitStack"><code class="xref py py-class docutils literal notranslate"><span class="pre">ExitStack</span></code></a>，因为它在离开任何 with 语句时会发起调用 <em>所有</em> 当前已注册的回调，不论回调是在哪里添加的:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">contextlib</span> <span class="kn">import</span> <span class="n">ExitStack</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">stack</span> <span class="o">=</span> <span class="n">ExitStack</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">with</span> <span class="n">stack</span><span class="p">:</span>
<span class="gp">... </span> <span class="n">stack</span><span class="o">.</span><span class="n">callback</span><span class="p">(</span><span class="nb">print</span><span class="p">,</span> <span class="s2">&quot;Callback: from first context&quot;</span><span class="p">)</span>
<span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Leaving first context&quot;</span><span class="p">)</span>
<span class="gp">...</span>
<span class="go">Leaving first context</span>
<span class="go">Callback: from first context</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">with</span> <span class="n">stack</span><span class="p">:</span>
<span class="gp">... </span> <span class="n">stack</span><span class="o">.</span><span class="n">callback</span><span class="p">(</span><span class="nb">print</span><span class="p">,</span> <span class="s2">&quot;Callback: from second context&quot;</span><span class="p">)</span>
<span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Leaving second context&quot;</span><span class="p">)</span>
<span class="gp">...</span>
<span class="go">Leaving second context</span>
<span class="go">Callback: from second context</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">with</span> <span class="n">stack</span><span class="p">:</span>
<span class="gp">... </span> <span class="n">stack</span><span class="o">.</span><span class="n">callback</span><span class="p">(</span><span class="nb">print</span><span class="p">,</span> <span class="s2">&quot;Callback: from outer context&quot;</span><span class="p">)</span>
<span class="gp">... </span> <span class="k">with</span> <span class="n">stack</span><span class="p">:</span>
<span class="gp">... </span> <span class="n">stack</span><span class="o">.</span><span class="n">callback</span><span class="p">(</span><span class="nb">print</span><span class="p">,</span> <span class="s2">&quot;Callback: from inner context&quot;</span><span class="p">)</span>
<span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Leaving inner context&quot;</span><span class="p">)</span>
<span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Leaving outer context&quot;</span><span class="p">)</span>
<span class="gp">...</span>
<span class="go">Leaving inner context</span>
<span class="go">Callback: from inner context</span>
<span class="go">Callback: from outer context</span>
<span class="go">Leaving outer context</span>
</pre></div>
</div>
<p>正如这个例子的输出所显示的，在多个 with 语句中重用一个单独的栈对象可以正确工作，但调试嵌套它们就将导致栈在最内层的 with 语句结束时被清空，这不大可能是符合期望的行为。</p>
<p>使用单独的 <a class="reference internal" href="#contextlib.ExitStack" title="contextlib.ExitStack"><code class="xref py py-class docutils literal notranslate"><span class="pre">ExitStack</span></code></a> 实例而不是重复使用一个实例可以避免此问题:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">contextlib</span> <span class="kn">import</span> <span class="n">ExitStack</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">with</span> <span class="n">ExitStack</span><span class="p">()</span> <span class="k">as</span> <span class="n">outer_stack</span><span class="p">:</span>
<span class="gp">... </span> <span class="n">outer_stack</span><span class="o">.</span><span class="n">callback</span><span class="p">(</span><span class="nb">print</span><span class="p">,</span> <span class="s2">&quot;Callback: from outer context&quot;</span><span class="p">)</span>
<span class="gp">... </span> <span class="k">with</span> <span class="n">ExitStack</span><span class="p">()</span> <span class="k">as</span> <span class="n">inner_stack</span><span class="p">:</span>
<span class="gp">... </span> <span class="n">inner_stack</span><span class="o">.</span><span class="n">callback</span><span class="p">(</span><span class="nb">print</span><span class="p">,</span> <span class="s2">&quot;Callback: from inner context&quot;</span><span class="p">)</span>
<span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Leaving inner context&quot;</span><span class="p">)</span>
<span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Leaving outer context&quot;</span><span class="p">)</span>
<span class="gp">...</span>
<span class="go">Leaving inner context</span>
<span class="go">Callback: from inner context</span>
<span class="go">Leaving outer context</span>
<span class="go">Callback: from outer context</span>
</pre></div>
</div>
</section>
</section>
</section>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="../contents.html">目录</a></h3>
<ul>
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">contextlib</span></code> --- 为 <code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code>语句上下文提供的工具</a><ul>
<li><a class="reference internal" href="#utilities">工具</a></li>
<li><a class="reference internal" href="#examples-and-recipes">例子和配方</a><ul>
<li><a class="reference internal" href="#supporting-a-variable-number-of-context-managers">支持可变数量的上下文管理器</a></li>
<li><a class="reference internal" href="#catching-exceptions-from-enter-methods">捕获 <code class="docutils literal notranslate"><span class="pre">__enter__</span></code> 方法产生的异常</a></li>
<li><a class="reference internal" href="#cleaning-up-in-an-enter-implementation">在一个 <code class="docutils literal notranslate"><span class="pre">__enter__</span></code> 方法的实现中进行清理</a></li>
<li><a class="reference internal" href="#replacing-any-use-of-try-finally-and-flag-variables">替换任何对 <code class="docutils literal notranslate"><span class="pre">try-finally</span></code> 和旗标变量的使用</a></li>
<li><a class="reference internal" href="#using-a-context-manager-as-a-function-decorator">将上下文管理器作为函数装饰器使用</a></li>
</ul>
</li>
<li><a class="reference internal" href="#single-use-reusable-and-reentrant-context-managers">单独使用，可重用并可重进入的上下文管理器</a><ul>
<li><a class="reference internal" href="#reentrant-context-managers">重进入上下文管理器</a></li>
<li><a class="reference internal" href="#reusable-context-managers">可重用的上下文管理器</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>上一个主题</h4>
<p class="topless"><a href="dataclasses.html"
title="上一章"><code class="xref py py-mod docutils literal notranslate"><span class="pre">dataclasses</span></code> --- 数据类</a></p>
<h4>下一个主题</h4>
<p class="topless"><a href="abc.html"
title="下一章"><code class="xref py py-mod docutils literal notranslate"><span class="pre">abc</span></code> --- 抽象基类</a></p>
<div role="note" aria-label="source link">
<h3>本页</h3>
<ul class="this-page-menu">
<li><a href="../bugs.html">报告 Bug</a></li>
<li>
<a href="https://github.com/python/cpython/blob/3.8/Doc/library/contextlib.rst"
rel="nofollow">显示源代码
</a>
</li>
</ul>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>导航</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="总目录"
>索引</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python 模块索引"
>模块</a> |</li>
<li class="right" >
<a href="abc.html" title="abc --- 抽象基类"
>下一页</a> |</li>
<li class="right" >
<a href="dataclasses.html" title="dataclasses --- 数据类"
>上一页</a> |</li>
<li><img src="../_static/py.svg" alt="python logo" style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> &#187;</li>
<li class="switchers">
<div class="language_switcher_placeholder"></div>
<div class="version_switcher_placeholder"></div>
</li>
<li>
</li>
<li id="cpython-language-and-version">
<a href="../index.html">3.8.20 Documentation</a> &#187;
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python 标准库</a> &#187;</li>
<li class="nav-item nav-item-2"><a href="python.html" >Python 运行时服务</a> &#187;</li>
<li class="right">
<div class="inline-search" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="快速搜索" aria-label="快速搜索" type="text" name="q" />
<input type="submit" value="转向" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
|
</li>
</ul>
</div>
<div class="footer">
&copy; <a href="../copyright.html">版权所有</a> 2001-2024, Python Software Foundation.
<br />
This page is licensed under the Python Software Foundation License Version 2.
<br />
Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.
<br />
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
<br />
最后更新于 12月 09, 2024.
<a href="https://docs.python.org/3/bugs.html">Found a bug</a>?
<br />
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 2.4.4.
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink