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

diff --git a/Lib/commands.py b/Lib/commands.py
index 6471a8db594c29e1df79dbce42b3b26355be54d9..567248e405690f932ed4bad8a0a4ef97de28ad5b 100644 (file)
--- 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