wake-alarm/wake_alarm/_curtains.py
Krzysztof kuhy Rudnicki f5eb7fc2bd Phase 7: curtains open on the alarm, no-op until hardware exists (item 5)
_curtains.py: a two-method driver protocol, a registry, and a logging no-op
default. prepare_hardware() calls open_curtains() next to turn_on_plug().

The no-op is not a placeholder awaiting hardware -- it is the correct
behaviour on a machine with no motor. Shipping it now means the call site and
the JSONL event are real, so buying a motor later is a config file rather than
a code change.

Shaped like _smart_plug.py, which solves the same problem: absent or malformed
config means "no curtains" rather than an error, an unknown driver name
degrades with a WARNING, and a driver that throws is caught -- a jammed motor
must never be the reason nobody is woken. The call sits on the startup path,
ahead of the first beep, so an exception escaping it would take the alarm down
entirely.

Why bother at all with no hardware: the audio failsafe silences the alarm at
FAILSAFE_SILENCE_SECONDS, and daylight is the one wake cue that outlives it --
and the only one independent of a sink, a speaker or an HDMI handshake, which
is the exact chain that made this alarm silent in the first place.

DOCS-curtains-hardware.md has the buy list, the three rules a new driver must
follow, and what is deliberately excluded (no cloud, no scheduling of its own,
no close-at-night -- closing belongs to the night lockdown, item 13).

CURTAINS_CONFIG_FILE and CURTAINS_DEFAULT_DRIVER live in _curtains.py rather
than _constants.py, since this is their only consumer -- the same call
_rounds.py and _alarm_session.py already make. That also keeps _constants.py
under the 250-line cap without dragging _sync.py's pre-existing overage into
this commit; splitting _sync.py belongs to the phase that legitimately touches
it (item 8).

465 tests pass, 100% branch coverage. vmbox harness 8/8, exit 0.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EckWmyfetYq3Mi8MAnUudh
2026-08-27 21:00:11 +02:00

167 lines
5.7 KiB
Python

"""Open the curtains when the alarm fires, if any hardware is configured.
Item 5. There is **no curtain hardware yet**, so the default driver is a
logging no-op: it records what it would have done and returns. That is the
whole point of shipping this now rather than waiting for a motor — the alarm
sequence gains its call site, the JSONL log gains its event, and buying
hardware later is a config file, not a code change.
Deliberately shaped like :mod:`wake_alarm._smart_plug`, which solves the same
problem (optional hardware that must never delay or break the alarm):
* absent or malformed config means "no curtains", never an error;
* every failure is caught and logged, because a stuck motor must not stop the
alarm from ringing;
* a driver's dependency is import-guarded, so an uninstalled library degrades
to the no-op instead of killing the alarm process.
Config lives at ``~/.config/wake_alarm/curtains.json``::
{"driver": "noop"}
``DOCS-curtains-hardware.md`` has the buy list and what each driver needs.
"""
from __future__ import annotations
import json
import logging
from pathlib import Path
from typing import TYPE_CHECKING, Protocol
if TYPE_CHECKING:
from collections.abc import Callable
_logger = logging.getLogger(__name__)
# Kept here rather than in _constants.py because this module is their only
# consumer -- the same call the repo already makes for _rounds.py's timing
# constants and _alarm_session.py's state names.
CURTAINS_CONFIG_FILE = Path.home() / ".config" / "wake_alarm" / "curtains.json"
"""Which motor to drive, if any. Absent => the no-op driver."""
CURTAINS_DEFAULT_DRIVER = "noop"
"""Used when nothing is configured, and when a config names an unknown one."""
class CurtainDriver(Protocol):
"""What any curtain implementation has to provide.
Two methods, both of which must return rather than raise: the alarm calls
them on its startup path, and a driver that throws would take the whole
alarm down with it.
"""
def open(self) -> bool:
"""Open the curtains. Returns True when the hardware acknowledged."""
def close(self) -> bool:
"""Close the curtains. Returns True when the hardware acknowledged."""
class NoOpCurtains:
"""The default: log the intent, touch nothing.
Not a placeholder to be replaced later so much as the correct behaviour on
a machine with no curtain motor. It keeps the call site and the log event
real, so the day hardware arrives the only change is a config file.
"""
name = "noop"
def open(self) -> bool:
"""Record that the curtains would have opened."""
_logger.info(
"Curtains: would open now (no hardware configured)",
extra={"event": "curtains_open", "driver": self.name, "real": False},
)
return True
def close(self) -> bool:
"""Record that the curtains would have closed."""
_logger.info(
"Curtains: would close now (no hardware configured)",
extra={"event": "curtains_close", "driver": self.name, "real": False},
)
return True
# Driver registry. A new motor means adding one entry and one class, with its
# dependency import-guarded inside the factory so an uninstalled library
# degrades to the no-op rather than killing the alarm.
_DRIVERS: dict[str, Callable[[], CurtainDriver]] = {
NoOpCurtains.name: NoOpCurtains,
}
def _load_config() -> dict[str, object] | None:
"""Return the curtain config, or None when there is none to read.
Returns:
The parsed config dict, or None when the file is absent, unreadable,
or not a JSON object. Every one of those means "no curtains", which is
the correct state on a machine that has none.
"""
if not CURTAINS_CONFIG_FILE.exists():
return None
try:
with CURTAINS_CONFIG_FILE.open() as handle:
config = json.load(handle)
except (OSError, json.JSONDecodeError):
_logger.warning(
"Cannot read %s; falling back to the no-op curtain driver",
CURTAINS_CONFIG_FILE,
)
return None
if not isinstance(config, dict):
_logger.warning("Curtain config is not a JSON object; using the no-op driver")
return None
return config
def get_driver() -> CurtainDriver:
"""Build the configured curtain driver, or the no-op when none applies.
Returns:
A driver honouring :class:`CurtainDriver`. Never None and never
raising: the alarm calls this on its startup path.
"""
config = _load_config()
name = CURTAINS_DEFAULT_DRIVER
if config is not None:
requested = config.get("driver")
if isinstance(requested, str):
name = requested
factory = _DRIVERS.get(name)
if factory is None:
_logger.warning(
"Unknown curtain driver %r; using %s. Known drivers: %s",
name,
CURTAINS_DEFAULT_DRIVER,
", ".join(sorted(_DRIVERS)),
)
factory = _DRIVERS[CURTAINS_DEFAULT_DRIVER]
return factory()
def open_curtains() -> bool:
"""Open the curtains as part of the alarm's wake sequence.
Sunlight is the one wake cue that keeps working after the sound stops at
``FAILSAFE_SILENCE_SECONDS``, which is why this is worth a call site even
with no motor attached yet.
Returns:
True when a driver reported success. A failure is logged and
swallowed — a jammed curtain must never stop the alarm ringing.
"""
try:
return get_driver().open()
except (OSError, RuntimeError, ValueError):
_logger.warning(
"Curtain driver failed to open; the alarm continues",
exc_info=True,
extra={"event": "curtains_failed"},
)
return False