hassreactor 0.2.0__tar.gz

hassreactor-0.2.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: hassreactor
+Version: 0.2.0
+Summary: Event-driven Home Assistant automations in Python
+Home-page: https://github.com/N4S4/hassreactor
+Author: Renato Visaggio
+Author-email: synology.python.api@gmail.com
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: aiohttp>=3.8
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# hassreactor
+
+Event-driven Home Assistant automations in Python. No YAML, no Node-RED, no AppDaemon — just Python.
+
+## Why
+
+Home Assistant has a powerful automation engine, but it lives in YAML or a UI. Sometimes you just want to write a Python script:
+
+- "If living room temp > 28°C, turn on fan"
+- "If front door opens, send me a Telegram message"
+- "Every hour, log the temperature"
+
+hassreactor lets you write these as plain Python files using WebSocket events — no polling, no complex setup.
+
+## Install
+
+```bash
+pip install hassreactor
+```
+
+## Quick Start
+
+Create a file `automations.py`:
+
+```python
+from hassreactor import Reactor
+
+app = Reactor("http://homeassistant:8123", "your-long-lived-token")
+
+@app.when("sensor.temperatura_salotto", above=28)
+async def accendi_ventilatore(event):
+    """When temp goes above 28°C, turn on the fan."""
+    await app.fan.turn_on(entity_id="fan.ventilatore")
+
+@app.when("binary_sensor.porta_ingresso", to="on")
+async def porta_aperta(event):
+    """When front door opens, notify."""
+    await app.notify.telegram(message="Porta d'ingresso aperta!")
+
+@app.schedule("every 1h")
+async def report():
+    temp = await app.get_state("sensor.temperatura_salotto")
+    print(f"Current temperature: {temp}°C")
+
+if __name__ == "__main__":
+    app.run()
+```
+
+Run it:
+
+```bash
+python automations.py
+```
+
+## Trigger Types
+
+| Trigger | Description |
+|---|---|
+| `@app.when(entity, above=N)` | Numeric value crosses ABOVE threshold |
+| `@app.when(entity, below=N)` | Numeric value crosses BELOW threshold |
+| `@app.when(entity, to="on")` | State changes TO an exact value |
+| `@app.when(entity, changes=True)` | ANY state change |
+| `@app.schedule("every 30m")` | Run every 30 minutes |
+| `@app.schedule("every 2h")` | Run every 2 hours |
+| `@app.schedule("0 9 * * *")` | Cron expression (every day at 9am) |
+
+## Calling Services
+
+Any HA service is available as a method on the domain:
+
+```python
+await app.light.turn_on(entity_id="light.kitchen", brightness=128)
+await app.climate.set_temperature(entity_id="climate.home", temperature=22)
+await app.switch.toggle(entity_id="switch.pump")
+await app.notify.telegram(message="Hello!")
+```
+
+## How It Works
+
+hassreactor connects to Home Assistant via **WebSocket** and subscribes to `state_changed` events. When an entity you're watching changes state, your function runs instantly — no polling, no sleep loops.
+
+Service calls use the REST API.
+
+Only dependency: `aiohttp`.
+
+## License
+
+MIT

hassreactor-0.2.0/README.md

