matrix-planner 0.1.0

Lightweight async task scheduler

matrix-planner

Lightweight async task scheduler for Python 3.13+. Single dependency: croniter.

import asyncio
from matrix_planner import Planner, every

planner = Planner()


@planner.task(every("10s"))
def heartbeat() -> None:
    print("tick")


@planner.task(
    every("30s"),
    max_retries=3,
    backoff=lambda a: 2 ** a,   # 2, 4, 8… seconds between retries
    timeout="15s",               # cancel and log if execution exceeds 15s
)
async def fetch() -> None:
    ...


planner.run_forever()

Key features

Feature	API
Fixed-interval schedule	every("10s"), every(timedelta(minutes=5))
Cron schedule	cron("*/5 * * * *")
One-shot schedule	once(datetime(2026, 12, 31))
Decorator registration	@planner.task(every("2s"))
Manual registration	planner.add(Task(func=..., schedule=...))
Retry policy	max_retries=N, backoff=float | Callable[[int], float]
Per-execution timeout	timeout="15s" | timedelta | float
Error callback	on_error=my_handler
Sync + async functions	sync dispatched via run_in_executor
Direct task invocation	task() bypasses scheduler (useful in tests)
anchor="start"	first tick interval after creation, steady cadence
anchor="end"	interval measured from end of each execution

Schedules

# Every 10 seconds (first tick after 10s from now)
s = every("10s")

# Every 5 minutes, anchored to end of execution
s = every("5m", anchor="end")

# Cron expression (fires at 09:00 every weekday)
s = cron("0 9 * * 1-5")

# Cron with timezone
s = cron("0 9 * * *", tz=timezone.utc)

# Fire once at a specific datetime
s = once(datetime(2026, 12, 31, 23, 59))

Task parameters

Task(
    func=my_fn,
    schedule=every("10s"),
    name="my-task",              # defaults to func.__name__
    args=(1, 2),
    kwargs={"key": "val"},
    max_retries=2,
    backoff=1.0,                 # fixed delay, or lambda a: 2 ** a
    timeout="15s",               # None = no limit
    on_error=lambda e: ...,      # called instead of logging on failure
)

Requirements

Python 3.13+. Single dependency: croniter>=6.2.3.

Install: uv add matrix-planner or pip install matrix-planner.

---

Written with love by dotmatrix.