← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/__init__.py

Merge cleanup into first-try

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/__init__.py
14
14
# along with this program; if not, write to the Free Software
15
15
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
16
16
 
17
 
"""bzr library"""
 
17
"""All of bzr.
 
18
 
 
19
Developer documentation is available at
 
20
http://doc.bazaar.canonical.com/bzr.dev/developers/
 
21
 
 
22
The project website is at http://bazaar.canonical.com/
 
23
 
 
24
Some particularly interesting things in bzrlib are:
 
25
 
 
26
 * bzrlib.initialize -- setup the library for use
 
27
 * bzrlib.plugin.load_plugins -- load all installed plugins
 
28
 * bzrlib.branch.Branch.open -- open a branch
 
29
 * bzrlib.workingtree.WorkingTree.open -- open a working tree
 
30
 
 
31
We hope you enjoy this library.
 
32
"""
18
33
 
19
34
import time
20
35
 
114
129
__version__ = _format_version_tuple(version_info)
115
130
version_string = __version__
116
131
 
117
 
 
118
 
def test_suite():
119
 
    import tests
120
 
    return tests.test_suite()
121
 
 
122
 
 
123
 
def initialize(
124
 
    setup_ui=True,
125
 
    stdin=None, stdout=None, stderr=None):
 
132
# bzr has various bits of global state that are slowly being eliminated.
 
133
# This variable is intended to permit any new state-like things to be attached
 
134
# to a BzrLibraryState object rather than getting new global variables that
 
135
# need to be hunted down. Accessing the current BzrLibraryState through this
 
136
# variable is not encouraged: it is better to pass it around as part of the
 
137
# context of an operation than to look it up directly, but when that is too
 
138
# hard, it is better to use this variable than to make a branch new global
 
139
# variable.
 
140
# If using this variable by looking it up (because it can't be easily obtained)
 
141
# it is important to store the reference you get, rather than looking it up
 
142
# repeatedly; that way your code will behave properly in the bzrlib test suite
 
143
# and from programs that do use multiple library contexts.
 
144
global_state = None
 
145
 
 
146
 
 
147
class BzrLibraryState(object):
 
148
    """The state about how bzrlib has been configured.
 
149
    
 
150
    :ivar saved_state: The bzrlib.global_state at the time __enter__ was
 
151
        called.
 
152
    :ivar cleanups: An ObjectWithCleanups which can be used for cleanups that
 
153
        should occur when the use of bzrlib is completed. This is initialised
 
154
        in __enter__ and executed in __exit__.
 
155
    """
 
156
 
 
157
    def __init__(self, setup_ui=True, stdin=None, stdout=None, stderr=None):
 
158
        """Create library start for normal use of bzrlib.
 
159
 
 
160
        Most applications that embed bzrlib, including bzr itself, should just
 
161
        call bzrlib.initialize(), but it is possible to use the state class
 
162
        directly.
 
163
 
 
164
        More options may be added in future so callers should use named
 
165
        arguments.
 
166
 
 
167
        BzrLibraryState implements the Python 2.5 Context Manager protocol
 
168
        PEP343, and can be used with the with statement. Upon __enter__ the
 
169
        global variables in use by bzr are set, and they are cleared on
 
170
        __exit__.
 
171
 
 
172
        :param setup_ui: If true (default) use a terminal UI; otherwise 
 
173
            some other ui_factory must be assigned to `bzrlib.ui.ui_factory` by
 
174
            the caller.
 
175
        :param stdin, stdout, stderr: If provided, use these for terminal IO;
 
176
            otherwise use the files in `sys`.
 
177
        """
 
178
        self.setup_ui = setup_ui
 
179
        self.stdin = stdin
 
180
        self.stdout = stdout
 
181
        self.stderr = stderr
 
182
 
 
183
    def __enter__(self):
 
184
        # NB: This function tweaks so much global state it's hard to test it in
 
185
        # isolation within the same interpreter.  It's not reached on normal
 
186
        # in-process run_bzr calls.  If it's broken, we expect that
 
187
        # TestRunBzrSubprocess may fail.
 
188
        if version_info[3] == 'final':
 
189
            from bzrlib.symbol_versioning import suppress_deprecation_warnings
 
190
            suppress_deprecation_warnings(override=True)
 
