dimplex-controller 0.10.1__tar.gz → 0.11.0__tar.gz

{dimplex_controller-0.10.1 → dimplex_controller-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dimplex-controller
-Version: 0.10.1
+Version: 0.11.0
 Summary: Python client for Dimplex heating controllers (GDHV IoT)
 License: MIT
 License-File: LICENSE
@@ -20,7 +20,6 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Home Automation
 Requires-Dist: aiohttp (>=3.9.0,<4.0.0)
-Requires-Dist: beautifulsoup4 (>=4.14.3,<5.0.0)
 Requires-Dist: pydantic (>=2.0.0,<3.0.0)
 Project-URL: Homepage, https://github.com/KRoperUK/dimplex-controller-py
 Project-URL: Repository, https://github.com/KRoperUK/dimplex-controller-py
@@ -127,17 +126,22 @@ if __name__ == "__main__":
 
 ### Authentication
 
-Dimplex uses Azure AD B2C. You cannot log in purely programmatically with just a username and password — the library must first capture a short-lived authorisation code.
+Dimplex uses Azure AD B2C. The library supports two methods:
 
-The recommended approach is to run the included demo script once:
+#### Email / password (headless login) — recommended
 
-```bash
-python demo.py
+```python
+client = DimplexControl(session)
+await client.auth.headless_login("you@example.com", "password")
 ```
 
-The script walks you through opening a browser, signing in, and pasting the resulting redirect URL back into the terminal. On success, it saves a `dimplex_tokens.json` file in the current working directory.
+This automates the full B2C flow via HTTP. On success, `client.is_authenticated` is `True` and tokens can be persisted with `client.export_tokens()`.
+
+#### Manual auth code (browser)
+
+Run `demo.py` to open a browser, sign in, and paste the redirect URL. The script saves tokens to `dimplex_tokens.json`. Subsequent runs load the refresh token automatically.
 
-Subsequent runs read the refresh token from that file automatically. You can also pass the refresh token directly to `DimplexControl` if you prefer to manage storage yourself.
+Either way, refresh tokens are used on future calls — the library handles token renewal transparently.
 
 ### Discovery
 
@@ -216,22 +220,31 @@ See [docs/compatibility.md](docs/compatibility.md) for the library ↔ Home Assi
 
 ### `DimplexControl`
 
-Main client class. Construct with an `aiohttp.ClientSession` and a `refresh_token`.
+Main client class. Construct with an `aiohttp.ClientSession` and a `refresh_token` (or `token_bundle`).
 
 | Method | Description |
 |--------|-------------|
 | `get_hubs()` | Returns `list[Hub]`. |
 | `get_hub_zones(hub_id)` | Returns `list[Zone]` for a Hub. |
 | `get_zone(hub_id, zone_id)` | Returns a single `Zone`. |
-| `get_appliance_overview(hub_id, appliance_ids)` | Returns `list[ApplianceStatus]`. |
+| `get_appliance_overview(hub_id, appliance_ids)` | Returns `list[ApplianceStatus]` (may be `[]`). |
+| `get_appliance_overview_map(hub_id, appliance_ids)` | Stable `dict[str, ApplianceStatus \| None]`. |
 | `get_user_context()` | Returns `UserContext`. |
-| `get_appliance_features(hub_id, appliance_ids)` | Returns raw appliance feature data. |
-| `set_mode(hub_id, appliance_ids, mode, temperature)` | Set operation mode. |
-| `set_target_temperature(...)` | Placeholder for future target temperature control. |
-| `set_appliance_mode(hub_id, appliance_ids, settings)` | Send full mode settings. |
-| `set_eco_start(hub_id, appliance_ids, enabled)` | Toggle EcoStart. |
-| `set_open_window_detection(hub_id, appliance_ids, enabled)` | Toggle Open Window Detection. |
-| `get_tsi_energy_report(hub_id)` | Returns `TsiEnergyReport`. |
+| `get_product_models()` | Returns `list[ProductModel]` (cacheable). |
+| `get_schedule(hub_id, appliance_id)` | Returns `TimerModeSettings` (timer + periods). |
+| `set_mode(hub_id, appliance_id, mode)` | Change timer/operation mode. |
+| `set_target_temperature(hub_id, appliance_id, temp)` | Rewrite all period setpoints or install full-week schedule. |
+| `set_period_setpoint(...)` | Update one timer period without clobbering siblings. |
+| `update_period(...)` | Replace a timer period matched by day + start time. |
+| `set_boost(hub_id, appliance_ids, *, temperature, duration_minutes, enable)` | Enable/disable Boost. |
+| `clear_boost(hub_id, appliance_ids)` | Disable Boost. |
+| `set_away(hub_id, appliance_ids, *, temperature, enable, number_of_days)` | Enable/disable Away. |
+| `clear_away(hub_id, appliance_ids)` | Disable Away. |
+| `set_eco_start(hub_id, appliance_ids, enable)` | Toggle EcoStart. |
+| `set_open_window_detection(hub_id, appliance_ids, enable)` | Toggle Open Window Detection. |
+| `get_tsi_energy_report(hub_id, ...)` | Returns `TsiEnergyReport`. |
+| `capabilities_for(appliance, *, status, product)` | Derive an `ApplianceCapabilities` matrix. |
+| `export_tokens()` / `apply_tokens(bundle)` | Token persistence helpers. |
 
 ### Models
 
@@ -281,7 +294,24 @@ If `parse_telemetry_points` returns an empty list, the API likely returned an un
 
 ### Rate limiting
 
-The GDHV cloud API has rate limits. If you hit them, back off for a few minutes before retrying. The library does not currently implement automatic retries with back-off.
+The GDHV cloud API has rate limits. The library retries idempotent `GET`
+requests automatically on HTTP 429/5xx and connection errors, using exponential
+backoff with jitter and honouring the `Retry-After` header when present.
+Non-idempotent control calls (`POST`/`PUT`/`PATCH`/`DELETE`) are **not** retried
+by default. Tune this via the client constructor:
+
+```python
+client = DimplexControl(
+    session,
+    refresh_token="...",
+    max_retries=3,             # retries after the first attempt (0 disables)
+    retry_base_delay=0.5,      # seconds; exponential base
+    retry_max_delay=8.0,       # seconds; backoff ceiling
+    retry_non_idempotent=False,  # set True to also retry POST/PUT/etc.
+)
+```
+
+If you still hit persistent limits, back off for a few minutes before retrying.
 
 ### `get_appliance_overview` returns an empty list
 

{dimplex_controller-0.10.1 → dimplex_controller-0.11.0}/README.md

@@ -99,17 +99,22 @@ if __name__ == "__main__":
 
 ### Authentication
 
-Dimplex uses Azure AD B2C. You cannot log in purely programmatically with just a username and password — the library must first capture a short-lived authorisation code.
+Dimplex uses Azure AD B2C. The library supports two methods:
 
-The recommended approach is to run the included demo script once:
+#### Email / password (headless login) — recommended
 
-```bash
-python demo.py
+```python
+client = DimplexControl(session)
+await client.auth.headless_login("you@example.com", "password")
 ```
 
-The script walks you through opening a browser, signing in, and pasting the resulting redirect URL back into the terminal. On success, it saves a `dimplex_tokens.json` file in the current working directory.
+This automates the full B2C flow via HTTP. On success, `client.is_authenticated` is `True` and tokens can be persisted with `client.export_tokens()`.
+
+#### Manual auth code (browser)
+
+Run `demo.py` to open a browser, sign in, and paste the redirect URL. The script saves tokens to `dimplex_tokens.json`. Subsequent runs load the refresh token automatically.
 
-Subsequent runs read the refresh token from that file automatically. You can also pass the refresh token directly to `DimplexControl` if you prefer to manage storage yourself.
+Either way, refresh tokens are used on future calls — the library handles token renewal transparently.
 
 ### Discovery
 
@@ -188,22 +193,31 @@ See [docs/compatibility.md](docs/compatibility.md) for the library ↔ Home Assi
 
 ### `DimplexControl`
 
-Main client class. Construct with an `aiohttp.ClientSession` and a `refresh_token`.
+Main client class. Construct with an `aiohttp.ClientSession` and a `refresh_token` (or `token_bundle`).
 
 | Method | Description |
 |--------|-------------|
 | `get_hubs()` | Returns `list[Hub]`. |
 | `get_hub_zones(hub_id)` | Returns `list[Zone]` for a Hub. |
 | `get_zone(hub_id, zone_id)` | Returns a single `Zone`. |
-| `get_appliance_overview(hub_id, appliance_ids)` | Returns `list[ApplianceStatus]`. |
+| `get_appliance_overview(hub_id, appliance_ids)` | Returns `list[ApplianceStatus]` (may be `[]`). |
+| `get_appliance_overview_map(hub_id, appliance_ids)` | Stable `dict[str, ApplianceStatus \| None]`. |
 | `get_user_context()` | Returns `UserContext`. |
-| `get_appliance_features(hub_id, appliance_ids)` | Returns raw appliance feature data. |
-| `set_mode(hub_id, appliance_ids, mode, temperature)` | Set operation mode. |
-| `set_target_temperature(...)` | Placeholder for future target temperature control. |
-| `set_appliance_mode(hub_id, appliance_ids, settings)` | Send full mode settings. |
-| `set_eco_start(hub_id, appliance_ids, enabled)` | Toggle EcoStart. |
-| `set_open_window_detection(hub_id, appliance_ids, enabled)` | Toggle Open Window Detection. |
-| `get_tsi_energy_report(hub_id)` | Returns `TsiEnergyReport`. |
+| `get_product_models()` | Returns `list[ProductModel]` (cacheable). |
+| `get_schedule(hub_id, appliance_id)` | Returns `TimerModeSettings` (timer + periods). |
+| `set_mode(hub_id, appliance_id, mode)` | Change timer/operation mode. |
+| `set_target_temperature(hub_id, appliance_id, temp)` | Rewrite all period setpoints or install full-week schedule. |
+| `set_period_setpoint(...)` | Update one timer period without clobbering siblings. |
+| `update_period(...)` | Replace a timer period matched by day + start time. |
+| `set_boost(hub_id, appliance_ids, *, temperature, duration_minutes, enable)` | Enable/disable Boost. |
+| `clear_boost(hub_id, appliance_ids)` | Disable Boost. |
+| `set_away(hub_id, appliance_ids, *, temperature, enable, number_of_days)` | Enable/disable Away. |
+| `clear_away(hub_id, appliance_ids)` | Disable Away. |
+| `set_eco_start(hub_id, appliance_ids, enable)` | Toggle EcoStart. |
+| `set_open_window_detection(hub_id, appliance_ids, enable)` | Toggle Open Window Detection. |
+| `get_tsi_energy_report(hub_id, ...)` | Returns `TsiEnergyReport`. |
+| `capabilities_for(appliance, *, status, product)` | Derive an `ApplianceCapabilities` matrix. |
+| `export_tokens()` / `apply_tokens(bundle)` | Token persistence helpers. |
 
 ### Models
 
@@ -253,7 +267,24 @@ If `parse_telemetry_points` returns an empty list, the API likely returned an un
 
 ### Rate limiting
 
-The GDHV cloud API has rate limits. If you hit them, back off for a few minutes before retrying. The library does not currently implement automatic retries with back-off.
+The GDHV cloud API has rate limits. The library retries idempotent `GET`
+requests automatically on HTTP 429/5xx and connection errors, using exponential
+backoff with jitter and honouring the `Retry-After` header when present.
+Non-idempotent control calls (`POST`/`PUT`/`PATCH`/`DELETE`) are **not** retried
+by default. Tune this via the client constructor:
+
+```python
+client = DimplexControl(
+    session,
+    refresh_token="...",
+    max_retries=3,             # retries after the first attempt (0 disables)
+    retry_base_delay=0.5,      # seconds; exponential base
+    retry_max_delay=8.0,       # seconds; backoff ceiling
+    retry_non_idempotent=False,  # set True to also retry POST/PUT/etc.
+)
+```
+
+If you still hit persistent limits, back off for a few minutes before retrying.
 
 ### `get_appliance_overview` returns an empty list
 

{dimplex_controller-0.10.1 → dimplex_controller-0.11.0}/dimplex_controller/auth.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import asyncio
 import inspect
 import json
 import logging
@@ -39,6 +40,15 @@ TokenListener = Callable[["TokenBundle"], Awaitable[None] | None]
 _MAX_REDIRECT_HOPS = 20
 
 
+def _coerce_auth_timeout(timeout: aiohttp.ClientTimeout | float | None) -> aiohttp.ClientTimeout | None:
+    """Normalise an auth timeout into an :class:`aiohttp.ClientTimeout`."""
+    if timeout is None:
+        return None
+    if isinstance(timeout, aiohttp.ClientTimeout):
+        return timeout
+    return aiohttp.ClientTimeout(total=float(timeout))
+
+
 @dataclass(frozen=True, slots=True)
 class TokenBundle:
     """Public, serialisable snapshot of auth tokens."""
@@ -76,15 +86,28 @@ class AuthManager:
         token_data: dict[str, Any] | TokenBundle | None = None,
         *,
         on_token_update: TokenListener | None = None,
+        timeout: aiohttp.ClientTimeout | float | None = None,
     ):
