From 2708f3a53abcdfe4c0793acd04a5b53c7372608d Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 20 Dec 2009 14:38:23 +0000 Subject: [PATCH] Recorded merge of revisions 76925 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r76925 | georg.brandl | 2009-12-20 15:33:20 +0100 (So, 20 Dez 2009) | 1 line #7381: subprocess documentation and library docstring consistency fixes. ........ --- Doc/library/subprocess.rst | 22 ++++++++++------------ Lib/subprocess.py | 29 ++++++++++++++--------------- 2 files changed, 24 insertions(+), 27 deletions(-) diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst index 93ad19c8f16..93c1ed0c1d8 100644 --- a/Doc/library/subprocess.rst +++ b/Doc/library/subprocess.rst @@ -105,10 +105,9 @@ This module defines one class called :class:`Popen`: .. note:: - If specified, *env* must provide any variables required - for the program to execute. On Windows, in order to run a - `side-by-side assembly`_ the specified *env* **must** include a valid - :envvar:`SystemRoot`. + If specified, *env* must provide any variables required for the program to + execute. On Windows, in order to run a `side-by-side assembly`_ the + specified *env* **must** include a valid :envvar:`SystemRoot`. .. _side-by-side assembly: http://en.wikipedia.org/wiki/Side-by-Side_Assembly @@ -157,7 +156,7 @@ This module also defines four shortcut functions: The arguments are the same as for the Popen constructor. Example:: - retcode = call(["ls", "-l"]) + >>> retcode = subprocess.call(["ls", "-l"]) .. warning:: @@ -176,7 +175,8 @@ This module also defines four shortcut functions: The arguments are the same as for the Popen constructor. Example:: - check_call(["ls", "-l"]) + >>> subprocess.check_call(["ls", "-l"]) + 0 .. warning:: @@ -195,15 +195,15 @@ This module also defines four shortcut functions: The arguments are the same as for the :class:`Popen` constructor. Example:: >>> subprocess.check_output(["ls", "-l", "/dev/null"]) - 'crw-rw-rw- 1 root root 1, 3 Oct 18 2007 /dev/null\n' + b'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_output( - ["/bin/sh", "-c", "ls non_existent_file ; exit 0"], - stderr=subprocess.STDOUT) - 'ls: non_existent_file: No such file or directory\n' + ... ["/bin/sh", "-c", "ls non_existent_file; exit 0"], + ... stderr=subprocess.STDOUT) + b'ls: non_existent_file: No such file or directory\n' .. versionadded:: 3.1 @@ -217,7 +217,6 @@ This module also defines four shortcut functions: stripped from the output. The exit status for the command can be interpreted according to the rules for the C function :cfunc:`wait`. Example:: - >>> import subprocess >>> subprocess.getstatusoutput('ls /bin/ls') (0, '/bin/ls') >>> subprocess.getstatusoutput('cat /bin/junk') @@ -234,7 +233,6 @@ This module also defines four shortcut functions: Like :func:`getstatusoutput`, except the exit status is ignored and the return value is a string containing the command's output. Example:: - >>> import subprocess >>> subprocess.getoutput('ls /bin/ls') '/bin/ls' diff --git a/Lib/subprocess.py b/Lib/subprocess.py index 30cbfcb684f..b1577c52669 100644 --- a/Lib/subprocess.py +++ b/Lib/subprocess.py @@ -110,7 +110,7 @@ call(*popenargs, **kwargs): The arguments are the same as for the Popen constructor. Example: - retcode = call(["ls", "-l"]) + >>> retcode = call(["ls", "-l"]) check_call(*popenargs, **kwargs): Run command with arguments. Wait for command to complete. If the @@ -120,7 +120,8 @@ check_call(*popenargs, **kwargs): The arguments are the same as for the Popen constructor. Example: - check_call(["ls", "-l"]) + >>> check_call(["ls", "-l"]) + 0 getstatusoutput(cmd): Return (status, output) of executing cmd in a shell. @@ -131,7 +132,6 @@ getstatusoutput(cmd): is stripped from the output. The exit status for the command can be interpreted according to the rules for the C function wait(). Example: - >>> import subprocess >>> subprocess.getstatusoutput('ls /bin/ls') (0, '/bin/ls') >>> subprocess.getstatusoutput('cat /bin/junk') @@ -145,20 +145,19 @@ getoutput(cmd): Like getstatusoutput(), except the exit status is ignored and the return value is a string containing the command's output. Example: - >>> import subprocess >>> subprocess.getoutput('ls /bin/ls') '/bin/ls' check_output(*popenargs, **kwargs): - Run command with arguments and return its output as a byte string. + 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. + 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: + The arguments are the same as for the Popen constructor. Example: - output = subprocess.check_output(["ls", "-l", "/dev/null"]) + >>> output = subprocess.check_output(["ls", "-l", "/dev/null"]) Exceptions @@ -438,7 +437,7 @@ def check_call(*popenargs, **kwargs): def check_output(*popenargs, **kwargs): - """Run command with arguments and return its output as a byte string. + 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 @@ -447,15 +446,15 @@ def check_output(*popenargs, **kwargs): 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' + b'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. >>> check_output(["/bin/sh", "-c", - "ls -l non_existent_file ; exit 0"], - stderr=subprocess.STDOUT) - 'ls: non_existent_file: No such file or directory\n' + ... "ls -l non_existent_file ; exit 0"], + ... stderr=subprocess.STDOUT) + b'ls: non_existent_file: No such file or directory\n' """ if 'stdout' in kwargs: raise ValueError('stdout argument not allowed, it will be overridden.')