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

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,6 +29,7 @@
 # Get 'ls -l' status for an object into a string
 #
 def getstatus(file):
+    """Return output of "ls -ld <file>" in a string."""
     return getoutput('ls -ld' + mkarg(file))
 
 
@@ -16,6 +38,7 @@ def getstatus(file):
 # Assume the command will work with '{ ... ; } 2>&1' around it..
 #
 def getoutput(cmd):
+    """Return output (stdout or stderr) of executing cmd in a shell."""
     return getstatusoutput(cmd)[1]
 
 
@@ -23,6 +46,7 @@ def getoutput(cmd):
 # Returns a pair (sts, output)
 #
 def getstatusoutput(cmd):
+    """Return (status, output) of executing cmd in a shell."""
     import os
     pipe = os.popen('{ ' + cmd + '; } 2>&1', 'r')
     text = pipe.read()