1 # subprocess - Subprocesses with accessible I/O streams
3 # For more information about this module, see PEP 324.
5 # This module should remain compatible with Python 2.2, see PEP 291.
7 # Copyright (c) 2003-2005 by Peter Astrand <astrand@lysator.liu.se>
9 # Licensed to PSF under a Contributor Agreement.
10 # See http://www.python.org/2.4/license for licensing details.
12 r
"""subprocess - Subprocesses with accessible I/O streams
14 This module allows you to spawn processes, connect to their
15 input/output/error pipes, and obtain their return codes. This module
16 intends to replace several other, older modules and functions, like:
24 Information about how the subprocess module can be used to replace these
25 modules and functions can be found below.
29 Using the subprocess module
30 ===========================
31 This module defines one class called Popen:
33 class Popen(args, bufsize=0, executable=None,
34 stdin=None, stdout=None, stderr=None,
35 preexec_fn=None, close_fds=False, shell=False,
36 cwd=None, env=None, universal_newlines=False,
37 startupinfo=None, creationflags=0):
42 args should be a string, or a sequence of program arguments. The
43 program to execute is normally the first item in the args sequence or
44 string, but can be explicitly set by using the executable argument.
46 On UNIX, with shell=False (default): In this case, the Popen class
47 uses os.execvp() to execute the child program. args should normally
48 be a sequence. A string will be treated as a sequence with the string
49 as the only item (the program to execute).
51 On UNIX, with shell=True: If args is a string, it specifies the
52 command string to execute through the shell. If args is a sequence,
53 the first item specifies the command string, and any additional items
54 will be treated as additional shell arguments.
56 On Windows: the Popen class uses CreateProcess() to execute the child
57 program, which operates on strings. If args is a sequence, it will be
58 converted to a string using the list2cmdline method. Please note that
59 not all MS Windows applications interpret the command line the same
60 way: The list2cmdline is designed for applications using the same
61 rules as the MS C runtime.
63 bufsize, if given, has the same meaning as the corresponding argument
64 to the built-in open() function: 0 means unbuffered, 1 means line
65 buffered, any other positive value means use a buffer of
66 (approximately) that size. A negative bufsize means to use the system
67 default, which usually means fully buffered. The default value for
68 bufsize is 0 (unbuffered).
70 stdin, stdout and stderr specify the executed programs' standard
71 input, standard output and standard error file handles, respectively.
72 Valid values are PIPE, an existing file descriptor (a positive
73 integer), an existing file object, and None. PIPE indicates that a
74 new pipe to the child should be created. With None, no redirection
75 will occur; the child's file handles will be inherited from the
76 parent. Additionally, stderr can be STDOUT, which indicates that the
77 stderr data from the applications should be captured into the same
78 file handle as for stdout.
80 If preexec_fn is set to a callable object, this object will be called
81 in the child process just before the child is executed.
83 If close_fds is true, all file descriptors except 0, 1 and 2 will be
84 closed before the child process is executed.
86 if shell is true, the specified command will be executed through the
89 If cwd is not None, the current directory will be changed to cwd
90 before the child is executed.
92 If env is not None, it defines the environment variables for the new
95 If universal_newlines is true, the file objects stdout and stderr are
96 opened as a text files, but lines may be terminated by any of '\n',
97 the Unix end-of-line convention, '\r', the Macintosh convention or
98 '\r\n', the Windows convention. All of these external representations
99 are seen as '\n' by the Python program. Note: This feature is only
100 available if Python is built with universal newline support (the
101 default). Also, the newlines attribute of the file objects stdout,
102 stdin and stderr are not updated by the communicate() method.
104 The startupinfo and creationflags, if given, will be passed to the
105 underlying CreateProcess() function. They can specify things such as
106 appearance of the main window and priority for the new process.
110 This module also defines some shortcut functions:
112 call(*popenargs, **kwargs):
113 Run command with arguments. Wait for command to complete, then
114 return the returncode attribute.
116 The arguments are the same as for the Popen constructor. Example:
118 retcode = call(["ls", "-l"])
120 check_call(*popenargs, **kwargs):
121 Run command with arguments. Wait for command to complete. If the
122 exit code was zero then return, otherwise raise
123 CalledProcessError. The CalledProcessError object will have the
124 return code in the returncode attribute.
126 The arguments are the same as for the Popen constructor. Example:
128 check_call(["ls", "-l"])
130 check_output(*popenargs, **kwargs):
131 Run command with arguments and return its output as a byte string.
133 If the exit code was non-zero it raises a CalledProcessError. The
134 CalledProcessError object will have the return code in the returncode
135 attribute and output in the output attribute.
137 The arguments are the same as for the Popen constructor. Example:
139 output = subprocess.check_output(["ls", "-l", "/dev/null"])
143 Exceptions raised in the child process, before the new program has
144 started to execute, will be re-raised in the parent. Additionally,
145 the exception object will have one extra attribute called
146 'child_traceback', which is a string containing traceback information
147 from the childs point of view.
149 The most common exception raised is OSError. This occurs, for
150 example, when trying to execute a non-existent file. Applications
151 should prepare for OSErrors.
153 A ValueError will be raised if Popen is called with invalid arguments.
155 check_call() and check_output() will raise CalledProcessError, if the
156 called process returns a non-zero return code.
161 Unlike some other popen functions, this implementation will never call
162 /bin/sh implicitly. This means that all characters, including shell
163 metacharacters, can safely be passed to child processes.
168 Instances of the Popen class have the following methods:
171 Check if child process has terminated. Returns returncode
175 Wait for child process to terminate. Returns returncode attribute.
177 communicate(input=None)
178 Interact with process: Send data to stdin. Read data from stdout
179 and stderr, until end-of-file is reached. Wait for process to
180 terminate. The optional input argument should be a string to be
181 sent to the child process, or None, if no data should be sent to
184 communicate() returns a tuple (stdout, stderr).
186 Note: The data read is buffered in memory, so do not use this
187 method if the data size is large or unlimited.
189 The following attributes are also available:
192 If the stdin argument is PIPE, this attribute is a file object
193 that provides input to the child process. Otherwise, it is None.
196 If the stdout argument is PIPE, this attribute is a file object
197 that provides output from the child process. Otherwise, it is
201 If the stderr argument is PIPE, this attribute is file object that
202 provides error output from the child process. Otherwise, it is
206 The process ID of the child process.
209 The child return code. A None value indicates that the process
210 hasn't terminated yet. A negative value -N indicates that the
211 child was terminated by signal N (UNIX only).
214 Replacing older functions with the subprocess module
215 ====================================================
216 In this section, "a ==> b" means that b can be used as a replacement
219 Note: All functions in this section fail (more or less) silently if
220 the executed program cannot be found; this module raises an OSError
223 In the following examples, we assume that the subprocess module is
224 imported with "from subprocess import *".
227 Replacing /bin/sh shell backquote
228 ---------------------------------
231 output = Popen(["mycmd", "myarg"], stdout=PIPE).communicate()[0]
234 Replacing shell pipe line
235 -------------------------
236 output=`dmesg | grep hda`
238 p1 = Popen(["dmesg"], stdout=PIPE)
239 p2 = Popen(["grep", "hda"], stdin=p1.stdout, stdout=PIPE)
240 output = p2.communicate()[0]
243 Replacing os.system()
244 ---------------------
245 sts = os.system("mycmd" + " myarg")
247 p = Popen("mycmd" + " myarg", shell=True)
248 pid, sts = os.waitpid(p.pid, 0)
252 * Calling the program through the shell is usually not required.
254 * It's easier to look at the returncode attribute than the
257 A more real-world example would look like this:
260 retcode = call("mycmd" + " myarg", shell=True)
262 print >>sys.stderr, "Child was terminated by signal", -retcode
264 print >>sys.stderr, "Child returned", retcode
266 print >>sys.stderr, "Execution failed:", e
273 pid = os.spawnlp(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg")
275 pid = Popen(["/bin/mycmd", "myarg"]).pid
280 retcode = os.spawnlp(os.P_WAIT, "/bin/mycmd", "mycmd", "myarg")
282 retcode = call(["/bin/mycmd", "myarg"])
287 os.spawnvp(os.P_NOWAIT, path, args)
289 Popen([path] + args[1:])
294 os.spawnlpe(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg", env)
296 Popen(["/bin/mycmd", "myarg"], env={"PATH": "/usr/bin"})
301 pipe = os.popen("cmd", mode='r', bufsize)
303 pipe = Popen("cmd", shell=True, bufsize=bufsize, stdout=PIPE).stdout
305 pipe = os.popen("cmd", mode='w', bufsize)
307 pipe = Popen("cmd", shell=True, bufsize=bufsize, stdin=PIPE).stdin
310 (child_stdin, child_stdout) = os.popen2("cmd", mode, bufsize)
312 p = Popen("cmd", shell=True, bufsize=bufsize,
313 stdin=PIPE, stdout=PIPE, close_fds=True)
314 (child_stdin, child_stdout) = (p.stdin, p.stdout)
319 child_stderr) = os.popen3("cmd", mode, bufsize)
321 p = Popen("cmd", shell=True, bufsize=bufsize,
322 stdin=PIPE, stdout=PIPE, stderr=PIPE, close_fds=True)
325 child_stderr) = (p.stdin, p.stdout, p.stderr)
328 (child_stdin, child_stdout_and_stderr) = os.popen4("cmd", mode,
331 p = Popen("cmd", shell=True, bufsize=bufsize,
332 stdin=PIPE, stdout=PIPE, stderr=STDOUT, close_fds=True)
333 (child_stdin, child_stdout_and_stderr) = (p.stdin, p.stdout)
335 On Unix, os.popen2, os.popen3 and os.popen4 also accept a sequence as
336 the command to execute, in which case arguments will be passed
337 directly to the program without shell intervention. This usage can be
340 (child_stdin, child_stdout) = os.popen2(["/bin/ls", "-l"], mode,
343 p = Popen(["/bin/ls", "-l"], bufsize=bufsize, stdin=PIPE, stdout=PIPE)
344 (child_stdin, child_stdout) = (p.stdin, p.stdout)
346 Return code handling translates as follows:
348 pipe = os.popen("cmd", 'w')
351 if rc != None and rc % 256:
352 print "There were some errors"
354 process = Popen("cmd", 'w', shell=True, stdin=PIPE)
356 process.stdin.close()
357 if process.wait() != 0:
358 print "There were some errors"
363 (child_stdout, child_stdin) = popen2.popen2("somestring", bufsize, mode)
365 p = Popen(["somestring"], shell=True, bufsize=bufsize
366 stdin=PIPE, stdout=PIPE, close_fds=True)
367 (child_stdout, child_stdin) = (p.stdout, p.stdin)
369 On Unix, popen2 also accepts a sequence as the command to execute, in
370 which case arguments will be passed directly to the program without
371 shell intervention. This usage can be replaced as follows:
373 (child_stdout, child_stdin) = popen2.popen2(["mycmd", "myarg"], bufsize,
376 p = Popen(["mycmd", "myarg"], bufsize=bufsize,
377 stdin=PIPE, stdout=PIPE, close_fds=True)
378 (child_stdout, child_stdin) = (p.stdout, p.stdin)
380 The popen2.Popen3 and popen2.Popen4 basically works as subprocess.Popen,
383 * subprocess.Popen raises an exception if the execution fails
384 * the capturestderr argument is replaced with the stderr argument.
385 * stdin=PIPE and stdout=PIPE must be specified.
386 * popen2 closes all filedescriptors by default, but you have to specify
387 close_fds=True with subprocess.Popen.
391 mswindows
= (sys
.platform
== "win32")
399 # Exception classes used by this module.
400 class CalledProcessError(Exception):
401 """This exception is raised when a process run by check_call() or
402 check_output() returns a non-zero exit status.
403 The exit status will be stored in the returncode attribute;
404 check_output() will also store the output in the output attribute.
406 def __init__(self
, returncode
, cmd
, output
=None):
407 self
.returncode
= returncode
411 return "Command '%s' returned non-zero exit status %d" % (self
.cmd
, self
.returncode
)
417 if 0: # <-- change this to use pywin32 instead of the _subprocess driver
419 from win32api
import GetStdHandle
, STD_INPUT_HANDLE
, \
420 STD_OUTPUT_HANDLE
, STD_ERROR_HANDLE
421 from win32api
import GetCurrentProcess
, DuplicateHandle
, \
422 GetModuleFileName
, GetVersion
423 from win32con
import DUPLICATE_SAME_ACCESS
, SW_HIDE
424 from win32pipe
import CreatePipe
425 from win32process
import CreateProcess
, STARTUPINFO
, \
426 GetExitCodeProcess
, STARTF_USESTDHANDLES
, \
427 STARTF_USESHOWWINDOW
, CREATE_NEW_CONSOLE
428 from win32process
import TerminateProcess
429 from win32event
import WaitForSingleObject
, INFINITE
, WAIT_OBJECT_0
431 from _subprocess
import *
442 _has_poll
= hasattr(select
, 'poll')
447 # When select or poll has indicated that the file is writable,
448 # we can write up to _PIPE_BUF bytes without risk of blocking.
449 # POSIX defines PIPE_BUF as >= 512.
450 _PIPE_BUF
= getattr(select
, 'PIPE_BUF', 512)
453 __all__
= ["Popen", "PIPE", "STDOUT", "call", "check_call",
454 "check_output", "CalledProcessError"]
457 MAXFD
= os
.sysconf("SC_OPEN_MAX")
464 for inst
in _active
[:]:
465 if inst
._internal
_poll
(_deadstate
=sys
.maxint
) >= 0:
469 # This can happen if two threads create a new Popen instance.
470 # It's harmless that it was already removed, so ignore.
477 def call(*popenargs
, **kwargs
):
478 """Run command with arguments. Wait for command to complete, then
479 return the returncode attribute.
481 The arguments are the same as for the Popen constructor. Example:
483 retcode = call(["ls", "-l"])
485 return Popen(*popenargs
, **kwargs
).wait()
488 def check_call(*popenargs
, **kwargs
):
489 """Run command with arguments. Wait for command to complete. If
490 the exit code was zero then return, otherwise raise
491 CalledProcessError. The CalledProcessError object will have the
492 return code in the returncode attribute.
494 The arguments are the same as for the Popen constructor. Example:
496 check_call(["ls", "-l"])
498 retcode
= call(*popenargs
, **kwargs
)
500 cmd
= kwargs
.get("args")
503 raise CalledProcessError(retcode
, cmd
)
507 def check_output(*popenargs
, **kwargs
):
508 """Run command with arguments and return its output as a byte string.
510 If the exit code was non-zero it raises a CalledProcessError. The
511 CalledProcessError object will have the return code in the returncode
512 attribute and output in the output attribute.
514 The arguments are the same as for the Popen constructor. Example:
516 >>> check_output(["ls", "-l", "/dev/null"])
517 'crw-rw-rw- 1 root root 1, 3 Oct 18 2007 /dev/null\n'
519 The stdout argument is not allowed as it is used internally.
520 To capture standard error in the result, use stderr=subprocess.STDOUT.
522 >>> check_output(["/bin/sh", "-c",
523 "ls -l non_existent_file ; exit 0"],
524 stderr=subprocess.STDOUT)
525 'ls: non_existent_file: No such file or directory\n'
527 if 'stdout' in kwargs
:
528 raise ValueError('stdout argument not allowed, it will be overridden.')
529 process
= Popen(stdout
=PIPE
, *popenargs
, **kwargs
)
530 output
, unused_err
= process
.communicate()
531 retcode
= process
.poll()
533 cmd
= kwargs
.get("args")
536 raise CalledProcessError(retcode
, cmd
, output
=output
)
540 def list2cmdline(seq
):
542 Translate a sequence of arguments into a command line
543 string, using the same rules as the MS C runtime:
545 1) Arguments are delimited by white space, which is either a
548 2) A string surrounded by double quotation marks is
549 interpreted as a single argument, regardless of white space
550 or pipe characters contained within. A quoted string can be
551 embedded in an argument.
553 3) A double quotation mark preceded by a backslash is
554 interpreted as a literal double quotation mark.
556 4) Backslashes are interpreted literally, unless they
557 immediately precede a double quotation mark.
559 5) If backslashes immediately precede a double quotation mark,
560 every pair of backslashes is interpreted as a literal
561 backslash. If the number of backslashes is odd, the last
562 backslash escapes the next double quotation mark as
567 # http://msdn.microsoft.com/library/en-us/vccelng/htm/progs_12.asp
573 # Add a space to separate this argument from the others
577 needquote
= (" " in arg
) or ("\t" in arg
) or ("|" in arg
) or not arg
583 # Don't know if we need to double yet.
586 # Double backslashes.
587 result
.append('\\' * len(bs_buf
)*2)
593 result
.extend(bs_buf
)
597 # Add remaining backslashes, if any.
599 result
.extend(bs_buf
)
602 result
.extend(bs_buf
)
605 return ''.join(result
)
609 def __init__(self
, args
, bufsize
=0, executable
=None,
610 stdin
=None, stdout
=None, stderr
=None,
611 preexec_fn
=None, close_fds
=False, shell
=False,
612 cwd
=None, env
=None, universal_newlines
=False,
613 startupinfo
=None, creationflags
=0):
614 """Create new Popen instance."""
617 self
._child
_created
= False
618 if not isinstance(bufsize
, (int, long)):
619 raise TypeError("bufsize must be an integer")
622 if preexec_fn
is not None:
623 raise ValueError("preexec_fn is not supported on Windows "
625 if close_fds
and (stdin
is not None or stdout
is not None or
627 raise ValueError("close_fds is not supported on Windows "
628 "platforms if you redirect stdin/stdout/stderr")
631 if startupinfo
is not None:
632 raise ValueError("startupinfo is only supported on Windows "
634 if creationflags
!= 0:
635 raise ValueError("creationflags is only supported on Windows "
642 self
.returncode
= None
643 self
.universal_newlines
= universal_newlines
645 # Input and output objects. The general principle is like
650 # p2cwrite ---stdin---> p2cread
651 # c2pread <--stdout--- c2pwrite
652 # errread <--stderr--- errwrite
654 # On POSIX, the child objects are file descriptors. On
655 # Windows, these are Windows file handles. The parent objects
656 # are file descriptors on both platforms. The parent objects
657 # are None when not using PIPEs. The child objects are None
658 # when not redirecting.
662 errread
, errwrite
) = self
._get
_handles
(stdin
, stdout
, stderr
)
664 self
._execute
_child
(args
, executable
, preexec_fn
, close_fds
,
665 cwd
, env
, universal_newlines
,
666 startupinfo
, creationflags
, shell
,
672 if p2cwrite
is not None:
673 p2cwrite
= msvcrt
.open_osfhandle(p2cwrite
.Detach(), 0)
674 if c2pread
is not None:
675 c2pread
= msvcrt
.open_osfhandle(c2pread
.Detach(), 0)
676 if errread
is not None:
677 errread
= msvcrt
.open_osfhandle(errread
.Detach(), 0)
679 if p2cwrite
is not None:
680 self
.stdin
= os
.fdopen(p2cwrite
, 'wb', bufsize
)
681 if c2pread
is not None:
682 if universal_newlines
:
683 self
.stdout
= os
.fdopen(c2pread
, 'rU', bufsize
)
685 self
.stdout
= os
.fdopen(c2pread
, 'rb', bufsize
)
686 if errread
is not None:
687 if universal_newlines
:
688 self
.stderr
= os
.fdopen(errread
, 'rU', bufsize
)
690 self
.stderr
= os
.fdopen(errread
, 'rb', bufsize
)
693 def _translate_newlines(self
, data
):
694 data
= data
.replace("\r\n", "\n")
695 data
= data
.replace("\r", "\n")
699 def __del__(self
, sys
=sys
):
700 if not self
._child
_created
:
701 # We didn't get to successfully create a child process.
703 # In case the child hasn't been waited on, check if it's done.
704 self
._internal
_poll
(_deadstate
=sys
.maxint
)
705 if self
.returncode
is None and _active
is not None:
706 # Child is still running, keep us alive until we can wait on it.
710 def communicate(self
, input=None):
711 """Interact with process: Send data to stdin. Read data from
712 stdout and stderr, until end-of-file is reached. Wait for
713 process to terminate. The optional input argument should be a
714 string to be sent to the child process, or None, if no data
715 should be sent to the child.
717 communicate() returns a tuple (stdout, stderr)."""
719 # Optimization: If we are only using one pipe, or no pipe at
720 # all, using select() or threads is unnecessary.
721 if [self
.stdin
, self
.stdout
, self
.stderr
].count(None) >= 2:
726 self
.stdin
.write(input)
729 stdout
= self
.stdout
.read()
732 stderr
= self
.stderr
.read()
735 return (stdout
, stderr
)
737 return self
._communicate
(input)
741 return self
._internal
_poll
()
748 def _get_handles(self
, stdin
, stdout
, stderr
):
749 """Construct and return tuple with IO objects:
750 p2cread, p2cwrite, c2pread, c2pwrite, errread, errwrite
752 if stdin
is None and stdout
is None and stderr
is None:
753 return (None, None, None, None, None, None)
755 p2cread
, p2cwrite
= None, None
756 c2pread
, c2pwrite
= None, None
757 errread
, errwrite
= None, None
760 p2cread
= GetStdHandle(STD_INPUT_HANDLE
)
762 p2cread
, _
= CreatePipe(None, 0)
764 p2cread
, p2cwrite
= CreatePipe(None, 0)
765 elif isinstance(stdin
, int):
766 p2cread
= msvcrt
.get_osfhandle(stdin
)
768 # Assuming file-like object
769 p2cread
= msvcrt
.get_osfhandle(stdin
.fileno())
770 p2cread
= self
._make
_inheritable
(p2cread
)
773 c2pwrite
= GetStdHandle(STD_OUTPUT_HANDLE
)
775 _
, c2pwrite
= CreatePipe(None, 0)
777 c2pread
, c2pwrite
= CreatePipe(None, 0)
778 elif isinstance(stdout
, int):
779 c2pwrite
= msvcrt
.get_osfhandle(stdout
)
781 # Assuming file-like object
782 c2pwrite
= msvcrt
.get_osfhandle(stdout
.fileno())
783 c2pwrite
= self
._make
_inheritable
(c2pwrite
)
786 errwrite
= GetStdHandle(STD_ERROR_HANDLE
)
788 _
, errwrite
= CreatePipe(None, 0)
790 errread
, errwrite
= CreatePipe(None, 0)
791 elif stderr
== STDOUT
:
793 elif isinstance(stderr
, int):
794 errwrite
= msvcrt
.get_osfhandle(stderr
)
796 # Assuming file-like object
797 errwrite
= msvcrt
.get_osfhandle(stderr
.fileno())
798 errwrite
= self
._make
_inheritable
(errwrite
)
800 return (p2cread
, p2cwrite
,
805 def _make_inheritable(self
, handle
):
806 """Return a duplicate of handle, which is inheritable"""
807 return DuplicateHandle(GetCurrentProcess(), handle
,
808 GetCurrentProcess(), 0, 1,
809 DUPLICATE_SAME_ACCESS
)
812 def _find_w9xpopen(self
):
813 """Find and return absolut path to w9xpopen.exe"""
814 w9xpopen
= os
.path
.join(os
.path
.dirname(GetModuleFileName(0)),
816 if not os
.path
.exists(w9xpopen
):
817 # Eeek - file-not-found - possibly an embedding
818 # situation - see if we can locate it in sys.exec_prefix
819 w9xpopen
= os
.path
.join(os
.path
.dirname(sys
.exec_prefix
),
821 if not os
.path
.exists(w9xpopen
):
822 raise RuntimeError("Cannot locate w9xpopen.exe, which is "
823 "needed for Popen to work with your "
824 "shell or platform.")
828 def _execute_child(self
, args
, executable
, preexec_fn
, close_fds
,
829 cwd
, env
, universal_newlines
,
830 startupinfo
, creationflags
, shell
,
834 """Execute program (MS Windows version)"""
836 if not isinstance(args
, types
.StringTypes
):
837 args
= list2cmdline(args
)
839 # Process startup details
840 if startupinfo
is None:
841 startupinfo
= STARTUPINFO()
842 if None not in (p2cread
, c2pwrite
, errwrite
):
843 startupinfo
.dwFlags |
= STARTF_USESTDHANDLES
844 startupinfo
.hStdInput
= p2cread
845 startupinfo
.hStdOutput
= c2pwrite
846 startupinfo
.hStdError
= errwrite
849 startupinfo
.dwFlags |
= STARTF_USESHOWWINDOW
850 startupinfo
.wShowWindow
= SW_HIDE
851 comspec
= os
.environ
.get("COMSPEC", "cmd.exe")
852 args
= comspec
+ " /c " + args
853 if (GetVersion() >= 0x80000000L
or
854 os
.path
.basename(comspec
).lower() == "command.com"):
855 # Win9x, or using command.com on NT. We need to
856 # use the w9xpopen intermediate program. For more
857 # information, see KB Q150956
858 # (http://web.archive.org/web/20011105084002/http://support.microsoft.com/support/kb/articles/Q150/9/56.asp)
859 w9xpopen
= self
._find
_w
9xpopen
()
860 args
= '"%s" %s' % (w9xpopen
, args
)
861 # Not passing CREATE_NEW_CONSOLE has been known to
862 # cause random failures on win9x. Specifically a
863 # dialog: "Your program accessed mem currently in
864 # use at xxx" and a hopeful warning about the
865 # stability of your system. Cost is Ctrl+C wont
867 creationflags |
= CREATE_NEW_CONSOLE
871 hp
, ht
, pid
, tid
= CreateProcess(executable
, args
,
872 # no special security
879 except pywintypes
.error
, e
:
880 # Translate pywintypes.error to WindowsError, which is
881 # a subclass of OSError. FIXME: We should really
882 # translate errno using _sys_errlist (or simliar), but
883 # how can this be done from Python?
884 raise WindowsError(*e
.args
)
886 # Retain the process handle, but close the thread handle
887 self
._child
_created
= True
892 # Child is launched. Close the parent's copy of those pipe
893 # handles that only the child should have open. You need
894 # to make sure that no handles to the write end of the
895 # output pipe are maintained in this process or else the
896 # pipe will not close when the child process exits and the
897 # ReadFile will hang.
898 if p2cread
is not None:
900 if c2pwrite
is not None:
902 if errwrite
is not None:
906 def _internal_poll(self
, _deadstate
=None):
907 """Check if child process has terminated. Returns returncode
909 if self
.returncode
is None:
910 if WaitForSingleObject(self
._handle
, 0) == WAIT_OBJECT_0
:
911 self
.returncode
= GetExitCodeProcess(self
._handle
)
912 return self
.returncode
916 """Wait for child process to terminate. Returns returncode
918 if self
.returncode
is None:
919 obj
= WaitForSingleObject(self
._handle
, INFINITE
)
920 self
.returncode
= GetExitCodeProcess(self
._handle
)
921 return self
.returncode
924 def _readerthread(self
, fh
, buffer):
925 buffer.append(fh
.read())
928 def _communicate(self
, input):
929 stdout
= None # Return
930 stderr
= None # Return
934 stdout_thread
= threading
.Thread(target
=self
._readerthread
,
935 args
=(self
.stdout
, stdout
))
936 stdout_thread
.setDaemon(True)
937 stdout_thread
.start()
940 stderr_thread
= threading
.Thread(target
=self
._readerthread
,
941 args
=(self
.stderr
, stderr
))
942 stderr_thread
.setDaemon(True)
943 stderr_thread
.start()
946 if input is not None:
947 self
.stdin
.write(input)
955 # All data exchanged. Translate lists into strings.
956 if stdout
is not None:
958 if stderr
is not None:
961 # Translate newlines, if requested. We cannot let the file
962 # object do the translation: It is based on stdio, which is
963 # impossible to combine with select (unless forcing no
965 if self
.universal_newlines
and hasattr(file, 'newlines'):
967 stdout
= self
._translate
_newlines
(stdout
)
969 stderr
= self
._translate
_newlines
(stderr
)
972 return (stdout
, stderr
)
974 def send_signal(self
, sig
):
975 """Send a signal to the process
977 if sig
== signal
.SIGTERM
:
980 raise ValueError("Only SIGTERM is supported on Windows")
983 """Terminates the process
985 TerminateProcess(self
._handle
, 1)
993 def _get_handles(self
, stdin
, stdout
, stderr
):
994 """Construct and return tuple with IO objects:
995 p2cread, p2cwrite, c2pread, c2pwrite, errread, errwrite
997 p2cread
, p2cwrite
= None, None
998 c2pread
, c2pwrite
= None, None
999 errread
, errwrite
= None, None
1004 p2cread
, p2cwrite
= os
.pipe()
1005 elif isinstance(stdin
, int):
1008 # Assuming file-like object
1009 p2cread
= stdin
.fileno()
1013 elif stdout
== PIPE
:
1014 c2pread
, c2pwrite
= os
.pipe()
1015 elif isinstance(stdout
, int):
1018 # Assuming file-like object
1019 c2pwrite
= stdout
.fileno()
1023 elif stderr
== PIPE
:
1024 errread
, errwrite
= os
.pipe()
1025 elif stderr
== STDOUT
:
1027 elif isinstance(stderr
, int):
1030 # Assuming file-like object
1031 errwrite
= stderr
.fileno()
1033 return (p2cread
, p2cwrite
,
1038 def _set_cloexec_flag(self
, fd
):
1040 cloexec_flag
= fcntl
.FD_CLOEXEC
1041 except AttributeError:
1044 old
= fcntl
.fcntl(fd
, fcntl
.F_GETFD
)
1045 fcntl
.fcntl(fd
, fcntl
.F_SETFD
, old | cloexec_flag
)
1048 def _close_fds(self
, but
):
1049 if hasattr(os
, 'closerange'):
1050 os
.closerange(3, but
)
1051 os
.closerange(but
+ 1, MAXFD
)
1053 for i
in xrange(3, MAXFD
):
1062 def _execute_child(self
, args
, executable
, preexec_fn
, close_fds
,
1063 cwd
, env
, universal_newlines
,
1064 startupinfo
, creationflags
, shell
,
1068 """Execute program (POSIX version)"""
1070 if isinstance(args
, types
.StringTypes
):
1076 args
= ["/bin/sh", "-c"] + args
1078 if executable
is None:
1079 executable
= args
[0]
1081 # For transferring possible exec failure from child to parent
1082 # The first char specifies the exception type: 0 means
1083 # OSError, 1 means some other error.
1084 errpipe_read
, errpipe_write
= os
.pipe()
1087 self
._set
_cloexec
_flag
(errpipe_write
)
1089 gc_was_enabled
= gc
.isenabled()
1090 # Disable gc to avoid bug where gc -> file_dealloc ->
1091 # write to stderr -> hang. http://bugs.python.org/issue1336
1094 self
.pid
= os
.fork()
1099 self
._child
_created
= True
1103 # Close parent's pipe ends
1104 if p2cwrite
is not None:
1106 if c2pread
is not None:
1108 if errread
is not None:
1110 os
.close(errpipe_read
)
1113 if p2cread
is not None:
1115 if c2pwrite
is not None:
1116 os
.dup2(c2pwrite
, 1)
1117 if errwrite
is not None:
1118 os
.dup2(errwrite
, 2)
1120 # Close pipe fds. Make sure we don't close the same
1121 # fd more than once, or standard fds.
1122 if p2cread
is not None and p2cread
not in (0,):
1124 if c2pwrite
is not None and c2pwrite
not in (p2cread
, 1):
1126 if errwrite
is not None and errwrite
not in (p2cread
, c2pwrite
, 2):
1129 # Close all other fds, if asked for
1131 self
._close
_fds
(but
=errpipe_write
)
1140 os
.execvp(executable
, args
)
1142 os
.execvpe(executable
, args
, env
)
1145 exc_type
, exc_value
, tb
= sys
.exc_info()
1146 # Save the traceback and attach it to the exception object
1147 exc_lines
= traceback
.format_exception(exc_type
,
1150 exc_value
.child_traceback
= ''.join(exc_lines
)
1151 os
.write(errpipe_write
, pickle
.dumps(exc_value
))
1153 # This exitcode won't be reported to applications, so it
1154 # really doesn't matter what we return.
1161 # be sure the FD is closed no matter what
1162 os
.close(errpipe_write
)
1164 if p2cread
is not None and p2cwrite
is not None:
1166 if c2pwrite
is not None and c2pread
is not None:
1168 if errwrite
is not None and errread
is not None:
1171 # Wait for exec to fail or succeed; possibly raising exception
1172 data
= os
.read(errpipe_read
, 1048576) # Exception limited to 1M
1174 # be sure the FD is closed no matter what
1175 os
.close(errpipe_read
)
1178 os
.waitpid(self
.pid
, 0)
1179 child_exception
= pickle
.loads(data
)
1180 for fd
in (p2cwrite
, c2pread
, errread
):
1183 raise child_exception
1186 def _handle_exitstatus(self
, sts
):
1187 if os
.WIFSIGNALED(sts
):
1188 self
.returncode
= -os
.WTERMSIG(sts
)
1189 elif os
.WIFEXITED(sts
):
1190 self
.returncode
= os
.WEXITSTATUS(sts
)
1192 # Should never happen
1193 raise RuntimeError("Unknown child exit status!")
1196 def _internal_poll(self
, _deadstate
=None):
1197 """Check if child process has terminated. Returns returncode
1199 if self
.returncode
is None:
1201 pid
, sts
= os
.waitpid(self
.pid
, os
.WNOHANG
)
1203 self
._handle
_exitstatus
(sts
)
1205 if _deadstate
is not None:
1206 self
.returncode
= _deadstate
1207 return self
.returncode
1211 """Wait for child process to terminate. Returns returncode
1213 if self
.returncode
is None:
1214 pid
, sts
= os
.waitpid(self
.pid
, 0)
1215 self
._handle
_exitstatus
(sts
)
1216 return self
.returncode
1219 def _communicate(self
, input):
1221 # Flush stdio buffer. This might block, if the user has
1222 # been writing to .stdin in an uncontrolled fashion.
1228 stdout
, stderr
= self
._communicate
_with
_poll
(input)
1230 stdout
, stderr
= self
._communicate
_with
_select
(input)
1232 # All data exchanged. Translate lists into strings.
1233 if stdout
is not None:
1234 stdout
= ''.join(stdout
)
1235 if stderr
is not None:
1236 stderr
= ''.join(stderr
)
1238 # Translate newlines, if requested. We cannot let the file
1239 # object do the translation: It is based on stdio, which is
1240 # impossible to combine with select (unless forcing no
1242 if self
.universal_newlines
and hasattr(file, 'newlines'):
1244 stdout
= self
._translate
_newlines
(stdout
)
1246 stderr
= self
._translate
_newlines
(stderr
)
1249 return (stdout
, stderr
)
1252 def _communicate_with_poll(self
, input):
1253 stdout
= None # Return
1254 stderr
= None # Return
1258 poller
= select
.poll()
1259 def register_and_append(file_obj
, eventmask
):
1260 poller
.register(file_obj
.fileno(), eventmask
)
1261 fd2file
[file_obj
.fileno()] = file_obj
1263 def close_unregister_and_remove(fd
):
1264 poller
.unregister(fd
)
1268 if self
.stdin
and input:
1269 register_and_append(self
.stdin
, select
.POLLOUT
)
1271 select_POLLIN_POLLPRI
= select
.POLLIN | select
.POLLPRI
1273 register_and_append(self
.stdout
, select_POLLIN_POLLPRI
)
1274 fd2output
[self
.stdout
.fileno()] = stdout
= []
1276 register_and_append(self
.stderr
, select_POLLIN_POLLPRI
)
1277 fd2output
[self
.stderr
.fileno()] = stderr
= []
1282 ready
= poller
.poll()
1283 except select
.error
, e
:
1284 if e
.args
[0] == errno
.EINTR
:
1288 for fd
, mode
in ready
:
1289 if mode
& select
.POLLOUT
:
1290 chunk
= input[input_offset
: input_offset
+ _PIPE_BUF
]
1291 input_offset
+= os
.write(fd
, chunk
)
1292 if input_offset
>= len(input):
1293 close_unregister_and_remove(fd
)
1294 elif mode
& select_POLLIN_POLLPRI
:
1295 data
= os
.read(fd
, 4096)
1297 close_unregister_and_remove(fd
)
1298 fd2output
[fd
].append(data
)
1300 # Ignore hang up or errors.
1301 close_unregister_and_remove(fd
)
1303 return (stdout
, stderr
)
1306 def _communicate_with_select(self
, input):
1309 stdout
= None # Return
1310 stderr
= None # Return
1312 if self
.stdin
and input:
1313 write_set
.append(self
.stdin
)
1315 read_set
.append(self
.stdout
)
1318 read_set
.append(self
.stderr
)
1322 while read_set
or write_set
:
1324 rlist
, wlist
, xlist
= select
.select(read_set
, write_set
, [])
1325 except select
.error
, e
:
1326 if e
.args
[0] == errno
.EINTR
:
1330 if self
.stdin
in wlist
:
1331 chunk
= input[input_offset
: input_offset
+ _PIPE_BUF
]
1332 bytes_written
= os
.write(self
.stdin
.fileno(), chunk
)
1333 input_offset
+= bytes_written
1334 if input_offset
>= len(input):
1336 write_set
.remove(self
.stdin
)
1338 if self
.stdout
in rlist
:
1339 data
= os
.read(self
.stdout
.fileno(), 1024)
1342 read_set
.remove(self
.stdout
)
1345 if self
.stderr
in rlist
:
1346 data
= os
.read(self
.stderr
.fileno(), 1024)
1349 read_set
.remove(self
.stderr
)
1352 return (stdout
, stderr
)
1355 def send_signal(self
, sig
):
1356 """Send a signal to the process
1358 os
.kill(self
.pid
, sig
)
1360 def terminate(self
):
1361 """Terminate the process with SIGTERM
1363 self
.send_signal(signal
.SIGTERM
)
1366 """Kill the process with SIGKILL
1368 self
.send_signal(signal
.SIGKILL
)
1373 # Example 1: Simple redirection: Get process list
1375 plist
= Popen(["ps"], stdout
=PIPE
).communicate()[0]
1376 print "Process list:"
1380 # Example 2: Change uid before executing child
1382 if os
.getuid() == 0:
1383 p
= Popen(["id"], preexec_fn
=lambda: os
.setuid(100))
1387 # Example 3: Connecting several subprocesses
1389 print "Looking for 'hda'..."
1390 p1
= Popen(["dmesg"], stdout
=PIPE
)
1391 p2
= Popen(["grep", "hda"], stdin
=p1
.stdout
, stdout
=PIPE
)
1392 print repr(p2
.communicate()[0])
1395 # Example 4: Catch execution error
1398 print "Trying a weird file..."
1400 print Popen(["/this/path/does/not/exist"]).communicate()
1402 if e
.errno
== errno
.ENOENT
:
1403 print "The file didn't exist. I thought so..."
1404 print "Child traceback:"
1405 print e
.child_traceback
1407 print "Error", e
.errno
1409 print >>sys
.stderr
, "Gosh. No error."
1412 def _demo_windows():
1414 # Example 1: Connecting several subprocesses
1416 print "Looking for 'PROMPT' in set output..."
1417 p1
= Popen("set", stdout
=PIPE
, shell
=True)
1418 p2
= Popen('find "PROMPT"', stdin
=p1
.stdout
, stdout
=PIPE
)
1419 print repr(p2
.communicate()[0])
1422 # Example 2: Simple execution of program
1424 print "Executing calc..."
1429 if __name__
== "__main__":