API reference: Between trigger

class schedium.triggers.between.Between(unit, start, end)[source][source]

Bases: BaseTrigger

Constraint trigger that matches when a datetime field is within a range.

Between is a constraint: it filters time, but does not define a cadence.

Parameters:
unitstr

Which datetime component to examine.

Supported values:

  • "year"

  • "month_of_year" (1..12)

  • "week_of_year" (ISO week number via datetime.isocalendar().week)

  • "day_of_week" (1..7 where 1=Mon, 7=Sun)

  • "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)

startint

Inclusive lower bound for the selected unit.

endint

Inclusive upper bound for the selected unit.

Parameters:

  • unit (Literal['year', 'month_of_year', 'week_of_year', 'day_of_week', 'day_of_month', 'hour_of_day', 'minute_of_hour', 'second_of_minute', 'millisecond_of_second'])

  • start (int)

  • end (int)

Notes

Inclusivity

Ranges are inclusive: a datetime matches when start <= value <= end.

Validation

If start > end a ValueError is raised.

Day-of-week numbering

unit="day_of_week" uses ISO / cron-style numbering (1..7) via datetime.datetime.isoweekday(). Values outside 1..7 raise ValueError.

Next-run computation

Most units fall back to a generic forward scan in next_window() using an inferred granularity.

unit="year" overrides next_window() to return:

  • None when after.year > end

  • a window starting at after when already inside the range

  • a window starting at datetime(start, 1, 1, tzinfo=after.tzinfo) otherwise

Examples

Working hours: any 10 minute between 09:00 and 17:00

>>> from schedium import Between, Every
>>> trigger = Every(unit="minute", interval=10) & Between(unit="hour_of_day", start=9, end=17)

First business week of the month (Mon..Fri)

>>> from schedium import Between, Tick
>>> trigger = (
...     Tick(granularity="day")
...     & Between(unit="day_of_month", start=1, end=7)
...     & Between(unit="day_of_week", start=1, end=5)
... )
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