Run command with arguments and return a CompletedProcess instance. The returned instance will have attributes args, returncode, stdout and stderr. By default, stdout and stderr are not captured, and those attributes will be None. Pass stdout=PIPE and/or stderr=PIPE in order to captu
(*popenargs,
input=None, capture_output=False, timeout=None, check=False, **kwargs)
| 504 | |
| 505 | |
| 506 | def run(*popenargs, |
| 507 | input=None, capture_output=False, timeout=None, check=False, **kwargs): |
| 508 | """Run command with arguments and return a CompletedProcess instance. |
| 509 | |
| 510 | The returned instance will have attributes args, returncode, stdout and |
| 511 | stderr. By default, stdout and stderr are not captured, and those attributes |
| 512 | will be None. Pass stdout=PIPE and/or stderr=PIPE in order to capture them, |
| 513 | or pass capture_output=True to capture both. |
| 514 | |
| 515 | If check is True and the exit code was non-zero, it raises a |
| 516 | CalledProcessError. The CalledProcessError object will have the return code |
| 517 | in the returncode attribute, and output & stderr attributes if those streams |
| 518 | were captured. |
| 519 | |
| 520 | If timeout is given, and the process takes too long, a TimeoutExpired |
| 521 | exception will be raised. |
| 522 | |
| 523 | There is an optional argument "input", allowing you to |
| 524 | pass bytes or a string to the subprocess's stdin. If you use this argument |
| 525 | you may not also use the Popen constructor's "stdin" argument, as |
| 526 | it will be used internally. |
| 527 | |
| 528 | By default, all communication is in bytes, and therefore any "input" should |
| 529 | be bytes, and the stdout and stderr will be bytes. If in text mode, any |
| 530 | "input" should be a string, and stdout and stderr will be strings decoded |
| 531 | according to locale encoding, or by "encoding" if set. Text mode is |
| 532 | triggered by setting any of text, encoding, errors or universal_newlines. |
| 533 | |
| 534 | The other arguments are the same as for the Popen constructor. |
| 535 | """ |
| 536 | if input is not None: |
| 537 | if kwargs.get('stdin') is not None: |
| 538 | raise ValueError('stdin and input arguments may not both be used.') |
| 539 | kwargs['stdin'] = PIPE |
| 540 | |
| 541 | if capture_output: |
| 542 | if kwargs.get('stdout') is not None or kwargs.get('stderr') is not None: |
| 543 | raise ValueError('stdout and stderr arguments may not be used ' |
| 544 | 'with capture_output.') |
| 545 | kwargs['stdout'] = PIPE |
| 546 | kwargs['stderr'] = PIPE |
| 547 | |
| 548 | with Popen(*popenargs, **kwargs) as process: |
| 549 | try: |
| 550 | stdout, stderr = process.communicate(input, timeout=timeout) |
| 551 | except TimeoutExpired as exc: |
| 552 | process.kill() |
| 553 | if _mswindows: |
| 554 | # Windows accumulates the output in a single blocking |
| 555 | # read() call run on child threads, with the timeout |
| 556 | # being done in a join() on those threads. communicate() |
| 557 | # _after_ kill() is required to collect that and add it |
| 558 | # to the exception. |
| 559 | exc.stdout, exc.stderr = process.communicate() |
| 560 | else: |
| 561 | # POSIX _communicate already populated the output so |
| 562 | # far into the TimeoutExpired exception. |
| 563 | process.wait() |
no test coverage detected