https://github.com/nandyalu/quiv
quiv is a lightweight background task scheduler for Python applications.
https://github.com/nandyalu/quiv
async background-jobs python scheduler stoppable tasks
Last synced: 3 months ago
JSON representation
quiv is a lightweight background task scheduler for Python applications.
- Host: GitHub
- URL: https://github.com/nandyalu/quiv
- Owner: nandyalu
- License: mit
- Created: 2026-03-06T05:14:25.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-03-08T07:48:22.000Z (4 months ago)
- Last Synced: 2026-03-08T12:17:32.448Z (4 months ago)
- Topics: async, background-jobs, python, scheduler, stoppable, tasks
- Language: Python
- Homepage: https://nandyalu.github.io/quiv/
- Size: 246 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
#
`quiv` is a lightweight background task scheduler for Python applications.
It is designed to work especially well with FastAPI apps that need predictable,
in-process background task orchestration.
Supports Python 3.10 through 3.14.
It provides:
- threadpool-backed execution
- support for sync and async task handlers
- cooperative cancellation (`_stop_event`)
- progress callbacks routed to your main async loop (`_progress_hook`)
- persistent task/job state via SQLModel + SQLite
## When to use quiv
Use `quiv` when you need in-process background scheduling for app-level jobs,
for example:
- polling APIs every N seconds
- periodic cleanup tasks
- one-shot delayed jobs
- progress-aware long-running workloads
## Install
```bash
uv add quiv
# or
pip install quiv
```
## Quick start
```python
from contextlib import asynccontextmanager
from fastapi import FastAPI
from quiv import Quiv
scheduler = Quiv(timezone="UTC")
def ping(_progress_hook=None):
for i in range(30):
# do some work
if _progress_hook:
_progress_hook(message="ping", progress=i, total=30)
async def on_progress(**payload):
# Replace with websocket broadcast, logging, metrics, etc.
print("progress", payload)
@asynccontextmanager
async def lifespan(app: FastAPI):
# Startup
scheduler.start()
yield
# Shutdown
scheduler.shutdown()
app = FastAPI(lifespan=lifespan)
@app.post("/start-heartbeat")
def start_heartbeat():
scheduler.add_task(
task_name="heartbeat",
func=ping,
interval=30,
progress_callback=on_progress,
)
return {"message": "Heartbeat started successfully!"}
```
## Documentation
Full documentation is available at
**[nandyalu.github.io/quiv](https://nandyalu.github.io/quiv/)**.
- [Getting Started](https://nandyalu.github.io/quiv/getting-started/)
- [Bigger Applications](https://nandyalu.github.io/quiv/bigger-applications/)
- [API Reference](https://nandyalu.github.io/quiv/api/)
- [Architecture](https://nandyalu.github.io/quiv/architecture/)
- [Progress Callbacks](https://nandyalu.github.io/quiv/progress-callbacks/)
- [Cancellation](https://nandyalu.github.io/quiv/cancellation/)
- [Exceptions](https://nandyalu.github.io/quiv/exceptions/)
## License
MIT