~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/ui/__init__.py

  • Committer: Aaron Bentley
  • Date: 2008-10-11 17:52:14 UTC
  • mto: This revision was merged to the branch mainline in revision 3823.
  • Revision ID: aaron@aaronbentley.com-20081011175214-85vfxt61753sp404
Make status nicer by not shelving lines for files not being changed

Show diffs side-by-side

added added

removed removed

Lines of Context:
1
 
# Copyright (C) 2005-2010 Canonical Ltd
2
 
#
3
 
# This program is free software; you can redistribute it and/or modify
4
 
# it under the terms of the GNU General Public License as published by
5
 
# the Free Software Foundation; either version 2 of the License, or
6
 
# (at your option) any later version.
7
 
#
8
 
# This program is distributed in the hope that it will be useful,
9
 
# but WITHOUT ANY WARRANTY; without even the implied warranty of
10
 
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
11
 
# GNU General Public License for more details.
12
 
#
13
 
# You should have received a copy of the GNU General Public License
14
 
# along with this program; if not, write to the Free Software
15
 
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
16
 
 
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.
42
 
"""
43
 
 
44
 
 
45
 
import os
46
 
import sys
47
 
import warnings
48
 
 
49
 
from bzrlib.lazy_import import lazy_import
50
 
lazy_import(globals(), """
51
 
import getpass
52
 
 
53
 
from bzrlib import (
54
 
    errors,
55
 
    osutils,
56
 
    progress,
57
 
    trace,
58
 
    )
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
101
 
 
102
 
 
103
 
class UIFactory(object):
104
 
    """UI abstraction.
105
 
 
106
 
    This tells the library how to display things to the user.  Through this
107
 
    layer different applications can choose the style of UI.
108
 
    """
109
 
 
110
 
    def __init__(self):
111
 
        self._task_stack = []
112
 
        self._quiet = False
113
 
 
114
 
    def be_quiet(self, state):
115
 
        """Tell the UI to be more quiet, or not.
116
 
 
117
 
        Typically this suppresses progress bars; the application may also look
118
 
        at ui_factory.is_quiet().
119
 
        """
120
 
        self._quiet = state
121
 
 
122
 
    def get_password(self, prompt='', **kwargs):
123
 
        """Prompt the user for a password.
124
 
 
125
 
        :param prompt: The prompt to present the user
126
 
        :param kwargs: Arguments which will be expanded into the prompt.
127
 
                       This lets front ends display different things if
128
 
                       they so choose.
129
 
 
130
 
        :return: The password string, return None if the user canceled the
131
 
                 request. Note that we do not touch the encoding, users may
132
 
                 have whatever they see fit and the password should be
133
 
                 transported as is.
134
 
        """
135
 
        raise NotImplementedError(self.get_password)
136
 
 
137
 
    def is_quiet(self):
138
 
        return self._quiet
139
 
 
140
 
    def make_output_stream(self, encoding=None, encoding_type=None):
141
 
        """Get a stream for sending out bulk text data.
142
 
 
143
 
        This is used for commands that produce bulk text, such as log or diff
144
 
        output, as opposed to user interaction.  This should work even for
145
 
        non-interactive user interfaces.  Typically this goes to a decorated
146
 
        version of stdout, but in a GUI it might be appropriate to send it to a 
147
 
        window displaying the text.
148
 
     
149
 
        :param encoding: Unicode encoding for output; default is the 
150
 
            terminal encoding, which may be different from the user encoding.
151
 
            (See get_terminal_encoding.)
152
 
 
153
 
        :param encoding_type: How to handle encoding errors:
154
 
            replace/strict/escape/exact.  Default is replace.
155
 
        """
156
 
        # XXX: is the caller supposed to close the resulting object?
157
 
        if encoding is None:
158
 
            encoding = osutils.get_terminal_encoding()
159
 
        if encoding_type is None:
160
 
            encoding_type = 'replace'
161
 
        out_stream = self._make_output_stream_explicit(encoding, encoding_type)
162
 
        return out_stream
163
 
 
164
 
    def _make_output_stream_explicit(self, encoding, encoding_type):
165
 
        raise NotImplementedError("%s doesn't support make_output_stream"
166
 
            % (self.__class__.__name__))
