~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/progress.py

  • Committer: John Arbash Meinel
  • Author(s): Mark Hammond
  • Date: 2008-09-09 17:02:21 UTC
  • mto: This revision was merged to the branch mainline in revision 3697.
  • Revision ID: john@arbash-meinel.com-20080909170221-svim3jw2mrz0amp3
An updated transparent icon for bzr.

Show diffs side-by-side

added added

removed removed

Lines of Context:
1
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.
 
2
# Copyright (C) 2005, 2006 Canonical Ltd
 
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
"""Progress indicators.
 
20
 
 
21
The usual way to use this is via bzrlib.ui.ui_factory.nested_progress_bar which
 
22
will maintain a ProgressBarStack for you.
 
23
 
 
24
For direct use, the factory ProgressBar will return an auto-detected progress
 
25
bar that should match your terminal type. You can manually create a
 
26
ProgressBarStack too if you need multiple levels of cooperating progress bars.
 
27
Note that bzrlib's internal functions use the ui module, so if you are using
 
28
bzrlib it really is best to use bzrlib.ui.ui_factory.
27
29
"""
28
30
 
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
31
# TODO: Optionally show elapsed time instead/as well as ETA; nicer
36
32
# when the rate is unpredictable
37
33
 
38
 
 
39
34
import sys
40
35
import time
41
36
import os
42
 
from collections import deque
 
37
 
 
38
from bzrlib.lazy_import import lazy_import
 
39
lazy_import(globals(), """
 
40
from bzrlib import (
 
41
    errors,
 
42
    )
 
43
""")
 
44
 
 
45
from bzrlib.trace import mutter
43
46
 
44
47
 
45
48
def _supports_progress(f):
46
 
    if not hasattr(f, 'isatty'):
 
49
    """Detect if we can use pretty progress bars on the output stream f.
 
50
 
 
51
    If this returns true we expect that a human may be looking at that 
 
52
    output, and that we can repaint a line to update it.
 
53
    """
 
54
    isatty = getattr(f, 'isatty', None)
 
55
    if isatty is None:
47
56
        return False
48
 
    if not f.isatty():
 
57
    if not isatty():
49
58
        return False
50
59
    if os.environ.get('TERM') == 'dumb':
51
60
        # e.g. emacs compile window
53
62
    return True
54
63
 
55
64
 
56
 
 
57
 
def ProgressBar(to_file=sys.stderr, **kwargs):
 
65
_progress_bar_types = {}
 
66
 
 
67
 
 
68
def ProgressBar(to_file=None, **kwargs):
58
69
    """Abstract factory"""
59
 
    if _supports_progress(to_file):
60
 
        return TTYProgressBar(to_file=to_file, **kwargs)
 
70
    if to_file is None:
 
71
        to_file = sys.stderr
 
72
    requested_bar_type = os.environ.get('BZR_PROGRESS_BAR')
 
73
    # An value of '' or not set reverts to standard processing
 
74
    if requested_bar_type in (None, ''):
 
75
        if _supports_progress(to_file):
 
76
            return TTYProgressBar(to_file=to_file, **kwargs)
 
77
        else:
 
78
            return DummyProgress(to_file=to_file, **kwargs)
61
79
    else:
62
 
        return DotsProgressBar(to_file=to_file, **kwargs)
63
 
    
64
 
    
 
80
        # Minor sanitation to prevent spurious errors
 
81
        requested_bar_type = requested_bar_type.lower().strip()
 
82
        # TODO: jam 20060710 Arguably we shouldn't raise an exception
 
83
        #       but should instead just disable progress bars if we
 
84
        #       don't recognize the type
 
85
        if requested_bar_type not in _progress_bar_types:
 
86
            raise errors.InvalidProgressBarType(requested_bar_type,
 
87
                                                _progress_bar_types.keys())
 
88
        return _progress_bar_types[requested_bar_type](to_file=to_file, **kwargs)
 
89
 
 
90
 
 
91
class ProgressBarStack(object):
 
92
    """A stack of progress bars."""
 
93
 
 
94
    def __init__(self,
 
95
                 to_file=None,
 
96
                 show_pct=False,
 
97
                 show_spinner=True,
 
98
                 show_eta=False,
 
99
                 show_bar=True,
 
100
                 show_count=True,
 
101
                 to_messages_file=None,
 
102
                 klass=None):
 
103
        """Setup the stack with the parameters the progress bars should have."""
 
104
        if to_file is None:
 
105
            to_file = sys.stderr
 
106
        if to_messages_file is None:
 
107
            to_messages_file = sys.stdout
 
