enlighten 1.12.3

Enlighten Progress Bar

Overview

Enlighten Progress Bar is a console progress bar library for Python.

The main advantage of Enlighten is it allows writing to stdout and stderr without any redirection or additional code. Just print or log as you normally would.

Enlighten also includes experimental support for Jupyter Notebooks.

The code for this animation can be found in demo.py in examples.

Documentation

https://python-enlighten.readthedocs.io

Installation

PIP

$ pip install enlighten

RPM

Fedora and EL8 (RHEL/CentOS)

(For EPEL repositories must be configured)

$ dnf install python3-enlighten

DEB

Debian and Ubuntu

$ apt-get install python3-enlighten

Conda

$ conda install -c conda-forge enlighten

How to Use

Managers

The first step is to create a manager. Managers handle output to the terminal and allow multiple progress bars to be displayed at the same time.

get_manager can be used to get a Manager instance. Managers will only display output when the output stream, sys.__stdout__ by default, is attached to a TTY. If the stream is not attached to a TTY, the manager instance returned will be disabled.

In most cases, a manager can be created like this.

import enlighten
manager = enlighten.get_manager()

If you need to use a different output stream, or override the defaults, see the documentation for get_manager

Progress Bars

For a basic progress bar, invoke the Manager.counter method.

import time
import enlighten

manager = enlighten.get_manager()
pbar = manager.counter(total=100, desc='Basic', unit='ticks')

for num in range(100):
    time.sleep(0.1)  # Simulate work
    pbar.update()

Additional progress bars can be created with additional calls to the Manager.counter method.

import time
import enlighten

manager = enlighten.get_manager()
ticks = manager.counter(total=100, desc='Ticks', unit='ticks')
tocks = manager.counter(total=20, desc='Tocks', unit='tocks')

for num in range(100):
    time.sleep(0.1)  # Simulate work
    print(num)
    ticks.update()
    if not num % 5:
        tocks.update()

manager.stop()

Counters

The Counter class has two output formats, progress bar and counter.

The progress bar format is used when a total is not None and the count is less than the total. If neither of these conditions are met, the counter format is used:

import time
import enlighten

manager = enlighten.get_manager()
counter = manager.counter(desc='Basic', unit='ticks')

for num in range(100):
    time.sleep(0.1)  # Simulate work
    counter.update()

Status Bars

Status bars are bars that work similarly to progress bars and counters, but present relatively static information. Status bars are created with Manager.status_bar.

import enlighten
import time

manager = enlighten.get_manager()
status_bar = manager.status_bar('Static Message',
                                color='white_on_red',
                                justify=enlighten.Justify.CENTER)
time.sleep(1)
status_bar.update('Updated static message')
time.sleep(1)

Status bars can also use formatting with dynamic variables.

import enlighten
import time

manager = enlighten.get_manager()
status_format = '{program}{fill}Stage: {stage}{fill} Status {status}'
status_bar = manager.status_bar(status_format=status_format,
                                color='bold_slategray',
                                program='Demo',
                                stage='Loading',
                                status='OKAY')
time.sleep(1)
status_bar.update(stage='Initializing', status='OKAY')
time.sleep(1)
status_bar.update(status='FAIL')

Status bars, like other bars can be pinned. To pin a status bar to the top of all other bars, initialize it before any other bars. To pin a bar to the bottom of the screen, use position=1 when initializing.

See StatusBar for more details.

Color

Status bars and the bar component of a progress bar can be colored by setting the color keyword argument. See Series Color for more information about valid colors.

import time
import enlighten

manager = enlighten.get_manager()
counter = manager.counter(total=100, desc='Colorized', unit='ticks', color='red')

for num in range(100):
    time.sleep(0.1)  # Simulate work
counter.update()

Additionally, any part of the progress bar can be colored using counter formatting and the color capabilities of the underlying Blessed Terminal.

import enlighten

manager = enlighten.get_manager()

# Standard bar format
std_bar_format = u'{desc}{desc_pad}{percentage:3.0f}%|{bar}| ' + \
                 u'{count:{len_total}d}/{total:d} ' + \
                 u'[{elapsed}<{eta}, {rate:.2f}{unit_pad}{unit}/s]'

# Red text
bar_format = manager.term.red(std_bar_format)

