Python code coverage for Lib/subprocess.py

#	count	content
1	n/a	# subprocess - Subprocesses with accessible I/O streams
2	n/a	#
3	n/a	# For more information about this module, see PEP 324.
4	n/a	#
5	n/a	# Copyright (c) 2003-2005 by Peter Astrand <astrand@lysator.liu.se>
6	n/a	#
7	n/a	# Licensed to PSF under a Contributor Agreement.
8	n/a	# See http://www.python.org/2.4/license for licensing details.
9	n/a
10	n/a	r"""Subprocesses with accessible I/O streams
11	n/a
12	n/a	This module allows you to spawn processes, connect to their
13	n/a	input/output/error pipes, and obtain their return codes.
14	n/a
15	n/a	For a complete description of this module see the Python documentation.
16	n/a
17	n/a	Main API
18	n/a	========
19	n/a	run(...): Runs a command, waits for it to complete, then returns a
20	n/a	CompletedProcess instance.
21	n/a	Popen(...): A class for flexibly executing a command in a new process
22	n/a
23	n/a	Constants
24	n/a	---------
25	n/a	DEVNULL: Special value that indicates that os.devnull should be used
26	n/a	PIPE: Special value that indicates a pipe should be created
27	n/a	STDOUT: Special value that indicates that stderr should go to stdout
28	n/a
29	n/a
30	n/a	Older API
31	n/a	=========
32	n/a	call(...): Runs a command, waits for it to complete, then returns
33	n/a	the return code.
34	n/a	check_call(...): Same as call() but raises CalledProcessError()
35	n/a	if return code is not 0
36	n/a	check_output(...): Same as check_call() but returns the contents of
37	n/a	stdout instead of a return code
38	n/a	getoutput(...): Runs a command in the shell, waits for it to complete,
39	n/a	then returns the output
40	n/a	getstatusoutput(...): Runs a command in the shell, waits for it to complete,
41	n/a	then returns a (status, output) tuple
42	n/a	"""
43	n/a
44	n/a	import sys
45	n/a	_mswindows = (sys.platform == "win32")
46	n/a
47	n/a	import io
48	n/a	import os
49	n/a	import time
50	n/a	import signal
51	n/a	import builtins
52	n/a	import warnings
53	n/a	import errno
54	n/a	from time import monotonic as _time
55	n/a
56	n/a	# Exception classes used by this module.
57	n/a	class SubprocessError(Exception): pass
58	n/a
59	n/a
60	n/a	class CalledProcessError(SubprocessError):
61	n/a	"""Raised when run() is called with check=True and the process
62	n/a	returns a non-zero exit status.
63	n/a
64	n/a	Attributes:
65	n/a	cmd, returncode, stdout, stderr, output
66	n/a	"""
67	n/a	def __init__(self, returncode, cmd, output=None, stderr=None):
68	n/a	self.returncode = returncode
69	n/a	self.cmd = cmd
70	n/a	self.output = output
71	n/a	self.stderr = stderr
72	n/a
73	n/a	def __str__(self):
74	n/a	if self.returncode and self.returncode < 0:
75	n/a	try:
76	n/a	return "Command '%s' died with %r." % (
77	n/a	self.cmd, signal.Signals(-self.returncode))
78	n/a	except ValueError:
79	n/a	return "Command '%s' died with unknown signal %d." % (
80	n/a	self.cmd, -self.returncode)
81	n/a	else:
82	n/a	return "Command '%s' returned non-zero exit status %d." % (
83	n/a	self.cmd, self.returncode)
84	n/a
85	n/a	@property
86	n/a	def stdout(self):
87	n/a	"""Alias for output attribute, to match stderr"""
88	n/a	return self.output
89	n/a
90	n/a	@stdout.setter
91	n/a	def stdout(self, value):
92	n/a	# There's no obvious reason to set this, but allow it anyway so
93	n/a	# .stdout is a transparent alias for .output
94	n/a	self.output = value
95	n/a
96	n/a
97	n/a	class TimeoutExpired(SubprocessError):
98	n/a	"""This exception is raised when the timeout expires while waiting for a
99	n/a	child process.
100	n/a
101	n/a	Attributes:
102	n/a	cmd, output, stdout, stderr, timeout
103	n/a	"""
104	n/a	def __init__(self, cmd, timeout, output=None, stderr=None):
105	n/a	self.cmd = cmd
106	n/a	self.timeout = timeout
107	n/a	self.output = output
108	n/a	self.stderr = stderr
109	n/a
110	n/a	def __str__(self):
111	n/a	return ("Command '%s' timed out after %s seconds" %
112	n/a	(self.cmd, self.timeout))
113	n/a
114	n/a	@property
115	n/a	def stdout(self):
116	n/a	return self.output
117	n/a
118	n/a	@stdout.setter
119	n/a	def stdout(self, value):
120	n/a	# There's no obvious reason to set this, but allow it anyway so
121	n/a	# .stdout is a transparent alias for .output
122	n/a	self.output = value
123	n/a
124	n/a
125	n/a	if _mswindows:
126	n/a	import threading
127	n/a	import msvcrt
128	n/a	import _winapi
129	n/a	class STARTUPINFO:
130	n/a	dwFlags = 0
131	n/a	hStdInput = None
132	n/a	hStdOutput = None
133	n/a	hStdError = None
134	n/a	wShowWindow = 0
135	n/a	else:
136	n/a	import _posixsubprocess
137	n/a	import select
138	n/a	import selectors
139	n/a	try:
140	n/a	import threading
141	n/a	except ImportError:
142	n/a	import dummy_threading as threading
143	n/a
144	n/a	# When select or poll has indicated that the file is writable,
145	n/a	# we can write up to _PIPE_BUF bytes without risk of blocking.
146	n/a	# POSIX defines PIPE_BUF as >= 512.
147	n/a	_PIPE_BUF = getattr(select, 'PIPE_BUF', 512)
148	n/a
149	n/a	# poll/select have the advantage of not requiring any extra file
150	n/a	# descriptor, contrarily to epoll/kqueue (also, they require a single
151	n/a	# syscall).
152	n/a	if hasattr(selectors, 'PollSelector'):
153	n/a	_PopenSelector = selectors.PollSelector
154	n/a	else:
155	n/a	_PopenSelector = selectors.SelectSelector
156	n/a
157	n/a
158	n/a	__all__ = ["Popen", "PIPE", "STDOUT", "call", "check_call", "getstatusoutput",
159	n/a	"getoutput", "check_output", "run", "CalledProcessError", "DEVNULL",
160	n/a	"SubprocessError", "TimeoutExpired", "CompletedProcess"]
161	n/a	# NOTE: We intentionally exclude list2cmdline as it is
162	n/a	# considered an internal implementation detail. issue10838.
163	n/a
164	n/a	if _mswindows:
165	n/a	from _winapi import (CREATE_NEW_CONSOLE, CREATE_NEW_PROCESS_GROUP,
166	n/a	STD_INPUT_HANDLE, STD_OUTPUT_HANDLE,
167	n/a	STD_ERROR_HANDLE, SW_HIDE,
168	n/a	STARTF_USESTDHANDLES, STARTF_USESHOWWINDOW)
169	n/a
170	n/a	__all__.extend(["CREATE_NEW_CONSOLE", "CREATE_NEW_PROCESS_GROUP",
171	n/a	"STD_INPUT_HANDLE", "STD_OUTPUT_HANDLE",
172	n/a	"STD_ERROR_HANDLE", "SW_HIDE",
173	n/a	"STARTF_USESTDHANDLES", "STARTF_USESHOWWINDOW",
174	n/a	"STARTUPINFO"])
175	n/a
176	n/a	class Handle(int):
177	n/a	closed = False
178	n/a
179	n/a	def Close(self, CloseHandle=_winapi.CloseHandle):
180	n/a	if not self.closed:
181	n/a	self.closed = True
182	n/a	CloseHandle(self)
183	n/a
184	n/a	def Detach(self):
185	n/a	if not self.closed:
186	n/a	self.closed = True
187	n/a	return int(self)
188	n/a	raise ValueError("already closed")
189	n/a
190	n/a	def __repr__(self):
191	n/a	return "%s(%d)" % (self.__class__.__name__, int(self))
192	n/a
193	n/a	__del__ = Close
194	n/a	__str__ = __repr__
195	n/a
196	n/a
197	n/a	# This lists holds Popen instances for which the underlying process had not
198	n/a	# exited at the time its __del__ method got called: those processes are wait()ed
199	n/a	# for synchronously from _cleanup() when a new Popen object is created, to avoid
200	n/a	# zombie processes.
201	n/a	_active = []
202	n/a
203	n/a	def _cleanup():
204	n/a	for inst in _active[:]:
205	n/a	res = inst._internal_poll(_deadstate=sys.maxsize)
206	n/a	if res is not None:
207	n/a	try:
208	n/a	_active.remove(inst)
209	n/a	except ValueError:
210	n/a	# This can happen if two threads create a new Popen instance.
211	n/a	# It's harmless that it was already removed, so ignore.
212	n/a	pass
213	n/a
214	n/a	PIPE = -1
215	n/a	STDOUT = -2
216	n/a	DEVNULL = -3
217	n/a
218	n/a
219	n/a	# XXX This function is only used by multiprocessing and the test suite,
220	n/a	# but it's here so that it can be imported when Python is compiled without
221	n/a	# threads.
222	n/a
223	n/a	def _optim_args_from_interpreter_flags():
224	n/a	"""Return a list of command-line arguments reproducing the current
225	n/a	optimization settings in sys.flags."""
226	n/a	args = []
227	n/a	value = sys.flags.optimize
228	n/a	if value > 0:
229	n/a	args.append('-' + 'O' * value)
230	n/a	return args
231	n/a
232	n/a
233	n/a	def _args_from_interpreter_flags():
234	n/a	"""Return a list of command-line arguments reproducing the current
235	n/a	settings in sys.flags and sys.warnoptions."""
236	n/a	flag_opt_map = {
237	n/a	'debug': 'd',
238	n/a	# 'inspect': 'i',
239	n/a	# 'interactive': 'i',
240	n/a	'dont_write_bytecode': 'B',
241	n/a	'no_user_site': 's',
242	n/a	'no_site': 'S',
243	n/a	'ignore_environment': 'E',
244	n/a	'verbose': 'v',
245	n/a	'bytes_warning': 'b',
246	n/a	'quiet': 'q',
247	n/a	# -O is handled in _optim_args_from_interpreter_flags()
248	n/a	}
249	n/a	args = _optim_args_from_interpreter_flags()
250	n/a	for flag, opt in flag_opt_map.items():
251	n/a	v = getattr(sys.flags, flag)
252	n/a	if v > 0:
253	n/a	args.append('-' + opt * v)
254	n/a	for opt in sys.warnoptions:
255	n/a	args.append('-W' + opt)
256	n/a	return args
257	n/a
258	n/a
259	n/a	def call(popenargs, timeout=None, *kwargs):
260	n/a	"""Run command with arguments. Wait for command to complete or
261	n/a	timeout, then return the returncode attribute.
262	n/a
263	n/a	The arguments are the same as for the Popen constructor. Example:
264	n/a
265	n/a	retcode = call(["ls", "-l"])
266	n/a	"""
267	n/a	with Popen(popenargs, *kwargs) as p:
268	n/a	try:
269	n/a	return p.wait(timeout=timeout)
270	n/a	except:
271	n/a	p.kill()
272	n/a	p.wait()
273	n/a	raise
274	n/a
275	n/a
276	n/a	def check_call(popenargs, *kwargs):
277	n/a	"""Run command with arguments. Wait for command to complete. If
278	n/a	the exit code was zero then return, otherwise raise
279	n/a	CalledProcessError. The CalledProcessError object will have the
280	n/a	return code in the returncode attribute.
281	n/a
282	n/a	The arguments are the same as for the call function. Example:
283	n/a
284	n/a	check_call(["ls", "-l"])
285	n/a	"""
286	n/a	retcode = call(popenargs, *kwargs)
287	n/a	if retcode:
288	n/a	cmd = kwargs.get("args")
289	n/a	if cmd is None:
290	n/a	cmd = popenargs[0]
291	n/a	raise CalledProcessError(retcode, cmd)
292	n/a	return 0
293	n/a
294	n/a
295	n/a	def check_output(popenargs, timeout=None, *kwargs):
296	n/a	r"""Run command with arguments and return its output.
297	n/a
298	n/a	If the exit code was non-zero it raises a CalledProcessError. The
299	n/a	CalledProcessError object will have the return code in the returncode
300	n/a	attribute and output in the output attribute.
301	n/a
302	n/a	The arguments are the same as for the Popen constructor. Example:
303	n/a
304	n/a	>>> check_output(["ls", "-l", "/dev/null"])
305	n/a	b'crw-rw-rw- 1 root root 1, 3 Oct 18 2007 /dev/null\n'
306	n/a
307	n/a	The stdout argument is not allowed as it is used internally.
308	n/a	To capture standard error in the result, use stderr=STDOUT.
309	n/a
310	n/a	>>> check_output(["/bin/sh", "-c",
311	n/a	... "ls -l non_existent_file ; exit 0"],
312	n/a	... stderr=STDOUT)
313	n/a	b'ls: non_existent_file: No such file or directory\n'
314	n/a
315	n/a	There is an additional optional argument, "input", allowing you to
316	n/a	pass a string to the subprocess's stdin. If you use this argument
317	n/a	you may not also use the Popen constructor's "stdin" argument, as
318	n/a	it too will be used internally. Example:
319	n/a
320	n/a	>>> check_output(["sed", "-e", "s/foo/bar/"],
321	n/a	... input=b"when in the course of fooman events\n")
322	n/a	b'when in the course of barman events\n'
323	n/a
324	n/a	If universal_newlines=True is passed, the "input" argument must be a
325	n/a	string and the return value will be a string rather than bytes.
326	n/a	"""
327	n/a	if 'stdout' in kwargs:
328	n/a	raise ValueError('stdout argument not allowed, it will be overridden.')
329	n/a
330	n/a	if 'input' in kwargs and kwargs['input'] is None:
331	n/a	# Explicitly passing input=None was previously equivalent to passing an
332	n/a	# empty string. That is maintained here for backwards compatibility.
333	n/a	kwargs['input'] = '' if kwargs.get('universal_newlines', False) else b''
334	n/a
335	n/a	return run(*popenargs, stdout=PIPE, timeout=timeout, check=True,
336	n/a	**kwargs).stdout
337	n/a
338	n/a
339	n/a	class CompletedProcess(object):
340	n/a	"""A process that has finished running.
341	n/a
342	n/a	This is returned by run().
343	n/a
344	n/a	Attributes:
345	n/a	args: The list or str args passed to run().
346	n/a	returncode: The exit code of the process, negative for signals.
347	n/a	stdout: The standard output (None if not captured).
348	n/a	stderr: The standard error (None if not captured).
349	n/a	"""
350	n/a	def __init__(self, args, returncode, stdout=None, stderr=None):
351	n/a	self.args = args
352	n/a	self.returncode = returncode
353	n/a	self.stdout = stdout
354	n/a	self.stderr = stderr
355	n/a
356	n/a	def __repr__(self):
357	n/a	args = ['args={!r}'.format(self.args),
358	n/a	'returncode={!r}'.format(self.returncode)]
359	n/a	if self.stdout is not None:
360	n/a	args.append('stdout={!r}'.format(self.stdout))
361	n/a	if self.stderr is not None:
362	n/a	args.append('stderr={!r}'.format(self.stderr))
363	n/a	return "{}({})".format(type(self).__name__, ', '.join(args))
364	n/a
365	n/a	def check_returncode(self):
366	n/a	"""Raise CalledProcessError if the exit code is non-zero."""
367	n/a	if self.returncode:
368	n/a	raise CalledProcessError(self.returncode, self.args, self.stdout,
369	n/a	self.stderr)
370	n/a
371	n/a
372	n/a	def run(popenargs, input=None, timeout=None, check=False, *kwargs):
373	n/a	"""Run command with arguments and return a CompletedProcess instance.
374	n/a
375	n/a	The returned instance will have attributes args, returncode, stdout and
376	n/a	stderr. By default, stdout and stderr are not captured, and those attributes
377	n/a	will be None. Pass stdout=PIPE and/or stderr=PIPE in order to capture them.
378	n/a
379	n/a	If check is True and the exit code was non-zero, it raises a
380	n/a	CalledProcessError. The CalledProcessError object will have the return code
381	n/a	in the returncode attribute, and output & stderr attributes if those streams
382	n/a	were captured.
383	n/a
384	n/a	If timeout is given, and the process takes too long, a TimeoutExpired
385	n/a	exception will be raised.
386	n/a
387	n/a	There is an optional argument "input", allowing you to
388	n/a	pass a string to the subprocess's stdin. If you use this argument
389	n/a	you may not also use the Popen constructor's "stdin" argument, as
390	n/a	it will be used internally.
391	n/a
392	n/a	The other arguments are the same as for the Popen constructor.
393	n/a
394	n/a	If universal_newlines=True is passed, the "input" argument must be a
395	n/a	string and stdout/stderr in the returned object will be strings rather than
396	n/a	bytes.
397	n/a	"""
398	n/a	if input is not None:
399	n/a	if 'stdin' in kwargs:
400	n/a	raise ValueError('stdin and input arguments may not both be used.')
401	n/a	kwargs['stdin'] = PIPE
402	n/a
403	n/a	with Popen(popenargs, *kwargs) as process:
404	n/a	try:
405	n/a	stdout, stderr = process.communicate(input, timeout=timeout)
406	n/a	except TimeoutExpired:
407	n/a	process.kill()
408	n/a	stdout, stderr = process.communicate()
409	n/a	raise TimeoutExpired(process.args, timeout, output=stdout,
410	n/a	stderr=stderr)
411	n/a	except:
412	n/a	process.kill()
413	n/a	process.wait()
414	n/a	raise
415	n/a	retcode = process.poll()
416	n/a	if check and retcode:
417	n/a	raise CalledProcessError(retcode, process.args,
418	n/a	output=stdout, stderr=stderr)
419	n/a	return CompletedProcess(process.args, retcode, stdout, stderr)
420	n/a
421	n/a
422	n/a	def list2cmdline(seq):
423	n/a	"""
424	n/a	Translate a sequence of arguments into a command line
425	n/a	string, using the same rules as the MS C runtime:
426	n/a
427	n/a	1) Arguments are delimited by white space, which is either a
428	n/a	space or a tab.
429	n/a
430	n/a	2) A string surrounded by double quotation marks is
431	n/a	interpreted as a single argument, regardless of white space
432	n/a	contained within. A quoted string can be embedded in an
433	n/a	argument.
434	n/a
435	n/a	3) A double quotation mark preceded by a backslash is
436	n/a	interpreted as a literal double quotation mark.
437	n/a
438	n/a	4) Backslashes are interpreted literally, unless they
439	n/a	immediately precede a double quotation mark.
440	n/a
441	n/a	5) If backslashes immediately precede a double quotation mark,
442	n/a	every pair of backslashes is interpreted as a literal
443	n/a	backslash. If the number of backslashes is odd, the last
444	n/a	backslash escapes the next double quotation mark as
445	n/a	described in rule 3.
446	n/a	"""
447	n/a
448	n/a	# See
449	n/a	# http://msdn.microsoft.com/en-us/library/17w5ykft.aspx
450	n/a	# or search http://msdn.microsoft.com for
451	n/a	# "Parsing C++ Command-Line Arguments"
452	n/a	result = []
453	n/a	needquote = False
454	n/a	for arg in seq:
455	n/a	bs_buf = []
456	n/a
457	n/a	# Add a space to separate this argument from the others
458	n/a	if result:
459	n/a	result.append(' ')
460	n/a
461	n/a	needquote = (" " in arg) or ("\t" in arg) or not arg
462	n/a	if needquote:
463	n/a	result.append('"')
464	n/a
465	n/a	for c in arg:
466	n/a	if c == '\\':
467	n/a	# Don't know if we need to double yet.
468	n/a	bs_buf.append(c)
469	n/a	elif c == '"':
470	n/a	# Double backslashes.
471	n/a	result.append('\\' * len(bs_buf)*2)
472	n/a	bs_buf = []
473	n/a	result.append('\\"')
474	n/a	else:
475	n/a	# Normal char
476	n/a	if bs_buf:
477	n/a	result.extend(bs_buf)
478	n/a	bs_buf = []
479	n/a	result.append(c)
480	n/a
481	n/a	# Add remaining backslashes, if any.
482	n/a	if bs_buf:
483	n/a	result.extend(bs_buf)
484	n/a
485	n/a	if needquote:
486	n/a	result.extend(bs_buf)
487	n/a	result.append('"')
488	n/a
489	n/a	return ''.join(result)
490	n/a
491	n/a
492	n/a	# Various tools for executing commands and looking at their output and status.
493	n/a	#
494	n/a
495	n/a	def getstatusoutput(cmd):
496	n/a	""" Return (status, output) of executing cmd in a shell.
497	n/a
498	n/a	Execute the string 'cmd' in a shell with 'check_output' and
499	n/a	return a 2-tuple (status, output). The locale encoding is used
500	n/a	to decode the output and process newlines.
501	n/a
502	n/a	A trailing newline is stripped from the output.
503	n/a	The exit status for the command can be interpreted
504	n/a	according to the rules for the function 'wait'. Example:
505	n/a
506	n/a	>>> import subprocess
507	n/a	>>> subprocess.getstatusoutput('ls /bin/ls')
508	n/a	(0, '/bin/ls')
509	n/a	>>> subprocess.getstatusoutput('cat /bin/junk')
510	n/a	(256, 'cat: /bin/junk: No such file or directory')
511	n/a	>>> subprocess.getstatusoutput('/bin/junk')
512	n/a	(256, 'sh: /bin/junk: not found')
513	n/a	"""
514	n/a	try:
515	n/a	data = check_output(cmd, shell=True, universal_newlines=True, stderr=STDOUT)
516	n/a	status = 0
517	n/a	except CalledProcessError as ex:
518	n/a	data = ex.output
519	n/a	status = ex.returncode
520	n/a	if data[-1:] == '\n':
521	n/a	data = data[:-1]
522	n/a	return status, data
523	n/a
524	n/a	def getoutput(cmd):
525	n/a	"""Return output (stdout or stderr) of executing cmd in a shell.
526	n/a
527	n/a	Like getstatusoutput(), except the exit status is ignored and the return
528	n/a	value is a string containing the command's output. Example:
529	n/a
530	n/a	>>> import subprocess
531	n/a	>>> subprocess.getoutput('ls /bin/ls')
532	n/a	'/bin/ls'
533	n/a	"""
534	n/a	return getstatusoutput(cmd)[1]
535	n/a
536	n/a
537	n/a	_PLATFORM_DEFAULT_CLOSE_FDS = object()
538	n/a
539	n/a
540	n/a	class Popen(object):
541	n/a	""" Execute a child program in a new process.
542	n/a
543	n/a	For a complete description of the arguments see the Python documentation.
544	n/a
545	n/a	Arguments:
546	n/a	args: A string, or a sequence of program arguments.
547	n/a
548	n/a	bufsize: supplied as the buffering argument to the open() function when
549	n/a	creating the stdin/stdout/stderr pipe file objects
550	n/a
551	n/a	executable: A replacement program to execute.
552	n/a
553	n/a	stdin, stdout and stderr: These specify the executed programs' standard
554	n/a	input, standard output and standard error file handles, respectively.
555	n/a
556	n/a	preexec_fn: (POSIX only) An object to be called in the child process
557	n/a	just before the child is executed.
558	n/a
559	n/a	close_fds: Controls closing or inheriting of file descriptors.
560	n/a
561	n/a	shell: If true, the command will be executed through the shell.
562	n/a
563	n/a	cwd: Sets the current directory before the child is executed.
564	n/a
565	n/a	env: Defines the environment variables for the new process.
566	n/a
567	n/a	universal_newlines: If true, use universal line endings for file
568	n/a	objects stdin, stdout and stderr.
569	n/a
570	n/a	startupinfo and creationflags (Windows only)
571	n/a
572	n/a	restore_signals (POSIX only)
573	n/a
574	n/a	start_new_session (POSIX only)
575	n/a
576	n/a	pass_fds (POSIX only)
577	n/a
578	n/a	encoding and errors: Text mode encoding and error handling to use for
579	n/a	file objects stdin, stdout and stderr.
580	n/a
581	n/a	Attributes:
582	n/a	stdin, stdout, stderr, pid, returncode
583	n/a	"""
584	n/a	_child_created = False # Set here since __del__ checks it
585	n/a
586	n/a	def __init__(self, args, bufsize=-1, executable=None,
587	n/a	stdin=None, stdout=None, stderr=None,
588	n/a	preexec_fn=None, close_fds=_PLATFORM_DEFAULT_CLOSE_FDS,
589	n/a	shell=False, cwd=None, env=None, universal_newlines=False,
590	n/a	startupinfo=None, creationflags=0,
591	n/a	restore_signals=True, start_new_session=False,
592	n/a	pass_fds=(), *, encoding=None, errors=None):
593	n/a	"""Create new Popen instance."""
594	n/a	_cleanup()
595	n/a	# Held while anything is calling waitpid before returncode has been
596	n/a	# updated to prevent clobbering returncode if wait() or poll() are
597	n/a	# called from multiple threads at once. After acquiring the lock,
598	n/a	# code must re-check self.returncode to see if another thread just
599	n/a	# finished a waitpid() call.
600	n/a	self._waitpid_lock = threading.Lock()
601	n/a
602	n/a	self._input = None
603	n/a	self._communication_started = False
604	n/a	if bufsize is None:
605	n/a	bufsize = -1 # Restore default
606	n/a	if not isinstance(bufsize, int):
607	n/a	raise TypeError("bufsize must be an integer")
608	n/a
609	n/a	if _mswindows:
610	n/a	if preexec_fn is not None:
611	n/a	raise ValueError("preexec_fn is not supported on Windows "
612	n/a	"platforms")
613	n/a	any_stdio_set = (stdin is not None or stdout is not None or
614	n/a	stderr is not None)
615	n/a	if close_fds is _PLATFORM_DEFAULT_CLOSE_FDS:
616	n/a	if any_stdio_set:
617	n/a	close_fds = False
618	n/a	else:
619	n/a	close_fds = True
620	n/a	elif close_fds and any_stdio_set:
621	n/a	raise ValueError(
622	n/a	"close_fds is not supported on Windows platforms"
623	n/a	" if you redirect stdin/stdout/stderr")
624	n/a	else:
625	n/a	# POSIX
626	n/a	if close_fds is _PLATFORM_DEFAULT_CLOSE_FDS:
627	n/a	close_fds = True
628	n/a	if pass_fds and not close_fds:
629	n/a	warnings.warn("pass_fds overriding close_fds.", RuntimeWarning)
630	n/a	close_fds = True
631	n/a	if startupinfo is not None:
632	n/a	raise ValueError("startupinfo is only supported on Windows "
633	n/a	"platforms")
634	n/a	if creationflags != 0:
635	n/a	raise ValueError("creationflags is only supported on Windows "
636	n/a	"platforms")
637	n/a
638	n/a	self.args = args
639	n/a	self.stdin = None
640	n/a	self.stdout = None
641	n/a	self.stderr = None
642	n/a	self.pid = None
643	n/a	self.returncode = None
644	n/a	self.universal_newlines = universal_newlines
645	n/a	self.encoding = encoding
646	n/a	self.errors = errors
647	n/a
648	n/a	# Input and output objects. The general principle is like
649	n/a	# this:
650	n/a	#
651	n/a	# Parent Child
652	n/a	# ------ -----
653	n/a	# p2cwrite ---stdin---> p2cread
654	n/a	# c2pread <--stdout--- c2pwrite
655	n/a	# errread <--stderr--- errwrite
656	n/a	#
657	n/a	# On POSIX, the child objects are file descriptors. On
658	n/a	# Windows, these are Windows file handles. The parent objects
659	n/a	# are file descriptors on both platforms. The parent objects
660	n/a	# are -1 when not using PIPEs. The child objects are -1
661	n/a	# when not redirecting.
662	n/a
663	n/a	(p2cread, p2cwrite,
664	n/a	c2pread, c2pwrite,
665	n/a	errread, errwrite) = self._get_handles(stdin, stdout, stderr)
666	n/a
667	n/a	# We wrap OS handles before launching the child, otherwise a
668	n/a	# quickly terminating child could make our fds unwrappable
669	n/a	# (see #8458).
670	n/a
671	n/a	if _mswindows:
672	n/a	if p2cwrite != -1:
673	n/a	p2cwrite = msvcrt.open_osfhandle(p2cwrite.Detach(), 0)
674	n/a	if c2pread != -1:
675	n/a	c2pread = msvcrt.open_osfhandle(c2pread.Detach(), 0)
676	n/a	if errread != -1:
677	n/a	errread = msvcrt.open_osfhandle(errread.Detach(), 0)
678	n/a
679	n/a	text_mode = encoding or errors or universal_newlines
680	n/a
681	n/a	self._closed_child_pipe_fds = False
682	n/a
683	n/a	try:
684	n/a	if p2cwrite != -1:
685	n/a	self.stdin = io.open(p2cwrite, 'wb', bufsize)
686	n/a	if text_mode:
687	n/a	self.stdin = io.TextIOWrapper(self.stdin, write_through=True,
688	n/a	line_buffering=(bufsize == 1),
689	n/a	encoding=encoding, errors=errors)
690	n/a	if c2pread != -1:
691	n/a	self.stdout = io.open(c2pread, 'rb', bufsize)
692	n/a	if text_mode:
693	n/a	self.stdout = io.TextIOWrapper(self.stdout,
694	n/a	encoding=encoding, errors=errors)
695	n/a	if errread != -1:
696	n/a	self.stderr = io.open(errread, 'rb', bufsize)
697	n/a	if text_mode:
698	n/a	self.stderr = io.TextIOWrapper(self.stderr,
699	n/a	encoding=encoding, errors=errors)
700	n/a
701	n/a	self._execute_child(args, executable, preexec_fn, close_fds,
702	n/a	pass_fds, cwd, env,
703	n/a	startupinfo, creationflags, shell,
704	n/a	p2cread, p2cwrite,
705	n/a	c2pread, c2pwrite,
706	n/a	errread, errwrite,
707	n/a	restore_signals, start_new_session)
708	n/a	except:
709	n/a	# Cleanup if the child failed starting.
710	n/a	for f in filter(None, (self.stdin, self.stdout, self.stderr)):
711	n/a	try:
712	n/a	f.close()
713	n/a	except OSError:
714	n/a	pass # Ignore EBADF or other errors.
715	n/a
716	n/a	if not self._closed_child_pipe_fds:
717	n/a	to_close = []
718	n/a	if stdin == PIPE:
719	n/a	to_close.append(p2cread)
720	n/a	if stdout == PIPE:
721	n/a	to_close.append(c2pwrite)
722	n/a	if stderr == PIPE:
723	n/a	to_close.append(errwrite)
724	n/a	if hasattr(self, '_devnull'):
725	n/a	to_close.append(self._devnull)
726	n/a	for fd in to_close:
727	n/a	try:
728	n/a	os.close(fd)
729	n/a	except OSError:
730	n/a	pass
731	n/a
732	n/a	raise
733	n/a
734	n/a	def _translate_newlines(self, data, encoding, errors):
735	n/a	data = data.decode(encoding, errors)
736	n/a	return data.replace("\r\n", "\n").replace("\r", "\n")
737	n/a
738	n/a	def __enter__(self):
739	n/a	return self
740	n/a
741	n/a	def __exit__(self, type, value, traceback):
742	n/a	if self.stdout:
743	n/a	self.stdout.close()
744	n/a	if self.stderr:
745	n/a	self.stderr.close()
746	n/a	try: # Flushing a BufferedWriter may raise an error
747	n/a	if self.stdin:
748	n/a	self.stdin.close()
749	n/a	finally:
750	n/a	# Wait for the process to terminate, to avoid zombies.
751	n/a	self.wait()
752	n/a
753	n/a	def __del__(self, _maxsize=sys.maxsize, _warn=warnings.warn):
754	n/a	if not self._child_created:
755	n/a	# We didn't get to successfully create a child process.
756	n/a	return
757	n/a	if self.returncode is None:
758	n/a	# Not reading subprocess exit status creates a zombi process which
759	n/a	# is only destroyed at the parent python process exit
760	n/a	_warn("subprocess %s is still running" % self.pid,
761	n/a	ResourceWarning, source=self)
762	n/a	# In case the child hasn't been waited on, check if it's done.
763	n/a	self._internal_poll(_deadstate=_maxsize)
764	n/a	if self.returncode is None and _active is not None:
765	n/a	# Child is still running, keep us alive until we can wait on it.
766	n/a	_active.append(self)
767	n/a
768	n/a	def _get_devnull(self):
769	n/a	if not hasattr(self, '_devnull'):
770	n/a	self._devnull = os.open(os.devnull, os.O_RDWR)
771	n/a	return self._devnull
772	n/a
773	n/a	def _stdin_write(self, input):
774	n/a	if input:
775	n/a	try:
776	n/a	self.stdin.write(input)
777	n/a	except BrokenPipeError:
778	n/a	pass # communicate() must ignore broken pipe errors.
779	n/a	except OSError as e:
780	n/a	if e.errno == errno.EINVAL and self.poll() is not None:
781	n/a	# Issue #19612: On Windows, stdin.write() fails with EINVAL
782	n/a	# if the process already exited before the write
783	n/a	pass
784	n/a	else:
785	n/a	raise
786	n/a	try:
787	n/a	self.stdin.close()
788	n/a	except BrokenPipeError:
789	n/a	pass # communicate() must ignore broken pipe errors.
790	n/a	except OSError as e:
791	n/a	if e.errno == errno.EINVAL and self.poll() is not None:
792	n/a	pass
793	n/a	else:
794	n/a	raise
795	n/a
796	n/a	def communicate(self, input=None, timeout=None):
797	n/a	"""Interact with process: Send data to stdin. Read data from
798	n/a	stdout and stderr, until end-of-file is reached. Wait for
799	n/a	process to terminate.
800	n/a
801	n/a	The optional "input" argument should be data to be sent to the
802	n/a	child process (if self.universal_newlines is True, this should
803	n/a	be a string; if it is False, "input" should be bytes), or
804	n/a	None, if no data should be sent to the child.
805	n/a
806	n/a	communicate() returns a tuple (stdout, stderr). These will be
807	n/a	bytes or, if self.universal_newlines was True, a string.
808	n/a	"""
809	n/a
810	n/a	if self._communication_started and input:
811	n/a	raise ValueError("Cannot send input after starting communication")
812	n/a
813	n/a	# Optimization: If we are not worried about timeouts, we haven't
814	n/a	# started communicating, and we have one or zero pipes, using select()
815	n/a	# or threads is unnecessary.
816	n/a	if (timeout is None and not self._communication_started and
817	n/a	[self.stdin, self.stdout, self.stderr].count(None) >= 2):
818	n/a	stdout = None
819	n/a	stderr = None
820	n/a	if self.stdin:
821	n/a	self._stdin_write(input)
822	n/a	elif self.stdout:
823	n/a	stdout = self.stdout.read()
824	n/a	self.stdout.close()
825	n/a	elif self.stderr:
826	n/a	stderr = self.stderr.read()
827	n/a	self.stderr.close()
828	n/a	self.wait()
829	n/a	else:
830	n/a	if timeout is not None:
831	n/a	endtime = _time() + timeout
832	n/a	else:
833	n/a	endtime = None
834	n/a
835	n/a	try:
836	n/a	stdout, stderr = self._communicate(input, endtime, timeout)
837	n/a	finally:
838	n/a	self._communication_started = True
839	n/a
840	n/a	sts = self.wait(timeout=self._remaining_time(endtime))
841	n/a
842	n/a	return (stdout, stderr)
843	n/a
844	n/a
845	n/a	def poll(self):
846	n/a	"""Check if child process has terminated. Set and return returncode
847	n/a	attribute."""
848	n/a	return self._internal_poll()
849	n/a
850	n/a
851	n/a	def _remaining_time(self, endtime):
852	n/a	"""Convenience for _communicate when computing timeouts."""
853	n/a	if endtime is None:
854	n/a	return None
855	n/a	else:
856	n/a	return endtime - _time()
857	n/a
858	n/a
859	n/a	def _check_timeout(self, endtime, orig_timeout):
860	n/a	"""Convenience for checking if a timeout has expired."""
861	n/a	if endtime is None:
862	n/a	return
863	n/a	if _time() > endtime:
864	n/a	raise TimeoutExpired(self.args, orig_timeout)
865	n/a
866	n/a
867	n/a	if _mswindows:
868	n/a	#
869	n/a	# Windows methods
870	n/a	#
871	n/a	def _get_handles(self, stdin, stdout, stderr):
872	n/a	"""Construct and return tuple with IO objects:
873	n/a	p2cread, p2cwrite, c2pread, c2pwrite, errread, errwrite
874	n/a	"""
875	n/a	if stdin is None and stdout is None and stderr is None:
876	n/a	return (-1, -1, -1, -1, -1, -1)
877	n/a
878	n/a	p2cread, p2cwrite = -1, -1
879	n/a	c2pread, c2pwrite = -1, -1
880	n/a	errread, errwrite = -1, -1
881	n/a
882	n/a	if stdin is None:
883	n/a	p2cread = _winapi.GetStdHandle(_winapi.STD_INPUT_HANDLE)
884	n/a	if p2cread is None:
885	n/a	p2cread, _ = _winapi.CreatePipe(None, 0)
886	n/a	p2cread = Handle(p2cread)
887	n/a	_winapi.CloseHandle(_)
888	n/a	elif stdin == PIPE:
889	n/a	p2cread, p2cwrite = _winapi.CreatePipe(None, 0)
890	n/a	p2cread, p2cwrite = Handle(p2cread), Handle(p2cwrite)
891	n/a	elif stdin == DEVNULL:
892	n/a	p2cread = msvcrt.get_osfhandle(self._get_devnull())
893	n/a	elif isinstance(stdin, int):
894	n/a	p2cread = msvcrt.get_osfhandle(stdin)
895	n/a	else:
896	n/a	# Assuming file-like object
897	n/a	p2cread = msvcrt.get_osfhandle(stdin.fileno())
898	n/a	p2cread = self._make_inheritable(p2cread)
899	n/a
900	n/a	if stdout is None:
901	n/a	c2pwrite = _winapi.GetStdHandle(_winapi.STD_OUTPUT_HANDLE)
902	n/a	if c2pwrite is None:
903	n/a	_, c2pwrite = _winapi.CreatePipe(None, 0)
904	n/a	c2pwrite = Handle(c2pwrite)
905	n/a	_winapi.CloseHandle(_)
906	n/a	elif stdout == PIPE:
907	n/a	c2pread, c2pwrite = _winapi.CreatePipe(None, 0)
908	n/a	c2pread, c2pwrite = Handle(c2pread), Handle(c2pwrite)
909	n/a	elif stdout == DEVNULL:
910	n/a	c2pwrite = msvcrt.get_osfhandle(self._get_devnull())
911	n/a	elif isinstance(stdout, int):
912	n/a	c2pwrite = msvcrt.get_osfhandle(stdout)
913	n/a	else:
914	n/a	# Assuming file-like object
915	n/a	c2pwrite = msvcrt.get_osfhandle(stdout.fileno())
916	n/a	c2pwrite = self._make_inheritable(c2pwrite)
917	n/a
918	n/a	if stderr is None:
919	n/a	errwrite = _winapi.GetStdHandle(_winapi.STD_ERROR_HANDLE)
920	n/a	if errwrite is None:
921	n/a	_, errwrite = _winapi.CreatePipe(None, 0)
922	n/a	errwrite = Handle(errwrite)
923	n/a	_winapi.CloseHandle(_)
924	n/a	elif stderr == PIPE:
925	n/a	errread, errwrite = _winapi.CreatePipe(None, 0)
926	n/a	errread, errwrite = Handle(errread), Handle(errwrite)
927	n/a	elif stderr == STDOUT:
928	n/a	errwrite = c2pwrite
929	n/a	elif stderr == DEVNULL:
930	n/a	errwrite = msvcrt.get_osfhandle(self._get_devnull())
931	n/a	elif isinstance(stderr, int):
932	n/a	errwrite = msvcrt.get_osfhandle(stderr)
933	n/a	else:
934	n/a	# Assuming file-like object
935	n/a	errwrite = msvcrt.get_osfhandle(stderr.fileno())
936	n/a	errwrite = self._make_inheritable(errwrite)
937	n/a
938	n/a	return (p2cread, p2cwrite,
939	n/a	c2pread, c2pwrite,
940	n/a	errread, errwrite)
941	n/a
942	n/a
943	n/a	def _make_inheritable(self, handle):
944	n/a	"""Return a duplicate of handle, which is inheritable"""
945	n/a	h = _winapi.DuplicateHandle(
946	n/a	_winapi.GetCurrentProcess(), handle,
947	n/a	_winapi.GetCurrentProcess(), 0, 1,
948	n/a	_winapi.DUPLICATE_SAME_ACCESS)
949	n/a	return Handle(h)
950	n/a
951	n/a
952	n/a	def _execute_child(self, args, executable, preexec_fn, close_fds,
953	n/a	pass_fds, cwd, env,
954	n/a	startupinfo, creationflags, shell,
955	n/a	p2cread, p2cwrite,
956	n/a	c2pread, c2pwrite,
957	n/a	errread, errwrite,
958	n/a	unused_restore_signals, unused_start_new_session):
959	n/a	"""Execute program (MS Windows version)"""
960	n/a
961	n/a	assert not pass_fds, "pass_fds not supported on Windows."
962	n/a
963	n/a	if not isinstance(args, str):
964	n/a	args = list2cmdline(args)
965	n/a
966	n/a	# Process startup details
967	n/a	if startupinfo is None:
968	n/a	startupinfo = STARTUPINFO()
969	n/a	if -1 not in (p2cread, c2pwrite, errwrite):
970	n/a	startupinfo.dwFlags \|= _winapi.STARTF_USESTDHANDLES
971	n/a	startupinfo.hStdInput = p2cread
972	n/a	startupinfo.hStdOutput = c2pwrite
973	n/a	startupinfo.hStdError = errwrite
974	n/a
975	n/a	if shell:
976	n/a	startupinfo.dwFlags \|= _winapi.STARTF_USESHOWWINDOW
977	n/a	startupinfo.wShowWindow = _winapi.SW_HIDE
978	n/a	comspec = os.environ.get("COMSPEC", "cmd.exe")
979	n/a	args = '{} /c "{}"'.format (comspec, args)
980	n/a
981	n/a	# Start the process
982	n/a	try:
983	n/a	hp, ht, pid, tid = _winapi.CreateProcess(executable, args,
984	n/a	# no special security
985	n/a	None, None,
986	n/a	int(not close_fds),
987	n/a	creationflags,
988	n/a	env,
989	n/a	cwd,
990	n/a	startupinfo)
991	n/a	finally:
992	n/a	# Child is launched. Close the parent's copy of those pipe
993	n/a	# handles that only the child should have open. You need
994	n/a	# to make sure that no handles to the write end of the
995	n/a	# output pipe are maintained in this process or else the
996	n/a	# pipe will not close when the child process exits and the
997	n/a	# ReadFile will hang.
998	n/a	if p2cread != -1:
999	n/a	p2cread.Close()
1000	n/a	if c2pwrite != -1:
1001	n/a	c2pwrite.Close()
1002	n/a	if errwrite != -1:
1003	n/a	errwrite.Close()
1004	n/a	if hasattr(self, '_devnull'):
1005	n/a	os.close(self._devnull)
1006	n/a
1007	n/a	# Retain the process handle, but close the thread handle
1008	n/a	self._child_created = True
1009	n/a	self._handle = Handle(hp)
1010	n/a	self.pid = pid
1011	n/a	_winapi.CloseHandle(ht)
1012	n/a
1013	n/a	def _internal_poll(self, _deadstate=None,
1014	n/a	_WaitForSingleObject=_winapi.WaitForSingleObject,
1015	n/a	_WAIT_OBJECT_0=_winapi.WAIT_OBJECT_0,
1016	n/a	_GetExitCodeProcess=_winapi.GetExitCodeProcess):
1017	n/a	"""Check if child process has terminated. Returns returncode
1018	n/a	attribute.
1019	n/a
1020	n/a	This method is called by __del__, so it can only refer to objects
1021	n/a	in its local scope.
1022	n/a
1023	n/a	"""
1024	n/a	if self.returncode is None:
1025	n/a	if _WaitForSingleObject(self._handle, 0) == _WAIT_OBJECT_0:
1026	n/a	self.returncode = _GetExitCodeProcess(self._handle)
1027	n/a	return self.returncode
1028	n/a
1029	n/a
1030	n/a	def wait(self, timeout=None):
1031	n/a	"""Wait for child process to terminate. Returns returncode
1032	n/a	attribute."""
1033	n/a	if timeout is None:
1034	n/a	timeout_millis = _winapi.INFINITE
1035	n/a	else:
1036	n/a	timeout_millis = int(timeout * 1000)
1037	n/a	if self.returncode is None:
1038	n/a	result = _winapi.WaitForSingleObject(self._handle,
1039	n/a	timeout_millis)
1040	n/a	if result == _winapi.WAIT_TIMEOUT:
1041	n/a	raise TimeoutExpired(self.args, timeout)
1042	n/a	self.returncode = _winapi.GetExitCodeProcess(self._handle)
1043	n/a	return self.returncode
1044	n/a
1045	n/a
1046	n/a	def _readerthread(self, fh, buffer):
1047	n/a	buffer.append(fh.read())
1048	n/a	fh.close()
1049	n/a
1050	n/a
1051	n/a	def _communicate(self, input, endtime, orig_timeout):
1052	n/a	# Start reader threads feeding into a list hanging off of this
1053	n/a	# object, unless they've already been started.
1054	n/a	if self.stdout and not hasattr(self, "_stdout_buff"):
1055	n/a	self._stdout_buff = []
1056	n/a	self.stdout_thread = \
1057	n/a	threading.Thread(target=self._readerthread,
1058	n/a	args=(self.stdout, self._stdout_buff))
1059	n/a	self.stdout_thread.daemon = True
1060	n/a	self.stdout_thread.start()
1061	n/a	if self.stderr and not hasattr(self, "_stderr_buff"):
1062	n/a	self._stderr_buff = []
1063	n/a	self.stderr_thread = \
1064	n/a	threading.Thread(target=self._readerthread,
1065	n/a	args=(self.stderr, self._stderr_buff))
1066	n/a	self.stderr_thread.daemon = True
1067	n/a	self.stderr_thread.start()
1068	n/a
1069	n/a	if self.stdin:
1070	n/a	self._stdin_write(input)
1071	n/a
1072	n/a	# Wait for the reader threads, or time out. If we time out, the
1073	n/a	# threads remain reading and the fds left open in case the user
1074	n/a	# calls communicate again.
1075	n/a	if self.stdout is not None:
1076	n/a	self.stdout_thread.join(self._remaining_time(endtime))
1077	n/a	if self.stdout_thread.is_alive():
1078	n/a	raise TimeoutExpired(self.args, orig_timeout)
1079	n/a	if self.stderr is not None:
1080	n/a	self.stderr_thread.join(self._remaining_time(endtime))
1081	n/a	if self.stderr_thread.is_alive():
1082	n/a	raise TimeoutExpired(self.args, orig_timeout)
1083	n/a
1084	n/a	# Collect the output from and close both pipes, now that we know
1085	n/a	# both have been read successfully.
1086	n/a	stdout = None
1087	n/a	stderr = None
1088	n/a	if self.stdout:
1089	n/a	stdout = self._stdout_buff
1090	n/a	self.stdout.close()
1091	n/a	if self.stderr:
1092	n/a	stderr = self._stderr_buff
1093	n/a	self.stderr.close()
1094	n/a
1095	n/a	# All data exchanged. Translate lists into strings.
1096	n/a	if stdout is not None:
1097	n/a	stdout = stdout[0]
1098	n/a	if stderr is not None:
1099	n/a	stderr = stderr[0]
1100	n/a
1101	n/a	return (stdout, stderr)
1102	n/a
1103	n/a	def send_signal(self, sig):
1104	n/a	"""Send a signal to the process."""
1105	n/a	# Don't signal a process that we know has already died.
1106	n/a	if self.returncode is not None:
1107	n/a	return
1108	n/a	if sig == signal.SIGTERM:
1109	n/a	self.terminate()
1110	n/a	elif sig == signal.CTRL_C_EVENT:
1111	n/a	os.kill(self.pid, signal.CTRL_C_EVENT)
1112	n/a	elif sig == signal.CTRL_BREAK_EVENT:
1113	n/a	os.kill(self.pid, signal.CTRL_BREAK_EVENT)
1114	n/a	else:
1115	n/a	raise ValueError("Unsupported signal: {}".format(sig))
1116	n/a
1117	n/a	def terminate(self):
1118	n/a	"""Terminates the process."""
1119	n/a	# Don't terminate a process that we know has already died.
1120	n/a	if self.returncode is not None:
1121	n/a	return
1122	n/a	try:
1123	n/a	_winapi.TerminateProcess(self._handle, 1)
1124	n/a	except PermissionError:
1125	n/a	# ERROR_ACCESS_DENIED (winerror 5) is received when the
1126	n/a	# process already died.
1127	n/a	rc = _winapi.GetExitCodeProcess(self._handle)
1128	n/a	if rc == _winapi.STILL_ACTIVE:
1129	n/a	raise
1130	n/a	self.returncode = rc
1131	n/a
1132	n/a	kill = terminate
1133	n/a
1134	n/a	else:
1135	n/a	#
1136	n/a	# POSIX methods
1137	n/a	#
1138	n/a	def _get_handles(self, stdin, stdout, stderr):
1139	n/a	"""Construct and return tuple with IO objects:
1140	n/a	p2cread, p2cwrite, c2pread, c2pwrite, errread, errwrite
1141	n/a	"""
1142	n/a	p2cread, p2cwrite = -1, -1
1143	n/a	c2pread, c2pwrite = -1, -1
1144	n/a	errread, errwrite = -1, -1
1145	n/a
1146	n/a	if stdin is None:
1147	n/a	pass
1148	n/a	elif stdin == PIPE:
1149	n/a	p2cread, p2cwrite = os.pipe()
1150	n/a	elif stdin == DEVNULL:
1151	n/a	p2cread = self._get_devnull()
1152	n/a	elif isinstance(stdin, int):
1153	n/a	p2cread = stdin
1154	n/a	else:
1155	n/a	# Assuming file-like object
1156	n/a	p2cread = stdin.fileno()
1157	n/a
1158	n/a	if stdout is None:
1159	n/a	pass
1160	n/a	elif stdout == PIPE:
1161	n/a	c2pread, c2pwrite = os.pipe()
1162	n/a	elif stdout == DEVNULL:
1163	n/a	c2pwrite = self._get_devnull()
1164	n/a	elif isinstance(stdout, int):
1165	n/a	c2pwrite = stdout
1166	n/a	else:
1167	n/a	# Assuming file-like object
1168	n/a	c2pwrite = stdout.fileno()
1169	n/a
1170	n/a	if stderr is None:
1171	n/a	pass
1172	n/a	elif stderr == PIPE:
1173	n/a	errread, errwrite = os.pipe()
1174	n/a	elif stderr == STDOUT:
1175	n/a	if c2pwrite != -1:
1176	n/a	errwrite = c2pwrite
1177	n/a	else: # child's stdout is not set, use parent's stdout
1178	n/a	errwrite = sys.__stdout__.fileno()
1179	n/a	elif stderr == DEVNULL:
1180	n/a	errwrite = self._get_devnull()
1181	n/a	elif isinstance(stderr, int):
1182	n/a	errwrite = stderr
1183	n/a	else:
1184	n/a	# Assuming file-like object
1185	n/a	errwrite = stderr.fileno()
1186	n/a
1187	n/a	return (p2cread, p2cwrite,
1188	n/a	c2pread, c2pwrite,
1189	n/a	errread, errwrite)
1190	n/a
1191	n/a
1192	n/a	def _execute_child(self, args, executable, preexec_fn, close_fds,
1193	n/a	pass_fds, cwd, env,
1194	n/a	startupinfo, creationflags, shell,
1195	n/a	p2cread, p2cwrite,
1196	n/a	c2pread, c2pwrite,
1197	n/a	errread, errwrite,
1198	n/a	restore_signals, start_new_session):
1199	n/a	"""Execute program (POSIX version)"""
1200	n/a
1201	n/a	if isinstance(args, (str, bytes)):
1202	n/a	args = [args]
1203	n/a	else:
1204	n/a	args = list(args)
1205	n/a
1206	n/a	if shell:
1207	n/a	# On Android the default shell is at '/system/bin/sh'.
1208	n/a	unix_shell = ('/system/bin/sh' if
1209	n/a	hasattr(sys, 'getandroidapilevel') else '/bin/sh')
1210	n/a	args = [unix_shell, "-c"] + args
1211	n/a	if executable:
1212	n/a	args[0] = executable
1213	n/a
1214	n/a	if executable is None:
1215	n/a	executable = args[0]
1216	n/a	orig_executable = executable
1217	n/a
1218	n/a	# For transferring possible exec failure from child to parent.
1219	n/a	# Data format: "exception name:hex errno:description"
1220	n/a	# Pickle is not used; it is complex and involves memory allocation.
1221	n/a	errpipe_read, errpipe_write = os.pipe()
1222	n/a	# errpipe_write must not be in the standard io 0, 1, or 2 fd range.
1223	n/a	low_fds_to_close = []
1224	n/a	while errpipe_write < 3:
1225	n/a	low_fds_to_close.append(errpipe_write)
1226	n/a	errpipe_write = os.dup(errpipe_write)
1227	n/a	for low_fd in low_fds_to_close:
1228	n/a	os.close(low_fd)
1229	n/a	try:
1230	n/a	try:
1231	n/a	# We must avoid complex work that could involve
1232	n/a	# malloc or free in the child process to avoid
1233	n/a	# potential deadlocks, thus we do all this here.
1234	n/a	# and pass it to fork_exec()
1235	n/a
1236	n/a	if env is not None:
1237	n/a	env_list = [os.fsencode(k) + b'=' + os.fsencode(v)
1238	n/a	for k, v in env.items()]
1239	n/a	else:
1240	n/a	env_list = None # Use execv instead of execve.
1241	n/a	executable = os.fsencode(executable)
1242	n/a	if os.path.dirname(executable):
1243	n/a	executable_list = (executable,)
1244	n/a	else:
1245	n/a	# This matches the behavior of os._execvpe().
1246	n/a	executable_list = tuple(
1247	n/a	os.path.join(os.fsencode(dir), executable)
1248	n/a	for dir in os.get_exec_path(env))
1249	n/a	fds_to_keep = set(pass_fds)
1250	n/a	fds_to_keep.add(errpipe_write)
1251	n/a	self.pid = _posixsubprocess.fork_exec(
1252	n/a	args, executable_list,
1253	n/a	close_fds, sorted(fds_to_keep), cwd, env_list,
1254	n/a	p2cread, p2cwrite, c2pread, c2pwrite,
1255	n/a	errread, errwrite,
1256	n/a	errpipe_read, errpipe_write,
1257	n/a	restore_signals, start_new_session, preexec_fn)
1258	n/a	self._child_created = True
1259	n/a	finally:
1260	n/a	# be sure the FD is closed no matter what
1261	n/a	os.close(errpipe_write)
1262	n/a
1263	n/a	# self._devnull is not always defined.
1264	n/a	devnull_fd = getattr(self, '_devnull', None)
1265	n/a	if p2cread != -1 and p2cwrite != -1 and p2cread != devnull_fd:
1266	n/a	os.close(p2cread)
1267	n/a	if c2pwrite != -1 and c2pread != -1 and c2pwrite != devnull_fd:
1268	n/a	os.close(c2pwrite)
1269	n/a	if errwrite != -1 and errread != -1 and errwrite != devnull_fd:
1270	n/a	os.close(errwrite)
1271	n/a	if devnull_fd is not None:
1272	n/a	os.close(devnull_fd)
1273	n/a	# Prevent a double close of these fds from __init__ on error.
1274	n/a	self._closed_child_pipe_fds = True
1275	n/a
1276	n/a	# Wait for exec to fail or succeed; possibly raising an
1277	n/a	# exception (limited in size)
1278	n/a	errpipe_data = bytearray()
1279	n/a	while True:
1280	n/a	part = os.read(errpipe_read, 50000)
1281	n/a	errpipe_data += part
1282	n/a	if not part or len(errpipe_data) > 50000:
1283	n/a	break
1284	n/a	finally:
1285	n/a	# be sure the FD is closed no matter what
1286	n/a	os.close(errpipe_read)
1287	n/a
1288	n/a	if errpipe_data:
1289	n/a	try:
1290	n/a	pid, sts = os.waitpid(self.pid, 0)
1291	n/a	if pid == self.pid:
1292	n/a	self._handle_exitstatus(sts)
1293	n/a	else:
1294	n/a	self.returncode = sys.maxsize
1295	n/a	except ChildProcessError:
1296	n/a	pass
1297	n/a
1298	n/a	try:
1299	n/a	exception_name, hex_errno, err_msg = (
1300	n/a	errpipe_data.split(b':', 2))
1301	n/a	except ValueError:
1302	n/a	exception_name = b'SubprocessError'
1303	n/a	hex_errno = b'0'
1304	n/a	err_msg = (b'Bad exception data from child: ' +
1305	n/a	repr(errpipe_data))
1306	n/a	child_exception_type = getattr(
1307	n/a	builtins, exception_name.decode('ascii'),
1308	n/a	SubprocessError)
1309	n/a	err_msg = err_msg.decode(errors="surrogatepass")
1310	n/a	if issubclass(child_exception_type, OSError) and hex_errno:
1311	n/a	errno_num = int(hex_errno, 16)
1312	n/a	child_exec_never_called = (err_msg == "noexec")
1313	n/a	if child_exec_never_called:
1314	n/a	err_msg = ""
1315	n/a	if errno_num != 0:
1316	n/a	err_msg = os.strerror(errno_num)
1317	n/a	if errno_num == errno.ENOENT:
1318	n/a	if child_exec_never_called:
1319	n/a	# The error must be from chdir(cwd).
1320	n/a	err_msg += ': ' + repr(cwd)
1321	n/a	else:
1322	n/a	err_msg += ': ' + repr(orig_executable)
1323	n/a	raise child_exception_type(errno_num, err_msg)
1324	n/a	raise child_exception_type(err_msg)
1325	n/a
1326	n/a
1327	n/a	def _handle_exitstatus(self, sts, _WIFSIGNALED=os.WIFSIGNALED,
1328	n/a	_WTERMSIG=os.WTERMSIG, _WIFEXITED=os.WIFEXITED,
1329	n/a	_WEXITSTATUS=os.WEXITSTATUS, _WIFSTOPPED=os.WIFSTOPPED,
1330	n/a	_WSTOPSIG=os.WSTOPSIG):
1331	n/a	"""All callers to this function MUST hold self._waitpid_lock."""
1332	n/a	# This method is called (indirectly) by __del__, so it cannot
1333	n/a	# refer to anything outside of its local scope.
1334	n/a	if _WIFSIGNALED(sts):
1335	n/a	self.returncode = -_WTERMSIG(sts)
1336	n/a	elif _WIFEXITED(sts):
1337	n/a	self.returncode = _WEXITSTATUS(sts)
1338	n/a	elif _WIFSTOPPED(sts):
1339	n/a	self.returncode = -_WSTOPSIG(sts)
1340	n/a	else:
1341	n/a	# Should never happen
1342	n/a	raise SubprocessError("Unknown child exit status!")
1343	n/a
1344	n/a
1345	n/a	def _internal_poll(self, _deadstate=None, _waitpid=os.waitpid,
1346	n/a	_WNOHANG=os.WNOHANG, _ECHILD=errno.ECHILD):
1347	n/a	"""Check if child process has terminated. Returns returncode
1348	n/a	attribute.
1349	n/a
1350	n/a	This method is called by __del__, so it cannot reference anything
1351	n/a	outside of the local scope (nor can any methods it calls).
1352	n/a
1353	n/a	"""
1354	n/a	if self.returncode is None:
1355	n/a	if not self._waitpid_lock.acquire(False):
1356	n/a	# Something else is busy calling waitpid. Don't allow two
1357	n/a	# at once. We know nothing yet.
1358	n/a	return None
1359	n/a	try:
1360	n/a	if self.returncode is not None:
1361	n/a	return self.returncode # Another thread waited.
1362	n/a	pid, sts = _waitpid(self.pid, _WNOHANG)
1363	n/a	if pid == self.pid:
1364	n/a	self._handle_exitstatus(sts)
1365	n/a	except OSError as e:
1366	n/a	if _deadstate is not None:
1367	n/a	self.returncode = _deadstate
1368	n/a	elif e.errno == _ECHILD:
1369	n/a	# This happens if SIGCLD is set to be ignored or
1370	n/a	# waiting for child processes has otherwise been
1371	n/a	# disabled for our process. This child is dead, we
1372	n/a	# can't get the status.
1373	n/a	# http://bugs.python.org/issue15756
1374	n/a	self.returncode = 0
1375	n/a	finally:
1376	n/a	self._waitpid_lock.release()
1377	n/a	return self.returncode
1378	n/a
1379	n/a
1380	n/a	def _try_wait(self, wait_flags):
1381	n/a	"""All callers to this function MUST hold self._waitpid_lock."""
1382	n/a	try:
1383	n/a	(pid, sts) = os.waitpid(self.pid, wait_flags)
1384	n/a	except ChildProcessError:
1385	n/a	# This happens if SIGCLD is set to be ignored or waiting
1386	n/a	# for child processes has otherwise been disabled for our
1387	n/a	# process. This child is dead, we can't get the status.
1388	n/a	pid = self.pid
1389	n/a	sts = 0
1390	n/a	return (pid, sts)
1391	n/a
1392	n/a
1393	n/a	def wait(self, timeout=None):
1394	n/a	"""Wait for child process to terminate. Returns returncode
1395	n/a	attribute."""
1396	n/a	if self.returncode is not None:
1397	n/a	return self.returncode
1398	n/a
1399	n/a	if timeout is not None:
1400	n/a	endtime = _time() + timeout
1401	n/a	# Enter a busy loop if we have a timeout. This busy loop was
1402	n/a	# cribbed from Lib/threading.py in Thread.wait() at r71065.
1403	n/a	delay = 0.0005 # 500 us -> initial delay of 1 ms
1404	n/a	while True:
1405	n/a	if self._waitpid_lock.acquire(False):
1406	n/a	try:
1407	n/a	if self.returncode is not None:
1408	n/a	break # Another thread waited.
1409	n/a	(pid, sts) = self._try_wait(os.WNOHANG)
1410	n/a	assert pid == self.pid or pid == 0
1411	n/a	if pid == self.pid:
1412	n/a	self._handle_exitstatus(sts)
1413	n/a	break
1414	n/a	finally:
1415	n/a	self._waitpid_lock.release()
1416	n/a	remaining = self._remaining_time(endtime)
1417	n/a	if remaining <= 0:
1418	n/a	raise TimeoutExpired(self.args, timeout)
1419	n/a	delay = min(delay * 2, remaining, .05)
1420	n/a	time.sleep(delay)
1421	n/a	else:
1422	n/a	while self.returncode is None:
1423	n/a	with self._waitpid_lock:
1424	n/a	if self.returncode is not None:
1425	n/a	break # Another thread waited.
1426	n/a	(pid, sts) = self._try_wait(0)
1427	n/a	# Check the pid and loop as waitpid has been known to
1428	n/a	# return 0 even without WNOHANG in odd situations.
1429	n/a	# http://bugs.python.org/issue14396.
1430	n/a	if pid == self.pid:
1431	n/a	self._handle_exitstatus(sts)
1432	n/a	return self.returncode
1433	n/a
1434	n/a
1435	n/a	def _communicate(self, input, endtime, orig_timeout):
1436	n/a	if self.stdin and not self._communication_started:
1437	n/a	# Flush stdio buffer. This might block, if the user has
1438	n/a	# been writing to .stdin in an uncontrolled fashion.
1439	n/a	try:
1440	n/a	self.stdin.flush()
1441	n/a	except BrokenPipeError:
1442	n/a	pass # communicate() must ignore BrokenPipeError.
1443	n/a	if not input:
1444	n/a	try:
1445	n/a	self.stdin.close()
1446	n/a	except BrokenPipeError:
1447	n/a	pass # communicate() must ignore BrokenPipeError.
1448	n/a
1449	n/a	stdout = None
1450	n/a	stderr = None
1451	n/a
1452	n/a	# Only create this mapping if we haven't already.
1453	n/a	if not self._communication_started:
1454	n/a	self._fileobj2output = {}
1455	n/a	if self.stdout:
1456	n/a	self._fileobj2output[self.stdout] = []
1457	n/a	if self.stderr:
1458	n/a	self._fileobj2output[self.stderr] = []
1459	n/a
1460	n/a	if self.stdout:
1461	n/a	stdout = self._fileobj2output[self.stdout]
1462	n/a	if self.stderr:
1463	n/a	stderr = self._fileobj2output[self.stderr]
1464	n/a
1465	n/a	self._save_input(input)
1466	n/a
1467	n/a	if self._input:
1468	n/a	input_view = memoryview(self._input)
1469	n/a
1470	n/a	with _PopenSelector() as selector:
1471	n/a	if self.stdin and input:
1472	n/a	selector.register(self.stdin, selectors.EVENT_WRITE)
1473	n/a	if self.stdout:
1474	n/a	selector.register(self.stdout, selectors.EVENT_READ)
1475	n/a	if self.stderr:
1476	n/a	selector.register(self.stderr, selectors.EVENT_READ)
1477	n/a
1478	n/a	while selector.get_map():
1479	n/a	timeout = self._remaining_time(endtime)
1480	n/a	if timeout is not None and timeout < 0:
1481	n/a	raise TimeoutExpired(self.args, orig_timeout)
1482	n/a
1483	n/a	ready = selector.select(timeout)
1484	n/a	self._check_timeout(endtime, orig_timeout)
1485	n/a
1486	n/a	# XXX Rewrite these to use non-blocking I/O on the file
1487	n/a	# objects; they are no longer using C stdio!
1488	n/a
1489	n/a	for key, events in ready:
1490	n/a	if key.fileobj is self.stdin:
1491	n/a	chunk = input_view[self._input_offset :
1492	n/a	self._input_offset + _PIPE_BUF]
1493	n/a	try:
1494	n/a	self._input_offset += os.write(key.fd, chunk)
1495	n/a	except BrokenPipeError:
1496	n/a	selector.unregister(key.fileobj)
1497	n/a	key.fileobj.close()
1498	n/a	else:
1499	n/a	if self._input_offset >= len(self._input):
1500	n/a	selector.unregister(key.fileobj)
1501	n/a	key.fileobj.close()
1502	n/a	elif key.fileobj in (self.stdout, self.stderr):
1503	n/a	data = os.read(key.fd, 32768)
1504	n/a	if not data:
1505	n/a	selector.unregister(key.fileobj)
1506	n/a	key.fileobj.close()
1507	n/a	self._fileobj2output[key.fileobj].append(data)
1508	n/a
1509	n/a	self.wait(timeout=self._remaining_time(endtime))
1510	n/a
1511	n/a	# All data exchanged. Translate lists into strings.
1512	n/a	if stdout is not None:
1513	n/a	stdout = b''.join(stdout)
1514	n/a	if stderr is not None:
1515	n/a	stderr = b''.join(stderr)
1516	n/a
1517	n/a	# Translate newlines, if requested.
1518	n/a	# This also turns bytes into strings.
1519	n/a	if self.encoding or self.errors or self.universal_newlines:
1520	n/a	if stdout is not None:
1521	n/a	stdout = self._translate_newlines(stdout,
1522	n/a	self.stdout.encoding,
1523	n/a	self.stdout.errors)
1524	n/a	if stderr is not None:
1525	n/a	stderr = self._translate_newlines(stderr,
1526	n/a	self.stderr.encoding,
1527	n/a	self.stderr.errors)
1528	n/a
1529	n/a	return (stdout, stderr)
1530	n/a
1531	n/a
1532	n/a	def _save_input(self, input):
1533	n/a	# This method is called from the _communicate_with_*() methods
1534	n/a	# so that if we time out while communicating, we can continue
1535	n/a	# sending input if we retry.
1536	n/a	if self.stdin and self._input is None:
1537	n/a	self._input_offset = 0
1538	n/a	self._input = input
1539	n/a	if input is not None and (
1540	n/a	self.encoding or self.errors or self.universal_newlines):
1541	n/a	self._input = self._input.encode(self.stdin.encoding,
1542	n/a	self.stdin.errors)
1543	n/a
1544	n/a
1545	n/a	def send_signal(self, sig):
1546	n/a	"""Send a signal to the process."""
1547	n/a	# Skip signalling a process that we know has already died.
1548	n/a	if self.returncode is None:
1549	n/a	os.kill(self.pid, sig)
1550	n/a
1551	n/a	def terminate(self):
1552	n/a	"""Terminate the process with SIGTERM
1553	n/a	"""
1554	n/a	self.send_signal(signal.SIGTERM)
1555	n/a
1556	n/a	def kill(self):
1557	n/a	"""Kill the process with SIGKILL
1558	n/a	"""
1559	n/a	self.send_signal(signal.SIGKILL)