1222 lines
106 KiB
HTML
1222 lines
106 KiB
HTML
|
||
<!DOCTYPE html>
|
||
|
||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
<head>
|
||
<meta charset="utf-8" />
|
||
<title>Transports and Protocols — 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="Policies" href="asyncio-policy.html" />
|
||
<link rel="prev" title="Futures" href="asyncio-future.html" />
|
||
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
|
||
<link rel="canonical" href="https://docs.python.org/3/library/asyncio-protocol.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-policy.html" title="Policies"
|
||
accesskey="N">next</a> |</li>
|
||
<li class="right" >
|
||
<a href="asyncio-future.html" title="Futures"
|
||
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="transports-and-protocols">
|
||
<span id="asyncio-transports-protocols"></span><h1>Transports and Protocols<a class="headerlink" href="#transports-and-protocols" title="Permalink to this headline">¶</a></h1>
|
||
<p class="rubric">Preface</p>
|
||
<p>Transports and Protocols are used by the <strong>low-level</strong> event loop
|
||
APIs such as <a class="reference internal" href="asyncio-eventloop.html#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>. They use
|
||
callback-based programming style and enable high-performance
|
||
implementations of network or IPC protocols (e.g. HTTP).</p>
|
||
<p>Essentially, transports and protocols should only be used in
|
||
libraries and frameworks and never in high-level asyncio
|
||
applications.</p>
|
||
<p>This documentation page covers both <a class="reference internal" href="#transports">Transports</a> and <a class="reference internal" href="#protocols">Protocols</a>.</p>
|
||
<p class="rubric">Introduction</p>
|
||
<p>At the highest level, the transport is concerned with <em>how</em> bytes
|
||
are transmitted, while the protocol determines <em>which</em> bytes to
|
||
transmit (and to some extent when).</p>
|
||
<p>A different way of saying the same thing: a transport is an
|
||
abstraction for a socket (or similar I/O endpoint) while a protocol
|
||
is an abstraction for an application, from the transport’s point
|
||
of view.</p>
|
||
<p>Yet another view is the transport and protocol interfaces
|
||
together define an abstract interface for using network I/O and
|
||
interprocess I/O.</p>
|
||
<p>There is always a 1:1 relationship between transport and protocol
|
||
objects: the protocol calls transport methods to send data,
|
||
while the transport calls protocol methods to pass it data that
|
||
has been received.</p>
|
||
<p>Most of connection oriented event loop methods
|
||
(such as <a class="reference internal" href="asyncio-eventloop.html#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>) usually accept a
|
||
<em>protocol_factory</em> argument used to create a <em>Protocol</em> object
|
||
for an accepted connection, represented by a <em>Transport</em> object.
|
||
Such methods usually return a tuple of <code class="docutils literal notranslate"><span class="pre">(transport,</span> <span class="pre">protocol)</span></code>.</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="#transports">Transports</a> section documents asyncio <a class="reference internal" href="#asyncio.BaseTransport" title="asyncio.BaseTransport"><code class="xref py py-class docutils literal notranslate"><span class="pre">BaseTransport</span></code></a>,
|
||
<a class="reference internal" href="#asyncio.ReadTransport" title="asyncio.ReadTransport"><code class="xref py py-class docutils literal notranslate"><span class="pre">ReadTransport</span></code></a>, <a class="reference internal" href="#asyncio.WriteTransport" title="asyncio.WriteTransport"><code class="xref py py-class docutils literal notranslate"><span class="pre">WriteTransport</span></code></a>, <a class="reference internal" href="#asyncio.Transport" title="asyncio.Transport"><code class="xref py py-class docutils literal notranslate"><span class="pre">Transport</span></code></a>,
|
||
<a class="reference internal" href="#asyncio.DatagramTransport" title="asyncio.DatagramTransport"><code class="xref py py-class docutils literal notranslate"><span class="pre">DatagramTransport</span></code></a>, and <a class="reference internal" href="#asyncio.SubprocessTransport" title="asyncio.SubprocessTransport"><code class="xref py py-class docutils literal notranslate"><span class="pre">SubprocessTransport</span></code></a>
|
||
classes.</p></li>
|
||
<li><p>The <a class="reference internal" href="#protocols">Protocols</a> section documents asyncio <a class="reference internal" href="#asyncio.BaseProtocol" title="asyncio.BaseProtocol"><code class="xref py py-class docutils literal notranslate"><span class="pre">BaseProtocol</span></code></a>,
|
||
<a class="reference internal" href="#asyncio.Protocol" title="asyncio.Protocol"><code class="xref py py-class docutils literal notranslate"><span class="pre">Protocol</span></code></a>, <a class="reference internal" href="#asyncio.BufferedProtocol" title="asyncio.BufferedProtocol"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedProtocol</span></code></a>,
|
||
<a class="reference internal" href="#asyncio.DatagramProtocol" title="asyncio.DatagramProtocol"><code class="xref py py-class docutils literal notranslate"><span class="pre">DatagramProtocol</span></code></a>, and <a class="reference internal" href="#asyncio.SubprocessProtocol" title="asyncio.SubprocessProtocol"><code class="xref py py-class docutils literal notranslate"><span class="pre">SubprocessProtocol</span></code></a> classes.</p></li>
|
||
<li><p>The <a class="reference internal" href="#examples">Examples</a> section showcases how to work with transports,
|
||
protocols, and low-level event loop APIs.</p></li>
|
||
</ul>
|
||
<div class="section" id="transports">
|
||
<span id="asyncio-transport"></span><h2>Transports<a class="headerlink" href="#transports" title="Permalink to this headline">¶</a></h2>
|
||
<p>Transports are classes provided by <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> in order to abstract
|
||
various kinds of communication channels.</p>
|
||
<p>Transport objects are always instantiated by an
|
||
<a class="reference internal" href="asyncio-eventloop.html#asyncio-event-loop"><span class="std std-ref">asyncio event loop</span></a>.</p>
|
||
<p>asyncio implements transports for TCP, UDP, SSL, and subprocess pipes.
|
||
The methods available on a transport depend on the transport’s kind.</p>
|
||
<p>The transport classes are <a class="reference internal" href="asyncio-dev.html#asyncio-multithreading"><span class="std std-ref">not thread safe</span></a>.</p>
|
||
<div class="section" id="transports-hierarchy">
|
||
<h3>Transports Hierarchy<a class="headerlink" href="#transports-hierarchy" title="Permalink to this headline">¶</a></h3>
|
||
<dl class="class">
|
||
<dt id="asyncio.BaseTransport">
|
||
<em class="property">class </em><code class="descclassname">asyncio.</code><code class="descname">BaseTransport</code><a class="headerlink" href="#asyncio.BaseTransport" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Base class for all transports. Contains methods that all
|
||
asyncio transports share.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="asyncio.WriteTransport">
|
||
<em class="property">class </em><code class="descclassname">asyncio.</code><code class="descname">WriteTransport</code><span class="sig-paren">(</span><em>BaseTransport</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.WriteTransport" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>A base transport for write-only connections.</p>
|
||
<p>Instances of the <em>WriteTransport</em> class are returned from
|
||
the <a class="reference internal" href="asyncio-eventloop.html#asyncio.loop.connect_write_pipe" title="asyncio.loop.connect_write_pipe"><code class="xref py py-meth docutils literal notranslate"><span class="pre">loop.connect_write_pipe()</span></code></a> event loop method and
|
||
are also used by subprocess-related methods like
|
||
<a class="reference internal" href="asyncio-eventloop.html#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>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="asyncio.ReadTransport">
|
||
<em class="property">class </em><code class="descclassname">asyncio.</code><code class="descname">ReadTransport</code><span class="sig-paren">(</span><em>BaseTransport</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.ReadTransport" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>A base transport for read-only connections.</p>
|
||
<p>Instances of the <em>ReadTransport</em> class are returned from
|
||
the <a class="reference internal" href="asyncio-eventloop.html#asyncio.loop.connect_read_pipe" title="asyncio.loop.connect_read_pipe"><code class="xref py py-meth docutils literal notranslate"><span class="pre">loop.connect_read_pipe()</span></code></a> event loop method and
|
||
are also used by subprocess-related methods like
|
||
<a class="reference internal" href="asyncio-eventloop.html#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>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="asyncio.Transport">
|
||
<em class="property">class </em><code class="descclassname">asyncio.</code><code class="descname">Transport</code><span class="sig-paren">(</span><em>WriteTransport</em>, <em>ReadTransport</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Transport" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Interface representing a bidirectional transport, such as a
|
||
TCP connection.</p>
|
||
<p>The user does not instantiate a transport directly; they call a
|
||
utility function, passing it a protocol factory and other
|
||
information necessary to create the transport and protocol.</p>
|
||
<p>Instances of the <em>Transport</em> class are returned from or used by
|
||
event loop methods like <a class="reference internal" href="asyncio-eventloop.html#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>,
|
||
<a class="reference internal" href="asyncio-eventloop.html#asyncio.loop.create_unix_connection" title="asyncio.loop.create_unix_connection"><code class="xref py py-meth docutils literal notranslate"><span class="pre">loop.create_unix_connection()</span></code></a>,
|
||
<a class="reference internal" href="asyncio-eventloop.html#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-eventloop.html#asyncio.loop.sendfile" title="asyncio.loop.sendfile"><code class="xref py py-meth docutils literal notranslate"><span class="pre">loop.sendfile()</span></code></a>, etc.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="asyncio.DatagramTransport">
|
||
<em class="property">class </em><code class="descclassname">asyncio.</code><code class="descname">DatagramTransport</code><span class="sig-paren">(</span><em>BaseTransport</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.DatagramTransport" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>A transport for datagram (UDP) connections.</p>
|
||
<p>Instances of the <em>DatagramTransport</em> class are returned from
|
||
the <a class="reference internal" href="asyncio-eventloop.html#asyncio.loop.create_datagram_endpoint" title="asyncio.loop.create_datagram_endpoint"><code class="xref py py-meth docutils literal notranslate"><span class="pre">loop.create_datagram_endpoint()</span></code></a> event loop method.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="asyncio.SubprocessTransport">
|
||
<em class="property">class </em><code class="descclassname">asyncio.</code><code class="descname">SubprocessTransport</code><span class="sig-paren">(</span><em>BaseTransport</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.SubprocessTransport" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>An abstraction to represent a connection between a parent and its
|
||
child OS process.</p>
|
||
<p>Instances of the <em>SubprocessTransport</em> class are returned from
|
||
event loop methods <a class="reference internal" href="asyncio-eventloop.html#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> and
|
||
<a class="reference internal" href="asyncio-eventloop.html#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>.</p>
|
||
</dd></dl>
|
||
|
||
</div>
|
||
<div class="section" id="base-transport">
|
||
<h3>Base Transport<a class="headerlink" href="#base-transport" title="Permalink to this headline">¶</a></h3>
|
||
<dl class="method">
|
||
<dt id="asyncio.BaseTransport.close">
|
||
<code class="descclassname">BaseTransport.</code><code class="descname">close</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.BaseTransport.close" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Close the transport.</p>
|
||
<p>If the transport has a buffer for outgoing
|
||
data, buffered data will be flushed asynchronously. No more data
|
||
will be received. After all buffered data is flushed, the
|
||
protocol’s <a class="reference internal" href="#asyncio.BaseProtocol.connection_lost" title="asyncio.BaseProtocol.connection_lost"><code class="xref py py-meth docutils literal notranslate"><span class="pre">protocol.connection_lost()</span></code></a> method will be called with
|
||
<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> as its argument.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="asyncio.BaseTransport.is_closing">
|
||
<code class="descclassname">BaseTransport.</code><code class="descname">is_closing</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.BaseTransport.is_closing" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return <code class="docutils literal notranslate"><span class="pre">True</span></code> if the transport is closing or is closed.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="asyncio.BaseTransport.get_extra_info">
|
||
<code class="descclassname">BaseTransport.</code><code class="descname">get_extra_info</code><span class="sig-paren">(</span><em>name</em>, <em>default=None</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.BaseTransport.get_extra_info" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return information about the transport or underlying resources
|
||
it uses.</p>
|
||
<p><em>name</em> is a string representing the piece of transport-specific
|
||
information to get.</p>
|
||
<p><em>default</em> is the value to return if the information is not
|
||
available, or if the transport does not support querying it
|
||
with the given third-party event loop implementation or on the
|
||
current platform.</p>
|
||
<p>For example, the following code attempts to get the underlying
|
||
socket object of the transport:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">sock</span> <span class="o">=</span> <span class="n">transport</span><span class="o">.</span><span class="n">get_extra_info</span><span class="p">(</span><span class="s1">'socket'</span><span class="p">)</span>
|
||
<span class="k">if</span> <span class="n">sock</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="n">sock</span><span class="o">.</span><span class="n">getsockopt</span><span class="p">(</span><span class="o">...</span><span class="p">))</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Categories of information that can be queried on some transports:</p>
|
||
<ul class="simple">
|
||
<li><p>socket:</p>
|
||
<ul>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">'peername'</span></code>: the remote address to which the socket is
|
||
connected, result of <a class="reference internal" href="socket.html#socket.socket.getpeername" title="socket.socket.getpeername"><code class="xref py py-meth docutils literal notranslate"><span class="pre">socket.socket.getpeername()</span></code></a>
|
||
(<code class="docutils literal notranslate"><span class="pre">None</span></code> on error)</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">'socket'</span></code>: <a class="reference internal" href="socket.html#socket.socket" title="socket.socket"><code class="xref py py-class docutils literal notranslate"><span class="pre">socket.socket</span></code></a> instance</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">'sockname'</span></code>: the socket’s own address,
|
||
result of <a class="reference internal" href="socket.html#socket.socket.getsockname" title="socket.socket.getsockname"><code class="xref py py-meth docutils literal notranslate"><span class="pre">socket.socket.getsockname()</span></code></a></p></li>
|
||
</ul>
|
||
</li>
|
||
<li><p>SSL socket:</p>
|
||
<ul>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">'compression'</span></code>: the compression algorithm being used as a
|
||
string, or <code class="docutils literal notranslate"><span class="pre">None</span></code> if the connection isn’t compressed; result
|
||
of <a class="reference internal" href="ssl.html#ssl.SSLSocket.compression" title="ssl.SSLSocket.compression"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ssl.SSLSocket.compression()</span></code></a></p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">'cipher'</span></code>: a three-value tuple containing the name of the
|
||
cipher being used, the version of the SSL protocol that defines
|
||
its use, and the number of secret bits being used; result of
|
||
<a class="reference internal" href="ssl.html#ssl.SSLSocket.cipher" title="ssl.SSLSocket.cipher"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ssl.SSLSocket.cipher()</span></code></a></p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">'peercert'</span></code>: peer certificate; result of
|
||
<a class="reference internal" href="ssl.html#ssl.SSLSocket.getpeercert" title="ssl.SSLSocket.getpeercert"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ssl.SSLSocket.getpeercert()</span></code></a></p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">'sslcontext'</span></code>: <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> instance</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">'ssl_object'</span></code>: <a class="reference internal" href="ssl.html#ssl.SSLObject" title="ssl.SSLObject"><code class="xref py py-class docutils literal notranslate"><span class="pre">ssl.SSLObject</span></code></a> or
|
||
<a class="reference internal" href="ssl.html#ssl.SSLSocket" title="ssl.SSLSocket"><code class="xref py py-class docutils literal notranslate"><span class="pre">ssl.SSLSocket</span></code></a> instance</p></li>
|
||
</ul>
|
||
</li>
|
||
<li><p>pipe:</p>
|
||
<ul>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">'pipe'</span></code>: pipe object</p></li>
|
||
</ul>
|
||
</li>
|
||
<li><p>subprocess:</p>
|
||
<ul>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">'subprocess'</span></code>: <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> instance</p></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="asyncio.BaseTransport.set_protocol">
|
||
<code class="descclassname">BaseTransport.</code><code class="descname">set_protocol</code><span class="sig-paren">(</span><em>protocol</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.BaseTransport.set_protocol" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Set a new protocol.</p>
|
||
<p>Switching protocol should only be done when both
|
||
protocols are documented to support the switch.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="asyncio.BaseTransport.get_protocol">
|
||
<code class="descclassname">BaseTransport.</code><code class="descname">get_protocol</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.BaseTransport.get_protocol" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return the current protocol.</p>
|
||
</dd></dl>
|
||
|
||
</div>
|
||
<div class="section" id="read-only-transports">
|
||
<h3>Read-only Transports<a class="headerlink" href="#read-only-transports" title="Permalink to this headline">¶</a></h3>
|
||
<dl class="method">
|
||
<dt id="asyncio.ReadTransport.is_reading">
|
||
<code class="descclassname">ReadTransport.</code><code class="descname">is_reading</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.ReadTransport.is_reading" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return <code class="docutils literal notranslate"><span class="pre">True</span></code> if the transport is receiving new data.</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.ReadTransport.pause_reading">
|
||
<code class="descclassname">ReadTransport.</code><code class="descname">pause_reading</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.ReadTransport.pause_reading" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Pause the receiving end of the transport. No data will be passed to
|
||
the protocol’s <a class="reference internal" href="#asyncio.Protocol.data_received" title="asyncio.Protocol.data_received"><code class="xref py py-meth docutils literal notranslate"><span class="pre">protocol.data_received()</span></code></a>
|
||
method until <a class="reference internal" href="#asyncio.ReadTransport.resume_reading" title="asyncio.ReadTransport.resume_reading"><code class="xref py py-meth docutils literal notranslate"><span class="pre">resume_reading()</span></code></a> is called.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.7: </span>The method is idempotent, i.e. it can be called when the
|
||
transport is already paused or closed.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="asyncio.ReadTransport.resume_reading">
|
||
<code class="descclassname">ReadTransport.</code><code class="descname">resume_reading</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.ReadTransport.resume_reading" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Resume the receiving end. The protocol’s
|
||
<a class="reference internal" href="#asyncio.Protocol.data_received" title="asyncio.Protocol.data_received"><code class="xref py py-meth docutils literal notranslate"><span class="pre">protocol.data_received()</span></code></a> method
|
||
will be called once again if some data is available for reading.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.7: </span>The method is idempotent, i.e. it can be called when the
|
||
transport is already reading.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
</div>
|
||
<div class="section" id="write-only-transports">
|
||
<h3>Write-only Transports<a class="headerlink" href="#write-only-transports" title="Permalink to this headline">¶</a></h3>
|
||
<dl class="method">
|
||
<dt id="asyncio.WriteTransport.abort">
|
||
<code class="descclassname">WriteTransport.</code><code class="descname">abort</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.WriteTransport.abort" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Close the transport immediately, without waiting for pending operations
|
||
to complete. Buffered data will be lost. No more data will be received.
|
||
The protocol’s <a class="reference internal" href="#asyncio.BaseProtocol.connection_lost" title="asyncio.BaseProtocol.connection_lost"><code class="xref py py-meth docutils literal notranslate"><span class="pre">protocol.connection_lost()</span></code></a> method will eventually be
|
||
called with <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> as its argument.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="asyncio.WriteTransport.can_write_eof">
|
||
<code class="descclassname">WriteTransport.</code><code class="descname">can_write_eof</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.WriteTransport.can_write_eof" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return <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> if the transport supports
|
||
<a class="reference internal" href="#asyncio.WriteTransport.write_eof" title="asyncio.WriteTransport.write_eof"><code class="xref py py-meth docutils literal notranslate"><span class="pre">write_eof()</span></code></a>, <a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a> if not.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="asyncio.WriteTransport.get_write_buffer_size">
|
||
<code class="descclassname">WriteTransport.</code><code class="descname">get_write_buffer_size</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.WriteTransport.get_write_buffer_size" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return the current size of the output buffer used by the transport.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="asyncio.WriteTransport.get_write_buffer_limits">
|
||
<code class="descclassname">WriteTransport.</code><code class="descname">get_write_buffer_limits</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.WriteTransport.get_write_buffer_limits" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Get the <em>high</em> and <em>low</em> watermarks for write flow control. Return a
|
||
tuple <code class="docutils literal notranslate"><span class="pre">(low,</span> <span class="pre">high)</span></code> where <em>low</em> and <em>high</em> are positive number of
|
||
bytes.</p>
|
||
<p>Use <a class="reference internal" href="#asyncio.WriteTransport.set_write_buffer_limits" title="asyncio.WriteTransport.set_write_buffer_limits"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set_write_buffer_limits()</span></code></a> to set the limits.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.4.2.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="asyncio.WriteTransport.set_write_buffer_limits">
|
||
<code class="descclassname">WriteTransport.</code><code class="descname">set_write_buffer_limits</code><span class="sig-paren">(</span><em>high=None</em>, <em>low=None</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.WriteTransport.set_write_buffer_limits" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Set the <em>high</em> and <em>low</em> watermarks for write flow control.</p>
|
||
<p>These two values (measured in number of
|
||
bytes) control when the protocol’s
|
||
<a class="reference internal" href="#asyncio.BaseProtocol.pause_writing" title="asyncio.BaseProtocol.pause_writing"><code class="xref py py-meth docutils literal notranslate"><span class="pre">protocol.pause_writing()</span></code></a>
|
||
and <a class="reference internal" href="#asyncio.BaseProtocol.resume_writing" title="asyncio.BaseProtocol.resume_writing"><code class="xref py py-meth docutils literal notranslate"><span class="pre">protocol.resume_writing()</span></code></a>
|
||
methods are called. If specified, the low watermark must be less
|
||
than or equal to the high watermark. Neither <em>high</em> nor <em>low</em>
|
||
can be negative.</p>
|
||
<p><a class="reference internal" href="#asyncio.BaseProtocol.pause_writing" title="asyncio.BaseProtocol.pause_writing"><code class="xref py py-meth docutils literal notranslate"><span class="pre">pause_writing()</span></code></a> is called when the buffer size
|
||
becomes greater than or equal to the <em>high</em> value. If writing has
|
||
been paused, <a class="reference internal" href="#asyncio.BaseProtocol.resume_writing" title="asyncio.BaseProtocol.resume_writing"><code class="xref py py-meth docutils literal notranslate"><span class="pre">resume_writing()</span></code></a> is called when
|
||
the buffer size becomes less than or equal to the <em>low</em> value.</p>
|
||
<p>The defaults are implementation-specific. If only the
|
||
high watermark is given, the low watermark defaults to an
|
||
implementation-specific value less than or equal to the
|
||
high watermark. Setting <em>high</em> to zero forces <em>low</em> to zero as
|
||
well, and causes <a class="reference internal" href="#asyncio.BaseProtocol.pause_writing" title="asyncio.BaseProtocol.pause_writing"><code class="xref py py-meth docutils literal notranslate"><span class="pre">pause_writing()</span></code></a> to be called
|
||
whenever the buffer becomes non-empty. Setting <em>low</em> to zero causes
|
||
<a class="reference internal" href="#asyncio.BaseProtocol.resume_writing" title="asyncio.BaseProtocol.resume_writing"><code class="xref py py-meth docutils literal notranslate"><span class="pre">resume_writing()</span></code></a> to be called only once the
|
||
buffer is empty. Use of zero for either limit is generally
|
||
sub-optimal as it reduces opportunities for doing I/O and
|
||
computation concurrently.</p>
|
||
<p>Use <a class="reference internal" href="#asyncio.WriteTransport.get_write_buffer_limits" title="asyncio.WriteTransport.get_write_buffer_limits"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get_write_buffer_limits()</span></code></a>
|
||
to get the limits.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="asyncio.WriteTransport.write">
|
||
<code class="descclassname">WriteTransport.</code><code class="descname">write</code><span class="sig-paren">(</span><em>data</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.WriteTransport.write" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Write some <em>data</em> bytes to the transport.</p>
|
||
<p>This method does not block; it buffers the data and arranges for it
|
||
to be sent out asynchronously.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="asyncio.WriteTransport.writelines">
|
||
<code class="descclassname">WriteTransport.</code><code class="descname">writelines</code><span class="sig-paren">(</span><em>list_of_data</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.WriteTransport.writelines" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Write a list (or any iterable) of data bytes to the transport.
|
||
This is functionally equivalent to calling <a class="reference internal" href="#asyncio.WriteTransport.write" title="asyncio.WriteTransport.write"><code class="xref py py-meth docutils literal notranslate"><span class="pre">write()</span></code></a> on each
|
||
element yielded by the iterable, but may be implemented more
|
||
efficiently.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="asyncio.WriteTransport.write_eof">
|
||
<code class="descclassname">WriteTransport.</code><code class="descname">write_eof</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.WriteTransport.write_eof" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Close the write end of the transport after flushing all buffered data.
|
||
Data may still be received.</p>
|
||
<p>This method can raise <a class="reference internal" href="exceptions.html#NotImplementedError" title="NotImplementedError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">NotImplementedError</span></code></a> if the transport
|
||
(e.g. SSL) doesn’t support half-closed connections.</p>
|
||
</dd></dl>
|
||
|
||
</div>
|
||
<div class="section" id="datagram-transports">
|
||
<h3>Datagram Transports<a class="headerlink" href="#datagram-transports" title="Permalink to this headline">¶</a></h3>
|
||
<dl class="method">
|
||
<dt id="asyncio.DatagramTransport.sendto">
|
||
<code class="descclassname">DatagramTransport.</code><code class="descname">sendto</code><span class="sig-paren">(</span><em>data</em>, <em>addr=None</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.DatagramTransport.sendto" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Send the <em>data</em> bytes to the remote peer given by <em>addr</em> (a
|
||
transport-dependent target address). If <em>addr</em> is <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>,
|
||
the data is sent to the target address given on transport
|
||
creation.</p>
|
||
<p>This method does not block; it buffers the data and arranges
|
||
for it to be sent out asynchronously.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="asyncio.DatagramTransport.abort">
|
||
<code class="descclassname">DatagramTransport.</code><code class="descname">abort</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.DatagramTransport.abort" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Close the transport immediately, without waiting for pending
|
||
operations to complete. Buffered data will be lost.
|
||
No more data will be received. The protocol’s
|
||
<a class="reference internal" href="#asyncio.BaseProtocol.connection_lost" title="asyncio.BaseProtocol.connection_lost"><code class="xref py py-meth docutils literal notranslate"><span class="pre">protocol.connection_lost()</span></code></a>
|
||
method will eventually be called with <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> as its argument.</p>
|
||
</dd></dl>
|
||
|
||
</div>
|
||
<div class="section" id="subprocess-transports">
|
||
<span id="asyncio-subprocess-transports"></span><h3>Subprocess Transports<a class="headerlink" href="#subprocess-transports" title="Permalink to this headline">¶</a></h3>
|
||
<dl class="method">
|
||
<dt id="asyncio.SubprocessTransport.get_pid">
|
||
<code class="descclassname">SubprocessTransport.</code><code class="descname">get_pid</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.SubprocessTransport.get_pid" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return the subprocess process id as an integer.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="asyncio.SubprocessTransport.get_pipe_transport">
|
||
<code class="descclassname">SubprocessTransport.</code><code class="descname">get_pipe_transport</code><span class="sig-paren">(</span><em>fd</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.SubprocessTransport.get_pipe_transport" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return the transport for the communication pipe corresponding to the
|
||
integer file descriptor <em>fd</em>:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">0</span></code>: readable streaming transport of the standard input (<em>stdin</em>),
|
||
or <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> if the subprocess was not created with <code class="docutils literal notranslate"><span class="pre">stdin=PIPE</span></code></p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">1</span></code>: writable streaming transport of the standard output (<em>stdout</em>),
|
||
or <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> if the subprocess was not created with <code class="docutils literal notranslate"><span class="pre">stdout=PIPE</span></code></p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">2</span></code>: writable streaming transport of the standard error (<em>stderr</em>),
|
||
or <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> if the subprocess was not created with <code class="docutils literal notranslate"><span class="pre">stderr=PIPE</span></code></p></li>
|
||
<li><p>other <em>fd</em>: <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>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="asyncio.SubprocessTransport.get_returncode">
|
||
<code class="descclassname">SubprocessTransport.</code><code class="descname">get_returncode</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.SubprocessTransport.get_returncode" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return the subprocess return code as an integer or <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>
|
||
if it hasn’t returned, which is similar to the
|
||
<a class="reference internal" href="subprocess.html#subprocess.Popen.returncode" title="subprocess.Popen.returncode"><code class="xref py py-attr docutils literal notranslate"><span class="pre">subprocess.Popen.returncode</span></code></a> attribute.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="asyncio.SubprocessTransport.kill">
|
||
<code class="descclassname">SubprocessTransport.</code><code class="descname">kill</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.SubprocessTransport.kill" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Kill the subprocess.</p>
|
||
<p>On POSIX systems, the function sends SIGKILL to the subprocess.
|
||
On Windows, this method is an alias for <a class="reference internal" href="#asyncio.SubprocessTransport.terminate" title="asyncio.SubprocessTransport.terminate"><code class="xref py py-meth docutils literal notranslate"><span class="pre">terminate()</span></code></a>.</p>
|
||
<p>See also <a class="reference internal" href="subprocess.html#subprocess.Popen.kill" title="subprocess.Popen.kill"><code class="xref py py-meth docutils literal notranslate"><span class="pre">subprocess.Popen.kill()</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="asyncio.SubprocessTransport.send_signal">
|
||
<code class="descclassname">SubprocessTransport.</code><code class="descname">send_signal</code><span class="sig-paren">(</span><em>signal</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.SubprocessTransport.send_signal" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Send the <em>signal</em> number to the subprocess, as in
|
||
<a class="reference internal" href="subprocess.html#subprocess.Popen.send_signal" title="subprocess.Popen.send_signal"><code class="xref py py-meth docutils literal notranslate"><span class="pre">subprocess.Popen.send_signal()</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="asyncio.SubprocessTransport.terminate">
|
||
<code class="descclassname">SubprocessTransport.</code><code class="descname">terminate</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.SubprocessTransport.terminate" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Stop the subprocess.</p>
|
||
<p>On POSIX systems, this method sends SIGTERM to the subprocess.
|
||
On Windows, the Windows API function TerminateProcess() is called to
|
||
stop the subprocess.</p>
|
||
<p>See also <a class="reference internal" href="subprocess.html#subprocess.Popen.terminate" title="subprocess.Popen.terminate"><code class="xref py py-meth docutils literal notranslate"><span class="pre">subprocess.Popen.terminate()</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="asyncio.SubprocessTransport.close">
|
||
<code class="descclassname">SubprocessTransport.</code><code class="descname">close</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.SubprocessTransport.close" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Kill the subprocess by calling the <a class="reference internal" href="#asyncio.SubprocessTransport.kill" title="asyncio.SubprocessTransport.kill"><code class="xref py py-meth docutils literal notranslate"><span class="pre">kill()</span></code></a> method.</p>
|
||
<p>If the subprocess hasn’t returned yet, and close transports of
|
||
<em>stdin</em>, <em>stdout</em>, and <em>stderr</em> pipes.</p>
|
||
</dd></dl>
|
||
|
||
</div>
|
||
</div>
|
||
<div class="section" id="protocols">
|
||
<span id="asyncio-protocol"></span><h2>Protocols<a class="headerlink" href="#protocols" title="Permalink to this headline">¶</a></h2>
|
||
<p>asyncio provides a set of abstract base classes that should be used
|
||
to implement network protocols. Those classes are meant to be used
|
||
together with <a class="reference internal" href="#asyncio-transport"><span class="std std-ref">transports</span></a>.</p>
|
||
<p>Subclasses of abstract base protocol classes may implement some or
|
||
all methods. All these methods are callbacks: they are called by
|
||
transports on certain events, for example when some data is received.
|
||
A base protocol method should be called by the corresponding transport.</p>
|
||
<div class="section" id="base-protocols">
|
||
<h3>Base Protocols<a class="headerlink" href="#base-protocols" title="Permalink to this headline">¶</a></h3>
|
||
<dl class="class">
|
||
<dt id="asyncio.BaseProtocol">
|
||
<em class="property">class </em><code class="descclassname">asyncio.</code><code class="descname">BaseProtocol</code><a class="headerlink" href="#asyncio.BaseProtocol" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Base protocol with methods that all protocols share.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="asyncio.Protocol">
|
||
<em class="property">class </em><code class="descclassname">asyncio.</code><code class="descname">Protocol</code><span class="sig-paren">(</span><em>BaseProtocol</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Protocol" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>The base class for implementing streaming protocols
|
||
(TCP, Unix sockets, etc).</p>
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="asyncio.BufferedProtocol">
|
||
<em class="property">class </em><code class="descclassname">asyncio.</code><code class="descname">BufferedProtocol</code><span class="sig-paren">(</span><em>BaseProtocol</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.BufferedProtocol" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>A base class for implementing streaming protocols with manual
|
||
control of the receive buffer.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="asyncio.DatagramProtocol">
|
||
<em class="property">class </em><code class="descclassname">asyncio.</code><code class="descname">DatagramProtocol</code><span class="sig-paren">(</span><em>BaseProtocol</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.DatagramProtocol" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>The base class for implementing datagram (UDP) protocols.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="asyncio.SubprocessProtocol">
|
||
<em class="property">class </em><code class="descclassname">asyncio.</code><code class="descname">SubprocessProtocol</code><span class="sig-paren">(</span><em>BaseProtocol</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.SubprocessProtocol" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>The base class for implementing protocols communicating with child
|
||
processes (unidirectional pipes).</p>
|
||
</dd></dl>
|
||
|
||
</div>
|
||
<div class="section" id="base-protocol">
|
||
<h3>Base Protocol<a class="headerlink" href="#base-protocol" title="Permalink to this headline">¶</a></h3>
|
||
<p>All asyncio protocols can implement Base Protocol callbacks.</p>
|
||
<p class="rubric">Connection Callbacks</p>
|
||
<p>Connection callbacks are called on all protocols, exactly once per
|
||
a successful connection. All other protocol callbacks can only be
|
||
called between those two methods.</p>
|
||
<dl class="method">
|
||
<dt id="asyncio.BaseProtocol.connection_made">
|
||
<code class="descclassname">BaseProtocol.</code><code class="descname">connection_made</code><span class="sig-paren">(</span><em>transport</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.BaseProtocol.connection_made" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Called when a connection is made.</p>
|
||
<p>The <em>transport</em> argument is the transport representing the
|
||
connection. The protocol is responsible for storing the reference
|
||
to its transport.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="asyncio.BaseProtocol.connection_lost">
|
||
<code class="descclassname">BaseProtocol.</code><code class="descname">connection_lost</code><span class="sig-paren">(</span><em>exc</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.BaseProtocol.connection_lost" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Called when the connection is lost or closed.</p>
|
||
<p>The argument is either an exception object or <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>.
|
||
The latter means a regular EOF is received, or the connection was
|
||
aborted or closed by this side of the connection.</p>
|
||
</dd></dl>
|
||
|
||
<p class="rubric">Flow Control Callbacks</p>
|
||
<p>Flow control callbacks can be called by transports to pause or
|
||
resume writing performed by the protocol.</p>
|
||
<p>See the documentation of the <a class="reference internal" href="#asyncio.WriteTransport.set_write_buffer_limits" title="asyncio.WriteTransport.set_write_buffer_limits"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set_write_buffer_limits()</span></code></a>
|
||
method for more details.</p>
|
||
<dl class="method">
|
||
<dt id="asyncio.BaseProtocol.pause_writing">
|
||
<code class="descclassname">BaseProtocol.</code><code class="descname">pause_writing</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.BaseProtocol.pause_writing" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Called when the transport’s buffer goes over the high watermark.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="asyncio.BaseProtocol.resume_writing">
|
||
<code class="descclassname">BaseProtocol.</code><code class="descname">resume_writing</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.BaseProtocol.resume_writing" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Called when the transport’s buffer drains below the low watermark.</p>
|
||
</dd></dl>
|
||
|
||
<p>If the buffer size equals the high watermark,
|
||
<a class="reference internal" href="#asyncio.BaseProtocol.pause_writing" title="asyncio.BaseProtocol.pause_writing"><code class="xref py py-meth docutils literal notranslate"><span class="pre">pause_writing()</span></code></a> is not called: the buffer size must
|
||
go strictly over.</p>
|
||
<p>Conversely, <a class="reference internal" href="#asyncio.BaseProtocol.resume_writing" title="asyncio.BaseProtocol.resume_writing"><code class="xref py py-meth docutils literal notranslate"><span class="pre">resume_writing()</span></code></a> is called when the
|
||
buffer size is equal or lower than the low watermark. These end
|
||
conditions are important to ensure that things go as expected when
|
||
either mark is zero.</p>
|
||
</div>
|
||
<div class="section" id="streaming-protocols">
|
||
<h3>Streaming Protocols<a class="headerlink" href="#streaming-protocols" title="Permalink to this headline">¶</a></h3>
|
||
<p>Event methods, such as <a class="reference internal" href="asyncio-eventloop.html#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-eventloop.html#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-eventloop.html#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>,
|
||
<a class="reference internal" href="asyncio-eventloop.html#asyncio.loop.create_unix_connection" title="asyncio.loop.create_unix_connection"><code class="xref py py-meth docutils literal notranslate"><span class="pre">loop.create_unix_connection()</span></code></a>, <a class="reference internal" href="asyncio-eventloop.html#asyncio.loop.connect_accepted_socket" title="asyncio.loop.connect_accepted_socket"><code class="xref py py-meth docutils literal notranslate"><span class="pre">loop.connect_accepted_socket()</span></code></a>,
|
||
<a class="reference internal" href="asyncio-eventloop.html#asyncio.loop.connect_read_pipe" title="asyncio.loop.connect_read_pipe"><code class="xref py py-meth docutils literal notranslate"><span class="pre">loop.connect_read_pipe()</span></code></a>, and <a class="reference internal" href="asyncio-eventloop.html#asyncio.loop.connect_write_pipe" title="asyncio.loop.connect_write_pipe"><code class="xref py py-meth docutils literal notranslate"><span class="pre">loop.connect_write_pipe()</span></code></a>
|
||
accept factories that return streaming protocols.</p>
|
||
<dl class="method">
|
||
<dt id="asyncio.Protocol.data_received">
|
||
<code class="descclassname">Protocol.</code><code class="descname">data_received</code><span class="sig-paren">(</span><em>data</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Protocol.data_received" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Called when some data is received. <em>data</em> is a non-empty bytes
|
||
object containing the incoming data.</p>
|
||
<p>Whether the data is buffered, chunked or reassembled depends on
|
||
the transport. In general, you shouldn’t rely on specific semantics
|
||
and instead make your parsing generic and flexible. However,
|
||
data is always received in the correct order.</p>
|
||
<p>The method can be called an arbitrary number of times while
|
||
a connection is open.</p>
|
||
<p>However, <a class="reference internal" href="#asyncio.Protocol.eof_received" title="asyncio.Protocol.eof_received"><code class="xref py py-meth docutils literal notranslate"><span class="pre">protocol.eof_received()</span></code></a>
|
||
is called at most once. Once <cite>eof_received()</cite> is called,
|
||
<code class="docutils literal notranslate"><span class="pre">data_received()</span></code> is not called anymore.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="asyncio.Protocol.eof_received">
|
||
<code class="descclassname">Protocol.</code><code class="descname">eof_received</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Protocol.eof_received" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Called when the other end signals it won’t send any more data
|
||
(for example by calling <a class="reference internal" href="#asyncio.WriteTransport.write_eof" title="asyncio.WriteTransport.write_eof"><code class="xref py py-meth docutils literal notranslate"><span class="pre">transport.write_eof()</span></code></a>, if the other end also uses
|
||
asyncio).</p>
|
||
<p>This method may return a false value (including <code class="docutils literal notranslate"><span class="pre">None</span></code>), in which case
|
||
the transport will close itself. Conversely, if this method returns a
|
||
true value, the protocol used determines whether to close the transport.
|
||
Since the default implementation returns <code class="docutils literal notranslate"><span class="pre">None</span></code>, it implicitly closes the
|
||
connection.</p>
|
||
<p>Some transports, including SSL, don’t support half-closed connections,
|
||
in which case returning true from this method will result in the connection
|
||
being closed.</p>
|
||
</dd></dl>
|
||
|
||
<p>State machine:</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>start -> connection_made
|
||
[-> data_received]*
|
||
[-> eof_received]?
|
||
-> connection_lost -> end
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="buffered-streaming-protocols">
|
||
<h3>Buffered Streaming Protocols<a class="headerlink" href="#buffered-streaming-protocols" title="Permalink to this headline">¶</a></h3>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.7: </span><strong>Important:</strong> this has been added to asyncio in Python 3.7
|
||
<em>on a provisional basis</em>! This is as an experimental API that
|
||
might be changed or removed completely in Python 3.8.</p>
|
||
</div>
|
||
<p>Buffered Protocols can be used with any event loop method
|
||
that supports <a class="reference internal" href="#streaming-protocols">Streaming Protocols</a>.</p>
|
||
<p><code class="docutils literal notranslate"><span class="pre">BufferedProtocol</span></code> implementations allow explicit manual allocation
|
||
and control of the receive buffer. Event loops can then use the buffer
|
||
provided by the protocol to avoid unnecessary data copies. This
|
||
can result in noticeable performance improvement for protocols that
|
||
receive big amounts of data. Sophisticated protocol implementations
|
||
can significantly reduce the number of buffer allocations.</p>
|
||
<p>The following callbacks are called on <a class="reference internal" href="#asyncio.BufferedProtocol" title="asyncio.BufferedProtocol"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedProtocol</span></code></a>
|
||
instances:</p>
|
||
<dl class="method">
|
||
<dt id="asyncio.BufferedProtocol.get_buffer">
|
||
<code class="descclassname">BufferedProtocol.</code><code class="descname">get_buffer</code><span class="sig-paren">(</span><em>sizehint</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.BufferedProtocol.get_buffer" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Called to allocate a new receive buffer.</p>
|
||
<p><em>sizehint</em> is the recommended minimum size for the returned
|
||
buffer. It is acceptable to return smaller or larger buffers
|
||
than what <em>sizehint</em> suggests. When set to -1, the buffer size
|
||
can be arbitrary. It is an error to return a buffer with a zero size.</p>
|
||
<p><code class="docutils literal notranslate"><span class="pre">get_buffer()</span></code> must return an object implementing the
|
||
<a class="reference internal" href="../c-api/buffer.html#bufferobjects"><span class="std std-ref">buffer protocol</span></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="asyncio.BufferedProtocol.buffer_updated">
|
||
<code class="descclassname">BufferedProtocol.</code><code class="descname">buffer_updated</code><span class="sig-paren">(</span><em>nbytes</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.BufferedProtocol.buffer_updated" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Called when the buffer was updated with the received data.</p>
|
||
<p><em>nbytes</em> is the total number of bytes that were written to the buffer.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="asyncio.BufferedProtocol.eof_received">
|
||
<code class="descclassname">BufferedProtocol.</code><code class="descname">eof_received</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.BufferedProtocol.eof_received" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>See the documentation of the <a class="reference internal" href="#asyncio.Protocol.eof_received" title="asyncio.Protocol.eof_received"><code class="xref py py-meth docutils literal notranslate"><span class="pre">protocol.eof_received()</span></code></a> method.</p>
|
||
</dd></dl>
|
||
|
||
<p><a class="reference internal" href="#asyncio.BufferedProtocol.get_buffer" title="asyncio.BufferedProtocol.get_buffer"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get_buffer()</span></code></a> can be called an arbitrary number
|
||
of times during a connection. However, <a class="reference internal" href="#asyncio.Protocol.eof_received" title="asyncio.Protocol.eof_received"><code class="xref py py-meth docutils literal notranslate"><span class="pre">protocol.eof_received()</span></code></a> is called at most once
|
||
and, if called, <a class="reference internal" href="#asyncio.BufferedProtocol.get_buffer" title="asyncio.BufferedProtocol.get_buffer"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get_buffer()</span></code></a> and
|
||
<a class="reference internal" href="#asyncio.BufferedProtocol.buffer_updated" title="asyncio.BufferedProtocol.buffer_updated"><code class="xref py py-meth docutils literal notranslate"><span class="pre">buffer_updated()</span></code></a> won’t be called after it.</p>
|
||
<p>State machine:</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>start -> connection_made
|
||
[-> get_buffer
|
||
[-> buffer_updated]?
|
||
]*
|
||
[-> eof_received]?
|
||
-> connection_lost -> end
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="datagram-protocols">
|
||
<h3>Datagram Protocols<a class="headerlink" href="#datagram-protocols" title="Permalink to this headline">¶</a></h3>
|
||
<p>Datagram Protocol instances should be constructed by protocol
|
||
factories passed to the <a class="reference internal" href="asyncio-eventloop.html#asyncio.loop.create_datagram_endpoint" title="asyncio.loop.create_datagram_endpoint"><code class="xref py py-meth docutils literal notranslate"><span class="pre">loop.create_datagram_endpoint()</span></code></a> method.</p>
|
||
<dl class="method">
|
||
<dt id="asyncio.DatagramProtocol.datagram_received">
|
||
<code class="descclassname">DatagramProtocol.</code><code class="descname">datagram_received</code><span class="sig-paren">(</span><em>data</em>, <em>addr</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.DatagramProtocol.datagram_received" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Called when a datagram is received. <em>data</em> is a bytes object containing
|
||
the incoming data. <em>addr</em> is the address of the peer sending the data;
|
||
the exact format depends on the transport.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="asyncio.DatagramProtocol.error_received">
|
||
<code class="descclassname">DatagramProtocol.</code><code class="descname">error_received</code><span class="sig-paren">(</span><em>exc</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.DatagramProtocol.error_received" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Called when a previous send or receive operation raises an
|
||
<a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-class docutils literal notranslate"><span class="pre">OSError</span></code></a>. <em>exc</em> is the <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-class docutils literal notranslate"><span class="pre">OSError</span></code></a> instance.</p>
|
||
<p>This method is called in rare conditions, when the transport (e.g. UDP)
|
||
detects that a datagram could not be delivered to its recipient.
|
||
In many conditions though, undeliverable datagrams will be silently
|
||
dropped.</p>
|
||
</dd></dl>
|
||
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>On BSD systems (macOS, FreeBSD, etc.) flow control is not supported
|
||
for datagram protocols, because there is no reliable way to detect send
|
||
failures caused by writing too many packets.</p>
|
||
<p>The socket always appears ‘ready’ and excess packets are dropped. An
|
||
<a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-class docutils literal notranslate"><span class="pre">OSError</span></code></a> with <code class="docutils literal notranslate"><span class="pre">errno</span></code> set to <a class="reference internal" href="errno.html#errno.ENOBUFS" title="errno.ENOBUFS"><code class="xref py py-const docutils literal notranslate"><span class="pre">errno.ENOBUFS</span></code></a> may
|
||
or may not be raised; if it is raised, it will be reported to
|
||
<a class="reference internal" href="#asyncio.DatagramProtocol.error_received" title="asyncio.DatagramProtocol.error_received"><code class="xref py py-meth docutils literal notranslate"><span class="pre">DatagramProtocol.error_received()</span></code></a> but otherwise ignored.</p>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="subprocess-protocols">
|
||
<span id="asyncio-subprocess-protocols"></span><h3>Subprocess Protocols<a class="headerlink" href="#subprocess-protocols" title="Permalink to this headline">¶</a></h3>
|
||
<p>Datagram Protocol instances should be constructed by protocol
|
||
factories passed to the <a class="reference internal" href="asyncio-eventloop.html#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-eventloop.html#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>
|
||
<dl class="method">
|
||
<dt id="asyncio.SubprocessProtocol.pipe_data_received">
|
||
<code class="descclassname">SubprocessProtocol.</code><code class="descname">pipe_data_received</code><span class="sig-paren">(</span><em>fd</em>, <em>data</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.SubprocessProtocol.pipe_data_received" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Called when the child process writes data into its stdout or stderr
|
||
pipe.</p>
|
||
<p><em>fd</em> is the integer file descriptor of the pipe.</p>
|
||
<p><em>data</em> is a non-empty bytes object containing the received data.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="asyncio.SubprocessProtocol.pipe_connection_lost">
|
||
<code class="descclassname">SubprocessProtocol.</code><code class="descname">pipe_connection_lost</code><span class="sig-paren">(</span><em>fd</em>, <em>exc</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.SubprocessProtocol.pipe_connection_lost" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Called when one of the pipes communicating with the child process
|
||
is closed.</p>
|
||
<p><em>fd</em> is the integer file descriptor that was closed.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="asyncio.SubprocessProtocol.process_exited">
|
||
<code class="descclassname">SubprocessProtocol.</code><code class="descname">process_exited</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.SubprocessProtocol.process_exited" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Called when the child process has exited.</p>
|
||
</dd></dl>
|
||
|
||
</div>
|
||
</div>
|
||
<div class="section" id="examples">
|
||
<h2>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h2>
|
||
<div class="section" id="tcp-echo-server">
|
||
<span id="asyncio-example-tcp-echo-server-protocol"></span><h3>TCP Echo Server<a class="headerlink" href="#tcp-echo-server" title="Permalink to this headline">¶</a></h3>
|
||
<p>Create a TCP echo server using the <a class="reference internal" href="asyncio-eventloop.html#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, send back
|
||
received data, and close the connection:</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">class</span> <span class="nc">EchoServerProtocol</span><span class="p">(</span><span class="n">asyncio</span><span class="o">.</span><span class="n">Protocol</span><span class="p">):</span>
|
||
<span class="k">def</span> <span class="nf">connection_made</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">transport</span><span class="p">):</span>
|
||
<span class="n">peername</span> <span class="o">=</span> <span class="n">transport</span><span class="o">.</span><span class="n">get_extra_info</span><span class="p">(</span><span class="s1">'peername'</span><span class="p">)</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="s1">'Connection from </span><span class="si">{}</span><span class="s1">'</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">peername</span><span class="p">))</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">transport</span> <span class="o">=</span> <span class="n">transport</span>
|
||
|
||
<span class="k">def</span> <span class="nf">data_received</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">data</span><span class="p">):</span>
|
||
<span class="n">message</span> <span class="o">=</span> <span class="n">data</span><span class="o">.</span><span class="n">decode</span><span class="p">()</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="s1">'Data received: </span><span class="si">{!r}</span><span class="s1">'</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">message</span><span class="p">))</span>
|
||
|
||
<span class="nb">print</span><span class="p">(</span><span class="s1">'Send: </span><span class="si">{!r}</span><span class="s1">'</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">message</span><span class="p">))</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">transport</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>
|
||
|
||
<span class="nb">print</span><span class="p">(</span><span class="s1">'Close the client socket'</span><span class="p">)</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">transport</span><span class="o">.</span><span class="n">close</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="c1"># Get a reference to the event loop as we plan to use</span>
|
||
<span class="c1"># low-level APIs.</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="n">server</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="k">lambda</span><span class="p">:</span> <span class="n">EchoServerProtocol</span><span class="p">(),</span>
|
||
<span class="s1">'127.0.0.1'</span><span class="p">,</span> <span class="mi">8888</span><span class="p">)</span>
|
||
|
||
<span class="k">async</span> <span class="k">with</span> <span class="n">server</span><span class="p">:</span>
|
||
<span class="k">await</span> <span class="n">server</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>
|
||
</pre></div>
|
||
</div>
|
||
<div class="admonition seealso">
|
||
<p class="admonition-title">See also</p>
|
||
<p>The <a class="reference internal" href="asyncio-stream.html#asyncio-tcp-echo-server-streams"><span class="std std-ref">TCP echo server using streams</span></a>
|
||
example uses the high-level <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">asyncio.start_server()</span></code></a> function.</p>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="tcp-echo-client">
|
||
<span id="asyncio-example-tcp-echo-client-protocol"></span><h3>TCP Echo Client<a class="headerlink" href="#tcp-echo-client" title="Permalink to this headline">¶</a></h3>
|
||
<p>A TCP echo client using the <a class="reference internal" href="asyncio-eventloop.html#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, sends
|
||
data, and waits until the connection is closed:</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">class</span> <span class="nc">EchoClientProtocol</span><span class="p">(</span><span class="n">asyncio</span><span class="o">.</span><span class="n">Protocol</span><span class="p">):</span>
|
||
<span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">message</span><span class="p">,</span> <span class="n">on_con_lost</span><span class="p">,</span> <span class="n">loop</span><span class="p">):</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">message</span> <span class="o">=</span> <span class="n">message</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">loop</span> <span class="o">=</span> <span class="n">loop</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">on_con_lost</span> <span class="o">=</span> <span class="n">on_con_lost</span>
|
||
|
||
<span class="k">def</span> <span class="nf">connection_made</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">transport</span><span class="p">):</span>
|
||
<span class="n">transport</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">message</span><span class="o">.</span><span class="n">encode</span><span class="p">())</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="s1">'Data sent: </span><span class="si">{!r}</span><span class="s1">'</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">message</span><span class="p">))</span>
|
||
|
||
<span class="k">def</span> <span class="nf">data_received</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">data</span><span class="p">):</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="s1">'Data received: </span><span class="si">{!r}</span><span class="s1">'</span><span class="o">.</span><span class="n">format</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="k">def</span> <span class="nf">connection_lost</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">exc</span><span class="p">):</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="s1">'The server closed the connection'</span><span class="p">)</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">on_con_lost</span><span class="o">.</span><span class="n">set_result</span><span class="p">(</span><span class="kc">True</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="c1"># Get a reference to the event loop as we plan to use</span>
|
||
<span class="c1"># low-level APIs.</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="n">on_con_lost</span> <span class="o">=</span> <span class="n">loop</span><span class="o">.</span><span class="n">create_future</span><span class="p">()</span>
|
||
<span class="n">message</span> <span class="o">=</span> <span class="s1">'Hello World!'</span>
|
||
|
||
<span class="n">transport</span><span class="p">,</span> <span class="n">protocol</span> <span class="o">=</span> <span class="k">await</span> <span class="n">loop</span><span class="o">.</span><span class="n">create_connection</span><span class="p">(</span>
|
||
<span class="k">lambda</span><span class="p">:</span> <span class="n">EchoClientProtocol</span><span class="p">(</span><span class="n">message</span><span class="p">,</span> <span class="n">on_con_lost</span><span class="p">,</span> <span class="n">loop</span><span class="p">),</span>
|
||
<span class="s1">'127.0.0.1'</span><span class="p">,</span> <span class="mi">8888</span><span class="p">)</span>
|
||
|
||
<span class="c1"># Wait until the protocol signals that the connection</span>
|
||
<span class="c1"># is lost and close the transport.</span>
|
||
<span class="k">try</span><span class="p">:</span>
|
||
<span class="k">await</span> <span class="n">on_con_lost</span>
|
||
<span class="k">finally</span><span class="p">:</span>
|
||
<span class="n">transport</span><span class="o">.</span><span class="n">close</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 class="admonition seealso">
|
||
<p class="admonition-title">See also</p>
|
||
<p>The <a class="reference internal" href="asyncio-stream.html#asyncio-tcp-echo-client-streams"><span class="std std-ref">TCP echo client using streams</span></a>
|
||
example uses 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.</p>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="udp-echo-server">
|
||
<span id="asyncio-udp-echo-server-protocol"></span><h3>UDP Echo Server<a class="headerlink" href="#udp-echo-server" title="Permalink to this headline">¶</a></h3>
|
||
<p>A UDP echo server, using the <a class="reference internal" href="asyncio-eventloop.html#asyncio.loop.create_datagram_endpoint" title="asyncio.loop.create_datagram_endpoint"><code class="xref py py-meth docutils literal notranslate"><span class="pre">loop.create_datagram_endpoint()</span></code></a>
|
||
method, sends back received data:</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">class</span> <span class="nc">EchoServerProtocol</span><span class="p">:</span>
|
||
<span class="k">def</span> <span class="nf">connection_made</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">transport</span><span class="p">):</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">transport</span> <span class="o">=</span> <span class="n">transport</span>
|
||
|
||
<span class="k">def</span> <span class="nf">datagram_received</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">data</span><span class="p">,</span> <span class="n">addr</span><span class="p">):</span>
|
||
<span class="n">message</span> <span class="o">=</span> <span class="n">data</span><span class="o">.</span><span class="n">decode</span><span class="p">()</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="s1">'Received </span><span class="si">%r</span><span class="s1"> from </span><span class="si">%s</span><span class="s1">'</span> <span class="o">%</span> <span class="p">(</span><span class="n">message</span><span class="p">,</span> <span class="n">addr</span><span class="p">))</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="s1">'Send </span><span class="si">%r</span><span class="s1"> to </span><span class="si">%s</span><span class="s1">'</span> <span class="o">%</span> <span class="p">(</span><span class="n">message</span><span class="p">,</span> <span class="n">addr</span><span class="p">))</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">transport</span><span class="o">.</span><span class="n">sendto</span><span class="p">(</span><span class="n">data</span><span class="p">,</span> <span class="n">addr</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="nb">print</span><span class="p">(</span><span class="s2">"Starting UDP server"</span><span class="p">)</span>
|
||
|
||
<span class="c1"># Get a reference to the event loop as we plan to use</span>
|
||
<span class="c1"># low-level APIs.</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"># One protocol instance will be created to serve all</span>
|
||
<span class="c1"># client requests.</span>
|
||
<span class="n">transport</span><span class="p">,</span> <span class="n">protocol</span> <span class="o">=</span> <span class="k">await</span> <span class="n">loop</span><span class="o">.</span><span class="n">create_datagram_endpoint</span><span class="p">(</span>
|
||
<span class="k">lambda</span><span class="p">:</span> <span class="n">EchoServerProtocol</span><span class="p">(),</span>
|
||
<span class="n">local_addr</span><span class="o">=</span><span class="p">(</span><span class="s1">'127.0.0.1'</span><span class="p">,</span> <span class="mi">9999</span><span class="p">))</span>
|
||
|
||
<span class="k">try</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="c1"># Serve for 1 hour.</span>
|
||
<span class="k">finally</span><span class="p">:</span>
|
||
<span class="n">transport</span><span class="o">.</span><span class="n">close</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 class="section" id="udp-echo-client">
|
||
<span id="asyncio-udp-echo-client-protocol"></span><h3>UDP Echo Client<a class="headerlink" href="#udp-echo-client" title="Permalink to this headline">¶</a></h3>
|
||
<p>A UDP echo client, using the <a class="reference internal" href="asyncio-eventloop.html#asyncio.loop.create_datagram_endpoint" title="asyncio.loop.create_datagram_endpoint"><code class="xref py py-meth docutils literal notranslate"><span class="pre">loop.create_datagram_endpoint()</span></code></a>
|
||
method, sends data and closes the transport when it receives the answer:</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">class</span> <span class="nc">EchoClientProtocol</span><span class="p">:</span>
|
||
<span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">message</span><span class="p">,</span> <span class="n">loop</span><span class="p">):</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">message</span> <span class="o">=</span> <span class="n">message</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">loop</span> <span class="o">=</span> <span class="n">loop</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">transport</span> <span class="o">=</span> <span class="kc">None</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">on_con_lost</span> <span class="o">=</span> <span class="n">loop</span><span class="o">.</span><span class="n">create_future</span><span class="p">()</span>
|
||
|
||
<span class="k">def</span> <span class="nf">connection_made</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">transport</span><span class="p">):</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">transport</span> <span class="o">=</span> <span class="n">transport</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="s1">'Send:'</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">message</span><span class="p">)</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">transport</span><span class="o">.</span><span class="n">sendto</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">message</span><span class="o">.</span><span class="n">encode</span><span class="p">())</span>
|
||
|
||
<span class="k">def</span> <span class="nf">datagram_received</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">data</span><span class="p">,</span> <span class="n">addr</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="nb">print</span><span class="p">(</span><span class="s2">"Close the socket"</span><span class="p">)</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">transport</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
|
||
|
||
<span class="k">def</span> <span class="nf">error_received</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">exc</span><span class="p">):</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="s1">'Error received:'</span><span class="p">,</span> <span class="n">exc</span><span class="p">)</span>
|
||
|
||
<span class="k">def</span> <span class="nf">connection_lost</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">exc</span><span class="p">):</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="s2">"Connection closed"</span><span class="p">)</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">on_con_lost</span><span class="o">.</span><span class="n">set_result</span><span class="p">(</span><span class="kc">True</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="c1"># Get a reference to the event loop as we plan to use</span>
|
||
<span class="c1"># low-level APIs.</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="n">message</span> <span class="o">=</span> <span class="s2">"Hello World!"</span>
|
||
<span class="n">transport</span><span class="p">,</span> <span class="n">protocol</span> <span class="o">=</span> <span class="k">await</span> <span class="n">loop</span><span class="o">.</span><span class="n">create_datagram_endpoint</span><span class="p">(</span>
|
||
<span class="k">lambda</span><span class="p">:</span> <span class="n">EchoClientProtocol</span><span class="p">(</span><span class="n">message</span><span class="p">,</span> <span class="n">loop</span><span class="p">),</span>
|
||
<span class="n">remote_addr</span><span class="o">=</span><span class="p">(</span><span class="s1">'127.0.0.1'</span><span class="p">,</span> <span class="mi">9999</span><span class="p">))</span>
|
||
|
||
<span class="k">try</span><span class="p">:</span>
|
||
<span class="k">await</span> <span class="n">protocol</span><span class="o">.</span><span class="n">on_con_lost</span>
|
||
<span class="k">finally</span><span class="p">:</span>
|
||
<span class="n">transport</span><span class="o">.</span><span class="n">close</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 class="section" id="connecting-existing-sockets">
|
||
<span id="asyncio-example-create-connection"></span><h3>Connecting Existing Sockets<a class="headerlink" href="#connecting-existing-sockets" title="Permalink to this headline">¶</a></h3>
|
||
<p>Wait until a socket receives data using the
|
||
<a class="reference internal" href="asyncio-eventloop.html#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 with a protocol:</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">socket</span>
|
||
|
||
|
||
<span class="k">class</span> <span class="nc">MyProtocol</span><span class="p">(</span><span class="n">asyncio</span><span class="o">.</span><span class="n">Protocol</span><span class="p">):</span>
|
||
|
||
<span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">loop</span><span class="p">):</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">transport</span> <span class="o">=</span> <span class="kc">None</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">on_con_lost</span> <span class="o">=</span> <span class="n">loop</span><span class="o">.</span><span class="n">create_future</span><span class="p">()</span>
|
||
|
||
<span class="k">def</span> <span class="nf">connection_made</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">transport</span><span class="p">):</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">transport</span> <span class="o">=</span> <span class="n">transport</span>
|
||
|
||
<span class="k">def</span> <span class="nf">data_received</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">data</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: close the transport;</span>
|
||
<span class="c1"># connection_lost() will be called automatically.</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">transport</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
|
||
|
||
<span class="k">def</span> <span class="nf">connection_lost</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">exc</span><span class="p">):</span>
|
||
<span class="c1"># The socket has been closed</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">on_con_lost</span><span class="o">.</span><span class="n">set_result</span><span class="p">(</span><span class="kc">True</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="c1"># Get a reference to the event loop as we plan to use</span>
|
||
<span class="c1"># low-level APIs.</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"># Create a pair of connected sockets</span>
|
||
<span class="n">rsock</span><span class="p">,</span> <span class="n">wsock</span> <span class="o">=</span> <span class="n">socket</span><span class="o">.</span><span class="n">socketpair</span><span class="p">()</span>
|
||
|
||
<span class="c1"># Register the socket to wait for data.</span>
|
||
<span class="n">transport</span><span class="p">,</span> <span class="n">protocol</span> <span class="o">=</span> <span class="k">await</span> <span class="n">loop</span><span class="o">.</span><span class="n">create_connection</span><span class="p">(</span>
|
||
<span class="k">lambda</span><span class="p">:</span> <span class="n">MyProtocol</span><span class="p">(</span><span class="n">loop</span><span class="p">),</span> <span class="n">sock</span><span class="o">=</span><span class="n">rsock</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="k">await</span> <span class="n">protocol</span><span class="o">.</span><span class="n">on_con_lost</span>
|
||
<span class="k">finally</span><span class="p">:</span>
|
||
<span class="n">transport</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">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 class="admonition seealso">
|
||
<p class="admonition-title">See also</p>
|
||
<p>The <a class="reference internal" href="asyncio-eventloop.html#asyncio-example-watch-fd"><span class="std std-ref">watch a file descriptor for read events</span></a> example uses the low-level
|
||
<a class="reference internal" href="asyncio-eventloop.html#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 to register an FD.</p>
|
||
<p>The <a class="reference internal" href="asyncio-stream.html#asyncio-example-create-connection-streams"><span class="std std-ref">register an open socket to wait for data using streams</span></a> example uses high-level streams
|
||
created by 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 in a coroutine.</p>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="loop-subprocess-exec-and-subprocessprotocol">
|
||
<span id="asyncio-example-subprocess-proto"></span><h3>loop.subprocess_exec() and SubprocessProtocol<a class="headerlink" href="#loop-subprocess-exec-and-subprocessprotocol" title="Permalink to this headline">¶</a></h3>
|
||
<p>An example of a subprocess protocol used to get the output of a
|
||
subprocess and to wait for the subprocess exit.</p>
|
||
<p>The subprocess is created by th <a class="reference internal" href="asyncio-eventloop.html#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> 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">sys</span>
|
||
|
||
<span class="k">class</span> <span class="nc">DateProtocol</span><span class="p">(</span><span class="n">asyncio</span><span class="o">.</span><span class="n">SubprocessProtocol</span><span class="p">):</span>
|
||
<span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">exit_future</span><span class="p">):</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">exit_future</span> <span class="o">=</span> <span class="n">exit_future</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">output</span> <span class="o">=</span> <span class="nb">bytearray</span><span class="p">()</span>
|
||
|
||
<span class="k">def</span> <span class="nf">pipe_data_received</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">fd</span><span class="p">,</span> <span class="n">data</span><span class="p">):</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">output</span><span class="o">.</span><span class="n">extend</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>
|
||
|
||
<span class="k">def</span> <span class="nf">process_exited</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">exit_future</span><span class="o">.</span><span class="n">set_result</span><span class="p">(</span><span class="kc">True</span><span class="p">)</span>
|
||
|
||
<span class="k">async</span> <span class="k">def</span> <span class="nf">get_date</span><span class="p">():</span>
|
||
<span class="c1"># Get a reference to the event loop as we plan to use</span>
|
||
<span class="c1"># low-level APIs.</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="n">code</span> <span class="o">=</span> <span class="s1">'import datetime; print(datetime.datetime.now())'</span>
|
||
<span class="n">exit_future</span> <span class="o">=</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">Future</span><span class="p">(</span><span class="n">loop</span><span class="o">=</span><span class="n">loop</span><span class="p">)</span>
|
||
|
||
<span class="c1"># Create the subprocess controlled by DateProtocol;</span>
|
||
<span class="c1"># redirect the standard output into a pipe.</span>
|
||
<span class="n">transport</span><span class="p">,</span> <span class="n">protocol</span> <span class="o">=</span> <span class="k">await</span> <span class="n">loop</span><span class="o">.</span><span class="n">subprocess_exec</span><span class="p">(</span>
|
||
<span class="k">lambda</span><span class="p">:</span> <span class="n">DateProtocol</span><span class="p">(</span><span class="n">exit_future</span><span class="p">),</span>
|
||
<span class="n">sys</span><span class="o">.</span><span class="n">executable</span><span class="p">,</span> <span class="s1">'-c'</span><span class="p">,</span> <span class="n">code</span><span class="p">,</span>
|
||
<span class="n">stdin</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">stderr</span><span class="o">=</span><span class="kc">None</span><span class="p">)</span>
|
||
|
||
<span class="c1"># Wait for the subprocess exit using the process_exited()</span>
|
||
<span class="c1"># method of the protocol.</span>
|
||
<span class="k">await</span> <span class="n">exit_future</span>
|
||
|
||
<span class="c1"># Close the stdout pipe.</span>
|
||
<span class="n">transport</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
|
||
|
||
<span class="c1"># Read the output which was collected by the</span>
|
||
<span class="c1"># pipe_data_received() method of the protocol.</span>
|
||
<span class="n">data</span> <span class="o">=</span> <span class="nb">bytes</span><span class="p">(</span><span class="n">protocol</span><span class="o">.</span><span class="n">output</span><span class="p">)</span>
|
||
<span class="k">return</span> <span class="n">data</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s1">'ascii'</span><span class="p">)</span><span class="o">.</span><span class="n">rstrip</span><span class="p">()</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="s2">"win32"</span><span class="p">:</span>
|
||
<span class="n">asyncio</span><span class="o">.</span><span class="n">set_event_loop_policy</span><span class="p">(</span>
|
||
<span class="n">asyncio</span><span class="o">.</span><span class="n">WindowsProactorEventLoopPolicy</span><span class="p">())</span>
|
||
|
||
<span class="n">date</span> <span class="o">=</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">get_date</span><span class="p">())</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="s2">"Current date: </span><span class="si">{date}</span><span class="s2">"</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>See also the <a class="reference internal" href="asyncio-subprocess.html#asyncio-example-create-subprocess-exec"><span class="std std-ref">same example</span></a>
|
||
written using high-level APIs.</p>
|
||
</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="#">Transports and Protocols</a><ul>
|
||
<li><a class="reference internal" href="#transports">Transports</a><ul>
|
||
<li><a class="reference internal" href="#transports-hierarchy">Transports Hierarchy</a></li>
|
||
<li><a class="reference internal" href="#base-transport">Base Transport</a></li>
|
||
<li><a class="reference internal" href="#read-only-transports">Read-only Transports</a></li>
|
||
<li><a class="reference internal" href="#write-only-transports">Write-only Transports</a></li>
|
||
<li><a class="reference internal" href="#datagram-transports">Datagram Transports</a></li>
|
||
<li><a class="reference internal" href="#subprocess-transports">Subprocess Transports</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#protocols">Protocols</a><ul>
|
||
<li><a class="reference internal" href="#base-protocols">Base Protocols</a></li>
|
||
<li><a class="reference internal" href="#base-protocol">Base Protocol</a></li>
|
||
<li><a class="reference internal" href="#streaming-protocols">Streaming Protocols</a></li>
|
||
<li><a class="reference internal" href="#buffered-streaming-protocols">Buffered Streaming Protocols</a></li>
|
||
<li><a class="reference internal" href="#datagram-protocols">Datagram Protocols</a></li>
|
||
<li><a class="reference internal" href="#subprocess-protocols">Subprocess Protocols</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#examples">Examples</a><ul>
|
||
<li><a class="reference internal" href="#tcp-echo-server">TCP Echo Server</a></li>
|
||
<li><a class="reference internal" href="#tcp-echo-client">TCP Echo Client</a></li>
|
||
<li><a class="reference internal" href="#udp-echo-server">UDP Echo Server</a></li>
|
||
<li><a class="reference internal" href="#udp-echo-client">UDP Echo Client</a></li>
|
||
<li><a class="reference internal" href="#connecting-existing-sockets">Connecting Existing Sockets</a></li>
|
||
<li><a class="reference internal" href="#loop-subprocess-exec-and-subprocessprotocol">loop.subprocess_exec() and SubprocessProtocol</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
<h4>Previous topic</h4>
|
||
<p class="topless"><a href="asyncio-future.html"
|
||
title="previous chapter">Futures</a></p>
|
||
<h4>Next topic</h4>
|
||
<p class="topless"><a href="asyncio-policy.html"
|
||
title="next chapter">Policies</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-protocol.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-policy.html" title="Policies"
|
||
>next</a> |</li>
|
||
<li class="right" >
|
||
<a href="asyncio-future.html" title="Futures"
|
||
>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> |