boneio 1.6.0.dev2__tar.gz → 1.6.0.dev4__tar.gz

{boneio-1.6.0.dev2/boneio.egg-info → boneio-1.6.0.dev4}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: boneio
-Version: 1.6.0.dev2
+Version: 1.6.0.dev4
 Summary: Python App for BoneIO
 Author-email: Paweł Szafer <pszafer@gmail.com>
 License: GNU General Public License v3.0
 Project-URL: Homepage, https://boneio.eu
-Project-URL: Repository, https://github.com/boneIO-eu/app_bbb
+Project-URL: Repository, https://github.com/boneIO-eu/app_black
 Project-URL: Documentation, https://boneio.eu/docs/intro/
-Project-URL: Changelog, https://github.com/boneIO-eu/app_bbb/releases
+Project-URL: Changelog, https://github.com/boneIO-eu/app_black/releases
 Requires-Python: >=3.13
 Description-Content-Type: text/markdown
 License-File: LICENSE

boneio-1.6.0.dev4/boneio/core/config/provenance.py

@@ -0,0 +1,114 @@
+"""Tell a freshly flashed controller from one that has been in service.
+
+The first-run wizard has two steps that are only appropriate on a blank
+device. The import step offers to restore a configuration, which on a device
+that already has one reads as "yours is gone". The devices step is worse than
+misleading: it replaces the whole ``event`` section, so a controller with fifty
+configured inputs loses them to a wizard its owner opened only to create an
+account.
+
+So the question has to be answered before those steps are offered, and the two
+ways of getting it wrong are not equally bad:
+
+  * Treating an upgraded device as fresh costs the owner their configuration.
+  * Treating a fresh device as upgraded costs them a step in a wizard; they
+    can still import and bind inputs from the normal interface afterwards.
+
+This module is therefore written to answer "is it fresh" and to say no when it
+cannot tell. Freshness has to be demonstrated, not assumed.
+
+The demonstration is that the configuration is still the factory one. The image
+copies a variant out of ``~/.cache/boneio_configs/<variant>/`` verbatim, and
+per-device work touches only ``mqtt.yaml`` (the broker password), so a
+controller nobody has configured yet still has a ``config.yaml`` byte-identical
+to its template.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+
+_LOGGER = logging.getLogger(__name__)
+
+#: Where the image leaves the per-variant templates it seeded the device from.
+FACTORY_TEMPLATE_DIR = Path.home() / ".cache" / "boneio_configs"
+
+
+def _digest(path: Path) -> bytes | None:
+    """Read a file for comparison.
+
+    Args:
+        path: File to read.
+
+    Returns:
+        Its contents, or None when it cannot be read.
+    """
+    try:
+        return path.read_bytes()
+    except OSError:
+        return None
+
+
+def looks_factory_fresh(
+    config_path: str | os.PathLike[str],
+    template_dir: str | os.PathLike[str] | None = None,
+) -> bool:
+    """Whether this device still carries an untouched factory configuration.
+
+    Args:
+        config_path: The device's ``config.yaml``.
+        template_dir: Where the per-variant templates live. Defaults to
+            :data:`FACTORY_TEMPLATE_DIR`.
+
+    Returns:
+        True only when freshness can be positively shown: there is no
+        configuration at all, or the configuration is identical to one of the
+        templates the image ships. False whenever the answer is not certain.
+    """
+    config = Path(config_path)
+    current = _digest(config)
+    if current is None:
+        # Nothing to lose, and nothing that an import could overwrite.
+        _LOGGER.debug("No configuration at %s — treating the device as fresh", config)
+        return True
+
+    root = Path(template_dir) if template_dir is not None else FACTORY_TEMPLATE_DIR
+    try:
+        variants = sorted(p for p in root.iterdir() if p.is_dir())
+    except OSError:
+        # No templates to compare against: the honest answer is "cannot tell",
+        # and the safe reading of that is "assume it has been configured".
+        _LOGGER.debug("No factory templates under %s — assuming configured", root)
+        return False
+
+    for variant in variants:
+        if current == _digest(variant / "config.yaml"):
+            _LOGGER.debug("Configuration matches the %s template", variant.name)
+            return True
+
+    return False
+
+
+def was_configured_before(
+    config_path: str | os.PathLike[str],
+    had_legacy_auth: bool = False,
+    template_dir: str | os.PathLike[str] | None = None,
+) -> bool:
+    """Whether the wizard should skip the steps that assume a blank device.
+
+    Args:
+        config_path: The device's ``config.yaml``.
+        had_legacy_auth: Whether a pre-1.6 ``web.auth`` block was found. It
+            proves the device is not fresh, but its absence proves nothing —
+            most 1.5.x controllers never had web authentication at all, which
+            is exactly the case this used to get wrong.
+        template_dir: Passed through to :func:`looks_factory_fresh`.
+
+    Returns:
+        True when the device already has a configuration of its own.
+    """
+    if had_legacy_auth:
+        return True
+    return not looks_factory_fresh(config_path, template_dir)

{boneio-1.6.0.dev2 → boneio-1.6.0.dev4}/boneio/core/config/yaml_util.py

@@ -773,6 +773,179 @@ class CustomValidator(Validator):
         kwarg = unit_to_kwarg[one_of(*unit_to_kwarg)(unit_str)]
         return TimePeriod(**{kwarg: float(match.group(1))})
 
+    def _normalize_coerce_sun_offset(self, value) -> float:
+        """Parse a signed offset from a sun anchor into seconds.
+
+        Unlike ``positive_time_period`` this must accept negative values —
+        "half an hour before sunset" is the whole point — and it returns plain
+        seconds rather than a TimePeriod, because the only thing that ever
+        happens to it is being added to a datetime.
+
+        A bare number means **seconds**, not milliseconds. That differs from
+        ``positive_time_period`` deliberately: a sun offset measured in
+        milliseconds would be meaningless, and the frontend always sends a unit.
+
+        Args:
+            value: ``"-30min"``, ``"1h"``, ``"45s"``, or a number of seconds.
+
+        Returns:
+            The offset in seconds, negative for "before".
+
+        Raises:
+            ConfigurationException: If the value cannot be read as an offset.
+        """
+        if value is None or value == "":
+            return 0.0
+        if isinstance(value, bool):
+            raise ConfigurationException(f"Expected a sun offset, got {value!r}")
+        if isinstance(value, (int, float)):
+            return float(value)
+
+        text = str(value).strip().lower()
+        if not text:
+            return 0.0
+
+        match = re.match(r"^([-+]?[0-9]*\.?[0-9]+)\s*(\w*)$", text)
+        if match is None:
+            raise ConfigurationException(
+                f"Expected an offset like '-30min', '15m' or '1h', got {value!r}"
+            )
+
+        unit_to_seconds = {
+            "": 1.0,
+            "s": 1.0,
+            "sec": 1.0,
+            "secs": 1.0,
+            "second": 1.0,
+            "seconds": 1.0,
+            "m": 60.0,
+            "min": 60.0,
+            "mins": 60.0,
+            "minute": 60.0,
+            "minutes": 60.0,
+            "h": 3600.0,
+            "hour": 3600.0,
+            "hours": 3600.0,
+        }
+        unit = match.group(2)
+        if unit not in unit_to_seconds:
+            raise ConfigurationException(
+                f"Unknown unit {unit!r} in sun offset {value!r}. Use s, min or h."
+            )
+        return float(match.group(1)) * unit_to_seconds[unit]
+
+    def _check_with_schedule_shape(self, field, value):
+        """Reject a schedule whose trigger does not match its own type.
+
+        Cerberus can require a dict and check each field on its own, but not
+        "a sun trigger needs an event and a time trigger needs a time". Left to
+        runtime the symptom is a schedule that quietly never fires, which is
+        the hardest kind of misconfiguration to notice.
+        """
+        if not isinstance(value, dict):
+            return
+
+        trigger = value.get("trigger") or {}
+        kind = trigger.get("type", "sun")
+
+        if kind == "sun":
+            from boneio.core.utils.sun import ANCHOR_NAMES
+
+            event = trigger.get("event")
+            if not event:
+                self._error(  # type: ignore[attr-defined]
+                    field, "A sun trigger needs an 'event', e.g. sunset or civil_dusk."
+                )
+            elif event not in ANCHOR_NAMES:
+                self._error(  # type: ignore[attr-defined]
+                    field,
+                    f"Unknown sun event {event!r}. "
+                    f"Expected one of: {', '.join(sorted(ANCHOR_NAMES))}.",
+                )
+            if trigger.get("at"):
+                self._error(  # type: ignore[attr-defined]
+                    field, "'at' belongs to a time trigger, not a sun trigger."
+                )
+        elif kind == "time":
+            if not trigger.get("at"):
+                self._error(  # type: ignore[attr-defined]
+                    field, "A time trigger needs 'at' in HH:MM."
+                )
+            if trigger.get("event"):
+                self._error(  # type: ignore[attr-defined]
+                    field, "'event' belongs to a sun trigger, not a time trigger."
+                )
+
+        if not value.get("actions"):
+            self._error(  # type: ignore[attr-defined]
+                field, "A schedule with no actions would fire and do nothing."
+            )
+
+    def _check_with_condition_shape(self, field, value):
+        """Reject a condition whose fields do not match its own type.
+
+        Cerberus can say "this is a dict of allowed keys" but not "a sun
+        condition is one of three shapes and never a mixture". Without this a
+        typo like ``type: sun`` with ``after: "05:00"`` reaches runtime, where
+        the only symptom is an action that silently never fires.
+        """
+        if not isinstance(value, dict):
+            return
+        if value.get("type") != "sun":
+            return
+
+        from boneio.core.utils.sun import ANCHOR_NAMES, PHASE_NAMES
+
+        window = [key for key in ("after", "before") if value.get(key)]
+        phase = value.get("phase")
+        elevation = [key for key in ("above", "below") if value.get(key) is not None]
+
+        modes = [bool(window), bool(phase), bool(elevation)]
+        if sum(modes) == 0:
+            self._error(  # type: ignore[attr-defined]
+                field,
+                "A sun condition needs one of: after/before (anchors), "
+                "phase, or above/below (elevation in degrees).",
+            )
+            return
+        if sum(modes) > 1:
+            self._error(  # type: ignore[attr-defined]
+                field,
+                "A sun condition must use only one of after/before, phase, or "
+                "above/below — not a mixture.",
+            )
+            return
+
+        for key in ("after", "before"):
+            anchor = value.get(key)
+            if anchor and anchor not in ANCHOR_NAMES:
+                self._error(  # type: ignore[attr-defined]
+                    field,
+                    f"Unknown sun anchor {anchor!r} in '{key}'. "
+                    f"Expected one of: {', '.join(sorted(ANCHOR_NAMES))}.",
+                )
+
+        for key, other in (("after_offset", "after"), ("before_offset", "before")):
+            if value.get(key) and not value.get(other):
+                self._error(  # type: ignore[attr-defined]
+                    field, f"'{key}' has no effect without '{other}'."
+                )
+
+        if phase and phase not in PHASE_NAMES:
+            self._error(  # type: ignore[attr-defined]
+                field,
+                f"Unknown sun phase {phase!r}. "
+                f"Expected one of: {', '.join(sorted(PHASE_NAMES))}.",
+            )
+
+        above, below = value.get("above"), value.get("below")
+        if above is not None and below is not None and above >= below:
+            self._error(  # type: ignore[attr-defined]
+                field,
+                f"'above' ({above}) must be lower than 'below' ({below}); "
+                "the pair describes a band of elevations.",
+            )
+
     def _lookup_field(self, path: str) -> tuple:
         """
         Implement relative paths with dot (.) notation, following Python

