← Back to branch summary

~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: 2008-05-29 15:57:16 UTC
  • mfrom: (3427.5.9 dep_warnings)
  • Revision ID: pqm@pqm.ubuntu.com-20080529155716-0w3kic8lioa63231
(jam) Enable Deprecation Warnings when running -Werror and when
        running selftest

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/progress.py
1
1
# Copyright (C) 2005 Aaron Bentley <aaron.bentley@utoronto.ca>
2
 
# Copyright (C) 2005, 2006 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
43
 
 
44
 
 
45
 
import bzrlib.errors as errors
46
 
from bzrlib.trace import mutter 
 
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
47
46
 
48
47
 
49
48
def _supports_progress(f):
50
 
    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:
51
56
        return False
52
 
    if not f.isatty():
 
57
    if not isatty():
53
58
        return False
54
59
    if os.environ.get('TERM') == 'dumb':
55
60
        # e.g. emacs compile window
57
62
    return True
58
63
 
59
64
 
60
 
 
61
 
def ProgressBar(to_file=sys.stderr, **kwargs):
 
65
_progress_bar_types = {}
 
66
 
 
67
 
 
68
def ProgressBar(to_file=None, **kwargs):
62
69
    """Abstract factory"""
63
 
    if _supports_progress(to_file):
64
 
        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)
65
79
    else:
66
 
        return DotsProgressBar(to_file=to_file, **kwargs)
67
 
    
 
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
 
68
90
 
69
91
class ProgressBarStack(object):
70
92
    """A stack of progress bars."""
71
93
 
72
94
    def __init__(self,
73
 
                 to_file=sys.stderr,
 
95
                 to_file=None,
74
96
                 show_pct=False,
75
97
                 show_spinner=True,
76
98
                 show_eta=False,
77
99
                 show_bar=True,
78
100
                 show_count=True,
79
 
                 to_messages_file=sys.stdout,
 
101
                 to_messages_file=None,
80
102
                 klass=None):
81
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
82
108
        self._to_file = to_file
83
109
        self._show_pct = show_pct
84
110
        self._show_spinner = show_spinner
87
113
        self._show_count = show_count
88
114
        self._to_messages_file = to_messages_file
89
115
        self._stack = []
90
 
        self._klass = klass or TTYProgressBar
 
116
        self._klass = klass or ProgressBar
91
117
 
92
118
    def top(self):
93
119
        if len(self._stack) != 0:
128
154
class _BaseProgressBar(object):
129
155
 
130
156
    def __init__(self,
131
 
                 to_file=sys.stderr,
 
157
                 to_file=None,
132
158
                 show_pct=False,
133
159
                 show_spinner=False,
134
 
                 show_eta=True,
 
160
                 show_eta=False,
135
161
                 show_bar=True,
136
162
                 show_count=True,
137
 
                 to_messages_file=sys.stdout,
 
163
                 to_messages_file=None,
138
164
                 _stack=None):
139
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
140
170
        self.to_file = to_file
141
171
        self.to_messages_file = to_messages_file
142
172
        self.last_msg = None
150
180
        self._stack = _stack
151
181
        # seed throttler
152
182
        self.MIN_PAUSE = 0.1 # seconds
153
 
        now = time.clock()
 
183
        now = time.time()
154
184
        # starting now
155
185
        self.start_time = now
156
186
        # next update should not throttle
159
189
    def finished(self):
160
190
        """Return this bar to its progress stack."""
161
191
        self.clear()
162
 
        assert self._stack is not None
163
192
        self._stack.return_pb(self)
164
193
 
165
194
    def note(self, fmt_string, *args, **kwargs):
195
224
    def child_progress(self, **kwargs):
196
225
        return DummyProgress(**kwargs)
197
226
 
 
227
 
 
228
_progress_bar_types['dummy'] = DummyProgress
 
229
_progress_bar_types['none'] = DummyProgress
 
230
 
 
231
 
198
232
class DotsProgressBar(_BaseProgressBar):
199
233
 
200
234
    def __init__(self, **kwargs):
209
243
        if msg and msg != self.last_msg:
210
244
            if self.need_nl:
211
245
                self.to_file.write('\n')
212
 
            
213
246
            self.to_file.write(msg + ': ')
214
247
            self.last_msg = msg
215
248
        self.need_nl = True
218
251
    def clear(self):
219
252
        if self.need_nl:
220
253
            self.to_file.write('\n')
 
254
        self.need_nl = False
221
255
        
222
256
    def child_update(self, message, current, total):
223
257
        self.tick()
 
258
 
 
259
 
 
260
_progress_bar_types['dots'] = DotsProgressBar
 
261
 
224
262
    
