Higher level methods in bzrlib for library users

[Tim Penhey]

Hi All,

I brought this up with Martin Pool earlier this week I think, and I want to 
take the idea to the list before I take it any further.

My situation is one where I use bzr as a python library through bzrlib, but 
I'm not a bazaar hacker, nor do I have a detailed in-depth understanding of 
the bazaar internals.  I am a regular bzr user though and have been for over 
four years now.

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.

I've found some sample code for some of these on the bazaar wiki, but there 
are others which I've not found.  These methods are pretty trivial to write if 
you have the in-depth understanding of bzrlib that the core developers have, 
but not obvious to those that don't.

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)
 * 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

My selfish reasons for these are to integrate into wikkid (the bzr wiki I'm 
messing with).  I'm sure there will be others that I'll think about later, and 
other methods that other library users would love to have simpler.

I see several benefits of doing this:

 1) The methods are implemented once by the people that know the code well, 
and are well tested as part of the bazaar test suite
 2) The methods work as real, tested, code examples for other developers
 3) A higher level of abstraction may reduce the barrier for new plugin or 
application developers

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.

I'm reasonably confident that many of these methods may well already be written 
in some of the existing plugins, but if we can move them into trunk, then 
others don't have to write them as well.


Thoughts and comments?

Tim