* doc strings for util module

pisi/util.py

@@ -13,21 +13,20 @@ class FileError(Exception):
 class UtilError(Exception):
     pass
 
-# shorthand to check if a file exists
 def check_file(file, mode = os.F_OK):
+    "shorthand to check if a file exists"
     if not os.access(file, mode):
         raise FileError("File " + file + " not found")
 
-# check if directory exists, and create if it doesn't
-# works recursively
-# FIXME: could have a better name
 def check_dir(dir):
+    """check if directory exists, and create if it doesn't.
+    works recursively"""
     dir = dir.strip().rstrip("/")
     if not os.access(dir, os.F_OK):
         os.makedirs(dir)
 
 def clean_dir(top):
-    """Remove all content of a directory (top)"""
+    "Remove all content of a directory (top)"
     for root, dirs, files in os.walk(top, topdown=False):
 	for name in files:
 	    os.remove(os.path.join(root, name))
@@ -35,9 +34,9 @@ def clean_dir(top):
 	    os.rmdir(os.path.join(root, name))
 
 
-# calculate the size of files under a dir
-# based on the os module example
 def dir_size(dir):
+    """ calculate the size of files under a dir
+    based on the os module example"""
     from os.path import join, getsize
     def sizes():
         for root, dirs, files in os.walk(dir):
@@ -45,26 +44,29 @@ def dir_size(dir):
             yield sum(getsize(join(root, name)) for name in files)
     return sum( sizes() )
 
-def copy_file(s,d):
-    check_file(s)
-    check_dir(os.path.dirname(d))
-    fs = file(s, 'rb')
-    fd = file(d, 'wb')
+def copy_file(src,dest):
+    """copy source file to destination file"""
+    check_file(src)
+    check_dir(os.path.dirname(dest))
+    fs = file(src, 'rb')
+    fd = file(dest, 'wb')
     for l in fs:
         fd.write(l)
 
-def copy_dir():
+def copy_dir(src, dest):
+    """copy source dir to destination dir recursively"""
     raise UtilError("not implemented")
 
 def md5_file(filename):
+    """calculate md5 hash of filename"""
     m = md5.new()
     f = file(filename, 'rb')
     for l in f:
         m.update(l)
     return m.hexdigest()
 
-# run a command non-interactively
 def run_batch(cmd):
+    """run command non-interactively and report return value and output"""
     ui.info('running ' + cmd)
     a = os.popen(cmd)
     lines = a.readlines()
@@ -75,6 +77,6 @@ def run_batch(cmd):
       ui.error('ERROR: executing command: ' + cmd + '\n' + strlist(lines))
     return (successful,lines)
 
-# print a list
 def strlist(l):
+    """concatenate string reps of l's elements"""
     return string.join(map(lambda x: str(x) + ' ', l))