refactor: extract API version resolution into VersionResolver

Move the version-to-API-config mapping policy out of the BSBLAN client
into a dedicated _version.py collaborator. _set_api_version now delegates
to VersionResolver.resolve_config_version, and the pure mapping logic
(previously _resolve_api_version) lives in the module-level
_map_reported_version helper.

Behavior-preserving: the JSON-API version remains preferred over firmware,
the same version floors and v3 thresholds apply, and the public api_version
/ json_api_version properties are unchanged. Existing tests pass unchanged.

Author: liudger

src/bsblan/_version.py

@@ -0,0 +1,126 @@
+"""API version resolution for the BSBLAN client.
+
+Owns the policy that maps a device's reported version signals to a supported
+API configuration version. The BSB-LAN JSON-API version (from ``/JV``) is the
+documented, firmware-independent compatibility signal and is preferred when
+available; the adapter firmware version (from ``/JI``) is used as a fallback
+for very old firmware that does not expose ``/JV``.
+"""
+
+from __future__ import annotations
+
+from packaging import version as pkg_version
+from packaging.version import InvalidVersion
+
+from .constants import (
+    BASIC_API_VERSION,
+    MIN_SUPPORTED_FIRMWARE,
+    MIN_SUPPORTED_JSON_API,
+    SUPPORTED_API_VERSION,
+    V3_FIRMWARE_MINIMUM,
+    V3_JSON_API_MINIMUM,
+    ErrorMsg,
+)
+from .exceptions import BSBLANError, BSBLANVersionError
+
+
+def _map_reported_version(reported: str, *, minimum: str, v3_minimum: str) -> str:
+    """Map a reported version string to a supported API config version.
+
+    Args:
+        reported: The version string reported by the device.
+        minimum: The lowest supported version; anything below is rejected.
+        v3_minimum: The threshold at or above which the full "v3" config is
+            used; below it the basic "v2" config is used.
+
+    Returns:
+        ``"v2"`` for the basic single-circuit config or ``"v3"`` for the full
+        config.
+
+    Raises:
+        BSBLANVersionError: If the reported version cannot be parsed or is
+            below ``minimum``.
+
+    """
+    try:
+        parsed = pkg_version.parse(reported)
+    except InvalidVersion as exc:
+        raise BSBLANVersionError(ErrorMsg.VERSION, version=reported) from exc
+    if parsed < pkg_version.parse(minimum):
+        raise BSBLANVersionError(ErrorMsg.VERSION, version=reported)
+    if parsed < pkg_version.parse(v3_minimum):
+        # Legacy / basic capability: single-circuit support only.
+        return BASIC_API_VERSION
+    return SUPPORTED_API_VERSION
+
+
+class VersionResolver:
+    """Resolve the API configuration version from reported device versions.
+
+    The resolver is configured with the version floors and ``v3`` thresholds
+    for both the JSON-API and firmware signals. Defaults use the library's
+    named constants; custom thresholds can be supplied for testing.
+    """
+
+    def __init__(
+        self,
+        *,
+        firmware_minimum: str = MIN_SUPPORTED_FIRMWARE,
+        firmware_v3_minimum: str = V3_FIRMWARE_MINIMUM,
+        json_api_minimum: str = MIN_SUPPORTED_JSON_API,
+        json_api_v3_minimum: str = V3_JSON_API_MINIMUM,
+    ) -> None:
+        """Initialize the resolver with version policy thresholds.
+
+        Args:
+            firmware_minimum: Lowest supported adapter firmware version.
+            firmware_v3_minimum: Firmware version at/above which "v3" is used.
+            json_api_minimum: Lowest supported JSON-API version.
+            json_api_v3_minimum: JSON-API version at/above which "v3" is used.
+
+        """
+        self._firmware_minimum = firmware_minimum
+        self._firmware_v3_minimum = firmware_v3_minimum
+        self._json_api_minimum = json_api_minimum
+        self._json_api_v3_minimum = json_api_v3_minimum
+
+    def resolve_config_version(
+        self,
+        *,
+        json_api_version: str | None,
+        firmware_version: str | None,
+    ) -> str:
+        """Resolve the API config version from the available version signals.
+
+        The JSON-API version is preferred when present; otherwise the firmware
+        version is used as a fallback.
+
+        Args:
+            json_api_version: The JSON-API version reported by ``/JV``, or None.
+            firmware_version: The adapter firmware version from ``/JI``, or None.
+
+        Returns:
+            ``"v2"`` for the basic single-circuit config or ``"v3"`` for the
+            full config.
+
+        Raises:
+            BSBLANError: If neither the JSON-API version nor the firmware
+                version is available.
+            BSBLANVersionError: If the reported version is not supported.
+
+        """
+        if json_api_version is not None:
+            return _map_reported_version(
+                json_api_version,
+                minimum=self._json_api_minimum,
+                v3_minimum=self._json_api_v3_minimum,
+            )
+
+        if not firmware_version:
+            raise BSBLANError(ErrorMsg.FIRMWARE_VERSION)
+
+        return _map_reported_version(
+            firmware_version,
+            minimum=self._firmware_minimum,
+            v3_minimum=self._firmware_v3_minimum,
+        )

