Team Ai
Apppublic

parthtamu/rag-code-assistant

sourceHugging Faceupdated 7mo agoView on Hugging Face
0likes
asyncio-task.html1897 linesDownload Raw Back to docs
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="Coroutines and Tasks" />8<meta property="og:type" content="website" />9<meta property="og:url" content="https://docs.python.org/3/library/asyncio-task.html" />10<meta property="og:site_name" content="Python documentation" />11<meta property="og:description" content="This section outlines high-level asyncio APIs to work with coroutines and Tasks. Coroutines, Awaitables, Creating Tasks, Task Cancellation, Task Groups, Sleeping, Running Tasks Concurrently, Eager ..." />12<meta property="og:image:width" content="1146" />13<meta property="og:image:height" content="600" />14<meta property="og:image" content="https://docs.python.org/3.15/_images/social_previews/summary_library_asyncio-task_bedaa95c.png" />15<meta property="og:image:alt" content="This section outlines high-level asyncio APIs to work with coroutines and Tasks. Coroutines, Awaitables, Creating Tasks, Task Cancellation, Task Groups, Sleeping, Running Tasks Concurrently, Eager ..." />16<meta name="description" content="This section outlines high-level asyncio APIs to work with coroutines and Tasks. Coroutines, Awaitables, Creating Tasks, Task Cancellation, Task Groups, Sleeping, Running Tasks Concurrently, Eager ..." />17<meta name="twitter:card" content="summary_large_image" />18<meta name="theme-color" content="#3776ab">19 20    <title>Coroutines and Tasks &#8212; Python 3.15.0a6 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">21    22    <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />23    <link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" />24    <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=89a2f22a" />25    <link rel="stylesheet" type="text/css" href="../_static/profiling-sampling-visualization.css?v=0c2600ae" />26    <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=5349f25f" />27    28    <script src="../_static/documentation_options.js?v=6b7c9ff5"></script>29    <script src="../_static/doctools.js?v=9bcbadda"></script>30    <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>31    <script src="../_static/profiling-sampling-visualization.js?v=9811ed04"></script>32    33    <script src="../_static/sidebar.js"></script>34    35    <link rel="search" type="application/opensearchdescription+xml"36          title="Search within Python 3.15.0a6 documentation"37          href="../_static/opensearch.xml"/>38    <link rel="author" title="About these documents" href="../about.html" />39    <link rel="index" title="Index" href="../genindex.html" />40    <link rel="search" title="Search" href="../search.html" />41    <link rel="copyright" title="Copyright" href="../copyright.html" />42    <link rel="next" title="Streams" href="asyncio-stream.html" />43    <link rel="prev" title="Runners" href="asyncio-runner.html" />44    45      46      <script defer file-types="bz2,epub,zip" data-domain="docs.python.org" src="https://analytics.python.org/js/script.file-downloads.outbound-links.js"></script>47      48      <link rel="canonical" href="https://docs.python.org/3/library/asyncio-task.html">49      50    51 52    53    <style>54      @media only screen {55        table.full-width-table {56            width: 100%;57        }58      }59    </style>60<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">61    <link rel="shortcut icon" type="image/png" href="../_static/py.svg">62            <script type="text/javascript" src="../_static/copybutton.js"></script>63            <script type="text/javascript" src="../_static/menu.js"></script>64            <script type="text/javascript" src="../_static/search-focus.js"></script>65            <script type="text/javascript" src="../_static/themetoggle.js"></script> 66            <script type="text/javascript" src="../_static/rtd_switcher.js"></script>67            <meta name="readthedocs-addons-api-version" content="1">68 69  </head>70<body>71<div class="mobile-nav">72    <input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"73           aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu">74    <nav class="nav-content" role="navigation">75        <label for="menuToggler" class="toggler__label">76            <span></span>77        </label>78        <span class="nav-items-wrapper">79            <a href="https://www.python.org/" class="nav-logo">80                <img src="../_static/py.svg" alt="Python logo">81            </a>82            <span class="version_switcher_placeholder"></span>83            <form role="search" class="search" action="../search.html" method="get">84                <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">85                    <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>86                </svg>87                <input placeholder="Quick search" aria-label="Quick search" type="search" name="q">88                <input type="submit" value="Go">89            </form>90        </span>91    </nav>92    <div class="menu-wrapper">93        <nav class="menu" role="navigation" aria-label="main navigation">94            <div class="language_switcher_placeholder"></div>95            96<label class="theme-selector-label">97    Theme98    <select class="theme-selector" oninput="activateTheme(this.value)">99        <option value="auto" selected>Auto</option>100        <option value="light">Light</option>101        <option value="dark">Dark</option>102    </select>103</label>104  <div>105    <h3><a href="../contents.html">Table of Contents</a></h3>106    <ul>107<li><a class="reference internal" href="#">Coroutines and Tasks</a><ul>108<li><a class="reference internal" href="#coroutines">Coroutines</a></li>109<li><a class="reference internal" href="#awaitables">Awaitables</a></li>110<li><a class="reference internal" href="#creating-tasks">Creating Tasks</a></li>111<li><a class="reference internal" href="#task-cancellation">Task Cancellation</a></li>112<li><a class="reference internal" href="#task-groups">Task Groups</a><ul>113<li><a class="reference internal" href="#terminating-a-task-group">Terminating a Task Group</a></li>114</ul>115</li>116<li><a class="reference internal" href="#sleeping">Sleeping</a></li>117<li><a class="reference internal" href="#running-tasks-concurrently">Running Tasks Concurrently</a></li>118<li><a class="reference internal" href="#eager-task-factory">Eager Task Factory</a></li>119<li><a class="reference internal" href="#shielding-from-cancellation">Shielding From Cancellation</a></li>120<li><a class="reference internal" href="#timeouts">Timeouts</a></li>121<li><a class="reference internal" href="#waiting-primitives">Waiting Primitives</a></li>122<li><a class="reference internal" href="#running-in-threads">Running in Threads</a></li>123<li><a class="reference internal" href="#scheduling-from-other-threads">Scheduling From Other Threads</a></li>124<li><a class="reference internal" href="#introspection">Introspection</a></li>125<li><a class="reference internal" href="#task-object">Task Object</a></li>126</ul>127</li>128</ul>129 130  </div>131  <div>132    <h4>Previous topic</h4>133    <p class="topless"><a href="asyncio-runner.html"134                          title="previous chapter">Runners</a></p>135  </div>136  <div>137    <h4>Next topic</h4>138    <p class="topless"><a href="asyncio-stream.html"139                          title="next chapter">Streams</a></p>140  </div>141  <script>142    document.addEventListener('DOMContentLoaded', () => {143        const title = document.querySelector('meta[property="og:title"]').content;144        const elements = document.querySelectorAll('.improvepage');145        const pageurl = window.location.href.split('?')[0];146        elements.forEach(element => {147            const url = new URL(element.href.split('?')[0].replace("-nojs", ""));148            url.searchParams.set('pagetitle', title);149            url.searchParams.set('pageurl', pageurl);150            url.searchParams.set('pagesource', "library/asyncio-task.rst");151            element.href = url.toString();152        });153    });154  </script>155  <div role="note" aria-label="source link">156    <h3>This page</h3>157    <ul class="this-page-menu">158      <li><a href="../bugs.html">Report a bug</a></li>159      <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>160      <li>161        <a href="https://github.com/python/cpython/blob/main/Doc/library/asyncio-task.rst?plain=1"162            rel="nofollow">Show source163        </a>164      </li>165      166    </ul>167  </div>168        </nav>169    </div>170</div>171 172  173    <div class="related" role="navigation" aria-label="Related">174      <h3>Navigation</h3>175      <ul>176        <li class="right" style="margin-right: 10px">177          <a href="../genindex.html" title="General Index"178             accesskey="I">index</a></li>179        <li class="right" >180          <a href="../py-modindex.html" title="Python Module Index"181             >modules</a> |</li>182        <li class="right" >183          <a href="asyncio-stream.html" title="Streams"184             accesskey="N">next</a> |</li>185        <li class="right" >186          <a href="asyncio-runner.html" title="Runners"187             accesskey="P">previous</a> |</li>188 189          <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>190          <li><a href="https://www.python.org/">Python</a> &#187;</li>191          <li class="switchers">192            <div class="language_switcher_placeholder"></div>193            <div class="version_switcher_placeholder"></div>194          </li>195          <li>196              197          </li>198    <li id="cpython-language-and-version">199      <a href="../index.html">3.15.0a6 Documentation</a> &#187;200    </li>201 202          <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>203          <li class="nav-item nav-item-2"><a href="ipc.html" >Networking and Interprocess Communication</a> &#187;</li>204          <li class="nav-item nav-item-3"><a href="asyncio.html" accesskey="U"><code class="xref py py-mod docutils literal notranslate"><span class="pre">asyncio</span></code> — Asynchronous I/O</a> &#187;</li>205        <li class="nav-item nav-item-this"><a href="">Coroutines and Tasks</a></li>206                <li class="right">207                    208 209    <div class="inline-search" role="search">210        <form class="inline-search" action="../search.html" method="get">211          <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">212          <input type="submit" value="Go">213        </form>214    </div>215                     |216                </li>217            <li class="right">218<label class="theme-selector-label">219    Theme220    <select class="theme-selector" oninput="activateTheme(this.value)">221        <option value="auto" selected>Auto</option>222        <option value="light">Light</option>223        <option value="dark">Dark</option>224    </select>225</label> |</li>226            227      </ul>228    </div>    229 230    <div class="document">231      <div class="documentwrapper">232        <div class="bodywrapper">233          <div class="body" role="main">234            235  <section id="coroutines-and-tasks">236<h1>Coroutines and Tasks<a class="headerlink" href="#coroutines-and-tasks" title="Link to this heading">¶</a></h1>237<p>This section outlines high-level asyncio APIs to work with coroutines238and Tasks.</p>239<nav class="contents local" id="contents">240<ul class="simple">241<li><p><a class="reference internal" href="#coroutines" id="id2">Coroutines</a></p></li>242<li><p><a class="reference internal" href="#awaitables" id="id3">Awaitables</a></p></li>243<li><p><a class="reference internal" href="#creating-tasks" id="id4">Creating Tasks</a></p></li>244<li><p><a class="reference internal" href="#task-cancellation" id="id5">Task Cancellation</a></p></li>245<li><p><a class="reference internal" href="#task-groups" id="id6">Task Groups</a></p></li>246<li><p><a class="reference internal" href="#sleeping" id="id7">Sleeping</a></p></li>247<li><p><a class="reference internal" href="#running-tasks-concurrently" id="id8">Running Tasks Concurrently</a></p></li>248<li><p><a class="reference internal" href="#eager-task-factory" id="id9">Eager Task Factory</a></p></li>249<li><p><a class="reference internal" href="#shielding-from-cancellation" id="id10">Shielding From Cancellation</a></p></li>250<li><p><a class="reference internal" href="#timeouts" id="id11">Timeouts</a></p></li>251<li><p><a class="reference internal" href="#waiting-primitives" id="id12">Waiting Primitives</a></p></li>252<li><p><a class="reference internal" href="#running-in-threads" id="id13">Running in Threads</a></p></li>253<li><p><a class="reference internal" href="#scheduling-from-other-threads" id="id14">Scheduling From Other Threads</a></p></li>254<li><p><a class="reference internal" href="#introspection" id="id15">Introspection</a></p></li>255<li><p><a class="reference internal" href="#task-object" id="id16">Task Object</a></p></li>256</ul>257</nav>258<section id="coroutines">259<span id="coroutine"></span><h2><a class="toc-backref" href="#id2" role="doc-backlink">Coroutines</a><a class="headerlink" href="#coroutines" title="Link to this heading">¶</a></h2>260<p><strong>Source code:</strong> <a class="extlink-source reference external" href="https://github.com/python/cpython/tree/main/Lib/asyncio/coroutines.py">Lib/asyncio/coroutines.py</a></p>261<hr class="docutils" />262<p><a class="reference internal" href="../glossary.html#term-coroutine"><span class="xref std std-term">Coroutines</span></a> declared with the async/await syntax is the263preferred way of writing asyncio applications.  For example, the following264snippet of code prints “hello”, waits 1 second,265and then prints “world”:</p>266<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span><span class="w"> </span><span class="nn">asyncio</span>267 268<span class="gp">&gt;&gt;&gt; </span><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">main</span><span class="p">():</span>269<span class="gp">... </span>    <span class="nb">print</span><span class="p">(</span><span class="s1">&#39;hello&#39;</span><span class="p">)</span>270<span class="gp">... </span>    <span class="k">await</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>271<span class="gp">... </span>    <span class="nb">print</span><span class="p">(</span><span class="s1">&#39;world&#39;</span><span class="p">)</span>272 273<span class="gp">&gt;&gt;&gt; </span><span class="n">asyncio</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">main</span><span class="p">())</span>274<span class="go">hello</span>275<span class="go">world</span>276</pre></div>277</div>278<p>Note that simply calling a coroutine will not schedule it to279be executed:</p>280<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">main</span><span class="p">()</span>281<span class="go">&lt;coroutine object main at 0x1053bb7c8&gt;</span>282</pre></div>283</div>284<p>To actually run a coroutine, asyncio provides the following mechanisms:</p>285<ul>286<li><p>The <a class="reference internal" href="asyncio-runner.html#asyncio.run" title="asyncio.run"><code class="xref py py-func docutils literal notranslate"><span class="pre">asyncio.run()</span></code></a> function to run the top-level287entry point “main()” function (see the above example.)</p></li>288<li><p>Awaiting on a coroutine.  The following snippet of code will289print “hello” after waiting for 1 second, and then print “world”290after waiting for <em>another</em> 2 seconds:</p>291<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">asyncio</span>292<span class="kn">import</span><span class="w"> </span><span class="nn">time</span>293 294<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">say_after</span><span class="p">(</span><span class="n">delay</span><span class="p">,</span> <span class="n">what</span><span class="p">):</span>295    <span class="k">await</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="n">delay</span><span class="p">)</span>296    <span class="nb">print</span><span class="p">(</span><span class="n">what</span><span class="p">)</span>297 298<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">main</span><span class="p">():</span>299    <span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;started at </span><span class="si">{</span><span class="n">time</span><span class="o">.</span><span class="n">strftime</span><span class="p">(</span><span class="s1">&#39;</span><span class="si">%X</span><span class="s1">&#39;</span><span class="p">)</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>300 301    <span class="k">await</span> <span class="n">say_after</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="s1">&#39;hello&#39;</span><span class="p">)</span>302    <span class="k">await</span> <span class="n">say_after</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="s1">&#39;world&#39;</span><span class="p">)</span>303 304    <span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;finished at </span><span class="si">{</span><span class="n">time</span><span class="o">.</span><span class="n">strftime</span><span class="p">(</span><span class="s1">&#39;</span><span class="si">%X</span><span class="s1">&#39;</span><span class="p">)</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>305 306<span class="n">asyncio</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">main</span><span class="p">())</span>307</pre></div>308</div>309<p>Expected output:</p>310<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">started</span> <span class="n">at</span> <span class="mi">17</span><span class="p">:</span><span class="mi">13</span><span class="p">:</span><span class="mi">52</span>311<span class="n">hello</span>312<span class="n">world</span>313<span class="n">finished</span> <span class="n">at</span> <span class="mi">17</span><span class="p">:</span><span class="mi">13</span><span class="p">:</span><span class="mi">55</span>314</pre></div>315</div>316</li>317<li><p>The <a class="reference internal" href="#asyncio.create_task" title="asyncio.create_task"><code class="xref py py-func docutils literal notranslate"><span class="pre">asyncio.create_task()</span></code></a> function to run coroutines318concurrently as asyncio <a class="reference internal" href="#asyncio.Task" title="asyncio.Task"><code class="xref py py-class docutils literal notranslate"><span class="pre">Tasks</span></code></a>.</p>319<p>Let’s modify the above example and run two <code class="docutils literal notranslate"><span class="pre">say_after</span></code> coroutines320<em>concurrently</em>:</p>321<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">main</span><span class="p">():</span>322    <span class="n">task1</span> <span class="o">=</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">create_task</span><span class="p">(</span>323        <span class="n">say_after</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="s1">&#39;hello&#39;</span><span class="p">))</span>324 325    <span class="n">task2</span> <span class="o">=</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">create_task</span><span class="p">(</span>326        <span class="n">say_after</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="s1">&#39;world&#39;</span><span class="p">))</span>327 328    <span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;started at </span><span class="si">{</span><span class="n">time</span><span class="o">.</span><span class="n">strftime</span><span class="p">(</span><span class="s1">&#39;</span><span class="si">%X</span><span class="s1">&#39;</span><span class="p">)</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>329 330    <span class="c1"># Wait until both tasks are completed (should take</span>331    <span class="c1"># around 2 seconds.)</span>332    <span class="k">await</span> <span class="n">task1</span>333    <span class="k">await</span> <span class="n">task2</span>334 335    <span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;finished at </span><span class="si">{</span><span class="n">time</span><span class="o">.</span><span class="n">strftime</span><span class="p">(</span><span class="s1">&#39;</span><span class="si">%X</span><span class="s1">&#39;</span><span class="p">)</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>336</pre></div>337</div>338<p>Note that expected output now shows that the snippet runs3391 second faster than before:</p>340<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">started</span> <span class="n">at</span> <span class="mi">17</span><span class="p">:</span><span class="mi">14</span><span class="p">:</span><span class="mi">32</span>341<span class="n">hello</span>342<span class="n">world</span>343<span class="n">finished</span> <span class="n">at</span> <span class="mi">17</span><span class="p">:</span><span class="mi">14</span><span class="p">:</span><span class="mi">34</span>344</pre></div>345</div>346</li>347<li><p>The <a class="reference internal" href="#asyncio.TaskGroup" title="asyncio.TaskGroup"><code class="xref py py-class docutils literal notranslate"><span class="pre">asyncio.TaskGroup</span></code></a> class provides a more modern348alternative to <a class="reference internal" href="#asyncio.create_task" title="asyncio.create_task"><code class="xref py py-func docutils literal notranslate"><span class="pre">create_task()</span></code></a>.349Using this API, the last example becomes:</p>350<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">main</span><span class="p">():</span>351    <span class="k">async</span> <span class="k">with</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">TaskGroup</span><span class="p">()</span> <span class="k">as</span> <span class="n">tg</span><span class="p">:</span>352        <span class="n">task1</span> <span class="o">=</span> <span class="n">tg</span><span class="o">.</span><span class="n">create_task</span><span class="p">(</span>353            <span class="n">say_after</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="s1">&#39;hello&#39;</span><span class="p">))</span>354 355        <span class="n">task2</span> <span class="o">=</span> <span class="n">tg</span><span class="o">.</span><span class="n">create_task</span><span class="p">(</span>356            <span class="n">say_after</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="s1">&#39;world&#39;</span><span class="p">))</span>357 358        <span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;started at </span><span class="si">{</span><span class="n">time</span><span class="o">.</span><span class="n">strftime</span><span class="p">(</span><span class="s1">&#39;</span><span class="si">%X</span><span class="s1">&#39;</span><span class="p">)</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>359 360    <span class="c1"># The await is implicit when the context manager exits.</span>361 362    <span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;finished at </span><span class="si">{</span><span class="n">time</span><span class="o">.</span><span class="n">strftime</span><span class="p">(</span><span class="s1">&#39;</span><span class="si">%X</span><span class="s1">&#39;</span><span class="p">)</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>363</pre></div>364</div>365<p>The timing and output should be the same as for the previous version.</p>366<div class="versionadded">367<p><span class="versionmodified added">Added in version 3.11: </span><a class="reference internal" href="#asyncio.TaskGroup" title="asyncio.TaskGroup"><code class="xref py py-class docutils literal notranslate"><span class="pre">asyncio.TaskGroup</span></code></a>.</p>368</div>369</li>370</ul>371</section>372<section id="awaitables">373<span id="asyncio-awaitables"></span><h2><a class="toc-backref" href="#id3" role="doc-backlink">Awaitables</a><a class="headerlink" href="#awaitables" title="Link to this heading">¶</a></h2>374<p>We say that an object is an <strong>awaitable</strong> object if it can be used375in an <a class="reference internal" href="../reference/expressions.html#await"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">await</span></code></a> expression.  Many asyncio APIs are designed to376accept awaitables.</p>377<p>There are three main types of <em>awaitable</em> objects:378<strong>coroutines</strong>, <strong>Tasks</strong>, and <strong>Futures</strong>.</p>379<p class="rubric">Coroutines</p>380<p>Python coroutines are <em>awaitables</em> and therefore can be awaited from381other coroutines:</p>382<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">asyncio</span>383 384<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">nested</span><span class="p">():</span>385    <span class="k">return</span> <span class="mi">42</span>386 387<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">main</span><span class="p">():</span>388    <span class="c1"># Nothing happens if we just call &quot;nested()&quot;.</span>389    <span class="c1"># A coroutine object is created but not awaited,</span>390    <span class="c1"># so it *won&#39;t run at all*.</span>391    <span class="n">nested</span><span class="p">()</span>  <span class="c1"># will raise a &quot;RuntimeWarning&quot;.</span>392 393    <span class="c1"># Let&#39;s do it differently now and await it:</span>394    <span class="nb">print</span><span class="p">(</span><span class="k">await</span> <span class="n">nested</span><span class="p">())</span>  <span class="c1"># will print &quot;42&quot;.</span>395 396<span class="n">asyncio</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">main</span><span class="p">())</span>397</pre></div>398</div>399<div class="admonition important">400<p class="admonition-title">Important</p>401<p>In this documentation the term “coroutine” can be used for402two closely related concepts:</p>403<ul class="simple">404<li><p>a <em>coroutine function</em>: an <a class="reference internal" href="../reference/compound_stmts.html#async-def"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">async</span> <span class="pre">def</span></code></a> function;</p></li>405<li><p>a <em>coroutine object</em>: an object returned by calling a406<em>coroutine function</em>.</p></li>407</ul>408</div>409<p class="rubric">Tasks</p>410<p><em>Tasks</em> are used to schedule coroutines <em>concurrently</em>.</p>411<p>When a coroutine is wrapped into a <em>Task</em> with functions like412<a class="reference internal" href="#asyncio.create_task" title="asyncio.create_task"><code class="xref py py-func docutils literal notranslate"><span class="pre">asyncio.create_task()</span></code></a> the coroutine is automatically413scheduled to run soon:</p>414<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">asyncio</span>415 416<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">nested</span><span class="p">():</span>417    <span class="k">return</span> <span class="mi">42</span>418 419<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">main</span><span class="p">():</span>420    <span class="c1"># Schedule nested() to run soon concurrently</span>421    <span class="c1"># with &quot;main()&quot;.</span>422    <span class="n">task</span> <span class="o">=</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">create_task</span><span class="p">(</span><span class="n">nested</span><span class="p">())</span>423 424    <span class="c1"># &quot;task&quot; can now be used to cancel &quot;nested()&quot;, or</span>425    <span class="c1"># can simply be awaited to wait until it is complete:</span>426    <span class="k">await</span> <span class="n">task</span>427 428<span class="n">asyncio</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">main</span><span class="p">())</span>429</pre></div>430</div>431<p class="rubric">Futures</p>432<p>A <a class="reference internal" href="asyncio-future.html#asyncio.Future" title="asyncio.Future"><code class="xref py py-class docutils literal notranslate"><span class="pre">Future</span></code></a> is a special <strong>low-level</strong> awaitable object that433represents an <strong>eventual result</strong> of an asynchronous operation.</p>434<p>When a Future object is <em>awaited</em> it means that the coroutine will435wait until the Future is resolved in some other place.</p>436<p>Future objects in asyncio are needed to allow callback-based code437to be used with async/await.</p>438<p>Normally <strong>there is no need</strong> to create Future objects at the439application level code.</p>440<p>Future objects, sometimes exposed by libraries and some asyncio441APIs, can be awaited:</p>442<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">main</span><span class="p">():</span>443    <span class="k">await</span> <span class="n">function_that_returns_a_future_object</span><span class="p">()</span>444 445    <span class="c1"># this is also valid:</span>446    <span class="k">await</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">gather</span><span class="p">(</span>447        <span class="n">function_that_returns_a_future_object</span><span class="p">(),</span>448        <span class="n">some_python_coroutine</span><span class="p">()</span>449    <span class="p">)</span>450</pre></div>451</div>452<p>A good example of a low-level function that returns a Future object453is <a class="reference internal" href="asyncio-eventloop.html#asyncio.loop.run_in_executor" title="asyncio.loop.run_in_executor"><code class="xref py py-meth docutils literal notranslate"><span class="pre">loop.run_in_executor()</span></code></a>.</p>454</section>455<section id="creating-tasks">456<h2><a class="toc-backref" href="#id4" role="doc-backlink">Creating Tasks</a><a class="headerlink" href="#creating-tasks" title="Link to this heading">¶</a></h2>457<p><strong>Source code:</strong> <a class="extlink-source reference external" href="https://github.com/python/cpython/tree/main/Lib/asyncio/tasks.py">Lib/asyncio/tasks.py</a></p>458<hr class="docutils" />459<dl class="py function">460<dt class="sig sig-object py" id="asyncio.create_task">461<span class="sig-prename descclassname"><span class="pre">asyncio.</span></span><span class="sig-name descname"><span class="pre">create_task</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">coro</span></span></em>, <em class="sig-param"><span class="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">name</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">context</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">eager_start</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.create_task" title="Link to this definition">¶</a></dt>462<dd><p>Wrap the <em>coro</em> <a class="reference internal" href="#coroutine"><span class="std std-ref">coroutine</span></a> into a <a class="reference internal" href="#asyncio.Task" title="asyncio.Task"><code class="xref py py-class docutils literal notranslate"><span class="pre">Task</span></code></a>463and schedule its execution.  Return the Task object.</p>464<p>The full function signature is largely the same as that of the465<a class="reference internal" href="#asyncio.Task" title="asyncio.Task"><code class="xref py py-class docutils literal notranslate"><span class="pre">Task</span></code></a> constructor (or factory) - all of the keyword arguments to466this function are passed through to that interface.</p>467<p>An optional keyword-only <em>context</em> argument allows specifying a468custom <a class="reference internal" href="contextvars.html#contextvars.Context" title="contextvars.Context"><code class="xref py py-class docutils literal notranslate"><span class="pre">contextvars.Context</span></code></a> for the <em>coro</em> to run in.469The current context copy is created when no <em>context</em> is provided.</p>470<p>An optional keyword-only <em>eager_start</em> argument allows specifying471if the task should execute eagerly during the call to create_task,472or be scheduled later. If <em>eager_start</em> is not passed the mode set473by <a class="reference internal" href="asyncio-eventloop.html#asyncio.loop.set_task_factory" title="asyncio.loop.set_task_factory"><code class="xref py py-meth docutils literal notranslate"><span class="pre">loop.set_task_factory()</span></code></a> will be used.</p>474<p>The task is executed in the loop returned by <a class="reference internal" href="asyncio-eventloop.html#asyncio.get_running_loop" title="asyncio.get_running_loop"><code class="xref py py-func docutils literal notranslate"><span class="pre">get_running_loop()</span></code></a>,475<a class="reference internal" href="exceptions.html#RuntimeError" title="RuntimeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">RuntimeError</span></code></a> is raised if there is no running loop in476current thread.</p>477<div class="admonition note">478<p class="admonition-title">Note</p>479<p><a class="reference internal" href="#asyncio.TaskGroup.create_task" title="asyncio.TaskGroup.create_task"><code class="xref py py-meth docutils literal notranslate"><span class="pre">asyncio.TaskGroup.create_task()</span></code></a> is a new alternative480leveraging structural concurrency; it allows for waiting481for a group of related tasks with strong safety guarantees.</p>482</div>483<div class="admonition important">484<p class="admonition-title">Important</p>485<p>Save a reference to the result of this function, to avoid486a task disappearing mid-execution. The event loop only keeps487weak references to tasks. A task that isn’t referenced elsewhere488may get garbage collected at any time, even before it’s done.489For reliable “fire-and-forget” background tasks, gather them in490a collection:</p>491<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">background_tasks</span> <span class="o">=</span> <span class="nb">set</span><span class="p">()</span>492 493<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">10</span><span class="p">):</span>494    <span class="n">task</span> <span class="o">=</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">create_task</span><span class="p">(</span><span class="n">some_coro</span><span class="p">(</span><span class="n">param</span><span class="o">=</span><span class="n">i</span><span class="p">))</span>495 496    <span class="c1"># Add task to the set. This creates a strong reference.</span>497    <span class="n">background_tasks</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="n">task</span><span class="p">)</span>498 499    <span class="c1"># To prevent keeping references to finished tasks forever,</span>500    <span class="c1"># make each task remove its own reference from the set after</span>501    <span class="c1"># completion:</span>502    <span class="n">task</span><span class="o">.</span><span class="n">add_done_callback</span><span class="p">(</span><span class="n">background_tasks</span><span class="o">.</span><span class="n">discard</span><span class="p">)</span>503</pre></div>504</div>505</div>506<div class="versionadded">507<p><span class="versionmodified added">Added in version 3.7.</span></p>508</div>509<div class="versionchanged">510<p><span class="versionmodified changed">Changed in version 3.8: </span>Added the <em>name</em> parameter.</p>511</div>512<div class="versionchanged">513<p><span class="versionmodified changed">Changed in version 3.11: </span>Added the <em>context</em> parameter.</p>514</div>515<div class="versionchanged">516<p><span class="versionmodified changed">Changed in version 3.14: </span>Added the <em>eager_start</em> parameter by passing on all <em>kwargs</em>.</p>517</div>518</dd></dl>519 520</section>521<section id="task-cancellation">522<h2><a class="toc-backref" href="#id5" role="doc-backlink">Task Cancellation</a><a class="headerlink" href="#task-cancellation" title="Link to this heading">¶</a></h2>523<p>Tasks can easily and safely be cancelled.524When a task is cancelled, <a class="reference internal" href="asyncio-exceptions.html#asyncio.CancelledError" title="asyncio.CancelledError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">asyncio.CancelledError</span></code></a> will be raised525in the task at the next opportunity.</p>526<p>It is recommended that coroutines use <code class="docutils literal notranslate"><span class="pre">try/finally</span></code> blocks to robustly527perform clean-up logic. In case <a class="reference internal" href="asyncio-exceptions.html#asyncio.CancelledError" title="asyncio.CancelledError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">asyncio.CancelledError</span></code></a>528is explicitly caught, it should generally be propagated when529clean-up is complete. <code class="xref py py-exc docutils literal notranslate"><span class="pre">asyncio.CancelledError</span></code> directly subclasses530<a class="reference internal" href="exceptions.html#BaseException" title="BaseException"><code class="xref py py-exc docutils literal notranslate"><span class="pre">BaseException</span></code></a> so most code will not need to be aware of it.</p>531<p>The asyncio components that enable structured concurrency, like532<a class="reference internal" href="#asyncio.TaskGroup" title="asyncio.TaskGroup"><code class="xref py py-class docutils literal notranslate"><span class="pre">asyncio.TaskGroup</span></code></a> and <a class="reference internal" href="#asyncio.timeout" title="asyncio.timeout"><code class="xref py py-func docutils literal notranslate"><span class="pre">asyncio.timeout()</span></code></a>,533are implemented using cancellation internally and might misbehave if534a coroutine swallows <a class="reference internal" href="asyncio-exceptions.html#asyncio.CancelledError" title="asyncio.CancelledError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">asyncio.CancelledError</span></code></a>. Similarly, user code535should not generally call <a class="reference internal" href="#asyncio.Task.uncancel" title="asyncio.Task.uncancel"><code class="xref py py-meth docutils literal notranslate"><span class="pre">uncancel</span></code></a>.536However, in cases when suppressing <code class="xref py py-exc docutils literal notranslate"><span class="pre">asyncio.CancelledError</span></code> is537truly desired, it is necessary to also call <code class="docutils literal notranslate"><span class="pre">uncancel()</span></code> to completely538remove the cancellation state.</p>539</section>540<section id="task-groups">541<span id="taskgroups"></span><h2><a class="toc-backref" href="#id6" role="doc-backlink">Task Groups</a><a class="headerlink" href="#task-groups" title="Link to this heading">¶</a></h2>542<p>Task groups combine a task creation API with a convenient543and reliable way to wait for all tasks in the group to finish.</p>544<dl class="py class">545<dt class="sig sig-object py" id="asyncio.TaskGroup">546<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">asyncio.</span></span><span class="sig-name descname"><span class="pre">TaskGroup</span></span><a class="headerlink" href="#asyncio.TaskGroup" title="Link to this definition">¶</a></dt>547<dd><p>An <a class="reference internal" href="../reference/datamodel.html#async-context-managers"><span class="std std-ref">asynchronous context manager</span></a>548holding a group of tasks.549Tasks can be added to the group using <a class="reference internal" href="#asyncio.create_task" title="asyncio.create_task"><code class="xref py py-meth docutils literal notranslate"><span class="pre">create_task()</span></code></a>.550All tasks are awaited when the context manager exits.</p>551<div class="versionadded">552<p><span class="versionmodified added">Added in version 3.11.</span></p>553</div>554<dl class="py method">555<dt class="sig sig-object py" id="asyncio.TaskGroup.create_task">556<span class="sig-name descname"><span class="pre">create_task</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">coro</span></span></em>, <em class="sig-param"><span class="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">name</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">context</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">eager_start</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.TaskGroup.create_task" title="Link to this definition">¶</a></dt>557<dd><p>Create a task in this task group.558The signature matches that of <a class="reference internal" href="#asyncio.create_task" title="asyncio.create_task"><code class="xref py py-func docutils literal notranslate"><span class="pre">asyncio.create_task()</span></code></a>.559If the task group is inactive (e.g. not yet entered,560already finished, or in the process of shutting down),561we will close the given <code class="docutils literal notranslate"><span class="pre">coro</span></code>.</p>562<div class="versionchanged">563<p><span class="versionmodified changed">Changed in version 3.13: </span>Close the given coroutine if the task group is not active.</p>564</div>565<div class="versionchanged">566<p><span class="versionmodified changed">Changed in version 3.14: </span>Passes on all <em>kwargs</em> to <a class="reference internal" href="asyncio-eventloop.html#asyncio.loop.create_task" title="asyncio.loop.create_task"><code class="xref py py-meth docutils literal notranslate"><span class="pre">loop.create_task()</span></code></a></p>567</div>568</dd></dl>569 570</dd></dl>571 572<p>Example:</p>573<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">main</span><span class="p">():</span>574    <span class="k">async</span> <span class="k">with</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">TaskGroup</span><span class="p">()</span> <span class="k">as</span> <span class="n">tg</span><span class="p">:</span>575        <span class="n">task1</span> <span class="o">=</span> <span class="n">tg</span><span class="o">.</span><span class="n">create_task</span><span class="p">(</span><span class="n">some_coro</span><span class="p">(</span><span class="o">...</span><span class="p">))</span>576        <span class="n">task2</span> <span class="o">=</span> <span class="n">tg</span><span class="o">.</span><span class="n">create_task</span><span class="p">(</span><span class="n">another_coro</span><span class="p">(</span><span class="o">...</span><span class="p">))</span>577    <span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Both tasks have completed now: </span><span class="si">{</span><span class="n">task1</span><span class="o">.</span><span class="n">result</span><span class="p">()</span><span class="si">}</span><span class="s2">, </span><span class="si">{</span><span class="n">task2</span><span class="o">.</span><span class="n">result</span><span class="p">()</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>578</pre></div>579</div>580<p>The <code class="docutils literal notranslate"><span class="pre">async</span> <span class="pre">with</span></code> statement will wait for all tasks in the group to finish.581While waiting, new tasks may still be added to the group582(for example, by passing <code class="docutils literal notranslate"><span class="pre">tg</span></code> into one of the coroutines583and calling <code class="docutils literal notranslate"><span class="pre">tg.create_task()</span></code> in that coroutine).584Once the last task has finished and the <code class="docutils literal notranslate"><span class="pre">async</span> <span class="pre">with</span></code> block is exited,585no new tasks may be added to the group.</p>586<p>The first time any of the tasks belonging to the group fails587with an exception other than <a class="reference internal" href="asyncio-exceptions.html#asyncio.CancelledError" title="asyncio.CancelledError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">asyncio.CancelledError</span></code></a>,588the remaining tasks in the group are cancelled.589No further tasks can then be added to the group.590At this point, if the body of the <code class="docutils literal notranslate"><span class="pre">async</span> <span class="pre">with</span></code> statement is still active591(i.e., <a class="reference internal" href="../reference/datamodel.html#object.__aexit__" title="object.__aexit__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__aexit__()</span></code></a> hasn’t been called yet),592the task directly containing the <code class="docutils literal notranslate"><span class="pre">async</span> <span class="pre">with</span></code> statement is also cancelled.593The resulting <code class="xref py py-exc docutils literal notranslate"><span class="pre">asyncio.CancelledError</span></code> will interrupt an <code class="docutils literal notranslate"><span class="pre">await</span></code>,594but it will not bubble out of the containing <code class="docutils literal notranslate"><span class="pre">async</span> <span class="pre">with</span></code> statement.</p>595<p>Once all tasks have finished, if any tasks have failed596with an exception other than <a class="reference internal" href="asyncio-exceptions.html#asyncio.CancelledError" title="asyncio.CancelledError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">asyncio.CancelledError</span></code></a>,597those exceptions are combined in an598<a class="reference internal" href="exceptions.html#ExceptionGroup" title="ExceptionGroup"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ExceptionGroup</span></code></a> or <a class="reference internal" href="exceptions.html#BaseExceptionGroup" title="BaseExceptionGroup"><code class="xref py py-exc docutils literal notranslate"><span class="pre">BaseExceptionGroup</span></code></a>599(as appropriate; see their documentation)600which is then raised.</p>601<p>Two base exceptions are treated specially:602If any task fails with <a class="reference internal" href="exceptions.html#KeyboardInterrupt" title="KeyboardInterrupt"><code class="xref py py-exc docutils literal notranslate"><span class="pre">KeyboardInterrupt</span></code></a> or <a class="reference internal" href="exceptions.html#SystemExit" title="SystemExit"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SystemExit</span></code></a>,603the task group still cancels the remaining tasks and waits for them,604but then the initial <code class="xref py py-exc docutils literal notranslate"><span class="pre">KeyboardInterrupt</span></code> or <code class="xref py py-exc docutils literal notranslate"><span class="pre">SystemExit</span></code>605is re-raised instead of <a class="reference internal" href="exceptions.html#ExceptionGroup" title="ExceptionGroup"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ExceptionGroup</span></code></a> or <a class="reference internal" href="exceptions.html#BaseExceptionGroup" title="BaseExceptionGroup"><code class="xref py py-exc docutils literal notranslate"><span class="pre">BaseExceptionGroup</span></code></a>.</p>606<p>If the body of the <code class="docutils literal notranslate"><span class="pre">async</span> <span class="pre">with</span></code> statement exits with an exception607(so <a class="reference internal" href="../reference/datamodel.html#object.__aexit__" title="object.__aexit__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__aexit__()</span></code></a> is called with an exception set),608this is treated the same as if one of the tasks failed:609the remaining tasks are cancelled and then waited for,610and non-cancellation exceptions are grouped into an611exception group and raised.612The exception passed into <code class="xref py py-meth docutils literal notranslate"><span class="pre">__aexit__()</span></code>,613unless it is <a class="reference internal" href="asyncio-exceptions.html#asyncio.CancelledError" title="asyncio.CancelledError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">asyncio.CancelledError</span></code></a>,614is also included in the exception group.615The same special case is made for616<a class="reference internal" href="exceptions.html#KeyboardInterrupt" title="KeyboardInterrupt"><code class="xref py py-exc docutils literal notranslate"><span class="pre">KeyboardInterrupt</span></code></a> and <a class="reference internal" href="exceptions.html#SystemExit" title="SystemExit"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SystemExit</span></code></a> as in the previous paragraph.</p>617<p>Task groups are careful not to mix up the internal cancellation used to618“wake up” their <a class="reference internal" href="../reference/datamodel.html#object.__aexit__" title="object.__aexit__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__aexit__()</span></code></a> with cancellation requests619for the task in which they are running made by other parties.620In particular, when one task group is syntactically nested in another,621and both experience an exception in one of their child tasks simultaneously,622the inner task group will process its exceptions, and then the outer task group623will receive another cancellation and process its own exceptions.</p>624<p>In the case where a task group is cancelled externally and also must625raise an <a class="reference internal" href="exceptions.html#ExceptionGroup" title="ExceptionGroup"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ExceptionGroup</span></code></a>, it will call the parent task’s626<a class="reference internal" href="#asyncio.Task.cancel" title="asyncio.Task.cancel"><code class="xref py py-meth docutils literal notranslate"><span class="pre">cancel()</span></code></a> method. This ensures that a627<a class="reference internal" href="asyncio-exceptions.html#asyncio.CancelledError" title="asyncio.CancelledError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">asyncio.CancelledError</span></code></a> will be raised at the next628<a class="reference internal" href="../reference/expressions.html#await"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">await</span></code></a>, so the cancellation is not lost.</p>629<p>Task groups preserve the cancellation count630reported by <a class="reference internal" href="#asyncio.Task.cancelling" title="asyncio.Task.cancelling"><code class="xref py py-meth docutils literal notranslate"><span class="pre">asyncio.Task.cancelling()</span></code></a>.</p>631<div class="versionchanged">632<p><span class="versionmodified changed">Changed in version 3.13: </span>Improved handling of simultaneous internal and external cancellations633and correct preservation of cancellation counts.</p>634</div>635<section id="terminating-a-task-group">636<h3>Terminating a Task Group<a class="headerlink" href="#terminating-a-task-group" title="Link to this heading">¶</a></h3>637<p>While terminating a task group is not natively supported by the standard638library, termination can be achieved by adding an exception-raising task639to the task group and ignoring the raised exception:</p>640<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">asyncio</span>641<span class="kn">from</span><span class="w"> </span><span class="nn">asyncio</span><span class="w"> </span><span class="kn">import</span> <span class="n">TaskGroup</span>642 643<span class="k">class</span><span class="w"> </span><span class="nc">TerminateTaskGroup</span><span class="p">(</span><span class="ne">Exception</span><span class="p">):</span>644<span class="w">    </span><span class="sd">&quot;&quot;&quot;Exception raised to terminate a task group.&quot;&quot;&quot;</span>645 646<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">force_terminate_task_group</span><span class="p">():</span>647<span class="w">    </span><span class="sd">&quot;&quot;&quot;Used to force termination of a task group.&quot;&quot;&quot;</span>648    <span class="k">raise</span> <span class="n">TerminateTaskGroup</span><span class="p">()</span>649 650<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">job</span><span class="p">(</span><span class="n">task_id</span><span class="p">,</span> <span class="n">sleep_time</span><span class="p">):</span>651    <span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s1">&#39;Task </span><span class="si">{</span><span class="n">task_id</span><span class="si">}</span><span class="s1">: start&#39;</span><span class="p">)</span>652    <span class="k">await</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="n">sleep_time</span><span class="p">)</span>653    <span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s1">&#39;Task </span><span class="si">{</span><span class="n">task_id</span><span class="si">}</span><span class="s1">: done&#39;</span><span class="p">)</span>654 655<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">main</span><span class="p">():</span>656    <span class="k">try</span><span class="p">:</span>657        <span class="k">async</span> <span class="k">with</span> <span class="n">TaskGroup</span><span class="p">()</span> <span class="k">as</span> <span class="n">group</span><span class="p">:</span>658            <span class="c1"># spawn some tasks</span>659            <span class="n">group</span><span class="o">.</span><span class="n">create_task</span><span class="p">(</span><span class="n">job</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mf">0.5</span><span class="p">))</span>660            <span class="n">group</span><span class="o">.</span><span class="n">create_task</span><span class="p">(</span><span class="n">job</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="mf">1.5</span><span class="p">))</span>661            <span class="c1"># sleep for 1 second</span>662            <span class="k">await</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>663            <span class="c1"># add an exception-raising task to force the group to terminate</span>664            <span class="n">group</span><span class="o">.</span><span class="n">create_task</span><span class="p">(</span><span class="n">force_terminate_task_group</span><span class="p">())</span>665    <span class="k">except</span><span class="o">*</span> <span class="n">TerminateTaskGroup</span><span class="p">:</span>666        <span class="k">pass</span>667 668<span class="n">asyncio</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">main</span><span class="p">())</span>669</pre></div>670</div>671<p>Expected output:</p>672<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Task 1: start673Task 2: start674Task 1: done675</pre></div>676</div>677</section>678</section>679<section id="sleeping">680<h2><a class="toc-backref" href="#id7" role="doc-backlink">Sleeping</a><a class="headerlink" href="#sleeping" title="Link to this heading">¶</a></h2>681<dl class="py function">682<dt class="sig sig-object py" id="asyncio.sleep">683<em class="property"><span class="k"><span class="pre">async</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">asyncio.</span></span><span class="sig-name descname"><span class="pre">sleep</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">delay</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">result</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.sleep" title="Link to this definition">¶</a></dt>684<dd><p>Block for <em>delay</em> seconds.</p>685<p>If <em>result</em> is provided, it is returned to the caller686when the coroutine completes.</p>687<p><code class="docutils literal notranslate"><span class="pre">sleep()</span></code> always suspends the current task, allowing other tasks688to run.</p>689<p>Setting the delay to 0 provides an optimized path to allow other690tasks to run. This can be used by long-running functions to avoid691blocking the event loop for the full duration of the function call.</p>692<p id="asyncio-example-sleep">Example of coroutine displaying the current date every second693for 5 seconds:</p>694<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">asyncio</span>695<span class="kn">import</span><span class="w"> </span><span class="nn">datetime</span>696 697<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">display_date</span><span class="p">():</span>698    <span class="n">loop</span> <span class="o">=</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">get_running_loop</span><span class="p">()</span>699    <span class="n">end_time</span> <span class="o">=</span> <span class="n">loop</span><span class="o">.</span><span class="n">time</span><span class="p">()</span> <span class="o">+</span> <span class="mf">5.0</span>700    <span class="k">while</span> <span class="kc">True</span><span class="p">:</span>701        <span class="nb">print</span><span class="p">(</span><span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="o">.</span><span class="n">now</span><span class="p">())</span>702        <span class="k">if</span> <span class="p">(</span><span class="n">loop</span><span class="o">.</span><span class="n">time</span><span class="p">()</span> <span class="o">+</span> <span class="mf">1.0</span><span class="p">)</span> <span class="o">&gt;=</span> <span class="n">end_time</span><span class="p">:</span>703            <span class="k">break</span>704        <span class="k">await</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>705 706<span class="n">asyncio</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">display_date</span><span class="p">())</span>707</pre></div>708</div>709<div class="versionchanged">710<p><span class="versionmodified changed">Changed in version 3.10: </span>Removed the <em>loop</em> parameter.</p>711</div>712<div class="versionchanged">713<p><span class="versionmodified changed">Changed in version 3.13: </span>Raises <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> if <em>delay</em> is <a class="reference internal" href="math.html#math.nan" title="math.nan"><code class="xref py py-data docutils literal notranslate"><span class="pre">nan</span></code></a>.</p>714</div>715</dd></dl>716 717</section>718<section id="running-tasks-concurrently">719<h2><a class="toc-backref" href="#id8" role="doc-backlink">Running Tasks Concurrently</a><a class="headerlink" href="#running-tasks-concurrently" title="Link to this heading">¶</a></h2>720<dl class="py function">721<dt class="sig sig-object py" id="asyncio.gather">722<em class="property"><span class="pre">awaitable</span> </em><span class="sig-prename descclassname"><span class="pre">asyncio.</span></span><span class="sig-name descname"><span class="pre">gather</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">aws</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">return_exceptions</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.gather" title="Link to this definition">¶</a></dt>723<dd><p>Run <a class="reference internal" href="#asyncio-awaitables"><span class="std std-ref">awaitable objects</span></a> in the <em>aws</em>724sequence <em>concurrently</em>.</p>725<p>If any awaitable in <em>aws</em> is a coroutine, it is automatically726scheduled as a Task.</p>727<p>If all awaitables are completed successfully, the result is an728aggregate list of returned values.  The order of result values729corresponds to the order of awaitables in <em>aws</em>.</p>730<p>If <em>return_exceptions</em> is <code class="docutils literal notranslate"><span class="pre">False</span></code> (default), the first731raised exception is immediately propagated to the task that732awaits on <code class="docutils literal notranslate"><span class="pre">gather()</span></code>.  Other awaitables in the <em>aws</em> sequence733<strong>won’t be cancelled</strong> and will continue to run.</p>734<p>If <em>return_exceptions</em> is <code class="docutils literal notranslate"><span class="pre">True</span></code>, exceptions are treated the735same as successful results, and aggregated in the result list.</p>736<p>If <code class="docutils literal notranslate"><span class="pre">gather()</span></code> is <em>cancelled</em>, all submitted awaitables737(that have not completed yet) are also <em>cancelled</em>.</p>738<p>If any Task or Future from the <em>aws</em> sequence is <em>cancelled</em>, it is739treated as if it raised <a class="reference internal" href="asyncio-exceptions.html#asyncio.CancelledError" title="asyncio.CancelledError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">CancelledError</span></code></a> – the <code class="docutils literal notranslate"><span class="pre">gather()</span></code>740call is <strong>not</strong> cancelled in this case.  This is to prevent the741cancellation of one submitted Task/Future to cause other742Tasks/Futures to be cancelled.</p>743<div class="admonition note">744<p class="admonition-title">Note</p>745<p>A new alternative to create and run tasks concurrently and746wait for their completion is <a class="reference internal" href="#asyncio.TaskGroup" title="asyncio.TaskGroup"><code class="xref py py-class docutils literal notranslate"><span class="pre">asyncio.TaskGroup</span></code></a>. <em>TaskGroup</em>747provides stronger safety guarantees than <em>gather</em> for scheduling a nesting of subtasks:748if a task (or a subtask, a task scheduled by a task)749raises an exception, <em>TaskGroup</em> will, while <em>gather</em> will not,750cancel the remaining scheduled tasks).</p>751</div>752<p id="asyncio-example-gather">Example:</p>753<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">asyncio</span>754 755<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">factorial</span><span class="p">(</span><span class="n">name</span><span class="p">,</span> <span class="n">number</span><span class="p">):</span>756    <span class="n">f</span> <span class="o">=</span> <span class="mi">1</span>757    <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">2</span><span class="p">,</span> <span class="n">number</span> <span class="o">+</span> <span class="mi">1</span><span class="p">):</span>758        <span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Task </span><span class="si">{</span><span class="n">name</span><span class="si">}</span><span class="s2">: Compute factorial(</span><span class="si">{</span><span class="n">number</span><span class="si">}</span><span class="s2">), currently i=</span><span class="si">{</span><span class="n">i</span><span class="si">}</span><span class="s2">...&quot;</span><span class="p">)</span>759        <span class="k">await</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>760        <span class="n">f</span> <span class="o">*=</span> <span class="n">i</span>761    <span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Task </span><span class="si">{</span><span class="n">name</span><span class="si">}</span><span class="s2">: factorial(</span><span class="si">{</span><span class="n">number</span><span class="si">}</span><span class="s2">) = </span><span class="si">{</span><span class="n">f</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>762    <span class="k">return</span> <span class="n">f</span>763 764<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">main</span><span class="p">():</span>765    <span class="c1"># Schedule three calls *concurrently*:</span>766    <span class="n">L</span> <span class="o">=</span> <span class="k">await</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">gather</span><span class="p">(</span>767        <span class="n">factorial</span><span class="p">(</span><span class="s2">&quot;A&quot;</span><span class="p">,</span> <span class="mi">2</span><span class="p">),</span>768        <span class="n">factorial</span><span class="p">(</span><span class="s2">&quot;B&quot;</span><span class="p">,</span> <span class="mi">3</span><span class="p">),</span>769        <span class="n">factorial</span><span class="p">(</span><span class="s2">&quot;C&quot;</span><span class="p">,</span> <span class="mi">4</span><span class="p">),</span>770    <span class="p">)</span>771    <span class="nb">print</span><span class="p">(</span><span class="n">L</span><span class="p">)</span>772 773<span class="n">asyncio</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">main</span><span class="p">())</span>774 775<span class="c1"># Expected output:</span>776<span class="c1">#</span>777<span class="c1">#     Task A: Compute factorial(2), currently i=2...</span>778<span class="c1">#     Task B: Compute factorial(3), currently i=2...</span>779<span class="c1">#     Task C: Compute factorial(4), currently i=2...</span>780<span class="c1">#     Task A: factorial(2) = 2</span>781<span class="c1">#     Task B: Compute factorial(3), currently i=3...</span>782<span class="c1">#     Task C: Compute factorial(4), currently i=3...</span>783<span class="c1">#     Task B: factorial(3) = 6</span>784<span class="c1">#     Task C: Compute factorial(4), currently i=4...</span>785<span class="c1">#     Task C: factorial(4) = 24</span>786<span class="c1">#     [2, 6, 24]</span>787</pre></div>788</div>789<div class="admonition note">790<p class="admonition-title">Note</p>791<p>If <em>return_exceptions</em> is false, cancelling gather() after it792has been marked done won’t cancel any submitted awaitables.793For instance, gather can be marked done after propagating an794exception to the caller, therefore, calling <code class="docutils literal notranslate"><span class="pre">gather.cancel()</span></code>795after catching an exception (raised by one of the awaitables) from796gather won’t cancel any other awaitables.</p>797</div>798<div class="versionchanged">799<p><span class="versionmodified changed">Changed in version 3.7: </span>If the <em>gather</em> itself is cancelled, the cancellation is800propagated regardless of <em>return_exceptions</em>.</p>801</div>802<div class="versionchanged">803<p><span class="versionmodified changed">Changed in version 3.10: </span>Removed the <em>loop</em> parameter.</p>804</div>805<div class="deprecated">806<p><span class="versionmodified deprecated">Deprecated since version 3.10: </span>Deprecation warning is emitted if no positional arguments are provided807or not all positional arguments are Future-like objects808and there is no running event loop.</p>809</div>810</dd></dl>811 812</section>813<section id="eager-task-factory">814<span id="id1"></span><h2><a class="toc-backref" href="#id9" role="doc-backlink">Eager Task Factory</a><a class="headerlink" href="#eager-task-factory" title="Link to this heading">¶</a></h2>815<dl class="py function">816<dt class="sig sig-object py" id="asyncio.eager_task_factory">817<span class="sig-prename descclassname"><span class="pre">asyncio.</span></span><span class="sig-name descname"><span class="pre">eager_task_factory</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">loop</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">coro</span></span></em>, <em class="sig-param"><span class="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">name</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">context</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.eager_task_factory" title="Link to this definition">¶</a></dt>818<dd><p>A task factory for eager task execution.</p>819<p>When using this factory (via <a class="reference internal" href="asyncio-eventloop.html#asyncio.loop.set_task_factory" title="asyncio.loop.set_task_factory"><code class="xref py py-meth docutils literal notranslate"><span class="pre">loop.set_task_factory(asyncio.eager_task_factory)</span></code></a>),820coroutines begin execution synchronously during <a class="reference internal" href="#asyncio.Task" title="asyncio.Task"><code class="xref py py-class docutils literal notranslate"><span class="pre">Task</span></code></a> construction.821Tasks are only scheduled on the event loop if they block.822This can be a performance improvement as the overhead of loop scheduling823is avoided for coroutines that complete synchronously.</p>824<p>A common example where this is beneficial is coroutines which employ825caching or memoization to avoid actual I/O when possible.</p>826<div class="admonition note">827<p class="admonition-title">Note</p>828<p>Immediate execution of the coroutine is a semantic change.829If the coroutine returns or raises, the task is never scheduled830to the event loop. If the coroutine execution blocks, the task is831scheduled to the event loop. This change may introduce behavior832changes to existing applications. For example,833the application’s task execution order is likely to change.</p>834</div>835<div class="versionadded">836<p><span class="versionmodified added">Added in version 3.12.</span></p>837</div>838</dd></dl>839 840<dl class="py function">841<dt class="sig sig-object py" id="asyncio.create_eager_task_factory">842<span class="sig-prename descclassname"><span class="pre">asyncio.</span></span><span class="sig-name descname"><span class="pre">create_eager_task_factory</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">custom_task_constructor</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.create_eager_task_factory" title="Link to this definition">¶</a></dt>843<dd><p>Create an eager task factory, similar to <a class="reference internal" href="#asyncio.eager_task_factory" title="asyncio.eager_task_factory"><code class="xref py py-func docutils literal notranslate"><span class="pre">eager_task_factory()</span></code></a>,844using the provided <em>custom_task_constructor</em> when creating a new task instead845of the default <a class="reference internal" href="#asyncio.Task" title="asyncio.Task"><code class="xref py py-class docutils literal notranslate"><span class="pre">Task</span></code></a>.</p>846<p><em>custom_task_constructor</em> must be a <em>callable</em> with the signature matching847the signature of <a class="reference internal" href="#asyncio.Task" title="asyncio.Task"><code class="xref py py-class docutils literal notranslate"><span class="pre">Task.__init__</span></code></a>.848The callable must return a <a class="reference internal" href="#asyncio.Task" title="asyncio.Task"><code class="xref py py-class docutils literal notranslate"><span class="pre">asyncio.Task</span></code></a>-compatible object.</p>849<p>This function returns a <em>callable</em> intended to be used as a task factory of an850event loop via <a class="reference internal" href="asyncio-eventloop.html#asyncio.loop.set_task_factory" title="asyncio.loop.set_task_factory"><code class="xref py py-meth docutils literal notranslate"><span class="pre">loop.set_task_factory(factory)</span></code></a>).</p>851<div class="versionadded">852<p><span class="versionmodified added">Added in version 3.12.</span></p>853</div>854</dd></dl>855 856</section>857<section id="shielding-from-cancellation">858<h2><a class="toc-backref" href="#id10" role="doc-backlink">Shielding From Cancellation</a><a class="headerlink" href="#shielding-from-cancellation" title="Link to this heading">¶</a></h2>859<dl class="py function">860<dt class="sig sig-object py" id="asyncio.shield">861<em class="property"><span class="pre">awaitable</span> </em><span class="sig-prename descclassname"><span class="pre">asyncio.</span></span><span class="sig-name descname"><span class="pre">shield</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">aw</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.shield" title="Link to this definition">¶</a></dt>862<dd><p>Protect an <a class="reference internal" href="#asyncio-awaitables"><span class="std std-ref">awaitable object</span></a>863from being <a class="reference internal" href="#asyncio.Task.cancel" title="asyncio.Task.cancel"><code class="xref py py-meth docutils literal notranslate"><span class="pre">cancelled</span></code></a>.</p>864<p>If <em>aw</em> is a coroutine it is automatically scheduled as a Task.</p>865<p>The statement:</p>866<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">task</span> <span class="o">=</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">create_task</span><span class="p">(</span><span class="n">something</span><span class="p">())</span>867<span class="n">res</span> <span class="o">=</span> <span class="k">await</span> <span class="n">shield</span><span class="p">(</span><span class="n">task</span><span class="p">)</span>868</pre></div>869</div>870<p>is equivalent to:</p>871<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">res</span> <span class="o">=</span> <span class="k">await</span> <span class="n">something</span><span class="p">()</span>872</pre></div>873</div>874<p><em>except</em> that if the coroutine containing it is cancelled, the875Task running in <code class="docutils literal notranslate"><span class="pre">something()</span></code> is not cancelled.  From the point876of view of <code class="docutils literal notranslate"><span class="pre">something()</span></code>, the cancellation did not happen.877Although its caller is still cancelled, so the “await” expression878still raises a <a class="reference internal" href="asyncio-exceptions.html#asyncio.CancelledError" title="asyncio.CancelledError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">CancelledError</span></code></a>.</p>879<p>If <code class="docutils literal notranslate"><span class="pre">something()</span></code> is cancelled by other means (i.e. from within880itself) that would also cancel <code class="docutils literal notranslate"><span class="pre">shield()</span></code>.</p>881<p>If it is desired to completely ignore cancellation (not recommended)882the <code class="docutils literal notranslate"><span class="pre">shield()</span></code> function should be combined with a try/except883clause, as follows:</p>884<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">task</span> <span class="o">=</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">create_task</span><span class="p">(</span><span class="n">something</span><span class="p">())</span>885<span class="k">try</span><span class="p">:</span>886    <span class="n">res</span> <span class="o">=</span> <span class="k">await</span> <span class="n">shield</span><span class="p">(</span><span class="n">task</span><span class="p">)</span>887<span class="k">except</span> <span class="n">CancelledError</span><span class="p">:</span>888    <span class="n">res</span> <span class="o">=</span> <span class="kc">None</span>889</pre></div>890</div>891<div class="admonition important">892<p class="admonition-title">Important</p>893<p>Save a reference to tasks passed to this function, to avoid894a task disappearing mid-execution. The event loop only keeps895weak references to tasks. A task that isn’t referenced elsewhere896may get garbage collected at any time, even before it’s done.</p>897</div>898<div class="versionchanged">899<p><span class="versionmodified changed">Changed in version 3.10: </span>Removed the <em>loop</em> parameter.</p>900</div>901<div class="deprecated">902<p><span class="versionmodified deprecated">Deprecated since version 3.10: </span>Deprecation warning is emitted if <em>aw</em> is not Future-like object903and there is no running event loop.</p>904</div>905</dd></dl>906 907</section>908<section id="timeouts">909<h2><a class="toc-backref" href="#id11" role="doc-backlink">Timeouts</a><a class="headerlink" href="#timeouts" title="Link to this heading">¶</a></h2>910<dl class="py function">911<dt class="sig sig-object py" id="asyncio.timeout">912<span class="sig-prename descclassname"><span class="pre">asyncio.</span></span><span class="sig-name descname"><span class="pre">timeout</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">delay</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.timeout" title="Link to this definition">¶</a></dt>913<dd><p>Return an <a class="reference internal" href="../reference/datamodel.html#async-context-managers"><span class="std std-ref">asynchronous context manager</span></a>914that can be used to limit the amount of time spent waiting on915something.</p>916<p><em>delay</em> can either be <code class="docutils literal notranslate"><span class="pre">None</span></code>, or a float/int number of917seconds to wait. If <em>delay</em> is <code class="docutils literal notranslate"><span class="pre">None</span></code>, no time limit will918be applied; this can be useful if the delay is unknown when919the context manager is created.</p>920<p>In either case, the context manager can be rescheduled after921creation using <a class="reference internal" href="#asyncio.Timeout.reschedule" title="asyncio.Timeout.reschedule"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Timeout.reschedule()</span></code></a>.</p>922<p>Example:</p>923<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">main</span><span class="p">():</span>924    <span class="k">async</span> <span class="k">with</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">timeout</span><span class="p">(</span><span class="mi">10</span><span class="p">):</span>925        <span class="k">await</span> <span class="n">long_running_task</span><span class="p">()</span>926</pre></div>927</div>928<p>If <code class="docutils literal notranslate"><span class="pre">long_running_task</span></code> takes more than 10 seconds to complete,929the context manager will cancel the current task and handle930the resulting <a class="reference internal" href="asyncio-exceptions.html#asyncio.CancelledError" title="asyncio.CancelledError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">asyncio.CancelledError</span></code></a> internally, transforming it931into a <a class="reference internal" href="exceptions.html#TimeoutError" title="TimeoutError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TimeoutError</span></code></a> which can be caught and handled.</p>932<div class="admonition note">933<p class="admonition-title">Note</p>934<p>The <a class="reference internal" href="#asyncio.timeout" title="asyncio.timeout"><code class="xref py py-func docutils literal notranslate"><span class="pre">asyncio.timeout()</span></code></a> context manager is what transforms935the <a class="reference internal" href="asyncio-exceptions.html#asyncio.CancelledError" title="asyncio.CancelledError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">asyncio.CancelledError</span></code></a> into a <a class="reference internal" href="exceptions.html#TimeoutError" title="TimeoutError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TimeoutError</span></code></a>,936which means the <code class="xref py py-exc docutils literal notranslate"><span class="pre">TimeoutError</span></code> can only be caught937<em>outside</em> of the context manager.</p>938</div>939<p>Example of catching <a class="reference internal" href="exceptions.html#TimeoutError" title="TimeoutError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TimeoutError</span></code></a>:</p>940<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">main</span><span class="p">():</span>941    <span class="k">try</span><span class="p">:</span>942        <span class="k">async</span> <span class="k">with</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">timeout</span><span class="p">(</span><span class="mi">10</span><span class="p">):</span>943            <span class="k">await</span> <span class="n">long_running_task</span><span class="p">()</span>944    <span class="k">except</span> <span class="ne">TimeoutError</span><span class="p">:</span>945        <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;The long operation timed out, but we&#39;ve handled it.&quot;</span><span class="p">)</span>946 947    <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;This statement will run regardless.&quot;</span><span class="p">)</span>948</pre></div>949</div>950<p>The context manager produced by <a class="reference internal" href="#asyncio.timeout" title="asyncio.timeout"><code class="xref py py-func docutils literal notranslate"><span class="pre">asyncio.timeout()</span></code></a> can be951rescheduled to a different deadline and inspected.</p>952<dl class="py class">953<dt class="sig sig-object py" id="asyncio.Timeout">954<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">asyncio.</span></span><span class="sig-name descname"><span class="pre">Timeout</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">when</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Timeout" title="Link to this definition">¶</a></dt>955<dd><p>An <a class="reference internal" href="../reference/datamodel.html#async-context-managers"><span class="std std-ref">asynchronous context manager</span></a>956for cancelling overdue coroutines.</p>957<p>Prefer using <a class="reference internal" href="#asyncio.timeout" title="asyncio.timeout"><code class="xref py py-func docutils literal notranslate"><span class="pre">asyncio.timeout()</span></code></a> or <a class="reference internal" href="#asyncio.timeout_at" title="asyncio.timeout_at"><code class="xref py py-func docutils literal notranslate"><span class="pre">asyncio.timeout_at()</span></code></a>958rather than instantiating <code class="xref py py-class docutils literal notranslate"><span class="pre">Timeout</span></code> directly.</p>959<p><code class="docutils literal notranslate"><span class="pre">when</span></code> should be an absolute time at which the context should time out,960as measured by the event loop’s clock:</p>961<ul class="simple">962<li><p>If <code class="docutils literal notranslate"><span class="pre">when</span></code> is <code class="docutils literal notranslate"><span class="pre">None</span></code>, the timeout will never trigger.</p></li>963<li><p>If <code class="docutils literal notranslate"><span class="pre">when</span> <span class="pre">&lt;</span> <span class="pre">loop.time()</span></code>, the timeout will trigger on the next964iteration of the event loop.</p></li>965</ul>966<blockquote>967<div><dl class="py method">968<dt class="sig sig-object py" id="asyncio.Timeout.when">969<span class="sig-name descname"><span class="pre">when</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference internal" href="functions.html#float" title="float"><span class="pre">float</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference internal" href="constants.html#None" title="None"><span class="pre">None</span></a></span></span><a class="headerlink" href="#asyncio.Timeout.when" title="Link to this definition">¶</a></dt>970<dd><p>Return the current deadline, or <code class="docutils literal notranslate"><span class="pre">None</span></code> if the current971deadline is not set.</p>972</dd></dl>973 974<dl class="py method">975<dt class="sig sig-object py" id="asyncio.Timeout.reschedule">976<span class="sig-name descname"><span class="pre">reschedule</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">when</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="functions.html#float" title="float"><span class="pre">float</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference internal" href="constants.html#None" title="None"><span class="pre">None</span></a></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Timeout.reschedule" title="Link to this definition">¶</a></dt>977<dd><p>Reschedule the timeout.</p>978</dd></dl>979 980<dl class="py method">981<dt class="sig sig-object py" id="asyncio.Timeout.expired">982<span class="sig-name descname"><span class="pre">expired</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference internal" href="functions.html#bool" title="bool"><span class="pre">bool</span></a></span></span><a class="headerlink" href="#asyncio.Timeout.expired" title="Link to this definition">¶</a></dt>983<dd><p>Return whether the context manager has exceeded its deadline984(expired).</p>985</dd></dl>986 987</div></blockquote>988</dd></dl>989 990<p>Example:</p>991<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">main</span><span class="p">():</span>992    <span class="k">try</span><span class="p">:</span>993        <span class="c1"># We do not know the timeout when starting, so we pass ``None``.</span>994        <span class="k">async</span> <span class="k">with</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">timeout</span><span class="p">(</span><span class="kc">None</span><span class="p">)</span> <span class="k">as</span> <span class="n">cm</span><span class="p">:</span>995            <span class="c1"># We know the timeout now, so we reschedule it.</span>996            <span class="n">new_deadline</span> <span class="o">=</span> <span class="n">get_running_loop</span><span class="p">()</span><span class="o">.</span><span class="n">time</span><span class="p">()</span> <span class="o">+</span> <span class="mi">10</span>997            <span class="n">cm</span><span class="o">.</span><span class="n">reschedule</span><span class="p">(</span><span class="n">new_deadline</span><span class="p">)</span>998 999            <span class="k">await</span> <span class="n">long_running_task</span><span class="p">()</span>1000    <span class="k">except</span> <span class="ne">TimeoutError</span><span class="p">:</span>1001        <span class="k">pass</span>1002 1003    <span class="k">if</span> <span class="n">cm</span><span class="o">.</span><span class="n">expired</span><span class="p">():</span>1004        <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Looks like we haven&#39;t finished on time.&quot;</span><span class="p">)</span>1005</pre></div>1006</div>1007<p>Timeout context managers can be safely nested.</p>1008<div class="versionadded">1009<p><span class="versionmodified added">Added in version 3.11.</span></p>1010</div>1011</dd></dl>1012 1013<dl class="py function">1014<dt class="sig sig-object py" id="asyncio.timeout_at">1015<span class="sig-prename descclassname"><span class="pre">asyncio.</span></span><span class="sig-name descname"><span class="pre">timeout_at</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">when</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.timeout_at" title="Link to this definition">¶</a></dt>1016<dd><p>Similar to <a class="reference internal" href="#asyncio.timeout" title="asyncio.timeout"><code class="xref py py-func docutils literal notranslate"><span class="pre">asyncio.timeout()</span></code></a>, except <em>when</em> is the absolute time1017to stop waiting, or <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>1018<p>Example:</p>1019<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">main</span><span class="p">():</span>1020    <span class="n">loop</span> <span class="o">=</span> <span class="n">get_running_loop</span><span class="p">()</span>1021    <span class="n">deadline</span> <span class="o">=</span> <span class="n">loop</span><span class="o">.</span><span class="n">time</span><span class="p">()</span> <span class="o">+</span> <span class="mi">20</span>1022    <span class="k">try</span><span class="p">:</span>1023        <span class="k">async</span> <span class="k">with</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">timeout_at</span><span class="p">(</span><span class="n">deadline</span><span class="p">):</span>1024            <span class="k">await</span> <span class="n">long_running_task</span><span class="p">()</span>1025    <span class="k">except</span> <span class="ne">TimeoutError</span><span class="p">:</span>1026        <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;The long operation timed out, but we&#39;ve handled it.&quot;</span><span class="p">)</span>1027 1028    <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;This statement will run regardless.&quot;</span><span class="p">)</span>1029</pre></div>1030</div>1031<div class="versionadded">1032<p><span class="versionmodified added">Added in version 3.11.</span></p>1033</div>1034</dd></dl>1035 1036<dl class="py function">1037<dt class="sig sig-object py" id="asyncio.wait_for">1038<em class="property"><span class="k"><span class="pre">async</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">asyncio.</span></span><span class="sig-name descname"><span class="pre">wait_for</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">aw</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">timeout</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.wait_for" title="Link to this definition">¶</a></dt>1039<dd><p>Wait for the <em>aw</em> <a class="reference internal" href="#asyncio-awaitables"><span class="std std-ref">awaitable</span></a>1040to complete with a timeout.</p>1041<p>If <em>aw</em> is a coroutine it is automatically scheduled as a Task.</p>1042<p><em>timeout</em> can either be <code class="docutils literal notranslate"><span class="pre">None</span></code> or a float or int number of seconds1043to wait for.  If <em>timeout</em> is <code class="docutils literal notranslate"><span class="pre">None</span></code>, block until the future1044completes.</p>1045<p>If a timeout occurs, it cancels the task and raises1046<a class="reference internal" href="exceptions.html#TimeoutError" title="TimeoutError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TimeoutError</span></code></a>.</p>1047<p>To avoid the task <a class="reference internal" href="#asyncio.Task.cancel" title="asyncio.Task.cancel"><code class="xref py py-meth docutils literal notranslate"><span class="pre">cancellation</span></code></a>,1048wrap it in <a class="reference internal" href="#asyncio.shield" title="asyncio.shield"><code class="xref py py-func docutils literal notranslate"><span class="pre">shield()</span></code></a>.</p>1049<p>The function will wait until the future is actually cancelled,1050so the total wait time may exceed the <em>timeout</em>. If an exception1051happens during cancellation, it is propagated.</p>1052<p>If the wait is cancelled, the future <em>aw</em> is also cancelled.</p>1053<p id="asyncio-example-waitfor">Example:</p>1054<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">eternity</span><span class="p">():</span>1055    <span class="c1"># Sleep for one hour</span>1056    <span class="k">await</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mi">3600</span><span class="p">)</span>1057    <span class="nb">print</span><span class="p">(</span><span class="s1">&#39;yay!&#39;</span><span class="p">)</span>1058 1059<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">main</span><span class="p">():</span>1060    <span class="c1"># Wait for at most 1 second</span>1061    <span class="k">try</span><span class="p">:</span>1062        <span class="k">await</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">wait_for</span><span class="p">(</span><span class="n">eternity</span><span class="p">(),</span> <span class="n">timeout</span><span class="o">=</span><span class="mf">1.0</span><span class="p">)</span>1063    <span class="k">except</span> <span class="ne">TimeoutError</span><span class="p">:</span>1064        <span class="nb">print</span><span class="p">(</span><span class="s1">&#39;timeout!&#39;</span><span class="p">)</span>1065 1066<span class="n">asyncio</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">main</span><span class="p">())</span>1067 1068<span class="c1"># Expected output:</span>1069<span class="c1">#</span>1070<span class="c1">#     timeout!</span>1071</pre></div>1072</div>1073<div class="versionchanged">1074<p><span class="versionmodified changed">Changed in version 3.7: </span>When <em>aw</em> is cancelled due to a timeout, <code class="docutils literal notranslate"><span class="pre">wait_for</span></code> waits1075for <em>aw</em> to be cancelled.  Previously, it raised1076<a class="reference internal" href="exceptions.html#TimeoutError" title="TimeoutError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TimeoutError</span></code></a> immediately.</p>1077</div>1078<div class="versionchanged">1079<p><span class="versionmodified changed">Changed in version 3.10: </span>Removed the <em>loop</em> parameter.</p>1080</div>1081<div class="versionchanged">1082<p><span class="versionmodified changed">Changed in version 3.11: </span>Raises <a class="reference internal" href="exceptions.html#TimeoutError" title="TimeoutError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TimeoutError</span></code></a> instead of <a class="reference internal" href="asyncio-exceptions.html#asyncio.TimeoutError" title="asyncio.TimeoutError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">asyncio.TimeoutError</span></code></a>.</p>1083</div>1084</dd></dl>1085 1086</section>1087<section id="waiting-primitives">1088<h2><a class="toc-backref" href="#id12" role="doc-backlink">Waiting Primitives</a><a class="headerlink" href="#waiting-primitives" title="Link to this heading">¶</a></h2>1089<dl class="py function">1090<dt class="sig sig-object py" id="asyncio.wait">1091<em class="property"><span class="k"><span class="pre">async</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">asyncio.</span></span><span class="sig-name descname"><span class="pre">wait</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">aws</span></span></em>, <em class="sig-param"><span class="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">timeout</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">return_when</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">ALL_COMPLETED</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.wait" title="Link to this definition">¶</a></dt>1092<dd><p>Run <a class="reference internal" href="asyncio-future.html#asyncio.Future" title="asyncio.Future"><code class="xref py py-class docutils literal notranslate"><span class="pre">Future</span></code></a> and <a class="reference internal" href="#asyncio.Task" title="asyncio.Task"><code class="xref py py-class docutils literal notranslate"><span class="pre">Task</span></code></a> instances in the <em>aws</em>1093iterable concurrently and block until the condition specified1094by <em>return_when</em>.</p>1095<p>The <em>aws</em> iterable must not be empty.</p>1096<p>Returns two sets of Tasks/Futures: <code class="docutils literal notranslate"><span class="pre">(done,</span> <span class="pre">pending)</span></code>.</p>1097<p>Usage:</p>1098<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">done</span><span class="p">,</span> <span class="n">pending</span> <span class="o">=</span> <span class="k">await</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">wait</span><span class="p">(</span><span class="n">aws</span><span class="p">)</span>1099</pre></div>1100</div>1101<p><em>timeout</em> (a float or int), if specified, can be used to control1102the maximum number of seconds to wait before returning.</p>1103<p>Note that this function does not raise <a class="reference internal" href="exceptions.html#TimeoutError" title="TimeoutError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TimeoutError</span></code></a>.1104Futures or Tasks that aren’t done when the timeout occurs are simply1105returned in the second set.</p>1106<p><em>return_when</em> indicates when this function should return.  It must1107be one of the following constants:</p>1108<table class="docutils align-default">1109<thead>1110<tr class="row-odd"><th class="head"><p>Constant</p></th>1111<th class="head"><p>Description</p></th>1112</tr>1113</thead>1114<tbody>1115<tr class="row-even"><td><dl class="py data">1116<dt class="sig sig-object py" id="asyncio.FIRST_COMPLETED">1117<span class="sig-prename descclassname"><span class="pre">asyncio.</span></span><span class="sig-name descname"><span class="pre">FIRST_COMPLETED</span></span><a class="headerlink" href="#asyncio.FIRST_COMPLETED" title="Link to this definition">¶</a></dt>1118<dd></dd></dl>1119 1120</td>1121<td><p>The function will return when any future finishes or is cancelled.</p></td>1122</tr>1123<tr class="row-odd"><td><dl class="py data">1124<dt class="sig sig-object py" id="asyncio.FIRST_EXCEPTION">1125<span class="sig-prename descclassname"><span class="pre">asyncio.</span></span><span class="sig-name descname"><span class="pre">FIRST_EXCEPTION</span></span><a class="headerlink" href="#asyncio.FIRST_EXCEPTION" title="Link to this definition">¶</a></dt>1126<dd></dd></dl>1127 1128</td>1129<td><p>The function will return when any future finishes by raising an1130exception. If no future raises an exception1131then it is equivalent to <a class="reference internal" href="#asyncio.ALL_COMPLETED" title="asyncio.ALL_COMPLETED"><code class="xref py py-const docutils literal notranslate"><span class="pre">ALL_COMPLETED</span></code></a>.</p></td>1132</tr>1133<tr class="row-even"><td><dl class="py data">1134<dt class="sig sig-object py" id="asyncio.ALL_COMPLETED">1135<span class="sig-prename descclassname"><span class="pre">asyncio.</span></span><span class="sig-name descname"><span class="pre">ALL_COMPLETED</span></span><a class="headerlink" href="#asyncio.ALL_COMPLETED" title="Link to this definition">¶</a></dt>1136<dd></dd></dl>1137 1138</td>1139<td><p>The function will return when all futures finish or are cancelled.</p></td>1140</tr>1141</tbody>1142</table>1143<p>Unlike <a class="reference internal" href="#asyncio.wait_for" title="asyncio.wait_for"><code class="xref py py-func docutils literal notranslate"><span class="pre">wait_for()</span></code></a>, <code class="docutils literal notranslate"><span class="pre">wait()</span></code> does not cancel the1144futures when a timeout occurs.</p>1145<div class="versionchanged">1146<p><span class="versionmodified changed">Changed in version 3.10: </span>Removed the <em>loop</em> parameter.</p>1147</div>1148<div class="versionchanged">1149<p><span class="versionmodified changed">Changed in version 3.11: </span>Passing coroutine objects to <code class="docutils literal notranslate"><span class="pre">wait()</span></code> directly is forbidden.</p>1150</div>1151<div class="versionchanged">1152<p><span class="versionmodified changed">Changed in version 3.12: </span>Added support for generators yielding tasks.</p>1153</div>1154</dd></dl>1155 1156<dl class="py function">1157<dt class="sig sig-object py" id="asyncio.as_completed">1158<span class="sig-prename descclassname"><span class="pre">asyncio.</span></span><span class="sig-name descname"><span class="pre">as_completed</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">aws</span></span></em>, <em class="sig-param"><span class="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">timeout</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.as_completed" title="Link to this definition">¶</a></dt>1159<dd><p>Run <a class="reference internal" href="#asyncio-awaitables"><span class="std std-ref">awaitable objects</span></a> in the <em>aws</em> iterable1160concurrently. The returned object can be iterated to obtain the results1161of the awaitables as they finish.</p>1162<p>The object returned by <code class="docutils literal notranslate"><span class="pre">as_completed()</span></code> can be iterated as an1163<a class="reference internal" href="../glossary.html#term-asynchronous-iterator"><span class="xref std std-term">asynchronous iterator</span></a> or a plain <a class="reference internal" href="../glossary.html#term-iterator"><span class="xref std std-term">iterator</span></a>. When asynchronous1164iteration is used, the originally-supplied awaitables are yielded if they1165are tasks or futures. This makes it easy to correlate previously-scheduled1166tasks with their results. Example:</p>1167<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">ipv4_connect</span> <span class="o">=</span> <span class="n">create_task</span><span class="p">(</span><span class="n">open_connection</span><span class="p">(</span><span class="s2">&quot;127.0.0.1&quot;</span><span class="p">,</span> <span class="mi">80</span><span class="p">))</span>1168<span class="n">ipv6_connect</span> <span class="o">=</span> <span class="n">create_task</span><span class="p">(</span><span class="n">open_connection</span><span class="p">(</span><span class="s2">&quot;::1&quot;</span><span class="p">,</span> <span class="mi">80</span><span class="p">))</span>1169<span class="n">tasks</span> <span class="o">=</span> <span class="p">[</span><span class="n">ipv4_connect</span><span class="p">,</span> <span class="n">ipv6_connect</span><span class="p">]</span>1170 1171<span class="k">async</span> <span class="k">for</span> <span class="n">earliest_connect</span> <span class="ow">in</span> <span class="n">as_completed</span><span class="p">(</span><span class="n">tasks</span><span class="p">):</span>1172    <span class="c1"># earliest_connect is done. The result can be obtained by</span>1173    <span class="c1"># awaiting it or calling earliest_connect.result()</span>1174    <span class="n">reader</span><span class="p">,</span> <span class="n">writer</span> <span class="o">=</span> <span class="k">await</span> <span class="n">earliest_connect</span>1175 1176    <span class="k">if</span> <span class="n">earliest_connect</span> <span class="ow">is</span> <span class="n">ipv6_connect</span><span class="p">:</span>1177        <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;IPv6 connection established.&quot;</span><span class="p">)</span>1178    <span class="k">else</span><span class="p">:</span>1179        <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;IPv4 connection established.&quot;</span><span class="p">)</span>1180</pre></div>1181</div>1182<p>During asynchronous iteration, implicitly-created tasks will be yielded for1183supplied awaitables that aren’t tasks or futures.</p>1184<p>When used as a plain iterator, each iteration yields a new coroutine that1185returns the result or raises the exception of the next completed awaitable.1186This pattern is compatible with Python versions older than 3.13:</p>1187<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">ipv4_connect</span> <span class="o">=</span> <span class="n">create_task</span><span class="p">(</span><span class="n">open_connection</span><span class="p">(</span><span class="s2">&quot;127.0.0.1&quot;</span><span class="p">,</span> <span class="mi">80</span><span class="p">))</span>1188<span class="n">ipv6_connect</span> <span class="o">=</span> <span class="n">create_task</span><span class="p">(</span><span class="n">open_connection</span><span class="p">(</span><span class="s2">&quot;::1&quot;</span><span class="p">,</span> <span class="mi">80</span><span class="p">))</span>1189<span class="n">tasks</span> <span class="o">=</span> <span class="p">[</span><span class="n">ipv4_connect</span><span class="p">,</span> <span class="n">ipv6_connect</span><span class="p">]</span>1190 1191<span class="k">for</span> <span class="n">next_connect</span> <span class="ow">in</span> <span class="n">as_completed</span><span class="p">(</span><span class="n">tasks</span><span class="p">):</span>1192    <span class="c1"># next_connect is not one of the original task objects. It must be</span>1193    <span class="c1"># awaited to obtain the result value or raise the exception of the</span>1194    <span class="c1"># awaitable that finishes next.</span>1195    <span class="n">reader</span><span class="p">,</span> <span class="n">writer</span> <span class="o">=</span> <span class="k">await</span> <span class="n">next_connect</span>1196</pre></div>1197</div>1198<p>A <a class="reference internal" href="exceptions.html#TimeoutError" title="TimeoutError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TimeoutError</span></code></a> is raised if the timeout occurs before all awaitables1199are done. This is raised by the <code class="docutils literal notranslate"><span class="pre">async</span> <span class="pre">for</span></code> loop during asynchronous1200iteration or by the coroutines yielded during plain iteration.</p>

Showing the first 1,200 of 1897 lines. Download the file for the rest.