1612 lines
154 KiB
HTML
1612 lines
154 KiB
HTML
|
||
<!DOCTYPE html>
|
||
|
||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
<head>
|
||
<meta charset="utf-8" />
|
||
<title>subprocess — Subprocess management — 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="sched — Event scheduler" href="sched.html" />
|
||
<link rel="prev" title="concurrent.futures — Launching parallel tasks" href="concurrent.futures.html" />
|
||
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
|
||
<link rel="canonical" href="https://docs.python.org/3/library/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="sched.html" title="sched — Event scheduler"
|
||
accesskey="N">next</a> |</li>
|
||
<li class="right" >
|
||
<a href="concurrent.futures.html" title="concurrent.futures — Launching parallel tasks"
|
||
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="concurrency.html" accesskey="U">Concurrent Execution</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="module-subprocess">
|
||
<span id="subprocess-subprocess-management"></span><h1><a class="reference internal" href="#module-subprocess" title="subprocess: Subprocess management."><code class="xref py py-mod docutils literal notranslate"><span class="pre">subprocess</span></code></a> — Subprocess management<a class="headerlink" href="#module-subprocess" title="Permalink to this headline">¶</a></h1>
|
||
<p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.7/Lib/subprocess.py">Lib/subprocess.py</a></p>
|
||
<hr class="docutils" />
|
||
<p>The <a class="reference internal" href="#module-subprocess" title="subprocess: Subprocess management."><code class="xref py py-mod docutils literal notranslate"><span class="pre">subprocess</span></code></a> module allows you to spawn new processes, connect to their
|
||
input/output/error pipes, and obtain their return codes. This module intends to
|
||
replace several older modules and functions:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">os</span><span class="o">.</span><span class="n">system</span>
|
||
<span class="n">os</span><span class="o">.</span><span class="n">spawn</span><span class="o">*</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Information about how the <a class="reference internal" href="#module-subprocess" title="subprocess: Subprocess management."><code class="xref py py-mod docutils literal notranslate"><span class="pre">subprocess</span></code></a> module can be used to replace these
|
||
modules and functions can be found in the following sections.</p>
|
||
<div class="admonition seealso">
|
||
<p class="admonition-title">See also</p>
|
||
<p><span class="target" id="index-0"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0324"><strong>PEP 324</strong></a> – PEP proposing the subprocess module</p>
|
||
</div>
|
||
<div class="section" id="using-the-subprocess-module">
|
||
<h2>Using the <a class="reference internal" href="#module-subprocess" title="subprocess: Subprocess management."><code class="xref py py-mod docutils literal notranslate"><span class="pre">subprocess</span></code></a> Module<a class="headerlink" href="#using-the-subprocess-module" title="Permalink to this headline">¶</a></h2>
|
||
<p>The recommended approach to invoking subprocesses is to use the <a class="reference internal" href="#subprocess.run" title="subprocess.run"><code class="xref py py-func docutils literal notranslate"><span class="pre">run()</span></code></a>
|
||
function for all use cases it can handle. For more advanced use cases, the
|
||
underlying <a class="reference internal" href="#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">Popen</span></code></a> interface can be used directly.</p>
|
||
<p>The <a class="reference internal" href="#subprocess.run" title="subprocess.run"><code class="xref py py-func docutils literal notranslate"><span class="pre">run()</span></code></a> function was added in Python 3.5; if you need to retain
|
||
compatibility with older versions, see the <a class="reference internal" href="#call-function-trio"><span class="std std-ref">Older high-level API</span></a> section.</p>
|
||
<dl class="function">
|
||
<dt id="subprocess.run">
|
||
<code class="descclassname">subprocess.</code><code class="descname">run</code><span class="sig-paren">(</span><em>args</em>, <em>*</em>, <em>stdin=None</em>, <em>input=None</em>, <em>stdout=None</em>, <em>stderr=None</em>, <em>capture_output=False</em>, <em>shell=False</em>, <em>cwd=None</em>, <em>timeout=None</em>, <em>check=False</em>, <em>encoding=None</em>, <em>errors=None</em>, <em>text=None</em>, <em>env=None</em>, <em>universal_newlines=None</em><span class="sig-paren">)</span><a class="headerlink" href="#subprocess.run" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Run the command described by <em>args</em>. Wait for command to complete, then
|
||
return a <a class="reference internal" href="#subprocess.CompletedProcess" title="subprocess.CompletedProcess"><code class="xref py py-class docutils literal notranslate"><span class="pre">CompletedProcess</span></code></a> instance.</p>
|
||
<p>The arguments shown above are merely the most common ones, described below
|
||
in <a class="reference internal" href="#frequently-used-arguments"><span class="std std-ref">Frequently Used Arguments</span></a> (hence the use of keyword-only notation
|
||
in the abbreviated signature). The full function signature is largely the
|
||
same as that of the <a class="reference internal" href="#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">Popen</span></code></a> constructor - most of the arguments to
|
||
this function are passed through to that interface. (<em>timeout</em>, <em>input</em>,
|
||
<em>check</em>, and <em>capture_output</em> are not.)</p>
|
||
<p>If <em>capture_output</em> is true, stdout and stderr will be captured.
|
||
When used, the internal <a class="reference internal" href="#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">Popen</span></code></a> object is automatically created with
|
||
<code class="docutils literal notranslate"><span class="pre">stdout=PIPE</span></code> and <code class="docutils literal notranslate"><span class="pre">stderr=PIPE</span></code>. The <em>stdout</em> and <em>stderr</em> arguments may
|
||
not be supplied at the same time as <em>capture_output</em>. If you wish to capture
|
||
and combine both streams into one, use <code class="docutils literal notranslate"><span class="pre">stdout=PIPE</span></code> and <code class="docutils literal notranslate"><span class="pre">stderr=STDOUT</span></code>
|
||
instead of <em>capture_output</em>.</p>
|
||
<p>The <em>timeout</em> argument is passed to <a class="reference internal" href="#subprocess.Popen.communicate" title="subprocess.Popen.communicate"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Popen.communicate()</span></code></a>. If the timeout
|
||
expires, the child process will be killed and waited for. The
|
||
<a class="reference internal" href="#subprocess.TimeoutExpired" title="subprocess.TimeoutExpired"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TimeoutExpired</span></code></a> exception will be re-raised after the child process
|
||
has terminated.</p>
|
||
<p>The <em>input</em> argument is passed to <a class="reference internal" href="#subprocess.Popen.communicate" title="subprocess.Popen.communicate"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Popen.communicate()</span></code></a> and thus to the
|
||
subprocess’s stdin. If used it must be a byte sequence, or a string if
|
||
<em>encoding</em> or <em>errors</em> is specified or <em>text</em> is true. When
|
||
used, the internal <a class="reference internal" href="#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">Popen</span></code></a> object is automatically created with
|
||
<code class="docutils literal notranslate"><span class="pre">stdin=PIPE</span></code>, and the <em>stdin</em> argument may not be used as well.</p>
|
||
<p>If <em>check</em> is true, and the process exits with a non-zero exit code, a
|
||
<a class="reference internal" href="#subprocess.CalledProcessError" title="subprocess.CalledProcessError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">CalledProcessError</span></code></a> exception will be raised. Attributes of that
|
||
exception hold the arguments, the exit code, and stdout and stderr if they
|
||
were captured.</p>
|
||
<p>If <em>encoding</em> or <em>errors</em> are specified, or <em>text</em> is true,
|
||
file objects for stdin, stdout and stderr are opened in text mode using the
|
||
specified <em>encoding</em> and <em>errors</em> or the <a class="reference internal" href="io.html#io.TextIOWrapper" title="io.TextIOWrapper"><code class="xref py py-class docutils literal notranslate"><span class="pre">io.TextIOWrapper</span></code></a> default.
|
||
The <em>universal_newlines</em> argument is equivalent to <em>text</em> and is provided
|
||
for backwards compatibility. By default, file objects are opened in binary mode.</p>
|
||
<p>If <em>env</em> is not <code class="docutils literal notranslate"><span class="pre">None</span></code>, it must be a mapping that defines the environment
|
||
variables for the new process; these are used instead of the default
|
||
behavior of inheriting the current process’ environment. It is passed directly
|
||
to <a class="reference internal" href="#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">Popen</span></code></a>.</p>
|
||
<p>Examples:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">subprocess</span><span class="o">.</span><span class="n">run</span><span class="p">([</span><span class="s2">"ls"</span><span class="p">,</span> <span class="s2">"-l"</span><span class="p">])</span> <span class="c1"># doesn't capture output</span>
|
||
<span class="go">CompletedProcess(args=['ls', '-l'], returncode=0)</span>
|
||
|
||
<span class="gp">>>> </span><span class="n">subprocess</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="s2">"exit 1"</span><span class="p">,</span> <span class="n">shell</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">check</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
|
||
<span class="gt">Traceback (most recent call last):</span>
|
||
<span class="c">...</span>
|
||
<span class="gr">subprocess.CalledProcessError</span>: <span class="n">Command 'exit 1' returned non-zero exit status 1</span>
|
||
|
||
<span class="gp">>>> </span><span class="n">subprocess</span><span class="o">.</span><span class="n">run</span><span class="p">([</span><span class="s2">"ls"</span><span class="p">,</span> <span class="s2">"-l"</span><span class="p">,</span> <span class="s2">"/dev/null"</span><span class="p">],</span> <span class="n">capture_output</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
|
||
<span class="go">CompletedProcess(args=['ls', '-l', '/dev/null'], returncode=0,</span>
|
||
<span class="go">stdout=b'crw-rw-rw- 1 root root 1, 3 Jan 23 16:23 /dev/null\n', stderr=b'')</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.5.</span></p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Added <em>encoding</em> and <em>errors</em> parameters</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.7: </span>Added the <em>text</em> parameter, as a more understandable alias of <em>universal_newlines</em>.
|
||
Added the <em>capture_output</em> parameter.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="subprocess.CompletedProcess">
|
||
<em class="property">class </em><code class="descclassname">subprocess.</code><code class="descname">CompletedProcess</code><a class="headerlink" href="#subprocess.CompletedProcess" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>The return value from <a class="reference internal" href="#subprocess.run" title="subprocess.run"><code class="xref py py-func docutils literal notranslate"><span class="pre">run()</span></code></a>, representing a process that has finished.</p>
|
||
<dl class="attribute">
|
||
<dt id="subprocess.CompletedProcess.args">
|
||
<code class="descname">args</code><a class="headerlink" href="#subprocess.CompletedProcess.args" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>The arguments used to launch the process. This may be a list or a string.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="subprocess.CompletedProcess.returncode">
|
||
<code class="descname">returncode</code><a class="headerlink" href="#subprocess.CompletedProcess.returncode" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Exit status of the child process. Typically, an exit status of 0 indicates
|
||
that it ran successfully.</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>
|
||
|
||
<dl class="attribute">
|
||
<dt id="subprocess.CompletedProcess.stdout">
|
||
<code class="descname">stdout</code><a class="headerlink" href="#subprocess.CompletedProcess.stdout" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Captured stdout from the child process. A bytes sequence, or a string if
|
||
<a class="reference internal" href="#subprocess.run" title="subprocess.run"><code class="xref py py-func docutils literal notranslate"><span class="pre">run()</span></code></a> was called with an encoding, errors, or text=True.
|
||
<code class="docutils literal notranslate"><span class="pre">None</span></code> if stdout was not captured.</p>
|
||
<p>If you ran the process with <code class="docutils literal notranslate"><span class="pre">stderr=subprocess.STDOUT</span></code>, stdout and
|
||
stderr will be combined in this attribute, and <a class="reference internal" href="#subprocess.CompletedProcess.stderr" title="subprocess.CompletedProcess.stderr"><code class="xref py py-attr docutils literal notranslate"><span class="pre">stderr</span></code></a> will be
|
||
<code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="subprocess.CompletedProcess.stderr">
|
||
<code class="descname">stderr</code><a class="headerlink" href="#subprocess.CompletedProcess.stderr" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Captured stderr from the child process. A bytes sequence, or a string if
|
||
<a class="reference internal" href="#subprocess.run" title="subprocess.run"><code class="xref py py-func docutils literal notranslate"><span class="pre">run()</span></code></a> was called with an encoding, errors, or text=True.
|
||
<code class="docutils literal notranslate"><span class="pre">None</span></code> if stderr was not captured.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="subprocess.CompletedProcess.check_returncode">
|
||
<code class="descname">check_returncode</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#subprocess.CompletedProcess.check_returncode" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>If <a class="reference internal" href="#subprocess.CompletedProcess.returncode" title="subprocess.CompletedProcess.returncode"><code class="xref py py-attr docutils literal notranslate"><span class="pre">returncode</span></code></a> is non-zero, raise a <a class="reference internal" href="#subprocess.CalledProcessError" title="subprocess.CalledProcessError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">CalledProcessError</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.5.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="subprocess.DEVNULL">
|
||
<code class="descclassname">subprocess.</code><code class="descname">DEVNULL</code><a class="headerlink" href="#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 <a class="reference internal" href="#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">Popen</span></code></a> and 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.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="subprocess.PIPE">
|
||
<code class="descclassname">subprocess.</code><code class="descname">PIPE</code><a class="headerlink" href="#subprocess.PIPE" 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 <a class="reference internal" href="#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">Popen</span></code></a> and indicates that a pipe to the standard stream should be
|
||
opened. Most useful with <a class="reference internal" href="#subprocess.Popen.communicate" title="subprocess.Popen.communicate"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Popen.communicate()</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="subprocess.STDOUT">
|
||
<code class="descclassname">subprocess.</code><code class="descname">STDOUT</code><a class="headerlink" href="#subprocess.STDOUT" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Special value that can be used as the <em>stderr</em> argument to <a class="reference internal" href="#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">Popen</span></code></a> and
|
||
indicates that standard error should go into the same handle as standard
|
||
output.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="exception">
|
||
<dt id="subprocess.SubprocessError">
|
||
<em class="property">exception </em><code class="descclassname">subprocess.</code><code class="descname">SubprocessError</code><a class="headerlink" href="#subprocess.SubprocessError" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Base class for all other exceptions from this module.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="exception">
|
||
<dt id="subprocess.TimeoutExpired">
|
||
<em class="property">exception </em><code class="descclassname">subprocess.</code><code class="descname">TimeoutExpired</code><a class="headerlink" href="#subprocess.TimeoutExpired" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Subclass of <a class="reference internal" href="#subprocess.SubprocessError" title="subprocess.SubprocessError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SubprocessError</span></code></a>, raised when a timeout expires
|
||
while waiting for a child process.</p>
|
||
<dl class="attribute">
|
||
<dt id="subprocess.TimeoutExpired.cmd">
|
||
<code class="descname">cmd</code><a class="headerlink" href="#subprocess.TimeoutExpired.cmd" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Command that was used to spawn the child process.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="subprocess.TimeoutExpired.timeout">
|
||
<code class="descname">timeout</code><a class="headerlink" href="#subprocess.TimeoutExpired.timeout" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Timeout in seconds.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="subprocess.TimeoutExpired.output">
|
||
<code class="descname">output</code><a class="headerlink" href="#subprocess.TimeoutExpired.output" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Output of the child process if it was captured by <a class="reference internal" href="#subprocess.run" title="subprocess.run"><code class="xref py py-func docutils literal notranslate"><span class="pre">run()</span></code></a> or
|
||
<a class="reference internal" href="#subprocess.check_output" title="subprocess.check_output"><code class="xref py py-func docutils literal notranslate"><span class="pre">check_output()</span></code></a>. Otherwise, <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="subprocess.TimeoutExpired.stdout">
|
||
<code class="descname">stdout</code><a class="headerlink" href="#subprocess.TimeoutExpired.stdout" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Alias for output, for symmetry with <a class="reference internal" href="#subprocess.TimeoutExpired.stderr" title="subprocess.TimeoutExpired.stderr"><code class="xref py py-attr docutils literal notranslate"><span class="pre">stderr</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="subprocess.TimeoutExpired.stderr">
|
||
<code class="descname">stderr</code><a class="headerlink" href="#subprocess.TimeoutExpired.stderr" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Stderr output of the child process if it was captured by <a class="reference internal" href="#subprocess.run" title="subprocess.run"><code class="xref py py-func docutils literal notranslate"><span class="pre">run()</span></code></a>.
|
||
Otherwise, <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3.</span></p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.5: </span><em>stdout</em> and <em>stderr</em> attributes added</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="exception">
|
||
<dt id="subprocess.CalledProcessError">
|
||
<em class="property">exception </em><code class="descclassname">subprocess.</code><code class="descname">CalledProcessError</code><a class="headerlink" href="#subprocess.CalledProcessError" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Subclass of <a class="reference internal" href="#subprocess.SubprocessError" title="subprocess.SubprocessError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SubprocessError</span></code></a>, raised when a process run by
|
||
<a class="reference internal" href="#subprocess.check_call" title="subprocess.check_call"><code class="xref py py-func docutils literal notranslate"><span class="pre">check_call()</span></code></a> or <a class="reference internal" href="#subprocess.check_output" title="subprocess.check_output"><code class="xref py py-func docutils literal notranslate"><span class="pre">check_output()</span></code></a> returns a non-zero exit status.</p>
|
||
<dl class="attribute">
|
||
<dt id="subprocess.CalledProcessError.returncode">
|
||
<code class="descname">returncode</code><a class="headerlink" href="#subprocess.CalledProcessError.returncode" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Exit status of the child process. If the process exited due to a
|
||
signal, this will be the negative signal number.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="subprocess.CalledProcessError.cmd">
|
||
<code class="descname">cmd</code><a class="headerlink" href="#subprocess.CalledProcessError.cmd" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Command that was used to spawn the child process.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="subprocess.CalledProcessError.output">
|
||
<code class="descname">output</code><a class="headerlink" href="#subprocess.CalledProcessError.output" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Output of the child process if it was captured by <a class="reference internal" href="#subprocess.run" title="subprocess.run"><code class="xref py py-func docutils literal notranslate"><span class="pre">run()</span></code></a> or
|
||
<a class="reference internal" href="#subprocess.check_output" title="subprocess.check_output"><code class="xref py py-func docutils literal notranslate"><span class="pre">check_output()</span></code></a>. Otherwise, <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="subprocess.CalledProcessError.stdout">
|
||
<code class="descname">stdout</code><a class="headerlink" href="#subprocess.CalledProcessError.stdout" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Alias for output, for symmetry with <a class="reference internal" href="#subprocess.CalledProcessError.stderr" title="subprocess.CalledProcessError.stderr"><code class="xref py py-attr docutils literal notranslate"><span class="pre">stderr</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="subprocess.CalledProcessError.stderr">
|
||
<code class="descname">stderr</code><a class="headerlink" href="#subprocess.CalledProcessError.stderr" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Stderr output of the child process if it was captured by <a class="reference internal" href="#subprocess.run" title="subprocess.run"><code class="xref py py-func docutils literal notranslate"><span class="pre">run()</span></code></a>.
|
||
Otherwise, <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.5: </span><em>stdout</em> and <em>stderr</em> attributes added</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<div class="section" id="frequently-used-arguments">
|
||
<span id="id1"></span><h3>Frequently Used Arguments<a class="headerlink" href="#frequently-used-arguments" title="Permalink to this headline">¶</a></h3>
|
||
<p>To support a wide variety of use cases, the <a class="reference internal" href="#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">Popen</span></code></a> constructor (and
|
||
the convenience functions) accept a large number of optional arguments. For
|
||
most typical use cases, many of these arguments can be safely left at their
|
||
default values. The arguments that are most commonly needed are:</p>
|
||
<blockquote>
|
||
<div><p><em>args</em> is required for all calls and should be a string, or a sequence of
|
||
program arguments. Providing a sequence of arguments is generally
|
||
preferred, as it allows the module to take care of any required escaping
|
||
and quoting of arguments (e.g. to permit spaces in file names). If passing
|
||
a single string, either <em>shell</em> must be <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> (see below) or else
|
||
the string must simply name the program to be executed without specifying
|
||
any arguments.</p>
|
||
<p><em>stdin</em>, <em>stdout</em> and <em>stderr</em> specify the executed program’s standard input,
|
||
standard output and standard error file handles, respectively. Valid values
|
||
are <a class="reference internal" href="#subprocess.PIPE" title="subprocess.PIPE"><code class="xref py py-data docutils literal notranslate"><span class="pre">PIPE</span></code></a>, <a class="reference internal" href="#subprocess.DEVNULL" title="subprocess.DEVNULL"><code class="xref py py-data docutils literal notranslate"><span class="pre">DEVNULL</span></code></a>, an existing file descriptor (a positive
|
||
integer), an existing file object, and <code class="docutils literal notranslate"><span class="pre">None</span></code>. <a class="reference internal" href="#subprocess.PIPE" title="subprocess.PIPE"><code class="xref py py-data docutils literal notranslate"><span class="pre">PIPE</span></code></a> indicates
|
||
that a new pipe to the child should be created. <a class="reference internal" href="#subprocess.DEVNULL" title="subprocess.DEVNULL"><code class="xref py py-data docutils literal notranslate"><span class="pre">DEVNULL</span></code></a> 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. With the default
|
||
settings of <code class="docutils literal notranslate"><span class="pre">None</span></code>, no redirection will occur; the child’s file handles
|
||
will be inherited from the parent. Additionally, <em>stderr</em> can be
|
||
<a class="reference internal" href="#subprocess.STDOUT" title="subprocess.STDOUT"><code class="xref py py-data docutils literal notranslate"><span class="pre">STDOUT</span></code></a>, which indicates that the stderr data from the child
|
||
process should be captured into the same file handle as for <em>stdout</em>.</p>
|
||
<p id="index-1">If <em>encoding</em> or <em>errors</em> are specified, or <em>text</em> (also known as
|
||
<em>universal_newlines</em>) is true,
|
||
the file objects <em>stdin</em>, <em>stdout</em> and <em>stderr</em> will be opened in text
|
||
mode using the <em>encoding</em> and <em>errors</em> specified in the call or the
|
||
defaults for <a class="reference internal" href="io.html#io.TextIOWrapper" title="io.TextIOWrapper"><code class="xref py py-class docutils literal notranslate"><span class="pre">io.TextIOWrapper</span></code></a>.</p>
|
||
<p>For <em>stdin</em>, line ending characters <code class="docutils literal notranslate"><span class="pre">'\n'</span></code> in the input will be converted
|
||
to the default line separator <a class="reference internal" href="os.html#os.linesep" title="os.linesep"><code class="xref py py-data docutils literal notranslate"><span class="pre">os.linesep</span></code></a>. For <em>stdout</em> and <em>stderr</em>,
|
||
all line endings in the output will be converted to <code class="docutils literal notranslate"><span class="pre">'\n'</span></code>. For more
|
||
information see the documentation of the <a class="reference internal" href="io.html#io.TextIOWrapper" title="io.TextIOWrapper"><code class="xref py py-class docutils literal notranslate"><span class="pre">io.TextIOWrapper</span></code></a> class
|
||
when the <em>newline</em> argument to its constructor is <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
|
||
<p>If text mode is not used, <em>stdin</em>, <em>stdout</em> and <em>stderr</em> will be opened as
|
||
binary streams. No encoding or line ending conversion is performed.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.6: </span>Added <em>encoding</em> and <em>errors</em> parameters.</p>
|
||
</div>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.7: </span>Added the <em>text</em> parameter as an alias for <em>universal_newlines</em>.</p>
|
||
</div>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>The newlines attribute of the file objects <a class="reference internal" href="#subprocess.Popen.stdin" title="subprocess.Popen.stdin"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Popen.stdin</span></code></a>,
|
||
<a class="reference internal" href="#subprocess.Popen.stdout" title="subprocess.Popen.stdout"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Popen.stdout</span></code></a> and <a class="reference internal" href="#subprocess.Popen.stderr" title="subprocess.Popen.stderr"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Popen.stderr</span></code></a> are not updated by
|
||
the <a class="reference internal" href="#subprocess.Popen.communicate" title="subprocess.Popen.communicate"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Popen.communicate()</span></code></a> method.</p>
|
||
</div>
|
||
<p>If <em>shell</em> is <code class="docutils literal notranslate"><span class="pre">True</span></code>, the specified command will be executed through
|
||
the shell. This can be useful if you are using Python primarily for the
|
||
enhanced control flow it offers over most system shells and still want
|
||
convenient access to other shell features such as shell pipes, filename
|
||
wildcards, environment variable expansion, and expansion of <code class="docutils literal notranslate"><span class="pre">~</span></code> to a
|
||
user’s home directory. However, note that Python itself offers
|
||
implementations of many shell-like features (in particular, <a class="reference internal" href="glob.html#module-glob" title="glob: Unix shell style pathname pattern expansion."><code class="xref py py-mod docutils literal notranslate"><span class="pre">glob</span></code></a>,
|
||
<a class="reference internal" href="fnmatch.html#module-fnmatch" title="fnmatch: Unix shell style filename pattern matching."><code class="xref py py-mod docutils literal notranslate"><span class="pre">fnmatch</span></code></a>, <a class="reference internal" href="os.html#os.walk" title="os.walk"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.walk()</span></code></a>, <a class="reference internal" href="os.path.html#os.path.expandvars" title="os.path.expandvars"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.path.expandvars()</span></code></a>,
|
||
<a class="reference internal" href="os.path.html#os.path.expanduser" title="os.path.expanduser"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.path.expanduser()</span></code></a>, and <a class="reference internal" href="shutil.html#module-shutil" title="shutil: High-level file operations, including copying."><code class="xref py py-mod docutils literal notranslate"><span class="pre">shutil</span></code></a>).</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.3: </span>When <em>universal_newlines</em> is <code class="docutils literal notranslate"><span class="pre">True</span></code>, the class uses the encoding
|
||
<a class="reference internal" href="locale.html#locale.getpreferredencoding" title="locale.getpreferredencoding"><code class="xref py py-func docutils literal notranslate"><span class="pre">locale.getpreferredencoding(False)</span></code></a>
|
||
instead of <code class="docutils literal notranslate"><span class="pre">locale.getpreferredencoding()</span></code>. See the
|
||
<a class="reference internal" href="io.html#io.TextIOWrapper" title="io.TextIOWrapper"><code class="xref py py-class docutils literal notranslate"><span class="pre">io.TextIOWrapper</span></code></a> class for more information on this change.</p>
|
||
</div>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>Read the <a class="reference internal" href="#security-considerations">Security Considerations</a> section before using <code class="docutils literal notranslate"><span class="pre">shell=True</span></code>.</p>
|
||
</div>
|
||
</div></blockquote>
|
||
<p>These options, along with all of the other options, are described in more
|
||
detail in the <a class="reference internal" href="#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">Popen</span></code></a> constructor documentation.</p>
|
||
</div>
|
||
<div class="section" id="popen-constructor">
|
||
<h3>Popen Constructor<a class="headerlink" href="#popen-constructor" title="Permalink to this headline">¶</a></h3>
|
||
<p>The underlying process creation and management in this module is handled by
|
||
the <a class="reference internal" href="#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">Popen</span></code></a> class. It offers a lot of flexibility so that developers
|
||
are able to handle the less common cases not covered by the convenience
|
||
functions.</p>
|
||
<dl class="class">
|
||
<dt id="subprocess.Popen">
|
||
<em class="property">class </em><code class="descclassname">subprocess.</code><code class="descname">Popen</code><span class="sig-paren">(</span><em>args</em>, <em>bufsize=-1</em>, <em>executable=None</em>, <em>stdin=None</em>, <em>stdout=None</em>, <em>stderr=None</em>, <em>preexec_fn=None</em>, <em>close_fds=True</em>, <em>shell=False</em>, <em>cwd=None</em>, <em>env=None</em>, <em>universal_newlines=None</em>, <em>startupinfo=None</em>, <em>creationflags=0</em>, <em>restore_signals=True</em>, <em>start_new_session=False</em>, <em>pass_fds=()</em>, <em>*</em>, <em>encoding=None</em>, <em>errors=None</em>, <em>text=None</em><span class="sig-paren">)</span><a class="headerlink" href="#subprocess.Popen" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Execute a child program in a new process. On POSIX, the class uses
|
||
<a class="reference internal" href="os.html#os.execvp" title="os.execvp"><code class="xref py py-meth docutils literal notranslate"><span class="pre">os.execvp()</span></code></a>-like behavior to execute the child program. On Windows,
|
||
the class uses the Windows <code class="docutils literal notranslate"><span class="pre">CreateProcess()</span></code> function. The arguments to
|
||
<a class="reference internal" href="#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">Popen</span></code></a> are as follows.</p>
|
||
<p><em>args</em> should be a sequence of program arguments or else a single string.
|
||
By default, the program to execute is the first item in <em>args</em> if <em>args</em> is
|
||
a sequence. If <em>args</em> is a string, the interpretation is
|
||
platform-dependent and described below. See the <em>shell</em> and <em>executable</em>
|
||
arguments for additional differences from the default behavior. Unless
|
||
otherwise stated, it is recommended to pass <em>args</em> as a sequence.</p>
|
||
<p>On POSIX, if <em>args</em> is a string, the string is interpreted as the name or
|
||
path of the program to execute. However, this can only be done if not
|
||
passing arguments to the program.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p><a class="reference internal" href="shlex.html#shlex.split" title="shlex.split"><code class="xref py py-meth docutils literal notranslate"><span class="pre">shlex.split()</span></code></a> can be useful when determining the correct
|
||
tokenization for <em>args</em>, especially in complex cases:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span> <span class="nn">shlex</span><span class="o">,</span> <span class="nn">subprocess</span>
|
||
<span class="gp">>>> </span><span class="n">command_line</span> <span class="o">=</span> <span class="nb">input</span><span class="p">()</span>
|
||
<span class="go">/bin/vikings -input eggs.txt -output "spam spam.txt" -cmd "echo '$MONEY'"</span>
|
||
<span class="gp">>>> </span><span class="n">args</span> <span class="o">=</span> <span class="n">shlex</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="n">command_line</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">args</span><span class="p">)</span>
|
||
<span class="go">['/bin/vikings', '-input', 'eggs.txt', '-output', 'spam spam.txt', '-cmd', "echo '$MONEY'"]</span>
|
||
<span class="gp">>>> </span><span class="n">p</span> <span class="o">=</span> <span class="n">subprocess</span><span class="o">.</span><span class="n">Popen</span><span class="p">(</span><span class="n">args</span><span class="p">)</span> <span class="c1"># Success!</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Note in particular that options (such as <em>-input</em>) and arguments (such
|
||
as <em>eggs.txt</em>) that are separated by whitespace in the shell go in separate
|
||
list elements, while arguments that need quoting or backslash escaping when
|
||
used in the shell (such as filenames containing spaces or the <em>echo</em> command
|
||
shown above) are single list elements.</p>
|
||
</div>
|
||
<p>On Windows, if <em>args</em> is a sequence, it will be converted to a string in a
|
||
manner described in <a class="reference internal" href="#converting-argument-sequence"><span class="std std-ref">Converting an argument sequence to a string on Windows</span></a>. This is because
|
||
the underlying <code class="docutils literal notranslate"><span class="pre">CreateProcess()</span></code> operates on strings.</p>
|
||
<p>The <em>shell</em> argument (which defaults to <code class="docutils literal notranslate"><span class="pre">False</span></code>) specifies whether to use
|
||
the shell as the program to execute. If <em>shell</em> is <code class="docutils literal notranslate"><span class="pre">True</span></code>, it is
|
||
recommended to pass <em>args</em> as a string rather than as a sequence.</p>
|
||
<p>On POSIX with <code class="docutils literal notranslate"><span class="pre">shell=True</span></code>, the shell defaults to <code class="file docutils literal notranslate"><span class="pre">/bin/sh</span></code>. If
|
||
<em>args</em> is a string, the string specifies the command
|
||
to execute through the shell. This means that the string must be
|
||
formatted exactly as it would be when typed at the shell prompt. This
|
||
includes, for example, quoting or backslash escaping filenames with spaces in
|
||
them. If <em>args</em> is a sequence, the first item specifies the command string, and
|
||
any additional items will be treated as additional arguments to the shell
|
||
itself. That is to say, <a class="reference internal" href="#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">Popen</span></code></a> does the equivalent of:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">Popen</span><span class="p">([</span><span class="s1">'/bin/sh'</span><span class="p">,</span> <span class="s1">'-c'</span><span class="p">,</span> <span class="n">args</span><span class="p">[</span><span class="mi">0</span><span class="p">],</span> <span class="n">args</span><span class="p">[</span><span class="mi">1</span><span class="p">],</span> <span class="o">...</span><span class="p">])</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>On Windows with <code class="docutils literal notranslate"><span class="pre">shell=True</span></code>, the <span class="target" id="index-2"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">COMSPEC</span></code> environment variable
|
||
specifies the default shell. The only time you need to specify
|
||
<code class="docutils literal notranslate"><span class="pre">shell=True</span></code> on Windows is when the command you wish to execute is built
|
||
into the shell (e.g. <strong class="command">dir</strong> or <strong class="command">copy</strong>). You do not need
|
||
<code class="docutils literal notranslate"><span class="pre">shell=True</span></code> to run a batch file or console-based executable.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>Read the <a class="reference internal" href="#security-considerations">Security Considerations</a> section before using <code class="docutils literal notranslate"><span class="pre">shell=True</span></code>.</p>
|
||
</div>
|
||
<p><em>bufsize</em> will be supplied as the corresponding argument to the
|
||
<a class="reference internal" href="functions.html#open" title="open"><code class="xref py py-func docutils literal notranslate"><span class="pre">open()</span></code></a> function when creating the stdin/stdout/stderr pipe
|
||
file objects:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="xref py py-const docutils literal notranslate"><span class="pre">0</span></code> means unbuffered (read and write are one
|
||
system call and can return short)</p></li>
|
||
<li><p><code class="xref py py-const docutils literal notranslate"><span class="pre">1</span></code> means line buffered
|
||
(only usable if <code class="docutils literal notranslate"><span class="pre">universal_newlines=True</span></code> i.e., in a text mode)</p></li>
|
||
<li><p>any other positive value means use a buffer of approximately that
|
||
size</p></li>
|
||
<li><p>negative bufsize (the default) means the system default of
|
||
io.DEFAULT_BUFFER_SIZE will be used.</p></li>
|
||
</ul>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.3.1: </span><em>bufsize</em> now defaults to -1 to enable buffering by default to match the
|
||
behavior that most code expects. In versions prior to Python 3.2.4 and
|
||
3.3.1 it incorrectly defaulted to <code class="xref py py-const docutils literal notranslate"><span class="pre">0</span></code> which was unbuffered
|
||
and allowed short reads. This was unintentional and did not match the
|
||
behavior of Python 2 as most code expected.</p>
|
||
</div>
|
||
<p>The <em>executable</em> argument specifies a replacement program to execute. It
|
||
is very seldom needed. When <code class="docutils literal notranslate"><span class="pre">shell=False</span></code>, <em>executable</em> replaces the
|
||
program to execute specified by <em>args</em>. However, the original <em>args</em> is
|
||
still passed to the program. Most programs treat the program specified
|
||
by <em>args</em> as the command name, which can then be different from the program
|
||
actually executed. On POSIX, the <em>args</em> name
|
||
becomes the display name for the executable in utilities such as
|
||
<strong class="program">ps</strong>. If <code class="docutils literal notranslate"><span class="pre">shell=True</span></code>, on POSIX the <em>executable</em> argument
|
||
specifies a replacement shell for the default <code class="file docutils literal notranslate"><span class="pre">/bin/sh</span></code>.</p>
|
||
<p><em>stdin</em>, <em>stdout</em> and <em>stderr</em> specify the executed program’s standard input,
|
||
standard output and standard error file handles, respectively. Valid values
|
||
are <a class="reference internal" href="#subprocess.PIPE" title="subprocess.PIPE"><code class="xref py py-data docutils literal notranslate"><span class="pre">PIPE</span></code></a>, <a class="reference internal" href="#subprocess.DEVNULL" title="subprocess.DEVNULL"><code class="xref py py-data docutils literal notranslate"><span class="pre">DEVNULL</span></code></a>, an existing file descriptor (a positive
|
||
integer), an existing <a class="reference internal" href="../glossary.html#term-file-object"><span class="xref std std-term">file object</span></a>, and <code class="docutils literal notranslate"><span class="pre">None</span></code>. <a class="reference internal" href="#subprocess.PIPE" title="subprocess.PIPE"><code class="xref py py-data docutils literal notranslate"><span class="pre">PIPE</span></code></a>
|
||
indicates that a new pipe to the child should be created. <a class="reference internal" href="#subprocess.DEVNULL" title="subprocess.DEVNULL"><code class="xref py py-data docutils literal notranslate"><span class="pre">DEVNULL</span></code></a>
|
||
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. With the
|
||
default settings of <code class="docutils literal notranslate"><span class="pre">None</span></code>, no redirection will occur; the child’s file
|
||
handles will be inherited from the parent. Additionally, <em>stderr</em> can be
|
||
<a class="reference internal" href="#subprocess.STDOUT" title="subprocess.STDOUT"><code class="xref py py-data docutils literal notranslate"><span class="pre">STDOUT</span></code></a>, which indicates that the stderr data from the applications
|
||
should be captured into the same file handle as for stdout.</p>
|
||
<p>If <em>preexec_fn</em> is set to a callable object, this object will be called in the
|
||
child process just before the child is executed.
|
||
(POSIX only)</p>
|
||
<div class="admonition warning">
|
||
<p class="admonition-title">Warning</p>
|
||
<p>The <em>preexec_fn</em> parameter is not safe to use in the presence of threads
|
||
in your application. The child process could deadlock before exec is
|
||
called.
|
||
If you must use it, keep it trivial! Minimize the number of libraries
|
||
you call into.</p>
|
||
</div>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>If you need to modify the environment for the child use the <em>env</em>
|
||
parameter rather than doing it in a <em>preexec_fn</em>.
|
||
The <em>start_new_session</em> parameter can take the place of a previously
|
||
common use of <em>preexec_fn</em> to call os.setsid() in the child.</p>
|
||
</div>
|
||
<p>If <em>close_fds</em> is true, all file descriptors except <code class="xref py py-const docutils literal notranslate"><span class="pre">0</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">1</span></code> and
|
||
<code class="xref py py-const docutils literal notranslate"><span class="pre">2</span></code> will be closed before the child process is executed. Otherwise
|
||
when <em>close_fds</em> is false, file descriptors obey their inheritable flag
|
||
as described in <a class="reference internal" href="os.html#fd-inheritance"><span class="std std-ref">Inheritance of File Descriptors</span></a>.</p>
|
||
<p>On Windows, if <em>close_fds</em> is true then no handles will be inherited by the
|
||
child process unless explicitly passed in the <code class="docutils literal notranslate"><span class="pre">handle_list</span></code> element of
|
||
<a class="reference internal" href="#subprocess.STARTUPINFO.lpAttributeList" title="subprocess.STARTUPINFO.lpAttributeList"><code class="xref py py-attr docutils literal notranslate"><span class="pre">STARTUPINFO.lpAttributeList</span></code></a>, or by standard handle redirection.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.2: </span>The default for <em>close_fds</em> was changed from <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> to
|
||
what is described above.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.7: </span>On Windows the default for <em>close_fds</em> was changed from <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> to
|
||
<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> when redirecting the standard handles. It’s now possible to
|
||
set <em>close_fds</em> to <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> when redirecting the standard handles.</p>
|
||
</div>
|
||
<p><em>pass_fds</em> is an optional sequence of file descriptors to keep open
|
||
between the parent and child. Providing any <em>pass_fds</em> forces
|
||
<em>close_fds</em> to be <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>. (POSIX only)</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.2: </span>The <em>pass_fds</em> parameter was added.</p>
|
||
</div>
|
||
<p>If <em>cwd</em> is not <code class="docutils literal notranslate"><span class="pre">None</span></code>, the function changes the working directory to
|
||
<em>cwd</em> before executing the child. <em>cwd</em> can be a <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> and
|
||
<a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like</span></a> object. In particular, the function
|
||
looks for <em>executable</em> (or for the first item in <em>args</em>) relative to <em>cwd</em>
|
||
if the executable path is a relative path.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span><em>cwd</em> parameter accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.</p>
|
||
</div>
|
||
<p>If <em>restore_signals</em> is true (the default) all signals that Python has set to
|
||
SIG_IGN are restored to SIG_DFL in the child process before the exec.
|
||
Currently this includes the SIGPIPE, SIGXFZ and SIGXFSZ signals.
|
||
(POSIX only)</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.2: </span><em>restore_signals</em> was added.</p>
|
||
</div>
|
||
<p>If <em>start_new_session</em> is true the setsid() system call will be made in the
|
||
child process prior to the execution of the subprocess. (POSIX only)</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.2: </span><em>start_new_session</em> was added.</p>
|
||
</div>
|
||
<p>If <em>env</em> is not <code class="docutils literal notranslate"><span class="pre">None</span></code>, it must be a mapping that defines the environment
|
||
variables for the new process; these are used instead of the default
|
||
behavior of inheriting the current process’ environment.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>If specified, <em>env</em> must provide any variables required for the program to
|
||
execute. On Windows, in order to run a <a class="reference external" href="https://en.wikipedia.org/wiki/Side-by-Side_Assembly">side-by-side assembly</a> the
|
||
specified <em>env</em> <strong>must</strong> include a valid <span class="target" id="index-3"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">SystemRoot</span></code>.</p>
|
||
</div>
|
||
<p>If <em>encoding</em> or <em>errors</em> are specified, or <em>text</em> is true, the file objects
|
||
<em>stdin</em>, <em>stdout</em> and <em>stderr</em> are opened in text mode with the specified
|
||
encoding and <em>errors</em>, as described above in <a class="reference internal" href="#frequently-used-arguments"><span class="std std-ref">Frequently Used Arguments</span></a>.
|
||
The <em>universal_newlines</em> argument is equivalent to <em>text</em> and is provided
|
||
for backwards compatibility. By default, file objects are opened in binary mode.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.6: </span><em>encoding</em> and <em>errors</em> were added.</p>
|
||
</div>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.7: </span><em>text</em> was added as a more readable alias for <em>universal_newlines</em>.</p>
|
||
</div>
|
||
<p>If given, <em>startupinfo</em> will be a <a class="reference internal" href="#subprocess.STARTUPINFO" title="subprocess.STARTUPINFO"><code class="xref py py-class docutils literal notranslate"><span class="pre">STARTUPINFO</span></code></a> object, which is
|
||
passed to the underlying <code class="docutils literal notranslate"><span class="pre">CreateProcess</span></code> function.
|
||
<em>creationflags</em>, if given, can be one or more of the following flags:</p>
|
||
<blockquote>
|
||
<div><ul class="simple">
|
||
<li><p><a class="reference internal" href="#subprocess.CREATE_NEW_CONSOLE" title="subprocess.CREATE_NEW_CONSOLE"><code class="xref py py-data docutils literal notranslate"><span class="pre">CREATE_NEW_CONSOLE</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="#subprocess.CREATE_NEW_PROCESS_GROUP" title="subprocess.CREATE_NEW_PROCESS_GROUP"><code class="xref py py-data docutils literal notranslate"><span class="pre">CREATE_NEW_PROCESS_GROUP</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="#subprocess.ABOVE_NORMAL_PRIORITY_CLASS" title="subprocess.ABOVE_NORMAL_PRIORITY_CLASS"><code class="xref py py-data docutils literal notranslate"><span class="pre">ABOVE_NORMAL_PRIORITY_CLASS</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="#subprocess.BELOW_NORMAL_PRIORITY_CLASS" title="subprocess.BELOW_NORMAL_PRIORITY_CLASS"><code class="xref py py-data docutils literal notranslate"><span class="pre">BELOW_NORMAL_PRIORITY_CLASS</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="#subprocess.HIGH_PRIORITY_CLASS" title="subprocess.HIGH_PRIORITY_CLASS"><code class="xref py py-data docutils literal notranslate"><span class="pre">HIGH_PRIORITY_CLASS</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="#subprocess.IDLE_PRIORITY_CLASS" title="subprocess.IDLE_PRIORITY_CLASS"><code class="xref py py-data docutils literal notranslate"><span class="pre">IDLE_PRIORITY_CLASS</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="#subprocess.NORMAL_PRIORITY_CLASS" title="subprocess.NORMAL_PRIORITY_CLASS"><code class="xref py py-data docutils literal notranslate"><span class="pre">NORMAL_PRIORITY_CLASS</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="#subprocess.REALTIME_PRIORITY_CLASS" title="subprocess.REALTIME_PRIORITY_CLASS"><code class="xref py py-data docutils literal notranslate"><span class="pre">REALTIME_PRIORITY_CLASS</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="#subprocess.CREATE_NO_WINDOW" title="subprocess.CREATE_NO_WINDOW"><code class="xref py py-data docutils literal notranslate"><span class="pre">CREATE_NO_WINDOW</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="#subprocess.DETACHED_PROCESS" title="subprocess.DETACHED_PROCESS"><code class="xref py py-data docutils literal notranslate"><span class="pre">DETACHED_PROCESS</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="#subprocess.CREATE_DEFAULT_ERROR_MODE" title="subprocess.CREATE_DEFAULT_ERROR_MODE"><code class="xref py py-data docutils literal notranslate"><span class="pre">CREATE_DEFAULT_ERROR_MODE</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="#subprocess.CREATE_BREAKAWAY_FROM_JOB" title="subprocess.CREATE_BREAKAWAY_FROM_JOB"><code class="xref py py-data docutils literal notranslate"><span class="pre">CREATE_BREAKAWAY_FROM_JOB</span></code></a></p></li>
|
||
</ul>
|
||
</div></blockquote>
|
||
<p>Popen objects are supported as context managers via the <a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a> statement:
|
||
on exit, standard file descriptors are closed, and the process is waited for.</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="n">Popen</span><span class="p">([</span><span class="s2">"ifconfig"</span><span class="p">],</span> <span class="n">stdout</span><span class="o">=</span><span class="n">PIPE</span><span class="p">)</span> <span class="k">as</span> <span class="n">proc</span><span class="p">:</span>
|
||
<span class="n">log</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="n">proc</span><span class="o">.</span><span class="n">stdout</span><span class="o">.</span><span class="n">read</span><span class="p">())</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.2: </span>Added context manager support.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Popen destructor now emits a <a class="reference internal" href="exceptions.html#ResourceWarning" title="ResourceWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ResourceWarning</span></code></a> warning if the child
|
||
process is still running.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
</div>
|
||
<div class="section" id="exceptions">
|
||
<h3>Exceptions<a class="headerlink" href="#exceptions" title="Permalink to this headline">¶</a></h3>
|
||
<p>Exceptions raised in the child process, before the new program has started to
|
||
execute, will be re-raised in the parent.</p>
|
||
<p>The most common exception raised is <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a>. This occurs, for example,
|
||
when trying to execute a non-existent file. Applications should prepare for
|
||
<a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a> exceptions.</p>
|
||
<p>A <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> will be raised if <a class="reference internal" href="#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">Popen</span></code></a> is called with invalid
|
||
arguments.</p>
|
||
<p><a class="reference internal" href="#subprocess.check_call" title="subprocess.check_call"><code class="xref py py-func docutils literal notranslate"><span class="pre">check_call()</span></code></a> and <a class="reference internal" href="#subprocess.check_output" title="subprocess.check_output"><code class="xref py py-func docutils literal notranslate"><span class="pre">check_output()</span></code></a> will raise
|
||
<a class="reference internal" href="#subprocess.CalledProcessError" title="subprocess.CalledProcessError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">CalledProcessError</span></code></a> if the called process returns a non-zero return
|
||
code.</p>
|
||
<p>All of the functions and methods that accept a <em>timeout</em> parameter, such as
|
||
<a class="reference internal" href="#subprocess.call" title="subprocess.call"><code class="xref py py-func docutils literal notranslate"><span class="pre">call()</span></code></a> and <a class="reference internal" href="#subprocess.Popen.communicate" title="subprocess.Popen.communicate"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Popen.communicate()</span></code></a> will raise <a class="reference internal" href="#subprocess.TimeoutExpired" title="subprocess.TimeoutExpired"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TimeoutExpired</span></code></a> if
|
||
the timeout expires before the process exits.</p>
|
||
<p>Exceptions defined in this module all inherit from <a class="reference internal" href="#subprocess.SubprocessError" title="subprocess.SubprocessError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SubprocessError</span></code></a>.</p>
|
||
<blockquote>
|
||
<div><div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3: </span>The <a class="reference internal" href="#subprocess.SubprocessError" title="subprocess.SubprocessError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SubprocessError</span></code></a> base class was added.</p>
|
||
</div>
|
||
</div></blockquote>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="security-considerations">
|
||
<h2>Security Considerations<a class="headerlink" href="#security-considerations" title="Permalink to this headline">¶</a></h2>
|
||
<p>Unlike some other popen functions, this implementation will never
|
||
implicitly call a system shell. This means that all characters,
|
||
including shell metacharacters, can safely be passed to child processes.
|
||
If the shell is invoked explicitly, via <code class="docutils literal notranslate"><span class="pre">shell=True</span></code>, it is the application’s
|
||
responsibility to ensure that all whitespace and metacharacters are
|
||
quoted appropriately to avoid
|
||
<a class="reference external" href="https://en.wikipedia.org/wiki/Shell_injection#Shell_injection">shell injection</a>
|
||
vulnerabilities.</p>
|
||
<p>When using <code class="docutils literal notranslate"><span class="pre">shell=True</span></code>, 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 shell metacharacters in strings
|
||
that are going to be used to construct shell commands.</p>
|
||
</div>
|
||
<div class="section" id="popen-objects">
|
||
<h2>Popen Objects<a class="headerlink" href="#popen-objects" title="Permalink to this headline">¶</a></h2>
|
||
<p>Instances of the <a class="reference internal" href="#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">Popen</span></code></a> class have the following methods:</p>
|
||
<dl class="method">
|
||
<dt id="subprocess.Popen.poll">
|
||
<code class="descclassname">Popen.</code><code class="descname">poll</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#subprocess.Popen.poll" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Check if child process has terminated. Set and return
|
||
<a class="reference internal" href="#subprocess.Popen.returncode" title="subprocess.Popen.returncode"><code class="xref py py-attr docutils literal notranslate"><span class="pre">returncode</span></code></a> attribute. Otherwise, returns <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="subprocess.Popen.wait">
|
||
<code class="descclassname">Popen.</code><code class="descname">wait</code><span class="sig-paren">(</span><em>timeout=None</em><span class="sig-paren">)</span><a class="headerlink" href="#subprocess.Popen.wait" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Wait for child process to terminate. Set and return
|
||
<a class="reference internal" href="#subprocess.Popen.returncode" title="subprocess.Popen.returncode"><code class="xref py py-attr docutils literal notranslate"><span class="pre">returncode</span></code></a> attribute.</p>
|
||
<p>If the process does not terminate after <em>timeout</em> seconds, raise a
|
||
<a class="reference internal" href="#subprocess.TimeoutExpired" title="subprocess.TimeoutExpired"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TimeoutExpired</span></code></a> exception. It is safe to catch this exception and
|
||
retry the wait.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>This will 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 enough output to a pipe such that
|
||
it blocks waiting for the OS pipe buffer to accept more data.
|
||
Use <a class="reference internal" href="#subprocess.Popen.communicate" title="subprocess.Popen.communicate"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Popen.communicate()</span></code></a> when using pipes to avoid that.</p>
|
||
</div>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>The function is implemented using a busy loop (non-blocking call and
|
||
short sleeps). Use the <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> module for an asynchronous wait:
|
||
see <a class="reference internal" href="asyncio-subprocess.html#asyncio.create_subprocess_exec" title="asyncio.create_subprocess_exec"><code class="xref py py-class docutils literal notranslate"><span class="pre">asyncio.create_subprocess_exec</span></code></a>.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.3: </span><em>timeout</em> was added.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="subprocess.Popen.communicate">
|
||
<code class="descclassname">Popen.</code><code class="descname">communicate</code><span class="sig-paren">(</span><em>input=None</em>, <em>timeout=None</em><span class="sig-paren">)</span><a class="headerlink" href="#subprocess.Popen.communicate" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Interact with process: Send data to stdin. Read data from stdout and stderr,
|
||
until end-of-file is reached. Wait for process to terminate. The optional
|
||
<em>input</em> argument should be data to be sent to the child process, or
|
||
<code class="docutils literal notranslate"><span class="pre">None</span></code>, if no data should be sent to the child. If streams were opened in
|
||
text mode, <em>input</em> must be a string. Otherwise, it must be bytes.</p>
|
||
<p><a class="reference internal" href="#subprocess.Popen.communicate" title="subprocess.Popen.communicate"><code class="xref py py-meth docutils literal notranslate"><span class="pre">communicate()</span></code></a> returns a tuple <code class="docutils literal notranslate"><span class="pre">(stdout_data,</span> <span class="pre">stderr_data)</span></code>.
|
||
The data will be strings if streams were opened in text mode; otherwise,
|
||
bytes.</p>
|
||
<p>Note that if you want to send data to the process’s stdin, you need to create
|
||
the Popen object 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, you need to give <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> too.</p>
|
||
<p>If the process does not terminate after <em>timeout</em> seconds, a
|
||
<a class="reference internal" href="#subprocess.TimeoutExpired" title="subprocess.TimeoutExpired"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TimeoutExpired</span></code></a> exception will be raised. Catching this exception and
|
||
retrying communication will not lose any output.</p>
|
||
<p>The child process is not killed if the timeout expires, so in order to
|
||
cleanup properly a well-behaved application should kill the child process and
|
||
finish communication:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">proc</span> <span class="o">=</span> <span class="n">subprocess</span><span class="o">.</span><span class="n">Popen</span><span class="p">(</span><span class="o">...</span><span class="p">)</span>
|
||
<span class="k">try</span><span class="p">:</span>
|
||
<span class="n">outs</span><span class="p">,</span> <span class="n">errs</span> <span class="o">=</span> <span class="n">proc</span><span class="o">.</span><span class="n">communicate</span><span class="p">(</span><span class="n">timeout</span><span class="o">=</span><span class="mi">15</span><span class="p">)</span>
|
||
<span class="k">except</span> <span class="n">TimeoutExpired</span><span class="p">:</span>
|
||
<span class="n">proc</span><span class="o">.</span><span class="n">kill</span><span class="p">()</span>
|
||
<span class="n">outs</span><span class="p">,</span> <span class="n">errs</span> <span class="o">=</span> <span class="n">proc</span><span class="o">.</span><span class="n">communicate</span><span class="p">()</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>The data read is buffered in memory, so do not use this method if the data
|
||
size is large or unlimited.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.3: </span><em>timeout</em> was added.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="subprocess.Popen.send_signal">
|
||
<code class="descclassname">Popen.</code><code class="descname">send_signal</code><span class="sig-paren">(</span><em>signal</em><span class="sig-paren">)</span><a class="headerlink" href="#subprocess.Popen.send_signal" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Sends the signal <em>signal</em> to the child.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>On Windows, SIGTERM is an alias for <a class="reference internal" href="#subprocess.Popen.terminate" title="subprocess.Popen.terminate"><code class="xref py py-meth docutils literal notranslate"><span class="pre">terminate()</span></code></a>. CTRL_C_EVENT and
|
||
CTRL_BREAK_EVENT can be sent to processes started with a <em>creationflags</em>
|
||
parameter which includes <cite>CREATE_NEW_PROCESS_GROUP</cite>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="subprocess.Popen.terminate">
|
||
<code class="descclassname">Popen.</code><code class="descname">terminate</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#subprocess.Popen.terminate" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Stop the child. On Posix OSs the method sends SIGTERM to the
|
||
child. 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.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="subprocess.Popen.kill">
|
||
<code class="descclassname">Popen.</code><code class="descname">kill</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#subprocess.Popen.kill" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Kills the child. On Posix OSs the function sends SIGKILL to the child.
|
||
On Windows <a class="reference internal" href="#subprocess.Popen.kill" title="subprocess.Popen.kill"><code class="xref py py-meth docutils literal notranslate"><span class="pre">kill()</span></code></a> is an alias for <a class="reference internal" href="#subprocess.Popen.terminate" title="subprocess.Popen.terminate"><code class="xref py py-meth docutils literal notranslate"><span class="pre">terminate()</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<p>The following attributes are also available:</p>
|
||
<dl class="attribute">
|
||
<dt id="subprocess.Popen.args">
|
||
<code class="descclassname">Popen.</code><code class="descname">args</code><a class="headerlink" href="#subprocess.Popen.args" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>The <em>args</em> argument as it was passed to <a class="reference internal" href="#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">Popen</span></code></a> – a
|
||
sequence of program arguments or else a single string.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="subprocess.Popen.stdin">
|
||
<code class="descclassname">Popen.</code><code class="descname">stdin</code><a class="headerlink" href="#subprocess.Popen.stdin" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>If the <em>stdin</em> argument was <a class="reference internal" href="#subprocess.PIPE" title="subprocess.PIPE"><code class="xref py py-data docutils literal notranslate"><span class="pre">PIPE</span></code></a>, this attribute is a writeable
|
||
stream object as returned by <a class="reference internal" href="functions.html#open" title="open"><code class="xref py py-func docutils literal notranslate"><span class="pre">open()</span></code></a>. If the <em>encoding</em> or <em>errors</em>
|
||
arguments were specified or the <em>universal_newlines</em> argument was <code class="docutils literal notranslate"><span class="pre">True</span></code>,
|
||
the stream is a text stream, otherwise it is a byte stream. If the <em>stdin</em>
|
||
argument was not <a class="reference internal" href="#subprocess.PIPE" title="subprocess.PIPE"><code class="xref py py-data docutils literal notranslate"><span class="pre">PIPE</span></code></a>, this attribute is <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="subprocess.Popen.stdout">
|
||
<code class="descclassname">Popen.</code><code class="descname">stdout</code><a class="headerlink" href="#subprocess.Popen.stdout" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>If the <em>stdout</em> argument was <a class="reference internal" href="#subprocess.PIPE" title="subprocess.PIPE"><code class="xref py py-data docutils literal notranslate"><span class="pre">PIPE</span></code></a>, this attribute is a readable
|
||
stream object as returned by <a class="reference internal" href="functions.html#open" title="open"><code class="xref py py-func docutils literal notranslate"><span class="pre">open()</span></code></a>. Reading from the stream provides
|
||
output from the child process. If the <em>encoding</em> or <em>errors</em> arguments were
|
||
specified or the <em>universal_newlines</em> argument was <code class="docutils literal notranslate"><span class="pre">True</span></code>, the stream is a
|
||
text stream, otherwise it is a byte stream. If the <em>stdout</em> argument was not
|
||
<a class="reference internal" href="#subprocess.PIPE" title="subprocess.PIPE"><code class="xref py py-data docutils literal notranslate"><span class="pre">PIPE</span></code></a>, this attribute is <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="subprocess.Popen.stderr">
|
||
<code class="descclassname">Popen.</code><code class="descname">stderr</code><a class="headerlink" href="#subprocess.Popen.stderr" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>If the <em>stderr</em> argument was <a class="reference internal" href="#subprocess.PIPE" title="subprocess.PIPE"><code class="xref py py-data docutils literal notranslate"><span class="pre">PIPE</span></code></a>, this attribute is a readable
|
||
stream object as returned by <a class="reference internal" href="functions.html#open" title="open"><code class="xref py py-func docutils literal notranslate"><span class="pre">open()</span></code></a>. Reading from the stream provides
|
||
error output from the child process. If the <em>encoding</em> or <em>errors</em> arguments
|
||
were specified or the <em>universal_newlines</em> argument was <code class="docutils literal notranslate"><span class="pre">True</span></code>, the stream
|
||
is a text stream, otherwise it is a byte stream. If the <em>stderr</em> argument was
|
||
not <a class="reference internal" href="#subprocess.PIPE" title="subprocess.PIPE"><code class="xref py py-data docutils literal notranslate"><span class="pre">PIPE</span></code></a>, this attribute is <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<div class="admonition warning">
|
||
<p class="admonition-title">Warning</p>
|
||
<p>Use <a class="reference internal" href="#subprocess.Popen.communicate" title="subprocess.Popen.communicate"><code class="xref py py-meth docutils literal notranslate"><span class="pre">communicate()</span></code></a> rather than <a class="reference internal" href="#subprocess.Popen.stdin" title="subprocess.Popen.stdin"><code class="xref py py-attr docutils literal notranslate"><span class="pre">.stdin.write</span></code></a>,
|
||
<a class="reference internal" href="#subprocess.Popen.stdout" title="subprocess.Popen.stdout"><code class="xref py py-attr docutils literal notranslate"><span class="pre">.stdout.read</span></code></a> or <a class="reference internal" href="#subprocess.Popen.stderr" title="subprocess.Popen.stderr"><code class="xref py py-attr docutils literal notranslate"><span class="pre">.stderr.read</span></code></a> to avoid
|
||
deadlocks due to any of the other OS pipe buffers filling up and blocking the
|
||
child process.</p>
|
||
</div>
|
||
<dl class="attribute">
|
||
<dt id="subprocess.Popen.pid">
|
||
<code class="descclassname">Popen.</code><code class="descname">pid</code><a class="headerlink" href="#subprocess.Popen.pid" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>The process ID of the child process.</p>
|
||
<p>Note that if you set the <em>shell</em> argument to <code class="docutils literal notranslate"><span class="pre">True</span></code>, this is the process ID
|
||
of the spawned shell.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="subprocess.Popen.returncode">
|
||
<code class="descclassname">Popen.</code><code class="descname">returncode</code><a class="headerlink" href="#subprocess.Popen.returncode" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>The child return code, set by <a class="reference internal" href="#subprocess.Popen.poll" title="subprocess.Popen.poll"><code class="xref py py-meth docutils literal notranslate"><span class="pre">poll()</span></code></a> and <a class="reference internal" href="#subprocess.Popen.wait" title="subprocess.Popen.wait"><code class="xref py py-meth docutils literal notranslate"><span class="pre">wait()</span></code></a> (and indirectly
|
||
by <a class="reference internal" href="#subprocess.Popen.communicate" title="subprocess.Popen.communicate"><code class="xref py py-meth docutils literal notranslate"><span class="pre">communicate()</span></code></a>). A <code class="docutils literal notranslate"><span class="pre">None</span></code> value indicates that the process
|
||
hasn’t 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>
|
||
|
||
</div>
|
||
<div class="section" id="windows-popen-helpers">
|
||
<h2>Windows Popen Helpers<a class="headerlink" href="#windows-popen-helpers" title="Permalink to this headline">¶</a></h2>
|
||
<p>The <a class="reference internal" href="#subprocess.STARTUPINFO" title="subprocess.STARTUPINFO"><code class="xref py py-class docutils literal notranslate"><span class="pre">STARTUPINFO</span></code></a> class and following constants are only available
|
||
on Windows.</p>
|
||
<dl class="class">
|
||
<dt id="subprocess.STARTUPINFO">
|
||
<em class="property">class </em><code class="descclassname">subprocess.</code><code class="descname">STARTUPINFO</code><span class="sig-paren">(</span><em>*</em>, <em>dwFlags=0</em>, <em>hStdInput=None</em>, <em>hStdOutput=None</em>, <em>hStdError=None</em>, <em>wShowWindow=0</em>, <em>lpAttributeList=None</em><span class="sig-paren">)</span><a class="headerlink" href="#subprocess.STARTUPINFO" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Partial support of the Windows
|
||
<a class="reference external" href="https://msdn.microsoft.com/en-us/library/ms686331(v=vs.85).aspx">STARTUPINFO</a>
|
||
structure is used for <a class="reference internal" href="#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">Popen</span></code></a> creation. The following attributes can
|
||
be set by passing them as keyword-only arguments.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.7: </span>Keyword-only argument support was added.</p>
|
||
</div>
|
||
<dl class="attribute">
|
||
<dt id="subprocess.STARTUPINFO.dwFlags">
|
||
<code class="descname">dwFlags</code><a class="headerlink" href="#subprocess.STARTUPINFO.dwFlags" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>A bit field that determines whether certain <a class="reference internal" href="#subprocess.STARTUPINFO" title="subprocess.STARTUPINFO"><code class="xref py py-class docutils literal notranslate"><span class="pre">STARTUPINFO</span></code></a>
|
||
attributes are used when the process creates a window.</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">si</span> <span class="o">=</span> <span class="n">subprocess</span><span class="o">.</span><span class="n">STARTUPINFO</span><span class="p">()</span>
|
||
<span class="n">si</span><span class="o">.</span><span class="n">dwFlags</span> <span class="o">=</span> <span class="n">subprocess</span><span class="o">.</span><span class="n">STARTF_USESTDHANDLES</span> <span class="o">|</span> <span class="n">subprocess</span><span class="o">.</span><span class="n">STARTF_USESHOWWINDOW</span>
|
||
</pre></div>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="subprocess.STARTUPINFO.hStdInput">
|
||
<code class="descname">hStdInput</code><a class="headerlink" href="#subprocess.STARTUPINFO.hStdInput" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>If <a class="reference internal" href="#subprocess.STARTUPINFO.dwFlags" title="subprocess.STARTUPINFO.dwFlags"><code class="xref py py-attr docutils literal notranslate"><span class="pre">dwFlags</span></code></a> specifies <a class="reference internal" href="#subprocess.STARTF_USESTDHANDLES" title="subprocess.STARTF_USESTDHANDLES"><code class="xref py py-data docutils literal notranslate"><span class="pre">STARTF_USESTDHANDLES</span></code></a>, this attribute
|
||
is the standard input handle for the process. If
|
||
<a class="reference internal" href="#subprocess.STARTF_USESTDHANDLES" title="subprocess.STARTF_USESTDHANDLES"><code class="xref py py-data docutils literal notranslate"><span class="pre">STARTF_USESTDHANDLES</span></code></a> is not specified, the default for standard
|
||
input is the keyboard buffer.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="subprocess.STARTUPINFO.hStdOutput">
|
||
<code class="descname">hStdOutput</code><a class="headerlink" href="#subprocess.STARTUPINFO.hStdOutput" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>If <a class="reference internal" href="#subprocess.STARTUPINFO.dwFlags" title="subprocess.STARTUPINFO.dwFlags"><code class="xref py py-attr docutils literal notranslate"><span class="pre">dwFlags</span></code></a> specifies <a class="reference internal" href="#subprocess.STARTF_USESTDHANDLES" title="subprocess.STARTF_USESTDHANDLES"><code class="xref py py-data docutils literal notranslate"><span class="pre">STARTF_USESTDHANDLES</span></code></a>, this attribute
|
||
is the standard output handle for the process. Otherwise, this attribute
|
||
is ignored and the default for standard output is the console window’s
|
||
buffer.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="subprocess.STARTUPINFO.hStdError">
|
||
<code class="descname">hStdError</code><a class="headerlink" href="#subprocess.STARTUPINFO.hStdError" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>If <a class="reference internal" href="#subprocess.STARTUPINFO.dwFlags" title="subprocess.STARTUPINFO.dwFlags"><code class="xref py py-attr docutils literal notranslate"><span class="pre">dwFlags</span></code></a> specifies <a class="reference internal" href="#subprocess.STARTF_USESTDHANDLES" title="subprocess.STARTF_USESTDHANDLES"><code class="xref py py-data docutils literal notranslate"><span class="pre">STARTF_USESTDHANDLES</span></code></a>, this attribute
|
||
is the standard error handle for the process. Otherwise, this attribute is
|
||
ignored and the default for standard error is the console window’s buffer.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="subprocess.STARTUPINFO.wShowWindow">
|
||
<code class="descname">wShowWindow</code><a class="headerlink" href="#subprocess.STARTUPINFO.wShowWindow" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>If <a class="reference internal" href="#subprocess.STARTUPINFO.dwFlags" title="subprocess.STARTUPINFO.dwFlags"><code class="xref py py-attr docutils literal notranslate"><span class="pre">dwFlags</span></code></a> specifies <a class="reference internal" href="#subprocess.STARTF_USESHOWWINDOW" title="subprocess.STARTF_USESHOWWINDOW"><code class="xref py py-data docutils literal notranslate"><span class="pre">STARTF_USESHOWWINDOW</span></code></a>, this attribute
|
||
can be any of the values that can be specified in the <code class="docutils literal notranslate"><span class="pre">nCmdShow</span></code>
|
||
parameter for the
|
||
<a class="reference external" href="https://msdn.microsoft.com/en-us/library/ms633548(v=vs.85).aspx">ShowWindow</a>
|
||
function, except for <code class="docutils literal notranslate"><span class="pre">SW_SHOWDEFAULT</span></code>. Otherwise, this attribute is
|
||
ignored.</p>
|
||
<p><a class="reference internal" href="#subprocess.SW_HIDE" title="subprocess.SW_HIDE"><code class="xref py py-data docutils literal notranslate"><span class="pre">SW_HIDE</span></code></a> is provided for this attribute. It is used when
|
||
<a class="reference internal" href="#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">Popen</span></code></a> is called with <code class="docutils literal notranslate"><span class="pre">shell=True</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="subprocess.STARTUPINFO.lpAttributeList">
|
||
<code class="descname">lpAttributeList</code><a class="headerlink" href="#subprocess.STARTUPINFO.lpAttributeList" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>A dictionary of additional attributes for process creation as given in
|
||
<code class="docutils literal notranslate"><span class="pre">STARTUPINFOEX</span></code>, see
|
||
<a class="reference external" href="https://msdn.microsoft.com/en-us/library/windows/desktop/ms686880(v=vs.85).aspx">UpdateProcThreadAttribute</a>.</p>
|
||
<p>Supported attributes:</p>
|
||
<dl>
|
||
<dt><strong>handle_list</strong></dt><dd><p>Sequence of handles that will be inherited. <em>close_fds</em> must be true if
|
||
non-empty.</p>
|
||
<p>The handles must be temporarily made inheritable by
|
||
<a class="reference internal" href="os.html#os.set_handle_inheritable" title="os.set_handle_inheritable"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.set_handle_inheritable()</span></code></a> when passed to the <a class="reference internal" href="#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">Popen</span></code></a>
|
||
constructor, else <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> will be raised with Windows error
|
||
<code class="docutils literal notranslate"><span class="pre">ERROR_INVALID_PARAMETER</span></code> (87).</p>
|
||
<div class="admonition warning">
|
||
<p class="admonition-title">Warning</p>
|
||
<p>In a multithreaded process, use caution to avoid leaking handles
|
||
that are marked inheritable when combining this feature with
|
||
concurrent calls to other process creation functions that inherit
|
||
all handles such as <a class="reference internal" href="os.html#os.system" title="os.system"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.system()</span></code></a>. This also applies to
|
||
standard handle redirection, which temporarily creates inheritable
|
||
handles.</p>
|
||
</div>
|
||
</dd>
|
||
</dl>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.7.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
<div class="section" id="windows-constants">
|
||
<h3>Windows Constants<a class="headerlink" href="#windows-constants" title="Permalink to this headline">¶</a></h3>
|
||
<p>The <a class="reference internal" href="#module-subprocess" title="subprocess: Subprocess management."><code class="xref py py-mod docutils literal notranslate"><span class="pre">subprocess</span></code></a> module exposes the following constants.</p>
|
||
<dl class="data">
|
||
<dt id="subprocess.STD_INPUT_HANDLE">
|
||
<code class="descclassname">subprocess.</code><code class="descname">STD_INPUT_HANDLE</code><a class="headerlink" href="#subprocess.STD_INPUT_HANDLE" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>The standard input device. Initially, this is the console input buffer,
|
||
<code class="docutils literal notranslate"><span class="pre">CONIN$</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="subprocess.STD_OUTPUT_HANDLE">
|
||
<code class="descclassname">subprocess.</code><code class="descname">STD_OUTPUT_HANDLE</code><a class="headerlink" href="#subprocess.STD_OUTPUT_HANDLE" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>The standard output device. Initially, this is the active console screen
|
||
buffer, <code class="docutils literal notranslate"><span class="pre">CONOUT$</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="subprocess.STD_ERROR_HANDLE">
|
||
<code class="descclassname">subprocess.</code><code class="descname">STD_ERROR_HANDLE</code><a class="headerlink" href="#subprocess.STD_ERROR_HANDLE" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>The standard error device. Initially, this is the active console screen
|
||
buffer, <code class="docutils literal notranslate"><span class="pre">CONOUT$</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="subprocess.SW_HIDE">
|
||
<code class="descclassname">subprocess.</code><code class="descname">SW_HIDE</code><a class="headerlink" href="#subprocess.SW_HIDE" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Hides the window. Another window will be activated.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="subprocess.STARTF_USESTDHANDLES">
|
||
<code class="descclassname">subprocess.</code><code class="descname">STARTF_USESTDHANDLES</code><a class="headerlink" href="#subprocess.STARTF_USESTDHANDLES" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Specifies that the <a class="reference internal" href="#subprocess.STARTUPINFO.hStdInput" title="subprocess.STARTUPINFO.hStdInput"><code class="xref py py-attr docutils literal notranslate"><span class="pre">STARTUPINFO.hStdInput</span></code></a>,
|
||
<a class="reference internal" href="#subprocess.STARTUPINFO.hStdOutput" title="subprocess.STARTUPINFO.hStdOutput"><code class="xref py py-attr docutils literal notranslate"><span class="pre">STARTUPINFO.hStdOutput</span></code></a>, and <a class="reference internal" href="#subprocess.STARTUPINFO.hStdError" title="subprocess.STARTUPINFO.hStdError"><code class="xref py py-attr docutils literal notranslate"><span class="pre">STARTUPINFO.hStdError</span></code></a> attributes
|
||
contain additional information.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="subprocess.STARTF_USESHOWWINDOW">
|
||
<code class="descclassname">subprocess.</code><code class="descname">STARTF_USESHOWWINDOW</code><a class="headerlink" href="#subprocess.STARTF_USESHOWWINDOW" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Specifies that the <a class="reference internal" href="#subprocess.STARTUPINFO.wShowWindow" title="subprocess.STARTUPINFO.wShowWindow"><code class="xref py py-attr docutils literal notranslate"><span class="pre">STARTUPINFO.wShowWindow</span></code></a> attribute contains
|
||
additional information.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="subprocess.CREATE_NEW_CONSOLE">
|
||
<code class="descclassname">subprocess.</code><code class="descname">CREATE_NEW_CONSOLE</code><a class="headerlink" href="#subprocess.CREATE_NEW_CONSOLE" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>The new process has a new console, instead of inheriting its parent’s
|
||
console (the default).</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="subprocess.CREATE_NEW_PROCESS_GROUP">
|
||
<code class="descclassname">subprocess.</code><code class="descname">CREATE_NEW_PROCESS_GROUP</code><a class="headerlink" href="#subprocess.CREATE_NEW_PROCESS_GROUP" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>A <a class="reference internal" href="#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">Popen</span></code></a> <code class="docutils literal notranslate"><span class="pre">creationflags</span></code> parameter to specify that a new process
|
||
group will be created. This flag is necessary for using <a class="reference internal" href="os.html#os.kill" title="os.kill"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.kill()</span></code></a>
|
||
on the subprocess.</p>
|
||
<p>This flag is ignored if <a class="reference internal" href="#subprocess.CREATE_NEW_CONSOLE" title="subprocess.CREATE_NEW_CONSOLE"><code class="xref py py-data docutils literal notranslate"><span class="pre">CREATE_NEW_CONSOLE</span></code></a> is specified.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="subprocess.ABOVE_NORMAL_PRIORITY_CLASS">
|
||
<code class="descclassname">subprocess.</code><code class="descname">ABOVE_NORMAL_PRIORITY_CLASS</code><a class="headerlink" href="#subprocess.ABOVE_NORMAL_PRIORITY_CLASS" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>A <a class="reference internal" href="#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">Popen</span></code></a> <code class="docutils literal notranslate"><span class="pre">creationflags</span></code> parameter to specify that a new process
|
||
will have an above average priority.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.7.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="subprocess.BELOW_NORMAL_PRIORITY_CLASS">
|
||
<code class="descclassname">subprocess.</code><code class="descname">BELOW_NORMAL_PRIORITY_CLASS</code><a class="headerlink" href="#subprocess.BELOW_NORMAL_PRIORITY_CLASS" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>A <a class="reference internal" href="#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">Popen</span></code></a> <code class="docutils literal notranslate"><span class="pre">creationflags</span></code> parameter to specify that a new process
|
||
will have a below average priority.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.7.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="subprocess.HIGH_PRIORITY_CLASS">
|
||
<code class="descclassname">subprocess.</code><code class="descname">HIGH_PRIORITY_CLASS</code><a class="headerlink" href="#subprocess.HIGH_PRIORITY_CLASS" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>A <a class="reference internal" href="#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">Popen</span></code></a> <code class="docutils literal notranslate"><span class="pre">creationflags</span></code> parameter to specify that a new process
|
||
will have a high priority.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.7.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="subprocess.IDLE_PRIORITY_CLASS">
|
||
<code class="descclassname">subprocess.</code><code class="descname">IDLE_PRIORITY_CLASS</code><a class="headerlink" href="#subprocess.IDLE_PRIORITY_CLASS" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>A <a class="reference internal" href="#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">Popen</span></code></a> <code class="docutils literal notranslate"><span class="pre">creationflags</span></code> parameter to specify that a new process
|
||
will have an idle (lowest) priority.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.7.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="subprocess.NORMAL_PRIORITY_CLASS">
|
||
<code class="descclassname">subprocess.</code><code class="descname">NORMAL_PRIORITY_CLASS</code><a class="headerlink" href="#subprocess.NORMAL_PRIORITY_CLASS" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>A <a class="reference internal" href="#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">Popen</span></code></a> <code class="docutils literal notranslate"><span class="pre">creationflags</span></code> parameter to specify that a new process
|
||
will have an normal priority. (default)</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.7.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="subprocess.REALTIME_PRIORITY_CLASS">
|
||
<code class="descclassname">subprocess.</code><code class="descname">REALTIME_PRIORITY_CLASS</code><a class="headerlink" href="#subprocess.REALTIME_PRIORITY_CLASS" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>A <a class="reference internal" href="#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">Popen</span></code></a> <code class="docutils literal notranslate"><span class="pre">creationflags</span></code> parameter to specify that a new process
|
||
will have realtime priority.
|
||
You should almost never use REALTIME_PRIORITY_CLASS, because this interrupts
|
||
system threads that manage mouse input, keyboard input, and background disk
|
||
flushing. This class can be appropriate for applications that “talk” directly
|
||
to hardware or that perform brief tasks that should have limited interruptions.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.7.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="subprocess.CREATE_NO_WINDOW">
|
||
<code class="descclassname">subprocess.</code><code class="descname">CREATE_NO_WINDOW</code><a class="headerlink" href="#subprocess.CREATE_NO_WINDOW" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>A <a class="reference internal" href="#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">Popen</span></code></a> <code class="docutils literal notranslate"><span class="pre">creationflags</span></code> parameter to specify that a new process
|
||
will not create a window.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.7.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="subprocess.DETACHED_PROCESS">
|
||
<code class="descclassname">subprocess.</code><code class="descname">DETACHED_PROCESS</code><a class="headerlink" href="#subprocess.DETACHED_PROCESS" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>A <a class="reference internal" href="#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">Popen</span></code></a> <code class="docutils literal notranslate"><span class="pre">creationflags</span></code> parameter to specify that a new process
|
||
will not inherit its parent’s console.
|
||
This value cannot be used with CREATE_NEW_CONSOLE.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.7.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="subprocess.CREATE_DEFAULT_ERROR_MODE">
|
||
<code class="descclassname">subprocess.</code><code class="descname">CREATE_DEFAULT_ERROR_MODE</code><a class="headerlink" href="#subprocess.CREATE_DEFAULT_ERROR_MODE" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>A <a class="reference internal" href="#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">Popen</span></code></a> <code class="docutils literal notranslate"><span class="pre">creationflags</span></code> parameter to specify that a new process
|
||
does not inherit the error mode of the calling process. Instead, the new
|
||
process gets the default error mode.
|
||
This feature is particularly useful for multithreaded shell applications
|
||
that run with hard errors disabled.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.7.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="subprocess.CREATE_BREAKAWAY_FROM_JOB">
|
||
<code class="descclassname">subprocess.</code><code class="descname">CREATE_BREAKAWAY_FROM_JOB</code><a class="headerlink" href="#subprocess.CREATE_BREAKAWAY_FROM_JOB" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>A <a class="reference internal" href="#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">Popen</span></code></a> <code class="docutils literal notranslate"><span class="pre">creationflags</span></code> parameter to specify that a new process
|
||
is not associated with the job.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.7.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
</div>
|
||
</div>
|
||
<div class="section" id="older-high-level-api">
|
||
<span id="call-function-trio"></span><h2>Older high-level API<a class="headerlink" href="#older-high-level-api" title="Permalink to this headline">¶</a></h2>
|
||
<p>Prior to Python 3.5, these three functions comprised the high level API to
|
||
subprocess. You can now use <a class="reference internal" href="#subprocess.run" title="subprocess.run"><code class="xref py py-func docutils literal notranslate"><span class="pre">run()</span></code></a> in many cases, but lots of existing code
|
||
calls these functions.</p>
|
||
<dl class="function">
|
||
<dt id="subprocess.call">
|
||
<code class="descclassname">subprocess.</code><code class="descname">call</code><span class="sig-paren">(</span><em>args</em>, <em>*</em>, <em>stdin=None</em>, <em>stdout=None</em>, <em>stderr=None</em>, <em>shell=False</em>, <em>cwd=None</em>, <em>timeout=None</em><span class="sig-paren">)</span><a class="headerlink" href="#subprocess.call" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Run the command described by <em>args</em>. Wait for command to complete, then
|
||
return the <a class="reference internal" href="#subprocess.Popen.returncode" title="subprocess.Popen.returncode"><code class="xref py py-attr docutils literal notranslate"><span class="pre">returncode</span></code></a> attribute.</p>
|
||
<p>Code needing to capture stdout or stderr should use <a class="reference internal" href="#subprocess.run" title="subprocess.run"><code class="xref py py-func docutils literal notranslate"><span class="pre">run()</span></code></a> instead:</p>
|
||
<blockquote>
|
||
<div><p>run(…).returncode</p>
|
||
</div></blockquote>
|
||
<p>To suppress stdout or stderr, supply a value of <a class="reference internal" href="#subprocess.DEVNULL" title="subprocess.DEVNULL"><code class="xref py py-data docutils literal notranslate"><span class="pre">DEVNULL</span></code></a>.</p>
|
||
<p>The arguments shown above are merely some common ones.
|
||
The full function signature is the
|
||
same as that of the <a class="reference internal" href="#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">Popen</span></code></a> constructor - this function passes all
|
||
supplied arguments other than <em>timeout</em> directly through to that interface.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>Do not use <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> with this
|
||
function. The child process will block if it generates enough
|
||
output to a pipe to fill up the OS pipe buffer as the pipes are
|
||
not being read from.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.3: </span><em>timeout</em> was added.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="subprocess.check_call">
|
||
<code class="descclassname">subprocess.</code><code class="descname">check_call</code><span class="sig-paren">(</span><em>args</em>, <em>*</em>, <em>stdin=None</em>, <em>stdout=None</em>, <em>stderr=None</em>, <em>shell=False</em>, <em>cwd=None</em>, <em>timeout=None</em><span class="sig-paren">)</span><a class="headerlink" href="#subprocess.check_call" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Run command with arguments. Wait for command to complete. If the return
|
||
code was zero then return, otherwise raise <a class="reference internal" href="#subprocess.CalledProcessError" title="subprocess.CalledProcessError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">CalledProcessError</span></code></a>. The
|
||
<a class="reference internal" href="#subprocess.CalledProcessError" title="subprocess.CalledProcessError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">CalledProcessError</span></code></a> object will have the return code in the
|
||
<a class="reference internal" href="#subprocess.CalledProcessError.returncode" title="subprocess.CalledProcessError.returncode"><code class="xref py py-attr docutils literal notranslate"><span class="pre">returncode</span></code></a> attribute.</p>
|
||
<p>Code needing to capture stdout or stderr should use <a class="reference internal" href="#subprocess.run" title="subprocess.run"><code class="xref py py-func docutils literal notranslate"><span class="pre">run()</span></code></a> instead:</p>
|
||
<blockquote>
|
||
<div><p>run(…, check=True)</p>
|
||
</div></blockquote>
|
||
<p>To suppress stdout or stderr, supply a value of <a class="reference internal" href="#subprocess.DEVNULL" title="subprocess.DEVNULL"><code class="xref py py-data docutils literal notranslate"><span class="pre">DEVNULL</span></code></a>.</p>
|
||
<p>The arguments shown above are merely some common ones.
|
||
The full function signature is the
|
||
same as that of the <a class="reference internal" href="#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">Popen</span></code></a> constructor - this function passes all
|
||
supplied arguments other than <em>timeout</em> directly through to that interface.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>Do not use <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> with this
|
||
function. The child process will block if it generates enough
|
||
output to a pipe to fill up the OS pipe buffer as the pipes are
|
||
not being read from.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.3: </span><em>timeout</em> was added.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="subprocess.check_output">
|
||
<code class="descclassname">subprocess.</code><code class="descname">check_output</code><span class="sig-paren">(</span><em>args</em>, <em>*</em>, <em>stdin=None</em>, <em>stderr=None</em>, <em>shell=False</em>, <em>cwd=None</em>, <em>encoding=None</em>, <em>errors=None</em>, <em>universal_newlines=None</em>, <em>timeout=None</em>, <em>text=None</em><span class="sig-paren">)</span><a class="headerlink" href="#subprocess.check_output" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Run command with arguments and return its output.</p>
|
||
<p>If the return code was non-zero it raises a <a class="reference internal" href="#subprocess.CalledProcessError" title="subprocess.CalledProcessError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">CalledProcessError</span></code></a>. The
|
||
<a class="reference internal" href="#subprocess.CalledProcessError" title="subprocess.CalledProcessError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">CalledProcessError</span></code></a> object will have the return code in the
|
||
<a class="reference internal" href="#subprocess.CalledProcessError.returncode" title="subprocess.CalledProcessError.returncode"><code class="xref py py-attr docutils literal notranslate"><span class="pre">returncode</span></code></a> attribute and any output in the
|
||
<a class="reference internal" href="#subprocess.CalledProcessError.output" title="subprocess.CalledProcessError.output"><code class="xref py py-attr docutils literal notranslate"><span class="pre">output</span></code></a> attribute.</p>
|
||
<p>This is equivalent to:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">run</span><span class="p">(</span><span class="o">...</span><span class="p">,</span> <span class="n">check</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">stdout</span><span class="o">=</span><span class="n">PIPE</span><span class="p">)</span><span class="o">.</span><span class="n">stdout</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The arguments shown above are merely some common ones.
|
||
The full function signature is largely the same as that of <a class="reference internal" href="#subprocess.run" title="subprocess.run"><code class="xref py py-func docutils literal notranslate"><span class="pre">run()</span></code></a> -
|
||
most arguments are passed directly through to that interface.
|
||
However, explicitly passing <code class="docutils literal notranslate"><span class="pre">input=None</span></code> to inherit the parent’s
|
||
standard input file handle is not supported.</p>
|
||
<p>By default, this function will return the data as encoded bytes. The actual
|
||
encoding of the output data may depend on the command being invoked, so the
|
||
decoding to text will often need to be handled at the application level.</p>
|
||
<p>This behaviour may be overridden by setting <em>text</em>, <em>encoding</em>, <em>errors</em>,
|
||
or <em>universal_newlines</em> to <code class="docutils literal notranslate"><span class="pre">True</span></code> as described in
|
||
<a class="reference internal" href="#frequently-used-arguments"><span class="std std-ref">Frequently Used Arguments</span></a> and <a class="reference internal" href="#subprocess.run" title="subprocess.run"><code class="xref py py-func docutils literal notranslate"><span class="pre">run()</span></code></a>.</p>
|
||
<p>To also capture standard error in the result, use
|
||
<code class="docutils literal notranslate"><span class="pre">stderr=subprocess.STDOUT</span></code>:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">subprocess</span><span class="o">.</span><span class="n">check_output</span><span class="p">(</span>
|
||
<span class="gp">... </span> <span class="s2">"ls non_existent_file; exit 0"</span><span class="p">,</span>
|
||
<span class="gp">... </span> <span class="n">stderr</span><span class="o">=</span><span class="n">subprocess</span><span class="o">.</span><span class="n">STDOUT</span><span class="p">,</span>
|
||
<span class="gp">... </span> <span class="n">shell</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
|
||
<span class="go">'ls: non_existent_file: No such file or directory\n'</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.1.</span></p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.3: </span><em>timeout</em> was added.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.4: </span>Support for the <em>input</em> keyword argument was added.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span><em>encoding</em> and <em>errors</em> were added. See <a class="reference internal" href="#subprocess.run" title="subprocess.run"><code class="xref py py-func docutils literal notranslate"><span class="pre">run()</span></code></a> for details.</p>
|
||
</div>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.7: </span><em>text</em> was added as a more readable alias for <em>universal_newlines</em>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
</div>
|
||
<div class="section" id="replacing-older-functions-with-the-subprocess-module">
|
||
<span id="subprocess-replacements"></span><h2>Replacing Older Functions with the <a class="reference internal" href="#module-subprocess" title="subprocess: Subprocess management."><code class="xref py py-mod docutils literal notranslate"><span class="pre">subprocess</span></code></a> Module<a class="headerlink" href="#replacing-older-functions-with-the-subprocess-module" title="Permalink to this headline">¶</a></h2>
|
||
<p>In this section, “a becomes b” means that b can be used as a replacement for a.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>All “a” functions in this section fail (more or less) silently if the
|
||
executed program cannot be found; the “b” replacements raise <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a>
|
||
instead.</p>
|
||
<p>In addition, the replacements using <a class="reference internal" href="#subprocess.check_output" title="subprocess.check_output"><code class="xref py py-func docutils literal notranslate"><span class="pre">check_output()</span></code></a> will fail with a
|
||
<a class="reference internal" href="#subprocess.CalledProcessError" title="subprocess.CalledProcessError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">CalledProcessError</span></code></a> if the requested operation produces a non-zero
|
||
return code. The output is still available as the
|
||
<a class="reference internal" href="#subprocess.CalledProcessError.output" title="subprocess.CalledProcessError.output"><code class="xref py py-attr docutils literal notranslate"><span class="pre">output</span></code></a> attribute of the raised exception.</p>
|
||
</div>
|
||
<p>In the following examples, we assume that the relevant functions have already
|
||
been imported from the <a class="reference internal" href="#module-subprocess" title="subprocess: Subprocess management."><code class="xref py py-mod docutils literal notranslate"><span class="pre">subprocess</span></code></a> module.</p>
|
||
<div class="section" id="replacing-bin-sh-shell-backquote">
|
||
<h3>Replacing /bin/sh shell backquote<a class="headerlink" href="#replacing-bin-sh-shell-backquote" title="Permalink to this headline">¶</a></h3>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nv">output</span><span class="o">=</span><span class="sb">`</span>mycmd myarg<span class="sb">`</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>becomes:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">output</span> <span class="o">=</span> <span class="n">check_output</span><span class="p">([</span><span class="s2">"mycmd"</span><span class="p">,</span> <span class="s2">"myarg"</span><span class="p">])</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="replacing-shell-pipeline">
|
||
<h3>Replacing shell pipeline<a class="headerlink" href="#replacing-shell-pipeline" title="Permalink to this headline">¶</a></h3>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nv">output</span><span class="o">=</span><span class="sb">`</span>dmesg <span class="p">|</span> grep hda<span class="sb">`</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>becomes:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">p1</span> <span class="o">=</span> <span class="n">Popen</span><span class="p">([</span><span class="s2">"dmesg"</span><span class="p">],</span> <span class="n">stdout</span><span class="o">=</span><span class="n">PIPE</span><span class="p">)</span>
|
||
<span class="n">p2</span> <span class="o">=</span> <span class="n">Popen</span><span class="p">([</span><span class="s2">"grep"</span><span class="p">,</span> <span class="s2">"hda"</span><span class="p">],</span> <span class="n">stdin</span><span class="o">=</span><span class="n">p1</span><span class="o">.</span><span class="n">stdout</span><span class="p">,</span> <span class="n">stdout</span><span class="o">=</span><span class="n">PIPE</span><span class="p">)</span>
|
||
<span class="n">p1</span><span class="o">.</span><span class="n">stdout</span><span class="o">.</span><span class="n">close</span><span class="p">()</span> <span class="c1"># Allow p1 to receive a SIGPIPE if p2 exits.</span>
|
||
<span class="n">output</span> <span class="o">=</span> <span class="n">p2</span><span class="o">.</span><span class="n">communicate</span><span class="p">()[</span><span class="mi">0</span><span class="p">]</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The p1.stdout.close() call after starting the p2 is important in order for p1
|
||
to receive a SIGPIPE if p2 exits before p1.</p>
|
||
<p>Alternatively, for trusted input, the shell’s own pipeline support may still
|
||
be used directly:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nv">output</span><span class="o">=</span><span class="sb">`</span>dmesg <span class="p">|</span> grep hda<span class="sb">`</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>becomes:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">output</span><span class="o">=</span><span class="n">check_output</span><span class="p">(</span><span class="s2">"dmesg | grep hda"</span><span class="p">,</span> <span class="n">shell</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="replacing-os-system">
|
||
<h3>Replacing <a class="reference internal" href="os.html#os.system" title="os.system"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.system()</span></code></a><a class="headerlink" href="#replacing-os-system" title="Permalink to this headline">¶</a></h3>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">sts</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">system</span><span class="p">(</span><span class="s2">"mycmd"</span> <span class="o">+</span> <span class="s2">" myarg"</span><span class="p">)</span>
|
||
<span class="c1"># becomes</span>
|
||
<span class="n">sts</span> <span class="o">=</span> <span class="n">call</span><span class="p">(</span><span class="s2">"mycmd"</span> <span class="o">+</span> <span class="s2">" myarg"</span><span class="p">,</span> <span class="n">shell</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Notes:</p>
|
||
<ul class="simple">
|
||
<li><p>Calling the program through the shell is usually not required.</p></li>
|
||
</ul>
|
||
<p>A more realistic example would look like this:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">try</span><span class="p">:</span>
|
||
<span class="n">retcode</span> <span class="o">=</span> <span class="n">call</span><span class="p">(</span><span class="s2">"mycmd"</span> <span class="o">+</span> <span class="s2">" myarg"</span><span class="p">,</span> <span class="n">shell</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
|
||
<span class="k">if</span> <span class="n">retcode</span> <span class="o"><</span> <span class="mi">0</span><span class="p">:</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="s2">"Child was terminated by signal"</span><span class="p">,</span> <span class="o">-</span><span class="n">retcode</span><span class="p">,</span> <span class="n">file</span><span class="o">=</span><span class="n">sys</span><span class="o">.</span><span class="n">stderr</span><span class="p">)</span>
|
||
<span class="k">else</span><span class="p">:</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="s2">"Child returned"</span><span class="p">,</span> <span class="n">retcode</span><span class="p">,</span> <span class="n">file</span><span class="o">=</span><span class="n">sys</span><span class="o">.</span><span class="n">stderr</span><span class="p">)</span>
|
||
<span class="k">except</span> <span class="ne">OSError</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="s2">"Execution failed:"</span><span class="p">,</span> <span class="n">e</span><span class="p">,</span> <span class="n">file</span><span class="o">=</span><span class="n">sys</span><span class="o">.</span><span class="n">stderr</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="replacing-the-os-spawn-family">
|
||
<h3>Replacing the <a class="reference internal" href="os.html#os.spawnl" title="os.spawnl"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.spawn</span></code></a> family<a class="headerlink" href="#replacing-the-os-spawn-family" title="Permalink to this headline">¶</a></h3>
|
||
<p>P_NOWAIT example:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">pid</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">spawnlp</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">P_NOWAIT</span><span class="p">,</span> <span class="s2">"/bin/mycmd"</span><span class="p">,</span> <span class="s2">"mycmd"</span><span class="p">,</span> <span class="s2">"myarg"</span><span class="p">)</span>
|
||
<span class="o">==></span>
|
||
<span class="n">pid</span> <span class="o">=</span> <span class="n">Popen</span><span class="p">([</span><span class="s2">"/bin/mycmd"</span><span class="p">,</span> <span class="s2">"myarg"</span><span class="p">])</span><span class="o">.</span><span class="n">pid</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>P_WAIT example:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">retcode</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">spawnlp</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">P_WAIT</span><span class="p">,</span> <span class="s2">"/bin/mycmd"</span><span class="p">,</span> <span class="s2">"mycmd"</span><span class="p">,</span> <span class="s2">"myarg"</span><span class="p">)</span>
|
||
<span class="o">==></span>
|
||
<span class="n">retcode</span> <span class="o">=</span> <span class="n">call</span><span class="p">([</span><span class="s2">"/bin/mycmd"</span><span class="p">,</span> <span class="s2">"myarg"</span><span class="p">])</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Vector example:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">os</span><span class="o">.</span><span class="n">spawnvp</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">P_NOWAIT</span><span class="p">,</span> <span class="n">path</span><span class="p">,</span> <span class="n">args</span><span class="p">)</span>
|
||
<span class="o">==></span>
|
||
<span class="n">Popen</span><span class="p">([</span><span class="n">path</span><span class="p">]</span> <span class="o">+</span> <span class="n">args</span><span class="p">[</span><span class="mi">1</span><span class="p">:])</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Environment example:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">os</span><span class="o">.</span><span class="n">spawnlpe</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">P_NOWAIT</span><span class="p">,</span> <span class="s2">"/bin/mycmd"</span><span class="p">,</span> <span class="s2">"mycmd"</span><span class="p">,</span> <span class="s2">"myarg"</span><span class="p">,</span> <span class="n">env</span><span class="p">)</span>
|
||
<span class="o">==></span>
|
||
<span class="n">Popen</span><span class="p">([</span><span class="s2">"/bin/mycmd"</span><span class="p">,</span> <span class="s2">"myarg"</span><span class="p">],</span> <span class="n">env</span><span class="o">=</span><span class="p">{</span><span class="s2">"PATH"</span><span class="p">:</span> <span class="s2">"/usr/bin"</span><span class="p">})</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="replacing-os-popen-os-popen2-os-popen3">
|
||
<h3>Replacing <a class="reference internal" href="os.html#os.popen" title="os.popen"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.popen()</span></code></a>, <code class="xref py py-func docutils literal notranslate"><span class="pre">os.popen2()</span></code>, <code class="xref py py-func docutils literal notranslate"><span class="pre">os.popen3()</span></code><a class="headerlink" href="#replacing-os-popen-os-popen2-os-popen3" title="Permalink to this headline">¶</a></h3>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="p">(</span><span class="n">child_stdin</span><span class="p">,</span> <span class="n">child_stdout</span><span class="p">)</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">popen2</span><span class="p">(</span><span class="n">cmd</span><span class="p">,</span> <span class="n">mode</span><span class="p">,</span> <span class="n">bufsize</span><span class="p">)</span>
|
||
<span class="o">==></span>
|
||
<span class="n">p</span> <span class="o">=</span> <span class="n">Popen</span><span class="p">(</span><span class="n">cmd</span><span class="p">,</span> <span class="n">shell</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">bufsize</span><span class="o">=</span><span class="n">bufsize</span><span class="p">,</span>
|
||
<span class="n">stdin</span><span class="o">=</span><span class="n">PIPE</span><span class="p">,</span> <span class="n">stdout</span><span class="o">=</span><span class="n">PIPE</span><span class="p">,</span> <span class="n">close_fds</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
|
||
<span class="p">(</span><span class="n">child_stdin</span><span class="p">,</span> <span class="n">child_stdout</span><span class="p">)</span> <span class="o">=</span> <span class="p">(</span><span class="n">p</span><span class="o">.</span><span class="n">stdin</span><span class="p">,</span> <span class="n">p</span><span class="o">.</span><span class="n">stdout</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="p">(</span><span class="n">child_stdin</span><span class="p">,</span>
|
||
<span class="n">child_stdout</span><span class="p">,</span>
|
||
<span class="n">child_stderr</span><span class="p">)</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">popen3</span><span class="p">(</span><span class="n">cmd</span><span class="p">,</span> <span class="n">mode</span><span class="p">,</span> <span class="n">bufsize</span><span class="p">)</span>
|
||
<span class="o">==></span>
|
||
<span class="n">p</span> <span class="o">=</span> <span class="n">Popen</span><span class="p">(</span><span class="n">cmd</span><span class="p">,</span> <span class="n">shell</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">bufsize</span><span class="o">=</span><span class="n">bufsize</span><span class="p">,</span>
|
||
<span class="n">stdin</span><span class="o">=</span><span class="n">PIPE</span><span class="p">,</span> <span class="n">stdout</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">PIPE</span><span class="p">,</span> <span class="n">close_fds</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
|
||
<span class="p">(</span><span class="n">child_stdin</span><span class="p">,</span>
|
||
<span class="n">child_stdout</span><span class="p">,</span>
|
||
<span class="n">child_stderr</span><span class="p">)</span> <span class="o">=</span> <span class="p">(</span><span class="n">p</span><span class="o">.</span><span class="n">stdin</span><span class="p">,</span> <span class="n">p</span><span class="o">.</span><span class="n">stdout</span><span class="p">,</span> <span class="n">p</span><span class="o">.</span><span class="n">stderr</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="p">(</span><span class="n">child_stdin</span><span class="p">,</span> <span class="n">child_stdout_and_stderr</span><span class="p">)</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">popen4</span><span class="p">(</span><span class="n">cmd</span><span class="p">,</span> <span class="n">mode</span><span class="p">,</span> <span class="n">bufsize</span><span class="p">)</span>
|
||
<span class="o">==></span>
|
||
<span class="n">p</span> <span class="o">=</span> <span class="n">Popen</span><span class="p">(</span><span class="n">cmd</span><span class="p">,</span> <span class="n">shell</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">bufsize</span><span class="o">=</span><span class="n">bufsize</span><span class="p">,</span>
|
||
<span class="n">stdin</span><span class="o">=</span><span class="n">PIPE</span><span class="p">,</span> <span class="n">stdout</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">STDOUT</span><span class="p">,</span> <span class="n">close_fds</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
|
||
<span class="p">(</span><span class="n">child_stdin</span><span class="p">,</span> <span class="n">child_stdout_and_stderr</span><span class="p">)</span> <span class="o">=</span> <span class="p">(</span><span class="n">p</span><span class="o">.</span><span class="n">stdin</span><span class="p">,</span> <span class="n">p</span><span class="o">.</span><span class="n">stdout</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Return code handling translates as follows:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">pipe</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">popen</span><span class="p">(</span><span class="n">cmd</span><span class="p">,</span> <span class="s1">'w'</span><span class="p">)</span>
|
||
<span class="o">...</span>
|
||
<span class="n">rc</span> <span class="o">=</span> <span class="n">pipe</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
|
||
<span class="k">if</span> <span class="n">rc</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span> <span class="ow">and</span> <span class="n">rc</span> <span class="o">>></span> <span class="mi">8</span><span class="p">:</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="s2">"There were some errors"</span><span class="p">)</span>
|
||
<span class="o">==></span>
|
||
<span class="n">process</span> <span class="o">=</span> <span class="n">Popen</span><span class="p">(</span><span class="n">cmd</span><span class="p">,</span> <span class="n">stdin</span><span class="o">=</span><span class="n">PIPE</span><span class="p">)</span>
|
||
<span class="o">...</span>
|
||
<span class="n">process</span><span class="o">.</span><span class="n">stdin</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
|
||
<span class="k">if</span> <span class="n">process</span><span class="o">.</span><span class="n">wait</span><span class="p">()</span> <span class="o">!=</span> <span class="mi">0</span><span class="p">:</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="s2">"There were some errors"</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="replacing-functions-from-the-popen2-module">
|
||
<h3>Replacing functions from the <code class="xref py py-mod docutils literal notranslate"><span class="pre">popen2</span></code> module<a class="headerlink" href="#replacing-functions-from-the-popen2-module" title="Permalink to this headline">¶</a></h3>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>If the cmd argument to popen2 functions is a string, the command is executed
|
||
through /bin/sh. If it is a list, the command is directly executed.</p>
|
||
</div>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="p">(</span><span class="n">child_stdout</span><span class="p">,</span> <span class="n">child_stdin</span><span class="p">)</span> <span class="o">=</span> <span class="n">popen2</span><span class="o">.</span><span class="n">popen2</span><span class="p">(</span><span class="s2">"somestring"</span><span class="p">,</span> <span class="n">bufsize</span><span class="p">,</span> <span class="n">mode</span><span class="p">)</span>
|
||
<span class="o">==></span>
|
||
<span class="n">p</span> <span class="o">=</span> <span class="n">Popen</span><span class="p">(</span><span class="s2">"somestring"</span><span class="p">,</span> <span class="n">shell</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">bufsize</span><span class="o">=</span><span class="n">bufsize</span><span class="p">,</span>
|
||
<span class="n">stdin</span><span class="o">=</span><span class="n">PIPE</span><span class="p">,</span> <span class="n">stdout</span><span class="o">=</span><span class="n">PIPE</span><span class="p">,</span> <span class="n">close_fds</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
|
||
<span class="p">(</span><span class="n">child_stdout</span><span class="p">,</span> <span class="n">child_stdin</span><span class="p">)</span> <span class="o">=</span> <span class="p">(</span><span class="n">p</span><span class="o">.</span><span class="n">stdout</span><span class="p">,</span> <span class="n">p</span><span class="o">.</span><span class="n">stdin</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="p">(</span><span class="n">child_stdout</span><span class="p">,</span> <span class="n">child_stdin</span><span class="p">)</span> <span class="o">=</span> <span class="n">popen2</span><span class="o">.</span><span class="n">popen2</span><span class="p">([</span><span class="s2">"mycmd"</span><span class="p">,</span> <span class="s2">"myarg"</span><span class="p">],</span> <span class="n">bufsize</span><span class="p">,</span> <span class="n">mode</span><span class="p">)</span>
|
||
<span class="o">==></span>
|
||
<span class="n">p</span> <span class="o">=</span> <span class="n">Popen</span><span class="p">([</span><span class="s2">"mycmd"</span><span class="p">,</span> <span class="s2">"myarg"</span><span class="p">],</span> <span class="n">bufsize</span><span class="o">=</span><span class="n">bufsize</span><span class="p">,</span>
|
||
<span class="n">stdin</span><span class="o">=</span><span class="n">PIPE</span><span class="p">,</span> <span class="n">stdout</span><span class="o">=</span><span class="n">PIPE</span><span class="p">,</span> <span class="n">close_fds</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
|
||
<span class="p">(</span><span class="n">child_stdout</span><span class="p">,</span> <span class="n">child_stdin</span><span class="p">)</span> <span class="o">=</span> <span class="p">(</span><span class="n">p</span><span class="o">.</span><span class="n">stdout</span><span class="p">,</span> <span class="n">p</span><span class="o">.</span><span class="n">stdin</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p><code class="xref py py-class docutils literal notranslate"><span class="pre">popen2.Popen3</span></code> and <code class="xref py py-class docutils literal notranslate"><span class="pre">popen2.Popen4</span></code> basically work as
|
||
<a class="reference internal" href="#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">subprocess.Popen</span></code></a>, except that:</p>
|
||
<ul class="simple">
|
||
<li><p><a class="reference internal" href="#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">Popen</span></code></a> raises an exception if the execution fails.</p></li>
|
||
<li><p>The <em>capturestderr</em> argument is replaced with the <em>stderr</em> argument.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">stdin=PIPE</span></code> and <code class="docutils literal notranslate"><span class="pre">stdout=PIPE</span></code> must be specified.</p></li>
|
||
<li><p>popen2 closes all file descriptors by default, but you have to specify
|
||
<code class="docutils literal notranslate"><span class="pre">close_fds=True</span></code> with <a class="reference internal" href="#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">Popen</span></code></a> to guarantee this behavior on
|
||
all platforms or past Python versions.</p></li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="legacy-shell-invocation-functions">
|
||
<h2>Legacy Shell Invocation Functions<a class="headerlink" href="#legacy-shell-invocation-functions" title="Permalink to this headline">¶</a></h2>
|
||
<p>This module also provides the following legacy functions from the 2.x
|
||
<code class="docutils literal notranslate"><span class="pre">commands</span></code> module. These operations implicitly invoke the system shell and
|
||
none of the guarantees described above regarding security and exception
|
||
handling consistency are valid for these functions.</p>
|
||
<dl class="function">
|
||
<dt id="subprocess.getstatusoutput">
|
||
<code class="descclassname">subprocess.</code><code class="descname">getstatusoutput</code><span class="sig-paren">(</span><em>cmd</em><span class="sig-paren">)</span><a class="headerlink" href="#subprocess.getstatusoutput" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return <code class="docutils literal notranslate"><span class="pre">(exitcode,</span> <span class="pre">output)</span></code> of executing <em>cmd</em> in a shell.</p>
|
||
<p>Execute the string <em>cmd</em> in a shell with <code class="xref py py-meth docutils literal notranslate"><span class="pre">Popen.check_output()</span></code> and
|
||
return a 2-tuple <code class="docutils literal notranslate"><span class="pre">(exitcode,</span> <span class="pre">output)</span></code>. The locale encoding is used;
|
||
see the notes on <a class="reference internal" href="#frequently-used-arguments"><span class="std std-ref">Frequently Used Arguments</span></a> for more details.</p>
|
||
<p>A trailing newline is stripped from the output.
|
||
The exit code for the command can be interpreted as the return code
|
||
of subprocess. Example:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">subprocess</span><span class="o">.</span><span class="n">getstatusoutput</span><span class="p">(</span><span class="s1">'ls /bin/ls'</span><span class="p">)</span>
|
||
<span class="go">(0, '/bin/ls')</span>
|
||
<span class="gp">>>> </span><span class="n">subprocess</span><span class="o">.</span><span class="n">getstatusoutput</span><span class="p">(</span><span class="s1">'cat /bin/junk'</span><span class="p">)</span>
|
||
<span class="go">(1, 'cat: /bin/junk: No such file or directory')</span>
|
||
<span class="gp">>>> </span><span class="n">subprocess</span><span class="o">.</span><span class="n">getstatusoutput</span><span class="p">(</span><span class="s1">'/bin/junk'</span><span class="p">)</span>
|
||
<span class="go">(127, 'sh: /bin/junk: not found')</span>
|
||
<span class="gp">>>> </span><span class="n">subprocess</span><span class="o">.</span><span class="n">getstatusoutput</span><span class="p">(</span><span class="s1">'/bin/kill $$'</span><span class="p">)</span>
|
||
<span class="go">(-15, '')</span>
|
||
</pre></div>
|
||
</div>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: POSIX & Windows.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.3.4: </span>Windows support was added.</p>
|
||
<p>The function now returns (exitcode, output) instead of (status, output)
|
||
as it did in Python 3.3.3 and earlier. exitcode has the same value as
|
||
<a class="reference internal" href="#subprocess.Popen.returncode" title="subprocess.Popen.returncode"><code class="xref py py-attr docutils literal notranslate"><span class="pre">returncode</span></code></a>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="subprocess.getoutput">
|
||
<code class="descclassname">subprocess.</code><code class="descname">getoutput</code><span class="sig-paren">(</span><em>cmd</em><span class="sig-paren">)</span><a class="headerlink" href="#subprocess.getoutput" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return output (stdout and stderr) of executing <em>cmd</em> in a shell.</p>
|
||
<p>Like <a class="reference internal" href="#subprocess.getstatusoutput" title="subprocess.getstatusoutput"><code class="xref py py-func docutils literal notranslate"><span class="pre">getstatusoutput()</span></code></a>, except the exit code is ignored and the return
|
||
value is a string containing the command’s output. Example:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">subprocess</span><span class="o">.</span><span class="n">getoutput</span><span class="p">(</span><span class="s1">'ls /bin/ls'</span><span class="p">)</span>
|
||
<span class="go">'/bin/ls'</span>
|
||
</pre></div>
|
||
</div>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: POSIX & Windows.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.3.4: </span>Windows support added</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
</div>
|
||
<div class="section" id="notes">
|
||
<h2>Notes<a class="headerlink" href="#notes" title="Permalink to this headline">¶</a></h2>
|
||
<div class="section" id="converting-an-argument-sequence-to-a-string-on-windows">
|
||
<span id="converting-argument-sequence"></span><h3>Converting an argument sequence to a string on Windows<a class="headerlink" href="#converting-an-argument-sequence-to-a-string-on-windows" title="Permalink to this headline">¶</a></h3>
|
||
<p>On Windows, an <em>args</em> sequence is converted to a string that can be parsed
|
||
using the following rules (which correspond to the rules used by the MS C
|
||
runtime):</p>
|
||
<ol class="arabic simple">
|
||
<li><p>Arguments are delimited by white space, which is either a
|
||
space or a tab.</p></li>
|
||
<li><p>A string surrounded by double quotation marks is
|
||
interpreted as a single argument, regardless of white space
|
||
contained within. A quoted string can be embedded in an
|
||
argument.</p></li>
|
||
<li><p>A double quotation mark preceded by a backslash is
|
||
interpreted as a literal double quotation mark.</p></li>
|
||
<li><p>Backslashes are interpreted literally, unless they
|
||
immediately precede a double quotation mark.</p></li>
|
||
<li><p>If backslashes immediately precede a double quotation mark,
|
||
every pair of backslashes is interpreted as a literal
|
||
backslash. If the number of backslashes is odd, the last
|
||
backslash escapes the next double quotation mark as
|
||
described in rule 3.</p></li>
|
||
</ol>
|
||
<div class="admonition seealso">
|
||
<p class="admonition-title">See also</p>
|
||
<dl class="simple">
|
||
<dt><a class="reference internal" href="shlex.html#module-shlex" title="shlex: Simple lexical analysis for Unix shell-like languages."><code class="xref py py-mod docutils literal notranslate"><span class="pre">shlex</span></code></a></dt><dd><p>Module which provides function to parse and escape command lines.</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
||
<div class="sphinxsidebarwrapper">
|
||
<h3><a href="../contents.html">Table of Contents</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">subprocess</span></code> — Subprocess management</a><ul>
|
||
<li><a class="reference internal" href="#using-the-subprocess-module">Using the <code class="xref py py-mod docutils literal notranslate"><span class="pre">subprocess</span></code> Module</a><ul>
|
||
<li><a class="reference internal" href="#frequently-used-arguments">Frequently Used Arguments</a></li>
|
||
<li><a class="reference internal" href="#popen-constructor">Popen Constructor</a></li>
|
||
<li><a class="reference internal" href="#exceptions">Exceptions</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#security-considerations">Security Considerations</a></li>
|
||
<li><a class="reference internal" href="#popen-objects">Popen Objects</a></li>
|
||
<li><a class="reference internal" href="#windows-popen-helpers">Windows Popen Helpers</a><ul>
|
||
<li><a class="reference internal" href="#windows-constants">Windows Constants</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#older-high-level-api">Older high-level API</a></li>
|
||
<li><a class="reference internal" href="#replacing-older-functions-with-the-subprocess-module">Replacing Older Functions with the <code class="xref py py-mod docutils literal notranslate"><span class="pre">subprocess</span></code> Module</a><ul>
|
||
<li><a class="reference internal" href="#replacing-bin-sh-shell-backquote">Replacing /bin/sh shell backquote</a></li>
|
||
<li><a class="reference internal" href="#replacing-shell-pipeline">Replacing shell pipeline</a></li>
|
||
<li><a class="reference internal" href="#replacing-os-system">Replacing <code class="xref py py-func docutils literal notranslate"><span class="pre">os.system()</span></code></a></li>
|
||
<li><a class="reference internal" href="#replacing-the-os-spawn-family">Replacing the <code class="xref py py-func docutils literal notranslate"><span class="pre">os.spawn</span></code> family</a></li>
|
||
<li><a class="reference internal" href="#replacing-os-popen-os-popen2-os-popen3">Replacing <code class="xref py py-func docutils literal notranslate"><span class="pre">os.popen()</span></code>, <code class="xref py py-func docutils literal notranslate"><span class="pre">os.popen2()</span></code>, <code class="xref py py-func docutils literal notranslate"><span class="pre">os.popen3()</span></code></a></li>
|
||
<li><a class="reference internal" href="#replacing-functions-from-the-popen2-module">Replacing functions from the <code class="xref py py-mod docutils literal notranslate"><span class="pre">popen2</span></code> module</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#legacy-shell-invocation-functions">Legacy Shell Invocation Functions</a></li>
|
||
<li><a class="reference internal" href="#notes">Notes</a><ul>
|
||
<li><a class="reference internal" href="#converting-an-argument-sequence-to-a-string-on-windows">Converting an argument sequence to a string on Windows</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
<h4>Previous topic</h4>
|
||
<p class="topless"><a href="concurrent.futures.html"
|
||
title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">concurrent.futures</span></code> — Launching parallel tasks</a></p>
|
||
<h4>Next topic</h4>
|
||
<p class="topless"><a href="sched.html"
|
||
title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">sched</span></code> — Event scheduler</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/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="sched.html" title="sched — Event scheduler"
|
||
>next</a> |</li>
|
||
<li class="right" >
|
||
<a href="concurrent.futures.html" title="concurrent.futures — Launching parallel tasks"
|
||
>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="concurrency.html" >Concurrent Execution</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> |