dimplex-controller 0.13.1__tar.gz → 0.14.0__tar.gz

{dimplex_controller-0.13.1 → dimplex_controller-0.14.0}/PKG-INFO

@@ -1,15 +1,13 @@
 Metadata-Version: 2.4
 Name: dimplex-controller
-Version: 0.13.1
+Version: 0.14.0
 Summary: Unofficial async Python client for Dimplex (GDHV IoT) heating appliances — not affiliated with Glen Dimplex
-License: MIT
-License-File: LICENSE
 Keywords: dimplex,heating,control,iot,asyncio
 Author: Kieran Roper
-Requires-Python: >=3.10,<4.0
+License-Expression: MIT
+License-File: LICENSE
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Natural Language :: English
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
@@ -19,8 +17,9 @@ Classifier: Programming Language :: Python :: 3.12
 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: pydantic (>=2.0.0,<3.0.0)
+Requires-Dist: aiohttp>=3.14.3,<4
+Requires-Dist: pydantic>=2.13.5,<3
+Requires-Python: >=3.10, <4.0
 Project-URL: Homepage, https://github.com/KRoperUK/dimplex-controller-py
 Project-URL: Repository, https://github.com/KRoperUK/dimplex-controller-py
 Description-Content-Type: text/markdown
@@ -104,9 +103,12 @@ pip install .
 ```bash
 git clone https://github.com/KRoperUK/dimplex-controller-py.git
 cd dimplex-controller-py
-pip install -e ".[dev]"
+uv sync
 ```
 
+`uv sync` creates `.venv`, installs the library in editable mode, and installs the
+dev dependency group from `uv.lock`.
+
 > **Requires:** Python 3.10 or later.
 
 ## Quick start
@@ -303,7 +305,7 @@ Main client class. Construct with an `aiohttp.ClientSession` and a `refresh_toke
 
 - **`DimplexError`** — Base exception.
 - **`DimplexAuthError`** — Authentication or token errors.
-- **`DimplexApiError`** — API returned a non-success status. Contains `status` and `message`.
+- **`DimplexApiError`** — API returned a non-success status. Contains `status`, `message`, `transient` (`True` for a 5xx/429 raised after retries were exhausted, so a caller can back off rather than surface it) and an optional `code`.
 - **`DimplexConnectionError`** — Network-level failures.
 
 ## Troubleshooting
@@ -400,4 +402,3 @@ Key points:
 ## Changelog
 
 See [CHANGELOG.md](CHANGELOG.md) for version history.
-

{dimplex_controller-0.13.1 → dimplex_controller-0.14.0}/README.md

@@ -77,9 +77,12 @@ pip install .
 ```bash
 git clone https://github.com/KRoperUK/dimplex-controller-py.git
 cd dimplex-controller-py
-pip install -e ".[dev]"
+uv sync
 ```
 
+`uv sync` creates `.venv`, installs the library in editable mode, and installs the
+dev dependency group from `uv.lock`.
+
 > **Requires:** Python 3.10 or later.
 
 ## Quick start
@@ -276,7 +279,7 @@ Main client class. Construct with an `aiohttp.ClientSession` and a `refresh_toke
 
 - **`DimplexError`** — Base exception.
 - **`DimplexAuthError`** — Authentication or token errors.
-- **`DimplexApiError`** — API returned a non-success status. Contains `status` and `message`.
+- **`DimplexApiError`** — API returned a non-success status. Contains `status`, `message`, `transient` (`True` for a 5xx/429 raised after retries were exhausted, so a caller can back off rather than surface it) and an optional `code`.
 - **`DimplexConnectionError`** — Network-level failures.
 
 ## Troubleshooting

{dimplex_controller-0.13.1 → dimplex_controller-0.14.0}/dimplex_controller/client.py

@@ -274,12 +274,14 @@ class DimplexControl:
                             attempts - 1,
                             delay,
                         )
-                        last_error = DimplexApiError(resp.status, text)
+                        last_error = DimplexApiError(resp.status, text, transient=resp.status in _RETRYABLE_STATUS)
                         await asyncio.sleep(delay)
                         continue
 
                     _LOGGER.error("API request failed: %s - %s", resp.status, text)
-                    raise DimplexApiError(resp.status, text)
+                    # A 5xx/429 that reaches here was retried and still failed, so it
+                    # is transient (back off); a 4xx is a hard failure (surface it).
+                    raise DimplexApiError(resp.status, text, transient=resp.status in _RETRYABLE_STATUS)
             except (aiohttp.ClientError, asyncio.TimeoutError) as e:
                 if allow_retry and attempt + 1 < attempts:
                     delay = self._backoff_seconds(attempt)

{dimplex_controller-0.13.1 → dimplex_controller-0.14.0}/dimplex_controller/exceptions.py

@@ -79,11 +79,31 @@ class DimplexAuthTransientError(DimplexAuthError):
 
 
 class DimplexApiError(DimplexError):
