1:mod:`subprocess` --- Subprocess management
2===========================================
3
4.. module:: subprocess
5   :synopsis: Subprocess management.
6
7.. moduleauthor:: Peter Åstrand <astrand@lysator.liu.se>
8.. sectionauthor:: Peter Åstrand <astrand@lysator.liu.se>
9
10**Source code:** :source:`Lib/subprocess.py`
11
12--------------
13
14The :mod:`subprocess` module allows you to spawn new processes, connect to their
15input/output/error pipes, and obtain their return codes.  This module intends to
16replace several older modules and functions::
17
18   os.system
19   os.spawn*
20
21Information about how the :mod:`subprocess` module can be used to replace these
22modules and functions can be found in the following sections.
23
24.. seealso::
25
26   :pep:`324` -- PEP proposing the subprocess module
27
28
29Using the :mod:`subprocess` Module
30----------------------------------
31
32The recommended approach to invoking subprocesses is to use the :func:`run`
33function for all use cases it can handle. For more advanced use cases, the
34underlying :class:`Popen` interface can be used directly.
35
36The :func:`run` function was added in Python 3.5; if you need to retain
37compatibility with older versions, see the :ref:`call-function-trio` section.
38
39
40.. function:: run(args, *, stdin=None, input=None, stdout=None, stderr=None,\
41                  capture_output=False, shell=False, cwd=None, timeout=None, \
42                  check=False, encoding=None, errors=None, text=None, env=None, \
43                  universal_newlines=None)
44
45   Run the command described by *args*.  Wait for command to complete, then
46   return a :class:`CompletedProcess` instance.
47
48   The arguments shown above are merely the most common ones, described below
49   in :ref:`frequently-used-arguments` (hence the use of keyword-only notation
50   in the abbreviated signature). The full function signature is largely the
51   same as that of the :class:`Popen` constructor - most of the arguments to
52   this function are passed through to that interface. (*timeout*,  *input*,
53   *check*, and *capture_output* are not.)
54
55   If *capture_output* is true, stdout and stderr will be captured.
56   When used, the internal :class:`Popen` object is automatically created with
57   ``stdout=PIPE`` and ``stderr=PIPE``. The *stdout* and *stderr* arguments may
58   not be used as well.
59
60   The *timeout* argument is passed to :meth:`Popen.communicate`. If the timeout
61   expires, the child process will be killed and waited for.  The
62   :exc:`TimeoutExpired` exception will be re-raised after the child process
63   has terminated.
64
65   The *input* argument is passed to :meth:`Popen.communicate` and thus to the
66   subprocess's stdin.  If used it must be a byte sequence, or a string if
67   *encoding* or *errors* is specified or *text* is true.  When
68   used, the internal :class:`Popen` object is automatically created with
69   ``stdin=PIPE``, and the *stdin* argument may not be used as well.
70
71   If *check* is true, and the process exits with a non-zero exit code, a
72   :exc:`CalledProcessError` exception will be raised. Attributes of that
73   exception hold the arguments, the exit code, and stdout and stderr if they
74   were captured.
75
76   If *encoding* or *errors* are specified, or *text* is true,
77   file objects for stdin, stdout and stderr are opened in text mode using the
78   specified *encoding* and *errors* or the :class:`io.TextIOWrapper` default.
79   The *universal_newlines* argument is equivalent  to *text* and is provided
80   for backwards compatibility. By default, file objects are opened in binary mode.
81
82   If *env* is not ``None``, it must be a mapping that defines the environment
83   variables for the new process; these are used instead of the default
84   behavior of inheriting the current process' environment. It is passed directly
85   to :class:`Popen`.
86
87   Examples::
88
89      >>> subprocess.run(["ls", "-l"])  # doesn't capture output
90      CompletedProcess(args=['ls', '-l'], returncode=0)
91
92      >>> subprocess.run("exit 1", shell=True, check=True)
93      Traceback (most recent call last):
94        ...
95      subprocess.CalledProcessError: Command 'exit 1' returned non-zero exit status 1
96
97      >>> subprocess.run(["ls", "-l", "/dev/null"], capture_output=True)
98      CompletedProcess(args=['ls', '-l', '/dev/null'], returncode=0,
99      stdout=b'crw-rw-rw- 1 root root 1, 3 Jan 23 16:23 /dev/null\n', stderr=b'')
100
101   .. versionadded:: 3.5
102
103   .. versionchanged:: 3.6
104
105      Added *encoding* and *errors* parameters
106
107   .. versionchanged:: 3.7
108
109      Added the *text* parameter, as a more understandable alias of *universal_newlines*.
110      Added the *capture_output* parameter.
111
112.. class:: CompletedProcess
113
114   The return value from :func:`run`, representing a process that has finished.
115
116   .. attribute:: args
117
118      The arguments used to launch the process. This may be a list or a string.
119
120   .. attribute:: returncode
121
122      Exit status of the child process. Typically, an exit status of 0 indicates
123      that it ran successfully.
124
125      A negative value ``-N`` indicates that the child was terminated by signal
126      ``N`` (POSIX only).
127
128   .. attribute:: stdout
129
130      Captured stdout from the child process. A bytes sequence, or a string if
131      :func:`run` was called with an encoding, errors, or text=True.
132      ``None`` if stdout was not captured.
133
134      If you ran the process with ``stderr=subprocess.STDOUT``, stdout and
135      stderr will be combined in this attribute, and :attr:`stderr` will be
136      ``None``.
137
138   .. attribute:: stderr
139
140      Captured stderr from the child process. A bytes sequence, or a string if
141      :func:`run` was called with an encoding, errors, or text=True.
142      ``None`` if stderr was not captured.
143
144   .. method:: check_returncode()
145
146      If :attr:`returncode` is non-zero, raise a :exc:`CalledProcessError`.
147
148   .. versionadded:: 3.5
149
150.. data:: DEVNULL
151
152   Special value that can be used as the *stdin*, *stdout* or *stderr* argument
153   to :class:`Popen` and indicates that the special file :data:`os.devnull`
154   will be used.
155
156   .. versionadded:: 3.3
157
158
159.. data:: PIPE
160
161   Special value that can be used as the *stdin*, *stdout* or *stderr* argument
162   to :class:`Popen` and indicates that a pipe to the standard stream should be
163   opened.  Most useful with :meth:`Popen.communicate`.
164
165
166.. data:: STDOUT
167
168   Special value that can be used as the *stderr* argument to :class:`Popen` and
169   indicates that standard error should go into the same handle as standard
170   output.
171
172
173.. exception:: SubprocessError
174
175    Base class for all other exceptions from this module.
176
177    .. versionadded:: 3.3
178
179
180.. exception:: TimeoutExpired
181
182    Subclass of :exc:`SubprocessError`, raised when a timeout expires
183    while waiting for a child process.
184
185    .. attribute:: cmd
186
187        Command that was used to spawn the child process.
188
189    .. attribute:: timeout
190
191        Timeout in seconds.
192
193    .. attribute:: output
194
195        Output of the child process if it was captured by :func:`run` or
196        :func:`check_output`.  Otherwise, ``None``.
197
198    .. attribute:: stdout
199
200        Alias for output, for symmetry with :attr:`stderr`.
201
202    .. attribute:: stderr
203
204        Stderr output of the child process if it was captured by :func:`run`.
205        Otherwise, ``None``.
206
207    .. versionadded:: 3.3
208
209    .. versionchanged:: 3.5
210        *stdout* and *stderr* attributes added
211
212.. exception:: CalledProcessError
213
214    Subclass of :exc:`SubprocessError`, raised when a process run by
215    :func:`check_call` or :func:`check_output` returns a non-zero exit status.
216
217    .. attribute:: returncode
218
219        Exit status of the child process.  If the process exited due to a
220        signal, this will be the negative signal number.
221
222    .. attribute:: cmd
223
224        Command that was used to spawn the child process.
225
226    .. attribute:: output
227
228        Output of the child process if it was captured by :func:`run` or
229        :func:`check_output`.  Otherwise, ``None``.
230
231    .. attribute:: stdout
232
233        Alias for output, for symmetry with :attr:`stderr`.
234
235    .. attribute:: stderr
236
237        Stderr output of the child process if it was captured by :func:`run`.
238        Otherwise, ``None``.
239
240    .. versionchanged:: 3.5
241        *stdout* and *stderr* attributes added
242
243
244.. _frequently-used-arguments:
245
246Frequently Used Arguments
247^^^^^^^^^^^^^^^^^^^^^^^^^
248
249To support a wide variety of use cases, the :class:`Popen` constructor (and
250the convenience functions) accept a large number of optional arguments. For
251most typical use cases, many of these arguments can be safely left at their
252default values. The arguments that are most commonly needed are:
253
254   *args* is required for all calls and should be a string, or a sequence of
255   program arguments. Providing a sequence of arguments is generally
256   preferred, as it allows the module to take care of any required escaping
257   and quoting of arguments (e.g. to permit spaces in file names). If passing
258   a single string, either *shell* must be :const:`True` (see below) or else
259   the string must simply name the program to be executed without specifying
260   any arguments.
261
262   *stdin*, *stdout* and *stderr* specify the executed program's standard input,
263   standard output and standard error file handles, respectively.  Valid values
264   are :data:`PIPE`, :data:`DEVNULL`, an existing file descriptor (a positive
265   integer), an existing file object, and ``None``.  :data:`PIPE` indicates
266   that a new pipe to the child should be created.  :data:`DEVNULL` indicates
267   that the special file :data:`os.devnull` will be used.  With the default
268   settings of ``None``, no redirection will occur; the child's file handles
269   will be inherited from the parent.  Additionally, *stderr* can be
270   :data:`STDOUT`, which indicates that the stderr data from the child
271   process should be captured into the same file handle as for *stdout*.
272
273   .. index::
274      single: universal newlines; subprocess module
275
276   If *encoding* or *errors* are specified, or *text* (also known as
277   *universal_newlines*) is true,
278   the file objects *stdin*, *stdout* and *stderr* will be opened in text
279   mode using the *encoding* and *errors* specified in the call or the
280   defaults for :class:`io.TextIOWrapper`.
281
282   For *stdin*, line ending characters ``'\n'`` in the input will be converted
283   to the default line separator :data:`os.linesep`. For *stdout* and *stderr*,
284   all line endings in the output will be converted to ``'\n'``.  For more
285   information see the documentation of the :class:`io.TextIOWrapper` class
286   when the *newline* argument to its constructor is ``None``.
287
288   If text mode is not used, *stdin*, *stdout* and *stderr* will be opened as
289   binary streams. No encoding or line ending conversion is performed.
290
291   .. versionadded:: 3.6
292      Added *encoding* and *errors* parameters.
293
294   .. versionadded:: 3.7
295      Added the *text* parameter as an alias for *universal_newlines*.
296
297   .. note::
298
299      The newlines attribute of the file objects :attr:`Popen.stdin`,
300      :attr:`Popen.stdout` and :attr:`Popen.stderr` are not updated by
301      the :meth:`Popen.communicate` method.
302
303   If *shell* is ``True``, the specified command will be executed through
304   the shell.  This can be useful if you are using Python primarily for the
305   enhanced control flow it offers over most system shells and still want
306   convenient access to other shell features such as shell pipes, filename
307   wildcards, environment variable expansion, and expansion of ``~`` to a
308   user's home directory.  However, note that Python itself offers
309   implementations of many shell-like features (in particular, :mod:`glob`,
310   :mod:`fnmatch`, :func:`os.walk`, :func:`os.path.expandvars`,
311   :func:`os.path.expanduser`, and :mod:`shutil`).
312
313   .. versionchanged:: 3.3
314      When *universal_newlines* is ``True``, the class uses the encoding
315      :func:`locale.getpreferredencoding(False) <locale.getpreferredencoding>`
316      instead of ``locale.getpreferredencoding()``.  See the
317      :class:`io.TextIOWrapper` class for more information on this change.
318
319   .. note::
320
321      Read the `Security Considerations`_ section before using ``shell=True``.
322
323These options, along with all of the other options, are described in more
324detail in the :class:`Popen` constructor documentation.
325
326
327Popen Constructor
328^^^^^^^^^^^^^^^^^
329
330The underlying process creation and management in this module is handled by
331the :class:`Popen` class. It offers a lot of flexibility so that developers
332are able to handle the less common cases not covered by the convenience
333functions.
334
335
336.. class:: Popen(args, bufsize=-1, executable=None, stdin=None, stdout=None, \
337                 stderr=None, preexec_fn=None, close_fds=True, shell=False, \
338                 cwd=None, env=None, universal_newlines=None, \
339                 startupinfo=None, creationflags=0, restore_signals=True, \
340                 start_new_session=False, pass_fds=(), *, \
341                 encoding=None, errors=None, text=None)
342
343   Execute a child program in a new process.  On POSIX, the class uses
344   :meth:`os.execvp`-like behavior to execute the child program.  On Windows,
345   the class uses the Windows ``CreateProcess()`` function.  The arguments to
346   :class:`Popen` are as follows.
347
348   *args* should be a sequence of program arguments or else a single string.
349   By default, the program to execute is the first item in *args* if *args* is
350   a sequence.  If *args* is a string, the interpretation is
351   platform-dependent and described below.  See the *shell* and *executable*
352   arguments for additional differences from the default behavior.  Unless
353   otherwise stated, it is recommended to pass *args* as a sequence.
354
355   On POSIX, if *args* is a string, the string is interpreted as the name or
356   path of the program to execute.  However, this can only be done if not
357   passing arguments to the program.
358
359   .. note::
360
361      :meth:`shlex.split` can be useful when determining the correct
362      tokenization for *args*, especially in complex cases::
363
364         >>> import shlex, subprocess
365         >>> command_line = input()
366         /bin/vikings -input eggs.txt -output "spam spam.txt" -cmd "echo '$MONEY'"
367         >>> args = shlex.split(command_line)
368         >>> print(args)
369         ['/bin/vikings', '-input', 'eggs.txt', '-output', 'spam spam.txt', '-cmd', "echo '$MONEY'"]
370         >>> p = subprocess.Popen(args) # Success!
371
372      Note in particular that options (such as *-input*) and arguments (such
373      as *eggs.txt*) that are separated by whitespace in the shell go in separate
374      list elements, while arguments that need quoting or backslash escaping when
375      used in the shell (such as filenames containing spaces or the *echo* command
376      shown above) are single list elements.
377
378   On Windows, if *args* is a sequence, it will be converted to a string in a
379   manner described in :ref:`converting-argument-sequence`.  This is because
380   the underlying ``CreateProcess()`` operates on strings.
381
382   The *shell* argument (which defaults to ``False``) specifies whether to use
383   the shell as the program to execute.  If *shell* is ``True``, it is
384   recommended to pass *args* as a string rather than as a sequence.
385
386   On POSIX with ``shell=True``, the shell defaults to :file:`/bin/sh`.  If
387   *args* is a string, the string specifies the command
388   to execute through the shell.  This means that the string must be
389   formatted exactly as it would be when typed at the shell prompt.  This
390   includes, for example, quoting or backslash escaping filenames with spaces in
391   them.  If *args* is a sequence, the first item specifies the command string, and
392   any additional items will be treated as additional arguments to the shell
393   itself.  That is to say, :class:`Popen` does the equivalent of::
394
395      Popen(['/bin/sh', '-c', args[0], args[1], ...])
396
397   On Windows with ``shell=True``, the :envvar:`COMSPEC` environment variable
398   specifies the default shell.  The only time you need to specify
399   ``shell=True`` on Windows is when the command you wish to execute is built
400   into the shell (e.g. :command:`dir` or :command:`copy`).  You do not need
401   ``shell=True`` to run a batch file or console-based executable.
402
403   .. note::
404
405      Read the `Security Considerations`_ section before using ``shell=True``.
406
407   *bufsize* will be supplied as the corresponding argument to the
408   :func:`open` function when creating the stdin/stdout/stderr pipe
409   file objects:
410
411   - :const:`0` means unbuffered (read and write are one
412     system call and can return short)
413   - :const:`1` means line buffered
414     (only usable if ``universal_newlines=True`` i.e., in a text mode)
415   - any other positive value means use a buffer of approximately that
416     size
417   - negative bufsize (the default) means the system default of
418     io.DEFAULT_BUFFER_SIZE will be used.
419
420   .. versionchanged:: 3.3.1
421      *bufsize* now defaults to -1 to enable buffering by default to match the
422      behavior that most code expects.  In versions prior to Python 3.2.4 and
423      3.3.1 it incorrectly defaulted to :const:`0` which was unbuffered
424      and allowed short reads.  This was unintentional and did not match the
425      behavior of Python 2 as most code expected.
426
427   The *executable* argument specifies a replacement program to execute.   It
428   is very seldom needed.  When ``shell=False``, *executable* replaces the
429   program to execute specified by *args*.  However, the original *args* is
430   still passed to the program.  Most programs treat the program specified
431   by *args* as the command name, which can then be different from the program
432   actually executed.  On POSIX, the *args* name
433   becomes the display name for the executable in utilities such as
434   :program:`ps`.  If ``shell=True``, on POSIX the *executable* argument
435   specifies a replacement shell for the default :file:`/bin/sh`.
436
437   *stdin*, *stdout* and *stderr* specify the executed program's standard input,
438   standard output and standard error file handles, respectively.  Valid values
439   are :data:`PIPE`, :data:`DEVNULL`, an existing file descriptor (a positive
440   integer), an existing :term:`file object`, and ``None``.  :data:`PIPE`
441   indicates that a new pipe to the child should be created.  :data:`DEVNULL`
442   indicates that the special file :data:`os.devnull` will be used. With the
443   default settings of ``None``, no redirection will occur; the child's file
444   handles will be inherited from the parent.  Additionally, *stderr* can be
445   :data:`STDOUT`, which indicates that the stderr data from the applications
446   should be captured into the same file handle as for stdout.
447
448   If *preexec_fn* is set to a callable object, this object will be called in the
449   child process just before the child is executed.
450   (POSIX only)
451
452   .. warning::
453
454      The *preexec_fn* parameter is not safe to use in the presence of threads
455      in your application.  The child process could deadlock before exec is
456      called.
457      If you must use it, keep it trivial!  Minimize the number of libraries
458      you call into.
459
460   .. note::
461
462      If you need to modify the environment for the child use the *env*
463      parameter rather than doing it in a *preexec_fn*.
464      The *start_new_session* parameter can take the place of a previously
465      common use of *preexec_fn* to call os.setsid() in the child.
466
467   If *close_fds* is true, all file descriptors except :const:`0`, :const:`1` and
468   :const:`2` will be closed before the child process is executed.  Otherwise
469   when *close_fds* is false, file descriptors obey their inheritable flag
470   as described in :ref:`fd_inheritance`.
471
472   On Windows, if *close_fds* is true then no handles will be inherited by the
473   child process unless explicitly passed in the ``handle_list`` element of
474   :attr:`STARTUPINFO.lpAttributeList`, or by standard handle redirection.
475
476   .. versionchanged:: 3.2
477      The default for *close_fds* was changed from :const:`False` to
478      what is described above.
479
480   .. versionchanged:: 3.7
481      On Windows the default for *close_fds* was changed from :const:`False` to
482      :const:`True` when redirecting the standard handles. It's now possible to
483      set *close_fds* to :const:`True` when redirecting the standard handles.
484
485   *pass_fds* is an optional sequence of file descriptors to keep open
486   between the parent and child.  Providing any *pass_fds* forces
487   *close_fds* to be :const:`True`.  (POSIX only)
488
489   .. versionadded:: 3.2
490      The *pass_fds* parameter was added.
491
492   If *cwd* is not ``None``, the function changes the working directory to
493   *cwd* before executing the child.  *cwd* can be a :class:`str` and
494   :term:`path-like <path-like object>` object.  In particular, the function
495   looks for *executable* (or for the first item in *args*) relative to *cwd*
496   if the executable path is a relative path.
497
498   .. versionchanged:: 3.6
499      *cwd* parameter accepts a :term:`path-like object`.
500
501   If *restore_signals* is true (the default) all signals that Python has set to
502   SIG_IGN are restored to SIG_DFL in the child process before the exec.
503   Currently this includes the SIGPIPE, SIGXFZ and SIGXFSZ signals.
504   (POSIX only)
505
506   .. versionchanged:: 3.2
507      *restore_signals* was added.
508
509   If *start_new_session* is true the setsid() system call will be made in the
510   child process prior to the execution of the subprocess.  (POSIX only)
511
512   .. versionchanged:: 3.2
513      *start_new_session* was added.
514
515   If *env* is not ``None``, it must be a mapping that defines the environment
516   variables for the new process; these are used instead of the default
517   behavior of inheriting the current process' environment.
518
519   .. note::
520
521      If specified, *env* must provide any variables required for the program to
522      execute.  On Windows, in order to run a `side-by-side assembly`_ the
523      specified *env* **must** include a valid :envvar:`SystemRoot`.
524
525   .. _side-by-side assembly: https://en.wikipedia.org/wiki/Side-by-Side_Assembly
526
527   If *encoding* or *errors* are specified, or *text* is true, the file objects
528   *stdin*, *stdout* and *stderr* are opened in text mode with the specified
529   encoding and *errors*, as described above in :ref:`frequently-used-arguments`.
530   The *universal_newlines* argument is equivalent  to *text* and is provided
531   for backwards compatibility. By default, file objects are opened in binary mode.
532
533   .. versionadded:: 3.6
534      *encoding* and *errors* were added.
535
536   .. versionadded:: 3.7
537      *text* was added as a more readable alias for *universal_newlines*.
538
539   If given, *startupinfo* will be a :class:`STARTUPINFO` object, which is
540   passed to the underlying ``CreateProcess`` function.
541   *creationflags*, if given, can be one or more of the following flags:
542
543      * :data:`CREATE_NEW_CONSOLE`
544      * :data:`CREATE_NEW_PROCESS_GROUP`
545      * :data:`ABOVE_NORMAL_PRIORITY_CLASS`
546      * :data:`BELOW_NORMAL_PRIORITY_CLASS`
547      * :data:`HIGH_PRIORITY_CLASS`
548      * :data:`IDLE_PRIORITY_CLASS`
549      * :data:`NORMAL_PRIORITY_CLASS`
550      * :data:`REALTIME_PRIORITY_CLASS`
551      * :data:`CREATE_NO_WINDOW`
552      * :data:`DETACHED_PROCESS`
553      * :data:`CREATE_DEFAULT_ERROR_MODE`
554      * :data:`CREATE_BREAKAWAY_FROM_JOB`
555
556   Popen objects are supported as context managers via the :keyword:`with` statement:
557   on exit, standard file descriptors are closed, and the process is waited for.
558   ::
559
560      with Popen(["ifconfig"], stdout=PIPE) as proc:
561          log.write(proc.stdout.read())
562
563   .. versionchanged:: 3.2
564      Added context manager support.
565
566   .. versionchanged:: 3.6
567      Popen destructor now emits a :exc:`ResourceWarning` warning if the child
568      process is still running.
569
570
571Exceptions
572^^^^^^^^^^
573
574Exceptions raised in the child process, before the new program has started to
575execute, will be re-raised in the parent.
576
577The most common exception raised is :exc:`OSError`.  This occurs, for example,
578when trying to execute a non-existent file.  Applications should prepare for
579:exc:`OSError` exceptions.
580
581A :exc:`ValueError` will be raised if :class:`Popen` is called with invalid
582arguments.
583
584:func:`check_call` and :func:`check_output` will raise
585:exc:`CalledProcessError` if the called process returns a non-zero return
586code.
587
588All of the functions and methods that accept a *timeout* parameter, such as
589:func:`call` and :meth:`Popen.communicate` will raise :exc:`TimeoutExpired` if
590the timeout expires before the process exits.
591
592Exceptions defined in this module all inherit from :exc:`SubprocessError`.
593
594   .. versionadded:: 3.3
595      The :exc:`SubprocessError` base class was added.
596
597
598Security Considerations
599-----------------------
600
601Unlike some other popen functions, this implementation will never
602implicitly call a system shell.  This means that all characters,
603including shell metacharacters, can safely be passed to child processes.
604If the shell is invoked explicitly, via ``shell=True``, it is the application's
605responsibility to ensure that all whitespace and metacharacters are
606quoted appropriately to avoid
607`shell injection <https://en.wikipedia.org/wiki/Shell_injection#Shell_injection>`_
608vulnerabilities.
609
610When using ``shell=True``, the :func:`shlex.quote` function can be
611used to properly escape whitespace and shell metacharacters in strings
612that are going to be used to construct shell commands.
613
614
615Popen Objects
616-------------
617
618Instances of the :class:`Popen` class have the following methods:
619
620
621.. method:: Popen.poll()
622
623   Check if child process has terminated.  Set and return
624   :attr:`~Popen.returncode` attribute. Otherwise, returns ``None``.
625
626
627.. method:: Popen.wait(timeout=None)
628
629   Wait for child process to terminate.  Set and return
630   :attr:`~Popen.returncode` attribute.
631
632   If the process does not terminate after *timeout* seconds, raise a
633   :exc:`TimeoutExpired` exception.  It is safe to catch this exception and
634   retry the wait.
635
636   .. note::
637
638      This will deadlock when using ``stdout=PIPE`` or ``stderr=PIPE``
639      and the child process generates enough output to a pipe such that
640      it blocks waiting for the OS pipe buffer to accept more data.
641      Use :meth:`Popen.communicate` when using pipes to avoid that.
642
643   .. note::
644
645      The function is implemented using a busy loop (non-blocking call and
646      short sleeps). Use the :mod:`asyncio` module for an asynchronous wait:
647      see :class:`asyncio.create_subprocess_exec`.
648
649   .. versionchanged:: 3.3
650      *timeout* was added.
651
652.. method:: Popen.communicate(input=None, timeout=None)
653
654   Interact with process: Send data to stdin.  Read data from stdout and stderr,
655   until end-of-file is reached.  Wait for process to terminate.  The optional
656   *input* argument should be data to be sent to the child process, or
657   ``None``, if no data should be sent to the child.  If streams were opened in
658   text mode, *input* must be a string.  Otherwise, it must be bytes.
659
660   :meth:`communicate` returns a tuple ``(stdout_data, stderr_data)``.
661   The data will be strings if streams were opened in text mode; otherwise,
662   bytes.
663
664   Note that if you want to send data to the process's stdin, you need to create
665   the Popen object with ``stdin=PIPE``.  Similarly, to get anything other than
666   ``None`` in the result tuple, you need to give ``stdout=PIPE`` and/or
667   ``stderr=PIPE`` too.
668
669   If the process does not terminate after *timeout* seconds, a
670   :exc:`TimeoutExpired` exception will be raised.  Catching this exception and
671   retrying communication will not lose any output.
672
673   The child process is not killed if the timeout expires, so in order to
674   cleanup properly a well-behaved application should kill the child process and
675   finish communication::
676
677      proc = subprocess.Popen(...)
678      try:
679          outs, errs = proc.communicate(timeout=15)
680      except TimeoutExpired:
681          proc.kill()
682          outs, errs = proc.communicate()
683
684   .. note::
685
686      The data read is buffered in memory, so do not use this method if the data
687      size is large or unlimited.
688
689   .. versionchanged:: 3.3
690      *timeout* was added.
691
692
693.. method:: Popen.send_signal(signal)
694
695   Sends the signal *signal* to the child.
696
697   .. note::
698
699      On Windows, SIGTERM is an alias for :meth:`terminate`. CTRL_C_EVENT and
700      CTRL_BREAK_EVENT can be sent to processes started with a *creationflags*
701      parameter which includes `CREATE_NEW_PROCESS_GROUP`.
702
703
704.. method:: Popen.terminate()
705
706   Stop the child. On Posix OSs the method sends SIGTERM to the
707   child. On Windows the Win32 API function :c:func:`TerminateProcess` is called
708   to stop the child.
709
710
711.. method:: Popen.kill()
712
713   Kills the child. On Posix OSs the function sends SIGKILL to the child.
714   On Windows :meth:`kill` is an alias for :meth:`terminate`.
715
716
717The following attributes are also available:
718
719.. attribute:: Popen.args
720
721   The *args* argument as it was passed to :class:`Popen` -- a
722   sequence of program arguments or else a single string.
723
724   .. versionadded:: 3.3
725
726.. attribute:: Popen.stdin
727
728   If the *stdin* argument was :data:`PIPE`, this attribute is a writeable
729   stream object as returned by :func:`open`. If the *encoding* or *errors*
730   arguments were specified or the *universal_newlines* argument was ``True``,
731   the stream is a text stream, otherwise it is a byte stream. If the *stdin*
732   argument was not :data:`PIPE`, this attribute is ``None``.
733
734
735.. attribute:: Popen.stdout
736
737   If the *stdout* argument was :data:`PIPE`, this attribute is a readable
738   stream object as returned by :func:`open`. Reading from the stream provides
739   output from the child process. If the *encoding* or *errors* arguments were
740   specified or the *universal_newlines* argument was ``True``, the stream is a
741   text stream, otherwise it is a byte stream. If the *stdout* argument was not
742   :data:`PIPE`, this attribute is ``None``.
743
744
745.. attribute:: Popen.stderr
746
747   If the *stderr* argument was :data:`PIPE`, this attribute is a readable
748   stream object as returned by :func:`open`. Reading from the stream provides
749   error output from the child process. If the *encoding* or *errors* arguments
750   were specified or the *universal_newlines* argument was ``True``, the stream
751   is a text stream, otherwise it is a byte stream. If the *stderr* argument was
752   not :data:`PIPE`, this attribute is ``None``.
753
754.. warning::
755
756   Use :meth:`~Popen.communicate` rather than :attr:`.stdin.write <Popen.stdin>`,
757   :attr:`.stdout.read <Popen.stdout>` or :attr:`.stderr.read <Popen.stderr>` to avoid
758   deadlocks due to any of the other OS pipe buffers filling up and blocking the
759   child process.
760
761
762.. attribute:: Popen.pid
763
764   The process ID of the child process.
765
766   Note that if you set the *shell* argument to ``True``, this is the process ID
767   of the spawned shell.
768
769
770.. attribute:: Popen.returncode
771
772   The child return code, set by :meth:`poll` and :meth:`wait` (and indirectly
773   by :meth:`communicate`).  A ``None`` value indicates that the process
774   hasn't terminated yet.
775
776   A negative value ``-N`` indicates that the child was terminated by signal
777   ``N`` (POSIX only).
778
779
780Windows Popen Helpers
781---------------------
782
783The :class:`STARTUPINFO` class and following constants are only available
784on Windows.
785
786.. class:: STARTUPINFO(*, dwFlags=0, hStdInput=None, hStdOutput=None, \
787                       hStdError=None, wShowWindow=0, lpAttributeList=None)
788
789   Partial support of the Windows
790   `STARTUPINFO <https://msdn.microsoft.com/en-us/library/ms686331(v=vs.85).aspx>`__
791   structure is used for :class:`Popen` creation.  The following attributes can
792   be set by passing them as keyword-only arguments.
793
794   .. versionchanged:: 3.7
795      Keyword-only argument support was added.
796
797   .. attribute:: dwFlags
798
799      A bit field that determines whether certain :class:`STARTUPINFO`
800      attributes are used when the process creates a window. ::
801
802         si = subprocess.STARTUPINFO()
803         si.dwFlags = subprocess.STARTF_USESTDHANDLES | subprocess.STARTF_USESHOWWINDOW
804
805   .. attribute:: hStdInput
806
807      If :attr:`dwFlags` specifies :data:`STARTF_USESTDHANDLES`, this attribute
808      is the standard input handle for the process. If
809      :data:`STARTF_USESTDHANDLES` is not specified, the default for standard
810      input is the keyboard buffer.
811
812   .. attribute:: hStdOutput
813
814      If :attr:`dwFlags` specifies :data:`STARTF_USESTDHANDLES`, this attribute
815      is the standard output handle for the process. Otherwise, this attribute
816      is ignored and the default for standard output is the console window's
817      buffer.
818
819   .. attribute:: hStdError
820
821      If :attr:`dwFlags` specifies :data:`STARTF_USESTDHANDLES`, this attribute
822      is the standard error handle for the process. Otherwise, this attribute is
823      ignored and the default for standard error is the console window's buffer.
824
825   .. attribute:: wShowWindow
826
827      If :attr:`dwFlags` specifies :data:`STARTF_USESHOWWINDOW`, this attribute
828      can be any of the values that can be specified in the ``nCmdShow``
829      parameter for the
830      `ShowWindow <https://msdn.microsoft.com/en-us/library/ms633548(v=vs.85).aspx>`__
831      function, except for ``SW_SHOWDEFAULT``. Otherwise, this attribute is
832      ignored.
833
834      :data:`SW_HIDE` is provided for this attribute. It is used when
835      :class:`Popen` is called with ``shell=True``.
836
837   .. attribute:: lpAttributeList
838
839      A dictionary of additional attributes for process creation as given in
840      ``STARTUPINFOEX``, see
841      `UpdateProcThreadAttribute <https://msdn.microsoft.com/en-us/library/windows/desktop/ms686880(v=vs.85).aspx>`__.
842
843      Supported attributes:
844
845      **handle_list**
846         Sequence of handles that will be inherited. *close_fds* must be true if
847         non-empty.
848
849         The handles must be temporarily made inheritable by
850         :func:`os.set_handle_inheritable` when passed to the :class:`Popen`
851         constructor, else :class:`OSError` will be raised with Windows error
852         ``ERROR_INVALID_PARAMETER`` (87).
853
854         .. warning::
855
856            In a multithreaded process, use caution to avoid leaking handles
857            that are marked inheritable when combining this feature with
858            concurrent calls to other process creation functions that inherit
859            all handles such as :func:`os.system`.  This also applies to
860            standard handle redirection, which temporarily creates inheritable
861            handles.
862
863      .. versionadded:: 3.7
864
865Windows Constants
866^^^^^^^^^^^^^^^^^
867
868The :mod:`subprocess` module exposes the following constants.
869
870.. data:: STD_INPUT_HANDLE
871
872   The standard input device. Initially, this is the console input buffer,
873   ``CONIN$``.
874
875.. data:: STD_OUTPUT_HANDLE
876
877   The standard output device. Initially, this is the active console screen
878   buffer, ``CONOUT$``.
879
880.. data:: STD_ERROR_HANDLE
881
882   The standard error device. Initially, this is the active console screen
883   buffer, ``CONOUT$``.
884
885.. data:: SW_HIDE
886
887   Hides the window. Another window will be activated.
888
889.. data:: STARTF_USESTDHANDLES
890
891   Specifies that the :attr:`STARTUPINFO.hStdInput`,
892   :attr:`STARTUPINFO.hStdOutput`, and :attr:`STARTUPINFO.hStdError` attributes
893   contain additional information.
894
895.. data:: STARTF_USESHOWWINDOW
896
897   Specifies that the :attr:`STARTUPINFO.wShowWindow` attribute contains
898   additional information.
899
900.. data:: CREATE_NEW_CONSOLE
901
902   The new process has a new console, instead of inheriting its parent's
903   console (the default).
904
905.. data:: CREATE_NEW_PROCESS_GROUP
906
907   A :class:`Popen` ``creationflags`` parameter to specify that a new process
908   group will be created. This flag is necessary for using :func:`os.kill`
909   on the subprocess.
910
911   This flag is ignored if :data:`CREATE_NEW_CONSOLE` is specified.
912
913.. data:: ABOVE_NORMAL_PRIORITY_CLASS
914
915   A :class:`Popen` ``creationflags`` parameter to specify that a new process
916   will have an above average priority.
917
918   .. versionadded:: 3.7
919
920.. data:: BELOW_NORMAL_PRIORITY_CLASS
921
922   A :class:`Popen` ``creationflags`` parameter to specify that a new process
923   will have a below average priority.
924
925   .. versionadded:: 3.7
926
927.. data:: HIGH_PRIORITY_CLASS
928
929   A :class:`Popen` ``creationflags`` parameter to specify that a new process
930   will have a high priority.
931
932   .. versionadded:: 3.7
933
934.. data:: IDLE_PRIORITY_CLASS
935
936   A :class:`Popen` ``creationflags`` parameter to specify that a new process
937   will have an idle (lowest) priority.
938
939   .. versionadded:: 3.7
940
941.. data:: NORMAL_PRIORITY_CLASS
942
943   A :class:`Popen` ``creationflags`` parameter to specify that a new process
944   will have an normal priority. (default)
945
946   .. versionadded:: 3.7
947
948.. data:: REALTIME_PRIORITY_CLASS
949
950   A :class:`Popen` ``creationflags`` parameter to specify that a new process
951   will have realtime priority.
952   You should almost never use REALTIME_PRIORITY_CLASS, because this interrupts
953   system threads that manage mouse input, keyboard input, and background disk
954   flushing. This class can be appropriate for applications that "talk" directly
955   to hardware or that perform brief tasks that should have limited interruptions.
956
957   .. versionadded:: 3.7
958
959.. data:: CREATE_NO_WINDOW
960
961   A :class:`Popen` ``creationflags`` parameter to specify that a new process
962   will not create a window.
963
964   .. versionadded:: 3.7
965
966.. data:: DETACHED_PROCESS
967
968   A :class:`Popen` ``creationflags`` parameter to specify that a new process
969   will not inherit its parent's console.
970   This value cannot be used with CREATE_NEW_CONSOLE.
971
972   .. versionadded:: 3.7
973
974.. data:: CREATE_DEFAULT_ERROR_MODE
975
976   A :class:`Popen` ``creationflags`` parameter to specify that a new process
977   does not inherit the error mode of the calling process. Instead, the new
978   process gets the default error mode.
979   This feature is particularly useful for multithreaded shell applications
980   that run with hard errors disabled.
981
982   .. versionadded:: 3.7
983
984.. data:: CREATE_BREAKAWAY_FROM_JOB
985
986   A :class:`Popen` ``creationflags`` parameter to specify that a new process
987   is not associated with the job.
988
989   .. versionadded:: 3.7
990
991.. _call-function-trio:
992
993Older high-level API
994--------------------
995
996Prior to Python 3.5, these three functions comprised the high level API to
997subprocess. You can now use :func:`run` in many cases, but lots of existing code
998calls these functions.
999
1000.. function:: call(args, *, stdin=None, stdout=None, stderr=None, shell=False, cwd=None, timeout=None)
1001
1002   Run the command described by *args*.  Wait for command to complete, then
1003   return the :attr:`~Popen.returncode` attribute.
1004
1005   This is equivalent to::
1006
1007       run(...).returncode
1008
1009   (except that the *input* and *check* parameters are not supported)
1010
1011   The arguments shown above are merely the most
1012   common ones. The full function signature is largely the
1013   same as that of the :class:`Popen` constructor - this function passes all
1014   supplied arguments other than *timeout* directly through to that interface.
1015
1016   .. note::
1017
1018      Do not use ``stdout=PIPE`` or ``stderr=PIPE`` with this
1019      function.  The child process will block if it generates enough
1020      output to a pipe to fill up the OS pipe buffer as the pipes are
1021      not being read from.
1022
1023   .. versionchanged:: 3.3
1024      *timeout* was added.
1025
1026.. function:: check_call(args, *, stdin=None, stdout=None, stderr=None, shell=False, cwd=None, timeout=None)
1027
1028   Run command with arguments.  Wait for command to complete. If the return
1029   code was zero then return, otherwise raise :exc:`CalledProcessError`. The
1030   :exc:`CalledProcessError` object will have the return code in the
1031   :attr:`~CalledProcessError.returncode` attribute.
1032
1033   This is equivalent to::
1034
1035       run(..., check=True)
1036
1037   (except that the *input* parameter is not supported)
1038
1039   The arguments shown above are merely the most
1040   common ones. The full function signature is largely the
1041   same as that of the :class:`Popen` constructor - this function passes all
1042   supplied arguments other than *timeout* directly through to that interface.
1043
1044   .. note::
1045
1046      Do not use ``stdout=PIPE`` or ``stderr=PIPE`` with this
1047      function.  The child process will block if it generates enough
1048      output to a pipe to fill up the OS pipe buffer as the pipes are
1049      not being read from.
1050
1051   .. versionchanged:: 3.3
1052      *timeout* was added.
1053
1054
1055.. function:: check_output(args, *, stdin=None, stderr=None, shell=False, \
1056                           cwd=None, encoding=None, errors=None, \
1057                           universal_newlines=None, timeout=None, text=None)
1058
1059   Run command with arguments and return its output.
1060
1061   If the return code was non-zero it raises a :exc:`CalledProcessError`. The
1062   :exc:`CalledProcessError` object will have the return code in the
1063   :attr:`~CalledProcessError.returncode` attribute and any output in the
1064   :attr:`~CalledProcessError.output` attribute.
1065
1066   This is equivalent to::
1067
1068       run(..., check=True, stdout=PIPE).stdout
1069
1070   The arguments shown above are merely the most common ones.
1071   The full function signature is largely the same as that of :func:`run` -
1072   most arguments are passed directly through to that interface.
1073   However, explicitly passing ``input=None`` to inherit the parent's
1074   standard input file handle is not supported.
1075
1076   By default, this function will return the data as encoded bytes. The actual
1077   encoding of the output data may depend on the command being invoked, so the
1078   decoding to text will often need to be handled at the application level.
1079
1080   This behaviour may be overridden by setting *universal_newlines* to
1081   ``True`` as described above in :ref:`frequently-used-arguments`.
1082
1083   To also capture standard error in the result, use
1084   ``stderr=subprocess.STDOUT``::
1085
1086      >>> subprocess.check_output(
1087      ...     "ls non_existent_file; exit 0",
1088      ...     stderr=subprocess.STDOUT,
1089      ...     shell=True)
1090      'ls: non_existent_file: No such file or directory\n'
1091
1092   .. versionadded:: 3.1
1093
1094   .. versionchanged:: 3.3
1095      *timeout* was added.
1096
1097   .. versionchanged:: 3.4
1098      Support for the *input* keyword argument was added.
1099
1100   .. versionchanged:: 3.6
1101      *encoding* and *errors* were added.  See :func:`run` for details.
1102
1103   .. versionadded:: 3.7
1104      *text* was added as a more readable alias for *universal_newlines*.
1105
1106
1107.. _subprocess-replacements:
1108
1109Replacing Older Functions with the :mod:`subprocess` Module
1110-----------------------------------------------------------
1111
1112In this section, "a becomes b" means that b can be used as a replacement for a.
1113
1114.. note::
1115
1116   All "a" functions in this section fail (more or less) silently if the
1117   executed program cannot be found; the "b" replacements raise :exc:`OSError`
1118   instead.
1119
1120   In addition, the replacements using :func:`check_output` will fail with a
1121   :exc:`CalledProcessError` if the requested operation produces a non-zero
1122   return code. The output is still available as the
1123   :attr:`~CalledProcessError.output` attribute of the raised exception.
1124
1125In the following examples, we assume that the relevant functions have already
1126been imported from the :mod:`subprocess` module.
1127
1128
1129Replacing /bin/sh shell backquote
1130^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1131
1132.. code-block:: bash
1133
1134   output=`mycmd myarg`
1135
1136becomes::
1137
1138   output = check_output(["mycmd", "myarg"])
1139
1140Replacing shell pipeline
1141^^^^^^^^^^^^^^^^^^^^^^^^
1142
1143.. code-block:: bash
1144
1145   output=`dmesg | grep hda`
1146
1147becomes::
1148
1149   p1 = Popen(["dmesg"], stdout=PIPE)
1150   p2 = Popen(["grep", "hda"], stdin=p1.stdout, stdout=PIPE)
1151   p1.stdout.close()  # Allow p1 to receive a SIGPIPE if p2 exits.
1152   output = p2.communicate()[0]
1153
1154The p1.stdout.close() call after starting the p2 is important in order for p1
1155to receive a SIGPIPE if p2 exits before p1.
1156
1157Alternatively, for trusted input, the shell's own pipeline support may still
1158be used directly:
1159
1160.. code-block:: bash
1161
1162   output=`dmesg | grep hda`
1163
1164becomes::
1165
1166   output=check_output("dmesg | grep hda", shell=True)
1167
1168
1169Replacing :func:`os.system`
1170^^^^^^^^^^^^^^^^^^^^^^^^^^^
1171
1172::
1173
1174   sts = os.system("mycmd" + " myarg")
1175   # becomes
1176   sts = call("mycmd" + " myarg", shell=True)
1177
1178Notes:
1179
1180* Calling the program through the shell is usually not required.
1181
1182A more realistic example would look like this::
1183
1184   try:
1185       retcode = call("mycmd" + " myarg", shell=True)
1186       if retcode < 0:
1187           print("Child was terminated by signal", -retcode, file=sys.stderr)
1188       else:
1189           print("Child returned", retcode, file=sys.stderr)
1190   except OSError as e:
1191       print("Execution failed:", e, file=sys.stderr)
1192
1193
1194Replacing the :func:`os.spawn <os.spawnl>` family
1195^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1196
1197P_NOWAIT example::
1198
1199   pid = os.spawnlp(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg")
1200   ==>
1201   pid = Popen(["/bin/mycmd", "myarg"]).pid
1202
1203P_WAIT example::
1204
1205   retcode = os.spawnlp(os.P_WAIT, "/bin/mycmd", "mycmd", "myarg")
1206   ==>
1207   retcode = call(["/bin/mycmd", "myarg"])
1208
1209Vector example::
1210
1211   os.spawnvp(os.P_NOWAIT, path, args)
1212   ==>
1213   Popen([path] + args[1:])
1214
1215Environment example::
1216
1217   os.spawnlpe(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg", env)
1218   ==>
1219   Popen(["/bin/mycmd", "myarg"], env={"PATH": "/usr/bin"})
1220
1221
1222
1223Replacing :func:`os.popen`, :func:`os.popen2`, :func:`os.popen3`
1224^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1225
1226::
1227
1228   (child_stdin, child_stdout) = os.popen2(cmd, mode, bufsize)
1229   ==>
1230   p = Popen(cmd, shell=True, bufsize=bufsize,
1231             stdin=PIPE, stdout=PIPE, close_fds=True)
1232   (child_stdin, child_stdout) = (p.stdin, p.stdout)
1233
1234::
1235
1236   (child_stdin,
1237    child_stdout,
1238    child_stderr) = os.popen3(cmd, mode, bufsize)
1239   ==>
1240   p = Popen(cmd, shell=True, bufsize=bufsize,
1241             stdin=PIPE, stdout=PIPE, stderr=PIPE, close_fds=True)
1242   (child_stdin,
1243    child_stdout,
1244    child_stderr) = (p.stdin, p.stdout, p.stderr)
1245
1246::
1247
1248   (child_stdin, child_stdout_and_stderr) = os.popen4(cmd, mode, bufsize)
1249   ==>
1250   p = Popen(cmd, shell=True, bufsize=bufsize,
1251             stdin=PIPE, stdout=PIPE, stderr=STDOUT, close_fds=True)
1252   (child_stdin, child_stdout_and_stderr) = (p.stdin, p.stdout)
1253
1254Return code handling translates as follows::
1255
1256   pipe = os.popen(cmd, 'w')
1257   ...
1258   rc = pipe.close()
1259   if rc is not None and rc >> 8:
1260       print("There were some errors")
1261   ==>
1262   process = Popen(cmd, stdin=PIPE)
1263   ...
1264   process.stdin.close()
1265   if process.wait() != 0:
1266       print("There were some errors")
1267
1268
1269Replacing functions from the :mod:`popen2` module
1270^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1271
1272.. note::
1273
1274   If the cmd argument to popen2 functions is a string, the command is executed
1275   through /bin/sh.  If it is a list, the command is directly executed.
1276
1277::
1278
1279   (child_stdout, child_stdin) = popen2.popen2("somestring", bufsize, mode)
1280   ==>
1281   p = Popen("somestring", shell=True, bufsize=bufsize,
1282             stdin=PIPE, stdout=PIPE, close_fds=True)
1283   (child_stdout, child_stdin) = (p.stdout, p.stdin)
1284
1285::
1286
1287   (child_stdout, child_stdin) = popen2.popen2(["mycmd", "myarg"], bufsize, mode)
1288   ==>
1289   p = Popen(["mycmd", "myarg"], bufsize=bufsize,
1290             stdin=PIPE, stdout=PIPE, close_fds=True)
1291   (child_stdout, child_stdin) = (p.stdout, p.stdin)
1292
1293:class:`popen2.Popen3` and :class:`popen2.Popen4` basically work as
1294:class:`subprocess.Popen`, except that:
1295
1296* :class:`Popen` raises an exception if the execution fails.
1297
1298* The *capturestderr* argument is replaced with the *stderr* argument.
1299
1300* ``stdin=PIPE`` and ``stdout=PIPE`` must be specified.
1301
1302* popen2 closes all file descriptors by default, but you have to specify
1303  ``close_fds=True`` with :class:`Popen` to guarantee this behavior on
1304  all platforms or past Python versions.
1305
1306
1307Legacy Shell Invocation Functions
1308---------------------------------
1309
1310This module also provides the following legacy functions from the 2.x
1311``commands`` module. These operations implicitly invoke the system shell and
1312none of the guarantees described above regarding security and exception
1313handling consistency are valid for these functions.
1314
1315.. function:: getstatusoutput(cmd)
1316
1317   Return ``(exitcode, output)`` of executing *cmd* in a shell.
1318
1319   Execute the string *cmd* in a shell with :meth:`Popen.check_output` and
1320   return a 2-tuple ``(exitcode, output)``. The locale encoding is used;
1321   see the notes on :ref:`frequently-used-arguments` for more details.
1322
1323   A trailing newline is stripped from the output.
1324   The exit code for the command can be interpreted as the return code
1325   of subprocess.  Example::
1326
1327      >>> subprocess.getstatusoutput('ls /bin/ls')
1328      (0, '/bin/ls')
1329      >>> subprocess.getstatusoutput('cat /bin/junk')
1330      (1, 'cat: /bin/junk: No such file or directory')
1331      >>> subprocess.getstatusoutput('/bin/junk')
1332      (127, 'sh: /bin/junk: not found')
1333      >>> subprocess.getstatusoutput('/bin/kill $$')
1334      (-15, '')
1335
1336   .. availability:: POSIX & Windows.
1337
1338   .. versionchanged:: 3.3.4
1339      Windows support was added.
1340
1341      The function now returns (exitcode, output) instead of (status, output)
1342      as it did in Python 3.3.3 and earlier.  exitcode has the same value as
1343      :attr:`~Popen.returncode`.
1344
1345
1346.. function:: getoutput(cmd)
1347
1348   Return output (stdout and stderr) of executing *cmd* in a shell.
1349
1350   Like :func:`getstatusoutput`, except the exit code is ignored and the return
1351   value is a string containing the command's output.  Example::
1352
1353      >>> subprocess.getoutput('ls /bin/ls')
1354      '/bin/ls'
1355
1356   .. availability:: POSIX & Windows.
1357
1358   .. versionchanged:: 3.3.4
1359      Windows support added
1360
1361
1362Notes
1363-----
1364
1365.. _converting-argument-sequence:
1366
1367Converting an argument sequence to a string on Windows
1368^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1369
1370On Windows, an *args* sequence is converted to a string that can be parsed
1371using the following rules (which correspond to the rules used by the MS C
1372runtime):
1373
13741. Arguments are delimited by white space, which is either a
1375   space or a tab.
1376
13772. A string surrounded by double quotation marks is
1378   interpreted as a single argument, regardless of white space
1379   contained within.  A quoted string can be embedded in an
1380   argument.
1381
13823. A double quotation mark preceded by a backslash is
1383   interpreted as a literal double quotation mark.
1384
13854. Backslashes are interpreted literally, unless they
1386   immediately precede a double quotation mark.
1387
13885. If backslashes immediately precede a double quotation mark,
1389   every pair of backslashes is interpreted as a literal
1390   backslash.  If the number of backslashes is odd, the last
1391   backslash escapes the next double quotation mark as
1392   described in rule 3.
1393
1394
1395.. seealso::
1396
1397   :mod:`shlex`
1398      Module which provides function to parse and escape command lines.
1399