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 = check_output(["ls", "-l", "/dev/null"])
144 Exceptions raised in the child process, before the new program has
145 started to execute, will be re-raised in the parent. Additionally,
146 the exception object will have one extra attribute called
147 'child_traceback', which is a string containing traceback information
148 from the childs point of view.
150 The most common exception raised is OSError. This occurs, for
151 example, when trying to execute a non-existent file. Applications
152 should prepare for OSErrors.
154 A ValueError will be raised if Popen is called with invalid arguments.
156 check_call() and check_output() will raise CalledProcessError, if the
157 called process returns a non-zero return code.
162 Unlike some other popen functions, this implementation will never call
163 /bin/sh implicitly. This means that all characters, including shell
164 metacharacters, can safely be passed to child processes.
169 Instances of the Popen class have the following methods:
172 Check if child process has terminated. Returns returncode
176 Wait for child process to terminate. Returns returncode attribute.
178 communicate(input=None)
179 Interact with process: Send data to stdin. Read data from stdout
180 and stderr, until end-of-file is reached. Wait for process to
181 terminate. The optional input argument should be a string to be
182 sent to the child process, or None, if no data should be sent to
185 communicate() returns a tuple (stdout, stderr).
187 Note: The data read is buffered in memory, so do not use this
188 method if the data size is large or unlimited.
190 The following attributes are also available:
193 If the stdin argument is PIPE, this attribute is a file object
194 that provides input to the child process. Otherwise, it is None.
197 If the stdout argument is PIPE, this attribute is a file object
198 that provides output from the child process. Otherwise, it is
202 If the stderr argument is PIPE, this attribute is file object that
203 provides error output from the child process. Otherwise, it is
207 The process ID of the child process.
210 The child return code. A None value indicates that the process
211 hasn't terminated yet. A negative value -N indicates that the
212 child was terminated by signal N (UNIX only).
215 Replacing older functions with the subprocess module
216 ====================================================
217 In this section, "a ==> b" means that b can be used as a replacement
220 Note: All functions in this section fail (more or less) silently if
221 the executed program cannot be found; this module raises an OSError
224 In the following examples, we assume that the subprocess module is
225 imported with "from subprocess import *".
228 Replacing /bin/sh shell backquote
229 ---------------------------------
232 output = Popen(["mycmd", "myarg"], stdout=PIPE).communicate()[0]
235 Replacing shell pipe line
236 -------------------------
237 output=`dmesg | grep hda`
239 p1 = Popen(["dmesg"], stdout=PIPE)
240 p2 = Popen(["grep", "hda"], stdin=p1.stdout, stdout=PIPE)
241 output = p2.communicate()[0]
244 Replacing os.system()
245 ---------------------
246 sts = os.system("mycmd" + " myarg")
248 p = Popen("mycmd" + " myarg", shell=True)
249 pid, sts = os.waitpid(p.pid, 0)
253 * Calling the program through the shell is usually not required.
255 * It's easier to look at the returncode attribute than the
258 A more real-world example would look like this:
261 retcode = call("mycmd" + " myarg", shell=True)
263 print >>sys.stderr, "Child was terminated by signal", -retcode
265 print >>sys.stderr, "Child returned", retcode
267 print >>sys.stderr, "Execution failed:", e
274 pid = os.spawnlp(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg")
276 pid = Popen(["/bin/mycmd", "myarg"]).pid
281 retcode = os.spawnlp(os.P_WAIT, "/bin/mycmd", "mycmd", "myarg")
283 retcode = call(["/bin/mycmd", "myarg"])
288 os.spawnvp(os.P_NOWAIT, path, args)
290 Popen([path] + args[1:])
295 os.spawnlpe(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg", env)
297 Popen(["/bin/mycmd", "myarg"], env={"PATH": "/usr/bin"})
302 pipe = os.popen("cmd", mode='r', bufsize)
304 pipe = Popen("cmd", shell=True, bufsize=bufsize, stdout=PIPE).stdout
306 pipe = os.popen("cmd", mode='w', bufsize)
308 pipe = Popen("cmd", shell=True, bufsize=bufsize, stdin=PIPE).stdin
311 (child_stdin, child_stdout) = os.popen2("cmd", mode, bufsize)
313 p = Popen("cmd", shell=True, bufsize=bufsize,
314 stdin=PIPE, stdout=PIPE, close_fds=True)
315 (child_stdin, child_stdout) = (p.stdin, p.stdout)
320 child_stderr) = os.popen3("cmd", mode, bufsize)
322 p = Popen("cmd", shell=True, bufsize=bufsize,
323 stdin=PIPE, stdout=PIPE, stderr=PIPE, close_fds=True)
326 child_stderr) = (p.stdin, p.stdout, p.stderr)
329 (child_stdin, child_stdout_and_stderr) = os.popen4("cmd", mode,
332 p = Popen("cmd", shell=True, bufsize=bufsize,
333 stdin=PIPE, stdout=PIPE, stderr=STDOUT, close_fds=True)
334 (child_stdin, child_stdout_and_stderr) = (p.stdin, p.stdout)
336 On Unix, os.popen2, os.popen3 and os.popen4 also accept a sequence as
337 the command to execute, in which case arguments will be passed
338 directly to the program without shell intervention. This usage can be
341 (child_stdin, child_stdout) = os.popen2(["/bin/ls", "-l"], mode,
344 p = Popen(["/bin/ls", "-l"], bufsize=bufsize, stdin=PIPE, stdout=PIPE)
345 (child_stdin, child_stdout) = (p.stdin, p.stdout)
347 Return code handling translates as follows:
349 pipe = os.popen("cmd", 'w')
352 if rc is not None and rc % 256:
353 print "There were some errors"
355 process = Popen("cmd", 'w', shell=True, stdin=PIPE)
357 process.stdin.close()
358 if process.wait() != 0:
359 print "There were some errors"
364 (child_stdout, child_stdin) = popen2.popen2("somestring", bufsize, mode)
366 p = Popen(["somestring"], shell=True, bufsize=bufsize
367 stdin=PIPE, stdout=PIPE, close_fds=True)
368 (child_stdout, child_stdin) = (p.stdout, p.stdin)
370 On Unix, popen2 also accepts a sequence as the command to execute, in
371 which case arguments will be passed directly to the program without
372 shell intervention. This usage can be replaced as follows:
374 (child_stdout, child_stdin) = popen2.popen2(["mycmd", "myarg"], bufsize,
377 p = Popen(["mycmd", "myarg"], bufsize=bufsize,
378 stdin=PIPE, stdout=PIPE, close_fds=True)
379 (child_stdout, child_stdin) = (p.stdout, p.stdin)
381 The popen2.Popen3 and popen2.Popen4 basically works as subprocess.Popen,
384 * subprocess.Popen raises an exception if the execution fails
385 * the capturestderr argument is replaced with the stderr argument.
386 * stdin=PIPE and stdout=PIPE must be specified.
387 * popen2 closes all filedescriptors by default, but you have to specify
388 close_fds=True with subprocess.Popen.
392 mswindows
= (sys
.platform
== "win32")
400 # Exception classes used by this module.
401 class CalledProcessError(Exception):
402 """This exception is raised when a process run by check_call() or
403 check_output() returns a non-zero exit status.
404 The exit status will be stored in the returncode attribute;
405 check_output() will also store the output in the output attribute.
407 def __init__(self
, returncode
, cmd
, output
=None):
408 self
.returncode
= returncode
412 return "Command '%s' returned non-zero exit status %d" % (self
.cmd
, self
.returncode
)
429 _has_poll
= hasattr(select
, 'poll')
434 # When select or poll has indicated that the file is writable,
435 # we can write up to _PIPE_BUF bytes without risk of blocking.
436 # POSIX defines PIPE_BUF as >= 512.
437 _PIPE_BUF
= getattr(select
, 'PIPE_BUF', 512)
440 __all__
= ["Popen", "PIPE", "STDOUT", "call", "check_call",
441 "check_output", "CalledProcessError"]
444 from _subprocess
import CREATE_NEW_CONSOLE
, CREATE_NEW_PROCESS_GROUP
445 __all__
.extend(["CREATE_NEW_CONSOLE", "CREATE_NEW_PROCESS_GROUP"])
447 MAXFD
= os
.sysconf("SC_OPEN_MAX")
454 for inst
in _active
[:]:
455 res
= inst
._internal
_poll
(_deadstate
=sys
.maxint
)
456 if res
is not None and res
>= 0:
460 # This can happen if two threads create a new Popen instance.
461 # It's harmless that it was already removed, so ignore.
468 def _eintr_retry_call(func
, *args
):
473 if e
.errno
== errno
.EINTR
:
478 def call(*popenargs
, **kwargs
):
479 """Run command with arguments. Wait for command to complete, then
480 return the returncode attribute.
482 The arguments are the same as for the Popen constructor. Example:
484 retcode = call(["ls", "-l"])
486 return Popen(*popenargs
, **kwargs
).wait()
489 def check_call(*popenargs
, **kwargs
):
490 """Run command with arguments. Wait for command to complete. If
491 the exit code was zero then return, otherwise raise
492 CalledProcessError. The CalledProcessError object will have the
493 return code in the returncode attribute.
495 The arguments are the same as for the Popen constructor. Example:
497 check_call(["ls", "-l"])
499 retcode
= call(*popenargs
, **kwargs
)
501 cmd
= kwargs
.get("args")
504 raise CalledProcessError(retcode
, cmd
)
508 def check_output(*popenargs
, **kwargs
):
509 r
"""Run command with arguments and return its output as a byte string.
511 If the exit code was non-zero it raises a CalledProcessError. The
512 CalledProcessError object will have the return code in the returncode
513 attribute and output in the output attribute.
515 The arguments are the same as for the Popen constructor. Example:
517 >>> check_output(["ls", "-l", "/dev/null"])
518 'crw-rw-rw- 1 root root 1, 3 Oct 18 2007 /dev/null\n'
520 The stdout argument is not allowed as it is used internally.
521 To capture standard error in the result, use stderr=STDOUT.
523 >>> check_output(["/bin/sh", "-c",
524 ... "ls -l non_existent_file ; exit 0"],
526 'ls: non_existent_file: No such file or directory\n'
528 if 'stdout' in kwargs
:
529 raise ValueError('stdout argument not allowed, it will be overridden.')
530 process
= Popen(stdout
=PIPE
, *popenargs
, **kwargs
)
531 output
, unused_err
= process
.communicate()
532 retcode
= process
.poll()
534 cmd
= kwargs
.get("args")
537 raise CalledProcessError(retcode
, cmd
, output
=output
)
541 def list2cmdline(seq
):
543 Translate a sequence of arguments into a command line
544 string, using the same rules as the MS C runtime:
546 1) Arguments are delimited by white space, which is either a
549 2) A string surrounded by double quotation marks is
550 interpreted as a single argument, regardless of white space
551 contained within. A quoted string can be embedded in an
554 3) A double quotation mark preceded by a backslash is
555 interpreted as a literal double quotation mark.
557 4) Backslashes are interpreted literally, unless they
558 immediately precede a double quotation mark.
560 5) If backslashes immediately precede a double quotation mark,
561 every pair of backslashes is interpreted as a literal
562 backslash. If the number of backslashes is odd, the last
563 backslash escapes the next double quotation mark as
568 # http://msdn.microsoft.com/en-us/library/17w5ykft.aspx
569 # or search http://msdn.microsoft.com for
570 # "Parsing C++ Command-Line Arguments"
576 # Add a space to separate this argument from the others
580 needquote
= (" " in arg
) or ("\t" in arg
) or not arg
586 # Don't know if we need to double yet.
589 # Double backslashes.
590 result
.append('\\' * len(bs_buf
)*2)
596 result
.extend(bs_buf
)
600 # Add remaining backslashes, if any.
602 result
.extend(bs_buf
)
605 result
.extend(bs_buf
)
608 return ''.join(result
)
612 def __init__(self
, args
, bufsize
=0, executable
=None,
613 stdin
=None, stdout
=None, stderr
=None,
614 preexec_fn
=None, close_fds
=False, shell
=False,
615 cwd
=None, env
=None, universal_newlines
=False,
616 startupinfo
=None, creationflags
=0):
617 """Create new Popen instance."""
620 self
._child
_created
= False
621 if not isinstance(bufsize
, (int, long)):
622 raise TypeError("bufsize must be an integer")
625 if preexec_fn
is not None:
626 raise ValueError("preexec_fn is not supported on Windows "
628 if close_fds
and (stdin
is not None or stdout
is not None or
630 raise ValueError("close_fds is not supported on Windows "
631 "platforms if you redirect stdin/stdout/stderr")
634 if startupinfo
is not None:
635 raise ValueError("startupinfo is only supported on Windows "
637 if creationflags
!= 0:
638 raise ValueError("creationflags is only supported on Windows "
645 self
.returncode
= None
646 self
.universal_newlines
= universal_newlines
648 # Input and output objects. The general principle is like
653 # p2cwrite ---stdin---> p2cread
654 # c2pread <--stdout--- c2pwrite
655 # errread <--stderr--- errwrite
657 # On POSIX, the child objects are file descriptors. On
658 # Windows, these are Windows file handles. The parent objects
659 # are file descriptors on both platforms. The parent objects
660 # are None when not using PIPEs. The child objects are None
661 # when not redirecting.
665 errread
, errwrite
) = self
._get
_handles
(stdin
, stdout
, stderr
)
667 self
._execute
_child
(args
, executable
, preexec_fn
, close_fds
,
668 cwd
, env
, universal_newlines
,
669 startupinfo
, creationflags
, shell
,
675 if p2cwrite
is not None:
676 p2cwrite
= msvcrt
.open_osfhandle(p2cwrite
.Detach(), 0)
677 if c2pread
is not None:
678 c2pread
= msvcrt
.open_osfhandle(c2pread
.Detach(), 0)
679 if errread
is not None:
680 errread
= msvcrt
.open_osfhandle(errread
.Detach(), 0)
682 if p2cwrite
is not None:
683 self
.stdin
= os
.fdopen(p2cwrite
, 'wb', bufsize
)
684 if c2pread
is not None:
685 if universal_newlines
:
686 self
.stdout
= os
.fdopen(c2pread
, 'rU', bufsize
)
688 self
.stdout
= os
.fdopen(c2pread
, 'rb', bufsize
)
689 if errread
is not None:
690 if universal_newlines
:
691 self
.stderr
= os
.fdopen(errread
, 'rU', bufsize
)
693 self
.stderr
= os
.fdopen(errread
, 'rb', bufsize
)
696 def _translate_newlines(self
, data
):
697 data
= data
.replace("\r\n", "\n")
698 data
= data
.replace("\r", "\n")
702 def __del__(self
, _maxint
=sys
.maxint
, _active
=_active
):
703 if not self
._child
_created
:
704 # We didn't get to successfully create a child process.
706 # In case the child hasn't been waited on, check if it's done.
707 self
._internal
_poll
(_deadstate
=_maxint
)
708 if self
.returncode
is None and _active
is not None:
709 # Child is still running, keep us alive until we can wait on it.
713 def communicate(self
, input=None):
714 """Interact with process: Send data to stdin. Read data from
715 stdout and stderr, until end-of-file is reached. Wait for
716 process to terminate. The optional input argument should be a
717 string to be sent to the child process, or None, if no data
718 should be sent to the child.
720 communicate() returns a tuple (stdout, stderr)."""
722 # Optimization: If we are only using one pipe, or no pipe at
723 # all, using select() or threads is unnecessary.
724 if [self
.stdin
, self
.stdout
, self
.stderr
].count(None) >= 2:
729 self
.stdin
.write(input)
732 stdout
= self
.stdout
.read()
735 stderr
= self
.stderr
.read()
738 return (stdout
, stderr
)
740 return self
._communicate
(input)
744 return self
._internal
_poll
()
751 def _get_handles(self
, stdin
, stdout
, stderr
):
752 """Construct and return tuple with IO objects:
753 p2cread, p2cwrite, c2pread, c2pwrite, errread, errwrite
755 if stdin
is None and stdout
is None and stderr
is None:
756 return (None, None, None, None, None, None)
758 p2cread
, p2cwrite
= None, None
759 c2pread
, c2pwrite
= None, None
760 errread
, errwrite
= None, None
763 p2cread
= _subprocess
.GetStdHandle(_subprocess
.STD_INPUT_HANDLE
)
765 p2cread
, _
= _subprocess
.CreatePipe(None, 0)
767 p2cread
, p2cwrite
= _subprocess
.CreatePipe(None, 0)
768 elif isinstance(stdin
, int):
769 p2cread
= msvcrt
.get_osfhandle(stdin
)
771 # Assuming file-like object
772 p2cread
= msvcrt
.get_osfhandle(stdin
.fileno())
773 p2cread
= self
._make
_inheritable
(p2cread
)
776 c2pwrite
= _subprocess
.GetStdHandle(_subprocess
.STD_OUTPUT_HANDLE
)
778 _
, c2pwrite
= _subprocess
.CreatePipe(None, 0)
780 c2pread
, c2pwrite
= _subprocess
.CreatePipe(None, 0)
781 elif isinstance(stdout
, int):
782 c2pwrite
= msvcrt
.get_osfhandle(stdout
)
784 # Assuming file-like object
785 c2pwrite
= msvcrt
.get_osfhandle(stdout
.fileno())
786 c2pwrite
= self
._make
_inheritable
(c2pwrite
)
789 errwrite
= _subprocess
.GetStdHandle(_subprocess
.STD_ERROR_HANDLE
)
791 _
, errwrite
= _subprocess
.CreatePipe(None, 0)
793 errread
, errwrite
= _subprocess
.CreatePipe(None, 0)
794 elif stderr
== STDOUT
:
796 elif isinstance(stderr
, int):
797 errwrite
= msvcrt
.get_osfhandle(stderr
)
799 # Assuming file-like object
800 errwrite
= msvcrt
.get_osfhandle(stderr
.fileno())
801 errwrite
= self
._make
_inheritable
(errwrite
)
803 return (p2cread
, p2cwrite
,
808 def _make_inheritable(self
, handle
):
809 """Return a duplicate of handle, which is inheritable"""
810 return _subprocess
.DuplicateHandle(_subprocess
.GetCurrentProcess(),
811 handle
, _subprocess
.GetCurrentProcess(), 0, 1,
812 _subprocess
.DUPLICATE_SAME_ACCESS
)
815 def _find_w9xpopen(self
):
816 """Find and return absolut path to w9xpopen.exe"""
817 w9xpopen
= os
.path
.join(
818 os
.path
.dirname(_subprocess
.GetModuleFileName(0)),
820 if not os
.path
.exists(w9xpopen
):
821 # Eeek - file-not-found - possibly an embedding
822 # situation - see if we can locate it in sys.exec_prefix
823 w9xpopen
= os
.path
.join(os
.path
.dirname(sys
.exec_prefix
),
825 if not os
.path
.exists(w9xpopen
):
826 raise RuntimeError("Cannot locate w9xpopen.exe, which is "
827 "needed for Popen to work with your "
828 "shell or platform.")
832 def _execute_child(self
, args
, executable
, preexec_fn
, close_fds
,
833 cwd
, env
, universal_newlines
,
834 startupinfo
, creationflags
, shell
,
838 """Execute program (MS Windows version)"""
840 if not isinstance(args
, types
.StringTypes
):
841 args
= list2cmdline(args
)
843 # Process startup details
844 if startupinfo
is None:
845 startupinfo
= STARTUPINFO()
846 if None not in (p2cread
, c2pwrite
, errwrite
):
847 startupinfo
.dwFlags |
= _subprocess
.STARTF_USESTDHANDLES
848 startupinfo
.hStdInput
= p2cread
849 startupinfo
.hStdOutput
= c2pwrite
850 startupinfo
.hStdError
= errwrite
853 startupinfo
.dwFlags |
= _subprocess
.STARTF_USESHOWWINDOW
854 startupinfo
.wShowWindow
= _subprocess
.SW_HIDE
855 comspec
= os
.environ
.get("COMSPEC", "cmd.exe")
856 args
= comspec
+ " /c " + args
857 if (_subprocess
.GetVersion() >= 0x80000000L
or
858 os
.path
.basename(comspec
).lower() == "command.com"):
859 # Win9x, or using command.com on NT. We need to
860 # use the w9xpopen intermediate program. For more
861 # information, see KB Q150956
862 # (http://web.archive.org/web/20011105084002/http://support.microsoft.com/support/kb/articles/Q150/9/56.asp)
863 w9xpopen
= self
._find
_w
9xpopen
()
864 args
= '"%s" %s' % (w9xpopen
, args
)
865 # Not passing CREATE_NEW_CONSOLE has been known to
866 # cause random failures on win9x. Specifically a
867 # dialog: "Your program accessed mem currently in
868 # use at xxx" and a hopeful warning about the
869 # stability of your system. Cost is Ctrl+C wont
871 creationflags |
= _subprocess
.CREATE_NEW_CONSOLE
875 hp
, ht
, pid
, tid
= _subprocess
.CreateProcess(executable
, args
,
876 # no special security
883 except pywintypes
.error
, e
:
884 # Translate pywintypes.error to WindowsError, which is
885 # a subclass of OSError. FIXME: We should really
886 # translate errno using _sys_errlist (or simliar), but
887 # how can this be done from Python?
888 raise WindowsError(*e
.args
)
890 # Retain the process handle, but close the thread handle
891 self
._child
_created
= True
896 # Child is launched. Close the parent's copy of those pipe
897 # handles that only the child should have open. You need
898 # to make sure that no handles to the write end of the
899 # output pipe are maintained in this process or else the
900 # pipe will not close when the child process exits and the
901 # ReadFile will hang.
902 if p2cread
is not None:
904 if c2pwrite
is not None:
906 if errwrite
is not None:
910 def _internal_poll(self
, _deadstate
=None,
911 _WaitForSingleObject
=_subprocess
.WaitForSingleObject
,
912 _WAIT_OBJECT_0
=_subprocess
.WAIT_OBJECT_0
,
913 _GetExitCodeProcess
=_subprocess
.GetExitCodeProcess
):
914 """Check if child process has terminated. Returns returncode
917 This method is called by __del__, so it can only refer to objects
921 if self
.returncode
is None:
922 if _WaitForSingleObject(self
._handle
, 0) == _WAIT_OBJECT_0
:
923 self
.returncode
= _GetExitCodeProcess(self
._handle
)
924 return self
.returncode
928 """Wait for child process to terminate. Returns returncode
930 if self
.returncode
is None:
931 _subprocess
.WaitForSingleObject(self
._handle
,
932 _subprocess
.INFINITE
)
933 self
.returncode
= _subprocess
.GetExitCodeProcess(self
._handle
)
934 return self
.returncode
937 def _readerthread(self
, fh
, buffer):
938 buffer.append(fh
.read())
941 def _communicate(self
, input):
942 stdout
= None # Return
943 stderr
= None # Return
947 stdout_thread
= threading
.Thread(target
=self
._readerthread
,
948 args
=(self
.stdout
, stdout
))
949 stdout_thread
.setDaemon(True)
950 stdout_thread
.start()
953 stderr_thread
= threading
.Thread(target
=self
._readerthread
,
954 args
=(self
.stderr
, stderr
))
955 stderr_thread
.setDaemon(True)
956 stderr_thread
.start()
959 if input is not None:
960 self
.stdin
.write(input)
968 # All data exchanged. Translate lists into strings.
969 if stdout
is not None:
971 if stderr
is not None:
974 # Translate newlines, if requested. We cannot let the file
975 # object do the translation: It is based on stdio, which is
976 # impossible to combine with select (unless forcing no
978 if self
.universal_newlines
and hasattr(file, 'newlines'):
980 stdout
= self
._translate
_newlines
(stdout
)
982 stderr
= self
._translate
_newlines
(stderr
)
985 return (stdout
, stderr
)
987 def send_signal(self
, sig
):
988 """Send a signal to the process
990 if sig
== signal
.SIGTERM
:
992 elif sig
== signal
.CTRL_C_EVENT
:
993 os
.kill(self
.pid
, signal
.CTRL_C_EVENT
)
994 elif sig
== signal
.CTRL_BREAK_EVENT
:
995 os
.kill(self
.pid
, signal
.CTRL_BREAK_EVENT
)
997 raise ValueError("Only SIGTERM is supported on Windows")
1000 """Terminates the process
1002 _subprocess
.TerminateProcess(self
._handle
, 1)
1010 def _get_handles(self
, stdin
, stdout
, stderr
):
1011 """Construct and return tuple with IO objects:
1012 p2cread, p2cwrite, c2pread, c2pwrite, errread, errwrite
1014 p2cread
, p2cwrite
= None, None
1015 c2pread
, c2pwrite
= None, None
1016 errread
, errwrite
= None, None
1021 p2cread
, p2cwrite
= os
.pipe()
1022 elif isinstance(stdin
, int):
1025 # Assuming file-like object
1026 p2cread
= stdin
.fileno()
1030 elif stdout
== PIPE
:
1031 c2pread
, c2pwrite
= os
.pipe()
1032 elif isinstance(stdout
, int):
1035 # Assuming file-like object
1036 c2pwrite
= stdout
.fileno()
1040 elif stderr
== PIPE
:
1041 errread
, errwrite
= os
.pipe()
1042 elif stderr
== STDOUT
:
1044 elif isinstance(stderr
, int):
1047 # Assuming file-like object
1048 errwrite
= stderr
.fileno()
1050 return (p2cread
, p2cwrite
,
1055 def _set_cloexec_flag(self
, fd
):
1057 cloexec_flag
= fcntl
.FD_CLOEXEC
1058 except AttributeError:
1061 old
= fcntl
.fcntl(fd
, fcntl
.F_GETFD
)
1062 fcntl
.fcntl(fd
, fcntl
.F_SETFD
, old | cloexec_flag
)
1065 def _close_fds(self
, but
):
1066 if hasattr(os
, 'closerange'):
1067 os
.closerange(3, but
)
1068 os
.closerange(but
+ 1, MAXFD
)
1070 for i
in xrange(3, MAXFD
):
1079 def _execute_child(self
, args
, executable
, preexec_fn
, close_fds
,
1080 cwd
, env
, universal_newlines
,
1081 startupinfo
, creationflags
, shell
,
1085 """Execute program (POSIX version)"""
1087 if isinstance(args
, types
.StringTypes
):
1093 args
= ["/bin/sh", "-c"] + args
1095 if executable
is None:
1096 executable
= args
[0]
1098 # For transferring possible exec failure from child to parent
1099 # The first char specifies the exception type: 0 means
1100 # OSError, 1 means some other error.
1101 errpipe_read
, errpipe_write
= os
.pipe()
1104 self
._set
_cloexec
_flag
(errpipe_write
)
1106 gc_was_enabled
= gc
.isenabled()
1107 # Disable gc to avoid bug where gc -> file_dealloc ->
1108 # write to stderr -> hang. http://bugs.python.org/issue1336
1111 self
.pid
= os
.fork()
1116 self
._child
_created
= True
1120 # Close parent's pipe ends
1121 if p2cwrite
is not None:
1123 if c2pread
is not None:
1125 if errread
is not None:
1127 os
.close(errpipe_read
)
1130 if p2cread
is not None:
1132 if c2pwrite
is not None:
1133 os
.dup2(c2pwrite
, 1)
1134 if errwrite
is not None:
1135 os
.dup2(errwrite
, 2)
1137 # Close pipe fds. Make sure we don't close the same
1138 # fd more than once, or standard fds.
1139 if p2cread
is not None and p2cread
not in (0,):
1141 if c2pwrite
is not None and c2pwrite
not in (p2cread
, 1):
1143 if errwrite
is not None and errwrite
not in (p2cread
, c2pwrite
, 2):
1146 # Close all other fds, if asked for
1148 self
._close
_fds
(but
=errpipe_write
)
1157 os
.execvp(executable
, args
)
1159 os
.execvpe(executable
, args
, env
)
1162 exc_type
, exc_value
, tb
= sys
.exc_info()
1163 # Save the traceback and attach it to the exception object
1164 exc_lines
= traceback
.format_exception(exc_type
,
1167 exc_value
.child_traceback
= ''.join(exc_lines
)
1168 os
.write(errpipe_write
, pickle
.dumps(exc_value
))
1170 # This exitcode won't be reported to applications, so it
1171 # really doesn't matter what we return.
1178 # be sure the FD is closed no matter what
1179 os
.close(errpipe_write
)
1181 if p2cread
is not None and p2cwrite
is not None:
1183 if c2pwrite
is not None and c2pread
is not None:
1185 if errwrite
is not None and errread
is not None:
1188 # Wait for exec to fail or succeed; possibly raising exception
1189 # Exception limited to 1M
1190 data
= _eintr_retry_call(os
.read
, errpipe_read
, 1048576)
1192 # be sure the FD is closed no matter what
1193 os
.close(errpipe_read
)
1196 _eintr_retry_call(os
.waitpid
, self
.pid
, 0)
1197 child_exception
= pickle
.loads(data
)
1198 for fd
in (p2cwrite
, c2pread
, errread
):
1201 raise child_exception
1204 def _handle_exitstatus(self
, sts
, _WIFSIGNALED
=os
.WIFSIGNALED
,
1205 _WTERMSIG
=os
.WTERMSIG
, _WIFEXITED
=os
.WIFEXITED
,
1206 _WEXITSTATUS
=os
.WEXITSTATUS
):
1207 # This method is called (indirectly) by __del__, so it cannot
1208 # refer to anything outside of its local scope."""
1209 if _WIFSIGNALED(sts
):
1210 self
.returncode
= -_WTERMSIG(sts
)
1211 elif _WIFEXITED(sts
):
1212 self
.returncode
= _WEXITSTATUS(sts
)
1214 # Should never happen
1215 raise RuntimeError("Unknown child exit status!")
1218 def _internal_poll(self
, _deadstate
=None, _waitpid
=os
.waitpid
,
1219 _WNOHANG
=os
.WNOHANG
, _os_error
=os
.error
):
1220 """Check if child process has terminated. Returns returncode
1223 This method is called by __del__, so it cannot reference anything
1224 outside of the local scope (nor can any methods it calls).
1227 if self
.returncode
is None:
1229 pid
, sts
= _waitpid(self
.pid
, _WNOHANG
)
1231 self
._handle
_exitstatus
(sts
)
1233 if _deadstate
is not None:
1234 self
.returncode
= _deadstate
1235 return self
.returncode
1239 """Wait for child process to terminate. Returns returncode
1241 if self
.returncode
is None:
1242 pid
, sts
= _eintr_retry_call(os
.waitpid
, self
.pid
, 0)
1243 self
._handle
_exitstatus
(sts
)
1244 return self
.returncode
1247 def _communicate(self
, input):
1249 # Flush stdio buffer. This might block, if the user has
1250 # been writing to .stdin in an uncontrolled fashion.
1256 stdout
, stderr
= self
._communicate
_with
_poll
(input)
1258 stdout
, stderr
= self
._communicate
_with
_select
(input)
1260 # All data exchanged. Translate lists into strings.
1261 if stdout
is not None:
1262 stdout
= ''.join(stdout
)
1263 if stderr
is not None:
1264 stderr
= ''.join(stderr
)
1266 # Translate newlines, if requested. We cannot let the file
1267 # object do the translation: It is based on stdio, which is
1268 # impossible to combine with select (unless forcing no
1270 if self
.universal_newlines
and hasattr(file, 'newlines'):
1272 stdout
= self
._translate
_newlines
(stdout
)
1274 stderr
= self
._translate
_newlines
(stderr
)
1277 return (stdout
, stderr
)
1280 def _communicate_with_poll(self
, input):
1281 stdout
= None # Return
1282 stderr
= None # Return
1286 poller
= select
.poll()
1287 def register_and_append(file_obj
, eventmask
):
1288 poller
.register(file_obj
.fileno(), eventmask
)
1289 fd2file
[file_obj
.fileno()] = file_obj
1291 def close_unregister_and_remove(fd
):
1292 poller
.unregister(fd
)
1296 if self
.stdin
and input:
1297 register_and_append(self
.stdin
, select
.POLLOUT
)
1299 select_POLLIN_POLLPRI
= select
.POLLIN | select
.POLLPRI
1301 register_and_append(self
.stdout
, select_POLLIN_POLLPRI
)
1302 fd2output
[self
.stdout
.fileno()] = stdout
= []
1304 register_and_append(self
.stderr
, select_POLLIN_POLLPRI
)
1305 fd2output
[self
.stderr
.fileno()] = stderr
= []
1310 ready
= poller
.poll()
1311 except select
.error
, e
:
1312 if e
.args
[0] == errno
.EINTR
:
1316 for fd
, mode
in ready
:
1317 if mode
& select
.POLLOUT
:
1318 chunk
= input[input_offset
: input_offset
+ _PIPE_BUF
]
1319 input_offset
+= os
.write(fd
, chunk
)
1320 if input_offset
>= len(input):
1321 close_unregister_and_remove(fd
)
1322 elif mode
& select_POLLIN_POLLPRI
:
1323 data
= os
.read(fd
, 4096)
1325 close_unregister_and_remove(fd
)
1326 fd2output
[fd
].append(data
)
1328 # Ignore hang up or errors.
1329 close_unregister_and_remove(fd
)
1331 return (stdout
, stderr
)
1334 def _communicate_with_select(self
, input):
1337 stdout
= None # Return
1338 stderr
= None # Return
1340 if self
.stdin
and input:
1341 write_set
.append(self
.stdin
)
1343 read_set
.append(self
.stdout
)
1346 read_set
.append(self
.stderr
)
1350 while read_set
or write_set
:
1352 rlist
, wlist
, xlist
= select
.select(read_set
, write_set
, [])
1353 except select
.error
, e
:
1354 if e
.args
[0] == errno
.EINTR
:
1358 if self
.stdin
in wlist
:
1359 chunk
= input[input_offset
: input_offset
+ _PIPE_BUF
]
1360 bytes_written
= os
.write(self
.stdin
.fileno(), chunk
)
1361 input_offset
+= bytes_written
1362 if input_offset
>= len(input):
1364 write_set
.remove(self
.stdin
)
1366 if self
.stdout
in rlist
:
1367 data
= os
.read(self
.stdout
.fileno(), 1024)
1370 read_set
.remove(self
.stdout
)
1373 if self
.stderr
in rlist
:
1374 data
= os
.read(self
.stderr
.fileno(), 1024)
1377 read_set
.remove(self
.stderr
)
1380 return (stdout
, stderr
)
1383 def send_signal(self
, sig
):
1384 """Send a signal to the process
1386 os
.kill(self
.pid
, sig
)
1388 def terminate(self
):
1389 """Terminate the process with SIGTERM
1391 self
.send_signal(signal
.SIGTERM
)
1394 """Kill the process with SIGKILL
1396 self
.send_signal(signal
.SIGKILL
)
1401 # Example 1: Simple redirection: Get process list
1403 plist
= Popen(["ps"], stdout
=PIPE
).communicate()[0]
1404 print "Process list:"
1408 # Example 2: Change uid before executing child
1410 if os
.getuid() == 0:
1411 p
= Popen(["id"], preexec_fn
=lambda: os
.setuid(100))
1415 # Example 3: Connecting several subprocesses
1417 print "Looking for 'hda'..."
1418 p1
= Popen(["dmesg"], stdout
=PIPE
)
1419 p2
= Popen(["grep", "hda"], stdin
=p1
.stdout
, stdout
=PIPE
)
1420 print repr(p2
.communicate()[0])
1423 # Example 4: Catch execution error
1426 print "Trying a weird file..."
1428 print Popen(["/this/path/does/not/exist"]).communicate()
1430 if e
.errno
== errno
.ENOENT
:
1431 print "The file didn't exist. I thought so..."
1432 print "Child traceback:"
1433 print e
.child_traceback
1435 print "Error", e
.errno
1437 print >>sys
.stderr
, "Gosh. No error."
1440 def _demo_windows():
1442 # Example 1: Connecting several subprocesses
1444 print "Looking for 'PROMPT' in set output..."
1445 p1
= Popen("set", stdout
=PIPE
, shell
=True)
1446 p2
= Popen('find "PROMPT"', stdin
=p1
.stdout
, stdout
=PIPE
)
1447 print repr(p2
.communicate()[0])
1450 # Example 2: Simple execution of program
1452 print "Executing calc..."
1457 if __name__
== "__main__":