← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/progress.py

  • Committer: Patch Queue Manager
  • Date: 2016-04-21 04:10:52 UTC
  • mfrom: (6616.1.1 fix-en-user-guide)
  • Revision ID: pqm@pqm.ubuntu.com-20160421041052-clcye7ns1qcl2n7w
(richard-wilbur) Ensure build of English use guide always uses English text
 even when user's locale specifies a different language. (Jelmer Vernooij)

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 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-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.
27
21
"""
28
22
 
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
 
23
from __future__ import absolute_import
 
24
 
40
25
import time
41
26
import os
42
27
 
43
28
 
44
 
def _width():
45
 
    """Return estimated terminal width.
46
 
 
47
 
    TODO: Do something smart on Windows?
48
 
 
49
 
    TODO: Is there anything that gets a better update when the window
50
 
          is resized while the program is running?
51
 
    """
52
 
    try:
53
 
        return int(os.environ['COLUMNS'])
54
 
    except (IndexError, KeyError, ValueError):
55
 
        return 80
56
 
 
57
 
 
58
29
def _supports_progress(f):
59
 
    if not hasattr(f, 'isatty'):
60
 
        return False
61
 
    if not f.isatty():
62
 
        return False
 
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.
63
46
    if os.environ.get('TERM') == 'dumb':
64
47
        # e.g. emacs compile window
65
48
        return False
66
49
    return True
67
50
 
68
51
 
69
 
 
70
 
def ProgressBar(to_file=sys.stderr, **kwargs):
71
 
    """Abstract factory"""
72
 
    if _supports_progress(to_file):
73
 
        return TTYProgressBar(to_file=to_file, **kwargs)
74
 
    else:
75
 
        return DotsProgressBar(to_file=to_file, **kwargs)
76
 
    
77
 
    
78
 
class _BaseProgressBar(object):
79
 
    def __init__(self,
80
 
                 to_file=sys.stderr,
81
 
                 show_pct=False,
82
 
                 show_spinner=False,
83
 
                 show_eta=True,
84
 
                 show_bar=True,
85
 
                 show_count=True):
86
 
        object.__init__(self)
87
 
        self.to_file = to_file
88
 
 
89
 
        self.last_msg = None
90
 
        self.last_cnt = None
91
 
        self.last_total = None
92
 
        self.show_pct = show_pct
93
 
        self.show_spinner = show_spinner
94
 
        self.show_eta = show_eta
95
 
        self.show_bar = show_bar
96
 
        self.show_count = show_count
97
 
 
98
 
 
99
 
 
100
 
class DummyProgress(_BaseProgressBar):
 
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):
101
169
    """Progress-bar standin that does nothing.
102
170
 
103
 
    This can be used as the default argument for methods that
104
 
    take an optional progress indicator."""
 
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
 
105
177
    def tick(self):
106
178
        pass
107
179
 
108
180
    def update(self, msg=None, current=None, total=None):
109
181
        pass
110
182
 
111
 
    def clear(self):
112
 
        pass
113
 
        
114
 
    
115
 
class DotsProgressBar(_BaseProgressBar):
116
 
    def __init__(self, **kwargs):
117
 
        _BaseProgressBar.__init__(self, **kwargs)
118
 
        self.last_msg = None
119
 
        self.need_nl = False
120
 
        
121
 
    def tick(self):
122
 
        self.update()
123
 
        
124
 
    def update(self, msg=None, current_cnt=None, total_cnt=None):
125
 
        if msg and msg != self.last_msg:
126
 
            if self.need_nl:
127
 
                self.to_file.write('\n')
128
 
            
129
 
            self.to_file.write(msg + ': ')
130
 
            self.last_msg = msg
131
 
        self.need_nl = True
132
 
        self.to_file.write('.')
133
 
        
134
 
    def clear(self):
135
 
        if self.need_nl:
136
 
            self.to_file.write('\n')
137
 
        
138
 
    
139
 
class TTYProgressBar(_BaseProgressBar):
140
 
    """Progress bar display object.
141
 
 
142
 
    Several options are available to control the display.  These can
143
 
    be passed as parameters to the constructor or assigned at any time:
144
 
 
145
 
    show_pct
146
 
        Show percentage complete.
147
 
    show_spinner
148
 
        Show rotating baton.  This ticks over on every update even
149
 
        if the values don't change.
150
 
    show_eta
151
 
        Show predicted time-to-completion.
152
 
    show_bar
153
 
        Show bar graph.
154
 
    show_count
155
 
        Show numerical counts.
156
 
 
157
 
    The output file should be in line-buffered or unbuffered mode.
