← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/ui/__init__.py

  • Committer: Canonical.com Patch Queue Manager
  • Date: 2010-09-01 08:02:42 UTC
  • mfrom: (5390.3.3 faster-revert-593560)
  • Revision ID: pqm@pqm.ubuntu.com-20100901080242-esg62ody4frwmy66
(spiv) Avoid repeatedly calling self.target.all_file_ids() in
 InterTree.iter_changes. (Andrew Bennetts)

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/ui/__init__.py
1
 
# Copyright (C) 2005, 2006, 2007, 2008, 2009 Canonical Ltd
 
1
# Copyright (C) 2005-2010 Canonical Ltd
2
2
#
3
3
# This program is free software; you can redistribute it and/or modify
4
4
# it under the terms of the GNU General Public License as published by
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
 
"""UI abstraction.
18
 
 
19
 
This tells the library how to display things to the user.  Through this
20
 
layer different applications can choose the style of UI.
21
 
 
22
 
At the moment this layer is almost trivial: the application can just
23
 
choose the style of progress bar.
24
 
 
25
 
Set the ui_factory member to define the behaviour.  The default
26
 
displays no output.
 
17
"""Abstraction for interacting with the user.
 
18
 
 
19
Applications can choose different types of UI, and they deal with displaying
 
20
messages or progress to the user, and with gathering different types of input.
 
21
 
 
22
Several levels are supported, and you can also register new factories such as
 
23
for a GUI.
 
24
 
 
25
bzrlib.ui.UIFactory
 
26
    Semi-abstract base class
 
27
 
 
28
bzrlib.ui.SilentUIFactory
 
29
    Produces no output and cannot take any input; useful for programs using
 
30
    bzrlib in batch mode or for programs such as loggerhead.
 
31
 
 
32
bzrlib.ui.CannedInputUIFactory
 
33
    For use in testing; the input values to be returned are provided 
 
34
    at construction.
 
35
 
 
36
bzrlib.ui.text.TextUIFactory
 
37
    Standard text command-line interface, with stdin, stdout, stderr.
 
38
    May make more or less advanced use of them, eg in drawing progress bars,
 
39
    depending on the detected capabilities of the terminal.
 
40
    GUIs may choose to subclass this so that unimplemented methods fall
 
41
    back to working through the terminal.
27
42
"""
28
43
 
 
44
 
29
45
import os
30
46
import sys
31
47
import warnings
41
57
    trace,
42
58
    )
43
59
""")
 
60
from bzrlib.symbol_versioning import (
 
61
    deprecated_function,
 
62
    deprecated_in,
 
63
    deprecated_method,
 
64
    )
 
65
 
 
66
 
 
67
_valid_boolean_strings = dict(yes=True, no=False,
 
68
                              y=True, n=False,
 
69
                              on=True, off=False,
 
70
                              true=True, false=False)
 
71
_valid_boolean_strings['1'] = True
 
72
_valid_boolean_strings['0'] = False
 
73
 
 
74
 
 
75
def bool_from_string(s, accepted_values=None):
 
76
    """Returns a boolean if the string can be interpreted as such.
 
77
 
 
78
    Interpret case insensitive strings as booleans. The default values
 
79
    includes: 'yes', 'no, 'y', 'n', 'true', 'false', '0', '1', 'on',
 
80
    'off'. Alternative values can be provided with the 'accepted_values'
 
81
    parameter.
 
82
 
 
83
    :param s: A string that should be interpreted as a boolean. It should be of
 
84
        type string or unicode.
 
85
 
 
86
    :param accepted_values: An optional dict with accepted strings as keys and
 
87
        True/False as values. The strings will be tested against a lowered
 
88
        version of 's'.
 
89
 
 
90
    :return: True or False for accepted strings, None otherwise.
 
91
    """
 
92
    if accepted_values is None:
 
93
        accepted_values = _valid_boolean_strings
 
94
    val = None
 
95
    if type(s) in (str, unicode):
 
96
        try:
 
97
            val = accepted_values[s.lower()]
 
98
        except KeyError:
 
99
            pass
 
100
    return val
44
101
 
45
102
 
46
103
class UIFactory(object):
48
105
 
49
106
    This tells the library how to display things to the user.  Through this
