allowing the subprocess's stdin to be provided as a (byte) string.
Patch by Zack Weinberg.
*timeout* was added.
-.. function:: check_output(args, *, stdin=None, stderr=None, shell=False, universal_newlines=False, timeout=None)
+.. function:: check_output(args, *, input=None, stdin=None, stderr=None, shell=False, universal_newlines=False, timeout=None)
Run command with arguments and return its output.
in :ref:`frequently-used-arguments` (hence the use of keyword-only notation
in the abbreviated signature). The full function signature is largely the
same as that of the :class:`Popen` constructor - this functions passes all
- supplied arguments other than *timeout* directly through to that interface.
- In addition, *stdout* is not permitted as an argument, as it is used
- internally to collect the output from the subprocess.
+ supplied arguments other than *input* and *timeout* directly through to
+ that interface. In addition, *stdout* is not permitted as an argument, as
+ it is used internally to collect the output from the subprocess.
The *timeout* argument is passed to :meth:`Popen.wait`. If the timeout
expires, the child process will be killed and then waited for again. The
:exc:`TimeoutExpired` exception will be re-raised after the child process
has terminated.
+ The *input* argument is passed to :meth:`Popen.communicate` and thus to the
+ subprocess's stdin. If used it must be a byte sequence, or a string if
+ ``universal_newlines=True``. When used, the internal :class:`Popen` object
+ is automatically created with ``stdin=PIPE``, and the *stdin* argument may
+ not be used as well.
+
Examples::
>>> subprocess.check_output(["echo", "Hello World!"])
>>> subprocess.check_output(["echo", "Hello World!"], universal_newlines=True)
'Hello World!\n'
+ >>> subprocess.check_output(["sed", "-e", "s/foo/bar/"],
+ ... input=b"when in the course of fooman events\n")
+ b'when in the course of barman events\n'
+
>>> subprocess.check_output("exit 1", shell=True)
Traceback (most recent call last):
...
... shell=True)
'ls: non_existent_file: No such file or directory\n'
- .. versionadded:: 3.1
-
- ..
-
.. warning::
Invoking the system shell with ``shell=True`` can be a security hazard
read in the current process, the child process may block if it
generates enough output to the pipe to fill up the OS pipe buffer.
+ .. versionadded:: 3.1
+
.. versionchanged:: 3.3
*timeout* was added.
+ .. versionchanged:: 3.4
+ *input* was added.
.. data:: DEVNULL
>>> output = subprocess.check_output(["ls", "-l", "/dev/null"])
+ There is an additional optional argument, "input", allowing you to
+ pass a string to the subprocess's stdin. If you use this argument
+ you may not also use the Popen constructor's "stdin" argument.
Exceptions
----------
... stderr=STDOUT)
b'ls: non_existent_file: No such file or directory\n'
+ There is an additional optional argument, "input", allowing you to
+ pass a string to the subprocess's stdin. If you use this argument
+ you may not also use the Popen constructor's "stdin" argument, as
+ it too will be used internally. Example:
+
+ >>> check_output(["sed", "-e", "s/foo/bar/"],
+ ... input=b"when in the course of fooman events\n")
+ b'when in the course of barman events\n'
+
If universal_newlines=True is passed, the return value will be a
string rather than bytes.
"""
if 'stdout' in kwargs:
raise ValueError('stdout argument not allowed, it will be overridden.')
+ if 'input' in kwargs:
+ if 'stdin' in kwargs:
+ raise ValueError('stdin and input arguments may not both be used.')
+ inputdata = kwargs['input']
+ del kwargs['input']
+ kwargs['stdin'] = PIPE
+ else:
+ inputdata = None
with Popen(*popenargs, stdout=PIPE, **kwargs) as process:
try:
- output, unused_err = process.communicate(timeout=timeout)
+ output, unused_err = process.communicate(inputdata, timeout=timeout)
except TimeoutExpired:
process.kill()
output, unused_err = process.communicate()
stderr=subprocess.STDOUT)
self.assertIn(b'BDFL', output)
+ def test_check_output_stdin_arg(self):
+ # check_output() can be called with stdin set to a file
+ tf = tempfile.TemporaryFile()
+ self.addCleanup(tf.close)
+ tf.write(b'pear')
+ tf.seek(0)
+ output = subprocess.check_output(
+ [sys.executable, "-c",
+ "import sys; sys.stdout.write(sys.stdin.read().upper())"],
+ stdin=tf)
+ self.assertIn(b'PEAR', output)
+
+ def test_check_output_input_arg(self):
+ # check_output() can be called with input set to a string
+ output = subprocess.check_output(
+ [sys.executable, "-c",
+ "import sys; sys.stdout.write(sys.stdin.read().upper())"],
+ input=b'pear')
+ self.assertIn(b'PEAR', output)
+
def test_check_output_stdout_arg(self):
- # check_output() function stderr redirected to stdout
+ # check_output() refuses to accept 'stdout' argument
with self.assertRaises(ValueError) as c:
output = subprocess.check_output(
[sys.executable, "-c", "print('will not be run')"],
self.fail("Expected ValueError when stdout arg supplied.")
self.assertIn('stdout', c.exception.args[0])
+ def test_check_output_stdin_with_input_arg(self):
+ # check_output() refuses to accept 'stdin' with 'input'
+ tf = tempfile.TemporaryFile()
+ self.addCleanup(tf.close)
+ tf.write(b'pear')
+ tf.seek(0)
+ with self.assertRaises(ValueError) as c:
+ output = subprocess.check_output(
+ [sys.executable, "-c", "print('will not be run')"],
+ stdin=tf, input=b'hare')
+ self.fail("Expected ValueError when stdin and input args supplied.")
+ self.assertIn('stdin', c.exception.args[0])
+ self.assertIn('input', c.exception.args[0])
+
def test_check_output_timeout(self):
# check_output() function with timeout arg
with self.assertRaises(subprocess.TimeoutExpired) as c:
Library
-------
+- Issue #16624: `subprocess.check_output` now accepts an `input` argument,
+ allowing the subprocess's stdin to be provided as a (byte) string.
+ Patch by Zack Weinberg.
+
- Issue #17795: Reverted backwards-incompatible change in SysLogHandler with
Unix domain sockets.
projects / python / commitdiff