Progress Bars & Spinners

Examples of the progress widgets in action can be seen by running the module directly:

cd src/okaara

Progress Bars

When instantiated, the only required argument is the Prompt class instance used to render the progress bar. The total number of values the bar will represent, or for that matter the data itself, are not needed at instantiation time.

At each step of the iteration, the render method is called. This will redraw the progress bar using the current step and total number of steps passed into it. Additionally, a message for that step may be specified to be displayed under the bar. This message may be a single line or contain n characters to have it display across multiple lines.

The simplest implementation of a progress bar can be seen in the following code snippet (module imports omitted for brevity):

p = Prompt()
pb = ProgressBar(p, show_trailing_percentage=True)

total = 21
for i in range(0, total + 1):
  pb.render(i, total)

The output will continue to update as it executes and is difficult to capture in documentation. The end result will appear as follows:

[======================================] 100%

It’s also possible to customize much of the rendering of the progress bar itself. The following code snippet changes the default characters used for the bar and disables the percentage indicator at the right:

pb = ProgressBar(p, fill='*', left_tick='-<', right_tick='>-', show_trailing_percentage=False)

And the output at the end:


Again, it’s hard to show how the progress bar updates during execution. The following code snippet shows how to add a message to the progress bar:

for i in range(0, total + 1):
  message = 'Step: %d of %d' % (i, total)
  pb.render(i, total, message)

At the end of the execution, the final result displays:

[======================================] 100%
Step: 21 of 21

Instead of manually handling the call to render, an iterator may be wrapped by the progress bar to automatically render it at each step in the iteration. When the iterator is wrapped, a function can be supplied that accepts the current item being rendered and return a message string to use for that step. For example, to automatically render a progress bar over a series of items:

wrapped = pb.iterator(items, message_func=lambda x: 'Generated for item: %s' % x)

for w in wrapped:
  # Do important stuff but don't worry about progress bar

Each time an item is iterated over, the progress bar will be updated, generating a message custom for that particular item.


If progress bars were difficult to show in static documentation, spinners are going to be near impossible. :)

A spinner is a sequence of characters that will render in place during a long running operation. Unlike a progress bar, a spinner has no concept of how many times it will be spun nor can it display a message at each step.

The simplest usage of a spinner is as follows:

p = Prompt()
spinner = Spinner(p)

total = 10
for i in range(0, total):

That example will use the default sequence (it looks like a line spinning around). At the end of executing the above code, the last rendered iteration look like:


A custom sequence of characters may be supplied, along with the left/right boundaries of the spinner:

sequence = '! @ # $ %'.split()
spinner = Spinner(p, sequence=sequence, left_tick='{', right_tick='}')

With the custom ticks, the end output of a loop oer 10 items looks like:


Again, not terribly interesting in static documentation. All of these examples appear in the progress module itself and can be seen in action using the instructions above.

The Spinner class also supports wrapping an iterator; the process is the same as for progress bars.

Project Versions

Table Of Contents

Previous topic


Next topic

Command Line Interface

This Page