Baoding-FenShuaJiang
/
Green_GoodERP18_FSJ_Standard
关注 1
点赞 0
百科 捐赠
gooderp18绿色标准版
您最多选择25个主题 主题必须以字母或数字开头，可以包含连字符 (-)，并且长度不得超过35个字符
目录树: 0f75e31513
分支列表 标签列表
${ item.name }
创建分支 ${ searchTerm }
从 '0f75e31513'
${ noResults }
Green_GoodERP18_FSJ_Standard/python/Doc/html/tutorial/controlflow.html

1365 行
131KB
原始文件 Blame 文件历史 

  1. <!DOCTYPE html>

  2. 

  3. <html lang="en" data-content_root="../">

  4.   <head>

  5.     <meta charset="utf-8" />

  6.     <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />

  7. <meta property="og:title" content="4. More Control Flow Tools" />

  8. <meta property="og:type" content="website" />

  9. <meta property="og:url" content="https://docs.python.org/3/tutorial/controlflow.html" />

  10. <meta property="og:site_name" content="Python documentation" />

  11. <meta property="og:description" content="As well as the while statement just introduced, Python uses a few more that we will encounter in this chapter. if Statements: Perhaps the most well-known statement type is the if statement. For exa..." />

  12. <meta property="og:image" content="https://docs.python.org/3/_static/og-image.png" />

  13. <meta property="og:image:alt" content="Python documentation" />

  14. <meta name="description" content="As well as the while statement just introduced, Python uses a few more that we will encounter in this chapter. if Statements: Perhaps the most well-known statement type is the if statement. For exa..." />

  15. <meta property="og:image:width" content="200" />

  16. <meta property="og:image:height" content="200" />

  17. <meta name="theme-color" content="#3776ab" />

  18. 

  19.     <title>4. More Control Flow Tools &#8212; Python 3.12.3 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">

  20.     

  21.     <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=80d5e7a1" />

  22.     <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=bb723527" />

  23.     <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=b20cc3f5" />

  24.     

  25.     <script src="../_static/documentation_options.js?v=2c828074"></script>

  26.     <script src="../_static/doctools.js?v=888ff710"></script>

  27.     <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>

  28.     

  29.     <script src="../_static/sidebar.js"></script>

  30.     

  31.     <link rel="search" type="application/opensearchdescription+xml"

  32.           title="Search within Python 3.12.3 documentation"

  33.           href="../_static/opensearch.xml"/>

  34.     <link rel="author" title="About these documents" href="../about.html" />

  35.     <link rel="index" title="Index" href="../genindex.html" />

  36.     <link rel="search" title="Search" href="../search.html" />

  37.     <link rel="copyright" title="Copyright" href="../copyright.html" />

  38.     <link rel="next" title="5. Data Structures" href="datastructures.html" />

  39.     <link rel="prev" title="3. An Informal Introduction to Python" href="introduction.html" />

  40.     <link rel="canonical" href="https://docs.python.org/3/tutorial/controlflow.html" />

  41.     

  42.       

  43.     

  44. 

  45.     

  46.     <style>

  47.       @media only screen {

  48.         table.full-width-table {

  49.             width: 100%;

  50.         }

  51.       }

  52.     </style>

  53. <link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">

  54.     <link rel="shortcut icon" type="image/png" href="../_static/py.svg" />

  55.             <script type="text/javascript" src="../_static/copybutton.js"></script>

  56.             <script type="text/javascript" src="../_static/menu.js"></script>

  57.             <script type="text/javascript" src="../_static/search-focus.js"></script>

  58.             <script type="text/javascript" src="../_static/themetoggle.js"></script> 

  59. 

  60.   </head>

  61. <body>

  62. <div class="mobile-nav">

  63.     <input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"

  64.            aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu" />

  65.     <nav class="nav-content" role="navigation">

  66.         <label for="menuToggler" class="toggler__label">

  67.             <span></span>

  68.         </label>

  69.         <span class="nav-items-wrapper">

  70.             <a href="https://www.python.org/" class="nav-logo">

  71.                 <img src="../_static/py.svg" alt="Python logo"/>

  72.             </a>

  73.             <span class="version_switcher_placeholder"></span>

  74.             <form role="search" class="search" action="../search.html" method="get">

  75.                 <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">

  76.                     <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>

  77.                 </svg>

  78.                 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" />

  79.                 <input type="submit" value="Go"/>

  80.             </form>

  81.         </span>

  82.     </nav>

  83.     <div class="menu-wrapper">

  84.         <nav class="menu" role="navigation" aria-label="main navigation">

  85.             <div class="language_switcher_placeholder"></div>

  86.             

  87. <label class="theme-selector-label">

  88.     Theme

  89.     <select class="theme-selector" oninput="activateTheme(this.value)">

  90.         <option value="auto" selected>Auto</option>

  91.         <option value="light">Light</option>

  92.         <option value="dark">Dark</option>

  93.     </select>

  94. </label>

  95.   <div>

  96.     <h3><a href="../contents.html">Table of Contents</a></h3>

  97.     <ul>

  98. <li><a class="reference internal" href="#">4. More Control Flow Tools</a><ul>

  99. <li><a class="reference internal" href="#if-statements">4.1. <code class="xref std std-keyword docutils literal notranslate"><span class="pre">if</span></code> Statements</a></li>

  100. <li><a class="reference internal" href="#for-statements">4.2. <code class="xref std std-keyword docutils literal notranslate"><span class="pre">for</span></code> Statements</a></li>

  101. <li><a class="reference internal" href="#the-range-function">4.3. The <code class="xref py py-func docutils literal notranslate"><span class="pre">range()</span></code> Function</a></li>

  102. <li><a class="reference internal" href="#break-and-continue-statements-and-else-clauses-on-loops">4.4. <code class="xref std std-keyword docutils literal notranslate"><span class="pre">break</span></code> and <code class="xref std std-keyword docutils literal notranslate"><span class="pre">continue</span></code> Statements, and <code class="xref std std-keyword docutils literal notranslate"><span class="pre">else</span></code> Clauses on Loops</a></li>

  103. <li><a class="reference internal" href="#pass-statements">4.5. <code class="xref std std-keyword docutils literal notranslate"><span class="pre">pass</span></code> Statements</a></li>

  104. <li><a class="reference internal" href="#match-statements">4.6. <code class="xref std std-keyword docutils literal notranslate"><span class="pre">match</span></code> Statements</a></li>

  105. <li><a class="reference internal" href="#defining-functions">4.7. Defining Functions</a></li>

  106. <li><a class="reference internal" href="#more-on-defining-functions">4.8. More on Defining Functions</a><ul>

  107. <li><a class="reference internal" href="#default-argument-values">4.8.1. Default Argument Values</a></li>

  108. <li><a class="reference internal" href="#keyword-arguments">4.8.2. Keyword Arguments</a></li>

  109. <li><a class="reference internal" href="#special-parameters">4.8.3. Special parameters</a><ul>

  110. <li><a class="reference internal" href="#positional-or-keyword-arguments">4.8.3.1. Positional-or-Keyword Arguments</a></li>

  111. <li><a class="reference internal" href="#positional-only-parameters">4.8.3.2. Positional-Only Parameters</a></li>

  112. <li><a class="reference internal" href="#keyword-only-arguments">4.8.3.3. Keyword-Only Arguments</a></li>

  113. <li><a class="reference internal" href="#function-examples">4.8.3.4. Function Examples</a></li>

  114. <li><a class="reference internal" href="#recap">4.8.3.5. Recap</a></li>

  115. </ul>

  116. </li>

  117. <li><a class="reference internal" href="#arbitrary-argument-lists">4.8.4. Arbitrary Argument Lists</a></li>

  118. <li><a class="reference internal" href="#unpacking-argument-lists">4.8.5. Unpacking Argument Lists</a></li>

  119. <li><a class="reference internal" href="#lambda-expressions">4.8.6. Lambda Expressions</a></li>

  120. <li><a class="reference internal" href="#documentation-strings">4.8.7. Documentation Strings</a></li>

  121. <li><a class="reference internal" href="#function-annotations">4.8.8. Function Annotations</a></li>

  122. </ul>

  123. </li>

  124. <li><a class="reference internal" href="#intermezzo-coding-style">4.9. Intermezzo: Coding Style</a></li>

  125. </ul>

  126. </li>

  127. </ul>

  128. 

  129.   </div>

  130.   <div>

  131.     <h4>Previous topic</h4>

  132.     <p class="topless"><a href="introduction.html"

  133.                           title="previous chapter"><span class="section-number">3. </span>An Informal Introduction to Python</a></p>

  134.   </div>

  135.   <div>

  136.     <h4>Next topic</h4>

  137.     <p class="topless"><a href="datastructures.html"

  138.                           title="next chapter"><span class="section-number">5. </span>Data Structures</a></p>

  139.   </div>

  140.   <div role="note" aria-label="source link">

  141.     <h3>This Page</h3>

  142.     <ul class="this-page-menu">

  143.       <li><a href="../bugs.html">Report a Bug</a></li>

  144.       <li>

  145.         <a href="https://github.com/python/cpython/blob/main/Doc/tutorial/controlflow.rst"

  146.             rel="nofollow">Show Source

  147.         </a>

  148.       </li>

  149.     </ul>

  150.   </div>

  151.         </nav>

  152.     </div>

  153. </div>

  154. 

  155.   

  156.     <div class="related" role="navigation" aria-label="related navigation">

  157.       <h3>Navigation</h3>

  158.       <ul>

  159.         <li class="right" style="margin-right: 10px">

  160.           <a href="../genindex.html" title="General Index"

  161.              accesskey="I">index</a></li>

  162.         <li class="right" >

  163.           <a href="../py-modindex.html" title="Python Module Index"

  164.              >modules</a> |</li>

  165.         <li class="right" >

  166.           <a href="datastructures.html" title="5. Data Structures"

  167.              accesskey="N">next</a> |</li>

  168.         <li class="right" >

  169.           <a href="introduction.html" title="3. An Informal Introduction to Python"

  170.              accesskey="P">previous</a> |</li>

  171. 

  172.           <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>

  173.           <li><a href="https://www.python.org/">Python</a> &#187;</li>

  174.           <li class="switchers">

  175.             <div class="language_switcher_placeholder"></div>

  176.             <div class="version_switcher_placeholder"></div>

  177.           </li>

  178.           <li>

  179.               

  180.           </li>

  181.     <li id="cpython-language-and-version">

  182.       <a href="../index.html">3.12.3 Documentation</a> &#187;

  183.     </li>

  184. 

  185.           <li class="nav-item nav-item-1"><a href="index.html" accesskey="U">The Python Tutorial</a> &#187;</li>

  186.         <li class="nav-item nav-item-this"><a href=""><span class="section-number">4. </span>More Control Flow Tools</a></li>

  187.                 <li class="right">

  188.                     

  189. 

  190.     <div class="inline-search" role="search">

  191.         <form class="inline-search" action="../search.html" method="get">

  192.           <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />

  193.           <input type="submit" value="Go" />

  194.         </form>

  195.     </div>

  196.                      |

  197.                 </li>

  198.             <li class="right">

  199. <label class="theme-selector-label">

  200.     Theme

  201.     <select class="theme-selector" oninput="activateTheme(this.value)">

  202.         <option value="auto" selected>Auto</option>

  203.         <option value="light">Light</option>

  204.         <option value="dark">Dark</option>

  205.     </select>

  206. </label> |</li>

  207.             

  208.       </ul>

  209.     </div>    

  210. 

  211.     <div class="document">

  212.       <div class="documentwrapper">

  213.         <div class="bodywrapper">

  214.           <div class="body" role="main">

  215.             

  216.   <section id="more-control-flow-tools">

  217. <span id="tut-morecontrol"></span><h1><span class="section-number">4. </span>More Control Flow Tools<a class="headerlink" href="#more-control-flow-tools" title="Link to this heading">¶</a></h1>

  218. <p>As well as the <a class="reference internal" href="../reference/compound_stmts.html#while"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">while</span></code></a> statement just introduced, Python uses a few more

  219. that we will encounter in this chapter.</p>

  220. <section id="if-statements">

  221. <span id="tut-if"></span><h2><span class="section-number">4.1. </span><code class="xref std std-keyword docutils literal notranslate"><span class="pre">if</span></code> Statements<a class="headerlink" href="#if-statements" title="Link to this heading">¶</a></h2>

  222. <p>Perhaps the most well-known statement type is the <a class="reference internal" href="../reference/compound_stmts.html#if"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">if</span></code></a> statement.  For

  223. example:</p>

  224. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">x</span> <span class="o">=</span> <span class="nb">int</span><span class="p">(</span><span class="nb">input</span><span class="p">(</span><span class="s2">&quot;Please enter an integer: &quot;</span><span class="p">))</span>

  225. <span class="go">Please enter an integer: 42</span>

  226. <span class="gp">&gt;&gt;&gt; </span><span class="k">if</span> <span class="n">x</span> <span class="o">&lt;</span> <span class="mi">0</span><span class="p">:</span>

  227. <span class="gp">... </span>    <span class="n">x</span> <span class="o">=</span> <span class="mi">0</span>

  228. <span class="gp">... </span>    <span class="nb">print</span><span class="p">(</span><span class="s1">&#39;Negative changed to zero&#39;</span><span class="p">)</span>

  229. <span class="gp">... </span><span class="k">elif</span> <span class="n">x</span> <span class="o">==</span> <span class="mi">0</span><span class="p">:</span>

  230. <span class="gp">... </span>    <span class="nb">print</span><span class="p">(</span><span class="s1">&#39;Zero&#39;</span><span class="p">)</span>

  231. <span class="gp">... </span><span class="k">elif</span> <span class="n">x</span> <span class="o">==</span> <span class="mi">1</span><span class="p">:</span>

  232. <span class="gp">... </span>    <span class="nb">print</span><span class="p">(</span><span class="s1">&#39;Single&#39;</span><span class="p">)</span>

  233. <span class="gp">... </span><span class="k">else</span><span class="p">:</span>

  234. <span class="gp">... </span>    <span class="nb">print</span><span class="p">(</span><span class="s1">&#39;More&#39;</span><span class="p">)</span>

  235. <span class="gp">...</span>

  236. <span class="go">More</span>

  237. </pre></div>

  238. </div>

  239. <p>There can be zero or more <a class="reference internal" href="../reference/compound_stmts.html#elif"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">elif</span></code></a> parts, and the <a class="reference internal" href="../reference/compound_stmts.html#else"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">else</span></code></a> part is

  240. optional.  The keyword ‘<code class="xref std std-keyword docutils literal notranslate"><span class="pre">elif</span></code>’ is short for ‘else if’, and is useful

  241. to avoid excessive indentation.  An  <code class="xref std std-keyword docutils literal notranslate"><span class="pre">if</span></code> … <code class="xref std std-keyword docutils literal notranslate"><span class="pre">elif</span></code> …

  242. <code class="xref std std-keyword docutils literal notranslate"><span class="pre">elif</span></code> … sequence is a substitute for the <code class="docutils literal notranslate"><span class="pre">switch</span></code> or

  243. <code class="docutils literal notranslate"><span class="pre">case</span></code> statements found in other languages.</p>

  244. <p>If you’re comparing the same value to several constants, or checking for specific types or

  245. attributes, you may also find the <code class="xref std std-keyword docutils literal notranslate"><span class="pre">match</span></code> statement useful. For more

  246. details see <a class="reference internal" href="#tut-match"><span class="std std-ref">match Statements</span></a>.</p>

  247. </section>

  248. <section id="for-statements">

  249. <span id="tut-for"></span><h2><span class="section-number">4.2. </span><code class="xref std std-keyword docutils literal notranslate"><span class="pre">for</span></code> Statements<a class="headerlink" href="#for-statements" title="Link to this heading">¶</a></h2>

  250. <p id="index-0">The <a class="reference internal" href="../reference/compound_stmts.html#for"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">for</span></code></a> statement in Python differs a bit from what you may be used

  251. to in C or Pascal.  Rather than always iterating over an arithmetic progression

  252. of numbers (like in Pascal), or giving the user the ability to define both the

  253. iteration step and halting condition (as C), Python’s <code class="xref std std-keyword docutils literal notranslate"><span class="pre">for</span></code> statement

  254. iterates over the items of any sequence (a list or a string), in the order that

  255. they appear in the sequence.  For example (no pun intended):</p>

  256. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="c1"># Measure some strings:</span>

  257. <span class="gp">... </span><span class="n">words</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;cat&#39;</span><span class="p">,</span> <span class="s1">&#39;window&#39;</span><span class="p">,</span> <span class="s1">&#39;defenestrate&#39;</span><span class="p">]</span>

  258. <span class="gp">&gt;&gt;&gt; </span><span class="k">for</span> <span class="n">w</span> <span class="ow">in</span> <span class="n">words</span><span class="p">:</span>

  259. <span class="gp">... </span>    <span class="nb">print</span><span class="p">(</span><span class="n">w</span><span class="p">,</span> <span class="nb">len</span><span class="p">(</span><span class="n">w</span><span class="p">))</span>

  260. <span class="gp">...</span>

  261. <span class="go">cat 3</span>

  262. <span class="go">window 6</span>

  263. <span class="go">defenestrate 12</span>

  264. </pre></div>

  265. </div>

  266. <p>Code that modifies a collection while iterating over that same collection can

  267. be tricky to get right.  Instead, it is usually more straight-forward to loop

  268. over a copy of the collection or to create a new collection:</p>

  269. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="c1"># Create a sample collection</span>

  270. <span class="n">users</span> <span class="o">=</span> <span class="p">{</span><span class="s1">&#39;Hans&#39;</span><span class="p">:</span> <span class="s1">&#39;active&#39;</span><span class="p">,</span> <span class="s1">&#39;Éléonore&#39;</span><span class="p">:</span> <span class="s1">&#39;inactive&#39;</span><span class="p">,</span> <span class="s1">&#39;景太郎&#39;</span><span class="p">:</span> <span class="s1">&#39;active&#39;</span><span class="p">}</span>

  271. 

  272. <span class="c1"># Strategy:  Iterate over a copy</span>

  273. <span class="k">for</span> <span class="n">user</span><span class="p">,</span> <span class="n">status</span> <span class="ow">in</span> <span class="n">users</span><span class="o">.</span><span class="n">copy</span><span class="p">()</span><span class="o">.</span><span class="n">items</span><span class="p">():</span>

  274.     <span class="k">if</span> <span class="n">status</span> <span class="o">==</span> <span class="s1">&#39;inactive&#39;</span><span class="p">:</span>

  275.         <span class="k">del</span> <span class="n">users</span><span class="p">[</span><span class="n">user</span><span class="p">]</span>

  276. 

  277. <span class="c1"># Strategy:  Create a new collection</span>

  278. <span class="n">active_users</span> <span class="o">=</span> <span class="p">{}</span>

  279. <span class="k">for</span> <span class="n">user</span><span class="p">,</span> <span class="n">status</span> <span class="ow">in</span> <span class="n">users</span><span class="o">.</span><span class="n">items</span><span class="p">():</span>

  280.     <span class="k">if</span> <span class="n">status</span> <span class="o">==</span> <span class="s1">&#39;active&#39;</span><span class="p">:</span>

  281.         <span class="n">active_users</span><span class="p">[</span><span class="n">user</span><span class="p">]</span> <span class="o">=</span> <span class="n">status</span>

  282. </pre></div>

  283. </div>

  284. </section>

  285. <section id="the-range-function">

  286. <span id="tut-range"></span><h2><span class="section-number">4.3. </span>The <a class="reference internal" href="../library/stdtypes.html#range" title="range"><code class="xref py py-func docutils literal notranslate"><span class="pre">range()</span></code></a> Function<a class="headerlink" href="#the-range-function" title="Link to this heading">¶</a></h2>

  287. <p>If you do need to iterate over a sequence of numbers, the built-in function

  288. <a class="reference internal" href="../library/stdtypes.html#range" title="range"><code class="xref py py-func docutils literal notranslate"><span class="pre">range()</span></code></a> comes in handy.  It generates arithmetic progressions:</p>

  289. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">5</span><span class="p">):</span>

  290. <span class="gp">... </span>    <span class="nb">print</span><span class="p">(</span><span class="n">i</span><span class="p">)</span>

  291. <span class="gp">...</span>

  292. <span class="go">0</span>

  293. <span class="go">1</span>

  294. <span class="go">2</span>

  295. <span class="go">3</span>

  296. <span class="go">4</span>

  297. </pre></div>

  298. </div>

  299. <p>The given end point is never part of the generated sequence; <code class="docutils literal notranslate"><span class="pre">range(10)</span></code> generates

  300. 10 values, the legal indices for items of a sequence of length 10.  It

  301. is possible to let the range start at another number, or to specify a different

  302. increment (even negative; sometimes this is called the ‘step’):</p>

  303. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="mi">5</span><span class="p">,</span> <span class="mi">10</span><span class="p">))</span>

  304. <span class="go">[5, 6, 7, 8, 9]</span>

  305. 

  306. <span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">3</span><span class="p">))</span>

  307. <span class="go">[0, 3, 6, 9]</span>

  308. 

  309. <span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="o">-</span><span class="mi">10</span><span class="p">,</span> <span class="o">-</span><span class="mi">100</span><span class="p">,</span> <span class="o">-</span><span class="mi">30</span><span class="p">))</span>

  310. <span class="go">[-10, -40, -70]</span>

  311. </pre></div>

  312. </div>

  313. <p>To iterate over the indices of a sequence, you can combine <a class="reference internal" href="../library/stdtypes.html#range" title="range"><code class="xref py py-func docutils literal notranslate"><span class="pre">range()</span></code></a> and

  314. <a class="reference internal" href="../library/functions.html#len" title="len"><code class="xref py py-func docutils literal notranslate"><span class="pre">len()</span></code></a> as follows:</p>

  315. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">a</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;Mary&#39;</span><span class="p">,</span> <span class="s1">&#39;had&#39;</span><span class="p">,</span> <span class="s1">&#39;a&#39;</span><span class="p">,</span> <span class="s1">&#39;little&#39;</span><span class="p">,</span> <span class="s1">&#39;lamb&#39;</span><span class="p">]</span>

  316. <span class="gp">&gt;&gt;&gt; </span><span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="n">a</span><span class="p">)):</span>

  317. <span class="gp">... </span>    <span class="nb">print</span><span class="p">(</span><span class="n">i</span><span class="p">,</span> <span class="n">a</span><span class="p">[</span><span class="n">i</span><span class="p">])</span>

  318. <span class="gp">...</span>

  319. <span class="go">0 Mary</span>

  320. <span class="go">1 had</span>

  321. <span class="go">2 a</span>

  322. <span class="go">3 little</span>

  323. <span class="go">4 lamb</span>

  324. </pre></div>

  325. </div>

  326. <p>In most such cases, however, it is convenient to use the <a class="reference internal" href="../library/functions.html#enumerate" title="enumerate"><code class="xref py py-func docutils literal notranslate"><span class="pre">enumerate()</span></code></a>

  327. function, see <a class="reference internal" href="datastructures.html#tut-loopidioms"><span class="std std-ref">Looping Techniques</span></a>.</p>

  328. <p>A strange thing happens if you just print a range:</p>

  329. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="nb">range</span><span class="p">(</span><span class="mi">10</span><span class="p">)</span>

  330. <span class="go">range(0, 10)</span>

  331. </pre></div>

  332. </div>

  333. <p>In many ways the object returned by <a class="reference internal" href="../library/stdtypes.html#range" title="range"><code class="xref py py-func docutils literal notranslate"><span class="pre">range()</span></code></a> behaves as if it is a list,

  334. but in fact it isn’t. It is an object which returns the successive items of

  335. the desired sequence when you iterate over it, but it doesn’t really make

  336. the list, thus saving space.</p>

  337. <p>We say such an object is <a class="reference internal" href="../glossary.html#term-iterable"><span class="xref std std-term">iterable</span></a>, that is, suitable as a target for

  338. functions and constructs that expect something from which they can

  339. obtain successive items until the supply is exhausted.  We have seen that

  340. the <a class="reference internal" href="../reference/compound_stmts.html#for"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">for</span></code></a> statement is such a construct, while an example of a function

  341. that takes an iterable is <a class="reference internal" href="../library/functions.html#sum" title="sum"><code class="xref py py-func docutils literal notranslate"><span class="pre">sum()</span></code></a>:</p>

  342. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="nb">sum</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="mi">4</span><span class="p">))</span>  <span class="c1"># 0 + 1 + 2 + 3</span>

  343. <span class="go">6</span>

  344. </pre></div>

  345. </div>

  346. <p>Later we will see more functions that return iterables and take iterables as

  347. arguments.  In chapter <a class="reference internal" href="datastructures.html#tut-structures"><span class="std std-ref">Data Structures</span></a>, we will discuss in more detail about

  348. <a class="reference internal" href="../library/stdtypes.html#list" title="list"><code class="xref py py-func docutils literal notranslate"><span class="pre">list()</span></code></a>.</p>

  349. </section>

  350. <section id="break-and-continue-statements-and-else-clauses-on-loops">

  351. <span id="tut-break"></span><h2><span class="section-number">4.4. </span><code class="xref std std-keyword docutils literal notranslate"><span class="pre">break</span></code> and <code class="xref std std-keyword docutils literal notranslate"><span class="pre">continue</span></code> Statements, and <code class="xref std std-keyword docutils literal notranslate"><span class="pre">else</span></code> Clauses on Loops<a class="headerlink" href="#break-and-continue-statements-and-else-clauses-on-loops" title="Link to this heading">¶</a></h2>

  352. <p>The <a class="reference internal" href="../reference/simple_stmts.html#break"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">break</span></code></a> statement breaks out of the innermost enclosing

  353. <a class="reference internal" href="../reference/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="../reference/compound_stmts.html#while"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">while</span></code></a> loop.</p>

  354. <p>A <code class="xref std std-keyword docutils literal notranslate"><span class="pre">for</span></code> or <code class="xref std std-keyword docutils literal notranslate"><span class="pre">while</span></code> loop can include an <code class="xref std std-keyword docutils literal notranslate"><span class="pre">else</span></code> clause.</p>

  355. <p>In a <a class="reference internal" href="../reference/compound_stmts.html#for"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">for</span></code></a> loop, the <code class="xref std std-keyword docutils literal notranslate"><span class="pre">else</span></code> clause is executed

  356. after the loop reaches its final iteration.</p>

  357. <p>In a <a class="reference internal" href="../reference/compound_stmts.html#while"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">while</span></code></a> loop, it’s executed after the loop’s condition becomes false.</p>

  358. <p>In either kind of loop, the <code class="xref std std-keyword docutils literal notranslate"><span class="pre">else</span></code> clause is <strong>not</strong> executed

  359. if the loop was terminated by a <a class="reference internal" href="../reference/simple_stmts.html#break"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">break</span></code></a>.</p>

  360. <p>This is exemplified in the following <code class="xref std std-keyword docutils literal notranslate"><span class="pre">for</span></code> loop,

  361. which searches for prime numbers:</p>

  362. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">for</span> <span class="n">n</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="mi">10</span><span class="p">):</span>

  363. <span class="gp">... </span>    <span class="k">for</span> <span class="n">x</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="n">n</span><span class="p">):</span>

  364. <span class="gp">... </span>        <span class="k">if</span> <span class="n">n</span> <span class="o">%</span> <span class="n">x</span> <span class="o">==</span> <span class="mi">0</span><span class="p">:</span>

  365. <span class="gp">... </span>            <span class="nb">print</span><span class="p">(</span><span class="n">n</span><span class="p">,</span> <span class="s1">&#39;equals&#39;</span><span class="p">,</span> <span class="n">x</span><span class="p">,</span> <span class="s1">&#39;*&#39;</span><span class="p">,</span> <span class="n">n</span><span class="o">//</span><span class="n">x</span><span class="p">)</span>

  366. <span class="gp">... </span>            <span class="k">break</span>

  367. <span class="gp">... </span>    <span class="k">else</span><span class="p">:</span>

  368. <span class="gp">... </span>        <span class="c1"># loop fell through without finding a factor</span>

  369. <span class="gp">... </span>        <span class="nb">print</span><span class="p">(</span><span class="n">n</span><span class="p">,</span> <span class="s1">&#39;is a prime number&#39;</span><span class="p">)</span>

  370. <span class="gp">...</span>

  371. <span class="go">2 is a prime number</span>

  372. <span class="go">3 is a prime number</span>

  373. <span class="go">4 equals 2 * 2</span>

  374. <span class="go">5 is a prime number</span>

  375. <span class="go">6 equals 2 * 3</span>

  376. <span class="go">7 is a prime number</span>

  377. <span class="go">8 equals 2 * 4</span>

  378. <span class="go">9 equals 3 * 3</span>

  379. </pre></div>

  380. </div>

  381. <p>(Yes, this is the correct code.  Look closely: the <code class="docutils literal notranslate"><span class="pre">else</span></code> clause belongs to

  382. the <a class="reference internal" href="../reference/compound_stmts.html#for"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">for</span></code></a> loop, <strong>not</strong> the <a class="reference internal" href="../reference/compound_stmts.html#if"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">if</span></code></a> statement.)</p>

  383. <p>When used with a loop, the <code class="docutils literal notranslate"><span class="pre">else</span></code> clause has more in common with the

  384. <code class="docutils literal notranslate"><span class="pre">else</span></code> clause of a <a class="reference internal" href="../reference/compound_stmts.html#try"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">try</span></code></a> statement than it does with that of

  385. <a class="reference internal" href="../reference/compound_stmts.html#if"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">if</span></code></a> statements: a <a class="reference internal" href="../reference/compound_stmts.html#try"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">try</span></code></a> statement’s <code class="docutils literal notranslate"><span class="pre">else</span></code> clause runs

  386. when no exception occurs, and a loop’s <code class="docutils literal notranslate"><span class="pre">else</span></code> clause runs when no <code class="docutils literal notranslate"><span class="pre">break</span></code>

  387. occurs. For more on the <code class="xref std std-keyword docutils literal notranslate"><span class="pre">try</span></code> statement and exceptions, see

  388. <a class="reference internal" href="errors.html#tut-handling"><span class="std std-ref">Handling Exceptions</span></a>.</p>

  389. <p>The <a class="reference internal" href="../reference/simple_stmts.html#continue"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">continue</span></code></a> statement, also borrowed from C, continues with the next

  390. iteration of the loop:</p>

  391. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">for</span> <span class="n">num</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="mi">10</span><span class="p">):</span>

  392. <span class="gp">... </span>    <span class="k">if</span> <span class="n">num</span> <span class="o">%</span> <span class="mi">2</span> <span class="o">==</span> <span class="mi">0</span><span class="p">:</span>

  393. <span class="gp">... </span>        <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Found an even number&quot;</span><span class="p">,</span> <span class="n">num</span><span class="p">)</span>

  394. <span class="gp">... </span>        <span class="k">continue</span>

  395. <span class="gp">... </span>    <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Found an odd number&quot;</span><span class="p">,</span> <span class="n">num</span><span class="p">)</span>

  396. <span class="gp">...</span>

  397. <span class="go">Found an even number 2</span>

  398. <span class="go">Found an odd number 3</span>

  399. <span class="go">Found an even number 4</span>

  400. <span class="go">Found an odd number 5</span>

  401. <span class="go">Found an even number 6</span>

  402. <span class="go">Found an odd number 7</span>

  403. <span class="go">Found an even number 8</span>

  404. <span class="go">Found an odd number 9</span>

  405. </pre></div>

  406. </div>

  407. </section>

  408. <section id="pass-statements">

  409. <span id="tut-pass"></span><h2><span class="section-number">4.5. </span><code class="xref std std-keyword docutils literal notranslate"><span class="pre">pass</span></code> Statements<a class="headerlink" href="#pass-statements" title="Link to this heading">¶</a></h2>

  410. <p>The <a class="reference internal" href="../reference/simple_stmts.html#pass"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">pass</span></code></a> statement does nothing. It can be used when a statement is

  411. required syntactically but the program requires no action. For example:</p>

  412. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">while</span> <span class="kc">True</span><span class="p">:</span>

  413. <span class="gp">... </span>    <span class="k">pass</span>  <span class="c1"># Busy-wait for keyboard interrupt (Ctrl+C)</span>

  414. <span class="gp">...</span>

  415. </pre></div>

  416. </div>

  417. <p>This is commonly used for creating minimal classes:</p>

  418. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">MyEmptyClass</span><span class="p">:</span>

  419. <span class="gp">... </span>    <span class="k">pass</span>

  420. <span class="gp">...</span>

  421. </pre></div>

  422. </div>

  423. <p>Another place <a class="reference internal" href="../reference/simple_stmts.html#pass"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">pass</span></code></a> can be used is as a place-holder for a function or

  424. conditional body when you are working on new code, allowing you to keep thinking

  425. at a more abstract level.  The <code class="xref std std-keyword docutils literal notranslate"><span class="pre">pass</span></code> is silently ignored:</p>

  426. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">def</span> <span class="nf">initlog</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">):</span>

  427. <span class="gp">... </span>    <span class="k">pass</span>   <span class="c1"># Remember to implement this!</span>

  428. <span class="gp">...</span>

  429. </pre></div>

  430. </div>

  431. </section>

  432. <section id="match-statements">

  433. <span id="tut-match"></span><h2><span class="section-number">4.6. </span><code class="xref std std-keyword docutils literal notranslate"><span class="pre">match</span></code> Statements<a class="headerlink" href="#match-statements" title="Link to this heading">¶</a></h2>

  434. <p>A <a class="reference internal" href="../reference/compound_stmts.html#match"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">match</span></code></a> statement takes an expression and compares its value to successive

  435. patterns given as one or more case blocks.  This is superficially

  436. similar to a switch statement in C, Java or JavaScript (and many

  437. other languages), but it’s more similar to pattern matching in

  438. languages like Rust or Haskell. Only the first pattern that matches

  439. gets executed and it can also extract components (sequence elements

  440. or object attributes) from the value into variables.</p>

  441. <p>The simplest form compares a subject value against one or more literals:</p>

  442. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">http_error</span><span class="p">(</span><span class="n">status</span><span class="p">):</span>

  443.     <span class="k">match</span> <span class="n">status</span><span class="p">:</span>

  444.         <span class="k">case</span> <span class="mi">400</span><span class="p">:</span>

  445.             <span class="k">return</span> <span class="s2">&quot;Bad request&quot;</span>

  446.         <span class="k">case</span> <span class="mi">404</span><span class="p">:</span>

  447.             <span class="k">return</span> <span class="s2">&quot;Not found&quot;</span>

  448.         <span class="k">case</span> <span class="mi">418</span><span class="p">:</span>

  449.             <span class="k">return</span> <span class="s2">&quot;I&#39;m a teapot&quot;</span>

  450.         <span class="k">case</span><span class="w"> </span><span class="k">_</span><span class="p">:</span>

  451.             <span class="k">return</span> <span class="s2">&quot;Something&#39;s wrong with the internet&quot;</span>

  452. </pre></div>

  453. </div>

  454. <p>Note the last block: the “variable name” <code class="docutils literal notranslate"><span class="pre">_</span></code> acts as a <em>wildcard</em> and

  455. never fails to match. If no case matches, none of the branches is executed.</p>

  456. <p>You can combine several literals in a single pattern using <code class="docutils literal notranslate"><span class="pre">|</span></code> (“or”):</p>

  457. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">case</span> <span class="mi">401</span> <span class="o">|</span> <span class="mi">403</span> <span class="o">|</span> <span class="mi">404</span><span class="p">:</span>

  458.     <span class="k">return</span> <span class="s2">&quot;Not allowed&quot;</span>

  459. </pre></div>

  460. </div>

  461. <p>Patterns can look like unpacking assignments, and can be used to bind

  462. variables:</p>

  463. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="c1"># point is an (x, y) tuple</span>

  464. <span class="k">match</span> <span class="n">point</span><span class="p">:</span>

  465.     <span class="k">case</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">):</span>

  466.         <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Origin&quot;</span><span class="p">)</span>

  467.     <span class="k">case</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="n">y</span><span class="p">):</span>

  468.         <span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Y=</span><span class="si">{</span><span class="n">y</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>

  469.     <span class="k">case</span> <span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="mi">0</span><span class="p">):</span>

  470.         <span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;X=</span><span class="si">{</span><span class="n">x</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>

  471.     <span class="k">case</span> <span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">):</span>

  472.         <span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;X=</span><span class="si">{</span><span class="n">x</span><span class="si">}</span><span class="s2">, Y=</span><span class="si">{</span><span class="n">y</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>

  473.     <span class="k">case</span><span class="w"> </span><span class="k">_</span><span class="p">:</span>

  474.         <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s2">&quot;Not a point&quot;</span><span class="p">)</span>

  475. </pre></div>

  476. </div>

  477. <p>Study that one carefully!  The first pattern has two literals, and can

  478. be thought of as an extension of the literal pattern shown above.  But

  479. the next two patterns combine a literal and a variable, and the

  480. variable <em>binds</em> a value from the subject (<code class="docutils literal notranslate"><span class="pre">point</span></code>).  The fourth

  481. pattern captures two values, which makes it conceptually similar to

  482. the unpacking assignment <code class="docutils literal notranslate"><span class="pre">(x,</span> <span class="pre">y)</span> <span class="pre">=</span> <span class="pre">point</span></code>.</p>

  483. <p>If you are using classes to structure your data

  484. you can use the class name followed by an argument list resembling a

  485. constructor, but with the ability to capture attributes into variables:</p>

  486. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Point</span><span class="p">:</span>

  487.     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">):</span>

  488.         <span class="bp">self</span><span class="o">.</span><span class="n">x</span> <span class="o">=</span> <span class="n">x</span>

  489.         <span class="bp">self</span><span class="o">.</span><span class="n">y</span> <span class="o">=</span> <span class="n">y</span>

  490. 

  491. <span class="k">def</span> <span class="nf">where_is</span><span class="p">(</span><span class="n">point</span><span class="p">):</span>

  492.     <span class="k">match</span> <span class="n">point</span><span class="p">:</span>

  493.         <span class="k">case</span> <span class="n">Point</span><span class="p">(</span><span class="n">x</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> <span class="n">y</span><span class="o">=</span><span class="mi">0</span><span class="p">):</span>

  494.             <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Origin&quot;</span><span class="p">)</span>

  495.         <span class="k">case</span> <span class="n">Point</span><span class="p">(</span><span class="n">x</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> <span class="n">y</span><span class="o">=</span><span class="n">y</span><span class="p">):</span>

  496.             <span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Y=</span><span class="si">{</span><span class="n">y</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>

  497.         <span class="k">case</span> <span class="n">Point</span><span class="p">(</span><span class="n">x</span><span class="o">=</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="o">=</span><span class="mi">0</span><span class="p">):</span>

  498.             <span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;X=</span><span class="si">{</span><span class="n">x</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>

  499.         <span class="k">case</span> <span class="n">Point</span><span class="p">():</span>

  500.             <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Somewhere else&quot;</span><span class="p">)</span>

  501.         <span class="k">case</span><span class="w"> </span><span class="k">_</span><span class="p">:</span>

  502.             <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Not a point&quot;</span><span class="p">)</span>

  503. </pre></div>

  504. </div>

  505. <p>You can use positional parameters with some builtin classes that provide an

  506. ordering for their attributes (e.g. dataclasses). You can also define a specific

  507. position for attributes in patterns by setting the <code class="docutils literal notranslate"><span class="pre">__match_args__</span></code> special

  508. attribute in your classes. If it’s set to (“x”, “y”), the following patterns are all

  509. equivalent (and all bind the <code class="docutils literal notranslate"><span class="pre">y</span></code> attribute to the <code class="docutils literal notranslate"><span class="pre">var</span></code> variable):</p>

  510. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">Point</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="n">var</span><span class="p">)</span>

  511. <span class="n">Point</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="n">y</span><span class="o">=</span><span class="n">var</span><span class="p">)</span>

  512. <span class="n">Point</span><span class="p">(</span><span class="n">x</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">y</span><span class="o">=</span><span class="n">var</span><span class="p">)</span>

  513. <span class="n">Point</span><span class="p">(</span><span class="n">y</span><span class="o">=</span><span class="n">var</span><span class="p">,</span> <span class="n">x</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span>

  514. </pre></div>

  515. </div>

  516. <p>A recommended way to read patterns is to look at them as an extended form of what you

  517. would put on the left of an assignment, to understand which variables would be set to

  518. what.

  519. Only the standalone names (like <code class="docutils literal notranslate"><span class="pre">var</span></code> above) are assigned to by a match statement.

  520. Dotted names (like <code class="docutils literal notranslate"><span class="pre">foo.bar</span></code>), attribute names (the <code class="docutils literal notranslate"><span class="pre">x=</span></code> and <code class="docutils literal notranslate"><span class="pre">y=</span></code> above) or class names

  521. (recognized by the “(…)” next to them like <code class="docutils literal notranslate"><span class="pre">Point</span></code> above) are never assigned to.</p>

  522. <p>Patterns can be arbitrarily nested.  For example, if we have a short

  523. list of Points, with <code class="docutils literal notranslate"><span class="pre">__match_args__</span></code> added, we could match it like this:</p>

  524. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Point</span><span class="p">:</span>

  525.     <span class="n">__match_args__</span> <span class="o">=</span> <span class="p">(</span><span class="s1">&#39;x&#39;</span><span class="p">,</span> <span class="s1">&#39;y&#39;</span><span class="p">)</span>

  526.     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">):</span>

  527.         <span class="bp">self</span><span class="o">.</span><span class="n">x</span> <span class="o">=</span> <span class="n">x</span>

  528.         <span class="bp">self</span><span class="o">.</span><span class="n">y</span> <span class="o">=</span> <span class="n">y</span>

  529. 

  530. <span class="k">match</span> <span class="n">points</span><span class="p">:</span>

  531.     <span class="k">case</span> <span class="p">[]:</span>

  532.         <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;No points&quot;</span><span class="p">)</span>

  533.     <span class="k">case</span> <span class="p">[</span><span class="n">Point</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">)]:</span>

  534.         <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;The origin&quot;</span><span class="p">)</span>

  535.     <span class="k">case</span> <span class="p">[</span><span class="n">Point</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">)]:</span>

  536.         <span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Single point </span><span class="si">{</span><span class="n">x</span><span class="si">}</span><span class="s2">, </span><span class="si">{</span><span class="n">y</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>

  537.     <span class="k">case</span> <span class="p">[</span><span class="n">Point</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="n">y1</span><span class="p">),</span> <span class="n">Point</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="n">y2</span><span class="p">)]:</span>

  538.         <span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Two on the Y axis at </span><span class="si">{</span><span class="n">y1</span><span class="si">}</span><span class="s2">, </span><span class="si">{</span><span class="n">y2</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>

  539.     <span class="k">case</span><span class="w"> </span><span class="k">_</span><span class="p">:</span>

  540.         <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Something else&quot;</span><span class="p">)</span>

  541. </pre></div>

  542. </div>

  543. <p>We can add an <code class="docutils literal notranslate"><span class="pre">if</span></code> clause to a pattern, known as a “guard”.  If the

  544. guard is false, <code class="docutils literal notranslate"><span class="pre">match</span></code> goes on to try the next case block.  Note

  545. that value capture happens before the guard is evaluated:</p>

  546. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">match</span> <span class="n">point</span><span class="p">:</span>

  547.     <span class="k">case</span> <span class="n">Point</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">)</span> <span class="k">if</span> <span class="n">x</span> <span class="o">==</span> <span class="n">y</span><span class="p">:</span>

  548.         <span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Y=X at </span><span class="si">{</span><span class="n">x</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>

  549.     <span class="k">case</span> <span class="n">Point</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">):</span>

  550.         <span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Not on the diagonal&quot;</span><span class="p">)</span>

  551. </pre></div>

  552. </div>

  553. <p>Several other key features of this statement:</p>

  554. <ul>

  555. <li><p>Like unpacking assignments, tuple and list patterns have exactly the

  556. same meaning and actually match arbitrary sequences.  An important

  557. exception is that they don’t match iterators or strings.</p></li>

  558. <li><p>Sequence patterns support extended unpacking: <code class="docutils literal notranslate"><span class="pre">[x,</span> <span class="pre">y,</span> <span class="pre">*rest]</span></code> and <code class="docutils literal notranslate"><span class="pre">(x,</span> <span class="pre">y,</span>

  559. <span class="pre">*rest)</span></code> work similar to unpacking assignments.  The

  560. name after <code class="docutils literal notranslate"><span class="pre">*</span></code> may also be <code class="docutils literal notranslate"><span class="pre">_</span></code>, so <code class="docutils literal notranslate"><span class="pre">(x,</span> <span class="pre">y,</span> <span class="pre">*_)</span></code> matches a sequence

  561. of at least two items without binding the remaining items.</p></li>

  562. <li><p>Mapping patterns: <code class="docutils literal notranslate"><span class="pre">{&quot;bandwidth&quot;:</span> <span class="pre">b,</span> <span class="pre">&quot;latency&quot;:</span> <span class="pre">l}</span></code> captures the

  563. <code class="docutils literal notranslate"><span class="pre">&quot;bandwidth&quot;</span></code> and <code class="docutils literal notranslate"><span class="pre">&quot;latency&quot;</span></code> values from a dictionary.  Unlike sequence

  564. patterns, extra keys are ignored.  An unpacking like <code class="docutils literal notranslate"><span class="pre">**rest</span></code> is also

  565. supported.  (But <code class="docutils literal notranslate"><span class="pre">**_</span></code> would be redundant, so it is not allowed.)</p></li>

  566. <li><p>Subpatterns may be captured using the <code class="docutils literal notranslate"><span class="pre">as</span></code> keyword:</p>

  567. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">case</span> <span class="p">(</span><span class="n">Point</span><span class="p">(</span><span class="n">x1</span><span class="p">,</span> <span class="n">y1</span><span class="p">),</span> <span class="n">Point</span><span class="p">(</span><span class="n">x2</span><span class="p">,</span> <span class="n">y2</span><span class="p">)</span> <span class="k">as</span> <span class="n">p2</span><span class="p">):</span> <span class="o">...</span>

  568. </pre></div>

  569. </div>

  570. <p>will capture the second element of the input as <code class="docutils literal notranslate"><span class="pre">p2</span></code> (as long as the input is

  571. a sequence of two points)</p>

  572. </li>

  573. <li><p>Most literals are compared by equality, however the singletons <code class="docutils literal notranslate"><span class="pre">True</span></code>,

  574. <code class="docutils literal notranslate"><span class="pre">False</span></code> and <code class="docutils literal notranslate"><span class="pre">None</span></code> are compared by identity.</p></li>

  575. <li><p>Patterns may use named constants.  These must be dotted names

  576. to prevent them from being interpreted as capture variable:</p>

  577. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">enum</span> <span class="kn">import</span> <span class="n">Enum</span>

  578. <span class="k">class</span> <span class="nc">Color</span><span class="p">(</span><span class="n">Enum</span><span class="p">):</span>

  579.     <span class="n">RED</span> <span class="o">=</span> <span class="s1">&#39;red&#39;</span>

  580.     <span class="n">GREEN</span> <span class="o">=</span> <span class="s1">&#39;green&#39;</span>

  581.     <span class="n">BLUE</span> <span class="o">=</span> <span class="s1">&#39;blue&#39;</span>

  582. 

  583. <span class="n">color</span> <span class="o">=</span> <span class="n">Color</span><span class="p">(</span><span class="nb">input</span><span class="p">(</span><span class="s2">&quot;Enter your choice of &#39;red&#39;, &#39;blue&#39; or &#39;green&#39;: &quot;</span><span class="p">))</span>

  584. 

  585. <span class="k">match</span> <span class="n">color</span><span class="p">:</span>

  586.     <span class="k">case</span> <span class="n">Color</span><span class="o">.</span><span class="n">RED</span><span class="p">:</span>

  587.         <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;I see red!&quot;</span><span class="p">)</span>

  588.     <span class="k">case</span> <span class="n">Color</span><span class="o">.</span><span class="n">GREEN</span><span class="p">:</span>

  589.         <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Grass is green&quot;</span><span class="p">)</span>

  590.     <span class="k">case</span> <span class="n">Color</span><span class="o">.</span><span class="n">BLUE</span><span class="p">:</span>

  591.         <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;I&#39;m feeling the blues :(&quot;</span><span class="p">)</span>

  592. </pre></div>

  593. </div>

  594. </li>

  595. </ul>

  596. <p>For a more detailed explanation and additional examples, you can look into

  597. <span class="target" id="index-1"></span><a class="pep reference external" href="https://peps.python.org/pep-0636/"><strong>PEP 636</strong></a> which is written in a tutorial format.</p>

  598. </section>

  599. <section id="defining-functions">

  600. <span id="tut-functions"></span><h2><span class="section-number">4.7. </span>Defining Functions<a class="headerlink" href="#defining-functions" title="Link to this heading">¶</a></h2>

  601. <p>We can create a function that writes the Fibonacci series to an arbitrary

  602. boundary:</p>

  603. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">def</span> <span class="nf">fib</span><span class="p">(</span><span class="n">n</span><span class="p">):</span>    <span class="c1"># write Fibonacci series up to n</span>

  604. <span class="gp">... </span><span class="w">    </span><span class="sd">&quot;&quot;&quot;Print a Fibonacci series up to n.&quot;&quot;&quot;</span>

  605. <span class="gp">... </span>    <span class="n">a</span><span class="p">,</span> <span class="n">b</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span>

  606. <span class="gp">... </span>    <span class="k">while</span> <span class="n">a</span> <span class="o">&lt;</span> <span class="n">n</span><span class="p">:</span>

  607. <span class="gp">... </span>        <span class="nb">print</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">end</span><span class="o">=</span><span class="s1">&#39; &#39;</span><span class="p">)</span>

  608. <span class="gp">... </span>        <span class="n">a</span><span class="p">,</span> <span class="n">b</span> <span class="o">=</span> <span class="n">b</span><span class="p">,</span> <span class="n">a</span><span class="o">+</span><span class="n">b</span>

  609. <span class="gp">... </span>    <span class="nb">print</span><span class="p">()</span>

  610. <span class="gp">...</span>

  611. <span class="gp">&gt;&gt;&gt; </span><span class="c1"># Now call the function we just defined:</span>

  612. <span class="gp">... </span><span class="n">fib</span><span class="p">(</span><span class="mi">2000</span><span class="p">)</span>

  613. <span class="go">0 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 1597</span>

  614. </pre></div>

  615. </div>

  616. <p id="index-2">The keyword <a class="reference internal" href="../reference/compound_stmts.html#def"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">def</span></code></a> introduces a function <em>definition</em>.  It must be

  617. followed by the function name and the parenthesized list of formal parameters.

  618. The statements that form the body of the function start at the next line, and

  619. must be indented.</p>

  620. <p>The first statement of the function body can optionally be a string literal;

  621. this string literal is the function’s documentation string, or <em class="dfn">docstring</em>.

  622. (More about docstrings can be found in the section <a class="reference internal" href="#tut-docstrings"><span class="std std-ref">Documentation Strings</span></a>.)

  623. There are tools which use docstrings to automatically produce online or printed

  624. documentation, or to let the user interactively browse through code; it’s good

  625. practice to include docstrings in code that you write, so make a habit of it.</p>

  626. <p>The <em>execution</em> of a function introduces a new symbol table used for the local

  627. variables of the function.  More precisely, all variable assignments in a

  628. function store the value in the local symbol table; whereas variable references

  629. first look in the local symbol table, then in the local symbol tables of

  630. enclosing functions, then in the global symbol table, and finally in the table

  631. of built-in names. Thus, global variables and variables of enclosing functions

  632. cannot be directly assigned a value within a function (unless, for global

  633. variables, named in a <a class="reference internal" href="../reference/simple_stmts.html#global"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">global</span></code></a> statement, or, for variables of enclosing

  634. functions, named in a <a class="reference internal" href="../reference/simple_stmts.html#nonlocal"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">nonlocal</span></code></a> statement), although they may be

  635. referenced.</p>

  636. <p>The actual parameters (arguments) to a function call are introduced in the local

  637. symbol table of the called function when it is called; thus, arguments are

  638. passed using <em>call by value</em> (where the <em>value</em> is always an object <em>reference</em>,

  639. not the value of the object). <a class="footnote-reference brackets" href="#id2" id="id1" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a> When a function calls another function,

  640. or calls itself recursively, a new

  641. local symbol table is created for that call.</p>

  642. <p>A function definition associates the function name with the function object in

  643. the current symbol table.  The interpreter recognizes the object pointed to by

  644. that name as a user-defined function.  Other names can also point to that same

  645. function object and can also be used to access the function:</p>

  646. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">fib</span>

  647. <span class="go">&lt;function fib at 10042ed0&gt;</span>

  648. <span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">fib</span>

  649. <span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="p">(</span><span class="mi">100</span><span class="p">)</span>

  650. <span class="go">0 1 1 2 3 5 8 13 21 34 55 89</span>

  651. </pre></div>

  652. </div>

  653. <p>Coming from other languages, you might object that <code class="docutils literal notranslate"><span class="pre">fib</span></code> is not a function but

  654. a procedure since it doesn’t return a value.  In fact, even functions without a

  655. <a class="reference internal" href="../reference/simple_stmts.html#return"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">return</span></code></a> statement do return a value, albeit a rather boring one.  This

  656. value is called <code class="docutils literal notranslate"><span class="pre">None</span></code> (it’s a built-in name).  Writing the value <code class="docutils literal notranslate"><span class="pre">None</span></code> is

  657. normally suppressed by the interpreter if it would be the only value written.

  658. You can see it if you really want to using <a class="reference internal" href="../library/functions.html#print" title="print"><code class="xref py py-func docutils literal notranslate"><span class="pre">print()</span></code></a>:</p>

  659. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">fib</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span>

  660. <span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">fib</span><span class="p">(</span><span class="mi">0</span><span class="p">))</span>

  661. <span class="go">None</span>

  662. </pre></div>

  663. </div>

  664. <p>It is simple to write a function that returns a list of the numbers of the

  665. Fibonacci series, instead of printing it:</p>

  666. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">def</span> <span class="nf">fib2</span><span class="p">(</span><span class="n">n</span><span class="p">):</span>  <span class="c1"># return Fibonacci series up to n</span>

  667. <span class="gp">... </span><span class="w">    </span><span class="sd">&quot;&quot;&quot;Return a list containing the Fibonacci series up to n.&quot;&quot;&quot;</span>

  668. <span class="gp">... </span>    <span class="n">result</span> <span class="o">=</span> <span class="p">[]</span>

  669. <span class="gp">... </span>    <span class="n">a</span><span class="p">,</span> <span class="n">b</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span>

  670. <span class="gp">... </span>    <span class="k">while</span> <span class="n">a</span> <span class="o">&lt;</span> <span class="n">n</span><span class="p">:</span>

  671. <span class="gp">... </span>        <span class="n">result</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">a</span><span class="p">)</span>    <span class="c1"># see below</span>

  672. <span class="gp">... </span>        <span class="n">a</span><span class="p">,</span> <span class="n">b</span> <span class="o">=</span> <span class="n">b</span><span class="p">,</span> <span class="n">a</span><span class="o">+</span><span class="n">b</span>

  673. <span class="gp">... </span>    <span class="k">return</span> <span class="n">result</span>

  674. <span class="gp">...</span>

  675. <span class="gp">&gt;&gt;&gt; </span><span class="n">f100</span> <span class="o">=</span> <span class="n">fib2</span><span class="p">(</span><span class="mi">100</span><span class="p">)</span>    <span class="c1"># call it</span>

  676. <span class="gp">&gt;&gt;&gt; </span><span class="n">f100</span>                <span class="c1"># write the result</span>

  677. <span class="go">[0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]</span>

  678. </pre></div>

  679. </div>

  680. <p>This example, as usual, demonstrates some new Python features:</p>

  681. <ul class="simple">

  682. <li><p>The <a class="reference internal" href="../reference/simple_stmts.html#return"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">return</span></code></a> statement returns with a value from a function.

  683. <code class="xref std std-keyword docutils literal notranslate"><span class="pre">return</span></code> without an expression argument returns <code class="docutils literal notranslate"><span class="pre">None</span></code>. Falling off

  684. the end of a function also returns <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p></li>

  685. <li><p>The statement <code class="docutils literal notranslate"><span class="pre">result.append(a)</span></code> calls a <em>method</em> of the list object

  686. <code class="docutils literal notranslate"><span class="pre">result</span></code>.  A method is a function that ‘belongs’ to an object and is named

  687. <code class="docutils literal notranslate"><span class="pre">obj.methodname</span></code>, where <code class="docutils literal notranslate"><span class="pre">obj</span></code> is some object (this may be an expression),

  688. and <code class="docutils literal notranslate"><span class="pre">methodname</span></code> is the name of a method that is defined by the object’s type.

  689. Different types define different methods.  Methods of different types may have

  690. the same name without causing ambiguity.  (It is possible to define your own

  691. object types and methods, using <em>classes</em>, see <a class="reference internal" href="classes.html#tut-classes"><span class="std std-ref">Classes</span></a>)

  692. The method <code class="xref py py-meth docutils literal notranslate"><span class="pre">append()</span></code> shown in the example is defined for list objects; it

  693. adds a new element at the end of the list.  In this example it is equivalent to

  694. <code class="docutils literal notranslate"><span class="pre">result</span> <span class="pre">=</span> <span class="pre">result</span> <span class="pre">+</span> <span class="pre">[a]</span></code>, but more efficient.</p></li>

  695. </ul>

  696. </section>

  697. <section id="more-on-defining-functions">

  698. <span id="tut-defining"></span><h2><span class="section-number">4.8. </span>More on Defining Functions<a class="headerlink" href="#more-on-defining-functions" title="Link to this heading">¶</a></h2>

  699. <p>It is also possible to define functions with a variable number of arguments.

  700. There are three forms, which can be combined.</p>

  701. <section id="default-argument-values">

  702. <span id="tut-defaultargs"></span><h3><span class="section-number">4.8.1. </span>Default Argument Values<a class="headerlink" href="#default-argument-values" title="Link to this heading">¶</a></h3>

  703. <p>The most useful form is to specify a default value for one or more arguments.

  704. This creates a function that can be called with fewer arguments than it is

  705. defined to allow.  For example:</p>

  706. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">ask_ok</span><span class="p">(</span><span class="n">prompt</span><span class="p">,</span> <span class="n">retries</span><span class="o">=</span><span class="mi">4</span><span class="p">,</span> <span class="n">reminder</span><span class="o">=</span><span class="s1">&#39;Please try again!&#39;</span><span class="p">):</span>

  707.     <span class="k">while</span> <span class="kc">True</span><span class="p">:</span>

  708.         <span class="n">reply</span> <span class="o">=</span> <span class="nb">input</span><span class="p">(</span><span class="n">prompt</span><span class="p">)</span>

  709.         <span class="k">if</span> <span class="n">reply</span> <span class="ow">in</span> <span class="p">{</span><span class="s1">&#39;y&#39;</span><span class="p">,</span> <span class="s1">&#39;ye&#39;</span><span class="p">,</span> <span class="s1">&#39;yes&#39;</span><span class="p">}:</span>

  710.             <span class="k">return</span> <span class="kc">True</span>

  711.         <span class="k">if</span> <span class="n">reply</span> <span class="ow">in</span> <span class="p">{</span><span class="s1">&#39;n&#39;</span><span class="p">,</span> <span class="s1">&#39;no&#39;</span><span class="p">,</span> <span class="s1">&#39;nop&#39;</span><span class="p">,</span> <span class="s1">&#39;nope&#39;</span><span class="p">}:</span>

  712.             <span class="k">return</span> <span class="kc">False</span>

  713.         <span class="n">retries</span> <span class="o">=</span> <span class="n">retries</span> <span class="o">-</span> <span class="mi">1</span>

  714.         <span class="k">if</span> <span class="n">retries</span> <span class="o">&lt;</span> <span class="mi">0</span><span class="p">:</span>

  715.             <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s1">&#39;invalid user response&#39;</span><span class="p">)</span>

  716.         <span class="nb">print</span><span class="p">(</span><span class="n">reminder</span><span class="p">)</span>

  717. </pre></div>

  718. </div>

  719. <p>This function can be called in several ways:</p>

  720. <ul class="simple">

  721. <li><p>giving only the mandatory argument:

  722. <code class="docutils literal notranslate"><span class="pre">ask_ok('Do</span> <span class="pre">you</span> <span class="pre">really</span> <span class="pre">want</span> <span class="pre">to</span> <span class="pre">quit?')</span></code></p></li>

  723. <li><p>giving one of the optional arguments:

  724. <code class="docutils literal notranslate"><span class="pre">ask_ok('OK</span> <span class="pre">to</span> <span class="pre">overwrite</span> <span class="pre">the</span> <span class="pre">file?',</span> <span class="pre">2)</span></code></p></li>

  725. <li><p>or even giving all arguments:

  726. <code class="docutils literal notranslate"><span class="pre">ask_ok('OK</span> <span class="pre">to</span> <span class="pre">overwrite</span> <span class="pre">the</span> <span class="pre">file?',</span> <span class="pre">2,</span> <span class="pre">'Come</span> <span class="pre">on,</span> <span class="pre">only</span> <span class="pre">yes</span> <span class="pre">or</span> <span class="pre">no!')</span></code></p></li>

  727. </ul>

  728. <p>This example also introduces the <a class="reference internal" href="../reference/expressions.html#in"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">in</span></code></a> keyword. This tests whether or

  729. not a sequence contains a certain value.</p>

  730. <p>The default values are evaluated at the point of function definition in the

  731. <em>defining</em> scope, so that</p>

  732. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">i</span> <span class="o">=</span> <span class="mi">5</span>

  733. 

  734. <span class="k">def</span> <span class="nf">f</span><span class="p">(</span><span class="n">arg</span><span class="o">=</span><span class="n">i</span><span class="p">):</span>

  735.     <span class="nb">print</span><span class="p">(</span><span class="n">arg</span><span class="p">)</span>

  736. 

  737. <span class="n">i</span> <span class="o">=</span> <span class="mi">6</span>

  738. <span class="n">f</span><span class="p">()</span>

  739. </pre></div>

  740. </div>

  741. <p>will print <code class="docutils literal notranslate"><span class="pre">5</span></code>.</p>

  742. <p><strong>Important warning:</strong>  The default value is evaluated only once. This makes a

  743. difference when the default is a mutable object such as a list, dictionary, or

  744. instances of most classes.  For example, the following function accumulates the

  745. arguments passed to it on subsequent calls:</p>

  746. <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">a</span><span class="p">,</span> <span class="n">L</span><span class="o">=</span><span class="p">[]):</span>

  747.     <span class="n">L</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">a</span><span class="p">)</span>

  748.     <span class="k">return</span> <span class="n">L</span>

  749. 

  750. <span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="p">(</span><span class="mi">1</span><span class="p">))</span>

  751. <span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="p">(</span><span class="mi">2</span><span class="p">))</span>

  752. <span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="p">(</span><span class="mi">3</span><span class="p">))</span>

  753. </pre></div>

  754. </div>

  755. <p>This will print</p>

  756. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="p">[</span><span class="mi">1</span><span class="p">]</span>

  757. <span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">]</span>

  758. <span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">]</span>

  759. </pre></div>

  760. </div>

  761. <p>If you don’t want the default to be shared between subsequent calls, you can

  762. write the function like this instead:</p>

  763. <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">a</span><span class="p">,</span> <span class="n">L</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>

  764.     <span class="k">if</span> <span class="n">L</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>

  765.         <span class="n">L</span> <span class="o">=</span> <span class="p">[]</span>

  766.     <span class="n">L</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">a</span><span class="p">)</span>

  767.     <span class="k">return</span> <span class="n">L</span>

  768. </pre></div>

  769. </div>

  770. </section>

  771. <section id="keyword-arguments">

  772. <span id="tut-keywordargs"></span><h3><span class="section-number">4.8.2. </span>Keyword Arguments<a class="headerlink" href="#keyword-arguments" title="Link to this heading">¶</a></h3>

  773. <p>Functions can also be called using <a class="reference internal" href="../glossary.html#term-keyword-argument"><span class="xref std std-term">keyword arguments</span></a>

  774. of the form <code class="docutils literal notranslate"><span class="pre">kwarg=value</span></code>.  For instance, the following function:</p>

  775. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">parrot</span><span class="p">(</span><span class="n">voltage</span><span class="p">,</span> <span class="n">state</span><span class="o">=</span><span class="s1">&#39;a stiff&#39;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">&#39;voom&#39;</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="s1">&#39;Norwegian Blue&#39;</span><span class="p">):</span>

  776.     <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;-- This parrot wouldn&#39;t&quot;</span><span class="p">,</span> <span class="n">action</span><span class="p">,</span> <span class="n">end</span><span class="o">=</span><span class="s1">&#39; &#39;</span><span class="p">)</span>

  777.     <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;if you put&quot;</span><span class="p">,</span> <span class="n">voltage</span><span class="p">,</span> <span class="s2">&quot;volts through it.&quot;</span><span class="p">)</span>

  778.     <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;-- Lovely plumage, the&quot;</span><span class="p">,</span> <span class="nb">type</span><span class="p">)</span>

  779.     <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;-- It&#39;s&quot;</span><span class="p">,</span> <span class="n">state</span><span class="p">,</span> <span class="s2">&quot;!&quot;</span><span class="p">)</span>

  780. </pre></div>

  781. </div>

  782. <p>accepts one required argument (<code class="docutils literal notranslate"><span class="pre">voltage</span></code>) and three optional arguments

  783. (<code class="docutils literal notranslate"><span class="pre">state</span></code>, <code class="docutils literal notranslate"><span class="pre">action</span></code>, and <code class="docutils literal notranslate"><span class="pre">type</span></code>).  This function can be called in any

  784. of the following ways:</p>

  785. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">parrot</span><span class="p">(</span><span class="mi">1000</span><span class="p">)</span>                                          <span class="c1"># 1 positional argument</span>

  786. <span class="n">parrot</span><span class="p">(</span><span class="n">voltage</span><span class="o">=</span><span class="mi">1000</span><span class="p">)</span>                                  <span class="c1"># 1 keyword argument</span>

  787. <span class="n">parrot</span><span class="p">(</span><span class="n">voltage</span><span class="o">=</span><span class="mi">1000000</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">&#39;VOOOOOM&#39;</span><span class="p">)</span>             <span class="c1"># 2 keyword arguments</span>

  788. <span class="n">parrot</span><span class="p">(</span><span class="n">action</span><span class="o">=</span><span class="s1">&#39;VOOOOOM&#39;</span><span class="p">,</span> <span class="n">voltage</span><span class="o">=</span><span class="mi">1000000</span><span class="p">)</span>             <span class="c1"># 2 keyword arguments</span>

  789. <span class="n">parrot</span><span class="p">(</span><span class="s1">&#39;a million&#39;</span><span class="p">,</span> <span class="s1">&#39;bereft of life&#39;</span><span class="p">,</span> <span class="s1">&#39;jump&#39;</span><span class="p">)</span>         <span class="c1"># 3 positional arguments</span>

  790. <span class="n">parrot</span><span class="p">(</span><span class="s1">&#39;a thousand&#39;</span><span class="p">,</span> <span class="n">state</span><span class="o">=</span><span class="s1">&#39;pushing up the daisies&#39;</span><span class="p">)</span>  <span class="c1"># 1 positional, 1 keyword</span>

  791. </pre></div>

  792. </div>

  793. <p>but all the following calls would be invalid:</p>

  794. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">parrot</span><span class="p">()</span>                     <span class="c1"># required argument missing</span>

  795. <span class="n">parrot</span><span class="p">(</span><span class="n">voltage</span><span class="o">=</span><span class="mf">5.0</span><span class="p">,</span> <span class="s1">&#39;dead&#39;</span><span class="p">)</span>  <span class="c1"># non-keyword argument after a keyword argument</span>

  796. <span class="n">parrot</span><span class="p">(</span><span class="mi">110</span><span class="p">,</span> <span class="n">voltage</span><span class="o">=</span><span class="mi">220</span><span class="p">)</span>     <span class="c1"># duplicate value for the same argument</span>

  797. <span class="n">parrot</span><span class="p">(</span><span class="n">actor</span><span class="o">=</span><span class="s1">&#39;John Cleese&#39;</span><span class="p">)</span>  <span class="c1"># unknown keyword argument</span>

  798. </pre></div>

  799. </div>

  800. <p>In a function call, keyword arguments must follow positional arguments.

  801. All the keyword arguments passed must match one of the arguments

  802. accepted by the function (e.g. <code class="docutils literal notranslate"><span class="pre">actor</span></code> is not a valid argument for the

  803. <code class="docutils literal notranslate"><span class="pre">parrot</span></code> function), and their order is not important.  This also includes

  804. non-optional arguments (e.g. <code class="docutils literal notranslate"><span class="pre">parrot(voltage=1000)</span></code> is valid too).

  805. No argument may receive a value more than once.

  806. Here’s an example that fails due to this restriction:</p>

  807. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">def</span> <span class="nf">function</span><span class="p">(</span><span class="n">a</span><span class="p">):</span>

  808. <span class="gp">... </span>    <span class="k">pass</span>

  809. <span class="gp">...</span>

  810. <span class="gp">&gt;&gt;&gt; </span><span class="n">function</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="n">a</span><span class="o">=</span><span class="mi">0</span><span class="p">)</span>

  811. <span class="gt">Traceback (most recent call last):</span>

  812.   File <span class="nb">&quot;&lt;stdin&gt;&quot;</span>, line <span class="m">1</span>, in <span class="n">&lt;module&gt;</span>

  813. <span class="gr">TypeError</span>: <span class="n">function() got multiple values for argument &#39;a&#39;</span>

  814. </pre></div>

  815. </div>

  816. <p>When a final formal parameter of the form <code class="docutils literal notranslate"><span class="pre">**name</span></code> is present, it receives a

  817. dictionary (see <a class="reference internal" href="../library/stdtypes.html#typesmapping"><span class="std std-ref">Mapping Types — dict</span></a>) containing all keyword arguments except for

  818. those corresponding to a formal parameter.  This may be combined with a formal

  819. parameter of the form <code class="docutils literal notranslate"><span class="pre">*name</span></code> (described in the next subsection) which

  820. receives a <a class="reference internal" href="datastructures.html#tut-tuples"><span class="std std-ref">tuple</span></a> containing the positional

  821. arguments beyond the formal parameter list.  (<code class="docutils literal notranslate"><span class="pre">*name</span></code> must occur

  822. before <code class="docutils literal notranslate"><span class="pre">**name</span></code>.) For example, if we define a function like this:</p>

  823. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">cheeseshop</span><span class="p">(</span><span class="n">kind</span><span class="p">,</span> <span class="o">*</span><span class="n">arguments</span><span class="p">,</span> <span class="o">**</span><span class="n">keywords</span><span class="p">):</span>

  824.     <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;-- Do you have any&quot;</span><span class="p">,</span> <span class="n">kind</span><span class="p">,</span> <span class="s2">&quot;?&quot;</span><span class="p">)</span>

  825.     <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;-- I&#39;m sorry, we&#39;re all out of&quot;</span><span class="p">,</span> <span class="n">kind</span><span class="p">)</span>

  826.     <span class="k">for</span> <span class="n">arg</span> <span class="ow">in</span> <span class="n">arguments</span><span class="p">:</span>

  827.         <span class="nb">print</span><span class="p">(</span><span class="n">arg</span><span class="p">)</span>

  828.     <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;-&quot;</span> <span class="o">*</span> <span class="mi">40</span><span class="p">)</span>

  829.     <span class="k">for</span> <span class="n">kw</span> <span class="ow">in</span> <span class="n">keywords</span><span class="p">:</span>

  830.         <span class="nb">print</span><span class="p">(</span><span class="n">kw</span><span class="p">,</span> <span class="s2">&quot;:&quot;</span><span class="p">,</span> <span class="n">keywords</span><span class="p">[</span><span class="n">kw</span><span class="p">])</span>

  831. </pre></div>

  832. </div>

  833. <p>It could be called like this:</p>

  834. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">cheeseshop</span><span class="p">(</span><span class="s2">&quot;Limburger&quot;</span><span class="p">,</span> <span class="s2">&quot;It&#39;s very runny, sir.&quot;</span><span class="p">,</span>

  835.            <span class="s2">&quot;It&#39;s really very, VERY runny, sir.&quot;</span><span class="p">,</span>

  836.            <span class="n">shopkeeper</span><span class="o">=</span><span class="s2">&quot;Michael Palin&quot;</span><span class="p">,</span>

  837.            <span class="n">client</span><span class="o">=</span><span class="s2">&quot;John Cleese&quot;</span><span class="p">,</span>

  838.            <span class="n">sketch</span><span class="o">=</span><span class="s2">&quot;Cheese Shop Sketch&quot;</span><span class="p">)</span>

  839. </pre></div>

  840. </div>

  841. <p>and of course it would print:</p>

  842. <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>-- Do you have any Limburger ?

  843. -- I&#39;m sorry, we&#39;re all out of Limburger

  844. It&#39;s very runny, sir.

  845. It&#39;s really very, VERY runny, sir.

  846. ----------------------------------------

  847. shopkeeper : Michael Palin

  848. client : John Cleese

  849. sketch : Cheese Shop Sketch

  850. </pre></div>

  851. </div>

  852. <p>Note that the order in which the keyword arguments are printed is guaranteed

  853. to match the order in which they were provided in the function call.</p>

  854. </section>

  855. <section id="special-parameters">

  856. <h3><span class="section-number">4.8.3. </span>Special parameters<a class="headerlink" href="#special-parameters" title="Link to this heading">¶</a></h3>

  857. <p>By default, arguments may be passed to a Python function either by position

  858. or explicitly by keyword. For readability and performance, it makes sense to

  859. restrict the way arguments can be passed so that a developer need only look

  860. at the function definition to determine if items are passed by position, by

  861. position or keyword, or by keyword.</p>

  862. <p>A function definition may look like:</p>

  863. <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>def f(pos1, pos2, /, pos_or_kwd, *, kwd1, kwd2):

  864.       -----------    ----------     ----------

  865.         |             |                  |

  866.         |        Positional or keyword   |

  867.         |                                - Keyword only

  868.          -- Positional only

  869. </pre></div>

  870. </div>

  871. <p>where <code class="docutils literal notranslate"><span class="pre">/</span></code> and <code class="docutils literal notranslate"><span class="pre">*</span></code> are optional. If used, these symbols indicate the kind of

  872. parameter by how the arguments may be passed to the function:

  873. positional-only, positional-or-keyword, and keyword-only. Keyword parameters

  874. are also referred to as named parameters.</p>

  875. <section id="positional-or-keyword-arguments">

  876. <h4><span class="section-number">4.8.3.1. </span>Positional-or-Keyword Arguments<a class="headerlink" href="#positional-or-keyword-arguments" title="Link to this heading">¶</a></h4>

  877. <p>If <code class="docutils literal notranslate"><span class="pre">/</span></code> and <code class="docutils literal notranslate"><span class="pre">*</span></code> are not present in the function definition, arguments may

  878. be passed to a function by position or by keyword.</p>

  879. </section>

  880. <section id="positional-only-parameters">

  881. <h4><span class="section-number">4.8.3.2. </span>Positional-Only Parameters<a class="headerlink" href="#positional-only-parameters" title="Link to this heading">¶</a></h4>

  882. <p>Looking at this in a bit more detail, it is possible to mark certain parameters

  883. as <em>positional-only</em>. If <em>positional-only</em>, the parameters’ order matters, and

  884. the parameters cannot be passed by keyword. Positional-only parameters are

  885. placed before a <code class="docutils literal notranslate"><span class="pre">/</span></code> (forward-slash). The <code class="docutils literal notranslate"><span class="pre">/</span></code> is used to logically

  886. separate the positional-only parameters from the rest of the parameters.

  887. If there is no <code class="docutils literal notranslate"><span class="pre">/</span></code> in the function definition, there are no positional-only

  888. parameters.</p>

  889. <p>Parameters following the <code class="docutils literal notranslate"><span class="pre">/</span></code> may be <em>positional-or-keyword</em> or <em>keyword-only</em>.</p>

  890. </section>

  891. <section id="keyword-only-arguments">

  892. <h4><span class="section-number">4.8.3.3. </span>Keyword-Only Arguments<a class="headerlink" href="#keyword-only-arguments" title="Link to this heading">¶</a></h4>

  893. <p>To mark parameters as <em>keyword-only</em>, indicating the parameters must be passed

  894. by keyword argument, place an <code class="docutils literal notranslate"><span class="pre">*</span></code> in the arguments list just before the first

  895. <em>keyword-only</em> parameter.</p>

  896. </section>

  897. <section id="function-examples">

  898. <h4><span class="section-number">4.8.3.4. </span>Function Examples<a class="headerlink" href="#function-examples" title="Link to this heading">¶</a></h4>

  899. <p>Consider the following example function definitions paying close attention to the

  900. markers <code class="docutils literal notranslate"><span class="pre">/</span></code> and <code class="docutils literal notranslate"><span class="pre">*</span></code>:</p>

  901. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">def</span> <span class="nf">standard_arg</span><span class="p">(</span><span class="n">arg</span><span class="p">):</span>

  902. <span class="gp">... </span>    <span class="nb">print</span><span class="p">(</span><span class="n">arg</span><span class="p">)</span>

  903. <span class="gp">...</span>

  904. <span class="gp">&gt;&gt;&gt; </span><span class="k">def</span> <span class="nf">pos_only_arg</span><span class="p">(</span><span class="n">arg</span><span class="p">,</span> <span class="o">/</span><span class="p">):</span>

  905. <span class="gp">... </span>    <span class="nb">print</span><span class="p">(</span><span class="n">arg</span><span class="p">)</span>

  906. <span class="gp">...</span>

  907. <span class="gp">&gt;&gt;&gt; </span><span class="k">def</span> <span class="nf">kwd_only_arg</span><span class="p">(</span><span class="o">*</span><span class="p">,</span> <span class="n">arg</span><span class="p">):</span>

  908. <span class="gp">... </span>    <span class="nb">print</span><span class="p">(</span><span class="n">arg</span><span class="p">)</span>

  909. <span class="gp">...</span>

  910. <span class="gp">&gt;&gt;&gt; </span><span class="k">def</span> <span class="nf">combined_example</span><span class="p">(</span><span class="n">pos_only</span><span class="p">,</span> <span class="o">/</span><span class="p">,</span> <span class="n">standard</span><span class="p">,</span> <span class="o">*</span><span class="p">,</span> <span class="n">kwd_only</span><span class="p">):</span>

  911. <span class="gp">... </span>    <span class="nb">print</span><span class="p">(</span><span class="n">pos_only</span><span class="p">,</span> <span class="n">standard</span><span class="p">,</span> <span class="n">kwd_only</span><span class="p">)</span>

  912. </pre></div>

  913. </div>

  914. <p>The first function definition, <code class="docutils literal notranslate"><span class="pre">standard_arg</span></code>, the most familiar form,

  915. places no restrictions on the calling convention and arguments may be

  916. passed by position or keyword:</p>

  917. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">standard_arg</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span>

  918. <span class="go">2</span>

  919. 

  920. <span class="gp">&gt;&gt;&gt; </span><span class="n">standard_arg</span><span class="p">(</span><span class="n">arg</span><span class="o">=</span><span class="mi">2</span><span class="p">)</span>

  921. <span class="go">2</span>

  922. </pre></div>

  923. </div>

  924. <p>The second function <code class="docutils literal notranslate"><span class="pre">pos_only_arg</span></code> is restricted to only use positional

  925. parameters as there is a <code class="docutils literal notranslate"><span class="pre">/</span></code> in the function definition:</p>

  926. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">pos_only_arg</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>

  927. <span class="go">1</span>

  928. 

  929. <span class="gp">&gt;&gt;&gt; </span><span class="n">pos_only_arg</span><span class="p">(</span><span class="n">arg</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span>

  930. <span class="gt">Traceback (most recent call last):</span>

  931.   File <span class="nb">&quot;&lt;stdin&gt;&quot;</span>, line <span class="m">1</span>, in <span class="n">&lt;module&gt;</span>

  932. <span class="gr">TypeError</span>: <span class="n">pos_only_arg() got some positional-only arguments passed as keyword arguments: &#39;arg&#39;</span>

  933. </pre></div>

  934. </div>

  935. <p>The third function <code class="docutils literal notranslate"><span class="pre">kwd_only_args</span></code> only allows keyword arguments as indicated

  936. by a <code class="docutils literal notranslate"><span class="pre">*</span></code> in the function definition:</p>

  937. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">kwd_only_arg</span><span class="p">(</span><span class="mi">3</span><span class="p">)</span>

  938. <span class="gt">Traceback (most recent call last):</span>

  939.   File <span class="nb">&quot;&lt;stdin&gt;&quot;</span>, line <span class="m">1</span>, in <span class="n">&lt;module&gt;</span>

  940. <span class="gr">TypeError</span>: <span class="n">kwd_only_arg() takes 0 positional arguments but 1 was given</span>

  941. 

  942. <span class="gp">&gt;&gt;&gt; </span><span class="n">kwd_only_arg</span><span class="p">(</span><span class="n">arg</span><span class="o">=</span><span class="mi">3</span><span class="p">)</span>

  943. <span class="go">3</span>

  944. </pre></div>

  945. </div>

  946. <p>And the last uses all three calling conventions in the same function

  947. definition:</p>

  948. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">combined_example</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">)</span>

  949. <span class="gt">Traceback (most recent call last):</span>

  950.   File <span class="nb">&quot;&lt;stdin&gt;&quot;</span>, line <span class="m">1</span>, in <span class="n">&lt;module&gt;</span>

  951. <span class="gr">TypeError</span>: <span class="n">combined_example() takes 2 positional arguments but 3 were given</span>

  952. 

  953. <span class="gp">&gt;&gt;&gt; </span><span class="n">combined_example</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="n">kwd_only</span><span class="o">=</span><span class="mi">3</span><span class="p">)</span>

  954. <span class="go">1 2 3</span>

  955. 

  956. <span class="gp">&gt;&gt;&gt; </span><span class="n">combined_example</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="n">standard</span><span class="o">=</span><span class="mi">2</span><span class="p">,</span> <span class="n">kwd_only</span><span class="o">=</span><span class="mi">3</span><span class="p">)</span>

  957. <span class="go">1 2 3</span>

  958. 

  959. <span class="gp">&gt;&gt;&gt; </span><span class="n">combined_example</span><span class="p">(</span><span class="n">pos_only</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">standard</span><span class="o">=</span><span class="mi">2</span><span class="p">,</span> <span class="n">kwd_only</span><span class="o">=</span><span class="mi">3</span><span class="p">)</span>

  960. <span class="gt">Traceback (most recent call last):</span>

  961.   File <span class="nb">&quot;&lt;stdin&gt;&quot;</span>, line <span class="m">1</span>, in <span class="n">&lt;module&gt;</span>

  962. <span class="gr">TypeError</span>: <span class="n">combined_example() got some positional-only arguments passed as keyword arguments: &#39;pos_only&#39;</span>

  963. </pre></div>

  964. </div>

  965. <p>Finally, consider this function definition which has a potential collision between the positional argument <code class="docutils literal notranslate"><span class="pre">name</span></code>  and <code class="docutils literal notranslate"><span class="pre">**kwds</span></code> which has <code class="docutils literal notranslate"><span class="pre">name</span></code> as a key:</p>

  966. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">foo</span><span class="p">(</span><span class="n">name</span><span class="p">,</span> <span class="o">**</span><span class="n">kwds</span><span class="p">):</span>

  967.     <span class="k">return</span> <span class="s1">&#39;name&#39;</span> <span class="ow">in</span> <span class="n">kwds</span>

  968. </pre></div>

  969. </div>

  970. <p>There is no possible call that will make it return <code class="docutils literal notranslate"><span class="pre">True</span></code> as the keyword <code class="docutils literal notranslate"><span class="pre">'name'</span></code>

  971. will always bind to the first parameter. For example:</p>

  972. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">foo</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="o">**</span><span class="p">{</span><span class="s1">&#39;name&#39;</span><span class="p">:</span> <span class="mi">2</span><span class="p">})</span>

  973. <span class="gt">Traceback (most recent call last):</span>

  974.   File <span class="nb">&quot;&lt;stdin&gt;&quot;</span>, line <span class="m">1</span>, in <span class="n">&lt;module&gt;</span>

  975. <span class="gr">TypeError</span>: <span class="n">foo() got multiple values for argument &#39;name&#39;</span>

  976. <span class="gp">&gt;&gt;&gt;</span>

  977. </pre></div>

  978. </div>

  979. <p>But using <code class="docutils literal notranslate"><span class="pre">/</span></code> (positional only arguments), it is possible since it allows <code class="docutils literal notranslate"><span class="pre">name</span></code> as a positional argument and <code class="docutils literal notranslate"><span class="pre">'name'</span></code> as a key in the keyword arguments:</p>

  980. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">def</span> <span class="nf">foo</span><span class="p">(</span><span class="n">name</span><span class="p">,</span> <span class="o">/</span><span class="p">,</span> <span class="o">**</span><span class="n">kwds</span><span class="p">):</span>

  981. <span class="gp">... </span>    <span class="k">return</span> <span class="s1">&#39;name&#39;</span> <span class="ow">in</span> <span class="n">kwds</span>

  982. <span class="gp">...</span>

  983. <span class="gp">&gt;&gt;&gt; </span><span class="n">foo</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="o">**</span><span class="p">{</span><span class="s1">&#39;name&#39;</span><span class="p">:</span> <span class="mi">2</span><span class="p">})</span>

  984. <span class="go">True</span>

  985. </pre></div>

  986. </div>

  987. <p>In other words, the names of positional-only parameters can be used in

  988. <code class="docutils literal notranslate"><span class="pre">**kwds</span></code> without ambiguity.</p>

  989. </section>

  990. <section id="recap">

  991. <h4><span class="section-number">4.8.3.5. </span>Recap<a class="headerlink" href="#recap" title="Link to this heading">¶</a></h4>

  992. <p>The use case will determine which parameters to use in the function definition:</p>

  993. <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">pos1</span><span class="p">,</span> <span class="n">pos2</span><span class="p">,</span> <span class="o">/</span><span class="p">,</span> <span class="n">pos_or_kwd</span><span class="p">,</span> <span class="o">*</span><span class="p">,</span> <span class="n">kwd1</span><span class="p">,</span> <span class="n">kwd2</span><span class="p">):</span>

  994. </pre></div>

  995. </div>

  996. <p>As guidance:</p>

  997. <ul class="simple">

  998. <li><p>Use positional-only if you want the name of the parameters to not be

  999. available to the user. This is useful when parameter names have no real

  1000. meaning, if you want to enforce the order of the arguments when the function

  1001. is called or if you need to take some positional parameters and arbitrary

  1002. keywords.</p></li>

  1003. <li><p>Use keyword-only when names have meaning and the function definition is

  1004. more understandable by being explicit with names or you want to prevent

  1005. users relying on the position of the argument being passed.</p></li>

  1006. <li><p>For an API, use positional-only to prevent breaking API changes

  1007. if the parameter’s name is modified in the future.</p></li>

  1008. </ul>

  1009. </section>

  1010. </section>

  1011. <section id="arbitrary-argument-lists">

  1012. <span id="tut-arbitraryargs"></span><h3><span class="section-number">4.8.4. </span>Arbitrary Argument Lists<a class="headerlink" href="#arbitrary-argument-lists" title="Link to this heading">¶</a></h3>

  1013. <p id="index-3">Finally, the least frequently used option is to specify that a function can be

  1014. called with an arbitrary number of arguments.  These arguments will be wrapped

  1015. up in a tuple (see <a class="reference internal" href="datastructures.html#tut-tuples"><span class="std std-ref">Tuples and Sequences</span></a>).  Before the variable number of arguments,

  1016. zero or more normal arguments may occur.</p>

  1017. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">write_multiple_items</span><span class="p">(</span><span class="n">file</span><span class="p">,</span> <span class="n">separator</span><span class="p">,</span> <span class="o">*</span><span class="n">args</span><span class="p">):</span>

  1018.     <span class="n">file</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="n">separator</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">args</span><span class="p">))</span>

  1019. </pre></div>

  1020. </div>

  1021. <p>Normally, these <em>variadic</em> arguments will be last in the list of formal

  1022. parameters, because they scoop up all remaining input arguments that are

  1023. passed to the function. Any formal parameters which occur after the <code class="docutils literal notranslate"><span class="pre">*args</span></code>

  1024. parameter are ‘keyword-only’ arguments, meaning that they can only be used as

  1025. keywords rather than positional arguments.</p>

  1026. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">def</span> <span class="nf">concat</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="n">sep</span><span class="o">=</span><span class="s2">&quot;/&quot;</span><span class="p">):</span>

  1027. <span class="gp">... </span>    <span class="k">return</span> <span class="n">sep</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">args</span><span class="p">)</span>

  1028. <span class="gp">...</span>

  1029. <span class="gp">&gt;&gt;&gt; </span><span class="n">concat</span><span class="p">(</span><span class="s2">&quot;earth&quot;</span><span class="p">,</span> <span class="s2">&quot;mars&quot;</span><span class="p">,</span> <span class="s2">&quot;venus&quot;</span><span class="p">)</span>

  1030. <span class="go">&#39;earth/mars/venus&#39;</span>

  1031. <span class="gp">&gt;&gt;&gt; </span><span class="n">concat</span><span class="p">(</span><span class="s2">&quot;earth&quot;</span><span class="p">,</span> <span class="s2">&quot;mars&quot;</span><span class="p">,</span> <span class="s2">&quot;venus&quot;</span><span class="p">,</span> <span class="n">sep</span><span class="o">=</span><span class="s2">&quot;.&quot;</span><span class="p">)</span>

  1032. <span class="go">&#39;earth.mars.venus&#39;</span>

  1033. </pre></div>

  1034. </div>

  1035. </section>

  1036. <section id="unpacking-argument-lists">

  1037. <span id="tut-unpacking-arguments"></span><h3><span class="section-number">4.8.5. </span>Unpacking Argument Lists<a class="headerlink" href="#unpacking-argument-lists" title="Link to this heading">¶</a></h3>

  1038. <p>The reverse situation occurs when the arguments are already in a list or tuple

  1039. but need to be unpacked for a function call requiring separate positional

  1040. arguments.  For instance, the built-in <a class="reference internal" href="../library/stdtypes.html#range" title="range"><code class="xref py py-func docutils literal notranslate"><span class="pre">range()</span></code></a> function expects separate

  1041. <em>start</em> and <em>stop</em> arguments.  If they are not available separately, write the

  1042. function call with the  <code class="docutils literal notranslate"><span class="pre">*</span></code>-operator to unpack the arguments out of a list

  1043. or tuple:</p>

  1044. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="mi">3</span><span class="p">,</span> <span class="mi">6</span><span class="p">))</span>            <span class="c1"># normal call with separate arguments</span>

  1045. <span class="go">[3, 4, 5]</span>

  1046. <span class="gp">&gt;&gt;&gt; </span><span class="n">args</span> <span class="o">=</span> <span class="p">[</span><span class="mi">3</span><span class="p">,</span> <span class="mi">6</span><span class="p">]</span>

  1047. <span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">))</span>            <span class="c1"># call with arguments unpacked from a list</span>

  1048. <span class="go">[3, 4, 5]</span>

  1049. </pre></div>

  1050. </div>

  1051. <p id="index-4">In the same fashion, dictionaries can deliver keyword arguments with the

  1052. <code class="docutils literal notranslate"><span class="pre">**</span></code>-operator:</p>

  1053. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">def</span> <span class="nf">parrot</span><span class="p">(</span><span class="n">voltage</span><span class="p">,</span> <span class="n">state</span><span class="o">=</span><span class="s1">&#39;a stiff&#39;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">&#39;voom&#39;</span><span class="p">):</span>

  1054. <span class="gp">... </span>    <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;-- This parrot wouldn&#39;t&quot;</span><span class="p">,</span> <span class="n">action</span><span class="p">,</span> <span class="n">end</span><span class="o">=</span><span class="s1">&#39; &#39;</span><span class="p">)</span>

  1055. <span class="gp">... </span>    <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;if you put&quot;</span><span class="p">,</span> <span class="n">voltage</span><span class="p">,</span> <span class="s2">&quot;volts through it.&quot;</span><span class="p">,</span> <span class="n">end</span><span class="o">=</span><span class="s1">&#39; &#39;</span><span class="p">)</span>

  1056. <span class="gp">... </span>    <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;E&#39;s&quot;</span><span class="p">,</span> <span class="n">state</span><span class="p">,</span> <span class="s2">&quot;!&quot;</span><span class="p">)</span>

  1057. <span class="gp">...</span>

  1058. <span class="gp">&gt;&gt;&gt; </span><span class="n">d</span> <span class="o">=</span> <span class="p">{</span><span class="s2">&quot;voltage&quot;</span><span class="p">:</span> <span class="s2">&quot;four million&quot;</span><span class="p">,</span> <span class="s2">&quot;state&quot;</span><span class="p">:</span> <span class="s2">&quot;bleedin&#39; demised&quot;</span><span class="p">,</span> <span class="s2">&quot;action&quot;</span><span class="p">:</span> <span class="s2">&quot;VOOM&quot;</span><span class="p">}</span>

  1059. <span class="gp">&gt;&gt;&gt; </span><span class="n">parrot</span><span class="p">(</span><span class="o">**</span><span class="n">d</span><span class="p">)</span>

  1060. <span class="go">-- This parrot wouldn&#39;t VOOM if you put four million volts through it. E&#39;s bleedin&#39; demised !</span>

  1061. </pre></div>

  1062. </div>

  1063. </section>

  1064. <section id="lambda-expressions">

  1065. <span id="tut-lambda"></span><h3><span class="section-number">4.8.6. </span>Lambda Expressions<a class="headerlink" href="#lambda-expressions" title="Link to this heading">¶</a></h3>

  1066. <p>Small anonymous functions can be created with the <a class="reference internal" href="../reference/expressions.html#lambda"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">lambda</span></code></a> keyword.

  1067. This function returns the sum of its two arguments: <code class="docutils literal notranslate"><span class="pre">lambda</span> <span class="pre">a,</span> <span class="pre">b:</span> <span class="pre">a+b</span></code>.

  1068. Lambda functions can be used wherever function objects are required.  They are

  1069. syntactically restricted to a single expression.  Semantically, they are just

  1070. syntactic sugar for a normal function definition.  Like nested function

  1071. definitions, lambda functions can reference variables from the containing

  1072. scope:</p>

  1073. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">def</span> <span class="nf">make_incrementor</span><span class="p">(</span><span class="n">n</span><span class="p">):</span>

  1074. <span class="gp">... </span>    <span class="k">return</span> <span class="k">lambda</span> <span class="n">x</span><span class="p">:</span> <span class="n">x</span> <span class="o">+</span> <span class="n">n</span>

  1075. <span class="gp">...</span>

  1076. <span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">make_incrementor</span><span class="p">(</span><span class="mi">42</span><span class="p">)</span>

  1077. <span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span>

  1078. <span class="go">42</span>

  1079. <span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>

  1080. <span class="go">43</span>

  1081. </pre></div>

  1082. </div>

  1083. <p>The above example uses a lambda expression to return a function.  Another use

  1084. is to pass a small function as an argument:</p>

  1085. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">pairs</span> <span class="o">=</span> <span class="p">[(</span><span class="mi">1</span><span class="p">,</span> <span class="s1">&#39;one&#39;</span><span class="p">),</span> <span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="s1">&#39;two&#39;</span><span class="p">),</span> <span class="p">(</span><span class="mi">3</span><span class="p">,</span> <span class="s1">&#39;three&#39;</span><span class="p">),</span> <span class="p">(</span><span class="mi">4</span><span class="p">,</span> <span class="s1">&#39;four&#39;</span><span class="p">)]</span>

  1086. <span class="gp">&gt;&gt;&gt; </span><span class="n">pairs</span><span class="o">.</span><span class="n">sort</span><span class="p">(</span><span class="n">key</span><span class="o">=</span><span class="k">lambda</span> <span class="n">pair</span><span class="p">:</span> <span class="n">pair</span><span class="p">[</span><span class="mi">1</span><span class="p">])</span>

  1087. <span class="gp">&gt;&gt;&gt; </span><span class="n">pairs</span>

  1088. <span class="go">[(4, &#39;four&#39;), (1, &#39;one&#39;), (3, &#39;three&#39;), (2, &#39;two&#39;)]</span>

  1089. </pre></div>

  1090. </div>

  1091. </section>

  1092. <section id="documentation-strings">

  1093. <span id="tut-docstrings"></span><h3><span class="section-number">4.8.7. </span>Documentation Strings<a class="headerlink" href="#documentation-strings" title="Link to this heading">¶</a></h3>

  1094. <p id="index-5">Here are some conventions about the content and formatting of documentation

  1095. strings.</p>

  1096. <p>The first line should always be a short, concise summary of the object’s

  1097. purpose.  For brevity, it should not explicitly state the object’s name or type,

  1098. since these are available by other means (except if the name happens to be a

  1099. verb describing a function’s operation).  This line should begin with a capital

  1100. letter and end with a period.</p>

  1101. <p>If there are more lines in the documentation string, the second line should be

  1102. blank, visually separating the summary from the rest of the description.  The

  1103. following lines should be one or more paragraphs describing the object’s calling

  1104. conventions, its side effects, etc.</p>

  1105. <p>The Python parser does not strip indentation from multi-line string literals in

  1106. Python, so tools that process documentation have to strip indentation if

  1107. desired.  This is done using the following convention. The first non-blank line

  1108. <em>after</em> the first line of the string determines the amount of indentation for

  1109. the entire documentation string.  (We can’t use the first line since it is

  1110. generally adjacent to the string’s opening quotes so its indentation is not

  1111. apparent in the string literal.)  Whitespace “equivalent” to this indentation is

  1112. then stripped from the start of all lines of the string.  Lines that are

  1113. indented less should not occur, but if they occur all their leading whitespace

  1114. should be stripped.  Equivalence of whitespace should be tested after expansion

  1115. of tabs (to 8 spaces, normally).</p>

  1116. <p>Here is an example of a multi-line docstring:</p>

  1117. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">def</span> <span class="nf">my_function</span><span class="p">():</span>

  1118. <span class="gp">... </span><span class="w">    </span><span class="sd">&quot;&quot;&quot;Do nothing, but document it.</span>

  1119. <span class="gp">...</span>

  1120. <span class="gp">... </span><span class="sd">    No, really, it doesn&#39;t do anything.</span>

  1121. <span class="gp">... </span><span class="sd">    &quot;&quot;&quot;</span>

  1122. <span class="gp">... </span>    <span class="k">pass</span>

  1123. <span class="gp">...</span>

  1124. <span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">my_function</span><span class="o">.</span><span class="vm">__doc__</span><span class="p">)</span>

  1125. <span class="go">Do nothing, but document it.</span>

  1126. 

  1127. <span class="go">    No, really, it doesn&#39;t do anything.</span>

  1128. </pre></div>

  1129. </div>

  1130. </section>

  1131. <section id="function-annotations">

  1132. <span id="tut-annotations"></span><h3><span class="section-number">4.8.8. </span>Function Annotations<a class="headerlink" href="#function-annotations" title="Link to this heading">¶</a></h3>

  1133. <p id="index-6"><a class="reference internal" href="../reference/compound_stmts.html#function"><span class="std std-ref">Function annotations</span></a> are completely optional metadata

  1134. information about the types used by user-defined functions (see <span class="target" id="index-7"></span><a class="pep reference external" href="https://peps.python.org/pep-3107/"><strong>PEP 3107</strong></a> and

  1135. <span class="target" id="index-8"></span><a class="pep reference external" href="https://peps.python.org/pep-0484/"><strong>PEP 484</strong></a> for more information).</p>

  1136. <p><a class="reference internal" href="../glossary.html#term-function-annotation"><span class="xref std std-term">Annotations</span></a> are stored in the <code class="xref py py-attr docutils literal notranslate"><span class="pre">__annotations__</span></code>

  1137. attribute of the function as a dictionary and have no effect on any other part of the

  1138. function.  Parameter annotations are defined by a colon after the parameter name, followed

  1139. by an expression evaluating to the value of the annotation.  Return annotations are

  1140. defined by a literal <code class="docutils literal notranslate"><span class="pre">-&gt;</span></code>, followed by an expression, between the parameter

  1141. list and the colon denoting the end of the <a class="reference internal" href="../reference/compound_stmts.html#def"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">def</span></code></a> statement.  The

  1142. following example has a required argument, an optional argument, and the return

  1143. value annotated:</p>

  1144. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">def</span> <span class="nf">f</span><span class="p">(</span><span class="n">ham</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">eggs</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s1">&#39;eggs&#39;</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">str</span><span class="p">:</span>

  1145. <span class="gp">... </span>    <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Annotations:&quot;</span><span class="p">,</span> <span class="n">f</span><span class="o">.</span><span class="vm">__annotations__</span><span class="p">)</span>

  1146. <span class="gp">... </span>    <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Arguments:&quot;</span><span class="p">,</span> <span class="n">ham</span><span class="p">,</span> <span class="n">eggs</span><span class="p">)</span>

  1147. <span class="gp">... </span>    <span class="k">return</span> <span class="n">ham</span> <span class="o">+</span> <span class="s1">&#39; and &#39;</span> <span class="o">+</span> <span class="n">eggs</span>

  1148. <span class="gp">...</span>

  1149. <span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="p">(</span><span class="s1">&#39;spam&#39;</span><span class="p">)</span>

  1150. <span class="go">Annotations: {&#39;ham&#39;: &lt;class &#39;str&#39;&gt;, &#39;return&#39;: &lt;class &#39;str&#39;&gt;, &#39;eggs&#39;: &lt;class &#39;str&#39;&gt;}</span>

  1151. <span class="go">Arguments: spam eggs</span>

  1152. <span class="go">&#39;spam and eggs&#39;</span>

  1153. </pre></div>

  1154. </div>

  1155. </section>

  1156. </section>

  1157. <section id="intermezzo-coding-style">

  1158. <span id="tut-codingstyle"></span><h2><span class="section-number">4.9. </span>Intermezzo: Coding Style<a class="headerlink" href="#intermezzo-coding-style" title="Link to this heading">¶</a></h2>

  1159. <p id="index-9">Now that you are about to write longer, more complex pieces of Python, it is a

  1160. good time to talk about <em>coding style</em>.  Most languages can be written (or more

  1161. concise, <em>formatted</em>) in different styles; some are more readable than others.

  1162. Making it easy for others to read your code is always a good idea, and adopting

  1163. a nice coding style helps tremendously for that.</p>

  1164. <p>For Python, <span class="target" id="index-10"></span><a class="pep reference external" href="https://peps.python.org/pep-0008/"><strong>PEP 8</strong></a> has emerged as the style guide that most projects adhere to;

  1165. it promotes a very readable and eye-pleasing coding style.  Every Python

  1166. developer should read it at some point; here are the most important points

  1167. extracted for you:</p>

  1168. <ul>

  1169. <li><p>Use 4-space indentation, and no tabs.</p>

  1170. <p>4 spaces are a good compromise between small indentation (allows greater

  1171. nesting depth) and large indentation (easier to read).  Tabs introduce

  1172. confusion, and are best left out.</p>

  1173. </li>

  1174. <li><p>Wrap lines so that they don’t exceed 79 characters.</p>

  1175. <p>This helps users with small displays and makes it possible to have several

  1176. code files side-by-side on larger displays.</p>

  1177. </li>

  1178. <li><p>Use blank lines to separate functions and classes, and larger blocks of

  1179. code inside functions.</p></li>

  1180. <li><p>When possible, put comments on a line of their own.</p></li>

  1181. <li><p>Use docstrings.</p></li>

  1182. <li><p>Use spaces around operators and after commas, but not directly inside

  1183. bracketing constructs: <code class="docutils literal notranslate"><span class="pre">a</span> <span class="pre">=</span> <span class="pre">f(1,</span> <span class="pre">2)</span> <span class="pre">+</span> <span class="pre">g(3,</span> <span class="pre">4)</span></code>.</p></li>

  1184. <li><p>Name your classes and functions consistently; the convention is to use

  1185. <code class="docutils literal notranslate"><span class="pre">UpperCamelCase</span></code> for classes and <code class="docutils literal notranslate"><span class="pre">lowercase_with_underscores</span></code> for functions

  1186. and methods.  Always use <code class="docutils literal notranslate"><span class="pre">self</span></code> as the name for the first method argument

  1187. (see <a class="reference internal" href="classes.html#tut-firstclasses"><span class="std std-ref">A First Look at Classes</span></a> for more on classes and methods).</p></li>

  1188. <li><p>Don’t use fancy encodings if your code is meant to be used in international

  1189. environments.  Python’s default, UTF-8, or even plain ASCII work best in any

  1190. case.</p></li>

  1191. <li><p>Likewise, don’t use non-ASCII characters in identifiers if there is only the

  1192. slightest chance people speaking a different language will read or maintain

  1193. the code.</p></li>

  1194. </ul>

  1195. <p class="rubric">Footnotes</p>

  1196. <aside class="footnote-list brackets">

  1197. <aside class="footnote brackets" id="id2" role="doc-footnote">

  1198. <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id1">1</a><span class="fn-bracket">]</span></span>

  1199. <p>Actually, <em>call by object reference</em> would be a better description,

  1200. since if a mutable object is passed, the caller will see any changes the

  1201. callee makes to it (items inserted into a list).</p>

  1202. </aside>

  1203. </aside>

  1204. </section>

  1205. </section>

  1206. 

  1207. 

  1208.             <div class="clearer"></div>

  1209.           </div>

  1210.         </div>

  1211.       </div>

  1212.       <div class="sphinxsidebar" role="navigation" aria-label="main navigation">

  1213.         <div class="sphinxsidebarwrapper">

  1214.   <div>

  1215.     <h3><a href="../contents.html">Table of Contents</a></h3>

  1216.     <ul>

  1217. <li><a class="reference internal" href="#">4. More Control Flow Tools</a><ul>

  1218. <li><a class="reference internal" href="#if-statements">4.1. <code class="xref std std-keyword docutils literal notranslate"><span class="pre">if</span></code> Statements</a></li>

  1219. <li><a class="reference internal" href="#for-statements">4.2. <code class="xref std std-keyword docutils literal notranslate"><span class="pre">for</span></code> Statements</a></li>

  1220. <li><a class="reference internal" href="#the-range-function">4.3. The <code class="xref py py-func docutils literal notranslate"><span class="pre">range()</span></code> Function</a></li>

  1221. <li><a class="reference internal" href="#break-and-continue-statements-and-else-clauses-on-loops">4.4. <code class="xref std std-keyword docutils literal notranslate"><span class="pre">break</span></code> and <code class="xref std std-keyword docutils literal notranslate"><span class="pre">continue</span></code> Statements, and <code class="xref std std-keyword docutils literal notranslate"><span class="pre">else</span></code> Clauses on Loops</a></li>

  1222. <li><a class="reference internal" href="#pass-statements">4.5. <code class="xref std std-keyword docutils literal notranslate"><span class="pre">pass</span></code> Statements</a></li>

  1223. <li><a class="reference internal" href="#match-statements">4.6. <code class="xref std std-keyword docutils literal notranslate"><span class="pre">match</span></code> Statements</a></li>

  1224. <li><a class="reference internal" href="#defining-functions">4.7. Defining Functions</a></li>

  1225. <li><a class="reference internal" href="#more-on-defining-functions">4.8. More on Defining Functions</a><ul>

  1226. <li><a class="reference internal" href="#default-argument-values">4.8.1. Default Argument Values</a></li>

  1227. <li><a class="reference internal" href="#keyword-arguments">4.8.2. Keyword Arguments</a></li>

  1228. <li><a class="reference internal" href="#special-parameters">4.8.3. Special parameters</a><ul>

  1229. <li><a class="reference internal" href="#positional-or-keyword-arguments">4.8.3.1. Positional-or-Keyword Arguments</a></li>

  1230. <li><a class="reference internal" href="#positional-only-parameters">4.8.3.2. Positional-Only Parameters</a></li>

  1231. <li><a class="reference internal" href="#keyword-only-arguments">4.8.3.3. Keyword-Only Arguments</a></li>

  1232. <li><a class="reference internal" href="#function-examples">4.8.3.4. Function Examples</a></li>

  1233. <li><a class="reference internal" href="#recap">4.8.3.5. Recap</a></li>

  1234. </ul>

  1235. </li>

  1236. <li><a class="reference internal" href="#arbitrary-argument-lists">4.8.4. Arbitrary Argument Lists</a></li>

  1237. <li><a class="reference internal" href="#unpacking-argument-lists">4.8.5. Unpacking Argument Lists</a></li>

  1238. <li><a class="reference internal" href="#lambda-expressions">4.8.6. Lambda Expressions</a></li>

  1239. <li><a class="reference internal" href="#documentation-strings">4.8.7. Documentation Strings</a></li>

  1240. <li><a class="reference internal" href="#function-annotations">4.8.8. Function Annotations</a></li>

  1241. </ul>

  1242. </li>

  1243. <li><a class="reference internal" href="#intermezzo-coding-style">4.9. Intermezzo: Coding Style</a></li>

  1244. </ul>

  1245. </li>

  1246. </ul>

  1247. 

  1248.   </div>

  1249.   <div>

  1250.     <h4>Previous topic</h4>

  1251.     <p class="topless"><a href="introduction.html"

  1252.                           title="previous chapter"><span class="section-number">3. </span>An Informal Introduction to Python</a></p>

  1253.   </div>

  1254.   <div>

  1255.     <h4>Next topic</h4>

  1256.     <p class="topless"><a href="datastructures.html"

  1257.                           title="next chapter"><span class="section-number">5. </span>Data Structures</a></p>

  1258.   </div>

  1259.   <div role="note" aria-label="source link">

  1260.     <h3>This Page</h3>

  1261.     <ul class="this-page-menu">

  1262.       <li><a href="../bugs.html">Report a Bug</a></li>

  1263.       <li>

  1264.         <a href="https://github.com/python/cpython/blob/main/Doc/tutorial/controlflow.rst"

  1265.             rel="nofollow">Show Source

  1266.         </a>

  1267.       </li>

  1268.     </ul>

  1269.   </div>

  1270.         </div>

  1271. <div id="sidebarbutton" title="Collapse sidebar">

  1272. <span>«</span>

  1273. </div>

  1274. 

  1275.       </div>

  1276.       <div class="clearer"></div>

  1277.     </div>  

  1278.     <div class="related" role="navigation" aria-label="related navigation">

  1279.       <h3>Navigation</h3>

  1280.       <ul>

  1281.         <li class="right" style="margin-right: 10px">

  1282.           <a href="../genindex.html" title="General Index"

  1283.              >index</a></li>

  1284.         <li class="right" >

  1285.           <a href="../py-modindex.html" title="Python Module Index"

  1286.              >modules</a> |</li>

  1287.         <li class="right" >

  1288.           <a href="datastructures.html" title="5. Data Structures"

  1289.              >next</a> |</li>

  1290.         <li class="right" >

  1291.           <a href="introduction.html" title="3. An Informal Introduction to Python"

  1292.              >previous</a> |</li>

  1293. 

  1294.           <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>

  1295.           <li><a href="https://www.python.org/">Python</a> &#187;</li>

  1296.           <li class="switchers">

  1297.             <div class="language_switcher_placeholder"></div>

  1298.             <div class="version_switcher_placeholder"></div>

  1299.           </li>

  1300.           <li>

  1301.               

  1302.           </li>

  1303.     <li id="cpython-language-and-version">

  1304.       <a href="../index.html">3.12.3 Documentation</a> &#187;

  1305.     </li>

  1306. 

  1307.           <li class="nav-item nav-item-1"><a href="index.html" >The Python Tutorial</a> &#187;</li>

  1308.         <li class="nav-item nav-item-this"><a href=""><span class="section-number">4. </span>More Control Flow Tools</a></li>

  1309.                 <li class="right">

  1310.                     

  1311. 

  1312.     <div class="inline-search" role="search">

  1313.         <form class="inline-search" action="../search.html" method="get">

  1314.           <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />

  1315.           <input type="submit" value="Go" />

  1316.         </form>

  1317.     </div>

  1318.                      |

  1319.                 </li>

  1320.             <li class="right">

  1321. <label class="theme-selector-label">

  1322.     Theme

  1323.     <select class="theme-selector" oninput="activateTheme(this.value)">

  1324.         <option value="auto" selected>Auto</option>

  1325.         <option value="light">Light</option>

  1326.         <option value="dark">Dark</option>

  1327.     </select>

  1328. </label> |</li>

  1329.             

  1330.       </ul>

  1331.     </div>  

  1332.     <div class="footer">

  1333.     &copy; 

  1334.       <a href="../copyright.html">

  1335.     

  1336.     Copyright

  1337.     

  1338.       </a>

  1339.      2001-2024, Python Software Foundation.

  1340.     <br />

  1341.     This page is licensed under the Python Software Foundation License Version 2.

  1342.     <br />

  1343.     Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.

  1344.     <br />

  1345.     

  1346.       See <a href="/license.html">History and License</a> for more information.<br />

  1347.     

  1348.     

  1349.     <br />

  1350. 

  1351.     The Python Software Foundation is a non-profit corporation.

  1352. <a href="https://www.python.org/psf/donations/">Please donate.</a>

  1353. <br />

  1354.     <br />

  1355.       Last updated on Apr 09, 2024 (13:47 UTC).

  1356.     

  1357.       <a href="/bugs.html">Found a bug</a>?

  1358.     

  1359.     <br />

  1360. 

  1361.     Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 7.2.6.

  1362.     </div>

  1363. 

  1364.   </body>

  1365. </html>
上海开阖软件有限公司 沪ICP备12045867号-1