{boneio-1.6.0.dev2 → boneio-1.6.0.dev4}/boneio/core/manager/action_conditions.py

@@ -8,6 +8,8 @@ Optimisations over the generic conditions.py:
   - datetime.now() is called ONCE per execute_actions() batch
   - time/date strings are parsed once (at config load) rather than each press
   - state_resolver results can be cached within an evaluation cycle
+  - sun conditions hold the provider, which caches a day of anchors, so a
+    button press reads two datetimes instead of computing ephemerides
   - dedicated logger `boneio.action_conditions` for easy filtering
 
 Usage:
@@ -21,9 +23,14 @@ from __future__ import annotations
 
 import logging
 from collections.abc import Callable
-from datetime import datetime
+from datetime import datetime, timedelta
 from datetime import time as dt_time
-from typing import Any
+from typing import TYPE_CHECKING, Any
+
+from boneio.core.utils import sun as sun_utils
+
+if TYPE_CHECKING:
+    from boneio.core.manager.sun import SunProvider
 
 _LOGGER = logging.getLogger("boneio.action_conditions")
 
@@ -90,6 +97,170 @@ class _DateCondition:
         return True
 
 
+class _SunCondition:
+    """Pre-parsed sun condition: a window between anchors, a phase, or an angle.
+
+    Nothing is computed here at compile time. Anchor *times* change every day,
+    so the only thing worth pre-resolving is which anchors were asked for; the
+    provider hands back a cached day at evaluation time.
+    """
+
+    __slots__ = (
+        "mode",
+        "after",
+        "after_offset",
+        "before",
+        "before_offset",
+        "phase",
+        "above",
+        "below",
+        "_provider",
+        "_warned",
+    )
+
+    def __init__(
+        self,
+        provider: SunProvider | None,
+        *,
+        after: str | None = None,
+        after_offset: float = 0.0,
+        before: str | None = None,
+        before_offset: float = 0.0,
+        phase: str | None = None,
+        above: float | None = None,
+        below: float | None = None,
+    ) -> None:
+        self._provider = provider
+        self._warned = False
+        self.after = after
+        self.after_offset = after_offset
+        self.before = before
+        self.before_offset = before_offset
+        self.phase = phase
+        self.above = above
+        self.below = below
+        if phase:
+            self.mode = "phase"
+        elif above is not None or below is not None:
+            self.mode = "elevation"
+        else:
+            self.mode = "window"
+
+    # -- anchor resolution ------------------------------------------------
+
+    def _resolve(
+        self,
+        name: str,
+        offset: float,
+        now: datetime,
+        anchors: dict[str, datetime | None],
+        day_start: datetime,
+        day_end: datetime,
+    ) -> datetime:
+        """Turn an anchor name into an instant, polar days included.
+
+        A missing anchor is not "unknown" — it means the Sun stayed on one side
+        of that angle all day, and which side decides whether the bound should
+        collapse to the start or the end of the day. Getting this backwards is
+        how a window meant to mean "while it is dark" ends up covering a polar
+        summer.
+        """
+        moment = anchors.get(name)
+        if moment is not None:
+            return moment + timedelta(seconds=offset)
+
+        threshold, rising = sun_utils.ANCHORS.get(name, (None, True))
+        if threshold is None or self._provider is None:
+            return day_end
+
+        # `now`, not the wall clock: the day being asked about is the one the
+        # anchors came from, which is not necessarily today.
+        state = self._provider.threshold_state(threshold, now)
+        if state == "always_above":
+            # The Sun is permanently past this angle: a crossing upward is
+            # behind us, a crossing downward is still ahead.
+            return day_start if rising else day_end
+        if state == "always_below":
+            return day_end if rising else day_start
+        return day_end
+
+    # -- evaluation -------------------------------------------------------
+
+    def evaluate(self, now: datetime) -> bool:
+        """Check *now* against this condition.
+
+        Returns:
+            True when the condition holds. Also True when the Sun's position
+            cannot be known — no ``location:``, or a clock that has not been
+            set — which matches how every other condition treats a
+            configuration error: it does not block the action. The web UI
+            refuses to save a sun condition without a location, so this path
+            means something changed underneath a running device.
+        """
+        provider = self._provider
+        if provider is None or not provider.ready(now):
+            if not self._warned:
+                self._warned = True
+                _LOGGER.error(
+                    "Sun condition cannot be evaluated (no location, or the "
+                    "clock is not set yet) — allowing the action."
+                )
+            return True
+
+        if self.mode == "phase":
+            return bool(provider.in_phase(self.phase, now))
+
+        if self.mode == "elevation":
+            elevation = provider.elevation(now)
+            if elevation is None:
+                return True
+            if self.above is not None and elevation <= self.above:
+                return False
+            return not (self.below is not None and elevation >= self.below)
+
+        anchors = provider.anchors(now)
+        if not anchors:
+            return True
+
+        local = now.astimezone(provider.timezone)
+        day_start = local.replace(hour=0, minute=0, second=0, microsecond=0)
+        day_end = day_start + timedelta(days=1)
+
+        start = (
+            self._resolve(
+                self.after, self.after_offset, now, anchors, day_start, day_end
+            )
+            if self.after
+            else None
+        )
+        end = (
+            self._resolve(
+                self.before, self.before_offset, now, anchors, day_start, day_end
+            )
+            if self.before
+            else None
+        )
+
+        if start is not None and end is not None:
+            if start <= end:
+                return start <= now < end
+            # Crosses midnight, e.g. sunset → sunrise. Same rule as a time
+            # window, and the same rule that makes a polar-night window empty.
+            return now >= start or now < end
+        if start is not None:
+            return now >= start
+        if end is not None:
+            return now < end
+        return True
+
+    def __repr__(self) -> str:  # pragma: no cover - diagnostics only
+        if self.mode == "phase":
+            return f"<sun phase={self.phase}>"
+        if self.mode == "elevation":
+            return f"<sun above={self.above} below={self.below}>"
+        return f"<sun {self.after}+{self.after_offset:g}s .. {self.before}+{self.before_offset:g}s>"
+
+
 class _StateCondition:
     """Pre-parsed state condition with compile-time resolved evaluator.
     
@@ -190,7 +361,7 @@ class _ConditionGroup:
 
     def __init__(
         self,
-        items: list[_TimeCondition | _DateCondition | _StateCondition],
+        items: list[_TimeCondition | _DateCondition | _StateCondition | _SunCondition],
         use_all: bool,
     ) -> None:
         self.items = items
@@ -212,7 +383,7 @@ class _ConditionGroup:
 
 
 def _eval_single(
-    cond: _TimeCondition | _DateCondition | _StateCondition,
+    cond: _TimeCondition | _DateCondition | _StateCondition | _SunCondition,
     now: datetime,
     state_resolver: Callable[[str, str], Any] | None,
 ) -> bool:
@@ -221,6 +392,8 @@ def _eval_single(
         return cond.evaluate(now)
     if isinstance(cond, _DateCondition):
         return cond.evaluate(now)
+    if isinstance(cond, _SunCondition):
+        return cond.evaluate(now)
     if isinstance(cond, _StateCondition):
         return cond.evaluate(state_resolver)
     return True
@@ -248,13 +421,32 @@ def _parse_date(s: str) -> tuple[int, int]:
     raise ValueError(f"Invalid date format: '{s}'")
 
 
-def _compile_single(raw: dict) -> _TimeCondition | _DateCondition | _StateCondition | None:
+def _compile_single(
+    raw: dict,
+    sun_provider: SunProvider | None = None,
+) -> _TimeCondition | _DateCondition | _StateCondition | _SunCondition | None:
     """Compile a single condition dict into a fast evaluator.
 