167
 
 
168
 
    def nested_progress_bar(self):
169
 
        """Return a nested progress bar.
170
 
 
171
 
        When the bar has been finished with, it should be released by calling
172
 
        bar.finished().
173
 
        """
174
 
        if self._task_stack:
175
 
            t = progress.ProgressTask(self._task_stack[-1], self)
176
 
        else:
177
 
            t = progress.ProgressTask(None, self)
178
 
        self._task_stack.append(t)
179
 
        return t
180
 
 
181
 
    def _progress_finished(self, task):
182
 
        """Called by the ProgressTask when it finishes"""
183
 
        if not self._task_stack:
184
 
            warnings.warn("%r finished but nothing is active"
185
 
                % (task,))
186
 
        if task in self._task_stack:
187
 
            self._task_stack.remove(task)
188
 
        else:
189
 
            warnings.warn("%r is not in active stack %r"
190
 
                % (task, self._task_stack))
191
 
        if not self._task_stack:
192
 
            self._progress_all_finished()
193
 
 
194
 
    def _progress_all_finished(self):
195
 
        """Called when the top-level progress task finished"""
196
 
        pass
197
 
 
198
 
    def _progress_updated(self, task):
199
 
        """Called by the ProgressTask when it changes.
200
 
 
201
 
        Should be specialized to draw the progress.
202
 
        """
203
 
        pass
204
 
 
205
 
    def clear_term(self):
206
 
        """Prepare the terminal for output.
207
 
 
208
 
        This will, for example, clear text progress bars, and leave the
209
 
        cursor at the leftmost position.
210
 
        """
211
 
        pass
212
 
 
213
 
    def get_boolean(self, prompt):
214
 
        """Get a boolean question answered from the user.
215
 
 
216
 
        :param prompt: a message to prompt the user with. Should be a single
217
 
        line without terminating \n.
218
 
        :return: True or False for y/yes or n/no.
219
 
        """
220
 
        raise NotImplementedError(self.get_boolean)
221
 
 
222
 
    def get_integer(self, prompt):
223
 
        """Get an integer from the user.
224
 
 
225
 
        :param prompt: a message to prompt the user with. Could be a multi-line
226
 
            prompt but without a terminating \n.
227
 
 
228
 
        :return: A signed integer.
229
 
        """
230
 
        raise NotImplementedError(self.get_integer)
231
 
 
232
 
    def make_progress_view(self):
233
 
        """Construct a new ProgressView object for this UI.
234
 
 
235
 
        Application code should normally not call this but instead
236
 
        nested_progress_bar().
237
 
        """
238
 
        return NullProgressView()
239
 
 
240
 
    def recommend_upgrade(self,
241
 
        current_format_name,
242
 
        basedir):
243
 
        # this should perhaps be in the TextUIFactory and the default can do
244
 
        # nothing
245
 
        trace.warning("%s is deprecated "
246
 
            "and a better format is available.\n"
247
 
            "It is recommended that you upgrade by "
248
 
            "running the command\n"
249
 
            "  bzr upgrade %s",
250
 
            current_format_name,
251
 
            basedir)
252
 
 
253
 
    def report_transport_activity(self, transport, byte_count, direction):
254
 
        """Called by transports as they do IO.
255
 
 
256
 
        This may update a progress bar, spinner, or similar display.
257
 
        By default it does nothing.
258
 
        """
259
 
        pass
260
 
 
261
 
    def log_transport_activity(self, display=False):
262
 
        """Write out whatever transport activity has been measured.
263
 
 
264
 
        Implementations are allowed to do nothing, but it is useful if they can
265
 
        write a line to the log file.
266
 
 
267
 
        :param display: If False, only log to disk, if True also try to display
268
 
            a message to the user.
269
 
        :return: None
270
 
        """
271
 
        # Default implementation just does nothing
272
 
        pass
273
 
 
274
 
    def show_error(self, msg):
275
 
        """Show an error message (not an exception) to the user.
276
 
        
277
 
        The message should not have an error prefix or trailing newline.  That
278
 
        will be added by the factory if appropriate.
279
 
        """
280
 
        raise NotImplementedError(self.show_error)
281
 
 
282
 
    def show_message(self, msg):
283
 
        """Show a message to the user."""
