diff options
author | Jannis Pohlmann <jannis.pohlmann@codethink.co.uk> | 2012-04-09 19:22:04 +0100 |
---|---|---|
committer | Jannis Pohlmann <jannis.pohlmann@codethink.co.uk> | 2012-04-09 19:22:04 +0100 |
commit | 03fcdcfd008806712acd7e42c7b0ebd684fac0b4 (patch) | |
tree | 3667be486ea0b37f4588c0d5f161c54d0447168e /morphlib | |
parent | 91bdcc431086d9fccbd271d21a4b6d4459e88014 (diff) | |
download | morph-03fcdcfd008806712acd7e42c7b0ebd684fac0b4.tar.gz |
Add doc strings to the CachedRepo class.
Diffstat (limited to 'morphlib')
-rw-r--r-- | morphlib/cachedrepo.py | 57 |
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: |