kuu
a native distributed task queue for python
uv add kuu
# extras: dashboard, nats, postgres, prometheus, redis
quick start
# myapp/app.py
from kuu import Kuu
from kuu.brokers.redis import RedisBroker
from kuu.results.redis import RedisResults
app = Kuu(broker=RedisBroker(url=...), results=RedisResults(url=...))
# myapp/tasks.py
from typing import TypedDict
from datetime import timedelta
from .app import app
class ChargeResult(TypedDict):
ok: bool
charged: int
@app.task
async def charge(user_id: int, amount_cents: int) -> ChargeResult:
return {"ok": True, "charged": amount_cents}
@app.sched(every(hours=4, starting=time(hours=1, minutes=30))) # 1:30, 5:30, 9:30...
async def refresh_balance() -> None: ...
# myapp/main.py
from .tasks import charge
async def run() -> None:
# type checker infers TaskHandle[ChargeResult]
# args/kwargs of the task remain typed
handle = await charge.q(user_id=1, amount_cents=500)
# type checker infers ChargeResult
result = await handle.result(timeout=30)
# reads ./kuunfig.toml or [tool.kuu] in ./pyproject.toml
# starts control plane with all presets spawned
uv run kuu start
# singular preset with dashboard / remote uplink
uv run kuu start --preset ...
what's inside
- brokers: Redis Streams, NATS JetStream, in-memory (for tests)
- scheduler: interval jobs (
@app.every) and composable cron-like schedules (@app.sched) - middleware: logging, retry with exponential backoff + jitter, timeout, plus custom hooks
- events: pub/sub signals for task lifecycle (
task_enqueued..task_dead) - serialization: JSON (msgspec), Msgpack, Pickle, with extensible type coercion via
marshal - persistence: SQLite (zero-config) and PostgreSQL backends for run/log history
- dashboard: Starlette+HTMX web UI with live worker/queue stats and task management
- prometheus: multiprocess metrics with worker-side emitter and client-side middleware
- hot reload: watch filesystem changes, restart worker pool on settled batches
config
put the block below into kuunfig.toml, or under [tool.kuu] in your pyproject.toml
[default] holds base values; each [presets.<name>] overrides only the fields you set.
unset fields fall back to [default]. a flat config (no [default] wrapper) still works
[default]
queues = [] # consume from; empty = auto-discover from registry
processes = 1 # worker subprocesses to spawn
concurrency = 64 # max concurrent tasks per worker
prefetch = 16 # batch size; defaults to max(1, concurrency // 4)
shutdown_timeout = 30.0 # seconds to wait for in-flight tasks on stop
[default.metrics]
enable = false
host = "0.0.0.0"
port = 9191
[default.dashboard]
enable = false
host = "0.0.0.0"
port = 8181
path = "/dashboard"
scheduler.enable = false # run scheduler loop in-process; jobs declared via app.every / app.sched
[default.watch]
enable = false # reload workers on filesystem changes
root = "." # path to watch
respect_gitignore = true # skip files matched by .gitignore
exclude = [".git/**"] # extra globs to exclude
reload_delay = 0.25
reload_debounce = 0.5
[default.persistence]
enable = true # store run/log history
dsn = "sqlite:///./kuu.db" # sqlite (default) or postgres://...;
# also can be provided via KUU_PERSISTENCE_DSN env var
schema = "" # postgres schema; empty = default
runs_table = "kuu_runs" # Attempt rows
logical_runs_table = "kuu_logical_runs" # parent Runs
logs_table = "kuu_run_logs"
keep_days = 7 # auto-purge runs older than this
max_runs = 100_000 # hard cap on stored runs
log_level = "INFO"
capture_args = false # sensitive inputs are opt-in
capture_headers = false
capture_result = false
attempt_observation_bytes = 10_485_760 # per-Attempt budget; overflow becomes a gap
[presets.prod]
processes = 8
concurrency = 256
[presets.dev]
processes = 1
concurrency = 16
any setting can be overridden from the CLI with -o dotted.path=value
values are parsed as JSON when possible (true, 42, ["a","b"]), otherwise kept as strings
contribution
well if you insist... (issues / PRs welcome)
#clankersgoaway
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
kuu-0.4.1.tar.gz
(122.5 kB
view details)
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
kuu-0.4.1-py3-none-any.whl
(170.8 kB
view details)
File details
Details for the file kuu-0.4.1.tar.gz.
File metadata
- Download URL: kuu-0.4.1.tar.gz
- Upload date:
- Size: 122.5 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
uv/0.12.1 {"installer":{"name":"uv","version":"0.12.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
32caf93235159ac6818f04a0de79c951f9e0fc8f24ac7471f9ea12abf879bd0b
|
|
| MD5 |
c0d860acf1e08b479f176dbe24944dd9
|
|
| BLAKE2b-256 |
3eeae7aff23776104d3eb42fb2e0e02f68b73758890519d7c1bfbbc22aab15fe
|
File details
Details for the file kuu-0.4.1-py3-none-any.whl.
File metadata
- Download URL: kuu-0.4.1-py3-none-any.whl
- Upload date:
- Size: 170.8 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
uv/0.12.1 {"installer":{"name":"uv","version":"0.12.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
16117065749f3be45faf57e9275562caf018f9ab9dd0082176184a378fa3575e
|
|
| MD5 |
821ba96ea1137821c1eff454d0a7f35f
|
|
| BLAKE2b-256 |
d2bfb2aaec57d38921ddee4ac3ef5b3bdcae2f8c5a51a423b0279871656b938e
|
