1
# Copyright (C) 2005, 2006, 2008, 2009 Canonical Ltd
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.
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.
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
18
"""Progress indicators.
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.
33
from bzrlib.trace import mutter
34
from bzrlib.symbol_versioning import (
40
def _supports_progress(f):
41
"""Detect if we can use pretty progress bars on file F.
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.
46
This doesn't check the policy for whether we *should* use them.
48
isatty = getattr(f, 'isatty', None)
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
if os.environ.get('TERM') == 'dumb':
58
# e.g. emacs compile window
63
class ProgressTask(object):
64
"""Model component of a progress indicator.
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.
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.
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
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
83
def __init__(self, parent_task=None, ui_factory=None, progress_view=None):
84
"""Construct a new progress task.
86
:param parent_task: Enclosing ProgressTask or None.
88
:param progress_view: ProgressView to display this ProgressTask.
90
:param ui_factory: The UI factory that will display updates;
91
deprecated in favor of passing progress_view directly.
93
Normally you should not call this directly but rather through
94
`ui_factory.nested_progress_bar`.
96
self._parent_task = parent_task
99
self.current_cnt = None
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
109
self.update_latency = 0.1
110
self.show_transport_activity = True
113
return '%s(%r/%r, msg=%r)' % (
114
self.__class__.__name__,
119
def update(self, msg, current_cnt=None, total_cnt=None):
121
self.current_cnt = current_cnt
123
self.total_cnt = total_cnt
124
if self.progress_view:
125
self.progress_view.show_progress(self)
127
self.ui_factory._progress_updated(self)
130
self.update(self.msg)
133
if self.progress_view:
134
self.progress_view.task_finished(self)
136
self.ui_factory._progress_finished(self)
138
def make_sub_task(self):
139
return ProgressTask(self, ui_factory=self.ui_factory,
140
progress_view=self.progress_view)
142
def _overall_completion_fraction(self, child_fraction=0.0):
143
"""Return fractional completion of this task and its parents
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
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:
155
if own_fraction is None:
157
return self._parent_task._overall_completion_fraction(own_fraction)
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
163
self.ui_factory.note(fmt_string % args)
165
self.ui_factory.note(fmt_string)
168
# XXX: shouldn't be here; put it in mutter or the ui instead
169
if self.progress_view:
170
self.progress_view.clear()
172
self.ui_factory.clear_term()
175
@deprecated_function(deprecated_in((1, 16, 0)))
176
def ProgressBar(to_file=None, **kwargs):
177
"""Abstract factory"""
180
requested_bar_type = os.environ.get('BZR_PROGRESS_BAR')
181
# An value of '' or not set reverts to standard processing
182
if requested_bar_type in (None, ''):
183
if _supports_progress(to_file):
184
return TTYProgressBar(to_file=to_file, **kwargs)
186
return DummyProgress(to_file=to_file, **kwargs)
188
# Minor sanitation to prevent spurious errors
189
requested_bar_type = requested_bar_type.lower().strip()
190
# TODO: jam 20060710 Arguably we shouldn't raise an exception
191
# but should instead just disable progress bars if we
192
# don't recognize the type
193
if requested_bar_type not in _progress_bar_types:
194
raise errors.InvalidProgressBarType(requested_bar_type,
195
_progress_bar_types.keys())
196
return _progress_bar_types[requested_bar_type](to_file=to_file, **kwargs)
199
# NOTE: This is also deprecated; you should provide a ProgressView instead.
200
class _BaseProgressBar(object):
209
to_messages_file=None,
211
object.__init__(self)
214
if to_messages_file is None:
215
to_messages_file = sys.stdout
216
self.to_file = to_file
217
self.to_messages_file = to_messages_file
220
self.last_total = None
221
self.show_pct = show_pct
222
self.show_spinner = show_spinner
223
self.show_eta = show_eta
224
self.show_bar = show_bar
225
self.show_count = show_count
228
self.MIN_PAUSE = 0.1 # seconds
231
self.start_time = now
232
# next update should not throttle
233
self.last_update = now - self.MIN_PAUSE - 1
236
"""Return this bar to its progress stack."""
238
self._stack.return_pb(self)
240
def note(self, fmt_string, *args, **kwargs):
241
"""Record a note without disrupting the progress bar."""
243
self.to_messages_file.write(fmt_string % args)
244
self.to_messages_file.write('\n')
246
@deprecated_function(deprecated_in((1, 16, 0)))
247
def child_progress(self, **kwargs):
248
return ChildProgress(**kwargs)
251
class DummyProgress(_BaseProgressBar):
252
"""Progress-bar standin that does nothing.
254
This can be used as the default argument for methods that
255
take an optional progress indicator."""
260
def update(self, msg=None, current=None, total=None):
263
def child_update(self, message, current, total):
269
def note(self, fmt_string, *args, **kwargs):
270
"""See _BaseProgressBar.note()."""
272
def child_progress(self, **kwargs):
273
return DummyProgress(**kwargs)
276
class DotsProgressBar(_BaseProgressBar):
278
@deprecated_function(deprecated_in((1, 16, 0)))
279
def __init__(self, **kwargs):
280
_BaseProgressBar.__init__(self, **kwargs)
287
def update(self, msg=None, current_cnt=None, total_cnt=None):
288
if msg and msg != self.last_msg:
290
self.to_file.write('\n')
291
self.to_file.write(msg + ': ')
294
self.to_file.write('.')
298
self.to_file.write('\n')
301
def child_update(self, message, current, total):
305
class TTYProgressBar(_BaseProgressBar):
306
"""Progress bar display object.
308
Several options are available to control the display. These can
309
be passed as parameters to the constructor or assigned at any time:
312
Show percentage complete.
314
Show rotating baton. This ticks over on every update even
315
if the values don't change.
317
Show predicted time-to-completion.
321
Show numerical counts.
323
The output file should be in line-buffered or unbuffered mode.
327
@deprecated_function(deprecated_in((1, 16, 0)))
328
def __init__(self, **kwargs):
329
from bzrlib.osutils import terminal_width
330
_BaseProgressBar.__init__(self, **kwargs)
332
self.width = terminal_width()
333
self.last_updates = []
334
self._max_last_updates = 10
335
self.child_fraction = 0
336
self._have_output = False
338
def throttle(self, old_msg):
339
"""Return True if the bar was updated too recently"""
340
# time.time consistently takes 40/4000 ms = 0.01 ms.
341
# time.clock() is faster, but gives us CPU time, not wall-clock time
343
if self.start_time is not None and (now - self.start_time) < 1:
345
if old_msg != self.last_msg:
347
interval = now - self.last_update
349
if interval < self.MIN_PAUSE:
352
self.last_updates.append(now - self.last_update)
353
# Don't let the queue grow without bound
354
self.last_updates = self.last_updates[-self._max_last_updates:]
355
self.last_update = now
359
self.update(self.last_msg, self.last_cnt, self.last_total,
362
def child_update(self, message, current, total):
363
if current is not None and total != 0:
364
child_fraction = float(current) / total
365
if self.last_cnt is None:
367
elif self.last_cnt + child_fraction <= self.last_total:
368
self.child_fraction = child_fraction
369
if self.last_msg is None:
373
def update(self, msg, current_cnt=None, total_cnt=None,
375
"""Update and redraw progress bar.
380
if total_cnt is None:
381
total_cnt = self.last_total
386
if current_cnt > total_cnt:
387
total_cnt = current_cnt
389
## # optional corner case optimisation
390
## # currently does not seem to fire so costs more than saved.
391
## # trivial optimal case:
392
## # NB if callers are doing a clear and restore with
393
## # the saved values, this will prevent that:
394
## # in that case add a restore method that calls
395
## # _do_update or some such
396
## if (self.last_msg == msg and
397
## self.last_cnt == current_cnt and
398
## self.last_total == total_cnt and
399
## self.child_fraction == child_fraction):
405
old_msg = self.last_msg
406
# save these for the tick() function
408
self.last_cnt = current_cnt
409
self.last_total = total_cnt
410
self.child_fraction = child_fraction
412
# each function call takes 20ms/4000 = 0.005 ms,
413
# but multiple that by 4000 calls -> starts to cost.
414
# so anything to make this function call faster
415
# will improve base 'diff' time by up to 0.1 seconds.
416
if self.throttle(old_msg):
419
if self.show_eta and self.start_time and self.last_total:
420
eta = get_eta(self.start_time, self.last_cnt + self.child_fraction,
421
self.last_total, last_updates = self.last_updates)
422
eta_str = " " + str_tdelta(eta)
426
if self.show_spinner:
427
spin_str = self.SPIN_CHARS[self.spin_pos % 4] + ' '
431
# always update this; it's also used for the bar
434
if self.show_pct and self.last_total and self.last_cnt:
435
pct = 100.0 * ((self.last_cnt + self.child_fraction) / self.last_total)
436
pct_str = ' (%5.1f%%)' % pct
440
if not self.show_count:
442
elif self.last_cnt is None:
444
elif self.last_total is None:
445
count_str = ' %i' % (self.last_cnt)
447
# make both fields the same size
448
t = '%i' % (self.last_total)
449
c = '%*i' % (len(t), self.last_cnt)
450
count_str = ' ' + c + '/' + t
453
# progress bar, if present, soaks up all remaining space
454
cols = self.width - 1 - len(self.last_msg) - len(spin_str) - len(pct_str) \
455
- len(eta_str) - len(count_str) - 3
458
# number of markers highlighted in bar
459
markers = int(round(float(cols) *
460
(self.last_cnt + self.child_fraction) / self.last_total))
461
bar_str = '[' + ('=' * markers).ljust(cols) + '] '
463
# don't know total, so can't show completion.
464
# so just show an expanded spinning thingy
465
m = self.spin_pos % cols
466
ms = (' ' * m + '*').ljust(cols)
468
bar_str = '[' + ms + '] '
474
m = spin_str + bar_str + self.last_msg + count_str \
476
self.to_file.write('\r%-*.*s' % (self.width - 1, self.width - 1, m))
477
self._have_output = True
478
#self.to_file.flush()
481
if self._have_output:
482
self.to_file.write('\r%s\r' % (' ' * (self.width - 1)))
483
self._have_output = False
484
#self.to_file.flush()
489
class ChildProgress(_BaseProgressBar):
490
"""A progress indicator that pushes its data to the parent"""
492
@deprecated_function(deprecated_in((1, 16, 0)))
493
def __init__(self, _stack, **kwargs):
494
_BaseProgressBar.__init__(self, _stack=_stack, **kwargs)
495
self.parent = _stack.top()
498
self.child_fraction = 0
501
def update(self, msg, current_cnt=None, total_cnt=None):
502
self.current = current_cnt
503
if total_cnt is not None:
504
self.total = total_cnt
506
self.child_fraction = 0
509
def child_update(self, message, current, total):
510
if current is None or total == 0:
511
self.child_fraction = 0
513
self.child_fraction = float(current) / total
517
if self.current is None:
520
count = self.current+self.child_fraction
521
if count > self.total:
523
mutter('clamping count of %d to %d' % (count, self.total))
525
self.parent.child_update(self.message, count, self.total)
530
def note(self, *args, **kwargs):
531
self.parent.note(*args, **kwargs)
534
def str_tdelta(delt):
537
delt = int(round(delt))
538
return '%d:%02d:%02d' % (delt/3600,
543
def get_eta(start_time, current, total, enough_samples=3, last_updates=None, n_recent=10):
544
if start_time is None:
550
if current < enough_samples:
556
elapsed = time.time() - start_time
558
if elapsed < 2.0: # not enough time to estimate
561
total_duration = float(elapsed) * float(total) / float(current)
563
if last_updates and len(last_updates) >= n_recent:
564
avg = sum(last_updates) / float(len(last_updates))
565
time_left = avg * (total - current)
567
old_time_left = total_duration - elapsed
569
# We could return the average, or some other value here
570
return (time_left + old_time_left) / 2
572
return total_duration - elapsed
575
class ProgressPhase(object):
576
"""Update progress object with the current phase"""
577
def __init__(self, message, total, pb):
578
object.__init__(self)
580
self.message = message
582
self.cur_phase = None
584
def next_phase(self):
585
if self.cur_phase is None:
589
self.pb.update(self.message, self.cur_phase, self.total)
592
_progress_bar_types = {}
593
_progress_bar_types['dummy'] = DummyProgress
594
_progress_bar_types['none'] = DummyProgress
595
_progress_bar_types['tty'] = TTYProgressBar
596
_progress_bar_types['dots'] = DotsProgressBar
added
removed
bzrlib/progress.py