191
 
 
192
        import bzrlib.cleanup
 
193
        import bzrlib.trace
 
194
        self.cleanups = bzrlib.cleanup.ObjectWithCleanups()
 
195
        bzrlib.trace.enable_default_logging()
 
196
 
 
197
        if self.setup_ui:
 
198
            import bzrlib.ui
 
199
            stdin = self.stdin or sys.stdin
 
200
            stdout = self.stdout or sys.stdout
 
201
            stderr = self.stderr or sys.stderr
 
202
            bzrlib.ui.ui_factory = bzrlib.ui.make_ui_for_terminal(
 
203
                stdin, stdout, stderr)
 
204
        global global_state
 
205
        self.saved_state = global_state
 
206
        global_state = self
 
207
        return self # This is bound to the 'as' clause in a with statement.
 
208
 
 
209
    def __exit__(self, exc_type, exc_val, exc_tb):
 
210
        self.cleanups.cleanup_now()
 
211
        import bzrlib.ui
 
212
        bzrlib.trace._flush_stdout_stderr()
 
213
        bzrlib.trace._flush_trace()
 
214
        import bzrlib.osutils
 
215
        bzrlib.osutils.report_extension_load_failures()
 
216
        bzrlib.ui.ui_factory.__exit__(None, None, None)
 
217
        bzrlib.ui.ui_factory = None
 
218
        global global_state
 
219
        global_state = self.saved_state
 
220
        return False # propogate exceptions.
 
221
 
 
222
 
 
223
def initialize(setup_ui=True, stdin=None, stdout=None, stderr=None):
126
224
    """Set up everything needed for normal use of bzrlib.
127
225
 
128
226
    Most applications that embed bzrlib, including bzr itself, should call
131
229
    More options may be added in future so callers should use named arguments.
132
230
 
133
231
    :param setup_ui: If true (default) use a terminal UI; otherwise 
134
 
        something else must be put into `bzrlib.ui.ui_factory`.
 
232
        some other ui_factory must be assigned to `bzrlib.ui.ui_factory` by
 
233
        the caller.
135
234
    :param stdin, stdout, stderr: If provided, use these for terminal IO;
136
235
        otherwise use the files in `sys`.
 
236
    :return: A context manager for the use of bzrlib. The __enter__ method of
 
237
        this context needs to be called before it takes effect, and the __exit__
 
238
        should be called by the caller before exiting their process or
 
239
        otherwise stopping use of bzrlib. Advanced callers can use
 
240
        BzrLibraryState directly.
137
241
    """
138
 
    # TODO: mention this in a guide to embedding bzrlib
139
 
    #
140
 
    # NB: This function tweaks so much global state it's hard to test it in
141
 
    # isolation within the same interpreter.  It's not reached on normal
142
 
    # in-process run_bzr calls.  If it's broken, we expect that
143
 
    # TestRunBzrSubprocess may fail.
144
 
    
145
 
    import atexit
146
 
    import bzrlib.trace
147
 
 
148
 
    bzrlib.trace.enable_default_logging()
149
 
    atexit.register(bzrlib.trace._flush_stdout_stderr)
150
 
    atexit.register(bzrlib.trace._flush_trace)
151
 
 
152
 
    import bzrlib.ui
153
 
    if stdin is None:
154
 
        stdin = sys.stdin
155
 
    if stdout is None:
156
 
        stdout = sys.stdout
157
 
    if stderr is None:
158
 
        stderr = sys.stderr
159
 
 
160
 
    if setup_ui:
161
 
        bzrlib.ui.ui_factory = bzrlib.ui.make_ui_for_terminal(
162
 
            stdin, stdout, stderr)
163
 
 
164
 
    if bzrlib.version_info[3] == 'final':
165
 
        from bzrlib.symbol_versioning import suppress_deprecation_warnings
166
 
        suppress_deprecation_warnings(override=True)
167
 
 
168
 
    import bzrlib.osutils
169
 
    atexit.register(osutils.report_extension_load_failures)
 
242
    return BzrLibraryState(setup_ui=setup_ui, stdin=stdin,
 
243
        stdout=stdout, stderr=stderr)
 
244
 
 
245
 
 
246
def test_suite():
 
247
    import tests
 
248
    return tests.test_suite()