Merge commit 'origin/improvements_for_mainline' into integration

* commit 'origin/improvements_for_mainline':
  Moved compatibility information of possible future release into right spot ( to the top of the release list )
  repo_tests: fixed duplicate test-method name which would redefine the previous one which never ran
  Fixed Diff class which used Commits instead of Blobs - as Blobs contain the path ( in the 'name' member variable ), the a|b_path members of Diff have been removed. Tests were adjusted and run
  git.git.Git.__init__ takes None as default argument as the execute method handles this correctly
  Fixed git.blob.Blob.blame function which would return the text-per-commit as individual characters
  improved repo documentation
  Improved head and tag object documentation slightly
  Added docs for the error module
  Added missing information to docstrings of commit and stats module
  improved git.cmd documentation
  Improved documentation on Actor and Blob

Author: Byron

CHANGES

@@ -1,6 +1,20 @@
 =======
 CHANGES
 =======
+  
+0.1.X
+=====
+( Future Release )
+General
+-------
+* See changes in Diff class as your client code needs adjustments to work with it
+
+Diff
+----
+* Members a a_commit and b_commit renamed to a_blob and b_blob - they are populated
+  with Blob objects if possible
+* Members a_path and b_path removed as this information is kept in the blobs
+
 
 0.1.6
 =====

lib/git/actor.py

@@ -7,6 +7,9 @@
 import re
 
 class Actor(object):
+    """Actors hold information about a person acting on the repository. They 
+    can be committers and authors or anything with a name and an email as 
+    mentioned in the git log entries."""
     def __init__(self, name, email):
         self.name = name
         self.email = email

lib/git/blob.py

@@ -12,6 +12,7 @@
 from commit import Commit
 
 class Blob(object):
+    """A Blob encapsulates a git blob object"""
     DEFAULT_MIME_TYPE = "text/plain"
 
     def __init__(self, repo, id, mode=None, name=None):
@@ -48,6 +49,9 @@ def size(self):
 
         Returns
             int
+           
+        NOTE
+            The size will be cached after the first access
         """
         if self._size is None:
             self._size = int(self.repo.git.cat_file(self.id, s=True).rstrip())
@@ -60,6 +64,9 @@ def data(self):
 
         Returns
             str
+            
+        NOTE
+            The data will be cached after the first access.
         """
         self.data_stored = self.data_stored or self.repo.git.cat_file(self.id, p=True, with_raw_output=True)
         return self.data_stored
@@ -71,6 +78,9 @@ def mime_type(self):
 
         Returns
             str
+            
+        NOTE
+            Defaults to 'text/plain' in case the actual file type is unknown.
         """
         guesses = None
         if self.name:
@@ -79,6 +89,10 @@ def mime_type(self):
 
     @property
     def basename(self):
+      """
+      Returns
+          The basename of the Blobs file name
+      """
       return os.path.basename(self.name)
 
     @classmethod
@@ -88,6 +102,9 @@ def blame(cls, repo, commit, file):
 
         Returns
             list: [git.Commit, list: [<line>]]
+            A list of tuples associating a Commit object with a list of lines that 
+            changed within the given commit. The Commit objects will be given in order
+            of appearance.
         """
         data = repo.git.blame(commit, '--', file, p=True)
         commits = {}
@@ -135,7 +152,7 @@ def blame(cls, repo, commit, file):
                     m = re.search(r'^\t(.*)$', line)
                     text,  = m.groups()
                     blames[-1][0] = c
-                    blames[-1][1] += text
+                    blames[-1][1].append( text )
                     info = None
 
         return blames

lib/git/cmd.py

@@ -22,19 +22,47 @@
 
 class Git(object):
     """
-    The Git class manages communication with the Git binary
+    The Git class manages communication with the Git binary.
+    
+	It provides a convenient interface to calling the Git binary, such as in::
+	
+	 g = Git( git_dir )
+	 g.init()			        # calls 'git init' program
+	 rval = g.ls_files()		# calls 'git ls-files' program
+	
+	``Debugging``
+	    Set the GIT_PYTHON_TRACE environment variable print each invocation 
+	    of the command to stdout.
+	    Set its value to 'full' to see details about the returned values.
     """
