1754 lines
160 KiB
HTML
1754 lines
160 KiB
HTML
|
|
|||
|
|
<!DOCTYPE html>
|
|||
|
|
|
|||
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|||
|
|
<head>
|
|||
|
|
<meta charset="utf-8" />
|
|||
|
|
<title>Event Loop — Python 3.7.4 documentation</title>
|
|||
|
|
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
|
|||
|
|
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
|
|||
|
|
|
|||
|
|
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
|
|||
|
|
<script type="text/javascript" src="../_static/jquery.js"></script>
|
|||
|
|
<script type="text/javascript" src="../_static/underscore.js"></script>
|
|||
|
|
<script type="text/javascript" src="../_static/doctools.js"></script>
|
|||
|
|
<script type="text/javascript" src="../_static/language_data.js"></script>
|
|||
|
|
|
|||
|
|
<script type="text/javascript" src="../_static/sidebar.js"></script>
|
|||
|
|
|
|||
|
|
<link rel="search" type="application/opensearchdescription+xml"
|
|||
|
|
title="Search within Python 3.7.4 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="shortcut icon" type="image/png" href="../_static/py.png" />
|
|||
|
|
<link rel="canonical" href="https://docs.python.org/3/library/asyncio-eventloop.html" />
|
|||
|
|
|
|||
|
|
<script type="text/javascript" src="../_static/copybutton.js"></script>
|
|||
|
|
<script type="text/javascript" src="../_static/switchers.js"></script>
|
|||
|
|
|
|||
|
|
|
|||
|
|
|
|||
|
|
<style>
|
|||
|
|
@media only screen {
|
|||
|
|
table.full-width-table {
|
|||
|
|
width: 100%;
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
</style>
|
|||
|
|
|
|||
|
|
|
|||
|
|
</head><body>
|
|||
|
|
|
|||
|
|
<div class="related" role="navigation" aria-label="related navigation">
|
|||
|
|
<h3>Navigation</h3>
|
|||
|
|
<ul>
|
|||
|
|
<li class="right" style="margin-right: 10px">
|
|||
|
|
<a href="../genindex.html" title="General Index"
|
|||
|
|
accesskey="I">index</a></li>
|
|||
|
|
<li class="right" >
|
|||
|
|
<a href="../py-modindex.html" title="Python Module Index"
|
|||
|
|
>modules</a> |</li>
|
|||
|
|
<li class="right" >
|
|||
|
|
<a href="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.png" alt=""
|
|||
|
|
style="vertical-align: middle; margin-top: -1px"/></li>
|
|||
|
|
<li><a href="https://www.python.org/">Python</a> »</li>
|
|||
|
|
<li>
|
|||
|
|
<span class="language_switcher_placeholder">en</span>
|
|||
|
|
<span class="version_switcher_placeholder">3.7.4</span>
|
|||
|
|
<a href="../index.html">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="right">
|
|||
|
|
|
|||
|
|
|
|||
|
|
<div class="inline-search" style="display: none" role="search">
|
|||
|
|
<form class="inline-search" action="../search.html" method="get">
|
|||
|
|
<input placeholder="Quick search" type="text" name="q" />
|
|||
|
|
<input type="submit" value="Go" />
|
|||
|
|
<input type="hidden" name="check_keywords" value="yes" />
|
|||
|
|
<input type="hidden" name="area" value="default" />
|
|||
|
|
</form>
|
|||
|
|
</div>
|
|||
|
|
<script type="text/javascript">$('.inline-search').show(0);</script>
|
|||
|
|
|
|
|||
|
|
</li>
|
|||
|
|
|
|||
|
|
</ul>
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
<div class="document">
|
|||
|
|
<div class="documentwrapper">
|
|||
|
|
<div class="bodywrapper">
|
|||
|
|
<div class="body" role="main">
|
|||
|
|
|
|||
|
|
<div class="section" id="event-loop">
|
|||
|
|
<h1>Event Loop<a class="headerlink" href="#event-loop" title="Permalink to this headline">¶</a></h1>
|
|||
|
|
<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-task.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="function">
|
|||
|
|
<dt id="asyncio.get_running_loop">
|
|||
|
|
<code class="descclassname">asyncio.</code><code class="descname">get_running_loop</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.get_running_loop" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return the running event loop in the current OS thread.</p>
|
|||
|
|
<p>If there is no running event loop 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> is raised.
|
|||
|
|
This function can only be called from a coroutine or a callback.</p>
|
|||
|
|
<div class="versionadded">
|
|||
|
|
<p><span class="versionmodified added">New in version 3.7.</span></p>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="function">
|
|||
|
|
<dt id="asyncio.get_event_loop">
|
|||
|
|
<code class="descclassname">asyncio.</code><code class="descname">get_event_loop</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.get_event_loop" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Get the current event loop. If there is no current event loop set
|
|||
|
|
in the current OS thread and <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> has not yet
|
|||
|
|
been called, asyncio will create a new event loop and set it as the
|
|||
|
|
current one.</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>Consider also using the <a class="reference internal" href="asyncio-task.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
|
|||
|
|
lower level functions to manually create and close an event loop.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="function">
|
|||
|
|
<dt id="asyncio.set_event_loop">
|
|||
|
|
<code class="descclassname">asyncio.</code><code class="descname">set_event_loop</code><span class="sig-paren">(</span><em>loop</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.set_event_loop" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Set <em>loop</em> as a current event loop for the current OS thread.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="function">
|
|||
|
|
<dt id="asyncio.new_event_loop">
|
|||
|
|
<code class="descclassname">asyncio.</code><code class="descname">new_event_loop</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.new_event_loop" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Create 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>
|
|||
|
|
<div class="section" id="event-loop-methods">
|
|||
|
|
<span id="asyncio-event-loop"></span><h2>Event Loop Methods<a class="headerlink" href="#event-loop-methods" title="Permalink to this headline">¶</a></h2>
|
|||
|
|
<p>Event loops have <strong>low-level</strong> APIs for the following:</p>
|
|||
|
|
<div class="contents local topic" 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>
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="running-and-stopping-the-loop">
|
|||
|
|
<h3><a class="toc-backref" href="#id1">Running and stopping the loop</a><a class="headerlink" href="#running-and-stopping-the-loop" title="Permalink to this headline">¶</a></h3>
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="asyncio.loop.run_until_complete">
|
|||
|
|
<code class="descclassname">loop.</code><code class="descname">run_until_complete</code><span class="sig-paren">(</span><em>future</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.run_until_complete" title="Permalink 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="method">
|
|||
|
|
<dt id="asyncio.loop.run_forever">
|
|||
|
|
<code class="descclassname">loop.</code><code class="descname">run_forever</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.run_forever" title="Permalink 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="method">
|
|||
|
|
<dt id="asyncio.loop.stop">
|
|||
|
|
<code class="descclassname">loop.</code><code class="descname">stop</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.stop" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Stop the event loop.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="asyncio.loop.is_running">
|
|||
|
|
<code class="descclassname">loop.</code><code class="descname">is_running</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.is_running" title="Permalink 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="method">
|
|||
|
|
<dt id="asyncio.loop.is_closed">
|
|||
|
|
<code class="descclassname">loop.</code><code class="descname">is_closed</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.is_closed" title="Permalink 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="method">
|
|||
|
|
<dt id="asyncio.loop.close">
|
|||
|
|
<code class="descclassname">loop.</code><code class="descname">close</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.close" title="Permalink 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="method">
|
|||
|
|
<dt id="asyncio.loop.shutdown_asyncgens">
|
|||
|
|
<em class="property">coroutine </em><code class="descclassname">loop.</code><code class="descname">shutdown_asyncgens</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.shutdown_asyncgens" title="Permalink 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-task.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">New in version 3.6.</span></p>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="scheduling-callbacks">
|
|||
|
|
<h3><a class="toc-backref" href="#id2">Scheduling callbacks</a><a class="headerlink" href="#scheduling-callbacks" title="Permalink to this headline">¶</a></h3>
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="asyncio.loop.call_soon">
|
|||
|
|
<code class="descclassname">loop.</code><code class="descname">call_soon</code><span class="sig-paren">(</span><em>callback</em>, <em>*args</em>, <em>context=None</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.call_soon" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Schedule a <em>callback</em> to be called with <em>args</em> arguments at
|
|||
|
|
the next iteration of the event loop.</p>
|
|||
|
|
<p>Callbacks are called in the order in which they are registered.
|
|||
|
|
Each callback will be called exactly once.</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>
|
|||
|
|
<p>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> is returned, which can be
|
|||
|
|
used later to cancel the callback.</p>
|
|||
|
|
<p>This method is not thread-safe.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="asyncio.loop.call_soon_threadsafe">
|
|||
|
|
<code class="descclassname">loop.</code><code class="descname">call_soon_threadsafe</code><span class="sig-paren">(</span><em>callback</em>, <em>*args</em>, <em>context=None</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.call_soon_threadsafe" title="Permalink 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>. Must be used to
|
|||
|
|
schedule callbacks <em>from another thread</em>.</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>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<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://www.python.org/dev/peps/pep-0567"><strong>PEP 567</strong></a>
|
|||
|
|
for more details.</p>
|
|||
|
|
</div>
|
|||
|
|
<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>
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="scheduling-delayed-callbacks">
|
|||
|
|
<span id="asyncio-delayed-calls"></span><h3><a class="toc-backref" href="#id3">Scheduling delayed callbacks</a><a class="headerlink" href="#scheduling-delayed-callbacks" title="Permalink to this headline">¶</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="method">
|
|||
|
|
<dt id="asyncio.loop.call_later">
|
|||
|
|
<code class="descclassname">loop.</code><code class="descname">call_later</code><span class="sig-paren">(</span><em>delay</em>, <em>callback</em>, <em>*args</em>, <em>context=None</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.call_later" title="Permalink 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://www.python.org/dev/peps/pep-0567"><strong>PEP 567</strong></a>
|
|||
|
|
for more details.</p>
|
|||
|
|
</div>
|
|||
|
|
<div class="versionchanged">
|
|||
|
|
<p><span class="versionmodified changed">Changed in version 3.7.1: </span>In Python 3.7.0 and earlier with the default event loop implementation,
|
|||
|
|
the <em>delay</em> could not exceed one day.
|
|||
|
|
This has been fixed in Python 3.7.1.</p>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="asyncio.loop.call_at">
|
|||
|
|
<code class="descclassname">loop.</code><code class="descname">call_at</code><span class="sig-paren">(</span><em>when</em>, <em>callback</em>, <em>*args</em>, <em>context=None</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.call_at" title="Permalink 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://www.python.org/dev/peps/pep-0567"><strong>PEP 567</strong></a>
|
|||
|
|
for more details.</p>
|
|||
|
|
</div>
|
|||
|
|
<div class="versionchanged">
|
|||
|
|
<p><span class="versionmodified changed">Changed in version 3.7.1: </span>In Python 3.7.0 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.7.1.</p>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="asyncio.loop.time">
|
|||
|
|
<code class="descclassname">loop.</code><code class="descname">time</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.time" title="Permalink 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>
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="creating-futures-and-tasks">
|
|||
|
|
<h3><a class="toc-backref" href="#id4">Creating Futures and Tasks</a><a class="headerlink" href="#creating-futures-and-tasks" title="Permalink to this headline">¶</a></h3>
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="asyncio.loop.create_future">
|
|||
|
|
<code class="descclassname">loop.</code><code class="descname">create_future</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.create_future" title="Permalink 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">New in version 3.5.2.</span></p>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="asyncio.loop.create_task">
|
|||
|
|
<code class="descclassname">loop.</code><code class="descname">create_task</code><span class="sig-paren">(</span><em>coro</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.create_task" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Schedule the execution of a <a class="reference internal" href="asyncio-task.html#coroutine"><span class="std std-ref">Coroutines</span></a>.
|
|||
|
|
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>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="asyncio.loop.set_task_factory">
|
|||
|
|
<code class="descclassname">loop.</code><code class="descname">set_task_factory</code><span class="sig-paren">(</span><em>factory</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.set_task_factory" title="Permalink 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></code>, where <em>loop</em> is a reference to the active
|
|||
|
|
event loop, and <em>coro</em> is a coroutine object. The callable
|
|||
|
|
must return 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>-compatible object.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="asyncio.loop.get_task_factory">
|
|||
|
|
<code class="descclassname">loop.</code><code class="descname">get_task_factory</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.get_task_factory" title="Permalink 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>
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="opening-network-connections">
|
|||
|
|
<h3><a class="toc-backref" href="#id5">Opening network connections</a><a class="headerlink" href="#opening-network-connections" title="Permalink to this headline">¶</a></h3>
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="asyncio.loop.create_connection">
|
|||
|
|
<em class="property">coroutine </em><code class="descclassname">loop.</code><code class="descname">create_connection</code><span class="sig-paren">(</span><em>protocol_factory</em>, <em>host=None</em>, <em>port=None</em>, <em>*</em>, <em>ssl=None</em>, <em>family=0</em>, <em>proto=0</em>, <em>flags=0</em>, <em>sock=None</em>, <em>local_addr=None</em>, <em>server_hostname=None</em>, <em>ssl_handshake_timeout=None</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.create_connection" title="Permalink 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-data 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-data 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-data 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>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>
|
|||
|
|
and <em>local_addr</em> should be specified.</p></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 to 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>
|
|||
|
|
</ul>
|
|||
|
|
<div class="versionadded">
|
|||
|
|
<p><span class="versionmodified added">New in version 3.7: </span>The <em>ssl_handshake_timeout</em> parameter.</p>
|
|||
|
|
</div>
|
|||
|
|
<div class="versionchanged">
|
|||
|
|
<p><span class="versionmodified changed">Changed in version 3.6: </span>The socket option <code class="xref py py-data docutils literal notranslate"><span class="pre">TCP_NODELAY</span></code> is set by default
|
|||
|
|
for all TCP connections.</p>
|
|||
|
|
</div>
|
|||
|
|
<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="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="method">
|
|||
|
|
<dt id="asyncio.loop.create_datagram_endpoint">
|
|||
|
|
<em class="property">coroutine </em><code class="descclassname">loop.</code><code class="descname">create_datagram_endpoint</code><span class="sig-paren">(</span><em>protocol_factory</em>, <em>local_addr=None</em>, <em>remote_addr=None</em>, <em>*</em>, <em>family=0</em>, <em>proto=0</em>, <em>flags=0</em>, <em>reuse_address=None</em>, <em>reuse_port=None</em>, <em>allow_broadcast=None</em>, <em>sock=None</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.create_datagram_endpoint" title="Permalink 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-data 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-data 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-data 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-data 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 class="simple">
|
|||
|
|
<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 to 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_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
|
|||
|
|
and some Unixes. If the <code class="xref py py-data docutils literal notranslate"><span class="pre">SO_REUSEPORT</span></code> 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></li>
|
|||
|
|
</ul>
|
|||
|
|
<p>On Windows, with <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>, this method is not supported.</p>
|
|||
|
|
<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,
|
|||
|
|
*allow_broadcast</em>, and <em>sock</em> parameters were added.</p>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="asyncio.loop.create_unix_connection">
|
|||
|
|
<em class="property">coroutine </em><code class="descclassname">loop.</code><code class="descname">create_unix_connection</code><span class="sig-paren">(</span><em>protocol_factory</em>, <em>path=None</em>, <em>*</em>, <em>ssl=None</em>, <em>sock=None</em>, <em>server_hostname=None</em>, <em>ssl_handshake_timeout=None</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.create_unix_connection" title="Permalink 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-data 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-data 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>
|
|||
|
|
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
|||
|
|
<div class="versionadded">
|
|||
|
|
<p><span class="versionmodified added">New in version 3.7: </span>The <em>ssl_handshake_timeout</em> parameter.</p>
|
|||
|
|
</div>
|
|||
|
|
<div class="versionchanged">
|
|||
|
|
<p><span class="versionmodified changed">Changed in version 3.7: </span>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>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="creating-network-servers">
|
|||
|
|
<h3><a class="toc-backref" href="#id6">Creating network servers</a><a class="headerlink" href="#creating-network-servers" title="Permalink to this headline">¶</a></h3>
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="asyncio.loop.create_server">
|
|||
|
|
<em class="property">coroutine </em><code class="descclassname">loop.</code><code class="descname">create_server</code><span class="sig-paren">(</span><em>protocol_factory</em>, <em>host=None</em>, <em>port=None</em>, <em>*</em>, <em>family=socket.AF_UNSPEC</em>, <em>flags=socket.AI_PASSIVE</em>, <em>sock=None</em>, <em>backlog=100</em>, <em>ssl=None</em>, <em>reuse_address=None</em>, <em>reuse_port=None</em>, <em>ssl_handshake_timeout=None</em>, <em>start_serving=True</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.create_server" title="Permalink 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-data 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 class="simple">
|
|||
|
|
<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>
|
|||
|
|
<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><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-data 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-data 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 <code class="xref py py-data docutils literal notranslate"><span class="pre">AF_UNSPEC</span></code>).</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></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>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>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="versionadded">
|
|||
|
|
<p><span class="versionmodified added">New in version 3.7: </span>Added <em>ssl_handshake_timeout</em> and <em>start_serving</em> parameters.</p>
|
|||
|
|
</div>
|
|||
|
|
<div class="versionchanged">
|
|||
|
|
<p><span class="versionmodified changed">Changed in version 3.6: </span>The socket option <code class="xref py py-data docutils literal notranslate"><span class="pre">TCP_NODELAY</span></code> is set by default
|
|||
|
|
for all TCP connections.</p>
|
|||
|
|
</div>
|
|||
|
|
<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="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="method">
|
|||
|
|
<dt id="asyncio.loop.create_unix_server">
|
|||
|
|
<em class="property">coroutine </em><code class="descclassname">loop.</code><code class="descname">create_unix_server</code><span class="sig-paren">(</span><em>protocol_factory</em>, <em>path=None</em>, <em>*</em>, <em>sock=None</em>, <em>backlog=100</em>, <em>ssl=None</em>, <em>ssl_handshake_timeout=None</em>, <em>start_serving=True</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.create_unix_server" title="Permalink 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-data 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>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>
|
|||
|
|
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
|||
|
|
<div class="versionadded">
|
|||
|
|
<p><span class="versionmodified added">New in version 3.7: </span>The <em>ssl_handshake_timeout</em> and <em>start_serving</em> parameters.</p>
|
|||
|
|
</div>
|
|||
|
|
<div class="versionchanged">
|
|||
|
|
<p><span class="versionmodified changed">Changed in version 3.7: </span>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>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="asyncio.loop.connect_accepted_socket">
|
|||
|
|
<em class="property">coroutine </em><code class="descclassname">loop.</code><code class="descname">connect_accepted_socket</code><span class="sig-paren">(</span><em>protocol_factory</em>, <em>sock</em>, <em>*</em>, <em>ssl=None</em>, <em>ssl_handshake_timeout=None</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.connect_accepted_socket" title="Permalink 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 class="simple">
|
|||
|
|
<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></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>
|
|||
|
|
</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">New in version 3.7: </span>The <em>ssl_handshake_timeout</em> parameter.</p>
|
|||
|
|
</div>
|
|||
|
|
<div class="versionadded">
|
|||
|
|
<p><span class="versionmodified added">New in version 3.5.3.</span></p>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="transferring-files">
|
|||
|
|
<h3><a class="toc-backref" href="#id7">Transferring files</a><a class="headerlink" href="#transferring-files" title="Permalink to this headline">¶</a></h3>
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="asyncio.loop.sendfile">
|
|||
|
|
<em class="property">coroutine </em><code class="descclassname">loop.</code><code class="descname">sendfile</code><span class="sig-paren">(</span><em>transport</em>, <em>file</em>, <em>offset=0</em>, <em>count=None</em>, <em>*</em>, <em>fallback=True</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.sendfile" title="Permalink 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">New in version 3.7.</span></p>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="tls-upgrade">
|
|||
|
|
<h3><a class="toc-backref" href="#id8">TLS Upgrade</a><a class="headerlink" href="#tls-upgrade" title="Permalink to this headline">¶</a></h3>
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="asyncio.loop.start_tls">
|
|||
|
|
<em class="property">coroutine </em><code class="descclassname">loop.</code><code class="descname">start_tls</code><span class="sig-paren">(</span><em>transport</em>, <em>protocol</em>, <em>sslcontext</em>, <em>*</em>, <em>server_side=False</em>, <em>server_hostname=None</em>, <em>ssl_handshake_timeout=None</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.start_tls" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Upgrade an existing transport-based connection to TLS.</p>
|
|||
|
|
<p>Return a new transport instance, that the <em>protocol</em> must start using
|
|||
|
|
immediately after the <em>await</em>. The <em>transport</em> instance passed to
|
|||
|
|
the <em>start_tls</em> method should never be used again.</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>
|
|||
|
|
</ul>
|
|||
|
|
<div class="versionadded">
|
|||
|
|
<p><span class="versionmodified added">New in version 3.7.</span></p>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="watching-file-descriptors">
|
|||
|
|
<h3><a class="toc-backref" href="#id9">Watching file descriptors</a><a class="headerlink" href="#watching-file-descriptors" title="Permalink to this headline">¶</a></h3>
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="asyncio.loop.add_reader">
|
|||
|
|
<code class="descclassname">loop.</code><code class="descname">add_reader</code><span class="sig-paren">(</span><em>fd</em>, <em>callback</em>, <em>*args</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.add_reader" title="Permalink 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>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="asyncio.loop.remove_reader">
|
|||
|
|
<code class="descclassname">loop.</code><code class="descname">remove_reader</code><span class="sig-paren">(</span><em>fd</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.remove_reader" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Stop monitoring the <em>fd</em> file descriptor for read availability.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="asyncio.loop.add_writer">
|
|||
|
|
<code class="descclassname">loop.</code><code class="descname">add_writer</code><span class="sig-paren">(</span><em>fd</em>, <em>callback</em>, <em>*args</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.add_writer" title="Permalink 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>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="method">
|
|||
|
|
<dt id="asyncio.loop.remove_writer">
|
|||
|
|
<code class="descclassname">loop.</code><code class="descname">remove_writer</code><span class="sig-paren">(</span><em>fd</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.remove_writer" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Stop monitoring the <em>fd</em> file descriptor for write availability.</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>
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="working-with-socket-objects-directly">
|
|||
|
|
<h3><a class="toc-backref" href="#id10">Working with socket objects directly</a><a class="headerlink" href="#working-with-socket-objects-directly" title="Permalink to this headline">¶</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="method">
|
|||
|
|
<dt id="asyncio.loop.sock_recv">
|
|||
|
|
<em class="property">coroutine </em><code class="descclassname">loop.</code><code class="descname">sock_recv</code><span class="sig-paren">(</span><em>sock</em>, <em>nbytes</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.sock_recv" title="Permalink 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="method">
|
|||
|
|
<dt id="asyncio.loop.sock_recv_into">
|
|||
|
|
<em class="property">coroutine </em><code class="descclassname">loop.</code><code class="descname">sock_recv_into</code><span class="sig-paren">(</span><em>sock</em>, <em>buf</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.sock_recv_into" title="Permalink 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">New in version 3.7.</span></p>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="asyncio.loop.sock_sendall">
|
|||
|
|
<em class="property">coroutine </em><code class="descclassname">loop.</code><code class="descname">sock_sendall</code><span class="sig-paren">(</span><em>sock</em>, <em>data</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.sock_sendall" title="Permalink 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 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">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="method">
|
|||
|
|
<dt id="asyncio.loop.sock_connect">
|
|||
|
|
<em class="property">coroutine </em><code class="descclassname">loop.</code><code class="descname">sock_connect</code><span class="sig-paren">(</span><em>sock</em>, <em>address</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.sock_connect" title="Permalink 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="method">
|
|||
|
|
<dt id="asyncio.loop.sock_accept">
|
|||
|
|
<em class="property">coroutine </em><code class="descclassname">loop.</code><code class="descname">sock_accept</code><span class="sig-paren">(</span><em>sock</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.sock_accept" title="Permalink 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="method">
|
|||
|
|
<dt id="asyncio.loop.sock_sendfile">
|
|||
|
|
<em class="property">coroutine </em><code class="descclassname">loop.</code><code class="descname">sock_sendfile</code><span class="sig-paren">(</span><em>sock</em>, <em>file</em>, <em>offset=0</em>, <em>count=None</em>, <em>*</em>, <em>fallback=True</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.sock_sendfile" title="Permalink 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">New in version 3.7.</span></p>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="dns">
|
|||
|
|
<h3><a class="toc-backref" href="#id11">DNS</a><a class="headerlink" href="#dns" title="Permalink to this headline">¶</a></h3>
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="asyncio.loop.getaddrinfo">
|
|||
|
|
<em class="property">coroutine </em><code class="descclassname">loop.</code><code class="descname">getaddrinfo</code><span class="sig-paren">(</span><em>host</em>, <em>port</em>, <em>*</em>, <em>family=0</em>, <em>type=0</em>, <em>proto=0</em>, <em>flags=0</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.getaddrinfo" title="Permalink 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="method">
|
|||
|
|
<dt id="asyncio.loop.getnameinfo">
|
|||
|
|
<em class="property">coroutine </em><code class="descclassname">loop.</code><code class="descname">getnameinfo</code><span class="sig-paren">(</span><em>sockaddr</em>, <em>flags=0</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.getnameinfo" title="Permalink 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="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>
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="working-with-pipes">
|
|||
|
|
<h3><a class="toc-backref" href="#id12">Working with pipes</a><a class="headerlink" href="#working-with-pipes" title="Permalink to this headline">¶</a></h3>
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="asyncio.loop.connect_read_pipe">
|
|||
|
|
<em class="property">coroutine </em><code class="descclassname">loop.</code><code class="descname">connect_read_pipe</code><span class="sig-paren">(</span><em>protocol_factory</em>, <em>pipe</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.connect_read_pipe" title="Permalink 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="method">
|
|||
|
|
<dt id="asyncio.loop.connect_write_pipe">
|
|||
|
|
<em class="property">coroutine </em><code class="descclassname">loop.</code><code class="descname">connect_write_pipe</code><span class="sig-paren">(</span><em>protocol_factory</em>, <em>pipe</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.connect_write_pipe" title="Permalink 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>
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="unix-signals">
|
|||
|
|
<h3><a class="toc-backref" href="#id13">Unix signals</a><a class="headerlink" href="#unix-signals" title="Permalink to this headline">¶</a></h3>
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="asyncio.loop.add_signal_handler">
|
|||
|
|
<code class="descclassname">loop.</code><code class="descname">add_signal_handler</code><span class="sig-paren">(</span><em>signum</em>, <em>callback</em>, <em>*args</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.add_signal_handler" title="Permalink 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="method">
|
|||
|
|
<dt id="asyncio.loop.remove_signal_handler">
|
|||
|
|
<code class="descclassname">loop.</code><code class="descname">remove_signal_handler</code><span class="sig-paren">(</span><em>sig</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.remove_signal_handler" title="Permalink 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>
|
|||
|
|
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
|||
|
|
</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>
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="executing-code-in-thread-or-process-pools">
|
|||
|
|
<h3><a class="toc-backref" href="#id14">Executing code in thread or process pools</a><a class="headerlink" href="#executing-code-in-thread-or-process-pools" title="Permalink to this headline">¶</a></h3>
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="asyncio.loop.run_in_executor">
|
|||
|
|
<em class="property">awaitable </em><code class="descclassname">loop.</code><code class="descname">run_in_executor</code><span class="sig-paren">(</span><em>executor</em>, <em>func</em>, <em>*args</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.run_in_executor" title="Permalink 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>.</p>
|
|||
|
|
<p>Example:</p>
|
|||
|
|
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">asyncio</span>
|
|||
|
|
<span class="kn">import</span> <span class="nn">concurrent.futures</span>
|
|||
|
|
|
|||
|
|
<span class="k">def</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="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="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="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>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="method">
|
|||
|
|
<dt id="asyncio.loop.set_default_executor">
|
|||
|
|
<code class="descclassname">loop.</code><code class="descname">set_default_executor</code><span class="sig-paren">(</span><em>executor</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.set_default_executor" title="Permalink 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> should 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="deprecated">
|
|||
|
|
<p><span class="versionmodified deprecated">Deprecated since version 3.7: </span>Using an executor that is not 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> is deprecated and
|
|||
|
|
will trigger an error in Python 3.9.</p>
|
|||
|
|
</div>
|
|||
|
|
<p><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">concurrent.futures.ThreadPoolExecutor</span></code></a>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="error-handling-api">
|
|||
|
|
<h3><a class="toc-backref" href="#id15">Error Handling API</a><a class="headerlink" href="#error-handling-api" title="Permalink to this headline">¶</a></h3>
|
|||
|
|
<p>Allows customizing how exceptions are handled in the event loop.</p>
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="asyncio.loop.set_exception_handler">
|
|||
|
|
<code class="descclassname">loop.</code><code class="descname">set_exception_handler</code><span class="sig-paren">(</span><em>handler</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.set_exception_handler" title="Permalink 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>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="asyncio.loop.get_exception_handler">
|
|||
|
|
<code class="descclassname">loop.</code><code class="descname">get_exception_handler</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.get_exception_handler" title="Permalink 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">New in version 3.5.2.</span></p>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="asyncio.loop.default_exception_handler">
|
|||
|
|
<code class="descclassname">loop.</code><code class="descname">default_exception_handler</code><span class="sig-paren">(</span><em>context</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.default_exception_handler" title="Permalink 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="method">
|
|||
|
|
<dt id="asyncio.loop.call_exception_handler">
|
|||
|
|
<code class="descclassname">loop.</code><code class="descname">call_exception_handler</code><span class="sig-paren">(</span><em>context</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.call_exception_handler" title="Permalink 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>‘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>
|
|||
|
|
</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>
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="enabling-debug-mode">
|
|||
|
|
<h3><a class="toc-backref" href="#id16">Enabling debug mode</a><a class="headerlink" href="#enabling-debug-mode" title="Permalink to this headline">¶</a></h3>
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="asyncio.loop.get_debug">
|
|||
|
|
<code class="descclassname">loop.</code><code class="descname">get_debug</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.get_debug" title="Permalink 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-3"></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="method">
|
|||
|
|
<dt id="asyncio.loop.set_debug">
|
|||
|
|
<code class="descclassname">loop.</code><code class="descname">set_debug</code><span class="sig-paren">(</span><em>enabled: bool</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.set_debug" title="Permalink 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 <code class="docutils literal notranslate"><span class="pre">-X</span> <span class="pre">dev</span></code> command line option can now also be used
|
|||
|
|
to enable the debug mode.</p>
|
|||
|
|
</div>
|
|||
|
|
</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>
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="running-subprocesses">
|
|||
|
|
<h3><a class="toc-backref" href="#id17">Running Subprocesses</a><a class="headerlink" href="#running-subprocesses" title="Permalink to this headline">¶</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>The default asyncio event loop on <strong>Windows</strong> does not support
|
|||
|
|
subprocesses. 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="method">
|
|||
|
|
<dt id="asyncio.loop.subprocess_exec">
|
|||
|
|
<em class="property">coroutine </em><code class="descclassname">loop.</code><code class="descname">subprocess_exec</code><span class="sig-paren">(</span><em>protocol_factory</em>, <em>*args</em>, <em>stdin=subprocess.PIPE</em>, <em>stdout=subprocess.PIPE</em>, <em>stderr=subprocess.PIPE</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.subprocess_exec" title="Permalink 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>: either a file-like object representing a pipe to be
|
|||
|
|
connected to the subprocess’s standard input stream using
|
|||
|
|
<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 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). By default a new
|
|||
|
|
pipe will be created and connected.</p></li>
|
|||
|
|
<li><p><em>stdout</em>: either a file-like object representing the pipe to be
|
|||
|
|
connected to the subprocess’s standard output stream using
|
|||
|
|
<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>, or 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). By default a new pipe
|
|||
|
|
will be created and connected.</p></li>
|
|||
|
|
<li><p><em>stderr</em>: either a file-like object representing the pipe to be
|
|||
|
|
connected to the subprocess’s standard error stream using
|
|||
|
|
<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>, or one of
|
|||
|
|
<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> (default) or <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>
|
|||
|
|
constants.</p>
|
|||
|
|
<p>By default a new pipe will be created and connected. When
|
|||
|
|
<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> is specified, the subprocess’ standard
|
|||
|
|
error stream will be connected to the same pipe as the standard
|
|||
|
|
output stream.</p>
|
|||
|
|
</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>
|
|||
|
|
and <em>shell</em>, which should not be specified at all.</p></li>
|
|||
|
|
</ul>
|
|||
|
|
<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="method">
|
|||
|
|
<dt id="asyncio.loop.subprocess_shell">
|
|||
|
|
<em class="property">coroutine </em><code class="descclassname">loop.</code><code class="descname">subprocess_shell</code><span class="sig-paren">(</span><em>protocol_factory</em>, <em>cmd</em>, <em>*</em>, <em>stdin=subprocess.PIPE</em>, <em>stdout=subprocess.PIPE</em>, <em>stderr=subprocess.PIPE</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.loop.subprocess_shell" title="Permalink 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>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="callback-handles">
|
|||
|
|
<h2>Callback Handles<a class="headerlink" href="#callback-handles" title="Permalink to this headline">¶</a></h2>
|
|||
|
|
<dl class="class">
|
|||
|
|
<dt id="asyncio.Handle">
|
|||
|
|
<em class="property">class </em><code class="descclassname">asyncio.</code><code class="descname">Handle</code><a class="headerlink" href="#asyncio.Handle" title="Permalink 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="method">
|
|||
|
|
<dt id="asyncio.Handle.cancel">
|
|||
|
|
<code class="descname">cancel</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Handle.cancel" title="Permalink 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="method">
|
|||
|
|
<dt id="asyncio.Handle.cancelled">
|
|||
|
|
<code class="descname">cancelled</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Handle.cancelled" title="Permalink 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">New in version 3.7.</span></p>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="class">
|
|||
|
|
<dt id="asyncio.TimerHandle">
|
|||
|
|
<em class="property">class </em><code class="descclassname">asyncio.</code><code class="descname">TimerHandle</code><a class="headerlink" href="#asyncio.TimerHandle" title="Permalink 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="method">
|
|||
|
|
<dt id="asyncio.TimerHandle.when">
|
|||
|
|
<code class="descname">when</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.TimerHandle.when" title="Permalink 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">New in version 3.7.</span></p>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="server-objects">
|
|||
|
|
<h2>Server Objects<a class="headerlink" href="#server-objects" title="Permalink to this headline">¶</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 class directly.</p>
|
|||
|
|
<dl class="class">
|
|||
|
|
<dt id="asyncio.Server">
|
|||
|
|
<em class="property">class </em><code class="descclassname">asyncio.</code><code class="descname">Server</code><a class="headerlink" href="#asyncio.Server" title="Permalink 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>
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="asyncio.Server.close">
|
|||
|
|
<code class="descname">close</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Server.close" title="Permalink 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.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="asyncio.Server.get_loop">
|
|||
|
|
<code class="descname">get_loop</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Server.get_loop" title="Permalink 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">New in version 3.7.</span></p>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="asyncio.Server.start_serving">
|
|||
|
|
<em class="property">coroutine </em><code class="descname">start_serving</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Server.start_serving" title="Permalink 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 being 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">New in version 3.7.</span></p>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="asyncio.Server.serve_forever">
|
|||
|
|
<em class="property">coroutine </em><code class="descname">serve_forever</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Server.serve_forever" title="Permalink 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="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="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">New in version 3.7.</span></p>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="asyncio.Server.is_serving">
|
|||
|
|
<code class="descname">is_serving</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Server.is_serving" title="Permalink 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">New in version 3.7.</span></p>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="asyncio.Server.wait_closed">
|
|||
|
|
<em class="property">coroutine </em><code class="descname">wait_closed</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Server.wait_closed" title="Permalink 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.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="attribute">
|
|||
|
|
<dt id="asyncio.Server.sockets">
|
|||
|
|
<code class="descname">sockets</code><a class="headerlink" href="#asyncio.Server.sockets" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>List of <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> objects the server is listening on,
|
|||
|
|
or <code class="docutils literal notranslate"><span class="pre">None</span></code> if the server is closed.</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>
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="event-loop-implementations">
|
|||
|
|
<span id="asyncio-event-loops"></span><h2>Event Loop Implementations<a class="headerlink" href="#event-loop-implementations" title="Permalink to this headline">¶</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.SelectorEventLoop" title="asyncio.SelectorEventLoop"><code class="xref py py-class docutils literal notranslate"><span class="pre">SelectorEventLoop</span></code></a>
|
|||
|
|
on all platforms.</p>
|
|||
|
|
<dl class="class">
|
|||
|
|
<dt id="asyncio.SelectorEventLoop">
|
|||
|
|
<em class="property">class </em><code class="descclassname">asyncio.</code><code class="descname">SelectorEventLoop</code><a class="headerlink" href="#asyncio.SelectorEventLoop" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>An event loop 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="nn">asyncio</span>
|
|||
|
|
<span class="kn">import</span> <span class="nn">selectors</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="n">loop</span> <span class="o">=</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</span><span class="p">(</span><span class="n">loop</span><span class="p">)</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix, Windows.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="class">
|
|||
|
|
<dt id="asyncio.ProactorEventLoop">
|
|||
|
|
<em class="property">class </em><code class="descclassname">asyncio.</code><code class="descname">ProactorEventLoop</code><a class="headerlink" href="#asyncio.ProactorEventLoop" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>An event loop for Windows that uses “I/O Completion Ports” (IOCP).</p>
|
|||
|
|
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Windows.</p>
|
|||
|
|
<p>An example how to 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> on Windows:</p>
|
|||
|
|
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">asyncio</span>
|
|||
|
|
<span class="kn">import</span> <span class="nn">sys</span>
|
|||
|
|
|
|||
|
|
<span class="k">if</span> <span class="n">sys</span><span class="o">.</span><span class="n">platform</span> <span class="o">==</span> <span class="s1">'win32'</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">ProactorEventLoop</span><span class="p">()</span>
|
|||
|
|
<span class="n">asyncio</span><span class="o">.</span><span class="n">set_event_loop</span><span class="p">(</span><span class="n">loop</span><span class="p">)</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<div class="admonition seealso">
|
|||
|
|
<p class="admonition-title">See also</p>
|
|||
|
|
<p><a class="reference external" href="https://docs.microsoft.com/en-ca/windows/desktop/FileIO/i-o-completion-ports">MSDN documentation on I/O Completion Ports</a>.</p>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="class">
|
|||
|
|
<dt id="asyncio.AbstractEventLoop">
|
|||
|
|
<em class="property">class </em><code class="descclassname">asyncio.</code><code class="descname">AbstractEventLoop</code><a class="headerlink" href="#asyncio.AbstractEventLoop" title="Permalink 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"><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>
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="examples">
|
|||
|
|
<h2>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</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-task.html#asyncio.run" title="asyncio.run"><code class="xref py py-func docutils literal notranslate"><span class="pre">asyncio.run()</span></code></a>.</p>
|
|||
|
|
<div class="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="Permalink to this headline">¶</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="nn">asyncio</span>
|
|||
|
|
|
|||
|
|
<span class="k">def</span> <span class="nf">hello_world</span><span class="p">(</span><span class="n">loop</span><span class="p">):</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">get_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-task.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>
|
|||
|
|
</div>
|
|||
|
|
<div class="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="Permalink to this headline">¶</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="nn">asyncio</span>
|
|||
|
|
<span class="kn">import</span> <span class="nn">datetime</span>
|
|||
|
|
|
|||
|
|
<span class="k">def</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">get_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-task.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>
|
|||
|
|
</div>
|
|||
|
|
<div class="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="Permalink to this headline">¶</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="nn">asyncio</span>
|
|||
|
|
<span class="kn">from</span> <span class="nn">socket</span> <span class="k">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">get_event_loop</span><span class="p">()</span>
|
|||
|
|
|
|||
|
|
<span class="k">def</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>
|
|||
|
|
</div>
|
|||
|
|
<div class="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="Permalink to this headline">¶</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 <code class="xref py py-data docutils literal notranslate"><span class="pre">SIGINT</span></code> and <code class="xref py py-data docutils literal notranslate"><span class="pre">SIGTERM</span></code>
|
|||
|
|
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="nn">asyncio</span>
|
|||
|
|
<span class="kn">import</span> <span class="nn">functools</span>
|
|||
|
|
<span class="kn">import</span> <span class="nn">os</span>
|
|||
|
|
<span class="kn">import</span> <span class="nn">signal</span>
|
|||
|
|
|
|||
|
|
<span class="k">def</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="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="n">f</span><span class="s2">"pid {os.getpid()}: 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>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
|||
|
|
<div class="sphinxsidebarwrapper">
|
|||
|
|
<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>
|
|||
|
|
|
|||
|
|
<h4>Previous topic</h4>
|
|||
|
|
<p class="topless"><a href="asyncio-exceptions.html"
|
|||
|
|
title="previous chapter">Exceptions</a></p>
|
|||
|
|
<h4>Next topic</h4>
|
|||
|
|
<p class="topless"><a href="asyncio-future.html"
|
|||
|
|
title="next chapter">Futures</a></p>
|
|||
|
|
<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/3.7/Doc/library/asyncio-eventloop.rst"
|
|||
|
|
rel="nofollow">Show Source
|
|||
|
|
</a>
|
|||
|
|
</li>
|
|||
|
|
</ul>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<div class="clearer"></div>
|
|||
|
|
</div>
|
|||
|
|
<div class="related" role="navigation" aria-label="related navigation">
|
|||
|
|
<h3>Navigation</h3>
|
|||
|
|
<ul>
|
|||
|
|
<li class="right" style="margin-right: 10px">
|
|||
|
|
<a href="../genindex.html" title="General Index"
|
|||
|
|
>index</a></li>
|
|||
|
|
<li class="right" >
|
|||
|
|
<a href="../py-modindex.html" title="Python Module Index"
|
|||
|
|
>modules</a> |</li>
|
|||
|
|
<li class="right" >
|
|||
|
|
<a href="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.png" alt=""
|
|||
|
|
style="vertical-align: middle; margin-top: -1px"/></li>
|
|||
|
|
<li><a href="https://www.python.org/">Python</a> »</li>
|
|||
|
|
<li>
|
|||
|
|
<span class="language_switcher_placeholder">en</span>
|
|||
|
|
<span class="version_switcher_placeholder">3.7.4</span>
|
|||
|
|
<a href="../index.html">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="right">
|
|||
|
|
|
|||
|
|
|
|||
|
|
<div class="inline-search" style="display: none" role="search">
|
|||
|
|
<form class="inline-search" action="../search.html" method="get">
|
|||
|
|
<input placeholder="Quick search" type="text" name="q" />
|
|||
|
|
<input type="submit" value="Go" />
|
|||
|
|
<input type="hidden" name="check_keywords" value="yes" />
|
|||
|
|
<input type="hidden" name="area" value="default" />
|
|||
|
|
</form>
|
|||
|
|
</div>
|
|||
|
|
<script type="text/javascript">$('.inline-search').show(0);</script>
|
|||
|
|
|
|
|||
|
|
</li>
|
|||
|
|
|
|||
|
|
</ul>
|
|||
|
|
</div>
|
|||
|
|
<div class="footer">
|
|||
|
|
© <a href="../copyright.html">Copyright</a> 2001-2019, Python Software Foundation.
|
|||
|
|
<br />
|
|||
|
|
The Python Software Foundation is a non-profit corporation.
|
|||
|
|
<a href="https://www.python.org/psf/donations/">Please donate.</a>
|
|||
|
|
<br />
|
|||
|
|
Last updated on Jul 13, 2019.
|
|||
|
|
<a href="../bugs.html">Found a bug</a>?
|
|||
|
|
<br />
|
|||
|
|
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.0.1.
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
</body>
|
|||
|
|
</html>
|