Added docstrings by Sue Williams, re-indented to 4 spaces / level.

1 files changed, 44 insertions, 20 deletions

diff --git a/Lib/commands.py b/Lib/commands.py
index 6471a8db59..567248e405 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 @@ def getstatus(file):
 # 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 @@ def mk2arg(head, x):
 # 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