Metadata-Version: 2.4
Name: tqdm-overflow
Version: 0.1.0
Summary: Just replace your tqdm bars with this.
Project-URL: Homepage, https://github.com/CrossNox/tqdm-overflow
Project-URL: Repository, https://github.com/CrossNox/tqdm-overflow
Project-URL: Issues, https://github.com/CrossNox/tqdm-overflow/issues
Author-email: crossnox <ijmermet@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: animation,progress,progressbar,terminal,tqdm,tui
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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 :: Terminals
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: tqdm>=4.67.1
Description-Content-Type: text/markdown

# tqdm-overflow

A [`tqdm`](https://github.com/tqdm/tqdm) progress bar that is... well, more fun.

![demo](docs/overflow.gif)

It hits 100% long before the loop is done, and then the rest of the work just pours out the end of the bar and piles up at the bottom of your terminal as sand.

## Install

```bash
uv add tqdm-overflow
```

## Use

Like tqdm, with one extra knob:

```python
from tqdm_overflow import OverflowBar

for item in OverflowBar(range(1000), total=1000, fill_at=0.2):
    do_work(item)
```

`fill_at` is the fraction of `total` where the bar reads 100% (default `0.2`). Everything past that overflows. You still feed it the real `total` and never go over it — the bar just gets there early.

There's also `grains_per_unit`, `spawn_cap`, and `steps_per_frame` if you want a heavier pour or faster sand.

To play with the physics or the colors, build a `SandEngine` or `Screen` and pass it in — the bar sizes them to your terminal at run time:

```python
from tqdm_overflow import OverflowBar, SandEngine, Screen

OverflowBar(
    range(1000), total=1000, fill_at=0.2,
    engine=SandEngine(jitter=0.7, g=0.3),
    screen=Screen(palette=[(255, 80, 80), (180, 40, 40), (90, 20, 20)]),
)
```

Or just watch it:

```bash
tqdm-overflow
tqdm-overflow --fill-at 0.05 --delay 0.004
```

## Needs

Python 3.10+, and a terminal that does truecolor and braille — kitty, alacritty, wezterm, iTerm2, etc. Piped or redirected, it quietly falls back to a normal tqdm. Terminal size is read once at startup.
