Added docstrings by Sue Williams, re-indented to 4 spaces / level.
diff --git a/Lib/commands.py b/Lib/commands.py
index 6471a8d..567248e 100644
--- a/Lib/commands.py
+++ b/Lib/commands.py
@@ -1,3 +1,24 @@
+"""Execute shell commands via os.popen() and return status, output.
+
+Interface summary:
+
+ import commands
+
+ outtext = commands.getoutput(cmd)
+ (exitstatus, outtext) = commands.getstatusoutput(cmd)
+ outtext = commands.getstatus(file) # returns output of "ls -ld file"
+
+A trailing newline is removed from the output string.
+
+Encapsulates the basic operation:
+
+ pipe = os.popen('{ ' + cmd + '; } 2>&1', 'r')
+ text = pipe.read()
+ sts = pipe.close()
+
+ [Note: it would be nice to add functions to interpret the exit status.]
+"""
+
# Module 'commands'
#
# Various tools for executing commands and looking at their output and status.
@@ -8,7 +29,8 @@
# Get 'ls -l' status for an object into a string
#
def getstatus(file):
- return getoutput('ls -ld' + mkarg(file))
+ """Return output of "ls -ld <file>" in a string."""
+ return getoutput('ls -ld' + mkarg(file))
# Get the output from a shell command into a string.
@@ -16,27 +38,29 @@
# Assume the command will work with '{ ... ; } 2>&1' around it..
#
def getoutput(cmd):
- return getstatusoutput(cmd)[1]
+ """Return output (stdout or stderr) of executing cmd in a shell."""
+ return getstatusoutput(cmd)[1]
# Ditto but preserving the exit status.
# Returns a pair (sts, output)
#
def getstatusoutput(cmd):
- import os
- pipe = os.popen('{ ' + cmd + '; } 2>&1', 'r')
- text = pipe.read()
- sts = pipe.close()
- if sts == None: sts = 0
- if text[-1:] == '\n': text = text[:-1]
- return sts, text
+ """Return (status, output) of executing cmd in a shell."""
+ import os
+ pipe = os.popen('{ ' + cmd + '; } 2>&1', 'r')
+ text = pipe.read()
+ sts = pipe.close()
+ if sts == None: sts = 0
+ if text[-1:] == '\n': text = text[:-1]
+ return sts, text
# Make command argument from directory and pathname (prefix space, add quotes).
#
def mk2arg(head, x):
- import os
- return mkarg(os.path.join(head, x))
+ import os
+ return mkarg(os.path.join(head, x))
# Make a shell command argument from a string.
@@ -47,12 +71,12 @@
# with backslash.
#
def mkarg(x):
- if '\'' not in x:
- return ' \'' + x + '\''
- s = ' "'
- for c in x:
- if c in '\\$"`':
- s = s + '\\'
- s = s + c
- s = s + '"'
- return s
+ if '\'' not in x:
+ return ' \'' + x + '\''
+ s = ' "'
+ for c in x:
+ if c in '\\$"`':
+ s = s + '\\'
+ s = s + c
+ s = s + '"'
+ return s