← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/progress.py

  • Committer: Aaron Bentley
  • Date: 2007-01-16 13:12:54 UTC
  • mto: (2230.3.47 branch6)
  • mto: This revision was merged to the branch mainline in revision 2290.
  • Revision ID: aaron.bentley@utoronto.ca-20070116131254-sjruli93timappd4
work in progress bind stuff

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/progress.py
1
 
# Copyright (C) 2005, 2006, 2008, 2009 Canonical Ltd
 
1
# Copyright (C) 2005 Aaron Bentley <aaron.bentley@utoronto.ca>
 
2
# Copyright (C) 2005, 2006 Canonical Ltd
2
3
#
3
4
# This program is free software; you can redistribute it and/or modify
4
5
# it under the terms of the GNU General Public License as published by
12
13
#
13
14
# You should have received a copy of the GNU General Public License
14
15
# 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.
 
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.
22
27
"""
23
28
 
 
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
24
37
 
25
38
import sys
26
39
import time
27
40
import os
28
41
 
29
 
 
 
42
from bzrlib.lazy_import import lazy_import
 
43
lazy_import(globals(), """
30
44
from bzrlib import (
31
45
    errors,
32
46
    )
 
47
""")
 
48
 
33
49
from bzrlib.trace import mutter
34
 
from bzrlib.symbol_versioning import (
35
 
    deprecated_function,
36
 
    deprecated_in,
37
 
    )
38
50
 
39
51
 
40
52
def _supports_progress(f):
41
 
    """Detect if we can use pretty progress bars on file F.
42
 
 
43
 
    If this returns true we expect that a human may be looking at that
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.
47
 
    """
48
53
    isatty = getattr(f, 'isatty', None)
49
54
    if isatty is None:
50
55
        return False
51
56
    if not isatty():
52
57
        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.
57
58
    if os.environ.get('TERM') == 'dumb':
58
59
        # e.g. emacs compile window
59
60
        return False
60
61
    return True
61
62
 
62
63
 
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)))
 
64
_progress_bar_types = {}
 
65
 
 
66
 
176
67
def ProgressBar(to_file=None, **kwargs):
177
 
    """Construct a progress bar.
178
 
 
179
 
    Deprecated; ask the ui_factory for a progress task instead.