50
107
    layer different applications can choose the style of UI.
 
108
 
 
109
    UI Factories are also context managers, for some syntactic sugar some users
 
110
    need.
 
111
 
 
112
    :ivar suppressed_warnings: Identifiers for user warnings that should 
 
113
        no be emitted.
51
114
    """
52
115
 
 
116
    _user_warning_templates = dict(
 
117
        cross_format_fetch=("Doing on-the-fly conversion from "
 
118
            "%(from_format)s to %(to_format)s.\n"
 
119
            "This may take some time. Upgrade the repositories to the "
 
120
            "same format for better performance."
 
121
            )
 
122
        )
 
123
 
53
124
    def __init__(self):
54
125
        self._task_stack = []
 
126
        self.suppressed_warnings = set()
 
127
        self._quiet = False
 
128
 
 
129
    def __enter__(self):
 
130
        """Context manager entry support.
 
131
 
 
132
        Override in a concrete factory class if initialisation before use is
 
133
        needed.
 
134
        """
 
135
        return self # This is bound to the 'as' clause in a with statement.
 
136
 
 
137
    def __exit__(self, exc_type, exc_val, exc_tb):
 
138
        """Context manager exit support.
 
139
 
 
140
        Override in a concrete factory class if more cleanup than a simple
 
141
        self.clear_term() is needed when the UIFactory is finished with.
 
142
        """
 
143
        self.clear_term()
 
144
        return False # propogate exceptions.
 
145
 
 
146
    def be_quiet(self, state):
 
147
        """Tell the UI to be more quiet, or not.
 
148
 
 
149
        Typically this suppresses progress bars; the application may also look
 
150
        at ui_factory.is_quiet().
 
151
        """
 
152
        self._quiet = state
55
153
 
56
154
    def get_password(self, prompt='', **kwargs):
57
155
        """Prompt the user for a password.
68
166
        """
69
167
        raise NotImplementedError(self.get_password)
70
168
 
 
169
    def is_quiet(self):
 
170
        return self._quiet
 
171
 
 
172
    def make_output_stream(self, encoding=None, encoding_type=None):
 
173
        """Get a stream for sending out bulk text data.
 
174
 
 
175
        This is used for commands that produce bulk text, such as log or diff
 
176
        output, as opposed to user interaction.  This should work even for
 
177
        non-interactive user interfaces.  Typically this goes to a decorated
 
178
        version of stdout, but in a GUI it might be appropriate to send it to a 
 
179
        window displaying the text.
 
180
     
 
181
        :param encoding: Unicode encoding for output; if not specified 
 
182
            uses the configured 'output_encoding' if any; otherwise the 
 
183
            terminal encoding. 
 
184
            (See get_terminal_encoding.)
 
185
 
 
186
        :param encoding_type: How to handle encoding errors:
 
187
            replace/strict/escape/exact.  Default is replace.
 
188
        """
 
189
        # XXX: is the caller supposed to close the resulting object?
 
190
        if encoding is None:
 
191
            from bzrlib import config
 
192
            encoding = config.GlobalConfig().get_user_option(
 
193
                'output_encoding')
 
194
        if encoding is None:
 
195
            encoding = osutils.get_terminal_encoding(trace=True)
 
196
        if encoding_type is None:
 
197
            encoding_type = 'replace'
 
198
        out_stream = self._make_output_stream_explicit(encoding, encoding_type)
 
199
        return out_stream
 
200
 
 
201
    def _make_output_stream_explicit(self, encoding, encoding_type):
 
202
        raise NotImplementedError("%s doesn't support make_output_stream"
 
203
            % (self.__class__.__name__))
 
204
 
71
205
    def nested_progress_bar(self):
72
206
        """Return a nested progress bar.
73
207
 
86
220
        if not self._task_stack:
87
221
            warnings.warn("%r finished but nothing is active"
88
222
                % (task,))
89
 
        elif task != self._task_stack[-1]:
90
 
            warnings.warn("%r is not the active task %r"
91
 
                % (task, self._task_stack[-1]))
 
223
        if task in self._task_stack:
 
224
            self._task_stack.remove(task)
92
225
        else:
93
 
            del self._task_stack[-1]
 
