Metadata-Version: 2.5
Name: tqdm-live
Version: 0.7.0
Summary: Stream your tqdm progress bars to any browser, realtime. Zero config.
Project-URL: Homepage, https://runpeek.app
Project-URL: Documentation, https://runpeek.app/docs
Project-URL: Pricing, https://runpeek.app/pricing
Author-email: Bitgate <kevin@bitgate.com>
License: MIT
Keywords: ml,monitoring,progress,progress-bar,tqdm,training
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Framework :: Jupyter
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.8
Requires-Dist: tqdm>=4.60
Description-Content-Type: text/markdown

# tqdm-live

Stream your tqdm progress bars to any browser, realtime. Zero config, anonymous by default.

```bash
pip install tqdm-live
```

```python
from tqdm_live import tqdm

for epoch in tqdm(range(epochs)):
    train_one_epoch()

# prints: runpeek ▶ https://runpeek.app/b/<uuid>  (expires 30 min after the last update; 'tqdml login' saves runs)
```

Or leave your code completely untouched:

```python
import tqdm_live
tqdm_live.patch()  # every tqdm bar in this process now streams
```

Open the printed URL on your phone. Done.

## Runs

```python
tqdm_live.start_run("train-resnet")  # one link for every bar in this process
```

```bash
tqdml run -- python train.py --epochs 30
```

A run shows the process lifecycle next to its bars and closes with the real exit code. `tqdml run` wraps any command, streams its stdout/stderr and patches tqdm in the child without code changes.

## Alerts

```python
tqdm_live.start_run("train-resnet")
tqdm_live.notify("https://discord.com/api/webhooks/...")  # finished or failed
tqdm_live.notify("https://hooks.slack.com/services/...", events=("failed",), stall_after_minutes=15)
```

Discord and Slack webhooks get a formatted message, any other URL receives the raw JSON event. `stall_after_minutes` (1 to 1440) also alerts when the run goes silent that long. `notify()` needs an active run and returns whether the webhook was registered. `TQDMLIVE_NOTIFY` (comma-separated URLs) registers webhooks for every run, `tqdml run` included.

## Save runs to your dashboard

```bash
tqdml login    # approve once in the browser
tqdml whoami   # the account your runs are saved to
```

Once logged in, every script that shows a bar is saved as a run named after the script, next to your `start_run()` and `tqdml run` runs. On servers and CI, set `RUNPEEK_TOKEN` instead (create a token on the dashboard's Setup page). `tqdml logout` removes the saved login.

Notebooks, IPython and the Python REPL are the exception: bars there stay anonymous, so an idle kernel never becomes a run.
To save an experiment from a notebook, call `tqdm_live.start_run("my-experiment")` before the loop and `tqdm_live.end_run()` when it's done.

Free accounts keep 7 days of history, [Pro](https://runpeek.app/pricing) ($9/mo) keeps a year. Over the monthly saved-run limit a run still streams live, it just isn't saved.

## Notes

- Bars are addressed by unguessable UUIDs. No account needed, logging in is optional.
- Heartbeats are throttled (~0.75s) and sent from a daemon thread; your loop never blocks on the network, and send failures never raise into your code.
- An unsaved bar or run expires 30 minutes after its last heartbeat.

## Config (all optional)

```python
import tqdm_live
tqdm_live.setup(endpoint="https://runpeek.app", link_base="https://runpeek.link", min_interval=0.75, token="rpk_...")
```

Env vars: `RUNPEEK_TOKEN`, `TQDMLIVE_ENDPOINT`, `TQDMLIVE_LINK_BASE`, `TQDMLIVE_MIN_INTERVAL`, `TQDMLIVE_NOTIFY`, `TQDMLIVE_DISABLE=1`.
Printed view links use the link base; it defaults to the endpoint itself when unset, so
self-hosted setups keep working. A token is picked from `setup(token=...)`, then `RUNPEEK_TOKEN`,
then the login saved by `tqdml login` (`~/.config/runpeek/config.json`).
