← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/progress.py

  • Committer: John Arbash Meinel
  • Date: 2005-11-18 16:50:56 UTC
  • mto: (1185.82.108 w-changeset)
  • mto: This revision was merged to the branch mainline in revision 1738.
  • Revision ID: john@arbash-meinel.com-20051118165056-97f164d958a1886b
Moved testdata code to subdirectory

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/progress.py
1
 
# Copyright (C) 2005-2010 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
 
"""Progress indicators.
18
 
 
19
 
The usual way to use this is via bzrlib.ui.ui_factory.nested_progress_bar which
20
 
will manage a conceptual stack of nested activities.
 
1
# Copyright (C) 2005 Aaron Bentley <aaron.bentley@utoronto.ca>
 
2
# Copyright (C) 2005 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.
21
27
"""
22
28
 
23
 
from __future__ import absolute_import
24
 
 
 
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
 
 
39
import sys
25
40
import time
26
41
import os
 
42
from collections import deque
 
43
 
 
44
 
 
45
def _width():
 
46
    """Return estimated terminal width.
 
47
 
 
48
    TODO: Do something smart on Windows?
 
49
 
 
50
    TODO: Is there anything that gets a better update when the window
 
51
          is resized while the program is running?
 
52
    """
 
53
    try:
 
54
        return int(os.environ['COLUMNS'])
 
55
    except (IndexError, KeyError, ValueError):
 
56
        return 80
27
57
 
28
58
 
29
59
def _supports_progress(f):
30
 
    """Detect if we can use pretty progress bars on file F.
31
 
 
32
 
    If this returns true we expect that a human may be looking at that
33
 
    output, and that we can repaint a line to update it.
34
 
 
35
 
    This doesn't check the policy for whether we *should* use them.
36
 
    """
37
 
    isatty = getattr(f, 'isatty', None)
38
 
    if isatty is None:
39
 
        return False
40
 
    if not isatty():
41
 
        return False
42
 
    # The following case also handles Win32 - on that platform $TERM is
43
 
    # typically never set, so the case None is treated as a smart terminal,
44
 
    # not dumb.  <https://bugs.launchpad.net/bugs/334808>  win32 files do have
45
 
    # isatty methods that return true.
 
60
    if not hasattr(f, 'isatty'):
 
61
        return False
 
62
    if not f.isatty():
 
63
        return False
46
64
    if os.environ.get('TERM') == 'dumb':
47
65
        # e.g. emacs compile window
48
66
        return False
49
67
    return True
50
68
 
51
69
 
52
 
class ProgressTask(object):
53
 
    """Model component of a progress indicator.
54
 
 
55
 
    Most code that needs to indicate progress should update one of these,
56
 
    and it will in turn update the display, if one is present.
57
 
 
58
 
    Code updating the task may also set fields as hints about how to display
59
 
    it: show_pct, show_spinner, show_eta, show_count, show_bar.  UIs
60
 
    will not necessarily respect all these fields.
61
 
 
62
 
    The message given when updating a task must be unicode, not bytes.
63
 
 
64
 
    :ivar update_latency: The interval (in seconds) at which the PB should be
65
 
        updated.  Setting this to zero suggests every update should be shown
66
 
        synchronously.
67
 
 
68
 
    :ivar show_transport_activity: If true (default), transport activity
69
 
        will be shown when this task is drawn.  Disable it if you're sure 
70
 
        that only irrelevant or uninteresting transport activity can occur
71
 
        during this task.
72
 
    """
73
 
 
74
 
    def __init__(self, parent_task=None, ui_factory=None, progress_view=None):
75
 
        """Construct a new progress task.
76
 
 
77
 
        :param parent_task: Enclosing ProgressTask or None.
78
 
 
79
 
        :param progress_view: ProgressView to display this ProgressTask.
80
 
 
81
 
        :param ui_factory: The UI factory that will display updates; 
82
 
            deprecated in favor of passing progress_view directly.
83
 
 
84
 
        Normally you should not call this directly but rather through
85
 
        `ui_factory.nested_progress_bar`.
86
 
        """
87
 
        self._parent_task = parent_task
88
 
        self._last_update = 0
89
 
        self.total_cnt = None
90
 
        self.current_cnt = None
91
 
        self.msg = ''
92
 
        # TODO: deprecate passing ui_factory
93
 
        self.ui_factory = ui_factory
94
 
        self.progress_view = progress_view
95
 
        self.show_pct = False
96
 
        self.show_spinner = True
97
 
        self.show_eta = False,
98
 
        self.show_count = True
