API reference: Tick trigger

class schedium.triggers.sugar.tick.Tick(granularity)[source][source]

Bases: BaseTrigger

A trigger that always matches, but defines the dedup bucket.

Tick(…) doesn’t control when; it controls how often at most it can run (once per bucket) when other parts of the trigger tree make it match.

Even though both Every(unit=..., interval=1) and Tick(...) match for all now, they differ in their notion of “next time”. For example, for after=10:00:30:

  • Tick("minute").next_window(after) starts at 10:00:30.

  • Every("minute", interval=1).next_window(after) starts at the next

    epoch-aligned boundary (typically 10:01:00).

Why this is useful:

  • When composing constraints with AND, using Every(unit=”week”, interval=1)

    can force alignment to week boundaries (e.g. Monday 00:00), which makes intersection search for schedules like “Monday at 09:30” less direct.

  • Tick(Granularity.WEEK) keeps the schedule driven by the constraints

    (weekday/time), while still guaranteeing the job won’t run more than once per WEEK bucket.

Tick is intended mainly for “sugar” helpers (like Weekly(…)) and advanced compositions.

Parameters:
granularityschedium.schemas.granularity.Granularity | schedium.schemas.granularity.GranularityUnit

Deduplication bucket size. If given as a string, it is converted via UNIT_TO_GRANULARITY_MAP.

Parameters:

granularity (Granularity | GranularityUnit)

required_granularity()[source][source]
Return type:

Granularity

fallback_granularity()[source][source]
Return type:

Granularity

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