284
 
        raise NotImplementedError(self.show_message)
285
 
 
286
 
    def show_warning(self, msg):
287
 
        """Show a warning to the user."""
288
 
        raise NotImplementedError(self.show_warning)
289
 
 
290
 
    def warn_cross_format_fetch(self, from_format, to_format):
291
 
        """Warn about a potentially slow cross-format transfer"""
292
 
        # See <https://launchpad.net/bugs/456077> asking for a warning here
293
 
        trace.warning("Doing on-the-fly conversion from %s to %s.\n"
294
 
            "This may take some time. Upgrade the repositories to the "
295
 
            "same format for better performance.\n" %
296
 
            (from_format, to_format))
297
 
 
298
 
 
299
 
class SilentUIFactory(UIFactory):
300
 
    """A UI Factory which never prints anything.
301
 
 
302
 
    This is the default UI, if another one is never registered by a program
303
 
    using bzrlib, and it's also active for example inside 'bzr serve'.
304
 
 
305
 
    Methods that try to read from the user raise an error; methods that do
306
 
    output do nothing.
307
 
    """
308
 
 
309
 
    def __init__(self):
310
 
        UIFactory.__init__(self)
311
 
 
312
 
    def note(self, msg):
313
 
        pass
314
 
 
315
 
    def get_username(self, prompt, **kwargs):
316
 
        return None
317
 
 
318
 
    def _make_output_stream_explicit(self, encoding, encoding_type):
319
 
        return NullOutputStream(encoding)
320
 
 
321
 
    def show_error(self, msg):
322
 
        pass
323
 
 
324
 
    def show_message(self, msg):
325
 
        pass
326
 
 
327
 
    def show_warning(self, msg):
328
 
        pass
329
 
 
330
 
 
331
 
class CannedInputUIFactory(SilentUIFactory):
332
 
    """A silent UI that return canned input."""
333
 
 
334
 
    def __init__(self, responses):
335
 
        self.responses = responses
336
 
 
337
 
    def __repr__(self):
338
 
        return "%s(%r)" % (self.__class__.__name__, self.responses)
339
 
 
340
 
    def get_boolean(self, prompt):
341
 
        return self.responses.pop(0)
342
 
 
343
 
    def get_integer(self, prompt):
344
 
        return self.responses.pop(0)
345
 
 
346
 
    def get_password(self, prompt='', **kwargs):
347
 
        return self.responses.pop(0)
348
 
 
349
 
    def get_username(self, prompt, **kwargs):
350
 
        return self.responses.pop(0)
351
 
 
352
 
    def assert_all_input_consumed(self):
353
 
        if self.responses:
354
 
            raise AssertionError("expected all input in %r to be consumed"
355
 
                % (self,))
356
 
 
357
 
 
358
 
ui_factory = SilentUIFactory()
359
 
# IMPORTANT: never import this symbol directly. ONLY ever access it as
360
 
# ui.ui_factory, so that you refer to the current value.
361
 
 
362
 
 
363
 
def make_ui_for_terminal(stdin, stdout, stderr):
364
 
    """Construct and return a suitable UIFactory for a text mode program.
365
 
    """
366
 
    # this is now always TextUIFactory, which in turn decides whether it
367
 
    # should display progress bars etc
368
 
    from bzrlib.ui.text import TextUIFactory
369
 
    return TextUIFactory(stdin, stdout, stderr)
370
 
 
371
 
 
372
 
class NullProgressView(object):
373
 
    """Soak up and ignore progress information."""
374
 
 
375
 
    def clear(self):
376
 
        pass
377
 
 
378
 
    def show_progress(self, task):
379
 
        pass
380
 
 
381
 
    def show_transport_activity(self, transport, direction, byte_count):
382
 
        pass
383
 
 
384
 
    def log_transport_activity(self, display=False):
385
 
        pass
386
 
 
387
 
 
388
 
class NullOutputStream(object):
389
 
    """Acts like a file, but discard all output."""
390
 
 
391
 
    def __init__(self, encoding):
392
 
        self.encoding = encoding
393
 
 
394
 
    def write(self, data):
395
 
        pass
396
 
 
397
 
    def writelines(self, data):
398
 
        pass
399
 
 
400
 
    def close(self):
401
 
        pass