Added pydoc for utils.py

lib/ansible/utils.py

@@ -15,38 +15,52 @@
 # You should have received a copy of the GNU General Public License
 # along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
+###############################################################
+
 import sys
 try:
     import json
 except ImportError:
     import simplejson as json
 
+###############################################################
+# UTILITY FUNCTIONS FOR COMMAND LINE TOOLS
+###############################################################
+
 def err(msg):
+    ''' print an error message to stderr '''
     print >> sys.stderr, msg
 
 def exit(msg, rc=1):
+    ''' quit with an error to stdout and a failure code '''
     err(msg)
     sys.exit(rc)
 
 def _bigjson(result):
+    ''' format JSON output (uncompressed) '''
     return json.dumps(result, sort_keys=True, indent=4)
 
 def _json(result):
+    ''' format JSON output (compressed) '''
     return json.dumps(result, sort_keys=True)
 
 def regular_generic_msg(hostname, result, oneline, caption):
+    ''' output on the result of a module run that is not command '''
     if not oneline:
         return "%s | %s >>\n%s" % (hostname, caption, _bigjson(result))
     else:
         return "%s | %s >> %s" % (hostname, caption, _json(result))
 
 def regular_success_msg(hostname, result, oneline):
+    ''' output the result of a successful module run '''
     return regular_generic_msg(hostname, result, oneline, 'success')
 
 def regular_failure_msg(hostname, result, oneline):
+    ''' output the result of a failed module run '''
     return regular_generic_msg(hostname, result, oneline, 'FAILED')
 
 def command_generic_msg(hostname, result, oneline, caption):
+    ''' output the result of a command run '''
     rc     = result.get('rc', '0')
     stdout = result.get('stdout','')
     stderr = result.get('stderr', '')
@@ -67,18 +81,24 @@ def command_generic_msg(hostname, result, oneline, caption):
             return "%s | %s | rc=%s | (stdout) %s" % (hostname, caption, rc, stdout)
 
 def command_success_msg(hostname, result, oneline):
+    ''' output from a successful command run '''
     return command_generic_msg(hostname, result, oneline, 'success')
 
 def command_failure_msg(hostname, result, oneline):
+    ''' output from a failed command run '''
     return command_generic_msg(hostname, result, oneline, 'FAILED')
 
 def write_tree_file(hostname,buf):
+    ''' write something into treedir/hostname '''
+    # TODO: might be nice to append playbook runs per host in a similar way
+    # in which case, we'd want append mode.
     path = os.path.join(options.tree, hostname)
     fd = open(path, "w+")
     fd.write(buf)
     fd.close()
 
 def is_failed(result):
+    ''' is a given JSON result a failed result? '''
     failed = False
     rc = 0
     if type(result) == dict:
@@ -89,6 +109,7 @@ def is_failed(result):
     return failed
 
 def host_report_msg(hostname, module_name, result, oneline):
+    ''' summarize the JSON results for a particular host '''
     buf = ''
     failed = is_failed(result)
     if module_name == 'command':
@@ -104,6 +125,7 @@ def host_report_msg(hostname, module_name, result, oneline):
     return buf
 
 def dark_hosts_msg(results):
+    ''' summarize the results of all uncontactable hosts '''
     buf = ''
     if len(results['dark'].keys()) > 0:
         buf += "*** Hosts which could not be contacted or did not respond: ***"
@@ -113,15 +135,19 @@ def dark_hosts_msg(results):
     return buf
 
 def has_dark_hosts(results):
+    ''' are there any uncontactable hosts? '''
     return len(results['dark'].keys()) > 0
 
 def contacted_hosts(results):
+    ''' what are the contactable hosts? '''
     return sorted(results['contacted'])
 
 def contacted_host_result(results, hostname):
+    ''' what are the results for a given host? '''
     return results['contacted'][hostname]
 
 def prepare_writeable_dir(tree):
+    ''' make sure a directory exists and is writeable '''
     if tree != '/':
         tree = os.path.realpath(os.path.expanduser(options.tree))
     if not os.path.exists(tree):