180
 
    """
 
68
    """Abstract factory"""
181
69
    if to_file is None:
182
70
        to_file = sys.stderr
183
71
    requested_bar_type = os.environ.get('BZR_PROGRESS_BAR')
186
74
        if _supports_progress(to_file):
187
75
            return TTYProgressBar(to_file=to_file, **kwargs)
188
76
        else:
189
 
            return DummyProgress(to_file=to_file, **kwargs)
 
77
            return DotsProgressBar(to_file=to_file, **kwargs)
190
78
    else:
191
79
        # Minor sanitation to prevent spurious errors
192
80
        requested_bar_type = requested_bar_type.lower().strip()
198
86
                                                _progress_bar_types.keys())
199
87
        return _progress_bar_types[requested_bar_type](to_file=to_file, **kwargs)
200
88
 
201
 
 
202
 
# NOTE: This is also deprecated; you should provide a ProgressView instead.
 
89
 
 
90
class ProgressBarStack(object):
 
91
    """A stack of progress bars."""
 
92
 
 
93
    def __init__(self,
 
94
                 to_file=None,
 
95
                 show_pct=False,
 
96
                 show_spinner=True,
 
97
                 show_eta=False,
 
98
                 show_bar=True,
 
99
                 show_count=True,
 
100
                 to_messages_file=None,
 
101
                 klass=None):
 
102
        """Setup the stack with the parameters the progress bars should have."""
 
103
        if to_file is None:
 
104
            to_file = sys.stderr
 
105
        if to_messages_file is None:
 
106
            to_messages_file = sys.stdout
 
107
        self._to_file = to_file
 
108
        self._show_pct = show_pct
 
109
        self._show_spinner = show_spinner
 
110
        self._show_eta = show_eta
 
111
        self._show_bar = show_bar
 
112
        self._show_count = show_count
 
113
        self._to_messages_file = to_messages_file
 
114
        self._stack = []
 
115
        self._klass = klass or ProgressBar
 
116
 
 
117
    def top(self):
 
118
        if len(self._stack) != 0:
 
119
            return self._stack[-1]
 
120
        else:
 
121
            return None
 
122
 
 
123
    def bottom(self):
 
124
        if len(self._stack) != 0:
 
125
            return self._stack[0]
 
126
        else:
 
127
            return None
 
128
 
 
129
    def get_nested(self):
 
130
        """Return a nested progress bar."""
 
131
        if len(self._stack) == 0:
 
132
            func = self._klass
 
133
        else:
 
134
            func = self.top().child_progress
 
135
        new_bar = func(to_file=self._to_file,
 
136
                       show_pct=self._show_pct,
 
137
                       show_spinner=self._show_spinner,
 
138
                       show_eta=self._show_eta,
 
139
                       show_bar=self._show_bar,
 
140
                       show_count=self._show_count,
 
141
                       to_messages_file=self._to_messages_file,
 
142
                       _stack=self)
 
143
        self._stack.append(new_bar)
 
144
        return new_bar
 
145
 
 
146
    def return_pb(self, bar):
 
147
        """Return bar after its been used."""
 
148
        if bar is not self._stack[-1]:
 
149
            raise errors.MissingProgressBarFinish()
 
150
        self._stack.pop()
 
151
 
 
152
 
203
153
class _BaseProgressBar(object):
204
154
 
205
155
    def __init__(self,
238
188
    def finished(self):
239
189
        """Return this bar to its progress stack."""
240
190
        self.clear()
 
191
        assert self._stack is not None
241
192
        self._stack.return_pb(self)
242
193
 
243
194
    def note(self, fmt_string, *args, **kwargs):
246
197
        self.to_messages_file.write(fmt_string % args)
247
198
        self.to_messages_file.write('\n')
248
199
 
249
 
    @deprecated_function(deprecated_in((1, 16, 0)))
250
200
    def child_progress(self, **kwargs):
251
201
        return ChildProgress(**kwargs)
252
202
 
256
206
 
257
207
    This can be used as the default argument for methods that
258
208
    take an optional progress indicator."""
259
 
 
260
209
    def tick(self):
261
210
        pass
262
211
 
268
217
 
269
218
    def clear(self):
270
219
        pass
271
 
 
 
220
        
272
221
    def note(self, fmt_string, *args, **kwargs):
273
222
        """See _BaseProgressBar.note()."""
274
223
 
276
225
        return DummyProgress(**kwargs)
277
226
 
278
227
 
 
228
_progress_bar_types['dummy'] = DummyProgress
 
229
_progress_bar_types['none'] = DummyProgress
 
230
 
 
231
 
279
232
class DotsProgressBar(_BaseProgressBar):
280
233
 
281
 
    @deprecated_function(deprecated_in((1, 16, 0)))
282
234
    def __init__(self, **kwargs):
283
235
        _BaseProgressBar.__init__(self, **kwargs)
284
236
        self.last_msg = None
285
237
        self.need_nl = False
286
 
 
 
238
        
287
239
    def tick(self):
288
240
        self.update()
289
 
 
 
241
        
290
242
    def update(self, msg=None, current_cnt=None, total_cnt=None):
291
243
        if msg and msg != self.last_msg:
292
244
            if self.need_nl:
295
247
            self.last_msg = msg
296
248
        self.need_nl = True
297
249
        self.to_file.write('.')
298
 
 
 
250
        
299
251
    def clear(self):
300
252
        if self.need_nl:
301
253
            self.to_file.write('\n')
302
254
        self.need_nl = False
303
 
 
 
255
        
304
256
    def child_update(self, message, current, total):
305
257
        self.tick()
306
258
 
307
259
 
 
260
_progress_bar_types['dots'] = DotsProgressBar
 
261
 
 
262
    
308
263
class TTYProgressBar(_BaseProgressBar):
309
264
    """Progress bar display object.
310
265
 
327
282
    """
328
283
    SPIN_CHARS = r'/-\|'
329
284
 
330
 
    @deprecated_function(deprecated_in((1, 16, 0)))
 
285
 
331
286
    def __init__(self, **kwargs):
332
287
        from bzrlib.osutils import terminal_width
