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, bufsize)
330 p = Popen(cmd, shell=True, bufsize=bufsize,
331 stdin=PIPE, stdout=PIPE, stderr=STDOUT, close_fds=True)
332 (child_stdin, child_stdout_and_stderr) = (p.stdin, p.stdout)
337 Note: If the cmd argument to popen2 functions is a string, the command
338 is executed through /bin/sh. If it is a list, the command is directly
341 (child_stdout, child_stdin) = popen2.popen2("somestring", bufsize, mode)
343 p = Popen(["somestring"], shell=True, bufsize=bufsize
344 stdin=PIPE, stdout=PIPE, close_fds=True)
345 (child_stdout, child_stdin) = (p.stdout, p.stdin)
348 (child_stdout, child_stdin) = popen2.popen2(["mycmd", "myarg"], bufsize, mode)
350 p = Popen(["mycmd", "myarg"], bufsize=bufsize,
351 stdin=PIPE, stdout=PIPE, close_fds=True)
352 (child_stdout, child_stdin) = (p.stdout, p.stdin)
354 The popen2.Popen3 and popen2.Popen4 basically works as subprocess.Popen,
357 * subprocess.Popen raises an exception if the execution fails
358 * the capturestderr argument is replaced with the stderr argument.
359 * stdin=PIPE and stdout=PIPE must be specified.
360 * popen2 closes all filedescriptors by default, but you have to specify
361 close_fds=True with subprocess.Popen.
365 mswindows
= (sys
.platform
== "win32")
373 # Exception classes used by this module.
374 class CalledProcessError(Exception):
375 """This exception is raised when a process run by check_call() or
376 check_output() returns a non-zero exit status.
377 The exit status will be stored in the returncode attribute;
378 check_output() will also store the output in the output attribute.
380 def __init__(self
, returncode
, cmd
, output
=None):
381 self
.returncode
= returncode
385 return "Command '%s' returned non-zero exit status %d" % (self
.cmd
, self
.returncode
)
391 if 0: # <-- change this to use pywin32 instead of the _subprocess driver
393 from win32api
import GetStdHandle
, STD_INPUT_HANDLE
, \
394 STD_OUTPUT_HANDLE
, STD_ERROR_HANDLE
395 from win32api
import GetCurrentProcess
, DuplicateHandle
, \
396 GetModuleFileName
, GetVersion
397 from win32con
import DUPLICATE_SAME_ACCESS
, SW_HIDE
398 from win32pipe
import CreatePipe
399 from win32process
import CreateProcess
, STARTUPINFO
, \
400 GetExitCodeProcess
, STARTF_USESTDHANDLES
, \
401 STARTF_USESHOWWINDOW
, CREATE_NEW_CONSOLE
402 from win32process
import TerminateProcess
403 from win32event
import WaitForSingleObject
, INFINITE
, WAIT_OBJECT_0
405 from _subprocess
import *
420 __all__
= ["Popen", "PIPE", "STDOUT", "call", "check_call",
421 "check_output", "CalledProcessError"]
424 MAXFD
= os
.sysconf("SC_OPEN_MAX")
428 # True/False does not exist on 2.2.0
438 for inst
in _active
[:]:
439 if inst
._internal
_poll
(_deadstate
=sys
.maxint
) >= 0:
443 # This can happen if two threads create a new Popen instance.
444 # It's harmless that it was already removed, so ignore.
451 def call(*popenargs
, **kwargs
):
452 """Run command with arguments. Wait for command to complete, then
453 return the returncode attribute.
455 The arguments are the same as for the Popen constructor. Example:
457 retcode = call(["ls", "-l"])
459 return Popen(*popenargs
, **kwargs
).wait()
462 def check_call(*popenargs
, **kwargs
):
463 """Run command with arguments. Wait for command to complete. If
464 the exit code was zero then return, otherwise raise
465 CalledProcessError. The CalledProcessError object will have the
466 return code in the returncode attribute.
468 The arguments are the same as for the Popen constructor. Example:
470 check_call(["ls", "-l"])
472 retcode
= call(*popenargs
, **kwargs
)
474 cmd
= kwargs
.get("args")
477 raise CalledProcessError(retcode
, cmd
)
481 def check_output(*popenargs
, **kwargs
):
482 """Run command with arguments and return its output as a byte string.
484 If the exit code was non-zero it raises a CalledProcessError. The
485 CalledProcessError object will have the return code in the returncode
486 attribute and output in the output attribute.
488 The arguments are the same as for the Popen constructor. Example:
490 >>> check_output(["ls", "-l", "/dev/null"])
491 'crw-rw-rw- 1 root root 1, 3 Oct 18 2007 /dev/null\n'
493 The stdout argument is not allowed as it is used internally.
494 To capture standard error in the result, use stderr=subprocess.STDOUT.
496 >>> check_output(["/bin/sh", "-c",
497 "ls -l non_existent_file ; exit 0"],
498 stderr=subprocess.STDOUT)
499 'ls: non_existent_file: No such file or directory\n'
501 if 'stdout' in kwargs
:
502 raise ValueError('stdout argument not allowed, it will be overridden.')
503 process
= Popen(*popenargs
, stdout
=PIPE
, **kwargs
)
504 output
, unused_err
= process
.communicate()
505 retcode
= process
.poll()
507 cmd
= kwargs
.get("args")
510 raise CalledProcessError(retcode
, cmd
, output
=output
)
514 def list2cmdline(seq
):
516 Translate a sequence of arguments into a command line
517 string, using the same rules as the MS C runtime:
519 1) Arguments are delimited by white space, which is either a
522 2) A string surrounded by double quotation marks is
523 interpreted as a single argument, regardless of white space
524 or pipe characters contained within. A quoted string can be
525 embedded in an argument.
527 3) A double quotation mark preceded by a backslash is
528 interpreted as a literal double quotation mark.
530 4) Backslashes are interpreted literally, unless they
531 immediately precede a double quotation mark.
533 5) If backslashes immediately precede a double quotation mark,
534 every pair of backslashes is interpreted as a literal
535 backslash. If the number of backslashes is odd, the last
536 backslash escapes the next double quotation mark as
541 # http://msdn.microsoft.com/library/en-us/vccelng/htm/progs_12.asp
547 # Add a space to separate this argument from the others
551 needquote
= (" " in arg
) or ("\t" in arg
) or ("|" in arg
) or not arg
557 # Don't know if we need to double yet.
560 # Double backslashes.
561 result
.append('\\' * len(bs_buf
)*2)
567 result
.extend(bs_buf
)
571 # Add remaining backslashes, if any.
573 result
.extend(bs_buf
)
576 result
.extend(bs_buf
)
579 return ''.join(result
)
583 def __init__(self
, args
, bufsize
=0, executable
=None,
584 stdin
=None, stdout
=None, stderr
=None,
585 preexec_fn
=None, close_fds
=False, shell
=False,
586 cwd
=None, env
=None, universal_newlines
=False,
587 startupinfo
=None, creationflags
=0):
588 """Create new Popen instance."""
591 self
._child
_created
= False
592 if not isinstance(bufsize
, (int, long)):
593 raise TypeError("bufsize must be an integer")
596 if preexec_fn
is not None:
597 raise ValueError("preexec_fn is not supported on Windows "
599 if close_fds
and (stdin
is not None or stdout
is not None or
601 raise ValueError("close_fds is not supported on Windows "
602 "platforms if you redirect stdin/stdout/stderr")
605 if startupinfo
is not None:
606 raise ValueError("startupinfo is only supported on Windows "
608 if creationflags
!= 0:
609 raise ValueError("creationflags is only supported on Windows "
616 self
.returncode
= None
617 self
.universal_newlines
= universal_newlines
619 # Input and output objects. The general principle is like
624 # p2cwrite ---stdin---> p2cread
625 # c2pread <--stdout--- c2pwrite
626 # errread <--stderr--- errwrite
628 # On POSIX, the child objects are file descriptors. On
629 # Windows, these are Windows file handles. The parent objects
630 # are file descriptors on both platforms. The parent objects
631 # are None when not using PIPEs. The child objects are None
632 # when not redirecting.
636 errread
, errwrite
) = self
._get
_handles
(stdin
, stdout
, stderr
)
638 self
._execute
_child
(args
, executable
, preexec_fn
, close_fds
,
639 cwd
, env
, universal_newlines
,
640 startupinfo
, creationflags
, shell
,
646 if p2cwrite
is not None:
647 p2cwrite
= msvcrt
.open_osfhandle(p2cwrite
.Detach(), 0)
648 if c2pread
is not None:
649 c2pread
= msvcrt
.open_osfhandle(c2pread
.Detach(), 0)
650 if errread
is not None:
651 errread
= msvcrt
.open_osfhandle(errread
.Detach(), 0)
653 if p2cwrite
is not None:
654 self
.stdin
= os
.fdopen(p2cwrite
, 'wb', bufsize
)
655 if c2pread
is not None:
656 if universal_newlines
:
657 self
.stdout
= os
.fdopen(c2pread
, 'rU', bufsize
)
659 self
.stdout
= os
.fdopen(c2pread
, 'rb', bufsize
)
660 if errread
is not None:
661 if universal_newlines
:
662 self
.stderr
= os
.fdopen(errread
, 'rU', bufsize
)
664 self
.stderr
= os
.fdopen(errread
, 'rb', bufsize
)
667 def _translate_newlines(self
, data
):
668 data
= data
.replace("\r\n", "\n")
669 data
= data
.replace("\r", "\n")
673 def __del__(self
, sys
=sys
):
674 if not self
._child
_created
:
675 # We didn't get to successfully create a child process.
677 # In case the child hasn't been waited on, check if it's done.
678 self
._internal
_poll
(_deadstate
=sys
.maxint
)
679 if self
.returncode
is None and _active
is not None:
680 # Child is still running, keep us alive until we can wait on it.
684 def communicate(self
, input=None):
685 """Interact with process: Send data to stdin. Read data from
686 stdout and stderr, until end-of-file is reached. Wait for
687 process to terminate. The optional input argument should be a
688 string to be sent to the child process, or None, if no data
689 should be sent to the child.
691 communicate() returns a tuple (stdout, stderr)."""
693 # Optimization: If we are only using one pipe, or no pipe at
694 # all, using select() or threads is unnecessary.
695 if [self
.stdin
, self
.stdout
, self
.stderr
].count(None) >= 2:
700 self
.stdin
.write(input)
703 stdout
= self
.stdout
.read()
706 stderr
= self
.stderr
.read()
709 return (stdout
, stderr
)
711 return self
._communicate
(input)
715 return self
._internal
_poll
()
722 def _get_handles(self
, stdin
, stdout
, stderr
):
723 """Construct and return tupel with IO objects:
724 p2cread, p2cwrite, c2pread, c2pwrite, errread, errwrite
726 if stdin
is None and stdout
is None and stderr
is None:
727 return (None, None, None, None, None, None)
729 p2cread
, p2cwrite
= None, None
730 c2pread
, c2pwrite
= None, None
731 errread
, errwrite
= None, None
734 p2cread
= GetStdHandle(STD_INPUT_HANDLE
)
736 p2cread
, _
= CreatePipe(None, 0)
738 p2cread
, p2cwrite
= CreatePipe(None, 0)
739 elif isinstance(stdin
, int):
740 p2cread
= msvcrt
.get_osfhandle(stdin
)
742 # Assuming file-like object
743 p2cread
= msvcrt
.get_osfhandle(stdin
.fileno())
744 p2cread
= self
._make
_inheritable
(p2cread
)
747 c2pwrite
= GetStdHandle(STD_OUTPUT_HANDLE
)
749 _
, c2pwrite
= CreatePipe(None, 0)
751 c2pread
, c2pwrite
= CreatePipe(None, 0)
752 elif isinstance(stdout
, int):
753 c2pwrite
= msvcrt
.get_osfhandle(stdout
)
755 # Assuming file-like object
756 c2pwrite
= msvcrt
.get_osfhandle(stdout
.fileno())
757 c2pwrite
= self
._make
_inheritable
(c2pwrite
)
760 errwrite
= GetStdHandle(STD_ERROR_HANDLE
)
762 _
, errwrite
= CreatePipe(None, 0)
764 errread
, errwrite
= CreatePipe(None, 0)
765 elif stderr
== STDOUT
:
767 elif isinstance(stderr
, int):
768 errwrite
= msvcrt
.get_osfhandle(stderr
)
770 # Assuming file-like object
771 errwrite
= msvcrt
.get_osfhandle(stderr
.fileno())
772 errwrite
= self
._make
_inheritable
(errwrite
)
774 return (p2cread
, p2cwrite
,
779 def _make_inheritable(self
, handle
):
780 """Return a duplicate of handle, which is inheritable"""
781 return DuplicateHandle(GetCurrentProcess(), handle
,
782 GetCurrentProcess(), 0, 1,
783 DUPLICATE_SAME_ACCESS
)
786 def _find_w9xpopen(self
):
787 """Find and return absolut path to w9xpopen.exe"""
788 w9xpopen
= os
.path
.join(os
.path
.dirname(GetModuleFileName(0)),
790 if not os
.path
.exists(w9xpopen
):
791 # Eeek - file-not-found - possibly an embedding
792 # situation - see if we can locate it in sys.exec_prefix
793 w9xpopen
= os
.path
.join(os
.path
.dirname(sys
.exec_prefix
),
795 if not os
.path
.exists(w9xpopen
):
796 raise RuntimeError("Cannot locate w9xpopen.exe, which is "
797 "needed for Popen to work with your "
798 "shell or platform.")
802 def _execute_child(self
, args
, executable
, preexec_fn
, close_fds
,
803 cwd
, env
, universal_newlines
,
804 startupinfo
, creationflags
, shell
,
808 """Execute program (MS Windows version)"""
810 if not isinstance(args
, types
.StringTypes
):
811 args
= list2cmdline(args
)
813 # Process startup details
814 if startupinfo
is None:
815 startupinfo
= STARTUPINFO()
816 if None not in (p2cread
, c2pwrite
, errwrite
):
817 startupinfo
.dwFlags |
= STARTF_USESTDHANDLES
818 startupinfo
.hStdInput
= p2cread
819 startupinfo
.hStdOutput
= c2pwrite
820 startupinfo
.hStdError
= errwrite
823 startupinfo
.dwFlags |
= STARTF_USESHOWWINDOW
824 startupinfo
.wShowWindow
= SW_HIDE
825 comspec
= os
.environ
.get("COMSPEC", "cmd.exe")
826 args
= comspec
+ " /c " + args
827 if (GetVersion() >= 0x80000000L
or
828 os
.path
.basename(comspec
).lower() == "command.com"):
829 # Win9x, or using command.com on NT. We need to
830 # use the w9xpopen intermediate program. For more
831 # information, see KB Q150956
832 # (http://web.archive.org/web/20011105084002/http://support.microsoft.com/support/kb/articles/Q150/9/56.asp)
833 w9xpopen
= self
._find
_w
9xpopen
()
834 args
= '"%s" %s' % (w9xpopen
, args
)
835 # Not passing CREATE_NEW_CONSOLE has been known to
836 # cause random failures on win9x. Specifically a
837 # dialog: "Your program accessed mem currently in
838 # use at xxx" and a hopeful warning about the
839 # stability of your system. Cost is Ctrl+C wont
841 creationflags |
= CREATE_NEW_CONSOLE
845 hp
, ht
, pid
, tid
= CreateProcess(executable
, args
,
846 # no special security
853 except pywintypes
.error
, e
:
854 # Translate pywintypes.error to WindowsError, which is
855 # a subclass of OSError. FIXME: We should really
856 # translate errno using _sys_errlist (or simliar), but
857 # how can this be done from Python?
858 raise WindowsError(*e
.args
)
860 # Retain the process handle, but close the thread handle
861 self
._child
_created
= True
866 # Child is launched. Close the parent's copy of those pipe
867 # handles that only the child should have open. You need
868 # to make sure that no handles to the write end of the
869 # output pipe are maintained in this process or else the
870 # pipe will not close when the child process exits and the
871 # ReadFile will hang.
872 if p2cread
is not None:
874 if c2pwrite
is not None:
876 if errwrite
is not None:
880 def _internal_poll(self
, _deadstate
=None):
881 """Check if child process has terminated. Returns returncode
883 if self
.returncode
is None:
884 if WaitForSingleObject(self
._handle
, 0) == WAIT_OBJECT_0
:
885 self
.returncode
= GetExitCodeProcess(self
._handle
)
886 return self
.returncode
890 """Wait for child process to terminate. Returns returncode
892 if self
.returncode
is None:
893 obj
= WaitForSingleObject(self
._handle
, INFINITE
)
894 self
.returncode
= GetExitCodeProcess(self
._handle
)
895 return self
.returncode
898 def _readerthread(self
, fh
, buffer):
899 buffer.append(fh
.read())
902 def _communicate(self
, input):
903 stdout
= None # Return
904 stderr
= None # Return
908 stdout_thread
= threading
.Thread(target
=self
._readerthread
,
909 args
=(self
.stdout
, stdout
))
910 stdout_thread
.setDaemon(True)
911 stdout_thread
.start()
914 stderr_thread
= threading
.Thread(target
=self
._readerthread
,
915 args
=(self
.stderr
, stderr
))
916 stderr_thread
.setDaemon(True)
917 stderr_thread
.start()
920 if input is not None:
921 self
.stdin
.write(input)
929 # All data exchanged. Translate lists into strings.
930 if stdout
is not None:
932 if stderr
is not None:
935 # Translate newlines, if requested. We cannot let the file
936 # object do the translation: It is based on stdio, which is
937 # impossible to combine with select (unless forcing no
939 if self
.universal_newlines
and hasattr(file, 'newlines'):
941 stdout
= self
._translate
_newlines
(stdout
)
943 stderr
= self
._translate
_newlines
(stderr
)
946 return (stdout
, stderr
)
948 def send_signal(self
, sig
):
949 """Send a signal to the process
951 if sig
== signal
.SIGTERM
:
954 raise ValueError("Only SIGTERM is supported on Windows")
957 """Terminates the process
959 TerminateProcess(self
._handle
, 1)
967 def _get_handles(self
, stdin
, stdout
, stderr
):
968 """Construct and return tupel with IO objects:
969 p2cread, p2cwrite, c2pread, c2pwrite, errread, errwrite
971 p2cread
, p2cwrite
= None, None
972 c2pread
, c2pwrite
= None, None
973 errread
, errwrite
= None, None
978 p2cread
, p2cwrite
= os
.pipe()
979 elif isinstance(stdin
, int):
982 # Assuming file-like object
983 p2cread
= stdin
.fileno()
988 c2pread
, c2pwrite
= os
.pipe()
989 elif isinstance(stdout
, int):
992 # Assuming file-like object
993 c2pwrite
= stdout
.fileno()
998 errread
, errwrite
= os
.pipe()
999 elif stderr
== STDOUT
:
1001 elif isinstance(stderr
, int):
1004 # Assuming file-like object
1005 errwrite
= stderr
.fileno()
1007 return (p2cread
, p2cwrite
,
1012 def _set_cloexec_flag(self
, fd
):
1014 cloexec_flag
= fcntl
.FD_CLOEXEC
1015 except AttributeError:
1018 old
= fcntl
.fcntl(fd
, fcntl
.F_GETFD
)
1019 fcntl
.fcntl(fd
, fcntl
.F_SETFD
, old | cloexec_flag
)
1022 def _close_fds(self
, but
):
1023 os
.closerange(3, but
)
1024 os
.closerange(but
+ 1, MAXFD
)
1027 def _execute_child(self
, args
, executable
, preexec_fn
, close_fds
,
1028 cwd
, env
, universal_newlines
,
1029 startupinfo
, creationflags
, shell
,
1033 """Execute program (POSIX version)"""
1035 if isinstance(args
, types
.StringTypes
):
1041 args
= ["/bin/sh", "-c"] + args
1043 if executable
is None:
1044 executable
= args
[0]
1046 # For transferring possible exec failure from child to parent
1047 # The first char specifies the exception type: 0 means
1048 # OSError, 1 means some other error.
1049 errpipe_read
, errpipe_write
= os
.pipe()
1050 self
._set
_cloexec
_flag
(errpipe_write
)
1052 gc_was_enabled
= gc
.isenabled()
1053 # Disable gc to avoid bug where gc -> file_dealloc ->
1054 # write to stderr -> hang. http://bugs.python.org/issue1336
1057 self
.pid
= os
.fork()
1062 self
._child
_created
= True
1066 # Close parent's pipe ends
1067 if p2cwrite
is not None:
1069 if c2pread
is not None:
1071 if errread
is not None:
1073 os
.close(errpipe_read
)
1076 if p2cread
is not None:
1078 if c2pwrite
is not None:
1079 os
.dup2(c2pwrite
, 1)
1080 if errwrite
is not None:
1081 os
.dup2(errwrite
, 2)
1083 # Close pipe fds. Make sure we don't close the same
1084 # fd more than once, or standard fds.
1085 if p2cread
is not None and p2cread
not in (0,):
1087 if c2pwrite
is not None and c2pwrite
not in (p2cread
, 1):
1089 if errwrite
is not None and errwrite
not in (p2cread
, c2pwrite
, 2):
1092 # Close all other fds, if asked for
1094 self
._close
_fds
(but
=errpipe_write
)
1103 os
.execvp(executable
, args
)
1105 os
.execvpe(executable
, args
, env
)
1108 exc_type
, exc_value
, tb
= sys
.exc_info()
1109 # Save the traceback and attach it to the exception object
1110 exc_lines
= traceback
.format_exception(exc_type
,
1113 exc_value
.child_traceback
= ''.join(exc_lines
)
1114 os
.write(errpipe_write
, pickle
.dumps(exc_value
))
1116 # This exitcode won't be reported to applications, so it
1117 # really doesn't matter what we return.
1123 os
.close(errpipe_write
)
1124 if p2cread
is not None and p2cwrite
is not None:
1126 if c2pwrite
is not None and c2pread
is not None:
1128 if errwrite
is not None and errread
is not None:
1131 # Wait for exec to fail or succeed; possibly raising exception
1132 data
= os
.read(errpipe_read
, 1048576) # Exceptions limited to 1 MB
1133 os
.close(errpipe_read
)
1135 os
.waitpid(self
.pid
, 0)
1136 child_exception
= pickle
.loads(data
)
1137 for fd
in (p2cwrite
, c2pread
, errread
):
1140 raise child_exception
1143 def _handle_exitstatus(self
, sts
):
1144 if os
.WIFSIGNALED(sts
):
1145 self
.returncode
= -os
.WTERMSIG(sts
)
1146 elif os
.WIFEXITED(sts
):
1147 self
.returncode
= os
.WEXITSTATUS(sts
)
1149 # Should never happen
1150 raise RuntimeError("Unknown child exit status!")
1153 def _internal_poll(self
, _deadstate
=None):
1154 """Check if child process has terminated. Returns returncode
1156 if self
.returncode
is None:
1158 pid
, sts
= os
.waitpid(self
.pid
, os
.WNOHANG
)
1160 self
._handle
_exitstatus
(sts
)
1162 if _deadstate
is not None:
1163 self
.returncode
= _deadstate
1164 return self
.returncode
1168 """Wait for child process to terminate. Returns returncode
1170 if self
.returncode
is None:
1171 pid
, sts
= os
.waitpid(self
.pid
, 0)
1172 self
._handle
_exitstatus
(sts
)
1173 return self
.returncode
1176 def _communicate(self
, input):
1179 stdout
= None # Return
1180 stderr
= None # Return
1183 # Flush stdio buffer. This might block, if the user has
1184 # been writing to .stdin in an uncontrolled fashion.
1187 write_set
.append(self
.stdin
)
1191 read_set
.append(self
.stdout
)
1194 read_set
.append(self
.stderr
)
1198 while read_set
or write_set
:
1200 rlist
, wlist
, xlist
= select
.select(read_set
, write_set
, [])
1201 except select
.error
, e
:
1202 if e
.args
[0] == errno
.EINTR
:
1206 if self
.stdin
in wlist
:
1207 # When select has indicated that the file is writable,
1208 # we can write up to PIPE_BUF bytes without risk
1209 # blocking. POSIX defines PIPE_BUF >= 512
1210 chunk
= input[input_offset
: input_offset
+ 512]
1211 bytes_written
= os
.write(self
.stdin
.fileno(), chunk
)
1212 input_offset
+= bytes_written
1213 if input_offset
>= len(input):
1215 write_set
.remove(self
.stdin
)
1217 if self
.stdout
in rlist
:
1218 data
= os
.read(self
.stdout
.fileno(), 1024)
1221 read_set
.remove(self
.stdout
)
1224 if self
.stderr
in rlist
:
1225 data
= os
.read(self
.stderr
.fileno(), 1024)
1228 read_set
.remove(self
.stderr
)
1231 # All data exchanged. Translate lists into strings.
1232 if stdout
is not None:
1233 stdout
= ''.join(stdout
)
1234 if stderr
is not None:
1235 stderr
= ''.join(stderr
)
1237 # Translate newlines, if requested. We cannot let the file
1238 # object do the translation: It is based on stdio, which is
1239 # impossible to combine with select (unless forcing no
1241 if self
.universal_newlines
and hasattr(file, 'newlines'):
1243 stdout
= self
._translate
_newlines
(stdout
)
1245 stderr
= self
._translate
_newlines
(stderr
)
1248 return (stdout
, stderr
)
1250 def send_signal(self
, sig
):
1251 """Send a signal to the process
1253 os
.kill(self
.pid
, sig
)
1255 def terminate(self
):
1256 """Terminate the process with SIGTERM
1258 self
.send_signal(signal
.SIGTERM
)
1261 """Kill the process with SIGKILL
1263 self
.send_signal(signal
.SIGKILL
)
1268 # Example 1: Simple redirection: Get process list
1270 plist
= Popen(["ps"], stdout
=PIPE
).communicate()[0]
1271 print "Process list:"
1275 # Example 2: Change uid before executing child
1277 if os
.getuid() == 0:
1278 p
= Popen(["id"], preexec_fn
=lambda: os
.setuid(100))
1282 # Example 3: Connecting several subprocesses
1284 print "Looking for 'hda'..."
1285 p1
= Popen(["dmesg"], stdout
=PIPE
)
1286 p2
= Popen(["grep", "hda"], stdin
=p1
.stdout
, stdout
=PIPE
)
1287 print repr(p2
.communicate()[0])
1290 # Example 4: Catch execution error
1293 print "Trying a weird file..."
1295 print Popen(["/this/path/does/not/exist"]).communicate()
1297 if e
.errno
== errno
.ENOENT
:
1298 print "The file didn't exist. I thought so..."
1299 print "Child traceback:"
1300 print e
.child_traceback
1302 print "Error", e
.errno
1304 print >>sys
.stderr
, "Gosh. No error."
1307 def _demo_windows():
1309 # Example 1: Connecting several subprocesses
1311 print "Looking for 'PROMPT' in set output..."
1312 p1
= Popen("set", stdout
=PIPE
, shell
=True)
1313 p2
= Popen('find "PROMPT"', stdin
=p1
.stdout
, stdout
=PIPE
)
1314 print repr(p2
.communicate()[0])
1317 # Example 2: Simple execution of program
1319 print "Executing calc..."
1324 if __name__
== "__main__":