226
            warnings.warn("%r is not in active stack %r"
 
227
                % (task, self._task_stack))
94
228
        if not self._task_stack:
95
229
            self._progress_all_finished()
96
230
 
113
247
        """
114
248
        pass
115
249
 
 
250
    def format_user_warning(self, warning_id, message_args):
 
251
        try:
 
252
            template = self._user_warning_templates[warning_id]
 
253
        except KeyError:
 
254
            fail = "failed to format warning %r, %r" % (warning_id, message_args)
 
255
            warnings.warn(fail)   # so tests will fail etc
 
256
            return fail
 
257
        try:
 
258
            return template % message_args
 
259
        except ValueError, e:
 
260
            fail = "failed to format warning %r, %r: %s" % (
 
261
                warning_id, message_args, e)
 
262
            warnings.warn(fail)   # so tests will fail etc
 
263
            return fail
 
264
 
116
265
    def get_boolean(self, prompt):
117
266
        """Get a boolean question answered from the user.
118
267
 
122
271
        """
123
272
        raise NotImplementedError(self.get_boolean)
124
273
 
 
274
    def get_integer(self, prompt):
 
275
        """Get an integer from the user.
 
276
 
 
277
        :param prompt: a message to prompt the user with. Could be a multi-line
 
278
            prompt but without a terminating \n.
 
279
 
 
280
        :return: A signed integer.
 
281
        """
 
282
        raise NotImplementedError(self.get_integer)
 
283
 
 
284
    def make_progress_view(self):
 
285
        """Construct a new ProgressView object for this UI.
 
286
 
 
287
        Application code should normally not call this but instead
 
288
        nested_progress_bar().
 
289
        """
 
290
        return NullProgressView()
 
291
 
125
292
    def recommend_upgrade(self,
126
293
        current_format_name,
127
294
        basedir):
128
 
        # this should perhaps be in the TextUIFactory and the default can do
 
295
        # XXX: this should perhaps be in the TextUIFactory and the default can do
129
296
        # nothing
 
297
        #
 
298
        # XXX: Change to show_user_warning - that will accomplish the previous
 
299
        # xxx. -- mbp 2010-02-25
130
300
        trace.warning("%s is deprecated "
131
301
            "and a better format is available.\n"
132
302
            "It is recommended that you upgrade by "
143
313
        """
144
314
        pass
145
315
 
146
 
 
147
 
 
148
 
class CLIUIFactory(UIFactory):
149
 
    """Common behaviour for command line UI factories.
150
 
 
151
 
    This is suitable for dumb terminals that can't repaint existing text."""
152
 
 
153
 
    def __init__(self, stdin=None, stdout=None, stderr=None):
 
316
    def log_transport_activity(self, display=False):
 
317
        """Write out whatever transport activity has been measured.
 
318
 
 
319
        Implementations are allowed to do nothing, but it is useful if they can
 
320
        write a line to the log file.
 
321
 
 
322
        :param display: If False, only log to disk, if True also try to display
 
323
            a message to the user.
 
324
        :return: None
 
325
        """
 
326
        # Default implementation just does nothing
 
327
        pass
 
328
 
 
329
    def show_user_warning(self, warning_id, **message_args):
 
330
        """Show a warning to the user.
 
331
 
 
332
        This is specifically for things that are under the user's control (eg
 
333
        outdated formats), not for internal program warnings like deprecated
 
334
        APIs.
 
335
 
 
336
        This can be overridden by UIFactory subclasses to show it in some 
 
337
        appropriate way; the default UIFactory is noninteractive and does
 
338
        nothing.  format_user_warning maps it to a string, though other
 
339
        presentations can be used for particular UIs.
 
340
 
 
341
        :param warning_id: An identifier like 'cross_format_fetch' used to 
 
342
            check if the message is suppressed and to look up the string.
 
343
        :param message_args: Arguments to be interpolated into the message.
 
344
        """
 
345
        pass
 
346
 
 
347
    def show_error(self, msg):
 
348
        """Show an error message (not an exception) to the user.
 
349
        
 
350
        The message should not have an error prefix or trailing newline.  That
 
351
        will be added by the factory if appropriate.
 
352
        """
 
