enlighten Documentation

Enlighten supports automatic metric (SI) and binary (IEC) prefixes for numeric values.

• rate and interval fields use prefixed.Float.
• total and count fields default to int.
• If you set Counter.total or Counter.count to a float, or pass a float to Counter.update(), these fields will automatically use prefixed.Float formatting (e.g., converting bytes to MiB/GiB).

import time
import random
import enlighten

size = random.uniform(1.0, 10.0) * 2 ** 20  # 1-10 MiB (float)
chunk_size = 64 * 1024  # 64 KiB

# Use !.2j in the format string for prefixed float formatting
bar_format = '{desc}{desc_pad}{percentage:3.0f}%|{bar}| ' \
             '{count:!.2j}{unit} / {total:!.2j}{unit} ' \
             '[{elapsed}<{eta}, {rate:!.2j}{unit}/s]'

manager = enlighten.get_manager()
pbar = manager.counter(total=size, desc='Downloading', unit='B', bar_format=bar_format)

bytes_left = size
while bytes_left:
    time.sleep(random.uniform(0.05, 0.15))
    next_chunk = min(chunk_size, bytes_left)
    pbar.update(next_chunk)
    bytes_left -= next_chunk

You can track multiple categories within a single progress bar by adding subcounters to a parent counter using add_subcounter().

How it works:

• Colors are drawn from right to left in the order they were added.
• When all_fields=True is passed to add_subcounter, additional fields become available in the bar_format for that specific subcounter (indexed by _n or _2, etc.).

Available Fields for bar_format:

• count_n: Current value of subcounter $n$.
• count_0: Remaining count after deducting all subcounters.
• count_00: Sum of counts of all subcounters.
• percentage_n: Percentage complete for subcounter $n$.
• percentage_0: Remaining percentage after subcounters.
• percentage_00: Total percentage of all subcounters.
• eta_n (if all_fields=True): Estimated time to completion for subcounter $n$.
• rate_n (if all_fields=True): Average increments per second for subcounter $n$.

import random
import time
import enlighten

# Format using subcounter fields (e.g., count_2 for the second subcounter)
bar_format = u'{desc}{desc_pad}{percentage_2:3.0f}%|{bar}|' + \
            u' S:{count_0:{len_total}d} F:{count_2:{len_total}d} E:{count_1:{len_total}d}'

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')

# Update subcounters as work progresses
# errors.update()
# failures.update()
# success.update()

You can create multicolored progress bars to track different categories within a single bar. Colors are drawn from right to left in the order subcounters are added.

When using multicolored progress bars, the following additional fields are available for bar_format:

• count_n (int): Current value of count for the $n$-th subcounter.
• 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 for the $n$-th subcounter.
• percentage_0 (float): Remaining percentage after deducting percentages for all subcounters.
• percentage_00 (float): Total of percentages from all subcounters.

If you call Counter.add_subcounter_ with all_fields=True, the subcounter also provides:

• eta_n (str): Estimated time to completion for the $n$-th subcounter.
• rate_n (float): Average increments per second since the parent was created for the $n$-th subcounter.

import random
import time
import enlighten

# Example: Tracking test results (Success, Failures, Errors)
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))
    result = random.randint(0, 10)
    if result == 7:
        errors.update()
    elif result in (5, 6):
        failures.update()
    else:
        success.update()

If the manager is disabled (enabled=False), you can still retrieve the formatted string of a counter to print it manually. This is useful for custom logging or creating simple refreshing bars in environments without TTY support.

• Use Counter.format(width=...) to get the string.
• Coercing a Counter to a string (e.g., print(pbar)) calls .format() with default arguments.

import enlighten

# Method 1: Using .format()
manager = enlighten.get_manager(enabled=False)
pbar = manager.counter(desc='Progress', total=10)
pbar.update()
print(pbar.format(width=100))

# Method 2: String coercion
print(pbar)

# Method 3: Manual refreshing bar implementation
import time
manager = enlighten.get_manager(enabled=False)
pbar = manager.counter(desc='Progress', total=10)
print()
for _ in range(10):
    time.sleep(0.2)
    pbar.update()
    # Use carriage return \r to overwrite the line
    print(f'\r{pbar}', end='', flush=True)
print()