← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/developers/integration.txt

  • Committer: Tarmac
  • Author(s): Vincent Ladeuil
  • Date: 2017-01-30 14:42:05 UTC
  • mfrom: (6620.1.1 trunk)
  • Revision ID: tarmac-20170130144205-r8fh2xpmiuxyozpv
Merge  2.7 into trunk including fix for bug #1657238 [r=vila]

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/integration.txt
14
14
Starting with bzrlib
15
15
====================
16
16
 
17
 
Before doing anything else with bzrlib, you should run `bzrlib.initialize`
18
 
which sets up some global state.  
 
17
Within bzr
 
18
----------
 
19
 
 
20
When using bzrlib within the ``bzr`` program (for instance as a bzr
 
21
plugin), bzrlib's global state is already available for use.
 
22
 
 
23
From outside bzr
 
24
----------------
 
25
 
 
26
To use bzrlib outside of ``bzr`` some global state needs to be setup.
 
27
bzrlib needs ways to handle user input, passwords, a place to emit
 
28
progress bars, logging setup appropriately for your program. The easiest
 
29
way to set all this up in the same fashion ``bzr`` does is to call
 
30
``bzrlib.initialize``. 
 
31
 
 
32
This returns a context manager within which bzrlib functions will work
 
33
correctly. See the pydoc for ``bzrlib.initialize`` for more information. 
 
34
(You can get away without entering the context manager, because the setup
 
35
work happens directly from ``initialize``.)
 
36
 
 
37
In Python 2.4 the ``with`` keyword is not supported and
 
38
so you need to use the context manager manually::
 
39
 
 
40
  # This sets up your ~/.bzr.log, ui factory and so on and so forth. It is
 
41
  # not safe to use as a doctest.
 
42
  library_state = bzrlib.initialize()
 
43
  library_state.__enter__()
 
44
  try:
 
45
      pass
 
46
      # do stuff here
 
47
  finally:
 
48
      library_state.__exit__(None, None, None)
19
49
 
20
50
 
21
51
Running bzr commands
43
73
 
44
74
 
45
75
This gives us a WorkingTree object, which has various methods spread over
46
 
itself, and its parent classes MutableTree and Tree - its worth having a
 
76
itself, and its parent classes MutableTree and Tree - it's worth having a
47
77
look through these three files (workingtree.py, mutabletree.py and tree.py)
48
78
to see which methods are available.
49
79