clock.py

"""Pure time-to-display rendering logic.

No hardware, no I/O — just turns a datetime into what the four digits and the
colon should show. Kept separate so it can be unit-tested off-Pi.
"""

from __future__ import annotations

from dataclasses import dataclass
from datetime import datetime

#: What to show before the system clock has synchronized after boot, so the
#: clock never displays a confidently-wrong time.
UNSYNCED_TEXT = "----"


@dataclass(frozen=True)
class DisplayState:
    """Desired display contents: four characters, colon, and sync-indicator dot."""

    text: str  # exactly 4 chars; space means a blank digit
    colon: bool
    sync_dot: bool = False


def render(
    now: datetime,
    synced: bool,
    *,
    ever_synced: bool = False,
    hour24: bool = True,
    blink: bool = False,
) -> DisplayState:
    """Render the current local time into a DisplayState.

    Until the clock has synced for the first time, returns dashes with the
    colon off — never a confidently-wrong time. Once synced, formats HH:MM
    with the sync dot lit; in 12-hour mode the leading zero of the hour is
    blanked. If sync is later lost (``synced`` False, ``ever_synced`` True)
    the time stays up — the system clock free-runs and remains approximately
    right — and only the sync dot goes dark. The colon is steady by default;
    when ``blink`` is set it is lit only for the first half of each second.
    """
    if not synced and not ever_synced:
        return DisplayState(UNSYNCED_TEXT, colon=False)

    if hour24:
        text = f"{now.hour:02d}{now.minute:02d}"
    else:
        hour12 = (now.hour - 1) % 12 + 1
        text = f"{hour12:2d}{now.minute:02d}"  # space-pads a single-digit hour

    colon = (now.microsecond < 500_000) if blink else True
    return DisplayState(text, colon, sync_dot=synced)