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