99
 
        self.show_bar = True
100
 
        self.update_latency = 0.1
101
 
        self.show_transport_activity = True
102
 
 
103
 
    def __repr__(self):
104
 
        return '%s(%r/%r, msg=%r)' % (
105
 
            self.__class__.__name__,
106
 
            self.current_cnt,
107
 
            self.total_cnt,
108
 
            self.msg)
109
 
 
110
 
    def update(self, msg, current_cnt=None, total_cnt=None):
111
 
        """Report updated task message and if relevent progress counters
112
 
 
113
 
        The message given must be unicode, not a byte string.
114
 
        """
115
 
        self.msg = msg
116
 
        self.current_cnt = current_cnt
117
 
        if total_cnt:
118
 
            self.total_cnt = total_cnt
119
 
        if self.progress_view:
120
 
            self.progress_view.show_progress(self)
121
 
        else:
122
 
            self.ui_factory._progress_updated(self)
123
 
 
124
 
    def tick(self):
125
 
        self.update(self.msg)
126
 
 
127
 
    def finished(self):
128
 
        if self.progress_view:
129
 
            self.progress_view.task_finished(self)
130
 
        else:
131
 
            self.ui_factory._progress_finished(self)
132
 
 
133
 
    def make_sub_task(self):
134
 
        return ProgressTask(self, ui_factory=self.ui_factory,
135
 
            progress_view=self.progress_view)
136
 
 
137
 
    def _overall_completion_fraction(self, child_fraction=0.0):
138
 
        """Return fractional completion of this task and its parents
139
 
 
140
 
        Returns None if no completion can be computed."""
141
 
        if self.current_cnt is not None and self.total_cnt:
142
 
            own_fraction = (float(self.current_cnt) + child_fraction) / self.total_cnt
143
 
        else:
144
 
            # if this task has no estimation, it just passes on directly
145
 
            # whatever the child has measured...
146
 
            own_fraction = child_fraction
147
 
        if self._parent_task is None:
148
 
            return own_fraction
149
 
        else:
150
 
            if own_fraction is None:
151
 
                own_fraction = 0.0
152
 
            return self._parent_task._overall_completion_fraction(own_fraction)
153
 
 
154
 
    def clear(self):
155
 
        # TODO: deprecate this method; the model object shouldn't be concerned
156
 
        # with whether it's shown or not.  Most callers use this because they
157
 
        # want to write some different non-progress output to the screen, but
158
 
        # they should probably instead use a stream that's synchronized with
159
 
        # the progress output.  It may be there is a model-level use for
160
 
        # saying "this task's not active at the moment" but I don't see it. --
161
 
        # mbp 20090623
162
 
        if self.progress_view:
163
 
            self.progress_view.clear()
164
 
        else:
165
 
            self.ui_factory.clear_term()
166
 
 
167
 
 
168
 
class DummyProgress(object):
 
70
 
 
71
def ProgressBar(to_file=sys.stderr, **kwargs):
 
72
    """Abstract factory"""
 
73
    if _supports_progress(to_file):
 
74
        return TTYProgressBar(to_file=to_file, **kwargs)
 
75
    else:
 
76
        return DotsProgressBar(to_file=to_file, **kwargs)
 
77
    
 
78
    
 
79
class _BaseProgressBar(object):
 
80
    def __init__(self,
 
81
                 to_file=sys.stderr,
 
82
                 show_pct=False,
 
83
                 show_spinner=False,
 
84
                 show_eta=True,
 
85
                 show_bar=True,
 
86
                 show_count=True):
 
87
        object.__init__(self)
 
88
        self.to_file = to_file
 
89
 
 
90
        self.last_msg = None
 
91
        self.last_cnt = None
 
92
        self.last_total = None
 
93
        self.show_pct = show_pct
 
94
        self.show_spinner = show_spinner
 
95
        self.show_eta = show_eta
 
96
        self.show_bar = show_bar
 
97
        self.show_count = show_count
 
98
 
 
99
 
 
100
 
 
101
class DummyProgress(_BaseProgressBar):
169
102
    """Progress-bar standin that does nothing.
170
103
 
171
 
    This was previously often constructed by application code if no progress
172
 
    bar was explicitly passed in.  That's no longer recommended: instead, just
173
 
    create a progress task from the ui_factory.  This class can be used in
174
 
    test code that needs to fake a progress task for some reason.
175
 
    """
176
 
 
 
104
    This can be used as the default argument for methods that
 
