astrae

Guides

Background loops and scheduled work

@loop(seconds=...) marks a coroutine. The decorator alone does not start anything. Register it with client.add_loop(...) or a cog that does.

from astrae import Client, loop

bot = Client()

@loop(minutes=1)
async def refresh_status() -> None:
    print("refreshing status")

@loop

Name Purpose
seconds / minutes / hours Interval. Total must be positive.
client.add_loop Actually schedule it.
First run Waits one interval.
Raised error Logged. The loop keeps going.
Overrun Next iteration waits. No overlap.
Lifecycle Starts and cancels with the client.

Scheduler

Name Purpose
Scheduler.cron(expr) Five fields: minute, hour, day of month, month, weekday. *, int, or comma-separated ints.
Unsupported Ranges, steps, named months/days.
Timezone Uses the datetime's timezone. Watch DST.
scheduler.start() Run registered cron callbacks. Not started by @loop.
scheduler.stop() Cancel the runner.
Scheduler.lock(name, ttl=30) Ownership token, or None. Without Redis this is process-local.
Scheduler.hold(name, ttl=30) Acquire, renew about every third of TTL, release.
Cron claims Minute-scoped lock names so two workers do not run the same named job in the same minute.

This is best-effort. A paused process, partition, or expired lease can overlap work. Make jobs idempotent.