Progress bars 📊¶
A progress bar is a user interface element that indicates the progress of an operation. Progress bar supports two modes to represent progress: determinate, and indeterminate. Showing Progress Bars Sometimes, you have command line scripts that need to process a lot of data, but you want to quickly show the user some progress about how long that will take. Quo supports simple progress bar rendering for that.
The basic usage is very simple: the idea is that you have an iterable that you want to operate on. For each item in the iterable it might take some time to do processing.
Simple progress bar
¶
Creating a new progress bar can be done by calling the
ProgressBar
The progress can be displayed for any iterable. This works by wrapping the
iterable (like range
) with the
ProgressBar
. This
way, the progress bar knows when the next item is consumed by the forloop and
when progress happens.
import time
from quo.progress import ProgressBar
with ProgressBar() as pb:
for i in pb(range(800)):
time.sleep(.01)
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:
def some_iterable():
yield ...
with ProgressBar() as pb:
for i in pb(some_iterable, total=1000):
time.sleep(.01)
Multiple parallel tasks
¶
A quo ProgressBar
can display the
progress of multiple tasks running in parallel. Each task can run in a separate
thread and the 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.
from quo.progress 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)
Adding a title and label
¶
Each progress bar can have one title, and for each task an individual label.
from quo.progress import ProgressBar
from quo import echo
import time
title = echo(f"Downloading 4 files...", bg="yellow", fg="black")
label = echo(f"some file:", fg="red")
with ProgressBar(title=title) as pb:
for i in pb(range(800), label=label):
time.sleep(.01)
Formatting the progress bar
¶
The visualisation of a ProgressBar
can be
customized by using a different sequence of formatters. The default formatting looks something like this:
from quo.progress.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
Formatter
can be
passed to the formatter argument of
ProgressBar
. So, we could change this and
modify the progress bar to look like an apt-get style progress bar:
from quo.progress import ProgressBar, formatters
from quo.styles import Style
import time
style = Style.add({
'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)
Adding key bindings and toolbar
¶
Like other quo applications, we can add custom key bindings, by passing a KeyBinder
object:
from quo.text import Text
from quo.progress import ProgressBar
from quo.keys import Bind
from quo.patch_stdout import patch_stdout
import os
import time
import signal
example = Text(' <b>[f]</b> Print "f" <b>[x]</b> Abort.')
# Create custom key bindings first.
bind = Bind()
cancel = [False]
@bind.add('f')
def _(event):
print('You pressed `f`.')
@bind.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(bind=bind, bottom_toolbar=example) 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 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.
Read more about key bindings …