108
        self._to_file = to_file
 
109
        self._show_pct = show_pct
 
110
        self._show_spinner = show_spinner
 
111
        self._show_eta = show_eta
 
112
        self._show_bar = show_bar
 
113
        self._show_count = show_count
 
114
        self._to_messages_file = to_messages_file
 
115
        self._stack = []
 
116
        self._klass = klass or ProgressBar
 
117
 
 
118
    def top(self):
 
119
        if len(self._stack) != 0:
 
120
            return self._stack[-1]
 
121
        else:
 
122
            return None
 
123
 
 
124
    def bottom(self):
 
125
        if len(self._stack) != 0:
 
126
            return self._stack[0]
 
127
        else:
 
128
            return None
 
129
 
 
130
    def get_nested(self):
 
131
        """Return a nested progress bar."""
 
132
        if len(self._stack) == 0:
 
133
            func = self._klass
 
134
        else:
 
135
            func = self.top().child_progress
 
136
        new_bar = func(to_file=self._to_file,
 
137
                       show_pct=self._show_pct,
 
138
                       show_spinner=self._show_spinner,
 
139
                       show_eta=self._show_eta,
 
140
                       show_bar=self._show_bar,
 
141
                       show_count=self._show_count,
 
142
                       to_messages_file=self._to_messages_file,
 
143
                       _stack=self)
 
144
        self._stack.append(new_bar)
 
145
        return new_bar
 
146
 
 
147
    def return_pb(self, bar):
 
148
        """Return bar after its been used."""
 
149
        if bar is not self._stack[-1]:
 
150
            raise errors.MissingProgressBarFinish()
 
151
        self._stack.pop()
 
152
 
 
153
 
65
154
class _BaseProgressBar(object):
 
155
 
66
156
    def __init__(self,
67
 
                 to_file=sys.stderr,
 
157
                 to_file=None,
68
158
                 show_pct=False,
69
159
                 show_spinner=False,
70
 
                 show_eta=True,
 
160
                 show_eta=False,
71
161
                 show_bar=True,
72
 
                 show_count=True):
 
162
                 show_count=True,
 
163
                 to_messages_file=None,
 
164
                 _stack=None):
73
165
        object.__init__(self)
 
166
        if to_file is None:
 
167
            to_file = sys.stderr
 
168
        if to_messages_file is None:
 
169
            to_messages_file = sys.stdout
74
170
        self.to_file = to_file
75
 
 
 
171
        self.to_messages_file = to_messages_file
76
172
        self.last_msg = None
77
173
        self.last_cnt = None
78
174
        self.last_total = None
81
177
        self.show_eta = show_eta
82
178
        self.show_bar = show_bar
83
179
        self.show_count = show_count
84
 
 
 
180
        self._stack = _stack
 
181
        # seed throttler
 
182
        self.MIN_PAUSE = 0.1 # seconds
 
183
        now = time.time()
 
184
        # starting now
 
185
        self.start_time = now
 
186
        # next update should not throttle
 
187
        self.last_update = now - self.MIN_PAUSE - 1
 
188
 
 
189
    def finished(self):
 
190
        """Return this bar to its progress stack."""
 
191
        self.clear()
 
192
        self._stack.return_pb(self)
 
193
 
 
194
    def note(self, fmt_string, *args, **kwargs):
 
195
        """Record a note without disrupting the progress bar."""
 
196
        self.clear()
 
197
        self.to_messages_file.write(fmt_string % args)
 
198
        self.to_messages_file.write('\n')
 
199
 
 
200
    def child_progress(self, **kwargs):
 
201
        return ChildProgress(**kwargs)
85
202
 
86
203
 
87
204
class DummyProgress(_BaseProgressBar):
95
212
    def update(self, msg=None, current=None, total=None):
96
213
        pass
97
214
 
 
215
    def child_update(self, message, current, total):
 
216
        pass
 
217
 
98
218
    def clear(self):
99
219
        pass
100
220
        
101
 
    
 
221
    def note(self, fmt_string, *args, **kwargs):
 
222
        """See _BaseProgressBar.note()."""
 
223
 
 
224
    def child_progress(self, **kwargs):
 
225
        return DummyProgress(**kwargs)
 
226
 
 
227
 
 
228
_progress_bar_types['dummy'] = DummyProgress
 
229
_progress_bar_types['none'] = DummyProgress
 
230
 
 
231
 
102
232
class DotsProgressBar(_BaseProgressBar):
 
233
 
103
234
    def __init__(self, **kwargs):
104
235
        _BaseProgressBar.__init__(self, **kwargs)
