261 lines
10 KiB
Python
261 lines
10 KiB
Python
"""Calendar platform for TaskMate.
|
|
|
|
Exposes one read-only ``calendar.taskmate_<child>`` entity per child. Events are
|
|
derived live from existing TaskMate data — there is no second store and nothing
|
|
to keep in sync:
|
|
|
|
* chore occurrences come from the recurrence/assignment engine
|
|
(``_is_chore_scheduled_for_date`` + ``_compute_active_children``), rendered
|
|
as timed events inside the configured time-of-day window or as all-day
|
|
events when the chore is "anytime";
|
|
* away / unavailable blocks come from ``_is_child_on_vacation`` (#525),
|
|
coalesced into multi-day all-day events. On an away day the child's chores
|
|
are hidden, mirroring the rest of the integration.
|
|
|
|
Read-only for now: completing a chore from the calendar is intentionally not
|
|
supported.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import logging
|
|
from datetime import date, datetime, timedelta
|
|
|
|
from homeassistant.components.calendar import CalendarEntity, CalendarEvent
|
|
from homeassistant.config_entries import ConfigEntry
|
|
from homeassistant.core import HomeAssistant, callback
|
|
from homeassistant.helpers.entity import DeviceInfo
|
|
from homeassistant.helpers.entity_platform import AddEntitiesCallback
|
|
from homeassistant.helpers.update_coordinator import CoordinatorEntity
|
|
from homeassistant.util import dt as dt_util
|
|
|
|
from .const import DOMAIN
|
|
from .coordinator import TaskMateCoordinator
|
|
from .entity import taskmate_device_info
|
|
from .models import Child, Chore
|
|
|
|
_LOGGER = logging.getLogger(__name__)
|
|
|
|
# How far ahead the `event` (next-up) property scans for the soonest event.
|
|
_NEXT_EVENT_HORIZON_DAYS = 60
|
|
|
|
|
|
async def async_setup_entry(
|
|
hass: HomeAssistant,
|
|
entry: ConfigEntry,
|
|
async_add_entities: AddEntitiesCallback,
|
|
) -> None:
|
|
"""Set up one calendar entity per child, adding more as children are created."""
|
|
coordinator: TaskMateCoordinator = hass.data[DOMAIN][entry.entry_id]
|
|
tracked: set[str] = set()
|
|
|
|
def _new_entities() -> list[TaskMateCalendar]:
|
|
out: list[TaskMateCalendar] = []
|
|
for child in coordinator.data.get("children", []):
|
|
if child.id in tracked:
|
|
continue
|
|
tracked.add(child.id)
|
|
out.append(TaskMateCalendar(coordinator, entry, child))
|
|
return out
|
|
|
|
async_add_entities(_new_entities())
|
|
|
|
@callback
|
|
def _async_add_new() -> None:
|
|
new = _new_entities()
|
|
if new:
|
|
async_add_entities(new)
|
|
|
|
coordinator.async_add_listener(_async_add_new)
|
|
|
|
|
|
def _chore_applies_to_child(coordinator: TaskMateCoordinator, chore: Chore, child_id: str, day: date) -> bool:
|
|
"""True if ``chore`` is scheduled for ``child_id`` on ``day``.
|
|
|
|
Combines the recurrence schedule with the assignment engine so the calendar
|
|
matches who would actually see the chore — without consulting completion
|
|
state (the calendar projects the schedule, not today's done/not-done).
|
|
"""
|
|
if not getattr(chore, "enabled", True):
|
|
return False
|
|
if getattr(chore, "assignment_mode", "everyone") == "unassigned":
|
|
return False
|
|
if not coordinator._is_chore_scheduled_for_date(chore, day):
|
|
return False
|
|
active = coordinator._compute_active_children(chore, day)
|
|
if active:
|
|
return child_id in active
|
|
# Empty active set means an unrestricted "everyone" chore (no assigned_to).
|
|
return not chore.assigned_to
|
|
|
|
|
|
def _chore_description(chore: Chore) -> str:
|
|
"""Compact one-line description for a chore event."""
|
|
parts = ["TaskMate chore"]
|
|
pts = getattr(chore, "points", 0) or 0
|
|
parts.append(f"{pts} pts")
|
|
cat = getattr(chore, "time_category", "anytime") or "anytime"
|
|
if cat != "anytime":
|
|
parts.append(cat)
|
|
return " · ".join(parts)
|
|
|
|
|
|
def _as_local_dt(value: date | datetime) -> datetime:
|
|
"""Normalise a CalendarEvent start/end to an aware local datetime for sorting."""
|
|
if isinstance(value, datetime):
|
|
if value.tzinfo is None:
|
|
return value.replace(tzinfo=dt_util.DEFAULT_TIME_ZONE)
|
|
return value
|
|
return datetime(value.year, value.month, value.day, tzinfo=dt_util.DEFAULT_TIME_ZONE)
|
|
|
|
|
|
class TaskMateCalendar(CoordinatorEntity, CalendarEntity):
|
|
"""A read-only calendar of one child's chores and away periods."""
|
|
|
|
_attr_icon = "mdi:calendar-account"
|
|
|
|
def __init__(
|
|
self,
|
|
coordinator: TaskMateCoordinator,
|
|
entry: ConfigEntry,
|
|
child: Child,
|
|
) -> None:
|
|
super().__init__(coordinator)
|
|
self._entry = entry
|
|
self._child_id = child.id
|
|
self._attr_unique_id = f"{entry.entry_id}_{child.id}_calendar"
|
|
self._attr_name = f"TaskMate {child.name}"
|
|
self._events_cache: list[CalendarEvent] | None = None
|
|
self._events_key: tuple | None = None
|
|
|
|
@property
|
|
def device_info(self) -> DeviceInfo:
|
|
return taskmate_device_info(self._entry.entry_id)
|
|
|
|
@property
|
|
def _child(self) -> Child | None:
|
|
return self.coordinator.storage.get_child(self._child_id)
|
|
|
|
@property
|
|
def available(self) -> bool:
|
|
return self._child is not None and super().available
|
|
|
|
@property
|
|
def event(self) -> CalendarEvent | None:
|
|
"""The current or next upcoming event (HA shows this as the entity state).
|
|
|
|
Home Assistant reads this twice per state write (once for the state,
|
|
once for the state attributes), and writes on every coordinator
|
|
refresh — so the horizon projection is memoized against the same key
|
|
the sensors use: the data snapshot plus the external-entity version
|
|
that covers availability/visibility flips (#823). Only the cheap
|
|
"which one is next" filter re-runs.
|
|
"""
|
|
child = self._child
|
|
if not child:
|
|
return None
|
|
now = dt_util.now()
|
|
today = now.date()
|
|
events = self._cached_horizon(child, today)
|
|
upcoming = [e for e in events if _as_local_dt(e.end) > now]
|
|
upcoming.sort(key=lambda e: _as_local_dt(e.start))
|
|
return upcoming[0] if upcoming else None
|
|
|
|
def _cached_horizon(self, child: Child, today: date) -> list[CalendarEvent]:
|
|
"""The next-up horizon for ``today``, rebuilt only when inputs change."""
|
|
key = (
|
|
today,
|
|
id(self.coordinator.data),
|
|
getattr(self.coordinator, "external_state_version", 0),
|
|
)
|
|
cached = getattr(self, "_events_cache", None)
|
|
if cached is not None and getattr(self, "_events_key", None) == key:
|
|
return cached
|
|
events = self._build_events(child, today, today + timedelta(days=_NEXT_EVENT_HORIZON_DAYS))
|
|
self._events_cache = events
|
|
self._events_key = key
|
|
return events
|
|
|
|
async def async_get_events(
|
|
self, hass: HomeAssistant, start_date: datetime, end_date: datetime
|
|
) -> list[CalendarEvent]:
|
|
"""Return all events overlapping the requested range."""
|
|
child = self._child
|
|
if not child:
|
|
return []
|
|
return self._build_events(child, start_date.date(), end_date.date())
|
|
|
|
def _build_events(self, child: Child, start_day: date, end_day: date) -> list[CalendarEvent]:
|
|
with self.coordinator.availability_build_scope():
|
|
return self._build_events_locked(child, start_day, end_day)
|
|
|
|
def _build_events_locked(self, child: Child, start_day: date, end_day: date) -> list[CalendarEvent]:
|
|
"""Project the range. Must run inside ``availability_build_scope`` so the
|
|
rotation pool and balanced-mode grouping resolve from the scope cache
|
|
instead of rebuilding every stored chore/child per (chore, day) (#823).
|
|
"""
|
|
coord = self.coordinator
|
|
events: list[CalendarEvent] = []
|
|
|
|
# ---- away blocks: coalesce consecutive away days into one all-day event ----
|
|
run_start: date | None = None
|
|
run_label: str | None = None
|
|
day = start_day
|
|
while day <= end_day:
|
|
if coord._is_child_on_vacation(child, day):
|
|
if run_start is None:
|
|
period = coord.active_vacation(day)
|
|
run_label = (period or {}).get("name") or ""
|
|
run_start = day
|
|
elif run_start is not None:
|
|
events.append(_away_event(run_start, day, run_label))
|
|
run_start = None
|
|
day += timedelta(days=1)
|
|
if run_start is not None:
|
|
events.append(_away_event(run_start, end_day + timedelta(days=1), run_label))
|
|
|
|
# ---- chore occurrences (skipped on away days) ----
|
|
chores = coord._cached_chores()
|
|
tz = dt_util.DEFAULT_TIME_ZONE
|
|
day = start_day
|
|
while day <= end_day:
|
|
if not coord._is_child_on_vacation(child, day):
|
|
for chore in chores:
|
|
if not _chore_applies_to_child(coord, chore, child.id, day):
|
|
continue
|
|
window = coord._time_category_window(getattr(chore, "time_category", "anytime"), day)
|
|
desc = _chore_description(chore)
|
|
if window is None:
|
|
events.append(
|
|
CalendarEvent(
|
|
start=day,
|
|
end=day + timedelta(days=1),
|
|
summary=chore.name,
|
|
description=desc,
|
|
)
|
|
)
|
|
else:
|
|
start_dt, end_dt = window
|
|
events.append(
|
|
CalendarEvent(
|
|
start=start_dt.replace(tzinfo=tz),
|
|
end=end_dt.replace(tzinfo=tz),
|
|
summary=chore.name,
|
|
description=desc,
|
|
)
|
|
)
|
|
day += timedelta(days=1)
|
|
|
|
return events
|
|
|
|
|
|
def _away_event(start_day: date, end_day_exclusive: date, label: str | None) -> CalendarEvent:
|
|
"""Build a coalesced all-day 'away' event over [start, end)."""
|
|
summary = f"Away — {label}" if label else "Away"
|
|
return CalendarEvent(
|
|
start=start_day,
|
|
end=end_day_exclusive,
|
|
summary=summary,
|
|
description="Unavailable — streak paused and chores hidden.",
|
|
)
|