Higher level methods in bzrlib for library users

[Martin Pool]

On 3 December 2010 12:22, Jelmer Vernooij <jelmer at samba.org> wrote:
>> What I'm proposing is that we create a number of higher level methods in
>> bzrlib for library users.  There are other projects like bzr-xml, loggerhead,
>> bzr-explorer, the QT and gtk bindings and I'm sure others that all implement
>> very similar methods.  We should normalise these, make them available as part
>> of the library and have them tested and consistent.
> Yeah, that makes a lot of sense.

+1

>> In particular the methods that I'd like to see would be:
>>
>>  * Getting the files that have changed in a given revision (or revision range)
> Does Repository.get_revision_delta() perhaps do what you need?
>
>>  * Getting the diff for a particular revision (or revision range)
>>  * Getting the diff for a particular file in a particular revision
>>  * Getting the mainline revisions that had modified a particular file
> I wonder where we should put these methods - Repository is already big
> enough as is, but it does seem the most appropriate place for them.

One way to handle this is to say that these are really very close to
bzr command-line commands, but handled in-process.  Certainly the
examples Tim gives are pretty close to bzr st, log, and diff.

To get there, I think we just need to take the existing command
objects and split them so that the core logic is separated from:

 * checking and interpreting command line arguments
 * formatting the output into strings etc
 * user interactivity

There are a few nice things about this approach:

 * if someone wants to know "how do I get a diff from the api" then
it's pretty obvious to say "look at the method corresponding to the
command you want to run"
 * as we add new capabilities this ought to encourage people to expose
them in both the high-level api and cli
 * it probably would help the code clarity in the cli layer
 * it may make testing of these commands easier, because you wouldn't
have to do everything through the narrow cli interface - there are
some tests at the moment that cover this, but mostly not

There are some complications, though I think they can be addressed:
 * there is not at the moment any consistent pattern for how you ought
to construct and use a Command object if you're not the cli layer
 * not everybody will have the same idea what "high level" means: for
example, some callers might want to just pass in a url, whereas others
already have an open and locked repository
 * some existing cli code is a bit tangled

I agree that Repository and similar classes have grown uncomfortably
large by holding "everything you can do on a Repository" and a
different place is needed.

>> Martin suggested starting by filing bugs for each method I'd like to see in
>> bzrlib and tag them with a special tag.  This would allow us to track what is
>> done, who is doing it, and also perhaps some low hanging fruit for those who
>> know enough to write the methods that will help others.
> Happy to help where I can. :-)

I think a tag for the project would be a great idea: they have
something in common but they also can be tackled one by one.  Perhaps
also we should add to the developer guide a section saying this thing
exists, and what the patterns for it are.

-- 
Martin