903 lines
89 KiB
HTML
903 lines
89 KiB
HTML
|
||
<!DOCTYPE html>
|
||
|
||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
<head>
|
||
<meta charset="utf-8" />
|
||
<title>7. Simple statements — Python 3.7.4 documentation</title>
|
||
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
|
||
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
|
||
|
||
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
|
||
<script type="text/javascript" src="../_static/jquery.js"></script>
|
||
<script type="text/javascript" src="../_static/underscore.js"></script>
|
||
<script type="text/javascript" src="../_static/doctools.js"></script>
|
||
<script type="text/javascript" src="../_static/language_data.js"></script>
|
||
|
||
<script type="text/javascript" src="../_static/sidebar.js"></script>
|
||
|
||
<link rel="search" type="application/opensearchdescription+xml"
|
||
title="Search within Python 3.7.4 documentation"
|
||
href="../_static/opensearch.xml"/>
|
||
<link rel="author" title="About these documents" href="../about.html" />
|
||
<link rel="index" title="Index" href="../genindex.html" />
|
||
<link rel="search" title="Search" href="../search.html" />
|
||
<link rel="copyright" title="Copyright" href="../copyright.html" />
|
||
<link rel="next" title="8. Compound statements" href="compound_stmts.html" />
|
||
<link rel="prev" title="6. Expressions" href="expressions.html" />
|
||
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
|
||
<link rel="canonical" href="https://docs.python.org/3/reference/simple_stmts.html" />
|
||
|
||
<script type="text/javascript" src="../_static/copybutton.js"></script>
|
||
<script type="text/javascript" src="../_static/switchers.js"></script>
|
||
|
||
|
||
|
||
<style>
|
||
@media only screen {
|
||
table.full-width-table {
|
||
width: 100%;
|
||
}
|
||
}
|
||
</style>
|
||
|
||
|
||
</head><body>
|
||
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="General Index"
|
||
accesskey="I">index</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python Module Index"
|
||
>modules</a> |</li>
|
||
<li class="right" >
|
||
<a href="compound_stmts.html" title="8. Compound statements"
|
||
accesskey="N">next</a> |</li>
|
||
<li class="right" >
|
||
<a href="expressions.html" title="6. Expressions"
|
||
accesskey="P">previous</a> |</li>
|
||
<li><img src="../_static/py.png" alt=""
|
||
style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li>
|
||
<span class="language_switcher_placeholder">en</span>
|
||
<span class="version_switcher_placeholder">3.7.4</span>
|
||
<a href="../index.html">Documentation </a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">The Python Language Reference</a> »</li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" style="display: none" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="Quick search" type="text" name="q" />
|
||
<input type="submit" value="Go" />
|
||
<input type="hidden" name="check_keywords" value="yes" />
|
||
<input type="hidden" name="area" value="default" />
|
||
</form>
|
||
</div>
|
||
<script type="text/javascript">$('.inline-search').show(0);</script>
|
||
|
|
||
</li>
|
||
|
||
</ul>
|
||
</div>
|
||
|
||
<div class="document">
|
||
<div class="documentwrapper">
|
||
<div class="bodywrapper">
|
||
<div class="body" role="main">
|
||
|
||
<div class="section" id="simple-statements">
|
||
<span id="simple"></span><h1>7. Simple statements<a class="headerlink" href="#simple-statements" title="Permalink to this headline">¶</a></h1>
|
||
<p id="index-0">A simple statement is comprised within a single logical line. Several simple
|
||
statements may occur on a single line separated by semicolons. The syntax for
|
||
simple statements is:</p>
|
||
<pre>
|
||
<strong id="grammar-token-simple-stmt">simple_stmt</strong> ::= <a class="reference internal" href="#grammar-token-expression-stmt"><code class="xref docutils literal notranslate"><span class="pre">expression_stmt</span></code></a>
|
||
| <a class="reference internal" href="#grammar-token-assert-stmt"><code class="xref docutils literal notranslate"><span class="pre">assert_stmt</span></code></a>
|
||
| <a class="reference internal" href="#grammar-token-assignment-stmt"><code class="xref docutils literal notranslate"><span class="pre">assignment_stmt</span></code></a>
|
||
| <a class="reference internal" href="#grammar-token-augmented-assignment-stmt"><code class="xref docutils literal notranslate"><span class="pre">augmented_assignment_stmt</span></code></a>
|
||
| <a class="reference internal" href="#grammar-token-annotated-assignment-stmt"><code class="xref docutils literal notranslate"><span class="pre">annotated_assignment_stmt</span></code></a>
|
||
| <a class="reference internal" href="#grammar-token-pass-stmt"><code class="xref docutils literal notranslate"><span class="pre">pass_stmt</span></code></a>
|
||
| <a class="reference internal" href="#grammar-token-del-stmt"><code class="xref docutils literal notranslate"><span class="pre">del_stmt</span></code></a>
|
||
| <a class="reference internal" href="#grammar-token-return-stmt"><code class="xref docutils literal notranslate"><span class="pre">return_stmt</span></code></a>
|
||
| <a class="reference internal" href="#grammar-token-yield-stmt"><code class="xref docutils literal notranslate"><span class="pre">yield_stmt</span></code></a>
|
||
| <a class="reference internal" href="#grammar-token-raise-stmt"><code class="xref docutils literal notranslate"><span class="pre">raise_stmt</span></code></a>
|
||
| <a class="reference internal" href="#grammar-token-break-stmt"><code class="xref docutils literal notranslate"><span class="pre">break_stmt</span></code></a>
|
||
| <a class="reference internal" href="#grammar-token-continue-stmt"><code class="xref docutils literal notranslate"><span class="pre">continue_stmt</span></code></a>
|
||
| <a class="reference internal" href="#grammar-token-import-stmt"><code class="xref docutils literal notranslate"><span class="pre">import_stmt</span></code></a>
|
||
| <a class="reference internal" href="#grammar-token-future-stmt"><code class="xref docutils literal notranslate"><span class="pre">future_stmt</span></code></a>
|
||
| <a class="reference internal" href="#grammar-token-global-stmt"><code class="xref docutils literal notranslate"><span class="pre">global_stmt</span></code></a>
|
||
| <a class="reference internal" href="#grammar-token-nonlocal-stmt"><code class="xref docutils literal notranslate"><span class="pre">nonlocal_stmt</span></code></a>
|
||
</pre>
|
||
<div class="section" id="expression-statements">
|
||
<span id="exprstmts"></span><h2>7.1. Expression statements<a class="headerlink" href="#expression-statements" title="Permalink to this headline">¶</a></h2>
|
||
<span class="target" id="index-1"></span><p id="index-2">Expression statements are used (mostly interactively) to compute and write a
|
||
value, or (usually) to call a procedure (a function that returns no meaningful
|
||
result; in Python, procedures return the value <code class="docutils literal notranslate"><span class="pre">None</span></code>). Other uses of
|
||
expression statements are allowed and occasionally useful. The syntax for an
|
||
expression statement is:</p>
|
||
<pre>
|
||
<strong id="grammar-token-expression-stmt">expression_stmt</strong> ::= <a class="reference internal" href="expressions.html#grammar-token-starred-expression"><code class="xref docutils literal notranslate"><span class="pre">starred_expression</span></code></a>
|
||
</pre>
|
||
<p>An expression statement evaluates the expression list (which may be a single
|
||
expression).</p>
|
||
<p id="index-3">In interactive mode, if the value is not <code class="docutils literal notranslate"><span class="pre">None</span></code>, it is converted to a string
|
||
using the built-in <a class="reference internal" href="../library/functions.html#repr" title="repr"><code class="xref py py-func docutils literal notranslate"><span class="pre">repr()</span></code></a> function and the resulting string is written to
|
||
standard output on a line by itself (except if the result is <code class="docutils literal notranslate"><span class="pre">None</span></code>, so that
|
||
procedure calls do not cause any output.)</p>
|
||
</div>
|
||
<div class="section" id="assignment-statements">
|
||
<span id="assignment"></span><h2>7.2. Assignment statements<a class="headerlink" href="#assignment-statements" title="Permalink to this headline">¶</a></h2>
|
||
<p id="index-4">Assignment statements are used to (re)bind names to values and to modify
|
||
attributes or items of mutable objects:</p>
|
||
<pre>
|
||
<strong id="grammar-token-assignment-stmt">assignment_stmt</strong> ::= (<a class="reference internal" href="#grammar-token-target-list"><code class="xref docutils literal notranslate"><span class="pre">target_list</span></code></a> "=")+ (<a class="reference internal" href="expressions.html#grammar-token-starred-expression"><code class="xref docutils literal notranslate"><span class="pre">starred_expression</span></code></a> | <a class="reference internal" href="expressions.html#grammar-token-yield-expression"><code class="xref docutils literal notranslate"><span class="pre">yield_expression</span></code></a>)
|
||
<strong id="grammar-token-target-list">target_list </strong> ::= <a class="reference internal" href="#grammar-token-target"><code class="xref docutils literal notranslate"><span class="pre">target</span></code></a> ("," <a class="reference internal" href="#grammar-token-target"><code class="xref docutils literal notranslate"><span class="pre">target</span></code></a>)* [","]
|
||
<strong id="grammar-token-target">target </strong> ::= <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><code class="xref docutils literal notranslate"><span class="pre">identifier</span></code></a>
|
||
| "(" [<a class="reference internal" href="#grammar-token-target-list"><code class="xref docutils literal notranslate"><span class="pre">target_list</span></code></a>] ")"
|
||
| "[" [<a class="reference internal" href="#grammar-token-target-list"><code class="xref docutils literal notranslate"><span class="pre">target_list</span></code></a>] "]"
|
||
| <a class="reference internal" href="expressions.html#grammar-token-attributeref"><code class="xref docutils literal notranslate"><span class="pre">attributeref</span></code></a>
|
||
| <a class="reference internal" href="expressions.html#grammar-token-subscription"><code class="xref docutils literal notranslate"><span class="pre">subscription</span></code></a>
|
||
| <a class="reference internal" href="expressions.html#grammar-token-slicing"><code class="xref docutils literal notranslate"><span class="pre">slicing</span></code></a>
|
||
| "*" <a class="reference internal" href="#grammar-token-target"><code class="xref docutils literal notranslate"><span class="pre">target</span></code></a>
|
||
</pre>
|
||
<p>(See section <a class="reference internal" href="expressions.html#primaries"><span class="std std-ref">Primaries</span></a> for the syntax definitions for <em>attributeref</em>,
|
||
<em>subscription</em>, and <em>slicing</em>.)</p>
|
||
<p>An assignment statement evaluates the expression list (remember that this can be
|
||
a single expression or a comma-separated list, the latter yielding a tuple) and
|
||
assigns the single resulting object to each of the target lists, from left to
|
||
right.</p>
|
||
<p id="index-5">Assignment is defined recursively depending on the form of the target (list).
|
||
When a target is part of a mutable object (an attribute reference, subscription
|
||
or slicing), the mutable object must ultimately perform the assignment and
|
||
decide about its validity, and may raise an exception if the assignment is
|
||
unacceptable. The rules observed by various types and the exceptions raised are
|
||
given with the definition of the object types (see section <a class="reference internal" href="datamodel.html#types"><span class="std std-ref">The standard type hierarchy</span></a>).</p>
|
||
<p id="index-6">Assignment of an object to a target list, optionally enclosed in parentheses or
|
||
square brackets, is recursively defined as follows.</p>
|
||
<ul class="simple">
|
||
<li><p>If the target list is a single target with no trailing comma,
|
||
optionally in parentheses, the object is assigned to that target.</p></li>
|
||
<li><p>Else: The object must be an iterable with the same number of
|
||
items as there are targets in the target list, and the items are assigned,
|
||
from left to right, to the corresponding targets.</p>
|
||
<ul>
|
||
<li><p>If the target list contains one target prefixed with an asterisk, called a
|
||
“starred” target: The object must be an iterable with at least as many items
|
||
as there are targets in the target list, minus one. The first items of the
|
||
iterable are assigned, from left to right, to the targets before the starred
|
||
target. The final items of the iterable are assigned to the targets after
|
||
the starred target. A list of the remaining items in the iterable is then
|
||
assigned to the starred target (the list can be empty).</p></li>
|
||
<li><p>Else: The object must be an iterable with the same number of items as there
|
||
are targets in the target list, and the items are assigned, from left to
|
||
right, to the corresponding targets.</p></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>Assignment of an object to a single target is recursively defined as follows.</p>
|
||
<ul>
|
||
<li><p>If the target is an identifier (name):</p>
|
||
<ul class="simple">
|
||
<li><p>If the name does not occur in a <a class="reference internal" href="#global"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">global</span></code></a> or <a class="reference internal" href="#nonlocal"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">nonlocal</span></code></a>
|
||
statement in the current code block: the name is bound to the object in the
|
||
current local namespace.</p></li>
|
||
<li><p>Otherwise: the name is bound to the object in the global namespace or the
|
||
outer namespace determined by <a class="reference internal" href="#nonlocal"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">nonlocal</span></code></a>, respectively.</p></li>
|
||
</ul>
|
||
<p id="index-7">The name is rebound if it was already bound. This may cause the reference
|
||
count for the object previously bound to the name to reach zero, causing the
|
||
object to be deallocated and its destructor (if it has one) to be called.</p>
|
||
</li>
|
||
<li id="index-8"><p>If the target is an attribute reference: The primary expression in the
|
||
reference is evaluated. It should yield an object with assignable attributes;
|
||
if this is not the case, <a class="reference internal" href="../library/exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> is raised. That object is then
|
||
asked to assign the assigned object to the given attribute; if it cannot
|
||
perform the assignment, it raises an exception (usually but not necessarily
|
||
<a class="reference internal" href="../library/exceptions.html#AttributeError" title="AttributeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">AttributeError</span></code></a>).</p>
|
||
<p id="attr-target-note">Note: If the object is a class instance and the attribute reference occurs on
|
||
both sides of the assignment operator, the RHS expression, <code class="docutils literal notranslate"><span class="pre">a.x</span></code> can access
|
||
either an instance attribute or (if no instance attribute exists) a class
|
||
attribute. The LHS target <code class="docutils literal notranslate"><span class="pre">a.x</span></code> is always set as an instance attribute,
|
||
creating it if necessary. Thus, the two occurrences of <code class="docutils literal notranslate"><span class="pre">a.x</span></code> do not
|
||
necessarily refer to the same attribute: if the RHS expression refers to a
|
||
class attribute, the LHS creates a new instance attribute as the target of the
|
||
assignment:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Cls</span><span class="p">:</span>
|
||
<span class="n">x</span> <span class="o">=</span> <span class="mi">3</span> <span class="c1"># class variable</span>
|
||
<span class="n">inst</span> <span class="o">=</span> <span class="n">Cls</span><span class="p">()</span>
|
||
<span class="n">inst</span><span class="o">.</span><span class="n">x</span> <span class="o">=</span> <span class="n">inst</span><span class="o">.</span><span class="n">x</span> <span class="o">+</span> <span class="mi">1</span> <span class="c1"># writes inst.x as 4 leaving Cls.x as 3</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>This description does not necessarily apply to descriptor attributes, such as
|
||
properties created with <a class="reference internal" href="../library/functions.html#property" title="property"><code class="xref py py-func docutils literal notranslate"><span class="pre">property()</span></code></a>.</p>
|
||
</li>
|
||
<li id="index-9"><p>If the target is a subscription: The primary expression in the reference is
|
||
evaluated. It should yield either a mutable sequence object (such as a list)
|
||
or a mapping object (such as a dictionary). Next, the subscript expression is
|
||
evaluated.</p>
|
||
<p id="index-10">If the primary is a mutable sequence object (such as a list), the subscript
|
||
must yield an integer. If it is negative, the sequence’s length is added to
|
||
it. The resulting value must be a nonnegative integer less than the
|
||
sequence’s length, and the sequence is asked to assign the assigned object to
|
||
its item with that index. If the index is out of range, <a class="reference internal" href="../library/exceptions.html#IndexError" title="IndexError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">IndexError</span></code></a> is
|
||
raised (assignment to a subscripted sequence cannot add new items to a list).</p>
|
||
<p id="index-11">If the primary is a mapping object (such as a dictionary), the subscript must
|
||
have a type compatible with the mapping’s key type, and the mapping is then
|
||
asked to create a key/datum pair which maps the subscript to the assigned
|
||
object. This can either replace an existing key/value pair with the same key
|
||
value, or insert a new key/value pair (if no key with the same value existed).</p>
|
||
<p>For user-defined objects, the <a class="reference internal" href="datamodel.html#object.__setitem__" title="object.__setitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__setitem__()</span></code></a> method is called with
|
||
appropriate arguments.</p>
|
||
</li>
|
||
<li id="index-12"><p>If the target is a slicing: The primary expression in the reference is
|
||
evaluated. It should yield a mutable sequence object (such as a list). The
|
||
assigned object should be a sequence object of the same type. Next, the lower
|
||
and upper bound expressions are evaluated, insofar they are present; defaults
|
||
are zero and the sequence’s length. The bounds should evaluate to integers.
|
||
If either bound is negative, the sequence’s length is added to it. The
|
||
resulting bounds are clipped to lie between zero and the sequence’s length,
|
||
inclusive. Finally, the sequence object is asked to replace the slice with
|
||
the items of the assigned sequence. The length of the slice may be different
|
||
from the length of the assigned sequence, thus changing the length of the
|
||
target sequence, if the target sequence allows it.</p></li>
|
||
</ul>
|
||
<div class="impl-detail compound">
|
||
<p><strong>CPython implementation detail:</strong> In the current implementation, the syntax for targets is taken to be the same
|
||
as for expressions, and invalid syntax is rejected during the code generation
|
||
phase, causing less detailed error messages.</p>
|
||
</div>
|
||
<p>Although the definition of assignment implies that overlaps between the
|
||
left-hand side and the right-hand side are ‘simultaneous’ (for example <code class="docutils literal notranslate"><span class="pre">a,</span> <span class="pre">b</span> <span class="pre">=</span>
|
||
<span class="pre">b,</span> <span class="pre">a</span></code> swaps two variables), overlaps <em>within</em> the collection of assigned-to
|
||
variables occur left-to-right, sometimes resulting in confusion. For instance,
|
||
the following program prints <code class="docutils literal notranslate"><span class="pre">[0,</span> <span class="pre">2]</span></code>:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">x</span> <span class="o">=</span> <span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">]</span>
|
||
<span class="n">i</span> <span class="o">=</span> <span class="mi">0</span>
|
||
<span class="n">i</span><span class="p">,</span> <span class="n">x</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span> <span class="c1"># i is updated, then x[i] is updated</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="n">x</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="admonition seealso">
|
||
<p class="admonition-title">See also</p>
|
||
<dl class="simple">
|
||
<dt><span class="target" id="index-13"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-3132"><strong>PEP 3132</strong></a> - Extended Iterable Unpacking</dt><dd><p>The specification for the <code class="docutils literal notranslate"><span class="pre">*target</span></code> feature.</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
<div class="section" id="augmented-assignment-statements">
|
||
<span id="augassign"></span><h3>7.2.1. Augmented assignment statements<a class="headerlink" href="#augmented-assignment-statements" title="Permalink to this headline">¶</a></h3>
|
||
<p id="index-14">Augmented assignment is the combination, in a single statement, of a binary
|
||
operation and an assignment statement:</p>
|
||
<pre>
|
||
<strong id="grammar-token-augmented-assignment-stmt">augmented_assignment_stmt</strong> ::= <a class="reference internal" href="#grammar-token-augtarget"><code class="xref docutils literal notranslate"><span class="pre">augtarget</span></code></a> <a class="reference internal" href="#grammar-token-augop"><code class="xref docutils literal notranslate"><span class="pre">augop</span></code></a> (<a class="reference internal" href="expressions.html#grammar-token-expression-list"><code class="xref docutils literal notranslate"><span class="pre">expression_list</span></code></a> | <a class="reference internal" href="expressions.html#grammar-token-yield-expression"><code class="xref docutils literal notranslate"><span class="pre">yield_expression</span></code></a>)
|
||
<strong id="grammar-token-augtarget">augtarget </strong> ::= <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><code class="xref docutils literal notranslate"><span class="pre">identifier</span></code></a> | <a class="reference internal" href="expressions.html#grammar-token-attributeref"><code class="xref docutils literal notranslate"><span class="pre">attributeref</span></code></a> | <a class="reference internal" href="expressions.html#grammar-token-subscription"><code class="xref docutils literal notranslate"><span class="pre">subscription</span></code></a> | <a class="reference internal" href="expressions.html#grammar-token-slicing"><code class="xref docutils literal notranslate"><span class="pre">slicing</span></code></a>
|
||
<strong id="grammar-token-augop">augop </strong> ::= "+=" | "-=" | "*=" | "@=" | "/=" | "//=" | "%=" | "**="
|
||
| ">>=" | "<<=" | "&=" | "^=" | "|="
|
||
</pre>
|
||
<p>(See section <a class="reference internal" href="expressions.html#primaries"><span class="std std-ref">Primaries</span></a> for the syntax definitions of the last three
|
||
symbols.)</p>
|
||
<p>An augmented assignment evaluates the target (which, unlike normal assignment
|
||
statements, cannot be an unpacking) and the expression list, performs the binary
|
||
operation specific to the type of assignment on the two operands, and assigns
|
||
the result to the original target. The target is only evaluated once.</p>
|
||
<p>An augmented assignment expression like <code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">+=</span> <span class="pre">1</span></code> can be rewritten as <code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">=</span> <span class="pre">x</span> <span class="pre">+</span>
|
||
<span class="pre">1</span></code> to achieve a similar, but not exactly equal effect. In the augmented
|
||
version, <code class="docutils literal notranslate"><span class="pre">x</span></code> is only evaluated once. Also, when possible, the actual operation
|
||
is performed <em>in-place</em>, meaning that rather than creating a new object and
|
||
assigning that to the target, the old object is modified instead.</p>
|
||
<p>Unlike normal assignments, augmented assignments evaluate the left-hand side
|
||
<em>before</em> evaluating the right-hand side. For example, <code class="docutils literal notranslate"><span class="pre">a[i]</span> <span class="pre">+=</span> <span class="pre">f(x)</span></code> first
|
||
looks-up <code class="docutils literal notranslate"><span class="pre">a[i]</span></code>, then it evaluates <code class="docutils literal notranslate"><span class="pre">f(x)</span></code> and performs the addition, and
|
||
lastly, it writes the result back to <code class="docutils literal notranslate"><span class="pre">a[i]</span></code>.</p>
|
||
<p>With the exception of assigning to tuples and multiple targets in a single
|
||
statement, the assignment done by augmented assignment statements is handled the
|
||
same way as normal assignments. Similarly, with the exception of the possible
|
||
<em>in-place</em> behavior, the binary operation performed by augmented assignment is
|
||
the same as the normal binary operations.</p>
|
||
<p>For targets which are attribute references, the same <a class="reference internal" href="#attr-target-note"><span class="std std-ref">caveat about class
|
||
and instance attributes</span></a> applies as for regular assignments.</p>
|
||
</div>
|
||
<div class="section" id="annotated-assignment-statements">
|
||
<span id="annassign"></span><h3>7.2.2. Annotated assignment statements<a class="headerlink" href="#annotated-assignment-statements" title="Permalink to this headline">¶</a></h3>
|
||
<p id="index-15"><a class="reference internal" href="../glossary.html#term-variable-annotation"><span class="xref std std-term">Annotation</span></a> assignment is the combination, in a single
|
||
statement, of a variable or attribute annotation and an optional assignment statement:</p>
|
||
<pre>
|
||
<strong id="grammar-token-annotated-assignment-stmt">annotated_assignment_stmt</strong> ::= <a class="reference internal" href="#grammar-token-augtarget"><code class="xref docutils literal notranslate"><span class="pre">augtarget</span></code></a> ":" <a class="reference internal" href="expressions.html#grammar-token-expression"><code class="xref docutils literal notranslate"><span class="pre">expression</span></code></a> ["=" <a class="reference internal" href="expressions.html#grammar-token-expression"><code class="xref docutils literal notranslate"><span class="pre">expression</span></code></a>]
|
||
</pre>
|
||
<p>The difference from normal <a class="reference internal" href="#assignment"><span class="std std-ref">Assignment statements</span></a> is that only single target and
|
||
only single right hand side value is allowed.</p>
|
||
<p>For simple names as assignment targets, if in class or module scope,
|
||
the annotations are evaluated and stored in a special class or module
|
||
attribute <code class="xref py py-attr docutils literal notranslate"><span class="pre">__annotations__</span></code>
|
||
that is a dictionary mapping from variable names (mangled if private) to
|
||
evaluated annotations. This attribute is writable and is automatically
|
||
created at the start of class or module body execution, if annotations
|
||
are found statically.</p>
|
||
<p>For expressions as assignment targets, the annotations are evaluated if
|
||
in class or module scope, but not stored.</p>
|
||
<p>If a name is annotated in a function scope, then this name is local for
|
||
that scope. Annotations are never evaluated and stored in function scopes.</p>
|
||
<p>If the right hand side is present, an annotated
|
||
assignment performs the actual assignment before evaluating annotations
|
||
(where applicable). If the right hand side is not present for an expression
|
||
target, then the interpreter evaluates the target except for the last
|
||
<a class="reference internal" href="datamodel.html#object.__setitem__" title="object.__setitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__setitem__()</span></code></a> or <a class="reference internal" href="datamodel.html#object.__setattr__" title="object.__setattr__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__setattr__()</span></code></a> call.</p>
|
||
<div class="admonition seealso">
|
||
<p class="admonition-title">See also</p>
|
||
<dl class="simple">
|
||
<dt><span class="target" id="index-16"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0526"><strong>PEP 526</strong></a> - Syntax for Variable Annotations</dt><dd><p>The proposal that added syntax for annotating the types of variables
|
||
(including class variables and instance variables), instead of expressing
|
||
them through comments.</p>
|
||
</dd>
|
||
<dt><span class="target" id="index-17"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0484"><strong>PEP 484</strong></a> - Type hints</dt><dd><p>The proposal that added the <a class="reference internal" href="../library/typing.html#module-typing" title="typing: Support for type hints (see PEP 484)."><code class="xref py py-mod docutils literal notranslate"><span class="pre">typing</span></code></a> module to provide a standard
|
||
syntax for type annotations that can be used in static analysis tools and
|
||
IDEs.</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="the-assert-statement">
|
||
<span id="assert"></span><h2>7.3. The <code class="xref std std-keyword docutils literal notranslate"><span class="pre">assert</span></code> statement<a class="headerlink" href="#the-assert-statement" title="Permalink to this headline">¶</a></h2>
|
||
<p id="index-18">Assert statements are a convenient way to insert debugging assertions into a
|
||
program:</p>
|
||
<pre>
|
||
<strong id="grammar-token-assert-stmt">assert_stmt</strong> ::= "assert" <a class="reference internal" href="expressions.html#grammar-token-expression"><code class="xref docutils literal notranslate"><span class="pre">expression</span></code></a> ["," <a class="reference internal" href="expressions.html#grammar-token-expression"><code class="xref docutils literal notranslate"><span class="pre">expression</span></code></a>]
|
||
</pre>
|
||
<p>The simple form, <code class="docutils literal notranslate"><span class="pre">assert</span> <span class="pre">expression</span></code>, is equivalent to</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="n">__debug__</span><span class="p">:</span>
|
||
<span class="k">if</span> <span class="ow">not</span> <span class="n">expression</span><span class="p">:</span> <span class="k">raise</span> <span class="ne">AssertionError</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The extended form, <code class="docutils literal notranslate"><span class="pre">assert</span> <span class="pre">expression1,</span> <span class="pre">expression2</span></code>, is equivalent to</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="n">__debug__</span><span class="p">:</span>
|
||
<span class="k">if</span> <span class="ow">not</span> <span class="n">expression1</span><span class="p">:</span> <span class="k">raise</span> <span class="ne">AssertionError</span><span class="p">(</span><span class="n">expression2</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p id="index-19">These equivalences assume that <a class="reference internal" href="../library/constants.html#__debug__" title="__debug__"><code class="xref py py-const docutils literal notranslate"><span class="pre">__debug__</span></code></a> and <a class="reference internal" href="../library/exceptions.html#AssertionError" title="AssertionError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">AssertionError</span></code></a> refer to
|
||
the built-in variables with those names. In the current implementation, the
|
||
built-in variable <a class="reference internal" href="../library/constants.html#__debug__" title="__debug__"><code class="xref py py-const docutils literal notranslate"><span class="pre">__debug__</span></code></a> is <code class="docutils literal notranslate"><span class="pre">True</span></code> under normal circumstances,
|
||
<code class="docutils literal notranslate"><span class="pre">False</span></code> when optimization is requested (command line option <a class="reference internal" href="../using/cmdline.html#cmdoption-o"><code class="xref std std-option docutils literal notranslate"><span class="pre">-O</span></code></a>). The current
|
||
code generator emits no code for an assert statement when optimization is
|
||
requested at compile time. Note that it is unnecessary to include the source
|
||
code for the expression that failed in the error message; it will be displayed
|
||
as part of the stack trace.</p>
|
||
<p>Assignments to <a class="reference internal" href="../library/constants.html#__debug__" title="__debug__"><code class="xref py py-const docutils literal notranslate"><span class="pre">__debug__</span></code></a> are illegal. The value for the built-in variable
|
||
is determined when the interpreter starts.</p>
|
||
</div>
|
||
<div class="section" id="the-pass-statement">
|
||
<span id="pass"></span><h2>7.4. The <code class="xref std std-keyword docutils literal notranslate"><span class="pre">pass</span></code> statement<a class="headerlink" href="#the-pass-statement" title="Permalink to this headline">¶</a></h2>
|
||
<pre id="index-20">
|
||
<strong id="grammar-token-pass-stmt">pass_stmt</strong> ::= "pass"
|
||
</pre>
|
||
<p><a class="reference internal" href="#pass"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">pass</span></code></a> is a null operation — when it is executed, nothing happens.
|
||
It is useful as a placeholder when a statement is required syntactically, but no
|
||
code needs to be executed, for example:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">f</span><span class="p">(</span><span class="n">arg</span><span class="p">):</span> <span class="k">pass</span> <span class="c1"># a function that does nothing (yet)</span>
|
||
|
||
<span class="k">class</span> <span class="nc">C</span><span class="p">:</span> <span class="k">pass</span> <span class="c1"># a class with no methods (yet)</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="the-del-statement">
|
||
<span id="del"></span><h2>7.5. The <code class="xref std std-keyword docutils literal notranslate"><span class="pre">del</span></code> statement<a class="headerlink" href="#the-del-statement" title="Permalink to this headline">¶</a></h2>
|
||
<pre id="index-21">
|
||
<strong id="grammar-token-del-stmt">del_stmt</strong> ::= "del" <a class="reference internal" href="#grammar-token-target-list"><code class="xref docutils literal notranslate"><span class="pre">target_list</span></code></a>
|
||
</pre>
|
||
<p>Deletion is recursively defined very similar to the way assignment is defined.
|
||
Rather than spelling it out in full details, here are some hints.</p>
|
||
<p>Deletion of a target list recursively deletes each target, from left to right.</p>
|
||
<p id="index-22">Deletion of a name removes the binding of that name from the local or global
|
||
namespace, depending on whether the name occurs in a <a class="reference internal" href="#global"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">global</span></code></a> statement
|
||
in the same code block. If the name is unbound, a <a class="reference internal" href="../library/exceptions.html#NameError" title="NameError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">NameError</span></code></a> exception
|
||
will be raised.</p>
|
||
<p id="index-23">Deletion of attribute references, subscriptions and slicings is passed to the
|
||
primary object involved; deletion of a slicing is in general equivalent to
|
||
assignment of an empty slice of the right type (but even this is determined by
|
||
the sliced object).</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.2: </span>Previously it was illegal to delete a name from the local namespace if it
|
||
occurs as a free variable in a nested block.</p>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="the-return-statement">
|
||
<span id="return"></span><h2>7.6. The <code class="xref std std-keyword docutils literal notranslate"><span class="pre">return</span></code> statement<a class="headerlink" href="#the-return-statement" title="Permalink to this headline">¶</a></h2>
|
||
<pre id="index-24">
|
||
<strong id="grammar-token-return-stmt">return_stmt</strong> ::= "return" [<a class="reference internal" href="expressions.html#grammar-token-expression-list"><code class="xref docutils literal notranslate"><span class="pre">expression_list</span></code></a>]
|
||
</pre>
|
||
<p><a class="reference internal" href="#return"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">return</span></code></a> may only occur syntactically nested in a function definition,
|
||
not within a nested class definition.</p>
|
||
<p>If an expression list is present, it is evaluated, else <code class="docutils literal notranslate"><span class="pre">None</span></code> is substituted.</p>
|
||
<p><a class="reference internal" href="#return"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">return</span></code></a> leaves the current function call with the expression list (or
|
||
<code class="docutils literal notranslate"><span class="pre">None</span></code>) as return value.</p>
|
||
<p id="index-25">When <a class="reference internal" href="#return"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">return</span></code></a> passes control out of a <a class="reference internal" href="compound_stmts.html#try"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">try</span></code></a> statement with a
|
||
<a class="reference internal" href="compound_stmts.html#finally"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">finally</span></code></a> clause, that <code class="xref std std-keyword docutils literal notranslate"><span class="pre">finally</span></code> clause is executed before
|
||
really leaving the function.</p>
|
||
<p>In a generator function, the <a class="reference internal" href="#return"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">return</span></code></a> statement indicates that the
|
||
generator is done and will cause <a class="reference internal" href="../library/exceptions.html#StopIteration" title="StopIteration"><code class="xref py py-exc docutils literal notranslate"><span class="pre">StopIteration</span></code></a> to be raised. The returned
|
||
value (if any) is used as an argument to construct <a class="reference internal" href="../library/exceptions.html#StopIteration" title="StopIteration"><code class="xref py py-exc docutils literal notranslate"><span class="pre">StopIteration</span></code></a> and
|
||
becomes the <code class="xref py py-attr docutils literal notranslate"><span class="pre">StopIteration.value</span></code> attribute.</p>
|
||
<p>In an asynchronous generator function, an empty <a class="reference internal" href="#return"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">return</span></code></a> statement
|
||
indicates that the asynchronous generator is done and will cause
|
||
<a class="reference internal" href="../library/exceptions.html#StopAsyncIteration" title="StopAsyncIteration"><code class="xref py py-exc docutils literal notranslate"><span class="pre">StopAsyncIteration</span></code></a> to be raised. A non-empty <code class="xref std std-keyword docutils literal notranslate"><span class="pre">return</span></code>
|
||
statement is a syntax error in an asynchronous generator function.</p>
|
||
</div>
|
||
<div class="section" id="the-yield-statement">
|
||
<span id="yield"></span><h2>7.7. The <code class="xref std std-keyword docutils literal notranslate"><span class="pre">yield</span></code> statement<a class="headerlink" href="#the-yield-statement" title="Permalink to this headline">¶</a></h2>
|
||
<pre id="index-26">
|
||
<strong id="grammar-token-yield-stmt">yield_stmt</strong> ::= <a class="reference internal" href="expressions.html#grammar-token-yield-expression"><code class="xref docutils literal notranslate"><span class="pre">yield_expression</span></code></a>
|
||
</pre>
|
||
<p>A <a class="reference internal" href="#yield"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">yield</span></code></a> statement is semantically equivalent to a <a class="reference internal" href="expressions.html#yieldexpr"><span class="std std-ref">yield
|
||
expression</span></a>. The yield statement can be used to omit the parentheses
|
||
that would otherwise be required in the equivalent yield expression
|
||
statement. For example, the yield statements</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">yield</span> <span class="o"><</span><span class="n">expr</span><span class="o">></span>
|
||
<span class="k">yield from</span> <span class="o"><</span><span class="n">expr</span><span class="o">></span>
|
||
</pre></div>
|
||
</div>
|
||
<p>are equivalent to the yield expression statements</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="p">(</span><span class="k">yield</span> <span class="o"><</span><span class="n">expr</span><span class="o">></span><span class="p">)</span>
|
||
<span class="p">(</span><span class="k">yield from</span> <span class="o"><</span><span class="n">expr</span><span class="o">></span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Yield expressions and statements are only used when defining a <a class="reference internal" href="../glossary.html#term-generator"><span class="xref std std-term">generator</span></a>
|
||
function, and are only used in the body of the generator function. Using yield
|
||
in a function definition is sufficient to cause that definition to create a
|
||
generator function instead of a normal function.</p>
|
||
<p>For full details of <a class="reference internal" href="#yield"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">yield</span></code></a> semantics, refer to the
|
||
<a class="reference internal" href="expressions.html#yieldexpr"><span class="std std-ref">Yield expressions</span></a> section.</p>
|
||
</div>
|
||
<div class="section" id="the-raise-statement">
|
||
<span id="raise"></span><h2>7.8. The <code class="xref std std-keyword docutils literal notranslate"><span class="pre">raise</span></code> statement<a class="headerlink" href="#the-raise-statement" title="Permalink to this headline">¶</a></h2>
|
||
<pre id="index-27">
|
||
<strong id="grammar-token-raise-stmt">raise_stmt</strong> ::= "raise" [<a class="reference internal" href="expressions.html#grammar-token-expression"><code class="xref docutils literal notranslate"><span class="pre">expression</span></code></a> ["from" <a class="reference internal" href="expressions.html#grammar-token-expression"><code class="xref docutils literal notranslate"><span class="pre">expression</span></code></a>]]
|
||
</pre>
|
||
<p>If no expressions are present, <a class="reference internal" href="#raise"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">raise</span></code></a> re-raises the last exception
|
||
that was active in the current scope. If no exception is active in the current
|
||
scope, a <a class="reference internal" href="../library/exceptions.html#RuntimeError" title="RuntimeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">RuntimeError</span></code></a> exception is raised indicating that this is an
|
||
error.</p>
|
||
<p>Otherwise, <a class="reference internal" href="#raise"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">raise</span></code></a> evaluates the first expression as the exception
|
||
object. It must be either a subclass or an instance of <a class="reference internal" href="../library/exceptions.html#BaseException" title="BaseException"><code class="xref py py-class docutils literal notranslate"><span class="pre">BaseException</span></code></a>.
|
||
If it is a class, the exception instance will be obtained when needed by
|
||
instantiating the class with no arguments.</p>
|
||
<p>The <em class="dfn">type</em> of the exception is the exception instance’s class, the
|
||
<em class="dfn">value</em> is the instance itself.</p>
|
||
<p id="index-28">A traceback object is normally created automatically when an exception is raised
|
||
and attached to it as the <code class="xref py py-attr docutils literal notranslate"><span class="pre">__traceback__</span></code> attribute, which is writable.
|
||
You can create an exception and set your own traceback in one step using the
|
||
<code class="xref py py-meth docutils literal notranslate"><span class="pre">with_traceback()</span></code> exception method (which returns the same exception
|
||
instance, with its traceback set to its argument), like so:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">raise</span> <span class="ne">Exception</span><span class="p">(</span><span class="s2">"foo occurred"</span><span class="p">)</span><span class="o">.</span><span class="n">with_traceback</span><span class="p">(</span><span class="n">tracebackobj</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p id="index-29">The <code class="docutils literal notranslate"><span class="pre">from</span></code> clause is used for exception chaining: if given, the second
|
||
<em>expression</em> must be another exception class or instance, which will then be
|
||
attached to the raised exception as the <code class="xref py py-attr docutils literal notranslate"><span class="pre">__cause__</span></code> attribute (which is
|
||
writable). If the raised exception is not handled, both exceptions will be
|
||
printed:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="k">try</span><span class="p">:</span>
|
||
<span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="mi">1</span> <span class="o">/</span> <span class="mi">0</span><span class="p">)</span>
|
||
<span class="gp">... </span><span class="k">except</span> <span class="ne">Exception</span> <span class="k">as</span> <span class="n">exc</span><span class="p">:</span>
|
||
<span class="gp">... </span> <span class="k">raise</span> <span class="ne">RuntimeError</span><span class="p">(</span><span class="s2">"Something bad happened"</span><span class="p">)</span> <span class="kn">from</span> <span class="nn">exc</span>
|
||
<span class="gp">...</span>
|
||
<span class="gt">Traceback (most recent call last):</span>
|
||
File <span class="nb">"<stdin>"</span>, line <span class="m">2</span>, in <span class="n"><module></span>
|
||
<span class="gr">ZeroDivisionError</span>: <span class="n">division by zero</span>
|
||
|
||
<span class="go">The above exception was the direct cause of the following exception:</span>
|
||
|
||
<span class="gt">Traceback (most recent call last):</span>
|
||
File <span class="nb">"<stdin>"</span>, line <span class="m">4</span>, in <span class="n"><module></span>
|
||
<span class="gr">RuntimeError</span>: <span class="n">Something bad happened</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>A similar mechanism works implicitly if an exception is raised inside an
|
||
exception handler or a <a class="reference internal" href="compound_stmts.html#finally"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">finally</span></code></a> clause: the previous exception is then
|
||
attached as the new exception’s <code class="xref py py-attr docutils literal notranslate"><span class="pre">__context__</span></code> attribute:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="k">try</span><span class="p">:</span>
|
||
<span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="mi">1</span> <span class="o">/</span> <span class="mi">0</span><span class="p">)</span>
|
||
<span class="gp">... </span><span class="k">except</span><span class="p">:</span>
|
||
<span class="gp">... </span> <span class="k">raise</span> <span class="ne">RuntimeError</span><span class="p">(</span><span class="s2">"Something bad happened"</span><span class="p">)</span>
|
||
<span class="gp">...</span>
|
||
<span class="gt">Traceback (most recent call last):</span>
|
||
File <span class="nb">"<stdin>"</span>, line <span class="m">2</span>, in <span class="n"><module></span>
|
||
<span class="gr">ZeroDivisionError</span>: <span class="n">division by zero</span>
|
||
|
||
<span class="go">During handling of the above exception, another exception occurred:</span>
|
||
|
||
<span class="gt">Traceback (most recent call last):</span>
|
||
File <span class="nb">"<stdin>"</span>, line <span class="m">4</span>, in <span class="n"><module></span>
|
||
<span class="gr">RuntimeError</span>: <span class="n">Something bad happened</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Exception chaining can be explicitly suppressed by specifying <a class="reference internal" href="../library/constants.html#None" title="None"><code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code></a> in
|
||
the <code class="docutils literal notranslate"><span class="pre">from</span></code> clause:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="k">try</span><span class="p">:</span>
|
||
<span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="mi">1</span> <span class="o">/</span> <span class="mi">0</span><span class="p">)</span>
|
||
<span class="gp">... </span><span class="k">except</span><span class="p">:</span>
|
||
<span class="gp">... </span> <span class="k">raise</span> <span class="ne">RuntimeError</span><span class="p">(</span><span class="s2">"Something bad happened"</span><span class="p">)</span> <span class="kn">from</span> <span class="nn">None</span>
|
||
<span class="gp">...</span>
|
||
<span class="gt">Traceback (most recent call last):</span>
|
||
File <span class="nb">"<stdin>"</span>, line <span class="m">4</span>, in <span class="n"><module></span>
|
||
<span class="gr">RuntimeError</span>: <span class="n">Something bad happened</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Additional information on exceptions can be found in section <a class="reference internal" href="executionmodel.html#exceptions"><span class="std std-ref">Exceptions</span></a>,
|
||
and information about handling exceptions is in section <a class="reference internal" href="compound_stmts.html#try"><span class="std std-ref">The try statement</span></a>.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.3: </span><a class="reference internal" href="../library/constants.html#None" title="None"><code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code></a> is now permitted as <code class="docutils literal notranslate"><span class="pre">Y</span></code> in <code class="docutils literal notranslate"><span class="pre">raise</span> <span class="pre">X</span> <span class="pre">from</span> <span class="pre">Y</span></code>.</p>
|
||
</div>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3: </span>The <code class="docutils literal notranslate"><span class="pre">__suppress_context__</span></code> attribute to suppress automatic display of the
|
||
exception context.</p>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="the-break-statement">
|
||
<span id="break"></span><h2>7.9. The <code class="xref std std-keyword docutils literal notranslate"><span class="pre">break</span></code> statement<a class="headerlink" href="#the-break-statement" title="Permalink to this headline">¶</a></h2>
|
||
<pre id="index-30">
|
||
<strong id="grammar-token-break-stmt">break_stmt</strong> ::= "break"
|
||
</pre>
|
||
<p><a class="reference internal" href="#break"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">break</span></code></a> may only occur syntactically nested in a <a class="reference internal" href="compound_stmts.html#for"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">for</span></code></a> or
|
||
<a class="reference internal" href="compound_stmts.html#while"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">while</span></code></a> loop, but not nested in a function or class definition within
|
||
that loop.</p>
|
||
<p id="index-31">It terminates the nearest enclosing loop, skipping the optional <code class="xref std std-keyword docutils literal notranslate"><span class="pre">else</span></code>
|
||
clause if the loop has one.</p>
|
||
<p>If a <a class="reference internal" href="compound_stmts.html#for"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">for</span></code></a> loop is terminated by <a class="reference internal" href="#break"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">break</span></code></a>, the loop control
|
||
target keeps its current value.</p>
|
||
<p id="index-32">When <a class="reference internal" href="#break"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">break</span></code></a> passes control out of a <a class="reference internal" href="compound_stmts.html#try"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">try</span></code></a> statement with a
|
||
<a class="reference internal" href="compound_stmts.html#finally"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">finally</span></code></a> clause, that <code class="xref std std-keyword docutils literal notranslate"><span class="pre">finally</span></code> clause is executed before
|
||
really leaving the loop.</p>
|
||
</div>
|
||
<div class="section" id="the-continue-statement">
|
||
<span id="continue"></span><h2>7.10. The <code class="xref std std-keyword docutils literal notranslate"><span class="pre">continue</span></code> statement<a class="headerlink" href="#the-continue-statement" title="Permalink to this headline">¶</a></h2>
|
||
<pre id="index-33">
|
||
<strong id="grammar-token-continue-stmt">continue_stmt</strong> ::= "continue"
|
||
</pre>
|
||
<p><a class="reference internal" href="#continue"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">continue</span></code></a> may only occur syntactically nested in a <a class="reference internal" href="compound_stmts.html#for"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">for</span></code></a> or
|
||
<a class="reference internal" href="compound_stmts.html#while"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">while</span></code></a> loop, but not nested in a function or class definition or
|
||
<a class="reference internal" href="compound_stmts.html#finally"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">finally</span></code></a> clause within that loop. It continues with the next
|
||
cycle of the nearest enclosing loop.</p>
|
||
<p>When <a class="reference internal" href="#continue"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">continue</span></code></a> passes control out of a <a class="reference internal" href="compound_stmts.html#try"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">try</span></code></a> statement with a
|
||
<a class="reference internal" href="compound_stmts.html#finally"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">finally</span></code></a> clause, that <code class="xref std std-keyword docutils literal notranslate"><span class="pre">finally</span></code> clause is executed before
|
||
really starting the next loop cycle.</p>
|
||
</div>
|
||
<div class="section" id="the-import-statement">
|
||
<span id="from"></span><span id="import"></span><h2>7.11. The <code class="xref std std-keyword docutils literal notranslate"><span class="pre">import</span></code> statement<a class="headerlink" href="#the-import-statement" title="Permalink to this headline">¶</a></h2>
|
||
<pre id="index-34">
|
||
<strong id="grammar-token-import-stmt">import_stmt </strong> ::= "import" <a class="reference internal" href="#grammar-token-module"><code class="xref docutils literal notranslate"><span class="pre">module</span></code></a> ["as" <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><code class="xref docutils literal notranslate"><span class="pre">identifier</span></code></a>] ("," <a class="reference internal" href="#grammar-token-module"><code class="xref docutils literal notranslate"><span class="pre">module</span></code></a> ["as" <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><code class="xref docutils literal notranslate"><span class="pre">identifier</span></code></a>])*
|
||
| "from" <a class="reference internal" href="#grammar-token-relative-module"><code class="xref docutils literal notranslate"><span class="pre">relative_module</span></code></a> "import" <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><code class="xref docutils literal notranslate"><span class="pre">identifier</span></code></a> ["as" <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><code class="xref docutils literal notranslate"><span class="pre">identifier</span></code></a>]
|
||
("," <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><code class="xref docutils literal notranslate"><span class="pre">identifier</span></code></a> ["as" <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><code class="xref docutils literal notranslate"><span class="pre">identifier</span></code></a>])*
|
||
| "from" <a class="reference internal" href="#grammar-token-relative-module"><code class="xref docutils literal notranslate"><span class="pre">relative_module</span></code></a> "import" "(" <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><code class="xref docutils literal notranslate"><span class="pre">identifier</span></code></a> ["as" <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><code class="xref docutils literal notranslate"><span class="pre">identifier</span></code></a>]
|
||
("," <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><code class="xref docutils literal notranslate"><span class="pre">identifier</span></code></a> ["as" <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><code class="xref docutils literal notranslate"><span class="pre">identifier</span></code></a>])* [","] ")"
|
||
| "from" <a class="reference internal" href="#grammar-token-module"><code class="xref docutils literal notranslate"><span class="pre">module</span></code></a> "import" "*"
|
||
<strong id="grammar-token-module">module </strong> ::= (<a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><code class="xref docutils literal notranslate"><span class="pre">identifier</span></code></a> ".")* <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><code class="xref docutils literal notranslate"><span class="pre">identifier</span></code></a>
|
||
<strong id="grammar-token-relative-module">relative_module</strong> ::= "."* <a class="reference internal" href="#grammar-token-module"><code class="xref docutils literal notranslate"><span class="pre">module</span></code></a> | "."+
|
||
</pre>
|
||
<p>The basic import statement (no <a class="reference internal" href="#from"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">from</span></code></a> clause) is executed in two
|
||
steps:</p>
|
||
<ol class="arabic simple">
|
||
<li><p>find a module, loading and initializing it if necessary</p></li>
|
||
<li><p>define a name or names in the local namespace for the scope where
|
||
the <a class="reference internal" href="#import"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">import</span></code></a> statement occurs.</p></li>
|
||
</ol>
|
||
<p>When the statement contains multiple clauses (separated by
|
||
commas) the two steps are carried out separately for each clause, just
|
||
as though the clauses had been separated out into individual import
|
||
statements.</p>
|
||
<p>The details of the first step, finding and loading modules are described in
|
||
greater detail in the section on the <a class="reference internal" href="import.html#importsystem"><span class="std std-ref">import system</span></a>,
|
||
which also describes the various types of packages and modules that can
|
||
be imported, as well as all the hooks that can be used to customize
|
||
the import system. Note that failures in this step may indicate either
|
||
that the module could not be located, <em>or</em> that an error occurred while
|
||
initializing the module, which includes execution of the module’s code.</p>
|
||
<p>If the requested module is retrieved successfully, it will be made
|
||
available in the local namespace in one of three ways:</p>
|
||
<ul class="simple" id="index-35">
|
||
<li><p>If the module name is followed by <code class="xref std std-keyword docutils literal notranslate"><span class="pre">as</span></code>, then the name
|
||
following <code class="xref std std-keyword docutils literal notranslate"><span class="pre">as</span></code> is bound directly to the imported module.</p></li>
|
||
<li><p>If no other name is specified, and the module being imported is a top
|
||
level module, the module’s name is bound in the local namespace as a
|
||
reference to the imported module</p></li>
|
||
<li><p>If the module being imported is <em>not</em> a top level module, then the name
|
||
of the top level package that contains the module is bound in the local
|
||
namespace as a reference to the top level package. The imported module
|
||
must be accessed using its full qualified name rather than directly</p></li>
|
||
</ul>
|
||
<p id="index-36">The <a class="reference internal" href="#from"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">from</span></code></a> form uses a slightly more complex process:</p>
|
||
<ol class="arabic simple">
|
||
<li><p>find the module specified in the <a class="reference internal" href="#from"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">from</span></code></a> clause, loading and
|
||
initializing it if necessary;</p></li>
|
||
<li><p>for each of the identifiers specified in the <a class="reference internal" href="#import"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">import</span></code></a> clauses:</p>
|
||
<ol class="arabic simple">
|
||
<li><p>check if the imported module has an attribute by that name</p></li>
|
||
<li><p>if not, attempt to import a submodule with that name and then
|
||
check the imported module again for that attribute</p></li>
|
||
<li><p>if the attribute is not found, <a class="reference internal" href="../library/exceptions.html#ImportError" title="ImportError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ImportError</span></code></a> is raised.</p></li>
|
||
<li><p>otherwise, a reference to that value is stored in the local namespace,
|
||
using the name in the <code class="xref std std-keyword docutils literal notranslate"><span class="pre">as</span></code> clause if it is present,
|
||
otherwise using the attribute name</p></li>
|
||
</ol>
|
||
</li>
|
||
</ol>
|
||
<p>Examples:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">foo</span> <span class="c1"># foo imported and bound locally</span>
|
||
<span class="kn">import</span> <span class="nn">foo.bar.baz</span> <span class="c1"># foo.bar.baz imported, foo bound locally</span>
|
||
<span class="kn">import</span> <span class="nn">foo.bar.baz</span> <span class="k">as</span> <span class="nn">fbb</span> <span class="c1"># foo.bar.baz imported and bound as fbb</span>
|
||
<span class="kn">from</span> <span class="nn">foo.bar</span> <span class="k">import</span> <span class="n">baz</span> <span class="c1"># foo.bar.baz imported and bound as baz</span>
|
||
<span class="kn">from</span> <span class="nn">foo</span> <span class="k">import</span> <span class="n">attr</span> <span class="c1"># foo imported and foo.attr bound as attr</span>
|
||
</pre></div>
|
||
</div>
|
||
<p id="index-37">If the list of identifiers is replaced by a star (<code class="docutils literal notranslate"><span class="pre">'*'</span></code>), all public
|
||
names defined in the module are bound in the local namespace for the scope
|
||
where the <a class="reference internal" href="#import"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">import</span></code></a> statement occurs.</p>
|
||
<p id="index-38">The <em>public names</em> defined by a module are determined by checking the module’s
|
||
namespace for a variable named <code class="docutils literal notranslate"><span class="pre">__all__</span></code>; if defined, it must be a sequence
|
||
of strings which are names defined or imported by that module. The names
|
||
given in <code class="docutils literal notranslate"><span class="pre">__all__</span></code> are all considered public and are required to exist. If
|
||
<code class="docutils literal notranslate"><span class="pre">__all__</span></code> is not defined, the set of public names includes all names found
|
||
in the module’s namespace which do not begin with an underscore character
|
||
(<code class="docutils literal notranslate"><span class="pre">'_'</span></code>). <code class="docutils literal notranslate"><span class="pre">__all__</span></code> should contain the entire public API. It is intended
|
||
to avoid accidentally exporting items that are not part of the API (such as
|
||
library modules which were imported and used within the module).</p>
|
||
<p>The wild card form of import — <code class="docutils literal notranslate"><span class="pre">from</span> <span class="pre">module</span> <span class="pre">import</span> <span class="pre">*</span></code> — is only allowed at
|
||
the module level. Attempting to use it in class or function definitions will
|
||
raise a <a class="reference internal" href="../library/exceptions.html#SyntaxError" title="SyntaxError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SyntaxError</span></code></a>.</p>
|
||
<p id="index-39">When specifying what module to import you do not have to specify the absolute
|
||
name of the module. When a module or package is contained within another
|
||
package it is possible to make a relative import within the same top package
|
||
without having to mention the package name. By using leading dots in the
|
||
specified module or package after <a class="reference internal" href="#from"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">from</span></code></a> you can specify how high to
|
||
traverse up the current package hierarchy without specifying exact names. One
|
||
leading dot means the current package where the module making the import
|
||
exists. Two dots means up one package level. Three dots is up two levels, etc.
|
||
So if you execute <code class="docutils literal notranslate"><span class="pre">from</span> <span class="pre">.</span> <span class="pre">import</span> <span class="pre">mod</span></code> from a module in the <code class="docutils literal notranslate"><span class="pre">pkg</span></code> package
|
||
then you will end up importing <code class="docutils literal notranslate"><span class="pre">pkg.mod</span></code>. If you execute <code class="docutils literal notranslate"><span class="pre">from</span> <span class="pre">..subpkg2</span>
|
||
<span class="pre">import</span> <span class="pre">mod</span></code> from within <code class="docutils literal notranslate"><span class="pre">pkg.subpkg1</span></code> you will import <code class="docutils literal notranslate"><span class="pre">pkg.subpkg2.mod</span></code>.
|
||
The specification for relative imports is contained in
|
||
the <a class="reference internal" href="import.html#relativeimports"><span class="std std-ref">Package Relative Imports</span></a> section.</p>
|
||
<p><a class="reference internal" href="../library/importlib.html#importlib.import_module" title="importlib.import_module"><code class="xref py py-func docutils literal notranslate"><span class="pre">importlib.import_module()</span></code></a> is provided to support applications that
|
||
determine dynamically the modules to be loaded.</p>
|
||
<div class="section" id="future-statements">
|
||
<span id="future"></span><h3>7.11.1. Future statements<a class="headerlink" href="#future-statements" title="Permalink to this headline">¶</a></h3>
|
||
<p id="index-40">A <em class="dfn">future statement</em> is a directive to the compiler that a particular
|
||
module should be compiled using syntax or semantics that will be available in a
|
||
specified future release of Python where the feature becomes standard.</p>
|
||
<p>The future statement is intended to ease migration to future versions of Python
|
||
that introduce incompatible changes to the language. It allows use of the new
|
||
features on a per-module basis before the release in which the feature becomes
|
||
standard.</p>
|
||
<pre>
|
||
<strong id="grammar-token-future-stmt">future_stmt</strong> ::= "from" "__future__" "import" <a class="reference internal" href="#grammar-token-feature"><code class="xref docutils literal notranslate"><span class="pre">feature</span></code></a> ["as" <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><code class="xref docutils literal notranslate"><span class="pre">identifier</span></code></a>]
|
||
("," <a class="reference internal" href="#grammar-token-feature"><code class="xref docutils literal notranslate"><span class="pre">feature</span></code></a> ["as" <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><code class="xref docutils literal notranslate"><span class="pre">identifier</span></code></a>])*
|
||
| "from" "__future__" "import" "(" <a class="reference internal" href="#grammar-token-feature"><code class="xref docutils literal notranslate"><span class="pre">feature</span></code></a> ["as" <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><code class="xref docutils literal notranslate"><span class="pre">identifier</span></code></a>]
|
||
("," <a class="reference internal" href="#grammar-token-feature"><code class="xref docutils literal notranslate"><span class="pre">feature</span></code></a> ["as" <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><code class="xref docutils literal notranslate"><span class="pre">identifier</span></code></a>])* [","] ")"
|
||
<strong id="grammar-token-feature">feature </strong> ::= <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><code class="xref docutils literal notranslate"><span class="pre">identifier</span></code></a>
|
||
</pre>
|
||
<p>A future statement must appear near the top of the module. The only lines that
|
||
can appear before a future statement are:</p>
|
||
<ul class="simple">
|
||
<li><p>the module docstring (if any),</p></li>
|
||
<li><p>comments,</p></li>
|
||
<li><p>blank lines, and</p></li>
|
||
<li><p>other future statements.</p></li>
|
||
</ul>
|
||
<p>The only feature in Python 3.7 that requires using the future statement is
|
||
<code class="docutils literal notranslate"><span class="pre">annotations</span></code>.</p>
|
||
<p>All historical features enabled by the future statement are still recognized
|
||
by Python 3. The list includes <code class="docutils literal notranslate"><span class="pre">absolute_import</span></code>, <code class="docutils literal notranslate"><span class="pre">division</span></code>,
|
||
<code class="docutils literal notranslate"><span class="pre">generators</span></code>, <code class="docutils literal notranslate"><span class="pre">generator_stop</span></code>, <code class="docutils literal notranslate"><span class="pre">unicode_literals</span></code>,
|
||
<code class="docutils literal notranslate"><span class="pre">print_function</span></code>, <code class="docutils literal notranslate"><span class="pre">nested_scopes</span></code> and <code class="docutils literal notranslate"><span class="pre">with_statement</span></code>. They are
|
||
all redundant because they are always enabled, and only kept for
|
||
backwards compatibility.</p>
|
||
<p>A future statement is recognized and treated specially at compile time: Changes
|
||
to the semantics of core constructs are often implemented by generating
|
||
different code. It may even be the case that a new feature introduces new
|
||
incompatible syntax (such as a new reserved word), in which case the compiler
|
||
may need to parse the module differently. Such decisions cannot be pushed off
|
||
until runtime.</p>
|
||
<p>For any given release, the compiler knows which feature names have been defined,
|
||
and raises a compile-time error if a future statement contains a feature not
|
||
known to it.</p>
|
||
<p>The direct runtime semantics are the same as for any import statement: there is
|
||
a standard module <a class="reference internal" href="../library/__future__.html#module-__future__" title="__future__: Future statement definitions"><code class="xref py py-mod docutils literal notranslate"><span class="pre">__future__</span></code></a>, described later, and it will be imported in
|
||
the usual way at the time the future statement is executed.</p>
|
||
<p>The interesting runtime semantics depend on the specific feature enabled by the
|
||
future statement.</p>
|
||
<p>Note that there is nothing special about the statement:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">__future__</span> <span class="p">[</span><span class="k">as</span> <span class="n">name</span><span class="p">]</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>That is not a future statement; it’s an ordinary import statement with no
|
||
special semantics or syntax restrictions.</p>
|
||
<p>Code compiled by calls to the built-in functions <a class="reference internal" href="../library/functions.html#exec" title="exec"><code class="xref py py-func docutils literal notranslate"><span class="pre">exec()</span></code></a> and <a class="reference internal" href="../library/functions.html#compile" title="compile"><code class="xref py py-func docutils literal notranslate"><span class="pre">compile()</span></code></a>
|
||
that occur in a module <code class="xref py py-mod docutils literal notranslate"><span class="pre">M</span></code> containing a future statement will, by default,
|
||
use the new syntax or semantics associated with the future statement. This can
|
||
be controlled by optional arguments to <a class="reference internal" href="../library/functions.html#compile" title="compile"><code class="xref py py-func docutils literal notranslate"><span class="pre">compile()</span></code></a> — see the documentation
|
||
of that function for details.</p>
|
||
<p>A future statement typed at an interactive interpreter prompt will take effect
|
||
for the rest of the interpreter session. If an interpreter is started with the
|
||
<a class="reference internal" href="../using/cmdline.html#cmdoption-i"><code class="xref std std-option docutils literal notranslate"><span class="pre">-i</span></code></a> option, is passed a script name to execute, and the script includes
|
||
a future statement, it will be in effect in the interactive session started
|
||
after the script is executed.</p>
|
||
<div class="admonition seealso">
|
||
<p class="admonition-title">See also</p>
|
||
<dl class="simple">
|
||
<dt><span class="target" id="index-41"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0236"><strong>PEP 236</strong></a> - Back to the __future__</dt><dd><p>The original proposal for the __future__ mechanism.</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="the-global-statement">
|
||
<span id="global"></span><h2>7.12. The <code class="xref std std-keyword docutils literal notranslate"><span class="pre">global</span></code> statement<a class="headerlink" href="#the-global-statement" title="Permalink to this headline">¶</a></h2>
|
||
<pre id="index-42">
|
||
<strong id="grammar-token-global-stmt">global_stmt</strong> ::= "global" <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><code class="xref docutils literal notranslate"><span class="pre">identifier</span></code></a> ("," <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><code class="xref docutils literal notranslate"><span class="pre">identifier</span></code></a>)*
|
||
</pre>
|
||
<p>The <a class="reference internal" href="#global"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">global</span></code></a> statement is a declaration which holds for the entire
|
||
current code block. It means that the listed identifiers are to be interpreted
|
||
as globals. It would be impossible to assign to a global variable without
|
||
<code class="xref std std-keyword docutils literal notranslate"><span class="pre">global</span></code>, although free variables may refer to globals without being
|
||
declared global.</p>
|
||
<p>Names listed in a <a class="reference internal" href="#global"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">global</span></code></a> statement must not be used in the same code
|
||
block textually preceding that <code class="xref std std-keyword docutils literal notranslate"><span class="pre">global</span></code> statement.</p>
|
||
<p>Names listed in a <a class="reference internal" href="#global"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">global</span></code></a> statement must not be defined as formal
|
||
parameters or in a <a class="reference internal" href="compound_stmts.html#for"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">for</span></code></a> loop control target, <a class="reference internal" href="compound_stmts.html#class"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">class</span></code></a>
|
||
definition, function definition, <a class="reference internal" href="#import"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">import</span></code></a> statement, or variable
|
||
annotation.</p>
|
||
<div class="impl-detail compound">
|
||
<p><strong>CPython implementation detail:</strong> The current implementation does not enforce some of these restrictions, but
|
||
programs should not abuse this freedom, as future implementations may enforce
|
||
them or silently change the meaning of the program.</p>
|
||
</div>
|
||
<p id="index-43"><strong>Programmer’s note:</strong> <a class="reference internal" href="#global"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">global</span></code></a> is a directive to the parser. It
|
||
applies only to code parsed at the same time as the <code class="xref std std-keyword docutils literal notranslate"><span class="pre">global</span></code> statement.
|
||
In particular, a <code class="xref std std-keyword docutils literal notranslate"><span class="pre">global</span></code> statement contained in a string or code
|
||
object supplied to the built-in <a class="reference internal" href="../library/functions.html#exec" title="exec"><code class="xref py py-func docutils literal notranslate"><span class="pre">exec()</span></code></a> function does not affect the code
|
||
block <em>containing</em> the function call, and code contained in such a string is
|
||
unaffected by <code class="xref std std-keyword docutils literal notranslate"><span class="pre">global</span></code> statements in the code containing the function
|
||
call. The same applies to the <a class="reference internal" href="../library/functions.html#eval" title="eval"><code class="xref py py-func docutils literal notranslate"><span class="pre">eval()</span></code></a> and <a class="reference internal" href="../library/functions.html#compile" title="compile"><code class="xref py py-func docutils literal notranslate"><span class="pre">compile()</span></code></a> functions.</p>
|
||
</div>
|
||
<div class="section" id="the-nonlocal-statement">
|
||
<span id="nonlocal"></span><h2>7.13. The <code class="xref std std-keyword docutils literal notranslate"><span class="pre">nonlocal</span></code> statement<a class="headerlink" href="#the-nonlocal-statement" title="Permalink to this headline">¶</a></h2>
|
||
<pre id="index-44">
|
||
<strong id="grammar-token-nonlocal-stmt">nonlocal_stmt</strong> ::= "nonlocal" <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><code class="xref docutils literal notranslate"><span class="pre">identifier</span></code></a> ("," <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><code class="xref docutils literal notranslate"><span class="pre">identifier</span></code></a>)*
|
||
</pre>
|
||
<p>The <a class="reference internal" href="#nonlocal"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">nonlocal</span></code></a> statement causes the listed identifiers to refer to
|
||
previously bound variables in the nearest enclosing scope excluding globals.
|
||
This is important because the default behavior for binding is to search the
|
||
local namespace first. The statement allows encapsulated code to rebind
|
||
variables outside of the local scope besides the global (module) scope.</p>
|
||
<p>Names listed in a <a class="reference internal" href="#nonlocal"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">nonlocal</span></code></a> statement, unlike those listed in a
|
||
<a class="reference internal" href="#global"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">global</span></code></a> statement, must refer to pre-existing bindings in an
|
||
enclosing scope (the scope in which a new binding should be created cannot
|
||
be determined unambiguously).</p>
|
||
<p>Names listed in a <a class="reference internal" href="#nonlocal"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">nonlocal</span></code></a> statement must not collide with
|
||
pre-existing bindings in the local scope.</p>
|
||
<div class="admonition seealso">
|
||
<p class="admonition-title">See also</p>
|
||
<dl class="simple">
|
||
<dt><span class="target" id="index-45"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-3104"><strong>PEP 3104</strong></a> - Access to Names in Outer Scopes</dt><dd><p>The specification for the <a class="reference internal" href="#nonlocal"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">nonlocal</span></code></a> statement.</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
||
<div class="sphinxsidebarwrapper">
|
||
<h3><a href="../contents.html">Table of Contents</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#">7. Simple statements</a><ul>
|
||
<li><a class="reference internal" href="#expression-statements">7.1. Expression statements</a></li>
|
||
<li><a class="reference internal" href="#assignment-statements">7.2. Assignment statements</a><ul>
|
||
<li><a class="reference internal" href="#augmented-assignment-statements">7.2.1. Augmented assignment statements</a></li>
|
||
<li><a class="reference internal" href="#annotated-assignment-statements">7.2.2. Annotated assignment statements</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#the-assert-statement">7.3. The <code class="xref std std-keyword docutils literal notranslate"><span class="pre">assert</span></code> statement</a></li>
|
||
<li><a class="reference internal" href="#the-pass-statement">7.4. The <code class="xref std std-keyword docutils literal notranslate"><span class="pre">pass</span></code> statement</a></li>
|
||
<li><a class="reference internal" href="#the-del-statement">7.5. The <code class="xref std std-keyword docutils literal notranslate"><span class="pre">del</span></code> statement</a></li>
|
||
<li><a class="reference internal" href="#the-return-statement">7.6. The <code class="xref std std-keyword docutils literal notranslate"><span class="pre">return</span></code> statement</a></li>
|
||
<li><a class="reference internal" href="#the-yield-statement">7.7. The <code class="xref std std-keyword docutils literal notranslate"><span class="pre">yield</span></code> statement</a></li>
|
||
<li><a class="reference internal" href="#the-raise-statement">7.8. The <code class="xref std std-keyword docutils literal notranslate"><span class="pre">raise</span></code> statement</a></li>
|
||
<li><a class="reference internal" href="#the-break-statement">7.9. The <code class="xref std std-keyword docutils literal notranslate"><span class="pre">break</span></code> statement</a></li>
|
||
<li><a class="reference internal" href="#the-continue-statement">7.10. The <code class="xref std std-keyword docutils literal notranslate"><span class="pre">continue</span></code> statement</a></li>
|
||
<li><a class="reference internal" href="#the-import-statement">7.11. The <code class="xref std std-keyword docutils literal notranslate"><span class="pre">import</span></code> statement</a><ul>
|
||
<li><a class="reference internal" href="#future-statements">7.11.1. Future statements</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#the-global-statement">7.12. The <code class="xref std std-keyword docutils literal notranslate"><span class="pre">global</span></code> statement</a></li>
|
||
<li><a class="reference internal" href="#the-nonlocal-statement">7.13. The <code class="xref std std-keyword docutils literal notranslate"><span class="pre">nonlocal</span></code> statement</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
<h4>Previous topic</h4>
|
||
<p class="topless"><a href="expressions.html"
|
||
title="previous chapter">6. Expressions</a></p>
|
||
<h4>Next topic</h4>
|
||
<p class="topless"><a href="compound_stmts.html"
|
||
title="next chapter">8. Compound statements</a></p>
|
||
<div role="note" aria-label="source link">
|
||
<h3>This Page</h3>
|
||
<ul class="this-page-menu">
|
||
<li><a href="../bugs.html">Report a Bug</a></li>
|
||
<li>
|
||
<a href="https://github.com/python/cpython/blob/3.7/Doc/reference/simple_stmts.rst"
|
||
rel="nofollow">Show Source
|
||
</a>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="clearer"></div>
|
||
</div>
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="General Index"
|
||
>index</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python Module Index"
|
||
>modules</a> |</li>
|
||
<li class="right" >
|
||
<a href="compound_stmts.html" title="8. Compound statements"
|
||
>next</a> |</li>
|
||
<li class="right" >
|
||
<a href="expressions.html" title="6. Expressions"
|
||
>previous</a> |</li>
|
||
<li><img src="../_static/py.png" alt=""
|
||
style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li>
|
||
<span class="language_switcher_placeholder">en</span>
|
||
<span class="version_switcher_placeholder">3.7.4</span>
|
||
<a href="../index.html">Documentation </a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >The Python Language Reference</a> »</li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" style="display: none" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="Quick search" type="text" name="q" />
|
||
<input type="submit" value="Go" />
|
||
<input type="hidden" name="check_keywords" value="yes" />
|
||
<input type="hidden" name="area" value="default" />
|
||
</form>
|
||
</div>
|
||
<script type="text/javascript">$('.inline-search').show(0);</script>
|
||
|
|
||
</li>
|
||
|
||
</ul>
|
||
</div>
|
||
<div class="footer">
|
||
© <a href="../copyright.html">Copyright</a> 2001-2019, Python Software Foundation.
|
||
<br />
|
||
The Python Software Foundation is a non-profit corporation.
|
||
<a href="https://www.python.org/psf/donations/">Please donate.</a>
|
||
<br />
|
||
Last updated on Jul 13, 2019.
|
||
<a href="../bugs.html">Found a bug</a>?
|
||
<br />
|
||
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.0.1.
|
||
</div>
|
||
|
||
</body>
|
||
</html> |