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

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.