python-bsblan 6.1.5__tar.gz → 6.1.7__tar.gz

{python_bsblan-6.1.5 → python_bsblan-6.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-bsblan
-Version: 6.1.5
+Version: 6.1.7
 Summary: Asynchronous Python client for BSBLAN API
 Project-URL: Homepage, https://github.com/liudger/python-bsblan
 Project-URL: Repository, https://github.com/liudger/python-bsblan

{python_bsblan-6.1.5 → python_bsblan-6.1.7}/docs/api/exceptions.md

@@ -13,3 +13,11 @@ Custom exceptions raised by the library.
 ## BSBLANAuthError
 
 ::: bsblan.BSBLANAuthError
+
+## BSBLANUnsupportedFeatureError
+
+::: bsblan.BSBLANUnsupportedFeatureError
+
+## BSBLANMalformedResponseError
+
+::: bsblan.BSBLANMalformedResponseError

python_bsblan-6.1.7/openspec/changes/archive/2026-07-12-distinguish-schedule-error-types/.openspec.yaml

@@ -0,0 +1,3 @@
+---
+schema: spec-driven
+created: 2026-07-12

python_bsblan-6.1.7/openspec/changes/archive/2026-07-12-distinguish-schedule-error-types/design.md

@@ -0,0 +1,101 @@
+## Context
+
+`python-bsblan` currently exposes a single generic `BSBLANError` for a wide
+range of failure modes. Two of them are semantically opposite from a retry
+standpoint:
+
+- **Unsupported schedule** — the device does not expose the requested
+  time-program parameters. In `_schedules.heating_schedule()` this raises
+  `BSBLANError(ErrorMsg.NO_HEATING_SCHEDULE_PARAMS)`, and in
+  `_hot_water._get_filtered_data()` it raises `BSBLANError(error_msg)` for the
+  hot-water schedule group. This is a **permanent** condition.
+- **Malformed response** — the transport cannot decode or JSON-parse the body.
+  In `_transport.request_with_retry()` this is caught from `ValueError` /
+  `UnicodeDecodeError` and re-raised as
+  `BSBLANError(ErrorMsg.INVALID_RESPONSE.format(e))`. This is a **transient**
+  condition.
+
+Because both surface as `BSBLANError`, a downstream integration (Home Assistant)
+cannot decide whether to retry. It must either stop retrying (losing recovery
+from transient malformed responses) or retry forever (uselessly hammering a
+device that will never support a schedule after a write).
+
+The library's own `backoff` decorator only retries `TimeoutError` and
+`aiohttp.ClientError`, so `BSBLANError` is never retried inside the library; the
+retry decision lives in the consumer. The fix is therefore an additive exception
+taxonomy, not a change to the transport retry policy.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Let callers distinguish permanent unsupported-feature failures from transient
+  malformed-response failures by `except` type.
+- Keep the change fully backward compatible with existing `except BSBLANError`
+  handlers.
+- Reuse existing `ErrorMsg` strings; no message wording changes.
+
+**Non-Goals:**
+- Changing the transport-level `backoff` retry policy or which HTTP statuses are
+  retried (`client-retry-policy` is unchanged).
+- Adding automatic retry logic inside the library for schedules.
+- Reclassifying other existing `BSBLANError` raise sites beyond schedule reads
+  and malformed-response parsing.
+
+## Decisions
+
+**Decision: Two new subclasses of `BSBLANError`.**
+Add `BSBLANUnsupportedFeatureError` (permanent) and
+`BSBLANMalformedResponseError` (transient), both subclassing `BSBLANError`.
+Subclassing preserves backward compatibility: any existing `except BSBLANError`
+keeps catching them.
+- *Alternative considered:* a single new error with a `retryable: bool`
+  attribute. Rejected — attribute inspection is less idiomatic than `except`
+  type matching and easier to get wrong at call sites.
+- *Alternative considered:* schedule-specific name (e.g.
+  `BSBLANUnsupportedScheduleError`). Chose the more general
+  `BSBLANUnsupportedFeatureError` because the same permanent semantics apply to
+  both heating and hot-water schedule reads and can extend to other
+  unsupported-parameter cases later.
+
+**Decision: Raise the permanent error at the schedule-read guard sites.**
+Replace the bare `BSBLANError(...)` at
+`_schedules.heating_schedule()` (no mapped data) and the hot-water schedule
+branch in `_hot_water._get_filtered_data()` with
+`BSBLANUnsupportedFeatureError`, keeping the existing `ErrorMsg` text. The
+hot-water helper is shared by state/config/schedule reads, so scope the new
+error to the schedule group only (via `group_name == "schedule"`) to avoid
+reclassifying unrelated state/config failures.
+
+**Decision: Raise the transient error at the transport parse site.**
+In `_transport.request_with_retry()`, replace the
+`raise BSBLANError(msg)` in the `(ValueError, UnicodeDecodeError)` handler with
+`raise BSBLANMalformedResponseError(msg)`, reusing
+`ErrorMsg.INVALID_RESPONSE`.
+
+**Decision: Export the new exceptions from the package.**
+Add both classes to `bsblan.exceptions` and to the package `__all__` /
+re-exports so consumers can import them from the top-level `bsblan` namespace.
+
+## Risks / Trade-offs
+
+- **[Consumers catching the narrow generic message string]** → Mitigation:
+  messages are unchanged; only the concrete type is narrower. Broad
+  `except BSBLANError` still works.
+- **[Over-scoping the hot-water helper]** → Mitigation: gate the new error on the
+  schedule group so state/config reads keep raising the existing generic error
+  and existing tests stay green.
+- **[Missed raise site]** → Mitigation: grep for `NO_HEATING_SCHEDULE_PARAMS`,
+  the hot-water schedule `error_msg`, and `INVALID_RESPONSE` to confirm all
+  targeted sites are updated; add tests asserting the concrete types.
+
+## Migration Plan
+
+Additive, no migration required. Release as a minor version. Consumers may
+optionally add narrower `except BSBLANUnsupportedFeatureError` /
+`except BSBLANMalformedResponseError` handlers; existing code is unaffected.
+
+## Open Questions
+
+- Final class names: `BSBLANUnsupportedFeatureError` vs
+  `BSBLANUnsupportedScheduleError`. Proposed the broader name; confirm during
+  review.

python_bsblan-6.1.7/openspec/changes/archive/2026-07-12-distinguish-schedule-error-types/proposal.md

@@ -0,0 +1,49 @@
+## Why
+
+In python-bsblan 6.1.6 both an *unsupported schedule* (a device that will never
+return the requested time-program parameters) and a *malformed response* (a
+transient decode/parse failure) are surfaced as the same generic `BSBLANError`.
+Downstream integrations such as Home Assistant cannot tell them apart by
+exception type, so they must choose between stopping retries on a transient
+malformed response or retrying an unsupported schedule indefinitely after a
+write. A dedicated exception taxonomy is needed at the library level to make the
+permanent-vs-transient distinction explicit.
+
+## What Changes
+
+- Add a dedicated **permanent** exception `BSBLANUnsupportedFeatureError`
+  (subclass of `BSBLANError`) raised when a device does not expose the requested
+  schedule parameters, so callers know retrying will never succeed.
+- Add a dedicated **transient** exception `BSBLANMalformedResponseError`
+  (subclass of `BSBLANError`) raised when a response body cannot be decoded or
+  parsed as valid JSON, signalling that a retry may succeed.
+- Raise `BSBLANUnsupportedFeatureError` in the heating- and hot-water-schedule
+  read paths where a bare `BSBLANError` is currently raised for absent schedule
+  parameters.
+- Raise `BSBLANMalformedResponseError` in the transport layer where invalid
+  JSON / decode errors are currently wrapped in a bare `BSBLANError`.
+- Both new exceptions subclass `BSBLANError`, so existing `except BSBLANError`
+  handlers keep working (non-breaking).
+
+## Capabilities
+
+### New Capabilities
+- `error-classification`: A library exception taxonomy that distinguishes
+  permanent unsupported-feature failures from transient malformed-response
+  failures, letting callers make correct retry decisions.
+
+### Modified Capabilities
+<!-- No existing spec's requirements change; client-retry-policy behavior is unaffected. -->
+
+## Impact
+
+- `src/bsblan/exceptions.py`: two new exception classes.
+- `src/bsblan/_schedules.py` and `src/bsblan/_hot_water.py`: raise the new
+  unsupported-feature error for absent schedule parameters.
+- `src/bsblan/_transport.py`: raise the new malformed-response error for
+  decode/parse failures.
+- `src/bsblan/constants.py`: no new messages required; existing `ErrorMsg`
+  entries are reused.
+- `tests/`: new coverage asserting the specific exception types are raised.
+- Public API: additive only. Consumers relying on `BSBLANError` are unaffected;
+  consumers can opt into finer-grained handling.

python_bsblan-6.1.7/openspec/changes/archive/2026-07-12-distinguish-schedule-error-types/specs/error-classification/spec.md

@@ -0,0 +1,50 @@
+## ADDED Requirements
+
+### Requirement: Unsupported schedules raise a permanent error
+
+The client SHALL raise `BSBLANUnsupportedFeatureError` (a subclass of
+`BSBLANError`) when a schedule read cannot proceed because the device exposes no
+schedule parameters for the requested feature. This error MUST signal a
+permanent condition so callers know that retrying the same request will never
+succeed.
+
+#### Scenario: Heating schedule parameters absent
+
+- **WHEN** `heating_schedule()` is called for a circuit whose time-program
+  parameters are not present in the device response (no schedule parameters can
+  be mapped)
+- **THEN** the client raises `BSBLANUnsupportedFeatureError`
+- **AND** the raised exception is also an instance of `BSBLANError`
+
+#### Scenario: Hot water schedule parameters absent
+
+- **WHEN** `schedule()` is called on a device that exposes no hot-water
+  time-program parameters after include filtering
+- **THEN** the client raises `BSBLANUnsupportedFeatureError`
+- **AND** the raised exception is also an instance of `BSBLANError`
+
+### Requirement: Malformed responses raise a transient error
+
+The client SHALL raise `BSBLANMalformedResponseError` (a subclass of
+`BSBLANError`) when a device response body cannot be decoded or parsed as valid
+JSON. This error MUST signal a transient condition so callers know that a retry
+may succeed.
+
+#### Scenario: Response body is not valid JSON
+
+- **WHEN** a request receives an HTTP `200` response whose body cannot be parsed
+  as JSON
+- **THEN** the client raises `BSBLANMalformedResponseError`
+- **AND** the raised exception is also an instance of `BSBLANError`
+
+### Requirement: New exceptions preserve backward compatibility
+
+Both `BSBLANUnsupportedFeatureError` and `BSBLANMalformedResponseError` SHALL
+subclass `BSBLANError` so that existing `except BSBLANError` handlers continue to
+catch them without modification.
+
+#### Scenario: Existing broad handler still catches new errors
+
+- **WHEN** code catches `BSBLANError` around a call that raises either
+  `BSBLANUnsupportedFeatureError` or `BSBLANMalformedResponseError`
+- **THEN** the exception is caught by the `BSBLANError` handler

python_bsblan-6.1.7/openspec/changes/archive/2026-07-12-distinguish-schedule-error-types/tasks.md

@@ -0,0 +1,28 @@
+## 1. Exceptions
+
+- [x] 1.1 Add `BSBLANUnsupportedFeatureError(BSBLANError)` to `src/bsblan/exceptions.py` with a docstring describing it as a permanent (non-retryable) condition.
+- [x] 1.2 Add `BSBLANMalformedResponseError(BSBLANError)` to `src/bsblan/exceptions.py` with a docstring describing it as a transient (retryable) condition.
+- [x] 1.3 Import and re-export both new exceptions in `src/bsblan/__init__.py` and add them to `__all__`.
+
+## 2. Schedule read paths (permanent error)
+
+- [x] 2.1 In `src/bsblan/_schedules.py` `heating_schedule()`, raise `BSBLANUnsupportedFeatureError(ErrorMsg.NO_HEATING_SCHEDULE_PARAMS)` when no schedule parameters are mapped (replace the bare `BSBLANError`).
+- [x] 2.2 In `src/bsblan/_hot_water.py` `fetch_data()`, raise `BSBLANUnsupportedFeatureError(error_msg)` when the schedule group (`group_name == "schedule"`) has no filtered params, keeping other groups on the existing generic error.
+- [x] 2.3 Update the `Raises:` docstrings on the affected schedule methods to reference the new exception type.
+
+## 3. Transport parse path (transient error)
+
+- [x] 3.1 In `src/bsblan/_transport.py` `request_with_retry()`, raise `BSBLANMalformedResponseError(msg)` from the `(ValueError, UnicodeDecodeError)` handler (replace the bare `BSBLANError`), reusing `ErrorMsg.INVALID_RESPONSE`.
+- [x] 3.2 Update the `Raises:` docstring on `request_with_retry()` to reference the new exception type.
+
+## 4. Tests
+
+- [x] 4.1 Add a test asserting `heating_schedule()` raises `BSBLANUnsupportedFeatureError` when schedule params are absent, and that it is also a `BSBLANError`.
+- [x] 4.2 Add a test asserting hot-water `schedule()` raises `BSBLANUnsupportedFeatureError` when schedule params are absent.
+- [x] 4.3 Add a test asserting a non-JSON / undecodable response raises `BSBLANMalformedResponseError` and that it is also a `BSBLANError`.
+- [x] 4.4 Verify existing state/config hot-water tests still raise the generic `BSBLANError` (no regression from the group gating).
+
+## 5. Documentation & validation
+
+- [x] 5.1 Document the two new exceptions in `docs/api/exceptions.md`.
+- [x] 5.2 Run `uv run prek run --all-files` and `uv run pytest --cov=src/bsblan --cov-report=term-missing`; ensure total coverage stays >= 95% and patch coverage is 100%.

python_bsblan-6.1.7/openspec/specs/error-classification/spec.md

@@ -0,0 +1,59 @@
+# error-classification
+
+## Purpose
+
+A library exception taxonomy that distinguishes permanent unsupported-feature
+failures from transient malformed-response failures, letting callers make
+correct retry decisions. Both new exceptions subclass `BSBLANError` so existing
+broad handlers keep working.
+
+## Requirements
+
+### Requirement: Unsupported schedules raise a permanent error
+
+The client SHALL raise `BSBLANUnsupportedFeatureError` (a subclass of
+`BSBLANError`) when a schedule read cannot proceed because the device exposes no
+schedule parameters for the requested feature. This error MUST signal a
+permanent condition so callers know that retrying the same request will never
+succeed.
+
+#### Scenario: Heating schedule parameters absent
+
+- **WHEN** `heating_schedule()` is called for a circuit whose time-program
+  parameters are not present in the device response (no schedule parameters can
+  be mapped)
+- **THEN** the client raises `BSBLANUnsupportedFeatureError`
+- **AND** the raised exception is also an instance of `BSBLANError`
+
+#### Scenario: Hot water schedule parameters absent
+
+- **WHEN** `schedule()` is called on a device that exposes no hot-water
+  time-program parameters after include filtering
+- **THEN** the client raises `BSBLANUnsupportedFeatureError`
+- **AND** the raised exception is also an instance of `BSBLANError`
+
+### Requirement: Malformed responses raise a transient error
+
+The client SHALL raise `BSBLANMalformedResponseError` (a subclass of
+`BSBLANError`) when a device response body cannot be decoded or parsed as valid
+JSON. This error MUST signal a transient condition so callers know that a retry
+may succeed.
+
+#### Scenario: Response body is not valid JSON
+
+- **WHEN** a request receives an HTTP `200` response whose body cannot be parsed
+  as JSON
+- **THEN** the client raises `BSBLANMalformedResponseError`
+- **AND** the raised exception is also an instance of `BSBLANError`
+
+### Requirement: New exceptions preserve backward compatibility
+
+Both `BSBLANUnsupportedFeatureError` and `BSBLANMalformedResponseError` SHALL
+subclass `BSBLANError` so that existing `except BSBLANError` handlers continue to
+catch them without modification.
+
+#### Scenario: Existing broad handler still catches new errors
+
+- **WHEN** code catches `BSBLANError` around a call that raises either
+  `BSBLANUnsupportedFeatureError` or `BSBLANMalformedResponseError`
+- **THEN** the exception is caught by the `BSBLANError` handler

{python_bsblan-6.1.5 → python_bsblan-6.1.7}/package-lock.json

@@ -12,13 +12,13 @@
         "url-parse": "1.5.10"
       },
       "devDependencies": {
-        "prettier": "3.9.4"
+        "prettier": "3.9.5"
       }
     },
     "node_modules/prettier": {
-      "version": "3.9.4",
-      "resolved": "https://registry.npmjs.org/prettier/-/prettier-3.9.4.tgz",
-      "integrity": "sha512-yWG/o/4oJfo036EKAfK6ACAoDOfHeRHx4tuxkfBZiauURiaSmYwlpOr5LQqKtIkRD2z1PLteme2WoxEnj4tHTg==",
+      "version": "3.9.5",
+      "resolved": "https://registry.npmjs.org/prettier/-/prettier-3.9.5.tgz",
+      "integrity": "sha512-/FVl766LpUfB5vXgCYOYa0MeV/441Ia99AeICQIQFTY/Nw0roZwULcXpku5i1/m5kt/baz+s4Zogspd839HSMg==",
       "dev": true,
       "license": "MIT",
       "bin": {

{python_bsblan-6.1.5 → python_bsblan-6.1.7}/package.json

@@ -9,7 +9,7 @@
   "author": "WJL van Rootselaar <liudgervr@gmail.com>",
   "license": "MIT",
   "devDependencies": {
-    "prettier": "3.9.4"
+    "prettier": "3.9.5"
   },
   "dependencies": {
     "url-parse": "1.5.10"

{python_bsblan-6.1.5 → python_bsblan-6.1.7}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-bsblan"
-version = "6.1.5"
+version = "6.1.7"
 description = "Asynchronous Python client for BSBLAN API"
 authors = [
     {name = "Willem-Jan van Rootselaar", email = "liudgervr@gmail.com"}
@@ -196,7 +196,7 @@ dev = [
     # hatch is required to support type hinting and proper packaging of the py.typed file.
     "hatch>=1.14.1",
     "isort==8.0.1",
-    "ty==0.0.55",
+    "ty==0.0.56",
     "prek>=0.3.3",
     "pre-commit-hooks==6.0.0",
     "pylint==4.0.5",

{python_bsblan-6.1.5 → python_bsblan-6.1.7}/src/bsblan/__init__.py

@@ -12,6 +12,8 @@ from .exceptions import (
     BSBLANAuthError,
     BSBLANConnectionError,
     BSBLANError,
+    BSBLANMalformedResponseError,
+    BSBLANUnsupportedFeatureError,
     BSBLANVersionError,
 )
 from .models import (
@@ -45,6 +47,8 @@ __all__ = [
     "BSBLANConfig",
     "BSBLANConnectionError",
     "BSBLANError",
+    "BSBLANMalformedResponseError",
+    "BSBLANUnsupportedFeatureError",
     "BSBLANVersionError",
     "DHWSchedule",
     "DHWTimeSwitchPrograms",

{python_bsblan-6.1.5 → python_bsblan-6.1.7}/src/bsblan/_hot_water.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 from typing import TYPE_CHECKING, Any, TypeVar
 
 from .constants import ErrorMsg, HotWaterParams
-from .exceptions import BSBLANError
+from .exceptions import BSBLANError, BSBLANUnsupportedFeatureError
 from .models import (
     HotWaterConfig,
     HotWaterSchedule,
@@ -87,7 +87,10 @@ class HotWaterManager:
             The populated model instance.
 
         Raises:
-            BSBLANError: If no parameters are available for the filter.
+            BSBLANUnsupportedFeatureError: If the schedule group exposes no
+                parameters (a permanent condition).
+            BSBLANError: If no parameters are available for a non-schedule
+                group.
 
         """
         # Granular lazy load: validate only this param group on first access
@@ -105,6 +108,8 @@ class HotWaterManager:
         filtered_params = self._apply_include_filter(filtered_params, include)
 
         if not filtered_params:
+            if group_name == "schedule":
+                raise BSBLANUnsupportedFeatureError(error_msg)
             raise BSBLANError(error_msg)
 
         data = await self._request_named_params(filtered_params)

{python_bsblan-6.1.5 → python_bsblan-6.1.7}/src/bsblan/_schedules.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 from typing import TYPE_CHECKING, Any
 
 from .constants import ErrorMsg, HeatingScheduleParams, HotWaterParams
-from .exceptions import BSBLANError
+from .exceptions import BSBLANError, BSBLANUnsupportedFeatureError
 from .models import HeatingTimeSwitchPrograms
 
 if TYPE_CHECKING:
@@ -62,7 +62,8 @@ class ScheduleManager:
             HeatingTimeSwitchPrograms: Heating schedule information.
 
         Raises:
-            BSBLANError: If no schedule parameters are available.
+            BSBLANUnsupportedFeatureError: If the device exposes no heating
+                schedule parameters (a permanent condition).
 
         """
         self._validate_circuit(circuit)
@@ -79,7 +80,7 @@ class ScheduleManager:
         }
 
         if not mapped_data:
-            raise BSBLANError(ErrorMsg.NO_HEATING_SCHEDULE_PARAMS)
+            raise BSBLANUnsupportedFeatureError(ErrorMsg.NO_HEATING_SCHEDULE_PARAMS)
 
         return HeatingTimeSwitchPrograms.model_validate(mapped_data)
 

{python_bsblan-6.1.5 → python_bsblan-6.1.7}/src/bsblan/_transport.py

@@ -9,6 +9,7 @@ stable ``_request`` facade that delegates here.
 from __future__ import annotations
 
 import asyncio
+import json
 import logging
 from typing import TYPE_CHECKING, Any, cast
 
@@ -19,7 +20,7 @@ from packaging import version as pkg_version
 from yarl import URL
 
 from .constants import ErrorMsg
-from .exceptions import BSBLANAuthError, BSBLANError
+from .exceptions import BSBLANAuthError, BSBLANError, BSBLANMalformedResponseError
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Mapping
@@ -109,8 +110,10 @@ class BSBLANTransport:
             dict[str, Any]: The JSON response from the BSBLAN device.
 
         Raises:
-            BSBLANError: If the session is missing or the response is invalid.
+            BSBLANError: If the session is missing.
             BSBLANAuthError: If authentication fails (401/403, not retried).
+            BSBLANMalformedResponseError: If the response body cannot be
+                decoded or parsed as JSON (a transient condition).
 
         """
         session = self._session_getter()
@@ -131,7 +134,7 @@ class BSBLANTransport:
                     headers=headers,
                 ) as response:
                     response.raise_for_status()
-                    response_data = cast("dict[str, Any]", await response.json())
+                    response_data = await self._read_json(response)
                     return self._process_response(response_data, base_path)
         except aiohttp.ClientResponseError as e:
             if e.status in HTTP_AUTH_STATUSES:
@@ -140,7 +143,34 @@ class BSBLANTransport:
         except (ValueError, UnicodeDecodeError) as e:
             # Handle JSON decode errors and other parsing issues
             msg = ErrorMsg.INVALID_RESPONSE.format(e)
-            raise BSBLANError(msg) from e
+            raise BSBLANMalformedResponseError(msg) from e
+
+    @staticmethod
+    async def _read_json(response: aiohttp.ClientResponse) -> dict[str, Any]:
+        """Decode a BSB-LAN JSON response tolerant of non-UTF-8 encodings.
+
+        Some BSB-LAN firmwares serve custom parameter descriptions using
+        Latin-1 (ISO-8859-1) bytes (for example the ``§`` or ``°`` characters)
+        while declaring no charset. ``aiohttp`` assumes UTF-8 and raises
+        ``UnicodeDecodeError``. Read the raw body and fall back to Latin-1,
+        which can decode any byte sequence, before parsing the JSON.
+
+        Args:
+            response: The active aiohttp response to read.
+
+        Returns:
+            dict[str, Any]: The parsed JSON payload.
+
+        Raises:
+            ValueError: If the body is not valid JSON.
+
+        """
+        raw = await response.read()
+        try:
+            text = raw.decode("utf-8")
+        except UnicodeDecodeError:
+            text = raw.decode("latin-1")
+        return cast("dict[str, Any]", json.loads(text))
 
     def _process_response(
         self, response_data: dict[str, Any], base_path: str

{python_bsblan-6.1.5 → python_bsblan-6.1.7}/src/bsblan/exceptions.py

@@ -77,3 +77,20 @@ class BSBLANAuthError(BSBLANError):
     """Raised when authentication fails."""
 
     message: str = "Authentication failed. Please check your username and password."
+
+
+class BSBLANUnsupportedFeatureError(BSBLANError):
+    """Raised when the device does not support a requested feature.
+
+    This signals a permanent condition: the device does not expose the
+    requested parameters (for example a heating or hot water schedule), so
+    retrying the same request will never succeed.
+    """
+
+
+class BSBLANMalformedResponseError(BSBLANError):
+    """Raised when a device response cannot be decoded or parsed.
+
+    This signals a transient condition: the response body could not be decoded
+    or parsed as valid JSON, so a retry may succeed.
+    """

{python_bsblan-6.1.5 → python_bsblan-6.1.7}/tests/test_bsblan_edge_cases.py

@@ -9,7 +9,11 @@ import aiohttp
 import pytest
 
 from bsblan import BSBLAN, BSBLANConfig
-from bsblan.exceptions import BSBLANConnectionError, BSBLANError
+from bsblan.exceptions import (
+    BSBLANConnectionError,
+    BSBLANError,
+    BSBLANMalformedResponseError,
+)
 
 
 @pytest.mark.asyncio
@@ -71,15 +75,20 @@ async def test_value_error_path(monkeypatch: Any) -> None:
         # Mock a successful response but with invalid JSON processing
         mock_response = MagicMock()
         mock_response.raise_for_status = MagicMock()
-        mock_response.json = AsyncMock(side_effect=ValueError("Invalid JSON"))
+        mock_response.read = AsyncMock(return_value=b"Invalid JSON")
         mock_response.__aenter__ = AsyncMock(return_value=mock_response)
         mock_response.__aexit__ = AsyncMock(return_value=None)
 
         monkeypatch.setattr(session, "request", MagicMock(return_value=mock_response))
 
-        with pytest.raises(BSBLANError, match="Invalid JSON"):
+        with pytest.raises(
+            BSBLANMalformedResponseError, match="Invalid response format"
+        ) as exc_info:
             await bsblan._request()
 
+        # Transient error must remain catchable as the generic BSBLANError.
+        assert isinstance(exc_info.value, BSBLANError)
+
 
 def test_bsblan_config_initialization_edge_cases() -> None:
     """Test edge cases in BSBLAN initialization."""

{python_bsblan-6.1.5 → python_bsblan-6.1.7}/tests/test_heating_schedule.py

@@ -7,7 +7,7 @@ from unittest.mock import AsyncMock
 
 import pytest
 
-from bsblan.exceptions import BSBLANError
+from bsblan.exceptions import BSBLANError, BSBLANUnsupportedFeatureError
 from bsblan.models import HeatingTimeSwitchPrograms
 
 if TYPE_CHECKING:
@@ -138,8 +138,14 @@ async def test_heating_schedule_invalid_include_raises(mock_bsblan: BSBLAN) -> N
 
 @pytest.mark.asyncio
 async def test_heating_schedule_no_params_raises(mock_bsblan: BSBLAN) -> None:
-    """Test no schedule params in response raises error."""
+    """Test no schedule params in response raises unsupported-feature error."""
     mock_bsblan._request = AsyncMock(return_value={})  # type: ignore[method-assign]
 
-    with pytest.raises(BSBLANError, match="No heating schedule parameters available"):
+    with pytest.raises(
+        BSBLANUnsupportedFeatureError,
+        match="No heating schedule parameters available",
+    ) as exc_info:
         await mock_bsblan.heating_schedule(circuit=1)
+
+    # Permanent error must remain catchable as the generic BSBLANError.
+    assert isinstance(exc_info.value, BSBLANError)

{python_bsblan-6.1.5 → python_bsblan-6.1.7}/tests/test_hot_water_additional.py

@@ -12,7 +12,7 @@ import pytest
 
 from bsblan import BSBLAN, BSBLANConfig
 from bsblan.constants import API_FULL
-from bsblan.exceptions import BSBLANError
+from bsblan.exceptions import BSBLANError, BSBLANUnsupportedFeatureError
 from bsblan.models import HotWaterConfig, HotWaterSchedule
 from bsblan.utility import APIValidator
 from tests import load_fixture
@@ -253,11 +253,14 @@ async def test_hot_water_schedule_no_params_error(
         bsblan._validator._validated_hot_water_groups.add("schedule")
 
         with pytest.raises(
-            BSBLANError,
+            BSBLANUnsupportedFeatureError,
             match="No hot water schedule parameters available",
-        ):
+        ) as exc_info:
             await bsblan.hot_water_schedule()
 
+        # Permanent error must remain catchable as the generic BSBLANError.
+        assert isinstance(exc_info.value, BSBLANError)
+
 
 @pytest.mark.asyncio
 async def test_hot_water_state_no_params_error(
@@ -285,9 +288,12 @@ async def test_hot_water_state_no_params_error(
         with pytest.raises(
             BSBLANError,
             match="No essential hot water parameters available",
-        ):
+        ) as exc_info:
             await bsblan.hot_water_state()
 
+        # State group must NOT be reclassified as an unsupported-feature error.
+        assert not isinstance(exc_info.value, BSBLANUnsupportedFeatureError)
+
 
 @pytest.mark.asyncio
 async def test_granular_hot_water_validation(