1 2:mod:`subprocess` --- Subprocess management 3=========================================== 4 5.. module:: subprocess 6 :synopsis: Subprocess management. 7.. moduleauthor:: Peter Åstrand <astrand@lysator.liu.se> 8.. sectionauthor:: Peter Åstrand <astrand@lysator.liu.se> 9 10 11.. versionadded:: 2.4 12 13The :mod:`subprocess` module allows you to spawn new processes, connect to their 14input/output/error pipes, and obtain their return codes. This module intends to 15replace several older modules and functions:: 16 17 os.system 18 os.spawn* 19 os.popen* 20 popen2.* 21 commands.* 22 23Information about how this module can be used to replace the older 24functions can be found in the subprocess-replacements_ section. 25 26.. seealso:: 27 28 POSIX users (Linux, BSD, etc.) are strongly encouraged to install 29 and use the much more recent subprocess32_ module instead of the 30 version included with python 2.7. It is a drop in replacement with 31 better behavior in many situations. 32 33 :pep:`324` -- PEP proposing the subprocess module 34 35.. _subprocess32: https://pypi.python.org/pypi/subprocess32/ 36 37Using the :mod:`subprocess` Module 38---------------------------------- 39 40The recommended way to launch subprocesses is to use the following 41convenience functions. For more advanced use cases when these do not 42meet your needs, use the underlying :class:`Popen` interface. 43 44 45.. function:: call(args, *, stdin=None, stdout=None, stderr=None, shell=False) 46 47 Run the command described by *args*. Wait for command to complete, then 48 return the :attr:`returncode` attribute. 49 50 The arguments shown above are merely the most common ones, described below 51 in :ref:`frequently-used-arguments` (hence the slightly odd notation in 52 the abbreviated signature). The full function signature is the same as 53 that of the :class:`Popen` constructor - this functions passes all 54 supplied arguments directly through to that interface. 55 56 Examples:: 57 58 >>> subprocess.call(["ls", "-l"]) 59 0 60 61 >>> subprocess.call("exit 1", shell=True) 62 1 63 64 .. warning:: 65 66 Using ``shell=True`` can be a security hazard. See the warning 67 under :ref:`frequently-used-arguments` for details. 68 69 .. note:: 70 71 Do not use ``stdout=PIPE`` or ``stderr=PIPE`` with this function 72 as that can deadlock based on the child process output volume. 73 Use :class:`Popen` with the :meth:`communicate` method when you 74 need pipes. 75 76 77.. function:: check_call(args, *, stdin=None, stdout=None, stderr=None, shell=False) 78 79 Run command with arguments. Wait for command to complete. If the return 80 code was zero then return, otherwise raise :exc:`CalledProcessError`. The 81 :exc:`CalledProcessError` object will have the return code in the 82 :attr:`~CalledProcessError.returncode` attribute. 83 84 The arguments shown above are merely the most common ones, described below 85 in :ref:`frequently-used-arguments` (hence the slightly odd notation in 86 the abbreviated signature). The full function signature is the same as 87 that of the :class:`Popen` constructor - this functions passes all 88 supplied arguments directly through to that interface. 89 90 Examples:: 91 92 >>> subprocess.check_call(["ls", "-l"]) 93 0 94 95 >>> subprocess.check_call("exit 1", shell=True) 96 Traceback (most recent call last): 97 ... 98 subprocess.CalledProcessError: Command 'exit 1' returned non-zero exit status 1 99 100 .. versionadded:: 2.5 101 102 .. warning:: 103 104 Using ``shell=True`` can be a security hazard. See the warning 105 under :ref:`frequently-used-arguments` for details. 106 107 .. note:: 108 109 Do not use ``stdout=PIPE`` or ``stderr=PIPE`` with this function 110 as that can deadlock based on the child process output volume. 111 Use :class:`Popen` with the :meth:`communicate` method when you 112 need pipes. 113 114 115.. function:: check_output(args, *, stdin=None, stderr=None, shell=False, universal_newlines=False) 116 117 Run command with arguments and return its output as a byte string. 118 119 If the return code was non-zero it raises a :exc:`CalledProcessError`. The 120 :exc:`CalledProcessError` object will have the return code in the 121 :attr:`~CalledProcessError.returncode` attribute and any output in the 122 :attr:`~CalledProcessError.output` attribute. 123 124 The arguments shown above are merely the most common ones, described below 125 in :ref:`frequently-used-arguments` (hence the slightly odd notation in 126 the abbreviated signature). The full function signature is largely the 127 same as that of the :class:`Popen` constructor, except that *stdout* is 128 not permitted as it is used internally. All other supplied arguments are 129 passed directly through to the :class:`Popen` constructor. 130 131 Examples:: 132 133 >>> subprocess.check_output(["echo", "Hello World!"]) 134 'Hello World!\n' 135 136 >>> subprocess.check_output("exit 1", shell=True) 137 Traceback (most recent call last): 138 ... 139 subprocess.CalledProcessError: Command 'exit 1' returned non-zero exit status 1 140 141 To also capture standard error in the result, use 142 ``stderr=subprocess.STDOUT``:: 143 144 >>> subprocess.check_output( 145 ... "ls non_existent_file; exit 0", 146 ... stderr=subprocess.STDOUT, 147 ... shell=True) 148 'ls: non_existent_file: No such file or directory\n' 149 150 .. versionadded:: 2.7 151 152 .. warning:: 153 154 Using ``shell=True`` can be a security hazard. See the warning 155 under :ref:`frequently-used-arguments` for details. 156 157 .. note:: 158 159 Do not use ``stderr=PIPE`` with this function as that can deadlock 160 based on the child process error volume. Use :class:`Popen` with 161 the :meth:`communicate` method when you need a stderr pipe. 162 163 164.. data:: PIPE 165 166 Special value that can be used as the *stdin*, *stdout* or *stderr* argument 167 to :class:`Popen` and indicates that a pipe to the standard stream should be 168 opened. 169 170 171.. data:: STDOUT 172 173 Special value that can be used as the *stderr* argument to :class:`Popen` and 174 indicates that standard error should go into the same handle as standard 175 output. 176 177 178.. exception:: CalledProcessError 179 180 Exception raised when a process run by :func:`check_call` or 181 :func:`check_output` returns a non-zero exit status. 182 183 .. attribute:: returncode 184 185 Exit status of the child process. 186 187 .. attribute:: cmd 188 189 Command that was used to spawn the child process. 190 191 .. attribute:: output 192 193 Output of the child process if this exception is raised by 194 :func:`check_output`. Otherwise, ``None``. 195 196 197 198.. _frequently-used-arguments: 199 200Frequently Used Arguments 201^^^^^^^^^^^^^^^^^^^^^^^^^ 202 203To support a wide variety of use cases, the :class:`Popen` constructor (and 204the convenience functions) accept a large number of optional arguments. For 205most typical use cases, many of these arguments can be safely left at their 206default values. The arguments that are most commonly needed are: 207 208 *args* is required for all calls and should be a string, or a sequence of 209 program arguments. Providing a sequence of arguments is generally 210 preferred, as it allows the module to take care of any required escaping 211 and quoting of arguments (e.g. to permit spaces in file names). If passing 212 a single string, either *shell* must be :const:`True` (see below) or else 213 the string must simply name the program to be executed without specifying 214 any arguments. 215 216 *stdin*, *stdout* and *stderr* specify the executed program's standard input, 217 standard output and standard error file handles, respectively. Valid values 218 are :data:`PIPE`, an existing file descriptor (a positive integer), an 219 existing file object, and ``None``. :data:`PIPE` indicates that a new pipe 220 to the child should be created. With the default settings of ``None``, no 221 redirection will occur; the child's file handles will be inherited from the 222 parent. Additionally, *stderr* can be :data:`STDOUT`, which indicates that 223 the stderr data from the child process should be captured into the same file 224 handle as for stdout. 225 226 .. index:: 227 single: universal newlines; subprocess module 228 229 When *stdout* or *stderr* are pipes and *universal_newlines* is 230 ``True`` then all line endings will be converted to ``'\n'`` as described 231 for the :term:`universal newlines` ``'U'`` mode argument to :func:`open`. 232 233 If *shell* is ``True``, the specified command will be executed through 234 the shell. This can be useful if you are using Python primarily for the 235 enhanced control flow it offers over most system shells and still want 236 convenient access to other shell features such as shell pipes, filename 237 wildcards, environment variable expansion, and expansion of ``~`` to a 238 user's home directory. However, note that Python itself offers 239 implementations of many shell-like features (in particular, :mod:`glob`, 240 :mod:`fnmatch`, :func:`os.walk`, :func:`os.path.expandvars`, 241 :func:`os.path.expanduser`, and :mod:`shutil`). 242 243 .. warning:: 244 245 Executing shell commands that incorporate unsanitized input from an 246 untrusted source makes a program vulnerable to `shell injection 247 <http://en.wikipedia.org/wiki/Shell_injection#Shell_injection>`_, 248 a serious security flaw which can result in arbitrary command execution. 249 For this reason, the use of ``shell=True`` is **strongly discouraged** 250 in cases where the command string is constructed from external input:: 251 252 >>> from subprocess import call 253 >>> filename = input("What file would you like to display?\n") 254 What file would you like to display? 255 non_existent; rm -rf / # 256 >>> call("cat " + filename, shell=True) # Uh-oh. This will end badly... 257 258 ``shell=False`` disables all shell based features, but does not suffer 259 from this vulnerability; see the Note in the :class:`Popen` constructor 260 documentation for helpful hints in getting ``shell=False`` to work. 261 262 When using ``shell=True``, :func:`pipes.quote` can be used to properly 263 escape whitespace and shell metacharacters in strings that are going to 264 be used to construct shell commands. 265 266These options, along with all of the other options, are described in more 267detail in the :class:`Popen` constructor documentation. 268 269 270Popen Constructor 271^^^^^^^^^^^^^^^^^ 272 273The underlying process creation and management in this module is handled by 274the :class:`Popen` class. It offers a lot of flexibility so that developers 275are able to handle the less common cases not covered by the convenience 276functions. 277 278 279.. class:: Popen(args, bufsize=0, executable=None, stdin=None, stdout=None, \ 280 stderr=None, preexec_fn=None, close_fds=False, shell=False, \ 281 cwd=None, env=None, universal_newlines=False, \ 282 startupinfo=None, creationflags=0) 283 284 Execute a child program in a new process. On Unix, the class uses 285 :meth:`os.execvp`-like behavior to execute the child program. On Windows, 286 the class uses the Windows ``CreateProcess()`` function. The arguments to 287 :class:`Popen` are as follows. 288 289 *args* should be a sequence of program arguments or else a single string. 290 By default, the program to execute is the first item in *args* if *args* is 291 a sequence. If *args* is a string, the interpretation is 292 platform-dependent and described below. See the *shell* and *executable* 293 arguments for additional differences from the default behavior. Unless 294 otherwise stated, it is recommended to pass *args* as a sequence. 295 296 On Unix, if *args* is a string, the string is interpreted as the name or 297 path of the program to execute. However, this can only be done if not 298 passing arguments to the program. 299 300 .. note:: 301 302 :meth:`shlex.split` can be useful when determining the correct 303 tokenization for *args*, especially in complex cases:: 304 305 >>> import shlex, subprocess 306 >>> command_line = raw_input() 307 /bin/vikings -input eggs.txt -output "spam spam.txt" -cmd "echo '$MONEY'" 308 >>> args = shlex.split(command_line) 309 >>> print args 310 ['/bin/vikings', '-input', 'eggs.txt', '-output', 'spam spam.txt', '-cmd', "echo '$MONEY'"] 311 >>> p = subprocess.Popen(args) # Success! 312 313 Note in particular that options (such as *-input*) and arguments (such 314 as *eggs.txt*) that are separated by whitespace in the shell go in separate 315 list elements, while arguments that need quoting or backslash escaping when 316 used in the shell (such as filenames containing spaces or the *echo* command 317 shown above) are single list elements. 318 319 On Windows, if *args* is a sequence, it will be converted to a string in a 320 manner described in :ref:`converting-argument-sequence`. This is because 321 the underlying ``CreateProcess()`` operates on strings. 322 323 The *shell* argument (which defaults to ``False``) specifies whether to use 324 the shell as the program to execute. If *shell* is ``True``, it is 325 recommended to pass *args* as a string rather than as a sequence. 326 327 On Unix with ``shell=True``, the shell defaults to :file:`/bin/sh`. If 328 *args* is a string, the string specifies the command 329 to execute through the shell. This means that the string must be 330 formatted exactly as it would be when typed at the shell prompt. This 331 includes, for example, quoting or backslash escaping filenames with spaces in 332 them. If *args* is a sequence, the first item specifies the command string, and 333 any additional items will be treated as additional arguments to the shell 334 itself. That is to say, :class:`Popen` does the equivalent of:: 335 336 Popen(['/bin/sh', '-c', args[0], args[1], ...]) 337 338 On Windows with ``shell=True``, the :envvar:`COMSPEC` environment variable 339 specifies the default shell. The only time you need to specify 340 ``shell=True`` on Windows is when the command you wish to execute is built 341 into the shell (e.g. :command:`dir` or :command:`copy`). You do not need 342 ``shell=True`` to run a batch file or console-based executable. 343 344 .. warning:: 345 346 Passing ``shell=True`` can be a security hazard if combined with 347 untrusted input. See the warning under :ref:`frequently-used-arguments` 348 for details. 349 350 *bufsize*, if given, has the same meaning as the corresponding argument to the 351 built-in open() function: :const:`0` means unbuffered, :const:`1` means line 352 buffered, any other positive value means use a buffer of (approximately) that 353 size. A negative *bufsize* means to use the system default, which usually means 354 fully buffered. The default value for *bufsize* is :const:`0` (unbuffered). 355 356 .. note:: 357 358 If you experience performance issues, it is recommended that you try to 359 enable buffering by setting *bufsize* to either -1 or a large enough 360 positive value (such as 4096). 361 362 The *executable* argument specifies a replacement program to execute. It 363 is very seldom needed. When ``shell=False``, *executable* replaces the 364 program to execute specified by *args*. However, the original *args* is 365 still passed to the program. Most programs treat the program specified 366 by *args* as the command name, which can then be different from the program 367 actually executed. On Unix, the *args* name 368 becomes the display name for the executable in utilities such as 369 :program:`ps`. If ``shell=True``, on Unix the *executable* argument 370 specifies a replacement shell for the default :file:`/bin/sh`. 371 372 *stdin*, *stdout* and *stderr* specify the executed program's standard input, 373 standard output and standard error file handles, respectively. Valid values 374 are :data:`PIPE`, an existing file descriptor (a positive integer), an 375 existing file object, and ``None``. :data:`PIPE` indicates that a new pipe 376 to the child should be created. With the default settings of ``None``, no 377 redirection will occur; the child's file handles will be inherited from the 378 parent. Additionally, *stderr* can be :data:`STDOUT`, which indicates that 379 the stderr data from the child process should be captured into the same file 380 handle as for stdout. 381 382 If *preexec_fn* is set to a callable object, this object will be called in the 383 child process just before the child is executed. (Unix only) 384 385 If *close_fds* is true, all file descriptors except :const:`0`, :const:`1` and 386 :const:`2` will be closed before the child process is executed. (Unix only). 387 Or, on Windows, if *close_fds* is true then no handles will be inherited by the 388 child process. Note that on Windows, you cannot set *close_fds* to true and 389 also redirect the standard handles by setting *stdin*, *stdout* or *stderr*. 390 391 If *cwd* is not ``None``, the child's current directory will be changed to *cwd* 392 before it is executed. Note that this directory is not considered when 393 searching the executable, so you can't specify the program's path relative to 394 *cwd*. 395 396 If *env* is not ``None``, it must be a mapping that defines the environment 397 variables for the new process; these are used instead of inheriting the current 398 process' environment, which is the default behavior. 399 400 .. note:: 401 402 If specified, *env* must provide any variables required 403 for the program to execute. On Windows, in order to run a 404 `side-by-side assembly`_ the specified *env* **must** include a valid 405 :envvar:`SystemRoot`. 406 407 .. _side-by-side assembly: https://en.wikipedia.org/wiki/Side-by-Side_Assembly 408 409 If *universal_newlines* is ``True``, the file objects *stdout* and *stderr* 410 are opened as text files in :term:`universal newlines` mode. Lines may be 411 terminated by any of ``'\n'``, the Unix end-of-line convention, ``'\r'``, 412 the old Macintosh convention or ``'\r\n'``, the Windows convention. All of 413 these external representations are seen as ``'\n'`` by the Python program. 414 415 .. note:: 416 417 This feature is only available if Python is built with universal newline 418 support (the default). Also, the newlines attribute of the file objects 419 :attr:`stdout`, :attr:`stdin` and :attr:`stderr` are not updated by the 420 communicate() method. 421 422 If given, *startupinfo* will be a :class:`STARTUPINFO` object, which is 423 passed to the underlying ``CreateProcess`` function. 424 *creationflags*, if given, can be :data:`CREATE_NEW_CONSOLE` or 425 :data:`CREATE_NEW_PROCESS_GROUP`. (Windows only) 426 427 428Exceptions 429^^^^^^^^^^ 430 431Exceptions raised in the child process, before the new program has started to 432execute, will be re-raised in the parent. Additionally, the exception object 433will have one extra attribute called :attr:`child_traceback`, which is a string 434containing traceback information from the child's point of view. 435 436The most common exception raised is :exc:`OSError`. This occurs, for example, 437when trying to execute a non-existent file. Applications should prepare for 438:exc:`OSError` exceptions. 439 440A :exc:`ValueError` will be raised if :class:`Popen` is called with invalid 441arguments. 442 443:func:`check_call` and :func:`check_output` will raise 444:exc:`CalledProcessError` if the called process returns a non-zero return 445code. 446 447 448Security 449^^^^^^^^ 450 451Unlike some other popen functions, this implementation will never call a 452system shell implicitly. This means that all characters, including shell 453metacharacters, can safely be passed to child processes. Obviously, if the 454shell is invoked explicitly, then it is the application's responsibility to 455ensure that all whitespace and metacharacters are quoted appropriately. 456 457 458Popen Objects 459------------- 460 461Instances of the :class:`Popen` class have the following methods: 462 463 464.. method:: Popen.poll() 465 466 Check if child process has terminated. Set and return 467 :attr:`~Popen.returncode` attribute. 468 469 470.. method:: Popen.wait() 471 472 Wait for child process to terminate. Set and return 473 :attr:`~Popen.returncode` attribute. 474 475 .. warning:: 476 477 This will deadlock when using ``stdout=PIPE`` and/or 478 ``stderr=PIPE`` and the child process generates enough output to 479 a pipe such that it blocks waiting for the OS pipe buffer to 480 accept more data. Use :meth:`communicate` to avoid that. 481 482 483.. method:: Popen.communicate(input=None) 484 485 Interact with process: Send data to stdin. Read data from stdout and stderr, 486 until end-of-file is reached. Wait for process to terminate. The optional 487 *input* argument should be a string to be sent to the child process, or 488 ``None``, if no data should be sent to the child. 489 490 :meth:`communicate` returns a tuple ``(stdoutdata, stderrdata)``. 491 492 Note that if you want to send data to the process's stdin, you need to create 493 the Popen object with ``stdin=PIPE``. Similarly, to get anything other than 494 ``None`` in the result tuple, you need to give ``stdout=PIPE`` and/or 495 ``stderr=PIPE`` too. 496 497 .. note:: 498 499 The data read is buffered in memory, so do not use this method if the data 500 size is large or unlimited. 501 502 503.. method:: Popen.send_signal(signal) 504 505 Sends the signal *signal* to the child. 506 507 .. note:: 508 509 On Windows, SIGTERM is an alias for :meth:`terminate`. CTRL_C_EVENT and 510 CTRL_BREAK_EVENT can be sent to processes started with a *creationflags* 511 parameter which includes `CREATE_NEW_PROCESS_GROUP`. 512 513 .. versionadded:: 2.6 514 515 516.. method:: Popen.terminate() 517 518 Stop the child. On Posix OSs the method sends SIGTERM to the 519 child. On Windows the Win32 API function :c:func:`TerminateProcess` is called 520 to stop the child. 521 522 .. versionadded:: 2.6 523 524 525.. method:: Popen.kill() 526 527 Kills the child. On Posix OSs the function sends SIGKILL to the child. 528 On Windows :meth:`kill` is an alias for :meth:`terminate`. 529 530 .. versionadded:: 2.6 531 532 533The following attributes are also available: 534 535.. warning:: 536 537 Use :meth:`~Popen.communicate` rather than :attr:`.stdin.write <Popen.stdin>`, 538 :attr:`.stdout.read <Popen.stdout>` or :attr:`.stderr.read <Popen.stderr>` to avoid 539 deadlocks due to any of the other OS pipe buffers filling up and blocking the 540 child process. 541 542 543.. attribute:: Popen.stdin 544 545 If the *stdin* argument was :data:`PIPE`, this attribute is a file object 546 that provides input to the child process. Otherwise, it is ``None``. 547 548 549.. attribute:: Popen.stdout 550 551 If the *stdout* argument was :data:`PIPE`, this attribute is a file object 552 that provides output from the child process. Otherwise, it is ``None``. 553 554 555.. attribute:: Popen.stderr 556 557 If the *stderr* argument was :data:`PIPE`, this attribute is a file object 558 that provides error output from the child process. Otherwise, it is 559 ``None``. 560 561 562.. attribute:: Popen.pid 563 564 The process ID of the child process. 565 566 Note that if you set the *shell* argument to ``True``, this is the process ID 567 of the spawned shell. 568 569 570.. attribute:: Popen.returncode 571 572 The child return code, set by :meth:`poll` and :meth:`wait` (and indirectly 573 by :meth:`communicate`). A ``None`` value indicates that the process 574 hasn't terminated yet. 575 576 A negative value ``-N`` indicates that the child was terminated by signal 577 ``N`` (Unix only). 578 579 580Windows Popen Helpers 581--------------------- 582 583The :class:`STARTUPINFO` class and following constants are only available 584on Windows. 585 586.. class:: STARTUPINFO() 587 588 Partial support of the Windows 589 `STARTUPINFO <https://msdn.microsoft.com/en-us/library/ms686331(v=vs.85).aspx>`__ 590 structure is used for :class:`Popen` creation. 591 592 .. attribute:: dwFlags 593 594 A bit field that determines whether certain :class:`STARTUPINFO` 595 attributes are used when the process creates a window. :: 596 597 si = subprocess.STARTUPINFO() 598 si.dwFlags = subprocess.STARTF_USESTDHANDLES | subprocess.STARTF_USESHOWWINDOW 599 600 .. attribute:: hStdInput 601 602 If :attr:`dwFlags` specifies :data:`STARTF_USESTDHANDLES`, this attribute 603 is the standard input handle for the process. If 604 :data:`STARTF_USESTDHANDLES` is not specified, the default for standard 605 input is the keyboard buffer. 606 607 .. attribute:: hStdOutput 608 609 If :attr:`dwFlags` specifies :data:`STARTF_USESTDHANDLES`, this attribute 610 is the standard output handle for the process. Otherwise, this attribute 611 is ignored and the default for standard output is the console window's 612 buffer. 613 614 .. attribute:: hStdError 615 616 If :attr:`dwFlags` specifies :data:`STARTF_USESTDHANDLES`, this attribute 617 is the standard error handle for the process. Otherwise, this attribute is 618 ignored and the default for standard error is the console window's buffer. 619 620 .. attribute:: wShowWindow 621 622 If :attr:`dwFlags` specifies :data:`STARTF_USESHOWWINDOW`, this attribute 623 can be any of the values that can be specified in the ``nCmdShow`` 624 parameter for the 625 `ShowWindow <https://msdn.microsoft.com/en-us/library/ms633548(v=vs.85).aspx>`__ 626 function, except for ``SW_SHOWDEFAULT``. Otherwise, this attribute is 627 ignored. 628 629 :data:`SW_HIDE` is provided for this attribute. It is used when 630 :class:`Popen` is called with ``shell=True``. 631 632 633Constants 634^^^^^^^^^ 635 636The :mod:`subprocess` module exposes the following constants. 637 638.. data:: STD_INPUT_HANDLE 639 640 The standard input device. Initially, this is the console input buffer, 641 ``CONIN$``. 642 643.. data:: STD_OUTPUT_HANDLE 644 645 The standard output device. Initially, this is the active console screen 646 buffer, ``CONOUT$``. 647 648.. data:: STD_ERROR_HANDLE 649 650 The standard error device. Initially, this is the active console screen 651 buffer, ``CONOUT$``. 652 653.. data:: SW_HIDE 654 655 Hides the window. Another window will be activated. 656 657.. data:: STARTF_USESTDHANDLES 658 659 Specifies that the :attr:`STARTUPINFO.hStdInput`, 660 :attr:`STARTUPINFO.hStdOutput`, and :attr:`STARTUPINFO.hStdError` attributes 661 contain additional information. 662 663.. data:: STARTF_USESHOWWINDOW 664 665 Specifies that the :attr:`STARTUPINFO.wShowWindow` attribute contains 666 additional information. 667 668.. data:: CREATE_NEW_CONSOLE 669 670 The new process has a new console, instead of inheriting its parent's 671 console (the default). 672 673 This flag is always set when :class:`Popen` is created with ``shell=True``. 674 675.. data:: CREATE_NEW_PROCESS_GROUP 676 677 A :class:`Popen` ``creationflags`` parameter to specify that a new process 678 group will be created. This flag is necessary for using :func:`os.kill` 679 on the subprocess. 680 681 This flag is ignored if :data:`CREATE_NEW_CONSOLE` is specified. 682 683 684.. _subprocess-replacements: 685 686Replacing Older Functions with the :mod:`subprocess` Module 687----------------------------------------------------------- 688 689In this section, "a becomes b" means that b can be used as a replacement for a. 690 691.. note:: 692 693 All "a" functions in this section fail (more or less) silently if the 694 executed program cannot be found; the "b" replacements raise :exc:`OSError` 695 instead. 696 697 In addition, the replacements using :func:`check_output` will fail with a 698 :exc:`CalledProcessError` if the requested operation produces a non-zero 699 return code. The output is still available as the 700 :attr:`~CalledProcessError.output` attribute of the raised exception. 701 702In the following examples, we assume that the relevant functions have already 703been imported from the :mod:`subprocess` module. 704 705 706Replacing /bin/sh shell backquote 707^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 708 709.. code-block:: bash 710 711 output=`mycmd myarg` 712 713becomes:: 714 715 output = check_output(["mycmd", "myarg"]) 716 717Replacing shell pipeline 718^^^^^^^^^^^^^^^^^^^^^^^^ 719 720.. code-block:: bash 721 722 output=`dmesg | grep hda` 723 724becomes:: 725 726 p1 = Popen(["dmesg"], stdout=PIPE) 727 p2 = Popen(["grep", "hda"], stdin=p1.stdout, stdout=PIPE) 728 p1.stdout.close() # Allow p1 to receive a SIGPIPE if p2 exits. 729 output = p2.communicate()[0] 730 731The p1.stdout.close() call after starting the p2 is important in order for p1 732to receive a SIGPIPE if p2 exits before p1. 733 734Alternatively, for trusted input, the shell's own pipeline support may still 735be used directly: 736 737.. code-block:: bash 738 739 output=`dmesg | grep hda` 740 741becomes:: 742 743 output=check_output("dmesg | grep hda", shell=True) 744 745 746Replacing :func:`os.system` 747^^^^^^^^^^^^^^^^^^^^^^^^^^^ 748 749:: 750 751 status = os.system("mycmd" + " myarg") 752 # becomes 753 status = subprocess.call("mycmd" + " myarg", shell=True) 754 755Notes: 756 757* Calling the program through the shell is usually not required. 758 759A more realistic example would look like this:: 760 761 try: 762 retcode = call("mycmd" + " myarg", shell=True) 763 if retcode < 0: 764 print >>sys.stderr, "Child was terminated by signal", -retcode 765 else: 766 print >>sys.stderr, "Child returned", retcode 767 except OSError as e: 768 print >>sys.stderr, "Execution failed:", e 769 770 771Replacing the :func:`os.spawn <os.spawnl>` family 772^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 773 774P_NOWAIT example:: 775 776 pid = os.spawnlp(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg") 777 ==> 778 pid = Popen(["/bin/mycmd", "myarg"]).pid 779 780P_WAIT example:: 781 782 retcode = os.spawnlp(os.P_WAIT, "/bin/mycmd", "mycmd", "myarg") 783 ==> 784 retcode = call(["/bin/mycmd", "myarg"]) 785 786Vector example:: 787 788 os.spawnvp(os.P_NOWAIT, path, args) 789 ==> 790 Popen([path] + args[1:]) 791 792Environment example:: 793 794 os.spawnlpe(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg", env) 795 ==> 796 Popen(["/bin/mycmd", "myarg"], env={"PATH": "/usr/bin"}) 797 798 799Replacing :func:`os.popen`, :func:`os.popen2`, :func:`os.popen3` 800^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 801 802:: 803 804 pipe = os.popen("cmd", 'r', bufsize) 805 ==> 806 pipe = Popen("cmd", shell=True, bufsize=bufsize, stdout=PIPE).stdout 807 808:: 809 810 pipe = os.popen("cmd", 'w', bufsize) 811 ==> 812 pipe = Popen("cmd", shell=True, bufsize=bufsize, stdin=PIPE).stdin 813 814:: 815 816 (child_stdin, child_stdout) = os.popen2("cmd", mode, bufsize) 817 ==> 818 p = Popen("cmd", shell=True, bufsize=bufsize, 819 stdin=PIPE, stdout=PIPE, close_fds=True) 820 (child_stdin, child_stdout) = (p.stdin, p.stdout) 821 822:: 823 824 (child_stdin, 825 child_stdout, 826 child_stderr) = os.popen3("cmd", mode, bufsize) 827 ==> 828 p = Popen("cmd", shell=True, bufsize=bufsize, 829 stdin=PIPE, stdout=PIPE, stderr=PIPE, close_fds=True) 830 (child_stdin, 831 child_stdout, 832 child_stderr) = (p.stdin, p.stdout, p.stderr) 833 834:: 835 836 (child_stdin, child_stdout_and_stderr) = os.popen4("cmd", mode, 837 bufsize) 838 ==> 839 p = Popen("cmd", shell=True, bufsize=bufsize, 840 stdin=PIPE, stdout=PIPE, stderr=STDOUT, close_fds=True) 841 (child_stdin, child_stdout_and_stderr) = (p.stdin, p.stdout) 842 843On Unix, os.popen2, os.popen3 and os.popen4 also accept a sequence as 844the command to execute, in which case arguments will be passed 845directly to the program without shell intervention. This usage can be 846replaced as follows:: 847 848 (child_stdin, child_stdout) = os.popen2(["/bin/ls", "-l"], mode, 849 bufsize) 850 ==> 851 p = Popen(["/bin/ls", "-l"], bufsize=bufsize, stdin=PIPE, stdout=PIPE) 852 (child_stdin, child_stdout) = (p.stdin, p.stdout) 853 854Return code handling translates as follows:: 855 856 pipe = os.popen("cmd", 'w') 857 ... 858 rc = pipe.close() 859 if rc is not None and rc >> 8: 860 print "There were some errors" 861 ==> 862 process = Popen("cmd", shell=True, stdin=PIPE) 863 ... 864 process.stdin.close() 865 if process.wait() != 0: 866 print "There were some errors" 867 868 869Replacing functions from the :mod:`popen2` module 870^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 871 872:: 873 874 (child_stdout, child_stdin) = popen2.popen2("somestring", bufsize, mode) 875 ==> 876 p = Popen("somestring", shell=True, bufsize=bufsize, 877 stdin=PIPE, stdout=PIPE, close_fds=True) 878 (child_stdout, child_stdin) = (p.stdout, p.stdin) 879 880On Unix, popen2 also accepts a sequence as the command to execute, in 881which case arguments will be passed directly to the program without 882shell intervention. This usage can be replaced as follows:: 883 884 (child_stdout, child_stdin) = popen2.popen2(["mycmd", "myarg"], bufsize, 885 mode) 886 ==> 887 p = Popen(["mycmd", "myarg"], bufsize=bufsize, 888 stdin=PIPE, stdout=PIPE, close_fds=True) 889 (child_stdout, child_stdin) = (p.stdout, p.stdin) 890 891:class:`popen2.Popen3` and :class:`popen2.Popen4` basically work as 892:class:`subprocess.Popen`, except that: 893 894* :class:`Popen` raises an exception if the execution fails. 895 896* the *capturestderr* argument is replaced with the *stderr* argument. 897 898* ``stdin=PIPE`` and ``stdout=PIPE`` must be specified. 899 900* popen2 closes all file descriptors by default, but you have to specify 901 ``close_fds=True`` with :class:`Popen`. 902 903 904Notes 905----- 906 907.. _converting-argument-sequence: 908 909Converting an argument sequence to a string on Windows 910^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 911 912On Windows, an *args* sequence is converted to a string that can be parsed 913using the following rules (which correspond to the rules used by the MS C 914runtime): 915 9161. Arguments are delimited by white space, which is either a 917 space or a tab. 918 9192. A string surrounded by double quotation marks is 920 interpreted as a single argument, regardless of white space 921 contained within. A quoted string can be embedded in an 922 argument. 923 9243. A double quotation mark preceded by a backslash is 925 interpreted as a literal double quotation mark. 926 9274. Backslashes are interpreted literally, unless they 928 immediately precede a double quotation mark. 929 9305. If backslashes immediately precede a double quotation mark, 931 every pair of backslashes is interpreted as a literal 932 backslash. If the number of backslashes is odd, the last 933 backslash escapes the next double quotation mark as 934 described in rule 3. 935 936