dimplex-controller 0.3.0__tar.gz → 0.4.0__tar.gz

{dimplex_controller-0.3.0 → dimplex_controller-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dimplex-controller
-Version: 0.3.0
+Version: 0.4.0
 Summary: Python client for Dimplex heating controllers (GDHV IoT)
 License: MIT
 License-File: LICENSE

{dimplex_controller-0.3.0 → dimplex_controller-0.4.0}/dimplex_controller/__init__.py

@@ -2,7 +2,8 @@
 
 from .client import DimplexControl
 from .exceptions import DimplexApiError, DimplexAuthError, DimplexConnectionError, DimplexError
-from .models import Appliance, ApplianceModeSettings, ApplianceStatus, Hub, Zone
+from .models import Appliance, ApplianceModeSettings, ApplianceStatus, Hub, TsiEnergyReport, Zone
+from .telemetry import parse_telemetry_points
 
 __all__ = [
     "DimplexControl",
@@ -11,6 +12,8 @@ __all__ = [
     "Appliance",
     "ApplianceStatus",
     "ApplianceModeSettings",
+    "TsiEnergyReport",
+    "parse_telemetry_points",
     "DimplexError",
     "DimplexApiError",
     "DimplexAuthError",

{dimplex_controller-0.3.0 → dimplex_controller-0.4.0}/dimplex_controller/auth.py

@@ -3,7 +3,6 @@ import logging
 import os
 import re
 import time
-from typing import Dict, Optional
 from urllib.parse import parse_qs, urlparse
 
 import aiohttp
@@ -24,11 +23,11 @@ _LOGGER = logging.getLogger(__name__)
 class AuthManager:
     """Manages authentication for Dimplex Control."""
 
-    def __init__(self, session: aiohttp.ClientSession, token_data: Optional[Dict] = None):
+    def __init__(self, session: aiohttp.ClientSession, token_data: dict | None = None):
         """Initialize the auth manager."""
         self._session = session
-        self._access_token: Optional[str] = token_data.get("access_token") if token_data else None
-        self._refresh_token: Optional[str] = token_data.get("refresh_token") if token_data else None
+        self._access_token: str | None = token_data.get("access_token") if token_data else None
+        self._refresh_token: str | None = token_data.get("refresh_token") if token_data else None
         self._expires_at: float = token_data.get("expires_at", 0) if token_data else 0
 
     @property
@@ -42,11 +41,11 @@ class AuthManager:
             raise DimplexAuthError("No refresh token available. User must authenticate first.")
 
         if self.is_authenticated:
-            return self._access_token
+            return self._access_token  # type: ignore[return-value]
 
         # Token expired or missing, try refresh
         await self.refresh_tokens()
-        return self._access_token
+        return self._access_token  # type: ignore[return-value]
 
     async def refresh_tokens(self) -> None:
         """Refresh the access token using the refresh token."""
@@ -68,7 +67,7 @@ class AuthManager:
             data = await resp.json()
             self._update_tokens(data)
 
-    def _update_tokens(self, data: Dict) -> None:
+    def _update_tokens(self, data: dict) -> None:
         """Update internal token state from API response."""
         self._access_token = data.get("access_token")
         self._refresh_token = data.get("refresh_token")
@@ -318,12 +317,12 @@ class AuthManager:
         _LOGGER.info("Tokens saved to %s", file_path)
 
     @classmethod
-    def load_tokens(cls, file_path: str) -> Optional[Dict]:
+    def load_tokens(cls, file_path: str) -> dict | None:
         """Load tokens from a JSON file."""
         if not os.path.exists(file_path):
             return None
         try:
-            with open(file_path, "r") as f:
+            with open(file_path) as f:
                 return json.load(f)
         except Exception as e:
             _LOGGER.error("Failed to load tokens from %s: %s", file_path, e)

{dimplex_controller-0.3.0 → dimplex_controller-0.4.0}/dimplex_controller/client.py

@@ -1,5 +1,5 @@
 import logging
-from typing import Dict, List, Optional
+from datetime import datetime, timedelta, timezone
 
 import aiohttp
 
@@ -21,12 +21,25 @@ from .models import (
     ApplianceStatus,
     Hub,
     TimerModeSettings,
+    TsiEnergyReport,
     UserContext,
     Zone,
 )
 
 _LOGGER = logging.getLogger(__name__)
 
+# Default lookback when the caller does not pin a start date. The energy
+# endpoint is paginated server-side; 30 days is a reasonable default that
+# keeps the response small while still giving the caller a meaningful window.
+DEFAULT_TSI_REPORT_DAYS = 30
+DEFAULT_TSI_INTERVAL = "01:00:00"
+
+
+def _iso_utc_days_ago(days: int) -> str:
+    """Return an ISO-8601 UTC timestamp ``days`` before now (no microseconds)."""
+    dt = datetime.now(timezone.utc) - timedelta(days=days)
+    return dt.replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
 
 class DimplexControl:
     """Main client for Dimplex Control API."""
@@ -34,8 +47,8 @@ class DimplexControl:
     def __init__(
         self,
         session: aiohttp.ClientSession,
-        refresh_token: Optional[str] = None,
-        access_token: Optional[str] = None,
+        refresh_token: str | None = None,
+        access_token: str | None = None,
         expires_at: float = 0,
     ):
         """Initialize the client."""
@@ -45,7 +58,7 @@ class DimplexControl:
         if access_token:
             token_data["access_token"] = access_token
         if expires_at:
-            token_data["expires_at"] = expires_at
+            token_data["expires_at"] = expires_at  # type: ignore[assignment]
 
         self._session = session
         self.auth = AuthManager(session, token_data)
@@ -55,7 +68,7 @@ class DimplexControl:
         """Check if authenticated."""
         return self.auth.is_authenticated
 
-    async def _request(self, method: str, endpoint: str, **kwargs) -> Dict:
+    async def _request(self, method: str, endpoint: str, **kwargs) -> dict:
         """Make an authenticated request."""
         token = await self.auth.get_access_token()
         headers = kwargs.pop("headers", {})
@@ -92,13 +105,13 @@ class DimplexControl:
             _LOGGER.error("Connection error during API request: %s", e)
             raise DimplexConnectionError(f"Connection error: {e}") from e
 
-    async def get_hubs(self) -> List[Hub]:
+    async def get_hubs(self) -> list[Hub]:
         """Get all hubs for the user."""
         data = await self._request("GET", "/Hubs/GetUserHubs")
         # Log analysis shows list of objects
         return [Hub(**h) for h in data]
 
-    async def get_hub_zones(self, hub_id: str) -> List[Zone]:
+    async def get_hub_zones(self, hub_id: str) -> list[Zone]:
         """Get zones and appliances for a hub."""
         data = await self._request("GET", "/Zones/GetZonesAndAppliancesForHubId", params={"HubId": hub_id})
         return [Zone(**z) for z in data]
@@ -109,7 +122,7 @@ class DimplexControl:
         data = await self._request("POST", "/Zones/GetZone", json=payload)
         return Zone(**data)
 
-    async def get_appliance_overview(self, hub_id: str, appliance_ids: List[str]) -> List[ApplianceStatus]:
+    async def get_appliance_overview(self, hub_id: str, appliance_ids: list[str]) -> list[ApplianceStatus]:
         """Get status overview for specific appliances."""
         payload = {"HubId": hub_id, "ApplianceIds": appliance_ids}
         data = await self._request("POST", "/RemoteControl/GetApplianceOverview", json=payload)
@@ -159,18 +172,55 @@ class DimplexControl:
         pass
 
     async def set_appliance_mode(
-        self, hub_id: str, appliance_ids: List[str], mode_settings: ApplianceModeSettings
+        self, hub_id: str, appliance_ids: list[str], mode_settings: ApplianceModeSettings
     ) -> None:
         """Set appliance mode (Boost, Away, etc.)."""
         payload = {"Settings": mode_settings.dict(), "HubId": hub_id, "ApplianceIds": appliance_ids}
         await self._request("POST", "/RemoteControl/SetApplianceMode", json=payload)
 
-    async def set_eco_start(self, hub_id: str, appliance_ids: List[str], enable: bool) -> None:
+    async def set_eco_start(self, hub_id: str, appliance_ids: list[str], enable: bool) -> None:
         """Enable/Disable EcoStart."""
         payload = {"Enable": enable, "HubId": hub_id, "ApplianceIds": appliance_ids}
         await self._request("POST", "/RemoteControl/SetEcoStart", json=payload)
 
-    async def set_open_window_detection(self, hub_id: str, appliance_ids: List[str], enable: bool) -> None:
+    async def set_open_window_detection(self, hub_id: str, appliance_ids: list[str], enable: bool) -> None:
         """Enable/Disable Open Window Detection."""
         payload = {"Enable": enable, "HubId": hub_id, "ApplianceIds": appliance_ids}
         await self._request("POST", "/RemoteControl/SetOpenWindowDetection", json=payload)
+
+    async def get_tsi_energy_report(
+        self,
+        hub_id: str | None = None,
+        report_type: int = 1,
+        interval: str = DEFAULT_TSI_INTERVAL,
+        start_date: str | None = None,
+        include_previous_period: bool = False,
+        days_back: int = DEFAULT_TSI_REPORT_DAYS,
+    ) -> TsiEnergyReport:
+        """Fetch the Time Series Insights energy report for a hub.
+
+        Returns a :class:`~dimplex_controller.models.TsiEnergyReport`. The
+        cloud response is the same regardless of ``hub_id`` (the field is
+        informational), so ``hub_id`` is only required to populate the
+        returned model. Each per-appliance list is left as the raw payload —
+        use :func:`dimplex_controller.telemetry.parse_telemetry_points` to
+        normalise the points into ``(timestamp, value)`` tuples.
+
+        When the hub has no metered appliances (e.g. non-QRAD heaters, or a
+        quiet summer hub) the per-appliance lists come back empty; that is
+        treated as success, not an error.
+        """
+        if start_date is None:
+            start_date = _iso_utc_days_ago(days_back)
+
+        payload = {
+            "TsiReportType": report_type,
+            "Interval": interval,
+            "StartDate": start_date,
+            "IncludePreviousPeriod": include_previous_period,
+        }
+        data = await self._request("POST", "/Reports/GetTsiEnergyReportDataForHub", json=payload)
+        return TsiEnergyReport(
+            HubId=(hub_id or data.get("HubId", "")),
+            ApplianceTelemetryData=data.get("ApplianceTelemetryData", {}) or {},
+        )

dimplex_controller-0.4.0/dimplex_controller/models.py

@@ -0,0 +1,117 @@
+from datetime import datetime, time
+
+from pydantic import BaseModel, Field
+
+
+class Appliance(BaseModel):
+    ApplianceId: str
+    ApplianceType: str
+    ApplianceModel: str | None = None
+    ZoneId: str
+    FriendlyName: str
+    ZoneName: str
+    Icon: str | None = None
+    IconColor: str | None = None
+    InstallationDate: datetime | None = None
+    HasConnectivity: bool | None = None
+
+
+class Zone(BaseModel):
+    ZoneId: str
+    ZoneName: str
+    HubId: str
+    ZoneType: str
+    Appliances: list[Appliance] = Field(default_factory=list)
+
+
+class Hub(BaseModel):
+    HubId: str
+    Name: str | None = Field(None, alias="HubName")
+    FriendlyName: str | None = None
+
+
+class TimerPeriod(BaseModel):
+    DayOfWeek: int
+    StartTime: str  # Kept as str for easy JSON serialization
+    EndTime: str
+    Temperature: float
+
+    @property
+    def start_time_obj(self) -> time:
+        return datetime.strptime(self.StartTime, "%H:%M:%S").time()
+
+    @property
+    def end_time_obj(self) -> time:
+        return datetime.strptime(self.EndTime, "%H:%M:%S").time()
+
+
+class TimerModeSettings(BaseModel):
+    HubId: str
+    ApplianceId: str
+    TimerMode: int
+    TimerPeriods: list[TimerPeriod] = Field(default_factory=list)
+
+
+class UserContext(BaseModel):
+    Id: str
+    EmailAddress: str | None = None
+    Name: str | None = None
+
+
+class ApplianceStatus(BaseModel):
+    """Represents the real-time status of an appliance as returned by GetApplianceOverview."""
+
+    HubId: str
+    ApplianceId: str
+    ZoneId: str
+    StatusTwo: int | None = None
+    ApplianceModes: int | None = None
+    RoomTemperature: float | None = None
+    ActiveSetPointTemperature: int | None = None
+    NormalTemperature: float | None = None
+    AwayDateTime: str | None = None
+    AwayTemperature: float | None = None
+    BoostDuration: int | None = None
+    BoostTemperature: float | None = None
+    OpenWindowEnabled: bool | None = None
+    EcoStartEnabled: bool | None = None
+    SetbackEnabled: bool | None = None
+    SetbackEnabledInStatusFrame: bool | None = None
+    SetbackTemperature: float | None = None
+    ComfortStatus: bool | None = None
+    AvailableHotWater: float | None = None
+    LockStatus: int | None = None
+    ErrorCode: str | None = None
+    WarningCode: str | None = None
+
+
+class ApplianceModeSettings(BaseModel):
+    """Settings used to control appliance modes like Boost or Away."""
+
+    ApplianceModes: int
+    Status: int
+    Temperature: float = 23.0
+    Time: int = 0
+    Date: str = "0001-01-01T00:00:00"
+    StatusTwo: int = 0
+    NumberOfDays: int = 0
+    Frequency: int = 0
+
+
+class TsiEnergyReport(BaseModel):
+    """Response from `POST /Reports/GetTsiEnergyReportDataForHub`.
+
+    The cloud returns one telemetry bucket per appliance registered to the hub.
+    Each bucket is a list of points whose individual shape is undocumented and
+    appears to vary by firmware; entries are normalised by
+    :func:`dimplex_controller.telemetry.parse_telemetry_points` so callers do
+    not have to know the wire format.
+    """
+
+    HubId: str
+    ApplianceTelemetryData: dict[str, list] = Field(default_factory=dict)
+
+
+# `TsiReportType` integer values understood by the API. We do not know the
+# canonical mapping; these are observed in traffic captures.
+TSI_REPORT_TYPE_ENERGY = 1

dimplex_controller-0.4.0/dimplex_controller/telemetry.py

@@ -0,0 +1,133 @@
+"""Telemetry parsing for the Dimplex Reports API.
+
+The response from `POST /Reports/GetTsiEnergyReportDataForHub` contains
+``ApplianceTelemetryData``: a dict keyed by appliance id, with one list of
+``telemetry points`` per appliance. The shape of each point is not documented
+and varies between firmware versions, so we normalise whatever the cloud
+sends into ``(timestamp, value)`` tuples.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from datetime import datetime, timezone
+from typing import Any
+
+# Keys the cloud has been observed using, in priority order. The first match
+# wins. Case-insensitive lookup is done by lowercasing the dict before
+# scanning, so callers do not have to worry about casing.
+_TIMESTAMP_KEYS = (
+    "timestamp",
+    "time",
+    "ts",
+    "t",
+    "datetime",
+    "date",
+    "from",
+    "start",
+)
+_VALUE_KEYS = (
+    "value",
+    "kwh",
+    "energy",
+    "consumption",
+    "energykwh",
+    "amount",
+    "v",
+)
+
+
+def _coerce_timestamp(raw: Any) -> datetime | None:
+    """Best-effort conversion of ``raw`` into a ``datetime``.
+
+    Accepts ``datetime`` instances, ISO-8601 strings, and Unix epoch numbers
+    (seconds or milliseconds). Returns ``None`` if the value cannot be parsed.
+    """
+    if raw is None:
+        return None
+    if isinstance(raw, datetime):
+        return raw
+    if isinstance(raw, int | float):
+        ts = float(raw)
+        if ts > 1e12:
+            ts = ts / 1000.0
+        try:
+            return datetime.fromtimestamp(ts, tz=timezone.utc)
+        except (OverflowError, OSError, ValueError):
+            return None
+    if isinstance(raw, str):
+        text = raw.strip()
+        if not text:
+            return None
+        try:
+            return datetime.fromisoformat(text.replace("Z", "+00:00"))
+        except ValueError:
+            return None
+    return None
+
+
+def _coerce_value(raw: Any) -> float | None:
+    """Best-effort conversion of ``raw`` into a ``float``."""
+    if raw is None:
+        return None
+    if isinstance(raw, bool):
+        return None
+    if isinstance(raw, int | float):
+        return float(raw)
+    if isinstance(raw, str):
+        try:
+            return float(raw.strip())
+        except ValueError:
+            return None
+    return None
+
+
+def _iter_items(point: Any) -> Iterable[tuple[str, Any]] | None:
+    """Yield ``(key, value)`` pairs from a dict-like ``point``.
+
+    Returns ``None`` for non-dict points so the caller can fall through to the
+    list / scalar branches.
+    """
+    if not isinstance(point, dict):
+        return None
+    lower = {str(k).lower(): v for k, v in point.items()}
+    return ((k, lower.get(k)) for k in (*_TIMESTAMP_KEYS, *_VALUE_KEYS))
+
+
+def parse_telemetry_points(points: Any) -> list[tuple[datetime | None, float]]:
+    """Normalise a list of telemetry points into ``(timestamp, value)`` pairs.
+
+    Each entry in ``points`` may be:
+
+    * a ``dict`` with one of the recognised timestamp/value keys
+    * a 2-element ``[timestamp, value]`` list or tuple
+    * a bare scalar (treated as a cumulative value at an unknown timestamp)
+
+    Unparseable entries are silently skipped. The order of the input list is
+    preserved.
+    """
+    if not isinstance(points, list):
+        return []
+
+    out: list[tuple[datetime | None, float]] = []
+    for point in points:
+        ts: datetime | None = None
+        value: float | None = None
+
+        items = _iter_items(point)
+        if items is not None:
+            for key, raw in items:
+                if key in _TIMESTAMP_KEYS and ts is None:
+                    ts = _coerce_timestamp(raw)
+                elif key in _VALUE_KEYS and value is None:
+                    value = _coerce_value(raw)
+        elif isinstance(point, list | tuple) and len(point) == 2:
+            ts = _coerce_timestamp(point[0])
+            value = _coerce_value(point[1])
+        else:
+            value = _coerce_value(point)
+
+        if value is None:
+            continue
+        out.append((ts, value))
+    return out

{dimplex_controller-0.3.0 → dimplex_controller-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "dimplex-controller"
-version = "0.3.0"
+version = "0.4.0"
 description = "Python client for Dimplex heating controllers (GDHV IoT)"
 authors = ["Kieran Roper"]
 license = "MIT"
@@ -18,6 +18,7 @@ classifiers = [
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "Topic :: Home Automation",
 ]
 packages = [{ include = "dimplex_controller" }]
@@ -31,6 +32,7 @@ python-dotenv = "^1.2.1"
 [tool.poetry.group.dev.dependencies]
 pytest = "^8.0.0"
 pytest-asyncio = "^0.23.0"
+pytest-cov = "^6.0.0"
 aresponses = "^3.0.0"
 ruff = "^0.3.0"
 pre-commit = "^3.6.0"
@@ -41,7 +43,18 @@ line-length = 120
 target-version = "py310"
 
 [tool.ruff.lint]
-select = ["E", "F", "I", "W"]
+select = ["E", "F", "I", "W", "UP", "B", "SIM"]
+# E501 (line length) is handled by the formatter; long strings/comments are fine.
+ignore = ["E501"]
+
+[tool.mypy]
+# Loose by design — the library is mostly untyped and a strict pass is out of
+# scope for the CI modernisation. The two auth.py return-narrowing issues and
+# the client.py expires_at assignment are pre-existing and either fixed in
+# place or # type: ignore-d; remove when a full typing pass lands.
+python_version = "3.10"
+files = ["dimplex_controller"]
+ignore_missing_imports = true
 
 [build-system]
 requires = ["poetry-core"]

dimplex_controller-0.3.0/dimplex_controller/models.py

@@ -1,99 +0,0 @@
-from datetime import datetime, time
-from typing import List, Optional
-
-from pydantic import BaseModel, Field
-
-
-class Appliance(BaseModel):
-    ApplianceId: str
-    ApplianceType: str
-    ApplianceModel: Optional[str] = None
-    ZoneId: str
-    FriendlyName: str
-    ZoneName: str
-    Icon: Optional[str] = None
-    IconColor: Optional[str] = None
-    InstallationDate: Optional[datetime] = None
-    HasConnectivity: Optional[bool] = None
-
-
-class Zone(BaseModel):
-    ZoneId: str
-    ZoneName: str
-    HubId: str
-    ZoneType: str
-    Appliances: List[Appliance] = Field(default_factory=list)
-
-
-class Hub(BaseModel):
-    HubId: str
-    Name: Optional[str] = Field(None, alias="HubName")
-    FriendlyName: Optional[str] = None
-
-
-class TimerPeriod(BaseModel):
-    DayOfWeek: int
-    StartTime: str  # Kept as str for easy JSON serialization
-    EndTime: str
-    Temperature: float
-
-    @property
-    def start_time_obj(self) -> time:
-        return datetime.strptime(self.StartTime, "%H:%M:%S").time()
-
-    @property
-    def end_time_obj(self) -> time:
-        return datetime.strptime(self.EndTime, "%H:%M:%S").time()
-
-
-class TimerModeSettings(BaseModel):
-    HubId: str
-    ApplianceId: str
-    TimerMode: int
-    TimerPeriods: List[TimerPeriod] = Field(default_factory=list)
-
-
-class UserContext(BaseModel):
-    Id: str
-    EmailAddress: Optional[str] = None
-    Name: Optional[str] = None
-
-
-class ApplianceStatus(BaseModel):
-    """Represents the real-time status of an appliance as returned by GetApplianceOverview."""
-
-    HubId: str
-    ApplianceId: str
-    ZoneId: str
-    StatusTwo: Optional[int] = None
-    ApplianceModes: Optional[int] = None
-    RoomTemperature: Optional[float] = None
-    ActiveSetPointTemperature: Optional[int] = None
-    NormalTemperature: Optional[float] = None
-    AwayDateTime: Optional[str] = None
-    AwayTemperature: Optional[float] = None
-    BoostDuration: Optional[int] = None
-    BoostTemperature: Optional[float] = None
-    OpenWindowEnabled: Optional[bool] = None
-    EcoStartEnabled: Optional[bool] = None
-    SetbackEnabled: Optional[bool] = None
-    SetbackEnabledInStatusFrame: Optional[bool] = None
-    SetbackTemperature: Optional[float] = None
-    ComfortStatus: Optional[bool] = None
-    AvailableHotWater: Optional[float] = None
-    LockStatus: Optional[int] = None
-    ErrorCode: Optional[str] = None
-    WarningCode: Optional[str] = None
-
-
-class ApplianceModeSettings(BaseModel):
-    """Settings used to control appliance modes like Boost or Away."""
-
-    ApplianceModes: int
-    Status: int
-    Temperature: float = 23.0
-    Time: int = 0
-    Date: str = "0001-01-01T00:00:00"
-    StatusTwo: int = 0
-    NumberOfDays: int = 0
-    Frequency: int = 0