/brz/remove-bazaar

To get this branch, use:
bzr branch http://gegoxaren.bato24.eu/bzr/brz/remove-bazaar

« back to all changes in this revision

Viewing changes to bzrlib/ui/__init__.py

  • Committer: Jonathan Lange
  • Date: 2009-12-16 06:38:15 UTC
  • mto: This revision was merged to the branch mainline in revision 4907.
  • Revision ID: jml@canonical.com-20091216063815-3p9cc9fzcfj5ten9
Remove flakes.

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
 
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
 
 
113
    def get_password(self, prompt='', **kwargs):
 
114
        """Prompt the user for a password.
 
115
 
 
116
        :param prompt: The prompt to present the user
 
117
        :param kwargs: Arguments which will be expanded into the prompt.
 
118
                       This lets front ends display different things if
 
119
                       they so choose.
 
120
 
 
121
        :return: The password string, return None if the user canceled the
 
122
                 request. Note that we do not touch the encoding, users may
 
123
                 have whatever they see fit and the password should be
 
124
                 transported as is.
 
125
        """
 
126
        raise NotImplementedError(self.get_password)
 
127
 
 
128
    def make_output_stream(self, encoding=None, encoding_type=None):
 
129
        """Get a stream for sending out bulk text data.
 
130
 
 
131
        This is used for commands that produce bulk text, such as log or diff
 
132
        output, as opposed to user interaction.  This should work even for
 
133
        non-interactive user interfaces.  Typically this goes to a decorated
 
134
        version of stdout, but in a GUI it might be appropriate to send it to a 
 
135
        window displaying the text.
 
136
     
 
137
        :param encoding: Unicode encoding for output; default is the 
 
138
            terminal encoding, which may be different from the user encoding.
 
139
            (See get_terminal_encoding.)
 
140
 
 
141
        :param encoding_type: How to handle encoding errors:
 
142
            replace/strict/escape/exact.  Default is replace.
 
143
        """
 
144
        # XXX: is the caller supposed to close the resulting object?
 
145
        if encoding is None:
 
146
            encoding = osutils.get_terminal_encoding()
 
147
        if encoding_type is None:
 
148
            encoding_type = 'replace'
 
149
        out_stream = self._make_output_stream_explicit(encoding, encoding_type)
 
150
        return out_stream
 
151
 
 
152
    def _make_output_stream_explicit(self, encoding, encoding_type):
 
153
        raise NotImplementedError("%s doesn't support make_output_stream"
 
154
            % (self.__class__.__name__))
 
155
 
 
156
    def nested_progress_bar(self):
 
157
        """Return a nested progress bar.
 
158
 
 
159
        When the bar has been finished with, it should be released by calling
 
160
        bar.finished().
 
161
        """
 
162
        if self._task_stack:
 
163
            t = progress.ProgressTask(self._task_stack[-1], self)
 
164
        else:
 
165
            t = progress.ProgressTask(None, self)
 
166
        self._task_stack.append(t)
 
167
        return t
 
168
 
 
169
    def _progress_finished(self, task):
 
170
        """Called by the ProgressTask when it finishes"""
 
171
        if not self._task_stack:
 
172
            warnings.warn("%r finished but nothing is active"
 
173
                % (task,))
 
174
        elif task != self._task_stack[-1]:
 
175
            warnings.warn("%r is not the active task %r"
 
176
                % (task, self._task_stack[-1]))
 
177
        else:
 
178
            del self._task_stack[-1]
 
179
        if not self._task_stack:
 
180
            self._progress_all_finished()
 
181
 
 
182
    def _progress_all_finished(self):
 
183
        """Called when the top-level progress task finished"""
 
184
        pass
 
185
 
 
186
    def _progress_updated(self, task):
 
187
        """Called by the ProgressTask when it changes.
 
188
 
 
189
        Should be specialized to draw the progress.
 
190
        """
 
191
        pass
 
192
 
 
193
    def clear_term(self):
 
194
        """Prepare the terminal for output.
 
195
 
 
196
        This will, for example, clear text progress bars, and leave the
 
197
        cursor at the leftmost position.
 
198
        """
 
199
        pass
 
200
 
 
201
    def get_boolean(self, prompt):
 
202
        """Get a boolean question answered from the user.
 
203
 
 
204
        :param prompt: a message to prompt the user with. Should be a single
 
205
        line without terminating \n.
 
206
        :return: True or False for y/yes or n/no.
 
207
        """
 
208
        raise NotImplementedError(self.get_boolean)
 
209
 
 
210
    def make_progress_view(self):
 
211
        """Construct a new ProgressView object for this UI.
 
212
 
 
213
        Application code should normally not call this but instead
 
214
        nested_progress_bar().
 
215
        """
 
216
        return NullProgressView()
 
217
 
 
218
    def recommend_upgrade(self,
 
219
        current_format_name,
 
220
        basedir):
 
221
        # this should perhaps be in the TextUIFactory and the default can do
 
222
        # nothing
 
223
        trace.warning("%s is deprecated "
 
224
            "and a better format is available.\n"
 
225
            "It is recommended that you upgrade by "
 
226
            "running the command\n"
 
227
            "  bzr upgrade %s",
 
228
            current_format_name,
 
229
            basedir)
 
230
 
 
231
    def report_transport_activity(self, transport, byte_count, direction):
 
232
        """Called by transports as they do IO.
 
233
 
 
234
        This may update a progress bar, spinner, or similar display.
 
235
        By default it does nothing.
 
236
        """
 
237
        pass
 
238
 
 
239
    def show_error(self, msg):
 
240
        """Show an error message (not an exception) to the user.
 
241
        
 
242
        The message should not have an error prefix or trailing newline.  That
 
243
        will be added by the factory if appropriate. 
 
244
        """
 
245
        raise NotImplementedError(self.show_error)
 
246
 
 
247
    def show_message(self, msg):
 
248
        """Show a message to the user."""
 
249
        raise NotImplementedError(self.show_message)
 
250
 
 
251
    def show_warning(self, msg):
 
252
        """Show a warning to the user."""
 
253
        raise NotImplementedError(self.show_warning)
 
254
 
 
255
 
 
256
 
 
257
class SilentUIFactory(UIFactory):
 
258
    """A UI Factory which never prints anything.
 
259
 
 
260
    This is the default UI, if another one is never registered by a program
 
261
    using bzrlib, and it's also active for example inside 'bzr serve'.
 
262
 
 
263
    Methods that try to read from the user raise an error; methods that do
 
264
    output do nothing.
 
265
    """
 
266
 
 
267
    def __init__(self):
 
268
        UIFactory.__init__(self)
 
269
 
 
270
    def note(self, msg):
 
271
        pass
 
272
 
 
273
    def get_username(self, prompt, **kwargs):
 
274
        return None
 
275
 
 
276
    def show_error(self, msg):
 
277
        pass
 
278
 
 
279
    def show_message(self, msg):
 
280
        pass
 
281
 
 
282
    def show_warning(self, msg):
 
283
        pass
 
284
 
 
285
 
 
286
class CannedInputUIFactory(SilentUIFactory):
 
287
    """A silent UI that return canned input."""
 
288
 
 
289
    def __init__(self, responses):
 
290
        self.responses = responses
 
291
 
 
292
    def __repr__(self):
 
293
        return "%s(%r)" % (self.__class__.__name__, self.responses)
 
294
 
 
295
    def get_boolean(self, prompt):
 
296
        return self.responses.pop(0)
 
297
 
 
298
    def get_password(self, prompt='', **kwargs):
 
299
        return self.responses.pop(0)
 
300
 
 
301
    def get_username(self, prompt, **kwargs):
 
302
        return self.responses.pop(0)
 
303
    
 
304
    def assert_all_input_consumed(self):
 
305
        if self.responses:
 
306
            raise AssertionError("expected all input in %r to be consumed"
 
307
                % (self,))
 
308
 
 
309
 
 
310
ui_factory = SilentUIFactory()
 
311
# IMPORTANT: never import this symbol directly. ONLY ever access it as
 
312
# ui.ui_factory, so that you refer to the current value.
 
313
 
 
314
 
 
315
def make_ui_for_terminal(stdin, stdout, stderr):
 
316
    """Construct and return a suitable UIFactory for a text mode program.
 
317
    """
 
318
    # this is now always TextUIFactory, which in turn decides whether it
 
319
    # should display progress bars etc
 
320
    from bzrlib.ui.text import TextUIFactory
 
321
    return TextUIFactory(stdin, stdout, stderr)
 
322
 
 
323
 
 
324
class NullProgressView(object):
 
325
    """Soak up and ignore progress information."""
 
326
 
 
327
    def clear(self):
 
328
        pass
 
329
 
 
330
    def show_progress(self, task):
 
331
        pass
 
332
 
 
333
    def show_transport_activity(self, transport, direction, byte_count):
 
334
        pass