Compare commits

..
Author SHA1 Message Date
Joshua King e9dc0a1445 Test fix: week 0 runs Mon Jan 5 through Sun Jan 11
The six-day preview expectation missed that Jan 10-11 are still in
the present week (the away week starts Jan 12). Suite green before
commit: 1003 passed.
2026-09-15 18:20:42 -04:00
Joshua King 1bb0617471 Next-N-present-days preview (Feature 05, task 6)
PresenceEngine.next_present_dates(child_id, start_date, count):
walks forward from the INCLUSIVE start date through is_present, so
overrides and the pattern are honoured identically — this is the
preview the admin Schedule tab renders before a parent saves a
custody pattern. Count must be a positive int; the scan is capped at
two years (MAX_PREVIEW_SCAN_DAYS) and an always-absent child raises
a clear ValueError instead of looping forever. Tests: known two-week
pattern (straight five-day week, mid-week start skipping the absent
week), inclusive start, override blocking the preview start,
schedule-free child, input validation, always-absent error. Suite:
1002 passed.
2026-09-15 18:19:53 -04:00
Joshua King bdf3513609 Test fix: build the frozen-snapshot engine on the caller's list
Review round 3 (Codex gpt-5.6-terra, LOW): the helper copied the list,
so the mutation could never have affected even a shallow snapshot.
The engine is now constructed directly on the caller's list, making
the freeze regression-proof. Suite green before commit: 997 passed.
2026-09-15 18:16:40 -04:00
Joshua King 830d663a45 Test fix: tuples raise AttributeError for append, not TypeError
The frozen-snapshot test expected TypeError from tuple.append; tuples
have no append at all. Suite green BEFORE commit: 997 passed.
2026-09-15 18:15:13 -04:00
Joshua King bff2f4ff5e Review fix: freeze the engine's overrides snapshot
Review round 1 (Codex gpt-5.6-terra, MEDIUM): the overrides mapping
was shallow-copied, leaving caller-owned lists mutable through
_overrides — a later append would change is_present results. Each
validated list is copied into an immutable tuple before wrapping;
tests prove post-construction appends change nothing and the snapshot
refuses mutation. Suite: 996 passed.
2026-09-15 18:13:48 -04:00
Joshua King 8f04d93363 Overrides take precedence over the pattern (Feature 05, task 5)
PresenceEngine gains an overrides snapshot (child_id -> list of
PresenceOverride): is_present checks covering overrides BEFORE the
pattern and returns the override's flag as the answer — an absent
override on a normally-present day returns False, a present one on a
normally-absent day returns True, and an override on a child with no
schedule still applies (holidays work for the always-present sibling).
Snapshot validation mirrors the schedules': dict of lists keyed by the
override's own child id, exposed read-only. The DAO layer guarantees
no overlapping overrides per child; a hand-built snapshot that carries
them resolves deterministically to the LATEST start date (documented).
Tests: all three precedence cases, span edges (outside days stay on
the pattern), snapshot rejection matrix, deterministic overlap
tie-break. Suite: 995 passed.
2026-09-15 18:12:16 -04:00
Joshua King 94f54523f9 Review fix: gate the override race test inside A's transaction
Review round 1 (Codex gpt-5.6-terra, LOW): the racing test completed
synchronously and proved nothing. The executor now gates task A's
INSERT — inside its open transaction, after its overlap probe — so
task B queues on the connection lock, re-runs the probe against A's
committed row, and is rejected; exactly one lands. Suite: 990 passed.
2026-09-15 18:06:44 -04:00
Joshua King 51b1388233 Fix: inverted ranges skip the overlap probe and hit the schema CHECK
The matrix test's end-before-start probe (expecting the schema's
end>=start IntegrityError) hit the new overlap query first, since an
inverted range lexically 'overlaps' the seeded row. The overlap
check now runs only for well-ordered ranges; invalid ones fall
through to the INSERT and keep the IntegrityError contract. Suite:
990 passed.
2026-09-15 18:03:49 -04:00
Joshua King 744a40dcb5 Presence override overlap rejection naming the conflict (Feature 05, task 4)
PresenceOverridesDao.create now refuses an override that overlaps any
existing override of the SAME child (inclusive boundaries): the check
runs inside the same transaction as the INSERT under the connection
lock, so a racing create cannot slip a conflict between check and
write — a deterministic race test proves exactly one of two concurrent
overlapping creates lands. The ValueError names the conflicting
override's id, its range, and its flag. Round-trip, per-child scope,
and remove-then-recreate tests added. Suite: 990 passed.
2026-09-15 18:03:00 -04:00
4 changed files with 547 additions and 4 deletions
@@ -186,6 +186,15 @@ class PresenceOverridesDao:
The child must exist (validated atomically under the The child must exist (validated atomically under the
connection lock). Date shape is validated strictly, and the connection lock). Date shape is validated strictly, and the
schema CHECK rejects end < start. schema CHECK rejects end < start.
Overlap policy (Feature 05): an override for a child may not
overlap another override of the SAME child — two different
present/absent answers for one date are unresolvable. The
overlap check (inclusive boundaries) runs inside the same
transaction as the INSERT, so a racing create cannot slip a
conflicting override between the check and the write; a
conflict raises ValueError naming the conflicting override's
id and range.
""" """
_validate_date(start_date, "start_date") _validate_date(start_date, "start_date")
_validate_date(end_date, "end_date") _validate_date(end_date, "end_date")
@@ -196,6 +205,29 @@ class PresenceOverridesDao:
) )
if child is None: if child is None:
raise ValueError(f"child {child_id} does not exist") raise ValueError(f"child {child_id} does not exist")
# Only a well-ordered range has overlap semantics:
# inverted ranges fall through to the INSERT and hit
# the schema's end>=start CHECK, preserving the
# IntegrityError contract the matrix tests rely on.
if end_date >= start_date:
conflicting = await self._database.fetch_one(
f"SELECT {_OVERRIDE_COLUMNS} "
"FROM presence_overrides "
"WHERE child_id = ? AND end_date >= ? "
"AND start_date <= ? ORDER BY id LIMIT 1",
(child_id, start_date, end_date),
)
else:
conflicting = None
if conflicting is not None:
conflict = _override_from_row(conflicting)
raise ValueError(
f"override for child {child_id} "
f"[{start_date}, {end_date}] overlaps existing "
f"override {conflict.id} "
f"[{conflict.start_date}, {conflict.end_date}] "
f"(is_present={conflict.is_present})"
)
result = await self._database.execute( result = await self._database.execute(
"INSERT INTO presence_overrides (child_id, " "INSERT INTO presence_overrides (child_id, "
"start_date, end_date, is_present, note) " "start_date, end_date, is_present, note) "
+103 -3
View File
@@ -319,6 +319,13 @@ def cycle_week_index(
return (days // 7) % schedule.cycle_length_weeks return (days // 7) % schedule.cycle_length_weeks
#: Search cap for :meth:`PresenceEngine.next_present_dates`: two full
#: years of daily checks. A child absent every day (an all-absent
#: pattern with a blocking override) would otherwise loop forever; the
#: cap bounds the scan and surfaces the situation as an error instead.
MAX_PREVIEW_SCAN_DAYS = 366 * 2
class PresenceEngine: class PresenceEngine:
"""Answers "is this child at this house on this date?". """Answers "is this child at this house on this date?".
@@ -332,7 +339,11 @@ class PresenceEngine:
:func:`cycle_week_index`, never ISO week parity). :func:`cycle_week_index`, never ISO week parity).
""" """
def __init__(self, schedules: dict[int, PresenceSchedule]) -> None: def __init__(
self,
schedules: dict[int, PresenceSchedule],
overrides: dict[int, list[PresenceOverride]] | None = None,
) -> None:
if not isinstance(schedules, dict): if not isinstance(schedules, dict):
raise ValueError( raise ValueError(
f"schedules must map child_id to PresenceSchedule, got " f"schedules must map child_id to PresenceSchedule, got "
@@ -353,16 +364,66 @@ class PresenceEngine:
f"schedules is keyed {child_id!r} but holds the " f"schedules is keyed {child_id!r} but holds the "
f"schedule of child {schedule.child_id}" f"schedule of child {schedule.child_id}"
) )
if overrides is None:
overrides = {}
if not isinstance(overrides, dict):
raise ValueError(
"overrides must map child_id to a list of "
f"PresenceOverride, got {overrides!r}"
)
for child_id, entries in overrides.items():
_validate_child_id(child_id)
if not isinstance(entries, list):
raise ValueError(
f"overrides[{child_id!r}] must be a list of "
f"PresenceOverride, got {entries!r}"
)
for entry in entries:
if not isinstance(entry, PresenceOverride):
raise ValueError(
f"overrides[{child_id!r}] entries must be "
f"PresenceOverride, got {entry!r}"
)
if entry.child_id != child_id:
raise ValueError(
f"overrides is keyed {child_id!r} but holds an "
f"override of child {entry.child_id}"
)
# Read-only snapshot: reassignment is refused and no mutator # Read-only snapshot: reassignment is refused and no mutator
# exists, so a built engine answers consistently for its # exists, so a built engine answers consistently for its
# lifetime. # lifetime. The overrides lists are copied to immutable
# tuples — a shallow mapping copy alone would leave caller-
# owned lists reachable through _overrides, and mutating one
# later would change is_present results.
object.__setattr__(self, "_schedules", MappingProxyType(dict(schedules))) object.__setattr__(self, "_schedules", MappingProxyType(dict(schedules)))
object.__setattr__(
self,
"_overrides",
MappingProxyType(
{child_id: tuple(entries) for child_id, entries in overrides.items()}
),
)
def is_present(self, child_id: object, date: object) -> bool: def is_present(self, child_id: object, date: object) -> bool:
"""Return whether ``child_id`` is present on ``date``.""" """Return whether ``child_id`` is present on ``date``.
Overrides take precedence over the repeating pattern: when an
override covers the date, its flag IS the answer — including
for a child with no schedule at all. The DAO layer guarantees
a child's overrides never overlap; if a snapshot still carries
two covering the same date, the one with the LATEST start date
wins (deterministic, and matches "the most specific swap wins").
"""
if isinstance(child_id, bool) or not isinstance(child_id, int): if isinstance(child_id, bool) or not isinstance(child_id, int):
raise ValueError(f"child_id must be an integer, got {child_id!r}") raise ValueError(f"child_id must be an integer, got {child_id!r}")
target = _parse_date(date, "date") target = _parse_date(date, "date")
entries = self._overrides.get(child_id) or []
covering = [
entry for entry in entries if entry.covers(target)
]
if covering:
winner = max(covering, key=lambda entry: entry.start_date)
return winner.is_present
schedule = self._schedules.get(child_id) schedule = self._schedules.get(child_id)
if schedule is None: if schedule is None:
# No schedule at all: present every day (household default). # No schedule at all: present every day (household default).
@@ -370,6 +431,45 @@ class PresenceEngine:
week = cycle_week_index(schedule, target) week = cycle_week_index(schedule, target)
return target.weekday() in schedule.pattern[week] return target.weekday() in schedule.pattern[week]
def next_present_dates(
self,
child_id: object,
start_date: object,
count: int,
) -> list[datetime.date]:
"""Return the next ``count`` dates the child is present.
Walks forward from ``start_date`` (INCLUSIVE — a parent
previewing "starting Monday" expects Monday itself when the
child is present) checking :meth:`is_present` for every day,
so overrides and the pattern are honoured identically. The
admin Schedule tab renders this preview so a parent can confirm
a custody pattern is right before saving it.
A child absent every scanned day raises ValueError after the
two-year search cap — an always-absent child would otherwise
loop forever. ``count`` must be a positive integer.
"""
_validate_child_id(child_id)
start = _parse_date(start_date, "start_date")
if isinstance(count, bool) or not isinstance(count, int):
raise ValueError(f"count must be an integer, got {count!r}")
if count < 1:
raise ValueError(f"count must be at least 1, got {count}")
found: list[datetime.date] = []
day = start
for _ in range(MAX_PREVIEW_SCAN_DAYS):
if self.is_present(child_id, day):
found.append(day)
if len(found) == count:
return found
day += datetime.timedelta(days=1)
raise ValueError(
f"child {child_id} is not present on any of the "
f"{MAX_PREVIEW_SCAN_DAYS} days from {start.isoformat()}; "
f"{count} present day(s) cannot be previewed"
)
def __setattr__(self, name: object, value: object) -> None: def __setattr__(self, name: object, value: object) -> None:
raise AttributeError( raise AttributeError(
"PresenceEngine is an immutable snapshot; build a new engine " "PresenceEngine is an immutable snapshot; build a new engine "
+170 -1
View File
@@ -619,4 +619,173 @@ def test_dao_presence_test_file_uses_dao_not_raw_table_sql() -> None:
) )
assert sql_pattern.search(remaining) is None, ( assert sql_pattern.search(remaining) is None, (
"tests must go through the DAO, not raw SQL, for these tables" "tests must go through the DAO, not raw SQL, for these tables"
) )
# ---------------------------------------------------------------------------
# Presence overrides: overlap rejection naming the conflict
# ---------------------------------------------------------------------------
def test_override_create_round_trip_single_and_range(tmp_path) -> None:
async def _body(database, schedules, overrides, children, child):
single = await overrides.create(
child.id, "2026-07-20", "2026-07-20", False
)
assert (single.start_date, single.end_date) == ("2026-07-20",) * 2
span = await overrides.create(
child.id, "2026-08-01", "2026-08-05", True, note="traded week"
)
assert span.is_present is True
assert span.note == "traded week"
# Distinct, non-overlapping ranges coexist.
listed = await overrides.list_by_child_and_range(
child.id, "2026-01-01", "2026-12-31"
)
assert [row.id for row in listed] == [single.id, span.id]
return listed
_with_db(tmp_path, "override-round-trip.db")(_body)
def test_override_overlap_rejected_and_names_the_conflict(tmp_path) -> None:
async def _body(database, schedules, overrides, children, child):
existing = await overrides.create(
child.id, "2026-07-20", "2026-07-24", False, note="holiday"
)
for start, end in (
("2026-07-24", "2026-07-26"), # touches the existing end
("2026-07-18", "2026-07-20"), # touches the existing start
("2026-07-21", "2026-07-22"), # fully inside
("2026-07-01", "2026-07-30"), # fully covering
):
with pytest.raises(ValueError, match="overlaps existing"):
await overrides.create(
child.id, start, end, True, note="swap"
)
# The error NAMES the conflicting override (id + its range).
with pytest.raises(
ValueError,
match=(
rf"override {existing.id} "
rf"\[2026-07-20, 2026-07-24\].*is_present=False"
),
):
await overrides.create(child.id, "2026-07-22", "2026-07-22", True)
# Nothing was written by any rejected attempt.
listed = await overrides.list_by_child_and_range(
child.id, "2026-01-01", "2026-12-31"
)
assert [row.id for row in listed] == [existing.id]
return existing
_with_db(tmp_path, "override-overlap.db")(_body)
def test_override_overlap_is_per_child(tmp_path) -> None:
"""Different children's overrides may cover the same dates: the
conflict rule is per child."""
async def _body(database, schedules, overrides, children, child):
other = await children.create("Bo", NOW)
await overrides.create(child.id, "2026-07-20", "2026-07-24", False)
twin = await overrides.create(
other.id, "2026-07-20", "2026-07-24", True
)
assert twin.child_id == other.id
listed = await overrides.list_by_child_and_range(
other.id, "2026-01-01", "2026-12-31"
)
assert [row.id for row in listed] == [twin.id]
return twin
_with_db(tmp_path, "override-per-child.db")(_body)
def test_override_remove_then_recreate_overlapping(tmp_path) -> None:
async def _body(database, schedules, overrides, children, child):
first = await overrides.create(
child.id, "2026-07-20", "2026-07-24", False
)
assert await overrides.delete(first.id) is True
assert await overrides.delete(first.id) is False
replacement = await overrides.create(
child.id, "2026-07-20", "2026-07-24", True, note="swap back"
)
assert replacement.is_present is True
return replacement
_with_db(tmp_path, "override-recreate.db")(_body)
def test_override_create_racing_conflicts_serialize(tmp_path) -> None:
"""Two racing creates for the same child and dates: exactly one
lands, the other is rejected with the overlap error. DETERMINISTIC
gate: task A is paused at its INSERT — inside its open transaction,
after its overlap probe — so task B is created while A provably
holds the connection lock and must queue; B then re-runs the probe
against A's committed row and is rejected."""
import asyncio as asyncio_module
from unittest.mock import MagicMock
async def _main():
from custom_components.nestquest.dao_children import ChildrenDao
from custom_components.nestquest.dao_presence import (
PresenceOverridesDao,
)
from custom_components.nestquest.db import NestQuestDatabase
from custom_components.nestquest.migrations import apply_migrations
armed = {"active": False, "gated": False}
gate_open = asyncio_module.Event()
a_started = asyncio_module.Event()
hass = MagicMock()
async def _gated_executor(fn, *args):
if armed["active"]:
# Gate the FIRST _execute after arming: task A's INSERT,
# which runs inside its open transaction (BEGIN already
# executed) after the overlap probe.
if getattr(fn, "__name__", "") == "_execute" and not armed["gated"]:
armed["gated"] = True
a_started.set()
await gate_open.wait()
return fn(*args)
hass.async_add_executor_job = _gated_executor
database = NestQuestDatabase(hass)
await database.open(tmp_path / "override-race.db")
try:
await apply_migrations(database)
children = ChildrenDao(database)
overrides = PresenceOverridesDao(database)
child = await children.create("Ada", NOW)
armed["active"] = True
task_a = asyncio_module.ensure_future(
overrides.create(child.id, "2026-07-20", "2026-07-24", True)
)
await a_started.wait()
armed["active"] = False
task_b = asyncio_module.ensure_future(
overrides.create(child.id, "2026-07-22", "2026-07-26", False)
)
await asyncio_module.sleep(0)
gate_open.set()
record_a, error_b = await asyncio_module.gather(
task_a, task_b, return_exceptions=True
)
assert isinstance(record_a, object) and not isinstance(
record_a, BaseException
), f"A must land: {record_a!r}"
assert isinstance(error_b, ValueError), (
f"B must be rejected with the overlap error: {error_b!r}"
)
assert "overlaps existing" in str(error_b)
listed = await overrides.list_by_child_and_range(
child.id, "2026-01-01", "2026-12-31"
)
assert [row.id for row in listed] == [record_a.id]
finally:
await database.close()
asyncio.new_event_loop().run_until_complete(_main())
+242
View File
@@ -476,3 +476,245 @@ def test_engine_is_immutable() -> None:
engine._schedules = {} engine._schedules = {}
with pytest.raises(AttributeError, match="immutable snapshot"): with pytest.raises(AttributeError, match="immutable snapshot"):
engine.something_new = 1 engine.something_new = 1
# ---------------------------------------------------------------------------
# Overrides take precedence over the pattern
# ---------------------------------------------------------------------------
def _engine_with_overrides(*overrides_for_declan) -> PresenceEngine:
anchor = datetime.date(2026, 1, 5) # Monday
return PresenceEngine(
{
1: PresenceSchedule(
1, 2, anchor, {0: {0, 1, 2, 3, 4, 5, 6}, 1: set()}
)
},
overrides={1: list(overrides_for_declan)} if overrides_for_declan else {},
)
def test_absent_override_on_normally_present_day_wins() -> None:
# 2026-01-06 is Tuesday of Declan's week 0: normally present.
engine = _engine_with_overrides(
PresenceOverride(1, "2026-01-06", "2026-01-06", False, note="away")
)
assert engine.is_present(1, datetime.date(2026, 1, 6)) is False
# The pattern resumes outside the override.
assert engine.is_present(1, datetime.date(2026, 1, 7)) is True
def test_present_override_on_normally_absent_day_wins() -> None:
# 2026-01-13 is in Declan's week 1 (away all week); a present
# override on the Tuesday of week 1 brings him home for that day.
engine = _engine_with_overrides(
PresenceOverride(1, "2026-01-13", "2026-01-13", True, note="trade")
)
assert engine.is_present(1, datetime.date(2026, 1, 13)) is True
assert engine.is_present(1, datetime.date(2026, 1, 14)) is False
def test_override_applies_without_a_schedule() -> None:
"""An override on a schedule-free child still applies: holidays and
swaps must work for the always-present sibling too."""
engine = PresenceEngine(
{},
overrides={
3: [
PresenceOverride(
3, "2026-07-20", "2026-07-24", False, note="holiday"
)
]
},
)
assert engine.is_present(3, datetime.date(2026, 7, 22)) is False
assert engine.is_present(3, datetime.date(2026, 7, 19)) is True
assert engine.is_present(3, datetime.date(2026, 7, 25)) is True
def test_override_range_beats_pattern_for_its_span() -> None:
engine = _engine_with_overrides(
PresenceOverride(1, "2026-01-13", "2026-01-17", True, note="traded week")
)
for offset in range(12, 17):
day = datetime.date(2026, 1, 1) + datetime.timedelta(days=offset)
assert engine.is_present(1, day) is True, f"{day}"
# Days outside the span stay on the pattern (week 1: absent).
assert engine.is_present(1, datetime.date(2026, 1, 12)) is False
assert engine.is_present(1, datetime.date(2026, 1, 18)) is False
def test_engine_override_snapshot_validation() -> None:
schedule = PresenceSchedule(1, 1, ANCHOR, {0: {0}})
entry = PresenceOverride(1, "2026-07-20", "2026-07-20", True)
with pytest.raises(ValueError, match="must map child_id"):
PresenceEngine({1: schedule}, overrides=[entry])
with pytest.raises(ValueError, match="must be a list"):
PresenceEngine({1: schedule}, overrides={1: entry})
with pytest.raises(ValueError, match="must be"):
PresenceEngine({1: schedule}, overrides={1: ["nope"]})
with pytest.raises(ValueError, match="holds an override"):
PresenceEngine({1: schedule}, overrides={2: [entry]})
with pytest.raises(ValueError, match="child_id must be an integer"):
PresenceEngine({1: schedule}, overrides={True: [entry]})
def test_engine_overlapping_snapshot_uses_latest_start() -> None:
"""The DAO layer refuses overlapping overrides per child; if a
snapshot carries them anyway (hand-built), the latest start date
wins deterministically."""
engine = _engine_with_overrides(
PresenceOverride(1, "2026-01-06", "2026-01-10", False),
PresenceOverride(1, "2026-01-08", "2026-01-12", True),
)
# Jan 6-7: only the earlier override covers -> absent.
assert engine.is_present(1, datetime.date(2026, 1, 6)) is False
# Jan 8-10: both cover; the LATER start (present) wins.
assert engine.is_present(1, datetime.date(2026, 1, 9)) is True
# Jan 11-12: only the later override covers -> present.
assert engine.is_present(1, datetime.date(2026, 1, 11)) is True
def test_engine_override_lists_are_frozen() -> None:
"""The overrides snapshot must be truly read-only: the engine is
built directly on the CALLER's list, so mutating that list after
construction would change answers under a shallow copy — under the
frozen snapshot it must not."""
entry = PresenceOverride(1, "2026-01-06", "2026-01-06", False)
entries = [entry]
schedule = PresenceSchedule(
1, 2, ANCHOR, {0: {0, 1, 2, 3, 4, 5, 6}, 1: set()}
)
engine = PresenceEngine(
{1: schedule}, overrides={1: entries} # caller-owned list
)
assert engine.is_present(1, datetime.date(2026, 1, 6)) is False
entries.append(PresenceOverride(1, "2026-01-07", "2026-01-07", False))
# The late append must NOT change the engine's answers...
assert engine.is_present(1, datetime.date(2026, 1, 7)) is True
# Tuples have no append at all (AttributeError), and the mapping
# itself refuses reassignment.
with pytest.raises(AttributeError):
engine._overrides[1].append(entry)
with pytest.raises(AttributeError, match="immutable snapshot"):
engine._overrides = {}
# ---------------------------------------------------------------------------
# next_present_dates: the parent's pattern preview
# ---------------------------------------------------------------------------
def _preview_engine() -> PresenceEngine:
"""Declan: home all of week 0, away all of week 1 (anchor
2026-01-05, a Monday); an away override Tue Jan 13 (his away week)
would matter only for the override test."""
return PresenceEngine(
{
1: PresenceSchedule(
1, 2, datetime.date(2026, 1, 5),
{0: {0, 1, 2, 3, 4, 5, 6}, 1: set()},
)
}
)
def test_preview_returns_the_next_present_days_of_a_known_pattern() -> None:
engine = _preview_engine()
# Starting Monday Jan 5 (present week 0): five straight days.
preview = engine.next_present_dates(1, "2026-01-05", 5)
assert preview == [
datetime.date(2026, 1, 5),
datetime.date(2026, 1, 6),
datetime.date(2026, 1, 7),
datetime.date(2026, 1, 8),
datetime.date(2026, 1, 9),
]
# Starting mid-week: the rest of week 0 first, then the absent
# week 1 is skipped and the next present week picks up.
preview = engine.next_present_dates(1, "2026-01-07", 3)
assert preview == [
datetime.date(2026, 1, 7),
datetime.date(2026, 1, 8),
datetime.date(2026, 1, 9),
]
preview = engine.next_present_dates(1, "2026-01-07", 6)
# Week 0 runs Mon Jan 5 .. Sun Jan 11 (all present); the away week
# (Jan 12-18) is skipped; week 2 resumes Jan 19.
assert preview == [
datetime.date(2026, 1, 7),
datetime.date(2026, 1, 8),
datetime.date(2026, 1, 9),
datetime.date(2026, 1, 10),
datetime.date(2026, 1, 11),
datetime.date(2026, 1, 19),
]
def test_preview_start_date_is_inclusive() -> None:
engine = _preview_engine()
# Jan 12 (Monday of the away week) is absent: the first present day
# is Jan 19 — the start date itself when present.
preview = engine.next_present_dates(1, "2026-01-19", 1)
assert preview == [datetime.date(2026, 1, 19)]
def test_preview_honours_overrides() -> None:
schedule = PresenceSchedule(
1, 2, datetime.date(2026, 1, 5),
{0: {0, 1, 2, 3, 4, 5, 6}, 1: set()},
)
engine = PresenceEngine(
{1: schedule},
overrides={
1: [
PresenceOverride(
1, "2026-01-05", "2026-01-06", False, note="holiday"
)
]
},
)
# Jan 5-6 blocked by the override: the preview starts Jan 7.
preview = engine.next_present_dates(1, "2026-01-04", 3)
assert preview == [
datetime.date(2026, 1, 7),
datetime.date(2026, 1, 8),
datetime.date(2026, 1, 9),
]
def test_preview_schedule_free_child_returns_consecutive_days() -> None:
engine = PresenceEngine({})
preview = engine.next_present_dates(3, "2026-03-01", 3)
assert preview == [
datetime.date(2026, 3, 1),
datetime.date(2026, 3, 2),
datetime.date(2026, 3, 3),
]
def test_preview_rejects_bad_inputs() -> None:
engine = _preview_engine()
with pytest.raises(ValueError, match="count must be an integer"):
engine.next_present_dates(1, "2026-01-05", "3")
with pytest.raises(ValueError, match="count must be at least 1"):
engine.next_present_dates(1, "2026-01-05", 0)
with pytest.raises(ValueError, match="child_id must be an integer"):
engine.next_present_dates(True, "2026-01-05", 1)
with pytest.raises(ValueError, match="plain calendar date"):
engine.next_present_dates(1, datetime.datetime(2026, 1, 5), 1)
def test_preview_always_absent_child_raises_not_loops() -> None:
"""A child absent every scanned day must surface as an error, not
hang the admin preview."""
engine = PresenceEngine(
{
1: PresenceSchedule(
1, 1, datetime.date(2026, 1, 5), {0: set()}
)
}
)
with pytest.raises(ValueError, match="not present on any"):
engine.next_present_dates(1, "2026-01-05", 2)