API reference: Every trigger

class schedium.triggers.every.Every(unit, interval, offset=0, auto_offset=False)

Bases: BaseTrigger

Trigger that matches on a fixed cadence.

Every defines when time advances for a schedule. When it matches, the scheduler may run the job (subject to deduplication and any additional constraints).

Conceptually, Every divides time into buckets of a given granularity (minute/hour/day/etc.) starting at the Unix epoch, and matches when the bucket number satisfies:

unit_since_epoch % interval == offset

unit_since_epoch is the number of complete unit buckets since the Unix epoch. For example, for unit=”minute”, it counts the number of complete minutes since 1970-01-01T00:00:00Z.

Parameters:

unitschedium.schemas.granularity.GranularityUnit

The cadence unit. One of "year", "month", "week", "day", "hour", "minute", "second", "millisecond".

intervalint

The period in number of unit buckets. Must be > 0.

Example: interval=5 with unit="minute" means every 5 minutes on epoch-aligned boundaries.

offsetint, default 0

Phase offset within the cycle. Must satisfy 0 <= offset < interval.

Example: with Every(unit="minute", interval=5, offset=2), the trigger matches for minute buckets numbered 2, 7, 12, … since epoch.

auto_offsetbool, default False

If True, ignores the provided offset and chooses an offset based on the current time (UTC) such that the trigger matches immediately and then repeats every interval buckets.

This is useful when you want to start a job “now” but still maintain a stable cadence afterward.

Parameters:

• unit (GranularityUnit)

• interval (int)

• offset (int)

• auto_offset (bool)

Notes

Alignment (important)

Every is epoch-aligned, not “relative to job creation time” when auto_offset is False. For example, Every(unit="hour", interval=1) matches exactly on the hour. If you need a “run once sometime after X” semantics, consider AtDateTime.

Deduplication

schedium deduplicates at the job level using a trigger event token. For Every, the effective token bucket is the trigger’s granularity (minute/hour/day…). Calling Scheduler.run_pending repeatedly within the same bucket will run the job only once.

interval == 1

When interval=1, Every matches every bucket. The project logs a warning suggesting Tick instead, which is often clearer for “always match, but dedup by granularity”.

Every vs Tick

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).

Timezones

since_epoch(…) uses the provided datetime. If you use timezone- aware datetimes, keep them consistent across calls.

Examples

Every 5 minutes

>>> from schedium import Every
>>> Every(unit="minute", interval=5)
Every(unit='minute', interval=5, offset=0)

Every 5 minutes, but shifted by 2 minutes

>>> from schedium import Every
>>> Every(unit="minute", interval=5, offset=2)
Every(unit='minute', interval=5, offset=2)

Every 2 hours minute 30 (cadence + constraints)

>>> from schedium import Every, On
>>> trigger = Every(unit="hour", interval=2) & On(unit="minute_of_hour", value=30)

Auto-offset: run immediately, then every 10 minutes

>>> from schedium import Every
>>> trigger = Every(unit="minute", interval=10, auto_offset=True)

required_granularity()

Return type:

Granularity

fallback_granularity()

Return type:

Granularity

matches(now)

Parameters:

now (datetime)

Return type:

bool

next_window(after, *, max_iterations=100000)

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