Skip to content

xtr_scheduler

Recurring messages on xtr-messenger.

A :class:Schedule holds :class:RecurringMessage s — a message and when to send it, on a cron expression or every so often. A scheduler transport (schedule://<name>) turns the schedule into messages as they fall due, and a messenger worker consumes it like any other transport: each message is handled there, or sent on to where routing puts it.

RecurringMessage

RecurringMessage(trigger: TriggerInterface, provider: MessageProviderInterface)

Bases: MessageProviderInterface

What to send, and when: a message provider on a trigger.

Build one with :meth:every, :meth:cron or :meth:trigger. Its :attr:id is derived from what it sends and when, so the same recurring message declared in two processes — or in one process across restarts — is recognised as the same one, which is what lets saved state resume it. A message holding a set or a frozenset is the exception: its items are written in the order the set keeps them, which can change from one process to the next. So is one holding a value nothing can write, such as a callable or a lock: it is told apart by its class alone.

Send what provider produces whenever trigger fires.

id property

id: str

Return what identifies this recurring message within a schedule.

Derived from the data it sends and how its trigger describes itself, so it is the same in every process that declares it alike.

every classmethod

every(frequency: float | str | timedelta, message: object, *, from_: datetime | str | None = None, until: datetime | str = FAR_FUTURE) -> RecurringMessage

Send message every frequency — see :class:PeriodicalTrigger for the forms.

Raises:

cron classmethod

cron(expression: str, message: object, *, timezone: tzinfo | str | None = None) -> RecurringMessage

Send message whenever expression matches, on the clock of timezone.

A hashed expression ("# # * * *") picks its values from the message's string form, so the message must define __str__.

Raises:

  • InvalidArgumentError –

    If the expression is hashed and the message has no string form of its own, or the expression is invalid.

trigger classmethod

trigger(trigger: TriggerInterface, message: object) -> RecurringMessage

Send message whenever trigger fires.

message may be a :class:MessageProviderInterface, producing the messages of each run itself; anything else is sent as it is.

with_jitter

with_jitter(max_seconds: int = 60) -> RecurringMessage

Return this recurring message, each run delayed at random by up to max_seconds.

get_provider

get_provider() -> MessageProviderInterface

Return what produces the messages of each run.

get_trigger

get_trigger() -> TriggerInterface

Return what says when the message runs.

A method rather than a property because :meth:trigger is the factory building a recurring message from one.

Schedule

Schedule(*messages: RecurringMessage)

Bases: ScheduleProviderInterface

The recurring messages one scheduler transport runs, and how it runs them.

Without a lock, every process running the schedule sends every message; give it one — :meth:lock — and only the process holding it does. Without saved state, a restarted process starts over from the time it started; give it a cache — :meth:stateful — and it picks up where the last one stopped, sending what was missed in between.

Changing the set of messages while the schedule runs is safe: the next time it is asked for messages it rebuilds its plan, and what already ran is not sent again.

Start with messages.

Raises:

recurring_messages property

recurring_messages: tuple[RecurringMessage, ...]

Return the recurring messages, in the order they were added.

event_dispatcher property

event_dispatcher: EventDispatcherInterface | None

Return the dispatcher of this schedule's own listeners, if it has any.

should_restart property

should_restart: bool

Tell whether the set of messages changed since the plan was last built.

add

add(*messages: RecurringMessage) -> Self

Add messages.

Raises:

remove

remove(message: RecurringMessage) -> Self

Remove message, if it is in the schedule.

remove_by_id

remove_by_id(id_: str) -> Self

Remove the recurring message identified by id_, if it is in the schedule.

clear

clear() -> Self

Remove every recurring message.

lock

lock(lock: LockInterface) -> Self

Run only in the process that holds lock, and keep it held between runs.

get_lock

get_lock() -> LockInterface | None

Return the lock the schedule runs under, if any.

stateful

stateful(state: CacheInterface) -> Self

Keep what already ran in state, so a restart resumes rather than starts over.

get_state

get_state() -> CacheInterface | None

Return where the schedule keeps what already ran, if anywhere.

process_only_last_missed_run

process_only_last_missed_run(only_last_missed: bool = True) -> Self

After downtime, send only the latest missed run of each message, not every one.

Called with no argument it switches that on; False switches it back off.

should_process_only_last_missed_run

should_process_only_last_missed_run() -> bool

Tell whether only the latest missed run of each message is sent after downtime.

before

before(listener: Listener, priority: int = 0) -> Self

Call listener with a :class:PreRunEvent before each of this schedule's runs.

after

after(listener: Listener, priority: int = 0) -> Self

Call listener with a :class:PostRunEvent after each of this schedule's runs.

on_failure

on_failure(listener: Listener, priority: int = 0) -> Self

Call listener with a :class:FailureEvent when one of this schedule's runs fails.

set_restart

set_restart(restart: bool) -> None

Record whether the plan must be rebuilt — the generator clears it once it has.

ScheduleProviderInterface

Bases: Protocol

Builds, or holds, a :class:~xtr_scheduler.schedule.Schedule.

An application declares a class implementing this with :func:~xtr_scheduler.decorator.as_schedule; it builds its schedule from whatever it was constructed with. A :class:Schedule is one too, and hands over itself.

get_schedule

get_schedule() -> Schedule

Return the schedule — the same one on every call.