Higher level methods in bzrlib for library users

[Martin Pool]

On 5 December 2010 11:14, Tim Penhey <tim at penhey.net> wrote:
> Reading many of the responses I see that most people see that I'm advocating
> more methods on the existing objects.
>
> I wasn't thinking of that at all.

afaics people are discussing that just to dismiss it.

> Personally I was thinking of stand alone functions that take parameters.
> Those parameters generally don't change and have interface stability from
> release to release, as there isn't much that needs to change on the high level
> because you are asking higher level questions of the object model.  The tests
> enforce correctness from release to release.
>
> I was thinking of either:
>  a separate module, like bzrlib.something
> or
>  a collection of higher level objects that wrap the existing ones
>
> I'm not all that keen on functions wrapping the CLI as the main implementation
> because they have parameters up the kazoo.  What I care about is a simple,
> clean, understandable interface for non-bzr-gurus.

I wasn't suggesting this would wrap the CLI.  Rather, the CLI would
sit on top of this layer.  It seems like they have a fair amount in
common and it would not help to implement it twice.

> Stand-alone functions are simple to write, simple to document, simple to
> implement (ish), and can be encorporated at a later stage if deemed useful
> enough.

At the moment the command objects follow something like the Function
Object pattern (used once for the duration of a call) which I don't
find terribly satisfying in Python.  I feel if you're going to have an
object it ought to have some meaningful identity/lifetime, and in
bzrlib.commands they don't really, aside from handling cleanups.

We could either say that inside bzrlib.command there is a
machine-oriented interface, or perhaps have bzrlib.command directly
sit on top of a separate bzrlib.highlevel.  The latter might make it
clearer what code ought to go where.

Perhaps this approach could also help with plugins that want to add
parameters to, or otherwise modify, built in commands.

I think it would be feasible to give longer stability guarantees at this layer.

-- 
Martin