API reference: On trigger

class schedium.triggers.on.On(unit, value=None)[source][source]

Bases: BaseTrigger

Constraint trigger that matches when a datetime falls on a specific value.

On is a constraint: it filters time, but does not define a cadence by itself.

Parameters:
unit{year, month_of_year, week_of_year, day_of_week, weekdays, weekend_days,

day_of_month, hour_of_day, minute_of_hour, second_of_minute, millisecond_of_second}

Which part of the datetime to check.

Supported values are:

  • "year"

  • "month_of_year" (1..12)

  • "week_of_year" (ISO week number, 1..53)

  • "weekdays" (Mon..Fri; value is ignored)

  • "weekend_days" (Sat..Sun; value is ignored)

  • "day_of_week" (iso-style, 1..7 where 1=Mon)

  • "day_of_month" (1..31)

  • "hour_of_day" (0..23)

  • "minute_of_hour" (0..59)

  • "second_of_minute" (0..59)

  • "millisecond_of_second" (0..999)

valueint, default None

The target value to match for the selected unit.

For unit in {"weekdays", "weekend_days"} the value is ignored since the unit already fully defines the constraint.

Parameters:

  • unit (OnUnit)

  • value (int | None)

Notes

Scheduling notes

On may match for an extended interval (for example, an entire hour or day), so jobs should rely on deduplication to avoid repeated runs.

Day-of-week semantics

On uses iso-style day-of-week numbering (1..7) via datetime.datetime.isoweekday().

Timezones

All comparisons are performed against the provided datetime object. If you’re using timezone-aware datetimes, ensure you pass consistent tz-aware values to the scheduler.

Examples

Run every weekday at 08:00

>>> from schedium import Every, On
>>> trigger = (
...     Every(unit="day", interval=1)
...     & On(unit="weekdays")
...     & On(unit="hour_of_day", value=8)
...     & On(unit="minute_of_hour", value=0)
... )

Run on the 1st of each month at midnight

>>> from schedium import Every, On
>>> trigger = (
...     Every(unit="day", interval=1)
...     & On(unit="day_of_month", value=1)
...     & On(unit="hour_of_day", value=0)
...     & On(unit="minute_of_hour", value=0)
... )
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 | None