schedule.py

"""Pure day/night schedule logic: wall-clock time -> display phase.

The optional schedule blanks the 7-seg during the day (to spare the display),
shows it at the wake brightness in the evening, and dims it for night. This
module only decides *which window a given time falls in*; the loop in
piclock/app.py applies the result — and applies it only when the phase *changes*,
so a HomeKit/Siri override sticks until the schedule's next edge, exactly like
a timer-based schedule would behave.

No I/O and no globals, so it is unit-testable off-Pi like piclock/clock.py.
"""

from __future__ import annotations

from datetime import time

# The three phases, in daily order. OFF starts at off_at, WAKE at on_at,
# NIGHT at dim_at (wrapping past midnight back to off_at).
OFF = "off"  # display blanked
WAKE = "wake"  # display on at Config.wake_brightness
NIGHT = "night"  # display on at Config.night_brightness


def phase(now: time, *, off_at: time, on_at: time, dim_at: time) -> str:
    """Return the schedule phase (`OFF`/`WAKE`/`NIGHT`) that ``now`` falls in.

    Requires ``off_at < on_at < dim_at`` (Config validates this): the display
    is blanked in [off_at, on_at), shown at the wake brightness in
    [on_at, dim_at), and shown at the night brightness in [dim_at, off_at)
    across midnight.
    """
    if off_at <= now < on_at:
        return OFF
    if on_at <= now < dim_at:
        return WAKE
    return NIGHT


def edge(
    prev: str | None,
    new: str,
    *,
    wake_brightness: int,
    night_brightness: int,
) -> tuple[bool | None, int | None]:
    """What a phase edge applies to the display: ``(enabled, brightness)``.

    Either element is None when the edge leaves that property alone. The
    WAKE -> NIGHT dim only adjusts brightness — it must not relight a display
    that was turned off by hand (HomeKit/Siri) after the wake edge. Every other
    arrival at a phase (a scheduled on/off edge, startup with prev=None, or a
    clock jump) asserts the full state for that phase.
    """
    if new == OFF:
        return False, None
    if new == WAKE:
        return True, wake_brightness
    if prev == WAKE:
        return None, night_brightness  # dim in place; don't undo a manual off
    return True, night_brightness