RunScope

A progress bar that doesn't lie. Calibrated ETAs and completion intelligence for long-running Python jobs.

from runscope import trange           # drop-in for tqdm

for i in trange(48000, key="terrain_analysis"):
    process(tile(i))

terrain_analysis  ▕████████░░░░░░░░░░░░▏ 38%  17,492/48,000
  47m elapsed · about 1h 20m left · done ~10:42 PM
  likely 1h 12m–1h 31m · confidence high

Ordinary progress bars assume the rest of your job looks like the part that already ran. That assumption breaks exactly when it matters — when the expensive work is at the end. RunScope gives you an honest range instead of a fake exact number, and it learns your recurring jobs so each run's estimate gets better than the last.

Install

pip install runscope        # free, local, zero dependencies

Use it

1. Wrap any loop

import runscope

for item in runscope.track(items, key="my_job"):
    process(item)

2. Drop-in for tqdm

from runscope import trange
for i in trange(10000, key="my_job"):
    ...

3. Tell it how "big" each item is (stronger estimates)

for path in runscope.track(files, key="ingest", weight=lambda p: p.stat().st_size):
    process(path)

4. Peek at the future for known-heterogeneous jobs

# checks a tiny representative sample of the REMAINING work up front, so a
# back-loaded job can't ambush you with a 3x longer runtime at the end
for item in runscope.track(items, key="my_job", weight=size_of, measure=True):
    process(item)

5. Instrument an existing script without editing it

runscope run train.py        # transparently upgrades tqdm bars in the script

How it works (you never have to think about this)

Three layers combine automatically:

The key is what ties runs of the same job together so RunScope can learn. Use a stable name for recurring jobs (key="nightly_terrain").

Free vs Pro

• Free: local calibrated ETAs, honest ranges, and per-job history on your machine. No account, no network, no dependencies.
• Pro (coming): cloud history across machines, "today vs your last 20 runs," and push/Slack alerts when a job blows past its ETA or stalls.

What it's good at (and what it isn't)

RunScope is for enumerable work — loops over files, records, images, tiles, simulations, parameter grids, API calls. That covers a huge amount of scientific and data-processing work.

It does not try to predict the runtime of an arbitrary opaque operation with no sub-steps and no history. When there isn't enough information to estimate honestly, it tells you so instead of inventing a number. That restraint is on purpose.

The science

RunScope's estimators are not heuristics someone made up. They come from a research program (ETA-Proto) that tested dozens of ETA methods against a simple baseline under preregistered pass/fail gates and kept only what won by a required margin. The core finding: for enumerable jobs, a size-weighted estimate is very hard to beat — except by measuring a small sample of the unexecuted work, which cut remaining-time error 40–90% on hard, heterogeneous workloads. That measurement is the measure=True mode.

License

Apache-2.0.