,hJ&UddlmZddlZddlZddlZddlZddlZddlmZddlm Z ddl m Z m Z m Z mZmZmZmZddlZddlmZmZddlmZdd lmZmZmZdd lmZdd lmZm Z e r(ddl!Z!dd l"m#Z#m$Z$m%Z%m&Z&m'Z'dd l(m)Z)ddl*m+Z+m,Z,ddl-m.Z.m/Z/ee0e1ejde0ejde1fZ3de4d<de4d<e r dHdZ5ddlm6Z6m7Z7n dZ8 ddlm5Z5GddeZCe Gdd e!ZDdddd" dId#ZEdJd$ZFdJd%ZGd&ddddejd' dKd(ZIGd)d*ed+ZJe r'ejtd,k(rCGd-d.eJd+ZKdd/ dLd0ZLejdddddd1 dMd2ZMyGd3d4eJd+ZNGd5d6eNd+ZOGd7d8eOd+ZPGd9d:ed+ZQejd;k\rePZSGd<d=ePeQZTn,ejd>k\reOZSGd?d=eOeQZTneNZSGd@d=eNeQZTedd/ dNdAZLedddB dOdCZLedd/ dPdDZMedddB dQdEZMyeEZLdFxeL_UeL_VeIZMdGxeM_UeM_Vy#e9$rejtdk(rlddl;Z;e;jxddZ=e;j|e=j~_@e;j|e;j|e;j|ge=j~_AdZBdHdZ5ndZ8Yr>bsE r,r>ceZdZUdZdZded<dZded<dZded<dZded < dd Z dd Z e dd Z dd Z ddZddZddZddZddZy)ProcessuA child process. Like :class:`subprocess.Popen`, but async. This class has no public constructor. The most common way to get a `Process` object is to combine `Nursery.start` with `run_process`:: process_object = await nursery.start(run_process, ...) This way, `run_process` supervises the process and makes sure that it is cleaned up properly, while optionally checking the return value, feeding it input, and so on. If you need more control – for example, because you want to spawn a child process that outlives your program – then another option is to use `trio.lowlevel.open_process`:: process_object = await trio.lowlevel.open_process(...) Attributes: args (str or list): The ``command`` passed at construction time, specifying the process to execute and its arguments. pid (int): The process ID of the child process managed by this object. stdin (trio.abc.SendStream or None): A stream connected to the child's standard input stream: when you write bytes here, they become available for the child to read. Only available if the :class:`Process` was constructed using ``stdin=PIPE``; otherwise this will be None. stdout (trio.abc.ReceiveStream or None): A stream connected to the child's standard output stream: when the child writes to standard output, the written bytes become available for you to read here. Only available if the :class:`Process` was constructed using ``stdout=PIPE``; otherwise this will be None. stderr (trio.abc.ReceiveStream or None): A stream connected to the child's standard error stream: when the child writes to standard error, the written bytes become available for you to read here. Only available if the :class:`Process` was constructed using ``stderr=PIPE``; otherwise this will be None. stdio (trio.StapledStream or None): A stream that sends data to the child's standard input and receives from the child's standard output. Only available if both :attr:`stdin` and :attr:`stdout` are available; otherwise this will be None. Fruniversal_newlinesNencodingerrorsobject_wait_for_exit_datac||_||_||_||_d|_|j1|j%t |j|j|_t |_d|_tr1 t|jjd}t||_|jj|_|jj|_ y#t$rYBwxYwr2)_procstdinstdoutstderrstdiorr _wait_lock_pidfdr#r*pidopenr8args)rApopenrSrTrUr's r)__init__zProcess.__init__s    FJ :: !dkk&=&tzz4;;?DJ $,0  '$TZZ^^Q7#2h ?Czz      s> C%% C10C1c|j}|d|j}n|dkrd| }nd|}d|jd|dS)Nzrunning with PID rzexited with signal zexited with status z) returncoderYr[)rAr`statuss r)__repr__zProcess.__repr__s[__  ( 3FA~. {m<.zl; }Bvha88r,c^|jj}||j|S)aThe exit status of the process (an integer), or ``None`` if it's still running. By convention, a return code of zero indicates success. On UNIX, negative values indicate termination due to a signal, e.g., -11 if terminated by signal 11 (``SIGSEGV``). On Windows, a process that exits due to a call to :meth:`Process.terminate` will have an exit status of 1. Unlike the standard library `subprocess.Popen.returncode`, you don't have to call `poll` or `wait` to update this attribute; it's automatically updated as needed, and will always give you the latest information. )rRpoll _close_pidfd)rAr;s r)r`zProcess.returncodes+""       r,c|jYtjj|jj |jj d|_yyr%)rXtriolowlevelnotify_closingrBcloser@s r)rezProcess._close_pidfdsG ;; " MM ( (););)= > KK   DK #r,cxK|j4d{|j|jbtjt 5t jj|jjd{dddnt|d{|jj|jdddd{|jjJ|jjS77#1swYuxYw7|7D#1d{7swYTxYww)z{Block until the process exits. Returns: The exit status of the process; see :attr:`returncode`. N)rWrdrX contextlibsuppressrrgrh wait_readablerBrrRwaitrer`r@s r)roz Process.waits  ?? $ $yy{";;*#,,+P#mm99$++:L:L:NOOOPP -T222 !!!#! $ $"zz$$00zz$$$% $ PPP 3 $ $ $ $szD:DD:6D% ;DD D D%$D!%.D% D:D#3D:DD D%#D:%D7+D. ,D73D:c|jS)aReturns the exit status of the process (an integer), or ``None`` if it's still running. Note that on Trio (unlike the standard library `subprocess.Popen`), ``process.poll()`` and ``process.returncode`` always give the same result. See `returncode` for more details. This method is only included to make it easier to port code from `subprocess`. )r`r@s r)rdz Process.pollsr,c:|jj|y)a,Send signal ``sig`` to the process. On UNIX, ``sig`` may be any signal defined in the :mod:`signal` module, such as ``signal.SIGINT`` or ``signal.SIGTERM``. On Windows, it may be anything accepted by the standard library :meth:`subprocess.Popen.send_signal`. N)rR send_signal)rAsigs r)rrzProcess.send_signals s#r,c8|jjy)afTerminate the process, politely if possible. On UNIX, this is equivalent to ``send_signal(signal.SIGTERM)``; by convention this requests graceful termination, but a misbehaving or buggy process might ignore it. On Windows, :meth:`terminate` forcibly terminates the process in the same manner as :meth:`kill`. N)rR terminater@s r)ruzProcess.terminates r,c8|jjy)aImmediately terminate the process. On UNIX, this is equivalent to ``send_signal(signal.SIGKILL)``. On Windows, it calls ``TerminateProcess``. In both cases, the process cannot prevent itself from being killed, but the termination will be delivered asynchronously; use :meth:`wait` if you want to ensure the process is actually dead before proceeding. N)rRkillr@s r)rwz Process.kill%s r,) r\zsubprocess.Popen[bytes]rSzSendStream | NonerTReceiveStream | NonerUrxrDNone)rDstr)rD int | NonerDryrC)rszsignal.Signals | intrDry)rFrGrHrIrL__annotations__rMrNrPr]rbpropertyr`rerordrrrurwr&r,r)rKrKhs(V!&%HeFE #'&#'&#'!#'% #' % #'  #'J 9* %4 $  r,rK) metaclassrSrTrUc KdD]"}|j|std|dtjdk(rdt |t t fr|jds tdt |t t fs|jdr tdd}d}d}t5} t5} |tjk(rHt\}}| jtj|| j|j|tjk(rHt\}}| jtj|| j|j|tjk(r|^|}n[|tjk(rHt\}}| jtj|| j|jtj j#t%tj&|f|||d |d{} | j)ddddddt*j- |||S7<#1swY+xYw#1swY/xYww) a Execute a child program in a new process. After construction, you can interact with the child process by writing data to its `~trio.Process.stdin` stream (a `~trio.abc.SendStream`), reading data from its `~trio.Process.stdout` and/or `~trio.Process.stderr` streams (both `~trio.abc.ReceiveStream`\s), sending it signals using `~trio.Process.terminate`, `~trio.Process.kill`, or `~trio.Process.send_signal`, and waiting for it to exit using `~trio.Process.wait`. See `trio.Process` for details. Each standard stream is only available if you specify that a pipe should be created for it. For example, if you pass ``stdin=subprocess.PIPE``, you can write to the `~trio.Process.stdin` stream, else `~trio.Process.stdin` will be ``None``. Unlike `trio.run_process`, this function doesn't do any kind of automatic management of the child process. It's up to you to implement whatever semantics you want. Args: command: The command to run. Typically this is a sequence of strings or bytes such as ``['ls', '-l', 'directory with spaces']``, where the first element names the executable to invoke and the other elements specify its arguments. With ``shell=True`` in the ``**options``, or on Windows, ``command`` can be a string or bytes, which will be parsed following platform-dependent :ref:`quoting rules `. In all cases ``command`` can be a path or a sequence of paths. stdin: Specifies what the child process's standard input stream should connect to: output written by the parent (``subprocess.PIPE``), nothing (``subprocess.DEVNULL``), or an open file (pass a file descriptor or something whose ``fileno`` method returns one). If ``stdin`` is unspecified, the child process will have the same standard input stream as its parent. stdout: Like ``stdin``, but for the child process's standard output stream. stderr: Like ``stdin``, but for the child process's standard error stream. An additional value ``subprocess.STDOUT`` is supported, which causes the child's standard output and standard error messages to be intermixed on a single standard output stream, attached to whatever the ``stdout`` option says to attach it to. **options: Other :ref:`general subprocess options ` are also accepted. Returns: A new `trio.Process` object. Raises: OSError: if the process spawning fails, for example because the specified command could not be found. )rLtextrMrNbufsizezLtrio.Process only supports communicating over unbuffered byte streams; the 'z' option is not supportedposixshellzQcommand must be a sequence (not a string or bytes) if shell=False on UNIX systemszPcommand must be a string or bytes (not a sequence) if shell=True on UNIX systemsNr)get TypeErrorr9name isinstancerzbytesr subprocessPIPErcallbackrjrSTDOUTrg to_threadrun_syncrPopenpop_allrK_create) commandrSrTrUoptionskey trio_stdin trio_stdout trio_stderralways_cleanupcleanup_on_failr\s r) _open_processr2sFvO ;;s 1145NP  ww' gU| ,W[[5I. 'C<0W[[5I-  -1J04K04K #" #" JOO # : < J  # #BHHe 4  $ $Z%5%5 6 Z__ $"?"A K  # #BHHf 5  $ $[%6%6 7 Z&& &! z &"?"A K  # #BHHf 5  $ $[%6%6 7nn--             !G#"#"J ??5*k; GG  1#"#"#"#"sNI<BI<1 I0B$(A(A&8A(%B$&A(( B!1&BB$B!!B$r,)rScapture_stdoutcapture_stderrcheckdeliver_cancel task_statuscKt|tr td|tjuru|t j ur td|jdt j ur td|jdt j ur tdt|tttfr|t j |d<nd||d<|r"d|vr td t j |d<|r"d|vr td t j |d<5tjd k(rtntjd k(sJtg}g} dfd } dd} t!|fi|d{tj"4d{} 8j$J| j'| j$d_d_|r9j*J| j'| j*|d_d_|r2j,J| j'| j,| d_|j/j1d{dddd{|rdj9|nd}|rdj9| nd}j:r/|r-t j<j:j>||j:Jt j@j>j:||S777#t2$rtj4d5tj4ddfd } | j'| j1d{7j7#1swYnxYwY?wxYw78#1d{7swYIxYww)u 'Run ``command`` in a subprocess and wait for it to complete. This function can be called in two different ways. One option is a direct call, like:: completed_process_info = await trio.run_process(...) In this case, it returns a :class:`subprocess.CompletedProcess` instance describing the results. Use this if you want to treat a process like a function call. The other option is to run it as a task using `Nursery.start` – the enhanced version of `~Nursery.start_soon` that lets a task pass back a value during startup:: process = await nursery.start(trio.run_process, ...) In this case, `~Nursery.start` returns a `Process` object that you can use to interact with the process while it's running. Use this if you want to treat a process like a background task. Either way, `run_process` makes sure that the process has exited before returning, handles cancellation, optionally checks for errors, and provides some convenient shorthands for dealing with the child's input/output. **Input:** `run_process` supports all the same ``stdin=`` arguments as `subprocess.Popen`. In addition, if you simply want to pass in some fixed data, you can pass a plain `bytes` object, and `run_process` will take care of setting up a pipe, feeding in the data you gave, and then sending end-of-file. The default is ``b""``, which means that the child will receive an empty stdin. If you want the child to instead read from the parent's stdin, use ``stdin=None``. **Output:** By default, any output produced by the subprocess is passed through to the standard output and error streams of the parent Trio process. When calling `run_process` directly, you can capture the subprocess's output by passing ``capture_stdout=True`` to capture the subprocess's standard output, and/or ``capture_stderr=True`` to capture its standard error. Captured data is collected up by Trio into an in-memory buffer, and then provided as the :attr:`~subprocess.CompletedProcess.stdout` and/or :attr:`~subprocess.CompletedProcess.stderr` attributes of the returned :class:`~subprocess.CompletedProcess` object. The value for any stream that was not captured will be ``None``. If you want to capture both stdout and stderr while keeping them separate, pass ``capture_stdout=True, capture_stderr=True``. If you want to capture both stdout and stderr but mixed together in the order they were printed, use: ``capture_stdout=True, stderr=subprocess.STDOUT``. This directs the child's stderr into its stdout, so the combined output will be available in the `~subprocess.CompletedProcess.stdout` attribute. If you're using ``await nursery.start(trio.run_process, ...)`` and want to capture the subprocess's output for further processing, then use ``stdout=subprocess.PIPE`` and then make sure to read the data out of the `Process.stdout` stream. If you want to capture stderr separately, use ``stderr=subprocess.PIPE``. If you want to capture both, but mixed together in the correct order, use ``stdout=subprocess.PIPE, stderr=subprocess.STDOUT``. **Error checking:** If the subprocess exits with a nonzero status code, indicating failure, :func:`run_process` raises a :exc:`subprocess.CalledProcessError` exception rather than returning normally. The captured outputs are still available as the :attr:`~subprocess.CalledProcessError.stdout` and :attr:`~subprocess.CalledProcessError.stderr` attributes of that exception. To disable this behavior, so that :func:`run_process` returns normally even if the subprocess exits abnormally, pass ``check=False``. Note that this can make the ``capture_stdout`` and ``capture_stderr`` arguments useful even when starting `run_process` as a task: if you only care about the output if the process fails, then you can enable capturing and then read the output off of the `~subprocess.CalledProcessError`. **Cancellation:** If cancelled, `run_process` sends a termination request to the subprocess, then waits for it to fully exit. The ``deliver_cancel`` argument lets you control how the process is terminated. .. note:: `run_process` is intentionally similar to the standard library `subprocess.run`, but some of the defaults are different. Specifically, we default to: - ``check=True``, because `"errors should never pass silently / unless explicitly silenced" `__. - ``stdin=b""``, because it produces less-confusing results if a subprocess unexpectedly tries to read from stdin. To get the `subprocess.run` semantics, use ``check=False, stdin=None``. Args: command (list or str): The command to run. Typically this is a sequence of strings such as ``['ls', '-l', 'directory with spaces']``, where the first element names the executable to invoke and the other elements specify its arguments. With ``shell=True`` in the ``**options``, or on Windows, ``command`` may alternatively be a string, which will be parsed following platform-dependent :ref:`quoting rules `. stdin (:obj:`bytes`, subprocess.PIPE, file descriptor, or None): The bytes to provide to the subprocess on its standard input stream, or ``None`` if the subprocess's standard input should come from the same place as the parent Trio process's standard input. As is the case with the :mod:`subprocess` module, you can also pass a file descriptor or an object with a ``fileno()`` method, in which case the subprocess's standard input will come from that file. When starting `run_process` as a background task, you can also use ``stdin=subprocess.PIPE``, in which case `Process.stdin` will be a `~trio.abc.SendStream` that you can use to send data to the child. capture_stdout (bool): If true, capture the bytes that the subprocess writes to its standard output stream and return them in the `~subprocess.CompletedProcess.stdout` attribute of the returned `subprocess.CompletedProcess` or `subprocess.CalledProcessError`. capture_stderr (bool): If true, capture the bytes that the subprocess writes to its standard error stream and return them in the `~subprocess.CompletedProcess.stderr` attribute of the returned `~subprocess.CompletedProcess` or `subprocess.CalledProcessError`. check (bool): If false, don't validate that the subprocess exits successfully. You should be sure to check the ``returncode`` attribute of the returned object if you pass ``check=False``, so that errors don't pass silently. deliver_cancel (async function or None): If `run_process` is cancelled, then it needs to kill the child process. There are multiple ways to do this, so we let you customize it. If you pass None (the default), then the behavior depends on the platform: - On Windows, Trio calls ``TerminateProcess``, which should kill the process immediately. - On Unix-likes, the default behavior is to send a ``SIGTERM``, wait 5 seconds, and send a ``SIGKILL``. Alternatively, you can customize this behavior by passing in an arbitrary async function, which will be called with the `Process` object as an argument. For example, the default Unix behavior could be implemented like this:: async def my_deliver_cancel(process): process.send_signal(signal.SIGTERM) await trio.sleep(5) process.send_signal(signal.SIGKILL) When the process actually exits, the ``deliver_cancel`` function will automatically be cancelled – so if the process exits after ``SIGTERM``, then we'll never reach the ``SIGKILL``. In any case, `run_process` will always wait for the child process to exit before raising `Cancelled`. **options: :func:`run_process` also accepts any :ref:`general subprocess options ` and passes them on to the :class:`~trio.Process` constructor. This includes the ``stdout`` and ``stderr`` options, which provide additional redirection possibilities such as ``stderr=subprocess.STDOUT``, ``stdout=subprocess.DEVNULL``, or file descriptors. Returns: When called normally – a `subprocess.CompletedProcess` instance describing the return code and outputs. When called via `Nursery.start` – a `trio.Process` instance. Raises: UnicodeError: if ``stdin`` is specified as a Unicode string, rather than bytes ValueError: if multiple redirections are specified for the same stream, e.g., both ``capture_stdout=True`` and ``stdout=subprocess.DEVNULL`` subprocess.CalledProcessError: if ``check=False`` is not passed and the process exits with a nonzero exit status OSError: if an error is encountered starting or communicating with the process ExceptionGroup: if exceptions occur in ``deliver_cancel``, or when exceptions occur when communicating with the subprocess. If strict_exception_groups is set to false in the global context, which is deprecated, then single exceptions will be collapsed. .. note:: The child process runs in the same process group as the parent Trio process, so a Ctrl+C will be delivered simultaneously to both parent and child. If you don't want this behavior, consult your platform's documentation for starting child processes in a different process group. z$process stdin must be bytes, not strzstdout=subprocess.PIPE is only valid with nursery.start, since that's the only way to access the pipe; use nursery.start or pass the data you want to write directlyrTzestdout=subprocess.PIPE is only valid with nursery.start, since that's the only way to access the piperUzestderr=subprocess.PIPE is only valid with nursery.start, since that's the only way to access the piperSNz,can't specify both stdout and capture_stdoutz,can't specify both stderr and capture_stderrntrcK|4d{ J|jd{dddd{y737#tj$rY*wxYw7"#1d{7swYyxYwwr%)send_allrgBrokenResourceError)streaminput_s r) feed_inputz _run_process..feed_inputsv   ))oof---   .++       smA2>A2AAAA A2AA2AAAAAA2A/#A& $A/+A2cK|4d{|23d{}|j|7!76dddd{7y#1d{7swYyxYwwr%)append)rchunkschunks r) read_outputz!_run_process..read_outputsW % %% % %e e$ % %v % % % % %sXA+AA/-/AA/A A>AAA AAT)shieldc`K5d{dddy7 #1swYyxYwwr%r&)r killer_cscopeprocsr)killerz_run_process..killers5&3,T22233233s . " " ."+.r,)outputrU)rr rDry)rrrzlist[bytes | bytearray]rDryr|)!rrz UnicodeErrorrgTASK_STATUS_IGNOREDrr ValueErrorrr bytearray memoryviewr9rrr open_process open_nurseryrS start_soonrVrTrUstartedro BaseException CancelScopecanceljoinr`CalledProcessErrorr[CompletedProcess)rrSrrrrrr stdout_chunks stderr_chunksrrnurseryrrTrUrrrs ` @@@r) _run_processrs^%ABBd... JOO #>  ;;x JOO 3?  ;;x JOO 3? %%J78%??   w KL L&OO w KL L&OO 77d?4N77g% %2N-/M-/M%%'% %g11 1D  "g !zz--"":tzz:! ! {{..""; ]K" ! {{..""; ]K"    %))+  #>)7SXXm $DF(6SXXm $DF 5++ OO II   ****499doovvVVY 2"  !!.  $ 0 0 = 3""6*iik!!$$&    %sE=OL'O L*!O$N>&C L/3L-4L/8 ON;B$O*O-L//N8AN(N N((N1 -N84N>7N88N>;O>OO O OcNeZdZUdZded<ded<ded<ded<d ed <ded <y ) GeneralProcessArgsz"Arguments shared between all runs.int | HasFileno | NonerTrUr" close_fdszStrOrBytesPath | NonecwdzMapping[str, str] | Noneenv executableNrFrGrHrIr}r&r,r)rr$s(, "" ""O  !!%%r,r)totalwin32c0eZdZUdZded<ded<ded<y) WindowsProcessArgsz*Arguments shared between all Windows runs.r"rzsubprocess.STARTUPINFO | None startupinforE creationflagsNrr&r,r)rr2s <K6 6 r,r)rSc Kyw)a Execute a child program in a new process. After construction, you can interact with the child process by writing data to its `~trio.Process.stdin` stream (a `~trio.abc.SendStream`), reading data from its `~trio.Process.stdout` and/or `~trio.Process.stderr` streams (both `~trio.abc.ReceiveStream`\s), sending it signals using `~trio.Process.terminate`, `~trio.Process.kill`, or `~trio.Process.send_signal`, and waiting for it to exit using `~trio.Process.wait`. See `trio.Process` for details. Each standard stream is only available if you specify that a pipe should be created for it. For example, if you pass ``stdin=subprocess.PIPE``, you can write to the `~trio.Process.stdin` stream, else `~trio.Process.stdin` will be ``None``. Unlike `trio.run_process`, this function doesn't do any kind of automatic management of the child process. It's up to you to implement whatever semantics you want. Args: command (list or str): The command to run. Typically this is a sequence of strings such as ``['ls', '-l', 'directory with spaces']``, where the first element names the executable to invoke and the other elements specify its arguments. With ``shell=True`` in the ``**options``, or on Windows, ``command`` may alternatively be a string, which will be parsed following platform-dependent :ref:`quoting rules `. stdin: Specifies what the child process's standard input stream should connect to: output written by the parent (``subprocess.PIPE``), nothing (``subprocess.DEVNULL``), or an open file (pass a file descriptor or something whose ``fileno`` method returns one). If ``stdin`` is unspecified, the child process will have the same standard input stream as its parent. stdout: Like ``stdin``, but for the child process's standard output stream. stderr: Like ``stdin``, but for the child process's standard error stream. An additional value ``subprocess.STDOUT`` is supported, which causes the child's standard output and standard error messages to be intermixed on a single standard output stream, attached to whatever the ``stdout`` option says to attach it to. **options: Other :ref:`general subprocess options ` are also accepted. Returns: A new `trio.Process` object. Raises: OSError: if the process spawning fails, for example because the specified command could not be found. Nr&)rrSkwargss r)rr9s p )rrSrrrrc Kyw)u*Run ``command`` in a subprocess and wait for it to complete. This function can be called in two different ways. One option is a direct call, like:: completed_process_info = await trio.run_process(...) In this case, it returns a :class:`subprocess.CompletedProcess` instance describing the results. Use this if you want to treat a process like a function call. The other option is to run it as a task using `Nursery.start` – the enhanced version of `~Nursery.start_soon` that lets a task pass back a value during startup:: process = await nursery.start(trio.run_process, ...) In this case, `~Nursery.start` returns a `Process` object that you can use to interact with the process while it's running. Use this if you want to treat a process like a background task. Either way, `run_process` makes sure that the process has exited before returning, handles cancellation, optionally checks for errors, and provides some convenient shorthands for dealing with the child's input/output. **Input:** `run_process` supports all the same ``stdin=`` arguments as `subprocess.Popen`. In addition, if you simply want to pass in some fixed data, you can pass a plain `bytes` object, and `run_process` will take care of setting up a pipe, feeding in the data you gave, and then sending end-of-file. The default is ``b""``, which means that the child will receive an empty stdin. If you want the child to instead read from the parent's stdin, use ``stdin=None``. **Output:** By default, any output produced by the subprocess is passed through to the standard output and error streams of the parent Trio process. When calling `run_process` directly, you can capture the subprocess's output by passing ``capture_stdout=True`` to capture the subprocess's standard output, and/or ``capture_stderr=True`` to capture its standard error. Captured data is collected up by Trio into an in-memory buffer, and then provided as the :attr:`~subprocess.CompletedProcess.stdout` and/or :attr:`~subprocess.CompletedProcess.stderr` attributes of the returned :class:`~subprocess.CompletedProcess` object. The value for any stream that was not captured will be ``None``. If you want to capture both stdout and stderr while keeping them separate, pass ``capture_stdout=True, capture_stderr=True``. If you want to capture both stdout and stderr but mixed together in the order they were printed, use: ``capture_stdout=True, stderr=subprocess.STDOUT``. This directs the child's stderr into its stdout, so the combined output will be available in the `~subprocess.CompletedProcess.stdout` attribute. If you're using ``await nursery.start(trio.run_process, ...)`` and want to capture the subprocess's output for further processing, then use ``stdout=subprocess.PIPE`` and then make sure to read the data out of the `Process.stdout` stream. If you want to capture stderr separately, use ``stderr=subprocess.PIPE``. If you want to capture both, but mixed together in the correct order, use ``stdout=subprocess.PIPE, stderr=subprocess.STDOUT``. **Error checking:** If the subprocess exits with a nonzero status code, indicating failure, :func:`run_process` raises a :exc:`subprocess.CalledProcessError` exception rather than returning normally. The captured outputs are still available as the :attr:`~subprocess.CalledProcessError.stdout` and :attr:`~subprocess.CalledProcessError.stderr` attributes of that exception. To disable this behavior, so that :func:`run_process` returns normally even if the subprocess exits abnormally, pass ``check=False``. Note that this can make the ``capture_stdout`` and ``capture_stderr`` arguments useful even when starting `run_process` as a task: if you only care about the output if the process fails, then you can enable capturing and then read the output off of the `~subprocess.CalledProcessError`. **Cancellation:** If cancelled, `run_process` sends a termination request to the subprocess, then waits for it to fully exit. The ``deliver_cancel`` argument lets you control how the process is terminated. .. note:: `run_process` is intentionally similar to the standard library `subprocess.run`, but some of the defaults are different. Specifically, we default to: - ``check=True``, because `"errors should never pass silently / unless explicitly silenced" `__. - ``stdin=b""``, because it produces less-confusing results if a subprocess unexpectedly tries to read from stdin. To get the `subprocess.run` semantics, use ``check=False, stdin=None``. Args: command (list or str): The command to run. Typically this is a sequence of strings such as ``['ls', '-l', 'directory with spaces']``, where the first element names the executable to invoke and the other elements specify its arguments. With ``shell=True`` in the ``**options``, or on Windows, ``command`` may alternatively be a string, which will be parsed following platform-dependent :ref:`quoting rules `. stdin (:obj:`bytes`, subprocess.PIPE, file descriptor, or None): The bytes to provide to the subprocess on its standard input stream, or ``None`` if the subprocess's standard input should come from the same place as the parent Trio process's standard input. As is the case with the :mod:`subprocess` module, you can also pass a file descriptor or an object with a ``fileno()`` method, in which case the subprocess's standard input will come from that file. When starting `run_process` as a background task, you can also use ``stdin=subprocess.PIPE``, in which case `Process.stdin` will be a `~trio.abc.SendStream` that you can use to send data to the child. capture_stdout (bool): If true, capture the bytes that the subprocess writes to its standard output stream and return them in the `~subprocess.CompletedProcess.stdout` attribute of the returned `subprocess.CompletedProcess` or `subprocess.CalledProcessError`. capture_stderr (bool): If true, capture the bytes that the subprocess writes to its standard error stream and return them in the `~subprocess.CompletedProcess.stderr` attribute of the returned `~subprocess.CompletedProcess` or `subprocess.CalledProcessError`. check (bool): If false, don't validate that the subprocess exits successfully. You should be sure to check the ``returncode`` attribute of the returned object if you pass ``check=False``, so that errors don't pass silently. deliver_cancel (async function or None): If `run_process` is cancelled, then it needs to kill the child process. There are multiple ways to do this, so we let you customize it. If you pass None (the default), then the behavior depends on the platform: - On Windows, Trio calls ``TerminateProcess``, which should kill the process immediately. - On Unix-likes, the default behavior is to send a ``SIGTERM``, wait 5 seconds, and send a ``SIGKILL``. Alternatively, you can customize this behavior by passing in an arbitrary async function, which will be called with the `Process` object as an argument. For example, the default Unix behavior could be implemented like this:: async def my_deliver_cancel(process): process.send_signal(signal.SIGTERM) await trio.sleep(5) process.send_signal(signal.SIGKILL) When the process actually exits, the ``deliver_cancel`` function will automatically be cancelled – so if the process exits after ``SIGTERM``, then we'll never reach the ``SIGKILL``. In any case, `run_process` will always wait for the child process to exit before raising `Cancelled`. **options: :func:`run_process` also accepts any :ref:`general subprocess options ` and passes them on to the :class:`~trio.Process` constructor. This includes the ``stdout`` and ``stderr`` options, which provide additional redirection possibilities such as ``stderr=subprocess.STDOUT``, ``stdout=subprocess.DEVNULL``, or file descriptors. Returns: When called normally – a `subprocess.CompletedProcess` instance describing the return code and outputs. When called via `Nursery.start` – a `trio.Process` instance. Raises: UnicodeError: if ``stdin`` is specified as a Unicode string, rather than bytes ValueError: if multiple redirections are specified for the same stream, e.g., both ``capture_stdout=True`` and ``stdout=subprocess.DEVNULL`` subprocess.CalledProcessError: if ``check=False`` is not passed and the process exits with a nonzero exit status OSError: if an error is encountered starting or communicating with the process .. note:: The child process runs in the same process group as the parent Trio process, so a Ctrl+C will be delivered simultaneously to both parent and child. If you don't want this behavior, consult your platform's documentation for starting child processes in a different process group. Nr&)rrrSrrrrrs r) run_processrss T rcbeZdZUdZded<ded<ded<ded<d ed <d ed <d ed <ded<y)UnixProcessArgs3_9z'Arguments shared between all Unix runs.zCallable[[], object] | None preexec_fnr"restore_signalsstart_new_sessionz Sequence[int]pass_fdszstr | int | NonegroupzIterable[str | int] | None extra_groupsuserrEumaskNrr&r,r)rrDs6 93 3! !# ## #$ #4 4" "Jr,rceZdZUdZded<y)UnixProcessArgs3_10z0Arguments shared between all Unix runs on 3.10+.rEpipesizeNrr&r,r)rrRs BMr,rceZdZUdZded<y)UnixProcessArgs3_11z0Arguments shared between all Unix runs on 3.11+.r{ process_groupNrr&r,r)rrWs B% %r,rcDeZdZUdZded<ded<ded<ded<ded <y ) UnixRunProcessMixinz(Arguments unique to run_process on Unix.TaskStatus[Process]rr"rrrz+Callable[[Process], Awaitable[None]] | NonerNrr&r,r)rr\s" :, ,  KG Gr,r) ceZdZdZy)UnixRunProcessArgsz,Arguments for run_process on Unix with 3.11+NrFrGrHrIr&r,r)rrjBr,r)r ceZdZdZy)rz,Arguments for run_process on Unix with 3.10+Nrr&r,r)rrprr,ceZdZdZy)rz+Arguments for run_process on Unix with 3.9+Nrr&r,r)rrvsAr,c Kywr%r&rrSrrs r)rry r)rSrc Kywr%r&rs r)rrrrc Kywr%r&rs r)rr 25rc Kywr%r&rs r)rrr rrr)r'rEr(rErDrE) r)StrOrBytesPath | Sequence[StrOrBytesPath]rSrrTrrUrrrOrDrK)rrKrDry)rr rS7bytes | bytearray | memoryview | int | HasFileno | Nonerr"rr"rr"r-Callable[[Process], Awaitable[object]] | NonerrrrOrD"subprocess.CompletedProcess[bytes])rr rSrrUnpack[WindowsProcessArgs]rD trio.Process)rr rrrSr rr"rr"rr"rrrrrDr) rr!rSrr Literal[True]rUnpack[UnixProcessArgs]rDr) rSequence[StrOrBytesPath]rSrrr"rrrDr) rr!rSr rrrUnpack[UnixRunProcessArgs]rDr) rrrSr rr"rrrDr)W __future__rrlr9rsysrr functoolsrtypingrrrr r r r rg_corerr_highlevel_genericr_subprocess_platformrrr_syncr_utilrrsignalcollections.abcrrrrriortyping_extensionsrr_abcrr rzrPathLiker!r}r*r-r.r# ImportErrorplatformr6CDLLr3c_longr4restypeargtypesr5r>rKrrrrrrrrrrrrr version_infoUnixProcessArgsrrFrHr&r,r)r-s8"    2- -PP 3/"#ubkk#.> E@R"RS S 3OO&'!P!! F+FFX%)%)%) |H 6|H "|H # |H # |H  |H |H@  2FI  DH'+'?'?~W 6~W C~W ~W  ~W  ~WB~W%~W~W(~Wd &%& ||w !35 -18 >8 *8 1 8   8 z04/G/GMQ#(#(LPJ >J -J K J  ! J  ! J J JJ 1J 0J b !35  "4E   &"5U &  H)5 H   w &1O C%8:M C   (1O C%8:M C1O B%79L B -1 # * !   .        -1  - *    .        NR 5# 5K 5!  5 1  5 0  5  5 NR  5- 5K 5  5 1  5 0  5  5!L8FFLL5K6CCK;3Q# $' <<7 " #.6;;tt#D 39== ( ( 0   5 ( ( 1 "O "' I$'s J BLL