@@ -0,0 +1,88 @@
+# hassreactor
+
+Event-driven Home Assistant automations in Python. No YAML, no Node-RED, no AppDaemon — just Python.
+
+## Why
+
+Home Assistant has a powerful automation engine, but it lives in YAML or a UI. Sometimes you just want to write a Python script:
+
+- "If living room temp > 28°C, turn on fan"
+- "If front door opens, send me a Telegram message"
+- "Every hour, log the temperature"
+
+hassreactor lets you write these as plain Python files using WebSocket events — no polling, no complex setup.
+
+## Install
+
+```bash
+pip install hassreactor
+```
+
+## Quick Start
+
+Create a file `automations.py`:
+
+```python
+from hassreactor import Reactor
+
+app = Reactor("http://homeassistant:8123", "your-long-lived-token")
+
+@app.when("sensor.temperatura_salotto", above=28)
+async def accendi_ventilatore(event):
+    """When temp goes above 28°C, turn on the fan."""
+    await app.fan.turn_on(entity_id="fan.ventilatore")
+
+@app.when("binary_sensor.porta_ingresso", to="on")
+async def porta_aperta(event):
+    """When front door opens, notify."""
+    await app.notify.telegram(message="Porta d'ingresso aperta!")
+
+@app.schedule("every 1h")
+async def report():
+    temp = await app.get_state("sensor.temperatura_salotto")
+    print(f"Current temperature: {temp}°C")
+
+if __name__ == "__main__":
+    app.run()
+```
+
+Run it:
+
+```bash
+python automations.py
+```
+
+## Trigger Types
+
+| Trigger | Description |
+|---|---|
+| `@app.when(entity, above=N)` | Numeric value crosses ABOVE threshold |
+| `@app.when(entity, below=N)` | Numeric value crosses BELOW threshold |
+| `@app.when(entity, to="on")` | State changes TO an exact value |
+| `@app.when(entity, changes=True)` | ANY state change |
+| `@app.schedule("every 30m")` | Run every 30 minutes |
+| `@app.schedule("every 2h")` | Run every 2 hours |
+| `@app.schedule("0 9 * * *")` | Cron expression (every day at 9am) |
+
+## Calling Services
+
+Any HA service is available as a method on the domain:
+
+```python
+await app.light.turn_on(entity_id="light.kitchen", brightness=128)
+await app.climate.set_temperature(entity_id="climate.home", temperature=22)
+await app.switch.toggle(entity_id="switch.pump")
+await app.notify.telegram(message="Hello!")
+```
+
+## How It Works
+
+hassreactor connects to Home Assistant via **WebSocket** and subscribes to `state_changed` events. When an entity you're watching changes state, your function runs instantly — no polling, no sleep loops.
+
+Service calls use the REST API.
+
+Only dependency: `aiohttp`.
+
+## License
+
+MIT

hassreactor-0.2.0/hassreactor/__init__.py

@@ -0,0 +1,6 @@
+"""hassreactor — Event-driven Home Assistant automations in Python."""
+
+from .reactor import Reactor, TriggerEvent
+
+__version__ = "0.1.1"
+__all__ = ["Reactor", "TriggerEvent"]

hassreactor-0.2.0/hassreactor/domain_proxy.py

