More docstrings, test coverage.

dulwich/index.py

@@ -258,4 +258,9 @@ def commit_tree(object_store, blobs):
 
 
 def commit_index(object_store, index):
+    """Create a new tree from an index.
+
+    :param object_store: Object store to save the tree in
+    :param index: Index file
+    """
     return commit_tree(object_store, index.iterblobs())

dulwich/object_store.py

@@ -132,8 +132,12 @@ class BaseObjectStore(object):
         """
         return ObjectStoreGraphWalker(heads, lambda sha: self[sha].parents)
 
-
     def generate_pack_contents(self, have, want):
+        """Iterate over the contents of a pack file.
+
+        :param have: List of SHA1s of objects that should not be sent
+        :param want: List of SHA1s of objects that should be sent
+        """
         return self.iter_shas(self.find_missing_objects(have, want))
 
 
@@ -319,15 +323,17 @@ class DiskObjectStore(BaseObjectStore):
     def add_object(self, obj):
         """Add a single object to this object store.
 
+        :param obj: Object to add
         """
         self._add_shafile(obj.id, obj)
 
     def add_objects(self, objects):
         """Add a set of objects to this object store.
 
-        :param objects: Iterable over a list of objects.
+        :param objects: Iterable over objects, should support __len__.
         """
         if len(objects) == 0:
+            # Don't bother writing an empty pack file
             return
         f, commit = self.add_pack()
         write_pack_data(f, objects, len(objects))
@@ -335,12 +341,14 @@ class DiskObjectStore(BaseObjectStore):
 
 
 class MemoryObjectStore(BaseObjectStore):
+    """Object store that keeps all objects in memory."""
 
     def __init__(self):
         super(MemoryObjectStore, self).__init__()
         self._data = {}
 
     def __contains__(self, sha):
+        """Check if the object with a particular SHA is present."""
         return sha in self._data
 
     def __iter__(self):
@@ -403,19 +411,27 @@ class ObjectStoreIterator(ObjectIterator):
     """ObjectIterator that works on top of an ObjectStore."""
 
     def __init__(self, store, sha_iter):
+        """Create a new ObjectIterator.
+
+        :param store: Object store to retrieve from
+        :param sha_iter: Iterator over (sha, path) tuples
+        """
         self.store = store
         self.sha_iter = sha_iter
         self._shas = []
 
     def __iter__(self):
+        """Yield tuple with next object and path."""
         for sha, path in self.itershas():
             yield self.store[sha], path
 
     def iterobjects(self):
+        """Iterate over just the objects."""
         for o, path in self:
             yield o
 
     def itershas(self):
+        """Iterate over the SHAs."""
         for sha in self._shas:
             yield sha
         for sha in self.sha_iter:
@@ -425,12 +441,21 @@ class ObjectStoreIterator(ObjectIterator):
     def __contains__(self, needle):
         """Check if an object is present.
 
+        :note: This checks if the object is present in 
+            the underlying object store, not if it would
+            be yielded by the iterator.
+
         :param needle: SHA1 of the object to check for
         """
         return needle in self.store
 
     def __getitem__(self, key):
-        """Find an object by SHA1."""
+        """Find an object by SHA1.
+        
+        :note: This retrieves the object from the underlying
+            object store. It will also succeed if the object would
+            not be returned by the iterator.
+        """
         return self.store[key]
 
     def __len__(self):

dulwich/objects.py

@@ -106,7 +106,7 @@ class ShaFile(object):
         i = 0
         while text[0] >= '0' and text[0] <= '9':
             if i > 0 and size == 0:
-                assert False, "Size is not in canonical format"
+                raise AssertionError("Size is not in canonical format")
             size = (size * 10) + int(text[0])
             text = text[1:]
             i += 1

dulwich/pack.py

@@ -164,6 +164,14 @@ def load_pack_index(filename):
 
 
 def bisect_find_sha(start, end, sha, unpack_name):
+    """Find a SHA in a data blob with sorted SHAs.
+    
+    :param start: Start index of range to search
+    :param end: End index of range to search
+    :param sha: Sha to find
+    :param unpack_name: Callback to retrieve SHA by index
+    :return: Index of the SHA, or None if it wasn't found
+    """
     assert start <= end
     while start <= end:
         i = (start + end)/2
@@ -220,6 +228,9 @@ class PackIndex(object):
             if name1 != name2:
                 return False
         return True
+
+    def __ne__(self, other):
+        return not self.__eq__(other)
   
     def close(self):
         self._file.close()
@@ -248,6 +259,7 @@ class PackIndex(object):
         raise NotImplementedError(self._unpack_crc32_checksum)
   
     def __iter__(self):
+        """Iterate over the SHAs in this pack."""
         return imap(sha_to_hex, self._itersha())
   
     def _itersha(self):
@@ -277,6 +289,7 @@ class PackIndex(object):
   
     def check(self):
         """Check that the stored checksum matches the actual checksum."""
+        # TODO: Check pack contents, too
         return self.calculate_checksum() == self.get_stored_checksum()
   
     def calculate_checksum(self):
@@ -434,7 +447,7 @@ def unpack_object(map, offset=0):
         return type, uncomp, comp_len+raw_base
 
 
-def compute_object_size((num, obj)):
+def _compute_object_size((num, obj)):
     """Compute the size of a unresolved object for use with LRUSizeCache.
     """
     if num in (6, 7):
@@ -487,7 +500,7 @@ class PackData(object):
         self._file = open(self._filename, 'rb')
         self._read_header()
         self._offset_cache = LRUSizeCache(1024*1024*20, 
-            compute_size=compute_object_size)
+            compute_size=_compute_object_size)
 
     def close(self):
         self._file.close()