# HG changeset patch
# User Steve Losh <steve@stevelosh.com>
# Date 1251324525 14400
# Node ID 61803d906c96f9068a2964490db0c8f0e8e53cf3
# Parent  34c00c0b1d6d5df638f9d47a0d61e307f3559289
Add some docstrings.

diff -r 34c00c0b1d6d -r 61803d906c96 t.py
--- a/t.py	Wed Aug 26 17:43:13 2009 -0400
+++ b/t.py	Wed Aug 26 18:08:45 2009 -0400
@@ -12,6 +12,13 @@
     pass
 
 _hash = lambda s: hashlib.sha1(s).hexdigest()
+def _hash(s):
+    """Return a hash of the given string for use as an id.
+    
+    Currently SHA1 hashing is used.  It should be plenty for our purposes.
+    
+    """
+    return hashlib.sha1(s).hexdigest()
 
 def _task_from_taskline(taskline):
     """Parse a taskline (from a task file) and return a task.
@@ -35,7 +42,7 @@
     return task
 
 def _prefixes(ids):
-    """return a mapping of ids to prefixes
+    """Return a mapping of ids to prefixes.
     
     Each prefix will be the shortest possible substring of the ID that
     can uniquely identify it among the given group of IDs.
@@ -52,8 +59,10 @@
                 break
     return prefixes
 
+
 class TaskDict(object):
     def __init__(self, taskdir='.', name='tasks'):
+        """Initialize by reading the task files, if they exist."""
         self.tasks = {}
         self.done = {}
         self.name = name
@@ -71,10 +80,12 @@
                         getattr(self, kind)[task['id']] = task
     
     def add_task(self, text):
+        """Add a new, unfinished task with the given summary text."""
         id = _hash(text)
         self.tasks[id] = {'id': id, 'text': text}
     
     def write(self):
+        """Flush the finished and unfinished tasks to the files on disk."""
         filemap = (('tasks', self.name), ('done', '.%s.done' % self.name))
         for kind, filename in filemap:
             path = os.path.join(os.path.expanduser(self.taskdir), filename)
@@ -89,6 +100,7 @@
                     tfile.write('%s | %s\n' % (task['text'], meta_str))
     
     def print_list(self, kind='tasks', verbose=False):
+        """Print out a nicely formatted list of unfinished tasks."""
         tasks = dict(getattr(self, kind).items())
         label = 'prefix' if not verbose else 'id'
         if not verbose:
@@ -99,6 +111,12 @@
             print ('%-' + str(plen) + 's - %s') % (t[label], t['text'])
     
     def finish_task(self, prefix):
+        """Mark the task with the given prefix as finished.
+        
+        If more than one task matches the prefix an AmbiguousPrefix exception
+        will be raised.
+        
+        """
         matched = filter(lambda id: id.startswith(prefix), self.tasks.keys())
         if len(matched) == 1:
             task = self.tasks.pop(matched[0])
@@ -107,6 +125,7 @@
             raise AmbiguousPrefix
     
     def delete_finished(self):
+        """Remove all finished tasks."""
         self.done = {}
     
 
@@ -138,6 +157,7 @@
                       help="print more detailed output (full task ids, etc)")
     return parser
 
+
 if __name__ == '__main__':
     (options, args) = build_parser().parse_args()