← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/progress.py

  • Committer: Ian Clatworthy
  • Date: 2009-09-09 11:43:10 UTC
  • mto: (4634.37.2 prepare-2.0)
  • mto: This revision was merged to the branch mainline in revision 4689.
  • Revision ID: ian.clatworthy@canonical.com-20090909114310-glw7tv76i5gnx9pt
put rules back in Makefile supporting plain-style docs

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/progress.py
1
 
# Copyright (C) 2005 Aaron Bentley <aaron.bentley@utoronto.ca>
2
 
# Copyright (C) 2005, 2006 Canonical Ltd
 
1
# Copyright (C) 2005, 2006, 2008, 2009 Canonical Ltd
3
2
#
4
3
# This program is free software; you can redistribute it and/or modify
5
4
# it under the terms of the GNU General Public License as published by
13
12
#
14
13
# You should have received a copy of the GNU General Public License
15
14
# 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.
 
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
24
 
38
25
import sys
39
26
import time
40
27
import os
41
28
 
42
 
from bzrlib.lazy_import import lazy_import
43
 
lazy_import(globals(), """
 
29
 
44
30
from bzrlib import (
45
31
    errors,
46
32
    )
47
 
""")
48
 
 
49
33
from bzrlib.trace import mutter
 
34
from bzrlib.symbol_versioning import (
 
35
    deprecated_function,
 
36
    deprecated_in,
 
37
    )
50
38
 
51
39
 
52
40
def _supports_progress(f):
53
 
    """Detect if we can use pretty progress bars on the output stream f.
 
41
    """Detect if we can use pretty progress bars on file F.
54
42
 
55
 
    If this returns true we expect that a human may be looking at that 
 
43
    If this returns true we expect that a human may be looking at that
56
44
    output, and that we can repaint a line to update it.
 
45
 
 
46
    This doesn't check the policy for whether we *should* use them.
57
47
    """
58
48
    isatty = getattr(f, 'isatty', None)
59
49
    if isatty is None:
60
50
        return False
61
51
    if not isatty():
62
52
        return False
 
53
    # The following case also handles Win32 - on that platform $TERM is
 
54
    # typically never set, so the case None is treated as a smart terminal,
 
55
    # not dumb.  <https://bugs.launchpad.net/bugs/334808>  win32 files do have
 
56
    # isatty methods that return true.
63
57
    if os.environ.get('TERM') == 'dumb':
64
58
        # e.g. emacs compile window
65
59
        return False
66
60
    return True
67
61
 
68
62
 
69
 
_progress_bar_types = {}
70
 
 
71
 
 
 
63
class ProgressTask(object):
 
64
    """Model component of a progress indicator.
 
65
 
 
66
    Most code that needs to indicate progress should update one of these,
 
67
    and it will in turn update the display, if one is present.
 
68
 
 
69
    Code updating the task may also set fields as hints about how to display
 
70
    it: show_pct, show_spinner, show_eta, show_count, show_bar.  UIs
 
71
    will not necessarily respect all these fields.
 
72
    
 
73
    :ivar update_latency: The interval (in seconds) at which the PB should be
 
74
        updated.  Setting this to zero suggests every update should be shown
 
75
        synchronously.
 
76
 
 
77
    :ivar show_transport_activity: If true (default), transport activity
 
78
        will be shown when this task is drawn.  Disable it if you're sure 
 
79
        that only irrelevant or uninteresting transport activity can occur
 
80
        during this task.
 
81
    """
 
82
 
 
83
    def __init__(self, parent_task=None, ui_factory=None, progress_view=None):
 
84
        """Construct a new progress task.
 
85
 
 
86
        :param parent_task: Enclosing ProgressTask or None.
 
87
 
 
88
        :param progress_view: ProgressView to display this ProgressTask.
 
89
 
 
90
        :param ui_factory: The UI factory that will display updates; 
 
91
            deprecated in favor of passing progress_view directly.
 
92
 
 
93
        Normally you should not call this directly but rather through
 
94
        `ui_factory.nested_progress_bar`.
 
