Task

grelmicro.task

Task.

TaskError

Bases: GrelmicroError

Base grelmicro Task error.

TaskManager

TaskManager(
    *,
    auto_start: bool = True,
    tasks: list[Task] | None = None,
)

Bases: TaskRouter

Task Manager.

TaskManager class, the main entrypoint to manage scheduled tasks.

Initialize the task manager.

PARAMETER	DESCRIPTION
`auto_start`	Automatically start all tasks. TYPE: `bool` DEFAULT: `True`
`tasks`	A list of tasks to be started. TYPE: `list[Task] \| None` DEFAULT: `None`

start `async`

start() -> None

Start all tasks manually.

TaskRouter

TaskRouter(*, tasks: list[Task] | None = None)

Task Router.

TaskRouter class, used to group task schedules, for example to structure an app in multiple files. It would then be included in the TaskManager, or in another TaskRouter.

Initialize the task router.

PARAMETER	DESCRIPTION
`tasks`	A list of tasks to be scheduled. TYPE: `list[Task] \| None` DEFAULT: `None`

tasks `property`

tasks: list[Task]

List of scheduled tasks.

add_task

add_task(task: Task) -> None

Add a task to the scheduler.

interval

interval(
    *,
    seconds: float,
    name: str | None = None,
    max_lock_seconds: float | None = None,
    min_lock_seconds: float | None = None,
    leader: LeaderElection | None = None,
    backend: SyncBackend | None = None,
    worker: str | UUID | None = None,
    sync: SyncPrimitive | None = None,
) -> Callable[
    [Callable[..., Any | Awaitable[Any]]],
    Callable[..., Any | Awaitable[Any]],
]

Decorate function to add it as an interval task.

Supports three modes:

Local: No lock params, runs on every worker, every interval.
Distributed lock: Set max_lock_seconds to run at most once per interval across all workers.
Leader-gated: Set leader to restrict execution to the leader worker (lock is implied).

PARAMETER	DESCRIPTION
`seconds`	The duration in seconds between each task run. Accuracy is not guaranteed and may vary with system load. Consider the execution time of the task when setting the interval. TYPE: `float`
`name`	The name of the task. If None, a name will be generated automatically from the function. Also used as the lock name when distributed locking is enabled. TYPE: `str \| None` DEFAULT: `None`
`max_lock_seconds`	The maximum duration in seconds to hold the lock (crash protection). Setting this enables distributed locking: the task runs at most once per interval across all workers. Must be >= `seconds`. When `leader` is set without this, defaults to `seconds * 5`. TYPE: `float \| None` DEFAULT: `None`
`min_lock_seconds`	The minimum duration in seconds to hold the lock after task completion. Prevents re-execution on other nodes before this duration has elapsed. Defaults to `seconds` when distributed locking is enabled. Requires `max_lock_seconds` or `leader` to be set. TYPE: `float \| None` DEFAULT: `None`
`leader`	Optional leader election for leader gating. When provided, the task only executes on the leader worker. Implies distributed locking (lock is automatically configured). TYPE: `LeaderElection \| None` DEFAULT: `None`
`backend`	The distributed lock backend. By default, uses the lock backend registry. Only used when distributed locking is enabled. TYPE: `SyncBackend \| None` DEFAULT: `None`
`worker`	The worker identity. By default, a UUIDv1 will be generated. Only used when distributed locking is enabled. TYPE: `str \| UUID \| None` DEFAULT: `None`
`sync`	The synchronization primitive to use for the task. Use a `Lock` to synchronize access to a shared resource. .. deprecated:: 0.6.0 Using `sync` with `TaskLock` or `LeaderElection` is deprecated and will be removed in 0.7.0. Use `max_lock_seconds` and `leader` parameters instead. If None, no synchronization is used and the task will run on all workers. TYPE: `SyncPrimitive \| None` DEFAULT: `None`

RAISES	DESCRIPTION
`FunctionTypeError`	If the task name generation fails.
`ValueError`	If seconds is less than or equal to 0.
`ValueError`	If deprecated sync (non-Lock) is combined with max_lock_seconds, min_lock_seconds, or leader.
`ValueError`	If max_lock_seconds is less than seconds.
`ValueError`	If min_lock_seconds is set without max_lock_seconds or leader.
`ValueError`	If min_lock_seconds is greater than max_lock_seconds.

scheduled

scheduled(
    *,
    seconds: float,
    name: str | None = None,
    max_lock_seconds: float | None = None,
    leader: LeaderElection | None = None,
    backend: SyncBackend | None = None,
    worker: str | UUID | None = None,
) -> Callable[
    [Callable[..., Any | Awaitable[Any]]],
    Callable[..., Any | Awaitable[Any]],
]

Decorate function to add it as a distributed scheduled task.

.. deprecated:: 0.6.0 Use interval() with max_lock_seconds instead. Will be removed in 0.7.0.

The task runs at most once per interval across all workers, using a built-in TaskLock. Can optionally be gated behind a leader election.

PARAMETER	DESCRIPTION
`seconds`	The duration in seconds between each scheduling attempt. Each worker retries every N seconds, but only one worker executes per interval thanks to the built-in lock. Also used as the `min_lock_seconds` value. TYPE: `float`
`name`	The name of the task. If None, a name will be generated automatically from the function. Also used as the TaskLock name. TYPE: `str \| None` DEFAULT: `None`
`max_lock_seconds`	The maximum duration in seconds to hold the lock (crash protection). Defaults to `seconds * 5`. Must be >= `seconds`. TYPE: `float \| None` DEFAULT: `None`
`leader`	Optional leader election for leader gating. When provided, the task only executes on the leader worker. TYPE: `LeaderElection \| None` DEFAULT: `None`
`backend`	The distributed lock backend. By default, uses the lock backend registry. TYPE: `SyncBackend \| None` DEFAULT: `None`
`worker`	The worker identity. By default, a UUIDv1 will be generated. TYPE: `str \| UUID \| None` DEFAULT: `None`

RAISES	DESCRIPTION
`FunctionTypeError`	If the task name generation fails.
`ValueError`	If seconds is less than or equal to 0.
`ValueError`	If max_lock_seconds is less than seconds.

include_router

include_router(router: TaskRouter) -> None

Include another router in this router.

started

started() -> bool

Check if the task manager has started.

do_mark_as_started

do_mark_as_started() -> None

Mark the task manager as started.

Do not call this method directly. It is called by the task manager when the task manager is started.