Schedules
Returns the schedules configured for this project. A schedule defines
occupancy rules (when it is active) and the scene modes applied when it
is active or inactive. Pass schedule_id to fetch a single
schedule.
schedules(schedule_id=None)| Argument | Default | Description |
|---|---|---|
schedule_id |
None |
Optional schedule ID string to fetch a single schedule |
Returns
ScheduleList with the following attribute:
| Attribute | Type | Description |
|---|---|---|
schedules |
list[Schedule] |
Schedules in the response |
Each Schedule has:
| Attribute | Type | Description |
|---|---|---|
id |
str |
Schedule ID |
name |
str |
Schedule name |
schedule |
str |
Raw schedule string,
e.g. "weekdays 8:00-17:00, sat 9:00-12:00" |
rules |
list[ScheduleRule] |
Decoded occupancy rules |
active_mode_ids |
list[str] |
Scene mode IDs applied when active |
inactive_mode_ids |
list[str] |
Scene mode IDs applied when inactive |
Each ScheduleRule has:
| Attribute | Type | Description |
|---|---|---|
start_day |
int |
First weekday in the range (0=Mon .. 6=Sun) |
end_day |
int |
Last weekday in the range (may wrap, e.g. fri..mon) |
start |
datetime.time |
Inclusive start time of day |
end |
datetime.time |
Exclusive end time of day |
days |
frozenset[int] |
Weekday ordinals covered (derived) |
Evaluating active state
schedule.active(current_time=None, tolerance=None) # -> boolReturns True if current_time falls within
any of the schedule’s rules. current_time is a
datetime evaluated in its own timezone, so pass a
project-local datetime; it defaults to
datetime.now() (the host’s local time). A schedule is
active when the current time is in any rule’s window (start inclusive,
end exclusive).
If tolerance (a datetime.timedelta) is
given, each rule’s window is widened directionally: the start is shifted
earlier by tolerance and the end is left unchanged.
The schedule string is decoded automatically; the grammar is a
comma-separated list of "<days> hh:mm-hh:mm" rules
where <days> is weekdays, a single day
(mon..sun), or a contiguous range
(mon-fri).
Example
import datetime
# All schedules
for sched in client.schedules():
print(sched.id, sched.name, "->", sched.schedule)
# Is a schedule active right now? current_time defaults to datetime.now()
sched = client.schedules(schedule_id="sch.1").schedule("sch.1")
print(sched.active())
# ...or evaluate against a specific project-local time
when = datetime.datetime(2026, 6, 24, 10, 0) # a Wednesday, 10:00
print(sched.active(when)) # True
# With 30 minutes of tolerance (start shifted earlier; end unchanged)
tol = datetime.timedelta(minutes=30)
print(sched.active(when, tolerance=tol))
# The scene modes to apply based on state, resolved to SceneMode objects
scenes = client.scenes()
mode_ids = sched.active_mode_ids if sched.active() else sched.inactive_mode_ids
for mid in mode_ids:
mode = scenes.mode(mid) # resolve "sn.1.2" -> SceneMode
print(mode.name, dict(mode.vals))