-    Returns None if the condition is invalid (logs a warning).
+    Args:
+        raw: One condition from the config.
+        sun_provider: The manager's provider, needed only by sun conditions.
+
+    Returns:
+        A compiled condition, or None if it is invalid (logs an error).
     """
     ctype = raw.get("type")
     try:
+        if ctype == "sun":
+            return _SunCondition(
+                sun_provider,
+                after=raw.get("after"),
+                after_offset=float(raw.get("after_offset") or 0.0),
+                before=raw.get("before"),
+                before_offset=float(raw.get("before_offset") or 0.0),
+                phase=raw.get("phase"),
+                above=None if raw.get("above") is None else float(raw["above"]),
+                below=None if raw.get("below") is None else float(raw["below"]),
+            )
         if ctype == "time":
             after = _parse_time(raw["after"]) if raw.get("after") else None
             before = _parse_time(raw["before"]) if raw.get("before") else None
@@ -283,7 +475,8 @@ def _compile_single(raw: dict) -> _TimeCondition | _DateCondition | _StateCondit
 
 def precompile_conditions(
     action_definition: dict,
-) -> _ConditionGroup | _TimeCondition | _DateCondition | _StateCondition | None:
+    sun_provider: SunProvider | None = None,
+) -> _ConditionGroup | _TimeCondition | _DateCondition | _StateCondition | _SunCondition | None:
     """Pre-compile conditions from a parsed action definition.
 
     Call this once (at config load / parse_actions time) and store the
@@ -292,6 +485,9 @@ def precompile_conditions(
     Args:
         action_definition: A single action dict that may contain
             ``condition`` (single) or ``conditions`` (group).
+        sun_provider: The manager's :class:`SunProvider`. Held by reference, so
+            reconfiguring the location reaches conditions that were compiled
+            before the change without recompiling them.
 
     Returns:
         A compiled condition object, or None if there are no conditions.
@@ -300,7 +496,7 @@ def precompile_conditions(
     multi = action_definition.get("conditions")
 
     if single:
-        return _compile_single(single)
+        return _compile_single(single, sun_provider)
 
     if multi:
         mode = multi.get("mode", "and")
@@ -309,7 +505,7 @@ def precompile_conditions(
             return None
         compiled = []
         for raw in cond_list:
-            item = _compile_single(raw)
+            item = _compile_single(raw, sun_provider)
             if item is not None:
                 compiled.append(item)
         if not compiled:
@@ -324,6 +520,7 @@ def should_execute_action(
     | _TimeCondition
     | _DateCondition
     | _StateCondition
+    | _SunCondition
     | None,
     now: datetime,
     state_resolver: Callable[[str, str], Any] | None = None,