-        """Initialize the auth manager."""
+        """Initialize the auth manager.
+
+        ``timeout`` bounds every auth request (token refresh, code exchange, and
+        the headless B2C login). Pass a number for a total timeout in seconds,
+        an :class:`aiohttp.ClientTimeout`, or ``None`` for aiohttp defaults.
+        """
         self._session = session
         self._on_token_update = on_token_update
+        self._timeout = _coerce_auth_timeout(timeout)
         bundle = token_data if isinstance(token_data, TokenBundle) else TokenBundle.from_mapping(token_data)
         self._access_token: str | None = bundle.access_token
         self._refresh_token: str | None = bundle.refresh_token
         self._expires_at: float = bundle.expires_at
 
+    def _request_kwargs(self) -> dict[str, Any]:
+        """Common per-request kwargs (applies the configured timeout)."""
+        if self._timeout is not None:
+            return {"timeout": self._timeout}
+        return {}
+
     @property
     def is_authenticated(self) -> bool:
         """Check if we have a valid access token."""
@@ -139,7 +162,7 @@ class AuthManager:
         }
 
         try:
-            async with self._session.post(f"{AUTH_URL}/token", data=payload) as resp:
+            async with self._session.post(f"{AUTH_URL}/token", data=payload, **self._request_kwargs()) as resp:
                 if resp.status != HTTP_OK:
                     text = await resp.text()
                     _LOGGER.error(
@@ -153,7 +176,7 @@ class AuthManager:
                 await self._update_tokens(data)
         except DimplexAuthError:
             raise
-        except aiohttp.ClientError as exc:
+        except (aiohttp.ClientError, asyncio.TimeoutError) as exc:
             raise DimplexAuthTransientError(
                 f"Network error while refreshing token: {type(exc).__name__}",
                 details=str(exc)[:200],
@@ -217,7 +240,7 @@ class AuthManager:
 
         _LOGGER.debug("Exchanging authorization code for tokens")
         try:
-            async with self._session.post(f"{AUTH_URL}/token", data=payload) as resp:
+            async with self._session.post(f"{AUTH_URL}/token", data=payload, **self._request_kwargs()) as resp:
                 if resp.status != HTTP_OK:
                     text = await resp.text()
                     _LOGGER.error(
@@ -231,7 +254,7 @@ class AuthManager:
                 await self._update_tokens(data)
         except DimplexAuthError:
             raise
-        except aiohttp.ClientError as exc:
+        except (aiohttp.ClientError, asyncio.TimeoutError) as exc:
             raise DimplexAuthTransientError(
                 f"Network error while exchanging code: {type(exc).__name__}",
                 details=str(exc)[:200],
@@ -291,7 +314,7 @@ class AuthManager:
         start_url = self.get_login_url()
 
         try:
-            async with aiohttp.ClientSession(cookie_jar=jar) as session:
+            async with aiohttp.ClientSession(cookie_jar=jar, timeout=self._timeout) as session:
                 # Step 1: GET the auth URI, follow redirects to B2C login page
                 _LOGGER.debug("Fetching B2C login page")
                 try:

{dimplex_controller-0.10.1 → dimplex_controller-0.11.0}/dimplex_controller/client.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import asyncio
+import json
 import logging
 import random
 from datetime import datetime, timedelta, timezone
@@ -55,6 +56,24 @@ DEFAULT_RETRY_BASE_DELAY = 0.5
 DEFAULT_RETRY_MAX_DELAY = 8.0
 _RETRYABLE_STATUS = frozenset({429, 500, 502, 503, 504})
 
+# Default total request timeout in seconds. Without this aiohttp falls back to a
+# 5-minute default, which can hang a caller (e.g. a Home Assistant coordinator
+# poll) on a stalled connection. Callers may override per-client.
+DEFAULT_TIMEOUT = 30.0
+
+
+def _coerce_timeout(timeout: float | aiohttp.ClientTimeout | None) -> aiohttp.ClientTimeout | None:
+    """Normalise a timeout value into an :class:`aiohttp.ClientTimeout`.
+
+    ``None`` disables the client-level timeout (aiohttp defaults apply); a
+    number is treated as the total request timeout in seconds.
+    """
+    if timeout is None:
+        return None
+    if isinstance(timeout, aiohttp.ClientTimeout):
+        return timeout
+    return aiohttp.ClientTimeout(total=float(timeout))
+
 
 def _iso_utc_days_ago(days: int) -> str:
     """Return an ISO-8601 UTC timestamp ``days`` before now (no microseconds)."""
@@ -77,6 +96,7 @@ class DimplexControl:
         retry_base_delay: float = DEFAULT_RETRY_BASE_DELAY,
         retry_max_delay: float = DEFAULT_RETRY_MAX_DELAY,
         retry_non_idempotent: bool = False,
+        timeout: float | aiohttp.ClientTimeout | None = DEFAULT_TIMEOUT,
     ):
         """Initialize the client.
 
@@ -93,6 +113,12 @@ class DimplexControl:
           policy (use with care).
         * ``max_retries`` is the number of *retries* after the first attempt
           (0 disables retries).
+
+        ``timeout`` bounds every request (API and auth). Pass a number for a
+        total timeout in seconds (default 30s), an :class:`aiohttp.ClientTimeout`
+        for fine-grained control, or ``None`` to fall back to aiohttp defaults.
+        A timed-out request is surfaced as :class:`DimplexConnectionError` and,
+        for retryable methods, retried like any other connection error.
         """
         if token_bundle is not None:
             token_data: dict[str, Any] | TokenBundle = token_bundle
@@ -106,7 +132,8 @@ class DimplexControl:
                 token_data["expires_at"] = expires_at
 
         self._session = session
-        self.auth = AuthManager(session, token_data)
+        self._timeout = _coerce_timeout(timeout)
+        self.auth = AuthManager(session, token_data, timeout=self._timeout)
         self._max_retries = max(0, int(max_retries))
         self._retry_base_delay = float(retry_base_delay)
         self._retry_max_delay = float(retry_max_delay)
@@ -170,6 +197,8 @@ class DimplexControl:
         )
 
         url = f"{BASE_URL}{endpoint}"
+        if self._timeout is not None and "timeout" not in kwargs:
+            kwargs["timeout"] = self._timeout
         allow_retry = self._should_retry(method)
         attempts = self._max_retries + 1 if allow_retry else 1
         last_error: Exception | None = None
@@ -178,9 +207,7 @@ class DimplexControl:
             try:
                 async with self._session.request(method, url, headers=headers, **kwargs) as resp:
                     if resp.status == HTTP_OK:
-                        if resp.content_length == 0:
-                            return {}
-                        return await resp.json()
+                        return await self._decode_ok_body(resp)
 
                     text = await resp.text()
                     retry_after = self._parse_retry_after(resp.headers.get("Retry-After"))
@@ -192,7 +219,7 @@ class DimplexControl:
                             endpoint,
                             resp.status,
                             attempt + 1,
-                            self._max_retries,
+                            attempts - 1,
                             delay,
                         )
                         last_error = DimplexApiError(resp.status, text)
@@ -201,7 +228,7 @@ class DimplexControl:
 
                     _LOGGER.error("API request failed: %s - %s", resp.status, text)
                     raise DimplexApiError(resp.status, text)
-            except aiohttp.ClientError as e:
+            except (aiohttp.ClientError, asyncio.TimeoutError) as e:
                 if allow_retry and attempt + 1 < attempts:
                     delay = self._backoff_seconds(attempt)
                     _LOGGER.warning(
@@ -209,7 +236,7 @@ class DimplexControl:
                         method,
                         endpoint,
                         attempt + 1,
-                        self._max_retries,
+                        attempts - 1,
                         delay,
                         e,
                     )
@@ -225,6 +252,25 @@ class DimplexControl:
             raise last_error
         raise DimplexConnectionError("Request failed after retries")
 
+    @staticmethod
+    async def _decode_ok_body(resp: aiohttp.ClientResponse) -> Any:
+        """Decode a 2xx JSON body, tolerating empty responses.
+
+        Some Dimplex control endpoints reply ``200 OK`` with an empty body (no
+        ``Content-Length`` when chunked/compressed), so ``resp.content_length``
+        alone is unreliable. Read the raw text and treat empty/whitespace as an
+        empty object. A non-empty body that fails to parse is wrapped as a
+        :class:`DimplexConnectionError` rather than escaping as a raw
+        ``JSONDecodeError``.
+        """
+        text = await resp.text()
+        if not text or not text.strip():
+            return {}
+        try:
+            return json.loads(text)
+        except json.JSONDecodeError as exc:
+            raise DimplexConnectionError(f"Invalid JSON in response: {exc}") from exc
+
     @staticmethod
     def capabilities_for(
         appliance: Appliance | None = None,

{dimplex_controller-0.10.1 → dimplex_controller-0.11.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "dimplex-controller"
-version = "0.10.1"
+version = "0.11.0"
 description = "Python client for Dimplex heating controllers (GDHV IoT)"
 authors = ["Kieran Roper"]
 license = "MIT"
@@ -30,7 +30,6 @@ dimplex = "dimplex_controller.cli:main"
 python = "^3.10"
 aiohttp = "^3.9.0"
 pydantic = "^2.0.0"
-beautifulsoup4 = "^4.14.3"
 
 [tool.poetry.group.dev.dependencies]
 pytest = "^8.0.0"
@@ -61,6 +60,20 @@ python_version = "3.10"
 files = ["dimplex_controller"]
 ignore_missing_imports = true
 
+[tool.pytest.ini_options]
+# All async tests use asyncio; "auto" means new tests don't each need the
+# @pytest.mark.asyncio decorator (existing markers remain valid).
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.coverage.run]
+source = ["dimplex_controller"]
+
+[tool.coverage.report]
+show_missing = true
+# Guardrail so coverage can't silently regress. Raise as coverage improves.
+fail_under = 80
+
 [build-system]
 requires = ["poetry-core"]
 build-backend = "poetry.core.masonry.api"