new repository

1 files changed, 102 insertions, 0 deletions

diff --git a/devdocs/python~3.12/library%2Fasyncio-subprocess.html b/devdocs/python~3.12/library%2Fasyncio-subprocess.html
new file mode 100644
index 00000000..f3b26006
--- /dev/null
+++ b/devdocs/python~3.12/library%2Fasyncio-subprocess.html
@@ -0,0 +1,102 @@
+ <span id="asyncio-subprocess"></span><h1>Subprocesses</h1> <p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.12/Lib/asyncio/subprocess.py">Lib/asyncio/subprocess.py</a>, <a class="reference external" href="https://github.com/python/cpython/tree/3.12/Lib/asyncio/base_subprocess.py">Lib/asyncio/base_subprocess.py</a></p>  <p>This section describes high-level async/await asyncio APIs to create and manage subprocesses.</p> <p id="asyncio-example-subprocess-shell">Here’s an example of how asyncio can run a shell command and obtain its result:</p> <pre data-language="python">import asyncio
+
+async def run(cmd):
+    proc = await asyncio.create_subprocess_shell(
+        cmd,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE)
+
+    stdout, stderr = await proc.communicate()
+
+    print(f'[{cmd!r} exited with {proc.returncode}]')
+    if stdout:
+        print(f'[stdout]\n{stdout.decode()}')
+    if stderr:
+        print(f'[stderr]\n{stderr.decode()}')
+
+asyncio.run(run('ls /zzz'))
+</pre> <p>will print:</p> <pre data-language="python">['ls /zzz' exited with 1]
+[stderr]
+ls: /zzz: No such file or directory
+</pre> <p>Because all asyncio subprocess functions are asynchronous and asyncio provides many tools to work with such functions, it is easy to execute and monitor multiple subprocesses in parallel. It is indeed trivial to modify the above example to run several commands simultaneously:</p> <pre data-language="python">async def main():
+    await asyncio.gather(
+        run('ls /zzz'),
+        run('sleep 1; echo "hello"'))
+
+asyncio.run(main())
+</pre> <p>See also the <a class="reference internal" href="#examples">Examples</a> subsection.</p> <section id="creating-subprocesses"> <h2>Creating Subprocesses</h2> <dl class="py function"> <dt class="sig sig-object py" id="asyncio.create_subprocess_exec">
+<code>coroutine asyncio.create_subprocess_exec(program, *args, stdin=None, stdout=None, stderr=None, limit=None, **kwds)</code> </dt> <dd>
+<p>Create a subprocess.</p> <p>The <em>limit</em> argument sets the buffer limit for <a class="reference internal" href="asyncio-stream#asyncio.StreamReader" title="asyncio.StreamReader"><code>StreamReader</code></a> wrappers for <code>Process.stdout</code> and <code>Process.stderr</code> (if <a class="reference internal" href="subprocess#subprocess.PIPE" title="subprocess.PIPE"><code>subprocess.PIPE</code></a> is passed to <em>stdout</em> and <em>stderr</em> arguments).</p> <p>Return a <a class="reference internal" href="#asyncio.subprocess.Process" title="asyncio.subprocess.Process"><code>Process</code></a> instance.</p> <p>See the documentation of <a class="reference internal" href="asyncio-eventloop#asyncio.loop.subprocess_exec" title="asyncio.loop.subprocess_exec"><code>loop.subprocess_exec()</code></a> for other parameters.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.10: </span>Removed the <em>loop</em> parameter.</p> </div> </dd>
+</dl> <dl class="py function"> <dt class="sig sig-object py" id="asyncio.create_subprocess_shell">
+<code>coroutine asyncio.create_subprocess_shell(cmd, stdin=None, stdout=None, stderr=None, limit=None, **kwds)</code> </dt> <dd>
+<p>Run the <em>cmd</em> shell command.</p> <p>The <em>limit</em> argument sets the buffer limit for <a class="reference internal" href="asyncio-stream#asyncio.StreamReader" title="asyncio.StreamReader"><code>StreamReader</code></a> wrappers for <code>Process.stdout</code> and <code>Process.stderr</code> (if <a class="reference internal" href="subprocess#subprocess.PIPE" title="subprocess.PIPE"><code>subprocess.PIPE</code></a> is passed to <em>stdout</em> and <em>stderr</em> arguments).</p> <p>Return a <a class="reference internal" href="#asyncio.subprocess.Process" title="asyncio.subprocess.Process"><code>Process</code></a> instance.</p> <p>See the documentation of <a class="reference internal" href="asyncio-eventloop#asyncio.loop.subprocess_shell" title="asyncio.loop.subprocess_shell"><code>loop.subprocess_shell()</code></a> for other parameters.</p> <div class="admonition important"> <p class="admonition-title">Important</p> <p>It is the application’s responsibility to ensure that all whitespace and special characters are quoted appropriately to avoid <a class="reference external" href="https://en.wikipedia.org/wiki/Shell_injection#Shell_injection">shell injection</a> vulnerabilities. The <a class="reference internal" href="shlex#shlex.quote" title="shlex.quote"><code>shlex.quote()</code></a> function can be used to properly escape whitespace and special shell characters in strings that are going to be used to construct shell commands.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.10: </span>Removed the <em>loop</em> parameter.</p> </div> </dd>
+</dl> <div class="admonition note"> <p class="admonition-title">Note</p> <p>Subprocesses are available for Windows if a <a class="reference internal" href="asyncio-eventloop#asyncio.ProactorEventLoop" title="asyncio.ProactorEventLoop"><code>ProactorEventLoop</code></a> is used. See <a class="reference internal" href="asyncio-platforms#asyncio-windows-subprocess"><span class="std std-ref">Subprocess Support on Windows</span></a> for details.</p> </div> <div class="admonition seealso"> <p class="admonition-title">See also</p> <p>asyncio also has the following <em>low-level</em> APIs to work with subprocesses: <a class="reference internal" href="asyncio-eventloop#asyncio.loop.subprocess_exec" title="asyncio.loop.subprocess_exec"><code>loop.subprocess_exec()</code></a>, <a class="reference internal" href="asyncio-eventloop#asyncio.loop.subprocess_shell" title="asyncio.loop.subprocess_shell"><code>loop.subprocess_shell()</code></a>, <a class="reference internal" href="asyncio-eventloop#asyncio.loop.connect_read_pipe" title="asyncio.loop.connect_read_pipe"><code>loop.connect_read_pipe()</code></a>, <a class="reference internal" href="asyncio-eventloop#asyncio.loop.connect_write_pipe" title="asyncio.loop.connect_write_pipe"><code>loop.connect_write_pipe()</code></a>, as well as the <a class="reference internal" href="asyncio-protocol#asyncio-subprocess-transports"><span class="std std-ref">Subprocess Transports</span></a> and <a class="reference internal" href="asyncio-protocol#asyncio-subprocess-protocols"><span class="std std-ref">Subprocess Protocols</span></a>.</p> </div> </section> <section id="constants"> <h2>Constants</h2> <dl class="py data"> <dt class="sig sig-object py" id="asyncio.subprocess.PIPE">
+<code>asyncio.subprocess.PIPE</code> </dt> <dd>
+<p>Can be passed to the <em>stdin</em>, <em>stdout</em> or <em>stderr</em> parameters.</p> <p>If <em>PIPE</em> is passed to <em>stdin</em> argument, the <a class="reference internal" href="#asyncio.subprocess.Process.stdin" title="asyncio.subprocess.Process.stdin"><code>Process.stdin</code></a> attribute will point to a <code>StreamWriter</code> instance.</p> <p>If <em>PIPE</em> is passed to <em>stdout</em> or <em>stderr</em> arguments, the <a class="reference internal" href="#asyncio.subprocess.Process.stdout" title="asyncio.subprocess.Process.stdout"><code>Process.stdout</code></a> and <a class="reference internal" href="#asyncio.subprocess.Process.stderr" title="asyncio.subprocess.Process.stderr"><code>Process.stderr</code></a> attributes will point to <code>StreamReader</code> instances.</p> </dd>
+</dl> <dl class="py data"> <dt class="sig sig-object py" id="asyncio.subprocess.STDOUT">
+<code>asyncio.subprocess.STDOUT</code> </dt> <dd>
+<p>Special value that can be used as the <em>stderr</em> argument and indicates that standard error should be redirected into standard output.</p> </dd>
+</dl> <dl class="py data"> <dt class="sig sig-object py" id="asyncio.subprocess.DEVNULL">
+<code>asyncio.subprocess.DEVNULL</code> </dt> <dd>
+<p>Special value that can be used as the <em>stdin</em>, <em>stdout</em> or <em>stderr</em> argument to process creation functions. It indicates that the special file <a class="reference internal" href="os#os.devnull" title="os.devnull"><code>os.devnull</code></a> will be used for the corresponding subprocess stream.</p> </dd>
+</dl> </section> <section id="interacting-with-subprocesses"> <h2>Interacting with Subprocesses</h2> <p>Both <a class="reference internal" href="#asyncio.create_subprocess_exec" title="asyncio.create_subprocess_exec"><code>create_subprocess_exec()</code></a> and <a class="reference internal" href="#asyncio.create_subprocess_shell" title="asyncio.create_subprocess_shell"><code>create_subprocess_shell()</code></a> functions return instances of the <em>Process</em> class. <em>Process</em> is a high-level wrapper that allows communicating with subprocesses and watching for their completion.</p> <dl class="py class"> <dt class="sig sig-object py" id="asyncio.subprocess.Process">
+<code>class asyncio.subprocess.Process</code> </dt> <dd>
+<p>An object that wraps OS processes created by the <code>create_subprocess_exec()</code> and <code>create_subprocess_shell()</code> functions.</p> <p>This class is designed to have a similar API to the <a class="reference internal" href="subprocess#subprocess.Popen" title="subprocess.Popen"><code>subprocess.Popen</code></a> class, but there are some notable differences:</p> <ul class="simple"> <li>unlike Popen, Process instances do not have an equivalent to the <a class="reference internal" href="subprocess#subprocess.Popen.poll" title="subprocess.Popen.poll"><code>poll()</code></a> method;</li> <li>the <a class="reference internal" href="#asyncio.subprocess.Process.communicate" title="asyncio.subprocess.Process.communicate"><code>communicate()</code></a> and <a class="reference internal" href="#asyncio.subprocess.Process.wait" title="asyncio.subprocess.Process.wait"><code>wait()</code></a> methods don’t have a <em>timeout</em> parameter: use the <a class="reference internal" href="asyncio-task#asyncio.wait_for" title="asyncio.wait_for"><code>wait_for()</code></a> function;</li> <li>the <a class="reference internal" href="#asyncio.subprocess.Process.wait" title="asyncio.subprocess.Process.wait"><code>Process.wait()</code></a> method is asynchronous, whereas <a class="reference internal" href="subprocess#subprocess.Popen.wait" title="subprocess.Popen.wait"><code>subprocess.Popen.wait()</code></a> method is implemented as a blocking busy loop;</li> <li>the <em>universal_newlines</em> parameter is not supported.</li> </ul> <p>This class is <a class="reference internal" href="asyncio-dev#asyncio-multithreading"><span class="std std-ref">not thread safe</span></a>.</p> <p>See also the <a class="reference internal" href="#asyncio-subprocess-threads"><span class="std std-ref">Subprocess and Threads</span></a> section.</p> <dl class="py method"> <dt class="sig sig-object py" id="asyncio.subprocess.Process.wait">
+<code>coroutine wait()</code> </dt> <dd>
+<p>Wait for the child process to terminate.</p> <p>Set and return the <a class="reference internal" href="#asyncio.subprocess.Process.returncode" title="asyncio.subprocess.Process.returncode"><code>returncode</code></a> attribute.</p> <div class="admonition note"> <p class="admonition-title">Note</p> <p>This method can deadlock when using <code>stdout=PIPE</code> or <code>stderr=PIPE</code> and the child process generates so much output that it blocks waiting for the OS pipe buffer to accept more data. Use the <a class="reference internal" href="#asyncio.subprocess.Process.communicate" title="asyncio.subprocess.Process.communicate"><code>communicate()</code></a> method when using pipes to avoid this condition.</p> </div> </dd>
+</dl> <dl class="py method"> <dt class="sig sig-object py" id="asyncio.subprocess.Process.communicate">
+<code>coroutine communicate(input=None)</code> </dt> <dd>
+<p>Interact with process:</p> <ol class="arabic simple"> <li>send data to <em>stdin</em> (if <em>input</em> is not <code>None</code>);</li> <li>closes <em>stdin</em>;</li> <li>read data from <em>stdout</em> and <em>stderr</em>, until EOF is reached;</li> <li>wait for process to terminate.</li> </ol> <p>The optional <em>input</em> argument is the data (<a class="reference internal" href="stdtypes#bytes" title="bytes"><code>bytes</code></a> object) that will be sent to the child process.</p> <p>Return a tuple <code>(stdout_data, stderr_data)</code>.</p> <p>If either <a class="reference internal" href="exceptions#BrokenPipeError" title="BrokenPipeError"><code>BrokenPipeError</code></a> or <a class="reference internal" href="exceptions#ConnectionResetError" title="ConnectionResetError"><code>ConnectionResetError</code></a> exception is raised when writing <em>input</em> into <em>stdin</em>, the exception is ignored. This condition occurs when the process exits before all data are written into <em>stdin</em>.</p> <p>If it is desired to send data to the process’ <em>stdin</em>, the process needs to be created with <code>stdin=PIPE</code>. Similarly, to get anything other than <code>None</code> in the result tuple, the process has to be created with <code>stdout=PIPE</code> and/or <code>stderr=PIPE</code> arguments.</p> <p>Note, that the data read is buffered in memory, so do not use this method if the data size is large or unlimited.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.12: </span><em>stdin</em> gets closed when <code>input=None</code> too.</p> </div> </dd>
+</dl> <dl class="py method"> <dt class="sig sig-object py" id="asyncio.subprocess.Process.send_signal">
+<code>send_signal(signal)</code> </dt> <dd>
+<p>Sends the signal <em>signal</em> to the child process.</p> <div class="admonition note"> <p class="admonition-title">Note</p> <p>On Windows, <code>SIGTERM</code> is an alias for <a class="reference internal" href="#asyncio.subprocess.Process.terminate" title="asyncio.subprocess.Process.terminate"><code>terminate()</code></a>. <code>CTRL_C_EVENT</code> and <code>CTRL_BREAK_EVENT</code> can be sent to processes started with a <em>creationflags</em> parameter which includes <code>CREATE_NEW_PROCESS_GROUP</code>.</p> </div> </dd>
+</dl> <dl class="py method"> <dt class="sig sig-object py" id="asyncio.subprocess.Process.terminate">
+<code>terminate()</code> </dt> <dd>
+<p>Stop the child process.</p> <p>On POSIX systems this method sends <a class="reference internal" href="signal#signal.SIGTERM" title="signal.SIGTERM"><code>signal.SIGTERM</code></a> to the child process.</p> <p>On Windows the Win32 API function <code>TerminateProcess()</code> is called to stop the child process.</p> </dd>
+</dl> <dl class="py method"> <dt class="sig sig-object py" id="asyncio.subprocess.Process.kill">
+<code>kill()</code> </dt> <dd>
+<p>Kill the child process.</p> <p>On POSIX systems this method sends <code>SIGKILL</code> to the child process.</p> <p>On Windows this method is an alias for <a class="reference internal" href="#asyncio.subprocess.Process.terminate" title="asyncio.subprocess.Process.terminate"><code>terminate()</code></a>.</p> </dd>
+</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="asyncio.subprocess.Process.stdin">
+<code>stdin</code> </dt> <dd>
+<p>Standard input stream (<code>StreamWriter</code>) or <code>None</code> if the process was created with <code>stdin=None</code>.</p> </dd>
+</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="asyncio.subprocess.Process.stdout">
+<code>stdout</code> </dt> <dd>
+<p>Standard output stream (<code>StreamReader</code>) or <code>None</code> if the process was created with <code>stdout=None</code>.</p> </dd>
+</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="asyncio.subprocess.Process.stderr">
+<code>stderr</code> </dt> <dd>
+<p>Standard error stream (<code>StreamReader</code>) or <code>None</code> if the process was created with <code>stderr=None</code>.</p> </dd>
+</dl> <div class="admonition warning"> <p class="admonition-title">Warning</p> <p>Use the <a class="reference internal" href="#asyncio.subprocess.Process.communicate" title="asyncio.subprocess.Process.communicate"><code>communicate()</code></a> method rather than <a class="reference internal" href="#asyncio.subprocess.Process.stdin" title="asyncio.subprocess.Process.stdin"><code>process.stdin.write()</code></a>, <a class="reference internal" href="#asyncio.subprocess.Process.stdout" title="asyncio.subprocess.Process.stdout"><code>await process.stdout.read()</code></a> or <a class="reference internal" href="#asyncio.subprocess.Process.stderr" title="asyncio.subprocess.Process.stderr"><code>await process.stderr.read()</code></a>. This avoids deadlocks due to streams pausing reading or writing and blocking the child process.</p> </div> <dl class="py attribute"> <dt class="sig sig-object py" id="asyncio.subprocess.Process.pid">
+<code>pid</code> </dt> <dd>
+<p>Process identification number (PID).</p> <p>Note that for processes created by the <code>create_subprocess_shell()</code> function, this attribute is the PID of the spawned shell.</p> </dd>
+</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="asyncio.subprocess.Process.returncode">
+<code>returncode</code> </dt> <dd>
+<p>Return code of the process when it exits.</p> <p>A <code>None</code> value indicates that the process has not terminated yet.</p> <p>A negative value <code>-N</code> indicates that the child was terminated by signal <code>N</code> (POSIX only).</p> </dd>
+</dl> </dd>
+</dl> <section id="subprocess-and-threads"> <span id="asyncio-subprocess-threads"></span><h3>Subprocess and Threads</h3> <p>Standard asyncio event loop supports running subprocesses from different threads by default.</p> <p>On Windows subprocesses are provided by <a class="reference internal" href="asyncio-eventloop#asyncio.ProactorEventLoop" title="asyncio.ProactorEventLoop"><code>ProactorEventLoop</code></a> only (default), <a class="reference internal" href="asyncio-eventloop#asyncio.SelectorEventLoop" title="asyncio.SelectorEventLoop"><code>SelectorEventLoop</code></a> has no subprocess support.</p> <p>On UNIX <em>child watchers</em> are used for subprocess finish waiting, see <a class="reference internal" href="asyncio-policy#asyncio-watchers"><span class="std std-ref">Process Watchers</span></a> for more info.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.8: </span>UNIX switched to use <a class="reference internal" href="asyncio-policy#asyncio.ThreadedChildWatcher" title="asyncio.ThreadedChildWatcher"><code>ThreadedChildWatcher</code></a> for spawning subprocesses from different threads without any limitation.</p> <p>Spawning a subprocess with <em>inactive</em> current child watcher raises <a class="reference internal" href="exceptions#RuntimeError" title="RuntimeError"><code>RuntimeError</code></a>.</p> </div> <p>Note that alternative event loop implementations might have own limitations; please refer to their documentation.</p> <div class="admonition seealso"> <p class="admonition-title">See also</p> <p>The <a class="reference internal" href="asyncio-dev#asyncio-multithreading"><span class="std std-ref">Concurrency and multithreading in asyncio</span></a> section.</p> </div> </section> <section id="examples"> <h3>Examples</h3> <p>An example using the <a class="reference internal" href="#asyncio.subprocess.Process" title="asyncio.subprocess.Process"><code>Process</code></a> class to control a subprocess and the <a class="reference internal" href="asyncio-stream#asyncio.StreamReader" title="asyncio.StreamReader"><code>StreamReader</code></a> class to read from its standard output.</p> <p id="asyncio-example-create-subprocess-exec">The subprocess is created by the <a class="reference internal" href="#asyncio.create_subprocess_exec" title="asyncio.create_subprocess_exec"><code>create_subprocess_exec()</code></a> function:</p> <pre data-language="python">import asyncio
+import sys
+
+async def get_date():
+    code = 'import datetime; print(datetime.datetime.now())'
+
+    # Create the subprocess; redirect the standard output
+    # into a pipe.
+    proc = await asyncio.create_subprocess_exec(
+        sys.executable, '-c', code,
+        stdout=asyncio.subprocess.PIPE)
+
+    # Read one line of output.
+    data = await proc.stdout.readline()
+    line = data.decode('ascii').rstrip()
+
+    # Wait for the subprocess exit.
+    await proc.wait()
+    return line
+
+date = asyncio.run(get_date())
+print(f"Current date: {date}")
+</pre> <p>See also the <a class="reference internal" href="asyncio-protocol#asyncio-example-subprocess-proto"><span class="std std-ref">same example</span></a> written using low-level APIs.</p> </section> </section> <div class="_attribution">
+  <p class="_attribution-p">
+    &copy; 2001&ndash;2023 Python Software Foundation<br>Licensed under the PSF License.<br>
+    <a href="https://docs.python.org/3.12/library/asyncio-subprocess.html" class="_attribution-link">https://docs.python.org/3.12/library/asyncio-subprocess.html</a>
+  </p>
+</div>