progress1bar

A lightweight, ANSI-based progress bar for terminal output — configurable, readable, and easy to drop into loops or long-running jobs.

Installation

pip install progress1bar

Quick start

Use ProgressBar as a context manager. Set total, then increment count.

import time
from progress1bar import ProgressBar

with ProgressBar(total=250) as pb:
    for _ in range(pb.total):
        pb.count += 1
        time.sleep(0.01)  # simulate work

Showing what’s being processed (alias)

If you want the bar to show the “current item”, set alias as you go. You can also set a custom ticker.

import time
from faker import Faker
from colorama import Fore
from colorama import Style
from progress1bar import ProgressBar

kwargs = {
    'total': 75,
    'show_complete': False,
    'clear_alias': True,
    'show_duration': False,
    'ticker': Style.BRIGHT + Fore.RED + chr(9644) + Style.RESET_ALL,
}
with ProgressBar(**kwargs) as pb:
    for _ in range(pb.total):
        pb.alias = Faker().name()
        time.sleep(.08)  # simulate work
        pb.count += 1

Configuration

ProgressBar(
    total=None,
    fill=None,
    regex=None,
    completed_message=None,
    clear_alias=False,
    show_fraction=True,
    show_percentage=True,
    show_duration=False,
    show_complete=True,
    ticker=None,
    use_color=True,
    show_bar=True)

Number formatting (fill)

fill lets you pad the displayed total / count with leading zeros for a consistent look.

fill = {"max_total": 4, "max_completed": 4}

Regex-driven updates (regex)

If you’d rather drive the progress bar by feeding it messages (instead of setting attributes directly), you can supply regex patterns for total, count, and optionally alias. When a message matches, the captured value is applied.

import random
from faker import Faker
from progress1bar import ProgressBar

kwargs = {
    "ticker": 9733,  # ★
    "regex": {
        "total": r"^processing total of (?P<value>\d+)$",
        "count": r"^processed .*$",
        "alias": r"^processor is (?P<value>.*)$",
    },
    "use_color": False,
}

with ProgressBar(**kwargs) as pb:
    pb.match(f"processor is {Faker().name()}")
    total = random.randint(500, 750)
    pb.match(f"processing total of {total}")
    for _ in range(total):
        pb.match(f"processed {Faker().name()}")

Reuse the same progress bar (reset())

If you want to reuse one ProgressBar instance across multiple runs (and keep track of repeated usage), call:

pb.reset()

More Examples

The repo includes multiple runnable examples (including variations like “no bar, just percentage/fraction”, custom tickers, regex matching, and multiple iterations with resets).

Development

Clone the repository and ensure the latest version of Docker is installed on your development server.

Build the Docker image:

docker image build \
-t progress1bar:latest .

Run the Docker container:

docker container run \
--rm \
-it \
-v $PWD:/code \
progress1bar:latest \
bash

Execute the build:

make dev