95
        """
 
96
        self._parent_task = parent_task
 
97
        self._last_update = 0
 
98
        self.total_cnt = None
 
99
        self.current_cnt = None
 
100
        self.msg = ''
 
101
        # TODO: deprecate passing ui_factory
 
102
        self.ui_factory = ui_factory
 
103
        self.progress_view = progress_view
 
104
        self.show_pct = False
 
105
        self.show_spinner = True
 
106
        self.show_eta = False,
 
107
        self.show_count = True
 
108
        self.show_bar = True
 
109
        self.update_latency = 0.1
 
110
        self.show_transport_activity = True
 
111
 
 
112
    def __repr__(self):
 
113
        return '%s(%r/%r, msg=%r)' % (
 
114
            self.__class__.__name__,
 
115
            self.current_cnt,
 
116
            self.total_cnt,
 
117
            self.msg)
 
118
 
 
119
    def update(self, msg, current_cnt=None, total_cnt=None):
 
120
        self.msg = msg
 
121
        self.current_cnt = current_cnt
 
122
        if total_cnt:
 
123
            self.total_cnt = total_cnt
 
124
        if self.progress_view:
 
125
            self.progress_view.show_progress(self)
 
126
        else:
 
127
            self.ui_factory._progress_updated(self)
 
128
 
 
129
    def tick(self):
 
130
        self.update(self.msg)
 
131
 
 
132
    def finished(self):
 
133
        if self.progress_view:
 
134
            self.progress_view.task_finished(self)
 
135
        else:
 
136
            self.ui_factory._progress_finished(self)
 
137
 
 
138
    def make_sub_task(self):
 
139
        return ProgressTask(self, ui_factory=self.ui_factory,
 
140
            progress_view=self.progress_view)
 
141
 
 
142
    def _overall_completion_fraction(self, child_fraction=0.0):
 
143
        """Return fractional completion of this task and its parents
 
144
 
 
145
        Returns None if no completion can be computed."""
 
146
        if self.current_cnt is not None and self.total_cnt:
 
147
            own_fraction = (float(self.current_cnt) + child_fraction) / self.total_cnt
 
148
        else:
 
149
            # if this task has no estimation, it just passes on directly
 
150
            # whatever the child has measured...
 
151
            own_fraction = child_fraction
 
152
        if self._parent_task is None:
 
153
            return own_fraction
 
154
        else:
 
155
            if own_fraction is None:
 
156
                own_fraction = 0.0
 
157
            return self._parent_task._overall_completion_fraction(own_fraction)
 
158
 
 
159
    def note(self, fmt_string, *args):
 
160
        """Record a note without disrupting the progress bar."""
 
161
        # XXX: shouldn't be here; put it in mutter or the ui instead
 
162
        if args:
 
163
            self.ui_factory.note(fmt_string % args)
 
164
        else:
 
165
            self.ui_factory.note(fmt_string)
 
166
 
 
167
    def clear(self):
 
168
        # XXX: shouldn't be here; put it in mutter or the ui instead
 
169
        if self.progress_view:
 
170
            self.progress_view.clear()
 
171
        else:
 
172
            self.ui_factory.clear_term()
 
173
 
 
174
 
 
175
@deprecated_function(deprecated_in((1, 16, 0)))
72
176
def ProgressBar(to_file=None, **kwargs):
73
 
    """Abstract factory"""
 
177
    """Construct a progress bar.
 
178
 
 
179
    Deprecated; ask the ui_factory for a progress task instead.
 
