Schedule Helpers¶
Note
This is a topic targeted at advanced users. It might be hard to understand for newcomers.
These helpers can be used to evaluate schedule snippets from within an expression. That could be useful to make decisions based on the result a particular schedule snippet would provide when evaluated at a given point in time, even in the future.
Warning
Prospective evaluation of schedule snippets can only provide reliable results for such ones not including expressions that reference to the state of entities, because there is no way for Schedy to foresee state changes. Schedule snippets only having rules with plain values instead of expressions are however always safe in this regard.
ScheduleEvaluationResult
is a type defined as Tuple[Any, Set[str],
Rule]
. The first item is the value generated by the schedule, the
second a set with markers applied to the result and the third is the
Rule
object which generated the value. You’ll normally only want
the first item, the actual value.
schedule.evaluate
¶
schedule.evaluate(schedule: Schedule, when: datetime.datetime = None) -> Optional[ScheduleEvaluationResult]
Evaluates the given schedule at the given point in time. If when
is not specified, the current date and time is assumed.
When no result could be generated (e.g. because a rule evaluated to
Abort()
or all evaluated to Next()
), None
is returned instead
of a ScheduleEvaluationResult
.
Example:
result = schedule.evaluate(
schedule_snippets["snip"],
when=now+datetime.timedelta(hours=1),
)
if result:
value = result[0]
# do something with the value
schedule.next_results
¶
schedule.next_results(schedule: Schedule, start: datetime.datetime = None, end: datetime.datetime = None) -> Generator[Tuple[datetime.datetime, ScheduleEvaluationResult], None, None]
This function let’s you iterate over future results of a given schedule
snippet. Every Tuple[datetime.datetime, ScheduleEvaluationResult]
represents a point in time at which the result will change.
With the start
and end
parameters, you can limit the time range
to consider. The default is to start at the current time and continue
infinitely.
The first result generated is always that for the start
time, the
last one that for the end
time.
Example:
results = schedule.next_results(
schedule_snippets["snip"],
end=now+datetime.timedelta(hours=10),
)
for when, (value, markers, rule) in results:
# do something with the value