← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/__init__.py

  • Committer: Canonical.com Patch Queue Manager
  • Date: 2010-06-21 05:45:05 UTC
  • mfrom: (5222.2.10 fix-terminal-spew)
  • Revision ID: pqm@pqm.ubuntu.com-20100621054505-7b6lnkos9fcy3d4r
(lifeless) Aaron's output fix for bzr from the UDS sprint,
 tweaked to use a context manager for the whole library. (Aaron Bentley)
 (Robert Collins)

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, and
 
168
        can be used with the with statement. Upon __enter__ the global
 
169
        variables in use by bzr are set, and they are cleared on __exit__.
 
170
 
 
171
        :param setup_ui: If true (default) use a terminal UI; otherwise 
 
172
            some other ui_factory must be assigned to `bzrlib.ui.ui_factory` by
 
173
            the caller.
 
174
        :param stdin, stdout, stderr: If provided, use these for terminal IO;
 
175
            otherwise use the files in `sys`.
 
176
        """
 
177
        self.setup_ui = setup_ui
 
178
        self.stdin = stdin
 
179
        self.stdout = stdout
 
180
        self.stderr = stderr
 
181
 
 
182
    def __enter__(self):
 
183
        # NB: This function tweaks so much global state it's hard to test it in
 
184
        # isolation within the same interpreter.  It's not reached on normal
 
185
        # in-process run_bzr calls.  If it's broken, we expect that
 
186
        # TestRunBzrSubprocess may fail.
 
187
        if version_info[3] == 'final':
 
188
            from bzrlib.symbol_versioning import suppress_deprecation_warnings
 
189
            suppress_deprecation_warnings(override=True)
 
190
 
 
191
        import bzrlib.cleanup
 
192
        import bzrlib.trace
 
193
        self.cleanups = bzrlib.cleanup.ObjectWithCleanups()
 
194
        bzrlib.trace.enable_default_logging()
 
195
 
 
196
        if self.setup_ui:
 
197
            import bzrlib.ui
 
198
            stdin = self.stdin or sys.stdin
 
199
            stdout = self.stdout or sys.stdout
 
200
            stderr = self.stderr or sys.stderr
 
201
            bzrlib.ui.ui_factory = bzrlib.ui.make_ui_for_terminal(
 
202
                stdin, stdout, stderr)
 
203
        global global_state
 
204
        self.saved_state = global_state
 
205
        global_state = self
 
206
 
 
207
    def __exit__(self, exc_type, exc_val, exc_tb):
 
208
        self.cleanups.cleanup_now()
 
209
        import bzrlib.ui
 
210
        bzrlib.trace._flush_stdout_stderr()
 
211
        bzrlib.trace._flush_trace()
 
212
        import bzrlib.osutils
 
213
        bzrlib.osutils.report_extension_load_failures()
 
214
        bzrlib.ui.ui_factory.__exit__(None, None, None)
 
215
        bzrlib.ui.ui_factory = None
 
216
        global global_state
 
217
        global_state = self.saved_state
 
218
        return False # propogate exceptions.
 
219
 
 
220
 
 
221
def initialize(setup_ui=True, stdin=None, stdout=None, stderr=None):
126
222
    """Set up everything needed for normal use of bzrlib.
127
223
 
128
224
    Most applications that embed bzrlib, including bzr itself, should call
131
227
    More options may be added in future so callers should use named arguments.
132
228
 
133
229
    :param setup_ui: If true (default) use a terminal UI; otherwise 
134
 
        something else must be put into `bzrlib.ui.ui_factory`.
 
230
        some other ui_factory must be assigned to `bzrlib.ui.ui_factory` by
 
231
        the caller.
135
232
    :param stdin, stdout, stderr: If provided, use these for terminal IO;
136
233
        otherwise use the files in `sys`.
 
234
    :return: A context manager for the use of bzrlib. The __enter__ method of
 
235
        this context needs to be called before it takes effect, and the __exit__
 
236
        should be called by the caller before exiting their process or
 
237
        otherwise stopping use of bzrlib. Advanced callers can use
 
238
        BzrLibraryState directly.
137
239
    """
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)
 
240
    return BzrLibraryState(setup_ui=setup_ui, stdin=stdin,
 
241
        stdout=stdout, stderr=stderr)
 
242
 
 
243
 
 
244
def test_suite():
 
245
    import tests
 
246
    return tests.test_suite()