180
    """
74
181
    if to_file is None:
75
182
        to_file = sys.stderr
76
183
    requested_bar_type = os.environ.get('BZR_PROGRESS_BAR')
91
198
                                                _progress_bar_types.keys())
92
199
        return _progress_bar_types[requested_bar_type](to_file=to_file, **kwargs)
93
200
 
94
 
 
95
 
class ProgressBarStack(object):
96
 
    """A stack of progress bars."""
97
 
 
98
 
    def __init__(self,
99
 
                 to_file=None,
100
 
                 show_pct=False,
101
 
                 show_spinner=True,
102
 
                 show_eta=False,
103
 
                 show_bar=True,
104
 
                 show_count=True,
105
 
                 to_messages_file=None,
106
 
                 klass=None):
107
 
        """Setup the stack with the parameters the progress bars should have."""
108
 
        if to_file is None:
109
 
            to_file = sys.stderr
110
 
        if to_messages_file is None:
111
 
            to_messages_file = sys.stdout
112
 
        self._to_file = to_file
113
 
        self._show_pct = show_pct
114
 
        self._show_spinner = show_spinner
115
 
        self._show_eta = show_eta
116
 
        self._show_bar = show_bar
117
 
        self._show_count = show_count
118
 
        self._to_messages_file = to_messages_file
119
 
        self._stack = []
120
 
        self._klass = klass or ProgressBar
121
 
 
122
 
    def top(self):
123
 
        if len(self._stack) != 0:
124
 
            return self._stack[-1]
125
 
        else:
126
 
            return None
127
 
 
128
 
    def bottom(self):
129
 
        if len(self._stack) != 0:
130
 
            return self._stack[0]
131
 
        else:
132
 
            return None
133
 
 
134
 
    def get_nested(self):
135
 
        """Return a nested progress bar."""
136
 
        if len(self._stack) == 0:
137
 
            func = self._klass
138
 
        else:
139
 
            func = self.top().child_progress
140
 
        new_bar = func(to_file=self._to_file,
141
 
                       show_pct=self._show_pct,
142
 
                       show_spinner=self._show_spinner,
143
 
                       show_eta=self._show_eta,
144
 
                       show_bar=self._show_bar,
145
 
                       show_count=self._show_count,
146
 
                       to_messages_file=self._to_messages_file,
147
 
                       _stack=self)
148
 
        self._stack.append(new_bar)
149
 
        return new_bar
150
 
 
151
 
    def return_pb(self, bar):
152
 
        """Return bar after its been used."""
153
 
        if bar is not self._stack[-1]:
154
 
            raise errors.MissingProgressBarFinish()
155
 
        self._stack.pop()
156
 
 
157
 
 
 
201
 
 
202
# NOTE: This is also deprecated; you should provide a ProgressView instead.
158
203
class _BaseProgressBar(object):
159
204
 
160
205
    def __init__(self,
193
238
    def finished(self):
194
239
        """Return this bar to its progress stack."""
195
240
        self.clear()
196
 
        assert self._stack is not None
197
241
        self._stack.return_pb(self)
198
242
 
199
243
    def note(self, fmt_string, *args, **kwargs):
202
246
        self.to_messages_file.write(fmt_string % args)
203
247
        self.to_messages_file.write('\n')
204
248
 
 
249
    @deprecated_function(deprecated_in((1, 16, 0)))
205
250
    def child_progress(self, **kwargs):
206
251
        return ChildProgress(**kwargs)
207
252
 
211
256
 
212
257
    This can be used as the default argument for methods that
213
258
    take an optional progress indicator."""
 
259
 
214
260
    def tick(self):
215
261
        pass
216
262
 
222
268
 
223
269
    def clear(self):
224
270
        pass
225
 
        
 
271
 
226
272
    def note(self, fmt_string, *args, **kwargs):
227
273
        """See _BaseProgressBar.note()."""
228
274
 
230
276
        return DummyProgress(**kwargs)
231
277
 
232
278
 
233
 
_progress_bar_types['dummy'] = DummyProgress
234
 
_progress_bar_types['none'] = DummyProgress
235
 
 
236
 
 
237
279
class DotsProgressBar(_BaseProgressBar):
238
280
 
 
281
    @deprecated_function(deprecated_in((1, 16, 0)))
239
282
    def __init__(self, **kwargs):
240
283
        _BaseProgressBar.__init__(self, **kwargs)
241
284
        self.last_msg = None
242
285
        self.need_nl = False
243
 
        
 
286
 
244
287
    def tick(self):
245
288
        self.update()
246
 
        
 
289
 
247
290
    def update(self, msg=None, current_cnt=None, total_cnt=None):
248
291
        if msg and msg != self.last_msg:
249
292
            if self.need_nl:
252
295
            self.last_msg = msg
253
296
        self.need_nl = True
254
297
        self.to_file.write('.')
255
 
        
 
298
 
256
299
    def clear(self):
257
300
        if self.need_nl:
258
301
            self.to_file.write('\n')
259
302
        self.need_nl = False
260
 
        
 
303
 
261
304
    def child_update(self, message, current, total):
262
305
        self.tick()
263
306
 
264
307
 
265
 
_progress_bar_types['dots'] = DotsProgressBar
266
 
 
267
 
    
268
308
class TTYProgressBar(_BaseProgressBar):
269
309
    """Progress bar display object.
270
310
 
287
327
    """
288
328
    SPIN_CHARS = r'/-\|'
289
329
 
290
 
 
 
330
    @deprecated_function(deprecated_in((1, 16, 0)))
291
331
    def __init__(self, **kwargs):
292
332
        from bzrlib.osutils import terminal_width
