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