# subprocess - Subprocesses with accessible I/O streams
# For more information about this module, see PEP 324.
# Copyright (c) 2003-2005 by Peter Astrand <astrand@lysator.liu.se>
# Licensed to PSF under a Contributor Agreement.
# See http://www.python.org/2.4/license for licensing details.
r"""Subprocesses with accessible I/O streams
This module allows you to spawn processes, connect to their
input/output/error pipes, and obtain their return codes.
For a complete description of this module see the Python documentation.
call(...): Runs a command, waits for it to complete, then returns
check_call(...): Same as call() but raises CalledProcessError()
check_output(...): Same as check_call() but returns the contents of
stdout instead of a return code
Popen(...): A class for flexibly executing a command in a new process
PIPE: Special value that indicates a pipe should be created
STDOUT: Special value that indicates that stderr should go to stdout
mswindows = (sys.platform == "win32")
# Exception classes used by this module.
class CalledProcessError(Exception):
"""This exception is raised when a process run by check_call() or
check_output() returns a non-zero exit status.
def __init__(self, returncode, cmd, output=None):
self.returncode = returncode
return "Command '%s' returned non-zero exit status %d" % (self.cmd, self.returncode)
_has_poll = hasattr(select, 'poll')
# When select or poll has indicated that the file is writable,
# we can write up to _PIPE_BUF bytes without risk of blocking.
# POSIX defines PIPE_BUF as >= 512.
_PIPE_BUF = getattr(select, 'PIPE_BUF', 512)
__all__ = ["Popen", "PIPE", "STDOUT", "call", "check_call",
"check_output", "CalledProcessError"]
from _subprocess import (CREATE_NEW_CONSOLE, CREATE_NEW_PROCESS_GROUP,
STD_INPUT_HANDLE, STD_OUTPUT_HANDLE,
STD_ERROR_HANDLE, SW_HIDE,
STARTF_USESTDHANDLES, STARTF_USESHOWWINDOW)
__all__.extend(["CREATE_NEW_CONSOLE", "CREATE_NEW_PROCESS_GROUP",
"STD_INPUT_HANDLE", "STD_OUTPUT_HANDLE",
"STD_ERROR_HANDLE", "SW_HIDE",
"STARTF_USESTDHANDLES", "STARTF_USESHOWWINDOW"])
MAXFD = os.sysconf("SC_OPEN_MAX")
res = inst._internal_poll(_deadstate=sys.maxint)
# This can happen if two threads create a new Popen instance.
# It's harmless that it was already removed, so ignore.
def _eintr_retry_call(func, *args):
except (OSError, IOError) as e:
if e.errno == errno.EINTR:
# XXX This function is only used by multiprocessing and the test suite,
# but it's here so that it can be imported when Python is compiled without
def _args_from_interpreter_flags():
"""Return a list of command-line arguments reproducing the current
settings in sys.flags and sys.warnoptions."""
'dont_write_bytecode': 'B',
'ignore_environment': 'E',
for flag, opt in flag_opt_map.items():
v = getattr(sys.flags, flag)
args.append('-' + opt * v)
if getattr(sys.flags, 'hash_randomization') != 0:
for opt in sys.warnoptions:
def call(*popenargs, **kwargs):
"""Run command with arguments. Wait for command to complete, then
return the returncode attribute.
The arguments are the same as for the Popen constructor. Example:
retcode = call(["ls", "-l"])
return Popen(*popenargs, **kwargs).wait()
def check_call(*popenargs, **kwargs):
"""Run command with arguments. Wait for command to complete. If
the exit code was zero then return, otherwise raise
CalledProcessError. The CalledProcessError object will have the
return code in the returncode attribute.
The arguments are the same as for the Popen constructor. Example:
retcode = call(*popenargs, **kwargs)
raise CalledProcessError(retcode, cmd)
def check_output(*popenargs, **kwargs):
r"""Run command with arguments and return its output as a byte string.
If the exit code was non-zero it raises a CalledProcessError. The
CalledProcessError object will have the return code in the returncode
attribute and output in the output attribute.
The arguments are the same as for the Popen constructor. Example:
>>> check_output(["ls", "-l", "/dev/null"])
'crw-rw-rw- 1 root root 1, 3 Oct 18 2007 /dev/null\n'
The stdout argument is not allowed as it is used internally.
To capture standard error in the result, use stderr=STDOUT.
>>> check_output(["/bin/sh", "-c",
... "ls -l non_existent_file ; exit 0"],
'ls: non_existent_file: No such file or directory\n'
raise ValueError('stdout argument not allowed, it will be overridden.')
process = Popen(stdout=PIPE, *popenargs, **kwargs)
output, unused_err = process.communicate()
raise CalledProcessError(retcode, cmd, output=output)
Translate a sequence of arguments into a command line
string, using the same rules as the MS C runtime:
1) Arguments are delimited by white space, which is either a
2) A string surrounded by double quotation marks is
interpreted as a single argument, regardless of white space
contained within. A quoted string can be embedded in an
3) A double quotation mark preceded by a backslash is
interpreted as a literal double quotation mark.
4) Backslashes are interpreted literally, unless they
immediately precede a double quotation mark.
5) If backslashes immediately precede a double quotation mark,
every pair of backslashes is interpreted as a literal
backslash. If the number of backslashes is odd, the last
backslash escapes the next double quotation mark as
# http://msdn.microsoft.com/en-us/library/17w5ykft.aspx
# or search http://msdn.microsoft.com for
# "Parsing C++ Command-Line Arguments"
# Add a space to separate this argument from the others
needquote = (" " in arg) or ("\t" in arg) or not arg
# Don't know if we need to double yet.
result.append('\\' * len(bs_buf)*2)
# Add remaining backslashes, if any.
""" Execute a child program in a new process.
For a complete description of the arguments see the Python documentation.
args: A string, or a sequence of program arguments.
bufsize: supplied as the buffering argument to the open() function when
creating the stdin/stdout/stderr pipe file objects
executable: A replacement program to execute.
stdin, stdout and stderr: These specify the executed programs' standard
input, standard output and standard error file handles, respectively.
preexec_fn: (POSIX only) An object to be called in the child process
just before the child is executed.
close_fds: Controls closing or inheriting of file descriptors.
shell: If true, the command will be executed through the shell.
cwd: Sets the current directory before the child is executed.
env: Defines the environment variables for the new process.
universal_newlines: If true, use universal line endings for file
objects stdin, stdout and stderr.
startupinfo and creationflags (Windows only)
stdin, stdout, stderr, pid, returncode
_child_created = False # Set here since __del__ checks it
def __init__(self, args, bufsize=0, executable=None,
stdin=None, stdout=None, stderr=None,
preexec_fn=None, close_fds=False, shell=False,
cwd=None, env=None, universal_newlines=False,
startupinfo=None, creationflags=0):
"""Create new Popen instance."""
if not isinstance(bufsize, (int, long)):
raise TypeError("bufsize must be an integer")
if preexec_fn is not None:
raise ValueError("preexec_fn is not supported on Windows "
if close_fds and (stdin is not None or stdout is not None or
raise ValueError("close_fds is not supported on Windows "
"platforms if you redirect stdin/stdout/stderr")
if startupinfo is not None:
raise ValueError("startupinfo is only supported on Windows "
raise ValueError("creationflags is only supported on Windows "
self.universal_newlines = universal_newlines
# Input and output objects. The general principle is like
# p2cwrite ---stdin---> p2cread
# c2pread <--stdout--- c2pwrite
# errread <--stderr--- errwrite
# On POSIX, the child objects are file descriptors. On
# Windows, these are Windows file handles. The parent objects
# are file descriptors on both platforms. The parent objects
# are None when not using PIPEs. The child objects are None
errread, errwrite), to_close = self._get_handles(stdin, stdout, stderr)
self._execute_child(args, executable, preexec_fn, close_fds,
cwd, env, universal_newlines,
startupinfo, creationflags, shell, to_close,
# Preserve original exception in case os.close raises.
exc_type, exc_value, exc_trace = sys.exc_info()
raise exc_type, exc_value, exc_trace
p2cwrite = msvcrt.open_osfhandle(p2cwrite.Detach(), 0)
c2pread = msvcrt.open_osfhandle(c2pread.Detach(), 0)
errread = msvcrt.open_osfhandle(errread.Detach(), 0)
self.stdin = os.fdopen(p2cwrite, 'wb', bufsize)
self.stdout = os.fdopen(c2pread, 'rU', bufsize)
self.stdout = os.fdopen(c2pread, 'rb', bufsize)
self.stderr = os.fdopen(errread, 'rU', bufsize)
self.stderr = os.fdopen(errread, 'rb', bufsize)
def _translate_newlines(self, data):
data = data.replace("\r\n", "\n")
data = data.replace("\r", "\n")
def __del__(self, _maxint=sys.maxint):
# If __init__ hasn't had a chance to execute (e.g. if it
# was passed an undeclared keyword argument), we don't
# have a _child_created attribute at all.
if not self._child_created:
# We didn't get to successfully create a child process.
# In case the child hasn't been waited on, check if it's done.
self._internal_poll(_deadstate=_maxint)
if self.returncode is None and _active is not None:
# Child is still running, keep us alive until we can wait on it.
def communicate(self, input=None):
"""Interact with process: Send data to stdin. Read data from
stdout and stderr, until end-of-file is reached. Wait for
process to terminate. The optional input argument should be a
string to be sent to the child process, or None, if no data
should be sent to the child.
communicate() returns a tuple (stdout, stderr)."""
# Optimization: If we are only using one pipe, or no pipe at
# all, using select() or threads is unnecessary.
if [self.stdin, self.stdout, self.stderr].count(None) >= 2:
if e.errno != errno.EPIPE and e.errno != errno.EINVAL:
stdout = _eintr_retry_call(self.stdout.read)
stderr = _eintr_retry_call(self.stderr.read)
return self._communicate(input)
"""Check if child process has terminated. Set and return returncode
return self._internal_poll()
def _get_handles(self, stdin, stdout, stderr):
"""Construct and return tuple with IO objects:
p2cread, p2cwrite, c2pread, c2pwrite, errread, errwrite
It is recommended that you Edit text format, this type of Fix handles quite a lot in one request
