boneio 1.6.0.dev2__tar.gz → 1.6.0.dev3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boneio
-Version: 1.6.0.dev2
+Version: 1.6.0.dev3
 Summary: Python App for BoneIO
 Author-email: Paweł Szafer <pszafer@gmail.com>
 License: GNU General Public License v3.0

{boneio-1.6.0.dev2 → boneio-1.6.0.dev3}/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.dev3}/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,

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

@@ -49,8 +49,10 @@ from boneio.core.manager.irrigation import IrrigationManager
 from boneio.core.manager.modbus import ModbusManager
 from boneio.core.manager.outputs import OutputManager
 from boneio.core.manager.remote import RemoteDeviceManager
+from boneio.core.manager.scheduler import Scheduler
 from boneio.core.manager.security_alert import SecurityAlertPublisher
 from boneio.core.manager.sensors import SensorManager
+from boneio.core.manager.sun import SunProvider
 from boneio.core.manager.templates import TemplateManager
 from boneio.core.manager.update import UpdateManager
 from boneio.core.messaging import MessageBus
@@ -130,6 +132,8 @@ class Manager:
         irrigation: list[dict] | None = None,
         remote_devices: list[dict] | None = None,
         can: dict[str, Any] | None = None,
+        location: dict[str, Any] | None = None,
+        schedule: list[dict] | None = None,
         web_active: bool = False,
         web_port: int = 8090,
         early_oled_device: Any | None = None,
@@ -165,6 +169,11 @@ class Manager:
         self._config_file_path = config_file_path
         self._topic_prefix = config_helper.topic_prefix
 
+        # Where the Sun is. Built even when `location:` is absent: an
+        # unconfigured provider answers "not ready" and says so once, which is
+        # what every caller has to handle anyway.
+        self.sun = SunProvider(location)
+
         # Reports outstanding security recommendations to Home Assistant.
         self.security_alert = SecurityAlertPublisher(self)
 
@@ -300,6 +309,13 @@ class Manager:
             irrigation_config=merged_irrigation,
         )
 
+        # 13. Scheduler — actions that fire on their own. Built here because
+        # parsing its actions needs the outputs and covers to exist, and armed
+        # from a task because the first thing it does is look at the clock.
+        self.scheduler = Scheduler(manager=self, schedules=schedule or [])
+        if schedule:
+            self.append_task(coro=self.scheduler.start, name="scheduler")
+
         # Configure virtual energy sensors (must be after outputs are initialized)
         self.sensors.configure_virtual_energy_sensors()
 
@@ -613,6 +629,14 @@ class Manager:
             except Exception as e:
                 _LOGGER.debug("Error re-publishing sensor state %s: %s", sensor.id, e)
 
+        # Sun sensors. A broker that has just come back has no retained value
+        # for them, and the next scheduled update could be a minute away.
+        for sensor in self.sensors.get_sun_sensors():
+            try:
+                await sensor.async_update(timestamp)
+            except Exception as e:
+                _LOGGER.debug("Error re-publishing sensor state %s: %s", sensor.id, e)
+
     def publish_ha_discovery(
         self,
         id: str,
@@ -684,7 +708,7 @@ class Manager:
                 if action_definition.get(key) is not None:
                     parsed_action[key] = action_definition[key]
             # Pre-compile conditions for fast evaluation at action time
-            compiled = precompile_conditions(parsed_action)
+            compiled = precompile_conditions(parsed_action, self.sun)
             if compiled is not None:
                 parsed_action["_compiled_conditions"] = compiled
 
@@ -902,8 +926,12 @@ class Manager:
 
         duration_ms = (duration or 0) * 1000  # Convert to ms
 
-        # Compute datetime once for all condition evaluations in this batch
-        now_dt = datetime.now()
+        # Compute datetime once for all condition evaluations in this batch.
+        # Aware, not naive: sun anchors are born as aware UTC, and comparing
+        # them against a naive local time would be ambiguous in the hour the
+        # clock goes back. `.time()` and `.month` behave identically on an
+        # aware local datetime, so the time and date conditions are unaffected.
+        now_dt = datetime.now().astimezone()
 
         for idx, action_definition in enumerate(actions):
             is_repeat = action_definition.get("repeat", False)
@@ -1293,6 +1321,26 @@ class Manager:
         finally:
             self._pending_tilt_restores.pop(task_key, None)
 
+    async def _reload_schedule(self) -> None:
+        """Adopt a new schedule section, disarming whatever was armed before."""
+        config = self._config_helper.get_config() or {}
+        await self.scheduler.reload(config.get("schedule") or [])
+        # A device that started with no schedules never started the supervisor.
+        await self.scheduler.start()
+
+    def _reload_location(self) -> None:
+        """Adopt new coordinates and drop every cached sun answer.
+
+        Cheap enough to be synchronous: the provider recomputes lazily, so this
+        is a configure call and three cache clears.
+        """
+        config = self._config_helper.get_config() or {}
+        self.sun.configure(config.get("location"))
+        # Coordinates may have just appeared, in which case the sun sensors
+        # were never built. Existing ones need nothing: they read the provider
+        # on every update, so new coordinates reach them by themselves.
+        self.sensors.configure_sun_sensors()
+
     def _reload_logger(self) -> None:
         """Reload logger configuration from config file.
 
@@ -1704,6 +1752,8 @@ class Manager:
             "irrigation": self.irrigation.reload_irrigation,  # Irrigation controllers
             "adc": self.sensors.reload_adc_sensors,  # ADC analog sensors
             "areas": lambda: None,  # Areas are already reloaded in reload_config above
+            "location": self._reload_location,  # Coordinates for sun-based features
+            "schedule": self._reload_schedule,  # Time and sun driven schedules
             "oled": self.display.reload_oled,  # OLED display screens, screensaver
         }