1912 lines
216 KiB
HTML
1912 lines
216 KiB
HTML
<!DOCTYPE html>
|
||
|
||
<html lang="en" data-content_root="../">
|
||
<head>
|
||
<meta charset="utf-8" />
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
|
||
<meta property="og:title" content="6. Expressions" />
|
||
<meta property="og:type" content="website" />
|
||
<meta property="og:url" content="https://docs.python.org/3/reference/expressions.html" />
|
||
<meta property="og:site_name" content="Python documentation" />
|
||
<meta property="og:description" content="This chapter explains the meaning of the elements of expressions in Python. Syntax Notes: In this and the following chapters, extended BNF notation will be used to describe syntax, not lexical anal..." />
|
||
<meta property="og:image" content="https://docs.python.org/3/_static/og-image.png" />
|
||
<meta property="og:image:alt" content="Python documentation" />
|
||
<meta name="description" content="This chapter explains the meaning of the elements of expressions in Python. Syntax Notes: In this and the following chapters, extended BNF notation will be used to describe syntax, not lexical anal..." />
|
||
<meta property="og:image:width" content="200">
|
||
<meta property="og:image:height" content="200">
|
||
<meta name="theme-color" content="#3776ab">
|
||
|
||
<title>6. Expressions — Python 3.13.3 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
|
||
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />
|
||
<link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=23252803" />
|
||
<link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=5349f25f" />
|
||
|
||
<script src="../_static/documentation_options.js?v=5d57ca2d"></script>
|
||
<script src="../_static/doctools.js?v=9bcbadda"></script>
|
||
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
|
||
|
||
<script src="../_static/sidebar.js"></script>
|
||
|
||
<link rel="search" type="application/opensearchdescription+xml"
|
||
title="Search within Python 3.13.3 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="canonical" href="https://docs.python.org/3/reference/expressions.html">
|
||
|
||
|
||
|
||
|
||
|
||
<style>
|
||
@media only screen {
|
||
table.full-width-table {
|
||
width: 100%;
|
||
}
|
||
}
|
||
</style>
|
||
<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">
|
||
<link rel="shortcut icon" type="image/png" href="../_static/py.svg" />
|
||
<script type="text/javascript" src="../_static/copybutton.js"></script>
|
||
<script type="text/javascript" src="../_static/menu.js"></script>
|
||
<script type="text/javascript" src="../_static/search-focus.js"></script>
|
||
<script type="text/javascript" src="../_static/themetoggle.js"></script>
|
||
<script type="text/javascript" src="../_static/rtd_switcher.js"></script>
|
||
<meta name="readthedocs-addons-api-version" content="1">
|
||
|
||
</head>
|
||
<body>
|
||
<div class="mobile-nav">
|
||
<input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"
|
||
aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu" />
|
||
<nav class="nav-content" role="navigation">
|
||
<label for="menuToggler" class="toggler__label">
|
||
<span></span>
|
||
</label>
|
||
<span class="nav-items-wrapper">
|
||
<a href="https://www.python.org/" class="nav-logo">
|
||
<img src="../_static/py.svg" alt="Python logo"/>
|
||
</a>
|
||
<span class="version_switcher_placeholder"></span>
|
||
<form role="search" class="search" action="../search.html" method="get">
|
||
<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">
|
||
<path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>
|
||
</svg>
|
||
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" />
|
||
<input type="submit" value="Go"/>
|
||
</form>
|
||
</span>
|
||
</nav>
|
||
<div class="menu-wrapper">
|
||
<nav class="menu" role="navigation" aria-label="main navigation">
|
||
<div class="language_switcher_placeholder"></div>
|
||
|
||
<label class="theme-selector-label">
|
||
Theme
|
||
<select class="theme-selector" oninput="activateTheme(this.value)">
|
||
<option value="auto" selected>Auto</option>
|
||
<option value="light">Light</option>
|
||
<option value="dark">Dark</option>
|
||
</select>
|
||
</label>
|
||
<div>
|
||
<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><ul>
|
||
<li><a class="reference internal" href="#index-5">6.2.1.1. Private name mangling</a></li>
|
||
</ul>
|
||
</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="#assignment-expressions">6.12. Assignment expressions</a></li>
|
||
<li><a class="reference internal" href="#conditional-expressions">6.13. Conditional expressions</a></li>
|
||
<li><a class="reference internal" href="#lambda">6.14. Lambdas</a></li>
|
||
<li><a class="reference internal" href="#expression-lists">6.15. Expression lists</a></li>
|
||
<li><a class="reference internal" href="#evaluation-order">6.16. Evaluation order</a></li>
|
||
<li><a class="reference internal" href="#operator-precedence">6.17. Operator precedence</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
</div>
|
||
<div>
|
||
<h4>Previous topic</h4>
|
||
<p class="topless"><a href="import.html"
|
||
title="previous chapter"><span class="section-number">5. </span>The import system</a></p>
|
||
</div>
|
||
<div>
|
||
<h4>Next topic</h4>
|
||
<p class="topless"><a href="simple_stmts.html"
|
||
title="next chapter"><span class="section-number">7. </span>Simple statements</a></p>
|
||
</div>
|
||
<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/main/Doc/reference/expressions.rst"
|
||
rel="nofollow">Show Source
|
||
</a>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</nav>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
<div class="related" role="navigation" aria-label="Related">
|
||
<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.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li class="switchers">
|
||
<div class="language_switcher_placeholder"></div>
|
||
<div class="version_switcher_placeholder"></div>
|
||
</li>
|
||
<li>
|
||
|
||
</li>
|
||
<li id="cpython-language-and-version">
|
||
<a href="../index.html">3.13.3 Documentation</a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">The Python Language Reference</a> »</li>
|
||
<li class="nav-item nav-item-this"><a href=""><span class="section-number">6. </span>Expressions</a></li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />
|
||
<input type="submit" value="Go" />
|
||
</form>
|
||
</div>
|
||
|
|
||
</li>
|
||
<li class="right">
|
||
<label class="theme-selector-label">
|
||
Theme
|
||
<select class="theme-selector" oninput="activateTheme(this.value)">
|
||
<option value="auto" selected>Auto</option>
|
||
<option value="light">Light</option>
|
||
<option value="dark">Dark</option>
|
||
</select>
|
||
</label> |</li>
|
||
|
||
</ul>
|
||
</div>
|
||
|
||
<div class="document">
|
||
<div class="documentwrapper">
|
||
<div class="bodywrapper">
|
||
<div class="body" role="main">
|
||
|
||
<section id="expressions">
|
||
<span id="id1"></span><h1><span class="section-number">6. </span>Expressions<a class="headerlink" href="#expressions" title="Link to this heading">¶</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-python-grammar-name">name</strong> ::= othername
|
||
</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>
|
||
<section id="arithmetic-conversions">
|
||
<span id="conversions"></span><h2><span class="section-number">6.1. </span>Arithmetic conversions<a class="headerlink" href="#arithmetic-conversions" title="Link to this heading">¶</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>
|
||
</section>
|
||
<section id="atoms">
|
||
<span id="id2"></span><h2><span class="section-number">6.2. </span>Atoms<a class="headerlink" href="#atoms" title="Link to this heading">¶</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-python-grammar-atom">atom</strong> ::= <a class="reference internal" href="lexical_analysis.html#grammar-token-python-grammar-identifier"><code class="xref docutils literal notranslate"><span class="pre">identifier</span></code></a> | <a class="reference internal" href="#grammar-token-python-grammar-literal"><code class="xref docutils literal notranslate"><span class="pre">literal</span></code></a> | <a class="reference internal" href="#grammar-token-python-grammar-enclosure"><code class="xref docutils literal notranslate"><span class="pre">enclosure</span></code></a>
|
||
<strong id="grammar-token-python-grammar-enclosure">enclosure</strong> ::= <a class="reference internal" href="#grammar-token-python-grammar-parenth_form"><code class="xref docutils literal notranslate"><span class="pre">parenth_form</span></code></a> | <a class="reference internal" href="#grammar-token-python-grammar-list_display"><code class="xref docutils literal notranslate"><span class="pre">list_display</span></code></a> | <a class="reference internal" href="#grammar-token-python-grammar-dict_display"><code class="xref docutils literal notranslate"><span class="pre">dict_display</span></code></a> | <a class="reference internal" href="#grammar-token-python-grammar-set_display"><code class="xref docutils literal notranslate"><span class="pre">set_display</span></code></a>
|
||
| <a class="reference internal" href="#grammar-token-python-grammar-generator_expression"><code class="xref docutils literal notranslate"><span class="pre">generator_expression</span></code></a> | <a class="reference internal" href="#grammar-token-python-grammar-yield_atom"><code class="xref docutils literal notranslate"><span class="pre">yield_atom</span></code></a>
|
||
</pre>
|
||
<section id="atom-identifiers">
|
||
<span id="identifiers-names"></span><h3><span class="section-number">6.2.1. </span>Identifiers (Names)<a class="headerlink" href="#atom-identifiers" title="Link to this heading">¶</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>
|
||
<section id="index-5">
|
||
<span id="private-name-mangling"></span><span id="id3"></span><h4><span class="section-number">6.2.1.1. </span>Private name mangling<a class="headerlink" href="#index-5" title="Link to this heading">¶</a></h4>
|
||
<p>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.</p>
|
||
<div class="admonition seealso">
|
||
<p class="admonition-title">See also</p>
|
||
<p>The <a class="reference internal" href="compound_stmts.html#class"><span class="std std-ref">class specifications</span></a>.</p>
|
||
</div>
|
||
<p>More precisely, private names are transformed to a longer form before code is
|
||
generated for them. If the transformed name is longer than 255 characters,
|
||
implementation-defined truncation may happen.</p>
|
||
<p>The transformation is independent of the syntactical context in which the
|
||
identifier is used but only the following private identifiers are mangled:</p>
|
||
<ul>
|
||
<li><p>Any name used as the name of a variable that is assigned or read or any
|
||
name of an attribute being accessed.</p>
|
||
<p>The <a class="reference internal" href="../library/stdtypes.html#definition.__name__" title="definition.__name__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__name__</span></code></a> attribute of nested functions, classes, and
|
||
type aliases is however not mangled.</p>
|
||
</li>
|
||
<li><p>The name of imported modules, e.g., <code class="docutils literal notranslate"><span class="pre">__spam</span></code> in <code class="docutils literal notranslate"><span class="pre">import</span> <span class="pre">__spam</span></code>.
|
||
If the module is part of a package (i.e., its name contains a dot),
|
||
the name is <em>not</em> mangled, e.g., the <code class="docutils literal notranslate"><span class="pre">__foo</span></code> in <code class="docutils literal notranslate"><span class="pre">import</span> <span class="pre">__foo.bar</span></code>
|
||
is not mangled.</p></li>
|
||
<li><p>The name of an imported member, e.g., <code class="docutils literal notranslate"><span class="pre">__f</span></code> in <code class="docutils literal notranslate"><span class="pre">from</span> <span class="pre">spam</span> <span class="pre">import</span> <span class="pre">__f</span></code>.</p></li>
|
||
</ul>
|
||
<p>The transformation rule is defined as follows:</p>
|
||
<ul class="simple">
|
||
<li><p>The class name, with leading underscores removed and a single leading
|
||
underscore inserted, is inserted in front of the identifier, e.g., 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">Foo</span></code>, <code class="docutils literal notranslate"><span class="pre">_Foo</span></code> or
|
||
<code class="docutils literal notranslate"><span class="pre">__Foo</span></code> is transformed to <code class="docutils literal notranslate"><span class="pre">_Foo__spam</span></code>.</p></li>
|
||
<li><p>If the class name consists only of underscores, the transformation is the
|
||
identity, e.g., 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">_</span></code>
|
||
or <code class="docutils literal notranslate"><span class="pre">__</span></code> is left as is.</p></li>
|
||
</ul>
|
||
</section>
|
||
</section>
|
||
<section id="literals">
|
||
<span id="atom-literals"></span><h3><span class="section-number">6.2.2. </span>Literals<a class="headerlink" href="#literals" title="Link to this heading">¶</a></h3>
|
||
<p id="index-6">Python supports string and bytes literals and various numeric literals:</p>
|
||
<pre>
|
||
<strong id="grammar-token-python-grammar-literal">literal</strong> ::= <a class="reference internal" href="lexical_analysis.html#grammar-token-python-grammar-stringliteral"><code class="xref docutils literal notranslate"><span class="pre">stringliteral</span></code></a> | <a class="reference internal" href="lexical_analysis.html#grammar-token-python-grammar-bytesliteral"><code class="xref docutils literal notranslate"><span class="pre">bytesliteral</span></code></a>
|
||
| <a class="reference internal" href="lexical_analysis.html#grammar-token-python-grammar-integer"><code class="xref docutils literal notranslate"><span class="pre">integer</span></code></a> | <a class="reference internal" href="lexical_analysis.html#grammar-token-python-grammar-floatnumber"><code class="xref docutils literal notranslate"><span class="pre">floatnumber</span></code></a> | <a class="reference internal" href="lexical_analysis.html#grammar-token-python-grammar-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>
|
||
</section>
|
||
<section id="parenthesized-forms">
|
||
<span id="parenthesized"></span><h3><span class="section-number">6.2.3. </span>Parenthesized forms<a class="headerlink" href="#parenthesized-forms" title="Link to this heading">¶</a></h3>
|
||
<p id="index-8">A parenthesized form is an optional expression list enclosed in parentheses:</p>
|
||
<pre>
|
||
<strong id="grammar-token-python-grammar-parenth_form">parenth_form</strong> ::= "(" [<a class="reference internal" href="#grammar-token-python-grammar-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. 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>
|
||
</section>
|
||
<section id="displays-for-lists-sets-and-dictionaries">
|
||
<span id="comprehensions"></span><h3><span class="section-number">6.2.4. </span>Displays for lists, sets and dictionaries<a class="headerlink" href="#displays-for-lists-sets-and-dictionaries" title="Link to this heading">¶</a></h3>
|
||
<p id="index-11">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-12">Common syntax elements for comprehensions are:</p>
|
||
<pre>
|
||
<strong id="grammar-token-python-grammar-comprehension">comprehension</strong> ::= <a class="reference internal" href="#grammar-token-python-grammar-assignment_expression"><code class="xref docutils literal notranslate"><span class="pre">assignment_expression</span></code></a> <a class="reference internal" href="#grammar-token-python-grammar-comp_for"><code class="xref docutils literal notranslate"><span class="pre">comp_for</span></code></a>
|
||
<strong id="grammar-token-python-grammar-comp_for">comp_for</strong> ::= ["async"] "for" <a class="reference internal" href="simple_stmts.html#grammar-token-python-grammar-target_list"><code class="xref docutils literal notranslate"><span class="pre">target_list</span></code></a> "in" <a class="reference internal" href="#grammar-token-python-grammar-or_test"><code class="xref docutils literal notranslate"><span class="pre">or_test</span></code></a> [<a class="reference internal" href="#grammar-token-python-grammar-comp_iter"><code class="xref docutils literal notranslate"><span class="pre">comp_iter</span></code></a>]
|
||
<strong id="grammar-token-python-grammar-comp_iter">comp_iter</strong> ::= <a class="reference internal" href="#grammar-token-python-grammar-comp_for"><code class="xref docutils literal notranslate"><span class="pre">comp_for</span></code></a> | <a class="reference internal" href="#grammar-token-python-grammar-comp_if"><code class="xref docutils literal notranslate"><span class="pre">comp_if</span></code></a>
|
||
<strong id="grammar-token-python-grammar-comp_if">comp_if</strong> ::= "if" <a class="reference internal" href="#grammar-token-python-grammar-or_test"><code class="xref docutils literal notranslate"><span class="pre">or_test</span></code></a> [<a class="reference internal" href="#grammar-token-python-grammar-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 implicitly
|
||
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.</p>
|
||
<p id="index-13">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.</p>
|
||
<p>If a comprehension contains <code class="xref std std-keyword docutils literal notranslate"><span class="pre">async</span> <span class="pre">for</span></code> clauses, or if it contains
|
||
<code class="xref std std-keyword docutils literal notranslate"><span class="pre">await</span></code> expressions or other asynchronous comprehensions anywhere except
|
||
the iterable expression in the leftmost <code class="xref std std-keyword docutils literal notranslate"><span class="pre">for</span></code> clause, 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-14"></span><a class="pep reference external" href="https://peps.python.org/pep-0530/"><strong>PEP 530</strong></a>.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">Added in version 3.6: </span>Asynchronous comprehensions were introduced.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.8: </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> prohibited in the implicitly nested scope.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.11: </span>Asynchronous comprehensions are now allowed inside comprehensions in
|
||
asynchronous functions. Outer comprehensions implicitly become
|
||
asynchronous.</p>
|
||
</div>
|
||
</section>
|
||
<section id="list-displays">
|
||
<span id="lists"></span><h3><span class="section-number">6.2.5. </span>List displays<a class="headerlink" href="#list-displays" title="Link to this heading">¶</a></h3>
|
||
<p id="index-15">A list display is a possibly empty series of expressions enclosed in square
|
||
brackets:</p>
|
||
<pre>
|
||
<strong id="grammar-token-python-grammar-list_display">list_display</strong> ::= "[" [<a class="reference internal" href="#grammar-token-python-grammar-flexible_expression_list"><code class="xref docutils literal notranslate"><span class="pre">flexible_expression_list</span></code></a> | <a class="reference internal" href="#grammar-token-python-grammar-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>
|
||
</section>
|
||
<section id="set-displays">
|
||
<span id="set"></span><h3><span class="section-number">6.2.6. </span>Set displays<a class="headerlink" href="#set-displays" title="Link to this heading">¶</a></h3>
|
||
<p id="index-16">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-python-grammar-set_display">set_display</strong> ::= "{" (<a class="reference internal" href="#grammar-token-python-grammar-flexible_expression_list"><code class="xref docutils literal notranslate"><span class="pre">flexible_expression_list</span></code></a> | <a class="reference internal" href="#grammar-token-python-grammar-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>
|
||
</section>
|
||
<section id="dictionary-displays">
|
||
<span id="dict"></span><h3><span class="section-number">6.2.7. </span>Dictionary displays<a class="headerlink" href="#dictionary-displays" title="Link to this heading">¶</a></h3>
|
||
<p id="index-17">A dictionary display is a possibly empty series of dict items (key/value pairs)
|
||
enclosed in curly braces:</p>
|
||
<pre>
|
||
<strong id="grammar-token-python-grammar-dict_display">dict_display</strong> ::= "{" [<a class="reference internal" href="#grammar-token-python-grammar-dict_item_list"><code class="xref docutils literal notranslate"><span class="pre">dict_item_list</span></code></a> | <a class="reference internal" href="#grammar-token-python-grammar-dict_comprehension"><code class="xref docutils literal notranslate"><span class="pre">dict_comprehension</span></code></a>] "}"
|
||
<strong id="grammar-token-python-grammar-dict_item_list">dict_item_list</strong> ::= <a class="reference internal" href="#grammar-token-python-grammar-dict_item"><code class="xref docutils literal notranslate"><span class="pre">dict_item</span></code></a> ("," <a class="reference internal" href="#grammar-token-python-grammar-dict_item"><code class="xref docutils literal notranslate"><span class="pre">dict_item</span></code></a>)* [","]
|
||
<strong id="grammar-token-python-grammar-dict_item">dict_item</strong> ::= <a class="reference internal" href="#grammar-token-python-grammar-expression"><code class="xref docutils literal notranslate"><span class="pre">expression</span></code></a> ":" <a class="reference internal" href="#grammar-token-python-grammar-expression"><code class="xref docutils literal notranslate"><span class="pre">expression</span></code></a> | "**" <a class="reference internal" href="#grammar-token-python-grammar-or_expr"><code class="xref docutils literal notranslate"><span class="pre">or_expr</span></code></a>
|
||
<strong id="grammar-token-python-grammar-dict_comprehension">dict_comprehension</strong> ::= <a class="reference internal" href="#grammar-token-python-grammar-expression"><code class="xref docutils literal notranslate"><span class="pre">expression</span></code></a> ":" <a class="reference internal" href="#grammar-token-python-grammar-expression"><code class="xref docutils literal notranslate"><span class="pre">expression</span></code></a> <a class="reference internal" href="#grammar-token-python-grammar-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 dict items 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 value. This means
|
||
that you can specify the same key multiple times in the dict item list, and the
|
||
final dictionary’s value for that key will be the last one given.</p>
|
||
<p id="index-18">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 dict items and earlier dictionary unpackings.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">Added in version 3.5: </span>Unpacking into dictionary displays, originally proposed by <span class="target" id="index-19"></span><a class="pep reference external" href="https://peps.python.org/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-20">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
|
||
value (textually rightmost in the display) stored for a given key value
|
||
prevails.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.8: </span>Prior to Python 3.8, in dict comprehensions, the evaluation order of key
|
||
and value was not well-defined. In CPython, the value was evaluated before
|
||
the key. Starting with 3.8, the key is evaluated before the value, as
|
||
proposed by <span class="target" id="index-21"></span><a class="pep reference external" href="https://peps.python.org/pep-0572/"><strong>PEP 572</strong></a>.</p>
|
||
</div>
|
||
</section>
|
||
<section id="generator-expressions">
|
||
<span id="genexpr"></span><h3><span class="section-number">6.2.8. </span>Generator expressions<a class="headerlink" href="#generator-expressions" title="Link to this heading">¶</a></h3>
|
||
<p id="index-22">A generator expression is a compact generator notation in parentheses:</p>
|
||
<pre>
|
||
<strong id="grammar-token-python-grammar-generator_expression">generator_expression</strong> ::= "(" <a class="reference internal" href="#grammar-token-python-grammar-expression"><code class="xref docutils literal notranslate"><span class="pre">expression</span></code></a> <a class="reference internal" href="#grammar-token-python-grammar-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.</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">Added 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="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.8: </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> prohibited in the implicitly nested scope.</p>
|
||
</div>
|
||
</section>
|
||
<section id="yield-expressions">
|
||
<span id="yieldexpr"></span><h3><span class="section-number">6.2.9. </span>Yield expressions<a class="headerlink" href="#yield-expressions" title="Link to this heading">¶</a></h3>
|
||
<pre id="index-23">
|
||
<strong id="grammar-token-python-grammar-yield_atom">yield_atom</strong> ::= "(" <a class="reference internal" href="#grammar-token-python-grammar-yield_expression"><code class="xref docutils literal notranslate"><span class="pre">yield_expression</span></code></a> ")"
|
||
<strong id="grammar-token-python-grammar-yield_from">yield_from</strong> ::= "yield" "from" <a class="reference internal" href="#grammar-token-python-grammar-expression"><code class="xref docutils literal notranslate"><span class="pre">expression</span></code></a>
|
||
<strong id="grammar-token-python-grammar-yield_expression">yield_expression</strong> ::= "yield" <a class="reference internal" href="#grammar-token-python-grammar-yield_list"><code class="xref docutils literal notranslate"><span class="pre">yield_list</span></code></a> | <a class="reference internal" href="#grammar-token-python-grammar-yield_from"><code class="xref docutils literal notranslate"><span class="pre">yield_from</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 function,
|
||
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 function. For example:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </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="w"> </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.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.8: </span>Yield expressions prohibited 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-python-grammar-yield_list"><code class="xref std std-token docutils literal notranslate"><span class="pre">yield_list</span></code></a>
|
||
to the generator’s caller,
|
||
or <code class="docutils literal notranslate"><span class="pre">None</span></code> if <a class="reference internal" href="#grammar-token-python-grammar-yield_list"><code class="xref std std-token docutils literal notranslate"><span class="pre">yield_list</span></code></a> is omitted.
|
||
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-24">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-25">When <code class="docutils literal notranslate"><span class="pre">yield</span> <span class="pre">from</span> <span class="pre"><expr></span></code> is used, the supplied expression must be an
|
||
iterable. The values produced by iterating that iterable 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 <a class="reference internal" href="../library/exceptions.html#StopIteration.value" title="StopIteration.value"><code class="xref py py-attr docutils literal notranslate"><span class="pre">value</span></code></a>
|
||
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>
|
||
<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>
|
||
<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-26"></span><a class="pep reference external" href="https://peps.python.org/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-27"></span><a class="pep reference external" href="https://peps.python.org/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-28"></span><a class="pep reference external" href="https://peps.python.org/pep-0380/"><strong>PEP 380</strong></a> - Syntax for Delegating to a Subgenerator</dt><dd><p>The proposal to introduce the <a class="reference internal" href="#grammar-token-python-grammar-yield_from"><code class="xref std std-token docutils literal notranslate"><span class="pre">yield_from</span></code></a> syntax,
|
||
making delegation to subgenerators easy.</p>
|
||
</dd>
|
||
<dt><span class="target" id="index-29"></span><a class="pep reference external" href="https://peps.python.org/pep-0525/"><strong>PEP 525</strong></a> - Asynchronous Generators</dt><dd><p>The proposal that expanded on <span class="target" id="index-30"></span><a class="pep reference external" href="https://peps.python.org/pep-0492/"><strong>PEP 492</strong></a> by adding generator capabilities to
|
||
coroutine functions.</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
<section id="generator-iterator-methods">
|
||
<span id="generator-methods"></span><span id="index-31"></span><h4><span class="section-number">6.2.9.1. </span>Generator-iterator methods<a class="headerlink" href="#generator-iterator-methods" title="Link to this heading">¶</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>
|
||
<dl class="py method" id="index-32">
|
||
<dt class="sig sig-object py" id="generator.__next__">
|
||
<span class="sig-prename descclassname"><span class="pre">generator.</span></span><span class="sig-name descname"><span class="pre">__next__</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#generator.__next__" title="Link 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-python-grammar-yield_list"><code class="xref std std-token docutils literal notranslate"><span class="pre">yield_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="py method">
|
||
<dt class="sig sig-object py" id="generator.send">
|
||
<span class="sig-prename descclassname"><span class="pre">generator.</span></span><span class="sig-name descname"><span class="pre">send</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">value</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#generator.send" title="Link 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="py method">
|
||
<dt class="sig sig-object py" id="generator.throw">
|
||
<span class="sig-prename descclassname"><span class="pre">generator.</span></span><span class="sig-name descname"><span class="pre">throw</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">value</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#generator.throw" title="Link to this definition">¶</a></dt>
|
||
<dt class="sig sig-object py">
|
||
<span class="sig-prename descclassname"><span class="pre">generator.</span></span><span class="sig-name descname"><span class="pre">throw</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">type</span></span></em><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">value</span></span></em><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">traceback</span></span></em><span class="optional">]</span><span class="optional">]</span><span class="sig-paren">)</span></dt>
|
||
<dd><p>Raises an exception 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>
|
||
<p>In typical use, this is called with a single exception instance similar to the
|
||
way the <a class="reference internal" href="simple_stmts.html#raise"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">raise</span></code></a> keyword is used.</p>
|
||
<p>For backwards compatibility, however, the second signature is
|
||
supported, following a convention from older versions of Python.
|
||
The <em>type</em> argument should be an exception class, and <em>value</em>
|
||
should be an exception instance. If the <em>value</em> is not provided, the
|
||
<em>type</em> constructor is called to get an instance. If <em>traceback</em>
|
||
is provided, it is set on the exception, otherwise any existing
|
||
<a class="reference internal" href="../library/exceptions.html#BaseException.__traceback__" title="BaseException.__traceback__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__traceback__</span></code></a> attribute stored in <em>value</em> may
|
||
be cleared.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.12: </span>The second signature (type[, value[, traceback]]) is deprecated and
|
||
may be removed in a future version of Python.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py method" id="index-33">
|
||
<dt class="sig sig-object py" id="generator.close">
|
||
<span class="sig-prename descclassname"><span class="pre">generator.</span></span><span class="sig-name descname"><span class="pre">close</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#generator.close" title="Link 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 catches the exception and returns a
|
||
value, this value is returned from <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>. If the generator function
|
||
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), <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> returns <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>. 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. If the generator has already
|
||
exited due to an exception or normal exit, <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> returns
|
||
<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> and has no other effect.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.13: </span>If a generator returns a value upon being closed, the value is returned
|
||
by <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>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
</section>
|
||
<section id="examples">
|
||
<span id="index-34"></span><h4><span class="section-number">6.2.9.2. </span>Examples<a class="headerlink" href="#examples" title="Link to this heading">¶</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="w"> </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>
|
||
</section>
|
||
<section id="asynchronous-generator-functions">
|
||
<span id="id4"></span><h4><span class="section-number">6.2.9.3. </span>Asynchronous generator functions<a class="headerlink" href="#asynchronous-generator-functions" title="Link to this heading">¶</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-python-grammar-yield_list"><code class="xref std std-token docutils literal notranslate"><span class="pre">yield_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>If an asynchronous generator happens to exit early by <a class="reference internal" href="simple_stmts.html#break"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">break</span></code></a>, the caller
|
||
task being cancelled, or other exceptions, the generator’s async cleanup code
|
||
will run and possibly raise exceptions or access context variables in an
|
||
unexpected context–perhaps after the lifetime of tasks it depends, or
|
||
during the event loop shutdown when the async-generator garbage collection hook
|
||
is called.
|
||
To prevent this, the caller must explicitly close the async generator by calling
|
||
<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 to finalize the generator and ultimately detach it
|
||
from the event loop.</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 upon event loop termination, 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="extlink-source reference external" href="https://github.com/python/cpython/tree/3.13/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>
|
||
</section>
|
||
<section id="asynchronous-generator-iterator-methods">
|
||
<span id="asynchronous-generator-methods"></span><span id="index-35"></span><h4><span class="section-number">6.2.9.4. </span>Asynchronous generator-iterator methods<a class="headerlink" href="#asynchronous-generator-iterator-methods" title="Link to this heading">¶</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>
|
||
<dl class="py method" id="index-36">
|
||
<dt class="sig sig-object py" id="agen.__anext__">
|
||
<em class="property"><span class="k"><span class="pre">async</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">agen.</span></span><span class="sig-name descname"><span class="pre">__anext__</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#agen.__anext__" title="Link 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-python-grammar-yield_list"><code class="xref std std-token docutils literal notranslate"><span class="pre">yield_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="py method">
|
||
<dt class="sig sig-object py" id="agen.asend">
|
||
<em class="property"><span class="k"><span class="pre">async</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">agen.</span></span><span class="sig-name descname"><span class="pre">asend</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">value</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#agen.asend" title="Link 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="py method">
|
||
<dt class="sig sig-object py" id="agen.athrow">
|
||
<em class="property"><span class="k"><span class="pre">async</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">agen.</span></span><span class="sig-name descname"><span class="pre">athrow</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">value</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#agen.athrow" title="Link to this definition">¶</a></dt>
|
||
<dt class="sig sig-object py">
|
||
<em class="property"><span class="k"><span class="pre">async</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">agen.</span></span><span class="sig-name descname"><span class="pre">athrow</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">type</span></span></em><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">value</span></span></em><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">traceback</span></span></em><span class="optional">]</span><span class="optional">]</span><span class="sig-paren">)</span></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>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.12: </span>The second signature (type[, value[, traceback]]) is deprecated and
|
||
may be removed in a future version of Python.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py method" id="index-37">
|
||
<dt class="sig sig-object py" id="agen.aclose">
|
||
<em class="property"><span class="k"><span class="pre">async</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">agen.</span></span><span class="sig-name descname"><span class="pre">aclose</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#agen.aclose" title="Link 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>
|
||
|
||
</section>
|
||
</section>
|
||
</section>
|
||
<section id="primaries">
|
||
<span id="id5"></span><h2><span class="section-number">6.3. </span>Primaries<a class="headerlink" href="#primaries" title="Link to this heading">¶</a></h2>
|
||
<p id="index-38">Primaries represent the most tightly bound operations of the language. Their
|
||
syntax is:</p>
|
||
<pre>
|
||
<strong id="grammar-token-python-grammar-primary">primary</strong> ::= <a class="reference internal" href="#grammar-token-python-grammar-atom"><code class="xref docutils literal notranslate"><span class="pre">atom</span></code></a> | <a class="reference internal" href="#grammar-token-python-grammar-attributeref"><code class="xref docutils literal notranslate"><span class="pre">attributeref</span></code></a> | <a class="reference internal" href="#grammar-token-python-grammar-subscription"><code class="xref docutils literal notranslate"><span class="pre">subscription</span></code></a> | <a class="reference internal" href="#grammar-token-python-grammar-slicing"><code class="xref docutils literal notranslate"><span class="pre">slicing</span></code></a> | <a class="reference internal" href="#grammar-token-python-grammar-call"><code class="xref docutils literal notranslate"><span class="pre">call</span></code></a>
|
||
</pre>
|
||
<section id="attribute-references">
|
||
<span id="id6"></span><h3><span class="section-number">6.3.1. </span>Attribute references<a class="headerlink" href="#attribute-references" title="Link to this heading">¶</a></h3>
|
||
<p id="index-39">An attribute reference is a primary followed by a period and a name:</p>
|
||
<pre>
|
||
<strong id="grammar-token-python-grammar-attributeref">attributeref</strong> ::= <a class="reference internal" href="#grammar-token-python-grammar-primary"><code class="xref docutils literal notranslate"><span class="pre">primary</span></code></a> "." <a class="reference internal" href="lexical_analysis.html#grammar-token-python-grammar-identifier"><code class="xref docutils literal notranslate"><span class="pre">identifier</span></code></a>
|
||
</pre>
|
||
<p id="index-40">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. The type and value produced is
|
||
determined by the object. Multiple evaluations of the same attribute
|
||
reference may yield different objects.</p>
|
||
<p>This production can be customized by overriding the
|
||
<a class="reference internal" href="datamodel.html#object.__getattribute__" title="object.__getattribute__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__getattribute__()</span></code></a> method or 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. The <code class="xref py py-meth docutils literal notranslate"><span class="pre">__getattribute__()</span></code> method is called first and either
|
||
returns a value or raises <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> if the attribute is not
|
||
available.</p>
|
||
<p>If an <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 and the object has a <code class="xref py py-meth docutils literal notranslate"><span class="pre">__getattr__()</span></code>
|
||
method, that method is called as a fallback.</p>
|
||
</section>
|
||
<section id="subscriptions">
|
||
<span id="id7"></span><h3><span class="section-number">6.3.2. </span>Subscriptions<a class="headerlink" href="#subscriptions" title="Link to this heading">¶</a></h3>
|
||
<p id="index-42"><span id="index-41"></span>The subscription of an instance of a <a class="reference internal" href="datamodel.html#sequence-types"><span class="std std-ref">container class</span></a>
|
||
will generally select an element from the container. The subscription of a
|
||
<a class="reference internal" href="../glossary.html#term-generic-type"><span class="xref std std-term">generic class</span></a> will generally return a
|
||
<a class="reference internal" href="../library/stdtypes.html#types-genericalias"><span class="std std-ref">GenericAlias</span></a> object.</p>
|
||
<pre>
|
||
<strong id="grammar-token-python-grammar-subscription">subscription</strong> ::= <a class="reference internal" href="#grammar-token-python-grammar-primary"><code class="xref docutils literal notranslate"><span class="pre">primary</span></code></a> "[" <a class="reference internal" href="#grammar-token-python-grammar-flexible_expression_list"><code class="xref docutils literal notranslate"><span class="pre">flexible_expression_list</span></code></a> "]"
|
||
</pre>
|
||
<p>When an object is subscripted, the interpreter will evaluate the primary and
|
||
the expression list.</p>
|
||
<p>The primary must evaluate to an object that supports subscription. An object
|
||
may support subscription through defining one or both of
|
||
<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> and <a class="reference internal" href="datamodel.html#object.__class_getitem__" title="object.__class_getitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__class_getitem__()</span></code></a>. When the
|
||
primary is subscripted, the evaluated result of the expression list will be
|
||
passed to one of these methods. For more details on when <code class="docutils literal notranslate"><span class="pre">__class_getitem__</span></code>
|
||
is called instead of <code class="docutils literal notranslate"><span class="pre">__getitem__</span></code>, see <a class="reference internal" href="datamodel.html#classgetitem-versus-getitem"><span class="std std-ref">__class_getitem__ versus __getitem__</span></a>.</p>
|
||
<p>If the expression list contains at least one comma, or if any of the expressions
|
||
are starred, the expression list will evaluate to a <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> containing
|
||
the items of the expression list. Otherwise, the expression list will evaluate
|
||
to the value of the list’s sole member.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.11: </span>Expressions in an expression list may be starred. See <span class="target" id="index-43"></span><a class="pep reference external" href="https://peps.python.org/pep-0646/"><strong>PEP 646</strong></a>.</p>
|
||
</div>
|
||
<p>For built-in objects, there are two types of objects that support subscription
|
||
via <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>:</p>
|
||
<ol class="arabic simple">
|
||
<li><p>Mappings. If the primary is a <a class="reference internal" href="../glossary.html#term-mapping"><span class="xref std std-term">mapping</span></a>, 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.
|
||
An example of a builtin mapping class is the <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> class.</p></li>
|
||
<li><p>Sequences. If the primary is a <a class="reference internal" href="../glossary.html#term-sequence"><span class="xref std std-term">sequence</span></a>, the expression list must
|
||
evaluate to an <a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a> or a <a class="reference internal" href="../library/functions.html#slice" title="slice"><code class="xref py py-class docutils literal notranslate"><span class="pre">slice</span></code></a> (as discussed in the
|
||
following section). Examples of builtin sequence classes include the
|
||
<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>, <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> and <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> classes.</p></li>
|
||
</ol>
|
||
<p>The formal syntax makes no special provision for negative indices in
|
||
<a class="reference internal" href="../glossary.html#term-sequence"><span class="xref std std-term">sequences</span></a>. 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, for example, <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-44">A <a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">string</span></code></a> is a special kind of sequence whose items are
|
||
<em>characters</em>. A character is not a separate data type but a
|
||
string of exactly one character.</p>
|
||
</section>
|
||
<section id="slicings">
|
||
<span id="id8"></span><h3><span class="section-number">6.3.3. </span>Slicings<a class="headerlink" href="#slicings" title="Link to this heading">¶</a></h3>
|
||
<p id="index-46"><span id="index-45"></span>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-python-grammar-slicing">slicing</strong> ::= <a class="reference internal" href="#grammar-token-python-grammar-primary"><code class="xref docutils literal notranslate"><span class="pre">primary</span></code></a> "[" <a class="reference internal" href="#grammar-token-python-grammar-slice_list"><code class="xref docutils literal notranslate"><span class="pre">slice_list</span></code></a> "]"
|
||
<strong id="grammar-token-python-grammar-slice_list">slice_list</strong> ::= <a class="reference internal" href="#grammar-token-python-grammar-slice_item"><code class="xref docutils literal notranslate"><span class="pre">slice_item</span></code></a> ("," <a class="reference internal" href="#grammar-token-python-grammar-slice_item"><code class="xref docutils literal notranslate"><span class="pre">slice_item</span></code></a>)* [","]
|
||
<strong id="grammar-token-python-grammar-slice_item">slice_item</strong> ::= <a class="reference internal" href="#grammar-token-python-grammar-expression"><code class="xref docutils literal notranslate"><span class="pre">expression</span></code></a> | <a class="reference internal" href="#grammar-token-python-grammar-proper_slice"><code class="xref docutils literal notranslate"><span class="pre">proper_slice</span></code></a>
|
||
<strong id="grammar-token-python-grammar-proper_slice">proper_slice</strong> ::= [<a class="reference internal" href="#grammar-token-python-grammar-lower_bound"><code class="xref docutils literal notranslate"><span class="pre">lower_bound</span></code></a>] ":" [<a class="reference internal" href="#grammar-token-python-grammar-upper_bound"><code class="xref docutils literal notranslate"><span class="pre">upper_bound</span></code></a>] [ ":" [<a class="reference internal" href="#grammar-token-python-grammar-stride"><code class="xref docutils literal notranslate"><span class="pre">stride</span></code></a>] ]
|
||
<strong id="grammar-token-python-grammar-lower_bound">lower_bound</strong> ::= <a class="reference internal" href="#grammar-token-python-grammar-expression"><code class="xref docutils literal notranslate"><span class="pre">expression</span></code></a>
|
||
<strong id="grammar-token-python-grammar-upper_bound">upper_bound</strong> ::= <a class="reference internal" href="#grammar-token-python-grammar-expression"><code class="xref docutils literal notranslate"><span class="pre">expression</span></code></a>
|
||
<strong id="grammar-token-python-grammar-stride">stride</strong> ::= <a class="reference internal" href="#grammar-token-python-grammar-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-47">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 <a class="reference internal" href="../library/functions.html#slice.start" title="slice.start"><code class="xref py py-attr docutils literal notranslate"><span class="pre">start</span></code></a>,
|
||
<a class="reference internal" href="../library/functions.html#slice.stop" title="slice.stop"><code class="xref py py-attr docutils literal notranslate"><span class="pre">stop</span></code></a> and <a class="reference internal" href="../library/functions.html#slice.step" title="slice.step"><code class="xref py py-attr docutils literal notranslate"><span class="pre">step</span></code></a> 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>
|
||
</section>
|
||
<section id="calls">
|
||
<span id="index-48"></span><span id="id9"></span><h3><span class="section-number">6.3.4. </span>Calls<a class="headerlink" href="#calls" title="Link to this heading">¶</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-python-grammar-call">call</strong> ::= <a class="reference internal" href="#grammar-token-python-grammar-primary"><code class="xref docutils literal notranslate"><span class="pre">primary</span></code></a> "(" [<a class="reference internal" href="#grammar-token-python-grammar-argument_list"><code class="xref docutils literal notranslate"><span class="pre">argument_list</span></code></a> [","] | <a class="reference internal" href="#grammar-token-python-grammar-comprehension"><code class="xref docutils literal notranslate"><span class="pre">comprehension</span></code></a>] ")"
|
||
<strong id="grammar-token-python-grammar-argument_list">argument_list</strong> ::= <a class="reference internal" href="#grammar-token-python-grammar-positional_arguments"><code class="xref docutils literal notranslate"><span class="pre">positional_arguments</span></code></a> ["," <a class="reference internal" href="#grammar-token-python-grammar-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-python-grammar-keywords_arguments"><code class="xref docutils literal notranslate"><span class="pre">keywords_arguments</span></code></a>]
|
||
| <a class="reference internal" href="#grammar-token-python-grammar-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-python-grammar-keywords_arguments"><code class="xref docutils literal notranslate"><span class="pre">keywords_arguments</span></code></a>]
|
||
| <a class="reference internal" href="#grammar-token-python-grammar-keywords_arguments"><code class="xref docutils literal notranslate"><span class="pre">keywords_arguments</span></code></a>
|
||
<strong id="grammar-token-python-grammar-positional_arguments">positional_arguments</strong> ::= positional_item ("," positional_item)*
|
||
<strong id="grammar-token-python-grammar-positional_item">positional_item</strong> ::= <a class="reference internal" href="#grammar-token-python-grammar-assignment_expression"><code class="xref docutils literal notranslate"><span class="pre">assignment_expression</span></code></a> | "*" <a class="reference internal" href="#grammar-token-python-grammar-expression"><code class="xref docutils literal notranslate"><span class="pre">expression</span></code></a>
|
||
<strong id="grammar-token-python-grammar-starred_and_keywords">starred_and_keywords</strong> ::= ("*" <a class="reference internal" href="#grammar-token-python-grammar-expression"><code class="xref docutils literal notranslate"><span class="pre">expression</span></code></a> | <a class="reference internal" href="#grammar-token-python-grammar-keyword_item"><code class="xref docutils literal notranslate"><span class="pre">keyword_item</span></code></a>)
|
||
("," "*" <a class="reference internal" href="#grammar-token-python-grammar-expression"><code class="xref docutils literal notranslate"><span class="pre">expression</span></code></a> | "," <a class="reference internal" href="#grammar-token-python-grammar-keyword_item"><code class="xref docutils literal notranslate"><span class="pre">keyword_item</span></code></a>)*
|
||
<strong id="grammar-token-python-grammar-keywords_arguments">keywords_arguments</strong> ::= (<a class="reference internal" href="#grammar-token-python-grammar-keyword_item"><code class="xref docutils literal notranslate"><span class="pre">keyword_item</span></code></a> | "**" <a class="reference internal" href="#grammar-token-python-grammar-expression"><code class="xref docutils literal notranslate"><span class="pre">expression</span></code></a>)
|
||
("," <a class="reference internal" href="#grammar-token-python-grammar-keyword_item"><code class="xref docutils literal notranslate"><span class="pre">keyword_item</span></code></a> | "," "**" <a class="reference internal" href="#grammar-token-python-grammar-expression"><code class="xref docutils literal notranslate"><span class="pre">expression</span></code></a>)*
|
||
<strong id="grammar-token-python-grammar-keyword_item">keyword_item</strong> ::= <a class="reference internal" href="lexical_analysis.html#grammar-token-python-grammar-identifier"><code class="xref docutils literal notranslate"><span class="pre">identifier</span></code></a> "=" <a class="reference internal" href="#grammar-token-python-grammar-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-49">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
|
||
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-50">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="w"> </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 often arise.</p>
|
||
<p id="index-51">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 parameter matching a key has already been
|
||
given a value (by 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>When <code class="docutils literal notranslate"><span class="pre">**expression</span></code> is used, each key in this mapping must be
|
||
a string.
|
||
Each value from the mapping is assigned to the first formal parameter
|
||
eligible for keyword assignment whose name is equal to the key.
|
||
A key need not be a Python identifier (e.g. <code class="docutils literal notranslate"><span class="pre">"max-temp</span> <span class="pre">°F"</span></code> is acceptable,
|
||
although it will not match any formal parameter that could be declared).
|
||
If there is no match to a formal parameter
|
||
the key-value pair is collected by the <code class="docutils literal notranslate"><span class="pre">**</span></code> parameter, if there is one,
|
||
or if there is not, 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-52"></span><a class="pep reference external" href="https://peps.python.org/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-53">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. If execution reaches the end of the code block without
|
||
executing 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, the return value is <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
|
||
</dd>
|
||
<dt>a built-in function or method:</dt><dd><p id="index-54">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-55">A new instance of that class is returned.</p>
|
||
</dd>
|
||
<dt>a class instance method:</dt><dd><p id="index-56">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-57">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>
|
||
</section>
|
||
</section>
|
||
<section id="await-expression">
|
||
<span id="await"></span><span id="index-58"></span><h2><span class="section-number">6.4. </span>Await expression<a class="headerlink" href="#await-expression" title="Link to this heading">¶</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-python-grammar-await_expr">await_expr</strong> ::= "await" <a class="reference internal" href="#grammar-token-python-grammar-primary"><code class="xref docutils literal notranslate"><span class="pre">primary</span></code></a>
|
||
</pre>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">Added in version 3.5.</span></p>
|
||
</div>
|
||
</section>
|
||
<section id="the-power-operator">
|
||
<span id="power"></span><h2><span class="section-number">6.5. </span>The power operator<a class="headerlink" href="#the-power-operator" title="Link to this heading">¶</a></h2>
|
||
<p id="index-59">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-python-grammar-power">power</strong> ::= (<a class="reference internal" href="#grammar-token-python-grammar-await_expr"><code class="xref docutils literal notranslate"><span class="pre">await_expr</span></code></a> | <a class="reference internal" href="#grammar-token-python-grammar-primary"><code class="xref docutils literal notranslate"><span class="pre">primary</span></code></a>) ["**" <a class="reference internal" href="#grammar-token-python-grammar-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>
|
||
<p>This operation can be customized using the special <a class="reference internal" href="datamodel.html#object.__pow__" title="object.__pow__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__pow__()</span></code></a> and
|
||
<a class="reference internal" href="datamodel.html#object.__rpow__" title="object.__rpow__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__rpow__()</span></code></a> methods.</p>
|
||
</section>
|
||
<section id="unary-arithmetic-and-bitwise-operations">
|
||
<span id="unary"></span><h2><span class="section-number">6.6. </span>Unary arithmetic and bitwise operations<a class="headerlink" href="#unary-arithmetic-and-bitwise-operations" title="Link to this heading">¶</a></h2>
|
||
<p id="index-60">All unary arithmetic and bitwise operations have the same priority:</p>
|
||
<pre>
|
||
<strong id="grammar-token-python-grammar-u_expr">u_expr</strong> ::= <a class="reference internal" href="#grammar-token-python-grammar-power"><code class="xref docutils literal notranslate"><span class="pre">power</span></code></a> | "-" <a class="reference internal" href="#grammar-token-python-grammar-u_expr"><code class="xref docutils literal notranslate"><span class="pre">u_expr</span></code></a> | "+" <a class="reference internal" href="#grammar-token-python-grammar-u_expr"><code class="xref docutils literal notranslate"><span class="pre">u_expr</span></code></a> | "~" <a class="reference internal" href="#grammar-token-python-grammar-u_expr"><code class="xref docutils literal notranslate"><span class="pre">u_expr</span></code></a>
|
||
</pre>
|
||
<p id="index-61">The unary <code class="docutils literal notranslate"><span class="pre">-</span></code> (minus) operator yields the negation of its numeric argument; the
|
||
operation can be overridden with the <a class="reference internal" href="datamodel.html#object.__neg__" title="object.__neg__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__neg__()</span></code></a> special method.</p>
|
||
<p id="index-62">The unary <code class="docutils literal notranslate"><span class="pre">+</span></code> (plus) operator yields its numeric argument unchanged; the
|
||
operation can be overridden with the <a class="reference internal" href="datamodel.html#object.__pos__" title="object.__pos__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__pos__()</span></code></a> special method.</p>
|
||
<p id="index-63">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 or to custom objects that override the
|
||
<a class="reference internal" href="datamodel.html#object.__invert__" title="object.__invert__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__invert__()</span></code></a> special method.</p>
|
||
<p id="index-64">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>
|
||
</section>
|
||
<section id="binary-arithmetic-operations">
|
||
<span id="binary"></span><h2><span class="section-number">6.7. </span>Binary arithmetic operations<a class="headerlink" href="#binary-arithmetic-operations" title="Link to this heading">¶</a></h2>
|
||
<p id="index-65">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-python-grammar-m_expr">m_expr</strong> ::= <a class="reference internal" href="#grammar-token-python-grammar-u_expr"><code class="xref docutils literal notranslate"><span class="pre">u_expr</span></code></a> | <a class="reference internal" href="#grammar-token-python-grammar-m_expr"><code class="xref docutils literal notranslate"><span class="pre">m_expr</span></code></a> "*" <a class="reference internal" href="#grammar-token-python-grammar-u_expr"><code class="xref docutils literal notranslate"><span class="pre">u_expr</span></code></a> | <a class="reference internal" href="#grammar-token-python-grammar-m_expr"><code class="xref docutils literal notranslate"><span class="pre">m_expr</span></code></a> "@" <a class="reference internal" href="#grammar-token-python-grammar-m_expr"><code class="xref docutils literal notranslate"><span class="pre">m_expr</span></code></a> |
|
||
<a class="reference internal" href="#grammar-token-python-grammar-m_expr"><code class="xref docutils literal notranslate"><span class="pre">m_expr</span></code></a> "//" <a class="reference internal" href="#grammar-token-python-grammar-u_expr"><code class="xref docutils literal notranslate"><span class="pre">u_expr</span></code></a> | <a class="reference internal" href="#grammar-token-python-grammar-m_expr"><code class="xref docutils literal notranslate"><span class="pre">m_expr</span></code></a> "/" <a class="reference internal" href="#grammar-token-python-grammar-u_expr"><code class="xref docutils literal notranslate"><span class="pre">u_expr</span></code></a> |
|
||
<a class="reference internal" href="#grammar-token-python-grammar-m_expr"><code class="xref docutils literal notranslate"><span class="pre">m_expr</span></code></a> "%" <a class="reference internal" href="#grammar-token-python-grammar-u_expr"><code class="xref docutils literal notranslate"><span class="pre">u_expr</span></code></a>
|
||
<strong id="grammar-token-python-grammar-a_expr">a_expr</strong> ::= <a class="reference internal" href="#grammar-token-python-grammar-m_expr"><code class="xref docutils literal notranslate"><span class="pre">m_expr</span></code></a> | <a class="reference internal" href="#grammar-token-python-grammar-a_expr"><code class="xref docutils literal notranslate"><span class="pre">a_expr</span></code></a> "+" <a class="reference internal" href="#grammar-token-python-grammar-m_expr"><code class="xref docutils literal notranslate"><span class="pre">m_expr</span></code></a> | <a class="reference internal" href="#grammar-token-python-grammar-a_expr"><code class="xref docutils literal notranslate"><span class="pre">a_expr</span></code></a> "-" <a class="reference internal" href="#grammar-token-python-grammar-m_expr"><code class="xref docutils literal notranslate"><span class="pre">m_expr</span></code></a>
|
||
</pre>
|
||
<p id="index-66">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>This operation can be customized using the special <a class="reference internal" href="datamodel.html#object.__mul__" title="object.__mul__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__mul__()</span></code></a> and
|
||
<a class="reference internal" href="datamodel.html#object.__rmul__" title="object.__rmul__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__rmul__()</span></code></a> methods.</p>
|
||
<p id="index-67">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>
|
||
<p>This operation can be customized using the special <a class="reference internal" href="datamodel.html#object.__matmul__" title="object.__matmul__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__matmul__()</span></code></a> and
|
||
<a class="reference internal" href="datamodel.html#object.__rmatmul__" title="object.__rmatmul__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__rmatmul__()</span></code></a> methods.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">Added in version 3.5.</span></p>
|
||
</div>
|
||
<p id="index-68">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>The division operation can be customized using the special <a class="reference internal" href="datamodel.html#object.__truediv__" title="object.__truediv__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__truediv__()</span></code></a>
|
||
and <a class="reference internal" href="datamodel.html#object.__rtruediv__" title="object.__rtruediv__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__rtruediv__()</span></code></a> methods.
|
||
The floor division operation can be customized using the special
|
||
<a class="reference internal" href="datamodel.html#object.__floordiv__" title="object.__floordiv__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__floordiv__()</span></code></a> and <a class="reference internal" href="datamodel.html#object.__rfloordiv__" title="object.__rfloordiv__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__rfloordiv__()</span></code></a> methods.</p>
|
||
<p id="index-69">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="#id19" id="id10" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></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="#id20" id="id11" role="doc-noteref"><span class="fn-bracket">[</span>2<span class="fn-bracket">]</span></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 <em>modulo</em> operation can be customized using the special <a class="reference internal" href="datamodel.html#object.__mod__" title="object.__mod__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__mod__()</span></code></a>
|
||
and <a class="reference internal" href="datamodel.html#object.__rmod__" title="object.__rmod__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__rmod__()</span></code></a> methods.</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-70">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>This operation can be customized using the special <a class="reference internal" href="datamodel.html#object.__add__" title="object.__add__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__add__()</span></code></a> and
|
||
<a class="reference internal" href="datamodel.html#object.__radd__" title="object.__radd__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__radd__()</span></code></a> methods.</p>
|
||
<p id="index-71">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>
|
||
<p>This operation can be customized using the special <a class="reference internal" href="datamodel.html#object.__sub__" title="object.__sub__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__sub__()</span></code></a> and
|
||
<a class="reference internal" href="datamodel.html#object.__rsub__" title="object.__rsub__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__rsub__()</span></code></a> methods.</p>
|
||
</section>
|
||
<section id="shifting-operations">
|
||
<span id="shifting"></span><h2><span class="section-number">6.8. </span>Shifting operations<a class="headerlink" href="#shifting-operations" title="Link to this heading">¶</a></h2>
|
||
<p id="index-72">The shifting operations have lower priority than the arithmetic operations:</p>
|
||
<pre>
|
||
<strong id="grammar-token-python-grammar-shift_expr">shift_expr</strong> ::= <a class="reference internal" href="#grammar-token-python-grammar-a_expr"><code class="xref docutils literal notranslate"><span class="pre">a_expr</span></code></a> | <a class="reference internal" href="#grammar-token-python-grammar-shift_expr"><code class="xref docutils literal notranslate"><span class="pre">shift_expr</span></code></a> ("<<" | ">>") <a class="reference internal" href="#grammar-token-python-grammar-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>The left shift operation can be customized using the special <a class="reference internal" href="datamodel.html#object.__lshift__" title="object.__lshift__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__lshift__()</span></code></a>
|
||
and <a class="reference internal" href="datamodel.html#object.__rlshift__" title="object.__rlshift__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__rlshift__()</span></code></a> methods.
|
||
The right shift operation can be customized using the special <a class="reference internal" href="datamodel.html#object.__rshift__" title="object.__rshift__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__rshift__()</span></code></a>
|
||
and <a class="reference internal" href="datamodel.html#object.__rrshift__" title="object.__rrshift__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__rrshift__()</span></code></a> methods.</p>
|
||
<p id="index-73">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>
|
||
</section>
|
||
<section id="binary-bitwise-operations">
|
||
<span id="bitwise"></span><h2><span class="section-number">6.9. </span>Binary bitwise operations<a class="headerlink" href="#binary-bitwise-operations" title="Link to this heading">¶</a></h2>
|
||
<p id="index-74">Each of the three bitwise operations has a different priority level:</p>
|
||
<pre>
|
||
<strong id="grammar-token-python-grammar-and_expr">and_expr</strong> ::= <a class="reference internal" href="#grammar-token-python-grammar-shift_expr"><code class="xref docutils literal notranslate"><span class="pre">shift_expr</span></code></a> | <a class="reference internal" href="#grammar-token-python-grammar-and_expr"><code class="xref docutils literal notranslate"><span class="pre">and_expr</span></code></a> "&" <a class="reference internal" href="#grammar-token-python-grammar-shift_expr"><code class="xref docutils literal notranslate"><span class="pre">shift_expr</span></code></a>
|
||
<strong id="grammar-token-python-grammar-xor_expr">xor_expr</strong> ::= <a class="reference internal" href="#grammar-token-python-grammar-and_expr"><code class="xref docutils literal notranslate"><span class="pre">and_expr</span></code></a> | <a class="reference internal" href="#grammar-token-python-grammar-xor_expr"><code class="xref docutils literal notranslate"><span class="pre">xor_expr</span></code></a> "^" <a class="reference internal" href="#grammar-token-python-grammar-and_expr"><code class="xref docutils literal notranslate"><span class="pre">and_expr</span></code></a>
|
||
<strong id="grammar-token-python-grammar-or_expr">or_expr</strong> ::= <a class="reference internal" href="#grammar-token-python-grammar-xor_expr"><code class="xref docutils literal notranslate"><span class="pre">xor_expr</span></code></a> | <a class="reference internal" href="#grammar-token-python-grammar-or_expr"><code class="xref docutils literal notranslate"><span class="pre">or_expr</span></code></a> "|" <a class="reference internal" href="#grammar-token-python-grammar-xor_expr"><code class="xref docutils literal notranslate"><span class="pre">xor_expr</span></code></a>
|
||
</pre>
|
||
<p id="index-75">The <code class="docutils literal notranslate"><span class="pre">&</span></code> operator yields the bitwise AND of its arguments, which must be
|
||
integers or one of them must be a custom object overriding <a class="reference internal" href="datamodel.html#object.__and__" title="object.__and__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__and__()</span></code></a> or
|
||
<a class="reference internal" href="datamodel.html#object.__rand__" title="object.__rand__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__rand__()</span></code></a> special methods.</p>
|
||
<p id="index-76">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 or one of them must be a custom object overriding <a class="reference internal" href="datamodel.html#object.__xor__" title="object.__xor__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__xor__()</span></code></a> or
|
||
<a class="reference internal" href="datamodel.html#object.__rxor__" title="object.__rxor__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__rxor__()</span></code></a> special methods.</p>
|
||
<p id="index-77">The <code class="docutils literal notranslate"><span class="pre">|</span></code> operator yields the bitwise (inclusive) OR of its arguments, which
|
||
must be integers or one of them must be a custom object overriding <a class="reference internal" href="datamodel.html#object.__or__" title="object.__or__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__or__()</span></code></a> or
|
||
<a class="reference internal" href="datamodel.html#object.__ror__" title="object.__ror__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__ror__()</span></code></a> special methods.</p>
|
||
</section>
|
||
<section id="comparisons">
|
||
<span id="id12"></span><h2><span class="section-number">6.10. </span>Comparisons<a class="headerlink" href="#comparisons" title="Link to this heading">¶</a></h2>
|
||
<p id="index-78">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-python-grammar-comparison">comparison</strong> ::= <a class="reference internal" href="#grammar-token-python-grammar-or_expr"><code class="xref docutils literal notranslate"><span class="pre">or_expr</span></code></a> (<a class="reference internal" href="#grammar-token-python-grammar-comp_operator"><code class="xref docutils literal notranslate"><span class="pre">comp_operator</span></code></a> <a class="reference internal" href="#grammar-token-python-grammar-or_expr"><code class="xref docutils literal notranslate"><span class="pre">or_expr</span></code></a>)*
|
||
<strong id="grammar-token-python-grammar-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>. Custom
|
||
<em class="dfn">rich comparison methods</em> may return non-boolean values. In this case
|
||
Python will call <a class="reference internal" href="../library/functions.html#bool" title="bool"><code class="xref py py-func docutils literal notranslate"><span class="pre">bool()</span></code></a> on such value in boolean contexts.</p>
|
||
<p id="index-79">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>
|
||
<section id="value-comparisons">
|
||
<span id="expressions-value-comparisons"></span><h3><span class="section-number">6.10.1. </span>Value comparisons<a class="headerlink" href="#value-comparisons" title="Link to this heading">¶</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> and
|
||
<code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">==</span> <span class="pre">x</span></code> are all false, while <code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">!=</span> <span class="pre">x</span></code> is true. This behavior is
|
||
compliant with IEEE 754.</p>
|
||
</li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">None</span></code> and <a class="reference internal" href="../library/constants.html#NotImplemented" title="NotImplemented"><code class="xref py py-data docutils literal notranslate"><span class="pre">NotImplemented</span></code></a> are singletons. <span class="target" id="index-80"></span><a class="pep reference external" href="https://peps.python.org/pep-0008/"><strong>PEP 8</strong></a> advises that
|
||
comparisons for singletons should always be done with <code class="docutils literal notranslate"><span class="pre">is</span></code> or <code class="docutils literal notranslate"><span class="pre">is</span> <span class="pre">not</span></code>,
|
||
never the equality operators.</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="#id21" id="id13" role="doc-noteref"><span class="fn-bracket">[</span>3<span class="fn-bracket">]</span></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. The built-in containers typically assume identical objects are
|
||
equal to themselves. That lets them bypass equality tests for identical
|
||
objects to improve performance and to maintain their internal invariants.</p>
|
||
<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 <code class="docutils literal notranslate"><span class="pre">(key,</span> <span class="pre">value)</span></code> 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>
|
||
</section>
|
||
<section id="membership-test-operations">
|
||
<span id="membership-test-details"></span><span id="not-in"></span><span id="in"></span><h3><span class="section-number">6.10.2. </span>Membership test operations<a class="headerlink" href="#membership-test-operations" title="Link to this heading">¶</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-81">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>
|
||
</section>
|
||
<section id="is-not">
|
||
<span id="is"></span><span id="index-82"></span><span id="identity-comparisons"></span><h3><span class="section-number">6.10.3. </span>Identity comparisons<a class="headerlink" href="#is-not" title="Link to this heading">¶</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="#id22" id="id14" role="doc-noteref"><span class="fn-bracket">[</span>4<span class="fn-bracket">]</span></a></p>
|
||
</section>
|
||
</section>
|
||
<section id="boolean-operations">
|
||
<span id="not"></span><span id="or"></span><span id="and"></span><span id="booleans"></span><h2><span class="section-number">6.11. </span>Boolean operations<a class="headerlink" href="#boolean-operations" title="Link to this heading">¶</a></h2>
|
||
<pre id="index-83">
|
||
<strong id="grammar-token-python-grammar-or_test">or_test</strong> ::= <a class="reference internal" href="#grammar-token-python-grammar-and_test"><code class="xref docutils literal notranslate"><span class="pre">and_test</span></code></a> | <a class="reference internal" href="#grammar-token-python-grammar-or_test"><code class="xref docutils literal notranslate"><span class="pre">or_test</span></code></a> "or" <a class="reference internal" href="#grammar-token-python-grammar-and_test"><code class="xref docutils literal notranslate"><span class="pre">and_test</span></code></a>
|
||
<strong id="grammar-token-python-grammar-and_test">and_test</strong> ::= <a class="reference internal" href="#grammar-token-python-grammar-not_test"><code class="xref docutils literal notranslate"><span class="pre">not_test</span></code></a> | <a class="reference internal" href="#grammar-token-python-grammar-and_test"><code class="xref docutils literal notranslate"><span class="pre">and_test</span></code></a> "and" <a class="reference internal" href="#grammar-token-python-grammar-not_test"><code class="xref docutils literal notranslate"><span class="pre">not_test</span></code></a>
|
||
<strong id="grammar-token-python-grammar-not_test">not_test</strong> ::= <a class="reference internal" href="#grammar-token-python-grammar-comparison"><code class="xref docutils literal notranslate"><span class="pre">comparison</span></code></a> | "not" <a class="reference internal" href="#grammar-token-python-grammar-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-84">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-85">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-86">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>
|
||
</section>
|
||
<section id="assignment-expressions">
|
||
<span id="index-87"></span><span id="id15"></span><h2><span class="section-number">6.12. </span>Assignment expressions<a class="headerlink" href="#assignment-expressions" title="Link to this heading">¶</a></h2>
|
||
<pre>
|
||
<strong id="grammar-token-python-grammar-assignment_expression">assignment_expression</strong> ::= [<a class="reference internal" href="lexical_analysis.html#grammar-token-python-grammar-identifier"><code class="xref docutils literal notranslate"><span class="pre">identifier</span></code></a> ":="] <a class="reference internal" href="#grammar-token-python-grammar-expression"><code class="xref docutils literal notranslate"><span class="pre">expression</span></code></a>
|
||
</pre>
|
||
<p>An assignment expression (sometimes also called a “named expression” or
|
||
“walrus”) assigns an <a class="reference internal" href="#grammar-token-python-grammar-expression"><code class="xref std std-token docutils literal notranslate"><span class="pre">expression</span></code></a> to an
|
||
<a class="reference internal" href="lexical_analysis.html#grammar-token-python-grammar-identifier"><code class="xref std std-token docutils literal notranslate"><span class="pre">identifier</span></code></a>, while also returning the value of the
|
||
<a class="reference internal" href="#grammar-token-python-grammar-expression"><code class="xref std std-token docutils literal notranslate"><span class="pre">expression</span></code></a>.</p>
|
||
<p>One common use case is when handling matched regular expressions:</p>
|
||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="n">matching</span> <span class="o">:=</span> <span class="n">pattern</span><span class="o">.</span><span class="n">search</span><span class="p">(</span><span class="n">data</span><span class="p">):</span>
|
||
<span class="n">do_something</span><span class="p">(</span><span class="n">matching</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Or, when processing a file stream in chunks:</p>
|
||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">while</span> <span class="n">chunk</span> <span class="o">:=</span> <span class="n">file</span><span class="o">.</span><span class="n">read</span><span class="p">(</span><span class="mi">9000</span><span class="p">):</span>
|
||
<span class="n">process</span><span class="p">(</span><span class="n">chunk</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Assignment expressions must be surrounded by parentheses when
|
||
used as expression statements and when used as sub-expressions in
|
||
slicing, conditional, lambda,
|
||
keyword-argument, and comprehension-if expressions and
|
||
in <code class="docutils literal notranslate"><span class="pre">assert</span></code>, <code class="docutils literal notranslate"><span class="pre">with</span></code>, and <code class="docutils literal notranslate"><span class="pre">assignment</span></code> statements.
|
||
In all other places where they can be used, parentheses are not required,
|
||
including in <code class="docutils literal notranslate"><span class="pre">if</span></code> and <code class="docutils literal notranslate"><span class="pre">while</span></code> statements.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">Added in version 3.8: </span>See <span class="target" id="index-88"></span><a class="pep reference external" href="https://peps.python.org/pep-0572/"><strong>PEP 572</strong></a> for more details about assignment expressions.</p>
|
||
</div>
|
||
</section>
|
||
<section id="conditional-expressions">
|
||
<span id="if-expr"></span><h2><span class="section-number">6.13. </span>Conditional expressions<a class="headerlink" href="#conditional-expressions" title="Link to this heading">¶</a></h2>
|
||
<pre id="index-89">
|
||
<strong id="grammar-token-python-grammar-conditional_expression">conditional_expression</strong> ::= <a class="reference internal" href="#grammar-token-python-grammar-or_test"><code class="xref docutils literal notranslate"><span class="pre">or_test</span></code></a> ["if" <a class="reference internal" href="#grammar-token-python-grammar-or_test"><code class="xref docutils literal notranslate"><span class="pre">or_test</span></code></a> "else" <a class="reference internal" href="#grammar-token-python-grammar-expression"><code class="xref docutils literal notranslate"><span class="pre">expression</span></code></a>]
|
||
<strong id="grammar-token-python-grammar-expression">expression</strong> ::= <a class="reference internal" href="#grammar-token-python-grammar-conditional_expression"><code class="xref docutils literal notranslate"><span class="pre">conditional_expression</span></code></a> | <a class="reference internal" href="#grammar-token-python-grammar-lambda_expr"><code class="xref docutils literal notranslate"><span class="pre">lambda_expr</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-90"></span><a class="pep reference external" href="https://peps.python.org/pep-0308/"><strong>PEP 308</strong></a> for more details about conditional expressions.</p>
|
||
</section>
|
||
<section id="lambda">
|
||
<span id="lambdas"></span><span id="id16"></span><h2><span class="section-number">6.14. </span>Lambdas<a class="headerlink" href="#lambda" title="Link to this heading">¶</a></h2>
|
||
<pre id="index-91">
|
||
<strong id="grammar-token-python-grammar-lambda_expr">lambda_expr</strong> ::= "lambda" [<a class="reference internal" href="compound_stmts.html#grammar-token-python-grammar-parameter_list"><code class="xref docutils literal notranslate"><span class="pre">parameter_list</span></code></a>] ":" <a class="reference internal" href="#grammar-token-python-grammar-expression"><code class="xref docutils literal notranslate"><span class="pre">expression</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>
|
||
</section>
|
||
<section id="expression-lists">
|
||
<span id="exprlists"></span><h2><span class="section-number">6.15. </span>Expression lists<a class="headerlink" href="#expression-lists" title="Link to this heading">¶</a></h2>
|
||
<pre id="index-92">
|
||
<strong id="grammar-token-python-grammar-starred_expression">starred_expression</strong> ::= ["*"] <a class="reference internal" href="#grammar-token-python-grammar-or_expr"><code class="xref docutils literal notranslate"><span class="pre">or_expr</span></code></a>
|
||
<strong id="grammar-token-python-grammar-flexible_expression">flexible_expression</strong> ::= <a class="reference internal" href="#grammar-token-python-grammar-assignment_expression"><code class="xref docutils literal notranslate"><span class="pre">assignment_expression</span></code></a> | <a class="reference internal" href="#grammar-token-python-grammar-starred_expression"><code class="xref docutils literal notranslate"><span class="pre">starred_expression</span></code></a>
|
||
<strong id="grammar-token-python-grammar-flexible_expression_list">flexible_expression_list</strong> ::= <a class="reference internal" href="#grammar-token-python-grammar-flexible_expression"><code class="xref docutils literal notranslate"><span class="pre">flexible_expression</span></code></a> ("," <a class="reference internal" href="#grammar-token-python-grammar-flexible_expression"><code class="xref docutils literal notranslate"><span class="pre">flexible_expression</span></code></a>)* [","]
|
||
<strong id="grammar-token-python-grammar-starred_expression_list">starred_expression_list</strong> ::= <a class="reference internal" href="#grammar-token-python-grammar-starred_expression"><code class="xref docutils literal notranslate"><span class="pre">starred_expression</span></code></a> ("," <a class="reference internal" href="#grammar-token-python-grammar-starred_expression"><code class="xref docutils literal notranslate"><span class="pre">starred_expression</span></code></a>)* [","]
|
||
<strong id="grammar-token-python-grammar-expression_list">expression_list</strong> ::= <a class="reference internal" href="#grammar-token-python-grammar-expression"><code class="xref docutils literal notranslate"><span class="pre">expression</span></code></a> ("," <a class="reference internal" href="#grammar-token-python-grammar-expression"><code class="xref docutils literal notranslate"><span class="pre">expression</span></code></a>)* [","]
|
||
<strong id="grammar-token-python-grammar-yield_list">yield_list</strong> ::= <a class="reference internal" href="#grammar-token-python-grammar-expression_list"><code class="xref docutils literal notranslate"><span class="pre">expression_list</span></code></a> | <a class="reference internal" href="#grammar-token-python-grammar-starred_expression"><code class="xref docutils literal notranslate"><span class="pre">starred_expression</span></code></a> "," [<a class="reference internal" href="#grammar-token-python-grammar-starred_expression_list"><code class="xref docutils literal notranslate"><span class="pre">starred_expression_list</span></code></a>]
|
||
</pre>
|
||
<p id="index-93">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-94">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">Added in version 3.5: </span>Iterable unpacking in expression lists, originally proposed by <span class="target" id="index-95"></span><a class="pep reference external" href="https://peps.python.org/pep-0448/"><strong>PEP 448</strong></a>.</p>
|
||
</div>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">Added in version 3.11: </span>Any item in an expression list may be starred. See <span class="target" id="index-96"></span><a class="pep reference external" href="https://peps.python.org/pep-0646/"><strong>PEP 646</strong></a>.</p>
|
||
</div>
|
||
<p id="index-97">A trailing comma is required only to create a one-item tuple,
|
||
such as <code class="docutils literal notranslate"><span class="pre">1,</span></code>; 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>
|
||
</section>
|
||
<section id="evaluation-order">
|
||
<span id="evalorder"></span><h2><span class="section-number">6.16. </span>Evaluation order<a class="headerlink" href="#evaluation-order" title="Link to this heading">¶</a></h2>
|
||
<p id="index-98">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>
|
||
</section>
|
||
<section id="operator-precedence">
|
||
<span id="operator-summary"></span><h2><span class="section-number">6.17. </span>Operator precedence<a class="headerlink" href="#operator-precedence" title="Link to this heading">¶</a></h2>
|
||
<p id="index-99">The following table summarizes the operator precedence in Python, from highest
|
||
precedence (most binding) to lowest precedence (least 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 and conditional expressions, which group 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-default">
|
||
<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><code class="docutils literal notranslate"><span class="pre">(expressions...)</span></code>,</p>
|
||
<p><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 parenthesized
|
||
expression,
|
||
list display,
|
||
dictionary display,
|
||
set display</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><a class="reference internal" href="#await"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">await</span> <span class="pre">x</span></code></a></p></td>
|
||
<td><p>Await expression</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="#id23" id="id17" role="doc-noteref"><span class="fn-bracket">[</span>5<span class="fn-bracket">]</span></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>, <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="#id24" id="id18" role="doc-noteref"><span class="fn-bracket">[</span>6<span class="fn-bracket">]</span></a></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></p></td>
|
||
<td><p>Shifts</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></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 OR</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><a class="reference internal" href="#not"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">not</span> <span class="pre">x</span></code></a></p></td>
|
||
<td><p>Boolean NOT</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="#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="#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="#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><code class="docutils literal notranslate"><span class="pre">:=</span></code></p></td>
|
||
<td><p>Assignment expression</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<p class="rubric">Footnotes</p>
|
||
<aside class="footnote-list brackets">
|
||
<aside class="footnote brackets" id="id19" role="doc-footnote">
|
||
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id10">1</a><span class="fn-bracket">]</span></span>
|
||
<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>
|
||
</aside>
|
||
<aside class="footnote brackets" id="id20" role="doc-footnote">
|
||
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id11">2</a><span class="fn-bracket">]</span></span>
|
||
<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>
|
||
</aside>
|
||
<aside class="footnote brackets" id="id21" role="doc-footnote">
|
||
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id13">3</a><span class="fn-bracket">]</span></span>
|
||
<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>
|
||
</aside>
|
||
<aside class="footnote brackets" id="id22" role="doc-footnote">
|
||
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id14">4</a><span class="fn-bracket">]</span></span>
|
||
<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>
|
||
</aside>
|
||
<aside class="footnote brackets" id="id23" role="doc-footnote">
|
||
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id17">5</a><span class="fn-bracket">]</span></span>
|
||
<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>
|
||
</aside>
|
||
<aside class="footnote brackets" id="id24" role="doc-footnote">
|
||
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id18">6</a><span class="fn-bracket">]</span></span>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">%</span></code> operator is also used for string formatting; the same
|
||
precedence applies.</p>
|
||
</aside>
|
||
</aside>
|
||
</section>
|
||
</section>
|
||
|
||
|
||
<div class="clearer"></div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sphinxsidebar" role="navigation" aria-label="Main">
|
||
<div class="sphinxsidebarwrapper">
|
||
<div>
|
||
<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><ul>
|
||
<li><a class="reference internal" href="#index-5">6.2.1.1. Private name mangling</a></li>
|
||
</ul>
|
||
</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="#assignment-expressions">6.12. Assignment expressions</a></li>
|
||
<li><a class="reference internal" href="#conditional-expressions">6.13. Conditional expressions</a></li>
|
||
<li><a class="reference internal" href="#lambda">6.14. Lambdas</a></li>
|
||
<li><a class="reference internal" href="#expression-lists">6.15. Expression lists</a></li>
|
||
<li><a class="reference internal" href="#evaluation-order">6.16. Evaluation order</a></li>
|
||
<li><a class="reference internal" href="#operator-precedence">6.17. Operator precedence</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
</div>
|
||
<div>
|
||
<h4>Previous topic</h4>
|
||
<p class="topless"><a href="import.html"
|
||
title="previous chapter"><span class="section-number">5. </span>The import system</a></p>
|
||
</div>
|
||
<div>
|
||
<h4>Next topic</h4>
|
||
<p class="topless"><a href="simple_stmts.html"
|
||
title="next chapter"><span class="section-number">7. </span>Simple statements</a></p>
|
||
</div>
|
||
<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/main/Doc/reference/expressions.rst"
|
||
rel="nofollow">Show Source
|
||
</a>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
<div id="sidebarbutton" title="Collapse sidebar">
|
||
<span>«</span>
|
||
</div>
|
||
|
||
</div>
|
||
<div class="clearer"></div>
|
||
</div>
|
||
<div class="related" role="navigation" aria-label="Related">
|
||
<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.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li class="switchers">
|
||
<div class="language_switcher_placeholder"></div>
|
||
<div class="version_switcher_placeholder"></div>
|
||
</li>
|
||
<li>
|
||
|
||
</li>
|
||
<li id="cpython-language-and-version">
|
||
<a href="../index.html">3.13.3 Documentation</a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >The Python Language Reference</a> »</li>
|
||
<li class="nav-item nav-item-this"><a href=""><span class="section-number">6. </span>Expressions</a></li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />
|
||
<input type="submit" value="Go" />
|
||
</form>
|
||
</div>
|
||
|
|
||
</li>
|
||
<li class="right">
|
||
<label class="theme-selector-label">
|
||
Theme
|
||
<select class="theme-selector" oninput="activateTheme(this.value)">
|
||
<option value="auto" selected>Auto</option>
|
||
<option value="light">Light</option>
|
||
<option value="dark">Dark</option>
|
||
</select>
|
||
</label> |</li>
|
||
|
||
</ul>
|
||
</div>
|
||
<div class="footer">
|
||
©
|
||
<a href="../copyright.html">
|
||
|
||
Copyright
|
||
|
||
</a>
|
||
2001-2025, Python Software Foundation.
|
||
<br />
|
||
This page is licensed under the Python Software Foundation License Version 2.
|
||
<br />
|
||
Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.
|
||
<br />
|
||
|
||
See <a href="/license.html">History and License</a> for more information.<br />
|
||
|
||
|
||
<br />
|
||
|
||
The Python Software Foundation is a non-profit corporation.
|
||
<a href="https://www.python.org/psf/donations/">Please donate.</a>
|
||
<br />
|
||
<br />
|
||
Last updated on Apr 08, 2025 (14:33 UTC).
|
||
|
||
<a href="/bugs.html">Found a bug</a>?
|
||
|
||
<br />
|
||
|
||
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.
|
||
</div>
|
||
|
||
</body>
|
||
</html> |