[MERGE] Add optional 'fetch_spec' to argument to Repository.fetch

[Andrew Bennetts]

Jelmer Vernooij wrote:
[...]
> It would be nice if the fetch_spec parameter could be documented in
> Fetch(). In particular, is it allowed to ignore this parameter ? Will
> there be no revision id specified if this parameter is specified?

Yes, Robert pointed out the lack of documentation in his review too, so I
extended the docstring as part of the tweaks to land the branch.  It now
says:

    def fetch(self, source, revision_id=None, pb=None, find_ghosts=False,
            fetch_spec=None):
        """Fetch the content required to construct revision_id from source.

        If revision_id is None and fetch_spec is None, then all content is
        copied.

        :param find_ghosts: Find and copy revisions in the source that are
            ghosts in the target (and not reachable directly by walking out to
            the first-present revision in target from revision_id).
        :param revision_id: If specified, all the content needed for this
            revision ID will be copied to the target.  Fetch will determine for
            itself which content needs to be copied.
        :param fetch_spec: If specified, a SearchResult or
            PendingAncestryResult that describes which revisions to copy.  This
            allows copying multiple heads at once.  Mutually exclusive with
            revision_id.
        """

I hope that answers your questions.  If it doesn't let me know and I'll try
to improve the docstring some more.

Btw, in a couple of places (e.g.  InterPackRepo) that I didn't want to
update for fetch_spec I put in some code like:

        if fetch_spec is not None:
            if len(list(fetch_spec.heads)) != 1:
                raise AssertionError(
                    "InterPackRepo.fetch doesn't support "
                    "fetching multiple heads yet.")
            revision_id = fetch_spec.heads[0]
            fetch_spec = None

Which is just a simple backwards compatibility thing; currently the only
fetch_spec used in bzr.dev is a PendingAncestryResult with a single head
(and then only when sprouting or cloning into a newly created and
non-stacked repo), so it's easy to treat that like a single revision_id as
before.  Perhaps your plugins will want to do the same thing?

I have a suspicion we'll want to tweak this API some more in future
releases, but I think this change was a step in the right direction.

-Andrew.