353
        raise NotImplementedError(self.show_error)
 
354
 
 
355
    def show_message(self, msg):
 
356
        """Show a message to the user."""
 
357
        raise NotImplementedError(self.show_message)
 
358
 
 
359
    def show_warning(self, msg):
 
360
        """Show a warning to the user."""
 
361
        raise NotImplementedError(self.show_warning)
 
362
 
 
363
    def warn_cross_format_fetch(self, from_format, to_format):
 
364
        """Warn about a potentially slow cross-format transfer.
 
365
        
 
366
        This is deprecated in favor of show_user_warning, but retained for api
 
367
        compatibility in 2.0 and 2.1.
 
368
        """
 
369
        self.show_user_warning('cross_format_fetch', from_format=from_format,
 
370
            to_format=to_format)
 
371
 
 
372
    def warn_experimental_format_fetch(self, inter):
 
373
        """Warn about fetching into experimental repository formats."""
 
374
        if inter.target._format.experimental:
 
375
            trace.warning("Fetching into experimental format %s.\n"
 
376
                "This format may be unreliable or change in the future "
 
377
                "without an upgrade path.\n" % (inter.target._format,))
 
378
 
 
379
 
 
380
class SilentUIFactory(UIFactory):
 
381
    """A UI Factory which never prints anything.
 
382
 
 
383
    This is the default UI, if another one is never registered by a program
 
384
    using bzrlib, and it's also active for example inside 'bzr serve'.
 
385
 
 
386
    Methods that try to read from the user raise an error; methods that do
 
387
    output do nothing.
 
388
    """
 
389
 
 
390
    def __init__(self):
154
391
        UIFactory.__init__(self)
155
 
        self.stdin = stdin or sys.stdin
156
 
        self.stdout = stdout or sys.stdout
157
 
        self.stderr = stderr or sys.stderr
158
 
 
159
 
    def get_boolean(self, prompt):
160
 
        self.clear_term()
161
 
        # FIXME: make a regexp and handle case variations as well.
162
 
        while True:
163
 
            self.prompt(prompt + "? [y/n]: ")
164
 
            line = self.stdin.readline()
165
 
            if line in ('y\n', 'yes\n'):
166
 
                return True
167
 
            if line in ('n\n', 'no\n'):
168
 
                return False
169
 
 
170
 
    def get_non_echoed_password(self, prompt):
171
 
        if not sys.stdin.isatty():
172
 
            raise errors.NotATerminal()
173
 
        encoding = osutils.get_terminal_encoding()
174
 
        return getpass.getpass(prompt.encode(encoding, 'replace'))
175
 
 
176
 
    def get_password(self, prompt='', **kwargs):
177
 
        """Prompt the user for a password.
178
 
 
179
 
        :param prompt: The prompt to present the user
180
 
        :param kwargs: Arguments which will be expanded into the prompt.
181
 
                       This lets front ends display different things if
182
 
                       they so choose.
183
 
        :return: The password string, return None if the user
184
 
                 canceled the request.
185
 
        """
186
 
        prompt += ': '
187
 
        prompt = (prompt % kwargs)
188
 
        # There's currently no way to say 'i decline to enter a password'
189
 
        # as opposed to 'my password is empty' -- does it matter?
190
 
        return self.get_non_echoed_password(prompt)
191
 
 
192
 
    def prompt(self, prompt):
193
 
        """Emit prompt on the CLI."""
194
 
        self.stdout.write(prompt)
195
392
 
196
393
    def note(self, msg):
197
 
        """Write an already-formatted message."""
198
 
        self.stdout.write(msg + '\n')
199
 
 
200
 
 
201
 
class SilentUIFactory(CLIUIFactory):
202
 
    """A UI Factory which never prints anything.
203
 
 
204
 
    This is the default UI, if another one is never registered.
205
 
    """
206
 
 
207
 
    def __init__(self):
208
 
        CLIUIFactory.__init__(self)
209
 
 
210
 
    def get_password(self, prompt='', **kwargs):
 
394
        pass
 
395
 
 
396
    def get_username(self, prompt, **kwargs):
211
397
        return None
212
398
 
213
 
    def prompt(self, prompt):
214
 
        pass
215
 
 
216
 
    def note(self, msg):
