Merge branch 'doc_enhancements' into fixes

Author: Byron

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 = {}

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=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
         """
@@ -74,6 +80,10 @@ def __ne__(self, other):
         return self.id != other.id
 
     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
@@ -85,10 +95,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
@@ -122,10 +140,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
 
@@ -147,7 +166,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[]
@@ -180,7 +199,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
@@ -194,10 +213,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 []
 
@@ -216,6 +238,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):
@@ -230,6 +258,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 = ""
@@ -254,7 +289,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()

lib/git/errors.py

@@ -3,14 +3,24 @@
 #
 # This module is part of GitPython and is released under
 # the BSD License: http://www.opensource.org/licenses/bsd-license.php
+"""
+Module containing all exceptions thrown througout the git package,
+"""
 
 class InvalidGitRepositoryError(Exception):
-    pass
+    """
+    Thrown if the given repository appears to have an invalid format. 
+    """
 
 class NoSuchPathError(Exception):
-    pass
+    """
+    Thrown if a path could not be access by the system.
+    """
 
 class GitCommandError(Exception):
+    """
+    Thrown if execution of the git command fails with non-zero status code.
+    """
     def __init__(self, command, status, stderr=None):
         self.stderr = stderr
         self.status = status