@@ -0,0 +1,67 @@
+"""
+Domain proxy for fluent service calls.
+
+Provides `app.light.turn_on(...)` style API by dynamically
+generating proxy objects for each Home Assistant domain.
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .engine import EventEngine
+
+
+class _DomainProxy:
+    """Proxy for a single HA domain (light, switch, climate, etc.).
+
+    Service calls become method calls:
+        app.light.turn_on(entity_id='light.kitchen')
+    """
+
+    def __init__(self, engine: "EventEngine", domain: str):
+        self._engine = engine
+        self._domain = domain
+
+    def __getattr__(self, service: str):
+        """Return a callable that invokes the service."""
+        if service.startswith("_"):
+            raise AttributeError(service)
+
+        async def _call(**kwargs):
+            data = {k: v for k, v in kwargs.items() if k not in ("entity_id",)}
+            target = None
+            if "entity_id" in kwargs:
+                target = {"entity_id": kwargs["entity_id"]}
+            return await self._engine.call_service(
+                self._domain, service, data=data, target=target
+            )
+
+        return _call
+
+    def __dir__(self):
+        return []  # Dynamic — auto-complete not supported
+
+
+class DomainProxy:
+    """Top-level proxy that returns _DomainProxy instances.
+
+    Usage:
+        app = DomainProxy(engine)
+        await app.light.turn_on(entity_id='light.kitchen')
+        await app.climate.set_temperature(entity_id='climate.home', temperature=22)
+    """
+
+    def __init__(self, engine: "EventEngine"):
+        self._engine = engine
+        self._cache: dict[str, _DomainProxy] = {}
+
+    def __getattr__(self, domain: str) -> _DomainProxy:
+        if domain.startswith("_"):
+            raise AttributeError(domain)
+        if domain not in self._cache:
+            self._cache[domain] = _DomainProxy(self._engine, domain)
+        return self._cache[domain]
+
+    def __getitem__(self, domain: str) -> _DomainProxy:
+        return self.__getattr__(domain)

hassreactor-0.2.0/hassreactor/engine.py

@@ -0,0 +1,188 @@
+"""
+WebSocket event engine for Home Assistant.
+
+Handles authentication, subscription to state_changed events,
+and dispatches to registered triggers.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from typing import Any, Callable, Awaitable
+
+import aiohttp
+
+logger = logging.getLogger("hassreactor.engine")
+
+
+class EventEngine:
+    """Low-level WebSocket client for Home Assistant."""
+
+    def __init__(self, url: str, token: str, verify_ssl: bool = True):
+        if not url.startswith(("http://", "https://")):
+            url = f"http://{url}"
+        url = url.rstrip("/")
+        self._http_url = url
+        self._ws_url = url.replace("http://", "ws://").replace("https://", "wss://")
+        self._ws_url = f"{self._ws_url}/api/websocket"
+        self._token = token
+        self._verify_ssl = verify_ssl
+        self._msg_id = 0
+        self._session: aiohttp.ClientSession | None = None
+        self._ws: aiohttp.ClientWebSocketResponse | None = None
+        self._listeners: dict[str, list[Callable[[dict], Awaitable[None]]]] = {}
+        self._result_futures: dict[int, asyncio.Future] = {}
+        self._running = False
+        self._connected = False
+
+    # -- public API -----------------------------------------------------------
+
+    @property
+    def connected(self) -> bool:
+        return self._connected
+
+    async def connect(self) -> None:
+        """Authenticate and start listening."""
+        self._session = aiohttp.ClientSession()
+        self._ws = await self._session.ws_connect(
+            self._ws_url, verify_ssl=self._verify_ssl
+        )
+
+        # Read auth required message
+        auth_msg = await self._ws.receive_json()
+        if auth_msg.get("type") != "auth_required":
+            raise RuntimeError(f"Unexpected message: {auth_msg}")
+
+        # Authenticate
+        await self._ws.send_json({
+            "type": "auth",
+            "access_token": self._token,
+        })
+        auth_result = await self._ws.receive_json()
+        if auth_result.get("type") != "auth_ok":
+            raise RuntimeError(f"Auth failed: {auth_result}")
+
+        # Subscribe to state_changed events
+        sub_id = self._next_id()
+        await self._ws.send_json({
+            "id": sub_id,
+            "type": "subscribe_events",
+            "event_type": "state_changed",
+        })
+        sub_result = await self._ws.receive_json()
+        if not sub_result.get("success"):
+            raise RuntimeError(f"Subscribe failed: {sub_result}")
+
+        self._connected = True
+        self._running = True
+        logger.info("Connected to Home Assistant WebSocket")
+        asyncio.create_task(self._listen_loop())
+
+    async def disconnect(self) -> None:
+        """Close the WebSocket connection."""
+        self._running = False
+        self._connected = False
+        if self._ws and not self._ws.closed:
+            await self._ws.close()
+        if self._session:
+            await self._session.close()
+        logger.info("Disconnected from Home Assistant")
+
+    async def call_service(
+        self, domain: str, service: str, data: dict | None = None,
+        target: dict | None = None,
+    ) -> dict:
+        """Call a Home Assistant service via REST API."""
+        url = f"{self._http_url}/api/services/{domain}/{service}"
+        body: dict[str, Any] = {}
+        if data:
+            body = dict(data)
+        if target:
+            body["target"] = target
+        async with self._session.post(
+            url, json=body,
+            headers={"Authorization": f"Bearer {self._token}"},
+            verify_ssl=self._verify_ssl,
+        ) as resp:
+            return await resp.json()
+
+    async def get_states(self) -> list[dict]:
+        """Get all entity states via REST API."""
+        url = f"{self._http_url}/api/states"
+        async with self._session.get(
+            url,
+            headers={"Authorization": f"Bearer {self._token}"},
+            verify_ssl=self._verify_ssl,
+        ) as resp:
+            return await resp.json()
+
+    async def get_state(self, entity_id: str) -> dict | None:
+        """Get single entity state."""
+        url = f"{self._http_url}/api/states/{entity_id}"
+        async with self._session.get(
+            url,
+            headers={"Authorization": f"Bearer {self._token}"},
+            verify_ssl=self._verify_ssl,
+        ) as resp:
+            if resp.status == 404:
+                return None
+            return await resp.json()
+
+    def on_state_change(
+        self, entity_id: str, callback: Callable[[dict], Awaitable[None]],
+    ) -> None:
+        """Register a callback for state_changed events on a specific entity."""
+        if entity_id not in self._listeners:
+            self._listeners[entity_id] = []
+        self._listeners[entity_id].append(callback)
+
+    # -- internal -------------------------------------------------------------
+
+    def _next_id(self) -> int:
+        self._msg_id += 1
+        return self._msg_id
+
+    async def _listen_loop(self) -> None:
+        """Long-running loop: read WebSocket messages and dispatch."""
+        while self._running:
+            try:
+                ws_msg = await asyncio.wait_for(self._ws.receive(), timeout=30)
+            except asyncio.TimeoutError:
+                continue
+            except Exception:
+                logger.exception("WebSocket read error")
+                break
+
+            # Home Assistant sends binary frames (pings). Skip them.
+            if ws_msg.type != aiohttp.WSMsgType.TEXT:
+                continue
+
+            try:
+                msg = json.loads(ws_msg.data)
+            except (json.JSONDecodeError, TypeError):
+                logger.warning("Invalid JSON in WebSocket message")
+                continue
+
+            msg_type = msg.get("type")
+            if msg_type == "event":
+                event = msg.get("event", {})
+                if event.get("event_type") == "state_changed":
+                    data = event.get("data", {})
+                    entity_id = data.get("entity_id", "")
+                    # Dispatch to listeners
+                    callbacks = self._listeners.get(entity_id, [])
+                    for cb in callbacks:
+                        try:
+                            await cb(data)
+                        except Exception:
+                            logger.exception(
+                                "Error in listener for %s", entity_id
+                            )
+            elif msg_type == "result":
+                msg_id = msg.get("id")
+                future = self._result_futures.pop(msg_id, None)
+                if future:
+                    future.set_result(msg)
+
+        self._connected = False

