Adds a subprocess.check_call_output() function to return the output from a

process on success or raise an exception on error.

1 files changed, 24 insertions, 0 deletions

diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst
index 42e50f6..468892a 100644
--- a/Doc/library/subprocess.rst
+++ b/Doc/library/subprocess.rst
@@ -149,6 +149,30 @@ This module also defines two shortcut functions:
    .. versionadded:: 2.5
 
 
+.. function:: check_call_output(*popenargs, **kwargs)
+
+   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:
+
+      >>> subprocess.check_call_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=subprocess.STDOUT.
+
+      >>> subprocess.check_call_output(
+              ["/bin/sh", "-c", "ls non_existant_file ; exit 0"],
+              stderr=subprocess.STDOUT)
+      'ls: non_existant_file: No such file or directory\n'
+
+   .. versionadded:: 2.7
+
+
 Exceptions
 ^^^^^^^^^^