1557 lines
177 KiB
HTML
1557 lines
177 KiB
HTML
|
||
<!DOCTYPE html>
|
||
|
||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
<head>
|
||
<meta charset="utf-8" />
|
||
<title>6. Expressions — 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="7. Simple statements" href="simple_stmts.html" />
|
||
<link rel="prev" title="5. The import system" href="import.html" />
|
||
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
|
||
<link rel="canonical" href="https://docs.python.org/3/reference/expressions.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="simple_stmts.html" title="7. Simple statements"
|
||
accesskey="N">next</a> |</li>
|
||
<li class="right" >
|
||
<a href="import.html" title="5. The import system"
|
||
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="expressions">
|
||
<span id="id1"></span><h1>6. Expressions<a class="headerlink" href="#expressions" title="Permalink to this headline">¶</a></h1>
|
||
<p id="index-0">This chapter explains the meaning of the elements of expressions in Python.</p>
|
||
<p><strong>Syntax Notes:</strong> In this and the following chapters, extended BNF notation will
|
||
be used to describe syntax, not lexical analysis. When (one alternative of) a
|
||
syntax rule has the form</p>
|
||
<pre>
|
||
<strong id="grammar-token-name">name</strong> ::= <code class="xref docutils literal notranslate"><span class="pre">othername</span></code>
|
||
</pre>
|
||
<p>and no semantics are given, the semantics of this form of <code class="docutils literal notranslate"><span class="pre">name</span></code> are the same
|
||
as for <code class="docutils literal notranslate"><span class="pre">othername</span></code>.</p>
|
||
<div class="section" id="arithmetic-conversions">
|
||
<span id="conversions"></span><h2>6.1. Arithmetic conversions<a class="headerlink" href="#arithmetic-conversions" title="Permalink to this headline">¶</a></h2>
|
||
<p id="index-1">When a description of an arithmetic operator below uses the phrase “the numeric
|
||
arguments are converted to a common type,” this means that the operator
|
||
implementation for built-in types works as follows:</p>
|
||
<ul class="simple">
|
||
<li><p>If either argument is a complex number, the other is converted to complex;</p></li>
|
||
<li><p>otherwise, if either argument is a floating point number, the other is
|
||
converted to floating point;</p></li>
|
||
<li><p>otherwise, both must be integers and no conversion is necessary.</p></li>
|
||
</ul>
|
||
<p>Some additional rules apply for certain operators (e.g., a string as a left
|
||
argument to the ‘%’ operator). Extensions must define their own conversion
|
||
behavior.</p>
|
||
</div>
|
||
<div class="section" id="atoms">
|
||
<span id="id2"></span><h2>6.2. Atoms<a class="headerlink" href="#atoms" title="Permalink to this headline">¶</a></h2>
|
||
<p id="index-2">Atoms are the most basic elements of expressions. The simplest atoms are
|
||
identifiers or literals. Forms enclosed in parentheses, brackets or braces are
|
||
also categorized syntactically as atoms. The syntax for atoms is:</p>
|
||
<pre>
|
||
<strong id="grammar-token-atom">atom </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-literal"><code class="xref docutils literal notranslate"><span class="pre">literal</span></code></a> | <a class="reference internal" href="#grammar-token-enclosure"><code class="xref docutils literal notranslate"><span class="pre">enclosure</span></code></a>
|
||
<strong id="grammar-token-enclosure">enclosure</strong> ::= <a class="reference internal" href="#grammar-token-parenth-form"><code class="xref docutils literal notranslate"><span class="pre">parenth_form</span></code></a> | <a class="reference internal" href="#grammar-token-list-display"><code class="xref docutils literal notranslate"><span class="pre">list_display</span></code></a> | <a class="reference internal" href="#grammar-token-dict-display"><code class="xref docutils literal notranslate"><span class="pre">dict_display</span></code></a> | <a class="reference internal" href="#grammar-token-set-display"><code class="xref docutils literal notranslate"><span class="pre">set_display</span></code></a>
|
||
| <a class="reference internal" href="#grammar-token-generator-expression"><code class="xref docutils literal notranslate"><span class="pre">generator_expression</span></code></a> | <a class="reference internal" href="#grammar-token-yield-atom"><code class="xref docutils literal notranslate"><span class="pre">yield_atom</span></code></a>
|
||
</pre>
|
||
<div class="section" id="atom-identifiers">
|
||
<span id="identifiers-names"></span><h3>6.2.1. Identifiers (Names)<a class="headerlink" href="#atom-identifiers" title="Permalink to this headline">¶</a></h3>
|
||
<p id="index-3">An identifier occurring as an atom is a name. See section <a class="reference internal" href="lexical_analysis.html#identifiers"><span class="std std-ref">Identifiers and keywords</span></a>
|
||
for lexical definition and section <a class="reference internal" href="executionmodel.html#naming"><span class="std std-ref">Naming and binding</span></a> for documentation of naming and
|
||
binding.</p>
|
||
<p id="index-4">When the name is bound to an object, evaluation of the atom yields that object.
|
||
When a name is not bound, an attempt to evaluate it raises 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.</p>
|
||
<p id="index-5"><strong>Private name mangling:</strong> When an identifier that textually occurs in a class
|
||
definition begins with two or more underscore characters and does not end in two
|
||
or more underscores, it is considered a <em class="dfn">private name</em> of that class.
|
||
Private names are transformed to a longer form before code is generated for
|
||
them. The transformation inserts the class name, with leading underscores
|
||
removed and a single underscore inserted, in front of the name. For example,
|
||
the identifier <code class="docutils literal notranslate"><span class="pre">__spam</span></code> occurring in a class named <code class="docutils literal notranslate"><span class="pre">Ham</span></code> will be transformed
|
||
to <code class="docutils literal notranslate"><span class="pre">_Ham__spam</span></code>. This transformation is independent of the syntactical
|
||
context in which the identifier is used. If the transformed name is extremely
|
||
long (longer than 255 characters), implementation defined truncation may happen.
|
||
If the class name consists only of underscores, no transformation is done.</p>
|
||
</div>
|
||
<div class="section" id="literals">
|
||
<span id="atom-literals"></span><h3>6.2.2. Literals<a class="headerlink" href="#literals" title="Permalink to this headline">¶</a></h3>
|
||
<p id="index-6">Python supports string and bytes literals and various numeric literals:</p>
|
||
<pre>
|
||
<strong id="grammar-token-literal">literal</strong> ::= <a class="reference internal" href="lexical_analysis.html#grammar-token-stringliteral"><code class="xref docutils literal notranslate"><span class="pre">stringliteral</span></code></a> | <a class="reference internal" href="lexical_analysis.html#grammar-token-bytesliteral"><code class="xref docutils literal notranslate"><span class="pre">bytesliteral</span></code></a>
|
||
| <a class="reference internal" href="lexical_analysis.html#grammar-token-integer"><code class="xref docutils literal notranslate"><span class="pre">integer</span></code></a> | <a class="reference internal" href="lexical_analysis.html#grammar-token-floatnumber"><code class="xref docutils literal notranslate"><span class="pre">floatnumber</span></code></a> | <a class="reference internal" href="lexical_analysis.html#grammar-token-imagnumber"><code class="xref docutils literal notranslate"><span class="pre">imagnumber</span></code></a>
|
||
</pre>
|
||
<p>Evaluation of a literal yields an object of the given type (string, bytes,
|
||
integer, floating point number, complex number) with the given value. The value
|
||
may be approximated in the case of floating point and imaginary (complex)
|
||
literals. See section <a class="reference internal" href="lexical_analysis.html#literals"><span class="std std-ref">Literals</span></a> for details.</p>
|
||
<p id="index-7">All literals correspond to immutable data types, and hence the object’s identity
|
||
is less important than its value. Multiple evaluations of literals with the
|
||
same value (either the same occurrence in the program text or a different
|
||
occurrence) may obtain the same object or a different object with the same
|
||
value.</p>
|
||
</div>
|
||
<div class="section" id="parenthesized-forms">
|
||
<span id="parenthesized"></span><h3>6.2.3. Parenthesized forms<a class="headerlink" href="#parenthesized-forms" title="Permalink to this headline">¶</a></h3>
|
||
<p id="index-8">A parenthesized form is an optional expression list enclosed in parentheses:</p>
|
||
<pre>
|
||
<strong id="grammar-token-parenth-form">parenth_form</strong> ::= "(" [<a class="reference internal" href="#grammar-token-starred-expression"><code class="xref docutils literal notranslate"><span class="pre">starred_expression</span></code></a>] ")"
|
||
</pre>
|
||
<p>A parenthesized expression list yields whatever that expression list yields: if
|
||
the list contains at least one comma, it yields a tuple; otherwise, it yields
|
||
the single expression that makes up the expression list.</p>
|
||
<p id="index-9">An empty pair of parentheses yields an empty tuple object. Since tuples are
|
||
immutable, the same rules as for literals apply (i.e., two occurrences of the empty
|
||
tuple may or may not yield the same object).</p>
|
||
<p id="index-10">Note that tuples are not formed by the parentheses, but rather by use of the
|
||
comma operator. The exception is the empty tuple, for which parentheses <em>are</em>
|
||
required — allowing unparenthesized “nothing” in expressions would cause
|
||
ambiguities and allow common typos to pass uncaught.</p>
|
||
</div>
|
||
<div class="section" id="displays-for-lists-sets-and-dictionaries">
|
||
<span id="comprehensions"></span><h3>6.2.4. Displays for lists, sets and dictionaries<a class="headerlink" href="#displays-for-lists-sets-and-dictionaries" title="Permalink to this headline">¶</a></h3>
|
||
<p>For constructing a list, a set or a dictionary Python provides special syntax
|
||
called “displays”, each of them in two flavors:</p>
|
||
<ul class="simple">
|
||
<li><p>either the container contents are listed explicitly, or</p></li>
|
||
<li><p>they are computed via a set of looping and filtering instructions, called a
|
||
<em class="dfn">comprehension</em>.</p></li>
|
||
</ul>
|
||
<p id="index-11">Common syntax elements for comprehensions are:</p>
|
||
<pre>
|
||
<strong id="grammar-token-comprehension">comprehension</strong> ::= <a class="reference internal" href="#grammar-token-expression"><code class="xref docutils literal notranslate"><span class="pre">expression</span></code></a> <a class="reference internal" href="#grammar-token-comp-for"><code class="xref docutils literal notranslate"><span class="pre">comp_for</span></code></a>
|
||
<strong id="grammar-token-comp-for">comp_for </strong> ::= ["async"] "for" <a class="reference internal" href="simple_stmts.html#grammar-token-target-list"><code class="xref docutils literal notranslate"><span class="pre">target_list</span></code></a> "in" <a class="reference internal" href="#grammar-token-or-test"><code class="xref docutils literal notranslate"><span class="pre">or_test</span></code></a> [<a class="reference internal" href="#grammar-token-comp-iter"><code class="xref docutils literal notranslate"><span class="pre">comp_iter</span></code></a>]
|
||
<strong id="grammar-token-comp-iter">comp_iter </strong> ::= <a class="reference internal" href="#grammar-token-comp-for"><code class="xref docutils literal notranslate"><span class="pre">comp_for</span></code></a> | <a class="reference internal" href="#grammar-token-comp-if"><code class="xref docutils literal notranslate"><span class="pre">comp_if</span></code></a>
|
||
<strong id="grammar-token-comp-if">comp_if </strong> ::= "if" <a class="reference internal" href="#grammar-token-expression-nocond"><code class="xref docutils literal notranslate"><span class="pre">expression_nocond</span></code></a> [<a class="reference internal" href="#grammar-token-comp-iter"><code class="xref docutils literal notranslate"><span class="pre">comp_iter</span></code></a>]
|
||
</pre>
|
||
<p>The comprehension consists of a single expression followed by at least one
|
||
<code class="xref std std-keyword docutils literal notranslate"><span class="pre">for</span></code> clause and zero or more <code class="xref std std-keyword docutils literal notranslate"><span class="pre">for</span></code> or <code class="xref std std-keyword docutils literal notranslate"><span class="pre">if</span></code> clauses.
|
||
In this case, the elements of the new container are those that would be produced
|
||
by considering each of the <code class="xref std std-keyword docutils literal notranslate"><span class="pre">for</span></code> or <code class="xref std std-keyword docutils literal notranslate"><span class="pre">if</span></code> clauses a block,
|
||
nesting from left to right, and evaluating the expression to produce an element
|
||
each time the innermost block is reached.</p>
|
||
<p>However, aside from the iterable expression in the leftmost <code class="xref std std-keyword docutils literal notranslate"><span class="pre">for</span></code> clause,
|
||
the comprehension is executed in a separate implicitly nested scope. This ensures
|
||
that names assigned to in the target list don’t “leak” into the enclosing scope.</p>
|
||
<p>The iterable expression in the leftmost <code class="xref std std-keyword docutils literal notranslate"><span class="pre">for</span></code> clause is evaluated
|
||
directly in the enclosing scope and then passed as an argument to the implictly
|
||
nested scope. Subsequent <code class="xref std std-keyword docutils literal notranslate"><span class="pre">for</span></code> clauses and any filter condition in the
|
||
leftmost <code class="xref std std-keyword docutils literal notranslate"><span class="pre">for</span></code> clause cannot be evaluated in the enclosing scope as
|
||
they may depend on the values obtained from the leftmost iterable. For example:
|
||
<code class="docutils literal notranslate"><span class="pre">[x*y</span> <span class="pre">for</span> <span class="pre">x</span> <span class="pre">in</span> <span class="pre">range(10)</span> <span class="pre">for</span> <span class="pre">y</span> <span class="pre">in</span> <span class="pre">range(x,</span> <span class="pre">x+10)]</span></code>.</p>
|
||
<p>To ensure the comprehension always results in a container of the appropriate
|
||
type, <code class="docutils literal notranslate"><span class="pre">yield</span></code> and <code class="docutils literal notranslate"><span class="pre">yield</span> <span class="pre">from</span></code> expressions are prohibited in the implicitly
|
||
nested scope (in Python 3.7, such expressions emit <a class="reference internal" href="../library/exceptions.html#DeprecationWarning" title="DeprecationWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">DeprecationWarning</span></code></a>
|
||
when compiled, in Python 3.8+ they will emit <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-12">Since Python 3.6, in an <a class="reference internal" href="compound_stmts.html#async-def"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">async</span> <span class="pre">def</span></code></a> function, an <code class="xref std std-keyword docutils literal notranslate"><span class="pre">async</span> <span class="pre">for</span></code>
|
||
clause may be used to iterate over a <a class="reference internal" href="../glossary.html#term-asynchronous-iterator"><span class="xref std std-term">asynchronous iterator</span></a>.
|
||
A comprehension in an <code class="xref std std-keyword docutils literal notranslate"><span class="pre">async</span> <span class="pre">def</span></code> function may consist of either a
|
||
<code class="xref std std-keyword docutils literal notranslate"><span class="pre">for</span></code> or <code class="xref std std-keyword docutils literal notranslate"><span class="pre">async</span> <span class="pre">for</span></code> clause following the leading
|
||
expression, may contain additional <code class="xref std std-keyword docutils literal notranslate"><span class="pre">for</span></code> or <code class="xref std std-keyword docutils literal notranslate"><span class="pre">async</span> <span class="pre">for</span></code>
|
||
clauses, and may also use <a class="reference internal" href="#await"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">await</span></code></a> expressions.
|
||
If a comprehension contains either <code class="xref std std-keyword docutils literal notranslate"><span class="pre">async</span> <span class="pre">for</span></code> clauses
|
||
or <code class="xref std std-keyword docutils literal notranslate"><span class="pre">await</span></code> expressions it is called an
|
||
<em class="dfn">asynchronous comprehension</em>. An asynchronous comprehension may
|
||
suspend the execution of the coroutine function in which it appears.
|
||
See also <span class="target" id="index-13"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0530"><strong>PEP 530</strong></a>.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.6: </span>Asynchronous comprehensions were introduced.</p>
|
||
</div>
|
||
<div class="deprecated">
|
||
<p><span class="versionmodified deprecated">Deprecated since version 3.7: </span><code class="docutils literal notranslate"><span class="pre">yield</span></code> and <code class="docutils literal notranslate"><span class="pre">yield</span> <span class="pre">from</span></code> deprecated in the implicitly nested scope.</p>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="list-displays">
|
||
<span id="lists"></span><h3>6.2.5. List displays<a class="headerlink" href="#list-displays" title="Permalink to this headline">¶</a></h3>
|
||
<p id="index-14">A list display is a possibly empty series of expressions enclosed in square
|
||
brackets:</p>
|
||
<pre>
|
||
<strong id="grammar-token-list-display">list_display</strong> ::= "[" [<a class="reference internal" href="#grammar-token-starred-list"><code class="xref docutils literal notranslate"><span class="pre">starred_list</span></code></a> | <a class="reference internal" href="#grammar-token-comprehension"><code class="xref docutils literal notranslate"><span class="pre">comprehension</span></code></a>] "]"
|
||
</pre>
|
||
<p>A list display yields a new list object, the contents being specified by either
|
||
a list of expressions or a comprehension. When a comma-separated list of
|
||
expressions is supplied, its elements are evaluated from left to right and
|
||
placed into the list object in that order. When a comprehension is supplied,
|
||
the list is constructed from the elements resulting from the comprehension.</p>
|
||
</div>
|
||
<div class="section" id="set-displays">
|
||
<span id="set"></span><h3>6.2.6. Set displays<a class="headerlink" href="#set-displays" title="Permalink to this headline">¶</a></h3>
|
||
<p id="index-15">A set display is denoted by curly braces and distinguishable from dictionary
|
||
displays by the lack of colons separating keys and values:</p>
|
||
<pre>
|
||
<strong id="grammar-token-set-display">set_display</strong> ::= "{" (<a class="reference internal" href="#grammar-token-starred-list"><code class="xref docutils literal notranslate"><span class="pre">starred_list</span></code></a> | <a class="reference internal" href="#grammar-token-comprehension"><code class="xref docutils literal notranslate"><span class="pre">comprehension</span></code></a>) "}"
|
||
</pre>
|
||
<p>A set display yields a new mutable set object, the contents being specified by
|
||
either a sequence of expressions or a comprehension. When a comma-separated
|
||
list of expressions is supplied, its elements are evaluated from left to right
|
||
and added to the set object. When a comprehension is supplied, the set is
|
||
constructed from the elements resulting from the comprehension.</p>
|
||
<p>An empty set cannot be constructed with <code class="docutils literal notranslate"><span class="pre">{}</span></code>; this literal constructs an empty
|
||
dictionary.</p>
|
||
</div>
|
||
<div class="section" id="dictionary-displays">
|
||
<span id="dict"></span><h3>6.2.7. Dictionary displays<a class="headerlink" href="#dictionary-displays" title="Permalink to this headline">¶</a></h3>
|
||
<p id="index-16">A dictionary display is a possibly empty series of key/datum pairs enclosed in
|
||
curly braces:</p>
|
||
<pre>
|
||
<strong id="grammar-token-dict-display">dict_display </strong> ::= "{" [<a class="reference internal" href="#grammar-token-key-datum-list"><code class="xref docutils literal notranslate"><span class="pre">key_datum_list</span></code></a> | <a class="reference internal" href="#grammar-token-dict-comprehension"><code class="xref docutils literal notranslate"><span class="pre">dict_comprehension</span></code></a>] "}"
|
||
<strong id="grammar-token-key-datum-list">key_datum_list </strong> ::= <a class="reference internal" href="#grammar-token-key-datum"><code class="xref docutils literal notranslate"><span class="pre">key_datum</span></code></a> ("," <a class="reference internal" href="#grammar-token-key-datum"><code class="xref docutils literal notranslate"><span class="pre">key_datum</span></code></a>)* [","]
|
||
<strong id="grammar-token-key-datum">key_datum </strong> ::= <a class="reference internal" href="#grammar-token-expression"><code class="xref docutils literal notranslate"><span class="pre">expression</span></code></a> ":" <a class="reference internal" href="#grammar-token-expression"><code class="xref docutils literal notranslate"><span class="pre">expression</span></code></a> | "**" <a class="reference internal" href="#grammar-token-or-expr"><code class="xref docutils literal notranslate"><span class="pre">or_expr</span></code></a>
|
||
<strong id="grammar-token-dict-comprehension">dict_comprehension</strong> ::= <a class="reference internal" href="#grammar-token-expression"><code class="xref docutils literal notranslate"><span class="pre">expression</span></code></a> ":" <a class="reference internal" href="#grammar-token-expression"><code class="xref docutils literal notranslate"><span class="pre">expression</span></code></a> <a class="reference internal" href="#grammar-token-comp-for"><code class="xref docutils literal notranslate"><span class="pre">comp_for</span></code></a>
|
||
</pre>
|
||
<p>A dictionary display yields a new dictionary object.</p>
|
||
<p>If a comma-separated sequence of key/datum pairs is given, they are evaluated
|
||
from left to right to define the entries of the dictionary: each key object is
|
||
used as a key into the dictionary to store the corresponding datum. This means
|
||
that you can specify the same key multiple times in the key/datum list, and the
|
||
final dictionary’s value for that key will be the last one given.</p>
|
||
<p id="index-17">A double asterisk <code class="docutils literal notranslate"><span class="pre">**</span></code> denotes <em class="dfn">dictionary unpacking</em>.
|
||
Its operand must be a <a class="reference internal" href="../glossary.html#term-mapping"><span class="xref std std-term">mapping</span></a>. Each mapping item is added
|
||
to the new dictionary. Later values replace values already set by
|
||
earlier key/datum pairs and earlier dictionary unpackings.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.5: </span>Unpacking into dictionary displays, originally proposed by <span class="target" id="index-18"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0448"><strong>PEP 448</strong></a>.</p>
|
||
</div>
|
||
<p>A dict comprehension, in contrast to list and set comprehensions, needs two
|
||
expressions separated with a colon followed by the usual “for” and “if” clauses.
|
||
When the comprehension is run, the resulting key and value elements are inserted
|
||
in the new dictionary in the order they are produced.</p>
|
||
<p id="index-19">Restrictions on the types of the key values are listed earlier in section
|
||
<a class="reference internal" href="datamodel.html#types"><span class="std std-ref">The standard type hierarchy</span></a>. (To summarize, the key type should be <a class="reference internal" href="../glossary.html#term-hashable"><span class="xref std std-term">hashable</span></a>, which excludes
|
||
all mutable objects.) Clashes between duplicate keys are not detected; the last
|
||
datum (textually rightmost in the display) stored for a given key value
|
||
prevails.</p>
|
||
</div>
|
||
<div class="section" id="generator-expressions">
|
||
<span id="genexpr"></span><h3>6.2.8. Generator expressions<a class="headerlink" href="#generator-expressions" title="Permalink to this headline">¶</a></h3>
|
||
<p id="index-20">A generator expression is a compact generator notation in parentheses:</p>
|
||
<pre>
|
||
<strong id="grammar-token-generator-expression">generator_expression</strong> ::= "(" <a class="reference internal" href="#grammar-token-expression"><code class="xref docutils literal notranslate"><span class="pre">expression</span></code></a> <a class="reference internal" href="#grammar-token-comp-for"><code class="xref docutils literal notranslate"><span class="pre">comp_for</span></code></a> ")"
|
||
</pre>
|
||
<p>A generator expression yields a new generator object. Its syntax is the same as
|
||
for comprehensions, except that it is enclosed in parentheses instead of
|
||
brackets or curly braces.</p>
|
||
<p>Variables used in the generator expression are evaluated lazily when the
|
||
<a class="reference internal" href="#generator.__next__" title="generator.__next__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__next__()</span></code></a> method is called for the generator object (in the same
|
||
fashion as normal generators). However, the iterable expression in the
|
||
leftmost <code class="xref std std-keyword docutils literal notranslate"><span class="pre">for</span></code> clause is immediately evaluated, so that an error
|
||
produced by it will be emitted at the point where the generator expression
|
||
is defined, rather than at the point where the first value is retrieved.
|
||
Subsequent <code class="xref std std-keyword docutils literal notranslate"><span class="pre">for</span></code> clauses and any filter condition in the leftmost
|
||
<code class="xref std std-keyword docutils literal notranslate"><span class="pre">for</span></code> clause cannot be evaluated in the enclosing scope as they may
|
||
depend on the values obtained from the leftmost iterable. For example:
|
||
<code class="docutils literal notranslate"><span class="pre">(x*y</span> <span class="pre">for</span> <span class="pre">x</span> <span class="pre">in</span> <span class="pre">range(10)</span> <span class="pre">for</span> <span class="pre">y</span> <span class="pre">in</span> <span class="pre">range(x,</span> <span class="pre">x+10))</span></code>.</p>
|
||
<p>The parentheses can be omitted on calls with only one argument. See section
|
||
<a class="reference internal" href="#calls"><span class="std std-ref">Calls</span></a> for details.</p>
|
||
<p>To avoid interfering with the expected operation of the generator expression
|
||
itself, <code class="docutils literal notranslate"><span class="pre">yield</span></code> and <code class="docutils literal notranslate"><span class="pre">yield</span> <span class="pre">from</span></code> expressions are prohibited in the
|
||
implicitly defined generator (in Python 3.7, such expressions emit
|
||
<a class="reference internal" href="../library/exceptions.html#DeprecationWarning" title="DeprecationWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">DeprecationWarning</span></code></a> when compiled, in Python 3.8+ they will emit
|
||
<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>If a generator expression contains either <code class="xref std std-keyword docutils literal notranslate"><span class="pre">async</span> <span class="pre">for</span></code>
|
||
clauses or <a class="reference internal" href="#await"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">await</span></code></a> expressions it is called an
|
||
<em class="dfn">asynchronous generator expression</em>. An asynchronous generator
|
||
expression returns a new asynchronous generator object,
|
||
which is an asynchronous iterator (see <a class="reference internal" href="datamodel.html#async-iterators"><span class="std std-ref">Asynchronous Iterators</span></a>).</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.6: </span>Asynchronous generator expressions were introduced.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.7: </span>Prior to Python 3.7, asynchronous generator expressions could
|
||
only appear in <a class="reference internal" href="compound_stmts.html#async-def"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">async</span> <span class="pre">def</span></code></a> coroutines. Starting
|
||
with 3.7, any function can use asynchronous generator expressions.</p>
|
||
</div>
|
||
<div class="deprecated">
|
||
<p><span class="versionmodified deprecated">Deprecated since version 3.7: </span><code class="docutils literal notranslate"><span class="pre">yield</span></code> and <code class="docutils literal notranslate"><span class="pre">yield</span> <span class="pre">from</span></code> deprecated in the implicitly nested scope.</p>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="yield-expressions">
|
||
<span id="yieldexpr"></span><h3>6.2.9. Yield expressions<a class="headerlink" href="#yield-expressions" title="Permalink to this headline">¶</a></h3>
|
||
<pre id="index-21">
|
||
<strong id="grammar-token-yield-atom">yield_atom </strong> ::= "(" <a class="reference internal" href="#grammar-token-yield-expression"><code class="xref docutils literal notranslate"><span class="pre">yield_expression</span></code></a> ")"
|
||
<strong id="grammar-token-yield-expression">yield_expression</strong> ::= "yield" [<a class="reference internal" href="#grammar-token-expression-list"><code class="xref docutils literal notranslate"><span class="pre">expression_list</span></code></a> | "from" <a class="reference internal" href="#grammar-token-expression"><code class="xref docutils literal notranslate"><span class="pre">expression</span></code></a>]
|
||
</pre>
|
||
<p>The yield expression is used when defining a <a class="reference internal" href="../glossary.html#term-generator"><span class="xref std std-term">generator</span></a> function
|
||
or an <a class="reference internal" href="../glossary.html#term-asynchronous-generator"><span class="xref std std-term">asynchronous generator</span></a> function and
|
||
thus can only be used in the body of a function definition. Using a yield
|
||
expression in a function’s body causes that function to be a generator,
|
||
and using it in an <a class="reference internal" href="compound_stmts.html#async-def"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">async</span> <span class="pre">def</span></code></a> function’s body causes that
|
||
coroutine function to be an asynchronous generator. For example:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">gen</span><span class="p">():</span> <span class="c1"># defines a generator function</span>
|
||
<span class="k">yield</span> <span class="mi">123</span>
|
||
|
||
<span class="k">async</span> <span class="k">def</span> <span class="nf">agen</span><span class="p">():</span> <span class="c1"># defines an asynchronous generator function</span>
|
||
<span class="k">yield</span> <span class="mi">123</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Due to their side effects on the containing scope, <code class="docutils literal notranslate"><span class="pre">yield</span></code> expressions
|
||
are not permitted as part of the implicitly defined scopes used to
|
||
implement comprehensions and generator expressions (in Python 3.7, such
|
||
expressions emit <a class="reference internal" href="../library/exceptions.html#DeprecationWarning" title="DeprecationWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">DeprecationWarning</span></code></a> when compiled, in Python 3.8+
|
||
they will emit <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>
|
||
<div class="deprecated">
|
||
<p><span class="versionmodified deprecated">Deprecated since version 3.7: </span>Yield expressions deprecated in the implicitly nested scopes used to
|
||
implement comprehensions and generator expressions.</p>
|
||
</div>
|
||
<p>Generator functions are described below, while asynchronous generator
|
||
functions are described separately in section
|
||
<a class="reference internal" href="#asynchronous-generator-functions"><span class="std std-ref">Asynchronous generator functions</span></a>.</p>
|
||
<p>When a generator function is called, it returns an iterator known as a
|
||
generator. That generator then controls the execution of the generator function.
|
||
The execution starts when one of the generator’s methods is called. At that
|
||
time, the execution proceeds to the first yield expression, where it is
|
||
suspended again, returning the value of <a class="reference internal" href="#grammar-token-expression-list"><code class="xref std std-token docutils literal notranslate"><span class="pre">expression_list</span></code></a> to the generator’s
|
||
caller. By suspended, we mean that all local state is retained, including the
|
||
current bindings of local variables, the instruction pointer, the internal
|
||
evaluation stack, and the state of any exception handling. When the execution
|
||
is resumed by calling one of the
|
||
generator’s methods, the function can proceed exactly as if the yield expression
|
||
were just another external call. The value of the yield expression after
|
||
resuming depends on the method which resumed the execution. If
|
||
<a class="reference internal" href="#generator.__next__" title="generator.__next__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__next__()</span></code></a> is used (typically via either 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
|
||
the <a class="reference internal" href="../library/functions.html#next" title="next"><code class="xref py py-func docutils literal notranslate"><span class="pre">next()</span></code></a> builtin) then the result is <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>. Otherwise, if
|
||
<a class="reference internal" href="#generator.send" title="generator.send"><code class="xref py py-meth docutils literal notranslate"><span class="pre">send()</span></code></a> is used, then the result will be the value passed in to
|
||
that method.</p>
|
||
<p id="index-22">All of this makes generator functions quite similar to coroutines; they yield
|
||
multiple times, they have more than one entry point and their execution can be
|
||
suspended. The only difference is that a generator function cannot control
|
||
where the execution should continue after it yields; the control is always
|
||
transferred to the generator’s caller.</p>
|
||
<p>Yield expressions are allowed anywhere in 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> construct. If the
|
||
generator is not resumed before it is
|
||
finalized (by reaching a zero reference count or by being garbage collected),
|
||
the generator-iterator’s <a class="reference internal" href="#generator.close" title="generator.close"><code class="xref py py-meth docutils literal notranslate"><span class="pre">close()</span></code></a> method will be called,
|
||
allowing any pending <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> clauses to execute.</p>
|
||
<p id="index-23">When <code class="docutils literal notranslate"><span class="pre">yield</span> <span class="pre">from</span> <span class="pre"><expr></span></code> is used, it treats the supplied expression as
|
||
a subiterator. All values produced by that subiterator are passed directly
|
||
to the caller of the current generator’s methods. Any values passed in with
|
||
<a class="reference internal" href="#generator.send" title="generator.send"><code class="xref py py-meth docutils literal notranslate"><span class="pre">send()</span></code></a> and any exceptions passed in with
|
||
<a class="reference internal" href="#generator.throw" title="generator.throw"><code class="xref py py-meth docutils literal notranslate"><span class="pre">throw()</span></code></a> are passed to the underlying iterator if it has the
|
||
appropriate methods. If this is not the case, then <a class="reference internal" href="#generator.send" title="generator.send"><code class="xref py py-meth docutils literal notranslate"><span class="pre">send()</span></code></a>
|
||
will raise <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> or <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>, while
|
||
<a class="reference internal" href="#generator.throw" title="generator.throw"><code class="xref py py-meth docutils literal notranslate"><span class="pre">throw()</span></code></a> will just raise the passed in exception immediately.</p>
|
||
<p>When the underlying iterator is complete, the <code class="xref py py-attr docutils literal notranslate"><span class="pre">value</span></code>
|
||
attribute of the raised <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> instance becomes the value of
|
||
the yield expression. It can be either set explicitly when raising
|
||
<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>, or automatically when the subiterator is a generator
|
||
(by returning a value from the subgenerator).</p>
|
||
<blockquote>
|
||
<div><div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.3: </span>Added <code class="docutils literal notranslate"><span class="pre">yield</span> <span class="pre">from</span> <span class="pre"><expr></span></code> to delegate control flow to a subiterator.</p>
|
||
</div>
|
||
</div></blockquote>
|
||
<p>The parentheses may be omitted when the yield expression is the sole expression
|
||
on the right hand side of an assignment statement.</p>
|
||
<div class="admonition seealso">
|
||
<p class="admonition-title">See also</p>
|
||
<dl class="simple">
|
||
<dt><span class="target" id="index-24"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0255"><strong>PEP 255</strong></a> - Simple Generators</dt><dd><p>The proposal for adding generators and the <a class="reference internal" href="simple_stmts.html#yield"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">yield</span></code></a> statement to Python.</p>
|
||
</dd>
|
||
<dt><span class="target" id="index-25"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0342"><strong>PEP 342</strong></a> - Coroutines via Enhanced Generators</dt><dd><p>The proposal to enhance the API and syntax of generators, making them
|
||
usable as simple coroutines.</p>
|
||
</dd>
|
||
<dt><span class="target" id="index-26"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0380"><strong>PEP 380</strong></a> - Syntax for Delegating to a Subgenerator</dt><dd><p>The proposal to introduce the <code class="xref std std-token docutils literal notranslate"><span class="pre">yield_from</span></code> syntax, making delegation
|
||
to subgenerators easy.</p>
|
||
</dd>
|
||
<dt><span class="target" id="index-27"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0525"><strong>PEP 525</strong></a> - Asynchronous Generators</dt><dd><p>The proposal that expanded on <span class="target" id="index-28"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0492"><strong>PEP 492</strong></a> by adding generator capabilities to
|
||
coroutine functions.</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
<div class="section" id="generator-iterator-methods">
|
||
<span id="generator-methods"></span><span id="index-29"></span><h4>6.2.9.1. Generator-iterator methods<a class="headerlink" href="#generator-iterator-methods" title="Permalink to this headline">¶</a></h4>
|
||
<p>This subsection describes the methods of a generator iterator. They can
|
||
be used to control the execution of a generator function.</p>
|
||
<p>Note that calling any of the generator methods below when the generator
|
||
is already executing raises a <a class="reference internal" href="../library/exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> exception.</p>
|
||
<span class="target" id="index-30"></span><dl class="method">
|
||
<dt id="generator.__next__">
|
||
<code class="descclassname">generator.</code><code class="descname">__next__</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#generator.__next__" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Starts the execution of a generator function or resumes it at the last
|
||
executed yield expression. When a generator function is resumed with a
|
||
<a class="reference internal" href="#generator.__next__" title="generator.__next__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__next__()</span></code></a> method, the current yield expression always
|
||
evaluates to <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>. The execution then continues to the next yield
|
||
expression, where the generator is suspended again, and the value of the
|
||
<a class="reference internal" href="#grammar-token-expression-list"><code class="xref std std-token docutils literal notranslate"><span class="pre">expression_list</span></code></a> is returned to <a class="reference internal" href="#generator.__next__" title="generator.__next__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__next__()</span></code></a>’s caller. If the
|
||
generator exits without yielding another value, a <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>
|
||
exception is raised.</p>
|
||
<p>This method is normally called implicitly, e.g. by 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, or
|
||
by the built-in <a class="reference internal" href="../library/functions.html#next" title="next"><code class="xref py py-func docutils literal notranslate"><span class="pre">next()</span></code></a> function.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="generator.send">
|
||
<code class="descclassname">generator.</code><code class="descname">send</code><span class="sig-paren">(</span><em>value</em><span class="sig-paren">)</span><a class="headerlink" href="#generator.send" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Resumes the execution and “sends” a value into the generator function. The
|
||
<em>value</em> argument becomes the result of the current yield expression. The
|
||
<a class="reference internal" href="#generator.send" title="generator.send"><code class="xref py py-meth docutils literal notranslate"><span class="pre">send()</span></code></a> method returns the next value yielded by the generator, or
|
||
raises <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> if the generator exits without yielding another
|
||
value. When <a class="reference internal" href="#generator.send" title="generator.send"><code class="xref py py-meth docutils literal notranslate"><span class="pre">send()</span></code></a> is called to start the generator, it must be called
|
||
with <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> as the argument, because there is no yield expression that
|
||
could receive the value.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="generator.throw">
|
||
<code class="descclassname">generator.</code><code class="descname">throw</code><span class="sig-paren">(</span><em>type</em><span class="optional">[</span>, <em>value</em><span class="optional">[</span>, <em>traceback</em><span class="optional">]</span><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#generator.throw" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Raises an exception of type <code class="docutils literal notranslate"><span class="pre">type</span></code> at the point where the generator was paused,
|
||
and returns the next value yielded by the generator function. If the generator
|
||
exits without yielding another value, a <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> exception is
|
||
raised. If the generator function does not catch the passed-in exception, or
|
||
raises a different exception, then that exception propagates to the caller.</p>
|
||
</dd></dl>
|
||
|
||
<span class="target" id="index-31"></span><dl class="method">
|
||
<dt id="generator.close">
|
||
<code class="descclassname">generator.</code><code class="descname">close</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#generator.close" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Raises a <a class="reference internal" href="../library/exceptions.html#GeneratorExit" title="GeneratorExit"><code class="xref py py-exc docutils literal notranslate"><span class="pre">GeneratorExit</span></code></a> at the point where the generator function was
|
||
paused. If the generator function then exits gracefully, is already closed,
|
||
or raises <a class="reference internal" href="../library/exceptions.html#GeneratorExit" title="GeneratorExit"><code class="xref py py-exc docutils literal notranslate"><span class="pre">GeneratorExit</span></code></a> (by not catching the exception), close
|
||
returns to its caller. If the generator yields a value, 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> is raised. If the generator raises any other exception,
|
||
it is propagated to the caller. <a class="reference internal" href="#generator.close" title="generator.close"><code class="xref py py-meth docutils literal notranslate"><span class="pre">close()</span></code></a> does nothing if the generator
|
||
has already exited due to an exception or normal exit.</p>
|
||
</dd></dl>
|
||
|
||
</div>
|
||
<div class="section" id="examples">
|
||
<span id="index-32"></span><h4>6.2.9.2. Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h4>
|
||
<p>Here is a simple example that demonstrates the behavior of generators and
|
||
generator functions:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="k">def</span> <span class="nf">echo</span><span class="p">(</span><span class="n">value</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
|
||
<span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="s2">"Execution starts when 'next()' is called for the first time."</span><span class="p">)</span>
|
||
<span class="gp">... </span> <span class="k">try</span><span class="p">:</span>
|
||
<span class="gp">... </span> <span class="k">while</span> <span class="kc">True</span><span class="p">:</span>
|
||
<span class="gp">... </span> <span class="k">try</span><span class="p">:</span>
|
||
<span class="gp">... </span> <span class="n">value</span> <span class="o">=</span> <span class="p">(</span><span class="k">yield</span> <span class="n">value</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">e</span><span class="p">:</span>
|
||
<span class="gp">... </span> <span class="n">value</span> <span class="o">=</span> <span class="n">e</span>
|
||
<span class="gp">... </span> <span class="k">finally</span><span class="p">:</span>
|
||
<span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="s2">"Don't forget to clean up when 'close()' is called."</span><span class="p">)</span>
|
||
<span class="gp">...</span>
|
||
<span class="gp">>>> </span><span class="n">generator</span> <span class="o">=</span> <span class="n">echo</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="nb">next</span><span class="p">(</span><span class="n">generator</span><span class="p">))</span>
|
||
<span class="go">Execution starts when 'next()' is called for the first time.</span>
|
||
<span class="go">1</span>
|
||
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="nb">next</span><span class="p">(</span><span class="n">generator</span><span class="p">))</span>
|
||
<span class="go">None</span>
|
||
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">generator</span><span class="o">.</span><span class="n">send</span><span class="p">(</span><span class="mi">2</span><span class="p">))</span>
|
||
<span class="go">2</span>
|
||
<span class="gp">>>> </span><span class="n">generator</span><span class="o">.</span><span class="n">throw</span><span class="p">(</span><span class="ne">TypeError</span><span class="p">,</span> <span class="s2">"spam"</span><span class="p">)</span>
|
||
<span class="go">TypeError('spam',)</span>
|
||
<span class="gp">>>> </span><span class="n">generator</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
|
||
<span class="go">Don't forget to clean up when 'close()' is called.</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>For examples using <code class="docutils literal notranslate"><span class="pre">yield</span> <span class="pre">from</span></code>, see <a class="reference internal" href="../whatsnew/3.3.html#pep-380"><span class="std std-ref">PEP 380: Syntax for Delegating to a Subgenerator</span></a> in “What’s New in
|
||
Python.”</p>
|
||
</div>
|
||
<div class="section" id="asynchronous-generator-functions">
|
||
<span id="id3"></span><h4>6.2.9.3. Asynchronous generator functions<a class="headerlink" href="#asynchronous-generator-functions" title="Permalink to this headline">¶</a></h4>
|
||
<p>The presence of a yield expression in a function or method defined using
|
||
<a class="reference internal" href="compound_stmts.html#async-def"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">async</span> <span class="pre">def</span></code></a> further defines the function as an
|
||
<a class="reference internal" href="../glossary.html#term-asynchronous-generator"><span class="xref std std-term">asynchronous generator</span></a> function.</p>
|
||
<p>When an asynchronous generator function is called, it returns an
|
||
asynchronous iterator known as an asynchronous generator object.
|
||
That object then controls the execution of the generator function.
|
||
An asynchronous generator object is typically used in an
|
||
<a class="reference internal" href="compound_stmts.html#async-for"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">async</span> <span class="pre">for</span></code></a> statement in a coroutine function analogously to
|
||
how a generator object would be used 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> statement.</p>
|
||
<p>Calling one of the asynchronous generator’s methods returns an
|
||
<a class="reference internal" href="../glossary.html#term-awaitable"><span class="xref std std-term">awaitable</span></a> object, and the execution starts when this object
|
||
is awaited on. At that time, the execution proceeds to the first yield
|
||
expression, where it is suspended again, returning the value of
|
||
<a class="reference internal" href="#grammar-token-expression-list"><code class="xref std std-token docutils literal notranslate"><span class="pre">expression_list</span></code></a> to the awaiting coroutine. As with a generator,
|
||
suspension means that all local state is retained, including the
|
||
current bindings of local variables, the instruction pointer, the internal
|
||
evaluation stack, and the state of any exception handling. When the execution
|
||
is resumed by awaiting on the next object returned by the asynchronous
|
||
generator’s methods, the function can proceed exactly as if the yield
|
||
expression were just another external call. The value of the yield expression
|
||
after resuming depends on the method which resumed the execution. If
|
||
<a class="reference internal" href="#agen.__anext__" title="agen.__anext__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__anext__()</span></code></a> is used then the result is <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>. Otherwise, if
|
||
<a class="reference internal" href="#agen.asend" title="agen.asend"><code class="xref py py-meth docutils literal notranslate"><span class="pre">asend()</span></code></a> is used, then the result will be the value passed in to
|
||
that method.</p>
|
||
<p>In an asynchronous generator function, yield expressions are allowed anywhere
|
||
in 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> construct. However, if an asynchronous generator is not
|
||
resumed before it is finalized (by reaching a zero reference count or by
|
||
being garbage collected), then a yield expression within a <code class="xref std std-keyword docutils literal notranslate"><span class="pre">try</span></code>
|
||
construct could result in a failure to execute pending <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>
|
||
clauses. In this case, it is the responsibility of the event loop or
|
||
scheduler running the asynchronous generator to call the asynchronous
|
||
generator-iterator’s <a class="reference internal" href="#agen.aclose" title="agen.aclose"><code class="xref py py-meth docutils literal notranslate"><span class="pre">aclose()</span></code></a> method and run the resulting
|
||
coroutine object, thus allowing any pending <code class="xref std std-keyword docutils literal notranslate"><span class="pre">finally</span></code> clauses
|
||
to execute.</p>
|
||
<p>To take care of finalization, an event loop should define
|
||
a <em>finalizer</em> function which takes an asynchronous generator-iterator
|
||
and presumably calls <a class="reference internal" href="#agen.aclose" title="agen.aclose"><code class="xref py py-meth docutils literal notranslate"><span class="pre">aclose()</span></code></a> and executes the coroutine.
|
||
This <em>finalizer</em> may be registered by calling <a class="reference internal" href="../library/sys.html#sys.set_asyncgen_hooks" title="sys.set_asyncgen_hooks"><code class="xref py py-func docutils literal notranslate"><span class="pre">sys.set_asyncgen_hooks()</span></code></a>.
|
||
When first iterated over, an asynchronous generator-iterator will store the
|
||
registered <em>finalizer</em> to be called upon finalization. For a reference example
|
||
of a <em>finalizer</em> method see the implementation of
|
||
<code class="docutils literal notranslate"><span class="pre">asyncio.Loop.shutdown_asyncgens</span></code> in <a class="reference external" href="https://github.com/python/cpython/tree/3.7/Lib/asyncio/base_events.py">Lib/asyncio/base_events.py</a>.</p>
|
||
<p>The expression <code class="docutils literal notranslate"><span class="pre">yield</span> <span class="pre">from</span> <span class="pre"><expr></span></code> is a syntax error when used in an
|
||
asynchronous generator function.</p>
|
||
</div>
|
||
<div class="section" id="asynchronous-generator-iterator-methods">
|
||
<span id="asynchronous-generator-methods"></span><span id="index-33"></span><h4>6.2.9.4. Asynchronous generator-iterator methods<a class="headerlink" href="#asynchronous-generator-iterator-methods" title="Permalink to this headline">¶</a></h4>
|
||
<p>This subsection describes the methods of an asynchronous generator iterator,
|
||
which are used to control the execution of a generator function.</p>
|
||
<span class="target" id="index-34"></span><dl class="method">
|
||
<dt id="agen.__anext__">
|
||
<em class="property">coroutine </em><code class="descclassname">agen.</code><code class="descname">__anext__</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#agen.__anext__" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns an awaitable which when run starts to execute the asynchronous
|
||
generator or resumes it at the last executed yield expression. When an
|
||
asynchronous generator function is resumed with an <a class="reference internal" href="#agen.__anext__" title="agen.__anext__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__anext__()</span></code></a>
|
||
method, the current yield expression always evaluates to <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 returned awaitable, which when run will continue to the next yield
|
||
expression. The value of the <a class="reference internal" href="#grammar-token-expression-list"><code class="xref std std-token docutils literal notranslate"><span class="pre">expression_list</span></code></a> of the yield
|
||
expression is the value of the <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> exception raised by
|
||
the completing coroutine. If the asynchronous generator exits without
|
||
yielding another value, the awaitable instead raises a
|
||
<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> exception, signalling that the asynchronous
|
||
iteration has completed.</p>
|
||
<p>This method is normally called implicitly by a <a class="reference internal" href="compound_stmts.html#async-for"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">async</span> <span class="pre">for</span></code></a> loop.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="agen.asend">
|
||
<em class="property">coroutine </em><code class="descclassname">agen.</code><code class="descname">asend</code><span class="sig-paren">(</span><em>value</em><span class="sig-paren">)</span><a class="headerlink" href="#agen.asend" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns an awaitable which when run resumes the execution of the
|
||
asynchronous generator. As with the <a class="reference internal" href="#generator.send" title="generator.send"><code class="xref py py-meth docutils literal notranslate"><span class="pre">send()</span></code></a> method for a
|
||
generator, this “sends” a value into the asynchronous generator function,
|
||
and the <em>value</em> argument becomes the result of the current yield expression.
|
||
The awaitable returned by the <a class="reference internal" href="#agen.asend" title="agen.asend"><code class="xref py py-meth docutils literal notranslate"><span class="pre">asend()</span></code></a> method will return the next
|
||
value yielded by the generator as the value of the raised
|
||
<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>, or raises <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> if the
|
||
asynchronous generator exits without yielding another value. When
|
||
<a class="reference internal" href="#agen.asend" title="agen.asend"><code class="xref py py-meth docutils literal notranslate"><span class="pre">asend()</span></code></a> is called to start the asynchronous
|
||
generator, it must be called with <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> as the argument,
|
||
because there is no yield expression that could receive the value.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="agen.athrow">
|
||
<em class="property">coroutine </em><code class="descclassname">agen.</code><code class="descname">athrow</code><span class="sig-paren">(</span><em>type</em><span class="optional">[</span>, <em>value</em><span class="optional">[</span>, <em>traceback</em><span class="optional">]</span><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#agen.athrow" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns an awaitable that raises an exception of type <code class="docutils literal notranslate"><span class="pre">type</span></code> at the point
|
||
where the asynchronous generator was paused, and returns the next value
|
||
yielded by the generator function as the value of the raised
|
||
<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> exception. If the asynchronous generator exits
|
||
without yielding another value, a <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> exception is
|
||
raised by the awaitable.
|
||
If the generator function does not catch the passed-in exception, or
|
||
raises a different exception, then when the awaitable is run that exception
|
||
propagates to the caller of the awaitable.</p>
|
||
</dd></dl>
|
||
|
||
<span class="target" id="index-35"></span><dl class="method">
|
||
<dt id="agen.aclose">
|
||
<em class="property">coroutine </em><code class="descclassname">agen.</code><code class="descname">aclose</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#agen.aclose" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns an awaitable that when run will throw a <a class="reference internal" href="../library/exceptions.html#GeneratorExit" title="GeneratorExit"><code class="xref py py-exc docutils literal notranslate"><span class="pre">GeneratorExit</span></code></a> into
|
||
the asynchronous generator function at the point where it was paused.
|
||
If the asynchronous generator function then exits gracefully, is already
|
||
closed, or raises <a class="reference internal" href="../library/exceptions.html#GeneratorExit" title="GeneratorExit"><code class="xref py py-exc docutils literal notranslate"><span class="pre">GeneratorExit</span></code></a> (by not catching the exception),
|
||
then the returned awaitable will raise a <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> exception.
|
||
Any further awaitables returned by subsequent calls to the asynchronous
|
||
generator will raise a <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> exception. If the
|
||
asynchronous generator yields a value, 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> is raised
|
||
by the awaitable. If the asynchronous generator raises any other exception,
|
||
it is propagated to the caller of the awaitable. If the asynchronous
|
||
generator has already exited due to an exception or normal exit, then
|
||
further calls to <a class="reference internal" href="#agen.aclose" title="agen.aclose"><code class="xref py py-meth docutils literal notranslate"><span class="pre">aclose()</span></code></a> will return an awaitable that does nothing.</p>
|
||
</dd></dl>
|
||
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="primaries">
|
||
<span id="id4"></span><h2>6.3. Primaries<a class="headerlink" href="#primaries" title="Permalink to this headline">¶</a></h2>
|
||
<p id="index-36">Primaries represent the most tightly bound operations of the language. Their
|
||
syntax is:</p>
|
||
<pre>
|
||
<strong id="grammar-token-primary">primary</strong> ::= <a class="reference internal" href="#grammar-token-atom"><code class="xref docutils literal notranslate"><span class="pre">atom</span></code></a> | <a class="reference internal" href="#grammar-token-attributeref"><code class="xref docutils literal notranslate"><span class="pre">attributeref</span></code></a> | <a class="reference internal" href="#grammar-token-subscription"><code class="xref docutils literal notranslate"><span class="pre">subscription</span></code></a> | <a class="reference internal" href="#grammar-token-slicing"><code class="xref docutils literal notranslate"><span class="pre">slicing</span></code></a> | <a class="reference internal" href="#grammar-token-call"><code class="xref docutils literal notranslate"><span class="pre">call</span></code></a>
|
||
</pre>
|
||
<div class="section" id="attribute-references">
|
||
<span id="id5"></span><h3>6.3.1. Attribute references<a class="headerlink" href="#attribute-references" title="Permalink to this headline">¶</a></h3>
|
||
<p id="index-37">An attribute reference is a primary followed by a period and a name:</p>
|
||
<pre>
|
||
<strong id="grammar-token-attributeref">attributeref</strong> ::= <a class="reference internal" href="#grammar-token-primary"><code class="xref docutils literal notranslate"><span class="pre">primary</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 id="index-38">The primary must evaluate to an object of a type that supports attribute
|
||
references, which most objects do. This object is then asked to produce the
|
||
attribute whose name is the identifier. This production can be customized by
|
||
overriding the <a class="reference internal" href="datamodel.html#object.__getattr__" title="object.__getattr__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__getattr__()</span></code></a> method. If this attribute is not available,
|
||
the exception <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> is raised. Otherwise, the type and value of
|
||
the object produced is determined by the object. Multiple evaluations of the
|
||
same attribute reference may yield different objects.</p>
|
||
</div>
|
||
<div class="section" id="subscriptions">
|
||
<span id="id6"></span><h3>6.3.2. Subscriptions<a class="headerlink" href="#subscriptions" title="Permalink to this headline">¶</a></h3>
|
||
<span class="target" id="index-39"></span><p id="index-40">A subscription selects an item of a sequence (string, tuple or list) or mapping
|
||
(dictionary) object:</p>
|
||
<pre>
|
||
<strong id="grammar-token-subscription">subscription</strong> ::= <a class="reference internal" href="#grammar-token-primary"><code class="xref docutils literal notranslate"><span class="pre">primary</span></code></a> "[" <a class="reference internal" href="#grammar-token-expression-list"><code class="xref docutils literal notranslate"><span class="pre">expression_list</span></code></a> "]"
|
||
</pre>
|
||
<p>The primary must evaluate to an object that supports subscription (lists or
|
||
dictionaries for example). User-defined objects can support subscription by
|
||
defining a <a class="reference internal" href="datamodel.html#object.__getitem__" title="object.__getitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__getitem__()</span></code></a> method.</p>
|
||
<p>For built-in objects, there are two types of objects that support subscription:</p>
|
||
<p>If the primary is a mapping, the expression list must evaluate to an object
|
||
whose value is one of the keys of the mapping, and the subscription selects the
|
||
value in the mapping that corresponds to that key. (The expression list is a
|
||
tuple except if it has exactly one item.)</p>
|
||
<p>If the primary is a sequence, the expression list must evaluate to an integer
|
||
or a slice (as discussed in the following section).</p>
|
||
<p>The formal syntax makes no special provision for negative indices in
|
||
sequences; however, built-in sequences all provide a <a class="reference internal" href="datamodel.html#object.__getitem__" title="object.__getitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__getitem__()</span></code></a>
|
||
method that interprets negative indices by adding the length of the sequence
|
||
to the index (so that <code class="docutils literal notranslate"><span class="pre">x[-1]</span></code> selects the last item of <code class="docutils literal notranslate"><span class="pre">x</span></code>). The
|
||
resulting value must be a nonnegative integer less than the number of items in
|
||
the sequence, and the subscription selects the item whose index is that value
|
||
(counting from zero). Since the support for negative indices and slicing
|
||
occurs in the object’s <a class="reference internal" href="datamodel.html#object.__getitem__" title="object.__getitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__getitem__()</span></code></a> method, subclasses overriding
|
||
this method will need to explicitly add that support.</p>
|
||
<p id="index-41">A string’s items are characters. A character is not a separate data type but a
|
||
string of exactly one character.</p>
|
||
</div>
|
||
<div class="section" id="slicings">
|
||
<span id="id7"></span><h3>6.3.3. Slicings<a class="headerlink" href="#slicings" title="Permalink to this headline">¶</a></h3>
|
||
<span class="target" id="index-42"></span><p id="index-43">A slicing selects a range of items in a sequence object (e.g., a string, tuple
|
||
or list). Slicings may be used as expressions or as targets in assignment or
|
||
<a class="reference internal" href="simple_stmts.html#del"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">del</span></code></a> statements. The syntax for a slicing:</p>
|
||
<pre>
|
||
<strong id="grammar-token-slicing">slicing </strong> ::= <a class="reference internal" href="#grammar-token-primary"><code class="xref docutils literal notranslate"><span class="pre">primary</span></code></a> "[" <a class="reference internal" href="#grammar-token-slice-list"><code class="xref docutils literal notranslate"><span class="pre">slice_list</span></code></a> "]"
|
||
<strong id="grammar-token-slice-list">slice_list </strong> ::= <a class="reference internal" href="#grammar-token-slice-item"><code class="xref docutils literal notranslate"><span class="pre">slice_item</span></code></a> ("," <a class="reference internal" href="#grammar-token-slice-item"><code class="xref docutils literal notranslate"><span class="pre">slice_item</span></code></a>)* [","]
|
||
<strong id="grammar-token-slice-item">slice_item </strong> ::= <a class="reference internal" href="#grammar-token-expression"><code class="xref docutils literal notranslate"><span class="pre">expression</span></code></a> | <a class="reference internal" href="#grammar-token-proper-slice"><code class="xref docutils literal notranslate"><span class="pre">proper_slice</span></code></a>
|
||
<strong id="grammar-token-proper-slice">proper_slice</strong> ::= [<a class="reference internal" href="#grammar-token-lower-bound"><code class="xref docutils literal notranslate"><span class="pre">lower_bound</span></code></a>] ":" [<a class="reference internal" href="#grammar-token-upper-bound"><code class="xref docutils literal notranslate"><span class="pre">upper_bound</span></code></a>] [ ":" [<a class="reference internal" href="#grammar-token-stride"><code class="xref docutils literal notranslate"><span class="pre">stride</span></code></a>] ]
|
||
<strong id="grammar-token-lower-bound">lower_bound </strong> ::= <a class="reference internal" href="#grammar-token-expression"><code class="xref docutils literal notranslate"><span class="pre">expression</span></code></a>
|
||
<strong id="grammar-token-upper-bound">upper_bound </strong> ::= <a class="reference internal" href="#grammar-token-expression"><code class="xref docutils literal notranslate"><span class="pre">expression</span></code></a>
|
||
<strong id="grammar-token-stride">stride </strong> ::= <a class="reference internal" href="#grammar-token-expression"><code class="xref docutils literal notranslate"><span class="pre">expression</span></code></a>
|
||
</pre>
|
||
<p>There is ambiguity in the formal syntax here: anything that looks like an
|
||
expression list also looks like a slice list, so any subscription can be
|
||
interpreted as a slicing. Rather than further complicating the syntax, this is
|
||
disambiguated by defining that in this case the interpretation as a subscription
|
||
takes priority over the interpretation as a slicing (this is the case if the
|
||
slice list contains no proper slice).</p>
|
||
<p id="index-44">The semantics for a slicing are as follows. The primary is indexed (using the
|
||
same <a class="reference internal" href="datamodel.html#object.__getitem__" title="object.__getitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__getitem__()</span></code></a> method as
|
||
normal subscription) with a key that is constructed from the slice list, as
|
||
follows. If the slice list contains at least one comma, the key is a tuple
|
||
containing the conversion of the slice items; otherwise, the conversion of the
|
||
lone slice item is the key. The conversion of a slice item that is an
|
||
expression is that expression. The conversion of a proper slice is a slice
|
||
object (see section <a class="reference internal" href="datamodel.html#types"><span class="std std-ref">The standard type hierarchy</span></a>) whose <code class="xref py py-attr docutils literal notranslate"><span class="pre">start</span></code>,
|
||
<code class="xref py py-attr docutils literal notranslate"><span class="pre">stop</span></code> and <code class="xref py py-attr docutils literal notranslate"><span class="pre">step</span></code> attributes are the values of the
|
||
expressions given as lower bound, upper bound and stride, respectively,
|
||
substituting <code class="docutils literal notranslate"><span class="pre">None</span></code> for missing expressions.</p>
|
||
</div>
|
||
<div class="section" id="calls">
|
||
<span id="index-45"></span><span id="id8"></span><h3>6.3.4. Calls<a class="headerlink" href="#calls" title="Permalink to this headline">¶</a></h3>
|
||
<p>A call calls a callable object (e.g., a <a class="reference internal" href="../glossary.html#term-function"><span class="xref std std-term">function</span></a>) with a possibly empty
|
||
series of <a class="reference internal" href="../glossary.html#term-argument"><span class="xref std std-term">arguments</span></a>:</p>
|
||
<pre>
|
||
<strong id="grammar-token-call">call </strong> ::= <a class="reference internal" href="#grammar-token-primary"><code class="xref docutils literal notranslate"><span class="pre">primary</span></code></a> "(" [<a class="reference internal" href="#grammar-token-argument-list"><code class="xref docutils literal notranslate"><span class="pre">argument_list</span></code></a> [","] | <a class="reference internal" href="#grammar-token-comprehension"><code class="xref docutils literal notranslate"><span class="pre">comprehension</span></code></a>] ")"
|
||
<strong id="grammar-token-argument-list">argument_list </strong> ::= <a class="reference internal" href="#grammar-token-positional-arguments"><code class="xref docutils literal notranslate"><span class="pre">positional_arguments</span></code></a> ["," <a class="reference internal" href="#grammar-token-starred-and-keywords"><code class="xref docutils literal notranslate"><span class="pre">starred_and_keywords</span></code></a>]
|
||
["," <a class="reference internal" href="#grammar-token-keywords-arguments"><code class="xref docutils literal notranslate"><span class="pre">keywords_arguments</span></code></a>]
|
||
| <a class="reference internal" href="#grammar-token-starred-and-keywords"><code class="xref docutils literal notranslate"><span class="pre">starred_and_keywords</span></code></a> ["," <a class="reference internal" href="#grammar-token-keywords-arguments"><code class="xref docutils literal notranslate"><span class="pre">keywords_arguments</span></code></a>]
|
||
| <a class="reference internal" href="#grammar-token-keywords-arguments"><code class="xref docutils literal notranslate"><span class="pre">keywords_arguments</span></code></a>
|
||
<strong id="grammar-token-positional-arguments">positional_arguments</strong> ::= ["*"] <a class="reference internal" href="#grammar-token-expression"><code class="xref docutils literal notranslate"><span class="pre">expression</span></code></a> ("," ["*"] <a class="reference internal" href="#grammar-token-expression"><code class="xref docutils literal notranslate"><span class="pre">expression</span></code></a>)*
|
||
<strong id="grammar-token-starred-and-keywords">starred_and_keywords</strong> ::= ("*" <a class="reference internal" href="#grammar-token-expression"><code class="xref docutils literal notranslate"><span class="pre">expression</span></code></a> | <a class="reference internal" href="#grammar-token-keyword-item"><code class="xref docutils literal notranslate"><span class="pre">keyword_item</span></code></a>)
|
||
("," "*" <a class="reference internal" href="#grammar-token-expression"><code class="xref docutils literal notranslate"><span class="pre">expression</span></code></a> | "," <a class="reference internal" href="#grammar-token-keyword-item"><code class="xref docutils literal notranslate"><span class="pre">keyword_item</span></code></a>)*
|
||
<strong id="grammar-token-keywords-arguments">keywords_arguments </strong> ::= (<a class="reference internal" href="#grammar-token-keyword-item"><code class="xref docutils literal notranslate"><span class="pre">keyword_item</span></code></a> | "**" <a class="reference internal" href="#grammar-token-expression"><code class="xref docutils literal notranslate"><span class="pre">expression</span></code></a>)
|
||
("," <a class="reference internal" href="#grammar-token-keyword-item"><code class="xref docutils literal notranslate"><span class="pre">keyword_item</span></code></a> | "," "**" <a class="reference internal" href="#grammar-token-expression"><code class="xref docutils literal notranslate"><span class="pre">expression</span></code></a>)*
|
||
<strong id="grammar-token-keyword-item">keyword_item </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-expression"><code class="xref docutils literal notranslate"><span class="pre">expression</span></code></a>
|
||
</pre>
|
||
<p>An optional trailing comma may be present after the positional and keyword arguments
|
||
but does not affect the semantics.</p>
|
||
<p id="index-46">The primary must evaluate to a callable object (user-defined functions, built-in
|
||
functions, methods of built-in objects, class objects, methods of class
|
||
instances, and all objects having a <a class="reference internal" href="datamodel.html#object.__call__" title="object.__call__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__call__()</span></code></a> method are callable). All
|
||
argument expressions are evaluated before the call is attempted. Please refer
|
||
to section <a class="reference internal" href="compound_stmts.html#function"><span class="std std-ref">Function definitions</span></a> for the syntax of formal <a class="reference internal" href="../glossary.html#term-parameter"><span class="xref std std-term">parameter</span></a> lists.</p>
|
||
<p>If keyword arguments are present, they are first converted to positional
|
||
arguments, as follows. First, a list of unfilled slots is created for the
|
||
formal parameters. If there are N positional arguments, they are placed in the
|
||
first N slots. Next, for each keyword argument, the identifier is used to
|
||
determine the corresponding slot (if the identifier is the same as the first
|
||
formal parameter name, the first slot is used, and so on). If the slot is
|
||
already filled, a <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> exception is raised. Otherwise, the value of
|
||
the argument is placed in the slot, filling it (even if the expression is
|
||
<code class="docutils literal notranslate"><span class="pre">None</span></code>, it fills the slot). When all arguments have been processed, the slots
|
||
that are still unfilled are filled with the corresponding default value from the
|
||
function definition. (Default values are calculated, once, when the function is
|
||
defined; thus, a mutable object such as a list or dictionary used as default
|
||
value will be shared by all calls that don’t specify an argument value for the
|
||
corresponding slot; this should usually be avoided.) If there are any unfilled
|
||
slots for which no default value is specified, a <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> exception is
|
||
raised. Otherwise, the list of filled slots is used as the argument list for
|
||
the call.</p>
|
||
<div class="impl-detail compound">
|
||
<p><strong>CPython implementation detail:</strong> An implementation may provide built-in functions whose positional parameters
|
||
do not have names, even if they are ‘named’ for the purpose of documentation,
|
||
and which therefore cannot be supplied by keyword. In CPython, this is the
|
||
case for functions implemented in C that use <a class="reference internal" href="../c-api/arg.html#c.PyArg_ParseTuple" title="PyArg_ParseTuple"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_ParseTuple()</span></code></a> to
|
||
parse their arguments.</p>
|
||
</div>
|
||
<p>If there are more positional arguments than there are formal parameter slots, a
|
||
<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> exception is raised, unless a formal parameter using the syntax
|
||
<code class="docutils literal notranslate"><span class="pre">*identifier</span></code> is present; in this case, that formal parameter receives a tuple
|
||
containing the excess positional arguments (or an empty tuple if there were no
|
||
excess positional arguments).</p>
|
||
<p>If any keyword argument does not correspond to a formal parameter name, a
|
||
<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> exception is raised, unless a formal parameter using the syntax
|
||
<code class="docutils literal notranslate"><span class="pre">**identifier</span></code> is present; in this case, that formal parameter receives a
|
||
dictionary containing the excess keyword arguments (using the keywords as keys
|
||
and the argument values as corresponding values), or a (new) empty dictionary if
|
||
there were no excess keyword arguments.</p>
|
||
<p id="index-47">If the syntax <code class="docutils literal notranslate"><span class="pre">*expression</span></code> appears in the function call, <code class="docutils literal notranslate"><span class="pre">expression</span></code> must
|
||
evaluate to an <a class="reference internal" href="../glossary.html#term-iterable"><span class="xref std std-term">iterable</span></a>. Elements from these iterables are
|
||
treated as if they were additional positional arguments. For the call
|
||
<code class="docutils literal notranslate"><span class="pre">f(x1,</span> <span class="pre">x2,</span> <span class="pre">*y,</span> <span class="pre">x3,</span> <span class="pre">x4)</span></code>, if <em>y</em> evaluates to a sequence <em>y1</em>, …, <em>yM</em>,
|
||
this is equivalent to a call with M+4 positional arguments <em>x1</em>, <em>x2</em>,
|
||
<em>y1</em>, …, <em>yM</em>, <em>x3</em>, <em>x4</em>.</p>
|
||
<p>A consequence of this is that although the <code class="docutils literal notranslate"><span class="pre">*expression</span></code> syntax may appear
|
||
<em>after</em> explicit keyword arguments, it is processed <em>before</em> the
|
||
keyword arguments (and any <code class="docutils literal notranslate"><span class="pre">**expression</span></code> arguments – see below). So:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="k">def</span> <span class="nf">f</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">):</span>
|
||
<span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">)</span>
|
||
<span class="gp">...</span>
|
||
<span class="gp">>>> </span><span class="n">f</span><span class="p">(</span><span class="n">b</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="o">*</span><span class="p">(</span><span class="mi">2</span><span class="p">,))</span>
|
||
<span class="go">2 1</span>
|
||
<span class="gp">>>> </span><span class="n">f</span><span class="p">(</span><span class="n">a</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="o">*</span><span class="p">(</span><span class="mi">2</span><span class="p">,))</span>
|
||
<span class="gt">Traceback (most recent call last):</span>
|
||
File <span class="nb">"<stdin>"</span>, line <span class="m">1</span>, in <span class="n"><module></span>
|
||
<span class="gr">TypeError</span>: <span class="n">f() got multiple values for keyword argument 'a'</span>
|
||
<span class="gp">>>> </span><span class="n">f</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="o">*</span><span class="p">(</span><span class="mi">2</span><span class="p">,))</span>
|
||
<span class="go">1 2</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>It is unusual for both keyword arguments and the <code class="docutils literal notranslate"><span class="pre">*expression</span></code> syntax to be
|
||
used in the same call, so in practice this confusion does not arise.</p>
|
||
<p id="index-48">If the syntax <code class="docutils literal notranslate"><span class="pre">**expression</span></code> appears in the function call, <code class="docutils literal notranslate"><span class="pre">expression</span></code> must
|
||
evaluate to a <a class="reference internal" href="../glossary.html#term-mapping"><span class="xref std std-term">mapping</span></a>, the contents of which are treated as
|
||
additional keyword arguments. If a keyword is already present
|
||
(as an explicit keyword argument, or from another unpacking),
|
||
a <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> exception is raised.</p>
|
||
<p>Formal parameters using the syntax <code class="docutils literal notranslate"><span class="pre">*identifier</span></code> or <code class="docutils literal notranslate"><span class="pre">**identifier</span></code> cannot be
|
||
used as positional argument slots or as keyword argument names.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.5: </span>Function calls accept any number of <code class="docutils literal notranslate"><span class="pre">*</span></code> and <code class="docutils literal notranslate"><span class="pre">**</span></code> unpackings,
|
||
positional arguments may follow iterable unpackings (<code class="docutils literal notranslate"><span class="pre">*</span></code>),
|
||
and keyword arguments may follow dictionary unpackings (<code class="docutils literal notranslate"><span class="pre">**</span></code>).
|
||
Originally proposed by <span class="target" id="index-49"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0448"><strong>PEP 448</strong></a>.</p>
|
||
</div>
|
||
<p>A call always returns some value, possibly <code class="docutils literal notranslate"><span class="pre">None</span></code>, unless it raises an
|
||
exception. How this value is computed depends on the type of the callable
|
||
object.</p>
|
||
<p>If it is—</p>
|
||
<dl>
|
||
<dt>a user-defined function:</dt><dd><p id="index-50">The code block for the function is executed, passing it the argument list. The
|
||
first thing the code block will do is bind the formal parameters to the
|
||
arguments; this is described in section <a class="reference internal" href="compound_stmts.html#function"><span class="std std-ref">Function definitions</span></a>. When the code block
|
||
executes a <a class="reference internal" href="simple_stmts.html#return"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">return</span></code></a> statement, this specifies the return value of the
|
||
function call.</p>
|
||
</dd>
|
||
<dt>a built-in function or method:</dt><dd><p id="index-51">The result is up to the interpreter; see <a class="reference internal" href="../library/functions.html#built-in-funcs"><span class="std std-ref">Built-in Functions</span></a> for the
|
||
descriptions of built-in functions and methods.</p>
|
||
</dd>
|
||
<dt>a class object:</dt><dd><p id="index-52">A new instance of that class is returned.</p>
|
||
</dd>
|
||
<dt>a class instance method:</dt><dd><p id="index-53">The corresponding user-defined function is called, with an argument list that is
|
||
one longer than the argument list of the call: the instance becomes the first
|
||
argument.</p>
|
||
</dd>
|
||
<dt>a class instance:</dt><dd><p id="index-54">The class must define a <a class="reference internal" href="datamodel.html#object.__call__" title="object.__call__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__call__()</span></code></a> method; the effect is then the same as
|
||
if that method was called.</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="await-expression">
|
||
<span id="await"></span><span id="index-55"></span><h2>6.4. Await expression<a class="headerlink" href="#await-expression" title="Permalink to this headline">¶</a></h2>
|
||
<p>Suspend the execution of <a class="reference internal" href="../glossary.html#term-coroutine"><span class="xref std std-term">coroutine</span></a> on an <a class="reference internal" href="../glossary.html#term-awaitable"><span class="xref std std-term">awaitable</span></a> object.
|
||
Can only be used inside a <a class="reference internal" href="../glossary.html#term-coroutine-function"><span class="xref std std-term">coroutine function</span></a>.</p>
|
||
<pre>
|
||
<strong id="grammar-token-await-expr">await_expr</strong> ::= "await" <a class="reference internal" href="#grammar-token-primary"><code class="xref docutils literal notranslate"><span class="pre">primary</span></code></a>
|
||
</pre>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.5.</span></p>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="the-power-operator">
|
||
<span id="power"></span><h2>6.5. The power operator<a class="headerlink" href="#the-power-operator" title="Permalink to this headline">¶</a></h2>
|
||
<p id="index-56">The power operator binds more tightly than unary operators on its left; it binds
|
||
less tightly than unary operators on its right. The syntax is:</p>
|
||
<pre>
|
||
<strong id="grammar-token-power">power</strong> ::= (<a class="reference internal" href="#grammar-token-await-expr"><code class="xref docutils literal notranslate"><span class="pre">await_expr</span></code></a> | <a class="reference internal" href="#grammar-token-primary"><code class="xref docutils literal notranslate"><span class="pre">primary</span></code></a>) ["**" <a class="reference internal" href="#grammar-token-u-expr"><code class="xref docutils literal notranslate"><span class="pre">u_expr</span></code></a>]
|
||
</pre>
|
||
<p>Thus, in an unparenthesized sequence of power and unary operators, the operators
|
||
are evaluated from right to left (this does not constrain the evaluation order
|
||
for the operands): <code class="docutils literal notranslate"><span class="pre">-1**2</span></code> results in <code class="docutils literal notranslate"><span class="pre">-1</span></code>.</p>
|
||
<p>The power operator has the same semantics as the built-in <a class="reference internal" href="../library/functions.html#pow" title="pow"><code class="xref py py-func docutils literal notranslate"><span class="pre">pow()</span></code></a> function,
|
||
when called with two arguments: it yields its left argument raised to the power
|
||
of its right argument. The numeric arguments are first converted to a common
|
||
type, and the result is of that type.</p>
|
||
<p>For int operands, the result has the same type as the operands unless the second
|
||
argument is negative; in that case, all arguments are converted to float and a
|
||
float result is delivered. For example, <code class="docutils literal notranslate"><span class="pre">10**2</span></code> returns <code class="docutils literal notranslate"><span class="pre">100</span></code>, but
|
||
<code class="docutils literal notranslate"><span class="pre">10**-2</span></code> returns <code class="docutils literal notranslate"><span class="pre">0.01</span></code>.</p>
|
||
<p>Raising <code class="docutils literal notranslate"><span class="pre">0.0</span></code> to a negative power results in a <a class="reference internal" href="../library/exceptions.html#ZeroDivisionError" title="ZeroDivisionError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ZeroDivisionError</span></code></a>.
|
||
Raising a negative number to a fractional power results in a <a class="reference internal" href="../library/functions.html#complex" title="complex"><code class="xref py py-class docutils literal notranslate"><span class="pre">complex</span></code></a>
|
||
number. (In earlier versions it raised a <a class="reference internal" href="../library/exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a>.)</p>
|
||
</div>
|
||
<div class="section" id="unary-arithmetic-and-bitwise-operations">
|
||
<span id="unary"></span><h2>6.6. Unary arithmetic and bitwise operations<a class="headerlink" href="#unary-arithmetic-and-bitwise-operations" title="Permalink to this headline">¶</a></h2>
|
||
<p id="index-57">All unary arithmetic and bitwise operations have the same priority:</p>
|
||
<pre>
|
||
<strong id="grammar-token-u-expr">u_expr</strong> ::= <a class="reference internal" href="#grammar-token-power"><code class="xref docutils literal notranslate"><span class="pre">power</span></code></a> | "-" <a class="reference internal" href="#grammar-token-u-expr"><code class="xref docutils literal notranslate"><span class="pre">u_expr</span></code></a> | "+" <a class="reference internal" href="#grammar-token-u-expr"><code class="xref docutils literal notranslate"><span class="pre">u_expr</span></code></a> | "~" <a class="reference internal" href="#grammar-token-u-expr"><code class="xref docutils literal notranslate"><span class="pre">u_expr</span></code></a>
|
||
</pre>
|
||
<p id="index-58">The unary <code class="docutils literal notranslate"><span class="pre">-</span></code> (minus) operator yields the negation of its numeric argument.</p>
|
||
<p id="index-59">The unary <code class="docutils literal notranslate"><span class="pre">+</span></code> (plus) operator yields its numeric argument unchanged.</p>
|
||
<p id="index-60">The unary <code class="docutils literal notranslate"><span class="pre">~</span></code> (invert) operator yields the bitwise inversion of its integer
|
||
argument. The bitwise inversion of <code class="docutils literal notranslate"><span class="pre">x</span></code> is defined as <code class="docutils literal notranslate"><span class="pre">-(x+1)</span></code>. It only
|
||
applies to integral numbers.</p>
|
||
<p id="index-61">In all three cases, if the argument does not have the proper type, a
|
||
<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> exception is raised.</p>
|
||
</div>
|
||
<div class="section" id="binary-arithmetic-operations">
|
||
<span id="binary"></span><h2>6.7. Binary arithmetic operations<a class="headerlink" href="#binary-arithmetic-operations" title="Permalink to this headline">¶</a></h2>
|
||
<p id="index-62">The binary arithmetic operations have the conventional priority levels. Note
|
||
that some of these operations also apply to certain non-numeric types. Apart
|
||
from the power operator, there are only two levels, one for multiplicative
|
||
operators and one for additive operators:</p>
|
||
<pre>
|
||
<strong id="grammar-token-m-expr">m_expr</strong> ::= <a class="reference internal" href="#grammar-token-u-expr"><code class="xref docutils literal notranslate"><span class="pre">u_expr</span></code></a> | <a class="reference internal" href="#grammar-token-m-expr"><code class="xref docutils literal notranslate"><span class="pre">m_expr</span></code></a> "*" <a class="reference internal" href="#grammar-token-u-expr"><code class="xref docutils literal notranslate"><span class="pre">u_expr</span></code></a> | <a class="reference internal" href="#grammar-token-m-expr"><code class="xref docutils literal notranslate"><span class="pre">m_expr</span></code></a> "@" <a class="reference internal" href="#grammar-token-m-expr"><code class="xref docutils literal notranslate"><span class="pre">m_expr</span></code></a> |
|
||
<a class="reference internal" href="#grammar-token-m-expr"><code class="xref docutils literal notranslate"><span class="pre">m_expr</span></code></a> "//" <a class="reference internal" href="#grammar-token-u-expr"><code class="xref docutils literal notranslate"><span class="pre">u_expr</span></code></a> | <a class="reference internal" href="#grammar-token-m-expr"><code class="xref docutils literal notranslate"><span class="pre">m_expr</span></code></a> "/" <a class="reference internal" href="#grammar-token-u-expr"><code class="xref docutils literal notranslate"><span class="pre">u_expr</span></code></a> |
|
||
<a class="reference internal" href="#grammar-token-m-expr"><code class="xref docutils literal notranslate"><span class="pre">m_expr</span></code></a> "%" <a class="reference internal" href="#grammar-token-u-expr"><code class="xref docutils literal notranslate"><span class="pre">u_expr</span></code></a>
|
||
<strong id="grammar-token-a-expr">a_expr</strong> ::= <a class="reference internal" href="#grammar-token-m-expr"><code class="xref docutils literal notranslate"><span class="pre">m_expr</span></code></a> | <a class="reference internal" href="#grammar-token-a-expr"><code class="xref docutils literal notranslate"><span class="pre">a_expr</span></code></a> "+" <a class="reference internal" href="#grammar-token-m-expr"><code class="xref docutils literal notranslate"><span class="pre">m_expr</span></code></a> | <a class="reference internal" href="#grammar-token-a-expr"><code class="xref docutils literal notranslate"><span class="pre">a_expr</span></code></a> "-" <a class="reference internal" href="#grammar-token-m-expr"><code class="xref docutils literal notranslate"><span class="pre">m_expr</span></code></a>
|
||
</pre>
|
||
<p id="index-63">The <code class="docutils literal notranslate"><span class="pre">*</span></code> (multiplication) operator yields the product of its arguments. The
|
||
arguments must either both be numbers, or one argument must be an integer and
|
||
the other must be a sequence. In the former case, the numbers are converted to a
|
||
common type and then multiplied together. In the latter case, sequence
|
||
repetition is performed; a negative repetition factor yields an empty sequence.</p>
|
||
<p id="index-64">The <code class="docutils literal notranslate"><span class="pre">@</span></code> (at) operator is intended to be used for matrix multiplication. No
|
||
builtin Python types implement this operator.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.5.</span></p>
|
||
</div>
|
||
<p id="index-65">The <code class="docutils literal notranslate"><span class="pre">/</span></code> (division) and <code class="docutils literal notranslate"><span class="pre">//</span></code> (floor division) operators yield the quotient of
|
||
their arguments. The numeric arguments are first converted to a common type.
|
||
Division of integers yields a float, while floor division of integers results in an
|
||
integer; the result is that of mathematical division with the ‘floor’ function
|
||
applied to the result. Division by zero raises the <a class="reference internal" href="../library/exceptions.html#ZeroDivisionError" title="ZeroDivisionError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ZeroDivisionError</span></code></a>
|
||
exception.</p>
|
||
<p id="index-66">The <code class="docutils literal notranslate"><span class="pre">%</span></code> (modulo) operator yields the remainder from the division of the first
|
||
argument by the second. The numeric arguments are first converted to a common
|
||
type. A zero right argument raises the <a class="reference internal" href="../library/exceptions.html#ZeroDivisionError" title="ZeroDivisionError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ZeroDivisionError</span></code></a> exception. The
|
||
arguments may be floating point numbers, e.g., <code class="docutils literal notranslate"><span class="pre">3.14%0.7</span></code> equals <code class="docutils literal notranslate"><span class="pre">0.34</span></code>
|
||
(since <code class="docutils literal notranslate"><span class="pre">3.14</span></code> equals <code class="docutils literal notranslate"><span class="pre">4*0.7</span> <span class="pre">+</span> <span class="pre">0.34</span></code>.) The modulo operator always yields a
|
||
result with the same sign as its second operand (or zero); the absolute value of
|
||
the result is strictly smaller than the absolute value of the second operand
|
||
<a class="footnote-reference brackets" href="#id17" id="id9">1</a>.</p>
|
||
<p>The floor division and modulo operators are connected by the following
|
||
identity: <code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">==</span> <span class="pre">(x//y)*y</span> <span class="pre">+</span> <span class="pre">(x%y)</span></code>. Floor division and modulo are also
|
||
connected with the built-in function <a class="reference internal" href="../library/functions.html#divmod" title="divmod"><code class="xref py py-func docutils literal notranslate"><span class="pre">divmod()</span></code></a>: <code class="docutils literal notranslate"><span class="pre">divmod(x,</span> <span class="pre">y)</span> <span class="pre">==</span> <span class="pre">(x//y,</span>
|
||
<span class="pre">x%y)</span></code>. <a class="footnote-reference brackets" href="#id18" id="id10">2</a>.</p>
|
||
<p>In addition to performing the modulo operation on numbers, the <code class="docutils literal notranslate"><span class="pre">%</span></code> operator is
|
||
also overloaded by string objects to perform old-style string formatting (also
|
||
known as interpolation). The syntax for string formatting is described in the
|
||
Python Library Reference, section <a class="reference internal" href="../library/stdtypes.html#old-string-formatting"><span class="std std-ref">printf-style String Formatting</span></a>.</p>
|
||
<p>The floor division operator, the modulo operator, and the <a class="reference internal" href="../library/functions.html#divmod" title="divmod"><code class="xref py py-func docutils literal notranslate"><span class="pre">divmod()</span></code></a>
|
||
function are not defined for complex numbers. Instead, convert to a floating
|
||
point number using the <a class="reference internal" href="../library/functions.html#abs" title="abs"><code class="xref py py-func docutils literal notranslate"><span class="pre">abs()</span></code></a> function if appropriate.</p>
|
||
<p id="index-67">The <code class="docutils literal notranslate"><span class="pre">+</span></code> (addition) operator yields the sum of its arguments. The arguments
|
||
must either both be numbers or both be sequences of the same type. In the
|
||
former case, the numbers are converted to a common type and then added together.
|
||
In the latter case, the sequences are concatenated.</p>
|
||
<p id="index-68">The <code class="docutils literal notranslate"><span class="pre">-</span></code> (subtraction) operator yields the difference of its arguments. The
|
||
numeric arguments are first converted to a common type.</p>
|
||
</div>
|
||
<div class="section" id="shifting-operations">
|
||
<span id="shifting"></span><h2>6.8. Shifting operations<a class="headerlink" href="#shifting-operations" title="Permalink to this headline">¶</a></h2>
|
||
<p id="index-69">The shifting operations have lower priority than the arithmetic operations:</p>
|
||
<pre>
|
||
<strong id="grammar-token-shift-expr">shift_expr</strong> ::= <a class="reference internal" href="#grammar-token-a-expr"><code class="xref docutils literal notranslate"><span class="pre">a_expr</span></code></a> | <a class="reference internal" href="#grammar-token-shift-expr"><code class="xref docutils literal notranslate"><span class="pre">shift_expr</span></code></a> ("<<" | ">>") <a class="reference internal" href="#grammar-token-a-expr"><code class="xref docutils literal notranslate"><span class="pre">a_expr</span></code></a>
|
||
</pre>
|
||
<p>These operators accept integers as arguments. They shift the first argument to
|
||
the left or right by the number of bits given by the second argument.</p>
|
||
<p id="index-70">A right shift by <em>n</em> bits is defined as floor division by <code class="docutils literal notranslate"><span class="pre">pow(2,n)</span></code>. A left
|
||
shift by <em>n</em> bits is defined as multiplication with <code class="docutils literal notranslate"><span class="pre">pow(2,n)</span></code>.</p>
|
||
</div>
|
||
<div class="section" id="binary-bitwise-operations">
|
||
<span id="bitwise"></span><h2>6.9. Binary bitwise operations<a class="headerlink" href="#binary-bitwise-operations" title="Permalink to this headline">¶</a></h2>
|
||
<p id="index-71">Each of the three bitwise operations has a different priority level:</p>
|
||
<pre>
|
||
<strong id="grammar-token-and-expr">and_expr</strong> ::= <a class="reference internal" href="#grammar-token-shift-expr"><code class="xref docutils literal notranslate"><span class="pre">shift_expr</span></code></a> | <a class="reference internal" href="#grammar-token-and-expr"><code class="xref docutils literal notranslate"><span class="pre">and_expr</span></code></a> "&" <a class="reference internal" href="#grammar-token-shift-expr"><code class="xref docutils literal notranslate"><span class="pre">shift_expr</span></code></a>
|
||
<strong id="grammar-token-xor-expr">xor_expr</strong> ::= <a class="reference internal" href="#grammar-token-and-expr"><code class="xref docutils literal notranslate"><span class="pre">and_expr</span></code></a> | <a class="reference internal" href="#grammar-token-xor-expr"><code class="xref docutils literal notranslate"><span class="pre">xor_expr</span></code></a> "^" <a class="reference internal" href="#grammar-token-and-expr"><code class="xref docutils literal notranslate"><span class="pre">and_expr</span></code></a>
|
||
<strong id="grammar-token-or-expr">or_expr </strong> ::= <a class="reference internal" href="#grammar-token-xor-expr"><code class="xref docutils literal notranslate"><span class="pre">xor_expr</span></code></a> | <a class="reference internal" href="#grammar-token-or-expr"><code class="xref docutils literal notranslate"><span class="pre">or_expr</span></code></a> "|" <a class="reference internal" href="#grammar-token-xor-expr"><code class="xref docutils literal notranslate"><span class="pre">xor_expr</span></code></a>
|
||
</pre>
|
||
<p id="index-72">The <code class="docutils literal notranslate"><span class="pre">&</span></code> operator yields the bitwise AND of its arguments, which must be
|
||
integers.</p>
|
||
<p id="index-73">The <code class="docutils literal notranslate"><span class="pre">^</span></code> operator yields the bitwise XOR (exclusive OR) of its arguments, which
|
||
must be integers.</p>
|
||
<p id="index-74">The <code class="docutils literal notranslate"><span class="pre">|</span></code> operator yields the bitwise (inclusive) OR of its arguments, which
|
||
must be integers.</p>
|
||
</div>
|
||
<div class="section" id="comparisons">
|
||
<span id="id11"></span><h2>6.10. Comparisons<a class="headerlink" href="#comparisons" title="Permalink to this headline">¶</a></h2>
|
||
<p id="index-75">Unlike C, all comparison operations in Python have the same priority, which is
|
||
lower than that of any arithmetic, shifting or bitwise operation. Also unlike
|
||
C, expressions like <code class="docutils literal notranslate"><span class="pre">a</span> <span class="pre"><</span> <span class="pre">b</span> <span class="pre"><</span> <span class="pre">c</span></code> have the interpretation that is conventional
|
||
in mathematics:</p>
|
||
<pre>
|
||
<strong id="grammar-token-comparison">comparison </strong> ::= <a class="reference internal" href="#grammar-token-or-expr"><code class="xref docutils literal notranslate"><span class="pre">or_expr</span></code></a> (<a class="reference internal" href="#grammar-token-comp-operator"><code class="xref docutils literal notranslate"><span class="pre">comp_operator</span></code></a> <a class="reference internal" href="#grammar-token-or-expr"><code class="xref docutils literal notranslate"><span class="pre">or_expr</span></code></a>)*
|
||
<strong id="grammar-token-comp-operator">comp_operator</strong> ::= "<" | ">" | "==" | ">=" | "<=" | "!="
|
||
| "is" ["not"] | ["not"] "in"
|
||
</pre>
|
||
<p>Comparisons yield boolean values: <code class="docutils literal notranslate"><span class="pre">True</span></code> or <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p>
|
||
<p id="index-76">Comparisons can be chained arbitrarily, e.g., <code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre"><</span> <span class="pre">y</span> <span class="pre"><=</span> <span class="pre">z</span></code> is equivalent to
|
||
<code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre"><</span> <span class="pre">y</span> <span class="pre">and</span> <span class="pre">y</span> <span class="pre"><=</span> <span class="pre">z</span></code>, except that <code class="docutils literal notranslate"><span class="pre">y</span></code> is evaluated only once (but in both
|
||
cases <code class="docutils literal notranslate"><span class="pre">z</span></code> is not evaluated at all when <code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre"><</span> <span class="pre">y</span></code> is found to be false).</p>
|
||
<p>Formally, if <em>a</em>, <em>b</em>, <em>c</em>, …, <em>y</em>, <em>z</em> are expressions and <em>op1</em>, <em>op2</em>, …,
|
||
<em>opN</em> are comparison operators, then <code class="docutils literal notranslate"><span class="pre">a</span> <span class="pre">op1</span> <span class="pre">b</span> <span class="pre">op2</span> <span class="pre">c</span> <span class="pre">...</span> <span class="pre">y</span> <span class="pre">opN</span> <span class="pre">z</span></code> is equivalent
|
||
to <code class="docutils literal notranslate"><span class="pre">a</span> <span class="pre">op1</span> <span class="pre">b</span> <span class="pre">and</span> <span class="pre">b</span> <span class="pre">op2</span> <span class="pre">c</span> <span class="pre">and</span> <span class="pre">...</span> <span class="pre">y</span> <span class="pre">opN</span> <span class="pre">z</span></code>, except that each expression is
|
||
evaluated at most once.</p>
|
||
<p>Note that <code class="docutils literal notranslate"><span class="pre">a</span> <span class="pre">op1</span> <span class="pre">b</span> <span class="pre">op2</span> <span class="pre">c</span></code> doesn’t imply any kind of comparison between <em>a</em> and
|
||
<em>c</em>, so that, e.g., <code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre"><</span> <span class="pre">y</span> <span class="pre">></span> <span class="pre">z</span></code> is perfectly legal (though perhaps not
|
||
pretty).</p>
|
||
<div class="section" id="value-comparisons">
|
||
<h3>6.10.1. Value comparisons<a class="headerlink" href="#value-comparisons" title="Permalink to this headline">¶</a></h3>
|
||
<p>The operators <code class="docutils literal notranslate"><span class="pre"><</span></code>, <code class="docutils literal notranslate"><span class="pre">></span></code>, <code class="docutils literal notranslate"><span class="pre">==</span></code>, <code class="docutils literal notranslate"><span class="pre">>=</span></code>, <code class="docutils literal notranslate"><span class="pre"><=</span></code>, and <code class="docutils literal notranslate"><span class="pre">!=</span></code> compare the
|
||
values of two objects. The objects do not need to have the same type.</p>
|
||
<p>Chapter <a class="reference internal" href="datamodel.html#objects"><span class="std std-ref">Objects, values and types</span></a> states that objects have a value (in addition to type
|
||
and identity). The value of an object is a rather abstract notion in Python:
|
||
For example, there is no canonical access method for an object’s value. Also,
|
||
there is no requirement that the value of an object should be constructed in a
|
||
particular way, e.g. comprised of all its data attributes. Comparison operators
|
||
implement a particular notion of what the value of an object is. One can think
|
||
of them as defining the value of an object indirectly, by means of their
|
||
comparison implementation.</p>
|
||
<p>Because all types are (direct or indirect) subtypes of <a class="reference internal" href="../library/functions.html#object" title="object"><code class="xref py py-class docutils literal notranslate"><span class="pre">object</span></code></a>, they
|
||
inherit the default comparison behavior from <a class="reference internal" href="../library/functions.html#object" title="object"><code class="xref py py-class docutils literal notranslate"><span class="pre">object</span></code></a>. Types can
|
||
customize their comparison behavior by implementing
|
||
<em class="dfn">rich comparison methods</em> like <a class="reference internal" href="datamodel.html#object.__lt__" title="object.__lt__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__lt__()</span></code></a>, described in
|
||
<a class="reference internal" href="datamodel.html#customization"><span class="std std-ref">Basic customization</span></a>.</p>
|
||
<p>The default behavior for equality comparison (<code class="docutils literal notranslate"><span class="pre">==</span></code> and <code class="docutils literal notranslate"><span class="pre">!=</span></code>) is based on
|
||
the identity of the objects. Hence, equality comparison of instances with the
|
||
same identity results in equality, and equality comparison of instances with
|
||
different identities results in inequality. A motivation for this default
|
||
behavior is the desire that all objects should be reflexive (i.e. <code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">is</span> <span class="pre">y</span></code>
|
||
implies <code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">==</span> <span class="pre">y</span></code>).</p>
|
||
<p>A default order comparison (<code class="docutils literal notranslate"><span class="pre"><</span></code>, <code class="docutils literal notranslate"><span class="pre">></span></code>, <code class="docutils literal notranslate"><span class="pre"><=</span></code>, and <code class="docutils literal notranslate"><span class="pre">>=</span></code>) is not provided;
|
||
an attempt raises <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>. A motivation for this default behavior is
|
||
the lack of a similar invariant as for equality.</p>
|
||
<p>The behavior of the default equality comparison, that instances with different
|
||
identities are always unequal, may be in contrast to what types will need that
|
||
have a sensible definition of object value and value-based equality. Such
|
||
types will need to customize their comparison behavior, and in fact, a number
|
||
of built-in types have done that.</p>
|
||
<p>The following list describes the comparison behavior of the most important
|
||
built-in types.</p>
|
||
<ul>
|
||
<li><p>Numbers of built-in numeric types (<a class="reference internal" href="../library/stdtypes.html#typesnumeric"><span class="std std-ref">Numeric Types — int, float, complex</span></a>) and of the standard
|
||
library types <a class="reference internal" href="../library/fractions.html#fractions.Fraction" title="fractions.Fraction"><code class="xref py py-class docutils literal notranslate"><span class="pre">fractions.Fraction</span></code></a> and <a class="reference internal" href="../library/decimal.html#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal notranslate"><span class="pre">decimal.Decimal</span></code></a> can be
|
||
compared within and across their types, with the restriction that complex
|
||
numbers do not support order comparison. Within the limits of the types
|
||
involved, they compare mathematically (algorithmically) correct without loss
|
||
of precision.</p>
|
||
<p>The not-a-number values <code class="docutils literal notranslate"><span class="pre">float('NaN')</span></code> and <code class="docutils literal notranslate"><span class="pre">decimal.Decimal('NaN')</span></code> are
|
||
special. Any ordered comparison of a number to a not-a-number value is false.
|
||
A counter-intuitive implication is that not-a-number values are not equal to
|
||
themselves. For example, if <code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">=</span> <span class="pre">float('NaN')</span></code>, <code class="docutils literal notranslate"><span class="pre">3</span> <span class="pre"><</span> <span class="pre">x</span></code>, <code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre"><</span> <span class="pre">3</span></code>, <code class="docutils literal notranslate"><span class="pre">x</span>
|
||
<span class="pre">==</span> <span class="pre">x</span></code>, <code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">!=</span> <span class="pre">x</span></code> are all false. This behavior is compliant with IEEE 754.</p>
|
||
</li>
|
||
<li><p>Binary sequences (instances of <a class="reference internal" href="../library/stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> or <a class="reference internal" href="../library/stdtypes.html#bytearray" title="bytearray"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytearray</span></code></a>) can be
|
||
compared within and across their types. They compare lexicographically using
|
||
the numeric values of their elements.</p></li>
|
||
<li><p>Strings (instances of <a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>) compare lexicographically using the
|
||
numerical Unicode code points (the result of the built-in function
|
||
<a class="reference internal" href="../library/functions.html#ord" title="ord"><code class="xref py py-func docutils literal notranslate"><span class="pre">ord()</span></code></a>) of their characters. <a class="footnote-reference brackets" href="#id19" id="id12">3</a></p>
|
||
<p>Strings and binary sequences cannot be directly compared.</p>
|
||
</li>
|
||
<li><p>Sequences (instances of <a class="reference internal" href="../library/stdtypes.html#tuple" title="tuple"><code class="xref py py-class docutils literal notranslate"><span class="pre">tuple</span></code></a>, <a class="reference internal" href="../library/stdtypes.html#list" title="list"><code class="xref py py-class docutils literal notranslate"><span class="pre">list</span></code></a>, or <a class="reference internal" href="../library/stdtypes.html#range" title="range"><code class="xref py py-class docutils literal notranslate"><span class="pre">range</span></code></a>) can
|
||
be compared only within each of their types, with the restriction that ranges
|
||
do not support order comparison. Equality comparison across these types
|
||
results in inequality, and ordering comparison across these types raises
|
||
<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>.</p>
|
||
<p>Sequences compare lexicographically using comparison of corresponding
|
||
elements, whereby reflexivity of the elements is enforced.</p>
|
||
<p>In enforcing reflexivity of elements, the comparison of collections assumes
|
||
that for a collection element <code class="docutils literal notranslate"><span class="pre">x</span></code>, <code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">==</span> <span class="pre">x</span></code> is always true. Based on
|
||
that assumption, element identity is compared first, and element comparison
|
||
is performed only for distinct elements. This approach yields the same
|
||
result as a strict element comparison would, if the compared elements are
|
||
reflexive. For non-reflexive elements, the result is different than for
|
||
strict element comparison, and may be surprising: The non-reflexive
|
||
not-a-number values for example result in the following comparison behavior
|
||
when used in a list:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">nan</span> <span class="o">=</span> <span class="nb">float</span><span class="p">(</span><span class="s1">'NaN'</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">nan</span> <span class="ow">is</span> <span class="n">nan</span>
|
||
<span class="go">True</span>
|
||
<span class="gp">>>> </span><span class="n">nan</span> <span class="o">==</span> <span class="n">nan</span>
|
||
<span class="go">False <-- the defined non-reflexive behavior of NaN</span>
|
||
<span class="gp">>>> </span><span class="p">[</span><span class="n">nan</span><span class="p">]</span> <span class="o">==</span> <span class="p">[</span><span class="n">nan</span><span class="p">]</span>
|
||
<span class="go">True <-- list enforces reflexivity and tests identity first</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Lexicographical comparison between built-in collections works as follows:</p>
|
||
<ul class="simple">
|
||
<li><p>For two collections to compare equal, they must be of the same type, have
|
||
the same length, and each pair of corresponding elements must compare
|
||
equal (for example, <code class="docutils literal notranslate"><span class="pre">[1,2]</span> <span class="pre">==</span> <span class="pre">(1,2)</span></code> is false because the type is not the
|
||
same).</p></li>
|
||
<li><p>Collections that support order comparison are ordered the same as their
|
||
first unequal elements (for example, <code class="docutils literal notranslate"><span class="pre">[1,2,x]</span> <span class="pre"><=</span> <span class="pre">[1,2,y]</span></code> has the same
|
||
value as <code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre"><=</span> <span class="pre">y</span></code>). If a corresponding element does not exist, the
|
||
shorter collection is ordered first (for example, <code class="docutils literal notranslate"><span class="pre">[1,2]</span> <span class="pre"><</span> <span class="pre">[1,2,3]</span></code> is
|
||
true).</p></li>
|
||
</ul>
|
||
</li>
|
||
<li><p>Mappings (instances of <a class="reference internal" href="../library/stdtypes.html#dict" title="dict"><code class="xref py py-class docutils literal notranslate"><span class="pre">dict</span></code></a>) compare equal if and only if they have
|
||
equal <cite>(key, value)</cite> pairs. Equality comparison of the keys and values
|
||
enforces reflexivity.</p>
|
||
<p>Order comparisons (<code class="docutils literal notranslate"><span class="pre"><</span></code>, <code class="docutils literal notranslate"><span class="pre">></span></code>, <code class="docutils literal notranslate"><span class="pre"><=</span></code>, and <code class="docutils literal notranslate"><span class="pre">>=</span></code>) raise <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>.</p>
|
||
</li>
|
||
<li><p>Sets (instances of <a class="reference internal" href="../library/stdtypes.html#set" title="set"><code class="xref py py-class docutils literal notranslate"><span class="pre">set</span></code></a> or <a class="reference internal" href="../library/stdtypes.html#frozenset" title="frozenset"><code class="xref py py-class docutils literal notranslate"><span class="pre">frozenset</span></code></a>) can be compared within
|
||
and across their types.</p>
|
||
<p>They define order
|
||
comparison operators to mean subset and superset tests. Those relations do
|
||
not define total orderings (for example, the two sets <code class="docutils literal notranslate"><span class="pre">{1,2}</span></code> and <code class="docutils literal notranslate"><span class="pre">{2,3}</span></code>
|
||
are not equal, nor subsets of one another, nor supersets of one
|
||
another). Accordingly, sets are not appropriate arguments for functions
|
||
which depend on total ordering (for example, <a class="reference internal" href="../library/functions.html#min" title="min"><code class="xref py py-func docutils literal notranslate"><span class="pre">min()</span></code></a>, <a class="reference internal" href="../library/functions.html#max" title="max"><code class="xref py py-func docutils literal notranslate"><span class="pre">max()</span></code></a>, and
|
||
<a class="reference internal" href="../library/functions.html#sorted" title="sorted"><code class="xref py py-func docutils literal notranslate"><span class="pre">sorted()</span></code></a> produce undefined results given a list of sets as inputs).</p>
|
||
<p>Comparison of sets enforces reflexivity of its elements.</p>
|
||
</li>
|
||
<li><p>Most other built-in types have no comparison methods implemented, so they
|
||
inherit the default comparison behavior.</p></li>
|
||
</ul>
|
||
<p>User-defined classes that customize their comparison behavior should follow
|
||
some consistency rules, if possible:</p>
|
||
<ul>
|
||
<li><p>Equality comparison should be reflexive.
|
||
In other words, identical objects should compare equal:</p>
|
||
<blockquote>
|
||
<div><p><code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">is</span> <span class="pre">y</span></code> implies <code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">==</span> <span class="pre">y</span></code></p>
|
||
</div></blockquote>
|
||
</li>
|
||
<li><p>Comparison should be symmetric.
|
||
In other words, the following expressions should have the same result:</p>
|
||
<blockquote>
|
||
<div><p><code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">==</span> <span class="pre">y</span></code> and <code class="docutils literal notranslate"><span class="pre">y</span> <span class="pre">==</span> <span class="pre">x</span></code></p>
|
||
<p><code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">!=</span> <span class="pre">y</span></code> and <code class="docutils literal notranslate"><span class="pre">y</span> <span class="pre">!=</span> <span class="pre">x</span></code></p>
|
||
<p><code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre"><</span> <span class="pre">y</span></code> and <code class="docutils literal notranslate"><span class="pre">y</span> <span class="pre">></span> <span class="pre">x</span></code></p>
|
||
<p><code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre"><=</span> <span class="pre">y</span></code> and <code class="docutils literal notranslate"><span class="pre">y</span> <span class="pre">>=</span> <span class="pre">x</span></code></p>
|
||
</div></blockquote>
|
||
</li>
|
||
<li><p>Comparison should be transitive.
|
||
The following (non-exhaustive) examples illustrate that:</p>
|
||
<blockquote>
|
||
<div><p><code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">></span> <span class="pre">y</span> <span class="pre">and</span> <span class="pre">y</span> <span class="pre">></span> <span class="pre">z</span></code> implies <code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">></span> <span class="pre">z</span></code></p>
|
||
<p><code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre"><</span> <span class="pre">y</span> <span class="pre">and</span> <span class="pre">y</span> <span class="pre"><=</span> <span class="pre">z</span></code> implies <code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre"><</span> <span class="pre">z</span></code></p>
|
||
</div></blockquote>
|
||
</li>
|
||
<li><p>Inverse comparison should result in the boolean negation.
|
||
In other words, the following expressions should have the same result:</p>
|
||
<blockquote>
|
||
<div><p><code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">==</span> <span class="pre">y</span></code> and <code class="docutils literal notranslate"><span class="pre">not</span> <span class="pre">x</span> <span class="pre">!=</span> <span class="pre">y</span></code></p>
|
||
<p><code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre"><</span> <span class="pre">y</span></code> and <code class="docutils literal notranslate"><span class="pre">not</span> <span class="pre">x</span> <span class="pre">>=</span> <span class="pre">y</span></code> (for total ordering)</p>
|
||
<p><code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">></span> <span class="pre">y</span></code> and <code class="docutils literal notranslate"><span class="pre">not</span> <span class="pre">x</span> <span class="pre"><=</span> <span class="pre">y</span></code> (for total ordering)</p>
|
||
</div></blockquote>
|
||
<p>The last two expressions apply to totally ordered collections (e.g. to
|
||
sequences, but not to sets or mappings). See also the
|
||
<a class="reference internal" href="../library/functools.html#functools.total_ordering" title="functools.total_ordering"><code class="xref py py-func docutils literal notranslate"><span class="pre">total_ordering()</span></code></a> decorator.</p>
|
||
</li>
|
||
<li><p>The <a class="reference internal" href="../library/functions.html#hash" title="hash"><code class="xref py py-func docutils literal notranslate"><span class="pre">hash()</span></code></a> result should be consistent with equality.
|
||
Objects that are equal should either have the same hash value,
|
||
or be marked as unhashable.</p></li>
|
||
</ul>
|
||
<p>Python does not enforce these consistency rules. In fact, the not-a-number
|
||
values are an example for not following these rules.</p>
|
||
</div>
|
||
<div class="section" id="membership-test-operations">
|
||
<span id="membership-test-details"></span><span id="not-in"></span><span id="in"></span><h3>6.10.2. Membership test operations<a class="headerlink" href="#membership-test-operations" title="Permalink to this headline">¶</a></h3>
|
||
<p>The operators <a class="reference internal" href="#in"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">in</span></code></a> and <a class="reference internal" href="#not-in"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">not</span> <span class="pre">in</span></code></a> test for membership. <code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">in</span>
|
||
<span class="pre">s</span></code> evaluates to <code class="docutils literal notranslate"><span class="pre">True</span></code> if <em>x</em> is a member of <em>s</em>, and <code class="docutils literal notranslate"><span class="pre">False</span></code> otherwise.
|
||
<code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">not</span> <span class="pre">in</span> <span class="pre">s</span></code> returns the negation of <code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">in</span> <span class="pre">s</span></code>. All built-in sequences and
|
||
set types support this as well as dictionary, for which <code class="xref std std-keyword docutils literal notranslate"><span class="pre">in</span></code> tests
|
||
whether the dictionary has a given key. For container types such as list, tuple,
|
||
set, frozenset, dict, or collections.deque, the expression <code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">in</span> <span class="pre">y</span></code> is equivalent
|
||
to <code class="docutils literal notranslate"><span class="pre">any(x</span> <span class="pre">is</span> <span class="pre">e</span> <span class="pre">or</span> <span class="pre">x</span> <span class="pre">==</span> <span class="pre">e</span> <span class="pre">for</span> <span class="pre">e</span> <span class="pre">in</span> <span class="pre">y)</span></code>.</p>
|
||
<p>For the string and bytes types, <code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">in</span> <span class="pre">y</span></code> is <code class="docutils literal notranslate"><span class="pre">True</span></code> if and only if <em>x</em> is a
|
||
substring of <em>y</em>. An equivalent test is <code class="docutils literal notranslate"><span class="pre">y.find(x)</span> <span class="pre">!=</span> <span class="pre">-1</span></code>. Empty strings are
|
||
always considered to be a substring of any other string, so <code class="docutils literal notranslate"><span class="pre">""</span> <span class="pre">in</span> <span class="pre">"abc"</span></code> will
|
||
return <code class="docutils literal notranslate"><span class="pre">True</span></code>.</p>
|
||
<p>For user-defined classes which define the <a class="reference internal" href="datamodel.html#object.__contains__" title="object.__contains__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__contains__()</span></code></a> method, <code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">in</span>
|
||
<span class="pre">y</span></code> returns <code class="docutils literal notranslate"><span class="pre">True</span></code> if <code class="docutils literal notranslate"><span class="pre">y.__contains__(x)</span></code> returns a true value, and
|
||
<code class="docutils literal notranslate"><span class="pre">False</span></code> otherwise.</p>
|
||
<p>For user-defined classes which do not define <a class="reference internal" href="datamodel.html#object.__contains__" title="object.__contains__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__contains__()</span></code></a> but do define
|
||
<a class="reference internal" href="datamodel.html#object.__iter__" title="object.__iter__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__iter__()</span></code></a>, <code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">in</span> <span class="pre">y</span></code> is <code class="docutils literal notranslate"><span class="pre">True</span></code> if some value <code class="docutils literal notranslate"><span class="pre">z</span></code>, for which the
|
||
expression <code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">is</span> <span class="pre">z</span> <span class="pre">or</span> <span class="pre">x</span> <span class="pre">==</span> <span class="pre">z</span></code> is true, is produced while iterating over <code class="docutils literal notranslate"><span class="pre">y</span></code>.
|
||
If an exception is raised during the iteration, it is as if <a class="reference internal" href="#in"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">in</span></code></a> raised
|
||
that exception.</p>
|
||
<p>Lastly, the old-style iteration protocol is tried: if a class defines
|
||
<a class="reference internal" href="datamodel.html#object.__getitem__" title="object.__getitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__getitem__()</span></code></a>, <code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">in</span> <span class="pre">y</span></code> is <code class="docutils literal notranslate"><span class="pre">True</span></code> if and only if there is a non-negative
|
||
integer index <em>i</em> such that <code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">is</span> <span class="pre">y[i]</span> <span class="pre">or</span> <span class="pre">x</span> <span class="pre">==</span> <span class="pre">y[i]</span></code>, and no lower integer index
|
||
raises the <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> exception. (If any other exception is raised, it is as
|
||
if <a class="reference internal" href="#in"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">in</span></code></a> raised that exception).</p>
|
||
<p id="index-77">The operator <a class="reference internal" href="#not-in"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">not</span> <span class="pre">in</span></code></a> is defined to have the inverse truth value of
|
||
<a class="reference internal" href="#in"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">in</span></code></a>.</p>
|
||
</div>
|
||
<div class="section" id="is-not">
|
||
<span id="is"></span><span id="index-78"></span><span id="identity-comparisons"></span><h3>6.10.3. Identity comparisons<a class="headerlink" href="#is-not" title="Permalink to this headline">¶</a></h3>
|
||
<p>The operators <a class="reference internal" href="#is"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">is</span></code></a> and <a class="reference internal" href="#is-not"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">is</span> <span class="pre">not</span></code></a> test for an object’s identity: <code class="docutils literal notranslate"><span class="pre">x</span>
|
||
<span class="pre">is</span> <span class="pre">y</span></code> is true if and only if <em>x</em> and <em>y</em> are the same object. An Object’s identity
|
||
is determined using the <a class="reference internal" href="../library/functions.html#id" title="id"><code class="xref py py-meth docutils literal notranslate"><span class="pre">id()</span></code></a> function. <code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">is</span> <span class="pre">not</span> <span class="pre">y</span></code> yields the inverse
|
||
truth value. <a class="footnote-reference brackets" href="#id20" id="id13">4</a></p>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="boolean-operations">
|
||
<span id="not"></span><span id="or"></span><span id="and"></span><span id="booleans"></span><h2>6.11. Boolean operations<a class="headerlink" href="#boolean-operations" title="Permalink to this headline">¶</a></h2>
|
||
<pre id="index-79">
|
||
<strong id="grammar-token-or-test">or_test </strong> ::= <a class="reference internal" href="#grammar-token-and-test"><code class="xref docutils literal notranslate"><span class="pre">and_test</span></code></a> | <a class="reference internal" href="#grammar-token-or-test"><code class="xref docutils literal notranslate"><span class="pre">or_test</span></code></a> "or" <a class="reference internal" href="#grammar-token-and-test"><code class="xref docutils literal notranslate"><span class="pre">and_test</span></code></a>
|
||
<strong id="grammar-token-and-test">and_test</strong> ::= <a class="reference internal" href="#grammar-token-not-test"><code class="xref docutils literal notranslate"><span class="pre">not_test</span></code></a> | <a class="reference internal" href="#grammar-token-and-test"><code class="xref docutils literal notranslate"><span class="pre">and_test</span></code></a> "and" <a class="reference internal" href="#grammar-token-not-test"><code class="xref docutils literal notranslate"><span class="pre">not_test</span></code></a>
|
||
<strong id="grammar-token-not-test">not_test</strong> ::= <a class="reference internal" href="#grammar-token-comparison"><code class="xref docutils literal notranslate"><span class="pre">comparison</span></code></a> | "not" <a class="reference internal" href="#grammar-token-not-test"><code class="xref docutils literal notranslate"><span class="pre">not_test</span></code></a>
|
||
</pre>
|
||
<p>In the context of Boolean operations, and also when expressions are used by
|
||
control flow statements, the following values are interpreted as false:
|
||
<code class="docutils literal notranslate"><span class="pre">False</span></code>, <code class="docutils literal notranslate"><span class="pre">None</span></code>, numeric zero of all types, and empty strings and containers
|
||
(including strings, tuples, lists, dictionaries, sets and frozensets). All
|
||
other values are interpreted as true. User-defined objects can customize their
|
||
truth value by providing a <a class="reference internal" href="datamodel.html#object.__bool__" title="object.__bool__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__bool__()</span></code></a> method.</p>
|
||
<p id="index-80">The operator <a class="reference internal" href="#not"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">not</span></code></a> yields <code class="docutils literal notranslate"><span class="pre">True</span></code> if its argument is false, <code class="docutils literal notranslate"><span class="pre">False</span></code>
|
||
otherwise.</p>
|
||
<p id="index-81">The expression <code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">and</span> <span class="pre">y</span></code> first evaluates <em>x</em>; if <em>x</em> is false, its value is
|
||
returned; otherwise, <em>y</em> is evaluated and the resulting value is returned.</p>
|
||
<p id="index-82">The expression <code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">or</span> <span class="pre">y</span></code> first evaluates <em>x</em>; if <em>x</em> is true, its value is
|
||
returned; otherwise, <em>y</em> is evaluated and the resulting value is returned.</p>
|
||
<p>Note that neither <a class="reference internal" href="#and"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">and</span></code></a> nor <a class="reference internal" href="#or"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">or</span></code></a> restrict the value and type
|
||
they return to <code class="docutils literal notranslate"><span class="pre">False</span></code> and <code class="docutils literal notranslate"><span class="pre">True</span></code>, but rather return the last evaluated
|
||
argument. This is sometimes useful, e.g., if <code class="docutils literal notranslate"><span class="pre">s</span></code> is a string that should be
|
||
replaced by a default value if it is empty, the expression <code class="docutils literal notranslate"><span class="pre">s</span> <span class="pre">or</span> <span class="pre">'foo'</span></code> yields
|
||
the desired value. Because <a class="reference internal" href="#not"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">not</span></code></a> has to create a new value, it
|
||
returns a boolean value regardless of the type of its argument
|
||
(for example, <code class="docutils literal notranslate"><span class="pre">not</span> <span class="pre">'foo'</span></code> produces <code class="docutils literal notranslate"><span class="pre">False</span></code> rather than <code class="docutils literal notranslate"><span class="pre">''</span></code>.)</p>
|
||
</div>
|
||
<div class="section" id="conditional-expressions">
|
||
<span id="if-expr"></span><h2>6.12. Conditional expressions<a class="headerlink" href="#conditional-expressions" title="Permalink to this headline">¶</a></h2>
|
||
<pre id="index-83">
|
||
<strong id="grammar-token-conditional-expression">conditional_expression</strong> ::= <a class="reference internal" href="#grammar-token-or-test"><code class="xref docutils literal notranslate"><span class="pre">or_test</span></code></a> ["if" <a class="reference internal" href="#grammar-token-or-test"><code class="xref docutils literal notranslate"><span class="pre">or_test</span></code></a> "else" <a class="reference internal" href="#grammar-token-expression"><code class="xref docutils literal notranslate"><span class="pre">expression</span></code></a>]
|
||
<strong id="grammar-token-expression">expression </strong> ::= <a class="reference internal" href="#grammar-token-conditional-expression"><code class="xref docutils literal notranslate"><span class="pre">conditional_expression</span></code></a> | <a class="reference internal" href="#grammar-token-lambda-expr"><code class="xref docutils literal notranslate"><span class="pre">lambda_expr</span></code></a>
|
||
<strong id="grammar-token-expression-nocond">expression_nocond </strong> ::= <a class="reference internal" href="#grammar-token-or-test"><code class="xref docutils literal notranslate"><span class="pre">or_test</span></code></a> | <a class="reference internal" href="#grammar-token-lambda-expr-nocond"><code class="xref docutils literal notranslate"><span class="pre">lambda_expr_nocond</span></code></a>
|
||
</pre>
|
||
<p>Conditional expressions (sometimes called a “ternary operator”) have the lowest
|
||
priority of all Python operations.</p>
|
||
<p>The expression <code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">if</span> <span class="pre">C</span> <span class="pre">else</span> <span class="pre">y</span></code> first evaluates the condition, <em>C</em> rather than <em>x</em>.
|
||
If <em>C</em> is true, <em>x</em> is evaluated and its value is returned; otherwise, <em>y</em> is
|
||
evaluated and its value is returned.</p>
|
||
<p>See <span class="target" id="index-84"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0308"><strong>PEP 308</strong></a> for more details about conditional expressions.</p>
|
||
</div>
|
||
<div class="section" id="lambda">
|
||
<span id="lambdas"></span><span id="id14"></span><h2>6.13. Lambdas<a class="headerlink" href="#lambda" title="Permalink to this headline">¶</a></h2>
|
||
<pre id="index-85">
|
||
<strong id="grammar-token-lambda-expr">lambda_expr </strong> ::= "lambda" [<a class="reference internal" href="compound_stmts.html#grammar-token-parameter-list"><code class="xref docutils literal notranslate"><span class="pre">parameter_list</span></code></a>] ":" <a class="reference internal" href="#grammar-token-expression"><code class="xref docutils literal notranslate"><span class="pre">expression</span></code></a>
|
||
<strong id="grammar-token-lambda-expr-nocond">lambda_expr_nocond</strong> ::= "lambda" [<a class="reference internal" href="compound_stmts.html#grammar-token-parameter-list"><code class="xref docutils literal notranslate"><span class="pre">parameter_list</span></code></a>] ":" <a class="reference internal" href="#grammar-token-expression-nocond"><code class="xref docutils literal notranslate"><span class="pre">expression_nocond</span></code></a>
|
||
</pre>
|
||
<p>Lambda expressions (sometimes called lambda forms) are used to create anonymous
|
||
functions. The expression <code class="docutils literal notranslate"><span class="pre">lambda</span> <span class="pre">parameters:</span> <span class="pre">expression</span></code> yields a function
|
||
object. The unnamed object behaves like a function object defined with:</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>def <lambda>(parameters):
|
||
return expression
|
||
</pre></div>
|
||
</div>
|
||
<p>See section <a class="reference internal" href="compound_stmts.html#function"><span class="std std-ref">Function definitions</span></a> for the syntax of parameter lists. Note that
|
||
functions created with lambda expressions cannot contain statements or
|
||
annotations.</p>
|
||
</div>
|
||
<div class="section" id="expression-lists">
|
||
<span id="exprlists"></span><h2>6.14. Expression lists<a class="headerlink" href="#expression-lists" title="Permalink to this headline">¶</a></h2>
|
||
<pre id="index-86">
|
||
<strong id="grammar-token-expression-list">expression_list </strong> ::= <a class="reference internal" href="#grammar-token-expression"><code class="xref docutils literal notranslate"><span class="pre">expression</span></code></a> ("," <a class="reference internal" href="#grammar-token-expression"><code class="xref docutils literal notranslate"><span class="pre">expression</span></code></a>)* [","]
|
||
<strong id="grammar-token-starred-list">starred_list </strong> ::= <a class="reference internal" href="#grammar-token-starred-item"><code class="xref docutils literal notranslate"><span class="pre">starred_item</span></code></a> ("," <a class="reference internal" href="#grammar-token-starred-item"><code class="xref docutils literal notranslate"><span class="pre">starred_item</span></code></a>)* [","]
|
||
<strong id="grammar-token-starred-expression">starred_expression</strong> ::= <a class="reference internal" href="#grammar-token-expression"><code class="xref docutils literal notranslate"><span class="pre">expression</span></code></a> | (<a class="reference internal" href="#grammar-token-starred-item"><code class="xref docutils literal notranslate"><span class="pre">starred_item</span></code></a> ",")* [<a class="reference internal" href="#grammar-token-starred-item"><code class="xref docutils literal notranslate"><span class="pre">starred_item</span></code></a>]
|
||
<strong id="grammar-token-starred-item">starred_item </strong> ::= <a class="reference internal" href="#grammar-token-expression"><code class="xref docutils literal notranslate"><span class="pre">expression</span></code></a> | "*" <a class="reference internal" href="#grammar-token-or-expr"><code class="xref docutils literal notranslate"><span class="pre">or_expr</span></code></a>
|
||
</pre>
|
||
<p id="index-87">Except when part of a list or set display, an expression list
|
||
containing at least one comma yields a tuple. The length of
|
||
the tuple is the number of expressions in the list. The expressions are
|
||
evaluated from left to right.</p>
|
||
<p id="index-88">An asterisk <code class="docutils literal notranslate"><span class="pre">*</span></code> denotes <em class="dfn">iterable unpacking</em>. Its operand must be
|
||
an <a class="reference internal" href="../glossary.html#term-iterable"><span class="xref std std-term">iterable</span></a>. The iterable is expanded into a sequence of items,
|
||
which are included in the new tuple, list, or set, at the site of
|
||
the unpacking.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.5: </span>Iterable unpacking in expression lists, originally proposed by <span class="target" id="index-89"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0448"><strong>PEP 448</strong></a>.</p>
|
||
</div>
|
||
<p id="index-90">The trailing comma is required only to create a single tuple (a.k.a. a
|
||
<em>singleton</em>); it is optional in all other cases. A single expression without a
|
||
trailing comma doesn’t create a tuple, but rather yields the value of that
|
||
expression. (To create an empty tuple, use an empty pair of parentheses:
|
||
<code class="docutils literal notranslate"><span class="pre">()</span></code>.)</p>
|
||
</div>
|
||
<div class="section" id="evaluation-order">
|
||
<span id="evalorder"></span><h2>6.15. Evaluation order<a class="headerlink" href="#evaluation-order" title="Permalink to this headline">¶</a></h2>
|
||
<p id="index-91">Python evaluates expressions from left to right. Notice that while evaluating
|
||
an assignment, the right-hand side is evaluated before the left-hand side.</p>
|
||
<p>In the following lines, expressions will be evaluated in the arithmetic order of
|
||
their suffixes:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">expr1</span><span class="p">,</span> <span class="n">expr2</span><span class="p">,</span> <span class="n">expr3</span><span class="p">,</span> <span class="n">expr4</span>
|
||
<span class="p">(</span><span class="n">expr1</span><span class="p">,</span> <span class="n">expr2</span><span class="p">,</span> <span class="n">expr3</span><span class="p">,</span> <span class="n">expr4</span><span class="p">)</span>
|
||
<span class="p">{</span><span class="n">expr1</span><span class="p">:</span> <span class="n">expr2</span><span class="p">,</span> <span class="n">expr3</span><span class="p">:</span> <span class="n">expr4</span><span class="p">}</span>
|
||
<span class="n">expr1</span> <span class="o">+</span> <span class="n">expr2</span> <span class="o">*</span> <span class="p">(</span><span class="n">expr3</span> <span class="o">-</span> <span class="n">expr4</span><span class="p">)</span>
|
||
<span class="n">expr1</span><span class="p">(</span><span class="n">expr2</span><span class="p">,</span> <span class="n">expr3</span><span class="p">,</span> <span class="o">*</span><span class="n">expr4</span><span class="p">,</span> <span class="o">**</span><span class="n">expr5</span><span class="p">)</span>
|
||
<span class="n">expr3</span><span class="p">,</span> <span class="n">expr4</span> <span class="o">=</span> <span class="n">expr1</span><span class="p">,</span> <span class="n">expr2</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="operator-precedence">
|
||
<span id="operator-summary"></span><h2>6.16. Operator precedence<a class="headerlink" href="#operator-precedence" title="Permalink to this headline">¶</a></h2>
|
||
<p id="index-92">The following table summarizes the operator precedence in Python, from lowest
|
||
precedence (least binding) to highest precedence (most binding). Operators in
|
||
the same box have the same precedence. Unless the syntax is explicitly given,
|
||
operators are binary. Operators in the same box group left to right (except for
|
||
exponentiation, which groups from right to left).</p>
|
||
<p>Note that comparisons, membership tests, and identity tests, all have the same
|
||
precedence and have a left-to-right chaining feature as described in the
|
||
<a class="reference internal" href="#comparisons"><span class="std std-ref">Comparisons</span></a> section.</p>
|
||
<table class="docutils align-center">
|
||
<colgroup>
|
||
<col style="width: 56%" />
|
||
<col style="width: 44%" />
|
||
</colgroup>
|
||
<thead>
|
||
<tr class="row-odd"><th class="head"><p>Operator</p></th>
|
||
<th class="head"><p>Description</p></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="row-even"><td><p><a class="reference internal" href="#lambda"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">lambda</span></code></a></p></td>
|
||
<td><p>Lambda expression</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><a class="reference internal" href="#if-expr"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">if</span></code></a> – <code class="xref std std-keyword docutils literal notranslate"><span class="pre">else</span></code></p></td>
|
||
<td><p>Conditional expression</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><a class="reference internal" href="#or"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">or</span></code></a></p></td>
|
||
<td><p>Boolean OR</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><a class="reference internal" href="#and"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">and</span></code></a></p></td>
|
||
<td><p>Boolean AND</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><a class="reference internal" href="#not"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">not</span></code></a> <code class="docutils literal notranslate"><span class="pre">x</span></code></p></td>
|
||
<td><p>Boolean NOT</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><a class="reference internal" href="#in"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">in</span></code></a>, <a class="reference internal" href="#not-in"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">not</span> <span class="pre">in</span></code></a>,
|
||
<a class="reference internal" href="#is"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">is</span></code></a>, <a class="reference internal" href="#is-not"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">is</span> <span class="pre">not</span></code></a>, <code class="docutils literal notranslate"><span class="pre"><</span></code>,
|
||
<code class="docutils literal notranslate"><span class="pre"><=</span></code>, <code class="docutils literal notranslate"><span class="pre">></span></code>, <code class="docutils literal notranslate"><span class="pre">>=</span></code>, <code class="docutils literal notranslate"><span class="pre">!=</span></code>, <code class="docutils literal notranslate"><span class="pre">==</span></code></p></td>
|
||
<td><p>Comparisons, including membership
|
||
tests and identity tests</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">|</span></code></p></td>
|
||
<td><p>Bitwise OR</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">^</span></code></p></td>
|
||
<td><p>Bitwise XOR</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">&</span></code></p></td>
|
||
<td><p>Bitwise AND</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre"><<</span></code>, <code class="docutils literal notranslate"><span class="pre">>></span></code></p></td>
|
||
<td><p>Shifts</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">+</span></code>, <code class="docutils literal notranslate"><span class="pre">-</span></code></p></td>
|
||
<td><p>Addition and subtraction</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">*</span></code>, <code class="docutils literal notranslate"><span class="pre">@</span></code>, <code class="docutils literal notranslate"><span class="pre">/</span></code>, <code class="docutils literal notranslate"><span class="pre">//</span></code>, <code class="docutils literal notranslate"><span class="pre">%</span></code></p></td>
|
||
<td><p>Multiplication, matrix
|
||
multiplication, division, floor
|
||
division, remainder <a class="footnote-reference brackets" href="#id21" id="id15">5</a></p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">+x</span></code>, <code class="docutils literal notranslate"><span class="pre">-x</span></code>, <code class="docutils literal notranslate"><span class="pre">~x</span></code></p></td>
|
||
<td><p>Positive, negative, bitwise NOT</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">**</span></code></p></td>
|
||
<td><p>Exponentiation <a class="footnote-reference brackets" href="#id22" id="id16">6</a></p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><a class="reference internal" href="#await"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">await</span></code></a> <code class="docutils literal notranslate"><span class="pre">x</span></code></p></td>
|
||
<td><p>Await expression</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">x[index]</span></code>, <code class="docutils literal notranslate"><span class="pre">x[index:index]</span></code>,
|
||
<code class="docutils literal notranslate"><span class="pre">x(arguments...)</span></code>, <code class="docutils literal notranslate"><span class="pre">x.attribute</span></code></p></td>
|
||
<td><p>Subscription, slicing,
|
||
call, attribute reference</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">(expressions...)</span></code>,
|
||
<code class="docutils literal notranslate"><span class="pre">[expressions...]</span></code>,
|
||
<code class="docutils literal notranslate"><span class="pre">{key:</span> <span class="pre">value...}</span></code>,
|
||
<code class="docutils literal notranslate"><span class="pre">{expressions...}</span></code></p></td>
|
||
<td><p>Binding or tuple display,
|
||
list display,
|
||
dictionary display,
|
||
set display</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<p class="rubric">Footnotes</p>
|
||
<dl class="footnote brackets">
|
||
<dt class="label" id="id17"><span class="brackets"><a class="fn-backref" href="#id9">1</a></span></dt>
|
||
<dd><p>While <code class="docutils literal notranslate"><span class="pre">abs(x%y)</span> <span class="pre"><</span> <span class="pre">abs(y)</span></code> is true mathematically, for floats it may not be
|
||
true numerically due to roundoff. For example, and assuming a platform on which
|
||
a Python float is an IEEE 754 double-precision number, in order that <code class="docutils literal notranslate"><span class="pre">-1e-100</span> <span class="pre">%</span>
|
||
<span class="pre">1e100</span></code> have the same sign as <code class="docutils literal notranslate"><span class="pre">1e100</span></code>, the computed result is <code class="docutils literal notranslate"><span class="pre">-1e-100</span> <span class="pre">+</span>
|
||
<span class="pre">1e100</span></code>, which is numerically exactly equal to <code class="docutils literal notranslate"><span class="pre">1e100</span></code>. The function
|
||
<a class="reference internal" href="../library/math.html#math.fmod" title="math.fmod"><code class="xref py py-func docutils literal notranslate"><span class="pre">math.fmod()</span></code></a> returns a result whose sign matches the sign of the
|
||
first argument instead, and so returns <code class="docutils literal notranslate"><span class="pre">-1e-100</span></code> in this case. Which approach
|
||
is more appropriate depends on the application.</p>
|
||
</dd>
|
||
<dt class="label" id="id18"><span class="brackets"><a class="fn-backref" href="#id10">2</a></span></dt>
|
||
<dd><p>If x is very close to an exact integer multiple of y, it’s possible for
|
||
<code class="docutils literal notranslate"><span class="pre">x//y</span></code> to be one larger than <code class="docutils literal notranslate"><span class="pre">(x-x%y)//y</span></code> due to rounding. In such
|
||
cases, Python returns the latter result, in order to preserve that
|
||
<code class="docutils literal notranslate"><span class="pre">divmod(x,y)[0]</span> <span class="pre">*</span> <span class="pre">y</span> <span class="pre">+</span> <span class="pre">x</span> <span class="pre">%</span> <span class="pre">y</span></code> be very close to <code class="docutils literal notranslate"><span class="pre">x</span></code>.</p>
|
||
</dd>
|
||
<dt class="label" id="id19"><span class="brackets"><a class="fn-backref" href="#id12">3</a></span></dt>
|
||
<dd><p>The Unicode standard distinguishes between <em class="dfn">code points</em>
|
||
(e.g. U+0041) and <em class="dfn">abstract characters</em> (e.g. “LATIN CAPITAL LETTER A”).
|
||
While most abstract characters in Unicode are only represented using one
|
||
code point, there is a number of abstract characters that can in addition be
|
||
represented using a sequence of more than one code point. For example, the
|
||
abstract character “LATIN CAPITAL LETTER C WITH CEDILLA” can be represented
|
||
as a single <em class="dfn">precomposed character</em> at code position U+00C7, or as a
|
||
sequence of a <em class="dfn">base character</em> at code position U+0043 (LATIN CAPITAL
|
||
LETTER C), followed by a <em class="dfn">combining character</em> at code position U+0327
|
||
(COMBINING CEDILLA).</p>
|
||
<p>The comparison operators on strings compare at the level of Unicode code
|
||
points. This may be counter-intuitive to humans. For example,
|
||
<code class="docutils literal notranslate"><span class="pre">"\u00C7"</span> <span class="pre">==</span> <span class="pre">"\u0043\u0327"</span></code> is <code class="docutils literal notranslate"><span class="pre">False</span></code>, even though both strings
|
||
represent the same abstract character “LATIN CAPITAL LETTER C WITH CEDILLA”.</p>
|
||
<p>To compare strings at the level of abstract characters (that is, in a way
|
||
intuitive to humans), use <a class="reference internal" href="../library/unicodedata.html#unicodedata.normalize" title="unicodedata.normalize"><code class="xref py py-func docutils literal notranslate"><span class="pre">unicodedata.normalize()</span></code></a>.</p>
|
||
</dd>
|
||
<dt class="label" id="id20"><span class="brackets"><a class="fn-backref" href="#id13">4</a></span></dt>
|
||
<dd><p>Due to automatic garbage-collection, free lists, and the dynamic nature of
|
||
descriptors, you may notice seemingly unusual behaviour in certain uses of
|
||
the <a class="reference internal" href="#is"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">is</span></code></a> operator, like those involving comparisons between instance
|
||
methods, or constants. Check their documentation for more info.</p>
|
||
</dd>
|
||
<dt class="label" id="id21"><span class="brackets"><a class="fn-backref" href="#id15">5</a></span></dt>
|
||
<dd><p>The <code class="docutils literal notranslate"><span class="pre">%</span></code> operator is also used for string formatting; the same
|
||
precedence applies.</p>
|
||
</dd>
|
||
<dt class="label" id="id22"><span class="brackets"><a class="fn-backref" href="#id16">6</a></span></dt>
|
||
<dd><p>The power operator <code class="docutils literal notranslate"><span class="pre">**</span></code> binds less tightly than an arithmetic or
|
||
bitwise unary operator on its right, that is, <code class="docutils literal notranslate"><span class="pre">2**-1</span></code> is <code class="docutils literal notranslate"><span class="pre">0.5</span></code>.</p>
|
||
</dd>
|
||
</dl>
|
||
</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="#">6. Expressions</a><ul>
|
||
<li><a class="reference internal" href="#arithmetic-conversions">6.1. Arithmetic conversions</a></li>
|
||
<li><a class="reference internal" href="#atoms">6.2. Atoms</a><ul>
|
||
<li><a class="reference internal" href="#atom-identifiers">6.2.1. Identifiers (Names)</a></li>
|
||
<li><a class="reference internal" href="#literals">6.2.2. Literals</a></li>
|
||
<li><a class="reference internal" href="#parenthesized-forms">6.2.3. Parenthesized forms</a></li>
|
||
<li><a class="reference internal" href="#displays-for-lists-sets-and-dictionaries">6.2.4. Displays for lists, sets and dictionaries</a></li>
|
||
<li><a class="reference internal" href="#list-displays">6.2.5. List displays</a></li>
|
||
<li><a class="reference internal" href="#set-displays">6.2.6. Set displays</a></li>
|
||
<li><a class="reference internal" href="#dictionary-displays">6.2.7. Dictionary displays</a></li>
|
||
<li><a class="reference internal" href="#generator-expressions">6.2.8. Generator expressions</a></li>
|
||
<li><a class="reference internal" href="#yield-expressions">6.2.9. Yield expressions</a><ul>
|
||
<li><a class="reference internal" href="#generator-iterator-methods">6.2.9.1. Generator-iterator methods</a></li>
|
||
<li><a class="reference internal" href="#examples">6.2.9.2. Examples</a></li>
|
||
<li><a class="reference internal" href="#asynchronous-generator-functions">6.2.9.3. Asynchronous generator functions</a></li>
|
||
<li><a class="reference internal" href="#asynchronous-generator-iterator-methods">6.2.9.4. Asynchronous generator-iterator methods</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#primaries">6.3. Primaries</a><ul>
|
||
<li><a class="reference internal" href="#attribute-references">6.3.1. Attribute references</a></li>
|
||
<li><a class="reference internal" href="#subscriptions">6.3.2. Subscriptions</a></li>
|
||
<li><a class="reference internal" href="#slicings">6.3.3. Slicings</a></li>
|
||
<li><a class="reference internal" href="#calls">6.3.4. Calls</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#await-expression">6.4. Await expression</a></li>
|
||
<li><a class="reference internal" href="#the-power-operator">6.5. The power operator</a></li>
|
||
<li><a class="reference internal" href="#unary-arithmetic-and-bitwise-operations">6.6. Unary arithmetic and bitwise operations</a></li>
|
||
<li><a class="reference internal" href="#binary-arithmetic-operations">6.7. Binary arithmetic operations</a></li>
|
||
<li><a class="reference internal" href="#shifting-operations">6.8. Shifting operations</a></li>
|
||
<li><a class="reference internal" href="#binary-bitwise-operations">6.9. Binary bitwise operations</a></li>
|
||
<li><a class="reference internal" href="#comparisons">6.10. Comparisons</a><ul>
|
||
<li><a class="reference internal" href="#value-comparisons">6.10.1. Value comparisons</a></li>
|
||
<li><a class="reference internal" href="#membership-test-operations">6.10.2. Membership test operations</a></li>
|
||
<li><a class="reference internal" href="#is-not">6.10.3. Identity comparisons</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#boolean-operations">6.11. Boolean operations</a></li>
|
||
<li><a class="reference internal" href="#conditional-expressions">6.12. Conditional expressions</a></li>
|
||
<li><a class="reference internal" href="#lambda">6.13. Lambdas</a></li>
|
||
<li><a class="reference internal" href="#expression-lists">6.14. Expression lists</a></li>
|
||
<li><a class="reference internal" href="#evaluation-order">6.15. Evaluation order</a></li>
|
||
<li><a class="reference internal" href="#operator-precedence">6.16. Operator precedence</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
<h4>Previous topic</h4>
|
||
<p class="topless"><a href="import.html"
|
||
title="previous chapter">5. The import system</a></p>
|
||
<h4>Next topic</h4>
|
||
<p class="topless"><a href="simple_stmts.html"
|
||
title="next chapter">7. Simple 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/expressions.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="simple_stmts.html" title="7. Simple statements"
|
||
>next</a> |</li>
|
||
<li class="right" >
|
||
<a href="import.html" title="5. The import system"
|
||
>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> |