1375 lines
126 KiB
HTML
1375 lines
126 KiB
HTML
|
||
<!DOCTYPE html>
|
||
<html lang="en">
|
||
<head>
|
||
<meta charset="utf-8">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
<meta name="color-scheme" content="light dark">
|
||
<title>PEP 346 – User Defined (”with”) Statements | peps.python.org</title>
|
||
<link rel="shortcut icon" href="../_static/py.png">
|
||
<link rel="canonical" href="https://peps.python.org/pep-0346/">
|
||
<link rel="stylesheet" href="../_static/style.css" type="text/css">
|
||
<link rel="stylesheet" href="../_static/mq.css" type="text/css">
|
||
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" media="(prefers-color-scheme: light)" id="pyg-light">
|
||
<link rel="stylesheet" href="../_static/pygments_dark.css" type="text/css" media="(prefers-color-scheme: dark)" id="pyg-dark">
|
||
<link rel="alternate" type="application/rss+xml" title="Latest PEPs" href="https://peps.python.org/peps.rss">
|
||
<meta property="og:title" content='PEP 346 – User Defined (”with”) Statements | peps.python.org'>
|
||
<meta property="og:description" content="This PEP is a combination of PEP 310’s “Reliable Acquisition/Release Pairs” with the “Anonymous Block Statements” of Guido’s PEP 340. This PEP aims to take the good parts of PEP 340, blend them with parts of PEP 310 and rearrange the lot into an elegan...">
|
||
<meta property="og:type" content="website">
|
||
<meta property="og:url" content="https://peps.python.org/pep-0346/">
|
||
<meta property="og:site_name" content="Python Enhancement Proposals (PEPs)">
|
||
<meta property="og:image" content="https://peps.python.org/_static/og-image.png">
|
||
<meta property="og:image:alt" content="Python PEPs">
|
||
<meta property="og:image:width" content="200">
|
||
<meta property="og:image:height" content="200">
|
||
<meta name="description" content="This PEP is a combination of PEP 310’s “Reliable Acquisition/Release Pairs” with the “Anonymous Block Statements” of Guido’s PEP 340. This PEP aims to take the good parts of PEP 340, blend them with parts of PEP 310 and rearrange the lot into an elegan...">
|
||
<meta name="theme-color" content="#3776ab">
|
||
</head>
|
||
<body>
|
||
|
||
<svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
|
||
<symbol id="svg-sun-half" viewBox="0 0 24 24" pointer-events="all">
|
||
<title>Following system colour scheme</title>
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none"
|
||
stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
|
||
<circle cx="12" cy="12" r="9"></circle>
|
||
<path d="M12 3v18m0-12l4.65-4.65M12 14.3l7.37-7.37M12 19.6l8.85-8.85"></path>
|
||
</svg>
|
||
</symbol>
|
||
<symbol id="svg-moon" viewBox="0 0 24 24" pointer-events="all">
|
||
<title>Selected dark colour scheme</title>
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none"
|
||
stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
|
||
<path stroke="none" d="M0 0h24v24H0z" fill="none"></path>
|
||
<path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z"></path>
|
||
</svg>
|
||
</symbol>
|
||
<symbol id="svg-sun" viewBox="0 0 24 24" pointer-events="all">
|
||
<title>Selected light colour scheme</title>
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none"
|
||
stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
|
||
<circle cx="12" cy="12" r="5"></circle>
|
||
<line x1="12" y1="1" x2="12" y2="3"></line>
|
||
<line x1="12" y1="21" x2="12" y2="23"></line>
|
||
<line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line>
|
||
<line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line>
|
||
<line x1="1" y1="12" x2="3" y2="12"></line>
|
||
<line x1="21" y1="12" x2="23" y2="12"></line>
|
||
<line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line>
|
||
<line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line>
|
||
</svg>
|
||
</symbol>
|
||
</svg>
|
||
<script>
|
||
|
||
document.documentElement.dataset.colour_scheme = localStorage.getItem("colour_scheme") || "auto"
|
||
</script>
|
||
<section id="pep-page-section">
|
||
<header>
|
||
<h1>Python Enhancement Proposals</h1>
|
||
<ul class="breadcrumbs">
|
||
<li><a href="https://www.python.org/" title="The Python Programming Language">Python</a> » </li>
|
||
<li><a href="../pep-0000/">PEP Index</a> » </li>
|
||
<li>PEP 346</li>
|
||
</ul>
|
||
<button id="colour-scheme-cycler" onClick="setColourScheme(nextColourScheme())">
|
||
<svg aria-hidden="true" class="colour-scheme-icon-when-auto"><use href="#svg-sun-half"></use></svg>
|
||
<svg aria-hidden="true" class="colour-scheme-icon-when-dark"><use href="#svg-moon"></use></svg>
|
||
<svg aria-hidden="true" class="colour-scheme-icon-when-light"><use href="#svg-sun"></use></svg>
|
||
<span class="visually-hidden">Toggle light / dark / auto colour theme</span>
|
||
</button>
|
||
</header>
|
||
<article>
|
||
<section id="pep-content">
|
||
<h1 class="page-title">PEP 346 – User Defined (”<code class="docutils literal notranslate"><span class="pre">with</span></code>”) Statements</h1>
|
||
<dl class="rfc2822 field-list simple">
|
||
<dt class="field-odd">Author<span class="colon">:</span></dt>
|
||
<dd class="field-odd">Alyssa Coghlan <ncoghlan at gmail.com></dd>
|
||
<dt class="field-even">Status<span class="colon">:</span></dt>
|
||
<dd class="field-even"><abbr title="Removed from consideration by sponsor or authors">Withdrawn</abbr></dd>
|
||
<dt class="field-odd">Type<span class="colon">:</span></dt>
|
||
<dd class="field-odd"><abbr title="Normative PEP with a new feature for Python, implementation change for CPython or interoperability standard for the ecosystem">Standards Track</abbr></dd>
|
||
<dt class="field-even">Created<span class="colon">:</span></dt>
|
||
<dd class="field-even">06-May-2005</dd>
|
||
<dt class="field-odd">Python-Version<span class="colon">:</span></dt>
|
||
<dd class="field-odd">2.5</dd>
|
||
<dt class="field-even">Post-History<span class="colon">:</span></dt>
|
||
<dd class="field-even"><p></p></dd>
|
||
</dl>
|
||
<hr class="docutils" />
|
||
<section id="contents">
|
||
<details><summary>Table of Contents</summary><ul class="simple">
|
||
<li><a class="reference internal" href="#abstract">Abstract</a></li>
|
||
<li><a class="reference internal" href="#author-s-note">Author’s Note</a></li>
|
||
<li><a class="reference internal" href="#introduction">Introduction</a></li>
|
||
<li><a class="reference internal" href="#relationship-with-other-peps">Relationship with other PEPs</a></li>
|
||
<li><a class="reference internal" href="#user-defined-statements">User defined statements</a><ul>
|
||
<li><a class="reference internal" href="#usage-syntax-for-user-defined-statements">Usage syntax for user defined statements</a></li>
|
||
<li><a class="reference internal" href="#semantics-for-user-defined-statements">Semantics for user defined statements</a></li>
|
||
<li><a class="reference internal" href="#statement-template-protocol-enter">Statement template protocol: <code class="docutils literal notranslate"><span class="pre">__enter__</span></code></a></li>
|
||
<li><a class="reference internal" href="#statement-template-protocol-exit">Statement template protocol: <code class="docutils literal notranslate"><span class="pre">__exit__</span></code></a></li>
|
||
<li><a class="reference internal" href="#factoring-out-arbitrary-exception-handling">Factoring out arbitrary exception handling</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#generators">Generators</a><ul>
|
||
<li><a class="reference internal" href="#default-value-for-yield">Default value for <code class="docutils literal notranslate"><span class="pre">yield</span></code></a></li>
|
||
<li><a class="reference internal" href="#template-generator-decorator-statement-template">Template generator decorator: <code class="docutils literal notranslate"><span class="pre">statement_template</span></code></a></li>
|
||
<li><a class="reference internal" href="#template-generator-wrapper-enter-method">Template generator wrapper: <code class="docutils literal notranslate"><span class="pre">__enter__()</span></code> method</a></li>
|
||
<li><a class="reference internal" href="#template-generator-wrapper-exit-method">Template generator wrapper: <code class="docutils literal notranslate"><span class="pre">__exit__()</span></code> method</a></li>
|
||
<li><a class="reference internal" href="#injecting-exceptions-into-generators">Injecting exceptions into generators</a></li>
|
||
<li><a class="reference internal" href="#generator-finalisation">Generator finalisation</a></li>
|
||
<li><a class="reference internal" href="#generator-finalisation-terminateiteration-exception">Generator finalisation: <code class="docutils literal notranslate"><span class="pre">TerminateIteration</span></code> exception</a></li>
|
||
<li><a class="reference internal" href="#generator-finalisation-del-method">Generator finalisation: <code class="docutils literal notranslate"><span class="pre">__del__()</span></code> method</a></li>
|
||
<li><a class="reference internal" href="#deterministic-generator-finalisation">Deterministic generator finalisation</a></li>
|
||
<li><a class="reference internal" href="#generators-as-user-defined-statement-templates">Generators as user defined statement templates</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#examples">Examples</a></li>
|
||
<li><a class="reference internal" href="#open-issues">Open Issues</a></li>
|
||
<li><a class="reference internal" href="#rejected-options">Rejected Options</a><ul>
|
||
<li><a class="reference internal" href="#having-the-basic-construct-be-a-looping-construct">Having the basic construct be a looping construct</a></li>
|
||
<li><a class="reference internal" href="#allowing-statement-templates-to-suppress-exceptions">Allowing statement templates to suppress exceptions</a></li>
|
||
<li><a class="reference internal" href="#differentiating-between-non-exceptional-exits">Differentiating between non-exceptional exits</a></li>
|
||
<li><a class="reference internal" href="#not-injecting-raised-exceptions-into-generators">Not injecting raised exceptions into generators</a></li>
|
||
<li><a class="reference internal" href="#making-all-generators-statement-templates">Making all generators statement templates</a></li>
|
||
<li><a class="reference internal" href="#using-do-as-the-keyword">Using <code class="docutils literal notranslate"><span class="pre">do</span></code> as the keyword</a></li>
|
||
<li><a class="reference internal" href="#not-having-a-keyword">Not having a keyword</a></li>
|
||
<li><a class="reference internal" href="#enhancing-try-statements">Enhancing <code class="docutils literal notranslate"><span class="pre">try</span></code> statements</a></li>
|
||
<li><a class="reference internal" href="#having-the-template-protocol-directly-reflect-try-statements">Having the template protocol directly reflect <code class="docutils literal notranslate"><span class="pre">try</span></code> statements</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#iterator-finalisation-withdrawn">Iterator finalisation (WITHDRAWN)</a><ul>
|
||
<li><a class="reference internal" href="#iterator-protocol-addition-finish">Iterator protocol addition: <code class="docutils literal notranslate"><span class="pre">__finish__</span></code></a></li>
|
||
<li><a class="reference internal" href="#best-effort-finalisation">Best effort finalisation</a></li>
|
||
<li><a class="reference internal" href="#deterministic-finalisation">Deterministic finalisation</a></li>
|
||
<li><a class="reference internal" href="#for-loop-syntax"><code class="docutils literal notranslate"><span class="pre">for</span></code> loop syntax</a></li>
|
||
<li><a class="reference internal" href="#updated-for-loop-semantics">Updated <code class="docutils literal notranslate"><span class="pre">for</span></code> loop semantics</a></li>
|
||
<li><a class="reference internal" href="#generator-iterator-finalisation-finish-method">Generator iterator finalisation: <code class="docutils literal notranslate"><span class="pre">__finish__()</span></code> method</a></li>
|
||
<li><a class="reference internal" href="#partial-iteration-of-finishable-iterators">Partial iteration of finishable iterators</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#acknowledgements">Acknowledgements</a></li>
|
||
<li><a class="reference internal" href="#references">References</a></li>
|
||
<li><a class="reference internal" href="#copyright">Copyright</a></li>
|
||
</ul>
|
||
</details></section>
|
||
<section id="abstract">
|
||
<h2><a class="toc-backref" href="#abstract" role="doc-backlink">Abstract</a></h2>
|
||
<p>This PEP is a combination of <a class="pep reference internal" href="../pep-0310/" title="PEP 310 – Reliable Acquisition/Release Pairs">PEP 310</a>’s “Reliable Acquisition/Release
|
||
Pairs” with the “Anonymous Block Statements” of Guido’s <a class="pep reference internal" href="../pep-0340/" title="PEP 340 – Anonymous Block Statements">PEP 340</a>. This
|
||
PEP aims to take the good parts of <a class="pep reference internal" href="../pep-0340/" title="PEP 340 – Anonymous Block Statements">PEP 340</a>, blend them with parts of
|
||
<a class="pep reference internal" href="../pep-0310/" title="PEP 310 – Reliable Acquisition/Release Pairs">PEP 310</a> and rearrange the lot into an elegant whole. It borrows from
|
||
various other PEPs in order to paint a complete picture, and is
|
||
intended to stand on its own.</p>
|
||
</section>
|
||
<section id="author-s-note">
|
||
<h2><a class="toc-backref" href="#author-s-note" role="doc-backlink">Author’s Note</a></h2>
|
||
<p>During the discussion of <a class="pep reference internal" href="../pep-0340/" title="PEP 340 – Anonymous Block Statements">PEP 340</a>, I maintained drafts of this PEP as
|
||
PEP 3XX on my own website (since I didn’t have CVS access to update a
|
||
submitted PEP fast enough to track the activity on python-dev).</p>
|
||
<p>Since the first draft of this PEP, Guido wrote <a class="pep reference internal" href="../pep-0343/" title="PEP 343 – The “with” Statement">PEP 343</a> as a simplified
|
||
version of <a class="pep reference internal" href="../pep-0340/" title="PEP 340 – Anonymous Block Statements">PEP 340</a>. <a class="pep reference internal" href="../pep-0343/" title="PEP 343 – The “with” Statement">PEP 343</a> (at the time of writing) uses the exact
|
||
same semantics for the new statements as this PEP, but uses a slightly
|
||
different mechanism to allow generators to be used to write statement
|
||
templates. However, Guido has indicated that he intends to accept a
|
||
new PEP being written by Raymond Hettinger that will integrate <a class="pep reference internal" href="../pep-0288/" title="PEP 288 – Generators Attributes and Exceptions">PEP 288</a>
|
||
and <a class="pep reference internal" href="../pep-0325/" title="PEP 325 – Resource-Release Support for Generators">PEP 325</a>, and will permit a generator decorator like the one
|
||
described in this PEP to be used to write statement templates for PEP
|
||
343. The other difference was the choice of keyword (‘with’ versus
|
||
‘do’) and Guido has stated he will organise a vote on that in the
|
||
context of <a class="pep reference internal" href="../pep-0343/" title="PEP 343 – The “with” Statement">PEP 343</a>.</p>
|
||
<p>Accordingly, the version of this PEP submitted for archiving on
|
||
python.org is to be WITHDRAWN immediately after submission. <a class="pep reference internal" href="../pep-0343/" title="PEP 343 – The “with” Statement">PEP 343</a>
|
||
and the combined generator enhancement PEP will cover the important
|
||
ideas.</p>
|
||
</section>
|
||
<section id="introduction">
|
||
<h2><a class="toc-backref" href="#introduction" role="doc-backlink">Introduction</a></h2>
|
||
<p>This PEP proposes that Python’s ability to reliably manage resources
|
||
be enhanced by the introduction of a new <code class="docutils literal notranslate"><span class="pre">with</span></code> statement that
|
||
allows factoring out of arbitrary <code class="docutils literal notranslate"><span class="pre">try</span></code>/<code class="docutils literal notranslate"><span class="pre">finally</span></code> and some
|
||
<code class="docutils literal notranslate"><span class="pre">try</span></code>/<code class="docutils literal notranslate"><span class="pre">except</span></code>/<code class="docutils literal notranslate"><span class="pre">else</span></code> boilerplate. The new construct is called
|
||
a ‘user defined statement’, and the associated class definitions are
|
||
called ‘statement templates’.</p>
|
||
<p>The above is the main point of the PEP. However, if that was all it
|
||
said, then <a class="pep reference internal" href="../pep-0310/" title="PEP 310 – Reliable Acquisition/Release Pairs">PEP 310</a> would be sufficient and this PEP would be
|
||
essentially redundant. Instead, this PEP recommends additional
|
||
enhancements that make it natural to write these statement templates
|
||
using appropriately decorated generators. A side effect of those
|
||
enhancements is that it becomes important to appropriately deal
|
||
with the management of resources inside generators.</p>
|
||
<p>This is quite similar to <a class="pep reference internal" href="../pep-0343/" title="PEP 343 – The “with” Statement">PEP 343</a>, but the exceptions that occur are
|
||
re-raised inside the generators frame, and the issue of generator
|
||
finalisation needs to be addressed as a result. The template
|
||
generator decorator suggested by this PEP also creates reusable
|
||
templates, rather than the single use templates of <a class="pep reference internal" href="../pep-0340/" title="PEP 340 – Anonymous Block Statements">PEP 340</a>.</p>
|
||
<p>In comparison to <a class="pep reference internal" href="../pep-0340/" title="PEP 340 – Anonymous Block Statements">PEP 340</a>, this PEP eliminates the ability to suppress
|
||
exceptions, and makes the user defined statement a non-looping
|
||
construct. The other main difference is the use of a decorator to
|
||
turn generators into statement templates, and the incorporation of
|
||
ideas for addressing iterator finalisation.</p>
|
||
<p>If all that seems like an ambitious operation… well, Guido was the
|
||
one to set the bar that high when he wrote <a class="pep reference internal" href="../pep-0340/" title="PEP 340 – Anonymous Block Statements">PEP 340</a> :)</p>
|
||
</section>
|
||
<section id="relationship-with-other-peps">
|
||
<h2><a class="toc-backref" href="#relationship-with-other-peps" role="doc-backlink">Relationship with other PEPs</a></h2>
|
||
<p>This PEP competes directly with <a class="pep reference internal" href="../pep-0310/" title="PEP 310 – Reliable Acquisition/Release Pairs">PEP 310</a>, <a class="pep reference internal" href="../pep-0340/" title="PEP 340 – Anonymous Block Statements">PEP 340</a> and <a class="pep reference internal" href="../pep-0343/" title="PEP 343 – The “with” Statement">PEP 343</a>,
|
||
as those PEPs all describe alternative mechanisms for handling
|
||
deterministic resource management.</p>
|
||
<p>It does not compete with <a class="pep reference internal" href="../pep-0342/" title="PEP 342 – Coroutines via Enhanced Generators">PEP 342</a> which splits off <a class="pep reference internal" href="../pep-0340/" title="PEP 340 – Anonymous Block Statements">PEP 340</a>’s
|
||
enhancements related to passing data into iterators. The associated
|
||
changes to the <code class="docutils literal notranslate"><span class="pre">for</span></code> loop semantics would be combined with the
|
||
iterator finalisation changes suggested in this PEP. User defined
|
||
statements would not be affected.</p>
|
||
<p>Neither does this PEP compete with the generator enhancements
|
||
described in <a class="pep reference internal" href="../pep-0288/" title="PEP 288 – Generators Attributes and Exceptions">PEP 288</a>. While this PEP proposes the ability to
|
||
inject exceptions into generator frames, it is an internal
|
||
implementation detail, and does not require making that ability
|
||
publicly available to Python code. <a class="pep reference internal" href="../pep-0288/" title="PEP 288 – Generators Attributes and Exceptions">PEP 288</a> is, in part, about
|
||
making that implementation detail easily accessible.</p>
|
||
<p>This PEP would, however, make the generator resource release support
|
||
described in <a class="pep reference internal" href="../pep-0325/" title="PEP 325 – Resource-Release Support for Generators">PEP 325</a> redundant - iterators which require
|
||
finalisation should provide an appropriate implementation of the
|
||
statement template protocol.</p>
|
||
</section>
|
||
<section id="user-defined-statements">
|
||
<h2><a class="toc-backref" href="#user-defined-statements" role="doc-backlink">User defined statements</a></h2>
|
||
<p>To steal the motivating example from <a class="pep reference internal" href="../pep-0310/" title="PEP 310 – Reliable Acquisition/Release Pairs">PEP 310</a>, correct handling of a
|
||
synchronisation lock currently looks like this:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">the_lock</span><span class="o">.</span><span class="n">acquire</span><span class="p">()</span>
|
||
<span class="k">try</span><span class="p">:</span>
|
||
<span class="c1"># Code here executes with the lock held</span>
|
||
<span class="k">finally</span><span class="p">:</span>
|
||
<span class="n">the_lock</span><span class="o">.</span><span class="n">release</span><span class="p">()</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Like <a class="pep reference internal" href="../pep-0310/" title="PEP 310 – Reliable Acquisition/Release Pairs">PEP 310</a>, this PEP proposes that such code be able to be written
|
||
as:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="n">the_lock</span><span class="p">:</span>
|
||
<span class="c1"># Code here executes with the lock held</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>These user defined statements are primarily designed to allow easy
|
||
factoring of <code class="docutils literal notranslate"><span class="pre">try</span></code> blocks that are not easily converted to
|
||
functions. This is most commonly the case when the exception handling
|
||
pattern is consistent, but the body of the <code class="docutils literal notranslate"><span class="pre">try</span></code> block changes.
|
||
With a user-defined statement, it is straightforward to factor out the
|
||
exception handling into a statement template, with the body of the
|
||
<code class="docutils literal notranslate"><span class="pre">try</span></code> clause provided inline in the user code.</p>
|
||
<p>The term ‘user defined statement’ reflects the fact that the meaning
|
||
of a <code class="docutils literal notranslate"><span class="pre">with</span></code> statement is governed primarily by the statement
|
||
template used, and programmers are free to create their own statement
|
||
templates, just as they are free to create their own iterators for use
|
||
in <code class="docutils literal notranslate"><span class="pre">for</span></code> loops.</p>
|
||
<section id="usage-syntax-for-user-defined-statements">
|
||
<h3><a class="toc-backref" href="#usage-syntax-for-user-defined-statements" role="doc-backlink">Usage syntax for user defined statements</a></h3>
|
||
<p>The proposed syntax is simple:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="n">EXPR1</span> <span class="p">[</span><span class="k">as</span> <span class="n">VAR1</span><span class="p">]:</span>
|
||
<span class="n">BLOCK1</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="semantics-for-user-defined-statements">
|
||
<h3><a class="toc-backref" href="#semantics-for-user-defined-statements" role="doc-backlink">Semantics for user defined statements</a></h3>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">the_stmt</span> <span class="o">=</span> <span class="n">EXPR1</span>
|
||
<span class="n">stmt_enter</span> <span class="o">=</span> <span class="nb">getattr</span><span class="p">(</span><span class="n">the_stmt</span><span class="p">,</span> <span class="s2">"__enter__"</span><span class="p">,</span> <span class="kc">None</span><span class="p">)</span>
|
||
<span class="n">stmt_exit</span> <span class="o">=</span> <span class="nb">getattr</span><span class="p">(</span><span class="n">the_stmt</span><span class="p">,</span> <span class="s2">"__exit__"</span><span class="p">,</span> <span class="kc">None</span><span class="p">)</span>
|
||
<span class="k">if</span> <span class="n">stmt_enter</span> <span class="ow">is</span> <span class="kc">None</span> <span class="ow">or</span> <span class="n">stmt_exit</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
|
||
<span class="k">raise</span> <span class="ne">TypeError</span><span class="p">(</span><span class="s2">"Statement template required"</span><span class="p">)</span>
|
||
|
||
<span class="n">VAR1</span> <span class="o">=</span> <span class="n">stmt_enter</span><span class="p">()</span> <span class="c1"># Omit 'VAR1 =' if no 'as' clause</span>
|
||
<span class="n">exc</span> <span class="o">=</span> <span class="p">(</span><span class="kc">None</span><span class="p">,</span> <span class="kc">None</span><span class="p">,</span> <span class="kc">None</span><span class="p">)</span>
|
||
<span class="k">try</span><span class="p">:</span>
|
||
<span class="k">try</span><span class="p">:</span>
|
||
<span class="n">BLOCK1</span>
|
||
<span class="k">except</span><span class="p">:</span>
|
||
<span class="n">exc</span> <span class="o">=</span> <span class="n">sys</span><span class="o">.</span><span class="n">exc_info</span><span class="p">()</span>
|
||
<span class="k">raise</span>
|
||
<span class="k">finally</span><span class="p">:</span>
|
||
<span class="n">stmt_exit</span><span class="p">(</span><span class="o">*</span><span class="n">exc</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Other than <code class="docutils literal notranslate"><span class="pre">VAR1</span></code>, none of the local variables shown above will be
|
||
visible to user code. Like the iteration variable in a <code class="docutils literal notranslate"><span class="pre">for</span></code> loop,
|
||
<code class="docutils literal notranslate"><span class="pre">VAR1</span></code> is visible in both <code class="docutils literal notranslate"><span class="pre">BLOCK1</span></code> and code following the user
|
||
defined statement.</p>
|
||
<p>Note that the statement template can only react to exceptions, it
|
||
cannot suppress them. See <a class="reference internal" href="#rejected-options">Rejected Options</a> for an explanation as
|
||
to why.</p>
|
||
</section>
|
||
<section id="statement-template-protocol-enter">
|
||
<h3><a class="toc-backref" href="#statement-template-protocol-enter" role="doc-backlink">Statement template protocol: <code class="docutils literal notranslate"><span class="pre">__enter__</span></code></a></h3>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">__enter__()</span></code> method takes no arguments, and if it raises an
|
||
exception, <code class="docutils literal notranslate"><span class="pre">BLOCK1</span></code> is never executed. If this happens, the
|
||
<code class="docutils literal notranslate"><span class="pre">__exit__()</span></code> method is not called. The value returned by this
|
||
method is assigned to VAR1 if the <code class="docutils literal notranslate"><span class="pre">as</span></code> clause is used. Object’s
|
||
with no other value to return should generally return <code class="docutils literal notranslate"><span class="pre">self</span></code> rather
|
||
than <code class="docutils literal notranslate"><span class="pre">None</span></code> to permit in-place creation in the <code class="docutils literal notranslate"><span class="pre">with</span></code> statement.</p>
|
||
<p>Statement templates should use this method to set up the conditions
|
||
that are to exist during execution of the statement (e.g. acquisition
|
||
of a synchronisation lock).</p>
|
||
<p>Statement templates which are not always usable (e.g. closed file
|
||
objects) should raise a <code class="docutils literal notranslate"><span class="pre">RuntimeError</span></code> if an attempt is made to call
|
||
<code class="docutils literal notranslate"><span class="pre">__enter__()</span></code> when the template is not in a valid state.</p>
|
||
</section>
|
||
<section id="statement-template-protocol-exit">
|
||
<h3><a class="toc-backref" href="#statement-template-protocol-exit" role="doc-backlink">Statement template protocol: <code class="docutils literal notranslate"><span class="pre">__exit__</span></code></a></h3>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">__exit__()</span></code> method accepts three arguments which correspond to
|
||
the three “arguments” to the <code class="docutils literal notranslate"><span class="pre">raise</span></code> statement: type, value, and
|
||
traceback. All arguments are always supplied, and will be set to
|
||
<code class="docutils literal notranslate"><span class="pre">None</span></code> if no exception occurred. This method will be called exactly
|
||
once by the <code class="docutils literal notranslate"><span class="pre">with</span></code> statement machinery if the <code class="docutils literal notranslate"><span class="pre">__enter__()</span></code> method
|
||
completes successfully.</p>
|
||
<p>Statement templates perform their exception handling in this method.
|
||
If the first argument is <code class="docutils literal notranslate"><span class="pre">None</span></code>, it indicates non-exceptional
|
||
completion of <code class="docutils literal notranslate"><span class="pre">BLOCK1</span></code> - execution either reached the end of block,
|
||
or early completion was forced using a <code class="docutils literal notranslate"><span class="pre">return</span></code>, <code class="docutils literal notranslate"><span class="pre">break</span></code> or
|
||
<code class="docutils literal notranslate"><span class="pre">continue</span></code> statement. Otherwise, the three arguments reflect the
|
||
exception that terminated <code class="docutils literal notranslate"><span class="pre">BLOCK1</span></code>.</p>
|
||
<p>Any exceptions raised by the <code class="docutils literal notranslate"><span class="pre">__exit__()</span></code> method are propagated to
|
||
the scope containing the <code class="docutils literal notranslate"><span class="pre">with</span></code> statement. If the user code in
|
||
<code class="docutils literal notranslate"><span class="pre">BLOCK1</span></code> also raised an exception, that exception would be lost, and
|
||
replaced by the one raised by the <code class="docutils literal notranslate"><span class="pre">__exit__()</span></code> method.</p>
|
||
</section>
|
||
<section id="factoring-out-arbitrary-exception-handling">
|
||
<h3><a class="toc-backref" href="#factoring-out-arbitrary-exception-handling" role="doc-backlink">Factoring out arbitrary exception handling</a></h3>
|
||
<p>Consider the following exception handling arrangement:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">SETUP_BLOCK</span>
|
||
<span class="k">try</span><span class="p">:</span>
|
||
<span class="k">try</span><span class="p">:</span>
|
||
<span class="n">TRY_BLOCK</span>
|
||
<span class="k">except</span> <span class="n">exc_type1</span><span class="p">,</span> <span class="n">exc</span><span class="p">:</span>
|
||
<span class="n">EXCEPT_BLOCK1</span>
|
||
<span class="k">except</span> <span class="n">exc_type2</span><span class="p">,</span> <span class="n">exc</span><span class="p">:</span>
|
||
<span class="n">EXCEPT_BLOCK2</span>
|
||
<span class="k">except</span><span class="p">:</span>
|
||
<span class="n">EXCEPT_BLOCK3</span>
|
||
<span class="k">else</span><span class="p">:</span>
|
||
<span class="n">ELSE_BLOCK</span>
|
||
<span class="k">finally</span><span class="p">:</span>
|
||
<span class="n">FINALLY_BLOCK</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>It can be roughly translated to a statement template as follows:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">my_template</span><span class="p">(</span><span class="nb">object</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="o">*</span><span class="n">args</span><span class="p">):</span>
|
||
<span class="c1"># Any required arguments (e.g. a file name)</span>
|
||
<span class="c1"># get stored in member variables</span>
|
||
<span class="c1"># The various BLOCK's will need updating to reflect</span>
|
||
<span class="c1"># that.</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">SETUP_BLOCK</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">value</span><span class="p">,</span> <span class="n">traceback</span><span class="p">):</span>
|
||
<span class="k">try</span><span class="p">:</span>
|
||
<span class="k">try</span><span class="p">:</span>
|
||
<span class="k">if</span> <span class="n">exc_type</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span>
|
||
<span class="k">raise</span> <span class="n">exc_type</span><span class="p">,</span> <span class="n">value</span><span class="p">,</span> <span class="n">traceback</span>
|
||
<span class="k">except</span> <span class="n">exc_type1</span><span class="p">,</span> <span class="n">exc</span><span class="p">:</span>
|
||
<span class="n">EXCEPT_BLOCK1</span>
|
||
<span class="k">except</span> <span class="n">exc_type2</span><span class="p">,</span> <span class="n">exc</span><span class="p">:</span>
|
||
<span class="n">EXCEPT_BLOCK2</span>
|
||
<span class="k">except</span><span class="p">:</span>
|
||
<span class="n">EXCEPT_BLOCK3</span>
|
||
<span class="k">else</span><span class="p">:</span>
|
||
<span class="n">ELSE_BLOCK</span>
|
||
<span class="k">finally</span><span class="p">:</span>
|
||
<span class="n">FINALLY_BLOCK</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Which can then be used as:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="n">my_template</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">):</span>
|
||
<span class="n">TRY_BLOCK</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>However, there are two important semantic differences between this
|
||
code and the original <code class="docutils literal notranslate"><span class="pre">try</span></code> statement.</p>
|
||
<p>Firstly, in the original <code class="docutils literal notranslate"><span class="pre">try</span></code> statement, if a <code class="docutils literal notranslate"><span class="pre">break</span></code>, <code class="docutils literal notranslate"><span class="pre">return</span></code>
|
||
or <code class="docutils literal notranslate"><span class="pre">continue</span></code> statement is encountered in <code class="docutils literal notranslate"><span class="pre">TRY_BLOCK</span></code>, only
|
||
<code class="docutils literal notranslate"><span class="pre">FINALLY_BLOCK</span></code> will be executed as the statement completes. With
|
||
the statement template, <code class="docutils literal notranslate"><span class="pre">ELSE_BLOCK</span></code> will also execute, as these
|
||
statements are treated like any other non-exceptional block
|
||
termination. For use cases where it matters, this is likely to be a
|
||
good thing (see <code class="docutils literal notranslate"><span class="pre">transaction</span></code> in the <a class="reference internal" href="#examples">Examples</a>), as this hole where
|
||
neither the <code class="docutils literal notranslate"><span class="pre">except</span></code> nor the <code class="docutils literal notranslate"><span class="pre">else</span></code> clause gets executed is easy
|
||
to forget when writing exception handlers.</p>
|
||
<p>Secondly, the statement template will not suppress any exceptions.
|
||
If, for example, the original code suppressed the <code class="docutils literal notranslate"><span class="pre">exc_type1</span></code> and
|
||
<code class="docutils literal notranslate"><span class="pre">exc_type2</span></code> exceptions, then this would still need to be done inline
|
||
in the user code:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">try</span><span class="p">:</span>
|
||
<span class="k">with</span> <span class="n">my_template</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">):</span>
|
||
<span class="n">TRY_BLOCK</span>
|
||
<span class="k">except</span> <span class="p">(</span><span class="n">exc_type1</span><span class="p">,</span> <span class="n">exc_type2</span><span class="p">):</span>
|
||
<span class="k">pass</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>However, even in these cases where the suppression of exceptions needs
|
||
to be made explicit, the amount of boilerplate repeated at the calling
|
||
site is significantly reduced (See <a class="reference internal" href="#rejected-options">Rejected Options</a> for further
|
||
discussion of this behaviour).</p>
|
||
<p>In general, not all of the clauses will be needed. For resource
|
||
handling (like files or synchronisation locks), it is possible to
|
||
simply execute the code that would have been part of <code class="docutils literal notranslate"><span class="pre">FINALLY_BLOCK</span></code>
|
||
in the <code class="docutils literal notranslate"><span class="pre">__exit__()</span></code> method. This can be seen in the following
|
||
implementation that makes synchronisation locks into statement
|
||
templates as mentioned at the beginning of this section:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># New methods of synchronisation lock objects</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="bp">self</span><span class="o">.</span><span class="n">acquire</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_info</span><span class="p">):</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">release</span><span class="p">()</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
</section>
|
||
<section id="generators">
|
||
<h2><a class="toc-backref" href="#generators" role="doc-backlink">Generators</a></h2>
|
||
<p>With their ability to suspend execution, and return control to the
|
||
calling frame, generators are natural candidates for writing statement
|
||
templates. Adding user defined statements to the language does <em>not</em>
|
||
require the generator changes described in this section, thus making
|
||
this PEP an obvious candidate for a phased implementation (<code class="docutils literal notranslate"><span class="pre">with</span></code>
|
||
statements in phase 1, generator integration in phase 2). The
|
||
suggested generator updates allow arbitrary exception handling to
|
||
be factored out like this:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@statement_template</span>
|
||
<span class="k">def</span> <span class="nf">my_template</span><span class="p">(</span><span class="o">*</span><span class="n">arguments</span><span class="p">):</span>
|
||
<span class="n">SETUP_BLOCK</span>
|
||
<span class="k">try</span><span class="p">:</span>
|
||
<span class="k">try</span><span class="p">:</span>
|
||
<span class="k">yield</span>
|
||
<span class="k">except</span> <span class="n">exc_type1</span><span class="p">,</span> <span class="n">exc</span><span class="p">:</span>
|
||
<span class="n">EXCEPT_BLOCK1</span>
|
||
<span class="k">except</span> <span class="n">exc_type2</span><span class="p">,</span> <span class="n">exc</span><span class="p">:</span>
|
||
<span class="n">EXCEPT_BLOCK2</span>
|
||
<span class="k">except</span><span class="p">:</span>
|
||
<span class="n">EXCEPT_BLOCK3</span>
|
||
<span class="k">else</span><span class="p">:</span>
|
||
<span class="n">ELSE_BLOCK</span>
|
||
<span class="k">finally</span><span class="p">:</span>
|
||
<span class="n">FINALLY_BLOCK</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Notice that, unlike the class based version, none of the blocks need
|
||
to be modified, as shared values are local variables of the
|
||
generator’s internal frame, including the arguments passed in by the
|
||
invoking code. The semantic differences noted earlier (all
|
||
non-exceptional block termination triggers the <code class="docutils literal notranslate"><span class="pre">else</span></code> clause, and
|
||
the template is unable to suppress exceptions) still apply.</p>
|
||
<section id="default-value-for-yield">
|
||
<h3><a class="toc-backref" href="#default-value-for-yield" role="doc-backlink">Default value for <code class="docutils literal notranslate"><span class="pre">yield</span></code></a></h3>
|
||
<p>When creating a statement template with a generator, the <code class="docutils literal notranslate"><span class="pre">yield</span></code>
|
||
statement will often be used solely to return control to the body of
|
||
the user defined statement, rather than to return a useful value.</p>
|
||
<p>Accordingly, if this PEP is accepted, <code class="docutils literal notranslate"><span class="pre">yield</span></code>, like <code class="docutils literal notranslate"><span class="pre">return</span></code>, will
|
||
supply a default value of <code class="docutils literal notranslate"><span class="pre">None</span></code> (i.e. <code class="docutils literal notranslate"><span class="pre">yield</span></code> and <code class="docutils literal notranslate"><span class="pre">yield</span> <span class="pre">None</span></code>
|
||
will become equivalent statements).</p>
|
||
<p>This same change is being suggested in <a class="pep reference internal" href="../pep-0342/" title="PEP 342 – Coroutines via Enhanced Generators">PEP 342</a>. Obviously, it would
|
||
only need to be implemented once if both PEPs were accepted :)</p>
|
||
</section>
|
||
<section id="template-generator-decorator-statement-template">
|
||
<h3><a class="toc-backref" href="#template-generator-decorator-statement-template" role="doc-backlink">Template generator decorator: <code class="docutils literal notranslate"><span class="pre">statement_template</span></code></a></h3>
|
||
<p>As with <a class="pep reference internal" href="../pep-0343/" title="PEP 343 – The “with” Statement">PEP 343</a>, a new decorator is suggested that wraps a generator
|
||
in an object with the appropriate statement template semantics.
|
||
Unlike <a class="pep reference internal" href="../pep-0343/" title="PEP 343 – The “with” Statement">PEP 343</a>, the templates suggested here are reusable, as the
|
||
generator is instantiated anew in each call to <code class="docutils literal notranslate"><span class="pre">__enter__()</span></code>.
|
||
Additionally, any exceptions that occur in <code class="docutils literal notranslate"><span class="pre">BLOCK1</span></code> are re-raised in
|
||
the generator’s internal frame:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">template_generator_wrapper</span><span class="p">(</span><span class="nb">object</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">func</span><span class="p">,</span> <span class="n">func_args</span><span class="p">,</span> <span class="n">func_kwds</span><span class="p">):</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">func</span> <span class="o">=</span> <span class="n">func</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">args</span> <span class="o">=</span> <span class="n">func_args</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">kwds</span> <span class="o">=</span> <span class="n">func_kwds</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">gen</span> <span class="o">=</span> <span class="kc">None</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">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">gen</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span>
|
||
<span class="k">raise</span> <span class="ne">RuntimeError</span><span class="p">(</span><span class="s2">"Enter called without exit!"</span><span class="p">)</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">gen</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">func</span><span class="p">(</span><span class="o">*</span><span class="bp">self</span><span class="o">.</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="bp">self</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">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">gen</span><span class="o">.</span><span class="n">next</span><span class="p">()</span>
|
||
<span class="k">except</span> <span class="ne">StopIteration</span><span class="p">:</span>
|
||
<span class="k">raise</span> <span class="ne">RuntimeError</span><span class="p">(</span><span class="s2">"Generator didn't yield"</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="o">*</span><span class="n">exc_info</span><span class="p">):</span>
|
||
<span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">gen</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
|
||
<span class="k">raise</span> <span class="ne">RuntimeError</span><span class="p">(</span><span class="s2">"Exit called without enter!"</span><span class="p">)</span>
|
||
<span class="k">try</span><span class="p">:</span>
|
||
<span class="k">try</span><span class="p">:</span>
|
||
<span class="k">if</span> <span class="n">exc_info</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">gen</span><span class="o">.</span><span class="n">_inject_exception</span><span class="p">(</span><span class="o">*</span><span class="n">exc_info</span><span class="p">)</span>
|
||
<span class="k">else</span><span class="p">:</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">gen</span><span class="o">.</span><span class="n">next</span><span class="p">()</span>
|
||
<span class="k">except</span> <span class="ne">StopIteration</span><span class="p">:</span>
|
||
<span class="k">pass</span>
|
||
<span class="k">else</span><span class="p">:</span>
|
||
<span class="k">raise</span> <span class="ne">RuntimeError</span><span class="p">(</span><span class="s2">"Generator didn't stop"</span><span class="p">)</span>
|
||
<span class="k">finally</span><span class="p">:</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">gen</span> <span class="o">=</span> <span class="kc">None</span>
|
||
|
||
<span class="k">def</span> <span class="nf">statement_template</span><span class="p">(</span><span class="n">func</span><span class="p">):</span>
|
||
<span class="k">def</span> <span class="nf">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">kwds</span><span class="p">):</span>
|
||
<span class="k">return</span> <span class="n">template_generator_wrapper</span><span class="p">(</span><span class="n">func</span><span class="p">,</span> <span class="n">args</span><span class="p">,</span> <span class="n">kwds</span><span class="p">)</span>
|
||
<span class="k">return</span> <span class="n">factory</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="template-generator-wrapper-enter-method">
|
||
<h3><a class="toc-backref" href="#template-generator-wrapper-enter-method" role="doc-backlink">Template generator wrapper: <code class="docutils literal notranslate"><span class="pre">__enter__()</span></code> method</a></h3>
|
||
<p>The template generator wrapper has an <code class="docutils literal notranslate"><span class="pre">__enter__()</span></code> method that
|
||
creates a new instance of the contained generator, and then invokes
|
||
<code class="docutils literal notranslate"><span class="pre">next()</span></code> once. It will raise a <code class="docutils literal notranslate"><span class="pre">RuntimeError</span></code> if the last
|
||
generator instance has not been cleaned up, or if the generator
|
||
terminates instead of yielding a value.</p>
|
||
</section>
|
||
<section id="template-generator-wrapper-exit-method">
|
||
<h3><a class="toc-backref" href="#template-generator-wrapper-exit-method" role="doc-backlink">Template generator wrapper: <code class="docutils literal notranslate"><span class="pre">__exit__()</span></code> method</a></h3>
|
||
<p>The template generator wrapper has an <code class="docutils literal notranslate"><span class="pre">__exit__()</span></code> method that
|
||
simply invokes <code class="docutils literal notranslate"><span class="pre">next()</span></code> on the generator if no exception is passed
|
||
in. If an exception is passed in, it is re-raised in the contained
|
||
generator at the point of the last <code class="docutils literal notranslate"><span class="pre">yield</span></code> statement.</p>
|
||
<p>In either case, the generator wrapper will raise a RuntimeError if the
|
||
internal frame does not terminate as a result of the operation. The
|
||
<code class="docutils literal notranslate"><span class="pre">__exit__()</span></code> method will always clean up the reference to the used
|
||
generator instance, permitting <code class="docutils literal notranslate"><span class="pre">__enter__()</span></code> to be called again.</p>
|
||
<p>A <code class="docutils literal notranslate"><span class="pre">StopIteration</span></code> raised by the body of the user defined statement
|
||
may be inadvertently suppressed inside the <code class="docutils literal notranslate"><span class="pre">__exit__()</span></code> method, but
|
||
this is unimportant, as the originally raised exception still
|
||
propagates correctly.</p>
|
||
</section>
|
||
<section id="injecting-exceptions-into-generators">
|
||
<h3><a class="toc-backref" href="#injecting-exceptions-into-generators" role="doc-backlink">Injecting exceptions into generators</a></h3>
|
||
<p>To implement the <code class="docutils literal notranslate"><span class="pre">__exit__()</span></code> method of the template generator
|
||
wrapper, it is necessary to inject exceptions into the internal frame
|
||
of the generator. This is new implementation level behaviour that has
|
||
no current Python equivalent.</p>
|
||
<p>The injection mechanism (referred to as <code class="docutils literal notranslate"><span class="pre">_inject_exception</span></code> in this
|
||
PEP) raises an exception in the generator’s frame with the specified
|
||
type, value and traceback information. This means that the exception
|
||
looks like the original if it is allowed to propagate.</p>
|
||
<p>For the purposes of this PEP, there is no need to make this capability
|
||
available outside the Python implementation code.</p>
|
||
</section>
|
||
<section id="generator-finalisation">
|
||
<h3><a class="toc-backref" href="#generator-finalisation" role="doc-backlink">Generator finalisation</a></h3>
|
||
<p>To support resource management in template generators, this PEP will
|
||
eliminate the restriction on <code class="docutils literal notranslate"><span class="pre">yield</span></code> statements inside the <code class="docutils literal notranslate"><span class="pre">try</span></code>
|
||
block of a <code class="docutils literal notranslate"><span class="pre">try</span></code>/<code class="docutils literal notranslate"><span class="pre">finally</span></code> statement. Accordingly, generators
|
||
which require the use of a file or some such object can ensure the
|
||
object is managed correctly through the use of <code class="docutils literal notranslate"><span class="pre">try</span></code>/<code class="docutils literal notranslate"><span class="pre">finally</span></code> or
|
||
<code class="docutils literal notranslate"><span class="pre">with</span></code> statements.</p>
|
||
<p>This restriction will likely need to be lifted globally - it would be
|
||
difficult to restrict it so that it was only permitted inside
|
||
generators used to define statement templates. Accordingly, this PEP
|
||
includes suggestions designed to ensure generators which are not used
|
||
as statement templates are still finalised appropriately.</p>
|
||
</section>
|
||
<section id="generator-finalisation-terminateiteration-exception">
|
||
<h3><a class="toc-backref" href="#generator-finalisation-terminateiteration-exception" role="doc-backlink">Generator finalisation: <code class="docutils literal notranslate"><span class="pre">TerminateIteration</span></code> exception</a></h3>
|
||
<p>A new exception is proposed:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">TerminateIteration</span><span class="p">(</span><span class="ne">Exception</span><span class="p">):</span> <span class="k">pass</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The new exception is injected into a generator in order to request
|
||
finalisation. It should not be suppressed by well-behaved code.</p>
|
||
</section>
|
||
<section id="generator-finalisation-del-method">
|
||
<h3><a class="toc-backref" href="#generator-finalisation-del-method" role="doc-backlink">Generator finalisation: <code class="docutils literal notranslate"><span class="pre">__del__()</span></code> method</a></h3>
|
||
<p>To ensure a generator is finalised eventually (within the limits of
|
||
Python’s garbage collection), generators will acquire a <code class="docutils literal notranslate"><span class="pre">__del__()</span></code>
|
||
method with the following semantics:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="fm">__del__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
|
||
<span class="k">try</span><span class="p">:</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">_inject_exception</span><span class="p">(</span><span class="n">TerminateIteration</span><span class="p">,</span> <span class="kc">None</span><span class="p">,</span> <span class="kc">None</span><span class="p">)</span>
|
||
<span class="k">except</span> <span class="n">TerminateIteration</span><span class="p">:</span>
|
||
<span class="k">pass</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="deterministic-generator-finalisation">
|
||
<h3><a class="toc-backref" href="#deterministic-generator-finalisation" role="doc-backlink">Deterministic generator finalisation</a></h3>
|
||
<p>There is a simple way to provide deterministic finalisation of
|
||
generators - give them appropriate <code class="docutils literal notranslate"><span class="pre">__enter__()</span></code> and <code class="docutils literal notranslate"><span class="pre">__exit__()</span></code>
|
||
methods:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></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_info</span><span class="p">):</span>
|
||
<span class="k">try</span><span class="p">:</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">_inject_exception</span><span class="p">(</span><span class="n">TerminateIteration</span><span class="p">,</span> <span class="kc">None</span><span class="p">,</span> <span class="kc">None</span><span class="p">)</span>
|
||
<span class="k">except</span> <span class="n">TerminateIteration</span><span class="p">:</span>
|
||
<span class="k">pass</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Then any generator can be finalised promptly by wrapping the relevant
|
||
<code class="docutils literal notranslate"><span class="pre">for</span></code> loop inside a <code class="docutils literal notranslate"><span class="pre">with</span></code> statement:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="n">all_lines</span><span class="p">(</span><span class="n">filenames</span><span class="p">)</span> <span class="k">as</span> <span class="n">lines</span><span class="p">:</span>
|
||
<span class="k">for</span> <span class="n">line</span> <span class="ow">in</span> <span class="n">lines</span><span class="p">:</span>
|
||
<span class="nb">print</span> <span class="n">lines</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>(See the <a class="reference internal" href="#examples">Examples</a> for the definition of <code class="docutils literal notranslate"><span class="pre">all_lines</span></code>, and the reason
|
||
it requires prompt finalisation)</p>
|
||
<p>Compare the above example to the usage of file objects:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="n">filename</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>
|
||
<span class="k">for</span> <span class="n">line</span> <span class="ow">in</span> <span class="n">f</span><span class="p">:</span>
|
||
<span class="nb">print</span> <span class="n">f</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="generators-as-user-defined-statement-templates">
|
||
<h3><a class="toc-backref" href="#generators-as-user-defined-statement-templates" role="doc-backlink">Generators as user defined statement templates</a></h3>
|
||
<p>When used to implement a user defined statement, a generator should
|
||
yield only once on a given control path. The result of that yield
|
||
will then be provided as the result of the generator’s <code class="docutils literal notranslate"><span class="pre">__enter__()</span></code>
|
||
method. Having a single <code class="docutils literal notranslate"><span class="pre">yield</span></code> on each control path ensures that
|
||
the internal frame will terminate when the generator’s <code class="docutils literal notranslate"><span class="pre">__exit__()</span></code>
|
||
method is called. Multiple <code class="docutils literal notranslate"><span class="pre">yield</span></code> statements on a single control
|
||
path will result in a <code class="docutils literal notranslate"><span class="pre">RuntimeError</span></code> being raised by the
|
||
<code class="docutils literal notranslate"><span class="pre">__exit__()</span></code> method when the internal frame fails to terminate
|
||
correctly. Such an error indicates a bug in the statement template.</p>
|
||
<p>To respond to exceptions, or to clean up resources, it is sufficient
|
||
to wrap the <code class="docutils literal notranslate"><span class="pre">yield</span></code> statement in an appropriately constructed
|
||
<code class="docutils literal notranslate"><span class="pre">try</span></code> statement. If execution resumes after the <code class="docutils literal notranslate"><span class="pre">yield</span></code> without
|
||
an exception, the generator knows that the body of the <code class="docutils literal notranslate"><span class="pre">do</span></code>
|
||
statement completed without incident.</p>
|
||
</section>
|
||
</section>
|
||
<section id="examples">
|
||
<h2><a class="toc-backref" href="#examples" role="doc-backlink">Examples</a></h2>
|
||
<ol class="arabic">
|
||
<li>A template for ensuring that a lock, acquired at the start of a
|
||
block, is released when the block is left:<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># New methods on synchronisation locks</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="bp">self</span><span class="o">.</span><span class="n">acquire</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_info</span><span class="p">):</span>
|
||
<span class="n">lock</span><span class="o">.</span><span class="n">release</span><span class="p">()</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Used as follows:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="n">myLock</span><span class="p">:</span>
|
||
<span class="c1"># Code here executes with myLock held. The lock is</span>
|
||
<span class="c1"># guaranteed to be released when the block is left (even</span>
|
||
<span class="c1"># if via return or by an uncaught exception).</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li>A template for opening a file that ensures the file is closed when
|
||
the block is left:<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># New methods on file objects</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">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">closed</span><span class="p">:</span>
|
||
<span class="k">raise</span> <span class="ne">RuntimeError</span><span class="p">,</span> <span class="s2">"Cannot reopen closed file handle"</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">args</span><span class="p">):</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Used as follows:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s2">"/etc/passwd"</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>
|
||
<span class="k">for</span> <span class="n">line</span> <span class="ow">in</span> <span class="n">f</span><span class="p">:</span>
|
||
<span class="nb">print</span> <span class="n">line</span><span class="o">.</span><span class="n">rstrip</span><span class="p">()</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li>A template for committing or rolling back a database transaction:<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">transaction</span><span class="p">(</span><span class="n">db</span><span class="p">):</span>
|
||
<span class="k">try</span><span class="p">:</span>
|
||
<span class="k">yield</span>
|
||
<span class="k">except</span><span class="p">:</span>
|
||
<span class="n">db</span><span class="o">.</span><span class="n">rollback</span><span class="p">()</span>
|
||
<span class="k">else</span><span class="p">:</span>
|
||
<span class="n">db</span><span class="o">.</span><span class="n">commit</span><span class="p">()</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Used as follows:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="n">transaction</span><span class="p">(</span><span class="n">the_db</span><span class="p">):</span>
|
||
<span class="n">make_table</span><span class="p">(</span><span class="n">the_db</span><span class="p">)</span>
|
||
<span class="n">add_data</span><span class="p">(</span><span class="n">the_db</span><span class="p">)</span>
|
||
<span class="c1"># Getting to here automatically triggers a commit</span>
|
||
<span class="c1"># Any exception automatically triggers a rollback</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li>It is possible to nest blocks and combine templates:<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@statement_template</span>
|
||
<span class="k">def</span> <span class="nf">lock_opening</span><span class="p">(</span><span class="n">lock</span><span class="p">,</span> <span class="n">filename</span><span class="p">,</span> <span class="n">mode</span><span class="o">=</span><span class="s2">"r"</span><span class="p">):</span>
|
||
<span class="k">with</span> <span class="n">lock</span><span class="p">:</span>
|
||
<span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="n">filename</span><span class="p">,</span> <span class="n">mode</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>
|
||
<span class="k">yield</span> <span class="n">f</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Used as follows:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="n">lock_opening</span><span class="p">(</span><span class="n">myLock</span><span class="p">,</span> <span class="s2">"/etc/passwd"</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>
|
||
<span class="k">for</span> <span class="n">line</span> <span class="ow">in</span> <span class="n">f</span><span class="p">:</span>
|
||
<span class="nb">print</span> <span class="n">line</span><span class="o">.</span><span class="n">rstrip</span><span class="p">()</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li>Redirect stdout temporarily:<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@statement_template</span>
|
||
<span class="k">def</span> <span class="nf">redirected_stdout</span><span class="p">(</span><span class="n">new_stdout</span><span class="p">):</span>
|
||
<span class="n">save_stdout</span> <span class="o">=</span> <span class="n">sys</span><span class="o">.</span><span class="n">stdout</span>
|
||
<span class="k">try</span><span class="p">:</span>
|
||
<span class="n">sys</span><span class="o">.</span><span class="n">stdout</span> <span class="o">=</span> <span class="n">new_stdout</span>
|
||
<span class="k">yield</span>
|
||
<span class="k">finally</span><span class="p">:</span>
|
||
<span class="n">sys</span><span class="o">.</span><span class="n">stdout</span> <span class="o">=</span> <span class="n">save_stdout</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Used as follows:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="n">filename</span><span class="p">,</span> <span class="s2">"w"</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">redirected_stdout</span><span class="p">(</span><span class="n">f</span><span class="p">):</span>
|
||
<span class="nb">print</span> <span class="s2">"Hello world"</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li>A variant on <code class="docutils literal notranslate"><span class="pre">open()</span></code> that also returns an error condition:<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@statement_template</span>
|
||
<span class="k">def</span> <span class="nf">open_w_error</span><span class="p">(</span><span class="n">filename</span><span class="p">,</span> <span class="n">mode</span><span class="o">=</span><span class="s2">"r"</span><span class="p">):</span>
|
||
<span class="k">try</span><span class="p">:</span>
|
||
<span class="n">f</span> <span class="o">=</span> <span class="nb">open</span><span class="p">(</span><span class="n">filename</span><span class="p">,</span> <span class="n">mode</span><span class="p">)</span>
|
||
<span class="k">except</span> <span class="ne">IOError</span><span class="p">,</span> <span class="n">err</span><span class="p">:</span>
|
||
<span class="k">yield</span> <span class="kc">None</span><span class="p">,</span> <span class="n">err</span>
|
||
<span class="k">else</span><span class="p">:</span>
|
||
<span class="k">try</span><span class="p">:</span>
|
||
<span class="k">yield</span> <span class="n">f</span><span class="p">,</span> <span class="kc">None</span>
|
||
<span class="k">finally</span><span class="p">:</span>
|
||
<span class="n">f</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Used as follows:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">do</span> <span class="n">open_w_error</span><span class="p">(</span><span class="s2">"/etc/passwd"</span><span class="p">,</span> <span class="s2">"a"</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">,</span> <span class="n">err</span><span class="p">:</span>
|
||
<span class="k">if</span> <span class="n">err</span><span class="p">:</span>
|
||
<span class="nb">print</span> <span class="s2">"IOError:"</span><span class="p">,</span> <span class="n">err</span>
|
||
<span class="k">else</span><span class="p">:</span>
|
||
<span class="n">f</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s2">"guido::0:0::/:/bin/sh</span><span class="se">\n</span><span class="s2">"</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li>Find the first file with a specific header:<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">for</span> <span class="n">name</span> <span class="ow">in</span> <span class="n">filenames</span><span class="p">:</span>
|
||
<span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="n">name</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>
|
||
<span class="k">if</span> <span class="n">f</span><span class="o">.</span><span class="n">read</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span> <span class="o">==</span> <span class="mh">0xFEB0</span><span class="p">:</span>
|
||
<span class="k">break</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li>Find the first item you can handle, holding a lock for the entire
|
||
loop, or just for each iteration:<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="n">lock</span><span class="p">:</span>
|
||
<span class="k">for</span> <span class="n">item</span> <span class="ow">in</span> <span class="n">items</span><span class="p">:</span>
|
||
<span class="k">if</span> <span class="n">handle</span><span class="p">(</span><span class="n">item</span><span class="p">):</span>
|
||
<span class="k">break</span>
|
||
|
||
<span class="k">for</span> <span class="n">item</span> <span class="ow">in</span> <span class="n">items</span><span class="p">:</span>
|
||
<span class="k">with</span> <span class="n">lock</span><span class="p">:</span>
|
||
<span class="k">if</span> <span class="n">handle</span><span class="p">(</span><span class="n">item</span><span class="p">):</span>
|
||
<span class="k">break</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li>Hold a lock while inside a generator, but release it when
|
||
returning control to the outer scope:<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@statement_template</span>
|
||
<span class="k">def</span> <span class="nf">released</span><span class="p">(</span><span class="n">lock</span><span class="p">):</span>
|
||
<span class="n">lock</span><span class="o">.</span><span class="n">release</span><span class="p">()</span>
|
||
<span class="k">try</span><span class="p">:</span>
|
||
<span class="k">yield</span>
|
||
<span class="k">finally</span><span class="p">:</span>
|
||
<span class="n">lock</span><span class="o">.</span><span class="n">acquire</span><span class="p">()</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Used as follows:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="n">lock</span><span class="p">:</span>
|
||
<span class="k">for</span> <span class="n">item</span> <span class="ow">in</span> <span class="n">items</span><span class="p">:</span>
|
||
<span class="k">with</span> <span class="n">released</span><span class="p">(</span><span class="n">lock</span><span class="p">):</span>
|
||
<span class="k">yield</span> <span class="n">item</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li>Read the lines from a collection of files (e.g. processing
|
||
multiple configuration sources):<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">all_lines</span><span class="p">(</span><span class="n">filenames</span><span class="p">):</span>
|
||
<span class="k">for</span> <span class="n">name</span> <span class="ow">in</span> <span class="n">filenames</span><span class="p">:</span>
|
||
<span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="n">name</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>
|
||
<span class="k">for</span> <span class="n">line</span> <span class="ow">in</span> <span class="n">f</span><span class="p">:</span>
|
||
<span class="k">yield</span> <span class="n">line</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Used as follows:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="n">all_lines</span><span class="p">(</span><span class="n">filenames</span><span class="p">)</span> <span class="k">as</span> <span class="n">lines</span><span class="p">:</span>
|
||
<span class="k">for</span> <span class="n">line</span> <span class="ow">in</span> <span class="n">lines</span><span class="p">:</span>
|
||
<span class="n">update_config</span><span class="p">(</span><span class="n">line</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li>Not all uses need to involve resource management:<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@statement_template</span>
|
||
<span class="k">def</span> <span class="nf">tag</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="n">name</span> <span class="o">=</span> <span class="n">cgi</span><span class="o">.</span><span class="n">escape</span><span class="p">(</span><span class="n">args</span><span class="p">[</span><span class="mi">0</span><span class="p">])</span>
|
||
<span class="k">if</span> <span class="n">kwds</span><span class="p">:</span>
|
||
<span class="n">kwd_pairs</span> <span class="o">=</span> <span class="p">[</span><span class="s2">"</span><span class="si">%s</span><span class="s2">=</span><span class="si">%s</span><span class="s2">"</span> <span class="o">%</span> <span class="n">cgi</span><span class="o">.</span><span class="n">escape</span><span class="p">(</span><span class="n">key</span><span class="p">),</span> <span class="n">cgi</span><span class="o">.</span><span class="n">escape</span><span class="p">(</span><span class="n">value</span><span class="p">)</span>
|
||
<span class="k">for</span> <span class="n">key</span><span class="p">,</span> <span class="n">value</span> <span class="ow">in</span> <span class="n">kwds</span><span class="p">]</span>
|
||
<span class="nb">print</span> <span class="s1">'<</span><span class="si">%s</span><span class="s1"> </span><span class="si">%s</span><span class="s1">>'</span> <span class="o">%</span> <span class="n">name</span><span class="p">,</span> <span class="s2">" "</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">kwd_pairs</span><span class="p">)</span>
|
||
<span class="k">else</span><span class="p">:</span>
|
||
<span class="nb">print</span> <span class="s1">'<</span><span class="si">%s</span><span class="s1">>'</span> <span class="o">%</span> <span class="n">name</span>
|
||
<span class="k">yield</span>
|
||
<span class="nb">print</span> <span class="s1">'</</span><span class="si">%s</span><span class="s1">>'</span> <span class="o">%</span> <span class="n">name</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Used as follows:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="n">tag</span><span class="p">(</span><span class="s1">'html'</span><span class="p">):</span>
|
||
<span class="k">with</span> <span class="n">tag</span><span class="p">(</span><span class="s1">'head'</span><span class="p">):</span>
|
||
<span class="k">with</span> <span class="n">tag</span><span class="p">(</span><span class="s1">'title'</span><span class="p">):</span>
|
||
<span class="nb">print</span> <span class="s1">'A web page'</span>
|
||
<span class="k">with</span> <span class="n">tag</span><span class="p">(</span><span class="s1">'body'</span><span class="p">):</span>
|
||
<span class="k">for</span> <span class="n">par</span> <span class="ow">in</span> <span class="n">pars</span><span class="p">:</span>
|
||
<span class="k">with</span> <span class="n">tag</span><span class="p">(</span><span class="s1">'p'</span><span class="p">):</span>
|
||
<span class="nb">print</span> <span class="n">par</span>
|
||
<span class="k">with</span> <span class="n">tag</span><span class="p">(</span><span class="s1">'a'</span><span class="p">,</span> <span class="n">href</span><span class="o">=</span><span class="s2">"http://www.python.org"</span><span class="p">):</span>
|
||
<span class="nb">print</span> <span class="s2">"Not a dead parrot!"</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li>From <a class="pep reference internal" href="../pep-0343/" title="PEP 343 – The “with” Statement">PEP 343</a>, another useful example would be an operation that
|
||
blocks signals. The use could be like this:<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">signal</span> <span class="kn">import</span> <span class="n">blocked_signals</span>
|
||
|
||
<span class="k">with</span> <span class="n">blocked_signals</span><span class="p">():</span>
|
||
<span class="c1"># code executed without worrying about signals</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>An optional argument might be a list of signals to be blocked; by
|
||
default all signals are blocked. The implementation is left as an
|
||
exercise to the reader.</p>
|
||
</li>
|
||
<li>Another use for this feature is for Decimal contexts:<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># New methods on decimal Context objects</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">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">_old_context</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span>
|
||
<span class="k">raise</span> <span class="ne">RuntimeError</span><span class="p">(</span><span class="s2">"Already suspending other Context"</span><span class="p">)</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">_old_context</span> <span class="o">=</span> <span class="n">getcontext</span><span class="p">()</span>
|
||
<span class="n">setcontext</span><span class="p">(</span><span class="bp">self</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="o">*</span><span class="n">args</span><span class="p">):</span>
|
||
<span class="n">setcontext</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_old_context</span><span class="p">)</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">_old_context</span> <span class="o">=</span> <span class="kc">None</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Used as follows:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="n">decimal</span><span class="o">.</span><span class="n">Context</span><span class="p">(</span><span class="n">precision</span><span class="o">=</span><span class="mi">28</span><span class="p">):</span>
|
||
<span class="c1"># Code here executes with the given context</span>
|
||
<span class="c1"># The context always reverts after this statement</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
</ol>
|
||
</section>
|
||
<section id="open-issues">
|
||
<h2><a class="toc-backref" href="#open-issues" role="doc-backlink">Open Issues</a></h2>
|
||
<p>None, as this PEP has been withdrawn.</p>
|
||
</section>
|
||
<section id="rejected-options">
|
||
<h2><a class="toc-backref" href="#rejected-options" role="doc-backlink">Rejected Options</a></h2>
|
||
<section id="having-the-basic-construct-be-a-looping-construct">
|
||
<h3><a class="toc-backref" href="#having-the-basic-construct-be-a-looping-construct" role="doc-backlink">Having the basic construct be a looping construct</a></h3>
|
||
<p>The major issue with this idea, as illustrated by <a class="pep reference internal" href="../pep-0340/" title="PEP 340 – Anonymous Block Statements">PEP 340</a>’s
|
||
<code class="docutils literal notranslate"><span class="pre">block</span></code> statements, is that it causes problems with factoring
|
||
<code class="docutils literal notranslate"><span class="pre">try</span></code> statements that are inside loops, and contain <code class="docutils literal notranslate"><span class="pre">break</span></code> and
|
||
<code class="docutils literal notranslate"><span class="pre">continue</span></code> statements (as these statements would then apply to the
|
||
<code class="docutils literal notranslate"><span class="pre">block</span></code> construct, instead of the original loop). As a key goal is
|
||
to be able to factor out arbitrary exception handling (other than
|
||
suppression) into statement templates, this is a definite problem.</p>
|
||
<p>There is also an understandability problem, as can be seen in the
|
||
<a class="reference internal" href="#examples">Examples</a>. In the example showing acquisition of a lock either for an
|
||
entire loop, or for each iteration of the loop, if the user defined
|
||
statement was itself a loop, moving it from outside the <code class="docutils literal notranslate"><span class="pre">for</span></code> loop
|
||
to inside the <code class="docutils literal notranslate"><span class="pre">for</span></code> loop would have major semantic implications,
|
||
beyond those one would expect.</p>
|
||
<p>Finally, with a looping construct, there are significant problems with
|
||
TOOWTDI, as it is frequently unclear whether a particular situation
|
||
should be handled with a conventional <code class="docutils literal notranslate"><span class="pre">for</span></code> loop or the new looping
|
||
construct. With the current PEP, there is no such problem - <code class="docutils literal notranslate"><span class="pre">for</span></code>
|
||
loops continue to be used for iteration, and the new <code class="docutils literal notranslate"><span class="pre">do</span></code> statements
|
||
are used to factor out exception handling.</p>
|
||
<p>Another issue, specifically with <a class="pep reference internal" href="../pep-0340/" title="PEP 340 – Anonymous Block Statements">PEP 340</a>’s anonymous block statements,
|
||
is that they make it quite difficult to write statement templates
|
||
directly (i.e. not using a generator). This problem is addressed by
|
||
the current proposal, as can be seen by the relative simplicity of the
|
||
various class based implementations of statement templates in the
|
||
<a class="reference internal" href="#examples">Examples</a>.</p>
|
||
</section>
|
||
<section id="allowing-statement-templates-to-suppress-exceptions">
|
||
<h3><a class="toc-backref" href="#allowing-statement-templates-to-suppress-exceptions" role="doc-backlink">Allowing statement templates to suppress exceptions</a></h3>
|
||
<p>Earlier versions of this PEP gave statement templates the ability to
|
||
suppress exceptions. The BDFL expressed concern over the associated
|
||
complexity, and I agreed after reading an article by Raymond Chen
|
||
about the evils of hiding flow control inside macros in C code <a class="footnote-reference brackets" href="#id3" id="id1">[1]</a>.</p>
|
||
<p>Removing the suppression ability eliminated a whole lot of complexity
|
||
from both the explanation and implementation of user defined
|
||
statements, further supporting it as the correct choice. Older
|
||
versions of the PEP had to jump through some horrible hoops to avoid
|
||
inadvertently suppressing exceptions in <code class="docutils literal notranslate"><span class="pre">__exit__()</span></code> methods - that
|
||
issue does not exist with the current suggested semantics.</p>
|
||
<p>There was one example (<code class="docutils literal notranslate"><span class="pre">auto_retry</span></code>) that actually used the ability
|
||
to suppress exceptions. This use case, while not quite as elegant,
|
||
has significantly more obvious control flow when written out in full
|
||
in the user code:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">attempts</span><span class="p">(</span><span class="n">num_tries</span><span class="p">):</span>
|
||
<span class="k">return</span> <span class="nb">reversed</span><span class="p">(</span><span class="n">xrange</span><span class="p">(</span><span class="n">num_tries</span><span class="p">))</span>
|
||
|
||
<span class="k">for</span> <span class="n">retry</span> <span class="ow">in</span> <span class="n">attempts</span><span class="p">(</span><span class="mi">3</span><span class="p">):</span>
|
||
<span class="k">try</span><span class="p">:</span>
|
||
<span class="n">make_attempt</span><span class="p">()</span>
|
||
<span class="k">except</span> <span class="ne">IOError</span><span class="p">:</span>
|
||
<span class="k">if</span> <span class="ow">not</span> <span class="n">retry</span><span class="p">:</span>
|
||
<span class="k">raise</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>For what it’s worth, the perverse could still write this as:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">for</span> <span class="n">attempt</span> <span class="ow">in</span> <span class="n">auto_retry</span><span class="p">(</span><span class="mi">3</span><span class="p">,</span> <span class="ne">IOError</span><span class="p">):</span>
|
||
<span class="k">try</span><span class="p">:</span>
|
||
<span class="k">with</span> <span class="n">attempt</span><span class="p">:</span>
|
||
<span class="n">make_attempt</span><span class="p">()</span>
|
||
<span class="k">except</span> <span class="n">FailedAttempt</span><span class="p">:</span>
|
||
<span class="k">pass</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>To protect the innocent, the code to actually support that is not
|
||
included here.</p>
|
||
</section>
|
||
<section id="differentiating-between-non-exceptional-exits">
|
||
<h3><a class="toc-backref" href="#differentiating-between-non-exceptional-exits" role="doc-backlink">Differentiating between non-exceptional exits</a></h3>
|
||
<p>Earlier versions of this PEP allowed statement templates to
|
||
distinguish between exiting the block normally, and exiting via a
|
||
<code class="docutils literal notranslate"><span class="pre">return</span></code>, <code class="docutils literal notranslate"><span class="pre">break</span></code> or <code class="docutils literal notranslate"><span class="pre">continue</span></code> statement. The BDFL flirted
|
||
with a similar idea in <a class="pep reference internal" href="../pep-0343/" title="PEP 343 – The “with” Statement">PEP 343</a> and its associated discussion. This
|
||
added significant complexity to the description of the semantics, and
|
||
it required each and every statement template to decide whether or not
|
||
those statements should be treated like exceptions, or like a normal
|
||
mechanism for exiting the block.</p>
|
||
<p>This template-by-template decision process raised great potential for
|
||
confusion - consider if one database connector provided a transaction
|
||
template that treated early exits like an exception, whereas a second
|
||
connector treated them as normal block termination.</p>
|
||
<p>Accordingly, this PEP now uses the simplest solution - early exits
|
||
appear identical to normal block termination as far as the statement
|
||
template is concerned.</p>
|
||
</section>
|
||
<section id="not-injecting-raised-exceptions-into-generators">
|
||
<h3><a class="toc-backref" href="#not-injecting-raised-exceptions-into-generators" role="doc-backlink">Not injecting raised exceptions into generators</a></h3>
|
||
<p><a class="pep reference internal" href="../pep-0343/" title="PEP 343 – The “with” Statement">PEP 343</a> suggests simply invoking next() unconditionally on generators
|
||
used to define statement templates. This means the template
|
||
generators end up looking rather unintuitive, and the retention of the
|
||
ban against yielding inside <code class="docutils literal notranslate"><span class="pre">try</span></code>/<code class="docutils literal notranslate"><span class="pre">finally</span></code> means that Python’s
|
||
exception handling capabilities cannot be used to deal with management
|
||
of multiple resources.</p>
|
||
<p>The alternative which this PEP advocates (injecting raised exceptions
|
||
into the generator frame), means that multiple resources can be
|
||
managed elegantly as shown by <code class="docutils literal notranslate"><span class="pre">lock_opening</span></code> in the <a class="reference internal" href="#examples">Examples</a></p>
|
||
</section>
|
||
<section id="making-all-generators-statement-templates">
|
||
<h3><a class="toc-backref" href="#making-all-generators-statement-templates" role="doc-backlink">Making all generators statement templates</a></h3>
|
||
<p>Separating the template object from the generator itself makes it
|
||
possible to have reusable generator templates. That is, the following
|
||
code will work correctly if this PEP is accepted:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">open_it</span> <span class="o">=</span> <span class="n">lock_opening</span><span class="p">(</span><span class="n">parrot_lock</span><span class="p">,</span> <span class="s2">"dead_parrot.txt"</span><span class="p">)</span>
|
||
|
||
<span class="k">with</span> <span class="n">open_it</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>
|
||
<span class="c1"># use the file for a while</span>
|
||
|
||
<span class="k">with</span> <span class="n">open_it</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>
|
||
<span class="c1"># use the file again</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The second benefit is that iterator generators and template generators
|
||
are very different things - the decorator keeps that distinction
|
||
clear, and prevents one being used where the other is required.</p>
|
||
<p>Finally, requiring the decorator allows the native methods of
|
||
generator objects to be used to implement generator finalisation.</p>
|
||
</section>
|
||
<section id="using-do-as-the-keyword">
|
||
<h3><a class="toc-backref" href="#using-do-as-the-keyword" role="doc-backlink">Using <code class="docutils literal notranslate"><span class="pre">do</span></code> as the keyword</a></h3>
|
||
<p><code class="docutils literal notranslate"><span class="pre">do</span></code> was an alternative keyword proposed during the <a class="pep reference internal" href="../pep-0340/" title="PEP 340 – Anonymous Block Statements">PEP 340</a>
|
||
discussion. It reads well with appropriately named functions, but it
|
||
reads poorly when used with methods, or with objects that provide
|
||
native statement template support.</p>
|
||
<p>When <code class="docutils literal notranslate"><span class="pre">do</span></code> was first suggested, the BDFL had rejected <a class="pep reference internal" href="../pep-0310/" title="PEP 310 – Reliable Acquisition/Release Pairs">PEP 310</a>’s
|
||
<code class="docutils literal notranslate"><span class="pre">with</span></code> keyword, based on a desire to use it for a Pascal/Delphi
|
||
style <code class="docutils literal notranslate"><span class="pre">with</span></code> statement. Since then, the BDFL has retracted this
|
||
objection, as he no longer intends to provide such a statement. This
|
||
change of heart was apparently based on the C# developers reasons for
|
||
not providing the feature <a class="footnote-reference brackets" href="#id4" id="id2">[2]</a>.</p>
|
||
</section>
|
||
<section id="not-having-a-keyword">
|
||
<h3><a class="toc-backref" href="#not-having-a-keyword" role="doc-backlink">Not having a keyword</a></h3>
|
||
<p>This is an interesting option, and can be made to read quite well.
|
||
However, it’s awkward to look up in the documentation for new users,
|
||
and strikes some as being too magical. Accordingly, this PEP goes
|
||
with a keyword based suggestion.</p>
|
||
</section>
|
||
<section id="enhancing-try-statements">
|
||
<h3><a class="toc-backref" href="#enhancing-try-statements" role="doc-backlink">Enhancing <code class="docutils literal notranslate"><span class="pre">try</span></code> statements</a></h3>
|
||
<p>This suggestion involves give bare <code class="docutils literal notranslate"><span class="pre">try</span></code> statements a signature
|
||
similar to that proposed for <code class="docutils literal notranslate"><span class="pre">with</span></code> statements.</p>
|
||
<p>I think that trying to write a <code class="docutils literal notranslate"><span class="pre">with</span></code> statement as an enhanced
|
||
<code class="docutils literal notranslate"><span class="pre">try</span></code> statement makes as much sense as trying to write a <code class="docutils literal notranslate"><span class="pre">for</span></code>
|
||
loop as an enhanced <code class="docutils literal notranslate"><span class="pre">while</span></code> loop. That is, while the semantics of
|
||
the former can be explained as a particular way of using the latter,
|
||
the former is not an <em>instance</em> of the latter. The additional
|
||
semantics added around the more fundamental statement result in a new
|
||
construct, and the two different statements shouldn’t be confused.</p>
|
||
<p>This can be seen by the fact that the ‘enhanced’ <code class="docutils literal notranslate"><span class="pre">try</span></code> statement
|
||
still needs to be explained in terms of a ‘non-enhanced’ <code class="docutils literal notranslate"><span class="pre">try</span></code>
|
||
statement. If it’s something different, it makes more sense to give
|
||
it a different name.</p>
|
||
</section>
|
||
<section id="having-the-template-protocol-directly-reflect-try-statements">
|
||
<h3><a class="toc-backref" href="#having-the-template-protocol-directly-reflect-try-statements" role="doc-backlink">Having the template protocol directly reflect <code class="docutils literal notranslate"><span class="pre">try</span></code> statements</a></h3>
|
||
<p>One suggestion was to have separate methods in the protocol to cover
|
||
different parts of the structure of a generalised <code class="docutils literal notranslate"><span class="pre">try</span></code> statement.
|
||
Using the terms <code class="docutils literal notranslate"><span class="pre">try</span></code>, <code class="docutils literal notranslate"><span class="pre">except</span></code>, <code class="docutils literal notranslate"><span class="pre">else</span></code> and <code class="docutils literal notranslate"><span class="pre">finally</span></code>, we
|
||
would have something like:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">my_template</span><span class="p">(</span><span class="nb">object</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="o">*</span><span class="n">args</span><span class="p">):</span>
|
||
<span class="c1"># Any required arguments (e.g. a file name)</span>
|
||
<span class="c1"># get stored in member variables</span>
|
||
<span class="c1"># The various BLOCK's will need to updated to reflect</span>
|
||
<span class="c1"># that.</span>
|
||
|
||
<span class="k">def</span> <span class="nf">__try__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
|
||
<span class="n">SETUP_BLOCK</span>
|
||
|
||
<span class="k">def</span> <span class="nf">__except__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">exc</span><span class="p">,</span> <span class="n">value</span><span class="p">,</span> <span class="n">traceback</span><span class="p">):</span>
|
||
<span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">exc</span><span class="p">,</span> <span class="n">exc_type1</span><span class="p">):</span>
|
||
<span class="n">EXCEPT_BLOCK1</span>
|
||
<span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">exc</span><span class="p">,</span> <span class="n">exc_type2</span><span class="p">):</span>
|
||
<span class="n">EXCEPT_BLOCK2</span>
|
||
<span class="k">else</span><span class="p">:</span>
|
||
<span class="n">EXCEPT_BLOCK3</span>
|
||
|
||
<span class="k">def</span> <span class="nf">__else__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
|
||
<span class="n">ELSE_BLOCK</span>
|
||
|
||
<span class="k">def</span> <span class="nf">__finally__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
|
||
<span class="n">FINALLY_BLOCK</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Aside from preferring the addition of two method slots rather than
|
||
four, I consider it significantly easier to be able to simply
|
||
reproduce a slightly modified version of the original <code class="docutils literal notranslate"><span class="pre">try</span></code>
|
||
statement code in the <code class="docutils literal notranslate"><span class="pre">__exit__()</span></code> method (as shown in <a class="reference internal" href="#factoring-out-arbitrary-exception-handling">Factoring
|
||
out arbitrary exception handling</a>), rather than have to split the
|
||
functionality amongst several different methods (or figure out
|
||
which method to use if not all clauses are used by the template).</p>
|
||
<p>To make this discussion less theoretical, here is the <code class="docutils literal notranslate"><span class="pre">transaction</span></code>
|
||
example implemented using both the two method and the four method
|
||
protocols instead of a generator. Both implementations guarantee a
|
||
commit if a <code class="docutils literal notranslate"><span class="pre">break</span></code>, <code class="docutils literal notranslate"><span class="pre">return</span></code> or <code class="docutils literal notranslate"><span class="pre">continue</span></code> statement is
|
||
encountered (as does the generator-based implementation in the
|
||
<a class="reference internal" href="#examples">Examples</a> section):</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">transaction_2method</span><span class="p">(</span><span class="nb">object</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">db</span><span class="p">):</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">db</span> <span class="o">=</span> <span class="n">db</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">pass</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="o">*</span><span class="n">exc_details</span><span class="p">):</span>
|
||
<span class="k">if</span> <span class="n">exc_type</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">commit</span><span class="p">()</span>
|
||
<span class="k">else</span><span class="p">:</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">rollback</span><span class="p">()</span>
|
||
|
||
<span class="k">class</span> <span class="nc">transaction_4method</span><span class="p">(</span><span class="nb">object</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">db</span><span class="p">):</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">db</span> <span class="o">=</span> <span class="n">db</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">commit</span> <span class="o">=</span> <span class="kc">False</span>
|
||
|
||
<span class="k">def</span> <span class="nf">__try__</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">commit</span> <span class="o">=</span> <span class="kc">True</span>
|
||
|
||
<span class="k">def</span> <span class="nf">__except__</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_value</span><span class="p">,</span> <span class="n">traceback</span><span class="p">):</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">rollback</span><span class="p">()</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">commit</span> <span class="o">=</span> <span class="kc">False</span>
|
||
|
||
<span class="k">def</span> <span class="nf">__else__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
|
||
<span class="k">pass</span>
|
||
|
||
<span class="k">def</span> <span class="nf">__finally__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
|
||
<span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">commit</span><span class="p">:</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">commit</span><span class="p">()</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">commit</span> <span class="o">=</span> <span class="kc">False</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>There are two more minor points, relating to the specific method names
|
||
in the suggestion. The name of the <code class="docutils literal notranslate"><span class="pre">__try__()</span></code> method is
|
||
misleading, as <code class="docutils literal notranslate"><span class="pre">SETUP_BLOCK</span></code> executes <em>before</em> the <code class="docutils literal notranslate"><span class="pre">try</span></code> statement
|
||
is entered, and the name of the <code class="docutils literal notranslate"><span class="pre">__else__()</span></code> method is unclear in
|
||
isolation, as numerous other Python statements include an <code class="docutils literal notranslate"><span class="pre">else</span></code>
|
||
clause.</p>
|
||
</section>
|
||
</section>
|
||
<section id="iterator-finalisation-withdrawn">
|
||
<h2><a class="toc-backref" href="#iterator-finalisation-withdrawn" role="doc-backlink">Iterator finalisation (WITHDRAWN)</a></h2>
|
||
<p>The ability to use user defined statements inside generators is likely
|
||
to increase the need for deterministic finalisation of iterators, as
|
||
resource management is pushed inside the generators, rather than being
|
||
handled externally as is currently the case.</p>
|
||
<p>The PEP currently suggests handling this by making all generators
|
||
statement templates, and using <code class="docutils literal notranslate"><span class="pre">with</span></code> statements to handle
|
||
finalisation. However, earlier versions of this PEP suggested the
|
||
following, more complex, solution, that allowed the <em>author</em> of a
|
||
generator to flag the need for finalisation, and have <code class="docutils literal notranslate"><span class="pre">for</span></code> loops
|
||
deal with it automatically. It is included here as a long, detailed
|
||
rejected option.</p>
|
||
<section id="iterator-protocol-addition-finish">
|
||
<h3><a class="toc-backref" href="#iterator-protocol-addition-finish" role="doc-backlink">Iterator protocol addition: <code class="docutils literal notranslate"><span class="pre">__finish__</span></code></a></h3>
|
||
<p>An optional new method for iterators is proposed, called
|
||
<code class="docutils literal notranslate"><span class="pre">__finish__()</span></code>. It takes no arguments, and should not return
|
||
anything.</p>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">__finish__</span></code> method is expected to clean up all resources the
|
||
iterator has open. Iterators with a <code class="docutils literal notranslate"><span class="pre">__finish__()</span></code> method are
|
||
called ‘finishable iterators’ for the remainder of the PEP.</p>
|
||
</section>
|
||
<section id="best-effort-finalisation">
|
||
<h3><a class="toc-backref" href="#best-effort-finalisation" role="doc-backlink">Best effort finalisation</a></h3>
|
||
<p>A finishable iterator should ensure that it provides a <code class="docutils literal notranslate"><span class="pre">__del__</span></code>
|
||
method that also performs finalisation (e.g. by invoking the
|
||
<code class="docutils literal notranslate"><span class="pre">__finish__()</span></code> method). This allows Python to still make a best
|
||
effort at finalisation in the event that deterministic finalisation is
|
||
not applied to the iterator.</p>
|
||
</section>
|
||
<section id="deterministic-finalisation">
|
||
<h3><a class="toc-backref" href="#deterministic-finalisation" role="doc-backlink">Deterministic finalisation</a></h3>
|
||
<p>If the iterator used in a <code class="docutils literal notranslate"><span class="pre">for</span></code> loop has a <code class="docutils literal notranslate"><span class="pre">__finish__()</span></code> method,
|
||
the enhanced <code class="docutils literal notranslate"><span class="pre">for</span></code> loop semantics will guarantee that that method
|
||
will be executed, regardless of the means of exiting the loop. This
|
||
is important for iterator generators that utilise <a class="reference internal" href="#user-defined-statements">user defined
|
||
statements</a> or the now permitted <code class="docutils literal notranslate"><span class="pre">try</span></code>/<code class="docutils literal notranslate"><span class="pre">finally</span></code> statements, or
|
||
for new iterators that rely on timely finalisation to release
|
||
allocated resources (e.g. releasing a thread or database connection
|
||
back into a pool).</p>
|
||
</section>
|
||
<section id="for-loop-syntax">
|
||
<h3><a class="toc-backref" href="#for-loop-syntax" role="doc-backlink"><code class="docutils literal notranslate"><span class="pre">for</span></code> loop syntax</a></h3>
|
||
<p>No changes are suggested to <code class="docutils literal notranslate"><span class="pre">for</span></code> loop syntax. This is just to
|
||
define the statement parts needed for the description of the
|
||
semantics:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">for</span> <span class="n">VAR1</span> <span class="ow">in</span> <span class="n">EXPR1</span><span class="p">:</span>
|
||
<span class="n">BLOCK1</span>
|
||
<span class="k">else</span><span class="p">:</span>
|
||
<span class="n">BLOCK2</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="updated-for-loop-semantics">
|
||
<h3><a class="toc-backref" href="#updated-for-loop-semantics" role="doc-backlink">Updated <code class="docutils literal notranslate"><span class="pre">for</span></code> loop semantics</a></h3>
|
||
<p>When the target iterator does not have a <code class="docutils literal notranslate"><span class="pre">__finish__()</span></code> method, a
|
||
<code class="docutils literal notranslate"><span class="pre">for</span></code> loop will execute as follows (i.e. no change from the status
|
||
quo):</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">itr</span> <span class="o">=</span> <span class="nb">iter</span><span class="p">(</span><span class="n">EXPR1</span><span class="p">)</span>
|
||
<span class="n">exhausted</span> <span class="o">=</span> <span class="kc">False</span>
|
||
<span class="k">while</span> <span class="kc">True</span><span class="p">:</span>
|
||
<span class="k">try</span><span class="p">:</span>
|
||
<span class="n">VAR1</span> <span class="o">=</span> <span class="n">itr</span><span class="o">.</span><span class="n">next</span><span class="p">()</span>
|
||
<span class="k">except</span> <span class="ne">StopIteration</span><span class="p">:</span>
|
||
<span class="n">exhausted</span> <span class="o">=</span> <span class="kc">True</span>
|
||
<span class="k">break</span>
|
||
<span class="n">BLOCK1</span>
|
||
<span class="k">if</span> <span class="n">exhausted</span><span class="p">:</span>
|
||
<span class="n">BLOCK2</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>When the target iterator has a <code class="docutils literal notranslate"><span class="pre">__finish__()</span></code> method, a <code class="docutils literal notranslate"><span class="pre">for</span></code> loop
|
||
will execute as follows:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">itr</span> <span class="o">=</span> <span class="nb">iter</span><span class="p">(</span><span class="n">EXPR1</span><span class="p">)</span>
|
||
<span class="n">exhausted</span> <span class="o">=</span> <span class="kc">False</span>
|
||
<span class="k">try</span><span class="p">:</span>
|
||
<span class="k">while</span> <span class="kc">True</span><span class="p">:</span>
|
||
<span class="k">try</span><span class="p">:</span>
|
||
<span class="n">VAR1</span> <span class="o">=</span> <span class="n">itr</span><span class="o">.</span><span class="n">next</span><span class="p">()</span>
|
||
<span class="k">except</span> <span class="ne">StopIteration</span><span class="p">:</span>
|
||
<span class="n">exhausted</span> <span class="o">=</span> <span class="kc">True</span>
|
||
<span class="k">break</span>
|
||
<span class="n">BLOCK1</span>
|
||
<span class="k">if</span> <span class="n">exhausted</span><span class="p">:</span>
|
||
<span class="n">BLOCK2</span>
|
||
<span class="k">finally</span><span class="p">:</span>
|
||
<span class="n">itr</span><span class="o">.</span><span class="n">__finish__</span><span class="p">()</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The implementation will need to take some care to avoid incurring the
|
||
<code class="docutils literal notranslate"><span class="pre">try</span></code>/<code class="docutils literal notranslate"><span class="pre">finally</span></code> overhead when the iterator does not have a
|
||
<code class="docutils literal notranslate"><span class="pre">__finish__()</span></code> method.</p>
|
||
</section>
|
||
<section id="generator-iterator-finalisation-finish-method">
|
||
<h3><a class="toc-backref" href="#generator-iterator-finalisation-finish-method" role="doc-backlink">Generator iterator finalisation: <code class="docutils literal notranslate"><span class="pre">__finish__()</span></code> method</a></h3>
|
||
<p>When enabled with the appropriate decorator, generators will have a
|
||
<code class="docutils literal notranslate"><span class="pre">__finish__()</span></code> method that raises <code class="docutils literal notranslate"><span class="pre">TerminateIteration</span></code> in the
|
||
internal frame:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">__finish__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
|
||
<span class="k">try</span><span class="p">:</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">_inject_exception</span><span class="p">(</span><span class="n">TerminateIteration</span><span class="p">)</span>
|
||
<span class="k">except</span> <span class="n">TerminateIteration</span><span class="p">:</span>
|
||
<span class="k">pass</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>A decorator (e.g. <code class="docutils literal notranslate"><span class="pre">needs_finish()</span></code>) is required to enable this
|
||
feature, so that existing generators (which are not expecting
|
||
finalisation) continue to work as expected.</p>
|
||
</section>
|
||
<section id="partial-iteration-of-finishable-iterators">
|
||
<h3><a class="toc-backref" href="#partial-iteration-of-finishable-iterators" role="doc-backlink">Partial iteration of finishable iterators</a></h3>
|
||
<p>Partial iteration of a finishable iterator is possible, although it
|
||
requires some care to ensure the iterator is still finalised promptly
|
||
(it was made finishable for a reason!). First, we need a class to
|
||
enable partial iteration of a finishable iterator by hiding the
|
||
iterator’s <code class="docutils literal notranslate"><span class="pre">__finish__()</span></code> method from the <code class="docutils literal notranslate"><span class="pre">for</span></code> loop:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">partial_iter</span><span class="p">(</span><span class="nb">object</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">iterable</span><span class="p">):</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">iter</span> <span class="o">=</span> <span class="nb">iter</span><span class="p">(</span><span class="n">iterable</span><span class="p">)</span>
|
||
|
||
<span class="k">def</span> <span class="fm">__iter__</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="nf">next</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="o">.</span><span class="n">itr</span><span class="o">.</span><span class="n">next</span><span class="p">()</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Secondly, an appropriate statement template is needed to ensure the
|
||
iterator is finished eventually:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@statement_template</span>
|
||
<span class="k">def</span> <span class="nf">finishing</span><span class="p">(</span><span class="n">iterable</span><span class="p">):</span>
|
||
<span class="n">itr</span> <span class="o">=</span> <span class="nb">iter</span><span class="p">(</span><span class="n">iterable</span><span class="p">)</span>
|
||
<span class="n">itr_finish</span> <span class="o">=</span> <span class="nb">getattr</span><span class="p">(</span><span class="n">itr</span><span class="p">,</span> <span class="s2">"__finish__"</span><span class="p">,</span> <span class="kc">None</span><span class="p">)</span>
|
||
<span class="k">if</span> <span class="n">itr_finish</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
|
||
<span class="k">yield</span> <span class="n">itr</span>
|
||
<span class="k">else</span><span class="p">:</span>
|
||
<span class="k">try</span><span class="p">:</span>
|
||
<span class="k">yield</span> <span class="n">partial_iter</span><span class="p">(</span><span class="n">itr</span><span class="p">)</span>
|
||
<span class="k">finally</span><span class="p">:</span>
|
||
<span class="n">itr_finish</span><span class="p">()</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>This can then be used as follows:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">do</span> <span class="n">finishing</span><span class="p">(</span><span class="n">finishable_itr</span><span class="p">)</span> <span class="k">as</span> <span class="n">itr</span><span class="p">:</span>
|
||
<span class="k">for</span> <span class="n">header_item</span> <span class="ow">in</span> <span class="n">itr</span><span class="p">:</span>
|
||
<span class="k">if</span> <span class="n">end_of_header</span><span class="p">(</span><span class="n">header_item</span><span class="p">):</span>
|
||
<span class="k">break</span>
|
||
<span class="c1"># process header item</span>
|
||
<span class="k">for</span> <span class="n">body_item</span> <span class="ow">in</span> <span class="n">itr</span><span class="p">:</span>
|
||
<span class="c1"># process body item</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Note that none of the above is needed for an iterator that is not
|
||
finishable - without a <code class="docutils literal notranslate"><span class="pre">__finish__()</span></code> method, it will not be
|
||
promptly finalised by the <code class="docutils literal notranslate"><span class="pre">for</span></code> loop, and hence inherently allows
|
||
partial iteration. Allowing partial iteration of non-finishable
|
||
iterators as the default behaviour is a key element in keeping this
|
||
addition to the iterator protocol backwards compatible.</p>
|
||
</section>
|
||
</section>
|
||
<section id="acknowledgements">
|
||
<h2><a class="toc-backref" href="#acknowledgements" role="doc-backlink">Acknowledgements</a></h2>
|
||
<p>The acknowledgements section for <a class="pep reference internal" href="../pep-0340/" title="PEP 340 – Anonymous Block Statements">PEP 340</a> applies, since this text grew
|
||
out of the discussion of that PEP, but additional thanks go to Michael
|
||
Hudson, Paul Moore and Guido van Rossum for writing <a class="pep reference internal" href="../pep-0310/" title="PEP 310 – Reliable Acquisition/Release Pairs">PEP 310</a> and PEP
|
||
340 in the first place, and to (in no meaningful order) Fredrik Lundh,
|
||
Phillip J. Eby, Steven Bethard, Josiah Carlson, Greg Ewing, Tim
|
||
Delaney and Arnold deVos for prompting particular ideas that made
|
||
their way into this text.</p>
|
||
</section>
|
||
<section id="references">
|
||
<h2><a class="toc-backref" href="#references" role="doc-backlink">References</a></h2>
|
||
<aside class="footnote-list brackets">
|
||
<aside class="footnote brackets" id="id3" role="doc-footnote">
|
||
<dt class="label" id="id3">[<a href="#id1">1</a>]</dt>
|
||
<dd>A rant against flow control macros
|
||
(<a class="reference external" href="http://blogs.msdn.com/oldnewthing/archive/2005/01/06/347666.aspx">http://blogs.msdn.com/oldnewthing/archive/2005/01/06/347666.aspx</a>)</aside>
|
||
<aside class="footnote brackets" id="id4" role="doc-footnote">
|
||
<dt class="label" id="id4">[<a href="#id2">2</a>]</dt>
|
||
<dd>Why doesn’t C# have a ‘with’ statement?
|
||
(<a class="reference external" href="http://msdn.microsoft.com/vcsharp/programming/language/ask/withstatement/">http://msdn.microsoft.com/vcsharp/programming/language/ask/withstatement/</a>)</aside>
|
||
</aside>
|
||
</section>
|
||
<section id="copyright">
|
||
<h2><a class="toc-backref" href="#copyright" role="doc-backlink">Copyright</a></h2>
|
||
<p>This document has been placed in the public domain.</p>
|
||
</section>
|
||
</section>
|
||
<hr class="docutils" />
|
||
<p>Source: <a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-0346.rst">https://github.com/python/peps/blob/main/peps/pep-0346.rst</a></p>
|
||
<p>Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0346.rst">2023-10-11 12:05:51 GMT</a></p>
|
||
|
||
</article>
|
||
<nav id="pep-sidebar">
|
||
<h2>Contents</h2>
|
||
<ul>
|
||
<li><a class="reference internal" href="#abstract">Abstract</a></li>
|
||
<li><a class="reference internal" href="#author-s-note">Author’s Note</a></li>
|
||
<li><a class="reference internal" href="#introduction">Introduction</a></li>
|
||
<li><a class="reference internal" href="#relationship-with-other-peps">Relationship with other PEPs</a></li>
|
||
<li><a class="reference internal" href="#user-defined-statements">User defined statements</a><ul>
|
||
<li><a class="reference internal" href="#usage-syntax-for-user-defined-statements">Usage syntax for user defined statements</a></li>
|
||
<li><a class="reference internal" href="#semantics-for-user-defined-statements">Semantics for user defined statements</a></li>
|
||
<li><a class="reference internal" href="#statement-template-protocol-enter">Statement template protocol: <code class="docutils literal notranslate"><span class="pre">__enter__</span></code></a></li>
|
||
<li><a class="reference internal" href="#statement-template-protocol-exit">Statement template protocol: <code class="docutils literal notranslate"><span class="pre">__exit__</span></code></a></li>
|
||
<li><a class="reference internal" href="#factoring-out-arbitrary-exception-handling">Factoring out arbitrary exception handling</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#generators">Generators</a><ul>
|
||
<li><a class="reference internal" href="#default-value-for-yield">Default value for <code class="docutils literal notranslate"><span class="pre">yield</span></code></a></li>
|
||
<li><a class="reference internal" href="#template-generator-decorator-statement-template">Template generator decorator: <code class="docutils literal notranslate"><span class="pre">statement_template</span></code></a></li>
|
||
<li><a class="reference internal" href="#template-generator-wrapper-enter-method">Template generator wrapper: <code class="docutils literal notranslate"><span class="pre">__enter__()</span></code> method</a></li>
|
||
<li><a class="reference internal" href="#template-generator-wrapper-exit-method">Template generator wrapper: <code class="docutils literal notranslate"><span class="pre">__exit__()</span></code> method</a></li>
|
||
<li><a class="reference internal" href="#injecting-exceptions-into-generators">Injecting exceptions into generators</a></li>
|
||
<li><a class="reference internal" href="#generator-finalisation">Generator finalisation</a></li>
|
||
<li><a class="reference internal" href="#generator-finalisation-terminateiteration-exception">Generator finalisation: <code class="docutils literal notranslate"><span class="pre">TerminateIteration</span></code> exception</a></li>
|
||
<li><a class="reference internal" href="#generator-finalisation-del-method">Generator finalisation: <code class="docutils literal notranslate"><span class="pre">__del__()</span></code> method</a></li>
|
||
<li><a class="reference internal" href="#deterministic-generator-finalisation">Deterministic generator finalisation</a></li>
|
||
<li><a class="reference internal" href="#generators-as-user-defined-statement-templates">Generators as user defined statement templates</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#examples">Examples</a></li>
|
||
<li><a class="reference internal" href="#open-issues">Open Issues</a></li>
|
||
<li><a class="reference internal" href="#rejected-options">Rejected Options</a><ul>
|
||
<li><a class="reference internal" href="#having-the-basic-construct-be-a-looping-construct">Having the basic construct be a looping construct</a></li>
|
||
<li><a class="reference internal" href="#allowing-statement-templates-to-suppress-exceptions">Allowing statement templates to suppress exceptions</a></li>
|
||
<li><a class="reference internal" href="#differentiating-between-non-exceptional-exits">Differentiating between non-exceptional exits</a></li>
|
||
<li><a class="reference internal" href="#not-injecting-raised-exceptions-into-generators">Not injecting raised exceptions into generators</a></li>
|
||
<li><a class="reference internal" href="#making-all-generators-statement-templates">Making all generators statement templates</a></li>
|
||
<li><a class="reference internal" href="#using-do-as-the-keyword">Using <code class="docutils literal notranslate"><span class="pre">do</span></code> as the keyword</a></li>
|
||
<li><a class="reference internal" href="#not-having-a-keyword">Not having a keyword</a></li>
|
||
<li><a class="reference internal" href="#enhancing-try-statements">Enhancing <code class="docutils literal notranslate"><span class="pre">try</span></code> statements</a></li>
|
||
<li><a class="reference internal" href="#having-the-template-protocol-directly-reflect-try-statements">Having the template protocol directly reflect <code class="docutils literal notranslate"><span class="pre">try</span></code> statements</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#iterator-finalisation-withdrawn">Iterator finalisation (WITHDRAWN)</a><ul>
|
||
<li><a class="reference internal" href="#iterator-protocol-addition-finish">Iterator protocol addition: <code class="docutils literal notranslate"><span class="pre">__finish__</span></code></a></li>
|
||
<li><a class="reference internal" href="#best-effort-finalisation">Best effort finalisation</a></li>
|
||
<li><a class="reference internal" href="#deterministic-finalisation">Deterministic finalisation</a></li>
|
||
<li><a class="reference internal" href="#for-loop-syntax"><code class="docutils literal notranslate"><span class="pre">for</span></code> loop syntax</a></li>
|
||
<li><a class="reference internal" href="#updated-for-loop-semantics">Updated <code class="docutils literal notranslate"><span class="pre">for</span></code> loop semantics</a></li>
|
||
<li><a class="reference internal" href="#generator-iterator-finalisation-finish-method">Generator iterator finalisation: <code class="docutils literal notranslate"><span class="pre">__finish__()</span></code> method</a></li>
|
||
<li><a class="reference internal" href="#partial-iteration-of-finishable-iterators">Partial iteration of finishable iterators</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#acknowledgements">Acknowledgements</a></li>
|
||
<li><a class="reference internal" href="#references">References</a></li>
|
||
<li><a class="reference internal" href="#copyright">Copyright</a></li>
|
||
</ul>
|
||
|
||
<br>
|
||
<a id="source" href="https://github.com/python/peps/blob/main/peps/pep-0346.rst">Page Source (GitHub)</a>
|
||
</nav>
|
||
</section>
|
||
<script src="../_static/colour_scheme.js"></script>
|
||
<script src="../_static/wrap_tables.js"></script>
|
||
<script src="../_static/sticky_banner.js"></script>
|
||
</body>
|
||
</html> |