158
 
    """
159
 
    SPIN_CHARS = r'/-\|'
160
 
    MIN_PAUSE = 0.1 # seconds
161
 
 
162
 
 
163
 
    def __init__(self, **kwargs):
164
 
        _BaseProgressBar.__init__(self, **kwargs)
165
 
        self.spin_pos = 0
166
 
        self.width = _width()
167
 
        self.start_time = None
168
 
        self.last_update = None
169
 
    
170
 
 
171
 
    def throttle(self):
172
 
        """Return True if the bar was updated too recently"""
173
 
        now = time.time()
174
 
        if self.start_time is None:
175
 
            self.start_time = self.last_update = now
176
 
            return False
177
 
        else:
178
 
            interval = now - self.last_update
179
 
            if interval > 0 and interval < self.MIN_PAUSE:
180
 
                return True
181
 
 
182
 
        self.last_update = now
183
 
        return False
184
 
        
185
 
 
186
 
    def tick(self):
187
 
        self.update(self.last_msg, self.last_cnt, self.last_total)
188
 
                 
189
 
 
190
 
 
191
 
    def update(self, msg, current_cnt=None, total_cnt=None):
192
 
        """Update and redraw progress bar."""
193
 
 
194
 
        if current_cnt < 0:
195
 
            current_cnt = 0
196
 
            
197
 
        if current_cnt > total_cnt:
198
 
            total_cnt = current_cnt
199
 
 
200
 
        # save these for the tick() function
201
 
        self.last_msg = msg
202
 
        self.last_cnt = current_cnt
203
 
        self.last_total = total_cnt
204
 
            
205
 
        if self.throttle():
206
 
            return 
207
 
        
208
 
        if self.show_eta and self.start_time and total_cnt:
209
 
            eta = get_eta(self.start_time, current_cnt, total_cnt)
210
 
            eta_str = " " + str_tdelta(eta)
211
 
        else:
212
 
            eta_str = ""
213
 
 
214
 
        if self.show_spinner:
215
 
            spin_str = self.SPIN_CHARS[self.spin_pos % 4] + ' '            
216
 
        else:
217
 
            spin_str = ''
218
 
 
219
 
        # always update this; it's also used for the bar
220
 
        self.spin_pos += 1
221
 
 
222
 
        if self.show_pct and total_cnt and current_cnt:
223
 
            pct = 100.0 * current_cnt / total_cnt
224
 
            pct_str = ' (%5.1f%%)' % pct
225
 
        else:
226
 
            pct_str = ''
227
 
 
228
 
        if not self.show_count:
229
 
            count_str = ''
230
 
        elif current_cnt is None:
231
 
            count_str = ''
232
 
        elif total_cnt is None:
233
 
            count_str = ' %i' % (current_cnt)
234
 
        else:
235
 
            # make both fields the same size
236
 
            t = '%i' % (total_cnt)
237
 
            c = '%*i' % (len(t), current_cnt)
238
 
            count_str = ' ' + c + '/' + t 
239
 
 
240
 
        if self.show_bar:
241
 
            # progress bar, if present, soaks up all remaining space
242
 
            cols = self.width - 1 - len(msg) - len(spin_str) - len(pct_str) \
243
 
                   - len(eta_str) - len(count_str) - 3
244
 
 
245
 
            if total_cnt:
246
 
                # number of markers highlighted in bar
247
 
                markers = int(round(float(cols) * current_cnt / total_cnt))
248
 
                bar_str = '[' + ('=' * markers).ljust(cols) + '] '
249
 
            elif False:
250
 
                # don't know total, so can't show completion.
251
 
                # so just show an expanded spinning thingy
252
 
                m = self.spin_pos % cols
253
 
                ms = (' ' * m + '*').ljust(cols)
254
 
                
255
 
                bar_str = '[' + ms + '] '
256
 
            else:
257
 
                bar_str = ''
258
 
        else:
259
 
            bar_str = ''
260
 
 
261
 
        m = spin_str + bar_str + msg + count_str + pct_str + eta_str
262
 
 
263
 
        assert len(m) < self.width
264
 
        self.to_file.write('\r' + m.ljust(self.width - 1))
265
 
        #self.to_file.flush()
266
 
            
267
 
 
268
 
    def clear(self):        
269
 
        self.to_file.write('\r%s\r' % (' ' * (self.width - 1)))
270
 
        #self.to_file.flush()        
271
 
    
272
 
 
273
 
        
 
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
 
274
193
def str_tdelta(delt):
275
194
    if delt is None:
276
195
        return "-:--:--"
280
199
                             delt % 60)
281
200
 
282
201
 
283
 
def get_eta(start_time, current, total, enough_samples=3):
 
202
def get_eta(start_time, current, total, enough_samples=3, last_updates=None, n_recent=10):
284
203
    if start_time is None:
285
204
        return None
286
205
 
297
216
 
298
217
    if elapsed < 2.0:                   # not enough time to estimate
299
218
        return None
300
 
    
 
219
 
301
220
    total_duration = float(elapsed) * float(total) / float(current)
302
221
 
303
 
    assert total_duration >= elapsed
 
222
    if last_updates and len(last_updates) >= n_recent:
 
223
        avg = sum(last_updates) / float(len(last_updates))
 
224
        time_left = avg * (total - current)
 
225
 
 
226
        old_time_left = total_duration - elapsed
 
227
 
 
228
        # We could return the average, or some other value here
 
229
        return (time_left + old_time_left) / 2
304
230
 
305
231
    return total_duration - elapsed
306
232
 
307
233
 
308
 
def run_tests():
309
 
    import doctest
310
 
    result = doctest.testmod()
311
 
    if result[1] > 0:
312
 
        if result[0] == 0:
313
 
            print "All tests passed"
314
 
    else:
315
 
        print "No tests to run"
316
 
 
317
 
 
318
 
def demo():
319
 
    sleep = time.sleep
320
 
    
321
 
    print 'dumb-terminal test:'
322
 
    pb = DotsProgressBar()
323
 
    for i in range(100):
324
 
        pb.update('Leoparden', i, 99)
325
 
        sleep(0.1)
326
 
    sleep(1.5)
327
 
    pb.clear()
328
 
    sleep(1.5)
329
 
    
330
 
    print 'smart-terminal test:'
331
 
    pb = ProgressBar(show_pct=True, show_bar=True, show_spinner=False)
332
 
    for i in range(100):
333
 
        pb.update('Elephanten', i, 99)
334
 
        sleep(0.1)
335
 
    sleep(2)
336
 
    pb.clear()
337
 
    sleep(1)
338
 
 
339
 
    print 'done!'
340
 
 
341
 
if __name__ == "__main__":
342
 
    demo()
 
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)