artifactcache: improve _fetch_directory()

* Rename tree to dir_digest to make it clear this is a Digest object,
  and not a Tree object.
* Add documentation

1 files changed, 19 insertions, 6 deletions

diff --git a/buildstream/_artifactcache/cascache.py b/buildstream/_artifactcache/cascache.py
index d48c8aa01..8a0eb5195 100644
--- a/buildstream/_artifactcache/cascache.py
+++ b/buildstream/_artifactcache/cascache.py
@@ -803,14 +803,26 @@ class CASCache(ArtifactCache):
         out.flush()
         assert digest.size_bytes == os.fstat(out.fileno()).st_size
 
-    def _fetch_directory(self, remote, tree):
-        objpath = self.objpath(tree)
+    # _fetch_directory():
+    #
+    # Fetches remote directory and adds it to content addressable store.
+    #
+    # Fetches files, symbolic links and recursively other directories in
+    # the remote directory and adds them to the content addressable
+    # store.
+    #
+    # Args:
+    #     remote (Remote): The remote to use.
+    #     dir_digest (Digest): Digest object for the directory to fetch.
+    #
+    def _fetch_directory(self, remote, dir_digest):
+        objpath = self.objpath(dir_digest)
         if os.path.exists(objpath):
             # already in local cache
             return
 
         with tempfile.NamedTemporaryFile(dir=self.tmpdir) as out:
-            self._fetch_blob(remote, tree, out)
+            self._fetch_blob(remote, dir_digest, out)
 
             directory = remote_execution_pb2.Directory()
 
@@ -832,10 +844,11 @@ class CASCache(ArtifactCache):
             for dirnode in directory.directories:
                 self._fetch_directory(remote, dirnode.digest)
 
-            # place directory blob only in final location when we've downloaded
-            # all referenced blobs to avoid dangling references in the repository
+            # Place directory blob only in final location when we've
+            # downloaded all referenced blobs to avoid dangling
+            # references in the repository.
             digest = self.add_object(path=out.name)
-            assert digest.hash == tree.hash
+            assert digest.hash == dir_digest.hash
 
 
 # Represents a single remote CAS cache.