Add doc strings to the CachedRepo class.

1 files changed, 55 insertions, 2 deletions

diff --git a/morphlib/cachedrepo.py b/morphlib/cachedrepo.py
index 568839bb..df0ebf9d 100644
--- a/morphlib/cachedrepo.py
+++ b/morphlib/cachedrepo.py
@@ -24,14 +24,14 @@ import morphlib.execute
 class InvalidReferenceError(cliapp.AppException):
 
     def __init__(self, repo, ref):
-        Exception.__init__(self, '%s is an invalid reference for repo %s' %
+        Exception.__init__(self, 'Ref %s is an invalid reference for repo %s' %
                            (ref, repo))
 
 
 class UnresolvedNamedReferenceError(cliapp.AppException):
 
     def __init__(self, repo, ref):
-        Exception.__init__(self, '%s is not a SHA1 ref for repo %s' %
+        Exception.__init__(self, 'Ref %s is not a SHA1 ref for repo %s' %
                            (ref, repo))
 
 
@@ -59,16 +59,42 @@ class UpdateError(cliapp.AppException):
 
 class CachedRepo(object):
 
+    '''A locally cached Git repository with an origin remote set up.
+    
+    On instance of this class represents a locally cached version of a
+    remote Git repository. This remote repository is set up as the
+    'origin' remote.
+
+    CachedRepo objects can resolve Git refs into SHA1s. Given a SHA1
+    ref, they can also be asked to return the contents of a file via the
+    cat() method. They can furthermore check out the repository into
+    a local directory using a SHA1 ref. Last but not least, any cached
+    repo may be updated from it's origin remote using the update()
+    method.
+
+    '''
+
     def __init__(self, url, path):
+        '''Creates a new CachedRepo for a given repo URL and local path.'''
+
         self.url = url
         self.path = path
         self.ex = morphlib.execute.Execute(self.path, logging.debug)
 
     def is_valid_sha1(self, ref):
+        '''Checks whether a string is a valid SHA1.'''
+
         valid_chars = 'abcdefABCDEF0123456789'
         return len(ref) == 40 and all([x in valid_chars for x in ref])
 
     def resolve_ref(self, ref):
+        '''Attempts to resolve a Git ref into its corresponding SHA1.
+
+        Raises an InvalidReferenceError if the ref is not found in the
+        repository.
+
+        '''
+
         try:
             refs = self._show_ref(ref).split('\n')
             # split each ref line into an array, drop non-origin branches
@@ -85,6 +111,15 @@ class CachedRepo(object):
             raise InvalidReferenceError(self, ref)
 
     def cat(self, ref, filename):
+        '''Attempts to read a file given a SHA1 ref.
+
+        Raises an UnresolvedNamedReferenceError if the ref is not a SHA1
+        ref. Raises an InvalidReferenceError if the SHA1 ref is not found
+        in the repository. Raises an IOError if the requested file is not
+        found in the ref.
+
+        '''
+
         if not self.is_valid_sha1(ref):
             raise UnresolvedNamedReferenceError(self, ref)
         try:
@@ -99,6 +134,17 @@ class CachedRepo(object):
                           (filename, ref, self))
 
     def checkout(self, ref, target_dir):
+        '''Unpacks the repository in a directory and checks out a SHA1 ref.
+
+        Raises an UnresolvedNamedReferenceError if the specified ref is not
+        a SHA1 ref. Raises a CheckoutDirectoryExistsError if the target
+        directory already exists. Raises an InvalidReferenceError if the
+        ref is not found in the repository. Raises a CheckoutError if
+        something else goes wrong while copying the repository or checking
+        out the SHA1 ref.
+
+        '''
+
         if not self.is_valid_sha1(ref):
             raise UnresolvedNamedReferenceError(self, ref)
 
@@ -119,6 +165,13 @@ class CachedRepo(object):
             raise CheckoutError(self, ref, target_dir)
 
     def update(self):
+        '''Updates the cached repository using its origin remote.
+        
+        Raises an UpdateError if anything goes wrong while performing
+        the update.
+        
+        '''
+
         try:
             self._update()
         except morphlib.execute.CommandFailure: