~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/progress.py

  • Committer: Canonical.com Patch Queue Manager
  • Date: 2010-03-27 10:31:11 UTC
  • mfrom: (5118.1.1 news)
  • Revision ID: pqm@pqm.ubuntu.com-20100327103111-4g435d39ujhe95vp
(vila) Fix bug numbers and delete duplicated entry.

Show diffs side-by-side

added added

removed removed

Lines of Context:
1
 
# Copyright (C) 2005 Aaron Bentley <aaron.bentley@utoronto.ca>
2
 
# Copyright (C) 2005 Canonical <canonical.com>
3
 
#
4
 
#    This program is free software; you can redistribute it and/or modify
5
 
#    it under the terms of the GNU General Public License as published by
6
 
#    the Free Software Foundation; either version 2 of the License, or
7
 
#    (at your option) any later version.
8
 
#
9
 
#    This program is distributed in the hope that it will be useful,
10
 
#    but WITHOUT ANY WARRANTY; without even the implied warranty of
11
 
#    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12
 
#    GNU General Public License for more details.
13
 
#
14
 
#    You should have received a copy of the GNU General Public License
15
 
#    along with this program; if not, write to the Free Software
16
 
#    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
17
 
 
18
 
 
19
 
"""Simple text-mode progress indicator.
20
 
 
21
 
To display an indicator, create a ProgressBar object.  Call it,
22
 
passing Progress objects indicating the current state.  When done,
23
 
call clear().
24
 
 
25
 
Progress is suppressed when output is not sent to a terminal, so as
26
 
not to clutter log files.
 
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
 
 
18
"""Progress indicators.
 
19
 
 
20
The usual way to use this is via bzrlib.ui.ui_factory.nested_progress_bar which
 
21
will manage a conceptual stack of nested activities.
27
22
"""
28
23
 
29
 
# TODO: should be a global option e.g. --silent that disables progress
30
 
# indicators, preferably without needing to adjust all code that
31
 
# potentially calls them.
32
 
 
33
 
# TODO: If not on a tty perhaps just print '......' for the benefit of IDEs, etc
34
 
 
35
 
# TODO: Optionally show elapsed time instead/as well as ETA; nicer
36
 
# when the rate is unpredictable
37
 
 
38
24
 
39
25
import sys
40
26
import time
41
27
import os
42
28
 
43
29
 
44
 
def _width():
45
 
    """Return estimated terminal width.
46
 
 
47
 
    TODO: Do something smart on Windows?
48
 
 
49
 
    TODO: Is there anything that gets a better update when the window
50
 
          is resized while the program is running?
51
 
    """
52
 
    try:
53
 
        return int(os.environ['COLUMNS'])
54
 
    except (IndexError, KeyError, ValueError):
55
 
        return 80
 
30
from bzrlib import (
 
31
    errors,
 
32
    )
 
33
from bzrlib.trace import mutter
 
34
from bzrlib.symbol_versioning import (
 
35
    deprecated_function,
 
36
    deprecated_in,
 
37
    deprecated_method,
 
38
    )
56
39
 
57
40
 
58
41
def _supports_progress(f):
59
 
    if not hasattr(f, 'isatty'):
60
 
        return False
61
 
    if not f.isatty():
62
 
        return False
 
42
    """Detect if we can use pretty progress bars on file F.
 
43
 
 
44
    If this returns true we expect that a human may be looking at that
 
45
    output, and that we can repaint a line to update it.
 
46
 
 
47
    This doesn't check the policy for whether we *should* use them.
 
48
    """
 
49
    isatty = getattr(f, 'isatty', None)
 
50
    if isatty is None:
 
51
        return False
 
52
    if not isatty():
 
53
        return False
 
54
    # The following case also handles Win32 - on that platform $TERM is
 
55
    # typically never set, so the case None is treated as a smart terminal,
 
56
    # not dumb.  <https://bugs.launchpad.net/bugs/334808>  win32 files do have
 
57
    # isatty methods that return true.
63
58
    if os.environ.get('TERM') == 'dumb':
64
59
        # e.g. emacs compile window
65
60
        return False
66
61
    return True
67
62
 
68
63
 
69
 
 
70
 
def ProgressBar(to_file=sys.stderr, **kwargs):
71
 
    """Abstract factory"""
72
 
    if _supports_progress(to_file):
73
 
        return TTYProgressBar(to_file=to_file, **kwargs)
74
 
    else:
75
 
        return DotsProgressBar(to_file=to_file, **kwargs)
76
 
    
77
 
    
 
64
class ProgressTask(object):
 
65
    """Model component of a progress indicator.
 
66
 
 
67
    Most code that needs to indicate progress should update one of these,
 
68
    and it will in turn update the display, if one is present.
 
69
 
 
70
    Code updating the task may also set fields as hints about how to display
 
71
    it: show_pct, show_spinner, show_eta, show_count, show_bar.  UIs
 
72
    will not necessarily respect all these fields.
 
73
    
 
74
    :ivar update_latency: The interval (in seconds) at which the PB should be
 
75
        updated.  Setting this to zero suggests every update should be shown
 
76
        synchronously.
 
77
 
 
78
    :ivar show_transport_activity: If true (default), transport activity
 
79
        will be shown when this task is drawn.  Disable it if you're sure 
 
80
        that only irrelevant or uninteresting transport activity can occur
 
81
        during this task.
 
82
    """
 
83
 
 
84
    def __init__(self, parent_task=None, ui_factory=None, progress_view=None):
 
85
        """Construct a new progress task.
 
86
 
 
87
        :param parent_task: Enclosing ProgressTask or None.
 
88
 
 
89
        :param progress_view: ProgressView to display this ProgressTask.
 
90
 
 
91
        :param ui_factory: The UI factory that will display updates; 
 
92
            deprecated in favor of passing progress_view directly.
 
93
 
 
94
        Normally you should not call this directly but rather through
 
95
        `ui_factory.nested_progress_bar`.
 
96
        """
 
97
        self._parent_task = parent_task
 
98
        self._last_update = 0
 
99
        self.total_cnt = None
 
100
        self.current_cnt = None
 
101
        self.msg = ''
 
102
        # TODO: deprecate passing ui_factory
 
103
        self.ui_factory = ui_factory
 
104
        self.progress_view = progress_view
 
105
        self.show_pct = False
 
106
        self.show_spinner = True
 
107
        self.show_eta = False,
 
108
        self.show_count = True
 
109
        self.show_bar = True
 
110
        self.update_latency = 0.1
 
111
        self.show_transport_activity = True
 
112
 
 
113
    def __repr__(self):
 
114
        return '%s(%r/%r, msg=%r)' % (
 
115
            self.__class__.__name__,
 
116
            self.current_cnt,
 
117
            self.total_cnt,
 
118
            self.msg)
 
119
 
 
120
    def update(self, msg, current_cnt=None, total_cnt=None):
 
121
        self.msg = msg
 
122
        self.current_cnt = current_cnt
 
123
        if total_cnt:
 
124
            self.total_cnt = total_cnt
 
125
        if self.progress_view:
 
126
            self.progress_view.show_progress(self)
 
127
        else:
 
128
            self.ui_factory._progress_updated(self)
 
129
 
 
130
    def tick(self):
 
131
        self.update(self.msg)
 
132
 
 
133
    def finished(self):
 
134
        if self.progress_view:
 
135
            self.progress_view.task_finished(self)
 
136
        else:
 
137
            self.ui_factory._progress_finished(self)
 
138
 
 
139
    def make_sub_task(self):
 
140
        return ProgressTask(self, ui_factory=self.ui_factory,
 
141
            progress_view=self.progress_view)
 
142
 
 
143
    def _overall_completion_fraction(self, child_fraction=0.0):
 
144
        """Return fractional completion of this task and its parents
 
145
 
 
146
        Returns None if no completion can be computed."""
 
147
        if self.current_cnt is not None and self.total_cnt:
 
148
            own_fraction = (float(self.current_cnt) + child_fraction) / self.total_cnt
 
149
        else:
 
150
            # if this task has no estimation, it just passes on directly
 
151
            # whatever the child has measured...
 
152
            own_fraction = child_fraction
 
153
        if self._parent_task is None:
 
154
            return own_fraction
 
155
        else:
 
156
            if own_fraction is None:
 
157
                own_fraction = 0.0
 
158
            return self._parent_task._overall_completion_fraction(own_fraction)
 
159
 
 
160
    @deprecated_method(deprecated_in((2, 1, 0)))
 
161
    def note(self, fmt_string, *args):
 
162
        """Record a note without disrupting the progress bar.
 
163
        
 
164
        Deprecated: use ui_factory.note() instead or bzrlib.trace.  Note that
 
165
        ui_factory.note takes just one string as the argument, not a format
 
166
        string and arguments.
 
167
        """
 
168
        if args:
 
169
            self.ui_factory.note(fmt_string % args)
 
170
        else:
 
171
            self.ui_factory.note(fmt_string)
 
172
 
 
173
    def clear(self):
 
174
        # TODO: deprecate this method; the model object shouldn't be concerned
 
175
        # with whether it's shown or not.  Most callers use this because they
 
176
        # want to write some different non-progress output to the screen, but
 
177
        # they should probably instead use a stream that's synchronized with
 
178
        # the progress output.  It may be there is a model-level use for
 
179
        # saying "this task's not active at the moment" but I don't see it. --
 
180
        # mbp 20090623
 
181
        if self.progress_view:
 
182
            self.progress_view.clear()
 
183
        else:
 
184
            self.ui_factory.clear_term()
 
185
 
 
186
 
 
187
# NOTE: This is also deprecated; you should provide a ProgressView instead.
78
188
class _BaseProgressBar(object):
 
189
 
79
190
    def __init__(self,
80
 
                 to_file=sys.stderr,
 
191
                 to_file=None,
81
192
                 show_pct=False,
82
193
                 show_spinner=False,
83
 
                 show_eta=True,
 
194
                 show_eta=False,
84
195
                 show_bar=True,
85
 
                 show_count=True):
 
196
                 show_count=True,
 
197
                 to_messages_file=None,
 
198
                 _stack=None):
86
199
        object.__init__(self)
 
200
        if to_file is None:
 
201
            to_file = sys.stderr
 
202
        if to_messages_file is None:
 
203
            to_messages_file = sys.stdout
87
204
        self.to_file = to_file
88
 
 
 
205
        self.to_messages_file = to_messages_file
89
206
        self.last_msg = None
90
207
        self.last_cnt = None
91
208
        self.last_total = None
94
211
        self.show_eta = show_eta
95
212
        self.show_bar = show_bar
96
213
        self.show_count = show_count
97
 
 
98
 
 
99
 
 
100
 
class DummyProgress(_BaseProgressBar):
 
214
        self._stack = _stack
 
215
        # seed throttler
 
216
        self.MIN_PAUSE = 0.1 # seconds
 
217
        now = time.time()
 
218
        # starting now
 
219
        self.start_time = now
 
220
        # next update should not throttle
 
221
        self.last_update = now - self.MIN_PAUSE - 1
 
222
 
 
223
    def finished(self):
 
224
        """Return this bar to its progress stack."""
 
225
        self.clear()
 
226
        self._stack.return_pb(self)
 
227
 
 
228
    def note(self, fmt_string, *args, **kwargs):
 
229
        """Record a note without disrupting the progress bar."""
 
230
        self.clear()
 
231
        self.to_messages_file.write(fmt_string % args)
 
232
        self.to_messages_file.write('\n')
 
233
 
 
234
 
 
235
class DummyProgress(object):
101
236
    """Progress-bar standin that does nothing.
102
237
 
103
 
    This can be used as the default argument for methods that
104
 
    take an optional progress indicator."""
 
238
    This was previously often constructed by application code if no progress
 
239
    bar was explicitly passed in.  That's no longer recommended: instead, just
 
240
    create a progress task from the ui_factory.  This class can be used in
 
241
    test code that needs to fake a progress task for some reason.
 
242
    """
 
243
 
105
244
    def tick(self):
106
245
        pass
107
246
 
108
247
    def update(self, msg=None, current=None, total=None):
109
248
        pass
110
249
 
111
 
    def clear(self):
112
 
        pass
113
 
        
114
 
    
115
 
class DotsProgressBar(_BaseProgressBar):
116
 
    def __init__(self, **kwargs):
117
 
        _BaseProgressBar.__init__(self, **kwargs)
118
 
        self.last_msg = None
119
 
        self.need_nl = False
120
 
        
121
 
    def tick(self):
122
 
        self.update()
123
 
        
124
 
    def update(self, msg=None, current_cnt=None, total_cnt=None):
125
 
        if msg and msg != self.last_msg:
126
 
            if self.need_nl:
127
 
                self.to_file.write('\n')
128
 
            
129
 
            self.to_file.write(msg + ': ')
130
 
            self.last_msg = msg
131
 
        self.need_nl = True
132
 
        self.to_file.write('.')
133
 
        
134
 
    def clear(self):
135
 
        if self.need_nl:
136
 
            self.to_file.write('\n')
137
 
        
138
 
    
139
 
class TTYProgressBar(_BaseProgressBar):
140
 
    """Progress bar display object.
141
 
 
142
 
    Several options are available to control the display.  These can
143
 
    be passed as parameters to the constructor or assigned at any time:
144
 
 
145
 
    show_pct
146
 
        Show percentage complete.
147
 
    show_spinner
148
 
        Show rotating baton.  This ticks over on every update even
149
 
        if the values don't change.
150
 
    show_eta
151
 
        Show predicted time-to-completion.
152
 
    show_bar
153
 
        Show bar graph.
154
 
    show_count
155
 
        Show numerical counts.
156
 
 
157
 
    The output file should be in line-buffered or unbuffered mode.
158
 
    """
159
 
    SPIN_CHARS = r'/-\|'
160
 
    MIN_PAUSE = 0.1 # seconds
161
 
 
162
 
 
163
 
    def __init__(self, **kwargs):
164
 
        _BaseProgressBar.__init__(self, **kwargs)
165
 
        self.spin_pos = 0
166
 
        self.width = _width()
167
 
        self.start_time = None
168
 
        self.last_update = None
169
 
    
170
 
 
171
 
    def throttle(self):
172
 
        """Return True if the bar was updated too recently"""
173
 
        now = time.time()
174
 
        if self.start_time is None:
175
 
            self.start_time = self.last_update = now
176
 
            return False
177
 
        else:
178
 
            interval = now - self.last_update
179
 
            if interval > 0 and interval < self.MIN_PAUSE:
180
 
                return True
181
 
 
182
 
        self.last_update = now
183
 
        return False
184
 
        
185
 
 
186
 
    def tick(self):
187
 
        self.update(self.last_msg, self.last_cnt, self.last_total)
188
 
                 
189
 
 
190
 
 
191
 
    def update(self, msg, current_cnt=None, total_cnt=None):
192
 
        """Update and redraw progress bar."""
193
 
 
194
 
        # save these for the tick() function
195
 
        self.last_msg = msg
196
 
        self.last_cnt = current_cnt
197
 
        self.last_total = total_cnt
198
 
            
199
 
        if self.throttle():
200
 
            return 
201
 
        
202
 
        if total_cnt:
203
 
            assert current_cnt <= total_cnt
204
 
        if current_cnt:
205
 
            assert current_cnt >= 0
206
 
        
207
 
        if self.show_eta and self.start_time and total_cnt:
208
 
            eta = get_eta(self.start_time, current_cnt, total_cnt)
209
 
            eta_str = " " + str_tdelta(eta)
210
 
        else:
211
 
            eta_str = ""
212
 
 
213
 
        if self.show_spinner:
214
 
            spin_str = self.SPIN_CHARS[self.spin_pos % 4] + ' '            
215
 
        else:
216
 
            spin_str = ''
217
 
 
218
 
        # always update this; it's also used for the bar
219
 
        self.spin_pos += 1
220
 
 
221
 
        if self.show_pct and total_cnt and current_cnt:
222
 
            pct = 100.0 * current_cnt / total_cnt
223
 
            pct_str = ' (%5.1f%%)' % pct
224
 
        else:
225
 
            pct_str = ''
226
 
 
227
 
        if not self.show_count:
228
 
            count_str = ''
229
 
        elif current_cnt is None:
230
 
            count_str = ''
231
 
        elif total_cnt is None:
232
 
            count_str = ' %i' % (current_cnt)
233
 
        else:
234
 
            # make both fields the same size
235
 
            t = '%i' % (total_cnt)
236
 
            c = '%*i' % (len(t), current_cnt)
237
 
            count_str = ' ' + c + '/' + t 
238
 
 
239
 
        if self.show_bar:
240
 
            # progress bar, if present, soaks up all remaining space
241
 
            cols = self.width - 1 - len(msg) - len(spin_str) - len(pct_str) \
242
 
                   - len(eta_str) - len(count_str) - 3
243
 
 
244
 
            if total_cnt:
245
 
                # number of markers highlighted in bar
246
 
                markers = int(round(float(cols) * current_cnt / total_cnt))
247
 
                bar_str = '[' + ('=' * markers).ljust(cols) + '] '
248
 
            elif False:
249
 
                # don't know total, so can't show completion.
250
 
                # so just show an expanded spinning thingy
251
 
                m = self.spin_pos % cols
252
 
                ms = (' ' * m + '*').ljust(cols)
253
 
                
254
 
                bar_str = '[' + ms + '] '
255
 
            else:
256
 
                bar_str = ''
257
 
        else:
258
 
            bar_str = ''
259
 
 
260
 
        m = spin_str + bar_str + msg + count_str + pct_str + eta_str
261
 
 
262
 
        assert len(m) < self.width
263
 
        self.to_file.write('\r' + m.ljust(self.width - 1))
264
 
        #self.to_file.flush()
265
 
            
266
 
 
267
 
    def clear(self):        
268
 
        self.to_file.write('\r%s\r' % (' ' * (self.width - 1)))
269
 
        #self.to_file.flush()        
270
 
    
271
 
 
272
 
        
 
250
    def child_update(self, message, current, total):
 
251
        pass
 
252
 
 
253
    def clear(self):
 
254
        pass
 
255
 
 
256
    def note(self, fmt_string, *args, **kwargs):
 
257
        """See _BaseProgressBar.note()."""
 
258
 
 
259
    def child_progress(self, **kwargs):
 
260
        return DummyProgress(**kwargs)
 
261
 
 
262
 
273
263
def str_tdelta(delt):
274
264
    if delt is None:
275
265
        return "-:--:--"
279
269
                             delt % 60)
280
270
 
281
271
 
282
 
def get_eta(start_time, current, total, enough_samples=3):
 
272
def get_eta(start_time, current, total, enough_samples=3, last_updates=None, n_recent=10):
283
273
    if start_time is None:
284
274
        return None
285
275
 
296
286
 
297
287
    if elapsed < 2.0:                   # not enough time to estimate
298
288
        return None
299
 
    
 
289
 
300
290
    total_duration = float(elapsed) * float(total) / float(current)
301
291
 
302
 
    assert total_duration >= elapsed
 
292
    if last_updates and len(last_updates) >= n_recent:
 
293
        avg = sum(last_updates) / float(len(last_updates))
 
294
        time_left = avg * (total - current)
 
295
 
 
296
        old_time_left = total_duration - elapsed
 
297
 
 
298
        # We could return the average, or some other value here
 
299
        return (time_left + old_time_left) / 2
303
300
 
304
301
    return total_duration - elapsed
305
302
 
306
303
 
307
 
def run_tests():
308
 
    import doctest
309
 
    result = doctest.testmod()
310
 
    if result[1] > 0:
311
 
        if result[0] == 0:
312
 
            print "All tests passed"
313
 
    else:
314
 
        print "No tests to run"
315
 
 
316
 
 
317
 
def demo():
318
 
    sleep = time.sleep
319
 
    
320
 
    print 'dumb-terminal test:'
321
 
    pb = DotsProgressBar()
322
 
    for i in range(100):
323
 
        pb.update('Leoparden', i, 99)
324
 
        sleep(0.1)
325
 
    sleep(1.5)
326
 
    pb.clear()
327
 
    sleep(1.5)
328
 
    
329
 
    print 'smart-terminal test:'
330
 
    pb = ProgressBar(show_pct=True, show_bar=True, show_spinner=False)
331
 
    for i in range(100):
332
 
        pb.update('Elephanten', i, 99)
333
 
        sleep(0.1)
334
 
    sleep(2)
335
 
    pb.clear()
336
 
    sleep(1)
337
 
 
338
 
    print 'done!'
339
 
 
340
 
if __name__ == "__main__":
341
 
    demo()
 
304
class ProgressPhase(object):
 
305
    """Update progress object with the current phase"""
 
306
    def __init__(self, message, total, pb):
 
307
        object.__init__(self)
 
308
        self.pb = pb
 
309
        self.message = message
 
310
        self.total = total
 
311
        self.cur_phase = None
 
312
 
 
313
    def next_phase(self):
 
314
        if self.cur_phase is None:
 
315
            self.cur_phase = 0
 
316
        else:
 
317
            self.cur_phase += 1
 
318
        self.pb.update(self.message, self.cur_phase, self.total)