tqdm-overflow 0.1.0

Just replace your tqdm bars with this.

tqdm-overflow

A tqdm progress bar that is... well, more fun.

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

uv add tqdm-overflow

Use

Like tqdm, with one extra knob:

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:

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:

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.