hassreactor-0.2.0/hassreactor/reactor.py

@@ -0,0 +1,267 @@
+"""
+Reactor — the main entry point for hassreactor.
+
+Ties together the WebSocket engine, service proxy, and scheduler
+into a single, ergonomic interface for writing Home Assistant
+automations in Python.
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+import signal
+from typing import Any, Callable, Awaitable
+
+from .domain_proxy import DomainProxy
+from .engine import EventEngine
+from .scheduler import Scheduler
+
+
+class TriggerEvent:
+    """Event passed to @app.when callbacks."""
+
+    def __init__(self, engine: EventEngine, event_data: dict):
+        self.entity_id: str = event_data.get("entity_id", "")
+        self.old_state: dict | None = event_data.get("old_state")
+        self.new_state: dict | None = event_data.get("new_state")
+
+        # Convenience: new state value as string
+        ns = self.new_state or {}
+        self.state: str = ns.get("state", "")
+        self.attributes: dict = ns.get("attributes", {})
+
+    def __repr__(self) -> str:
+        return (
+            f"TriggerEvent(entity_id={self.entity_id!r}, "
+            f"state={self.state!r})"
+        )
+
+
+class Reactor:
+    """Main application class for hassreactor.
+
+    Usage::
+
+        app = Reactor("http://ha:8123", "token")
+
+        @app.when("sensor.temp", above=28)
+        async def hot(event):
+            await app.fan.turn_on(entity_id="fan.ventilatore")
+
+        if __name__ == "__main__":
+            app.run()
+    """
+
+    def __init__(
+        self,
+        url: str,
+        token: str,
+        verify_ssl: bool = True,
+    ):
+        self._engine = EventEngine(url, token, verify_ssl=verify_ssl)
+        self._proxy = DomainProxy(self._engine)
+        self._scheduler = Scheduler()
+        self._triggers: list[tuple[str, dict, Callable]] = []
+        self._running = False
+        self.log = logging.getLogger("hassreactor")
+
+    # -- domain access ---------------------------------------------------------
+
+    def __getattr__(self, name: str):
+        """Proxy unknown attrs to the domain proxy.
+
+        Example: app.light → DomainProxy(engine).light
+        """
+        if name.startswith("_"):
+            raise AttributeError(name)
+        # Check if it's a known domain or delegate to proxy
+        return getattr(self._proxy, name)
+
+    # -- decorators -----------------------------------------------------------
+
+    def when(
+        self,
+        entity_id: str,
+        *,
+        above: float | None = None,
+        below: float | None = None,
+        to: str | None = None,
+        changes: bool = False,
+    ):
+        """Decorator: trigger on state changes.
+
+        Args:
+            entity_id: HA entity to watch (e.g. 'sensor.temp')
+            above: Fire when numeric state goes ABOVE this value
+            below: Fire when numeric state goes BELOW this value
+            to: Fire when state changes TO this exact value
+            changes: Fire on ANY state change
+
+        Example::
+
+            @app.when("sensor.temp", above=28)
+            async def hot(event):
+                await app.fan.turn_on(entity_id="fan.ventilatore")
+        """
+        conditions = {}
+        if above is not None:
+            conditions["above"] = above
+        if below is not None:
+            conditions["below"] = below
+        if to is not None:
+            conditions["to"] = to
+        if changes:
+            conditions["changes"] = True
+
+        def decorator(fn: Callable):
+            self._triggers.append((entity_id, conditions, fn))
+            return fn
+
+        return decorator
+
+    def schedule(self, expression: str):
+        """Decorator: run on a schedule.
+
+        Args:
+            expression: "every 30m", "every 2h", or "0 9 * * *"
+
+        Example::
+
+            @app.schedule("every 1h")
+            async def report():
+                temp = await app.get_state("sensor.temp")
+                app.log.info("Temp: %s", temp)
+        """
+
+        def decorator(fn: Callable):
+            self._scheduler.add(expression, fn)
+            return fn
+
+        return decorator
+
+    # -- state access ----------------------------------------------------------
+
+    async def get_state(self, entity_id: str) -> str | None:
+        """Get current state value of an entity."""
+        s = await self._engine.get_state(entity_id)
+        if s:
+            return s.get("state")
+        return None
+
+    async def get_states(self) -> list[dict]:
+        """Get all entity states."""
+        return await self._engine.get_states()
+
+    # -- lifecycle ------------------------------------------------------------
+
+    def run(self) -> None:
+        """Start the reactor (blocking)."""
+        try:
+            asyncio.run(self._run())
+        except KeyboardInterrupt:
+            self.log.info("Shutting down...")
+
+    async def start(self) -> None:
+        """Start the reactor (non-blocking). Call from async context."""
+        await self._connect()
+
+    async def stop(self) -> None:
+        """Stop the reactor."""
+        await self._shutdown()
+
+    # -- internal -------------------------------------------------------------
+
+    async def _run(self) -> None:
+        await self._connect()
+
+        # Keep alive until signal
+        loop = asyncio.get_running_loop()
+        stop_event = asyncio.Event()
+
+        for sig in (signal.SIGINT, signal.SIGTERM):
+            try:
+                loop.add_signal_handler(sig, stop_event.set)
+            except NotImplementedError:
+                pass  # Windows
+
+        try:
+            await stop_event.wait()
+        finally:
+            await self._shutdown()
+
+    async def _connect(self) -> None:
+        await self._engine.connect()
+
+        # Register all triggers
+        for entity_id, conditions, fn in self._triggers:
+            self._engine.on_state_change(
+                entity_id,
+                self._make_listener(entity_id, conditions, fn),
+            )
+
+        self._running = True
+        self.log.info("Reactor running — %d triggers active", len(self._triggers))
+
+    def _make_listener(
+        self, entity_id: str, conditions: dict, fn: Callable,
+    ):
+        """Build a closure that filters events and calls the user function."""
+
+        async def listener(data: dict):
+            event = TriggerEvent(self._engine, data)
+
+            # Check conditions
+            if not conditions:
+                return  # Should not happen
+
+            # "changes" — fire on any state change
+            if conditions.get("changes"):
+                await fn(event)
+                return
+
+            new_state = data.get("new_state")
+            if not new_state:
+                return
+
+            state_val = new_state.get("state", "")
+
+            # "to" — exact state match
+            if "to" in conditions:
+                if state_val == conditions["to"]:
+                    await fn(event)
+                return
+
+            # "above" / "below" — numeric comparisons
+            try:
+                num_val = float(state_val)
+            except (TypeError, ValueError):
+                return
+
+            if "above" in conditions:
+                old_state = data.get("old_state") or {}
+                old_val = old_state.get("state", "")
+                try:
+                    old_num = float(old_val)
+                except (TypeError, ValueError):
+                    old_num = float("-inf")
+                # Fire only on crossing the threshold (not every poll while above)
+                if num_val > conditions["above"] and old_num <= conditions["above"]:
+                    await fn(event)
+
+            if "below" in conditions:
+                old_state = data.get("old_state") or {}
+                old_val = old_state.get("state", "")
+                try:
+                    old_num = float(old_val)
+                except (TypeError, ValueError):
+                    old_num = float("inf")
+                if num_val < conditions["below"] and old_num >= conditions["below"]:
+                    await fn(event)
+
+        return listener
+
+    async def _shutdown(self) -> None:
+        self._running = False
+        self._scheduler.cancel_all()
+        await self._engine.disconnect()
+        self.log.info("Reactor stopped")

hassreactor-0.2.0/hassreactor/scheduler.py

@@ -0,0 +1,165 @@
+"""
+Lightweight cron-like scheduler for recurring tasks.
+
+Supports human-readable intervals:
+    @app.schedule("every 30m")
+    @app.schedule("every 2h")
+    @app.schedule("every 1h 30m")
+    @app.schedule("0 9 * * *")        # cron expression
+    @app.schedule("*/5 * * * *")      # every 5 minutes via cron
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+import re
+import time
+from typing import Callable, Awaitable
+
+logger = logging.getLogger("hassreactor.scheduler")
+
+# Pre-compiled patterns for human-readable intervals
+_RE_EVERY = re.compile(
+    r"every\s+(\d+)\s*(h|hr|hrs|hour|hours|m|min|mins|minute|minutes|s|sec|secs|second|seconds)",
+    re.IGNORECASE,
+)
+
+# 5-field cron pattern
+_RE_CRON = re.compile(
+    r"^(\*|[\d,\-*/]+)\s+(\*|[\d,\-*/]+)\s+(\*|[\d,\-*/]+)"
+    r"\s+(\*|[\d,\-*/]+)\s+(\*|[\d,\-*/]+)$"
+)
+
+
+def _parse_interval(expression: str) -> float:
+    """Parse human-readable interval into seconds.
+
+    Returns 0 if it looks like a cron expression.
+    """
+    total_seconds = 0
+    for match in _RE_EVERY.finditer(expression):
+        value = int(match.group(1))
+        unit = match.group(2).lower()[0]
+        if unit == "h":
+            total_seconds += value * 3600
+        elif unit == "m":
+            total_seconds += value * 60
+        elif unit == "s":
+            total_seconds += value
+    return total_seconds
+
+
+def _cron_matches(cron_expr: str, now: None = None) -> bool:
+    """Check if a 5-field cron expression matches the current time."""
+    if now is None:
+        now = time.localtime()
+
+    m = _RE_CRON.match(cron_expr.strip())
+    if not m:
+        return False
+
+    fields = [m.group(i) for i in range(1, 6)]
+
+    now_fields = [
+        str(now.tm_min),   # minute 0-59
+        str(now.tm_hour),  # hour 0-23
+        str(now.tm_mday),  # day 1-31
+        str(now.tm_mon),   # month 1-12
+        str(now.tm_wday),  # weekday 0-6 (Sun=0)
+    ]
+
+    for field_expr, now_val in zip(fields, now_fields):
+        if not _cron_field_matches(field_expr, now_val):
+            return False
+    return True
+
+
+def _cron_field_matches(expr: str, value: str) -> bool:
+    if expr == "*":
+        return True
+    for part in expr.split(","):
+        if "/" in part:
+            base, step = part.split("/")
+            step = int(step)
+            base = 0 if base == "*" else int(base)
+            if (int(value) - base) % step == 0 and int(value) >= base:
+                return True
+        elif "-" in part:
+            lo, hi = part.split("-")
+            if int(lo) <= int(value) <= int(hi):
+                return True
+        elif part == value:
+            return True
+    return False
+
+
+class Scheduler:
+    """Manages scheduled tasks."""
+
+    def __init__(self):
+        self._tasks: list[asyncio.Task] = []
+
+    def add(
+        self,
+        expression: str,
+        callback: Callable[[], Awaitable[None]],
+    ) -> None:
+        """Schedule a recurring task.
+
+        Args:
+            expression: "every 30m" or "0 9 * * *"
+            callback: async function to call
+        """
+        interval = _parse_interval(expression)
+        is_cron = _RE_CRON.match(expression.strip())
+
+        if interval > 0:
+            task = asyncio.create_task(_run_interval(callback, interval))
+        elif is_cron:
+            task = asyncio.create_task(_run_cron(callback, expression.strip()))
+        else:
+            raise ValueError(f"Cannot parse schedule: {expression!r}")
+
+        self._tasks.append(task)
+
+    def cancel_all(self) -> None:
+        for task in self._tasks:
+            task.cancel()
+        self._tasks.clear()
+
+
+async def _run_interval(
+    callback: Callable[[], Awaitable[None]], interval: float,
+) -> None:
+    """Run callback every `interval` seconds."""
+    # Run once immediately
+    try:
+        await callback()
+    except Exception:
+        logger.exception("Error in scheduled task")
+    while True:
+        await asyncio.sleep(interval)
+        try:
+            await callback()
+        except asyncio.CancelledError:
+            break
+        except Exception:
+            logger.exception("Error in scheduled task")
+
+
+async def _run_cron(
+    callback: Callable[[], Awaitable[None]], cron_expr: str,
+) -> None:
+    """Run callback when cron expression matches (check every 30s)."""
+    while True:
+        now = time.localtime()
+        if _cron_matches(cron_expr, now):
+            try:
+                await callback()
+            except Exception:
+                logger.exception("Error in scheduled task")
+            # Sleep past this minute to avoid double-firing
+            await asyncio.sleep(60 - now.tm_sec)
+            continue
+        # Re-check in 30s
+        await asyncio.sleep(30)

