Metadata-Version: 2.4
Name: larzprogress
Version: 0.1.0
Summary: Progress bars and spinners that stay silent when output is not a terminal. Pure Python, zero dependencies.
Author: larz-scripter
License: MIT
Project-URL: Homepage, https://github.com/larz-scripter/larzprogress
Project-URL: Repository, https://github.com/larz-scripter/larzprogress
Project-URL: Issues, https://github.com/larz-scripter/larzprogress/issues
Keywords: progress,progressbar,progress-bar,spinner,cli,terminal,tqdm-alternative,eta,zero-dependency
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# 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.

```python
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](https://github.com/larz-scripter/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

```bash
pip install larzprogress
```

## Usage

```python
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

```bash
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](https://github.com/larz-scripter).

## License

MIT (c) larz-scripter
