Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/subprocess.py: 16%
956 statements
« prev ^ index » next coverage.py v7.0.5, created at 2023-01-17 06:13 +0000
1# subprocess - Subprocesses with accessible I/O streams
2#
3# For more information about this module, see PEP 324.
4#
5# Copyright (c) 2003-2005 by Peter Astrand <astrand@lysator.liu.se>
6#
7# Licensed to PSF under a Contributor Agreement.
8# See http://www.python.org/2.4/license for licensing details.
10r"""Subprocesses with accessible I/O streams
12This module allows you to spawn processes, connect to their
13input/output/error pipes, and obtain their return codes.
15For a complete description of this module see the Python documentation.
17Main API
18========
19run(...): Runs a command, waits for it to complete, then returns a
20 CompletedProcess instance.
21Popen(...): A class for flexibly executing a command in a new process
23Constants
24---------
25DEVNULL: Special value that indicates that os.devnull should be used
26PIPE: Special value that indicates a pipe should be created
27STDOUT: Special value that indicates that stderr should go to stdout
30Older API
31=========
32call(...): Runs a command, waits for it to complete, then returns
33 the return code.
34check_call(...): Same as call() but raises CalledProcessError()
35 if return code is not 0
36check_output(...): Same as check_call() but returns the contents of
37 stdout instead of a return code
38getoutput(...): Runs a command in the shell, waits for it to complete,
39 then returns the output
40getstatusoutput(...): Runs a command in the shell, waits for it to complete,
41 then returns a (exitcode, output) tuple
42"""
44import builtins
45import errno
46import io
47import os
48import time
49import signal
50import sys
51import threading
52import warnings
53import contextlib
54from time import monotonic as _time
57__all__ = ["Popen", "PIPE", "STDOUT", "call", "check_call", "getstatusoutput",
58 "getoutput", "check_output", "run", "CalledProcessError", "DEVNULL",
59 "SubprocessError", "TimeoutExpired", "CompletedProcess"]
60 # NOTE: We intentionally exclude list2cmdline as it is
61 # considered an internal implementation detail. issue10838.
63try:
64 import msvcrt
65 import _winapi
66 _mswindows = True
67except ModuleNotFoundError:
68 _mswindows = False
69 import _posixsubprocess
70 import select
71 import selectors
72else:
73 from _winapi import (CREATE_NEW_CONSOLE, CREATE_NEW_PROCESS_GROUP,
74 STD_INPUT_HANDLE, STD_OUTPUT_HANDLE,
75 STD_ERROR_HANDLE, SW_HIDE,
76 STARTF_USESTDHANDLES, STARTF_USESHOWWINDOW,
77 ABOVE_NORMAL_PRIORITY_CLASS, BELOW_NORMAL_PRIORITY_CLASS,
78 HIGH_PRIORITY_CLASS, IDLE_PRIORITY_CLASS,
79 NORMAL_PRIORITY_CLASS, REALTIME_PRIORITY_CLASS,
80 CREATE_NO_WINDOW, DETACHED_PROCESS,
81 CREATE_DEFAULT_ERROR_MODE, CREATE_BREAKAWAY_FROM_JOB)
83 __all__.extend(["CREATE_NEW_CONSOLE", "CREATE_NEW_PROCESS_GROUP",
84 "STD_INPUT_HANDLE", "STD_OUTPUT_HANDLE",
85 "STD_ERROR_HANDLE", "SW_HIDE",
86 "STARTF_USESTDHANDLES", "STARTF_USESHOWWINDOW",
87 "STARTUPINFO",
88 "ABOVE_NORMAL_PRIORITY_CLASS", "BELOW_NORMAL_PRIORITY_CLASS",
89 "HIGH_PRIORITY_CLASS", "IDLE_PRIORITY_CLASS",
90 "NORMAL_PRIORITY_CLASS", "REALTIME_PRIORITY_CLASS",
91 "CREATE_NO_WINDOW", "DETACHED_PROCESS",
92 "CREATE_DEFAULT_ERROR_MODE", "CREATE_BREAKAWAY_FROM_JOB"])
95# Exception classes used by this module.
96class SubprocessError(Exception): pass
99class CalledProcessError(SubprocessError):
100 """Raised when run() is called with check=True and the process
101 returns a non-zero exit status.
103 Attributes:
104 cmd, returncode, stdout, stderr, output
105 """
106 def __init__(self, returncode, cmd, output=None, stderr=None):
107 self.returncode = returncode
108 self.cmd = cmd
109 self.output = output
110 self.stderr = stderr
112 def __str__(self):
113 if self.returncode and self.returncode < 0:
114 try:
115 return "Command '%s' died with %r." % (
116 self.cmd, signal.Signals(-self.returncode))
117 except ValueError:
118 return "Command '%s' died with unknown signal %d." % (
119 self.cmd, -self.returncode)
120 else:
121 return "Command '%s' returned non-zero exit status %d." % (
122 self.cmd, self.returncode)
124 @property
125 def stdout(self):
126 """Alias for output attribute, to match stderr"""
127 return self.output
129 @stdout.setter
130 def stdout(self, value):
131 # There's no obvious reason to set this, but allow it anyway so
132 # .stdout is a transparent alias for .output
133 self.output = value
136class TimeoutExpired(SubprocessError):
137 """This exception is raised when the timeout expires while waiting for a
138 child process.
140 Attributes:
141 cmd, output, stdout, stderr, timeout
142 """
143 def __init__(self, cmd, timeout, output=None, stderr=None):
144 self.cmd = cmd
145 self.timeout = timeout
146 self.output = output
147 self.stderr = stderr
149 def __str__(self):
150 return ("Command '%s' timed out after %s seconds" %
151 (self.cmd, self.timeout))
153 @property
154 def stdout(self):
155 return self.output
157 @stdout.setter
158 def stdout(self, value):
159 # There's no obvious reason to set this, but allow it anyway so
160 # .stdout is a transparent alias for .output
161 self.output = value
164if _mswindows:
165 class STARTUPINFO:
166 def __init__(self, *, dwFlags=0, hStdInput=None, hStdOutput=None,
167 hStdError=None, wShowWindow=0, lpAttributeList=None):
168 self.dwFlags = dwFlags
169 self.hStdInput = hStdInput
170 self.hStdOutput = hStdOutput
171 self.hStdError = hStdError
172 self.wShowWindow = wShowWindow
173 self.lpAttributeList = lpAttributeList or {"handle_list": []}
175 def copy(self):
176 attr_list = self.lpAttributeList.copy()
177 if 'handle_list' in attr_list:
178 attr_list['handle_list'] = list(attr_list['handle_list'])
180 return STARTUPINFO(dwFlags=self.dwFlags,
181 hStdInput=self.hStdInput,
182 hStdOutput=self.hStdOutput,
183 hStdError=self.hStdError,
184 wShowWindow=self.wShowWindow,
185 lpAttributeList=attr_list)
188 class Handle(int):
189 closed = False
191 def Close(self, CloseHandle=_winapi.CloseHandle):
192 if not self.closed:
193 self.closed = True
194 CloseHandle(self)
196 def Detach(self):
197 if not self.closed:
198 self.closed = True
199 return int(self)
200 raise ValueError("already closed")
202 def __repr__(self):
203 return "%s(%d)" % (self.__class__.__name__, int(self))
205 __del__ = Close
206else:
207 # When select or poll has indicated that the file is writable,
208 # we can write up to _PIPE_BUF bytes without risk of blocking.
209 # POSIX defines PIPE_BUF as >= 512.
210 _PIPE_BUF = getattr(select, 'PIPE_BUF', 512)
212 # poll/select have the advantage of not requiring any extra file
213 # descriptor, contrarily to epoll/kqueue (also, they require a single
214 # syscall).
215 if hasattr(selectors, 'PollSelector'):
216 _PopenSelector = selectors.PollSelector
217 else:
218 _PopenSelector = selectors.SelectSelector
221if _mswindows:
222 # On Windows we just need to close `Popen._handle` when we no longer need
223 # it, so that the kernel can free it. `Popen._handle` gets closed
224 # implicitly when the `Popen` instance is finalized (see `Handle.__del__`,
225 # which is calling `CloseHandle` as requested in [1]), so there is nothing
226 # for `_cleanup` to do.
227 #
228 # [1] https://docs.microsoft.com/en-us/windows/desktop/ProcThread/
229 # creating-processes
230 _active = None
232 def _cleanup():
233 pass
234else:
235 # This lists holds Popen instances for which the underlying process had not
236 # exited at the time its __del__ method got called: those processes are
237 # wait()ed for synchronously from _cleanup() when a new Popen object is
238 # created, to avoid zombie processes.
239 _active = []
241 def _cleanup():
242 if _active is None:
243 return
244 for inst in _active[:]:
245 res = inst._internal_poll(_deadstate=sys.maxsize)
246 if res is not None:
247 try:
248 _active.remove(inst)
249 except ValueError:
250 # This can happen if two threads create a new Popen instance.
251 # It's harmless that it was already removed, so ignore.
252 pass
254PIPE = -1
255STDOUT = -2
256DEVNULL = -3
259# XXX This function is only used by multiprocessing and the test suite,
260# but it's here so that it can be imported when Python is compiled without
261# threads.
263def _optim_args_from_interpreter_flags():
264 """Return a list of command-line arguments reproducing the current
265 optimization settings in sys.flags."""
266 args = []
267 value = sys.flags.optimize
268 if value > 0:
269 args.append('-' + 'O' * value)
270 return args
273def _args_from_interpreter_flags():
274 """Return a list of command-line arguments reproducing the current
275 settings in sys.flags, sys.warnoptions and sys._xoptions."""
276 flag_opt_map = {
277 'debug': 'd',
278 # 'inspect': 'i',
279 # 'interactive': 'i',
280 'dont_write_bytecode': 'B',
281 'no_site': 'S',
282 'verbose': 'v',
283 'bytes_warning': 'b',
284 'quiet': 'q',
285 # -O is handled in _optim_args_from_interpreter_flags()
286 }
287 args = _optim_args_from_interpreter_flags()
288 for flag, opt in flag_opt_map.items():
289 v = getattr(sys.flags, flag)
290 if v > 0:
291 args.append('-' + opt * v)
293 if sys.flags.isolated:
294 args.append('-I')
295 else:
296 if sys.flags.ignore_environment:
297 args.append('-E')
298 if sys.flags.no_user_site:
299 args.append('-s')
301 # -W options
302 warnopts = sys.warnoptions[:]
303 bytes_warning = sys.flags.bytes_warning
304 xoptions = getattr(sys, '_xoptions', {})
305 dev_mode = ('dev' in xoptions)
307 if bytes_warning > 1:
308 warnopts.remove("error::BytesWarning")
309 elif bytes_warning:
310 warnopts.remove("default::BytesWarning")
311 if dev_mode:
312 warnopts.remove('default')
313 for opt in warnopts:
314 args.append('-W' + opt)
316 # -X options
317 if dev_mode:
318 args.extend(('-X', 'dev'))
319 for opt in ('faulthandler', 'tracemalloc', 'importtime',
320 'showalloccount', 'showrefcount', 'utf8'):
321 if opt in xoptions:
322 value = xoptions[opt]
323 if value is True:
324 arg = opt
325 else:
326 arg = '%s=%s' % (opt, value)
327 args.extend(('-X', arg))
329 return args
332def call(*popenargs, timeout=None, **kwargs):
333 """Run command with arguments. Wait for command to complete or
334 timeout, then return the returncode attribute.
336 The arguments are the same as for the Popen constructor. Example:
338 retcode = call(["ls", "-l"])
339 """
340 with Popen(*popenargs, **kwargs) as p:
341 try:
342 return p.wait(timeout=timeout)
343 except: # Including KeyboardInterrupt, wait handled that.
344 p.kill()
345 # We don't call p.wait() again as p.__exit__ does that for us.
346 raise
349def check_call(*popenargs, **kwargs):
350 """Run command with arguments. Wait for command to complete. If
351 the exit code was zero then return, otherwise raise
352 CalledProcessError. The CalledProcessError object will have the
353 return code in the returncode attribute.
355 The arguments are the same as for the call function. Example:
357 check_call(["ls", "-l"])
358 """
359 retcode = call(*popenargs, **kwargs)
360 if retcode:
361 cmd = kwargs.get("args")
362 if cmd is None:
363 cmd = popenargs[0]
364 raise CalledProcessError(retcode, cmd)
365 return 0
368def check_output(*popenargs, timeout=None, **kwargs):
369 r"""Run command with arguments and return its output.
371 If the exit code was non-zero it raises a CalledProcessError. The
372 CalledProcessError object will have the return code in the returncode
373 attribute and output in the output attribute.
375 The arguments are the same as for the Popen constructor. Example:
377 >>> check_output(["ls", "-l", "/dev/null"])
378 b'crw-rw-rw- 1 root root 1, 3 Oct 18 2007 /dev/null\n'
380 The stdout argument is not allowed as it is used internally.
381 To capture standard error in the result, use stderr=STDOUT.
383 >>> check_output(["/bin/sh", "-c",
384 ... "ls -l non_existent_file ; exit 0"],
385 ... stderr=STDOUT)
386 b'ls: non_existent_file: No such file or directory\n'
388 There is an additional optional argument, "input", allowing you to
389 pass a string to the subprocess's stdin. If you use this argument
390 you may not also use the Popen constructor's "stdin" argument, as
391 it too will be used internally. Example:
393 >>> check_output(["sed", "-e", "s/foo/bar/"],
394 ... input=b"when in the course of fooman events\n")
395 b'when in the course of barman events\n'
397 By default, all communication is in bytes, and therefore any "input"
398 should be bytes, and the return value will be bytes. If in text mode,
399 any "input" should be a string, and the return value will be a string
400 decoded according to locale encoding, or by "encoding" if set. Text mode
401 is triggered by setting any of text, encoding, errors or universal_newlines.
402 """
403 if 'stdout' in kwargs:
404 raise ValueError('stdout argument not allowed, it will be overridden.')
406 if 'input' in kwargs and kwargs['input'] is None:
407 # Explicitly passing input=None was previously equivalent to passing an
408 # empty string. That is maintained here for backwards compatibility.
409 kwargs['input'] = '' if kwargs.get('universal_newlines', False) else b''
411 return run(*popenargs, stdout=PIPE, timeout=timeout, check=True,
412 **kwargs).stdout
415class CompletedProcess(object):
416 """A process that has finished running.
418 This is returned by run().
420 Attributes:
421 args: The list or str args passed to run().
422 returncode: The exit code of the process, negative for signals.
423 stdout: The standard output (None if not captured).
424 stderr: The standard error (None if not captured).
425 """
426 def __init__(self, args, returncode, stdout=None, stderr=None):
427 self.args = args
428 self.returncode = returncode
429 self.stdout = stdout
430 self.stderr = stderr
432 def __repr__(self):
433 args = ['args={!r}'.format(self.args),
434 'returncode={!r}'.format(self.returncode)]
435 if self.stdout is not None:
436 args.append('stdout={!r}'.format(self.stdout))
437 if self.stderr is not None:
438 args.append('stderr={!r}'.format(self.stderr))
439 return "{}({})".format(type(self).__name__, ', '.join(args))
441 def check_returncode(self):
442 """Raise CalledProcessError if the exit code is non-zero."""
443 if self.returncode:
444 raise CalledProcessError(self.returncode, self.args, self.stdout,
445 self.stderr)
448def run(*popenargs,
449 input=None, capture_output=False, timeout=None, check=False, **kwargs):
450 """Run command with arguments and return a CompletedProcess instance.
452 The returned instance will have attributes args, returncode, stdout and
453 stderr. By default, stdout and stderr are not captured, and those attributes
454 will be None. Pass stdout=PIPE and/or stderr=PIPE in order to capture them.
456 If check is True and the exit code was non-zero, it raises a
457 CalledProcessError. The CalledProcessError object will have the return code
458 in the returncode attribute, and output & stderr attributes if those streams
459 were captured.
461 If timeout is given, and the process takes too long, a TimeoutExpired
462 exception will be raised.
464 There is an optional argument "input", allowing you to
465 pass bytes or a string to the subprocess's stdin. If you use this argument
466 you may not also use the Popen constructor's "stdin" argument, as
467 it will be used internally.
469 By default, all communication is in bytes, and therefore any "input" should
470 be bytes, and the stdout and stderr will be bytes. If in text mode, any
471 "input" should be a string, and stdout and stderr will be strings decoded
472 according to locale encoding, or by "encoding" if set. Text mode is
473 triggered by setting any of text, encoding, errors or universal_newlines.
475 The other arguments are the same as for the Popen constructor.
476 """
477 if input is not None:
478 if kwargs.get('stdin') is not None:
479 raise ValueError('stdin and input arguments may not both be used.')
480 kwargs['stdin'] = PIPE
482 if capture_output:
483 if kwargs.get('stdout') is not None or kwargs.get('stderr') is not None:
484 raise ValueError('stdout and stderr arguments may not be used '
485 'with capture_output.')
486 kwargs['stdout'] = PIPE
487 kwargs['stderr'] = PIPE
489 with Popen(*popenargs, **kwargs) as process:
490 try:
491 stdout, stderr = process.communicate(input, timeout=timeout)
492 except TimeoutExpired as exc:
493 process.kill()
494 if _mswindows:
495 # Windows accumulates the output in a single blocking
496 # read() call run on child threads, with the timeout
497 # being done in a join() on those threads. communicate()
498 # _after_ kill() is required to collect that and add it
499 # to the exception.
500 exc.stdout, exc.stderr = process.communicate()
501 else:
502 # POSIX _communicate already populated the output so
503 # far into the TimeoutExpired exception.
504 process.wait()
505 raise
506 except: # Including KeyboardInterrupt, communicate handled that.
507 process.kill()
508 # We don't call process.wait() as .__exit__ does that for us.
509 raise
510 retcode = process.poll()
511 if check and retcode:
512 raise CalledProcessError(retcode, process.args,
513 output=stdout, stderr=stderr)
514 return CompletedProcess(process.args, retcode, stdout, stderr)
517def list2cmdline(seq):
518 """
519 Translate a sequence of arguments into a command line
520 string, using the same rules as the MS C runtime:
522 1) Arguments are delimited by white space, which is either a
523 space or a tab.
525 2) A string surrounded by double quotation marks is
526 interpreted as a single argument, regardless of white space
527 contained within. A quoted string can be embedded in an
528 argument.
530 3) A double quotation mark preceded by a backslash is
531 interpreted as a literal double quotation mark.
533 4) Backslashes are interpreted literally, unless they
534 immediately precede a double quotation mark.
536 5) If backslashes immediately precede a double quotation mark,
537 every pair of backslashes is interpreted as a literal
538 backslash. If the number of backslashes is odd, the last
539 backslash escapes the next double quotation mark as
540 described in rule 3.
541 """
543 # See
544 # http://msdn.microsoft.com/en-us/library/17w5ykft.aspx
545 # or search http://msdn.microsoft.com for
546 # "Parsing C++ Command-Line Arguments"
547 result = []
548 needquote = False
549 for arg in map(os.fsdecode, seq):
550 bs_buf = []
552 # Add a space to separate this argument from the others
553 if result:
554 result.append(' ')
556 needquote = (" " in arg) or ("\t" in arg) or not arg
557 if needquote:
558 result.append('"')
560 for c in arg:
561 if c == '\\':
562 # Don't know if we need to double yet.
563 bs_buf.append(c)
564 elif c == '"':
565 # Double backslashes.
566 result.append('\\' * len(bs_buf)*2)
567 bs_buf = []
568 result.append('\\"')
569 else:
570 # Normal char
571 if bs_buf:
572 result.extend(bs_buf)
573 bs_buf = []
574 result.append(c)
576 # Add remaining backslashes, if any.
577 if bs_buf:
578 result.extend(bs_buf)
580 if needquote:
581 result.extend(bs_buf)
582 result.append('"')
584 return ''.join(result)
587# Various tools for executing commands and looking at their output and status.
588#
590def getstatusoutput(cmd):
591 """Return (exitcode, output) of executing cmd in a shell.
593 Execute the string 'cmd' in a shell with 'check_output' and
594 return a 2-tuple (status, output). The locale encoding is used
595 to decode the output and process newlines.
597 A trailing newline is stripped from the output.
598 The exit status for the command can be interpreted
599 according to the rules for the function 'wait'. Example:
601 >>> import subprocess
602 >>> subprocess.getstatusoutput('ls /bin/ls')
603 (0, '/bin/ls')
604 >>> subprocess.getstatusoutput('cat /bin/junk')
605 (1, 'cat: /bin/junk: No such file or directory')
606 >>> subprocess.getstatusoutput('/bin/junk')
607 (127, 'sh: /bin/junk: not found')
608 >>> subprocess.getstatusoutput('/bin/kill $$')
609 (-15, '')
610 """
611 try:
612 data = check_output(cmd, shell=True, text=True, stderr=STDOUT)
613 exitcode = 0
614 except CalledProcessError as ex:
615 data = ex.output
616 exitcode = ex.returncode
617 if data[-1:] == '\n':
618 data = data[:-1]
619 return exitcode, data
621def getoutput(cmd):
622 """Return output (stdout or stderr) of executing cmd in a shell.
624 Like getstatusoutput(), except the exit status is ignored and the return
625 value is a string containing the command's output. Example:
627 >>> import subprocess
628 >>> subprocess.getoutput('ls /bin/ls')
629 '/bin/ls'
630 """
631 return getstatusoutput(cmd)[1]
634def _use_posix_spawn():
635 """Check if posix_spawn() can be used for subprocess.
637 subprocess requires a posix_spawn() implementation that properly reports
638 errors to the parent process, & sets errno on the following failures:
640 * Process attribute actions failed.
641 * File actions failed.
642 * exec() failed.
644 Prefer an implementation which can use vfork() in some cases for best
645 performance.
646 """
647 if _mswindows or not hasattr(os, 'posix_spawn'):
648 # os.posix_spawn() is not available
649 return False
651 if sys.platform == 'darwin':
652 # posix_spawn() is a syscall on macOS and properly reports errors
653 return True
655 # Check libc name and runtime libc version
656 try:
657 ver = os.confstr('CS_GNU_LIBC_VERSION')
658 # parse 'glibc 2.28' as ('glibc', (2, 28))
659 parts = ver.split(maxsplit=1)
660 if len(parts) != 2:
661 # reject unknown format
662 raise ValueError
663 libc = parts[0]
664 version = tuple(map(int, parts[1].split('.')))
666 if sys.platform == 'linux' and libc == 'glibc' and version >= (2, 24):
667 # glibc 2.24 has a new Linux posix_spawn implementation using vfork
668 # which properly reports errors to the parent process.
669 return True
670 # Note: Don't use the implementation in earlier glibc because it doesn't
671 # use vfork (even if glibc 2.26 added a pipe to properly report errors
672 # to the parent process).
673 except (AttributeError, ValueError, OSError):
674 # os.confstr() or CS_GNU_LIBC_VERSION value not available
675 pass
677 # By default, assume that posix_spawn() does not properly report errors.
678 return False
681_USE_POSIX_SPAWN = _use_posix_spawn()
684class Popen(object):
685 """ Execute a child program in a new process.
687 For a complete description of the arguments see the Python documentation.
689 Arguments:
690 args: A string, or a sequence of program arguments.
692 bufsize: supplied as the buffering argument to the open() function when
693 creating the stdin/stdout/stderr pipe file objects
695 executable: A replacement program to execute.
697 stdin, stdout and stderr: These specify the executed programs' standard
698 input, standard output and standard error file handles, respectively.
700 preexec_fn: (POSIX only) An object to be called in the child process
701 just before the child is executed.
703 close_fds: Controls closing or inheriting of file descriptors.
705 shell: If true, the command will be executed through the shell.
707 cwd: Sets the current directory before the child is executed.
709 env: Defines the environment variables for the new process.
711 text: If true, decode stdin, stdout and stderr using the given encoding
712 (if set) or the system default otherwise.
714 universal_newlines: Alias of text, provided for backwards compatibility.
716 startupinfo and creationflags (Windows only)
718 restore_signals (POSIX only)
720 start_new_session (POSIX only)
722 pass_fds (POSIX only)
724 encoding and errors: Text mode encoding and error handling to use for
725 file objects stdin, stdout and stderr.
727 Attributes:
728 stdin, stdout, stderr, pid, returncode
729 """
730 _child_created = False # Set here since __del__ checks it
732 def __init__(self, args, bufsize=-1, executable=None,
733 stdin=None, stdout=None, stderr=None,
734 preexec_fn=None, close_fds=True,
735 shell=False, cwd=None, env=None, universal_newlines=None,
736 startupinfo=None, creationflags=0,
737 restore_signals=True, start_new_session=False,
738 pass_fds=(), *, encoding=None, errors=None, text=None):
739 """Create new Popen instance."""
740 _cleanup()
741 # Held while anything is calling waitpid before returncode has been
742 # updated to prevent clobbering returncode if wait() or poll() are
743 # called from multiple threads at once. After acquiring the lock,
744 # code must re-check self.returncode to see if another thread just
745 # finished a waitpid() call.
746 self._waitpid_lock = threading.Lock()
748 self._input = None
749 self._communication_started = False
750 if bufsize is None:
751 bufsize = -1 # Restore default
752 if not isinstance(bufsize, int):
753 raise TypeError("bufsize must be an integer")
755 if _mswindows:
756 if preexec_fn is not None:
757 raise ValueError("preexec_fn is not supported on Windows "
758 "platforms")
759 else:
760 # POSIX
761 if pass_fds and not close_fds:
762 warnings.warn("pass_fds overriding close_fds.", RuntimeWarning)
763 close_fds = True
764 if startupinfo is not None:
765 raise ValueError("startupinfo is only supported on Windows "
766 "platforms")
767 if creationflags != 0:
768 raise ValueError("creationflags is only supported on Windows "
769 "platforms")
771 self.args = args
772 self.stdin = None
773 self.stdout = None
774 self.stderr = None
775 self.pid = None
776 self.returncode = None
777 self.encoding = encoding
778 self.errors = errors
780 # Validate the combinations of text and universal_newlines
781 if (text is not None and universal_newlines is not None
782 and bool(universal_newlines) != bool(text)):
783 raise SubprocessError('Cannot disambiguate when both text '
784 'and universal_newlines are supplied but '
785 'different. Pass one or the other.')
787 # Input and output objects. The general principle is like
788 # this:
789 #
790 # Parent Child
791 # ------ -----
792 # p2cwrite ---stdin---> p2cread
793 # c2pread <--stdout--- c2pwrite
794 # errread <--stderr--- errwrite
795 #
796 # On POSIX, the child objects are file descriptors. On
797 # Windows, these are Windows file handles. The parent objects
798 # are file descriptors on both platforms. The parent objects
799 # are -1 when not using PIPEs. The child objects are -1
800 # when not redirecting.
802 (p2cread, p2cwrite,
803 c2pread, c2pwrite,
804 errread, errwrite) = self._get_handles(stdin, stdout, stderr)
806 # We wrap OS handles *before* launching the child, otherwise a
807 # quickly terminating child could make our fds unwrappable
808 # (see #8458).
810 if _mswindows:
811 if p2cwrite != -1:
812 p2cwrite = msvcrt.open_osfhandle(p2cwrite.Detach(), 0)
813 if c2pread != -1:
814 c2pread = msvcrt.open_osfhandle(c2pread.Detach(), 0)
815 if errread != -1:
816 errread = msvcrt.open_osfhandle(errread.Detach(), 0)
818 self.text_mode = encoding or errors or text or universal_newlines
820 # How long to resume waiting on a child after the first ^C.
821 # There is no right value for this. The purpose is to be polite
822 # yet remain good for interactive users trying to exit a tool.
823 self._sigint_wait_secs = 0.25 # 1/xkcd221.getRandomNumber()
825 self._closed_child_pipe_fds = False
827 if self.text_mode:
828 if bufsize == 1:
829 line_buffering = True
830 # Use the default buffer size for the underlying binary streams
831 # since they don't support line buffering.
832 bufsize = -1
833 else:
834 line_buffering = False
836 try:
837 if p2cwrite != -1:
838 self.stdin = io.open(p2cwrite, 'wb', bufsize)
839 if self.text_mode:
840 self.stdin = io.TextIOWrapper(self.stdin, write_through=True,
841 line_buffering=line_buffering,
842 encoding=encoding, errors=errors)
843 if c2pread != -1:
844 self.stdout = io.open(c2pread, 'rb', bufsize)
845 if self.text_mode:
846 self.stdout = io.TextIOWrapper(self.stdout,
847 encoding=encoding, errors=errors)
848 if errread != -1:
849 self.stderr = io.open(errread, 'rb', bufsize)
850 if self.text_mode:
851 self.stderr = io.TextIOWrapper(self.stderr,
852 encoding=encoding, errors=errors)
854 self._execute_child(args, executable, preexec_fn, close_fds,
855 pass_fds, cwd, env,
856 startupinfo, creationflags, shell,
857 p2cread, p2cwrite,
858 c2pread, c2pwrite,
859 errread, errwrite,
860 restore_signals, start_new_session)
861 except:
862 # Cleanup if the child failed starting.
863 for f in filter(None, (self.stdin, self.stdout, self.stderr)):
864 try:
865 f.close()
866 except OSError:
867 pass # Ignore EBADF or other errors.
869 if not self._closed_child_pipe_fds:
870 to_close = []
871 if stdin == PIPE:
872 to_close.append(p2cread)
873 if stdout == PIPE:
874 to_close.append(c2pwrite)
875 if stderr == PIPE:
876 to_close.append(errwrite)
877 if hasattr(self, '_devnull'):
878 to_close.append(self._devnull)
879 for fd in to_close:
880 try:
881 if _mswindows and isinstance(fd, Handle):
882 fd.Close()
883 else:
884 os.close(fd)
885 except OSError:
886 pass
888 raise
890 @property
891 def universal_newlines(self):
892 # universal_newlines as retained as an alias of text_mode for API
893 # compatibility. bpo-31756
894 return self.text_mode
896 @universal_newlines.setter
897 def universal_newlines(self, universal_newlines):
898 self.text_mode = bool(universal_newlines)
900 def _translate_newlines(self, data, encoding, errors):
901 data = data.decode(encoding, errors)
902 return data.replace("\r\n", "\n").replace("\r", "\n")
904 def __enter__(self):
905 return self
907 def __exit__(self, exc_type, value, traceback):
908 if self.stdout:
909 self.stdout.close()
910 if self.stderr:
911 self.stderr.close()
912 try: # Flushing a BufferedWriter may raise an error
913 if self.stdin:
914 self.stdin.close()
915 finally:
916 if exc_type == KeyboardInterrupt:
917 # https://bugs.python.org/issue25942
918 # In the case of a KeyboardInterrupt we assume the SIGINT
919 # was also already sent to our child processes. We can't
920 # block indefinitely as that is not user friendly.
921 # If we have not already waited a brief amount of time in
922 # an interrupted .wait() or .communicate() call, do so here
923 # for consistency.
924 if self._sigint_wait_secs > 0:
925 try:
926 self._wait(timeout=self._sigint_wait_secs)
927 except TimeoutExpired:
928 pass
929 self._sigint_wait_secs = 0 # Note that this has been done.
930 return # resume the KeyboardInterrupt
932 # Wait for the process to terminate, to avoid zombies.
933 self.wait()
935 def __del__(self, _maxsize=sys.maxsize, _warn=warnings.warn):
936 if not self._child_created:
937 # We didn't get to successfully create a child process.
938 return
939 if self.returncode is None:
940 # Not reading subprocess exit status creates a zombie process which
941 # is only destroyed at the parent python process exit
942 _warn("subprocess %s is still running" % self.pid,
943 ResourceWarning, source=self)
944 # In case the child hasn't been waited on, check if it's done.
945 self._internal_poll(_deadstate=_maxsize)
946 if self.returncode is None and _active is not None:
947 # Child is still running, keep us alive until we can wait on it.
948 _active.append(self)
950 def _get_devnull(self):
951 if not hasattr(self, '_devnull'):
952 self._devnull = os.open(os.devnull, os.O_RDWR)
953 return self._devnull
955 def _stdin_write(self, input):
956 if input:
957 try:
958 self.stdin.write(input)
959 except BrokenPipeError:
960 pass # communicate() must ignore broken pipe errors.
961 except OSError as exc:
962 if exc.errno == errno.EINVAL:
963 # bpo-19612, bpo-30418: On Windows, stdin.write() fails
964 # with EINVAL if the child process exited or if the child
965 # process is still running but closed the pipe.
966 pass
967 else:
968 raise
970 try:
971 self.stdin.close()
972 except BrokenPipeError:
973 pass # communicate() must ignore broken pipe errors.
974 except OSError as exc:
975 if exc.errno == errno.EINVAL:
976 pass
977 else:
978 raise
980 def communicate(self, input=None, timeout=None):
981 """Interact with process: Send data to stdin and close it.
982 Read data from stdout and stderr, until end-of-file is
983 reached. Wait for process to terminate.
985 The optional "input" argument should be data to be sent to the
986 child process, or None, if no data should be sent to the child.
987 communicate() returns a tuple (stdout, stderr).
989 By default, all communication is in bytes, and therefore any
990 "input" should be bytes, and the (stdout, stderr) will be bytes.
991 If in text mode (indicated by self.text_mode), any "input" should
992 be a string, and (stdout, stderr) will be strings decoded
993 according to locale encoding, or by "encoding" if set. Text mode
994 is triggered by setting any of text, encoding, errors or
995 universal_newlines.
996 """
998 if self._communication_started and input:
999 raise ValueError("Cannot send input after starting communication")
1001 # Optimization: If we are not worried about timeouts, we haven't
1002 # started communicating, and we have one or zero pipes, using select()
1003 # or threads is unnecessary.
1004 if (timeout is None and not self._communication_started and
1005 [self.stdin, self.stdout, self.stderr].count(None) >= 2):
1006 stdout = None
1007 stderr = None
1008 if self.stdin:
1009 self._stdin_write(input)
1010 elif self.stdout:
1011 stdout = self.stdout.read()
1012 self.stdout.close()
1013 elif self.stderr:
1014 stderr = self.stderr.read()
1015 self.stderr.close()
1016 self.wait()
1017 else:
1018 if timeout is not None:
1019 endtime = _time() + timeout
1020 else:
1021 endtime = None
1023 try:
1024 stdout, stderr = self._communicate(input, endtime, timeout)
1025 except KeyboardInterrupt:
1026 # https://bugs.python.org/issue25942
1027 # See the detailed comment in .wait().
1028 if timeout is not None:
1029 sigint_timeout = min(self._sigint_wait_secs,
1030 self._remaining_time(endtime))
1031 else:
1032 sigint_timeout = self._sigint_wait_secs
1033 self._sigint_wait_secs = 0 # nothing else should wait.
1034 try:
1035 self._wait(timeout=sigint_timeout)
1036 except TimeoutExpired:
1037 pass
1038 raise # resume the KeyboardInterrupt
1040 finally:
1041 self._communication_started = True
1043 sts = self.wait(timeout=self._remaining_time(endtime))
1045 return (stdout, stderr)
1048 def poll(self):
1049 """Check if child process has terminated. Set and return returncode
1050 attribute."""
1051 return self._internal_poll()
1054 def _remaining_time(self, endtime):
1055 """Convenience for _communicate when computing timeouts."""
1056 if endtime is None:
1057 return None
1058 else:
1059 return endtime - _time()
1062 def _check_timeout(self, endtime, orig_timeout, stdout_seq, stderr_seq,
1063 skip_check_and_raise=False):
1064 """Convenience for checking if a timeout has expired."""
1065 if endtime is None:
1066 return
1067 if skip_check_and_raise or _time() > endtime:
1068 raise TimeoutExpired(
1069 self.args, orig_timeout,
1070 output=b''.join(stdout_seq) if stdout_seq else None,
1071 stderr=b''.join(stderr_seq) if stderr_seq else None)
1074 def wait(self, timeout=None):
1075 """Wait for child process to terminate; returns self.returncode."""
1076 if timeout is not None:
1077 endtime = _time() + timeout
1078 try:
1079 return self._wait(timeout=timeout)
1080 except KeyboardInterrupt:
1081 # https://bugs.python.org/issue25942
1082 # The first keyboard interrupt waits briefly for the child to
1083 # exit under the common assumption that it also received the ^C
1084 # generated SIGINT and will exit rapidly.
1085 if timeout is not None:
1086 sigint_timeout = min(self._sigint_wait_secs,
1087 self._remaining_time(endtime))
1088 else:
1089 sigint_timeout = self._sigint_wait_secs
1090 self._sigint_wait_secs = 0 # nothing else should wait.
1091 try:
1092 self._wait(timeout=sigint_timeout)
1093 except TimeoutExpired:
1094 pass
1095 raise # resume the KeyboardInterrupt
1097 def _close_pipe_fds(self,
1098 p2cread, p2cwrite,
1099 c2pread, c2pwrite,
1100 errread, errwrite):
1101 # self._devnull is not always defined.
1102 devnull_fd = getattr(self, '_devnull', None)
1104 with contextlib.ExitStack() as stack:
1105 if _mswindows:
1106 if p2cread != -1:
1107 stack.callback(p2cread.Close)
1108 if c2pwrite != -1:
1109 stack.callback(c2pwrite.Close)
1110 if errwrite != -1:
1111 stack.callback(errwrite.Close)
1112 else:
1113 if p2cread != -1 and p2cwrite != -1 and p2cread != devnull_fd:
1114 stack.callback(os.close, p2cread)
1115 if c2pwrite != -1 and c2pread != -1 and c2pwrite != devnull_fd:
1116 stack.callback(os.close, c2pwrite)
1117 if errwrite != -1 and errread != -1 and errwrite != devnull_fd:
1118 stack.callback(os.close, errwrite)
1120 if devnull_fd is not None:
1121 stack.callback(os.close, devnull_fd)
1123 # Prevent a double close of these handles/fds from __init__ on error.
1124 self._closed_child_pipe_fds = True
1126 if _mswindows:
1127 #
1128 # Windows methods
1129 #
1130 def _get_handles(self, stdin, stdout, stderr):
1131 """Construct and return tuple with IO objects:
1132 p2cread, p2cwrite, c2pread, c2pwrite, errread, errwrite
1133 """
1134 if stdin is None and stdout is None and stderr is None:
1135 return (-1, -1, -1, -1, -1, -1)
1137 p2cread, p2cwrite = -1, -1
1138 c2pread, c2pwrite = -1, -1
1139 errread, errwrite = -1, -1
1141 if stdin is None:
1142 p2cread = _winapi.GetStdHandle(_winapi.STD_INPUT_HANDLE)
1143 if p2cread is None:
1144 p2cread, _ = _winapi.CreatePipe(None, 0)
1145 p2cread = Handle(p2cread)
1146 _winapi.CloseHandle(_)
1147 elif stdin == PIPE:
1148 p2cread, p2cwrite = _winapi.CreatePipe(None, 0)
1149 p2cread, p2cwrite = Handle(p2cread), Handle(p2cwrite)
1150 elif stdin == DEVNULL:
1151 p2cread = msvcrt.get_osfhandle(self._get_devnull())
1152 elif isinstance(stdin, int):
1153 p2cread = msvcrt.get_osfhandle(stdin)
1154 else:
1155 # Assuming file-like object
1156 p2cread = msvcrt.get_osfhandle(stdin.fileno())
1157 p2cread = self._make_inheritable(p2cread)
1159 if stdout is None:
1160 c2pwrite = _winapi.GetStdHandle(_winapi.STD_OUTPUT_HANDLE)
1161 if c2pwrite is None:
1162 _, c2pwrite = _winapi.CreatePipe(None, 0)
1163 c2pwrite = Handle(c2pwrite)
1164 _winapi.CloseHandle(_)
1165 elif stdout == PIPE:
1166 c2pread, c2pwrite = _winapi.CreatePipe(None, 0)
1167 c2pread, c2pwrite = Handle(c2pread), Handle(c2pwrite)
1168 elif stdout == DEVNULL:
1169 c2pwrite = msvcrt.get_osfhandle(self._get_devnull())
1170 elif isinstance(stdout, int):
1171 c2pwrite = msvcrt.get_osfhandle(stdout)
1172 else:
1173 # Assuming file-like object
1174 c2pwrite = msvcrt.get_osfhandle(stdout.fileno())
1175 c2pwrite = self._make_inheritable(c2pwrite)
1177 if stderr is None:
1178 errwrite = _winapi.GetStdHandle(_winapi.STD_ERROR_HANDLE)
1179 if errwrite is None:
1180 _, errwrite = _winapi.CreatePipe(None, 0)
1181 errwrite = Handle(errwrite)
1182 _winapi.CloseHandle(_)
1183 elif stderr == PIPE:
1184 errread, errwrite = _winapi.CreatePipe(None, 0)
1185 errread, errwrite = Handle(errread), Handle(errwrite)
1186 elif stderr == STDOUT:
1187 errwrite = c2pwrite
1188 elif stderr == DEVNULL:
1189 errwrite = msvcrt.get_osfhandle(self._get_devnull())
1190 elif isinstance(stderr, int):
1191 errwrite = msvcrt.get_osfhandle(stderr)
1192 else:
1193 # Assuming file-like object
1194 errwrite = msvcrt.get_osfhandle(stderr.fileno())
1195 errwrite = self._make_inheritable(errwrite)
1197 return (p2cread, p2cwrite,
1198 c2pread, c2pwrite,
1199 errread, errwrite)
1202 def _make_inheritable(self, handle):
1203 """Return a duplicate of handle, which is inheritable"""
1204 h = _winapi.DuplicateHandle(
1205 _winapi.GetCurrentProcess(), handle,
1206 _winapi.GetCurrentProcess(), 0, 1,
1207 _winapi.DUPLICATE_SAME_ACCESS)
1208 return Handle(h)
1211 def _filter_handle_list(self, handle_list):
1212 """Filter out console handles that can't be used
1213 in lpAttributeList["handle_list"] and make sure the list
1214 isn't empty. This also removes duplicate handles."""
1215 # An handle with it's lowest two bits set might be a special console
1216 # handle that if passed in lpAttributeList["handle_list"], will
1217 # cause it to fail.
1218 return list({handle for handle in handle_list
1219 if handle & 0x3 != 0x3
1220 or _winapi.GetFileType(handle) !=
1221 _winapi.FILE_TYPE_CHAR})
1224 def _execute_child(self, args, executable, preexec_fn, close_fds,
1225 pass_fds, cwd, env,
1226 startupinfo, creationflags, shell,
1227 p2cread, p2cwrite,
1228 c2pread, c2pwrite,
1229 errread, errwrite,
1230 unused_restore_signals, unused_start_new_session):
1231 """Execute program (MS Windows version)"""
1233 assert not pass_fds, "pass_fds not supported on Windows."
1235 if isinstance(args, str):
1236 pass
1237 elif isinstance(args, bytes):
1238 if shell:
1239 raise TypeError('bytes args is not allowed on Windows')
1240 args = list2cmdline([args])
1241 elif isinstance(args, os.PathLike):
1242 if shell:
1243 raise TypeError('path-like args is not allowed when '
1244 'shell is true')
1245 args = list2cmdline([args])
1246 else:
1247 args = list2cmdline(args)
1249 if executable is not None:
1250 executable = os.fsdecode(executable)
1252 # Process startup details
1253 if startupinfo is None:
1254 startupinfo = STARTUPINFO()
1255 else:
1256 # bpo-34044: Copy STARTUPINFO since it is modified above,
1257 # so the caller can reuse it multiple times.
1258 startupinfo = startupinfo.copy()
1260 use_std_handles = -1 not in (p2cread, c2pwrite, errwrite)
1261 if use_std_handles:
1262 startupinfo.dwFlags |= _winapi.STARTF_USESTDHANDLES
1263 startupinfo.hStdInput = p2cread
1264 startupinfo.hStdOutput = c2pwrite
1265 startupinfo.hStdError = errwrite
1267 attribute_list = startupinfo.lpAttributeList
1268 have_handle_list = bool(attribute_list and
1269 "handle_list" in attribute_list and
1270 attribute_list["handle_list"])
1272 # If we were given an handle_list or need to create one
1273 if have_handle_list or (use_std_handles and close_fds):
1274 if attribute_list is None:
1275 attribute_list = startupinfo.lpAttributeList = {}
1276 handle_list = attribute_list["handle_list"] = \
1277 list(attribute_list.get("handle_list", []))
1279 if use_std_handles:
1280 handle_list += [int(p2cread), int(c2pwrite), int(errwrite)]
1282 handle_list[:] = self._filter_handle_list(handle_list)
1284 if handle_list:
1285 if not close_fds:
1286 warnings.warn("startupinfo.lpAttributeList['handle_list'] "
1287 "overriding close_fds", RuntimeWarning)
1289 # When using the handle_list we always request to inherit
1290 # handles but the only handles that will be inherited are
1291 # the ones in the handle_list
1292 close_fds = False
1294 if shell:
1295 startupinfo.dwFlags |= _winapi.STARTF_USESHOWWINDOW
1296 startupinfo.wShowWindow = _winapi.SW_HIDE
1297 comspec = os.environ.get("COMSPEC", "cmd.exe")
1298 args = '{} /c "{}"'.format (comspec, args)
1300 if cwd is not None:
1301 cwd = os.fsdecode(cwd)
1303 sys.audit("subprocess.Popen", executable, args, cwd, env)
1305 # Start the process
1306 try:
1307 hp, ht, pid, tid = _winapi.CreateProcess(executable, args,
1308 # no special security
1309 None, None,
1310 int(not close_fds),
1311 creationflags,
1312 env,
1313 cwd,
1314 startupinfo)
1315 finally:
1316 # Child is launched. Close the parent's copy of those pipe
1317 # handles that only the child should have open. You need
1318 # to make sure that no handles to the write end of the
1319 # output pipe are maintained in this process or else the
1320 # pipe will not close when the child process exits and the
1321 # ReadFile will hang.
1322 self._close_pipe_fds(p2cread, p2cwrite,
1323 c2pread, c2pwrite,
1324 errread, errwrite)
1326 # Retain the process handle, but close the thread handle
1327 self._child_created = True
1328 self._handle = Handle(hp)
1329 self.pid = pid
1330 _winapi.CloseHandle(ht)
1332 def _internal_poll(self, _deadstate=None,
1333 _WaitForSingleObject=_winapi.WaitForSingleObject,
1334 _WAIT_OBJECT_0=_winapi.WAIT_OBJECT_0,
1335 _GetExitCodeProcess=_winapi.GetExitCodeProcess):
1336 """Check if child process has terminated. Returns returncode
1337 attribute.
1339 This method is called by __del__, so it can only refer to objects
1340 in its local scope.
1342 """
1343 if self.returncode is None:
1344 if _WaitForSingleObject(self._handle, 0) == _WAIT_OBJECT_0:
1345 self.returncode = _GetExitCodeProcess(self._handle)
1346 return self.returncode
1349 def _wait(self, timeout):
1350 """Internal implementation of wait() on Windows."""
1351 if timeout is None:
1352 timeout_millis = _winapi.INFINITE
1353 else:
1354 timeout_millis = int(timeout * 1000)
1355 if self.returncode is None:
1356 # API note: Returns immediately if timeout_millis == 0.
1357 result = _winapi.WaitForSingleObject(self._handle,
1358 timeout_millis)
1359 if result == _winapi.WAIT_TIMEOUT:
1360 raise TimeoutExpired(self.args, timeout)
1361 self.returncode = _winapi.GetExitCodeProcess(self._handle)
1362 return self.returncode
1365 def _readerthread(self, fh, buffer):
1366 buffer.append(fh.read())
1367 fh.close()
1370 def _communicate(self, input, endtime, orig_timeout):
1371 # Start reader threads feeding into a list hanging off of this
1372 # object, unless they've already been started.
1373 if self.stdout and not hasattr(self, "_stdout_buff"):
1374 self._stdout_buff = []
1375 self.stdout_thread = \
1376 threading.Thread(target=self._readerthread,
1377 args=(self.stdout, self._stdout_buff))
1378 self.stdout_thread.daemon = True
1379 self.stdout_thread.start()
1380 if self.stderr and not hasattr(self, "_stderr_buff"):
1381 self._stderr_buff = []
1382 self.stderr_thread = \
1383 threading.Thread(target=self._readerthread,
1384 args=(self.stderr, self._stderr_buff))
1385 self.stderr_thread.daemon = True
1386 self.stderr_thread.start()
1388 if self.stdin:
1389 self._stdin_write(input)
1391 # Wait for the reader threads, or time out. If we time out, the
1392 # threads remain reading and the fds left open in case the user
1393 # calls communicate again.
1394 if self.stdout is not None:
1395 self.stdout_thread.join(self._remaining_time(endtime))
1396 if self.stdout_thread.is_alive():
1397 raise TimeoutExpired(self.args, orig_timeout)
1398 if self.stderr is not None:
1399 self.stderr_thread.join(self._remaining_time(endtime))
1400 if self.stderr_thread.is_alive():
1401 raise TimeoutExpired(self.args, orig_timeout)
1403 # Collect the output from and close both pipes, now that we know
1404 # both have been read successfully.
1405 stdout = None
1406 stderr = None
1407 if self.stdout:
1408 stdout = self._stdout_buff
1409 self.stdout.close()
1410 if self.stderr:
1411 stderr = self._stderr_buff
1412 self.stderr.close()
1414 # All data exchanged. Translate lists into strings.
1415 if stdout is not None:
1416 stdout = stdout[0]
1417 if stderr is not None:
1418 stderr = stderr[0]
1420 return (stdout, stderr)
1422 def send_signal(self, sig):
1423 """Send a signal to the process."""
1424 # Don't signal a process that we know has already died.
1425 if self.returncode is not None:
1426 return
1427 if sig == signal.SIGTERM:
1428 self.terminate()
1429 elif sig == signal.CTRL_C_EVENT:
1430 os.kill(self.pid, signal.CTRL_C_EVENT)
1431 elif sig == signal.CTRL_BREAK_EVENT:
1432 os.kill(self.pid, signal.CTRL_BREAK_EVENT)
1433 else:
1434 raise ValueError("Unsupported signal: {}".format(sig))
1436 def terminate(self):
1437 """Terminates the process."""
1438 # Don't terminate a process that we know has already died.
1439 if self.returncode is not None:
1440 return
1441 try:
1442 _winapi.TerminateProcess(self._handle, 1)
1443 except PermissionError:
1444 # ERROR_ACCESS_DENIED (winerror 5) is received when the
1445 # process already died.
1446 rc = _winapi.GetExitCodeProcess(self._handle)
1447 if rc == _winapi.STILL_ACTIVE:
1448 raise
1449 self.returncode = rc
1451 kill = terminate
1453 else:
1454 #
1455 # POSIX methods
1456 #
1457 def _get_handles(self, stdin, stdout, stderr):
1458 """Construct and return tuple with IO objects:
1459 p2cread, p2cwrite, c2pread, c2pwrite, errread, errwrite
1460 """
1461 p2cread, p2cwrite = -1, -1
1462 c2pread, c2pwrite = -1, -1
1463 errread, errwrite = -1, -1
1465 if stdin is None:
1466 pass
1467 elif stdin == PIPE:
1468 p2cread, p2cwrite = os.pipe()
1469 elif stdin == DEVNULL:
1470 p2cread = self._get_devnull()
1471 elif isinstance(stdin, int):
1472 p2cread = stdin
1473 else:
1474 # Assuming file-like object
1475 p2cread = stdin.fileno()
1477 if stdout is None:
1478 pass
1479 elif stdout == PIPE:
1480 c2pread, c2pwrite = os.pipe()
1481 elif stdout == DEVNULL:
1482 c2pwrite = self._get_devnull()
1483 elif isinstance(stdout, int):
1484 c2pwrite = stdout
1485 else:
1486 # Assuming file-like object
1487 c2pwrite = stdout.fileno()
1489 if stderr is None:
1490 pass
1491 elif stderr == PIPE:
1492 errread, errwrite = os.pipe()
1493 elif stderr == STDOUT:
1494 if c2pwrite != -1:
1495 errwrite = c2pwrite
1496 else: # child's stdout is not set, use parent's stdout
1497 errwrite = sys.__stdout__.fileno()
1498 elif stderr == DEVNULL:
1499 errwrite = self._get_devnull()
1500 elif isinstance(stderr, int):
1501 errwrite = stderr
1502 else:
1503 # Assuming file-like object
1504 errwrite = stderr.fileno()
1506 return (p2cread, p2cwrite,
1507 c2pread, c2pwrite,
1508 errread, errwrite)
1511 def _posix_spawn(self, args, executable, env, restore_signals,
1512 p2cread, p2cwrite,
1513 c2pread, c2pwrite,
1514 errread, errwrite):
1515 """Execute program using os.posix_spawn()."""
1516 if env is None:
1517 env = os.environ
1519 kwargs = {}
1520 if restore_signals:
1521 # See _Py_RestoreSignals() in Python/pylifecycle.c
1522 sigset = []
1523 for signame in ('SIGPIPE', 'SIGXFZ', 'SIGXFSZ'):
1524 signum = getattr(signal, signame, None)
1525 if signum is not None:
1526 sigset.append(signum)
1527 kwargs['setsigdef'] = sigset
1529 file_actions = []
1530 for fd in (p2cwrite, c2pread, errread):
1531 if fd != -1:
1532 file_actions.append((os.POSIX_SPAWN_CLOSE, fd))
1533 for fd, fd2 in (
1534 (p2cread, 0),
1535 (c2pwrite, 1),
1536 (errwrite, 2),
1537 ):
1538 if fd != -1:
1539 file_actions.append((os.POSIX_SPAWN_DUP2, fd, fd2))
1540 if file_actions:
1541 kwargs['file_actions'] = file_actions
1543 self.pid = os.posix_spawn(executable, args, env, **kwargs)
1544 self._child_created = True
1546 self._close_pipe_fds(p2cread, p2cwrite,
1547 c2pread, c2pwrite,
1548 errread, errwrite)
1550 def _execute_child(self, args, executable, preexec_fn, close_fds,
1551 pass_fds, cwd, env,
1552 startupinfo, creationflags, shell,
1553 p2cread, p2cwrite,
1554 c2pread, c2pwrite,
1555 errread, errwrite,
1556 restore_signals, start_new_session):
1557 """Execute program (POSIX version)"""
1559 if isinstance(args, (str, bytes)):
1560 args = [args]
1561 elif isinstance(args, os.PathLike):
1562 if shell:
1563 raise TypeError('path-like args is not allowed when '
1564 'shell is true')
1565 args = [args]
1566 else:
1567 args = list(args)
1569 if shell:
1570 # On Android the default shell is at '/system/bin/sh'.
1571 unix_shell = ('/system/bin/sh' if
1572 hasattr(sys, 'getandroidapilevel') else '/bin/sh')
1573 args = [unix_shell, "-c"] + args
1574 if executable:
1575 args[0] = executable
1577 if executable is None:
1578 executable = args[0]
1580 sys.audit("subprocess.Popen", executable, args, cwd, env)
1582 if (_USE_POSIX_SPAWN
1583 and os.path.dirname(executable)
1584 and preexec_fn is None
1585 and not close_fds
1586 and not pass_fds
1587 and cwd is None
1588 and (p2cread == -1 or p2cread > 2)
1589 and (c2pwrite == -1 or c2pwrite > 2)
1590 and (errwrite == -1 or errwrite > 2)
1591 and not start_new_session):
1592 self._posix_spawn(args, executable, env, restore_signals,
1593 p2cread, p2cwrite,
1594 c2pread, c2pwrite,
1595 errread, errwrite)
1596 return
1598 orig_executable = executable
1600 # For transferring possible exec failure from child to parent.
1601 # Data format: "exception name:hex errno:description"
1602 # Pickle is not used; it is complex and involves memory allocation.
1603 errpipe_read, errpipe_write = os.pipe()
1604 # errpipe_write must not be in the standard io 0, 1, or 2 fd range.
1605 low_fds_to_close = []
1606 while errpipe_write < 3:
1607 low_fds_to_close.append(errpipe_write)
1608 errpipe_write = os.dup(errpipe_write)
1609 for low_fd in low_fds_to_close:
1610 os.close(low_fd)
1611 try:
1612 try:
1613 # We must avoid complex work that could involve
1614 # malloc or free in the child process to avoid
1615 # potential deadlocks, thus we do all this here.
1616 # and pass it to fork_exec()
1618 if env is not None:
1619 env_list = []
1620 for k, v in env.items():
1621 k = os.fsencode(k)
1622 if b'=' in k:
1623 raise ValueError("illegal environment variable name")
1624 env_list.append(k + b'=' + os.fsencode(v))
1625 else:
1626 env_list = None # Use execv instead of execve.
1627 executable = os.fsencode(executable)
1628 if os.path.dirname(executable):
1629 executable_list = (executable,)
1630 else:
1631 # This matches the behavior of os._execvpe().
1632 executable_list = tuple(
1633 os.path.join(os.fsencode(dir), executable)
1634 for dir in os.get_exec_path(env))
1635 fds_to_keep = set(pass_fds)
1636 fds_to_keep.add(errpipe_write)
1637 self.pid = _posixsubprocess.fork_exec(
1638 args, executable_list,
1639 close_fds, tuple(sorted(map(int, fds_to_keep))),
1640 cwd, env_list,
1641 p2cread, p2cwrite, c2pread, c2pwrite,
1642 errread, errwrite,
1643 errpipe_read, errpipe_write,
1644 restore_signals, start_new_session, preexec_fn)
1645 self._child_created = True
1646 finally:
1647 # be sure the FD is closed no matter what
1648 os.close(errpipe_write)
1650 self._close_pipe_fds(p2cread, p2cwrite,
1651 c2pread, c2pwrite,
1652 errread, errwrite)
1654 # Wait for exec to fail or succeed; possibly raising an
1655 # exception (limited in size)
1656 errpipe_data = bytearray()
1657 while True:
1658 part = os.read(errpipe_read, 50000)
1659 errpipe_data += part
1660 if not part or len(errpipe_data) > 50000:
1661 break
1662 finally:
1663 # be sure the FD is closed no matter what
1664 os.close(errpipe_read)
1666 if errpipe_data:
1667 try:
1668 pid, sts = os.waitpid(self.pid, 0)
1669 if pid == self.pid:
1670 self._handle_exitstatus(sts)
1671 else:
1672 self.returncode = sys.maxsize
1673 except ChildProcessError:
1674 pass
1676 try:
1677 exception_name, hex_errno, err_msg = (
1678 errpipe_data.split(b':', 2))
1679 # The encoding here should match the encoding
1680 # written in by the subprocess implementations
1681 # like _posixsubprocess
1682 err_msg = err_msg.decode()
1683 except ValueError:
1684 exception_name = b'SubprocessError'
1685 hex_errno = b'0'
1686 err_msg = 'Bad exception data from child: {!r}'.format(
1687 bytes(errpipe_data))
1688 child_exception_type = getattr(
1689 builtins, exception_name.decode('ascii'),
1690 SubprocessError)
1691 if issubclass(child_exception_type, OSError) and hex_errno:
1692 errno_num = int(hex_errno, 16)
1693 child_exec_never_called = (err_msg == "noexec")
1694 if child_exec_never_called:
1695 err_msg = ""
1696 # The error must be from chdir(cwd).
1697 err_filename = cwd
1698 else:
1699 err_filename = orig_executable
1700 if errno_num != 0:
1701 err_msg = os.strerror(errno_num)
1702 raise child_exception_type(errno_num, err_msg, err_filename)
1703 raise child_exception_type(err_msg)
1706 def _handle_exitstatus(self, sts, _WIFSIGNALED=os.WIFSIGNALED,
1707 _WTERMSIG=os.WTERMSIG, _WIFEXITED=os.WIFEXITED,
1708 _WEXITSTATUS=os.WEXITSTATUS, _WIFSTOPPED=os.WIFSTOPPED,
1709 _WSTOPSIG=os.WSTOPSIG):
1710 """All callers to this function MUST hold self._waitpid_lock."""
1711 # This method is called (indirectly) by __del__, so it cannot
1712 # refer to anything outside of its local scope.
1713 if _WIFSIGNALED(sts):
1714 self.returncode = -_WTERMSIG(sts)
1715 elif _WIFEXITED(sts):
1716 self.returncode = _WEXITSTATUS(sts)
1717 elif _WIFSTOPPED(sts):
1718 self.returncode = -_WSTOPSIG(sts)
1719 else:
1720 # Should never happen
1721 raise SubprocessError("Unknown child exit status!")
1724 def _internal_poll(self, _deadstate=None, _waitpid=os.waitpid,
1725 _WNOHANG=os.WNOHANG, _ECHILD=errno.ECHILD):
1726 """Check if child process has terminated. Returns returncode
1727 attribute.
1729 This method is called by __del__, so it cannot reference anything
1730 outside of the local scope (nor can any methods it calls).
1732 """
1733 if self.returncode is None:
1734 if not self._waitpid_lock.acquire(False):
1735 # Something else is busy calling waitpid. Don't allow two
1736 # at once. We know nothing yet.
1737 return None
1738 try:
1739 if self.returncode is not None:
1740 return self.returncode # Another thread waited.
1741 pid, sts = _waitpid(self.pid, _WNOHANG)
1742 if pid == self.pid:
1743 self._handle_exitstatus(sts)
1744 except OSError as e:
1745 if _deadstate is not None:
1746 self.returncode = _deadstate
1747 elif e.errno == _ECHILD:
1748 # This happens if SIGCLD is set to be ignored or
1749 # waiting for child processes has otherwise been
1750 # disabled for our process. This child is dead, we
1751 # can't get the status.
1752 # http://bugs.python.org/issue15756
1753 self.returncode = 0
1754 finally:
1755 self._waitpid_lock.release()
1756 return self.returncode
1759 def _try_wait(self, wait_flags):
1760 """All callers to this function MUST hold self._waitpid_lock."""
1761 try:
1762 (pid, sts) = os.waitpid(self.pid, wait_flags)
1763 except ChildProcessError:
1764 # This happens if SIGCLD is set to be ignored or waiting
1765 # for child processes has otherwise been disabled for our
1766 # process. This child is dead, we can't get the status.
1767 pid = self.pid
1768 sts = 0
1769 return (pid, sts)
1772 def _wait(self, timeout):
1773 """Internal implementation of wait() on POSIX."""
1774 if self.returncode is not None:
1775 return self.returncode
1777 if timeout is not None:
1778 endtime = _time() + timeout
1779 # Enter a busy loop if we have a timeout. This busy loop was
1780 # cribbed from Lib/threading.py in Thread.wait() at r71065.
1781 delay = 0.0005 # 500 us -> initial delay of 1 ms
1782 while True:
1783 if self._waitpid_lock.acquire(False):
1784 try:
1785 if self.returncode is not None:
1786 break # Another thread waited.
1787 (pid, sts) = self._try_wait(os.WNOHANG)
1788 assert pid == self.pid or pid == 0
1789 if pid == self.pid:
1790 self._handle_exitstatus(sts)
1791 break
1792 finally:
1793 self._waitpid_lock.release()
1794 remaining = self._remaining_time(endtime)
1795 if remaining <= 0:
1796 raise TimeoutExpired(self.args, timeout)
1797 delay = min(delay * 2, remaining, .05)
1798 time.sleep(delay)
1799 else:
1800 while self.returncode is None:
1801 with self._waitpid_lock:
1802 if self.returncode is not None:
1803 break # Another thread waited.
1804 (pid, sts) = self._try_wait(0)
1805 # Check the pid and loop as waitpid has been known to
1806 # return 0 even without WNOHANG in odd situations.
1807 # http://bugs.python.org/issue14396.
1808 if pid == self.pid:
1809 self._handle_exitstatus(sts)
1810 return self.returncode
1813 def _communicate(self, input, endtime, orig_timeout):
1814 if self.stdin and not self._communication_started:
1815 # Flush stdio buffer. This might block, if the user has
1816 # been writing to .stdin in an uncontrolled fashion.
1817 try:
1818 self.stdin.flush()
1819 except BrokenPipeError:
1820 pass # communicate() must ignore BrokenPipeError.
1821 if not input:
1822 try:
1823 self.stdin.close()
1824 except BrokenPipeError:
1825 pass # communicate() must ignore BrokenPipeError.
1827 stdout = None
1828 stderr = None
1830 # Only create this mapping if we haven't already.
1831 if not self._communication_started:
1832 self._fileobj2output = {}
1833 if self.stdout:
1834 self._fileobj2output[self.stdout] = []
1835 if self.stderr:
1836 self._fileobj2output[self.stderr] = []
1838 if self.stdout:
1839 stdout = self._fileobj2output[self.stdout]
1840 if self.stderr:
1841 stderr = self._fileobj2output[self.stderr]
1843 self._save_input(input)
1845 if self._input:
1846 input_view = memoryview(self._input)
1848 with _PopenSelector() as selector:
1849 if self.stdin and input:
1850 selector.register(self.stdin, selectors.EVENT_WRITE)
1851 if self.stdout and not self.stdout.closed:
1852 selector.register(self.stdout, selectors.EVENT_READ)
1853 if self.stderr and not self.stderr.closed:
1854 selector.register(self.stderr, selectors.EVENT_READ)
1856 while selector.get_map():
1857 timeout = self._remaining_time(endtime)
1858 if timeout is not None and timeout < 0:
1859 self._check_timeout(endtime, orig_timeout,
1860 stdout, stderr,
1861 skip_check_and_raise=True)
1862 raise RuntimeError( # Impossible :)
1863 '_check_timeout(..., skip_check_and_raise=True) '
1864 'failed to raise TimeoutExpired.')
1866 ready = selector.select(timeout)
1867 self._check_timeout(endtime, orig_timeout, stdout, stderr)
1869 # XXX Rewrite these to use non-blocking I/O on the file
1870 # objects; they are no longer using C stdio!
1872 for key, events in ready:
1873 if key.fileobj is self.stdin:
1874 chunk = input_view[self._input_offset :
1875 self._input_offset + _PIPE_BUF]
1876 try:
1877 self._input_offset += os.write(key.fd, chunk)
1878 except BrokenPipeError:
1879 selector.unregister(key.fileobj)
1880 key.fileobj.close()
1881 else:
1882 if self._input_offset >= len(self._input):
1883 selector.unregister(key.fileobj)
1884 key.fileobj.close()
1885 elif key.fileobj in (self.stdout, self.stderr):
1886 data = os.read(key.fd, 32768)
1887 if not data:
1888 selector.unregister(key.fileobj)
1889 key.fileobj.close()
1890 self._fileobj2output[key.fileobj].append(data)
1892 self.wait(timeout=self._remaining_time(endtime))
1894 # All data exchanged. Translate lists into strings.
1895 if stdout is not None:
1896 stdout = b''.join(stdout)
1897 if stderr is not None:
1898 stderr = b''.join(stderr)
1900 # Translate newlines, if requested.
1901 # This also turns bytes into strings.
1902 if self.text_mode:
1903 if stdout is not None:
1904 stdout = self._translate_newlines(stdout,
1905 self.stdout.encoding,
1906 self.stdout.errors)
1907 if stderr is not None:
1908 stderr = self._translate_newlines(stderr,
1909 self.stderr.encoding,
1910 self.stderr.errors)
1912 return (stdout, stderr)
1915 def _save_input(self, input):
1916 # This method is called from the _communicate_with_*() methods
1917 # so that if we time out while communicating, we can continue
1918 # sending input if we retry.
1919 if self.stdin and self._input is None:
1920 self._input_offset = 0
1921 self._input = input
1922 if input is not None and self.text_mode:
1923 self._input = self._input.encode(self.stdin.encoding,
1924 self.stdin.errors)
1927 def send_signal(self, sig):
1928 """Send a signal to the process."""
1929 # Skip signalling a process that we know has already died.
1930 if self.returncode is None:
1931 os.kill(self.pid, sig)
1933 def terminate(self):
1934 """Terminate the process with SIGTERM
1935 """
1936 self.send_signal(signal.SIGTERM)
1938 def kill(self):
1939 """Kill the process with SIGKILL
1940 """
1941 self.send_signal(signal.SIGKILL)