105
236
        self.last_msg = None
112
243
        if msg and msg != self.last_msg:
113
244
            if self.need_nl:
114
245
                self.to_file.write('\n')
115
 
            
116
246
            self.to_file.write(msg + ': ')
117
247
            self.last_msg = msg
118
248
        self.need_nl = True
121
251
    def clear(self):
122
252
        if self.need_nl:
123
253
            self.to_file.write('\n')
 
254
        self.need_nl = False
124
255
        
 
256
    def child_update(self, message, current, total):
 
257
        self.tick()
 
258
 
 
259
 
 
260
_progress_bar_types['dots'] = DotsProgressBar
 
261
 
125
262
    
126
263
class TTYProgressBar(_BaseProgressBar):
127
264
    """Progress bar display object.
144
281
    The output file should be in line-buffered or unbuffered mode.
145
282
    """
146
283
    SPIN_CHARS = r'/-\|'
147
 
    MIN_PAUSE = 0.1 # seconds
148
284
 
149
285
 
150
286
    def __init__(self, **kwargs):
152
288
        _BaseProgressBar.__init__(self, **kwargs)
153
289
        self.spin_pos = 0
154
290
        self.width = terminal_width()
155
 
        self.start_time = None
156
 
        self.last_update = None
157
 
        self.last_updates = deque()
 
291
        self.last_updates = []
 
292
        self._max_last_updates = 10
 
293
        self.child_fraction = 0
 
294
        self._have_output = False
158
295
    
159
 
 
160
 
    def throttle(self):
 
296
    def throttle(self, old_msg):
161
297
        """Return True if the bar was updated too recently"""
 
298
        # time.time consistently takes 40/4000 ms = 0.01 ms.
 
299
        # time.clock() is faster, but gives us CPU time, not wall-clock time
162
300
        now = time.time()
163
 
        if self.start_time is None:
164
 
            self.start_time = self.last_update = now
 
301
        if self.start_time is not None and (now - self.start_time) < 1:
 
302
            return True
 
303
        if old_msg != self.last_msg:
165
304
            return False
166
 
        else:
167
 
            interval = now - self.last_update
168
 
            if interval > 0 and interval < self.MIN_PAUSE:
169
 
                return True
 
305
        interval = now - self.last_update
 
306
        # if interval > 0
 
307
        if interval < self.MIN_PAUSE:
 
308
            return True
170
309
 
171
310
        self.last_updates.append(now - self.last_update)
 
311
        # Don't let the queue grow without bound
 
312
        self.last_updates = self.last_updates[-self._max_last_updates:]
172
313
        self.last_update = now
173
314
        return False
174
315
        
175
 
 
176
316
    def tick(self):
177
 
        self.update(self.last_msg, self.last_cnt, self.last_total)
178
 
                 
179
 
 
180
 
 
181
 
    def update(self, msg, current_cnt=None, total_cnt=None):
 
317
        self.update(self.last_msg, self.last_cnt, self.last_total,
 
318
                    self.child_fraction)
 
319
 
 
320
    def child_update(self, message, current, total):
 
321
        if current is not None and total != 0:
 
322
            child_fraction = float(current) / total
 
323
            if self.last_cnt is None:
 
324
                pass
 
325
            elif self.last_cnt + child_fraction <= self.last_total:
 
326
                self.child_fraction = child_fraction
 
327
        if self.last_msg is None:
 
328
            self.last_msg = ''
 
329
        self.tick()
 
330
 
 
331
    def update(self, msg, current_cnt=None, total_cnt=None,
 
332
               child_fraction=0):
182
333
        """Update and redraw progress bar."""
 
334
        if msg is None:
 
335
            msg = self.last_msg
 
336
 
 
337
        if total_cnt is None:
 
338
            total_cnt = self.last_total
183
339
 
184
340
        if current_cnt < 0:
185
341
            current_cnt = 0
186
342
            
187
343
        if current_cnt > total_cnt:
188
344
            total_cnt = current_cnt
 
345
        
 
346
        ## # optional corner case optimisation 
 
347
        ## # currently does not seem to fire so costs more than saved.
 
348
        ## # trivial optimal case:
 
349
        ## # NB if callers are doing a clear and restore with
 
350
        ## # the saved values, this will prevent that:
 
351
        ## # in that case add a restore method that calls
 
352
        ## # _do_update or some such
 
353
        ## if (self.last_msg == msg and
 
354
        ##     self.last_cnt == current_cnt and
 
355
        ##     self.last_total == total_cnt and
 
356
        ##     self.child_fraction == child_fraction):
 