hassreactor-0.2.0/hassreactor.egg-info/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: hassreactor
+Version: 0.2.0
+Summary: Event-driven Home Assistant automations in Python
+Home-page: https://github.com/N4S4/hassreactor
+Author: Renato Visaggio
+Author-email: synology.python.api@gmail.com
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: aiohttp>=3.8
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# hassreactor
+
+Event-driven Home Assistant automations in Python. No YAML, no Node-RED, no AppDaemon — just Python.
+
+## Why
+
+Home Assistant has a powerful automation engine, but it lives in YAML or a UI. Sometimes you just want to write a Python script:
+
+- "If living room temp > 28°C, turn on fan"
+- "If front door opens, send me a Telegram message"
+- "Every hour, log the temperature"
+
+hassreactor lets you write these as plain Python files using WebSocket events — no polling, no complex setup.
+
+## Install
+
+```bash
+pip install hassreactor
+```
+
+## Quick Start
+
+Create a file `automations.py`:
+
+```python
+from hassreactor import Reactor
+
+app = Reactor("http://homeassistant:8123", "your-long-lived-token")
+
+@app.when("sensor.temperatura_salotto", above=28)
+async def accendi_ventilatore(event):
+    """When temp goes above 28°C, turn on the fan."""
+    await app.fan.turn_on(entity_id="fan.ventilatore")
+
+@app.when("binary_sensor.porta_ingresso", to="on")
+async def porta_aperta(event):
+    """When front door opens, notify."""
+    await app.notify.telegram(message="Porta d'ingresso aperta!")
+
+@app.schedule("every 1h")
+async def report():
+    temp = await app.get_state("sensor.temperatura_salotto")
+    print(f"Current temperature: {temp}°C")
+
+if __name__ == "__main__":
+    app.run()
+```
+
+Run it:
+
+```bash
+python automations.py
+```
+
+## Trigger Types
+
+| Trigger | Description |
+|---|---|
+| `@app.when(entity, above=N)` | Numeric value crosses ABOVE threshold |
+| `@app.when(entity, below=N)` | Numeric value crosses BELOW threshold |
+| `@app.when(entity, to="on")` | State changes TO an exact value |
+| `@app.when(entity, changes=True)` | ANY state change |
+| `@app.schedule("every 30m")` | Run every 30 minutes |
+| `@app.schedule("every 2h")` | Run every 2 hours |
+| `@app.schedule("0 9 * * *")` | Cron expression (every day at 9am) |
+
+## Calling Services
+
+Any HA service is available as a method on the domain:
+
+```python
+await app.light.turn_on(entity_id="light.kitchen", brightness=128)
+await app.climate.set_temperature(entity_id="climate.home", temperature=22)
+await app.switch.toggle(entity_id="switch.pump")
+await app.notify.telegram(message="Hello!")
+```
+
+## How It Works
+
+hassreactor connects to Home Assistant via **WebSocket** and subscribes to `state_changed` events. When an entity you're watching changes state, your function runs instantly — no polling, no sleep loops.
+
+Service calls use the REST API.
+
+Only dependency: `aiohttp`.
+
+## License
+
+MIT

