← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/graph.py

Define SearchResult/Search interfaces with explicit abstract base classes, add some docstrings and change a method name.

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/graph.py
1536
1536
            return revs, ghosts
1537
1537
 
1538
1538
 
1539
 
class SearchResult(object):
 
1539
class AbstractSearchResult(object):
 
1540
 
 
1541
    def get_recipe(self):
 
1542
        """Return a recipe that can be used to replay this search.
 
1543
 
 
1544
        The recipe allows reconstruction of the same results at a later date.
 
1545
 
 
1546
        :return: A tuple of (search_kind_str, *details).  The details vary by
 
1547
            kind of search result.
 
1548
        """
 
1549
        raise NotImplementedError(self.get_recipe)
 
1550
 
 
1551
    def get_network_struct(self):
 
1552
        """Return a tuple that can be transmitted via the HPSS protocol."""
 
1553
        raise NotImplementedError(self.get_network_struct)
 
1554
 
 
1555
    def get_keys(self):
 
1556
        """Return the keys found in this search.
 
1557
 
 
1558
        :return: A set of keys.
 
1559
        """
 
1560
        raise NotImplementedError(self.get_keys)
 
1561
 
 
1562
    def is_empty(self):
 
1563
        """Return false if the search lists 1 or more revisions."""
 
1564
        raise NotImplementedError(self.is_empty)
 
1565
 
 
1566
    def refine(self, seen, referenced):
 
1567
        """Create a new search by refining this search.
 
1568
 
 
1569
        :param seen: Revisions that have been satisfied.
 
1570
        :param referenced: Revision references observed while satisfying some
 
1571
            of this search.
 
1572
        :return: A search result.
 
1573
        """
 
1574
        raise NotImplementedError(self.refine)
 
1575
 
 
1576
 
 
1577
class AbstractSearch(object):
 
1578
 
 
1579
    def get_search_result(self):
 
1580
        """Construct a network-ready search result from this search description.
 
1581
 
 
1582
        This may take some time to search repositories, etc.
 
1583
 
 
1584
        :return: A search result.
 
1585
        """
 
1586
        raise NotImplementedError(self.get_search_result)
 
1587
 
 
1588
 
 
1589
class SearchResult(AbstractSearchResult):
1540
1590
    """The result of a breadth first search.
1541
1591
 
1542
1592
    A SearchResult provides the ability to reconstruct the search or access a
1636
1686
        return SearchResult(pending_refs, exclude, count, keys)
1637
1687
 
1638
1688
 
1639
 
class PendingAncestryResult(object):
 
1689
class PendingAncestryResult(AbstractSearchResult):
1640
1690
    """A search result that will reconstruct the ancestry for some graph heads.
1641
1691
 
1642
1692
    Unlike SearchResult, this doesn't hold the complete search result in
1703
1753
        return PendingAncestryResult(referenced - seen, self.repo)
1704
1754
 
1705
1755
 
1706
 
class EmptySearchResult(object):
 
1756
class EmptySearchResult(AbstractSearchResult):
1707
1757
    """An empty search result."""
1708
1758
 
1709
1759
    def is_empty(self):
1710
1760
        return True
1711
1761
    
1712
1762
 
1713
 
class EverythingResult(object):
 
1763
class EverythingResult(AbstractSearchResult):
1714
1764
    """A search result that simply requests everything in the repository."""
1715
1765
 
1716
1766
    def __init__(self, repo):
1747
1797
        return PendingAncestryResult(heads, self._repo)
1748
1798
 
1749
1799
 
1750
 
class EverythingNotInOther(object):
 
1800
class EverythingNotInOther(AbstractSearch):
 
1801
    """Find all revisions in that are in one repo but not the other."""
1751
1802
 
1752
1803
    def __init__(self, to_repo, from_repo, find_ghosts=False):
1753
1804
        self.to_repo = to_repo
1754
1805
        self.from_repo = from_repo
1755
1806
        self.find_ghosts = find_ghosts
1756
1807
 
1757
 
    def get_search(self):
 
1808
    def get_search_result(self):
1758
1809
        return self.to_repo.search_missing_revision_ids(
1759
1810
            self.from_repo, find_ghosts=self.find_ghosts)
1760
1811
 
1761
1812
 
1762
 
class NotInOtherForRevs(object):
 
1813
class NotInOtherForRevs(AbstractSearch):
 
1814
    """Find all revisions missing in one repo for a some specific heads."""
1763
1815
 
1764
1816
    def __init__(self, to_repo, from_repo, required_ids, if_present_ids=None,
1765
1817
            find_ghosts=False):
 
1818
        """Constructor.
 
1819
 
 
1820
        :param required_ids: revision IDs of heads that must be found, or else
 
1821
            the search will fail with NoSuchRevision.  All revisions in their
 
1822
            ancestry not already in the other repository will be included in
 
1823
            the search result.
 
1824
        :param if_present_ids: revision IDs of heads that may be absent in the
 
1825
            source repository.  If present, then their ancestry not already
 
1826
            found in other will be included in the search result.
 
1827
        """
1766
1828
        self.to_repo = to_repo
1767
1829
        self.from_repo = from_repo
1768
1830
        self.find_ghosts = find_ghosts
1783
1845
            self.__class__.__name__, self.from_repo, self.to_repo,
1784
1846
            self.find_ghosts, reqd_revs_repr, ifp_revs_repr)
1785
1847
 
1786
 
    def get_search(self):
 
1848
    def get_search_result(self):
1787
1849
        return self.to_repo.search_missing_revision_ids(
1788
1850
            self.from_repo, revision_ids=self.required_ids,
1789
1851
            if_present_ids=self.if_present_ids, find_ghosts=self.find_ghosts)