python-bsblan 6.1.0__py3-none-any.whl → 6.1.2__py3-none-any.whl

bsblan/__init__.py

@@ -8,8 +8,14 @@ from .constants import (
     HVACActionCategory,
     get_hvac_action_category,
 )
-from .exceptions import BSBLANAuthError, BSBLANConnectionError, BSBLANError
+from .exceptions import (
+    BSBLANAuthError,
+    BSBLANConnectionError,
+    BSBLANError,
+    BSBLANVersionError,
+)
 from .models import (
+    ApiVersion,
     DaySchedule,
     Device,
     DeviceTime,
@@ -34,10 +40,12 @@ __all__ = [
     "BSBLAN",
     "UNIT_DEVICE_CLASS_MAP",
     "UNIT_STATE_CLASS_MAP",
+    "ApiVersion",
     "BSBLANAuthError",
     "BSBLANConfig",
     "BSBLANConnectionError",
     "BSBLANError",
+    "BSBLANVersionError",
     "DHWSchedule",
     "DHWTimeSwitchPrograms",
     "DaySchedule",

bsblan/_temperature.py

@@ -0,0 +1,324 @@
+"""Temperature range, unit, and bounds management for the BSBLAN client.
+
+Owns the per-circuit temperature range cache, the set of circuits whose range
+has been initialized, and the active temperature unit. Ranges are lazily
+fetched from the device static values and target temperatures are validated
+against the heating and cooling bounds. The owning client keeps thin
+delegations that forward here.
+
+The manager reads discovered circuits and fetches static values through
+callables supplied by the owning client so it does not hold a back-reference
+to the facade.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from .exceptions import BSBLANError, BSBLANInvalidParameterError
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+    from typing import Any
+
+    from .bsblan import SectionLiteral
+    from .models import StaticState
+
+logger = logging.getLogger(__name__)
+
+
+class TemperatureManager:
+    """Manage per-circuit temperature ranges, the unit, and bounds checks.
+
+    The manager owns the temperature state (per-circuit range cache, the set of
+    circuits whose range has been initialized, and the active unit). Static
+    values are read through ``static_values`` and discovered circuits through
+    ``get_available_circuits`` so the manager never holds a back-reference to
+    the owning client.
+    """
+
+    def __init__(
+        self,
+        *,
+        static_values: Callable[..., Awaitable[StaticState]],
+        get_available_circuits: Callable[[], set[int] | None],
+    ) -> None:
+        """Initialize the manager with the client's collaborators.
+
+        Args:
+            static_values: Callable returning the static values model for a
+                circuit.
+            get_available_circuits: Callable returning the set of circuits known
+                to be available, or ``None`` when discovery has not run.
+
+        """
+        self._static_values = static_values
+        self._get_available_circuits = get_available_circuits
+        self._temperature_unit: str = "°C"
+        # Per-circuit temperature ranges: circuit_number -> range dict.
+        self._circuit_temp_ranges: dict[int, dict[str, float | None]] = {}
+        self._circuit_temp_initialized: set[int] = set()
+
+    @property
+    def unit(self) -> str:
+        """Return the active temperature unit (°C or °F)."""
+        return self._temperature_unit
+
+    def should_extract_temperature_unit(
+        self,
+        section: SectionLiteral,
+        include: list[str] | None,
+        response_data: dict[str, Any],
+    ) -> bool:
+        """Return whether the validation response should update temperature unit."""
+        if section != "heating":
+            return False
+
+        if include is None or "target_temperature" in include:
+            return True
+
+        return any(param_id in response_data for param_id in ("710", "15004"))
+
+    def extract_temperature_unit_from_response(
+        self, response_data: dict[str, Any]
+    ) -> None:
+        """Extract temperature unit from heating section response data.
+
+        Gets the unit from the target_temperature parameter, which is always
+        present in the heating section.
+
+        Args:
+            response_data: The response data from heating section validation
+
+        """
+        # Look for target_temperature in the response.
+        for param_id, param_data in response_data.items():
+            if param_id in {"710", "15004"} and isinstance(param_data, dict):
+                unit = param_data.get("unit", "")
+                if unit in ("°C", "°C"):
+                    self._temperature_unit = "°C"
+                elif unit == "°F":
+                    self._temperature_unit = "°F"
+                else:
+                    # Keep default if unit is empty or unknown
+                    logger.debug(
+                        "Unknown or empty temperature unit from heating target: "
+                        "'%s'. Using default (°C)",
+                        unit,
+                    )
+                logger.debug("Temperature unit set to: %s", self._temperature_unit)
+                return
+
+        logger.warning(
+            "Could not find target temperature in heating section response. "
+            "Using default temperature unit (°C)"
+        )
+
+    async def _fetch_temperature_range(
+        self,
+        circuit: int,
+    ) -> dict[str, float | None]:
+        """Fetch min/max temperature range for a circuit from the device.
+
+        Args:
+            circuit: The heating circuit number (1 or 2).
+
+        Returns:
+            dict with heating and cooling min/max keys. Values may be None if
+            unavailable.
+
+        """
+        temp_range: dict[str, float | None] = {
+            "min": None,
+            "max": None,
+            "cooling_min": None,
+            "cooling_max": None,
+        }
+        available_circuits = self._get_available_circuits()
+        if available_circuits is not None and circuit not in available_circuits:
+            logger.debug(
+                "Skipping temperature range fetch for unavailable circuit %d",
+                circuit,
+            )
+            return temp_range
+
+        try:
+            static_values = await self._static_values(circuit=circuit)
+        except BSBLANError as err:
+            logger.warning(
+                "Failed to get static values for circuit %d: %s. "
+                "Temperature range will be None",
+                circuit,
+                str(err),
+            )
+            return temp_range
+
+        # Prefer heating_protective_setpoint (714/1014) as the true lower bound
+        # for standard circuits. Fall back to min_temp for PPS circuits (15006)
+        # which have no separate protective setpoint. Skip sources whose value is
+        # inactive (BSB-LAN may return "---" which becomes value=None).
+        min_source = next(
+            (
+                source
+                for source in (
+                    static_values.heating_protective_setpoint,
+                    static_values.min_temp,
+                )
+                if source is not None and source.value is not None
+            ),
+            None,
+        )
+        if min_source is not None:
+            temp_range["min"] = min_source.value
+            logger.debug(
+                "Circuit %d min temp initialized: %s",
+                circuit,
+                temp_range["min"],
+            )
+
+        # Prefer comfort_setpoint_max (716/1016) as the upper bound for standard
+        # circuits. Fall back to max_temp for PPS circuits (15007) which expose
+        # only a generic max. Skip sources whose value is inactive.
+        max_source = next(
+            (
+                source
+                for source in (
+                    static_values.comfort_setpoint_max,
+                    static_values.max_temp,
+                )
+                if source is not None and source.value is not None
+            ),
+            None,
+        )
+        if max_source is not None:
+            temp_range["max"] = max_source.value
+            logger.debug(
+                "Circuit %d max temp initialized: %s",
+                circuit,
+                temp_range["max"],
+            )
+
+        if static_values.cooling_comfort_setpoint_min is not None:
+            temp_range["cooling_min"] = static_values.cooling_comfort_setpoint_min.value
+            logger.debug(
+                "Circuit %d cooling min temp initialized: %s",
+                circuit,
+                temp_range["cooling_min"],
+            )
+
+        if static_values.cooling_reduced_setpoint is not None:
+            temp_range["cooling_max"] = static_values.cooling_reduced_setpoint.value
+            logger.debug(
+                "Circuit %d cooling max temp initialized: %s",
+                circuit,
+                temp_range["cooling_max"],
+            )
+
+        return temp_range
+
+    async def initialize_temperature_range(
+        self,
+        circuit: int = 1,
+    ) -> None:
+        """Initialize the temperature range from static values (lazy loaded).
+
+        This method is called on-demand when temperature range is needed.
+        It uses lazy loading through static_values() which will validate
+        the staticValues section if not already done.
+
+        Args:
+            circuit: The heating circuit number (1 or 2).
+
+        Note: Temperature unit is extracted during heating section validation,
+        so no extra API call is needed here.
+
+        """
+        if circuit in self._circuit_temp_initialized:
+            return
+
+        temp_range = await self._fetch_temperature_range(circuit)
+        self._circuit_temp_ranges[circuit] = temp_range
+        self._circuit_temp_initialized.add(circuit)
+
+    async def _validate_in_range(
+        self,
+        value: str | float,
+        circuit: int,
+        *,
+        min_key: str,
+        max_key: str,
+    ) -> None:
+        """Validate a temperature value against a circuit's configured bounds.
+
+        Lazy-loads the circuit temperature range when needed. If the device
+        does not expose the relevant bounds, only the float conversion is
+        validated.
+
+        Args:
+            value (str | float): The temperature value to validate.
+            circuit (int): The heating circuit number (1 or 2).
+            min_key (str): Range key holding the lower bound.
+            max_key (str): Range key holding the upper bound.
+
+        Raises:
+            BSBLANInvalidParameterError: If the value is not a valid float or
+                falls outside the configured bounds.
+
+        """
+        try:
+            temp = float(value)
+        except ValueError as err:
+            raise BSBLANInvalidParameterError(str(value)) from err
+
+        if circuit not in self._circuit_temp_initialized:
+            await self.initialize_temperature_range(circuit)
+
+        temp_range = self._circuit_temp_ranges.get(circuit, {})
+        min_temp = temp_range.get(min_key)
+        max_temp = temp_range.get(max_key)
+
+        if min_temp is None or max_temp is None:
+            return
+
+        if not (min_temp <= temp <= max_temp):
+            raise BSBLANInvalidParameterError(str(value))
+
+    async def validate_target_temperature_high(
+        self,
+        target_temperature_high: str | float,
+        circuit: int = 1,
+    ) -> None:
+        """Validate the cooling target temperature value."""
+        await self._validate_in_range(
+            target_temperature_high,
+            circuit,
+            min_key="cooling_min",
+            max_key="cooling_max",
+        )
+
+    async def validate_target_temperature(
+        self,
+        target_temperature: str,
+        circuit: int = 1,
+    ) -> None:
+        """Validate the target temperature.
+
+        This method lazy-loads the temperature range if not already initialized.
+        If the device does not provide min/max temperature parameters,
+        only validates that the value is a valid float.
+
+        Args:
+            target_temperature (str): The target temperature to validate.
+            circuit: The heating circuit number (1 or 2).
+
+        Raises:
+            BSBLANInvalidParameterError: If the target temperature is invalid.
+
+        """
+        await self._validate_in_range(
+            target_temperature,
+            circuit,
+            min_key="min",
+            max_key="max",
+        )

bsblan/_transport.py

@@ -0,0 +1,221 @@
+"""HTTP transport layer for the BSBLAN client.
+
+Owns the low-level concerns of talking to a BSB-LAN device: URL building,
+authentication, headers, request execution with exponential-backoff retries,
+and firmware-specific response post-processing. The owning client keeps a
+stable ``_request`` facade that delegates here.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import TYPE_CHECKING, Any, cast
+
+import aiohttp
+import backoff
+from aiohttp.helpers import BasicAuth
+from packaging import version as pkg_version
+from yarl import URL
+
+from .constants import ErrorMsg
+from .exceptions import BSBLANAuthError, BSBLANError
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Mapping
+
+    from aiohttp.client import ClientSession
+
+    from .bsblan import BSBLANConfig
+
+logger = logging.getLogger(__name__)
+
+# HTTP status that must not be retried (resource genuinely absent).
+HTTP_NOT_FOUND = 404
+# HTTP statuses that indicate authentication failure (not retried).
+HTTP_AUTH_STATUSES = (401, 403)
+# Firmware version at/after which /JQ responses include a debug `payload` field.
+PAYLOAD_FIELD_MIN_VERSION = "5.0.0"
+
+
+def _should_give_up_retry(error: Exception) -> bool:
+    """Return whether a failed request must not be retried.
+
+    Args:
+        error: The exception raised while performing the request.
+
+    Returns:
+        bool: True for HTTP 404 responses, which are not transient.
+
+    """
+    return (
+        isinstance(error, aiohttp.ClientResponseError)
+        and error.status == HTTP_NOT_FOUND
+    )
+
+
+class BSBLANTransport:
+    """Handle HTTP transport for a BSB-LAN device.
+
+    The session and firmware version are read through callables because both
+    are assigned on the owning client after it is constructed (the session in
+    ``__aenter__`` and the firmware version during ``initialize``).
+    """
+
+    def __init__(
+        self,
+        config: BSBLANConfig,
+        session_getter: Callable[[], ClientSession | None],
+        firmware_getter: Callable[[], str | None],
+    ) -> None:
+        """Initialize the transport.
+
+        Args:
+            config: Connection configuration (host, port, credentials, timeout).
+            session_getter: Callable returning the current client session.
+            firmware_getter: Callable returning the current firmware version.
+
+        """
+        self._config = config
+        self._session_getter = session_getter
+        self._firmware_getter = firmware_getter
+
+    @backoff.on_exception(
+        backoff.expo,
+        (TimeoutError, aiohttp.ClientError),
+        max_tries=3,
+        max_time=30,
+        giveup=_should_give_up_retry,
+        logger=logger,
+    )
+    async def request_with_retry(
+        self,
+        method: str,
+        base_path: str,
+        data: dict[str, object] | None,
+        params: Mapping[str, str | int] | str | None,
+    ) -> dict[str, Any]:
+        """Execute an HTTP request with automatic retries.
+
+        Decorated with backoff for automatic retries on transient failures.
+
+        Args:
+            method: The HTTP method to use.
+            base_path: The base path for the URL.
+            data: The data to send in the request body.
+            params: The query parameters to include.
+
+        Returns:
+            dict[str, Any]: The JSON response from the BSBLAN device.
+
+        Raises:
+            BSBLANError: If the session is missing or the response is invalid.
+            BSBLANAuthError: If authentication fails (401/403, not retried).
+
+        """
+        session = self._session_getter()
+        if session is None:
+            raise BSBLANError(ErrorMsg.SESSION_NOT_INITIALIZED)
+        url = self._build_url(base_path)
+        auth = self._get_auth()
+        headers = self._get_headers()
+
+        try:
+            async with asyncio.timeout(self._config.request_timeout):
+                async with session.request(
+                    method,
+                    url,
+                    auth=auth,
+                    params=params,
+                    json=data,
+                    headers=headers,
+                ) as response:
+                    response.raise_for_status()
+                    response_data = cast("dict[str, Any]", await response.json())
+                    return self._process_response(response_data, base_path)
+        except aiohttp.ClientResponseError as e:
+            if e.status in HTTP_AUTH_STATUSES:
+                raise BSBLANAuthError from e
+            raise
+        except (ValueError, UnicodeDecodeError) as e:
+            # Handle JSON decode errors and other parsing issues
+            msg = ErrorMsg.INVALID_RESPONSE.format(e)
+            raise BSBLANError(msg) from e
+
+    def _process_response(
+        self, response_data: dict[str, Any], base_path: str
+    ) -> dict[str, Any]:
+        """Process response data based on firmware version.
+
+        BSB-LAN 5.0+ includes an additional 'payload' field in /JQ responses
+        that needs to be handled for compatibility.
+
+        Args:
+            response_data: Raw response data from BSB-LAN.
+            base_path: The API endpoint that was called.
+
+        Returns:
+            Processed response data compatible with existing code.
+
+        """
+        # For non-JQ endpoints, return response as-is
+        if base_path != "/JQ":
+            return response_data
+
+        # Check if we have a firmware version to determine processing
+        firmware_version = self._firmware_getter()
+        if not firmware_version:
+            return response_data
+
+        # For BSB-LAN 5.0+, remove 'payload' field if present (debugging only)
+        version = pkg_version.parse(firmware_version)
+        if (
+            version >= pkg_version.parse(PAYLOAD_FIELD_MIN_VERSION)
+            and "payload" in response_data
+        ):
+            return {k: v for k, v in response_data.items() if k != "payload"}
+
+        return response_data
+
+    def _build_url(self, base_path: str) -> URL:
+        """Build the URL for the request.
+
+        Args:
+            base_path (str): The base path for the URL.
+
+        Returns:
+            URL: The constructed URL.
+
+        """
+        if self._config.passkey:
+            base_path = f"/{self._config.passkey}{base_path}"
+        return URL.build(
+            scheme="http",
+            host=self._config.host,
+            port=self._config.port,
+            path=base_path,
+        )
+
+    def _get_auth(self) -> BasicAuth | None:
+        """Get the authentication for the request.
+
+        Returns:
+            BasicAuth | None: The authentication object or None if no
+                authentication is required.
+
+        """
+        if self._config.username and self._config.password:
+            return BasicAuth(self._config.username, self._config.password)
+        return None
+
+    def _get_headers(self) -> dict[str, str]:
+        """Get the headers for the request.
+
+        Returns:
+            dict[str, str]: The headers for the request.
+
+        """
+        return {
+            "User-Agent": f"PythonBSBLAN/{self._firmware_getter()}",
+            "Accept": "application/json, */*",
+        }