357
        ##     return
189
358
 
 
359
        old_msg = self.last_msg
190
360
        # save these for the tick() function
191
361
        self.last_msg = msg
192
362
        self.last_cnt = current_cnt
193
363
        self.last_total = total_cnt
194
 
            
195
 
        if self.throttle():
196
 
            return 
197
 
        
198
 
        if self.show_eta and self.start_time and total_cnt:
199
 
            eta = get_eta(self.start_time, current_cnt, total_cnt,
200
 
                    last_updates = self.last_updates)
 
364
        self.child_fraction = child_fraction
 
365
 
 
366
        # each function call takes 20ms/4000 = 0.005 ms, 
 
367
        # but multiple that by 4000 calls -> starts to cost.
 
368
        # so anything to make this function call faster
 
369
        # will improve base 'diff' time by up to 0.1 seconds.
 
370
        if self.throttle(old_msg):
 
371
            return
 
372
 
 
373
        if self.show_eta and self.start_time and self.last_total:
 
374
            eta = get_eta(self.start_time, self.last_cnt + self.child_fraction, 
 
375
                    self.last_total, last_updates = self.last_updates)
201
376
            eta_str = " " + str_tdelta(eta)
202
377
        else:
203
378
            eta_str = ""
210
385
        # always update this; it's also used for the bar
211
386
        self.spin_pos += 1
212
387
 
213
 
        if self.show_pct and total_cnt and current_cnt:
214
 
            pct = 100.0 * current_cnt / total_cnt
 
388
        if self.show_pct and self.last_total and self.last_cnt:
 
389
            pct = 100.0 * ((self.last_cnt + self.child_fraction) / self.last_total)
215
390
            pct_str = ' (%5.1f%%)' % pct
216
391
        else:
217
392
            pct_str = ''
218
393
 
219
394
        if not self.show_count:
220
395
            count_str = ''
221
 
        elif current_cnt is None:
 
396
        elif self.last_cnt is None:
222
397
            count_str = ''
223
 
        elif total_cnt is None:
224
 
            count_str = ' %i' % (current_cnt)
 
398
        elif self.last_total is None:
 
399
            count_str = ' %i' % (self.last_cnt)
225
400
        else:
226
401
            # make both fields the same size
227
 
            t = '%i' % (total_cnt)
228
 
            c = '%*i' % (len(t), current_cnt)
 
402
            t = '%i' % (self.last_total)
 
403
            c = '%*i' % (len(t), self.last_cnt)
229
404
            count_str = ' ' + c + '/' + t 
230
405
 
231
406
        if self.show_bar:
232
407
            # progress bar, if present, soaks up all remaining space
233
 
            cols = self.width - 1 - len(msg) - len(spin_str) - len(pct_str) \
 
408
            cols = self.width - 1 - len(self.last_msg) - len(spin_str) - len(pct_str) \
234
409
                   - len(eta_str) - len(count_str) - 3
235
410
 
236
 
            if total_cnt:
 
411
            if self.last_total:
237
412
                # number of markers highlighted in bar
238
 
                markers = int(round(float(cols) * current_cnt / total_cnt))
 
413
                markers = int(round(float(cols) * 
 
414
                              (self.last_cnt + self.child_fraction) / self.last_total))
239
415
                bar_str = '[' + ('=' * markers).ljust(cols) + '] '
240
416
            elif False:
241
417
                # don't know total, so can't show completion.
249
425
        else:
250
426
            bar_str = ''
251
427
 
252
 
        m = spin_str + bar_str + msg + count_str + pct_str + eta_str
253
 
 
254
 
        assert len(m) < self.width
255
 
        self.to_file.write('\r' + m.ljust(self.width - 1))
 
428
        m = spin_str + bar_str + self.last_msg + count_str + pct_str + eta_str
 
429
        self.to_file.write('\r%-*.*s' % (self.width - 1, self.width - 1, m))
 
430
        self._have_output = True
256
431
        #self.to_file.flush()
257
432
            
258
 
 
259
 
    def clear(self):        
260
 
        self.to_file.write('\r%s\r' % (' ' * (self.width - 1)))
 
433
    def clear(self):
 
434
        if self._have_output:
 
435
            self.to_file.write('\r%s\r' % (' ' * (self.width - 1)))
 
436
        self._have_output = False
261
437
        #self.to_file.flush()        
262
 
    
263
 
 
264
 
        
 
438
 
 
439
 
 
440
_progress_bar_types['tty'] = TTYProgressBar
 
441
 
 
442
 
 
443
class ChildProgress(_BaseProgressBar):
 