293
333
        _BaseProgressBar.__init__(self, **kwargs)
297
337
        self._max_last_updates = 10
298
338
        self.child_fraction = 0
299
339
        self._have_output = False
300
 
    
301
340
 
302
341
    def throttle(self, old_msg):
303
342
        """Return True if the bar was updated too recently"""
318
357
        self.last_updates = self.last_updates[-self._max_last_updates:]
319
358
        self.last_update = now
320
359
        return False
321
 
        
 
360
 
322
361
    def tick(self):
323
 
        self.update(self.last_msg, self.last_cnt, self.last_total, 
 
362
        self.update(self.last_msg, self.last_cnt, self.last_total,
324
363
                    self.child_fraction)
325
364
 
326
365
    def child_update(self, message, current, total):
330
369
                pass
331
370
            elif self.last_cnt + child_fraction <= self.last_total:
332
371
                self.child_fraction = child_fraction
333
 
            else:
334
 
                mutter('not updating child fraction')
335
372
        if self.last_msg is None:
336
373
            self.last_msg = ''
337
374
        self.tick()
338
375
 
339
 
    def update(self, msg, current_cnt=None, total_cnt=None, 
340
 
               child_fraction=0):
341
 
        """Update and redraw progress bar."""
 
376
    def update(self, msg, current_cnt=None, total_cnt=None,
 
377
            child_fraction=0):
 
378
        """Update and redraw progress bar.
 
379
        """
342
380
        if msg is None:
343
381
            msg = self.last_msg
344
382
 
347
385
 
348
386
        if current_cnt < 0:
349
387
            current_cnt = 0
350
 
            
 
388
 
351
389
        if current_cnt > total_cnt:
352
390
            total_cnt = current_cnt
353
 
        
354
 
        ## # optional corner case optimisation 
 
391
 
 
392
        ## # optional corner case optimisation
355
393
        ## # currently does not seem to fire so costs more than saved.
356
394
        ## # trivial optimal case:
357
395
        ## # NB if callers are doing a clear and restore with
364
402
        ##     self.child_fraction == child_fraction):
365
403
        ##     return
366
404
 
 
405
        if msg is None:
 
406
            msg = ''
 
407
 
367
408
        old_msg = self.last_msg
368
409
        # save these for the tick() function
369
410
        self.last_msg = msg
371
412
        self.last_total = total_cnt
372
413
        self.child_fraction = child_fraction
373
414
 
374
 
        # each function call takes 20ms/4000 = 0.005 ms, 
 
415
        # each function call takes 20ms/4000 = 0.005 ms,
375
416
        # but multiple that by 4000 calls -> starts to cost.
376
417
        # so anything to make this function call faster
377
418
        # will improve base 'diff' time by up to 0.1 seconds.
379
420
            return
380
421
 
381
422
        if self.show_eta and self.start_time and self.last_total:
382
 
            eta = get_eta(self.start_time, self.last_cnt + self.child_fraction, 
 
423
            eta = get_eta(self.start_time, self.last_cnt + self.child_fraction,
383
424
                    self.last_total, last_updates = self.last_updates)
384
425
            eta_str = " " + str_tdelta(eta)
385
426
        else:
386
427
            eta_str = ""
387
428
 
388
429
        if self.show_spinner:
389
 
            spin_str = self.SPIN_CHARS[self.spin_pos % 4] + ' '            
 
430
            spin_str = self.SPIN_CHARS[self.spin_pos % 4] + ' '
390
431
        else:
391
432
            spin_str = ''
392
433
 
409
450
            # make both fields the same size
410
451
            t = '%i' % (self.last_total)
411
452
            c = '%*i' % (len(t), self.last_cnt)
412
 
            count_str = ' ' + c + '/' + t 
 
453
            count_str = ' ' + c + '/' + t
413
454
 
414
455
        if self.show_bar:
415
456
            # progress bar, if present, soaks up all remaining space
418
459
 
419
460
            if self.last_total:
420
461
                # number of markers highlighted in bar
421
 
                markers = int(round(float(cols) * 
 
462
                markers = int(round(float(cols) *
422
463
                              (self.last_cnt + self.child_fraction) / self.last_total))
423
464
                bar_str = '[' + ('=' * markers).ljust(cols) + '] '
424
465
            elif False:
426
467
                # so just show an expanded spinning thingy
427
468
                m = self.spin_pos % cols
428
469
                ms = (' ' * m + '*').ljust(cols)
429
 
                
 
470
 
430
471
                bar_str = '[' + ms + '] '
431
472
            else:
432
473
                bar_str = ''
433
474
        else:
434
475
            bar_str = ''
435
476
 
436
 
        m = spin_str + bar_str + self.last_msg + count_str + pct_str + eta_str
 
477
        m = spin_str + bar_str + self.last_msg + count_str \
 
478
            + pct_str + eta_str
437
479
        self.to_file.write('\r%-*.*s' % (self.width - 1, self.width - 1, m))
438
480
        self._have_output = True
439
481
        #self.to_file.flush()
440
 
            
441
 
    def clear(self):        
 
482
 
 
483
    def clear(self):
442
484
        if self._have_output:
443
485
            self.to_file.write('\r%s\r' % (' ' * (self.width - 1)))
444
486
        self._have_output = False
445
 
        #self.to_file.flush()        
446
 
 
447
 
 
448
 
_progress_bar_types['tty'] = TTYProgressBar
449
 
 
450
 
 
 
487
        #self.to_file.flush()
 
488
 
 
489
 
 
490
 
 
491
# DEPRECATED
451
492
class ChildProgress(_BaseProgressBar):
452
493
    """A progress indicator that pushes its data to the parent"""
453
494
 
 
495
    @deprecated_function(deprecated_in((1, 16, 0)))
454
496
    def __init__(self, _stack, **kwargs):
455
497
        _BaseProgressBar.__init__(self, _stack=_stack, **kwargs)
456
498
        self.parent = _stack.top()
461
503
 
462
504
    def update(self, msg, current_cnt=None, total_cnt=None):
463
505
        self.current = current_cnt
464
 
        self.total = total_cnt
 
506
        if total_cnt is not None:
 
507
            self.total = total_cnt
465
508
        self.message = msg
466
509
        self.child_fraction = 0
467
510
        self.tick()
490
533
    def note(self, *args, **kwargs):
491
534
        self.parent.note(*args, **kwargs)
492
535
 
493
 
 
 
536
 
494
537
def str_tdelta(delt):
495
538
    if delt is None:
496
539
        return "-:--:--"
517
560
 
518
561
    if elapsed < 2.0:                   # not enough time to estimate
519
562
        return None
520
 
    
 
563
 
521
564
    total_duration = float(elapsed) * float(total) / float(current)
522
565
 
523
 
    assert total_duration >= elapsed
524
 
 
525
566
    if last_updates and len(last_updates) >= n_recent:
526
567
        avg = sum(last_updates) / float(len(last_updates))
527
568
        time_left = avg * (total - current)
548
589
            self.cur_phase = 0
549
590
        else:
550
591
            self.cur_phase += 1
551
 
        assert self.cur_phase < self.total 
552
592
        self.pb.update(self.message, self.cur_phase, self.total)
553
593
 
554
594
 
555
 
def run_tests():
556
 
    import doctest
557
 
    result = doctest.testmod()
558
 
    if result[1] > 0:
559
 
        if result[0] == 0:
560
 
            print "All tests passed"
561
 
    else:
562
 
        print "No tests to run"
563
 
 
564
 
 
565
 
def demo():
566
 
    sleep = time.sleep
567
 
    
568
 
    print 'dumb-terminal test:'
569
 
    pb = DotsProgressBar()
570
 
    for i in range(100):
571
 
        pb.update('Leoparden', i, 99)
572
 
        sleep(0.1)
573
 
    sleep(1.5)
574
 
    pb.clear()
575
 
    sleep(1.5)
576
 
    
577
 
    print 'smart-terminal test:'
578
 
    pb = ProgressBar(show_pct=True, show_bar=True, show_spinner=False)
579
 
    for i in range(100):
580
 
        pb.update('Elephanten', i, 99)
581
 
        sleep(0.1)
582
 
    sleep(2)
583
 
    pb.clear()
584
 
    sleep(1)
585
 
 
586
 
    print 'done!'
587
 
 
588
 
if __name__ == "__main__":
589
 
    demo()
 
595
_progress_bar_types = {}
 
596
_progress_bar_types['dummy'] = DummyProgress
 
597
_progress_bar_types['none'] = DummyProgress
 
598
_progress_bar_types['tty'] = TTYProgressBar
 
599
_progress_bar_types['dots'] = DotsProgressBar