Add new exception types for unsupported features and malformed responses

- Introduced BSBLANUnsupportedFeatureError for permanent feature unavailability.
- Introduced BSBLANMalformedResponseError for transient JSON parsing issues.
- Updated relevant code to raise new exceptions in appropriate scenarios.
- Enhanced tests to cover new exception handling.

Author: liudger

src/bsblan/__init__.py

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

src/bsblan/_hot_water.py

@@ -5,7 +5,7 @@
 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 @@ async def fetch_data(
             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 @@ async def fetch_data(
         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)

src/bsblan/_schedules.py

@@ -5,7 +5,7 @@
 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 @@ async def heating_schedule(
             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 @@ async def heating_schedule(
         }
 
         if not mapped_data:
-            raise BSBLANError(ErrorMsg.NO_HEATING_SCHEDULE_PARAMS)
+            raise BSBLANUnsupportedFeatureError(ErrorMsg.NO_HEATING_SCHEDULE_PARAMS)
 
         return HeatingTimeSwitchPrograms.model_validate(mapped_data)
 

src/bsblan/_transport.py

@@ -20,7 +20,7 @@
 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
@@ -110,8 +110,10 @@ async def request_with_retry(
             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()
@@ -141,7 +143,7 @@ async def request_with_retry(
         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]:

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.
+    """

tests/test_bsblan_edge_cases.py

@@ -9,7 +9,11 @@
 import pytest
 
 from bsblan import BSBLAN, BSBLANConfig
-from bsblan.exceptions import BSBLANConnectionError, BSBLANError
+from bsblan.exceptions import (
+    BSBLANConnectionError,
+    BSBLANError,
+    BSBLANMalformedResponseError,
+)
 
 
 @pytest.mark.asyncio
@@ -77,9 +81,14 @@ async def test_value_error_path(monkeypatch: Any) -> None:
 
         monkeypatch.setattr(session, "request", MagicMock(return_value=mock_response))
 
-        with pytest.raises(BSBLANError, match="Invalid response format"):
+        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."""

tests/test_heating_schedule.py

@@ -7,7 +7,7 @@
 
 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)

tests/test_hot_water_additional.py

@@ -12,7 +12,7 @@
 
 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(