333
288
        _BaseProgressBar.__init__(self, **kwargs)
337
292
        self._max_last_updates = 10
338
293
        self.child_fraction = 0
339
294
        self._have_output = False
 
295
    
340
296
 
341
297
    def throttle(self, old_msg):
342
298
        """Return True if the bar was updated too recently"""
357
313
        self.last_updates = self.last_updates[-self._max_last_updates:]
358
314
        self.last_update = now
359
315
        return False
360
 
 
 
316
        
361
317
    def tick(self):
362
 
        self.update(self.last_msg, self.last_cnt, self.last_total,
 
318
        self.update(self.last_msg, self.last_cnt, self.last_total, 
363
319
                    self.child_fraction)
364
320
 
365
321
    def child_update(self, message, current, total):
369
325
                pass
370
326
            elif self.last_cnt + child_fraction <= self.last_total:
371
327
                self.child_fraction = child_fraction
 
328
            else:
 
329
                mutter('not updating child fraction')
372
330
        if self.last_msg is None:
373
331
            self.last_msg = ''
374
332
        self.tick()
375
333
 
376
 
    def update(self, msg, current_cnt=None, total_cnt=None,
377
 
            child_fraction=0):
378
 
        """Update and redraw progress bar.
379
 
        """
 
334
    def update(self, msg, current_cnt=None, total_cnt=None, 
 
335
               child_fraction=0):
 
336
        """Update and redraw progress bar."""
380
337
        if msg is None:
381
338
            msg = self.last_msg
382
339
 
385
342
 
386
343
        if current_cnt < 0:
387
344
            current_cnt = 0
388
 
 
 
345
            
389
346
        if current_cnt > total_cnt:
390
347
            total_cnt = current_cnt
391
 
 
392
 
        ## # optional corner case optimisation
 
348
        
 
349
        ## # optional corner case optimisation 
393
350
        ## # currently does not seem to fire so costs more than saved.
394
351
        ## # trivial optimal case:
395
352
        ## # NB if callers are doing a clear and restore with
402
359
        ##     self.child_fraction == child_fraction):
403
360
        ##     return
404
361
 
405
 
        if msg is None:
406
 
            msg = ''
407
 
 
408
362
        old_msg = self.last_msg
409
363
        # save these for the tick() function
410
364
        self.last_msg = msg
412
366
        self.last_total = total_cnt
413
367
        self.child_fraction = child_fraction
414
368
 
415
 
        # each function call takes 20ms/4000 = 0.005 ms,
 
369
        # each function call takes 20ms/4000 = 0.005 ms, 
416
370
        # but multiple that by 4000 calls -> starts to cost.
417
371
        # so anything to make this function call faster
418
372
        # will improve base 'diff' time by up to 0.1 seconds.
420
374
            return
421
375
 
422
376
        if self.show_eta and self.start_time and self.last_total:
423
 
            eta = get_eta(self.start_time, self.last_cnt + self.child_fraction,
 
377
            eta = get_eta(self.start_time, self.last_cnt + self.child_fraction, 
424
378
                    self.last_total, last_updates = self.last_updates)
425
379
            eta_str = " " + str_tdelta(eta)
426
380
        else:
427
381
            eta_str = ""
428
382
 
429
383
        if self.show_spinner:
430
 
            spin_str = self.SPIN_CHARS[self.spin_pos % 4] + ' '
 
384
            spin_str = self.SPIN_CHARS[self.spin_pos % 4] + ' '            
431
385
        else:
432
386
            spin_str = ''
433
387
 
450
404
            # make both fields the same size
451
405
            t = '%i' % (self.last_total)
452
406
            c = '%*i' % (len(t), self.last_cnt)
453
 
            count_str = ' ' + c + '/' + t
 
407
            count_str = ' ' + c + '/' + t 
454
408
 
455
409
        if self.show_bar:
456
410
            # progress bar, if present, soaks up all remaining space
459
413
 
460
414
            if self.last_total:
461
415
                # number of markers highlighted in bar
462
 
                markers = int(round(float(cols) *
 
416
                markers = int(round(float(cols) * 
463
417
                              (self.last_cnt + self.child_fraction) / self.last_total))
464
418
                bar_str = '[' + ('=' * markers).ljust(cols) + '] '
465
419
            elif False:
467
421
                # so just show an expanded spinning thingy
468
422
                m = self.spin_pos % cols
469
423
                ms = (' ' * m + '*').ljust(cols)
470
 
 
 
424
                
471
425
                bar_str = '[' + ms + '] '
472
426
            else:
473
427
                bar_str = ''
474
428
        else:
475
429
            bar_str = ''
476
430
 
477
 
        m = spin_str + bar_str + self.last_msg + count_str \
478
 
            + pct_str + eta_str
 
431
        m = spin_str + bar_str + self.last_msg + count_str + pct_str + eta_str
479
432
        self.to_file.write('\r%-*.*s' % (self.width - 1, self.width - 1, m))
480
433
        self._have_output = True
481
434
        #self.to_file.flush()
482
 
 
483
 
    def clear(self):
 
435
            
 
436
    def clear(self):        
484
437
        if self._have_output:
485
438
            self.to_file.write('\r%s\r' % (' ' * (self.width - 1)))
486
439
        self._have_output = False
487
 
        #self.to_file.flush()
488
 
 
489
 
 
490
 
 
491
 
# DEPRECATED
 
440
        #self.to_file.flush()        
 
441
 
 
442
 
 
443
_progress_bar_types['tty'] = TTYProgressBar
 
444
 
 
445
 
492
446
class ChildProgress(_BaseProgressBar):
493
447
    """A progress indicator that pushes its data to the parent"""
494
448
 
495
 
    @deprecated_function(deprecated_in((1, 16, 0)))
496
449
    def __init__(self, _stack, **kwargs):
497
450
        _BaseProgressBar.__init__(self, _stack=_stack, **kwargs)
498
451
        self.parent = _stack.top()
503
456
 
504
457
    def update(self, msg, current_cnt=None, total_cnt=None):
505
458
        self.current = current_cnt
506
 
        if total_cnt is not None:
507
 
            self.total = total_cnt
 
459
        self.total = total_cnt
508
460
        self.message = msg
509
461
        self.child_fraction = 0
510
462
        self.tick()
533
485
    def note(self, *args, **kwargs):
534
486
        self.parent.note(*args, **kwargs)
535
487
 
536
 
 
 
488
 
537
489
def str_tdelta(delt):
538
490
    if delt is None:
539
491
        return "-:--:--"
560
512
 
561
513
    if elapsed < 2.0:                   # not enough time to estimate
562
514
        return None
563
 
 
 
515
    
564
516
    total_duration = float(elapsed) * float(total) / float(current)
565
517
 
 
518
    assert total_duration >= elapsed
 
519
 
566
520
    if last_updates and len(last_updates) >= n_recent:
567
521
        avg = sum(last_updates) / float(len(last_updates))
568
522
        time_left = avg * (total - current)
589
543
            self.cur_phase = 0
590
544
        else:
591
545
            self.cur_phase += 1
 
546
        assert self.cur_phase < self.total 
592
547
        self.pb.update(self.message, self.cur_phase, self.total)
593
548
 
594
549
 
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
 
550
def run_tests():
 
551
    import doctest
 
552
    result = doctest.testmod()
 
553
    if result[1] > 0:
 
554
        if result[0] == 0:
 
555
            print "All tests passed"
 
556
    else:
 
557
        print "No tests to run"
 
558
 
 
559
 
 
560
def demo():
 
561
    sleep = time.sleep
 
562
    
 
563
    print 'dumb-terminal test:'
 
564
    pb = DotsProgressBar()
 
565
    for i in range(100):
 
566
        pb.update('Leoparden', i, 99)
 
567
        sleep(0.1)
 
568
    sleep(1.5)
 
569
    pb.clear()
 
570
    sleep(1.5)
 
571
    
 
572
    print 'smart-terminal test:'
 
573
    pb = ProgressBar(show_pct=True, show_bar=True, show_spinner=False)
 
574
    for i in range(100):
 
575
        pb.update('Elephanten', i, 99)
 
576
        sleep(0.1)
 
577
    sleep(2)
 
578
    pb.clear()
 
579
    sleep(1)
 
580
 
 
581
    print 'done!'
 
582
 
 
583
if __name__ == "__main__":
 
584
    demo()