Move panel payload shaping into core; pin the snapshot clock
PR #148 review (CHANGES_REQUIRED) follow-up: - Move the panel payload dict shaper (_instance_payload) from the HA-importing sensor.py into core/snapshot.py as instance_payload, and have sensor.py import it from core. The API panel route now shares ONE shaping implementation with the HA sensor layer (done -> completed, on_time passthrough, missed omitted unless include_missed). - build_snapshot takes the HA-local now explicitly instead of reading datetime.now(time_zone) internally, so date and time come from a single clock read and the overdue check is pinned in tests. The coordinator passes the same now it already resolved; time_zone is dropped (now is timezone-aware). - Strengthen tests/test_core_snapshot.py with explicit literal expected values instead of self-equality: an AWAY child (2-week absent-week schedule + a presence override => next_present), a due-timed quest exercised as overdue under a pinned 12:00 now, a completed quest (done -> completed, on_time True), cycle_day == 2, and a constructed missed view proving omission from the panel payload and retention in the admin payload. - Docstring cleanups: state plainly that settings is currently unused (no 'wired' implication); correct the coordinator docstring (settings are passed in, not resolved off the entry); trim the coordinator __all__ to what other modules actually import. - Derive the seed/materialize date from coordinator._local_now() so the seed date and snapshot date cannot diverge near midnight; drop the redundant bo/ghost/list_children leftovers from the prior seed.
This commit is contained in:
@@ -14,10 +14,11 @@ layers.
|
||||
The snapshot assembly itself lives in the Home-Assistant-free
|
||||
:mod:`custom_components.nestquest.core.snapshot` module
|
||||
(:func:`~core.snapshot.build_snapshot`); this coordinator is now a thin
|
||||
HA wrapper that resolves the local timezone and settings off the config
|
||||
entry and delegates to that builder. The API service's panel snapshot
|
||||
route shares the same builder, so both consumers render ONE snapshot
|
||||
shape.
|
||||
HA wrapper that resolves the local timezone and reads the settings handed
|
||||
into its constructor, then delegates to that builder, passing the SAME
|
||||
HA-local ``now`` it resolved in one clock read. The API service's panel
|
||||
snapshot route shares the same builder, so both consumers render ONE
|
||||
snapshot shape.
|
||||
|
||||
Presence is resolved through the SAME engine the materializer uses
|
||||
(:class:`~.presence.PresenceEngine`): schedules and overrides are read
|
||||
@@ -53,7 +54,6 @@ from .core.snapshot import (
|
||||
ChildDaySnapshot,
|
||||
NestQuestSnapshot,
|
||||
QuestInstanceView,
|
||||
_cycle_day,
|
||||
build_snapshot,
|
||||
)
|
||||
|
||||
@@ -62,8 +62,6 @@ __all__ = [
|
||||
"NestQuestCoordinator",
|
||||
"NestQuestSnapshot",
|
||||
"QuestInstanceView",
|
||||
"_cycle_day",
|
||||
"build_snapshot",
|
||||
]
|
||||
|
||||
|
||||
@@ -120,7 +118,6 @@ class NestQuestCoordinator(DataUpdateCoordinator):
|
||||
async def _async_update_data(self) -> NestQuestSnapshot:
|
||||
now = self._local_now()
|
||||
today = now.date()
|
||||
time_zone = ZoneInfo(self.hass.config.time_zone)
|
||||
return await build_snapshot(
|
||||
self.database, self.settings, today, time_zone
|
||||
self.database, self.settings, today, now
|
||||
)
|
||||
|
||||
@@ -13,24 +13,27 @@ the assembly itself touches no HA surface.
|
||||
This module holds the pure pieces — the snapshot dataclasses
|
||||
(:class:`QuestInstanceView`, :class:`ChildDaySnapshot`,
|
||||
:class:`NestQuestSnapshot`), the cycle-day helper (:func:`_cycle_day`),
|
||||
and the async :func:`build_snapshot` builder — so the HA coordinator and
|
||||
the API service's panel snapshot route share ONE implementation.
|
||||
the panel payload shaper (:func:`instance_payload`), and the async
|
||||
:func:`build_snapshot` builder — so the HA coordinator and the API
|
||||
service's panel snapshot route share ONE implementation of both the
|
||||
snapshot assembly and the entity-facing attribute payload shape.
|
||||
Nothing here imports :mod:`homeassistant`; the builder takes the
|
||||
database, the settings object, the target date, and the timezone and
|
||||
returns the snapshot, mirroring exactly what the coordinator used to do
|
||||
inline.
|
||||
database, the settings object, the target date, and the HA-local
|
||||
``now`` (a single clock read the caller already resolved) and returns
|
||||
the snapshot, mirroring exactly what the coordinator used to do inline.
|
||||
|
||||
``settings`` is accepted for forward-compatibility (the API route hands
|
||||
in the entry's :class:`~.settings.NestQuestSettings`); the current
|
||||
assembly does not read it, but the parameter keeps the builder's
|
||||
contract stable as future panel features derive scan caps or rollup
|
||||
behaviour from configuration.
|
||||
``settings`` is accepted because the API route hands in the entry's
|
||||
:class:`~.settings.NestQuestSettings`; it is CURRENTLY UNUSED — the
|
||||
assembly reads nothing from it — and is retained so the builder's
|
||||
contract stays stable if a future panel feature derives scan caps or
|
||||
rollup behaviour from configuration. No speculative read is wired in.
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import datetime
|
||||
from collections.abc import Iterable
|
||||
from dataclasses import dataclass
|
||||
from zoneinfo import ZoneInfo
|
||||
from typing import Any
|
||||
|
||||
from .completion import derive_state
|
||||
from .dao_children import ChildrenDao
|
||||
@@ -112,13 +115,53 @@ def _cycle_day(
|
||||
return 0
|
||||
|
||||
|
||||
def instance_payload(
|
||||
instances: Iterable[QuestInstanceView], *, include_missed: bool
|
||||
) -> list[dict[str, Any]]:
|
||||
"""Shape instance dicts per ENTITIES-AND-SERVICES.md §1.
|
||||
|
||||
The panel payload ``state`` is the documented ``open`` | ``completed``
|
||||
spelling, so the builder's derived ``done`` maps to ``completed`` here;
|
||||
``open`` passes through. ``missed`` instances are OMITTED from the
|
||||
entity-facing attribute payload (decision 5) unless ``include_missed``
|
||||
is set — the admin payload (D-009) keeps them with their ``missed``
|
||||
state. ``on_time`` passes the builder's ``was_on_time`` through
|
||||
verbatim (``True`` / ``False`` for a completed instance, ``None`` for
|
||||
an open one). This is the SINGLE shared implementation both the HA
|
||||
sensor layer and the API panel route read; it touches no Home
|
||||
Assistant surface.
|
||||
"""
|
||||
payload: list[dict[str, Any]] = []
|
||||
for view in instances:
|
||||
if view.state == "missed" and not include_missed:
|
||||
continue
|
||||
payload.append(
|
||||
{
|
||||
"id": view.instance_id,
|
||||
"definition_id": view.definition_id,
|
||||
"child_id": view.child_id,
|
||||
"title": view.title,
|
||||
"icon": view.icon,
|
||||
"window": view.window,
|
||||
"due_time": view.due_time,
|
||||
"state": (
|
||||
"completed" if view.state == "done" else view.state
|
||||
),
|
||||
"overdue": view.overdue,
|
||||
"completed_at": view.completed_at,
|
||||
"on_time": view.was_on_time,
|
||||
}
|
||||
)
|
||||
return payload
|
||||
|
||||
|
||||
async def build_snapshot(
|
||||
database: NestQuestDatabase,
|
||||
settings: NestQuestSettings,
|
||||
today: datetime.date,
|
||||
time_zone: ZoneInfo,
|
||||
now: datetime.datetime,
|
||||
) -> NestQuestSnapshot:
|
||||
"""Build the household panel snapshot for ``today`` in ``time_zone``.
|
||||
"""Build the household panel snapshot for ``today`` at the ``now`` instant.
|
||||
|
||||
Mirrors the assembly that lived in the coordinator's
|
||||
``_async_update_data``: active children in sort order, each child's
|
||||
@@ -128,10 +171,21 @@ async def build_snapshot(
|
||||
per-child rollup counts, and the custody cycle day of the first
|
||||
scheduled active child. Missed instances are retained on the
|
||||
snapshot (the rollup counts and the panel's missed plate need them)
|
||||
but the entity-facing attribute payload omits them at the sensor
|
||||
layer — this builder produces the shared shape both consumers read.
|
||||
but the entity-facing attribute payload omits them at the
|
||||
:func:`instance_payload` layer — this builder produces the shared
|
||||
shape both consumers read.
|
||||
|
||||
``now`` is the HA-local timezone-aware datetime the caller already
|
||||
resolved (a SINGLE clock read); the overdue check compares
|
||||
``now.time()`` against the instance's ``due_time`` for today's open
|
||||
instances. The builder performs NO internal clock read — it never
|
||||
calls :func:`datetime.datetime.now` — so the instant is pinned in
|
||||
tests and date and time can never disagree across two reads.
|
||||
``today`` is the calendar date the caller resolved from the same
|
||||
clock (``now.date()``); it anchors the due-date and cycle-day
|
||||
arithmetic. ``settings`` is accepted but currently unused (see the
|
||||
module docstring).
|
||||
"""
|
||||
now = datetime.datetime.now(time_zone)
|
||||
today_iso = today.isoformat()
|
||||
|
||||
children = await ChildrenDao(database).list_active()
|
||||
|
||||
@@ -39,6 +39,7 @@ from .coordinator import (
|
||||
NestQuestCoordinator,
|
||||
QuestInstanceView,
|
||||
)
|
||||
from .core.snapshot import instance_payload
|
||||
|
||||
#: Home Assistant's state machine refuses states longer than 255
|
||||
#: characters (its hard recorder/state limit). These sensors' states
|
||||
@@ -63,40 +64,6 @@ def _state_within_limit(state: Any) -> Any:
|
||||
return state
|
||||
|
||||
|
||||
def _instance_payload(
|
||||
instances: Iterable[QuestInstanceView], *, include_missed: bool
|
||||
) -> list[dict[str, Any]]:
|
||||
"""Shape instance dicts per ENTITIES-AND-SERVICES.md §1.
|
||||
|
||||
``state`` maps the coordinator's derived ``done`` to the panel's
|
||||
``completed`` spelling; ``missed`` instances are omitted unless
|
||||
``include_missed`` (the admin payload, D-009, keeps them with
|
||||
their ``missed`` state).
|
||||
"""
|
||||
payload: list[dict[str, Any]] = []
|
||||
for view in instances:
|
||||
if view.state == "missed" and not include_missed:
|
||||
continue
|
||||
payload.append(
|
||||
{
|
||||
"id": view.instance_id,
|
||||
"definition_id": view.definition_id,
|
||||
"child_id": view.child_id,
|
||||
"title": view.title,
|
||||
"icon": view.icon,
|
||||
"window": view.window,
|
||||
"due_time": view.due_time,
|
||||
"state": (
|
||||
"completed" if view.state == "done" else view.state
|
||||
),
|
||||
"overdue": view.overdue,
|
||||
"completed_at": view.completed_at,
|
||||
"on_time": view.was_on_time,
|
||||
}
|
||||
)
|
||||
return payload
|
||||
|
||||
|
||||
#: State reported by the next-quest sensor when the child owes nothing
|
||||
#: else today. A documented sentinel, never an empty string (an empty
|
||||
#: state reads as "sensor went unavailable" in HA).
|
||||
@@ -215,10 +182,10 @@ class NestQuestQuestsDueTodaySensor(_NestQuestChildDaySensor):
|
||||
if child is None:
|
||||
return None
|
||||
return {
|
||||
"instances": _instance_payload(
|
||||
"instances": instance_payload(
|
||||
child.instances, include_missed=False
|
||||
),
|
||||
"admin_instances": _instance_payload(
|
||||
"admin_instances": instance_payload(
|
||||
child.instances, include_missed=True
|
||||
),
|
||||
"child_id": child.child_id,
|
||||
|
||||
Reference in New Issue
Block a user