API reference: Combinator triggers

Combinator triggers let you build schedules by composing other triggers.

  • Use A & B (AND) to require that both branches match.

  • Use A | B (OR) to allow either branch to match.

In most cases you will compose using the operators rather than instantiating the classes directly.

from schedium import Every, On

trigger1 = Every(unit="day", interval=1)
trigger2 = On(unit="hour_of_day", value=8)
trigger3 = On(unit="minute_of_hour", value=0)

trigger = trigger1 & trigger2 & trigger3
print(trigger)
# AndTrigger(
#   Every(unit='day', interval=1, offset=0),
#   On(unit='hour_of_day', value=8),
#   On(unit='minute_of_hour', value=0)
# )
class schedium.triggers.base.AndTrigger(triggers)[source][source]

Bases: BaseCombinatorTrigger

Logical AND (intersection) of multiple triggers.

An AndTrigger matches a datetime only when all its child triggers match.

In window-time terms, A & B behaves like the intersection of the next validity windows returned by A and B.

Parameters:
triggersSequence[BaseTrigger]

Child triggers to combine with AND logic.

Parameters:

triggers (Sequence[BaseTrigger])

Notes

  • Prefer composing with & over instantiating AndTrigger directly.

  • & is associative in meaning. schedium also flattens nested AND nodes, so (A & B) & C becomes a single AndTrigger.

Examples

Use & to combine existing triggers:

>>> from schedium import Every, On
>>> trigger1 = Every(unit="day", interval=1)
>>> trigger2 = On(unit="hour_of_day", value=8)
>>> trigger3 = On(unit="minute_of_hour", value=0)

trigger1 & trigger2 produces an explicit AndTrigger(trigger1, trigger2):

>>> trigger1 & trigger2
AndTrigger(Every(unit='day', interval=1, offset=0), On(unit='hour_of_day', value=8))

Chaining & is flattened into a single AndTrigger node:

>>> trigger1 & trigger2 & trigger3
AndTrigger(Every(unit='day', interval=1, offset=0), On(unit='hour_of_day', value=8), On(unit='minute_of_hour', value=0))
matches(now)[source][source]
Parameters:

now (datetime)

Return type:

bool

next_window(after, *, max_iterations=100000)[source][source]

Return the next validity window whose start is >= after.

For most constraint-style triggers, the default implementation:

  1. finds the next matching time using a forward scan at an inferred granularity, then

  2. returns a single-bucket window at that granularity.

Parameters:
afterdatetime

Lower bound (inclusive) for the returned window start.

max_iterationsint, default 100_000

Safety cap used by some triggers/combinators that scan forward.

Returns:
schedium.types.time_window.TimeWindow | None

Next validity window, or None if no future window exists.

Raises:
ValueError

If max_iterations <= 0.

schedium.exceptions.NextRunMaxIterationsReached

If a forward scan exceeds max_iterations.

Parameters:

  • after (datetime)

  • max_iterations (int)

Return type:

TimeWindow | None

class schedium.triggers.base.OrTrigger(triggers)[source][source]

Bases: BaseCombinatorTrigger

Logical OR (alternatives) of multiple triggers.

An OrTrigger matches a datetime when any child trigger matches.

For A | B, next_window() returns the earliest next window among children. If multiple children yield overlapping windows at the earliest start, those windows are merged.

Parameters:
triggersSequence[BaseTrigger]

Child triggers to combine with OR logic.

Parameters:

triggers (Sequence[BaseTrigger])

Notes

  • Prefer composing with | over instantiating OrTrigger

    directly.

  • schedium flattens nested OR nodes, so (A | B) | C becomes a single

    OrTrigger.

matches(now)[source][source]
Parameters:

now (datetime)

Return type:

bool

next_window(after, *, max_iterations=100000)[source][source]

Return the next validity window whose start is >= after.

For most constraint-style triggers, the default implementation:

  1. finds the next matching time using a forward scan at an inferred granularity, then

  2. returns a single-bucket window at that granularity.

Parameters:
afterdatetime

Lower bound (inclusive) for the returned window start.

max_iterationsint, default 100_000

Safety cap used by some triggers/combinators that scan forward.

Returns:
schedium.types.time_window.TimeWindow | None

Next validity window, or None if no future window exists.

Raises:
ValueError

If max_iterations <= 0.

schedium.exceptions.NextRunMaxIterationsReached

If a forward scan exceeds max_iterations.

Parameters:

  • after (datetime)

  • max_iterations (int)

Return type:

TimeWindow | None