105
    take an optional progress indicator."""
177
106
    def tick(self):
178
107
        pass
179
108
 
180
109
    def update(self, msg=None, current=None, total=None):
181
110
        pass
182
111
 
183
 
    def child_update(self, message, current, total):
184
 
        pass
185
 
 
186
 
    def clear(self):
187
 
        pass
188
 
 
189
 
    def child_progress(self, **kwargs):
190
 
        return DummyProgress(**kwargs)
191
 
 
192
 
 
 
112
    def clear(self):
 
113
        pass
 
114
        
 
115
    
 
116
class DotsProgressBar(_BaseProgressBar):
 
117
    def __init__(self, **kwargs):
 
118
        _BaseProgressBar.__init__(self, **kwargs)
 
119
        self.last_msg = None
 
120
        self.need_nl = False
 
121
        
 
122
    def tick(self):
 
123
        self.update()
 
124
        
 
125
    def update(self, msg=None, current_cnt=None, total_cnt=None):
 
126
        if msg and msg != self.last_msg:
 
127
            if self.need_nl:
 
128
                self.to_file.write('\n')
 
129
            
 
130
            self.to_file.write(msg + ': ')
 
131
            self.last_msg = msg
 
132
        self.need_nl = True
 
133
        self.to_file.write('.')
 
134
        
 
135
    def clear(self):
 
136
        if self.need_nl:
 
137
            self.to_file.write('\n')
 
138
        
 
139
    
 
140
class TTYProgressBar(_BaseProgressBar):
 
141
    """Progress bar display object.
 
142
 
 
143
    Several options are available to control the display.  These can
 
144
    be passed as parameters to the constructor or assigned at any time:
 
145
 
 
146
    show_pct
 
147
        Show percentage complete.
 
148
    show_spinner
 
149
        Show rotating baton.  This ticks over on every update even
 
150
        if the values don't change.
 
151
    show_eta
 
152
        Show predicted time-to-completion.
 
153
    show_bar
 
154
        Show bar graph.
 
155
    show_count
 
156
        Show numerical counts.
 
157
 
 
158
    The output file should be in line-buffered or unbuffered mode.
 