217
 
        pass
218
 
 
219
 
 
220
 
def clear_decorator(func, *args, **kwargs):
221
 
    """Decorator that clears the term"""
222
 
    ui_factory.clear_term()
223
 
    func(*args, **kwargs)
 
399
    def _make_output_stream_explicit(self, encoding, encoding_type):
 
400
        return NullOutputStream(encoding)
 
401
 
 
402
    def show_error(self, msg):
 
403
        pass
 
404
 
 
405
    def show_message(self, msg):
 
406
        pass
 
407
 
 
408
    def show_warning(self, msg):
 
409
        pass
 
410
 
 
411
 
 
412
class CannedInputUIFactory(SilentUIFactory):
 
413
    """A silent UI that return canned input."""
 
414
 
 
415
    def __init__(self, responses):
 
416
        self.responses = responses
 
417
 
 
418
    def __repr__(self):
 
419
        return "%s(%r)" % (self.__class__.__name__, self.responses)
 
420
 
 
421
    def get_boolean(self, prompt):
 
422
        return self.responses.pop(0)
 
423
 
 
424
    def get_integer(self, prompt):
 
425
        return self.responses.pop(0)
 
426
 
 
427
    def get_password(self, prompt='', **kwargs):
 
428
        return self.responses.pop(0)
 
429
 
 
430
    def get_username(self, prompt, **kwargs):
 
431
        return self.responses.pop(0)
 
432
 
 
433
    def assert_all_input_consumed(self):
 
434
        if self.responses:
 
435
            raise AssertionError("expected all input in %r to be consumed"
 
436
                % (self,))
224
437
 
225
438
 
226
439
ui_factory = SilentUIFactory()
227
 
"""IMPORTANT: never import this symbol directly. ONLY ever access it as
228
 
ui.ui_factory."""
 
440
# IMPORTANT: never import this symbol directly. ONLY ever access it as
 
441
# ui.ui_factory, so that you refer to the current value.
229
442
 
230
443
 
231
444
def make_ui_for_terminal(stdin, stdout, stderr):
232
445
    """Construct and return a suitable UIFactory for a text mode program.
233
 
 
234
 
    If stdout is a smart terminal, this gets a smart UIFactory with
235
 
    progress indicators, etc.  If it's a dumb terminal, just plain text output.
236
446
    """
237
 
    cls = None
238
 
    isatty = getattr(stdin, 'isatty', None)
239
 
    if isatty is None:
240
 
        cls = CLIUIFactory
241
 
    elif not isatty():
242
 
        cls = CLIUIFactory
243
 
    elif os.environ.get('TERM') in ('dumb', ''):
244
 
        # e.g. emacs compile window
245
 
        cls = CLIUIFactory
246
 
    # User may know better, otherwise default to TextUIFactory
247
 
    if (   os.environ.get('BZR_USE_TEXT_UI', None) is not None
248
 
        or cls is None):
249
 
        from bzrlib.ui.text import TextUIFactory
250
 
        cls = TextUIFactory
251
 
    return cls(stdin=stdin, stdout=stdout, stderr=stderr)
 
447
    # this is now always TextUIFactory, which in turn decides whether it
 
448
    # should display progress bars etc
 
449
    from bzrlib.ui.text import TextUIFactory
 
450
    return TextUIFactory(stdin, stdout, stderr)
 
451
 
 
452
 
 
453
class NullProgressView(object):
 
454
    """Soak up and ignore progress information."""
 
455
 
 
456
    def clear(self):
 
457
        pass
 
458
 
 
459
    def show_progress(self, task):
 
460
        pass
 
461
 
 
462
    def show_transport_activity(self, transport, direction, byte_count):
 
463
        pass
 
464
 
 
465
    def log_transport_activity(self, display=False):
 
466
        pass
 
467
 
 
468
 
 
469
class NullOutputStream(object):
 
470
    """Acts like a file, but discard all output."""
 
471
 
 
472
    def __init__(self, encoding):
 
473
        self.encoding = encoding
 
474
 
 
475
    def write(self, data):
 
476
        pass
 
477
 
 
478
    def writelines(self, data):
 
479
        pass
 
480
 
 
481
    def close(self):
 
482
        pass