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 ¶
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
¶
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:
-
InvalidArgumentError–If the frequency or a date cannot be used.
cron
classmethod
¶
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
¶
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 ¶
Return this recurring message, each run delayed at random by up to max_seconds.
get_provider ¶
Return what produces the messages of each run.
get_trigger ¶
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 ¶
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:
-
SchedulerLogicError–If two of them are the same recurring message.
recurring_messages
property
¶
Return the recurring messages, in the order they were added.
event_dispatcher
property
¶
Return the dispatcher of this schedule's own listeners, if it has any.
should_restart
property
¶
Tell whether the set of messages changed since the plan was last built.
add ¶
remove_by_id ¶
Remove the recurring message identified by id_, if it is in the schedule.
lock ¶
Run only in the process that holds lock, and keep it held between runs.
stateful ¶
Keep what already ran in state, so a restart resumes rather than starts over.
get_state ¶
Return where the schedule keeps what already ran, if anywhere.
process_only_last_missed_run ¶
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 ¶
Tell whether only the latest missed run of each message is sent after downtime.
before ¶
Call listener with a :class:PreRunEvent before each of this schedule's runs.
after ¶
Call listener with a :class:PostRunEvent after each of this schedule's runs.
on_failure ¶
Call listener with a :class:FailureEvent when one of this schedule's runs fails.
set_restart ¶
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.