159
    """
 
160
    SPIN_CHARS = r'/-\|'
 
161
    MIN_PAUSE = 0.1 # seconds
 
162
 
 
163
 
 
164
    def __init__(self, **kwargs):
 
165
        _BaseProgressBar.__init__(self, **kwargs)
 
166
        self.spin_pos = 0
 
167
        self.width = _width()
 
168
        self.start_time = None
 
169
        self.last_update = None
 
170
        self.last_updates = deque()
 
171
    
 
172
 
 
173
    def throttle(self):
 
174
        """Return True if the bar was updated too recently"""
 
175
        now = time.time()
 
176
        if self.start_time is None:
 
177
            self.start_time = self.last_update = now
 
178
            return False
 
179
        else:
 
180
            interval = now - self.last_update
 
181
            if interval > 0 and interval < self.MIN_PAUSE:
 
182
                return True
 
183
 
 
184
        self.last_updates.append(now - self.last_update)
 
185
        self.last_update = now
 
186
        return False
 
187
        
 
188
 
 
189
    def tick(self):
 
190
        self.update(self.last_msg, self.last_cnt, self.last_total)
 
191
                 
 
192
 
 
193
 
 
194
    def update(self, msg, current_cnt=None, total_cnt=None):
 
195
        """Update and redraw progress bar."""
 
196
 
 
197
        if current_cnt < 0:
 
198
            current_cnt = 0
 
199
            
 
200
        if current_cnt > total_cnt:
 
201
            total_cnt = current_cnt
 
202
 
 
203
        # save these for the tick() function
 
204
        self.last_msg = msg
 
205
        self.last_cnt = current_cnt
 
206
        self.last_total = total_cnt
 
207
            
 
208
        if self.throttle():
 
209
            return 
 
210
        
 
211
        if self.show_eta and self.start_time and total_cnt:
 
212
            eta = get_eta(self.start_time, current_cnt, total_cnt,
 
213
                    last_updates = self.last_updates)
 
214
            eta_str = " " + str_tdelta(eta)
 
215
        else:
 
216
            eta_str = ""
 
217
 
 
218
        if self.show_spinner:
 
219
            spin_str = self.SPIN_CHARS[self.spin_pos % 4] + ' '            
 
220
        else:
 
221
            spin_str = ''
 
222
 
 
223
        # always update this; it's also used for the bar
 
224
        self.spin_pos += 1
 
225
 
 
226
        if self.show_pct and total_cnt and current_cnt:
 
227
            pct = 100.0 * current_cnt / total_cnt
 
228
            pct_str = ' (%5.1f%%)' % pct
 
229
        else:
 
230
            pct_str = ''
 
231
 
 
232
        if not self.show_count:
 
233
            count_str = ''
 
234
        elif current_cnt is None:
 
235
            count_str = ''
 
236
        elif total_cnt is None:
 
237
            count_str = ' %i' % (current_cnt)
 
238
        else:
 
239
            # make both fields the same size
 
240
            t = '%i' % (total_cnt)
 
241
            c = '%*i' % (len(t), current_cnt)
 
242
            count_str = ' ' + c + '/' + t 
 
243
 
 
244
        if self.show_bar:
 
245
            # progress bar, if present, soaks up all remaining space
 
246
            cols = self.width - 1 - len(msg) - len(spin_str) - len(pct_str) \
 
247
                   - len(eta_str) - len(count_str) - 3
 
248
 
 
249
            if total_cnt:
 
250
                # number of markers highlighted in bar
 
251
                markers = int(round(float(cols) * current_cnt / total_cnt))
 
252
                bar_str = '[' + ('=' * markers).ljust(cols) + '] '
 
253
            elif False:
 
254
                # don't know total, so can't show completion.
 
255
                # so just show an expanded spinning thingy
 
256
                m = self.spin_pos % cols
 
257
                ms = (' ' * m + '*').ljust(cols)
 
258
                
 
259
                bar_str = '[' + ms + '] '
 
260
            else:
 
261
                bar_str = ''
 
262
        else:
 
263
            bar_str = ''
 
264
 
 
265
        m = spin_str + bar_str + msg + count_str + pct_str + eta_str
 
266
 
 
267
        assert len(m) < self.width
 
268
        self.to_file.write('\r' + m.ljust(self.width - 1))
 
269
        #self.to_file.flush()
 
270
            
 
271
 
 
272
    def clear(self):        
 
273
        self.to_file.write('\r%s\r' % (' ' * (self.width - 1)))
 
274
        #self.to_file.flush()        
 
275
    
 
276
 
 
277
        
193
278
def str_tdelta(delt):
194
279
    if delt is None:
195
280
        return "-:--:--"
216
301
 
217
302
    if elapsed < 2.0:                   # not enough time to estimate
218
303
        return None
219
 
 
 
304
    
220
305
    total_duration = float(elapsed) * float(total) / float(current)
221
306
 
 
307
    assert total_duration >= elapsed
 
308
 
222
309
    if last_updates and len(last_updates) >= n_recent:
 
310
        while len(last_updates) > n_recent:
 
311
            last_updates.popleft()
223
312
        avg = sum(last_updates) / float(len(last_updates))
224
313
        time_left = avg * (total - current)
225
314
 
231
320
    return total_duration - elapsed
232
321
 
233
322
 
234
 
class ProgressPhase(object):
235
 
    """Update progress object with the current phase"""
236
 
    def __init__(self, message, total, pb):
237
 
        object.__init__(self)
238
 
        self.pb = pb
239
 
        self.message = message
240
 
        self.total = total
241
 
        self.cur_phase = None
242
 
 
243
 
    def next_phase(self):
244
 
        if self.cur_phase is None:
245
 
            self.cur_phase = 0
246
 
        else:
247
 
            self.cur_phase += 1
248
 
        self.pb.update(self.message, self.cur_phase, self.total)
 
323
def run_tests():
 
324
    import doctest
 
325
    result = doctest.testmod()
 
326
    if result[1] > 0:
 
327
        if result[0] == 0:
 
328
            print "All tests passed"
 
329
    else:
 
330
        print "No tests to run"
 
331
 
 
332
 
 
333
def demo():
 
334
    sleep = time.sleep
 
335
    
 
336
    print 'dumb-terminal test:'
 
337
    pb = DotsProgressBar()
 
338
    for i in range(100):
 
339
        pb.update('Leoparden', i, 99)
 
340
        sleep(0.1)
 
341
    sleep(1.5)
 
342
    pb.clear()
 
343
    sleep(1.5)
 
344
    
 
345
    print 'smart-terminal test:'
 
346
    pb = ProgressBar(show_pct=True, show_bar=True, show_spinner=False)
 
347
    for i in range(100):
 
348
        pb.update('Elephanten', i, 99)
 
349
        sleep(0.1)
 
350
    sleep(2)
 
351
    pb.clear()
 
352
    sleep(1)
 
353
 
 
354
    print 'done!'
 
355
 
 
356
if __name__ == "__main__":
 
357
    demo()