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