src/bsblan/bsblan.py

@@ -12,22 +12,17 @@
 
 import aiohttp
 from aiohttp.hdrs import METH_POST
-from packaging import version as pkg_version
-from packaging.version import InvalidVersion
 
 from ._transport import BSBLANTransport
+from ._version import VersionResolver
 from .constants import (
     API_V2,
     API_V3,
     BASIC_API_VERSION,
-    MIN_SUPPORTED_FIRMWARE,
-    MIN_SUPPORTED_JSON_API,
     PPS_HEATING_PARAMS,
     PPS_STATIC_VALUES_PARAMS,
     SUPPORTED_API_VERSION,
     SUPPORTED_API_VERSIONS,
-    V3_FIRMWARE_MINIMUM,
-    V3_JSON_API_MINIMUM,
     APIConfig,
     CircuitConfig,
     ErrorMsg,
@@ -127,6 +122,7 @@ class BSBLAN:
     _section_locks: dict[str, asyncio.Lock] = field(default_factory=dict)
     _hot_water_group_locks: dict[str, asyncio.Lock] = field(default_factory=dict)
     _transport: BSBLANTransport = field(init=False)
+    _version_resolver: VersionResolver = field(init=False)
 
     def __post_init__(self) -> None:
         """Wire up internal collaborators after dataclass construction."""
@@ -135,6 +131,7 @@ def __post_init__(self) -> None:
             lambda: self.session,
             lambda: self._firmware_version,
         )
+        self._version_resolver = VersionResolver()
 
     async def __aenter__(self) -> Self:
         """Enter the context manager.
@@ -666,58 +663,11 @@ def _set_api_version(self) -> None:
             BSBLANVersionError: If the reported version is not supported.
 
         """
-        if self._json_api_version is not None:
-            self._api_version = self._resolve_api_version(
-                self._json_api_version,
-                minimum=MIN_SUPPORTED_JSON_API,
-                v3_minimum=V3_JSON_API_MINIMUM,
-            )
-            return
-
-        if not self._firmware_version:
-            raise BSBLANError(ErrorMsg.FIRMWARE_VERSION)
-
-        self._api_version = self._resolve_api_version(
-            self._firmware_version,
-            minimum=MIN_SUPPORTED_FIRMWARE,
-            v3_minimum=V3_FIRMWARE_MINIMUM,
+        self._api_version = self._version_resolver.resolve_config_version(
+            json_api_version=self._json_api_version,
+            firmware_version=self._firmware_version,
         )
 
-    def _resolve_api_version(
-        self,
-        reported: str,
-        *,
-        minimum: str,
-        v3_minimum: str,
-    ) -> str:
-        """Map a reported version string to a supported API config version.
-
-        Args:
-            reported: The version string reported by the device.
-            minimum: The lowest supported version; anything below is rejected.
-            v3_minimum: The threshold at or above which the full "v3" config is
-                used; below it the basic "v2" config is used.
-
-        Returns:
-            ``"v2"`` for the basic single-circuit config or ``"v3"`` for the
-            full config.
-
-        Raises:
-            BSBLANVersionError: If the reported version cannot be parsed or is
-                below ``minimum``.
-
-        """
-        try:
-            parsed = pkg_version.parse(reported)
-        except InvalidVersion as exc:
-            raise BSBLANVersionError(ErrorMsg.VERSION, version=reported) from exc
-        if parsed < pkg_version.parse(minimum):
-            raise BSBLANVersionError(ErrorMsg.VERSION, version=reported)
-        if parsed < pkg_version.parse(v3_minimum):
-            # Legacy / basic capability: single-circuit support only.
-            return BASIC_API_VERSION
-        return SUPPORTED_API_VERSION
-
     async def _fetch_temperature_range(
         self,
         circuit: int,