hassreactor-0.2.0/hassreactor.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+setup.py
+hassreactor/__init__.py
+hassreactor/domain_proxy.py
+hassreactor/engine.py
+hassreactor/reactor.py
+hassreactor/scheduler.py
+hassreactor.egg-info/PKG-INFO
+hassreactor.egg-info/SOURCES.txt
+hassreactor.egg-info/dependency_links.txt
+hassreactor.egg-info/requires.txt
+hassreactor.egg-info/top_level.txt

hassreactor-0.2.0/hassreactor.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

hassreactor-0.2.0/hassreactor.egg-info/requires.txt

@@ -0,0 +1 @@
+aiohttp>=3.8

hassreactor-0.2.0/hassreactor.egg-info/top_level.txt

@@ -0,0 +1 @@
+hassreactor

hassreactor-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

hassreactor-0.2.0/setup.py

@@ -0,0 +1,37 @@
+"""
+hassreactor — Write Home Assistant automations in Python.
+
+Event-driven, WebSocket-native, no YAML required.
+"""
+from setuptools import setup, find_packages
+
+with open("README.md", encoding="utf-8") as f:
+    long_description = f.read()
+
+setup(
+    name="hassreactor",
+    version="0.2.0",
+    description="Event-driven Home Assistant automations in Python",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    author="Renato Visaggio",
+    author_email="synology.python.api@gmail.com",
+    url="https://github.com/N4S4/hassreactor",
+    packages=find_packages(),
+    python_requires=">=3.9",
+    install_requires=[
+        "aiohttp>=3.8",
+    ],
+    classifiers=[
+        "Development Status :: 3 - Alpha",
+        "Intended Audience :: Developers",
+        "License :: OSI Approved :: MIT License",
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+        "Programming Language :: Python :: 3.12",
+        "Programming Language :: Python :: 3.13",
+        "Topic :: Home Automation",
+    ],
+)