Spaces:
Sleeping
Sleeping
| <html lang="en" data-content_root="../"> | |
| <head> | |
| <meta charset="utf-8" /> | |
| <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" /> | |
| <meta property="og:title" content="Event Loop" /> | |
| <meta property="og:type" content="website" /> | |
| <meta property="og:url" content="https://docs.python.org/3/library/asyncio-eventloop.html" /> | |
| <meta property="og:site_name" content="Python documentation" /> | |
| <meta property="og:description" content="Source code: Lib/asyncio/events.py, Lib/asyncio/base_events.py Preface The event loop is the core of every asyncio application. Event loops run asynchronous tasks and callbacks, perform network IO ..." /> | |
| <meta property="og:image:width" content="1146" /> | |
| <meta property="og:image:height" content="600" /> | |
| <meta property="og:image" content="https://docs.python.org/3.15/_images/social_previews/summary_library_asyncio-eventloop_1be14a63.png" /> | |
| <meta property="og:image:alt" content="Source code: Lib/asyncio/events.py, Lib/asyncio/base_events.py Preface The event loop is the core of every asyncio application. Event loops run asynchronous tasks and callbacks, perform network IO ..." /> | |
| <meta name="description" content="Source code: Lib/asyncio/events.py, Lib/asyncio/base_events.py Preface The event loop is the core of every asyncio application. Event loops run asynchronous tasks and callbacks, perform network IO ..." /> | |
| <meta name="twitter:card" content="summary_large_image" /> | |
| <meta name="theme-color" content="#3776ab"> | |
| <title>Event Loop — Python 3.15.0a6 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0"> | |
| <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" /> | |
| <link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" /> | |
| <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=89a2f22a" /> | |
| <link rel="stylesheet" type="text/css" href="../_static/profiling-sampling-visualization.css?v=0c2600ae" /> | |
| <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=5349f25f" /> | |
| <script src="../_static/documentation_options.js?v=6b7c9ff5"></script> | |
| <script src="../_static/doctools.js?v=9bcbadda"></script> | |
| <script src="../_static/sphinx_highlight.js?v=dc90522c"></script> | |
| <script src="../_static/profiling-sampling-visualization.js?v=9811ed04"></script> | |
| <script src="../_static/sidebar.js"></script> | |
| <link rel="search" type="application/opensearchdescription+xml" | |
| title="Search within Python 3.15.0a6 documentation" | |
| href="../_static/opensearch.xml"/> | |
| <link rel="author" title="About these documents" href="../about.html" /> | |
| <link rel="index" title="Index" href="../genindex.html" /> | |
| <link rel="search" title="Search" href="../search.html" /> | |
| <link rel="copyright" title="Copyright" href="../copyright.html" /> | |
| <link rel="next" title="Futures" href="asyncio-future.html" /> | |
| <link rel="prev" title="Call Graph Introspection" href="asyncio-graph.html" /> | |
| <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> | |
| <link rel="canonical" href="https://docs.python.org/3/library/asyncio-eventloop.html"> | |
| <style> | |
| @media only screen { | |
| table.full-width-table { | |
| width: 100%; | |
| } | |
| } | |
| </style> | |
| <link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css"> | |
| <link rel="shortcut icon" type="image/png" href="../_static/py.svg"> | |
| <script type="text/javascript" src="../_static/copybutton.js"></script> | |
| <script type="text/javascript" src="../_static/menu.js"></script> | |
| <script type="text/javascript" src="../_static/search-focus.js"></script> | |
| <script type="text/javascript" src="../_static/themetoggle.js"></script> | |
| <script type="text/javascript" src="../_static/rtd_switcher.js"></script> | |
| <meta name="readthedocs-addons-api-version" content="1"> | |
| </head> | |
| <body> | |
| <div class="mobile-nav"> | |
| <input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation" | |
| aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu"> | |
| <nav class="nav-content" role="navigation"> | |
| <label for="menuToggler" class="toggler__label"> | |
| <span></span> | |
| </label> | |
| <span class="nav-items-wrapper"> | |
| <a href="https://www.python.org/" class="nav-logo"> | |
| <img src="../_static/py.svg" alt="Python logo"> | |
| </a> | |
| <span class="version_switcher_placeholder"></span> | |
| <form role="search" class="search" action="../search.html" method="get"> | |
| <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon"> | |
| <path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path> | |
| </svg> | |
| <input placeholder="Quick search" aria-label="Quick search" type="search" name="q"> | |
| <input type="submit" value="Go"> | |
| </form> | |
| </span> | |
| </nav> | |
| <div class="menu-wrapper"> | |
| <nav class="menu" role="navigation" aria-label="main navigation"> | |
| <div class="language_switcher_placeholder"></div> | |
| <label class="theme-selector-label"> | |
| Theme | |
| <select class="theme-selector" oninput="activateTheme(this.value)"> | |
| <option value="auto" selected>Auto</option> | |
| <option value="light">Light</option> | |
| <option value="dark">Dark</option> | |
| </select> | |
| </label> | |
| <div> | |
| <h3><a href="../contents.html">Table of Contents</a></h3> | |
| <ul> | |
| <li><a class="reference internal" href="#">Event Loop</a><ul> | |
| <li><a class="reference internal" href="#event-loop-methods">Event Loop Methods</a><ul> | |
| <li><a class="reference internal" href="#running-and-stopping-the-loop">Running and stopping the loop</a></li> | |
| <li><a class="reference internal" href="#scheduling-callbacks">Scheduling callbacks</a></li> | |
| <li><a class="reference internal" href="#scheduling-delayed-callbacks">Scheduling delayed callbacks</a></li> | |
| <li><a class="reference internal" href="#creating-futures-and-tasks">Creating Futures and Tasks</a></li> | |
| <li><a class="reference internal" href="#opening-network-connections">Opening network connections</a></li> | |
| <li><a class="reference internal" href="#creating-network-servers">Creating network servers</a></li> | |
| <li><a class="reference internal" href="#transferring-files">Transferring files</a></li> | |
| <li><a class="reference internal" href="#tls-upgrade">TLS Upgrade</a></li> | |
| <li><a class="reference internal" href="#watching-file-descriptors">Watching file descriptors</a></li> | |
| <li><a class="reference internal" href="#working-with-socket-objects-directly">Working with socket objects directly</a></li> | |
| <li><a class="reference internal" href="#dns">DNS</a></li> | |
| <li><a class="reference internal" href="#working-with-pipes">Working with pipes</a></li> | |
| <li><a class="reference internal" href="#unix-signals">Unix signals</a></li> | |
| <li><a class="reference internal" href="#executing-code-in-thread-or-process-pools">Executing code in thread or process pools</a></li> | |
| <li><a class="reference internal" href="#error-handling-api">Error Handling API</a></li> | |
| <li><a class="reference internal" href="#enabling-debug-mode">Enabling debug mode</a></li> | |
| <li><a class="reference internal" href="#running-subprocesses">Running Subprocesses</a></li> | |
| </ul> | |
| </li> | |
| <li><a class="reference internal" href="#callback-handles">Callback Handles</a></li> | |
| <li><a class="reference internal" href="#server-objects">Server Objects</a></li> | |
| <li><a class="reference internal" href="#event-loop-implementations">Event Loop Implementations</a></li> | |
| <li><a class="reference internal" href="#examples">Examples</a><ul> | |
| <li><a class="reference internal" href="#hello-world-with-call-soon">Hello World with call_soon()</a></li> | |
| <li><a class="reference internal" href="#display-the-current-date-with-call-later">Display the current date with call_later()</a></li> | |
| <li><a class="reference internal" href="#watch-a-file-descriptor-for-read-events">Watch a file descriptor for read events</a></li> | |
| <li><a class="reference internal" href="#set-signal-handlers-for-sigint-and-sigterm">Set signal handlers for SIGINT and SIGTERM</a></li> | |
| </ul> | |
| </li> | |
| </ul> | |
| </li> | |
| </ul> | |
| </div> | |
| <div> | |
| <h4>Previous topic</h4> | |
| <p class="topless"><a href="asyncio-graph.html" | |
| title="previous chapter">Call Graph Introspection</a></p> | |
| </div> | |
| <div> | |
| <h4>Next topic</h4> | |
| <p class="topless"><a href="asyncio-future.html" | |
| title="next chapter">Futures</a></p> | |
| </div> | |
| <script> | |
| document.addEventListener('DOMContentLoaded', () => { | |
| const title = document.querySelector('meta[property="og:title"]').content; | |
| const elements = document.querySelectorAll('.improvepage'); | |
| const pageurl = window.location.href.split('?')[0]; | |
| elements.forEach(element => { | |
| const url = new URL(element.href.split('?')[0].replace("-nojs", "")); | |
| url.searchParams.set('pagetitle', title); | |
| url.searchParams.set('pageurl', pageurl); | |
| url.searchParams.set('pagesource', "library/asyncio-eventloop.rst"); | |
| element.href = url.toString(); | |
| }); | |
| }); | |
| </script> | |
| <div role="note" aria-label="source link"> | |
| <h3>This page</h3> | |
| <ul class="this-page-menu"> | |
| <li><a href="../bugs.html">Report a bug</a></li> | |
| <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li> | |
| <li> | |
| <a href="https://github.com/python/cpython/blob/main/Doc/library/asyncio-eventloop.rst?plain=1" | |
| rel="nofollow">Show source | |
| </a> | |
| </li> | |
| </ul> | |
| </div> | |
| </nav> | |
| </div> | |
| </div> | |
| <div class="related" role="navigation" aria-label="Related"> | |
| <h3>Navigation</h3> | |
| <ul> | |
| <li class="right" style="margin-right: 10px"> | |
| <a href="../genindex.html" title="General Index" | |
| accesskey="I">index</a></li> | |
| <li class="right" > | |
| <a href="../py-modindex.html" title="Python Module Index" | |
| >modules</a> |</li> | |
| <li class="right" > | |
| <a href="asyncio-future.html" title="Futures" | |
| accesskey="N">next</a> |</li> | |
| <li class="right" > | |
| <a href="asyncio-graph.html" title="Call Graph Introspection" | |
| accesskey="P">previous</a> |</li> | |
| <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li> | |
| <li><a href="https://www.python.org/">Python</a> »</li> | |
| <li class="switchers"> | |
| <div class="language_switcher_placeholder"></div> | |
| <div class="version_switcher_placeholder"></div> | |
| </li> | |
| <li> | |
| </li> | |
| <li id="cpython-language-and-version"> | |
| <a href="../index.html">3.15.0a6 Documentation</a> » | |
| </li> | |
| <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li> | |
| <li class="nav-item nav-item-2"><a href="ipc.html" >Networking and Interprocess Communication</a> »</li> | |
| <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> »</li> | |
| <li class="nav-item nav-item-this"><a href="">Event Loop</a></li> | |
| <li class="right"> | |
| <div class="inline-search" role="search"> | |
| <form class="inline-search" action="../search.html" method="get"> | |
| <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box"> | |
| <input type="submit" value="Go"> | |
| </form> | |
| </div> | |
| | | |
| </li> | |
| <li class="right"> | |
| <label class="theme-selector-label"> | |
| Theme | |
| <select class="theme-selector" oninput="activateTheme(this.value)"> | |
| <option value="auto" selected>Auto</option> | |
| <option value="light">Light</option> | |
| <option value="dark">Dark</option> | |
| </select> | |
| </label> |</li> | |
| </ul> | |
| </div> | |
| <div class="document"> | |
| <div class="documentwrapper"> | |
| <div class="bodywrapper"> | |
| <div class="body" role="main"> | |
| <section id="event-loop"> | |
| <span id="asyncio-event-loop"></span><h1>Event Loop<a class="headerlink" href="#event-loop" title="Link to this heading">¶</a></h1> | |
| <p><strong>Source code:</strong> <a class="extlink-source reference external" href="https://github.com/python/cpython/tree/main/Lib/asyncio/events.py">Lib/asyncio/events.py</a>, | |
| <a class="extlink-source reference external" href="https://github.com/python/cpython/tree/main/Lib/asyncio/base_events.py">Lib/asyncio/base_events.py</a></p> | |
| <hr class="docutils" /> | |
| <p class="rubric">Preface</p> | |
| <p>The event loop is the core of every asyncio application. | |
| Event loops run asynchronous tasks and callbacks, perform network | |
| IO operations, and run subprocesses.</p> | |
| <p>Application developers should typically use the high-level asyncio functions, | |
| such as <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>, and should rarely need to reference the loop | |
| object or call its methods. This section is intended mostly for authors | |
| of lower-level code, libraries, and frameworks, who need finer control over | |
| the event loop behavior.</p> | |
| <p class="rubric">Obtaining the Event Loop</p> | |
| <p>The following low-level functions can be used to get, set, or create | |
| an event loop:</p> | |
| <dl class="py function"> | |
| <dt class="sig sig-object py" id="asyncio.get_running_loop"> | |
| <span class="sig-prename descclassname"><span class="pre">asyncio.</span></span><span class="sig-name descname"><span class="pre">get_running_loop</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.get_running_loop" title="Link to this definition">¶</a></dt> | |
| <dd><p>Return the running event loop in the current OS thread.</p> | |
| <p>Raise a <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> if there is no running event loop.</p> | |
| <p>This function can only be called from a coroutine or a callback.</p> | |
| <div class="versionadded"> | |
| <p><span class="versionmodified added">Added in version 3.7.</span></p> | |
| </div> | |
| </dd></dl> | |
| <dl class="py function"> | |
| <dt class="sig sig-object py" id="asyncio.get_event_loop"> | |
| <span class="sig-prename descclassname"><span class="pre">asyncio.</span></span><span class="sig-name descname"><span class="pre">get_event_loop</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.get_event_loop" title="Link to this definition">¶</a></dt> | |
| <dd><p>Get the current event loop.</p> | |
| <p>When called from a coroutine or a callback (e.g. scheduled with | |
| call_soon or similar API), this function will always return the | |
| running event loop.</p> | |
| <p>If there is no running event loop set, the function will return | |
| the result of the <code class="docutils literal notranslate"><span class="pre">get_event_loop_policy().get_event_loop()</span></code> call.</p> | |
| <p>Because this function has rather complex behavior (especially | |
| when custom event loop policies are in use), using the | |
| <a class="reference internal" href="#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> function is preferred to <code class="xref py py-func docutils literal notranslate"><span class="pre">get_event_loop()</span></code> | |
| in coroutines and callbacks.</p> | |
| <p>As noted above, consider using the higher-level <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, | |
| instead of using these lower level functions to manually create and close an | |
| event loop.</p> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.14: </span>Raises a <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> if there is no current event loop.</p> | |
| </div> | |
| <div class="admonition note"> | |
| <p class="admonition-title">Note</p> | |
| <p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">asyncio</span></code> policy system is deprecated and will be removed | |
| in Python 3.16; from there on, this function will return the current | |
| running event loop if present else it will return the | |
| loop set by <a class="reference internal" href="#asyncio.set_event_loop" title="asyncio.set_event_loop"><code class="xref py py-func docutils literal notranslate"><span class="pre">set_event_loop()</span></code></a>.</p> | |
| </div> | |
| </dd></dl> | |
| <dl class="py function"> | |
| <dt class="sig sig-object py" id="asyncio.set_event_loop"> | |
| <span class="sig-prename descclassname"><span class="pre">asyncio.</span></span><span class="sig-name descname"><span class="pre">set_event_loop</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">loop</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.set_event_loop" title="Link to this definition">¶</a></dt> | |
| <dd><p>Set <em>loop</em> as the current event loop for the current OS thread.</p> | |
| </dd></dl> | |
| <dl class="py function"> | |
| <dt class="sig sig-object py" id="asyncio.new_event_loop"> | |
| <span class="sig-prename descclassname"><span class="pre">asyncio.</span></span><span class="sig-name descname"><span class="pre">new_event_loop</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.new_event_loop" title="Link to this definition">¶</a></dt> | |
| <dd><p>Create and return a new event loop object.</p> | |
| </dd></dl> | |
| <p>Note that the behaviour of <a class="reference internal" href="#asyncio.get_event_loop" title="asyncio.get_event_loop"><code class="xref py py-func docutils literal notranslate"><span class="pre">get_event_loop()</span></code></a>, <a class="reference internal" href="#asyncio.set_event_loop" title="asyncio.set_event_loop"><code class="xref py py-func docutils literal notranslate"><span class="pre">set_event_loop()</span></code></a>, | |
| and <a class="reference internal" href="#asyncio.new_event_loop" title="asyncio.new_event_loop"><code class="xref py py-func docutils literal notranslate"><span class="pre">new_event_loop()</span></code></a> functions can be altered by | |
| <a class="reference internal" href="asyncio-policy.html#asyncio-policies"><span class="std std-ref">setting a custom event loop policy</span></a>.</p> | |
| <p class="rubric">Contents</p> | |
| <p>This documentation page contains the following sections:</p> | |
| <ul class="simple"> | |
| <li><p>The <a class="reference internal" href="#event-loop-methods">Event Loop Methods</a> section is the reference documentation of | |
| the event loop APIs;</p></li> | |
| <li><p>The <a class="reference internal" href="#callback-handles">Callback Handles</a> section documents the <a class="reference internal" href="#asyncio.Handle" title="asyncio.Handle"><code class="xref py py-class docutils literal notranslate"><span class="pre">Handle</span></code></a> and | |
| <a class="reference internal" href="#asyncio.TimerHandle" title="asyncio.TimerHandle"><code class="xref py py-class docutils literal notranslate"><span class="pre">TimerHandle</span></code></a> instances which are returned from scheduling | |
| methods such as <a class="reference internal" href="#asyncio.loop.call_soon" title="asyncio.loop.call_soon"><code class="xref py py-meth docutils literal notranslate"><span class="pre">loop.call_soon()</span></code></a> and <a class="reference internal" href="#asyncio.loop.call_later" title="asyncio.loop.call_later"><code class="xref py py-meth docutils literal notranslate"><span class="pre">loop.call_later()</span></code></a>;</p></li> | |
| <li><p>The <a class="reference internal" href="#server-objects">Server Objects</a> section documents types returned from | |
| event loop methods like <a class="reference internal" href="#asyncio.loop.create_server" title="asyncio.loop.create_server"><code class="xref py py-meth docutils literal notranslate"><span class="pre">loop.create_server()</span></code></a>;</p></li> | |
| <li><p>The <a class="reference internal" href="#event-loop-implementations">Event Loop Implementations</a> section documents the | |
| <a class="reference internal" href="#asyncio.SelectorEventLoop" title="asyncio.SelectorEventLoop"><code class="xref py py-class docutils literal notranslate"><span class="pre">SelectorEventLoop</span></code></a> and <a class="reference internal" href="#asyncio.ProactorEventLoop" title="asyncio.ProactorEventLoop"><code class="xref py py-class docutils literal notranslate"><span class="pre">ProactorEventLoop</span></code></a> classes;</p></li> | |
| <li><p>The <a class="reference internal" href="#examples">Examples</a> section showcases how to work with some event | |
| loop APIs.</p></li> | |
| </ul> | |
| <section id="event-loop-methods"> | |
| <span id="asyncio-event-loop-methods"></span><h2>Event Loop Methods<a class="headerlink" href="#event-loop-methods" title="Link to this heading">¶</a></h2> | |
| <p>Event loops have <strong>low-level</strong> APIs for the following:</p> | |
| <nav class="contents local" id="contents"> | |
| <ul class="simple"> | |
| <li><p><a class="reference internal" href="#running-and-stopping-the-loop" id="id1">Running and stopping the loop</a></p></li> | |
| <li><p><a class="reference internal" href="#scheduling-callbacks" id="id2">Scheduling callbacks</a></p></li> | |
| <li><p><a class="reference internal" href="#scheduling-delayed-callbacks" id="id3">Scheduling delayed callbacks</a></p></li> | |
| <li><p><a class="reference internal" href="#creating-futures-and-tasks" id="id4">Creating Futures and Tasks</a></p></li> | |
| <li><p><a class="reference internal" href="#opening-network-connections" id="id5">Opening network connections</a></p></li> | |
| <li><p><a class="reference internal" href="#creating-network-servers" id="id6">Creating network servers</a></p></li> | |
| <li><p><a class="reference internal" href="#transferring-files" id="id7">Transferring files</a></p></li> | |
| <li><p><a class="reference internal" href="#tls-upgrade" id="id8">TLS Upgrade</a></p></li> | |
| <li><p><a class="reference internal" href="#watching-file-descriptors" id="id9">Watching file descriptors</a></p></li> | |
| <li><p><a class="reference internal" href="#working-with-socket-objects-directly" id="id10">Working with socket objects directly</a></p></li> | |
| <li><p><a class="reference internal" href="#dns" id="id11">DNS</a></p></li> | |
| <li><p><a class="reference internal" href="#working-with-pipes" id="id12">Working with pipes</a></p></li> | |
| <li><p><a class="reference internal" href="#unix-signals" id="id13">Unix signals</a></p></li> | |
| <li><p><a class="reference internal" href="#executing-code-in-thread-or-process-pools" id="id14">Executing code in thread or process pools</a></p></li> | |
| <li><p><a class="reference internal" href="#error-handling-api" id="id15">Error Handling API</a></p></li> | |
| <li><p><a class="reference internal" href="#enabling-debug-mode" id="id16">Enabling debug mode</a></p></li> | |
| <li><p><a class="reference internal" href="#running-subprocesses" id="id17">Running Subprocesses</a></p></li> | |
| </ul> | |
| </nav> | |
| <section id="running-and-stopping-the-loop"> | |
| <h3><a class="toc-backref" href="#id1" role="doc-backlink">Running and stopping the loop</a><a class="headerlink" href="#running-and-stopping-the-loop" title="Link to this heading">¶</a></h3> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.loop.run_until_complete"> | |
| <span class="sig-prename descclassname"><span class="pre">loop.</span></span><span class="sig-name descname"><span class="pre">run_until_complete</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">future</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.run_until_complete" title="Link to this definition">¶</a></dt> | |
| <dd><p>Run until the <em>future</em> (an instance of <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>) has | |
| completed.</p> | |
| <p>If the argument is a <a class="reference internal" href="asyncio-task.html#coroutine"><span class="std std-ref">coroutine object</span></a> it | |
| is implicitly scheduled to run as a <a class="reference internal" href="asyncio-task.html#asyncio.Task" title="asyncio.Task"><code class="xref py py-class docutils literal notranslate"><span class="pre">asyncio.Task</span></code></a>.</p> | |
| <p>Return the Future’s result or raise its exception.</p> | |
| </dd></dl> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.loop.run_forever"> | |
| <span class="sig-prename descclassname"><span class="pre">loop.</span></span><span class="sig-name descname"><span class="pre">run_forever</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.run_forever" title="Link to this definition">¶</a></dt> | |
| <dd><p>Run the event loop until <a class="reference internal" href="#asyncio.loop.stop" title="asyncio.loop.stop"><code class="xref py py-meth docutils literal notranslate"><span class="pre">stop()</span></code></a> is called.</p> | |
| <p>If <a class="reference internal" href="#asyncio.loop.stop" title="asyncio.loop.stop"><code class="xref py py-meth docutils literal notranslate"><span class="pre">stop()</span></code></a> is called before <code class="xref py py-meth docutils literal notranslate"><span class="pre">run_forever()</span></code> is called, | |
| the loop will poll the I/O selector once with a timeout of zero, | |
| run all callbacks scheduled in response to I/O events (and | |
| those that were already scheduled), and then exit.</p> | |
| <p>If <a class="reference internal" href="#asyncio.loop.stop" title="asyncio.loop.stop"><code class="xref py py-meth docutils literal notranslate"><span class="pre">stop()</span></code></a> is called while <code class="xref py py-meth docutils literal notranslate"><span class="pre">run_forever()</span></code> is running, | |
| the loop will run the current batch of callbacks and then exit. | |
| Note that new callbacks scheduled by callbacks will not run in this | |
| case; instead, they will run the next time <code class="xref py py-meth docutils literal notranslate"><span class="pre">run_forever()</span></code> or | |
| <a class="reference internal" href="#asyncio.loop.run_until_complete" title="asyncio.loop.run_until_complete"><code class="xref py py-meth docutils literal notranslate"><span class="pre">run_until_complete()</span></code></a> is called.</p> | |
| </dd></dl> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.loop.stop"> | |
| <span class="sig-prename descclassname"><span class="pre">loop.</span></span><span class="sig-name descname"><span class="pre">stop</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.stop" title="Link to this definition">¶</a></dt> | |
| <dd><p>Stop the event loop.</p> | |
| </dd></dl> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.loop.is_running"> | |
| <span class="sig-prename descclassname"><span class="pre">loop.</span></span><span class="sig-name descname"><span class="pre">is_running</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.is_running" title="Link to this definition">¶</a></dt> | |
| <dd><p>Return <code class="docutils literal notranslate"><span class="pre">True</span></code> if the event loop is currently running.</p> | |
| </dd></dl> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.loop.is_closed"> | |
| <span class="sig-prename descclassname"><span class="pre">loop.</span></span><span class="sig-name descname"><span class="pre">is_closed</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.is_closed" title="Link to this definition">¶</a></dt> | |
| <dd><p>Return <code class="docutils literal notranslate"><span class="pre">True</span></code> if the event loop was closed.</p> | |
| </dd></dl> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.loop.close"> | |
| <span class="sig-prename descclassname"><span class="pre">loop.</span></span><span class="sig-name descname"><span class="pre">close</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.close" title="Link to this definition">¶</a></dt> | |
| <dd><p>Close the event loop.</p> | |
| <p>The loop must not be running when this function is called. | |
| Any pending callbacks will be discarded.</p> | |
| <p>This method clears all queues and shuts down the executor, but does | |
| not wait for the executor to finish.</p> | |
| <p>This method is idempotent and irreversible. No other methods | |
| should be called after the event loop is closed.</p> | |
| </dd></dl> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.loop.shutdown_asyncgens"> | |
| <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">loop.</span></span><span class="sig-name descname"><span class="pre">shutdown_asyncgens</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.shutdown_asyncgens" title="Link to this definition">¶</a></dt> | |
| <dd><p>Schedule all currently open <a class="reference internal" href="../glossary.html#term-asynchronous-generator"><span class="xref std std-term">asynchronous generator</span></a> objects to | |
| close with an <a class="reference internal" href="../reference/expressions.html#agen.aclose" title="agen.aclose"><code class="xref py py-meth docutils literal notranslate"><span class="pre">aclose()</span></code></a> call. After calling this method, | |
| the event loop will issue a warning if a new asynchronous generator | |
| is iterated. This should be used to reliably finalize all scheduled | |
| asynchronous generators.</p> | |
| <p>Note that there is no need to call this function when | |
| <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> is used.</p> | |
| <p>Example:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">try</span><span class="p">:</span> | |
| <span class="n">loop</span><span class="o">.</span><span class="n">run_forever</span><span class="p">()</span> | |
| <span class="k">finally</span><span class="p">:</span> | |
| <span class="n">loop</span><span class="o">.</span><span class="n">run_until_complete</span><span class="p">(</span><span class="n">loop</span><span class="o">.</span><span class="n">shutdown_asyncgens</span><span class="p">())</span> | |
| <span class="n">loop</span><span class="o">.</span><span class="n">close</span><span class="p">()</span> | |
| </pre></div> | |
| </div> | |
| <div class="versionadded"> | |
| <p><span class="versionmodified added">Added in version 3.6.</span></p> | |
| </div> | |
| </dd></dl> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.loop.shutdown_default_executor"> | |
| <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">loop.</span></span><span class="sig-name descname"><span class="pre">shutdown_default_executor</span></span><span class="sig-paren">(</span><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.loop.shutdown_default_executor" title="Link to this definition">¶</a></dt> | |
| <dd><p>Schedule the closure of the default executor and wait for it to join all of | |
| the threads in the <a class="reference internal" href="concurrent.futures.html#concurrent.futures.ThreadPoolExecutor" title="concurrent.futures.ThreadPoolExecutor"><code class="xref py py-class docutils literal notranslate"><span class="pre">ThreadPoolExecutor</span></code></a>. | |
| Once this method has been called, | |
| using the default executor with <a class="reference internal" href="#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> | |
| will raise a <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>.</p> | |
| <p>The <em>timeout</em> parameter specifies the amount of time | |
| (in <a class="reference internal" href="functions.html#float" title="float"><code class="xref py py-class docutils literal notranslate"><span class="pre">float</span></code></a> seconds) the executor will be given to finish joining. | |
| With the default, <code class="docutils literal notranslate"><span class="pre">None</span></code>, | |
| the executor is allowed an unlimited amount of time.</p> | |
| <p>If the <em>timeout</em> is reached, a <a class="reference internal" href="exceptions.html#RuntimeWarning" title="RuntimeWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">RuntimeWarning</span></code></a> is emitted | |
| and the default executor is terminated | |
| without waiting for its threads to finish joining.</p> | |
| <div class="admonition note"> | |
| <p class="admonition-title">Note</p> | |
| <p>Do not call this method when using <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>, | |
| as the latter handles default executor shutdown automatically.</p> | |
| </div> | |
| <div class="versionadded"> | |
| <p><span class="versionmodified added">Added in version 3.9.</span></p> | |
| </div> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.12: </span>Added the <em>timeout</em> parameter.</p> | |
| </div> | |
| </dd></dl> | |
| </section> | |
| <section id="scheduling-callbacks"> | |
| <h3><a class="toc-backref" href="#id2" role="doc-backlink">Scheduling callbacks</a><a class="headerlink" href="#scheduling-callbacks" title="Link to this heading">¶</a></h3> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.loop.call_soon"> | |
| <span class="sig-prename descclassname"><span class="pre">loop.</span></span><span class="sig-name descname"><span class="pre">call_soon</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">callback</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</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.loop.call_soon" title="Link to this definition">¶</a></dt> | |
| <dd><p>Schedule the <em>callback</em> <a class="reference internal" href="../glossary.html#term-callback"><span class="xref std std-term">callback</span></a> to be called with | |
| <em>args</em> arguments at the next iteration of the event loop.</p> | |
| <p>Return an instance of <a class="reference internal" href="#asyncio.Handle" title="asyncio.Handle"><code class="xref py py-class docutils literal notranslate"><span class="pre">asyncio.Handle</span></code></a>, | |
| which can be used later to cancel the callback.</p> | |
| <p>Callbacks are called in the order in which they are registered. | |
| Each callback will be called exactly once.</p> | |
| <p>The optional keyword-only <em>context</em> argument specifies a | |
| custom <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>callback</em> to run in. | |
| Callbacks use the current context when no <em>context</em> is provided.</p> | |
| <p>Unlike <a class="reference internal" href="#asyncio.loop.call_soon_threadsafe" title="asyncio.loop.call_soon_threadsafe"><code class="xref py py-meth docutils literal notranslate"><span class="pre">call_soon_threadsafe()</span></code></a>, this method is not thread-safe.</p> | |
| </dd></dl> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.loop.call_soon_threadsafe"> | |
| <span class="sig-prename descclassname"><span class="pre">loop.</span></span><span class="sig-name descname"><span class="pre">call_soon_threadsafe</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">callback</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</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.loop.call_soon_threadsafe" title="Link to this definition">¶</a></dt> | |
| <dd><p>A thread-safe variant of <a class="reference internal" href="#asyncio.loop.call_soon" title="asyncio.loop.call_soon"><code class="xref py py-meth docutils literal notranslate"><span class="pre">call_soon()</span></code></a>. When scheduling callbacks from | |
| another thread, this function <em>must</em> be used, since <code class="xref py py-meth docutils literal notranslate"><span class="pre">call_soon()</span></code> is not | |
| thread-safe.</p> | |
| <p>This function is safe to be called from a reentrant context or signal handler, | |
| however, it is not safe or fruitful to use the returned handle in such contexts.</p> | |
| <p>Raises <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> if called on a loop that’s been closed. | |
| This can happen on a secondary thread when the main application is | |
| shutting down.</p> | |
| <p>See the <a class="reference internal" href="asyncio-dev.html#asyncio-multithreading"><span class="std std-ref">concurrency and multithreading</span></a> | |
| section of the documentation.</p> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.7: </span>The <em>context</em> keyword-only parameter was added. See <span class="target" id="index-0"></span><a class="pep reference external" href="https://peps.python.org/pep-0567/"><strong>PEP 567</strong></a> | |
| for more details.</p> | |
| </div> | |
| </dd></dl> | |
| <div class="admonition note" id="asyncio-pass-keywords"> | |
| <p class="admonition-title">Note</p> | |
| <p>Most <a class="reference internal" href="asyncio.html#module-asyncio" title="asyncio: Asynchronous I/O."><code class="xref py py-mod docutils literal notranslate"><span class="pre">asyncio</span></code></a> scheduling functions don’t allow passing | |
| keyword arguments. To do that, use <a class="reference internal" href="functools.html#functools.partial" title="functools.partial"><code class="xref py py-func docutils literal notranslate"><span class="pre">functools.partial()</span></code></a>:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="c1"># will schedule "print("Hello", flush=True)"</span> | |
| <span class="n">loop</span><span class="o">.</span><span class="n">call_soon</span><span class="p">(</span> | |
| <span class="n">functools</span><span class="o">.</span><span class="n">partial</span><span class="p">(</span><span class="nb">print</span><span class="p">,</span> <span class="s2">"Hello"</span><span class="p">,</span> <span class="n">flush</span><span class="o">=</span><span class="kc">True</span><span class="p">))</span> | |
| </pre></div> | |
| </div> | |
| <p>Using partial objects is usually more convenient than using lambdas, | |
| as asyncio can render partial objects better in debug and error | |
| messages.</p> | |
| </div> | |
| </section> | |
| <section id="scheduling-delayed-callbacks"> | |
| <span id="asyncio-delayed-calls"></span><h3><a class="toc-backref" href="#id3" role="doc-backlink">Scheduling delayed callbacks</a><a class="headerlink" href="#scheduling-delayed-callbacks" title="Link to this heading">¶</a></h3> | |
| <p>Event loop provides mechanisms to schedule callback functions | |
| to be called at some point in the future. Event loop uses monotonic | |
| clocks to track time.</p> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.loop.call_later"> | |
| <span class="sig-prename descclassname"><span class="pre">loop.</span></span><span class="sig-name descname"><span class="pre">call_later</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">callback</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</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.loop.call_later" title="Link to this definition">¶</a></dt> | |
| <dd><p>Schedule <em>callback</em> to be called after the given <em>delay</em> | |
| number of seconds (can be either an int or a float).</p> | |
| <p>An instance of <a class="reference internal" href="#asyncio.TimerHandle" title="asyncio.TimerHandle"><code class="xref py py-class docutils literal notranslate"><span class="pre">asyncio.TimerHandle</span></code></a> is returned which can | |
| be used to cancel the callback.</p> | |
| <p><em>callback</em> will be called exactly once. If two callbacks are | |
| scheduled for exactly the same time, the order in which they | |
| are called is undefined.</p> | |
| <p>The optional positional <em>args</em> will be passed to the callback when | |
| it is called. Use <a class="reference internal" href="functools.html#functools.partial" title="functools.partial"><code class="xref py py-func docutils literal notranslate"><span class="pre">functools.partial()</span></code></a> | |
| <a class="reference internal" href="#asyncio-pass-keywords"><span class="std std-ref">to pass keyword arguments</span></a> to | |
| <em>callback</em>.</p> | |
| <p>An optional keyword-only <em>context</em> argument allows specifying a | |
| custom <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>callback</em> to run in. | |
| The current context is used when no <em>context</em> is provided.</p> | |
| <div class="admonition note"> | |
| <p class="admonition-title">Note</p> | |
| <p>For performance, callbacks scheduled with <code class="xref py py-meth docutils literal notranslate"><span class="pre">loop.call_later()</span></code> | |
| may run up to one clock-resolution early (see | |
| <code class="docutils literal notranslate"><span class="pre">time.get_clock_info('monotonic').resolution</span></code>).</p> | |
| </div> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.7: </span>The <em>context</em> keyword-only parameter was added. See <span class="target" id="index-1"></span><a class="pep reference external" href="https://peps.python.org/pep-0567/"><strong>PEP 567</strong></a> | |
| for more details.</p> | |
| </div> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.8: </span>In Python 3.7 and earlier with the default event loop implementation, | |
| the <em>delay</em> could not exceed one day. | |
| This has been fixed in Python 3.8.</p> | |
| </div> | |
| </dd></dl> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.loop.call_at"> | |
| <span class="sig-prename descclassname"><span class="pre">loop.</span></span><span class="sig-name descname"><span class="pre">call_at</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">when</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">callback</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</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.loop.call_at" title="Link to this definition">¶</a></dt> | |
| <dd><p>Schedule <em>callback</em> to be called at the given absolute timestamp | |
| <em>when</em> (an int or a float), using the same time reference as | |
| <a class="reference internal" href="#asyncio.loop.time" title="asyncio.loop.time"><code class="xref py py-meth docutils literal notranslate"><span class="pre">loop.time()</span></code></a>.</p> | |
| <p>This method’s behavior is the same as <a class="reference internal" href="#asyncio.loop.call_later" title="asyncio.loop.call_later"><code class="xref py py-meth docutils literal notranslate"><span class="pre">call_later()</span></code></a>.</p> | |
| <p>An instance of <a class="reference internal" href="#asyncio.TimerHandle" title="asyncio.TimerHandle"><code class="xref py py-class docutils literal notranslate"><span class="pre">asyncio.TimerHandle</span></code></a> is returned which can | |
| be used to cancel the callback.</p> | |
| <div class="admonition note"> | |
| <p class="admonition-title">Note</p> | |
| <p>For performance, callbacks scheduled with <code class="xref py py-meth docutils literal notranslate"><span class="pre">loop.call_at()</span></code> | |
| may run up to one clock-resolution early (see | |
| <code class="docutils literal notranslate"><span class="pre">time.get_clock_info('monotonic').resolution</span></code>).</p> | |
| </div> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.7: </span>The <em>context</em> keyword-only parameter was added. See <span class="target" id="index-2"></span><a class="pep reference external" href="https://peps.python.org/pep-0567/"><strong>PEP 567</strong></a> | |
| for more details.</p> | |
| </div> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.8: </span>In Python 3.7 and earlier with the default event loop implementation, | |
| the difference between <em>when</em> and the current time could not exceed | |
| one day. This has been fixed in Python 3.8.</p> | |
| </div> | |
| </dd></dl> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.loop.time"> | |
| <span class="sig-prename descclassname"><span class="pre">loop.</span></span><span class="sig-name descname"><span class="pre">time</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.time" title="Link to this definition">¶</a></dt> | |
| <dd><p>Return the current time, as a <a class="reference internal" href="functions.html#float" title="float"><code class="xref py py-class docutils literal notranslate"><span class="pre">float</span></code></a> value, according to | |
| the event loop’s internal monotonic clock.</p> | |
| </dd></dl> | |
| <div class="admonition note"> | |
| <p class="admonition-title">Note</p> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.8: </span>In Python 3.7 and earlier timeouts (relative <em>delay</em> or absolute <em>when</em>) | |
| should not exceed one day. This has been fixed in Python 3.8.</p> | |
| </div> | |
| </div> | |
| <div class="admonition seealso"> | |
| <p class="admonition-title">See also</p> | |
| <p>The <a class="reference internal" href="asyncio-task.html#asyncio.sleep" title="asyncio.sleep"><code class="xref py py-func docutils literal notranslate"><span class="pre">asyncio.sleep()</span></code></a> function.</p> | |
| </div> | |
| </section> | |
| <section id="creating-futures-and-tasks"> | |
| <h3><a class="toc-backref" href="#id4" role="doc-backlink">Creating Futures and Tasks</a><a class="headerlink" href="#creating-futures-and-tasks" title="Link to this heading">¶</a></h3> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.loop.create_future"> | |
| <span class="sig-prename descclassname"><span class="pre">loop.</span></span><span class="sig-name descname"><span class="pre">create_future</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.create_future" title="Link to this definition">¶</a></dt> | |
| <dd><p>Create an <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">asyncio.Future</span></code></a> object attached to the event loop.</p> | |
| <p>This is the preferred way to create Futures in asyncio. This lets | |
| third-party event loops provide alternative implementations of | |
| the Future object (with better performance or instrumentation).</p> | |
| <div class="versionadded"> | |
| <p><span class="versionmodified added">Added in version 3.5.2.</span></p> | |
| </div> | |
| </dd></dl> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.loop.create_task"> | |
| <span class="sig-prename descclassname"><span class="pre">loop.</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.loop.create_task" title="Link to this definition">¶</a></dt> | |
| <dd><p>Schedule the execution of <a class="reference internal" href="asyncio-task.html#coroutine"><span class="std std-ref">coroutine</span></a> <em>coro</em>. | |
| Return a <a class="reference internal" href="asyncio-task.html#asyncio.Task" title="asyncio.Task"><code class="xref py py-class docutils literal notranslate"><span class="pre">Task</span></code></a> object.</p> | |
| <p>Third-party event loops can use their own subclass of <a class="reference internal" href="asyncio-task.html#asyncio.Task" title="asyncio.Task"><code class="xref py py-class docutils literal notranslate"><span class="pre">Task</span></code></a> | |
| for interoperability. In this case, the result type is a subclass | |
| of <code class="xref py py-class docutils literal notranslate"><span class="pre">Task</span></code>.</p> | |
| <p>The full function signature is largely the same as that of the | |
| <a class="reference internal" href="asyncio-task.html#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 to | |
| this function are passed through to that interface.</p> | |
| <p>If the <em>name</em> argument is provided and not <code class="docutils literal notranslate"><span class="pre">None</span></code>, it is set as | |
| the name of the task using <a class="reference internal" href="asyncio-task.html#asyncio.Task.set_name" title="asyncio.Task.set_name"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Task.set_name()</span></code></a>.</p> | |
| <p>An optional keyword-only <em>context</em> argument allows specifying a | |
| custom <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. | |
| The current context copy is created when no <em>context</em> is provided.</p> | |
| <p>An optional keyword-only <em>eager_start</em> argument allows specifying | |
| if the task should execute eagerly during the call to create_task, | |
| or be scheduled later. If <em>eager_start</em> is not passed the mode set | |
| by <a class="reference internal" href="#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> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.8: </span>Added the <em>name</em> parameter.</p> | |
| </div> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.11: </span>Added the <em>context</em> parameter.</p> | |
| </div> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.13.3: </span>Added <code class="docutils literal notranslate"><span class="pre">kwargs</span></code> which passes on arbitrary extra parameters, including <code class="docutils literal notranslate"><span class="pre">name</span></code> and <code class="docutils literal notranslate"><span class="pre">context</span></code>.</p> | |
| </div> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.13.4: </span>Rolled back the change that passes on <em>name</em> and <em>context</em> (if it is None), | |
| while still passing on other arbitrary keyword arguments (to avoid breaking backwards compatibility with 3.13.3).</p> | |
| </div> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.14: </span>All <em>kwargs</em> are now passed on. The <em>eager_start</em> parameter works with eager task factories.</p> | |
| </div> | |
| </dd></dl> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.loop.set_task_factory"> | |
| <span class="sig-prename descclassname"><span class="pre">loop.</span></span><span class="sig-name descname"><span class="pre">set_task_factory</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">factory</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.set_task_factory" title="Link to this definition">¶</a></dt> | |
| <dd><p>Set a task factory that will be used by | |
| <a class="reference internal" href="#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> | |
| <p>If <em>factory</em> is <code class="docutils literal notranslate"><span class="pre">None</span></code> the default task factory will be set. | |
| Otherwise, <em>factory</em> must be a <em>callable</em> with the signature matching | |
| <code class="docutils literal notranslate"><span class="pre">(loop,</span> <span class="pre">coro,</span> <span class="pre">**kwargs)</span></code>, where <em>loop</em> is a reference to the active | |
| event loop, and <em>coro</em> is a coroutine object. The callable | |
| must pass on all <em>kwargs</em>, and return a <a class="reference internal" href="asyncio-task.html#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> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.13.3: </span>Required that all <em>kwargs</em> are passed on to <a class="reference internal" href="asyncio-task.html#asyncio.Task" title="asyncio.Task"><code class="xref py py-class docutils literal notranslate"><span class="pre">asyncio.Task</span></code></a>.</p> | |
| </div> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.13.4: </span><em>name</em> is no longer passed to task factories. <em>context</em> is no longer passed | |
| to task factories if it is <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.14: </span><em>name</em> and <em>context</em> are now unconditionally passed on to task factories again.</p> | |
| </div> | |
| </div> | |
| </dd></dl> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.loop.get_task_factory"> | |
| <span class="sig-prename descclassname"><span class="pre">loop.</span></span><span class="sig-name descname"><span class="pre">get_task_factory</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.get_task_factory" title="Link to this definition">¶</a></dt> | |
| <dd><p>Return a task factory or <code class="docutils literal notranslate"><span class="pre">None</span></code> if the default one is in use.</p> | |
| </dd></dl> | |
| </section> | |
| <section id="opening-network-connections"> | |
| <h3><a class="toc-backref" href="#id5" role="doc-backlink">Opening network connections</a><a class="headerlink" href="#opening-network-connections" title="Link to this heading">¶</a></h3> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.loop.create_connection"> | |
| <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">loop.</span></span><span class="sig-name descname"><span class="pre">create_connection</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">protocol_factory</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">host</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">port</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="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">ssl</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">family</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">proto</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">flags</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">sock</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">local_addr</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">server_hostname</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">ssl_handshake_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">ssl_shutdown_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">happy_eyeballs_delay</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">interleave</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">all_errors</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.loop.create_connection" title="Link to this definition">¶</a></dt> | |
| <dd><p>Open a streaming transport connection to a given | |
| address specified by <em>host</em> and <em>port</em>.</p> | |
| <p>The socket family can be either <a class="reference internal" href="socket.html#socket.AF_INET" title="socket.AF_INET"><code class="xref py py-const docutils literal notranslate"><span class="pre">AF_INET</span></code></a> or | |
| <a class="reference internal" href="socket.html#socket.AF_INET6" title="socket.AF_INET6"><code class="xref py py-const docutils literal notranslate"><span class="pre">AF_INET6</span></code></a> depending on <em>host</em> (or the <em>family</em> | |
| argument, if provided).</p> | |
| <p>The socket type will be <a class="reference internal" href="socket.html#socket.SOCK_STREAM" title="socket.SOCK_STREAM"><code class="xref py py-const docutils literal notranslate"><span class="pre">SOCK_STREAM</span></code></a>.</p> | |
| <p><em>protocol_factory</em> must be a callable returning an | |
| <a class="reference internal" href="asyncio-protocol.html#asyncio-protocol"><span class="std std-ref">asyncio protocol</span></a> implementation.</p> | |
| <p>This method will try to establish the connection in the background. | |
| When successful, it returns a <code class="docutils literal notranslate"><span class="pre">(transport,</span> <span class="pre">protocol)</span></code> pair.</p> | |
| <p>The chronological synopsis of the underlying operation is as follows:</p> | |
| <ol class="arabic simple"> | |
| <li><p>The connection is established and a <a class="reference internal" href="asyncio-protocol.html#asyncio-transport"><span class="std std-ref">transport</span></a> | |
| is created for it.</p></li> | |
| <li><p><em>protocol_factory</em> is called without arguments and is expected to | |
| return a <a class="reference internal" href="asyncio-protocol.html#asyncio-protocol"><span class="std std-ref">protocol</span></a> instance.</p></li> | |
| <li><p>The protocol instance is coupled with the transport by calling its | |
| <a class="reference internal" href="asyncio-protocol.html#asyncio.BaseProtocol.connection_made" title="asyncio.BaseProtocol.connection_made"><code class="xref py py-meth docutils literal notranslate"><span class="pre">connection_made()</span></code></a> method.</p></li> | |
| <li><p>A <code class="docutils literal notranslate"><span class="pre">(transport,</span> <span class="pre">protocol)</span></code> tuple is returned on success.</p></li> | |
| </ol> | |
| <p>The created transport is an implementation-dependent bidirectional | |
| stream.</p> | |
| <p>Other arguments:</p> | |
| <ul> | |
| <li><p><em>ssl</em>: if given and not false, a SSL/TLS transport is created | |
| (by default a plain TCP transport is created). If <em>ssl</em> is | |
| a <a class="reference internal" href="ssl.html#ssl.SSLContext" title="ssl.SSLContext"><code class="xref py py-class docutils literal notranslate"><span class="pre">ssl.SSLContext</span></code></a> object, this context is used to create | |
| the transport; if <em>ssl</em> is <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a>, a default context returned | |
| from <a class="reference internal" href="ssl.html#ssl.create_default_context" title="ssl.create_default_context"><code class="xref py py-func docutils literal notranslate"><span class="pre">ssl.create_default_context()</span></code></a> is used.</p> | |
| <div class="admonition seealso"> | |
| <p class="admonition-title">See also</p> | |
| <p><a class="reference internal" href="ssl.html#ssl-security"><span class="std std-ref">SSL/TLS security considerations</span></a></p> | |
| </div> | |
| </li> | |
| <li><p><em>server_hostname</em> sets or overrides the hostname that the target | |
| server’s certificate will be matched against. Should only be passed | |
| if <em>ssl</em> is not <code class="docutils literal notranslate"><span class="pre">None</span></code>. By default the value of the <em>host</em> argument | |
| is used. If <em>host</em> is empty, there is no default and you must pass a | |
| value for <em>server_hostname</em>. If <em>server_hostname</em> is an empty | |
| string, hostname matching is disabled (which is a serious security | |
| risk, allowing for potential man-in-the-middle attacks).</p></li> | |
| <li><p><em>family</em>, <em>proto</em>, <em>flags</em> are the optional address family, protocol | |
| and flags to be passed through to getaddrinfo() for <em>host</em> resolution. | |
| If given, these should all be integers from the corresponding | |
| <a class="reference internal" href="socket.html#module-socket" title="socket: Low-level networking interface."><code class="xref py py-mod docutils literal notranslate"><span class="pre">socket</span></code></a> module constants.</p></li> | |
| <li><p><em>happy_eyeballs_delay</em>, if given, enables Happy Eyeballs for this | |
| connection. It should | |
| be a floating-point number representing the amount of time in seconds | |
| to wait for a connection attempt to complete, before starting the next | |
| attempt in parallel. This is the “Connection Attempt Delay” as defined | |
| in <span class="target" id="index-3"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc8305.html"><strong>RFC 8305</strong></a>. A sensible default value recommended by the RFC is <code class="docutils literal notranslate"><span class="pre">0.25</span></code> | |
| (250 milliseconds).</p></li> | |
| <li><p><em>interleave</em> controls address reordering when a host name resolves to | |
| multiple IP addresses. | |
| If <code class="docutils literal notranslate"><span class="pre">0</span></code> or unspecified, no reordering is done, and addresses are | |
| tried in the order returned by <a class="reference internal" href="#asyncio.loop.getaddrinfo" title="asyncio.loop.getaddrinfo"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getaddrinfo()</span></code></a>. If a positive integer | |
| is specified, the addresses are interleaved by address family, and the | |
| given integer is interpreted as “First Address Family Count” as defined | |
| in <span class="target" id="index-4"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc8305.html"><strong>RFC 8305</strong></a>. The default is <code class="docutils literal notranslate"><span class="pre">0</span></code> if <em>happy_eyeballs_delay</em> is not | |
| specified, and <code class="docutils literal notranslate"><span class="pre">1</span></code> if it is.</p></li> | |
| <li><p><em>sock</em>, if given, should be an existing, already connected | |
| <a class="reference internal" href="socket.html#socket.socket" title="socket.socket"><code class="xref py py-class docutils literal notranslate"><span class="pre">socket.socket</span></code></a> object to be used by the transport. | |
| If <em>sock</em> is given, none of <em>host</em>, <em>port</em>, <em>family</em>, <em>proto</em>, <em>flags</em>, | |
| <em>happy_eyeballs_delay</em>, <em>interleave</em> | |
| and <em>local_addr</em> should be specified.</p> | |
| <div class="admonition note"> | |
| <p class="admonition-title">Note</p> | |
| <p>The <em>sock</em> argument transfers ownership of the socket to the | |
| transport created. To close the socket, call the transport’s | |
| <a class="reference internal" href="asyncio-protocol.html#asyncio.BaseTransport.close" title="asyncio.BaseTransport.close"><code class="xref py py-meth docutils literal notranslate"><span class="pre">close()</span></code></a> method.</p> | |
| </div> | |
| </li> | |
| <li><p><em>local_addr</em>, if given, is a <code class="docutils literal notranslate"><span class="pre">(local_host,</span> <span class="pre">local_port)</span></code> tuple used | |
| to bind the socket locally. The <em>local_host</em> and <em>local_port</em> | |
| are looked up using <code class="docutils literal notranslate"><span class="pre">getaddrinfo()</span></code>, similarly to <em>host</em> and <em>port</em>.</p></li> | |
| <li><p><em>ssl_handshake_timeout</em> is (for a TLS connection) the time in seconds | |
| to wait for the TLS handshake to complete before aborting the connection. | |
| <code class="docutils literal notranslate"><span class="pre">60.0</span></code> seconds if <code class="docutils literal notranslate"><span class="pre">None</span></code> (default).</p></li> | |
| <li><p><em>ssl_shutdown_timeout</em> is the time in seconds to wait for the SSL shutdown | |
| to complete before aborting the connection. <code class="docutils literal notranslate"><span class="pre">30.0</span></code> seconds if <code class="docutils literal notranslate"><span class="pre">None</span></code> | |
| (default).</p></li> | |
| <li><p><em>all_errors</em> determines what exceptions are raised when a connection cannot | |
| be created. By default, only a single <code class="docutils literal notranslate"><span class="pre">Exception</span></code> is raised: the first | |
| exception if there is only one or all errors have same message, or a single | |
| <code class="docutils literal notranslate"><span class="pre">OSError</span></code> with the error messages combined. When <code class="docutils literal notranslate"><span class="pre">all_errors</span></code> is <code class="docutils literal notranslate"><span class="pre">True</span></code>, | |
| an <code class="docutils literal notranslate"><span class="pre">ExceptionGroup</span></code> will be raised containing all exceptions (even if there | |
| is only one).</p></li> | |
| </ul> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.5: </span>Added support for SSL/TLS in <a class="reference internal" href="#asyncio.ProactorEventLoop" title="asyncio.ProactorEventLoop"><code class="xref py py-class docutils literal notranslate"><span class="pre">ProactorEventLoop</span></code></a>.</p> | |
| </div> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.6: </span>The socket option <a class="reference internal" href="socket.html#socket-unix-constants"><span class="std std-ref">socket.TCP_NODELAY</span></a> is set by default | |
| for all TCP connections.</p> | |
| </div> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.7: </span>Added the <em>ssl_handshake_timeout</em> parameter.</p> | |
| </div> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.8: </span>Added the <em>happy_eyeballs_delay</em> and <em>interleave</em> parameters.</p> | |
| <p>Happy Eyeballs Algorithm: Success with Dual-Stack Hosts. | |
| When a server’s IPv4 path and protocol are working, but the server’s | |
| IPv6 path and protocol are not working, a dual-stack client | |
| application experiences significant connection delay compared to an | |
| IPv4-only client. This is undesirable because it causes the | |
| dual-stack client to have a worse user experience. This document | |
| specifies requirements for algorithms that reduce this user-visible | |
| delay and provides an algorithm.</p> | |
| <p>For more information: <a class="reference external" href="https://datatracker.ietf.org/doc/html/rfc6555">https://datatracker.ietf.org/doc/html/rfc6555</a></p> | |
| </div> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.11: </span>Added the <em>ssl_shutdown_timeout</em> parameter.</p> | |
| </div> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.12: </span><em>all_errors</em> was added.</p> | |
| </div> | |
| <div class="admonition seealso"> | |
| <p class="admonition-title">See also</p> | |
| <p>The <a class="reference internal" href="asyncio-stream.html#asyncio.open_connection" title="asyncio.open_connection"><code class="xref py py-func docutils literal notranslate"><span class="pre">open_connection()</span></code></a> function is a high-level alternative | |
| API. It returns a pair of (<a class="reference internal" href="asyncio-stream.html#asyncio.StreamReader" title="asyncio.StreamReader"><code class="xref py py-class docutils literal notranslate"><span class="pre">StreamReader</span></code></a>, <a class="reference internal" href="asyncio-stream.html#asyncio.StreamWriter" title="asyncio.StreamWriter"><code class="xref py py-class docutils literal notranslate"><span class="pre">StreamWriter</span></code></a>) | |
| that can be used directly in async/await code.</p> | |
| </div> | |
| </dd></dl> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.loop.create_datagram_endpoint"> | |
| <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">loop.</span></span><span class="sig-name descname"><span class="pre">create_datagram_endpoint</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">protocol_factory</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">local_addr</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">remote_addr</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="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">family</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">proto</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">flags</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">reuse_port</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">allow_broadcast</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">sock</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.loop.create_datagram_endpoint" title="Link to this definition">¶</a></dt> | |
| <dd><p>Create a datagram connection.</p> | |
| <p>The socket family can be either <a class="reference internal" href="socket.html#socket.AF_INET" title="socket.AF_INET"><code class="xref py py-const docutils literal notranslate"><span class="pre">AF_INET</span></code></a>, | |
| <a class="reference internal" href="socket.html#socket.AF_INET6" title="socket.AF_INET6"><code class="xref py py-const docutils literal notranslate"><span class="pre">AF_INET6</span></code></a>, or <a class="reference internal" href="socket.html#socket.AF_UNIX" title="socket.AF_UNIX"><code class="xref py py-const docutils literal notranslate"><span class="pre">AF_UNIX</span></code></a>, | |
| depending on <em>host</em> (or the <em>family</em> argument, if provided).</p> | |
| <p>The socket type will be <a class="reference internal" href="socket.html#socket.SOCK_DGRAM" title="socket.SOCK_DGRAM"><code class="xref py py-const docutils literal notranslate"><span class="pre">SOCK_DGRAM</span></code></a>.</p> | |
| <p><em>protocol_factory</em> must be a callable returning a | |
| <a class="reference internal" href="asyncio-protocol.html#asyncio-protocol"><span class="std std-ref">protocol</span></a> implementation.</p> | |
| <p>A tuple of <code class="docutils literal notranslate"><span class="pre">(transport,</span> <span class="pre">protocol)</span></code> is returned on success.</p> | |
| <p>Other arguments:</p> | |
| <ul> | |
| <li><p><em>local_addr</em>, if given, is a <code class="docutils literal notranslate"><span class="pre">(local_host,</span> <span class="pre">local_port)</span></code> tuple used | |
| to bind the socket locally. The <em>local_host</em> and <em>local_port</em> | |
| are looked up using <a class="reference internal" href="#asyncio.loop.getaddrinfo" title="asyncio.loop.getaddrinfo"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getaddrinfo()</span></code></a>.</p> | |
| <div class="admonition note"> | |
| <p class="admonition-title">Note</p> | |
| <p>On Windows, when using the proactor event loop with <code class="docutils literal notranslate"><span class="pre">local_addr=None</span></code>, | |
| an <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a> with <code class="xref py py-attr docutils literal notranslate"><span class="pre">errno.WSAEINVAL</span></code> will be raised | |
| when running it.</p> | |
| </div> | |
| </li> | |
| <li><p><em>remote_addr</em>, if given, is a <code class="docutils literal notranslate"><span class="pre">(remote_host,</span> <span class="pre">remote_port)</span></code> tuple used | |
| to connect the socket to a remote address. The <em>remote_host</em> and | |
| <em>remote_port</em> are looked up using <a class="reference internal" href="#asyncio.loop.getaddrinfo" title="asyncio.loop.getaddrinfo"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getaddrinfo()</span></code></a>.</p></li> | |
| <li><p><em>family</em>, <em>proto</em>, <em>flags</em> are the optional address family, protocol | |
| and flags to be passed through to <a class="reference internal" href="#asyncio.loop.getaddrinfo" title="asyncio.loop.getaddrinfo"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getaddrinfo()</span></code></a> for <em>host</em> | |
| resolution. If given, these should all be integers from the | |
| corresponding <a class="reference internal" href="socket.html#module-socket" title="socket: Low-level networking interface."><code class="xref py py-mod docutils literal notranslate"><span class="pre">socket</span></code></a> module constants.</p></li> | |
| <li><p><em>reuse_port</em> tells the kernel to allow this endpoint to be bound to the | |
| same port as other existing endpoints are bound to, so long as they all | |
| set this flag when being created. This option is not supported on Windows | |
| and some Unixes. If the <a class="reference internal" href="socket.html#socket-unix-constants"><span class="std std-ref">socket.SO_REUSEPORT</span></a> constant is not | |
| defined then this capability is unsupported.</p></li> | |
| <li><p><em>allow_broadcast</em> tells the kernel to allow this endpoint to send | |
| messages to the broadcast address.</p></li> | |
| <li><p><em>sock</em> can optionally be specified in order to use a preexisting, | |
| already connected, <a class="reference internal" href="socket.html#socket.socket" title="socket.socket"><code class="xref py py-class docutils literal notranslate"><span class="pre">socket.socket</span></code></a> object to be used by the | |
| transport. If specified, <em>local_addr</em> and <em>remote_addr</em> should be omitted | |
| (must be <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code></a>).</p> | |
| <div class="admonition note"> | |
| <p class="admonition-title">Note</p> | |
| <p>The <em>sock</em> argument transfers ownership of the socket to the | |
| transport created. To close the socket, call the transport’s | |
| <a class="reference internal" href="asyncio-protocol.html#asyncio.BaseTransport.close" title="asyncio.BaseTransport.close"><code class="xref py py-meth docutils literal notranslate"><span class="pre">close()</span></code></a> method.</p> | |
| </div> | |
| </li> | |
| </ul> | |
| <p>See <a class="reference internal" href="asyncio-protocol.html#asyncio-udp-echo-client-protocol"><span class="std std-ref">UDP echo client protocol</span></a> and | |
| <a class="reference internal" href="asyncio-protocol.html#asyncio-udp-echo-server-protocol"><span class="std std-ref">UDP echo server protocol</span></a> examples.</p> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.4.4: </span>The <em>family</em>, <em>proto</em>, <em>flags</em>, <em>reuse_address</em>, <em>reuse_port</em>, | |
| <em>allow_broadcast</em>, and <em>sock</em> parameters were added.</p> | |
| </div> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.8: </span>Added support for Windows.</p> | |
| </div> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.8.1: </span>The <em>reuse_address</em> parameter is no longer supported, as using | |
| <a class="reference internal" href="socket.html#socket-unix-constants"><span class="std std-ref">socket.SO_REUSEADDR</span></a> | |
| poses a significant security concern for | |
| UDP. Explicitly passing <code class="docutils literal notranslate"><span class="pre">reuse_address=True</span></code> will raise an exception.</p> | |
| <p>When multiple processes with differing UIDs assign sockets to an | |
| identical UDP socket address with <code class="docutils literal notranslate"><span class="pre">SO_REUSEADDR</span></code>, incoming packets can | |
| become randomly distributed among the sockets.</p> | |
| <p>For supported platforms, <em>reuse_port</em> can be used as a replacement for | |
| similar functionality. With <em>reuse_port</em>, | |
| <a class="reference internal" href="socket.html#socket-unix-constants"><span class="std std-ref">socket.SO_REUSEPORT</span></a> | |
| is used instead, which specifically | |
| prevents processes with differing UIDs from assigning sockets to the same | |
| socket address.</p> | |
| </div> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.11: </span>The <em>reuse_address</em> parameter, disabled since Python 3.8.1, | |
| 3.7.6 and 3.6.10, has been entirely removed.</p> | |
| </div> | |
| </dd></dl> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.loop.create_unix_connection"> | |
| <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">loop.</span></span><span class="sig-name descname"><span class="pre">create_unix_connection</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">protocol_factory</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">path</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="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">ssl</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">sock</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">server_hostname</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">ssl_handshake_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">ssl_shutdown_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.loop.create_unix_connection" title="Link to this definition">¶</a></dt> | |
| <dd><p>Create a Unix connection.</p> | |
| <p>The socket family will be <a class="reference internal" href="socket.html#socket.AF_UNIX" title="socket.AF_UNIX"><code class="xref py py-const docutils literal notranslate"><span class="pre">AF_UNIX</span></code></a>; socket | |
| type will be <a class="reference internal" href="socket.html#socket.SOCK_STREAM" title="socket.SOCK_STREAM"><code class="xref py py-const docutils literal notranslate"><span class="pre">SOCK_STREAM</span></code></a>.</p> | |
| <p>A tuple of <code class="docutils literal notranslate"><span class="pre">(transport,</span> <span class="pre">protocol)</span></code> is returned on success.</p> | |
| <p><em>path</em> is the name of a Unix domain socket and is required, | |
| unless a <em>sock</em> parameter is specified. Abstract Unix sockets, | |
| <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>, <a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a>, and <a class="reference internal" href="pathlib.html#pathlib.Path" title="pathlib.Path"><code class="xref py py-class docutils literal notranslate"><span class="pre">Path</span></code></a> paths are | |
| supported.</p> | |
| <p>See the documentation of the <a class="reference internal" href="#asyncio.loop.create_connection" title="asyncio.loop.create_connection"><code class="xref py py-meth docutils literal notranslate"><span class="pre">loop.create_connection()</span></code></a> method | |
| for information about arguments to this method.</p> | |
| <div class="availability docutils container"> | |
| <p><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p> | |
| </div> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.7: </span>Added the <em>ssl_handshake_timeout</em> parameter. | |
| The <em>path</em> parameter can now be a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.</p> | |
| </div> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.11: </span>Added the <em>ssl_shutdown_timeout</em> parameter.</p> | |
| </div> | |
| </dd></dl> | |
| </section> | |
| <section id="creating-network-servers"> | |
| <h3><a class="toc-backref" href="#id6" role="doc-backlink">Creating network servers</a><a class="headerlink" href="#creating-network-servers" title="Link to this heading">¶</a></h3> | |
| <dl class="py method" id="loop-create-server"> | |
| <dt class="sig sig-object py" id="asyncio.loop.create_server"> | |
| <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">loop.</span></span><span class="sig-name descname"><span class="pre">create_server</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">protocol_factory</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">host</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">port</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="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">family</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">socket.AF_UNSPEC</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">flags</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">socket.AI_PASSIVE</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">sock</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">backlog</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">100</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">ssl</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">reuse_address</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">reuse_port</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">keep_alive</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">ssl_handshake_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">ssl_shutdown_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">start_serving</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.create_server" title="Link to this definition">¶</a></dt> | |
| <dd><p>Create a TCP server (socket type <a class="reference internal" href="socket.html#socket.SOCK_STREAM" title="socket.SOCK_STREAM"><code class="xref py py-const docutils literal notranslate"><span class="pre">SOCK_STREAM</span></code></a>) listening | |
| on <em>port</em> of the <em>host</em> address.</p> | |
| <p>Returns a <a class="reference internal" href="#asyncio.Server" title="asyncio.Server"><code class="xref py py-class docutils literal notranslate"><span class="pre">Server</span></code></a> object.</p> | |
| <p>Arguments:</p> | |
| <ul> | |
| <li><p><em>protocol_factory</em> must be a callable returning a | |
| <a class="reference internal" href="asyncio-protocol.html#asyncio-protocol"><span class="std std-ref">protocol</span></a> implementation.</p></li> | |
| <li><p>The <em>host</em> parameter can be set to several types which determine where | |
| the server would be listening:</p> | |
| <ul class="simple"> | |
| <li><p>If <em>host</em> is a string, the TCP server is bound to a single network | |
| interface specified by <em>host</em>.</p></li> | |
| <li><p>If <em>host</em> is a sequence of strings, the TCP server is bound to all | |
| network interfaces specified by the sequence.</p></li> | |
| <li><p>If <em>host</em> is an empty string or <code class="docutils literal notranslate"><span class="pre">None</span></code>, all interfaces are | |
| assumed and a list of multiple sockets will be returned (most likely | |
| one for IPv4 and another one for IPv6).</p></li> | |
| </ul> | |
| </li> | |
| <li><p>The <em>port</em> parameter can be set to specify which port the server should | |
| listen on. If <code class="docutils literal notranslate"><span class="pre">0</span></code> or <code class="docutils literal notranslate"><span class="pre">None</span></code> (the default), a random unused port will | |
| be selected (note that if <em>host</em> resolves to multiple network interfaces, | |
| a different random port will be selected for each interface).</p></li> | |
| <li><p><em>family</em> can be set to either <a class="reference internal" href="socket.html#socket.AF_INET" title="socket.AF_INET"><code class="xref py py-const docutils literal notranslate"><span class="pre">socket.AF_INET</span></code></a> or | |
| <a class="reference internal" href="socket.html#socket.AF_INET6" title="socket.AF_INET6"><code class="xref py py-const docutils literal notranslate"><span class="pre">AF_INET6</span></code></a> to force the socket to use IPv4 or IPv6. | |
| If not set, the <em>family</em> will be determined from host name | |
| (defaults to <a class="reference internal" href="socket.html#socket.AF_UNSPEC" title="socket.AF_UNSPEC"><code class="xref py py-const docutils literal notranslate"><span class="pre">AF_UNSPEC</span></code></a>).</p></li> | |
| <li><p><em>flags</em> is a bitmask for <a class="reference internal" href="#asyncio.loop.getaddrinfo" title="asyncio.loop.getaddrinfo"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getaddrinfo()</span></code></a>.</p></li> | |
| <li><p><em>sock</em> can optionally be specified in order to use a preexisting | |
| socket object. If specified, <em>host</em> and <em>port</em> must not be specified.</p> | |
| <div class="admonition note"> | |
| <p class="admonition-title">Note</p> | |
| <p>The <em>sock</em> argument transfers ownership of the socket to the | |
| server created. To close the socket, call the server’s | |
| <a class="reference internal" href="#asyncio.Server.close" title="asyncio.Server.close"><code class="xref py py-meth docutils literal notranslate"><span class="pre">close()</span></code></a> method.</p> | |
| </div> | |
| </li> | |
| <li><p><em>backlog</em> is the maximum number of queued connections passed to | |
| <a class="reference internal" href="socket.html#socket.socket.listen" title="socket.socket.listen"><code class="xref py py-meth docutils literal notranslate"><span class="pre">listen()</span></code></a> (defaults to 100).</p></li> | |
| <li><p><em>ssl</em> can be set to an <a class="reference internal" href="ssl.html#ssl.SSLContext" title="ssl.SSLContext"><code class="xref py py-class docutils literal notranslate"><span class="pre">SSLContext</span></code></a> instance to enable | |
| TLS over the accepted connections.</p></li> | |
| <li><p><em>reuse_address</em> tells the kernel to reuse a local socket in | |
| <code class="docutils literal notranslate"><span class="pre">TIME_WAIT</span></code> state, without waiting for its natural timeout to | |
| expire. If not specified will automatically be set to <code class="docutils literal notranslate"><span class="pre">True</span></code> on | |
| Unix.</p></li> | |
| <li><p><em>reuse_port</em> tells the kernel to allow this endpoint to be bound to the | |
| same port as other existing endpoints are bound to, so long as they all | |
| set this flag when being created. This option is not supported on | |
| Windows.</p></li> | |
| <li><p><em>keep_alive</em> set to <code class="docutils literal notranslate"><span class="pre">True</span></code> keeps connections active by enabling the | |
| periodic transmission of messages.</p></li> | |
| </ul> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.13: </span>Added the <em>keep_alive</em> parameter.</p> | |
| </div> | |
| <ul class="simple"> | |
| <li><p><em>ssl_handshake_timeout</em> is (for a TLS server) the time in seconds to wait | |
| for the TLS handshake to complete before aborting the connection. | |
| <code class="docutils literal notranslate"><span class="pre">60.0</span></code> seconds if <code class="docutils literal notranslate"><span class="pre">None</span></code> (default).</p></li> | |
| <li><p><em>ssl_shutdown_timeout</em> is the time in seconds to wait for the SSL shutdown | |
| to complete before aborting the connection. <code class="docutils literal notranslate"><span class="pre">30.0</span></code> seconds if <code class="docutils literal notranslate"><span class="pre">None</span></code> | |
| (default).</p></li> | |
| <li><p><em>start_serving</em> set to <code class="docutils literal notranslate"><span class="pre">True</span></code> (the default) causes the created server | |
| to start accepting connections immediately. When set to <code class="docutils literal notranslate"><span class="pre">False</span></code>, | |
| the user should await on <a class="reference internal" href="#asyncio.Server.start_serving" title="asyncio.Server.start_serving"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Server.start_serving()</span></code></a> or | |
| <a class="reference internal" href="#asyncio.Server.serve_forever" title="asyncio.Server.serve_forever"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Server.serve_forever()</span></code></a> to make the server to start accepting | |
| connections.</p></li> | |
| </ul> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.5: </span>Added support for SSL/TLS in <a class="reference internal" href="#asyncio.ProactorEventLoop" title="asyncio.ProactorEventLoop"><code class="xref py py-class docutils literal notranslate"><span class="pre">ProactorEventLoop</span></code></a>.</p> | |
| </div> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.5.1: </span>The <em>host</em> parameter can be a sequence of strings.</p> | |
| </div> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.6: </span>Added <em>ssl_handshake_timeout</em> and <em>start_serving</em> parameters. | |
| The socket option <a class="reference internal" href="socket.html#socket-unix-constants"><span class="std std-ref">socket.TCP_NODELAY</span></a> is set by default | |
| for all TCP connections.</p> | |
| </div> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.11: </span>Added the <em>ssl_shutdown_timeout</em> parameter.</p> | |
| </div> | |
| <div class="admonition seealso"> | |
| <p class="admonition-title">See also</p> | |
| <p>The <a class="reference internal" href="asyncio-stream.html#asyncio.start_server" title="asyncio.start_server"><code class="xref py py-func docutils literal notranslate"><span class="pre">start_server()</span></code></a> function is a higher-level alternative API | |
| that returns a pair of <a class="reference internal" href="asyncio-stream.html#asyncio.StreamReader" title="asyncio.StreamReader"><code class="xref py py-class docutils literal notranslate"><span class="pre">StreamReader</span></code></a> and <a class="reference internal" href="asyncio-stream.html#asyncio.StreamWriter" title="asyncio.StreamWriter"><code class="xref py py-class docutils literal notranslate"><span class="pre">StreamWriter</span></code></a> | |
| that can be used in an async/await code.</p> | |
| </div> | |
| </dd></dl> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.loop.create_unix_server"> | |
| <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">loop.</span></span><span class="sig-name descname"><span class="pre">create_unix_server</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">protocol_factory</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">path</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="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">sock</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">backlog</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">100</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">ssl</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">ssl_handshake_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">ssl_shutdown_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">start_serving</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">cleanup_socket</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.create_unix_server" title="Link to this definition">¶</a></dt> | |
| <dd><p>Similar to <a class="reference internal" href="#asyncio.loop.create_server" title="asyncio.loop.create_server"><code class="xref py py-meth docutils literal notranslate"><span class="pre">loop.create_server()</span></code></a> but works with the | |
| <a class="reference internal" href="socket.html#socket.AF_UNIX" title="socket.AF_UNIX"><code class="xref py py-const docutils literal notranslate"><span class="pre">AF_UNIX</span></code></a> socket family.</p> | |
| <p><em>path</em> is the name of a Unix domain socket, and is required, | |
| unless a <em>sock</em> argument is provided. Abstract Unix sockets, | |
| <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>, <a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a>, and <a class="reference internal" href="pathlib.html#pathlib.Path" title="pathlib.Path"><code class="xref py py-class docutils literal notranslate"><span class="pre">Path</span></code></a> paths | |
| are supported.</p> | |
| <p>If <em>cleanup_socket</em> is true then the Unix socket will automatically | |
| be removed from the filesystem when the server is closed, unless the | |
| socket has been replaced after the server has been created.</p> | |
| <p>See the documentation of the <a class="reference internal" href="#asyncio.loop.create_server" title="asyncio.loop.create_server"><code class="xref py py-meth docutils literal notranslate"><span class="pre">loop.create_server()</span></code></a> method | |
| for information about arguments to this method.</p> | |
| <div class="availability docutils container"> | |
| <p><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p> | |
| </div> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.7: </span>Added the <em>ssl_handshake_timeout</em> and <em>start_serving</em> parameters. | |
| The <em>path</em> parameter can now be a <a class="reference internal" href="pathlib.html#pathlib.Path" title="pathlib.Path"><code class="xref py py-class docutils literal notranslate"><span class="pre">Path</span></code></a> object.</p> | |
| </div> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.11: </span>Added the <em>ssl_shutdown_timeout</em> parameter.</p> | |
| </div> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.13: </span>Added the <em>cleanup_socket</em> parameter.</p> | |
| </div> | |
| </dd></dl> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.loop.connect_accepted_socket"> | |
| <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">loop.</span></span><span class="sig-name descname"><span class="pre">connect_accepted_socket</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">protocol_factory</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">sock</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">ssl</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">ssl_handshake_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">ssl_shutdown_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.loop.connect_accepted_socket" title="Link to this definition">¶</a></dt> | |
| <dd><p>Wrap an already accepted connection into a transport/protocol pair.</p> | |
| <p>This method can be used by servers that accept connections outside | |
| of asyncio but that use asyncio to handle them.</p> | |
| <p>Parameters:</p> | |
| <ul> | |
| <li><p><em>protocol_factory</em> must be a callable returning a | |
| <a class="reference internal" href="asyncio-protocol.html#asyncio-protocol"><span class="std std-ref">protocol</span></a> implementation.</p></li> | |
| <li><p><em>sock</em> is a preexisting socket object returned from | |
| <a class="reference internal" href="socket.html#socket.socket.accept" title="socket.socket.accept"><code class="xref py py-meth docutils literal notranslate"><span class="pre">socket.accept</span></code></a>.</p> | |
| <div class="admonition note"> | |
| <p class="admonition-title">Note</p> | |
| <p>The <em>sock</em> argument transfers ownership of the socket to the | |
| transport created. To close the socket, call the transport’s | |
| <a class="reference internal" href="asyncio-protocol.html#asyncio.BaseTransport.close" title="asyncio.BaseTransport.close"><code class="xref py py-meth docutils literal notranslate"><span class="pre">close()</span></code></a> method.</p> | |
| </div> | |
| </li> | |
| <li><p><em>ssl</em> can be set to an <a class="reference internal" href="ssl.html#ssl.SSLContext" title="ssl.SSLContext"><code class="xref py py-class docutils literal notranslate"><span class="pre">SSLContext</span></code></a> to enable SSL over | |
| the accepted connections.</p></li> | |
| <li><p><em>ssl_handshake_timeout</em> is (for an SSL connection) the time in seconds to | |
| wait for the SSL handshake to complete before aborting the connection. | |
| <code class="docutils literal notranslate"><span class="pre">60.0</span></code> seconds if <code class="docutils literal notranslate"><span class="pre">None</span></code> (default).</p></li> | |
| <li><p><em>ssl_shutdown_timeout</em> is the time in seconds to wait for the SSL shutdown | |
| to complete before aborting the connection. <code class="docutils literal notranslate"><span class="pre">30.0</span></code> seconds if <code class="docutils literal notranslate"><span class="pre">None</span></code> | |
| (default).</p></li> | |
| </ul> | |
| <p>Returns a <code class="docutils literal notranslate"><span class="pre">(transport,</span> <span class="pre">protocol)</span></code> pair.</p> | |
| <div class="versionadded"> | |
| <p><span class="versionmodified added">Added in version 3.5.3.</span></p> | |
| </div> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.7: </span>Added the <em>ssl_handshake_timeout</em> parameter.</p> | |
| </div> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.11: </span>Added the <em>ssl_shutdown_timeout</em> parameter.</p> | |
| </div> | |
| </dd></dl> | |
| </section> | |
| <section id="transferring-files"> | |
| <h3><a class="toc-backref" href="#id7" role="doc-backlink">Transferring files</a><a class="headerlink" href="#transferring-files" title="Link to this heading">¶</a></h3> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.loop.sendfile"> | |
| <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">loop.</span></span><span class="sig-name descname"><span class="pre">sendfile</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">transport</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">file</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">offset</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">count</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="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">fallback</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.sendfile" title="Link to this definition">¶</a></dt> | |
| <dd><p>Send a <em>file</em> over a <em>transport</em>. Return the total number of bytes | |
| sent.</p> | |
| <p>The method uses high-performance <a class="reference internal" href="os.html#os.sendfile" title="os.sendfile"><code class="xref py py-meth docutils literal notranslate"><span class="pre">os.sendfile()</span></code></a> if available.</p> | |
| <p><em>file</em> must be a regular file object opened in binary mode.</p> | |
| <p><em>offset</em> tells from where to start reading the file. If specified, | |
| <em>count</em> is the total number of bytes to transmit as opposed to | |
| sending the file until EOF is reached. File position is always updated, | |
| even when this method raises an error, and | |
| <a class="reference internal" href="io.html#io.IOBase.tell" title="io.IOBase.tell"><code class="xref py py-meth docutils literal notranslate"><span class="pre">file.tell()</span></code></a> can be used to obtain the actual | |
| number of bytes sent.</p> | |
| <p><em>fallback</em> set to <code class="docutils literal notranslate"><span class="pre">True</span></code> makes asyncio to manually read and send | |
| the file when the platform does not support the sendfile system call | |
| (e.g. Windows or SSL socket on Unix).</p> | |
| <p>Raise <a class="reference internal" href="asyncio-exceptions.html#asyncio.SendfileNotAvailableError" title="asyncio.SendfileNotAvailableError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SendfileNotAvailableError</span></code></a> if the system does not support | |
| the <em>sendfile</em> syscall and <em>fallback</em> is <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p> | |
| <div class="versionadded"> | |
| <p><span class="versionmodified added">Added in version 3.7.</span></p> | |
| </div> | |
| </dd></dl> | |
| </section> | |
| <section id="tls-upgrade"> | |
| <h3><a class="toc-backref" href="#id8" role="doc-backlink">TLS Upgrade</a><a class="headerlink" href="#tls-upgrade" title="Link to this heading">¶</a></h3> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.loop.start_tls"> | |
| <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">loop.</span></span><span class="sig-name descname"><span class="pre">start_tls</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">transport</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">protocol</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">sslcontext</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">server_side</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">server_hostname</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">ssl_handshake_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">ssl_shutdown_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.loop.start_tls" title="Link to this definition">¶</a></dt> | |
| <dd><p>Upgrade an existing transport-based connection to TLS.</p> | |
| <p>Create a TLS coder/decoder instance and insert it between the <em>transport</em> | |
| and the <em>protocol</em>. The coder/decoder implements both <em>transport</em>-facing | |
| protocol and <em>protocol</em>-facing transport.</p> | |
| <p>Return the created two-interface instance. After <em>await</em>, the <em>protocol</em> | |
| must stop using the original <em>transport</em> and communicate with the returned | |
| object only because the coder caches <em>protocol</em>-side data and sporadically | |
| exchanges extra TLS session packets with <em>transport</em>.</p> | |
| <p>In some situations (e.g. when the passed transport is already closing) this | |
| may return <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p> | |
| <p>Parameters:</p> | |
| <ul class="simple"> | |
| <li><p><em>transport</em> and <em>protocol</em> instances that methods like | |
| <a class="reference internal" href="#asyncio.loop.create_server" title="asyncio.loop.create_server"><code class="xref py py-meth docutils literal notranslate"><span class="pre">create_server()</span></code></a> and | |
| <a class="reference internal" href="#asyncio.loop.create_connection" title="asyncio.loop.create_connection"><code class="xref py py-meth docutils literal notranslate"><span class="pre">create_connection()</span></code></a> return.</p></li> | |
| <li><p><em>sslcontext</em>: a configured instance of <a class="reference internal" href="ssl.html#ssl.SSLContext" title="ssl.SSLContext"><code class="xref py py-class docutils literal notranslate"><span class="pre">SSLContext</span></code></a>.</p></li> | |
| <li><p><em>server_side</em> pass <code class="docutils literal notranslate"><span class="pre">True</span></code> when a server-side connection is being | |
| upgraded (like the one created by <a class="reference internal" href="#asyncio.loop.create_server" title="asyncio.loop.create_server"><code class="xref py py-meth docutils literal notranslate"><span class="pre">create_server()</span></code></a>).</p></li> | |
| <li><p><em>server_hostname</em>: sets or overrides the host name that the target | |
| server’s certificate will be matched against.</p></li> | |
| <li><p><em>ssl_handshake_timeout</em> is (for a TLS connection) the time in seconds to | |
| wait for the TLS handshake to complete before aborting the connection. | |
| <code class="docutils literal notranslate"><span class="pre">60.0</span></code> seconds if <code class="docutils literal notranslate"><span class="pre">None</span></code> (default).</p></li> | |
| <li><p><em>ssl_shutdown_timeout</em> is the time in seconds to wait for the SSL shutdown | |
| to complete before aborting the connection. <code class="docutils literal notranslate"><span class="pre">30.0</span></code> seconds if <code class="docutils literal notranslate"><span class="pre">None</span></code> | |
| (default).</p></li> | |
| </ul> | |
| <div class="versionadded"> | |
| <p><span class="versionmodified added">Added in version 3.7.</span></p> | |
| </div> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.11: </span>Added the <em>ssl_shutdown_timeout</em> parameter.</p> | |
| </div> | |
| </dd></dl> | |
| </section> | |
| <section id="watching-file-descriptors"> | |
| <h3><a class="toc-backref" href="#id9" role="doc-backlink">Watching file descriptors</a><a class="headerlink" href="#watching-file-descriptors" title="Link to this heading">¶</a></h3> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.loop.add_reader"> | |
| <span class="sig-prename descclassname"><span class="pre">loop.</span></span><span class="sig-name descname"><span class="pre">add_reader</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">fd</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">callback</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.add_reader" title="Link to this definition">¶</a></dt> | |
| <dd><p>Start monitoring the <em>fd</em> file descriptor for read availability and | |
| invoke <em>callback</em> with the specified arguments once <em>fd</em> is available for | |
| reading.</p> | |
| <p>Any preexisting callback registered for <em>fd</em> is cancelled and replaced by | |
| <em>callback</em>.</p> | |
| </dd></dl> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.loop.remove_reader"> | |
| <span class="sig-prename descclassname"><span class="pre">loop.</span></span><span class="sig-name descname"><span class="pre">remove_reader</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">fd</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.remove_reader" title="Link to this definition">¶</a></dt> | |
| <dd><p>Stop monitoring the <em>fd</em> file descriptor for read availability. Returns | |
| <code class="docutils literal notranslate"><span class="pre">True</span></code> if <em>fd</em> was previously being monitored for reads.</p> | |
| </dd></dl> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.loop.add_writer"> | |
| <span class="sig-prename descclassname"><span class="pre">loop.</span></span><span class="sig-name descname"><span class="pre">add_writer</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">fd</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">callback</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.add_writer" title="Link to this definition">¶</a></dt> | |
| <dd><p>Start monitoring the <em>fd</em> file descriptor for write availability and | |
| invoke <em>callback</em> with the specified arguments <em>args</em> once <em>fd</em> is | |
| available for writing.</p> | |
| <p>Any preexisting callback registered for <em>fd</em> is cancelled and replaced by | |
| <em>callback</em>.</p> | |
| <p>Use <a class="reference internal" href="functools.html#functools.partial" title="functools.partial"><code class="xref py py-func docutils literal notranslate"><span class="pre">functools.partial()</span></code></a> <a class="reference internal" href="#asyncio-pass-keywords"><span class="std std-ref">to pass keyword arguments</span></a> to <em>callback</em>.</p> | |
| </dd></dl> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.loop.remove_writer"> | |
| <span class="sig-prename descclassname"><span class="pre">loop.</span></span><span class="sig-name descname"><span class="pre">remove_writer</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">fd</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.remove_writer" title="Link to this definition">¶</a></dt> | |
| <dd><p>Stop monitoring the <em>fd</em> file descriptor for write availability. Returns | |
| <code class="docutils literal notranslate"><span class="pre">True</span></code> if <em>fd</em> was previously being monitored for writes.</p> | |
| </dd></dl> | |
| <p>See also <a class="reference internal" href="asyncio-platforms.html#asyncio-platform-support"><span class="std std-ref">Platform Support</span></a> section | |
| for some limitations of these methods.</p> | |
| </section> | |
| <section id="working-with-socket-objects-directly"> | |
| <h3><a class="toc-backref" href="#id10" role="doc-backlink">Working with socket objects directly</a><a class="headerlink" href="#working-with-socket-objects-directly" title="Link to this heading">¶</a></h3> | |
| <p>In general, protocol implementations that use transport-based APIs | |
| such as <a class="reference internal" href="#asyncio.loop.create_connection" title="asyncio.loop.create_connection"><code class="xref py py-meth docutils literal notranslate"><span class="pre">loop.create_connection()</span></code></a> and <a class="reference internal" href="#asyncio.loop.create_server" title="asyncio.loop.create_server"><code class="xref py py-meth docutils literal notranslate"><span class="pre">loop.create_server()</span></code></a> | |
| are faster than implementations that work with sockets directly. | |
| However, there are some use cases when performance is not critical, and | |
| working with <a class="reference internal" href="socket.html#socket.socket" title="socket.socket"><code class="xref py py-class docutils literal notranslate"><span class="pre">socket</span></code></a> objects directly is more | |
| convenient.</p> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.loop.sock_recv"> | |
| <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">loop.</span></span><span class="sig-name descname"><span class="pre">sock_recv</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">sock</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">nbytes</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.sock_recv" title="Link to this definition">¶</a></dt> | |
| <dd><p>Receive up to <em>nbytes</em> from <em>sock</em>. Asynchronous version of | |
| <a class="reference internal" href="socket.html#socket.socket.recv" title="socket.socket.recv"><code class="xref py py-meth docutils literal notranslate"><span class="pre">socket.recv()</span></code></a>.</p> | |
| <p>Return the received data as a bytes object.</p> | |
| <p><em>sock</em> must be a non-blocking socket.</p> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.7: </span>Even though this method was always documented as a coroutine | |
| method, releases before Python 3.7 returned 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>. | |
| Since Python 3.7 this is an <code class="docutils literal notranslate"><span class="pre">async</span> <span class="pre">def</span></code> method.</p> | |
| </div> | |
| </dd></dl> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.loop.sock_recv_into"> | |
| <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">loop.</span></span><span class="sig-name descname"><span class="pre">sock_recv_into</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">sock</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">buf</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.sock_recv_into" title="Link to this definition">¶</a></dt> | |
| <dd><p>Receive data from <em>sock</em> into the <em>buf</em> buffer. Modeled after the blocking | |
| <a class="reference internal" href="socket.html#socket.socket.recv_into" title="socket.socket.recv_into"><code class="xref py py-meth docutils literal notranslate"><span class="pre">socket.recv_into()</span></code></a> method.</p> | |
| <p>Return the number of bytes written to the buffer.</p> | |
| <p><em>sock</em> must be a non-blocking socket.</p> | |
| <div class="versionadded"> | |
| <p><span class="versionmodified added">Added in version 3.7.</span></p> | |
| </div> | |
| </dd></dl> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.loop.sock_recvfrom"> | |
| <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">loop.</span></span><span class="sig-name descname"><span class="pre">sock_recvfrom</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">sock</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">bufsize</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.sock_recvfrom" title="Link to this definition">¶</a></dt> | |
| <dd><p>Receive a datagram of up to <em>bufsize</em> from <em>sock</em>. Asynchronous version of | |
| <a class="reference internal" href="socket.html#socket.socket.recvfrom" title="socket.socket.recvfrom"><code class="xref py py-meth docutils literal notranslate"><span class="pre">socket.recvfrom()</span></code></a>.</p> | |
| <p>Return a tuple of (received data, remote address).</p> | |
| <p><em>sock</em> must be a non-blocking socket.</p> | |
| <div class="versionadded"> | |
| <p><span class="versionmodified added">Added in version 3.11.</span></p> | |
| </div> | |
| </dd></dl> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.loop.sock_recvfrom_into"> | |
| <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">loop.</span></span><span class="sig-name descname"><span class="pre">sock_recvfrom_into</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">sock</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">buf</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">nbytes</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.sock_recvfrom_into" title="Link to this definition">¶</a></dt> | |
| <dd><p>Receive a datagram of up to <em>nbytes</em> from <em>sock</em> into <em>buf</em>. | |
| Asynchronous version of | |
| <a class="reference internal" href="socket.html#socket.socket.recvfrom_into" title="socket.socket.recvfrom_into"><code class="xref py py-meth docutils literal notranslate"><span class="pre">socket.recvfrom_into()</span></code></a>.</p> | |
| <p>Return a tuple of (number of bytes received, remote address).</p> | |
| <p><em>sock</em> must be a non-blocking socket.</p> | |
| <div class="versionadded"> | |
| <p><span class="versionmodified added">Added in version 3.11.</span></p> | |
| </div> | |
| </dd></dl> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.loop.sock_sendall"> | |
| <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">loop.</span></span><span class="sig-name descname"><span class="pre">sock_sendall</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">sock</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">data</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.sock_sendall" title="Link to this definition">¶</a></dt> | |
| <dd><p>Send <em>data</em> to the <em>sock</em> socket. Asynchronous version of | |
| <a class="reference internal" href="socket.html#socket.socket.sendall" title="socket.socket.sendall"><code class="xref py py-meth docutils literal notranslate"><span class="pre">socket.sendall()</span></code></a>.</p> | |
| <p>This method continues to send to the socket until either all data | |
| in <em>data</em> has been sent or an error occurs. <code class="docutils literal notranslate"><span class="pre">None</span></code> is returned | |
| on success. On error, an exception is raised. Additionally, there is no way | |
| to determine how much data, if any, was successfully processed by the | |
| receiving end of the connection.</p> | |
| <p><em>sock</em> must be a non-blocking socket.</p> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.7: </span>Even though the method was always documented as a coroutine | |
| method, before Python 3.7 it returned 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>. | |
| Since Python 3.7, this is an <code class="docutils literal notranslate"><span class="pre">async</span> <span class="pre">def</span></code> method.</p> | |
| </div> | |
| </dd></dl> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.loop.sock_sendto"> | |
| <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">loop.</span></span><span class="sig-name descname"><span class="pre">sock_sendto</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">sock</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">data</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">address</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.sock_sendto" title="Link to this definition">¶</a></dt> | |
| <dd><p>Send a datagram from <em>sock</em> to <em>address</em>. | |
| Asynchronous version of | |
| <a class="reference internal" href="socket.html#socket.socket.sendto" title="socket.socket.sendto"><code class="xref py py-meth docutils literal notranslate"><span class="pre">socket.sendto()</span></code></a>.</p> | |
| <p>Return the number of bytes sent.</p> | |
| <p><em>sock</em> must be a non-blocking socket.</p> | |
| <div class="versionadded"> | |
| <p><span class="versionmodified added">Added in version 3.11.</span></p> | |
| </div> | |
| </dd></dl> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.loop.sock_connect"> | |
| <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">loop.</span></span><span class="sig-name descname"><span class="pre">sock_connect</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">sock</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">address</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.sock_connect" title="Link to this definition">¶</a></dt> | |
| <dd><p>Connect <em>sock</em> to a remote socket at <em>address</em>.</p> | |
| <p>Asynchronous version of <a class="reference internal" href="socket.html#socket.socket.connect" title="socket.socket.connect"><code class="xref py py-meth docutils literal notranslate"><span class="pre">socket.connect()</span></code></a>.</p> | |
| <p><em>sock</em> must be a non-blocking socket.</p> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.5.2: </span><code class="docutils literal notranslate"><span class="pre">address</span></code> no longer needs to be resolved. <code class="docutils literal notranslate"><span class="pre">sock_connect</span></code> | |
| will try to check if the <em>address</em> is already resolved by calling | |
| <a class="reference internal" href="socket.html#socket.inet_pton" title="socket.inet_pton"><code class="xref py py-func docutils literal notranslate"><span class="pre">socket.inet_pton()</span></code></a>. If not, | |
| <a class="reference internal" href="#asyncio.loop.getaddrinfo" title="asyncio.loop.getaddrinfo"><code class="xref py py-meth docutils literal notranslate"><span class="pre">loop.getaddrinfo()</span></code></a> will be used to resolve the | |
| <em>address</em>.</p> | |
| </div> | |
| <div class="admonition seealso"> | |
| <p class="admonition-title">See also</p> | |
| <p><a class="reference internal" href="#asyncio.loop.create_connection" title="asyncio.loop.create_connection"><code class="xref py py-meth docutils literal notranslate"><span class="pre">loop.create_connection()</span></code></a> | |
| and <a class="reference internal" href="asyncio-stream.html#asyncio.open_connection" title="asyncio.open_connection"><code class="xref py py-func docutils literal notranslate"><span class="pre">asyncio.open_connection()</span></code></a>.</p> | |
| </div> | |
| </dd></dl> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.loop.sock_accept"> | |
| <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">loop.</span></span><span class="sig-name descname"><span class="pre">sock_accept</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">sock</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.sock_accept" title="Link to this definition">¶</a></dt> | |
| <dd><p>Accept a connection. Modeled after the blocking | |
| <a class="reference internal" href="socket.html#socket.socket.accept" title="socket.socket.accept"><code class="xref py py-meth docutils literal notranslate"><span class="pre">socket.accept()</span></code></a> method.</p> | |
| <p>The socket must be bound to an address and listening | |
| for connections. The return value is a pair <code class="docutils literal notranslate"><span class="pre">(conn,</span> <span class="pre">address)</span></code> where <em>conn</em> | |
| is a <em>new</em> socket object usable to send and receive data on the connection, | |
| and <em>address</em> is the address bound to the socket on the other end of the | |
| connection.</p> | |
| <p><em>sock</em> must be a non-blocking socket.</p> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.7: </span>Even though the method was always documented as a coroutine | |
| method, before Python 3.7 it returned 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>. | |
| Since Python 3.7, this is an <code class="docutils literal notranslate"><span class="pre">async</span> <span class="pre">def</span></code> method.</p> | |
| </div> | |
| <div class="admonition seealso"> | |
| <p class="admonition-title">See also</p> | |
| <p><a class="reference internal" href="#asyncio.loop.create_server" title="asyncio.loop.create_server"><code class="xref py py-meth docutils literal notranslate"><span class="pre">loop.create_server()</span></code></a> and <a class="reference internal" href="asyncio-stream.html#asyncio.start_server" title="asyncio.start_server"><code class="xref py py-func docutils literal notranslate"><span class="pre">start_server()</span></code></a>.</p> | |
| </div> | |
| </dd></dl> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.loop.sock_sendfile"> | |
| <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">loop.</span></span><span class="sig-name descname"><span class="pre">sock_sendfile</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">sock</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">file</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">offset</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">count</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="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">fallback</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.sock_sendfile" title="Link to this definition">¶</a></dt> | |
| <dd><p>Send a file using high-performance <a class="reference internal" href="os.html#os.sendfile" title="os.sendfile"><code class="xref py py-mod docutils literal notranslate"><span class="pre">os.sendfile</span></code></a> if possible. | |
| Return the total number of bytes sent.</p> | |
| <p>Asynchronous version of <a class="reference internal" href="socket.html#socket.socket.sendfile" title="socket.socket.sendfile"><code class="xref py py-meth docutils literal notranslate"><span class="pre">socket.sendfile()</span></code></a>.</p> | |
| <p><em>sock</em> must be a non-blocking <a class="reference internal" href="socket.html#socket.SOCK_STREAM" title="socket.SOCK_STREAM"><code class="xref py py-const docutils literal notranslate"><span class="pre">socket.SOCK_STREAM</span></code></a> | |
| <a class="reference internal" href="socket.html#socket.socket" title="socket.socket"><code class="xref py py-class docutils literal notranslate"><span class="pre">socket</span></code></a>.</p> | |
| <p><em>file</em> must be a regular file object open in binary mode.</p> | |
| <p><em>offset</em> tells from where to start reading the file. If specified, | |
| <em>count</em> is the total number of bytes to transmit as opposed to | |
| sending the file until EOF is reached. File position is always updated, | |
| even when this method raises an error, and | |
| <a class="reference internal" href="io.html#io.IOBase.tell" title="io.IOBase.tell"><code class="xref py py-meth docutils literal notranslate"><span class="pre">file.tell()</span></code></a> can be used to obtain the actual | |
| number of bytes sent.</p> | |
| <p><em>fallback</em>, when set to <code class="docutils literal notranslate"><span class="pre">True</span></code>, makes asyncio manually read and send | |
| the file when the platform does not support the sendfile syscall | |
| (e.g. Windows or SSL socket on Unix).</p> | |
| <p>Raise <a class="reference internal" href="asyncio-exceptions.html#asyncio.SendfileNotAvailableError" title="asyncio.SendfileNotAvailableError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SendfileNotAvailableError</span></code></a> if the system does not support | |
| <em>sendfile</em> syscall and <em>fallback</em> is <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p> | |
| <p><em>sock</em> must be a non-blocking socket.</p> | |
| <div class="versionadded"> | |
| <p><span class="versionmodified added">Added in version 3.7.</span></p> | |
| </div> | |
| </dd></dl> | |
| </section> | |
| <section id="dns"> | |
| <h3><a class="toc-backref" href="#id11" role="doc-backlink">DNS</a><a class="headerlink" href="#dns" title="Link to this heading">¶</a></h3> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.loop.getaddrinfo"> | |
| <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">loop.</span></span><span class="sig-name descname"><span class="pre">getaddrinfo</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">host</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">port</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">family</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">type</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">proto</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">flags</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.getaddrinfo" title="Link to this definition">¶</a></dt> | |
| <dd><p>Asynchronous version of <a class="reference internal" href="socket.html#socket.getaddrinfo" title="socket.getaddrinfo"><code class="xref py py-meth docutils literal notranslate"><span class="pre">socket.getaddrinfo()</span></code></a>.</p> | |
| </dd></dl> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.loop.getnameinfo"> | |
| <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">loop.</span></span><span class="sig-name descname"><span class="pre">getnameinfo</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">sockaddr</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">flags</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.getnameinfo" title="Link to this definition">¶</a></dt> | |
| <dd><p>Asynchronous version of <a class="reference internal" href="socket.html#socket.getnameinfo" title="socket.getnameinfo"><code class="xref py py-meth docutils literal notranslate"><span class="pre">socket.getnameinfo()</span></code></a>.</p> | |
| </dd></dl> | |
| <div class="admonition note"> | |
| <p class="admonition-title">Note</p> | |
| <p>Both <em>getaddrinfo</em> and <em>getnameinfo</em> internally utilize their synchronous | |
| versions through the loop’s default thread pool executor. | |
| When this executor is saturated, these methods may experience delays, | |
| which higher-level networking libraries may report as increased timeouts. | |
| To mitigate this, consider using a custom executor for other user tasks, | |
| or setting a default executor with a larger number of workers.</p> | |
| </div> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.7: </span>Both <em>getaddrinfo</em> and <em>getnameinfo</em> methods were always documented | |
| to return a coroutine, but prior to Python 3.7 they were, in fact, | |
| returning <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">asyncio.Future</span></code></a> objects. Starting with Python 3.7 | |
| both methods are coroutines.</p> | |
| </div> | |
| </section> | |
| <section id="working-with-pipes"> | |
| <h3><a class="toc-backref" href="#id12" role="doc-backlink">Working with pipes</a><a class="headerlink" href="#working-with-pipes" title="Link to this heading">¶</a></h3> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.loop.connect_read_pipe"> | |
| <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">loop.</span></span><span class="sig-name descname"><span class="pre">connect_read_pipe</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">protocol_factory</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">pipe</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.connect_read_pipe" title="Link to this definition">¶</a></dt> | |
| <dd><p>Register the read end of <em>pipe</em> in the event loop.</p> | |
| <p><em>protocol_factory</em> must be a callable returning an | |
| <a class="reference internal" href="asyncio-protocol.html#asyncio-protocol"><span class="std std-ref">asyncio protocol</span></a> implementation.</p> | |
| <p><em>pipe</em> is a <a class="reference internal" href="../glossary.html#term-file-object"><span class="xref std std-term">file-like object</span></a>.</p> | |
| <p>Return pair <code class="docutils literal notranslate"><span class="pre">(transport,</span> <span class="pre">protocol)</span></code>, where <em>transport</em> supports | |
| the <a class="reference internal" href="asyncio-protocol.html#asyncio.ReadTransport" title="asyncio.ReadTransport"><code class="xref py py-class docutils literal notranslate"><span class="pre">ReadTransport</span></code></a> interface and <em>protocol</em> is an object | |
| instantiated by the <em>protocol_factory</em>.</p> | |
| <p>With <a class="reference internal" href="#asyncio.SelectorEventLoop" title="asyncio.SelectorEventLoop"><code class="xref py py-class docutils literal notranslate"><span class="pre">SelectorEventLoop</span></code></a> event loop, the <em>pipe</em> is set to | |
| non-blocking mode.</p> | |
| </dd></dl> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.loop.connect_write_pipe"> | |
| <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">loop.</span></span><span class="sig-name descname"><span class="pre">connect_write_pipe</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">protocol_factory</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">pipe</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.connect_write_pipe" title="Link to this definition">¶</a></dt> | |
| <dd><p>Register the write end of <em>pipe</em> in the event loop.</p> | |
| <p><em>protocol_factory</em> must be a callable returning an | |
| <a class="reference internal" href="asyncio-protocol.html#asyncio-protocol"><span class="std std-ref">asyncio protocol</span></a> implementation.</p> | |
| <p><em>pipe</em> is <a class="reference internal" href="../glossary.html#term-file-object"><span class="xref std std-term">file-like object</span></a>.</p> | |
| <p>Return pair <code class="docutils literal notranslate"><span class="pre">(transport,</span> <span class="pre">protocol)</span></code>, where <em>transport</em> supports | |
| <a class="reference internal" href="asyncio-protocol.html#asyncio.WriteTransport" title="asyncio.WriteTransport"><code class="xref py py-class docutils literal notranslate"><span class="pre">WriteTransport</span></code></a> interface and <em>protocol</em> is an object | |
| instantiated by the <em>protocol_factory</em>.</p> | |
| <p>With <a class="reference internal" href="#asyncio.SelectorEventLoop" title="asyncio.SelectorEventLoop"><code class="xref py py-class docutils literal notranslate"><span class="pre">SelectorEventLoop</span></code></a> event loop, the <em>pipe</em> is set to | |
| non-blocking mode.</p> | |
| </dd></dl> | |
| <div class="admonition note"> | |
| <p class="admonition-title">Note</p> | |
| <p><a class="reference internal" href="#asyncio.SelectorEventLoop" title="asyncio.SelectorEventLoop"><code class="xref py py-class docutils literal notranslate"><span class="pre">SelectorEventLoop</span></code></a> does not support the above methods on | |
| Windows. Use <a class="reference internal" href="#asyncio.ProactorEventLoop" title="asyncio.ProactorEventLoop"><code class="xref py py-class docutils literal notranslate"><span class="pre">ProactorEventLoop</span></code></a> instead for Windows.</p> | |
| </div> | |
| <div class="admonition seealso"> | |
| <p class="admonition-title">See also</p> | |
| <p>The <a class="reference internal" href="#asyncio.loop.subprocess_exec" title="asyncio.loop.subprocess_exec"><code class="xref py py-meth docutils literal notranslate"><span class="pre">loop.subprocess_exec()</span></code></a> and | |
| <a class="reference internal" href="#asyncio.loop.subprocess_shell" title="asyncio.loop.subprocess_shell"><code class="xref py py-meth docutils literal notranslate"><span class="pre">loop.subprocess_shell()</span></code></a> methods.</p> | |
| </div> | |
| </section> | |
| <section id="unix-signals"> | |
| <h3><a class="toc-backref" href="#id13" role="doc-backlink">Unix signals</a><a class="headerlink" href="#unix-signals" title="Link to this heading">¶</a></h3> | |
| <dl class="py method" id="loop-add-signal-handler"> | |
| <dt class="sig sig-object py" id="asyncio.loop.add_signal_handler"> | |
| <span class="sig-prename descclassname"><span class="pre">loop.</span></span><span class="sig-name descname"><span class="pre">add_signal_handler</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">signum</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">callback</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.add_signal_handler" title="Link to this definition">¶</a></dt> | |
| <dd><p>Set <em>callback</em> as the handler for the <em>signum</em> signal, | |
| passing <em>args</em> as positional arguments.</p> | |
| <p>The callback will be invoked by <em>loop</em>, along with other queued callbacks | |
| and runnable coroutines of that event loop. Unlike signal handlers | |
| registered using <a class="reference internal" href="signal.html#signal.signal" title="signal.signal"><code class="xref py py-func docutils literal notranslate"><span class="pre">signal.signal()</span></code></a>, a callback registered with this | |
| function is allowed to interact with the event loop.</p> | |
| <p>Raise <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 the signal number is invalid or uncatchable. | |
| Raise <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> if there is a problem setting up the handler.</p> | |
| <p>Use <a class="reference internal" href="functools.html#functools.partial" title="functools.partial"><code class="xref py py-func docutils literal notranslate"><span class="pre">functools.partial()</span></code></a> <a class="reference internal" href="#asyncio-pass-keywords"><span class="std std-ref">to pass keyword arguments</span></a> to <em>callback</em>.</p> | |
| <p>Like <a class="reference internal" href="signal.html#signal.signal" title="signal.signal"><code class="xref py py-func docutils literal notranslate"><span class="pre">signal.signal()</span></code></a>, this function must be invoked in the main | |
| thread.</p> | |
| </dd></dl> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.loop.remove_signal_handler"> | |
| <span class="sig-prename descclassname"><span class="pre">loop.</span></span><span class="sig-name descname"><span class="pre">remove_signal_handler</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">sig</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.remove_signal_handler" title="Link to this definition">¶</a></dt> | |
| <dd><p>Remove the handler for the <em>sig</em> signal.</p> | |
| <p>Return <code class="docutils literal notranslate"><span class="pre">True</span></code> if the signal handler was removed, or <code class="docutils literal notranslate"><span class="pre">False</span></code> if | |
| no handler was set for the given signal.</p> | |
| <div class="availability docutils container"> | |
| <p><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p> | |
| </div> | |
| </dd></dl> | |
| <div class="admonition seealso"> | |
| <p class="admonition-title">See also</p> | |
| <p>The <a class="reference internal" href="signal.html#module-signal" title="signal: Set handlers for asynchronous events."><code class="xref py py-mod docutils literal notranslate"><span class="pre">signal</span></code></a> module.</p> | |
| </div> | |
| </section> | |
| <section id="executing-code-in-thread-or-process-pools"> | |
| <h3><a class="toc-backref" href="#id14" role="doc-backlink">Executing code in thread or process pools</a><a class="headerlink" href="#executing-code-in-thread-or-process-pools" title="Link to this heading">¶</a></h3> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.loop.run_in_executor"> | |
| <em class="property"><span class="pre">awaitable</span> </em><span class="sig-prename descclassname"><span class="pre">loop.</span></span><span class="sig-name descname"><span class="pre">run_in_executor</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">executor</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">func</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.run_in_executor" title="Link to this definition">¶</a></dt> | |
| <dd><p>Arrange for <em>func</em> to be called in the specified executor | |
| passing <em>args</em> as positional arguments.</p> | |
| <p>The <em>executor</em> argument should be an <a class="reference internal" href="concurrent.futures.html#concurrent.futures.Executor" title="concurrent.futures.Executor"><code class="xref py py-class docutils literal notranslate"><span class="pre">concurrent.futures.Executor</span></code></a> | |
| instance. The default executor is used if <em>executor</em> is <code class="docutils literal notranslate"><span class="pre">None</span></code>. | |
| The default executor can be set by <a class="reference internal" href="#asyncio.loop.set_default_executor" title="asyncio.loop.set_default_executor"><code class="xref py py-meth docutils literal notranslate"><span class="pre">loop.set_default_executor()</span></code></a>, | |
| otherwise, a <a class="reference internal" href="concurrent.futures.html#concurrent.futures.ThreadPoolExecutor" title="concurrent.futures.ThreadPoolExecutor"><code class="xref py py-class docutils literal notranslate"><span class="pre">concurrent.futures.ThreadPoolExecutor</span></code></a> will be | |
| lazy-initialized and used by <a class="reference internal" href="#asyncio.loop.run_in_executor" title="asyncio.loop.run_in_executor"><code class="xref py py-func docutils literal notranslate"><span class="pre">run_in_executor()</span></code></a> if needed.</p> | |
| <p>Example:</p> | |
| <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> | |
| <span class="kn">import</span><span class="w"> </span><span class="nn">concurrent.futures</span> | |
| <span class="k">def</span><span class="w"> </span><span class="nf">blocking_io</span><span class="p">():</span> | |
| <span class="c1"># File operations (such as logging) can block the</span> | |
| <span class="c1"># event loop: run them in a thread pool.</span> | |
| <span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s1">'/dev/urandom'</span><span class="p">,</span> <span class="s1">'rb'</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span> | |
| <span class="k">return</span> <span class="n">f</span><span class="o">.</span><span class="n">read</span><span class="p">(</span><span class="mi">100</span><span class="p">)</span> | |
| <span class="k">def</span><span class="w"> </span><span class="nf">cpu_bound</span><span class="p">():</span> | |
| <span class="c1"># CPU-bound operations will block the event loop:</span> | |
| <span class="c1"># in general it is preferable to run them in a</span> | |
| <span class="c1"># process pool.</span> | |
| <span class="k">return</span> <span class="nb">sum</span><span class="p">(</span><span class="n">i</span> <span class="o">*</span> <span class="n">i</span> <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">10</span> <span class="o">**</span> <span class="mi">7</span><span class="p">))</span> | |
| <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">main</span><span class="p">():</span> | |
| <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> | |
| <span class="c1">## Options:</span> | |
| <span class="c1"># 1. Run in the default loop's executor:</span> | |
| <span class="n">result</span> <span class="o">=</span> <span class="k">await</span> <span class="n">loop</span><span class="o">.</span><span class="n">run_in_executor</span><span class="p">(</span> | |
| <span class="kc">None</span><span class="p">,</span> <span class="n">blocking_io</span><span class="p">)</span> | |
| <span class="nb">print</span><span class="p">(</span><span class="s1">'default thread pool'</span><span class="p">,</span> <span class="n">result</span><span class="p">)</span> | |
| <span class="c1"># 2. Run in a custom thread pool:</span> | |
| <span class="k">with</span> <span class="n">concurrent</span><span class="o">.</span><span class="n">futures</span><span class="o">.</span><span class="n">ThreadPoolExecutor</span><span class="p">()</span> <span class="k">as</span> <span class="n">pool</span><span class="p">:</span> | |
| <span class="n">result</span> <span class="o">=</span> <span class="k">await</span> <span class="n">loop</span><span class="o">.</span><span class="n">run_in_executor</span><span class="p">(</span> | |
| <span class="n">pool</span><span class="p">,</span> <span class="n">blocking_io</span><span class="p">)</span> | |
| <span class="nb">print</span><span class="p">(</span><span class="s1">'custom thread pool'</span><span class="p">,</span> <span class="n">result</span><span class="p">)</span> | |
| <span class="c1"># 3. Run in a custom process pool:</span> | |
| <span class="k">with</span> <span class="n">concurrent</span><span class="o">.</span><span class="n">futures</span><span class="o">.</span><span class="n">ProcessPoolExecutor</span><span class="p">()</span> <span class="k">as</span> <span class="n">pool</span><span class="p">:</span> | |
| <span class="n">result</span> <span class="o">=</span> <span class="k">await</span> <span class="n">loop</span><span class="o">.</span><span class="n">run_in_executor</span><span class="p">(</span> | |
| <span class="n">pool</span><span class="p">,</span> <span class="n">cpu_bound</span><span class="p">)</span> | |
| <span class="nb">print</span><span class="p">(</span><span class="s1">'custom process pool'</span><span class="p">,</span> <span class="n">result</span><span class="p">)</span> | |
| <span class="c1"># 4. Run in a custom interpreter pool:</span> | |
| <span class="k">with</span> <span class="n">concurrent</span><span class="o">.</span><span class="n">futures</span><span class="o">.</span><span class="n">InterpreterPoolExecutor</span><span class="p">()</span> <span class="k">as</span> <span class="n">pool</span><span class="p">:</span> | |
| <span class="n">result</span> <span class="o">=</span> <span class="k">await</span> <span class="n">loop</span><span class="o">.</span><span class="n">run_in_executor</span><span class="p">(</span> | |
| <span class="n">pool</span><span class="p">,</span> <span class="n">cpu_bound</span><span class="p">)</span> | |
| <span class="nb">print</span><span class="p">(</span><span class="s1">'custom interpreter pool'</span><span class="p">,</span> <span class="n">result</span><span class="p">)</span> | |
| <span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s1">'__main__'</span><span class="p">:</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> | |
| </pre></div> | |
| </div> | |
| <p>Note that the entry point guard (<code class="docutils literal notranslate"><span class="pre">if</span> <span class="pre">__name__</span> <span class="pre">==</span> <span class="pre">'__main__'</span></code>) | |
| is required for option 3 due to the peculiarities of <a class="reference internal" href="multiprocessing.html#module-multiprocessing" title="multiprocessing: Process-based parallelism."><code class="xref py py-mod docutils literal notranslate"><span class="pre">multiprocessing</span></code></a>, | |
| which is used by <a class="reference internal" href="concurrent.futures.html#concurrent.futures.ProcessPoolExecutor" title="concurrent.futures.ProcessPoolExecutor"><code class="xref py py-class docutils literal notranslate"><span class="pre">ProcessPoolExecutor</span></code></a>. | |
| See <a class="reference internal" href="multiprocessing.html#multiprocessing-safe-main-import"><span class="std std-ref">Safe importing of main module</span></a>.</p> | |
| <p>This method returns 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">asyncio.Future</span></code></a> object.</p> | |
| <p>Use <a class="reference internal" href="functools.html#functools.partial" title="functools.partial"><code class="xref py py-func docutils literal notranslate"><span class="pre">functools.partial()</span></code></a> <a class="reference internal" href="#asyncio-pass-keywords"><span class="std std-ref">to pass keyword arguments</span></a> to <em>func</em>.</p> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.5.3: </span><code class="xref py py-meth docutils literal notranslate"><span class="pre">loop.run_in_executor()</span></code> no longer configures the | |
| <code class="docutils literal notranslate"><span class="pre">max_workers</span></code> of the thread pool executor it creates, instead | |
| leaving it up to the thread pool executor | |
| (<a class="reference internal" href="concurrent.futures.html#concurrent.futures.ThreadPoolExecutor" title="concurrent.futures.ThreadPoolExecutor"><code class="xref py py-class docutils literal notranslate"><span class="pre">ThreadPoolExecutor</span></code></a>) to set the | |
| default.</p> | |
| </div> | |
| </dd></dl> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.loop.set_default_executor"> | |
| <span class="sig-prename descclassname"><span class="pre">loop.</span></span><span class="sig-name descname"><span class="pre">set_default_executor</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">executor</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.set_default_executor" title="Link to this definition">¶</a></dt> | |
| <dd><p>Set <em>executor</em> as the default executor used by <a class="reference internal" href="#asyncio.loop.run_in_executor" title="asyncio.loop.run_in_executor"><code class="xref py py-meth docutils literal notranslate"><span class="pre">run_in_executor()</span></code></a>. | |
| <em>executor</em> must be an instance of | |
| <a class="reference internal" href="concurrent.futures.html#concurrent.futures.ThreadPoolExecutor" title="concurrent.futures.ThreadPoolExecutor"><code class="xref py py-class docutils literal notranslate"><span class="pre">ThreadPoolExecutor</span></code></a>, which includes | |
| <a class="reference internal" href="concurrent.futures.html#concurrent.futures.InterpreterPoolExecutor" title="concurrent.futures.InterpreterPoolExecutor"><code class="xref py py-class docutils literal notranslate"><span class="pre">InterpreterPoolExecutor</span></code></a>.</p> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.11: </span><em>executor</em> must be an instance of | |
| <a class="reference internal" href="concurrent.futures.html#concurrent.futures.ThreadPoolExecutor" title="concurrent.futures.ThreadPoolExecutor"><code class="xref py py-class docutils literal notranslate"><span class="pre">ThreadPoolExecutor</span></code></a>.</p> | |
| </div> | |
| </dd></dl> | |
| </section> | |
| <section id="error-handling-api"> | |
| <h3><a class="toc-backref" href="#id15" role="doc-backlink">Error Handling API</a><a class="headerlink" href="#error-handling-api" title="Link to this heading">¶</a></h3> | |
| <p>Allows customizing how exceptions are handled in the event loop.</p> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.loop.set_exception_handler"> | |
| <span class="sig-prename descclassname"><span class="pre">loop.</span></span><span class="sig-name descname"><span class="pre">set_exception_handler</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">handler</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.set_exception_handler" title="Link to this definition">¶</a></dt> | |
| <dd><p>Set <em>handler</em> as the new event loop exception handler.</p> | |
| <p>If <em>handler</em> is <code class="docutils literal notranslate"><span class="pre">None</span></code>, the default exception handler will | |
| be set. Otherwise, <em>handler</em> must be a callable with the signature | |
| matching <code class="docutils literal notranslate"><span class="pre">(loop,</span> <span class="pre">context)</span></code>, where <code class="docutils literal notranslate"><span class="pre">loop</span></code> | |
| is a reference to the active event loop, and <code class="docutils literal notranslate"><span class="pre">context</span></code> | |
| is a <code class="docutils literal notranslate"><span class="pre">dict</span></code> object containing the details of the exception | |
| (see <a class="reference internal" href="#asyncio.loop.call_exception_handler" title="asyncio.loop.call_exception_handler"><code class="xref py py-meth docutils literal notranslate"><span class="pre">call_exception_handler()</span></code></a> documentation for details | |
| about context).</p> | |
| <p>If the handler is called on behalf of a <a class="reference internal" href="asyncio-task.html#asyncio.Task" title="asyncio.Task"><code class="xref py py-class docutils literal notranslate"><span class="pre">Task</span></code></a> or | |
| <a class="reference internal" href="#asyncio.Handle" title="asyncio.Handle"><code class="xref py py-class docutils literal notranslate"><span class="pre">Handle</span></code></a>, it is run in the | |
| <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> of that task or callback handle.</p> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.12: </span>The handler may be called in the <a class="reference internal" href="contextvars.html#contextvars.Context" title="contextvars.Context"><code class="xref py py-class docutils literal notranslate"><span class="pre">Context</span></code></a> | |
| of the task or handle where the exception originated.</p> | |
| </div> | |
| </dd></dl> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.loop.get_exception_handler"> | |
| <span class="sig-prename descclassname"><span class="pre">loop.</span></span><span class="sig-name descname"><span class="pre">get_exception_handler</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.get_exception_handler" title="Link to this definition">¶</a></dt> | |
| <dd><p>Return the current exception handler, or <code class="docutils literal notranslate"><span class="pre">None</span></code> if no custom | |
| exception handler was set.</p> | |
| <div class="versionadded"> | |
| <p><span class="versionmodified added">Added in version 3.5.2.</span></p> | |
| </div> | |
| </dd></dl> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.loop.default_exception_handler"> | |
| <span class="sig-prename descclassname"><span class="pre">loop.</span></span><span class="sig-name descname"><span class="pre">default_exception_handler</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">context</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.default_exception_handler" title="Link to this definition">¶</a></dt> | |
| <dd><p>Default exception handler.</p> | |
| <p>This is called when an exception occurs and no exception | |
| handler is set. This can be called by a custom exception | |
| handler that wants to defer to the default handler behavior.</p> | |
| <p><em>context</em> parameter has the same meaning as in | |
| <a class="reference internal" href="#asyncio.loop.call_exception_handler" title="asyncio.loop.call_exception_handler"><code class="xref py py-meth docutils literal notranslate"><span class="pre">call_exception_handler()</span></code></a>.</p> | |
| </dd></dl> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.loop.call_exception_handler"> | |
| <span class="sig-prename descclassname"><span class="pre">loop.</span></span><span class="sig-name descname"><span class="pre">call_exception_handler</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">context</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.call_exception_handler" title="Link to this definition">¶</a></dt> | |
| <dd><p>Call the current event loop exception handler.</p> | |
| <p><em>context</em> is a <code class="docutils literal notranslate"><span class="pre">dict</span></code> object containing the following keys | |
| (new keys may be introduced in future Python versions):</p> | |
| <ul class="simple"> | |
| <li><p>‘message’: Error message;</p></li> | |
| <li><p>‘exception’ (optional): Exception object;</p></li> | |
| <li><p>‘future’ (optional): <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">asyncio.Future</span></code></a> instance;</p></li> | |
| <li><p>‘task’ (optional): <a class="reference internal" href="asyncio-task.html#asyncio.Task" title="asyncio.Task"><code class="xref py py-class docutils literal notranslate"><span class="pre">asyncio.Task</span></code></a> instance;</p></li> | |
| <li><p>‘handle’ (optional): <a class="reference internal" href="#asyncio.Handle" title="asyncio.Handle"><code class="xref py py-class docutils literal notranslate"><span class="pre">asyncio.Handle</span></code></a> instance;</p></li> | |
| <li><p>‘protocol’ (optional): <a class="reference internal" href="asyncio-protocol.html#asyncio-protocol"><span class="std std-ref">Protocol</span></a> instance;</p></li> | |
| <li><p>‘transport’ (optional): <a class="reference internal" href="asyncio-protocol.html#asyncio-transport"><span class="std std-ref">Transport</span></a> instance;</p></li> | |
| <li><p>‘socket’ (optional): <a class="reference internal" href="socket.html#socket.socket" title="socket.socket"><code class="xref py py-class docutils literal notranslate"><span class="pre">socket.socket</span></code></a> instance;</p></li> | |
| <li><p>‘source_traceback’ (optional): Traceback of the source;</p></li> | |
| <li><p>‘handle_traceback’ (optional): Traceback of the handle;</p></li> | |
| <li><dl class="simple"> | |
| <dt>‘asyncgen’ (optional): Asynchronous generator that caused</dt><dd><p>the exception.</p> | |
| </dd> | |
| </dl> | |
| </li> | |
| </ul> | |
| <div class="admonition note"> | |
| <p class="admonition-title">Note</p> | |
| <p>This method should not be overloaded in subclassed | |
| event loops. For custom exception handling, use | |
| the <a class="reference internal" href="#asyncio.loop.set_exception_handler" title="asyncio.loop.set_exception_handler"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set_exception_handler()</span></code></a> method.</p> | |
| </div> | |
| </dd></dl> | |
| </section> | |
| <section id="enabling-debug-mode"> | |
| <h3><a class="toc-backref" href="#id16" role="doc-backlink">Enabling debug mode</a><a class="headerlink" href="#enabling-debug-mode" title="Link to this heading">¶</a></h3> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.loop.get_debug"> | |
| <span class="sig-prename descclassname"><span class="pre">loop.</span></span><span class="sig-name descname"><span class="pre">get_debug</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.get_debug" title="Link to this definition">¶</a></dt> | |
| <dd><p>Get the debug mode (<a class="reference internal" href="functions.html#bool" title="bool"><code class="xref py py-class docutils literal notranslate"><span class="pre">bool</span></code></a>) of the event loop.</p> | |
| <p>The default value is <code class="docutils literal notranslate"><span class="pre">True</span></code> if the environment variable | |
| <span class="target" id="index-5"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONASYNCIODEBUG"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONASYNCIODEBUG</span></code></a> is set to a non-empty string, <code class="docutils literal notranslate"><span class="pre">False</span></code> | |
| otherwise.</p> | |
| </dd></dl> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.loop.set_debug"> | |
| <span class="sig-prename descclassname"><span class="pre">loop.</span></span><span class="sig-name descname"><span class="pre">set_debug</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">enabled</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="functions.html#bool" title="bool"><span class="pre">bool</span></a></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.set_debug" title="Link to this definition">¶</a></dt> | |
| <dd><p>Set the debug mode of the event loop.</p> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.7: </span>The new <a class="reference internal" href="devmode.html#devmode"><span class="std std-ref">Python Development Mode</span></a> can now also be used | |
| to enable the debug mode.</p> | |
| </div> | |
| </dd></dl> | |
| <dl class="py attribute"> | |
| <dt class="sig sig-object py" id="asyncio.loop.slow_callback_duration"> | |
| <span class="sig-prename descclassname"><span class="pre">loop.</span></span><span class="sig-name descname"><span class="pre">slow_callback_duration</span></span><a class="headerlink" href="#asyncio.loop.slow_callback_duration" title="Link to this definition">¶</a></dt> | |
| <dd><p>This attribute can be used to set the | |
| minimum execution duration in seconds that is considered “slow”. | |
| When debug mode is enabled, “slow” callbacks are logged.</p> | |
| <p>Default value is 100 milliseconds.</p> | |
| </dd></dl> | |
| <div class="admonition seealso"> | |
| <p class="admonition-title">See also</p> | |
| <p>The <a class="reference internal" href="asyncio-dev.html#asyncio-debug-mode"><span class="std std-ref">debug mode of asyncio</span></a>.</p> | |
| </div> | |
| </section> | |
| <section id="running-subprocesses"> | |
| <h3><a class="toc-backref" href="#id17" role="doc-backlink">Running Subprocesses</a><a class="headerlink" href="#running-subprocesses" title="Link to this heading">¶</a></h3> | |
| <p>Methods described in this subsections are low-level. In regular | |
| async/await code consider using the high-level | |
| <a class="reference internal" href="asyncio-subprocess.html#asyncio.create_subprocess_shell" title="asyncio.create_subprocess_shell"><code class="xref py py-func docutils literal notranslate"><span class="pre">asyncio.create_subprocess_shell()</span></code></a> and | |
| <a class="reference internal" href="asyncio-subprocess.html#asyncio.create_subprocess_exec" title="asyncio.create_subprocess_exec"><code class="xref py py-func docutils literal notranslate"><span class="pre">asyncio.create_subprocess_exec()</span></code></a> convenience functions instead.</p> | |
| <div class="admonition note"> | |
| <p class="admonition-title">Note</p> | |
| <p>On Windows, the default event loop <a class="reference internal" href="#asyncio.ProactorEventLoop" title="asyncio.ProactorEventLoop"><code class="xref py py-class docutils literal notranslate"><span class="pre">ProactorEventLoop</span></code></a> supports | |
| subprocesses, whereas <a class="reference internal" href="#asyncio.SelectorEventLoop" title="asyncio.SelectorEventLoop"><code class="xref py py-class docutils literal notranslate"><span class="pre">SelectorEventLoop</span></code></a> does not. See | |
| <a class="reference internal" href="asyncio-platforms.html#asyncio-windows-subprocess"><span class="std std-ref">Subprocess Support on Windows</span></a> for | |
| details.</p> | |
| </div> | |
| <dl class="py method" id="loop-subprocess-exec"> | |
| <dt class="sig sig-object py" id="asyncio.loop.subprocess_exec"> | |
| <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">loop.</span></span><span class="sig-name descname"><span class="pre">subprocess_exec</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">protocol_factory</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">stdin</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">subprocess.PIPE</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">stdout</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">subprocess.PIPE</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">stderr</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">subprocess.PIPE</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.loop.subprocess_exec" title="Link to this definition">¶</a></dt> | |
| <dd><p>Create a subprocess from one or more string arguments specified by | |
| <em>args</em>.</p> | |
| <p><em>args</em> must be a list of strings represented by:</p> | |
| <ul class="simple"> | |
| <li><p><a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>;</p></li> | |
| <li><p>or <a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a>, encoded to the | |
| <a class="reference internal" href="os.html#filesystem-encoding"><span class="std std-ref">filesystem encoding</span></a>.</p></li> | |
| </ul> | |
| <p>The first string specifies the program executable, | |
| and the remaining strings specify the arguments. Together, string | |
| arguments form the <code class="docutils literal notranslate"><span class="pre">argv</span></code> of the program.</p> | |
| <p>This is similar to the standard library <a class="reference internal" href="subprocess.html#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">subprocess.Popen</span></code></a> | |
| class called with <code class="docutils literal notranslate"><span class="pre">shell=False</span></code> and the list of strings passed as | |
| the first argument; however, where <code class="xref py py-class docutils literal notranslate"><span class="pre">Popen</span></code> takes | |
| a single argument which is list of strings, <em>subprocess_exec</em> | |
| takes multiple string arguments.</p> | |
| <p>The <em>protocol_factory</em> must be a callable returning a subclass of the | |
| <a class="reference internal" href="asyncio-protocol.html#asyncio.SubprocessProtocol" title="asyncio.SubprocessProtocol"><code class="xref py py-class docutils literal notranslate"><span class="pre">asyncio.SubprocessProtocol</span></code></a> class.</p> | |
| <p>Other parameters:</p> | |
| <ul> | |
| <li><p><em>stdin</em> can be any of these:</p> | |
| <ul class="simple"> | |
| <li><p>a file-like object</p></li> | |
| <li><p>an existing file descriptor (a positive integer), for example those created with <a class="reference internal" href="os.html#os.pipe" title="os.pipe"><code class="xref py py-meth docutils literal notranslate"><span class="pre">os.pipe()</span></code></a></p></li> | |
| <li><p>the <a class="reference internal" href="subprocess.html#subprocess.PIPE" title="subprocess.PIPE"><code class="xref py py-const docutils literal notranslate"><span class="pre">subprocess.PIPE</span></code></a> constant (default) which will create a new | |
| pipe and connect it,</p></li> | |
| <li><p>the value <code class="docutils literal notranslate"><span class="pre">None</span></code> which will make the subprocess inherit the file | |
| descriptor from this process</p></li> | |
| <li><p>the <a class="reference internal" href="subprocess.html#subprocess.DEVNULL" title="subprocess.DEVNULL"><code class="xref py py-const docutils literal notranslate"><span class="pre">subprocess.DEVNULL</span></code></a> constant which indicates that the | |
| special <a class="reference internal" href="os.html#os.devnull" title="os.devnull"><code class="xref py py-data docutils literal notranslate"><span class="pre">os.devnull</span></code></a> file will be used</p></li> | |
| </ul> | |
| </li> | |
| <li><p><em>stdout</em> can be any of these:</p> | |
| <ul class="simple"> | |
| <li><p>a file-like object</p></li> | |
| <li><p>the <a class="reference internal" href="subprocess.html#subprocess.PIPE" title="subprocess.PIPE"><code class="xref py py-const docutils literal notranslate"><span class="pre">subprocess.PIPE</span></code></a> constant (default) which will create a new | |
| pipe and connect it,</p></li> | |
| <li><p>the value <code class="docutils literal notranslate"><span class="pre">None</span></code> which will make the subprocess inherit the file | |
| descriptor from this process</p></li> | |
| <li><p>the <a class="reference internal" href="subprocess.html#subprocess.DEVNULL" title="subprocess.DEVNULL"><code class="xref py py-const docutils literal notranslate"><span class="pre">subprocess.DEVNULL</span></code></a> constant which indicates that the | |
| special <a class="reference internal" href="os.html#os.devnull" title="os.devnull"><code class="xref py py-data docutils literal notranslate"><span class="pre">os.devnull</span></code></a> file will be used</p></li> | |
| </ul> | |
| </li> | |
| <li><p><em>stderr</em> can be any of these:</p> | |
| <ul class="simple"> | |
| <li><p>a file-like object</p></li> | |
| <li><p>the <a class="reference internal" href="subprocess.html#subprocess.PIPE" title="subprocess.PIPE"><code class="xref py py-const docutils literal notranslate"><span class="pre">subprocess.PIPE</span></code></a> constant (default) which will create a new | |
| pipe and connect it,</p></li> | |
| <li><p>the value <code class="docutils literal notranslate"><span class="pre">None</span></code> which will make the subprocess inherit the file | |
| descriptor from this process</p></li> | |
| <li><p>the <a class="reference internal" href="subprocess.html#subprocess.DEVNULL" title="subprocess.DEVNULL"><code class="xref py py-const docutils literal notranslate"><span class="pre">subprocess.DEVNULL</span></code></a> constant which indicates that the | |
| special <a class="reference internal" href="os.html#os.devnull" title="os.devnull"><code class="xref py py-data docutils literal notranslate"><span class="pre">os.devnull</span></code></a> file will be used</p></li> | |
| <li><p>the <a class="reference internal" href="subprocess.html#subprocess.STDOUT" title="subprocess.STDOUT"><code class="xref py py-const docutils literal notranslate"><span class="pre">subprocess.STDOUT</span></code></a> constant which will connect the standard | |
| error stream to the process’ standard output stream</p></li> | |
| </ul> | |
| </li> | |
| <li><p>All other keyword arguments are passed to <a class="reference internal" href="subprocess.html#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">subprocess.Popen</span></code></a> | |
| without interpretation, except for <em>bufsize</em>, <em>universal_newlines</em>, | |
| <em>shell</em>, <em>text</em>, <em>encoding</em> and <em>errors</em>, which should not be specified | |
| at all.</p> | |
| <p>The <code class="docutils literal notranslate"><span class="pre">asyncio</span></code> subprocess API does not support decoding the streams | |
| as text. <a class="reference internal" href="stdtypes.html#bytes.decode" title="bytes.decode"><code class="xref py py-func docutils literal notranslate"><span class="pre">bytes.decode()</span></code></a> can be used to convert the bytes returned | |
| from the stream to text.</p> | |
| </li> | |
| </ul> | |
| <p>If a file-like object passed as <em>stdin</em>, <em>stdout</em> or <em>stderr</em> represents a | |
| pipe, then the other side of this pipe should be registered with | |
| <a class="reference internal" href="#asyncio.loop.connect_write_pipe" title="asyncio.loop.connect_write_pipe"><code class="xref py py-meth docutils literal notranslate"><span class="pre">connect_write_pipe()</span></code></a> or <a class="reference internal" href="#asyncio.loop.connect_read_pipe" title="asyncio.loop.connect_read_pipe"><code class="xref py py-meth docutils literal notranslate"><span class="pre">connect_read_pipe()</span></code></a> for use | |
| with the event loop.</p> | |
| <p>See the constructor of the <a class="reference internal" href="subprocess.html#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">subprocess.Popen</span></code></a> class | |
| for documentation on other arguments.</p> | |
| <p>Returns a pair of <code class="docutils literal notranslate"><span class="pre">(transport,</span> <span class="pre">protocol)</span></code>, where <em>transport</em> | |
| conforms to the <a class="reference internal" href="asyncio-protocol.html#asyncio.SubprocessTransport" title="asyncio.SubprocessTransport"><code class="xref py py-class docutils literal notranslate"><span class="pre">asyncio.SubprocessTransport</span></code></a> base class and | |
| <em>protocol</em> is an object instantiated by the <em>protocol_factory</em>.</p> | |
| <p>If the transport is closed or is garbage collected, the child process | |
| is killed if it is still running.</p> | |
| </dd></dl> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.loop.subprocess_shell"> | |
| <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">loop.</span></span><span class="sig-name descname"><span class="pre">subprocess_shell</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">protocol_factory</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">cmd</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">stdin</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">subprocess.PIPE</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">stdout</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">subprocess.PIPE</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">stderr</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">subprocess.PIPE</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.loop.subprocess_shell" title="Link to this definition">¶</a></dt> | |
| <dd><p>Create a subprocess from <em>cmd</em>, which can be a <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> or a | |
| <a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> string encoded to the | |
| <a class="reference internal" href="os.html#filesystem-encoding"><span class="std std-ref">filesystem encoding</span></a>, | |
| using the platform’s “shell” syntax.</p> | |
| <p>This is similar to the standard library <a class="reference internal" href="subprocess.html#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">subprocess.Popen</span></code></a> | |
| class called with <code class="docutils literal notranslate"><span class="pre">shell=True</span></code>.</p> | |
| <p>The <em>protocol_factory</em> must be a callable returning a subclass of the | |
| <a class="reference internal" href="asyncio-protocol.html#asyncio.SubprocessProtocol" title="asyncio.SubprocessProtocol"><code class="xref py py-class docutils literal notranslate"><span class="pre">SubprocessProtocol</span></code></a> class.</p> | |
| <p>See <a class="reference internal" href="#asyncio.loop.subprocess_exec" title="asyncio.loop.subprocess_exec"><code class="xref py py-meth docutils literal notranslate"><span class="pre">subprocess_exec()</span></code></a> for more details about | |
| the remaining arguments.</p> | |
| <p>Returns a pair of <code class="docutils literal notranslate"><span class="pre">(transport,</span> <span class="pre">protocol)</span></code>, where <em>transport</em> | |
| conforms to the <a class="reference internal" href="asyncio-protocol.html#asyncio.SubprocessTransport" title="asyncio.SubprocessTransport"><code class="xref py py-class docutils literal notranslate"><span class="pre">SubprocessTransport</span></code></a> base class and | |
| <em>protocol</em> is an object instantiated by the <em>protocol_factory</em>.</p> | |
| <p>If the transport is closed or is garbage collected, the child process | |
| is killed if it is still running.</p> | |
| </dd></dl> | |
| <div class="admonition note"> | |
| <p class="admonition-title">Note</p> | |
| <p>It is the application’s responsibility to ensure that all whitespace | |
| and special characters are quoted appropriately to avoid <a class="reference external" href="https://en.wikipedia.org/wiki/Shell_injection#Shell_injection">shell injection</a> | |
| vulnerabilities. The <a class="reference internal" href="shlex.html#shlex.quote" title="shlex.quote"><code class="xref py py-func docutils literal notranslate"><span class="pre">shlex.quote()</span></code></a> function can be used to | |
| properly escape whitespace and special characters in strings that | |
| are going to be used to construct shell commands.</p> | |
| </div> | |
| </section> | |
| </section> | |
| <section id="callback-handles"> | |
| <h2>Callback Handles<a class="headerlink" href="#callback-handles" title="Link to this heading">¶</a></h2> | |
| <dl class="py class"> | |
| <dt class="sig sig-object py" id="asyncio.Handle"> | |
| <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">Handle</span></span><a class="headerlink" href="#asyncio.Handle" title="Link to this definition">¶</a></dt> | |
| <dd><p>A callback wrapper object returned by <a class="reference internal" href="#asyncio.loop.call_soon" title="asyncio.loop.call_soon"><code class="xref py py-meth docutils literal notranslate"><span class="pre">loop.call_soon()</span></code></a>, | |
| <a class="reference internal" href="#asyncio.loop.call_soon_threadsafe" title="asyncio.loop.call_soon_threadsafe"><code class="xref py py-meth docutils literal notranslate"><span class="pre">loop.call_soon_threadsafe()</span></code></a>.</p> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.Handle.get_context"> | |
| <span class="sig-name descname"><span class="pre">get_context</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Handle.get_context" title="Link to this definition">¶</a></dt> | |
| <dd><p>Return the <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> object | |
| associated with the handle.</p> | |
| <div class="versionadded"> | |
| <p><span class="versionmodified added">Added in version 3.12.</span></p> | |
| </div> | |
| </dd></dl> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.Handle.cancel"> | |
| <span class="sig-name descname"><span class="pre">cancel</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Handle.cancel" title="Link to this definition">¶</a></dt> | |
| <dd><p>Cancel the callback. If the callback has already been canceled | |
| or executed, this method has no effect.</p> | |
| </dd></dl> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.Handle.cancelled"> | |
| <span class="sig-name descname"><span class="pre">cancelled</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Handle.cancelled" title="Link to this definition">¶</a></dt> | |
| <dd><p>Return <code class="docutils literal notranslate"><span class="pre">True</span></code> if the callback was cancelled.</p> | |
| <div class="versionadded"> | |
| <p><span class="versionmodified added">Added in version 3.7.</span></p> | |
| </div> | |
| </dd></dl> | |
| </dd></dl> | |
| <dl class="py class"> | |
| <dt class="sig sig-object py" id="asyncio.TimerHandle"> | |
| <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">TimerHandle</span></span><a class="headerlink" href="#asyncio.TimerHandle" title="Link to this definition">¶</a></dt> | |
| <dd><p>A callback wrapper object returned by <a class="reference internal" href="#asyncio.loop.call_later" title="asyncio.loop.call_later"><code class="xref py py-meth docutils literal notranslate"><span class="pre">loop.call_later()</span></code></a>, | |
| and <a class="reference internal" href="#asyncio.loop.call_at" title="asyncio.loop.call_at"><code class="xref py py-meth docutils literal notranslate"><span class="pre">loop.call_at()</span></code></a>.</p> | |
| <p>This class is a subclass of <a class="reference internal" href="#asyncio.Handle" title="asyncio.Handle"><code class="xref py py-class docutils literal notranslate"><span class="pre">Handle</span></code></a>.</p> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.TimerHandle.when"> | |
| <span class="sig-name descname"><span class="pre">when</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.TimerHandle.when" title="Link to this definition">¶</a></dt> | |
| <dd><p>Return a scheduled callback time as <a class="reference internal" href="functions.html#float" title="float"><code class="xref py py-class docutils literal notranslate"><span class="pre">float</span></code></a> seconds.</p> | |
| <p>The time is an absolute timestamp, using the same time | |
| reference as <a class="reference internal" href="#asyncio.loop.time" title="asyncio.loop.time"><code class="xref py py-meth docutils literal notranslate"><span class="pre">loop.time()</span></code></a>.</p> | |
| <div class="versionadded"> | |
| <p><span class="versionmodified added">Added in version 3.7.</span></p> | |
| </div> | |
| </dd></dl> | |
| </dd></dl> | |
| </section> | |
| <section id="server-objects"> | |
| <h2>Server Objects<a class="headerlink" href="#server-objects" title="Link to this heading">¶</a></h2> | |
| <p>Server objects are created by <a class="reference internal" href="#asyncio.loop.create_server" title="asyncio.loop.create_server"><code class="xref py py-meth docutils literal notranslate"><span class="pre">loop.create_server()</span></code></a>, | |
| <a class="reference internal" href="#asyncio.loop.create_unix_server" title="asyncio.loop.create_unix_server"><code class="xref py py-meth docutils literal notranslate"><span class="pre">loop.create_unix_server()</span></code></a>, <a class="reference internal" href="asyncio-stream.html#asyncio.start_server" title="asyncio.start_server"><code class="xref py py-func docutils literal notranslate"><span class="pre">start_server()</span></code></a>, | |
| and <a class="reference internal" href="asyncio-stream.html#asyncio.start_unix_server" title="asyncio.start_unix_server"><code class="xref py py-func docutils literal notranslate"><span class="pre">start_unix_server()</span></code></a> functions.</p> | |
| <p>Do not instantiate the <a class="reference internal" href="#asyncio.Server" title="asyncio.Server"><code class="xref py py-class docutils literal notranslate"><span class="pre">Server</span></code></a> class directly.</p> | |
| <dl class="py class"> | |
| <dt class="sig sig-object py" id="asyncio.Server"> | |
| <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">Server</span></span><a class="headerlink" href="#asyncio.Server" title="Link to this definition">¶</a></dt> | |
| <dd><p><em>Server</em> objects are asynchronous context managers. When used in an | |
| <code class="docutils literal notranslate"><span class="pre">async</span> <span class="pre">with</span></code> statement, it’s guaranteed that the Server object is | |
| closed and not accepting new connections when the <code class="docutils literal notranslate"><span class="pre">async</span> <span class="pre">with</span></code> | |
| statement is completed:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">srv</span> <span class="o">=</span> <span class="k">await</span> <span class="n">loop</span><span class="o">.</span><span class="n">create_server</span><span class="p">(</span><span class="o">...</span><span class="p">)</span> | |
| <span class="k">async</span> <span class="k">with</span> <span class="n">srv</span><span class="p">:</span> | |
| <span class="c1"># some code</span> | |
| <span class="c1"># At this point, srv is closed and no longer accepts new connections.</span> | |
| </pre></div> | |
| </div> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.7: </span>Server object is an asynchronous context manager since Python 3.7.</p> | |
| </div> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.11: </span>This class was exposed publicly as <code class="docutils literal notranslate"><span class="pre">asyncio.Server</span></code> in Python 3.9.11, 3.10.3 and 3.11.</p> | |
| </div> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.Server.close"> | |
| <span class="sig-name descname"><span class="pre">close</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Server.close" title="Link to this definition">¶</a></dt> | |
| <dd><p>Stop serving: close listening sockets and set the <a class="reference internal" href="#asyncio.Server.sockets" title="asyncio.Server.sockets"><code class="xref py py-attr docutils literal notranslate"><span class="pre">sockets</span></code></a> | |
| attribute to <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p> | |
| <p>The sockets that represent existing incoming client connections | |
| are left open.</p> | |
| <p>The server is closed asynchronously; use the <a class="reference internal" href="#asyncio.Server.wait_closed" title="asyncio.Server.wait_closed"><code class="xref py py-meth docutils literal notranslate"><span class="pre">wait_closed()</span></code></a> | |
| coroutine to wait until the server is closed (and no more | |
| connections are active).</p> | |
| </dd></dl> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.Server.close_clients"> | |
| <span class="sig-name descname"><span class="pre">close_clients</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Server.close_clients" title="Link to this definition">¶</a></dt> | |
| <dd><p>Close all existing incoming client connections.</p> | |
| <p>Calls <a class="reference internal" href="asyncio-protocol.html#asyncio.BaseTransport.close" title="asyncio.BaseTransport.close"><code class="xref py py-meth docutils literal notranslate"><span class="pre">close()</span></code></a> on all associated | |
| transports.</p> | |
| <p><a class="reference internal" href="#asyncio.Server.close" title="asyncio.Server.close"><code class="xref py py-meth docutils literal notranslate"><span class="pre">close()</span></code></a> should be called before <code class="xref py py-meth docutils literal notranslate"><span class="pre">close_clients()</span></code> when | |
| closing the server to avoid races with new clients connecting.</p> | |
| <div class="versionadded"> | |
| <p><span class="versionmodified added">Added in version 3.13.</span></p> | |
| </div> | |
| </dd></dl> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.Server.abort_clients"> | |
| <span class="sig-name descname"><span class="pre">abort_clients</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Server.abort_clients" title="Link to this definition">¶</a></dt> | |
| <dd><p>Close all existing incoming client connections immediately, | |
| without waiting for pending operations to complete.</p> | |
| <p>Calls <a class="reference internal" href="asyncio-protocol.html#asyncio.WriteTransport.abort" title="asyncio.WriteTransport.abort"><code class="xref py py-meth docutils literal notranslate"><span class="pre">abort()</span></code></a> on all associated | |
| transports.</p> | |
| <p><a class="reference internal" href="#asyncio.Server.close" title="asyncio.Server.close"><code class="xref py py-meth docutils literal notranslate"><span class="pre">close()</span></code></a> should be called before <code class="xref py py-meth docutils literal notranslate"><span class="pre">abort_clients()</span></code> when | |
| closing the server to avoid races with new clients connecting.</p> | |
| <div class="versionadded"> | |
| <p><span class="versionmodified added">Added in version 3.13.</span></p> | |
| </div> | |
| </dd></dl> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.Server.get_loop"> | |
| <span class="sig-name descname"><span class="pre">get_loop</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Server.get_loop" title="Link to this definition">¶</a></dt> | |
| <dd><p>Return the event loop associated with the server object.</p> | |
| <div class="versionadded"> | |
| <p><span class="versionmodified added">Added in version 3.7.</span></p> | |
| </div> | |
| </dd></dl> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.Server.start_serving"> | |
| <em class="property"><span class="k"><span class="pre">async</span></span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">start_serving</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Server.start_serving" title="Link to this definition">¶</a></dt> | |
| <dd><p>Start accepting connections.</p> | |
| <p>This method is idempotent, so it can be called when | |
| the server is already serving.</p> | |
| <p>The <em>start_serving</em> keyword-only parameter to | |
| <a class="reference internal" href="#asyncio.loop.create_server" title="asyncio.loop.create_server"><code class="xref py py-meth docutils literal notranslate"><span class="pre">loop.create_server()</span></code></a> and | |
| <a class="reference internal" href="asyncio-stream.html#asyncio.start_server" title="asyncio.start_server"><code class="xref py py-meth docutils literal notranslate"><span class="pre">asyncio.start_server()</span></code></a> allows creating a Server object | |
| that is not accepting connections initially. In this case | |
| <code class="docutils literal notranslate"><span class="pre">Server.start_serving()</span></code>, or <a class="reference internal" href="#asyncio.Server.serve_forever" title="asyncio.Server.serve_forever"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Server.serve_forever()</span></code></a> can be used | |
| to make the Server start accepting connections.</p> | |
| <div class="versionadded"> | |
| <p><span class="versionmodified added">Added in version 3.7.</span></p> | |
| </div> | |
| </dd></dl> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.Server.serve_forever"> | |
| <em class="property"><span class="k"><span class="pre">async</span></span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">serve_forever</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Server.serve_forever" title="Link to this definition">¶</a></dt> | |
| <dd><p>Start accepting connections until the coroutine is cancelled. | |
| Cancellation of <code class="docutils literal notranslate"><span class="pre">serve_forever</span></code> task causes the server | |
| to be closed.</p> | |
| <p>This method can be called if the server is already accepting | |
| connections. Only one <code class="docutils literal notranslate"><span class="pre">serve_forever</span></code> task can exist per | |
| one <em>Server</em> object.</p> | |
| <p>Example:</p> | |
| <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">client_connected</span><span class="p">(</span><span class="n">reader</span><span class="p">,</span> <span class="n">writer</span><span class="p">):</span> | |
| <span class="c1"># Communicate with the client with</span> | |
| <span class="c1"># reader/writer streams. For example:</span> | |
| <span class="k">await</span> <span class="n">reader</span><span class="o">.</span><span class="n">readline</span><span class="p">()</span> | |
| <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">main</span><span class="p">(</span><span class="n">host</span><span class="p">,</span> <span class="n">port</span><span class="p">):</span> | |
| <span class="n">srv</span> <span class="o">=</span> <span class="k">await</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">start_server</span><span class="p">(</span> | |
| <span class="n">client_connected</span><span class="p">,</span> <span class="n">host</span><span class="p">,</span> <span class="n">port</span><span class="p">)</span> | |
| <span class="k">await</span> <span class="n">srv</span><span class="o">.</span><span class="n">serve_forever</span><span class="p">()</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><span class="s1">'127.0.0.1'</span><span class="p">,</span> <span class="mi">0</span><span class="p">))</span> | |
| </pre></div> | |
| </div> | |
| <div class="versionadded"> | |
| <p><span class="versionmodified added">Added in version 3.7.</span></p> | |
| </div> | |
| </dd></dl> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.Server.is_serving"> | |
| <span class="sig-name descname"><span class="pre">is_serving</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Server.is_serving" title="Link to this definition">¶</a></dt> | |
| <dd><p>Return <code class="docutils literal notranslate"><span class="pre">True</span></code> if the server is accepting new connections.</p> | |
| <div class="versionadded"> | |
| <p><span class="versionmodified added">Added in version 3.7.</span></p> | |
| </div> | |
| </dd></dl> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="asyncio.Server.wait_closed"> | |
| <em class="property"><span class="k"><span class="pre">async</span></span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">wait_closed</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Server.wait_closed" title="Link to this definition">¶</a></dt> | |
| <dd><p>Wait until the <a class="reference internal" href="#asyncio.Server.close" title="asyncio.Server.close"><code class="xref py py-meth docutils literal notranslate"><span class="pre">close()</span></code></a> method completes and all active | |
| connections have finished.</p> | |
| </dd></dl> | |
| <dl class="py attribute"> | |
| <dt class="sig sig-object py" id="asyncio.Server.sockets"> | |
| <span class="sig-name descname"><span class="pre">sockets</span></span><a class="headerlink" href="#asyncio.Server.sockets" title="Link to this definition">¶</a></dt> | |
| <dd><p>List of socket-like objects, <code class="docutils literal notranslate"><span class="pre">asyncio.trsock.TransportSocket</span></code>, which | |
| the server is listening on.</p> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.7: </span>Prior to Python 3.7 <code class="docutils literal notranslate"><span class="pre">Server.sockets</span></code> used to return an | |
| internal list of server sockets directly. In 3.7 a copy | |
| of that list is returned.</p> | |
| </div> | |
| </dd></dl> | |
| </dd></dl> | |
| </section> | |
| <section id="event-loop-implementations"> | |
| <span id="asyncio-event-loop-implementations"></span><span id="asyncio-event-loops"></span><h2>Event Loop Implementations<a class="headerlink" href="#event-loop-implementations" title="Link to this heading">¶</a></h2> | |
| <p>asyncio ships with two different event loop implementations: | |
| <a class="reference internal" href="#asyncio.SelectorEventLoop" title="asyncio.SelectorEventLoop"><code class="xref py py-class docutils literal notranslate"><span class="pre">SelectorEventLoop</span></code></a> and <a class="reference internal" href="#asyncio.ProactorEventLoop" title="asyncio.ProactorEventLoop"><code class="xref py py-class docutils literal notranslate"><span class="pre">ProactorEventLoop</span></code></a>.</p> | |
| <p>By default asyncio is configured to use <a class="reference internal" href="#asyncio.EventLoop" title="asyncio.EventLoop"><code class="xref py py-class docutils literal notranslate"><span class="pre">EventLoop</span></code></a>.</p> | |
| <dl class="py class"> | |
| <dt class="sig sig-object py" id="asyncio.SelectorEventLoop"> | |
| <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">SelectorEventLoop</span></span><a class="headerlink" href="#asyncio.SelectorEventLoop" title="Link to this definition">¶</a></dt> | |
| <dd><p>A subclass of <a class="reference internal" href="#asyncio.AbstractEventLoop" title="asyncio.AbstractEventLoop"><code class="xref py py-class docutils literal notranslate"><span class="pre">AbstractEventLoop</span></code></a> based on the | |
| <a class="reference internal" href="selectors.html#module-selectors" title="selectors: High-level I/O multiplexing."><code class="xref py py-mod docutils literal notranslate"><span class="pre">selectors</span></code></a> module.</p> | |
| <p>Uses the most efficient <em>selector</em> available for the given | |
| platform. It is also possible to manually configure the | |
| exact selector implementation to be used:</p> | |
| <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> | |
| <span class="kn">import</span><span class="w"> </span><span class="nn">selectors</span> | |
| <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">main</span><span class="p">():</span> | |
| <span class="o">...</span> | |
| <span class="n">loop_factory</span> <span class="o">=</span> <span class="k">lambda</span><span class="p">:</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">SelectorEventLoop</span><span class="p">(</span><span class="n">selectors</span><span class="o">.</span><span class="n">SelectSelector</span><span class="p">())</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> <span class="n">loop_factory</span><span class="o">=</span><span class="n">loop_factory</span><span class="p">)</span> | |
| </pre></div> | |
| </div> | |
| <div class="availability docutils container"> | |
| <p><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix, Windows.</p> | |
| </div> | |
| </dd></dl> | |
| <dl class="py class"> | |
| <dt class="sig sig-object py" id="asyncio.ProactorEventLoop"> | |
| <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">ProactorEventLoop</span></span><a class="headerlink" href="#asyncio.ProactorEventLoop" title="Link to this definition">¶</a></dt> | |
| <dd><p>A subclass of <a class="reference internal" href="#asyncio.AbstractEventLoop" title="asyncio.AbstractEventLoop"><code class="xref py py-class docutils literal notranslate"><span class="pre">AbstractEventLoop</span></code></a> for Windows that uses “I/O Completion Ports” (IOCP).</p> | |
| <div class="availability docutils container"> | |
| <p><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Windows.</p> | |
| </div> | |
| <div class="admonition seealso"> | |
| <p class="admonition-title">See also</p> | |
| <p><a class="reference external" href="https://learn.microsoft.com/windows/win32/fileio/i-o-completion-ports">MSDN documentation on I/O Completion Ports</a>.</p> | |
| </div> | |
| </dd></dl> | |
| <dl class="py class"> | |
| <dt class="sig sig-object py" id="asyncio.EventLoop"> | |
| <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">EventLoop</span></span><a class="headerlink" href="#asyncio.EventLoop" title="Link to this definition">¶</a></dt> | |
| <dd><blockquote> | |
| <div><p>An alias to the most efficient available subclass of <a class="reference internal" href="#asyncio.AbstractEventLoop" title="asyncio.AbstractEventLoop"><code class="xref py py-class docutils literal notranslate"><span class="pre">AbstractEventLoop</span></code></a> for the given | |
| platform.</p> | |
| <p>It is an alias to <a class="reference internal" href="#asyncio.SelectorEventLoop" title="asyncio.SelectorEventLoop"><code class="xref py py-class docutils literal notranslate"><span class="pre">SelectorEventLoop</span></code></a> on Unix and <a class="reference internal" href="#asyncio.ProactorEventLoop" title="asyncio.ProactorEventLoop"><code class="xref py py-class docutils literal notranslate"><span class="pre">ProactorEventLoop</span></code></a> on Windows.</p> | |
| </div></blockquote> | |
| <div class="versionadded"> | |
| <p><span class="versionmodified added">Added in version 3.13.</span></p> | |
| </div> | |
| </dd></dl> | |
| <dl class="py class"> | |
| <dt class="sig sig-object py" id="asyncio.AbstractEventLoop"> | |
| <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">AbstractEventLoop</span></span><a class="headerlink" href="#asyncio.AbstractEventLoop" title="Link to this definition">¶</a></dt> | |
| <dd><p>Abstract base class for asyncio-compliant event loops.</p> | |
| <p>The <a class="reference internal" href="#asyncio-event-loop-methods"><span class="std std-ref">Event Loop Methods</span></a> section lists all | |
| methods that an alternative implementation of <code class="docutils literal notranslate"><span class="pre">AbstractEventLoop</span></code> | |
| should have defined.</p> | |
| </dd></dl> | |
| </section> | |
| <section id="examples"> | |
| <h2>Examples<a class="headerlink" href="#examples" title="Link to this heading">¶</a></h2> | |
| <p>Note that all examples in this section <strong>purposefully</strong> show how | |
| to use the low-level event loop APIs, such as <a class="reference internal" href="#asyncio.loop.run_forever" title="asyncio.loop.run_forever"><code class="xref py py-meth docutils literal notranslate"><span class="pre">loop.run_forever()</span></code></a> | |
| and <a class="reference internal" href="#asyncio.loop.call_soon" title="asyncio.loop.call_soon"><code class="xref py py-meth docutils literal notranslate"><span class="pre">loop.call_soon()</span></code></a>. Modern asyncio applications rarely | |
| need to be written this way; consider using the high-level functions | |
| like <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>.</p> | |
| <section id="hello-world-with-call-soon"> | |
| <span id="asyncio-example-lowlevel-helloworld"></span><h3>Hello World with call_soon()<a class="headerlink" href="#hello-world-with-call-soon" title="Link to this heading">¶</a></h3> | |
| <p>An example using the <a class="reference internal" href="#asyncio.loop.call_soon" title="asyncio.loop.call_soon"><code class="xref py py-meth docutils literal notranslate"><span class="pre">loop.call_soon()</span></code></a> method to schedule a | |
| callback. The callback displays <code class="docutils literal notranslate"><span class="pre">"Hello</span> <span class="pre">World"</span></code> and then stops the | |
| event loop:</p> | |
| <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> | |
| <span class="k">def</span><span class="w"> </span><span class="nf">hello_world</span><span class="p">(</span><span class="n">loop</span><span class="p">):</span> | |
| <span class="w"> </span><span class="sd">"""A callback to print 'Hello World' and stop the event loop"""</span> | |
| <span class="nb">print</span><span class="p">(</span><span class="s1">'Hello World'</span><span class="p">)</span> | |
| <span class="n">loop</span><span class="o">.</span><span class="n">stop</span><span class="p">()</span> | |
| <span class="n">loop</span> <span class="o">=</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">new_event_loop</span><span class="p">()</span> | |
| <span class="c1"># Schedule a call to hello_world()</span> | |
| <span class="n">loop</span><span class="o">.</span><span class="n">call_soon</span><span class="p">(</span><span class="n">hello_world</span><span class="p">,</span> <span class="n">loop</span><span class="p">)</span> | |
| <span class="c1"># Blocking call interrupted by loop.stop()</span> | |
| <span class="k">try</span><span class="p">:</span> | |
| <span class="n">loop</span><span class="o">.</span><span class="n">run_forever</span><span class="p">()</span> | |
| <span class="k">finally</span><span class="p">:</span> | |
| <span class="n">loop</span><span class="o">.</span><span class="n">close</span><span class="p">()</span> | |
| </pre></div> | |
| </div> | |
| <div class="admonition seealso"> | |
| <p class="admonition-title">See also</p> | |
| <p>A similar <a class="reference internal" href="asyncio-task.html#coroutine"><span class="std std-ref">Hello World</span></a> | |
| example created with a coroutine and 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">run()</span></code></a> function.</p> | |
| </div> | |
| </section> | |
| <section id="display-the-current-date-with-call-later"> | |
| <span id="asyncio-example-call-later"></span><h3>Display the current date with call_later()<a class="headerlink" href="#display-the-current-date-with-call-later" title="Link to this heading">¶</a></h3> | |
| <p>An example of a callback displaying the current date every second. The | |
| callback uses the <a class="reference internal" href="#asyncio.loop.call_later" title="asyncio.loop.call_later"><code class="xref py py-meth docutils literal notranslate"><span class="pre">loop.call_later()</span></code></a> method to reschedule itself | |
| after 5 seconds, and then stops the event loop:</p> | |
| <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> | |
| <span class="kn">import</span><span class="w"> </span><span class="nn">datetime</span> | |
| <span class="k">def</span><span class="w"> </span><span class="nf">display_date</span><span class="p">(</span><span class="n">end_time</span><span class="p">,</span> <span class="n">loop</span><span class="p">):</span> | |
| <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> | |
| <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"><</span> <span class="n">end_time</span><span class="p">:</span> | |
| <span class="n">loop</span><span class="o">.</span><span class="n">call_later</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="n">display_date</span><span class="p">,</span> <span class="n">end_time</span><span class="p">,</span> <span class="n">loop</span><span class="p">)</span> | |
| <span class="k">else</span><span class="p">:</span> | |
| <span class="n">loop</span><span class="o">.</span><span class="n">stop</span><span class="p">()</span> | |
| <span class="n">loop</span> <span class="o">=</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">new_event_loop</span><span class="p">()</span> | |
| <span class="c1"># Schedule the first call to display_date()</span> | |
| <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> | |
| <span class="n">loop</span><span class="o">.</span><span class="n">call_soon</span><span class="p">(</span><span class="n">display_date</span><span class="p">,</span> <span class="n">end_time</span><span class="p">,</span> <span class="n">loop</span><span class="p">)</span> | |
| <span class="c1"># Blocking call interrupted by loop.stop()</span> | |
| <span class="k">try</span><span class="p">:</span> | |
| <span class="n">loop</span><span class="o">.</span><span class="n">run_forever</span><span class="p">()</span> | |
| <span class="k">finally</span><span class="p">:</span> | |
| <span class="n">loop</span><span class="o">.</span><span class="n">close</span><span class="p">()</span> | |
| </pre></div> | |
| </div> | |
| <div class="admonition seealso"> | |
| <p class="admonition-title">See also</p> | |
| <p>A similar <a class="reference internal" href="asyncio-task.html#asyncio-example-sleep"><span class="std std-ref">current date</span></a> example | |
| created with a coroutine and 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">run()</span></code></a> function.</p> | |
| </div> | |
| </section> | |
| <section id="watch-a-file-descriptor-for-read-events"> | |
| <span id="asyncio-example-watch-fd"></span><h3>Watch a file descriptor for read events<a class="headerlink" href="#watch-a-file-descriptor-for-read-events" title="Link to this heading">¶</a></h3> | |
| <p>Wait until a file descriptor received some data using the | |
| <a class="reference internal" href="#asyncio.loop.add_reader" title="asyncio.loop.add_reader"><code class="xref py py-meth docutils literal notranslate"><span class="pre">loop.add_reader()</span></code></a> method and then close the event loop:</p> | |
| <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> | |
| <span class="kn">from</span><span class="w"> </span><span class="nn">socket</span><span class="w"> </span><span class="kn">import</span> <span class="n">socketpair</span> | |
| <span class="c1"># Create a pair of connected file descriptors</span> | |
| <span class="n">rsock</span><span class="p">,</span> <span class="n">wsock</span> <span class="o">=</span> <span class="n">socketpair</span><span class="p">()</span> | |
| <span class="n">loop</span> <span class="o">=</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">new_event_loop</span><span class="p">()</span> | |
| <span class="k">def</span><span class="w"> </span><span class="nf">reader</span><span class="p">():</span> | |
| <span class="n">data</span> <span class="o">=</span> <span class="n">rsock</span><span class="o">.</span><span class="n">recv</span><span class="p">(</span><span class="mi">100</span><span class="p">)</span> | |
| <span class="nb">print</span><span class="p">(</span><span class="s2">"Received:"</span><span class="p">,</span> <span class="n">data</span><span class="o">.</span><span class="n">decode</span><span class="p">())</span> | |
| <span class="c1"># We are done: unregister the file descriptor</span> | |
| <span class="n">loop</span><span class="o">.</span><span class="n">remove_reader</span><span class="p">(</span><span class="n">rsock</span><span class="p">)</span> | |
| <span class="c1"># Stop the event loop</span> | |
| <span class="n">loop</span><span class="o">.</span><span class="n">stop</span><span class="p">()</span> | |
| <span class="c1"># Register the file descriptor for read event</span> | |
| <span class="n">loop</span><span class="o">.</span><span class="n">add_reader</span><span class="p">(</span><span class="n">rsock</span><span class="p">,</span> <span class="n">reader</span><span class="p">)</span> | |
| <span class="c1"># Simulate the reception of data from the network</span> | |
| <span class="n">loop</span><span class="o">.</span><span class="n">call_soon</span><span class="p">(</span><span class="n">wsock</span><span class="o">.</span><span class="n">send</span><span class="p">,</span> <span class="s1">'abc'</span><span class="o">.</span><span class="n">encode</span><span class="p">())</span> | |
| <span class="k">try</span><span class="p">:</span> | |
| <span class="c1"># Run the event loop</span> | |
| <span class="n">loop</span><span class="o">.</span><span class="n">run_forever</span><span class="p">()</span> | |
| <span class="k">finally</span><span class="p">:</span> | |
| <span class="c1"># We are done. Close sockets and the event loop.</span> | |
| <span class="n">rsock</span><span class="o">.</span><span class="n">close</span><span class="p">()</span> | |
| <span class="n">wsock</span><span class="o">.</span><span class="n">close</span><span class="p">()</span> | |
| <span class="n">loop</span><span class="o">.</span><span class="n">close</span><span class="p">()</span> | |
| </pre></div> | |
| </div> | |
| <div class="admonition seealso"> | |
| <p class="admonition-title">See also</p> | |
| <ul class="simple"> | |
| <li><p>A similar <a class="reference internal" href="asyncio-protocol.html#asyncio-example-create-connection"><span class="std std-ref">example</span></a> | |
| using transports, protocols, and the | |
| <a class="reference internal" href="#asyncio.loop.create_connection" title="asyncio.loop.create_connection"><code class="xref py py-meth docutils literal notranslate"><span class="pre">loop.create_connection()</span></code></a> method.</p></li> | |
| <li><p>Another similar <a class="reference internal" href="asyncio-stream.html#asyncio-example-create-connection-streams"><span class="std std-ref">example</span></a> | |
| using the high-level <a class="reference internal" href="asyncio-stream.html#asyncio.open_connection" title="asyncio.open_connection"><code class="xref py py-func docutils literal notranslate"><span class="pre">asyncio.open_connection()</span></code></a> function | |
| and streams.</p></li> | |
| </ul> | |
| </div> | |
| </section> | |
| <section id="set-signal-handlers-for-sigint-and-sigterm"> | |
| <span id="asyncio-example-unix-signals"></span><h3>Set signal handlers for SIGINT and SIGTERM<a class="headerlink" href="#set-signal-handlers-for-sigint-and-sigterm" title="Link to this heading">¶</a></h3> | |
| <p>(This <code class="docutils literal notranslate"><span class="pre">signals</span></code> example only works on Unix.)</p> | |
| <p>Register handlers for signals <a class="reference internal" href="signal.html#signal.SIGINT" title="signal.SIGINT"><code class="xref py py-const docutils literal notranslate"><span class="pre">SIGINT</span></code></a> and <a class="reference internal" href="signal.html#signal.SIGTERM" title="signal.SIGTERM"><code class="xref py py-const docutils literal notranslate"><span class="pre">SIGTERM</span></code></a> | |
| using the <a class="reference internal" href="#asyncio.loop.add_signal_handler" title="asyncio.loop.add_signal_handler"><code class="xref py py-meth docutils literal notranslate"><span class="pre">loop.add_signal_handler()</span></code></a> method:</p> | |
| <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> | |
| <span class="kn">import</span><span class="w"> </span><span class="nn">functools</span> | |
| <span class="kn">import</span><span class="w"> </span><span class="nn">os</span> | |
| <span class="kn">import</span><span class="w"> </span><span class="nn">signal</span> | |
| <span class="k">def</span><span class="w"> </span><span class="nf">ask_exit</span><span class="p">(</span><span class="n">signame</span><span class="p">,</span> <span class="n">loop</span><span class="p">):</span> | |
| <span class="nb">print</span><span class="p">(</span><span class="s2">"got signal </span><span class="si">%s</span><span class="s2">: exit"</span> <span class="o">%</span> <span class="n">signame</span><span class="p">)</span> | |
| <span class="n">loop</span><span class="o">.</span><span class="n">stop</span><span class="p">()</span> | |
| <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">main</span><span class="p">():</span> | |
| <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> | |
| <span class="k">for</span> <span class="n">signame</span> <span class="ow">in</span> <span class="p">{</span><span class="s1">'SIGINT'</span><span class="p">,</span> <span class="s1">'SIGTERM'</span><span class="p">}:</span> | |
| <span class="n">loop</span><span class="o">.</span><span class="n">add_signal_handler</span><span class="p">(</span> | |
| <span class="nb">getattr</span><span class="p">(</span><span class="n">signal</span><span class="p">,</span> <span class="n">signame</span><span class="p">),</span> | |
| <span class="n">functools</span><span class="o">.</span><span class="n">partial</span><span class="p">(</span><span class="n">ask_exit</span><span class="p">,</span> <span class="n">signame</span><span class="p">,</span> <span class="n">loop</span><span class="p">))</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">3600</span><span class="p">)</span> | |
| <span class="nb">print</span><span class="p">(</span><span class="s2">"Event loop running for 1 hour, press Ctrl+C to interrupt."</span><span class="p">)</span> | |
| <span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">"pid </span><span class="si">{</span><span class="n">os</span><span class="o">.</span><span class="n">getpid</span><span class="p">()</span><span class="si">}</span><span class="s2">: send SIGINT or SIGTERM to exit."</span><span class="p">)</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> | |
| </pre></div> | |
| </div> | |
| </section> | |
| </section> | |
| </section> | |
| <div class="clearer"></div> | |
| </div> | |
| </div> | |
| </div> | |
| <div class="sphinxsidebar" role="navigation" aria-label="Main"> | |
| <div class="sphinxsidebarwrapper"> | |
| <div> | |
| <h3><a href="../contents.html">Table of Contents</a></h3> | |
| <ul> | |
| <li><a class="reference internal" href="#">Event Loop</a><ul> | |
| <li><a class="reference internal" href="#event-loop-methods">Event Loop Methods</a><ul> | |
| <li><a class="reference internal" href="#running-and-stopping-the-loop">Running and stopping the loop</a></li> | |
| <li><a class="reference internal" href="#scheduling-callbacks">Scheduling callbacks</a></li> | |
| <li><a class="reference internal" href="#scheduling-delayed-callbacks">Scheduling delayed callbacks</a></li> | |
| <li><a class="reference internal" href="#creating-futures-and-tasks">Creating Futures and Tasks</a></li> | |
| <li><a class="reference internal" href="#opening-network-connections">Opening network connections</a></li> | |
| <li><a class="reference internal" href="#creating-network-servers">Creating network servers</a></li> | |
| <li><a class="reference internal" href="#transferring-files">Transferring files</a></li> | |
| <li><a class="reference internal" href="#tls-upgrade">TLS Upgrade</a></li> | |
| <li><a class="reference internal" href="#watching-file-descriptors">Watching file descriptors</a></li> | |
| <li><a class="reference internal" href="#working-with-socket-objects-directly">Working with socket objects directly</a></li> | |
| <li><a class="reference internal" href="#dns">DNS</a></li> | |
| <li><a class="reference internal" href="#working-with-pipes">Working with pipes</a></li> | |
| <li><a class="reference internal" href="#unix-signals">Unix signals</a></li> | |
| <li><a class="reference internal" href="#executing-code-in-thread-or-process-pools">Executing code in thread or process pools</a></li> | |
| <li><a class="reference internal" href="#error-handling-api">Error Handling API</a></li> | |
| <li><a class="reference internal" href="#enabling-debug-mode">Enabling debug mode</a></li> | |
| <li><a class="reference internal" href="#running-subprocesses">Running Subprocesses</a></li> | |
| </ul> | |
| </li> | |
| <li><a class="reference internal" href="#callback-handles">Callback Handles</a></li> | |
| <li><a class="reference internal" href="#server-objects">Server Objects</a></li> | |
| <li><a class="reference internal" href="#event-loop-implementations">Event Loop Implementations</a></li> | |
| <li><a class="reference internal" href="#examples">Examples</a><ul> | |
| <li><a class="reference internal" href="#hello-world-with-call-soon">Hello World with call_soon()</a></li> | |
| <li><a class="reference internal" href="#display-the-current-date-with-call-later">Display the current date with call_later()</a></li> | |
| <li><a class="reference internal" href="#watch-a-file-descriptor-for-read-events">Watch a file descriptor for read events</a></li> | |
| <li><a class="reference internal" href="#set-signal-handlers-for-sigint-and-sigterm">Set signal handlers for SIGINT and SIGTERM</a></li> | |
| </ul> | |
| </li> | |
| </ul> | |
| </li> | |
| </ul> | |
| </div> | |
| <div> | |
| <h4>Previous topic</h4> | |
| <p class="topless"><a href="asyncio-graph.html" | |
| title="previous chapter">Call Graph Introspection</a></p> | |
| </div> | |
| <div> | |
| <h4>Next topic</h4> | |
| <p class="topless"><a href="asyncio-future.html" | |
| title="next chapter">Futures</a></p> | |
| </div> | |
| <script> | |
| document.addEventListener('DOMContentLoaded', () => { | |
| const title = document.querySelector('meta[property="og:title"]').content; | |
| const elements = document.querySelectorAll('.improvepage'); | |
| const pageurl = window.location.href.split('?')[0]; | |
| elements.forEach(element => { | |
| const url = new URL(element.href.split('?')[0].replace("-nojs", "")); | |
| url.searchParams.set('pagetitle', title); | |
| url.searchParams.set('pageurl', pageurl); | |
| url.searchParams.set('pagesource', "library/asyncio-eventloop.rst"); | |
| element.href = url.toString(); | |
| }); | |
| }); | |
| </script> | |
| <div role="note" aria-label="source link"> | |
| <h3>This page</h3> | |
| <ul class="this-page-menu"> | |
| <li><a href="../bugs.html">Report a bug</a></li> | |
| <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li> | |
| <li> | |
| <a href="https://github.com/python/cpython/blob/main/Doc/library/asyncio-eventloop.rst?plain=1" | |
| rel="nofollow">Show source | |
| </a> | |
| </li> | |
| </ul> | |
| </div> | |
| </div> | |
| <div id="sidebarbutton" title="Collapse sidebar"> | |
| <span>«</span> | |
| </div> | |
| </div> | |
| <div class="clearer"></div> | |
| </div> | |
| <div class="related" role="navigation" aria-label="Related"> | |
| <h3>Navigation</h3> | |
| <ul> | |
| <li class="right" style="margin-right: 10px"> | |
| <a href="../genindex.html" title="General Index" | |
| >index</a></li> | |
| <li class="right" > | |
| <a href="../py-modindex.html" title="Python Module Index" | |
| >modules</a> |</li> | |
| <li class="right" > | |
| <a href="asyncio-future.html" title="Futures" | |
| >next</a> |</li> | |
| <li class="right" > | |
| <a href="asyncio-graph.html" title="Call Graph Introspection" | |
| >previous</a> |</li> | |
| <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li> | |
| <li><a href="https://www.python.org/">Python</a> »</li> | |
| <li class="switchers"> | |
| <div class="language_switcher_placeholder"></div> | |
| <div class="version_switcher_placeholder"></div> | |
| </li> | |
| <li> | |
| </li> | |
| <li id="cpython-language-and-version"> | |
| <a href="../index.html">3.15.0a6 Documentation</a> » | |
| </li> | |
| <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li> | |
| <li class="nav-item nav-item-2"><a href="ipc.html" >Networking and Interprocess Communication</a> »</li> | |
| <li class="nav-item nav-item-3"><a href="asyncio.html" ><code class="xref py py-mod docutils literal notranslate"><span class="pre">asyncio</span></code> — Asynchronous I/O</a> »</li> | |
| <li class="nav-item nav-item-this"><a href="">Event Loop</a></li> | |
| <li class="right"> | |
| <div class="inline-search" role="search"> | |
| <form class="inline-search" action="../search.html" method="get"> | |
| <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box"> | |
| <input type="submit" value="Go"> | |
| </form> | |
| </div> | |
| | | |
| </li> | |
| <li class="right"> | |
| <label class="theme-selector-label"> | |
| Theme | |
| <select class="theme-selector" oninput="activateTheme(this.value)"> | |
| <option value="auto" selected>Auto</option> | |
| <option value="light">Light</option> | |
| <option value="dark">Dark</option> | |
| </select> | |
| </label> |</li> | |
| </ul> | |
| </div> | |
| <div class="footer"> | |
| © <a href="../copyright.html">Copyright</a> 2001 Python Software Foundation. | |
| <br> | |
| This page is licensed under the Python Software Foundation License Version 2. | |
| <br> | |
| Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License. | |
| <br> | |
| See <a href="/license.html">History and License</a> for more information.<br> | |
| <br> | |
| The Python Software Foundation is a non-profit corporation. | |
| <a href="https://www.python.org/psf/donations/">Please donate.</a> | |
| <br> | |
| <br> | |
| Last updated on Mar 10, 2026 (08:58 UTC). | |
| <a href="/bugs.html">Found a bug</a>? | |
| <br> | |
| Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3. | |
| </div> | |
| </body> | |
| </html> |