1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
|
.. _progress_bars:
Progress bars
=============
Prompt_toolkit ships with a high level API for displaying progress bars,
inspired by `tqdm <https://github.com/tqdm/tqdm>`_
.. warning::
The API for the prompt_toolkit progress bars is still very new and can
possibly change in the future. It is usable and tested, but keep this in
mind when upgrading.
Remember that the `examples directory <https://github.com/prompt-toolkit/python-prompt-toolkit/tree/master/examples>`_
of the prompt_toolkit repository ships with many progress bar examples as well.
Simple progress bar
-------------------
Creating a new progress bar can be done by calling the
:class:`~prompt_toolkit.shortcuts.ProgressBar` context manager.
The progress can be displayed for any iterable. This works by wrapping the
iterable (like ``range``) with the
:class:`~prompt_toolkit.shortcuts.ProgressBar` context manager itself. This
way, the progress bar knows when the next item is consumed by the forloop and
when progress happens.
.. code:: python
from prompt_toolkit.shortcuts import ProgressBar
import time
with ProgressBar() as pb:
for i in pb(range(800)):
time.sleep(.01)
.. image:: ../images/progress-bars/simple-progress-bar.png
Keep in mind that not all iterables can report their total length. This happens
with a typical generator. In that case, you can still pass the total as follows
in order to make displaying the progress possible:
.. code:: python
def some_iterable():
yield ...
with ProgressBar() as pb:
for i in pb(some_iterable(), total=1000):
time.sleep(.01)
Multiple parallel tasks
-----------------------
A prompt_toolkit :class:`~prompt_toolkit.shortcuts.ProgressBar` can display the
progress of multiple tasks running in parallel. Each task can run in a separate
thread and the :class:`~prompt_toolkit.shortcuts.ProgressBar` user interface
runs in its own thread.
Notice that we set the "daemon" flag for both threads that run the tasks. This
is because control-c will stop the progress and quit our application. We don't
want the application to wait for the background threads to finish. Whether you
want this depends on the application.
.. code:: python
from prompt_toolkit.shortcuts import ProgressBar
import time
import threading
with ProgressBar() as pb:
# Two parallel tasks.
def task_1():
for i in pb(range(100)):
time.sleep(.05)
def task_2():
for i in pb(range(150)):
time.sleep(.08)
# Start threads.
t1 = threading.Thread(target=task_1)
t2 = threading.Thread(target=task_2)
t1.daemon = True
t2.daemon = True
t1.start()
t2.start()
# Wait for the threads to finish. We use a timeout for the join() call,
# because on Windows, join cannot be interrupted by Control-C or any other
# signal.
for t in [t1, t2]:
while t.is_alive():
t.join(timeout=.5)
.. image:: ../images/progress-bars/two-tasks.png
Adding a title and label
------------------------
Each progress bar can have one title, and for each task an individual label.
Both the title and the labels can be :ref:`formatted text <formatted_text>`.
.. code:: python
from prompt_toolkit.shortcuts import ProgressBar
from prompt_toolkit.formatted_text import HTML
import time
title = HTML('Downloading <style bg="yellow" fg="black">4 files...</style>')
label = HTML('<ansired>some file</ansired>: ')
with ProgressBar(title=title) as pb:
for i in pb(range(800), label=label):
time.sleep(.01)
.. image:: ../images/progress-bars/colored-title-and-label.png
Formatting the progress bar
---------------------------
The visualization of a :class:`~prompt_toolkit.shortcuts.ProgressBar` can be
customized by using a different sequence of formatters. The default formatting
looks something like this:
.. code:: python
from prompt_toolkit.shortcuts.progress_bar.formatters import *
default_formatting = [
Label(),
Text(' '),
Percentage(),
Text(' '),
Bar(),
Text(' '),
Progress(),
Text(' '),
Text('eta [', style='class:time-left'),
TimeLeft(),
Text(']', style='class:time-left'),
Text(' '),
]
That sequence of
:class:`~prompt_toolkit.shortcuts.progress_bar.formatters.Formatter` can be
passed to the `formatter` argument of
:class:`~prompt_toolkit.shortcuts.ProgressBar`. So, we could change this and
modify the progress bar to look like an apt-get style progress bar:
.. code:: python
from prompt_toolkit.shortcuts import ProgressBar
from prompt_toolkit.styles import Style
from prompt_toolkit.shortcuts.progress_bar import formatters
import time
style = Style.from_dict({
'label': 'bg:#ffff00 #000000',
'percentage': 'bg:#ffff00 #000000',
'current': '#448844',
'bar': '',
})
custom_formatters = [
formatters.Label(),
formatters.Text(': [', style='class:percentage'),
formatters.Percentage(),
formatters.Text(']', style='class:percentage'),
formatters.Text(' '),
formatters.Bar(sym_a='#', sym_b='#', sym_c='.'),
formatters.Text(' '),
]
with ProgressBar(style=style, formatters=custom_formatters) as pb:
for i in pb(range(1600), label='Installing'):
time.sleep(.01)
.. image:: ../images/progress-bars/apt-get.png
Adding key bindings and toolbar
-------------------------------
Like other prompt_toolkit applications, we can add custom key bindings, by
passing a :class:`~prompt_toolkit.key_binding.KeyBindings` object:
.. code:: python
from prompt_toolkit import HTML
from prompt_toolkit.key_binding import KeyBindings
from prompt_toolkit.patch_stdout import patch_stdout
from prompt_toolkit.shortcuts import ProgressBar
import os
import time
import signal
bottom_toolbar = HTML(' <b>[f]</b> Print "f" <b>[x]</b> Abort.')
# Create custom key bindings first.
kb = KeyBindings()
cancel = [False]
@kb.add('f')
def _(event):
print('You pressed `f`.')
@kb.add('x')
def _(event):
" Send Abort (control-c) signal. "
cancel[0] = True
os.kill(os.getpid(), signal.SIGINT)
# Use `patch_stdout`, to make sure that prints go above the
# application.
with patch_stdout():
with ProgressBar(key_bindings=kb, bottom_toolbar=bottom_toolbar) as pb:
for i in pb(range(800)):
time.sleep(.01)
# Stop when the cancel flag has been set.
if cancel[0]:
break
Notice that we use :func:`~prompt_toolkit.patch_stdout.patch_stdout` to make
printing text possible while the progress bar is displayed. This ensures that
printing happens above the progress bar.
Further, when "x" is pressed, we set a cancel flag, which stops the progress.
It would also be possible to send `SIGINT` to the mean thread, but that's not
always considered a clean way of cancelling something.
In the example above, we also display a toolbar at the bottom which shows the
key bindings.
.. image:: ../images/progress-bars/custom-key-bindings.png
:ref:`Read more about key bindings ...<key_bindings>`
|