# Red on white background
bar_format = manager.term.red_on_white(std_bar_format)

# X11 colors
bar_format = manager.term.peru_on_seagreen(std_bar_format)

# RBG text
bar_format = manager.term.color_rgb(2, 5, 128)(std_bar_format)

# RBG background
bar_format = manager.term.on_color_rgb(255, 190, 195)(std_bar_format)

# RGB text and background
bar_format = manager.term.on_color_rgb(255, 190, 195)(std_bar_format)
bar_format = manager.term.color_rgb(2, 5, 128)(bar_format)

# Apply color to select parts
bar_format = manager.term.red(u'{desc}') + u'{desc_pad}' + \
             manager.term.blue(u'{percentage:3.0f}%') + u'|{bar}|'

# Apply to counter
ticks = manager.counter(total=100, desc='Ticks', unit='ticks', bar_format=bar_format)

If the color option is applied to a Counter, it will override any foreground color applied.

Multicolored

The bar component of a progress bar can be multicolored to track multiple categories in a single progress bar.

The colors are drawn from right to left in the order they were added.

By default, when multicolored progress bars are used, additional fields are available for bar_format:

• count_n (int) - Current value of count

• count_0(int) - Remaining count after deducting counts for all subcounters

• count_00 (int) - Sum of counts from all subcounters

• percentage_n (float) - Percentage complete

• percentage_0(float) - Remaining percentage after deducting percentages for all subcounters

• percentage_00 (float) - Total of percentages from all subcounters

When Counter.add_subcounter is called with all_fields set to True, the subcounter will have the additional fields:

• eta_n (str) - Estimated time to completion

• rate_n (float) - Average increments per second since parent was created

More information about bar_format can be found in the Format section of the API.

One use case for multicolored progress bars is recording the status of a series of tests. In this example, Failures are red, errors are white, and successes are green. The count of each is listed in the progress bar.

import random
import time
import enlighten

bar_format = u'{desc}{desc_pad}{percentage:3.0f}%|{bar}| ' + \
            u'S:{count_0:{len_total}d} ' + \
            u'F:{count_2:{len_total}d} ' + \
            u'E:{count_1:{len_total}d} ' + \
            u'[{elapsed}<{eta}, {rate:.2f}{unit_pad}{unit}/s]'

manager = enlighten.get_manager()
success = manager.counter(total=100, desc='Testing', unit='tests',
                            color='green', bar_format=bar_format)
errors = success.add_subcounter('white')
failures = success.add_subcounter('red')

while success.count < 100:
    time.sleep(random.uniform(0.1, 0.3))  # Random processing time
    result = random.randint(0, 10)

    if result == 7:
        errors.update()
    if result in (5, 6):
        failures.update()
    else:
        success.update()

A more complicated example is recording process start-up. In this case, all items will start red, transition to yellow, and eventually all will be green. The count, percentage, rate, and eta fields are all derived from the second subcounter added.

import random
import time
import enlighten

services = 100
bar_format = u'{desc}{desc_pad}{percentage_2:3.0f}%|{bar}|' + \
            u' {count_2:{len_total}d}/{total:d} ' + \
            u'[{elapsed}<{eta_2}, {rate_2:.2f}{unit_pad}{unit}/s]'

manager = enlighten.get_manager()
initializing = manager.counter(total=services, desc='Starting', unit='services',
                                color='red', bar_format=bar_format)
starting = initializing.add_subcounter('yellow')
started = initializing.add_subcounter('green', all_fields=True)

while started.count < services:
    remaining = services - initializing.count
    if remaining:
        num = random.randint(0, min(4, remaining))
        initializing.update(num)

    ready = initializing.count - initializing.subcount
    if ready:
        num = random.randint(0, min(3, ready))
        starting.update_from(initializing, num)

    if starting.count:
        num = random.randint(0, min(2, starting.count))
        started.update_from(starting, num)

    time.sleep(random.uniform(0.1, 0.5))  # Random processing time

Additional Examples

• basic - Basic progress bar

• context manager - Managers and counters as context managers

• floats - Support totals and counts that are floats

• multicolored - Multicolored progress bars

• multiple with logging - Nested progress bars and logging

• FTP downloader - Show progress downloading files from FTP

Customization

Enlighten is highly configurable. For information on modifying the output, see the Series and Format sections of the Counter documentation.