-    """Exception for API errors."""
+    """Exception for API errors.
 
-    def __init__(self, status: int, message: str):
+    Attributes:
+        status: HTTP status returned by the API.
+        message: Short server message (never a full token).
+        transient: ``True`` when the failure may succeed on retry — a 5xx or 429
+            raised only after ``client.py`` exhausted its internal retries. ``False``
+            for a hard 4xx (404/400/403). Callers (e.g. the Home Assistant
+            coordinator) back off and keep entities available on ``transient``, and
+            surface the error otherwise.
+        code: Optional stable, machine-readable identifier.
+    """
+
+    def __init__(
+        self,
+        status: int,
+        message: str,
+        *,
+        transient: bool = False,
+        code: str | None = None,
+    ):
         self.status = status
         self.message = message
+        self.transient = transient
+        self.code = code
         super().__init__(f"API Error {status}: {message}")
 
 

{dimplex_controller-0.13.1 → dimplex_controller-0.14.0}/dimplex_controller/models.py

@@ -287,6 +287,14 @@ class ApplianceStatus(BaseModel):
     ErrorCode: str | None = None
     WarningCode: str | None = None
 
+    @field_validator("ErrorCode", "WarningCode", mode="before")
+    @classmethod
+    def _coerce_code(cls, value: Any) -> Any:
+        # GetApplianceOverview sends these as integers (0 when healthy).
+        if isinstance(value, int) and not isinstance(value, bool):
+            return str(value)
+        return value
+
     @property
     def mode_flags(self) -> ApplianceModeFlag:
         """Return ``ApplianceModes`` as a typed flag set."""

{dimplex_controller-0.13.1 → dimplex_controller-0.14.0}/dimplex_controller/telemetry.py

@@ -117,6 +117,15 @@ def _coerce_timestamp(raw: Any) -> datetime | None:
         return raw
     if isinstance(raw, int | float):
         ts = float(raw)
+        # Seconds-vs-milliseconds disambiguation is magnitude-only, which is safe for
+        # the data this parses: a Unix *seconds* epoch does not reach 1e12 until the
+        # year ~33658, and the cloud emits second-resolution `TS` values, so anything
+        # above the threshold is a millisecond epoch. The converse edge is not
+        # defended — a millisecond epoch before 2001-09-09 (< 1e12) would be misread
+        # as seconds — because the cloud has never produced one. A value just below
+        # 1e12 read as seconds lands past datetime's representable range and is
+        # dropped by the guard below rather than mis-parsed. See
+        # dimplex-controller-py#121 for why this is intentional rather than a gap.
         if ts > 1e12:
             ts = ts / 1000.0
         try:
