front-end developers/bzrlib non-plugin users - heads up, bzrlib.initialize changes in 2.2

[Robert Collins]

bzrlib.initialize is a fairly new helper function used to get bzrlib
ready to use. It is being changed in an incompatible fashion in 2.2
(the change is playing in PQM now, and is in NEWS).

If you do not directly use the bzrlib python module (outside of
writing bzrlib plugins) then you can ignore this email. Users of
wrappers of bzrlib may find that their wrapper API changes on the
first release after bzr 2.2 is released. (By wrappers I'm thinking of
things like config-manager, which use bzrlib as part of providing
other services). I've copied the maintainers of a couple of users of
bzrlib that are most likely affected.

The function bzrlib.initialize has had it's API has been changed to
aid with managing UI glitches relating to progress bars; the API
change required a new function call when the library was finished
with. As part of reviewing and polishing that change we've made it
into a full context manager, which makes it quite easy to use in
Python 2.5 and above with the with statement::


    with bzrlib.initialize() as bzrstate:
        bzrlib.workingtree.WorkingTree.open(..)


If you are using bzrlib in a webserver or other environment that
doesn't have a good opportunity to work with it as a context, you
should do the following:

state = bzrlib.initialize()
state.__enter__()
atexit.register(state.__exit__, (None, None, None))

or something similar - basically arrange for bzrlib to be shut down
cleanly when you are finished with it.

One advantage of the change we have made is that it can be detected at
runtime. Here is how you might handle 2.1 and 2.2 in the same code:
state = bzrlib.initialise()
if state:
    state.__enter__()
try:
    # do stuff
finally:
    if state:
        state.__exit__(None, None, None)

If you are not currently calling bzrlib.initialize(), thats fine -
most bits of global state are separately initialisable, and I'm going
to make the state used in bzrlib.initialize more fine grained, so that
it can fit better with things that e.g. want their own ~/.bzr.log
files.

-Rob