Merge ~racb/git-ubuntu:source-tree into git-ubuntu:master

[Robie Basak]

Documentation of this is included in docstrings and comments.

[Server Team CI bot (server-team-bot)]

FAILED: Continuous integration, rev:7a87399d0536f845c27e17c62b337b02249a1a8f
https://jenkins.ubuntu.com/server/job/git-ubuntu-ci/282/
Executed test runs:
    SUCCESS: Checkout
    SUCCESS: Style Check
    SUCCESS: Unit Tests
    FAILED: Integration Tests

Click here to trigger a rebuild:
https://jenkins.ubuntu.com/server/job/git-ubuntu-ci/282/rebuild

review: Needs Fixing (continuous-integration)

[Server Team CI bot (server-team-bot)]

FAILED: Continuous integration, rev:7a87399d0536f845c27e17c62b337b02249a1a8f
https://jenkins.ubuntu.com/server/job/git-ubuntu-ci/284/
Executed test runs:
    SUCCESS: Checkout
    SUCCESS: Style Check
    SUCCESS: Unit Tests
    FAILED: Integration Tests

Click here to trigger a rebuild:
https://jenkins.ubuntu.com/server/job/git-ubuntu-ci/284/rebuild

review: Needs Fixing (continuous-integration)

[Server Team CI bot (server-team-bot)]

PASSED: Continuous integration, rev:7a87399d0536f845c27e17c62b337b02249a1a8f
https://jenkins.ubuntu.com/server/job/git-ubuntu-ci/286/
Executed test runs:
    SUCCESS: Checkout
    SUCCESS: Style Check
    SUCCESS: Unit Tests
    SUCCESS: Integration Tests
    IN_PROGRESS: Declarative: Post Actions

Click here to trigger a rebuild:
https://jenkins.ubuntu.com/server/job/git-ubuntu-ci/286/rebuild

review: Approve (continuous-integration)

[Nish Aravamudan (nacc)]

review: Approve

diff --git a/gitubuntu/repo_builder.py b/gitubuntu/repo_builder.py
index cb93278..76d9209 100644
--- a/gitubuntu/repo_builder.py
+++ b/gitubuntu/repo_builder.py
@@ -1,3 +1,4 @@
+import binascii
 import functools
 import tempfile
 import unittest
@@ -5,6 +6,16 @@ import unittest
 import pygit2
 import pytest
 
+import gitubuntu.importer
+from gitubuntu.test_fixtures import (
+    repo,
+    pygit2_repo,
+)
+
+# Only for tests; can move to repo_builder_test when the move is done
+import gitubuntu.git_repository
+from gitubuntu.source_builder import Source
+
 
 """Build test git repositories as data structures
 
@@ -12,6 +23,12 @@ Represent a git repository as a data structure, nesting using Tree objects as
 required. Name objects in a flat namespace using the name keyword object to
 these constructors.
 
+Use a SourceTree object to get something that behaves like a Tree but is
+actually the exact source of a full, unpacked source package described using
+source_builder.Source. As source_builder.Source is slow, however, using a Tree
+directly is preferred when the behaviour under test does not need a complete
+source tree.
+
 Reference the same object with a Placeholder giving the name of the target to
 its constructor. This allows a build in a single data structure instead of
 having to use multiple statements to grab references to other parts of the same
@@ -29,6 +46,7 @@ __all__ = [
     'Blob',
     'Commit',
     'ExecutableBlob',
+    'SourceTree',
     'Symlink',
     'Placeholder',
     'Tree',
@@ -165,6 +183,25 @@ class Tree(NamedMixin, WriteMixin):
         return tree_builder.write()
 
 
+class SourceTree(NamedMixin, WriteMixin):
+    def __init__(self, source, **kwargs):
+        """Construct a git tree representation of a source_builder.Source
+
+        :param source_tree.SourceBuilder source: the source whose git tree this
+            object will represent
+        """
+        super().__init__(**kwargs)
+        self.source = source
+
+    def walk(self, parent=None):
+        yield parent, self
+
+    def _obj_to_oid(self, repo, record):
+        with self.source as dsc_path:
+            oid_str = gitubuntu.importer.dsc_to_tree_hash(repo, dsc_path)
+        return pygit2.Oid(binascii.unhexlify(oid_str))
+
+
 class Commit(NamedMixin, WriteMixin):
     def __init__(self, tree, **kwargs):
         super().__init__(**kwargs)
@@ -236,6 +273,16 @@ class TestObjectCreation(unittest.TestCase):
             commit['absent']
 
 
+def test_source_tree(pygit2_repo):
+    commit_str = Commit(SourceTree(Source())).write(pygit2_repo)
+    commit = pygit2_repo.get(commit_str)
+    assert gitubuntu.git_repository.follow_symlinks_to_blob(
+        repo=pygit2_repo,
+        treeish_object=commit,
+        path='debian/changelog',
+    )
+
+
 @pytest.mark.parametrize('cls', [
     functools.partial(Blob, b'qux'),
     functools.partial(ExecutableBlob, b'qux'),