larzprogress

Progress bars & spinners that behave in a pipe. Pure Python, zero deps.

Wrap a loop and get a live progress bar with percentage, counts, rate, and ETA - or a spinner for work of unknown length. The part most home-grown progress code gets wrong: when output is not a terminal (a log file, a CI pipe), larzprogress stays silent instead of spraying carriage returns and bar characters into your logs.

from larzprogress import progress, ProgressBar, Spinner

for item in progress(items, desc="Processing"):
    handle(item)
# Processing: 62%|███████████░░░░░| 620/1000 [00:12<00:07, 51.2 it/s]

with Spinner("Connecting"):
    connect()

Why

• Pipe-safe by default. Output only animates on a TTY; redirect to a file or run in CI and it produces nothing (no \r, no half-drawn bars in your logs) - the same care larzcolor takes.
• Everything you want on the bar. Percentage, count, elapsed, ETA, and rate, throttled so it doesn't flicker.
• Manual or automatic. progress(iterable) wraps a loop; ProgressBar gives you update()/close() for custom flows; Spinner covers unknown-length work.
• Testable & zero-dep. Injectable clock and stream (this repo's tests assert exact output), no tqdm, no dependency.

Install

pip install larzprogress

Usage

from larzprogress import progress, ProgressBar, Spinner

# wrap an iterable
for row in progress(rows, desc="Import"):
    save(row)

# manual
bar = ProgressBar(total=len(work), desc="Build")
for w in work:
    do(w); bar.update()
bar.close()

# or as a context manager
with ProgressBar(total=100) as bar:
    for _ in range(100):
        bar.update()

# unknown length
with Spinner("Fetching"):
    fetch()

Force behaviour with disable=True/False when you need to.

Tests

python -m unittest discover -s tests -v   # 13 tests incl. the silent-in-a-pipe guarantee

The Larz stack

One of 30+ pure-Python, zero-dependency libraries at github.com/larz-scripter.

License

MIT (c) larz-scripter