@@ -276,6 +285,11 @@ def summarise_energy(
     ``points`` may be raw cloud payloads or already-parsed
     :data:`TelemetryPoint` tuples. When raw, they are passed through
     :func:`parse_telemetry_points` first.
+
+    Points with no parseable timestamp (``ts is None``) are excluded from the
+    total in **every** mode. They cannot be placed on a calendar day, so
+    counting them only in ``lifetime`` would make the cumulative total disagree
+    with the sum of the per-day totals (dimplex-controller-py#120).
     """
     parsed: list[TelemetryPoint]
     if (
@@ -306,8 +320,16 @@ def summarise_energy(
             mode="daily",
         )
 
-    # lifetime — include every parseable point; window — optional start/end filter
-    selected = filter_telemetry_points(parsed, start=start, end=end, tz=tz) if mode == "window" else list(parsed)
+    # lifetime / window — totals must reconcile with the per-day totals, so a point
+    # with no parseable timestamp is dropped from both. A ``ts is None`` point cannot
+    # be placed on any calendar day (``daily``/``window`` already drop it via
+    # ``filter_telemetry_points``), so counting it only in the lifetime total made the
+    # cumulative meter disagree with the sum of its days — silent drift into the HA
+    # Energy Dashboard's TOTAL_INCREASING sensor (dimplex-controller-py#120).
+    if mode == "window":
+        selected = filter_telemetry_points(parsed, start=start, end=end, tz=tz)
+    else:
+        selected = [(ts, value) for ts, value in parsed if ts is not None]
 
     timestamps = [ts for ts, _ in selected if ts is not None]
     total = sum(v for _, v in selected)

dimplex_controller-0.14.0/pyproject.toml

@@ -0,0 +1,96 @@
+[project]
+name = "dimplex-controller"
+version = "0.14.0"
+description = "Unofficial async Python client for Dimplex (GDHV IoT) heating appliances — not affiliated with Glen Dimplex"
+license = "MIT"
+license-files = ["LICENSE"]
+readme = "README.md"
+requires-python = ">=3.10,<4.0"
+keywords = [
+    "dimplex",
+    "heating",
+    "control",
+    "iot",
+    "asyncio",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Natural Language :: English",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Home Automation",
+]
+dependencies = [
+    "aiohttp>=3.14.3,<4",
+    "pydantic>=2.13.5,<3",
+]
+
+[[project.authors]]
+name = "Kieran Roper"
+
+[project.urls]
+Homepage = "https://github.com/KRoperUK/dimplex-controller-py"
+Repository = "https://github.com/KRoperUK/dimplex-controller-py"
+
+[project.scripts]
+dimplex = "dimplex_controller.cli:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1,<10",
+    "pytest-asyncio>=1.4.0,<2",
+    "pytest-cov>=7.1.0,<8",
+    "aresponses>=3.0.0,<4",
+    "ruff>=0.16.7,<0.17",
+    "pre-commit>=4.6.2,<5",
+    "twine>=7.0.0,<8",
+    "python-dotenv>=1.2.3,<2",
+    "mypy>=2.3.1,<3",
+]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+extend-exclude = ["*.md"]
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "W",
+    "UP",
+    "B",
+    "SIM",
+]
+ignore = ["E501"]
+
+[tool.mypy]
+python_version = "3.10"
+files = ["dimplex_controller"]
+ignore_missing_imports = true
+strict = true
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.coverage.run]
+source = ["dimplex_controller"]
+
+[tool.coverage.report]
+show_missing = true
+fail_under = 80
+
+[tool.uv.build-backend]
+module-root = ""
+
+[build-system]
+requires = ["uv_build>=0.11.19,<0.13.0"]
+build-backend = "uv_build"

dimplex_controller-0.13.1/pyproject.toml → dimplex_controller-0.14.0/pyproject.toml.orig

@@ -1,17 +1,16 @@
-[tool.poetry]
+[project]
 name = "dimplex-controller"
-version = "0.13.1"
+version = "0.14.0"
 description = "Unofficial async Python client for Dimplex (GDHV IoT) heating appliances — not affiliated with Glen Dimplex"
-authors = ["Kieran Roper"]
+authors = [{ name = "Kieran Roper" }]
 license = "MIT"
+license-files = ["LICENSE"]
 readme = "README.md"
-homepage = "https://github.com/KRoperUK/dimplex-controller-py"
-repository = "https://github.com/KRoperUK/dimplex-controller-py"
+requires-python = ">=3.10,<4.0"
 keywords = ["dimplex", "heating", "control", "iot", "asyncio"]
 classifiers = [
     "Development Status :: 5 - Production/Stable",
     "Intended Audience :: Developers",
-    "License :: OSI Approved :: MIT License",
     "Natural Language :: English",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
@@ -19,32 +18,48 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Home Automation",
 ]
-packages = [{ include = "dimplex_controller" }]
+# Lower bounds are the versions this release was developed and tested against;
+# the upper bounds keep the previous caret semantics (a caret range is
+# `>=X,<next-major`), so consumers gain no surprise from the migration.
+dependencies = [
+    "aiohttp>=3.14.3,<4",
+    "pydantic>=2.13.5,<3",
+]
 
-[tool.poetry.scripts]
-dimplex = "dimplex_controller.cli:main"
+[project.urls]
+Homepage = "https://github.com/KRoperUK/dimplex-controller-py"
+Repository = "https://github.com/KRoperUK/dimplex-controller-py"
 
-[tool.poetry.dependencies]
-python = "^3.10"
-aiohttp = "^3.9.0"
-pydantic = "^2.0.0"
+[project.scripts]
+dimplex = "dimplex_controller.cli:main"
 
-[tool.poetry.group.dev.dependencies]
-pytest = "^8.0.0"
-pytest-asyncio = "^1.0.0"
-pytest-cov = "^6.0.0"
-aresponses = "^3.0.0"
-ruff = "^0.15.0"
-pre-commit = "^3.6.0"
-twine = "^6.2.0"
-python-dotenv = "^1.2.1"
-mypy = "^1.0.0"
+# PEP 735 dependency groups: not installed into a consumer's environment, only
+# into a development one.
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1,<10",
+    "pytest-asyncio>=1.4.0,<2",
+    "pytest-cov>=7.1.0,<8",
+    "aresponses>=3.0.0,<4",
+    "ruff>=0.16.7,<0.17",
+    "pre-commit>=4.6.2,<5",
+    "twine>=7.0.0,<8",
+    "python-dotenv>=1.2.3,<2",
+    "mypy>=2.3.1,<3",
+]
 
 [tool.ruff]
 line-length = 120
 target-version = "py310"
+# Python inside Markdown is not formatted here. The code blocks in README.md and
+# docs/ carry deliberate column alignment (see the temperature-constant table in
+# docs/api-reference.md) and ruff's formatter normalises comment spacing, so
+# formatting them would trade readable docs for tool uniformity. This also keeps a
+# bare `ruff format .` in step with the pre-commit hooks, which are python/pyi only.
+extend-exclude = ["*.md"]
 
 [tool.ruff.lint]
 select = ["E", "F", "I", "W", "UP", "B", "SIM"]
@@ -81,5 +96,11 @@ show_missing = true
 fail_under = 80
 
 [build-system]
-requires = ["poetry-core"]
-build-backend = "poetry.core.masonry.api"
+requires = ["uv_build>=0.11.19,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+# The package is at the repository root, not under src/, which is what uv_build
+# assumes by default. The module name is inferred from the project name
+# (dimplex-controller -> dimplex_controller), so it needs no override.
+module-root = ""