2275 lines
229 KiB
HTML
2275 lines
229 KiB
HTML
<!DOCTYPE html>
|
||
|
||
<html lang="en" data-content_root="../">
|
||
<head>
|
||
<meta charset="utf-8" />
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
|
||
<meta property="og:title" content="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" content="https://docs.python.org/3/_static/og-image.png" />
|
||
<meta property="og:image:alt" content="Python documentation" />
|
||
<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 property="og:image:width" content="200">
|
||
<meta property="og:image:height" content="200">
|
||
<meta name="theme-color" content="#3776ab">
|
||
|
||
<title>Event Loop — Python 3.13.3 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
|
||
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />
|
||
<link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=23252803" />
|
||
<link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=5349f25f" />
|
||
|
||
<script src="../_static/documentation_options.js?v=5d57ca2d"></script>
|
||
<script src="../_static/doctools.js?v=9bcbadda"></script>
|
||
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
|
||
|
||
<script src="../_static/sidebar.js"></script>
|
||
|
||
<link rel="search" type="application/opensearchdescription+xml"
|
||
title="Search within Python 3.13.3 documentation"
|
||
href="../_static/opensearch.xml"/>
|
||
<link rel="author" title="About these documents" href="../about.html" />
|
||
<link rel="index" title="Index" href="../genindex.html" />
|
||
<link rel="search" title="Search" href="../search.html" />
|
||
<link rel="copyright" title="Copyright" href="../copyright.html" />
|
||
<link rel="next" title="Futures" href="asyncio-future.html" />
|
||
<link rel="prev" title="Exceptions" href="asyncio-exceptions.html" />
|
||
|
||
<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-exceptions.html"
|
||
title="previous chapter">Exceptions</a></p>
|
||
</div>
|
||
<div>
|
||
<h4>Next topic</h4>
|
||
<p class="topless"><a href="asyncio-future.html"
|
||
title="next chapter">Futures</a></p>
|
||
</div>
|
||
<div role="note" aria-label="source link">
|
||
<h3>This Page</h3>
|
||
<ul class="this-page-menu">
|
||
<li><a href="../bugs.html">Report a Bug</a></li>
|
||
<li>
|
||
<a href="https://github.com/python/cpython/blob/main/Doc/library/asyncio-eventloop.rst"
|
||
rel="nofollow">Show Source
|
||
</a>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</nav>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
<div class="related" role="navigation" aria-label="Related">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="General Index"
|
||
accesskey="I">index</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python Module Index"
|
||
>modules</a> |</li>
|
||
<li class="right" >
|
||
<a href="asyncio-future.html" title="Futures"
|
||
accesskey="N">next</a> |</li>
|
||
<li class="right" >
|
||
<a href="asyncio-exceptions.html" title="Exceptions"
|
||
accesskey="P">previous</a> |</li>
|
||
|
||
<li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li class="switchers">
|
||
<div class="language_switcher_placeholder"></div>
|
||
<div class="version_switcher_placeholder"></div>
|
||
</li>
|
||
<li>
|
||
|
||
</li>
|
||
<li id="cpython-language-and-version">
|
||
<a href="../index.html">3.13.3 Documentation</a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >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/3.13/Lib/asyncio/events.py">Lib/asyncio/events.py</a>,
|
||
<a class="extlink-source reference external" href="https://github.com/python/cpython/tree/3.13/Lib/asyncio/base_events.py">Lib/asyncio/base_events.py</a></p>
|
||
<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 <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>
|
||
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="deprecated">
|
||
<p><span class="versionmodified deprecated">Deprecated since version 3.12: </span>Deprecation warning is emitted if there is no current event loop.
|
||
In some future Python release this will become an error.</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 <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">run_forever()</span></code></a> 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 <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">run_forever()</span></code></a> 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 <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">run_forever()</span></code></a> 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 <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> 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. If you want the callback to be called with keyword
|
||
arguments 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>
|
||
<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="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="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><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 <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>.</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>
|
||
<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>
|
||
</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>
|
||
</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></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 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.</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.</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="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><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> 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>.</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><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 <a class="reference internal" href="subprocess.html#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">Popen</span></code></a> 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>
|
||
</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>
|
||
</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 <a class="reference internal" href="#asyncio.Server.close_clients" title="asyncio.Server.close_clients"><code class="xref py py-meth docutils literal notranslate"><span class="pre">close_clients()</span></code></a> 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 <a class="reference internal" href="#asyncio.Server.abort_clients" title="asyncio.Server.abort_clients"><code class="xref py py-meth docutils literal notranslate"><span class="pre">abort_clients()</span></code></a> 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">class</span><span class="w"> </span><span class="nc">MyPolicy</span><span class="p">(</span><span class="n">asyncio</span><span class="o">.</span><span class="n">DefaultEventLoopPolicy</span><span class="p">):</span>
|
||
<span class="k">def</span><span class="w"> </span><span class="nf">new_event_loop</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
|
||
<span class="n">selector</span> <span class="o">=</span> <span class="n">selectors</span><span class="o">.</span><span class="n">SelectSelector</span><span class="p">()</span>
|
||
<span class="k">return</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">SelectorEventLoop</span><span class="p">(</span><span class="n">selector</span><span class="p">)</span>
|
||
|
||
<span class="n">asyncio</span><span class="o">.</span><span class="n">set_event_loop_policy</span><span class="p">(</span><span class="n">MyPolicy</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-exceptions.html"
|
||
title="previous chapter">Exceptions</a></p>
|
||
</div>
|
||
<div>
|
||
<h4>Next topic</h4>
|
||
<p class="topless"><a href="asyncio-future.html"
|
||
title="next chapter">Futures</a></p>
|
||
</div>
|
||
<div role="note" aria-label="source link">
|
||
<h3>This Page</h3>
|
||
<ul class="this-page-menu">
|
||
<li><a href="../bugs.html">Report a Bug</a></li>
|
||
<li>
|
||
<a href="https://github.com/python/cpython/blob/main/Doc/library/asyncio-eventloop.rst"
|
||
rel="nofollow">Show Source
|
||
</a>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
<div id="sidebarbutton" title="Collapse sidebar">
|
||
<span>«</span>
|
||
</div>
|
||
|
||
</div>
|
||
<div class="clearer"></div>
|
||
</div>
|
||
<div class="related" role="navigation" aria-label="Related">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="General Index"
|
||
>index</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python Module Index"
|
||
>modules</a> |</li>
|
||
<li class="right" >
|
||
<a href="asyncio-future.html" title="Futures"
|
||
>next</a> |</li>
|
||
<li class="right" >
|
||
<a href="asyncio-exceptions.html" title="Exceptions"
|
||
>previous</a> |</li>
|
||
|
||
<li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li class="switchers">
|
||
<div class="language_switcher_placeholder"></div>
|
||
<div class="version_switcher_placeholder"></div>
|
||
</li>
|
||
<li>
|
||
|
||
</li>
|
||
<li id="cpython-language-and-version">
|
||
<a href="../index.html">3.13.3 Documentation</a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >The Python 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-2025, Python Software Foundation.
|
||
<br />
|
||
This page is licensed under the Python Software Foundation License Version 2.
|
||
<br />
|
||
Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.
|
||
<br />
|
||
|
||
See <a href="/license.html">History and License</a> for more information.<br />
|
||
|
||
|
||
<br />
|
||
|
||
The Python Software Foundation is a non-profit corporation.
|
||
<a href="https://www.python.org/psf/donations/">Please donate.</a>
|
||
<br />
|
||
<br />
|
||
Last updated on Apr 08, 2025 (14:33 UTC).
|
||
|
||
<a href="/bugs.html">Found a bug</a>?
|
||
|
||
<br />
|
||
|
||
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.
|
||
</div>
|
||
|
||
</body>
|
||
</html> |