530 lines
42 KiB
HTML
530 lines
42 KiB
HTML
|
||
<!DOCTYPE html>
|
||
|
||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
<head>
|
||
<meta charset="utf-8" />
|
||
<title>Subprocesses — 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="Queues" href="asyncio-queue.html" />
|
||
<link rel="prev" title="Synchronization Primitives" href="asyncio-sync.html" />
|
||
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
|
||
<link rel="canonical" href="https://docs.python.org/3/library/asyncio-subprocess.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-queue.html" title="Queues"
|
||
accesskey="N">next</a> |</li>
|
||
<li class="right" >
|
||
<a href="asyncio-sync.html" title="Synchronization Primitives"
|
||
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="subprocesses">
|
||
<span id="asyncio-subprocess"></span><h1>Subprocesses<a class="headerlink" href="#subprocesses" title="Permalink to this headline">¶</a></h1>
|
||
<p>This section describes high-level async/await asyncio APIs to
|
||
create and manage subprocesses.</p>
|
||
<p id="asyncio-example-subprocess-shell">Here’s an example of how asyncio can run a shell command and
|
||
obtain its result:</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">async</span> <span class="k">def</span> <span class="nf">run</span><span class="p">(</span><span class="n">cmd</span><span class="p">):</span>
|
||
<span class="n">proc</span> <span class="o">=</span> <span class="k">await</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">create_subprocess_shell</span><span class="p">(</span>
|
||
<span class="n">cmd</span><span class="p">,</span>
|
||
<span class="n">stdout</span><span class="o">=</span><span class="n">asyncio</span><span class="o">.</span><span class="n">subprocess</span><span class="o">.</span><span class="n">PIPE</span><span class="p">,</span>
|
||
<span class="n">stderr</span><span class="o">=</span><span class="n">asyncio</span><span class="o">.</span><span class="n">subprocess</span><span class="o">.</span><span class="n">PIPE</span><span class="p">)</span>
|
||
|
||
<span class="n">stdout</span><span class="p">,</span> <span class="n">stderr</span> <span class="o">=</span> <span class="k">await</span> <span class="n">proc</span><span class="o">.</span><span class="n">communicate</span><span class="p">()</span>
|
||
|
||
<span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="s1">'[</span><span class="si">{cmd!r}</span><span class="s1"> exited with </span><span class="si">{proc.returncode}</span><span class="s1">]'</span><span class="p">)</span>
|
||
<span class="k">if</span> <span class="n">stdout</span><span class="p">:</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="s1">'[stdout]</span><span class="se">\n</span><span class="s1">{stdout.decode()}'</span><span class="p">)</span>
|
||
<span class="k">if</span> <span class="n">stderr</span><span class="p">:</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="s1">'[stderr]</span><span class="se">\n</span><span class="s1">{stderr.decode()}'</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">run</span><span class="p">(</span><span class="s1">'ls /zzz'</span><span class="p">))</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>will print:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="p">[</span><span class="s1">'ls /zzz'</span> <span class="n">exited</span> <span class="k">with</span> <span class="mi">1</span><span class="p">]</span>
|
||
<span class="p">[</span><span class="n">stderr</span><span class="p">]</span>
|
||
<span class="n">ls</span><span class="p">:</span> <span class="o">/</span><span class="n">zzz</span><span class="p">:</span> <span class="n">No</span> <span class="n">such</span> <span class="n">file</span> <span class="ow">or</span> <span class="n">directory</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Because all asyncio subprocess functions are asynchronous and asyncio
|
||
provides many tools to work with such functions, it is easy to execute
|
||
and monitor multiple subprocesses in parallel. It is indeed trivial
|
||
to modify the above example to run several commands simultaneously:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">async</span> <span class="k">def</span> <span class="nf">main</span><span class="p">():</span>
|
||
<span class="k">await</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">gather</span><span class="p">(</span>
|
||
<span class="n">run</span><span class="p">(</span><span class="s1">'ls /zzz'</span><span class="p">),</span>
|
||
<span class="n">run</span><span class="p">(</span><span class="s1">'sleep 1; echo "hello"'</span><span class="p">))</span>
|
||
|
||
<span class="n">asyncio</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">main</span><span class="p">())</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>See also the <a class="reference internal" href="#examples">Examples</a> subsection.</p>
|
||
<div class="section" id="creating-subprocesses">
|
||
<h2>Creating Subprocesses<a class="headerlink" href="#creating-subprocesses" title="Permalink to this headline">¶</a></h2>
|
||
<dl class="function">
|
||
<dt id="asyncio.create_subprocess_exec">
|
||
<em class="property">coroutine </em><code class="descclassname">asyncio.</code><code class="descname">create_subprocess_exec</code><span class="sig-paren">(</span><em>program</em>, <em>*args</em>, <em>stdin=None</em>, <em>stdout=None</em>, <em>stderr=None</em>, <em>loop=None</em>, <em>limit=None</em>, <em>**kwds</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.create_subprocess_exec" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Create a subprocess.</p>
|
||
<p>The <em>limit</em> argument sets the buffer limit for <a class="reference internal" href="asyncio-stream.html#asyncio.StreamReader" title="asyncio.StreamReader"><code class="xref py py-class docutils literal notranslate"><span class="pre">StreamReader</span></code></a>
|
||
wrappers for <code class="xref py py-attr docutils literal notranslate"><span class="pre">Process.stdout</span></code> and <code class="xref py py-attr docutils literal notranslate"><span class="pre">Process.stderr</span></code>
|
||
(if <a class="reference internal" href="subprocess.html#subprocess.PIPE" title="subprocess.PIPE"><code class="xref py py-attr docutils literal notranslate"><span class="pre">subprocess.PIPE</span></code></a> is passed to <em>stdout</em> and <em>stderr</em> arguments).</p>
|
||
<p>Return a <a class="reference internal" href="#asyncio.asyncio.subprocess.Process" title="asyncio.asyncio.subprocess.Process"><code class="xref py py-class docutils literal notranslate"><span class="pre">Process</span></code></a> instance.</p>
|
||
<p>See the documentation of <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> for other
|
||
parameters.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="asyncio.create_subprocess_shell">
|
||
<em class="property">coroutine </em><code class="descclassname">asyncio.</code><code class="descname">create_subprocess_shell</code><span class="sig-paren">(</span><em>cmd</em>, <em>stdin=None</em>, <em>stdout=None</em>, <em>stderr=None</em>, <em>loop=None</em>, <em>limit=None</em>, <em>**kwds</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.create_subprocess_shell" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Run the <em>cmd</em> shell command.</p>
|
||
<p>The <em>limit</em> argument sets the buffer limit for <a class="reference internal" href="asyncio-stream.html#asyncio.StreamReader" title="asyncio.StreamReader"><code class="xref py py-class docutils literal notranslate"><span class="pre">StreamReader</span></code></a>
|
||
wrappers for <code class="xref py py-attr docutils literal notranslate"><span class="pre">Process.stdout</span></code> and <code class="xref py py-attr docutils literal notranslate"><span class="pre">Process.stderr</span></code>
|
||
(if <a class="reference internal" href="subprocess.html#subprocess.PIPE" title="subprocess.PIPE"><code class="xref py py-attr docutils literal notranslate"><span class="pre">subprocess.PIPE</span></code></a> is passed to <em>stdout</em> and <em>stderr</em> arguments).</p>
|
||
<p>Return a <a class="reference internal" href="#asyncio.asyncio.subprocess.Process" title="asyncio.asyncio.subprocess.Process"><code class="xref py py-class docutils literal notranslate"><span class="pre">Process</span></code></a> instance.</p>
|
||
<p>See the documentation of <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> for other
|
||
parameters.</p>
|
||
</dd></dl>
|
||
|
||
<div class="admonition important">
|
||
<p class="admonition-title">Important</p>
|
||
<p>It is the application’s responsibility to ensure that all whitespace and
|
||
special characters are quoted appropriately to avoid <a class="reference external" href="https://en.wikipedia.org/wiki/Shell_injection#Shell_injection">shell injection</a>
|
||
vulnerabilities. The <a class="reference internal" href="shlex.html#shlex.quote" title="shlex.quote"><code class="xref py py-func docutils literal notranslate"><span class="pre">shlex.quote()</span></code></a> function can be used to properly
|
||
escape whitespace and special shell characters in strings that are going
|
||
to be used to construct shell commands.</p>
|
||
</div>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>The default asyncio event loop implementation on <strong>Windows</strong> does not
|
||
support subprocesses. Subprocesses are available for Windows if a
|
||
<a class="reference internal" href="asyncio-eventloop.html#asyncio.ProactorEventLoop" title="asyncio.ProactorEventLoop"><code class="xref py py-class docutils literal notranslate"><span class="pre">ProactorEventLoop</span></code></a> is used.
|
||
See <a class="reference internal" href="asyncio-platforms.html#asyncio-windows-subprocess"><span class="std std-ref">Subprocess Support on Windows</span></a>
|
||
for details.</p>
|
||
</div>
|
||
<div class="admonition seealso">
|
||
<p class="admonition-title">See also</p>
|
||
<p>asyncio also has the following <em>low-level</em> APIs to work with subprocesses:
|
||
<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>, <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>,
|
||
<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>, <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>,
|
||
as well as the <a class="reference internal" href="asyncio-protocol.html#asyncio-subprocess-transports"><span class="std std-ref">Subprocess Transports</span></a>
|
||
and <a class="reference internal" href="asyncio-protocol.html#asyncio-subprocess-protocols"><span class="std std-ref">Subprocess Protocols</span></a>.</p>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="constants">
|
||
<h2>Constants<a class="headerlink" href="#constants" title="Permalink to this headline">¶</a></h2>
|
||
<dl class="data">
|
||
<dt id="asyncio.asyncio.subprocess.PIPE">
|
||
<code class="descclassname">asyncio.subprocess.</code><code class="descname">PIPE</code><a class="headerlink" href="#asyncio.asyncio.subprocess.PIPE" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Can be passed to the <em>stdin</em>, <em>stdout</em> or <em>stderr</em> parameters.</p>
|
||
<p>If <em>PIPE</em> is passed to <em>stdin</em> argument, the
|
||
<a class="reference internal" href="#asyncio.asyncio.subprocess.Process.stdin" title="asyncio.asyncio.subprocess.Process.stdin"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Process.stdin</span></code></a> attribute
|
||
will point to a <a class="reference internal" href="asyncio-stream.html#asyncio.StreamWriter" title="asyncio.StreamWriter"><code class="xref py py-class docutils literal notranslate"><span class="pre">StreamWriter</span></code></a> instance.</p>
|
||
<p>If <em>PIPE</em> is passed to <em>stdout</em> or <em>stderr</em> arguments, the
|
||
<a class="reference internal" href="#asyncio.asyncio.subprocess.Process.stdout" title="asyncio.asyncio.subprocess.Process.stdout"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Process.stdout</span></code></a> and
|
||
<a class="reference internal" href="#asyncio.asyncio.subprocess.Process.stderr" title="asyncio.asyncio.subprocess.Process.stderr"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Process.stderr</span></code></a>
|
||
attributes will point to <a class="reference internal" href="asyncio-stream.html#asyncio.StreamReader" title="asyncio.StreamReader"><code class="xref py py-class docutils literal notranslate"><span class="pre">StreamReader</span></code></a> instances.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="asyncio.asyncio.subprocess.STDOUT">
|
||
<code class="descclassname">asyncio.subprocess.</code><code class="descname">STDOUT</code><a class="headerlink" href="#asyncio.asyncio.subprocess.STDOUT" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Special value that can be used as the <em>stderr</em> argument and indicates
|
||
that standard error should be redirected into standard output.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="asyncio.asyncio.subprocess.DEVNULL">
|
||
<code class="descclassname">asyncio.subprocess.</code><code class="descname">DEVNULL</code><a class="headerlink" href="#asyncio.asyncio.subprocess.DEVNULL" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Special value that can be used as the <em>stdin</em>, <em>stdout</em> or <em>stderr</em> argument
|
||
to process creation functions. It indicates that the special file
|
||
<a class="reference internal" href="os.html#os.devnull" title="os.devnull"><code class="xref py py-data docutils literal notranslate"><span class="pre">os.devnull</span></code></a> will be used for the corresponding subprocess stream.</p>
|
||
</dd></dl>
|
||
|
||
</div>
|
||
<div class="section" id="interacting-with-subprocesses">
|
||
<h2>Interacting with Subprocesses<a class="headerlink" href="#interacting-with-subprocesses" title="Permalink to this headline">¶</a></h2>
|
||
<p>Both <a class="reference internal" href="#asyncio.create_subprocess_exec" title="asyncio.create_subprocess_exec"><code class="xref py py-func docutils literal notranslate"><span class="pre">create_subprocess_exec()</span></code></a> and <a class="reference internal" href="#asyncio.create_subprocess_shell" title="asyncio.create_subprocess_shell"><code class="xref py py-func docutils literal notranslate"><span class="pre">create_subprocess_shell()</span></code></a>
|
||
functions return instances of the <em>Process</em> class. <em>Process</em> is a high-level
|
||
wrapper that allows communicating with subprocesses and watching for
|
||
their completion.</p>
|
||
<dl class="class">
|
||
<dt id="asyncio.asyncio.subprocess.Process">
|
||
<em class="property">class </em><code class="descclassname">asyncio.subprocess.</code><code class="descname">Process</code><a class="headerlink" href="#asyncio.asyncio.subprocess.Process" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>An object that wraps OS processes created by the
|
||
<a class="reference internal" href="#asyncio.create_subprocess_exec" title="asyncio.create_subprocess_exec"><code class="xref py py-func docutils literal notranslate"><span class="pre">create_subprocess_exec()</span></code></a> and <a class="reference internal" href="#asyncio.create_subprocess_shell" title="asyncio.create_subprocess_shell"><code class="xref py py-func docutils literal notranslate"><span class="pre">create_subprocess_shell()</span></code></a>
|
||
functions.</p>
|
||
<p>This class is designed to have a similar API to the
|
||
<a class="reference internal" href="subprocess.html#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">subprocess.Popen</span></code></a> class, but there are some
|
||
notable differences:</p>
|
||
<ul class="simple">
|
||
<li><p>unlike Popen, Process instances do not have an equivalent to
|
||
the <a class="reference internal" href="subprocess.html#subprocess.Popen.poll" title="subprocess.Popen.poll"><code class="xref py py-meth docutils literal notranslate"><span class="pre">poll()</span></code></a> method;</p></li>
|
||
<li><p>the <a class="reference internal" href="#asyncio.asyncio.subprocess.Process.communicate" title="asyncio.asyncio.subprocess.Process.communicate"><code class="xref py py-meth docutils literal notranslate"><span class="pre">communicate()</span></code></a> and
|
||
<a class="reference internal" href="#asyncio.asyncio.subprocess.Process.wait" title="asyncio.asyncio.subprocess.Process.wait"><code class="xref py py-meth docutils literal notranslate"><span class="pre">wait()</span></code></a> methods don’t have a
|
||
<em>timeout</em> parameter: use the <a class="reference internal" href="asyncio-task.html#asyncio.wait_for" title="asyncio.wait_for"><code class="xref py py-func docutils literal notranslate"><span class="pre">wait_for()</span></code></a> function;</p></li>
|
||
<li><p>the <a class="reference internal" href="#asyncio.asyncio.subprocess.Process.wait" title="asyncio.asyncio.subprocess.Process.wait"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Process.wait()</span></code></a> method
|
||
is asynchronous, whereas <a class="reference internal" href="subprocess.html#subprocess.Popen.wait" title="subprocess.Popen.wait"><code class="xref py py-meth docutils literal notranslate"><span class="pre">subprocess.Popen.wait()</span></code></a> method
|
||
is implemented as a blocking busy loop;</p></li>
|
||
<li><p>the <em>universal_newlines</em> parameter is not supported.</p></li>
|
||
</ul>
|
||
<p>This class is <a class="reference internal" href="asyncio-dev.html#asyncio-multithreading"><span class="std std-ref">not thread safe</span></a>.</p>
|
||
<p>See also the <a class="reference internal" href="#asyncio-subprocess-threads"><span class="std std-ref">Subprocess and Threads</span></a>
|
||
section.</p>
|
||
<dl class="method">
|
||
<dt id="asyncio.asyncio.subprocess.Process.wait">
|
||
<em class="property">coroutine </em><code class="descname">wait</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.asyncio.subprocess.Process.wait" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Wait for the child process to terminate.</p>
|
||
<p>Set and return the <a class="reference internal" href="#asyncio.asyncio.subprocess.Process.returncode" title="asyncio.asyncio.subprocess.Process.returncode"><code class="xref py py-attr docutils literal notranslate"><span class="pre">returncode</span></code></a> attribute.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>This method can deadlock when using <code class="docutils literal notranslate"><span class="pre">stdout=PIPE</span></code> or
|
||
<code class="docutils literal notranslate"><span class="pre">stderr=PIPE</span></code> and the child process generates so much output
|
||
that it blocks waiting for the OS pipe buffer to accept
|
||
more data. Use the <a class="reference internal" href="#asyncio.asyncio.subprocess.Process.communicate" title="asyncio.asyncio.subprocess.Process.communicate"><code class="xref py py-meth docutils literal notranslate"><span class="pre">communicate()</span></code></a> method when using pipes
|
||
to avoid this condition.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="asyncio.asyncio.subprocess.Process.communicate">
|
||
<em class="property">coroutine </em><code class="descname">communicate</code><span class="sig-paren">(</span><em>input=None</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.asyncio.subprocess.Process.communicate" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Interact with process:</p>
|
||
<ol class="arabic simple">
|
||
<li><p>send data to <em>stdin</em> (if <em>input</em> is not <code class="docutils literal notranslate"><span class="pre">None</span></code>);</p></li>
|
||
<li><p>read data from <em>stdout</em> and <em>stderr</em>, until EOF is reached;</p></li>
|
||
<li><p>wait for process to terminate.</p></li>
|
||
</ol>
|
||
<p>The optional <em>input</em> argument is the data (<a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> object)
|
||
that will be sent to the child process.</p>
|
||
<p>Return a tuple <code class="docutils literal notranslate"><span class="pre">(stdout_data,</span> <span class="pre">stderr_data)</span></code>.</p>
|
||
<p>If either <a class="reference internal" href="exceptions.html#BrokenPipeError" title="BrokenPipeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">BrokenPipeError</span></code></a> or <a class="reference internal" href="exceptions.html#ConnectionResetError" title="ConnectionResetError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ConnectionResetError</span></code></a>
|
||
exception is raised when writing <em>input</em> into <em>stdin</em>, the
|
||
exception is ignored. This condition occurs when the process
|
||
exits before all data are written into <em>stdin</em>.</p>
|
||
<p>If it is desired to send data to the process’ <em>stdin</em>,
|
||
the process needs to be created with <code class="docutils literal notranslate"><span class="pre">stdin=PIPE</span></code>. Similarly,
|
||
to get anything other than <code class="docutils literal notranslate"><span class="pre">None</span></code> in the result tuple, the
|
||
process has to be created with <code class="docutils literal notranslate"><span class="pre">stdout=PIPE</span></code> and/or
|
||
<code class="docutils literal notranslate"><span class="pre">stderr=PIPE</span></code> arguments.</p>
|
||
<p>Note, that the data read is buffered in memory, so do not use
|
||
this method if the data size is large or unlimited.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="asyncio.asyncio.subprocess.Process.send_signal">
|
||
<code class="descname">send_signal</code><span class="sig-paren">(</span><em>signal</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.asyncio.subprocess.Process.send_signal" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Sends the signal <em>signal</em> to the child process.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>On Windows, <code class="xref py py-data docutils literal notranslate"><span class="pre">SIGTERM</span></code> is an alias for <a class="reference internal" href="#asyncio.asyncio.subprocess.Process.terminate" title="asyncio.asyncio.subprocess.Process.terminate"><code class="xref py py-meth docutils literal notranslate"><span class="pre">terminate()</span></code></a>.
|
||
<code class="docutils literal notranslate"><span class="pre">CTRL_C_EVENT</span></code> and <code class="docutils literal notranslate"><span class="pre">CTRL_BREAK_EVENT</span></code> can be sent to processes
|
||
started with a <em>creationflags</em> parameter which includes
|
||
<code class="docutils literal notranslate"><span class="pre">CREATE_NEW_PROCESS_GROUP</span></code>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="asyncio.asyncio.subprocess.Process.terminate">
|
||
<code class="descname">terminate</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.asyncio.subprocess.Process.terminate" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Stop the child process.</p>
|
||
<p>On POSIX systems this method sends <code class="xref py py-data docutils literal notranslate"><span class="pre">signal.SIGTERM</span></code> to the
|
||
child process.</p>
|
||
<p>On Windows the Win32 API function <code class="xref c c-func docutils literal notranslate"><span class="pre">TerminateProcess()</span></code> is
|
||
called to stop the child process.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="asyncio.asyncio.subprocess.Process.kill">
|
||
<code class="descname">kill</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.asyncio.subprocess.Process.kill" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Kill the child.</p>
|
||
<p>On POSIX systems this method sends <code class="xref py py-data docutils literal notranslate"><span class="pre">SIGKILL</span></code> to the child
|
||
process.</p>
|
||
<p>On Windows this method is an alias for <a class="reference internal" href="#asyncio.asyncio.subprocess.Process.terminate" title="asyncio.asyncio.subprocess.Process.terminate"><code class="xref py py-meth docutils literal notranslate"><span class="pre">terminate()</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="asyncio.asyncio.subprocess.Process.stdin">
|
||
<code class="descname">stdin</code><a class="headerlink" href="#asyncio.asyncio.subprocess.Process.stdin" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Standard input stream (<a class="reference internal" href="asyncio-stream.html#asyncio.StreamWriter" title="asyncio.StreamWriter"><code class="xref py py-class docutils literal notranslate"><span class="pre">StreamWriter</span></code></a>) or <code class="docutils literal notranslate"><span class="pre">None</span></code>
|
||
if the process was created with <code class="docutils literal notranslate"><span class="pre">stdin=None</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="asyncio.asyncio.subprocess.Process.stdout">
|
||
<code class="descname">stdout</code><a class="headerlink" href="#asyncio.asyncio.subprocess.Process.stdout" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Standard output stream (<a class="reference internal" href="asyncio-stream.html#asyncio.StreamReader" title="asyncio.StreamReader"><code class="xref py py-class docutils literal notranslate"><span class="pre">StreamReader</span></code></a>) or <code class="docutils literal notranslate"><span class="pre">None</span></code>
|
||
if the process was created with <code class="docutils literal notranslate"><span class="pre">stdout=None</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="asyncio.asyncio.subprocess.Process.stderr">
|
||
<code class="descname">stderr</code><a class="headerlink" href="#asyncio.asyncio.subprocess.Process.stderr" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Standard error stream (<a class="reference internal" href="asyncio-stream.html#asyncio.StreamReader" title="asyncio.StreamReader"><code class="xref py py-class docutils literal notranslate"><span class="pre">StreamReader</span></code></a>) or <code class="docutils literal notranslate"><span class="pre">None</span></code>
|
||
if the process was created with <code class="docutils literal notranslate"><span class="pre">stderr=None</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<div class="admonition warning">
|
||
<p class="admonition-title">Warning</p>
|
||
<p>Use the <a class="reference internal" href="#asyncio.asyncio.subprocess.Process.communicate" title="asyncio.asyncio.subprocess.Process.communicate"><code class="xref py py-meth docutils literal notranslate"><span class="pre">communicate()</span></code></a> method rather than
|
||
<a class="reference internal" href="#asyncio.asyncio.subprocess.Process.stdin" title="asyncio.asyncio.subprocess.Process.stdin"><code class="xref py py-attr docutils literal notranslate"><span class="pre">process.stdin.write()</span></code></a>,
|
||
<a class="reference internal" href="#asyncio.asyncio.subprocess.Process.stdout" title="asyncio.asyncio.subprocess.Process.stdout"><code class="xref py py-attr docutils literal notranslate"><span class="pre">await</span> <span class="pre">process.stdout.read()</span></code></a> or
|
||
<a class="reference internal" href="#asyncio.asyncio.subprocess.Process.stderr" title="asyncio.asyncio.subprocess.Process.stderr"><code class="xref py py-attr docutils literal notranslate"><span class="pre">await</span> <span class="pre">process.stderr.read</span></code></a>.
|
||
This avoids deadlocks due to streams pausing reading or writing
|
||
and blocking the child process.</p>
|
||
</div>
|
||
<dl class="attribute">
|
||
<dt id="asyncio.asyncio.subprocess.Process.pid">
|
||
<code class="descname">pid</code><a class="headerlink" href="#asyncio.asyncio.subprocess.Process.pid" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Process identification number (PID).</p>
|
||
<p>Note that for processes created by the <a class="reference internal" href="#asyncio.create_subprocess_shell" title="asyncio.create_subprocess_shell"><code class="xref py py-func docutils literal notranslate"><span class="pre">create_subprocess_shell()</span></code></a>
|
||
function, this attribute is the PID of the spawned shell.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="asyncio.asyncio.subprocess.Process.returncode">
|
||
<code class="descname">returncode</code><a class="headerlink" href="#asyncio.asyncio.subprocess.Process.returncode" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return code of the process when it exits.</p>
|
||
<p>A <code class="docutils literal notranslate"><span class="pre">None</span></code> value indicates that the process has not terminated yet.</p>
|
||
<p>A negative value <code class="docutils literal notranslate"><span class="pre">-N</span></code> indicates that the child was terminated
|
||
by signal <code class="docutils literal notranslate"><span class="pre">N</span></code> (POSIX only).</p>
|
||
</dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
<div class="section" id="subprocess-and-threads">
|
||
<span id="asyncio-subprocess-threads"></span><h3>Subprocess and Threads<a class="headerlink" href="#subprocess-and-threads" title="Permalink to this headline">¶</a></h3>
|
||
<p>Standard asyncio event loop supports running subprocesses from
|
||
different threads, but there are limitations:</p>
|
||
<ul class="simple">
|
||
<li><p>An event loop must run in the main thread.</p></li>
|
||
<li><p>The child watcher must be instantiated in the main thread
|
||
before executing subprocesses from other threads. Call the
|
||
<a class="reference internal" href="asyncio-policy.html#asyncio.get_child_watcher" title="asyncio.get_child_watcher"><code class="xref py py-func docutils literal notranslate"><span class="pre">get_child_watcher()</span></code></a> function in the main thread to instantiate
|
||
the child watcher.</p></li>
|
||
</ul>
|
||
<p>Note that alternative event loop implementations might not share
|
||
the above limitations; please refer to their documentation.</p>
|
||
<div class="admonition seealso">
|
||
<p class="admonition-title">See also</p>
|
||
<p>The <a class="reference internal" href="asyncio-dev.html#asyncio-multithreading"><span class="std std-ref">Concurrency and multithreading in asyncio</span></a> section.</p>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="examples">
|
||
<h3>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h3>
|
||
<p>An example using the <a class="reference internal" href="#asyncio.asyncio.subprocess.Process" title="asyncio.asyncio.subprocess.Process"><code class="xref py py-class docutils literal notranslate"><span class="pre">Process</span></code></a> class to
|
||
control a subprocess and the <a class="reference internal" href="asyncio-stream.html#asyncio.StreamReader" title="asyncio.StreamReader"><code class="xref py py-class docutils literal notranslate"><span class="pre">StreamReader</span></code></a> class to read from
|
||
its standard output.</p>
|
||
<p id="asyncio-example-create-subprocess-exec">The subprocess is created by the <a class="reference internal" href="#asyncio.create_subprocess_exec" title="asyncio.create_subprocess_exec"><code class="xref py py-func docutils literal notranslate"><span class="pre">create_subprocess_exec()</span></code></a>
|
||
function:</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">async</span> <span class="k">def</span> <span class="nf">get_date</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="c1"># Create the subprocess; redirect the standard output</span>
|
||
<span class="c1"># into a pipe.</span>
|
||
<span class="n">proc</span> <span class="o">=</span> <span class="k">await</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">create_subprocess_exec</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">stdout</span><span class="o">=</span><span class="n">asyncio</span><span class="o">.</span><span class="n">subprocess</span><span class="o">.</span><span class="n">PIPE</span><span class="p">)</span>
|
||
|
||
<span class="c1"># Read one line of output.</span>
|
||
<span class="n">data</span> <span class="o">=</span> <span class="k">await</span> <span class="n">proc</span><span class="o">.</span><span class="n">stdout</span><span class="o">.</span><span class="n">readline</span><span class="p">()</span>
|
||
<span class="n">line</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="s1">'ascii'</span><span class="p">)</span><span class="o">.</span><span class="n">rstrip</span><span class="p">()</span>
|
||
|
||
<span class="c1"># Wait for the subprocess exit.</span>
|
||
<span class="k">await</span> <span class="n">proc</span><span class="o">.</span><span class="n">wait</span><span class="p">()</span>
|
||
<span class="k">return</span> <span class="n">line</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-protocol.html#asyncio-example-subprocess-proto"><span class="std std-ref">same example</span></a>
|
||
written using low-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="#">Subprocesses</a><ul>
|
||
<li><a class="reference internal" href="#creating-subprocesses">Creating Subprocesses</a></li>
|
||
<li><a class="reference internal" href="#constants">Constants</a></li>
|
||
<li><a class="reference internal" href="#interacting-with-subprocesses">Interacting with Subprocesses</a><ul>
|
||
<li><a class="reference internal" href="#subprocess-and-threads">Subprocess and Threads</a></li>
|
||
<li><a class="reference internal" href="#examples">Examples</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
<h4>Previous topic</h4>
|
||
<p class="topless"><a href="asyncio-sync.html"
|
||
title="previous chapter">Synchronization Primitives</a></p>
|
||
<h4>Next topic</h4>
|
||
<p class="topless"><a href="asyncio-queue.html"
|
||
title="next chapter">Queues</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-subprocess.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-queue.html" title="Queues"
|
||
>next</a> |</li>
|
||
<li class="right" >
|
||
<a href="asyncio-sync.html" title="Synchronization Primitives"
|
||
>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> |