444
    """A progress indicator that pushes its data to the parent"""
 
445
 
 
446
    def __init__(self, _stack, **kwargs):
 
447
        _BaseProgressBar.__init__(self, _stack=_stack, **kwargs)
 
448
        self.parent = _stack.top()
 
449
        self.current = None
 
450
        self.total = None
 
451
        self.child_fraction = 0
 
452
        self.message = None
 
453
 
 
454
    def update(self, msg, current_cnt=None, total_cnt=None):
 
455
        self.current = current_cnt
 
456
        if total_cnt is not None:
 
457
            self.total = total_cnt
 
458
        self.message = msg
 
459
        self.child_fraction = 0
 
460
        self.tick()
 
461
 
 
462
    def child_update(self, message, current, total):
 
463
        if current is None or total == 0:
 
464
            self.child_fraction = 0
 
465
        else:
 
466
            self.child_fraction = float(current) / total
 
467
        self.tick()
 
468
 
 
469
    def tick(self):
 
470
        if self.current is None:
 
471
            count = None
 
472
        else:
 
473
            count = self.current+self.child_fraction
 
474
            if count > self.total:
 
475
                if __debug__:
 
476
                    mutter('clamping count of %d to %d' % (count, self.total))
 
477
                count = self.total
 
478
        self.parent.child_update(self.message, count, self.total)
 
479
 
 
480
    def clear(self):
 
481
        pass
 
482
 
 
483
    def note(self, *args, **kwargs):
 
484
        self.parent.note(*args, **kwargs)
 
485
 
 
486
 
 
487
class InstrumentedProgress(TTYProgressBar):
 
488
    """TTYProgress variant that tracks outcomes"""
 
489
 
 
490
    def __init__(self, *args, **kwargs):
 
491
        self.always_throttled = True
 
492
        self.never_throttle = False
 
493
        TTYProgressBar.__init__(self, *args, **kwargs)
 
494
 
 
495
    def throttle(self, old_message):
 
496
        if self.never_throttle:
 
497
            result =  False
 
498
        else:
 
499
            result = TTYProgressBar.throttle(self, old_message)
 
500
        if result is False:
 
501
            self.always_throttled = False
 
502
 
 
503
 
265
504
def str_tdelta(delt):
266
505
    if delt is None:
267
506
        return "-:--:--"
291
530
    
292
531
    total_duration = float(elapsed) * float(total) / float(current)
293
532
 
294
 
    assert total_duration >= elapsed
295
 
 
296
533
    if last_updates and len(last_updates) >= n_recent:
297
 
        while len(last_updates) > n_recent:
298
 
            last_updates.popleft()
299
534
        avg = sum(last_updates) / float(len(last_updates))
300
535
        time_left = avg * (total - current)
301
536
 
307
542
    return total_duration - elapsed
308
543
 
309
544
 
310
 
def run_tests():
311
 
    import doctest
312
 
    result = doctest.testmod()
313
 
    if result[1] > 0:
314
 
        if result[0] == 0:
315
 
            print "All tests passed"
316
 
    else:
317
 
        print "No tests to run"
318
 
 
319
 
 
320
 
def demo():
321
 
    sleep = time.sleep
322
 
    
323
 
    print 'dumb-terminal test:'
324
 
    pb = DotsProgressBar()
325
 
    for i in range(100):
326
 
        pb.update('Leoparden', i, 99)
327
 
        sleep(0.1)
328
 
    sleep(1.5)
329
 
    pb.clear()
330
 
    sleep(1.5)
331
 
    
332
 
    print 'smart-terminal test:'
333
 
    pb = ProgressBar(show_pct=True, show_bar=True, show_spinner=False)
334
 
    for i in range(100):
335
 
        pb.update('Elephanten', i, 99)
336
 
        sleep(0.1)
337
 
    sleep(2)
338
 
    pb.clear()
339
 
    sleep(1)
340
 
 
341
 
    print 'done!'
342
 
 
343
 
if __name__ == "__main__":
344
 
    demo()
 
545
class ProgressPhase(object):
 
546
    """Update progress object with the current phase"""
 
547
    def __init__(self, message, total, pb):
 
548
        object.__init__(self)
 
549
        self.pb = pb
 
550
        self.message = message
 
551
        self.total = total
 
552
        self.cur_phase = None
 
553
 
 
554
    def next_phase(self):
 
555
        if self.cur_phase is None:
 
556
            self.cur_phase = 0
 
557
        else:
 
558
            self.cur_phase += 1
 
559
        self.pb.update(self.message, self.cur_phase, self.total)