225
263
class TTYProgressBar(_BaseProgressBar):
226
264
    """Progress bar display object.
250
288
        _BaseProgressBar.__init__(self, **kwargs)
251
289
        self.spin_pos = 0
252
290
        self.width = terminal_width()
253
 
        self.start_time = None
254
 
        self.last_updates = deque()
 
291
        self.last_updates = []
 
292
        self._max_last_updates = 10
255
293
        self.child_fraction = 0
 
294
        self._have_output = False
256
295
    
257
 
 
258
 
    def throttle(self):
 
296
    def throttle(self, old_msg):
259
297
        """Return True if the bar was updated too recently"""
260
298
        # time.time consistently takes 40/4000 ms = 0.01 ms.
261
 
        # but every single update to the pb invokes it.
262
 
        # so we use time.clock which takes 20/4000 ms = 0.005ms
263
 
        # on the downside, time.clock() appears to have approximately
264
 
        # 10ms granularity, so we treat a zero-time change as 'throttled.'
265
 
        
266
 
        now = time.clock()
 
299
        # time.clock() is faster, but gives us CPU time, not wall-clock time
 
300
        now = time.time()
 
301
        if self.start_time is not None and (now - self.start_time) < 1:
 
302
            return True
 
303
        if old_msg != self.last_msg:
 
304
            return False
267
305
        interval = now - self.last_update
268
306
        # if interval > 0
269
307
        if interval < self.MIN_PAUSE:
270
308
            return True
271
309
 
272
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:]
273
313
        self.last_update = now
274
314
        return False
275
315
        
276
 
 
277
316
    def tick(self):
278
 
        self.update(self.last_msg, self.last_cnt, self.last_total, 
 
317
        self.update(self.last_msg, self.last_cnt, self.last_total,
279
318
                    self.child_fraction)
280
319
 
281
320
    def child_update(self, message, current, total):
285
324
                pass
286
325
            elif self.last_cnt + child_fraction <= self.last_total:
287
326
                self.child_fraction = child_fraction
288
 
            else:
289
 
                mutter('not updating child fraction')
290
327
        if self.last_msg is None:
291
328
            self.last_msg = ''
292
329
        self.tick()
293
330
 
294
 
 
295
 
    def update(self, msg, current_cnt=None, total_cnt=None, 
 
331
    def update(self, msg, current_cnt=None, total_cnt=None,
296
332
               child_fraction=0):
297
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
298
339
 
299
340
        if current_cnt < 0:
300
341
            current_cnt = 0
326
367
        # but multiple that by 4000 calls -> starts to cost.
327
368
        # so anything to make this function call faster
328
369
        # will improve base 'diff' time by up to 0.1 seconds.
329
 
        if old_msg == self.last_msg and self.throttle():
 
370
        if self.throttle(old_msg):
330
371
            return
331
372
 
332
373
        if self.show_eta and self.start_time and self.last_total:
385
426
            bar_str = ''
386
427
 
387
428
        m = spin_str + bar_str + self.last_msg + count_str + pct_str + eta_str
388
 
 
389
 
        assert len(m) < self.width
390
 
        self.to_file.write('\r' + m.ljust(self.width - 1))
 
429
        self.to_file.write('\r%-*.*s' % (self.width - 1, self.width - 1, m))
 
430
        self._have_output = True
391
431
        #self.to_file.flush()
392
432
            
393
 
    def clear(self):        
394
 
        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
395
437
        #self.to_file.flush()        
396
438
 
397
439
 
 
440
_progress_bar_types['tty'] = TTYProgressBar
 
441
 
 
442
 
398
443
class ChildProgress(_BaseProgressBar):
399
444
    """A progress indicator that pushes its data to the parent"""
 
445
 
400
446
    def __init__(self, _stack, **kwargs):
401
447
        _BaseProgressBar.__init__(self, _stack=_stack, **kwargs)
402
448
        self.parent = _stack.top()
407
453
 
408
454
    def update(self, msg, current_cnt=None, total_cnt=None):
409
455
        self.current = current_cnt
410
 
        self.total = total_cnt
 
456
        if total_cnt is not None:
 
457
            self.total = total_cnt
411
458
        self.message = msg
412
459
        self.child_fraction = 0
413
460
        self.tick()
436
483
    def note(self, *args, **kwargs):
437
484
        self.parent.note(*args, **kwargs)
438
485
 
439
 
 
 
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
 
440
504
def str_tdelta(delt):
441
505
    if delt is None:
442
506
        return "-:--:--"
459
523
    if current > total:
460
524
        return None                     # wtf?
461
525
 
462
 
    elapsed = time.clock() - start_time
 
526
    elapsed = time.time() - start_time
463
527
 
464
528
    if elapsed < 2.0:                   # not enough time to estimate
465
529
        return None
466
530
    
467
531
    total_duration = float(elapsed) * float(total) / float(current)
468
532
 
469
 
    assert total_duration >= elapsed
470
 
 
471
533
    if last_updates and len(last_updates) >= n_recent:
472
 
        while len(last_updates) > n_recent:
473
 
            last_updates.popleft()
474
534
        avg = sum(last_updates) / float(len(last_updates))
475
535
        time_left = avg * (total - current)
476
536
 
496
556
            self.cur_phase = 0
497
557
        else:
498
558
            self.cur_phase += 1
499
 
        assert self.cur_phase < self.total 
500
559
        self.pb.update(self.message, self.cur_phase, self.total)
501
 
 
502
 
 
503
 
def run_tests():
504
 
    import doctest
505
 
    result = doctest.testmod()
506
 
    if result[1] > 0:
507
 
        if result[0] == 0:
508
 
            print "All tests passed"
509
 
    else:
510
 
        print "No tests to run"
511
 
 
512
 
 
513
 
def demo():
514
 
    sleep = time.sleep
515
 
    
516
 
    print 'dumb-terminal test:'
517
 
    pb = DotsProgressBar()
518
 
    for i in range(100):
519
 
        pb.update('Leoparden', i, 99)
520
 
        sleep(0.1)
521
 
    sleep(1.5)
522
 
    pb.clear()
523
 
    sleep(1.5)
524
 
    
525
 
    print 'smart-terminal test:'
526
 
    pb = ProgressBar(show_pct=True, show_bar=True, show_spinner=False)
527
 
    for i in range(100):
528
 
        pb.update('Elephanten', i, 99)
529
 
        sleep(0.1)
530
 
    sleep(2)
531
 
    pb.clear()
532
 
    sleep(1)
533
 
 
534
 
    print 'done!'
535
 
 
536
 
if __name__ == "__main__":
537
 
    demo()