← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/progress.py

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