homeconnect-watcher 0.0.12.dev3__tar.gz → 0.0.14.dev1__tar.gz

{homeconnect_watcher-0.0.12.dev3 → homeconnect_watcher-0.0.14.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: homeconnect-watcher
-Version: 0.0.12.dev3
+Version: 0.0.14.dev1
 Summary: Python service that listens to HomeConnect event and logs them.
 Author-email: Rogier van der Geer <rogier@vander-geer.nl>
 License: MIT
@@ -25,6 +25,7 @@ Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
 Requires-Dist: pytest-postgresql>=5.0.0; extra == "dev"
 Provides-Extra: prometheus
 Requires-Dist: prometheus-client>=0.16.0; extra == "prometheus"
+Dynamic: license-file
 
 # homeconnect-watcher
 
@@ -35,6 +36,11 @@ Python service that listens to HomeConnect event and logs them.
 ![PyPI - License](https://img.shields.io/pypi/l/homeconnect-watcher)
 ![PyPI - Downloads](https://img.shields.io/pypi/dm/homeconnect-watcher)
 
+## Project Summary
+
+This project attempts to do two things:
+- Listen to the HomeConnect API for events, make requests to gather additional information, and save everything to file and/or a database.
+- Group the events in the database into sessions, summarizing the collected data into programs that ran on the appliance.
 
 ## Usage
 
@@ -62,8 +68,11 @@ If the watcher is used regularly, this only needs to be done once.
 Next up, run
 
 ```
-homeconnect-watcher watch
+homeconnect-watcher watch --log-path ./logs
 ```
+to start watching your appliances and write the logs to "./logs".
+
+To store the logs to a database, provide `--db-uri <uri>` with a uri to a postgres database. This will store all events to the `events` table.
 
 ## Exposing Metrics to Prometheus
 

{homeconnect_watcher-0.0.12.dev3 → homeconnect_watcher-0.0.14.dev1}/README.md

@@ -7,6 +7,11 @@ Python service that listens to HomeConnect event and logs them.
 ![PyPI - License](https://img.shields.io/pypi/l/homeconnect-watcher)
 ![PyPI - Downloads](https://img.shields.io/pypi/dm/homeconnect-watcher)
 
+## Project Summary
+
+This project attempts to do two things:
+- Listen to the HomeConnect API for events, make requests to gather additional information, and save everything to file and/or a database.
+- Group the events in the database into sessions, summarizing the collected data into programs that ran on the appliance.
 
 ## Usage
 
@@ -34,8 +39,11 @@ If the watcher is used regularly, this only needs to be done once.
 Next up, run
 
 ```
-homeconnect-watcher watch
+homeconnect-watcher watch --log-path ./logs
 ```
+to start watching your appliances and write the logs to "./logs".
+
+To store the logs to a database, provide `--db-uri <uri>` with a uri to a postgres database. This will store all events to the `events` table.
 
 ## Exposing Metrics to Prometheus
 

homeconnect_watcher-0.0.14.dev1/src/homeconnect_watcher/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.0.14.dev1'
+__version_tuple__ = version_tuple = (0, 0, 14, 'dev1')
+
+__commit_id__ = commit_id = 'gaa9ced892'

{homeconnect_watcher-0.0.12.dev3 → homeconnect_watcher-0.0.14.dev1}/src/homeconnect_watcher/client/appliance.py

@@ -15,6 +15,10 @@ class HomeConnectAppliance:
         self.appliance_type = appliance_type
         self._available_programs: list[str] | None = None
         self._last_update: dict[str, float] = dict()
+        # Request types with a deferred fetch already scheduled. Used to
+        # collapse repeated triggers (e.g. a burst of NOTIFYs all wanting
+        # `status`) into a single fetch fired when the throttle expires.
+        self._pending: set[str] = set()
 
     def __repr__(self) -> str:
         return f"HomeConnect{self.appliance_type}(ha_id={repr(self.appliance_id)})"

{homeconnect_watcher-0.0.12.dev3 → homeconnect_watcher-0.0.14.dev1}/src/homeconnect_watcher/client/client.py

@@ -1,4 +1,5 @@
-from asyncio import sleep
+from asyncio import Queue, Task, create_task, sleep
+from collections.abc import Callable, Coroutine
 from json import load, dump
 from logging import getLogger
 from os import environ
@@ -41,6 +42,8 @@ class HomeConnectClient:
         self.client.auth = self.client.token_auth  # Ensure we use token auth for all requests.
         self._appliances: list["HomeConnectAppliance"] | None = None
         self._last_event: int | None = None
+        # Outstanding deferred-fetch tasks, tracked so they are cancelled when watching stops.
+        self._deferred_tasks: set[Task] = set()
         self.metrics = metrics
         if self.metrics:
             self.metrics.set_last_event(lambda: monotonic() - self._last_event if self._last_event else -1)
@@ -91,18 +94,41 @@ class HomeConnectClient:
         """
         Watch the status of one or all appliances.
 
-        Listens to the event stream and yield all events. In addition, processes triggers of these events
-        to make requests for further details.
+        Listens to the event stream and yields all events. In addition, processes
+        triggers of these events to make requests for further details. Throttled
+        requests that can't fire immediately are deferred — a single fetch is
+        scheduled for when the throttle expires, and any further triggers within
+        that window collapse onto the same pending fetch.
 
-        Automatically reconnects when disconnected or on timeout.
+        Both stream events and deferred-fetch results land on a shared queue and
+        are yielded in arrival order. Automatically reconnects when disconnected
+        or on timeout.
         """
-        async for event in self._initial_triggers(appliance_id=appliance_id):
-            yield event
+        queue: Queue[HomeConnectEvent] = Queue()
+        producer = create_task(self._producer(queue=queue, appliance_id=appliance_id, reconnect_delay=reconnect_delay))
+        try:
+            while True:
+                event = await queue.get()
+                if self.metrics:
+                    self.metrics.increment_event_counter(event=event)
+                yield event
+        finally:
+            producer.cancel()
+            for task in list(self._deferred_tasks):
+                task.cancel()
+
+    async def _producer(self, queue: "Queue[HomeConnectEvent]", appliance_id: str | None, reconnect_delay: int) -> None:
+        """Drive the SSE stream and dispatch triggers onto the shared queue."""
+        try:
+            await self._initial_triggers(queue=queue, appliance_id=appliance_id)
+        except Exception as e:
+            # Best-effort enrichment: a failure here must not kill the producer.
+            self.logger.warning("Error while handling initial triggers.", exc_info=e)
         while True:
             try:
                 async for event in self._event_stream(appliance_id=appliance_id):
-                    async for resulting_event in self._handle_event_and_triggers(event=event):
-                        yield resulting_event
+                    await queue.put(event)
+                    await self._handle_trigger(event.trigger, queue=queue)
             except HomeConnectConnectionClosed:
                 self.logger.warning(f"Connection closed. Reconnecting in {reconnect_delay} seconds.")
                 if self.metrics:
@@ -115,6 +141,14 @@ class HomeConnectClient:
                     self.metrics.increment_disconnects(reason="timeout")
                 await sleep(reconnect_delay)
                 continue
+            except Exception as e:
+                # Catch Exception (not BaseException) so CancelledError from watch()'s
+                # shutdown still stops the producer instead of being swallowed here.
+                self.logger.warning(f"Unexpected error. Reconnecting in {reconnect_delay} seconds.", exc_info=e)
+                if self.metrics:
+                    self.metrics.increment_disconnects(reason="error")
+                await sleep(reconnect_delay)
+                continue
 
     async def _event_stream(self, appliance_id: str | None = None) -> AsyncIterable[HomeConnectEvent]:
         """
@@ -151,60 +185,84 @@ class HomeConnectClient:
                 self.logger.info("Reached end of events stream.")
                 return
 
-    async def _handle_event_and_triggers(self, event: HomeConnectEvent) -> AsyncIterable[HomeConnectEvent]:
+    async def _initial_triggers(self, queue: "Queue[HomeConnectEvent]", appliance_id: str | None) -> None:
         """
-        Handle triggers for an event and increase all corresponding counters.
-        """
-        if self.metrics:
-            self.metrics.increment_event_counter(event=event)
-        yield event
-        async for triggered_event in self._handle_trigger(event.trigger):
-            if self.metrics:
-                self.metrics.increment_event_counter(triggered_event)
-            yield triggered_event
-
-    async def _initial_triggers(self, appliance_id: str | None) -> AsyncIterable[HomeConnectEvent]:
-        """
-        Create and handle initial triggers
+        Create and handle initial triggers.
 
-        If appliance_id is not None, only create requests for the single appliance. Otherwise do so
-        for all known appliances.
+        If appliance_id is not None, only create requests for the single appliance.
+        Otherwise do so for all known appliances. Results are pushed onto `queue`.
         """
         for appliance in await self.appliances:
             if appliance_id == appliance.appliance_id or appliance_id is None:
-                async for triggered_event in self._handle_trigger(
+                await self._handle_trigger(
                     Trigger(
                         appliance_id=appliance.appliance_id,
                         status=True,
                         settings=True,
                         active_program=True,
                         selected_program=True,
-                    )
-                ):
-                    yield triggered_event
-                    if self.metrics:
-                        self.metrics.increment_event_counter(triggered_event)
+                    ),
+                    queue=queue,
+                )
 
-    async def _handle_trigger(self, trigger: Trigger | None) -> AsyncIterable[HomeConnectEvent]:
+    async def _handle_trigger(self, trigger: Trigger | None, queue: "Queue[HomeConnectEvent]") -> None:
         """
-        Handle a trigger.
+        Handle a trigger by firing or deferring the requested fetches.
+
+        Each fetch either runs immediately (when the throttle has elapsed or
+        `trigger.interval` is False) or is scheduled to run when the throttle
+        next expires. Repeated triggers landing during the deferral window
+        collapse onto the single pending task. Results land on `queue`.
         """
         if trigger is None:
             return
         appliance = await self.get_appliance(trigger.appliance_id)
-        if trigger.status:
-            if not trigger.interval or appliance.time_since_update("status") >= 300:
-                yield await appliance.get_status()
-        if trigger.settings:
-            if not trigger.interval or appliance.time_since_update("settings") >= 300:
-                yield await appliance.get_settings()
-        if await appliance.get_available_programs():  # Only if the appliance supports programs.
-            if trigger.active_program:
-                if not trigger.interval or appliance.time_since_update("active_program") >= 300:
-                    yield await appliance.get_active_program()
-            if trigger.selected_program:
-                if not trigger.interval or appliance.time_since_update("selected_program") >= 300:
-                    yield await appliance.get_selected_program()
+        fetches: list[tuple[str, bool, Callable[[], Coroutine]]] = [
+            ("status", trigger.status, appliance.get_status),
+            ("settings", trigger.settings, appliance.get_settings),
+        ]
+        # active/selected program endpoints only exist for appliances that support programs.
+        if (trigger.active_program or trigger.selected_program) and await appliance.get_available_programs():
+            fetches += [
+                ("active_program", trigger.active_program, appliance.get_active_program),
+                ("selected_program", trigger.selected_program, appliance.get_selected_program),
+            ]
+        for kind, wanted, fetch in fetches:
+            if wanted:
+                await self._fetch_or_defer(appliance, kind, fetch, throttled=trigger.interval, queue=queue)
+
+    async def _fetch_or_defer(
+        self,
+        appliance: "HomeConnectAppliance",
+        kind: str,
+        fetch: Callable[[], Coroutine],
+        throttled: bool,
+        queue: "Queue[HomeConnectEvent]",
+    ) -> None:
+        """
+        Fetch immediately if the throttle has elapsed; otherwise schedule a
+        deferred fetch for when it expires. The pending-task set on the
+        appliance deduplicates concurrent triggers for the same request type.
+        """
+        if not throttled or appliance.time_since_update(kind) >= 300:
+            await queue.put(await fetch())
+            return
+        if kind in appliance._pending:
+            return
+        appliance._pending.add(kind)
+
+        async def deferred() -> None:
+            try:
+                wait = 300 - appliance.time_since_update(kind)
+                if wait > 0:
+                    await sleep(wait)
+                await queue.put(await fetch())
+            finally:
+                appliance._pending.discard(kind)
+
+        task = create_task(deferred())
+        self._deferred_tasks.add(task)
+        task.add_done_callback(self._deferred_tasks.discard)
 
     def _load_token(self) -> OAuth2Token | None:
         """Load the OAuth token from file."""

{homeconnect_watcher-0.0.12.dev3 → homeconnect_watcher-0.0.14.dev1}/src/homeconnect_watcher/utils/metrics.py

@@ -36,6 +36,7 @@ class Metrics:
         self._disconnects = Counter("disconnects", "The number of time the connection failed.", ["reason"])
         self._disconnects.labels(reason="timeout")
         self._disconnects.labels(reason="closed")
+        self._disconnects.labels(reason="error")
         self._events = Counter("events", "Number of events.", ["appliance_id", "event"])
         self._events.labels(appliance_id=None, event="KEEP-ALIVE")
         self._info = Info("version", "Version info.")

{homeconnect_watcher-0.0.12.dev3 → homeconnect_watcher-0.0.14.dev1}/src/homeconnect_watcher.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: homeconnect-watcher
-Version: 0.0.12.dev3
+Version: 0.0.14.dev1
 Summary: Python service that listens to HomeConnect event and logs them.
 Author-email: Rogier van der Geer <rogier@vander-geer.nl>
 License: MIT
@@ -25,6 +25,7 @@ Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
 Requires-Dist: pytest-postgresql>=5.0.0; extra == "dev"
 Provides-Extra: prometheus
 Requires-Dist: prometheus-client>=0.16.0; extra == "prometheus"
+Dynamic: license-file
 
 # homeconnect-watcher
 
@@ -35,6 +36,11 @@ Python service that listens to HomeConnect event and logs them.
 ![PyPI - License](https://img.shields.io/pypi/l/homeconnect-watcher)
 ![PyPI - Downloads](https://img.shields.io/pypi/dm/homeconnect-watcher)
 
+## Project Summary
+
+This project attempts to do two things:
+- Listen to the HomeConnect API for events, make requests to gather additional information, and save everything to file and/or a database.
+- Group the events in the database into sessions, summarizing the collected data into programs that ran on the appliance.
 
 ## Usage
 
@@ -62,8 +68,11 @@ If the watcher is used regularly, this only needs to be done once.
 Next up, run
 
 ```
-homeconnect-watcher watch
+homeconnect-watcher watch --log-path ./logs
 ```
+to start watching your appliances and write the logs to "./logs".
+
+To store the logs to a database, provide `--db-uri <uri>` with a uri to a postgres database. This will store all events to the `events` table.
 
 ## Exposing Metrics to Prometheus
 

{homeconnect_watcher-0.0.12.dev3 → homeconnect_watcher-0.0.14.dev1}/src/homeconnect_watcher.egg-info/SOURCES.txt

@@ -18,6 +18,8 @@ src/homeconnect_watcher.egg-info/SOURCES.txt
 src/homeconnect_watcher.egg-info/dependency_links.txt
 src/homeconnect_watcher.egg-info/entry_points.txt
 src/homeconnect_watcher.egg-info/requires.txt
+src/homeconnect_watcher.egg-info/scm_file_list.json
+src/homeconnect_watcher.egg-info/scm_version.json
 src/homeconnect_watcher.egg-info/top_level.txt
 src/homeconnect_watcher/client/__init__.py
 src/homeconnect_watcher/client/appliance.py
@@ -43,6 +45,7 @@ src/homeconnect_watcher/utils/timeout.py
 tests/conftest.py
 tests/test_event.py
 tests/client/test_client.py
+tests/client/test_watch.py
 tests/db/test_db_client.py
 tests/db/test_views.py
 tests/db/views/conftest.py

homeconnect_watcher-0.0.14.dev1/src/homeconnect_watcher.egg-info/scm_file_list.json

@@ -0,0 +1,53 @@
+{
+  "files": [
+    ".pre-commit-config.yaml",
+    "README.md",
+    "LICENSE",
+    "pyproject.toml",
+    ".gitignore",
+    "src/homeconnect_watcher/__init__.py",
+    "src/homeconnect_watcher/exceptions.py",
+    "src/homeconnect_watcher/trigger.py",
+    "src/homeconnect_watcher/event.py",
+    "src/homeconnect_watcher/api.py",
+    "src/homeconnect_watcher/read.py",
+    "src/homeconnect_watcher/cli.py",
+    "src/homeconnect_watcher/sql/1_events.sql",
+    "src/homeconnect_watcher/sql/3_raw_events_with_session_id.sql",
+    "src/homeconnect_watcher/sql/0_appliances.sql",
+    "src/homeconnect_watcher/sql/4_sessions.sql",
+    "src/homeconnect_watcher/sql/2_raw_events_active.sql",
+    "src/homeconnect_watcher/utils/__init__.py",
+    "src/homeconnect_watcher/utils/retry.py",
+    "src/homeconnect_watcher/utils/timeout.py",
+    "src/homeconnect_watcher/utils/logging.py",
+    "src/homeconnect_watcher/utils/metrics.py",
+    "src/homeconnect_watcher/db/__init__.py",
+    "src/homeconnect_watcher/db/utils.py",
+    "src/homeconnect_watcher/db/view.py",
+    "src/homeconnect_watcher/db/client.py",
+    "src/homeconnect_watcher/client/__init__.py",
+    "src/homeconnect_watcher/client/client.py",
+    "src/homeconnect_watcher/client/appliance.py",
+    "src/homeconnect_watcher/exporter/__init__.py",
+    "src/homeconnect_watcher/exporter/postgres.py",
+    "src/homeconnect_watcher/exporter/file.py",
+    "src/homeconnect_watcher/exporter/base.py",
+    "tests/conftest.py",
+    "tests/test_event.py",
+    "tests/utils/test_retry.py",
+    "tests/utils/test_timeout.py",
+    "tests/db/test_db_client.py",
+    "tests/db/test_views.py",
+    "tests/db/views/test_view_session.py",
+    "tests/db/views/test_view_appliances.py",
+    "tests/db/views/conftest.py",
+    "tests/db/views/test_view_events.py",
+    "tests/client/test_watch.py",
+    "tests/client/test_client.py",
+    "tests/exporter/test_file.py",
+    "tests/exporter/test_postgres.py",
+    ".github/workflows/publish.yaml",
+    ".github/workflows/ci.yaml"
+  ]
+}

homeconnect_watcher-0.0.14.dev1/src/homeconnect_watcher.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "0.0.14.dev1",
+  "distance": 0,
+  "node": "gaa9ced8929b726f3b6cd854dacc7fa4323c5e909",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-07-03"
+}

homeconnect_watcher-0.0.14.dev1/tests/client/test_watch.py

@@ -0,0 +1,105 @@
+from asyncio import CancelledError, Event, sleep
+from time import time
+from unittest.mock import Mock
+
+from pytest import fixture, mark, raises
+
+from homeconnect_watcher.client import HomeConnectClient
+from homeconnect_watcher.client.appliance import HomeConnectAppliance
+from homeconnect_watcher.event import HomeConnectEvent
+
+
+@fixture
+def client(tmp_path, monkeypatch) -> HomeConnectClient:
+    """A bare client for exercising watch(); every network path is patched in the tests.
+
+    Overrides the session-scoped `client` fixture from conftest so these tests need no
+    credentials or simulator connection.
+    """
+    monkeypatch.setenv("HOMECONNECT_CLIENT_ID", "id")
+    monkeypatch.setenv("HOMECONNECT_CLIENT_SECRET", "secret")
+    monkeypatch.setenv("HOMECONNECT_REDIRECT_URI", "http://localhost:8000/code/")
+    return HomeConnectClient(token_cache=tmp_path / "token")
+
+
+class TestWatchResilience:
+    @mark.asyncio
+    async def test_unexpected_error_reconnects(self, client: HomeConnectClient, monkeypatch):
+        """An unexpected error in the producer is logged, counted, and recovered from."""
+        keep_alive = HomeConnectEvent(event="KEEP-ALIVE", timestamp=0.0)
+        state = {"raised": False}
+
+        async def fake_event_stream(appliance_id=None):
+            if not state["raised"]:
+                state["raised"] = True
+                raise ValueError("boom")
+            yield keep_alive
+            await Event().wait()  # suspend so the loop can run the consumer; keep the stream "open"
+
+        async def noop_initial(queue, appliance_id):
+            return
+
+        async def noop_handle(trigger, queue):
+            return
+
+        metrics = Mock()
+        monkeypatch.setattr(client, "metrics", metrics)
+        monkeypatch.setattr(client, "_initial_triggers", noop_initial)
+        monkeypatch.setattr(client, "_event_stream", fake_event_stream)
+        monkeypatch.setattr(client, "_handle_trigger", noop_handle)
+
+        gen = client.watch(reconnect_delay=0)
+        try:
+            received = await gen.__anext__()
+        finally:
+            await gen.aclose()
+
+        # The producer survived the ValueError, reconnected, and delivered the next event.
+        assert received == keep_alive
+        assert state["raised"] is True
+        metrics.increment_disconnects.assert_any_call(reason="error")
+
+
+class TestWatchTaskCleanup:
+    @mark.asyncio
+    async def test_deferred_tasks_cancelled_on_close(self, client: HomeConnectClient, monkeypatch):
+        """Pending deferred fetches are cancelled (and untracked) when watching stops."""
+        appliance = HomeConnectAppliance(client, "SIEMENS-TEST-AB1234567890", "Washer")
+        appliance._last_update["status"] = time()  # throttle active -> the fetch is deferred, not run
+        scheduled = Event()
+
+        async def never_fetch():  # pragma: no cover - deferred task is cancelled before this runs
+            return HomeConnectEvent(event="STATUS-REQUEST", timestamp=0.0)
+
+        async def fake_handle_trigger(trigger, queue):
+            await client._fetch_or_defer(appliance, "status", never_fetch, throttled=True, queue=queue)
+            scheduled.set()
+
+        async def fake_event_stream(appliance_id=None):
+            yield HomeConnectEvent(event="KEEP-ALIVE", timestamp=0.0)
+            await Event().wait()  # keep the stream open so the deferred task stays pending
+
+        async def noop_initial(queue, appliance_id):
+            return
+
+        monkeypatch.setattr(client, "_initial_triggers", noop_initial)
+        monkeypatch.setattr(client, "_event_stream", fake_event_stream)
+        monkeypatch.setattr(client, "_handle_trigger", fake_handle_trigger)
+
+        before = set(client._deferred_tasks)
+        gen = client.watch(reconnect_delay=0)
+        await gen.__anext__()  # receive the KEEP-ALIVE event
+        await scheduled.wait()  # ensure the deferred fetch has been scheduled
+
+        new_tasks = client._deferred_tasks - before
+        assert len(new_tasks) == 1
+        task = new_tasks.pop()
+        assert not task.done()
+
+        await gen.aclose()  # runs watch()'s finally: cancels the producer and deferred tasks
+
+        with raises(CancelledError):
+            await task
+        await sleep(0)  # let the done-callback drain the task from the set
+        assert task.cancelled()
+        assert task not in client._deferred_tasks

homeconnect_watcher-0.0.12.dev3/src/homeconnect_watcher/_version.py

@@ -1,16 +0,0 @@
-# file generated by setuptools_scm
-# don't change, don't track in version control
-TYPE_CHECKING = False
-if TYPE_CHECKING:
-    from typing import Tuple, Union
-    VERSION_TUPLE = Tuple[Union[int, str], ...]
-else:
-    VERSION_TUPLE = object
-
-version: str
-__version__: str
-__version_tuple__: VERSION_TUPLE
-version_tuple: VERSION_TUPLE
-
-__version__ = version = '0.0.12.dev3'
-__version_tuple__ = version_tuple = (0, 0, 12, 'dev3')