-    def __init__(self, git_dir):
+    def __init__(self, git_dir=None):
+        """
+        Initialize this instance with:
+        
+        ``git_dir``
+           Git directory we should work in. If None, we always work in the current 
+           directory as returned by os.getcwd()
+        """
         super(Git, self).__init__()
         self.git_dir = git_dir
 
     def __getattr__(self, name):
+        """
+        A convenience method as it allows to call the command as if it was 
+        an object.
+        Returns
+            Callable object that will execute call _call_process with your arguments.
+        """
         if name[:1] == '_':
             raise AttributeError(name)
         return lambda *args, **kwargs: self._call_process(name, *args, **kwargs)
 
     @property
     def get_dir(self):
+        """
+        Returns
+            Git directory we are working on
+        """
         return self.git_dir
 
     def execute(self, command,
@@ -49,7 +77,9 @@ def execute(self, command,
         the returned information (stdout)
 
         ``command``
-            The command argument list to execute
+            The command argument list to execute.
+            It should be a string, or a sequence of program arguments. The
+            program to execute is the first item in the args sequence or string.
 
         ``istream``
             Standard input filehandle passed to subprocess.Popen.
@@ -68,11 +98,18 @@ def execute(self, command,
         ``with_raw_output``
             Whether to avoid stripping off trailing whitespace.
 
-        Returns
-            str(output)                     # extended_output = False (Default)
-            tuple(int(status), str(output)) # extended_output = True
+        Returns::
+        
+         str(output)                                  # extended_output = False (Default)
+         tuple(int(status), str(stdout), str(stderr)) # extended_output = True
+        
+        Raise
+        	GitCommandError
+        
+        NOTE
+           If you add additional keyword arguments to the signature of this method, 
+           you must update the execute_kwargs tuple housed in this module.
         """
-
         if GIT_PYTHON_TRACE and not GIT_PYTHON_TRACE == 'full':
             print ' '.join(command)
 
@@ -146,7 +183,8 @@ def _call_process(self, method, *args, **kwargs):
         the result as a String
 
         ``method``
-            is the command
+            is the command. Contained "_" characters will be converted to dashes,
+            such as in 'ls_files' to call 'ls-files'.
 
         ``args``
             is the list of arguments
@@ -156,7 +194,7 @@ def _call_process(self, method, *args, **kwargs):
             This function accepts the same optional keyword arguments
             as execute().
 
-        Examples
+        Examples::
             git.rev_list('master', max_count=10, header=True)
 
         Returns

lib/git/commit.py

@@ -14,38 +14,44 @@
 import stats
 
 class Commit(LazyMixin):
+    """
+    Wraps a git Commit object.
+    
+    This class will act lazily on some of its attributes and will query the 
+    value on demand only if it involves calling the git binary.
+    """
     def __init__(self, repo, id, tree=None, author=None, authored_date=None,
                  committer=None, committed_date=None, message=None, parents=None):
         """
-        Instantiate a new Commit
+        Instantiate a new Commit. All keyword arguments taking None as default will 
+        be implicitly set if id names a valid sha. 
+        
+        The parameter documentation indicates the type of the argument after a colon ':'.
 
         ``id``
-            is the id of the commit
+            is the sha id of the commit
 
-        ``parents``
-            is a list of commit ids (will be converted into Commit instances)
+        ``parents`` : list( Commit, ... )
+            is a list of commit ids
 
-        ``tree``
-            is the correspdonding tree id (will be converted into a Tree object)
+        ``tree`` : Tree
+            is the corresponding tree id
 
-        ``author``
-            is the author string
+        ``author`` : Actor
+            is the author string ( will be implicitly converted into an Actor object )
 
-        ``authored_date``
+        ``authored_date`` : (tm_year, tm_mon, tm_mday, tm_hour, tm_min, tm_sec, tm_wday, tm_yday, tm_isdst )
             is the authored DateTime
 
-        ``committer``
+        ``committer`` : Actor
             is the committer string
 
-        ``committed_date``
+        ``committed_date`` : (tm_year, tm_mon, tm_mday, tm_hour, tm_min, tm_sec, tm_wday, tm_yday, tm_isdst)
             is the committed DateTime
 
-        ``message``
+        ``message`` : string
             is the commit message
 
-        ``parents``
-            is the list of the parents of the commit
-
         Returns
             git.Commit
         """
@@ -68,6 +74,10 @@ def __init__(self, repo, id, tree=None, author=None, authored_date=None,
                 self.tree = Tree(repo, id=tree)
 
     def __bake__(self):
+        """
+        Called by LazyMixin superclass when the first uninitialized member needs 
+        to be set as it is queried.
+        """
         temp = Commit.find_all(self.repo, self.id, max_count=1)[0]
         self.parents = temp.parents
         self.tree = temp.tree
@@ -79,10 +89,18 @@ def __bake__(self):
 
     @property
     def id_abbrev(self):
+        """
+        Returns
+            First 7 bytes of the commit's sha id as an abbreviation of the full string.
+        """
         return self.id[0:7]
 
     @property
     def summary(self):
+        """
+        Returns
+            First line of the commit message.
+        """
         return self.message.split('\n', 1)[0]
 
     @classmethod
@@ -115,10 +133,11 @@ def find_all(cls, repo, ref, path='', **kwargs):
             is the ref from which to begin (SHA1 or name)
 
         ``path``
-            is an optinal path
+            is an optinal path, if set only Commits that include the path 
+            will be considered
 
-        ``options``
-            is a Hash of optional arguments to git where
+        ``kwargs``
+            optional keyword arguments to git where
             ``max_count`` is the maximum number of commits to fetch
             ``skip`` is the number of commits to skip
 
@@ -140,7 +159,7 @@ def list_from_string(cls, repo, text):
             is the Repo
 
         ``text``
-            is the text output from the git command (raw format)
+            is the text output from the git-rev-list command (raw format)
 
         Returns
             git.Commit[]
@@ -173,7 +192,7 @@ def list_from_string(cls, repo, text):
     @classmethod
     def diff(cls, repo, a, b=None, paths=None):
         """
-        Show diffs between two trees:
+        Creates diffs between a tree and the index or between two trees:
 
         ``repo``
             is the Repo
@@ -187,10 +206,13 @@ def diff(cls, repo, a, b=None, paths=None):
             given paths.
 
         ``paths``
-            is a list of paths to limit the diff.
+            is a list of paths to limit the diff to.
 
         Returns
-            git.Diff[]
+            git.Diff[]::
+            
+             between tree and the index if only a is given
+             between two trees if a and b  are given and are commits 
         """
         paths = paths or []
 
@@ -209,6 +231,12 @@ def diff(cls, repo, a, b=None, paths=None):
 
     @property
     def diffs(self):
+        """
+        Returns
+            git.Diff[]
+            Diffs between this commit and its first parent or all changes if this 
+            commit is the first commit and has no parent.
+        """
         if not self.parents:
             d = self.repo.git.show(self.id, '-M', full_index=True, pretty='raw')
             if re.search(r'diff --git a', d):
@@ -223,6 +251,13 @@ def diffs(self):
 
     @property
     def stats(self):
+        """
+        Create a git stat from changes between this commit and its first parent 
+        or from all changes done if this is the very first commit.
+        
+        Return
+            git.Stats
+        """
         if not self.parents:
             text = self.repo.git.diff_tree(self.id, '--', numstat=True, root=True)
             text2 = ""
@@ -247,7 +282,7 @@ def actor(cls, line):
         Parse out the actor (author or committer) info
 
         Returns
-            [str (actor name and email), time (acted at time)]
+            [Actor, gmtime(acted at time)]
         """
         m = re.search(r'^.+? (.*) (\d+) .*$', line)
         actor, epoch = m.groups()