python-bsblan 4.1.0b0__tar.gz → 4.1.0b1__tar.gz

{python_bsblan-4.1.0b0 → python_bsblan-4.1.0b1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-bsblan
-Version: 4.1.0b0
+Version: 4.1.0b1
 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-4.1.0b1/examples/speed_test.py

@@ -0,0 +1,382 @@
+"""Test speed comparison for BSB-LAN API calls.
+
+Compares different approaches:
+1. Multiple parallel calls (current approach)
+2. Combined read_parameters call
+3. With/without parameter filtering
+
+Usage:
+    # Set environment variables (optional - will use mDNS discovery if not set)
+    export BSBLAN_HOST=10.0.2.60
+    export BSBLAN_PORT=80
+    export BSBLAN_PASSKEY=your_passkey  # if needed
+
+    # Run the test
+    python examples/speed_test.py
+"""
+
+from __future__ import annotations
+
+import asyncio
+import statistics
+import time
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from bsblan import BSBLAN, BSBLANConfig
+from discovery import get_bsblan_host, get_config_from_env
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+# Test configuration
+NUM_WARMUP_RUNS = 2
+NUM_TEST_RUNS = 10
+
+# Parameters used in different tests
+INFO_PARAMS = ["6224"]  # Current firmware version
+STATIC_PARAMS = ["714", "716"]  # Min/max temp setpoints
+ALL_PARAMS = INFO_PARAMS + STATIC_PARAMS
+
+# Large parameter sets for scalability testing
+# Heating parameters
+HEATING_PARAMS = ["700", "710", "900", "8000", "8740", "8749"]
+
+# Sensor parameters
+SENSOR_PARAMS = ["8700", "8740"]
+
+# Hot water parameters (a good mix of config and state)
+HOT_WATER_PARAMS = [
+    "1600",  # operating_mode
+    "1601",  # eco_mode_selection
+    "1610",  # nominal_setpoint
+    "1614",  # nominal_setpoint_max
+    "1612",  # reduced_setpoint
+    "1620",  # release
+    "1630",  # dhw_charging_priority
+    "1640",  # legionella_function
+    "1641",  # legionella_function_periodicity
+    "1642",  # legionella_function_day
+    "1644",  # legionella_function_time
+    "1645",  # legionella_function_setpoint
+    "8830",  # dhw_actual_value_top_temperature
+    "8820",  # state_dhw_pump
+]
+
+# Combined large set (~20 params)
+LARGE_PARAM_SET = HEATING_PARAMS + SENSOR_PARAMS + HOT_WATER_PARAMS[:8]  # ~16 params
+
+# Extra large set (~22 params)
+XLARGE_PARAM_SET = HEATING_PARAMS + SENSOR_PARAMS + HOT_WATER_PARAMS  # ~22 params
+
+
+@dataclass
+class BenchmarkResult:
+    """Results from a speed benchmark."""
+
+    name: str
+    times: list[float]
+
+    @property
+    def avg(self) -> float:
+        """Average time."""
+        return statistics.mean(self.times)
+
+    @property
+    def min(self) -> float:
+        """Minimum time."""
+        return min(self.times)
+
+    @property
+    def max(self) -> float:
+        """Maximum time."""
+        return max(self.times)
+
+    @property
+    def median(self) -> float:
+        """Median time."""
+        return statistics.median(self.times)
+
+    @property
+    def stdev(self) -> float:
+        """Standard deviation."""
+        return statistics.stdev(self.times) if len(self.times) > 1 else 0.0
+
+    def __str__(self) -> str:
+        """Format results as string."""
+        return (
+            f"{self.name}:\n"
+            f"  avg={self.avg:.3f}s, median={self.median:.3f}s, "
+            f"min={self.min:.3f}s, max={self.max:.3f}s, stdev={self.stdev:.3f}s"
+        )
+
+
+async def run_test(
+    name: str,
+    test_fn: Callable[[], Awaitable[object]],
+    num_runs: int = NUM_TEST_RUNS,
+    warmup_runs: int = NUM_WARMUP_RUNS,
+) -> BenchmarkResult:
+    """Run a test function multiple times and collect timing stats.
+
+    Args:
+        name: Test name for display.
+        test_fn: Async function to test.
+        num_runs: Number of timed test runs.
+        warmup_runs: Number of warmup runs (not timed).
+
+    Returns:
+        BenchmarkResult with timing statistics.
+
+    """
+    # Warmup runs (not counted)
+    for _ in range(warmup_runs):
+        await test_fn()
+
+    # Timed runs
+    times: list[float] = []
+    for i in range(num_runs):
+        start = time.perf_counter()
+        await test_fn()
+        elapsed = time.perf_counter() - start
+        times.append(elapsed)
+        print(f"  Run {i + 1}/{num_runs}: {elapsed:.3f}s")
+
+    return BenchmarkResult(name=name, times=times)
+
+
+async def bench_3_parallel_calls(bsblan: BSBLAN) -> None:
+    """Benchmark 3 parallel calls (current initialization approach)."""
+    await asyncio.gather(
+        bsblan.device(),
+        bsblan.info(),
+        bsblan.static_values(),
+    )
+
+
+async def bench_2_parallel_calls(bsblan: BSBLAN) -> None:
+    """Benchmark 2 calls: device + combined read_parameters."""
+    await asyncio.gather(
+        bsblan.device(),
+        bsblan.read_parameters(ALL_PARAMS),
+    )
+
+
+async def bench_1_read_params(bsblan: BSBLAN) -> None:
+    """Benchmark single read_parameters call with all params."""
+    await bsblan.read_parameters(ALL_PARAMS)
+
+
+async def bench_static_values_filtered(bsblan: BSBLAN) -> None:
+    """Benchmark static_values with include filter."""
+    await bsblan.static_values(include=["min_temp"])
+
+
+async def bench_info_filtered(bsblan: BSBLAN) -> None:
+    """Benchmark info() with include filter."""
+    await bsblan.info(include=["device_identification"])
+
+
+async def bench_large_params_single_call(bsblan: BSBLAN) -> None:
+    """Benchmark single call with ~16 parameters."""
+    await bsblan.read_parameters(LARGE_PARAM_SET)
+
+
+async def bench_xlarge_params_single_call(bsblan: BSBLAN) -> None:
+    """Benchmark single call with ~22 parameters."""
+    await bsblan.read_parameters(XLARGE_PARAM_SET)
+
+
+async def bench_large_params_4_parallel_calls(bsblan: BSBLAN) -> None:
+    """Benchmark 4 parallel calls, each with ~4 parameters."""
+    chunk_size = len(LARGE_PARAM_SET) // 4
+    chunks = [
+        LARGE_PARAM_SET[i : i + chunk_size]
+        for i in range(0, len(LARGE_PARAM_SET), chunk_size)
+    ]
+    await asyncio.gather(*[bsblan.read_parameters(chunk) for chunk in chunks])
+
+
+async def bench_xlarge_params_4_parallel_calls(bsblan: BSBLAN) -> None:
+    """Benchmark 4 parallel calls splitting ~22 parameters."""
+    chunk_size = len(XLARGE_PARAM_SET) // 4
+    chunks = [
+        XLARGE_PARAM_SET[i : i + chunk_size]
+        for i in range(0, len(XLARGE_PARAM_SET), chunk_size)
+    ]
+    await asyncio.gather(*[bsblan.read_parameters(chunk) for chunk in chunks])
+
+
+async def bench_xlarge_params_2_parallel_calls(bsblan: BSBLAN) -> None:
+    """Benchmark 2 parallel calls splitting ~22 parameters."""
+    mid = len(XLARGE_PARAM_SET) // 2
+    await asyncio.gather(
+        bsblan.read_parameters(XLARGE_PARAM_SET[:mid]),
+        bsblan.read_parameters(XLARGE_PARAM_SET[mid:]),
+    )
+
+
+async def bench_info_only(bsblan: BSBLAN) -> None:
+    """Benchmark info() call only."""
+    await bsblan.info()
+
+
+async def bench_static_values_only(bsblan: BSBLAN) -> None:
+    """Benchmark static_values() call only."""
+    await bsblan.static_values()
+
+
+async def run_all_benchmarks(bsblan: BSBLAN) -> list[BenchmarkResult]:
+    """Run all speed benchmarks and return results."""
+    results: list[BenchmarkResult] = []
+
+    # Define basic tests
+    basic_tests = [
+        (
+            "Test 1: 3 parallel calls (device + info + static_values)",
+            "3 parallel calls",
+            lambda: bench_3_parallel_calls(bsblan),
+        ),
+        (
+            "Test 2: 2 parallel calls (device + read_parameters)",
+            "2 parallel calls",
+            lambda: bench_2_parallel_calls(bsblan),
+        ),
+        (
+            "Test 3: Single read_parameters call",
+            "1 read_parameters",
+            lambda: bench_1_read_params(bsblan),
+        ),
+        (
+            "Test 4: static_values with include filter (min_temp only)",
+            "static_values (filtered)",
+            lambda: bench_static_values_filtered(bsblan),
+        ),
+        (
+            "Test 5: info with include filter (device_identification only)",
+            "info (filtered)",
+            lambda: bench_info_filtered(bsblan),
+        ),
+        (
+            "Test 6: static_values without filter (all params)",
+            "static_values (all)",
+            lambda: bench_static_values_only(bsblan),
+        ),
+    ]
+
+    for desc, name, bench_fn in basic_tests:
+        print(f"\n{desc}")
+        result = await run_test(name, bench_fn)
+        results.append(result)
+
+    # Scalability tests
+    print("\n" + "=" * 60)
+    print("SCALABILITY TESTS - Many Parameters")
+    print("=" * 60)
+
+    scalability_tests = [
+        (
+            f"Test 7: Single call with {len(LARGE_PARAM_SET)} params",
+            f"1 call ({len(LARGE_PARAM_SET)} params)",
+            lambda: bench_large_params_single_call(bsblan),
+        ),
+        (
+            f"Test 8: 4 parallel calls ({len(LARGE_PARAM_SET)} params split)",
+            f"4 calls ({len(LARGE_PARAM_SET)} params)",
+            lambda: bench_large_params_4_parallel_calls(bsblan),
+        ),
+        (
+            f"Test 9: Single call with {len(XLARGE_PARAM_SET)} params",
+            f"1 call ({len(XLARGE_PARAM_SET)} params)",
+            lambda: bench_xlarge_params_single_call(bsblan),
+        ),
+        (
+            f"Test 10: 2 parallel calls ({len(XLARGE_PARAM_SET)} params split)",
+            f"2 calls ({len(XLARGE_PARAM_SET)} params)",
+            lambda: bench_xlarge_params_2_parallel_calls(bsblan),
+        ),
+        (
+            f"Test 11: 4 parallel calls ({len(XLARGE_PARAM_SET)} params split)",
+            f"4 calls ({len(XLARGE_PARAM_SET)} params)",
+            lambda: bench_xlarge_params_4_parallel_calls(bsblan),
+        ),
+    ]
+
+    for desc, name, bench_fn in scalability_tests:
+        print(f"\n{desc}")
+        result = await run_test(name, bench_fn)
+        results.append(result)
+
+    return results
+
+
+def print_results(results: list[BenchmarkResult]) -> None:
+    """Print test results summary."""
+    print("\n" + "=" * 60)
+    print("RESULTS SUMMARY")
+    print("=" * 60)
+
+    for r in results:
+        print(f"\n{r}")
+
+    # Compare approaches
+    baseline = results[0].avg  # 3 parallel calls
+    print("\n" + "-" * 60)
+    print("COMPARISON (vs 3 parallel calls baseline)")
+    print("-" * 60)
+
+    for r in results[1:]:
+        diff = baseline - r.avg
+        pct = (diff / baseline) * 100 if baseline > 0 else 0
+        faster_slower = "faster" if diff > 0 else "slower"
+        print(f"{r.name}: {abs(diff):.3f}s {faster_slower} ({abs(pct):.1f}%)")
+
+    # Best approach
+    best = min(results, key=lambda x: x.avg)
+    print(f"\n✓ Best approach: {best.name} (avg: {best.avg:.3f}s)")
+
+
+async def main() -> None:
+    """Run speed comparison tests."""
+    print("=" * 60)
+    print("BSB-LAN API Speed Comparison Test")
+    print("=" * 60)
+
+    # Get configuration from environment or discovery
+    env_config = get_config_from_env()
+
+    try:
+        host, port = await get_bsblan_host(discovery_seconds=3.0)
+    except RuntimeError:
+        print("\nNo BSB-LAN device found!")
+        print("Set BSBLAN_HOST environment variable or enable mDNS on your device.")
+        return
+
+    print(f"\nConnecting to: {host}:{port}")
+
+    # Build config - cast values to str for type safety
+    passkey = env_config.get("passkey")
+    username = env_config.get("username")
+    password = env_config.get("password")
+
+    config = BSBLANConfig(
+        host=host,
+        port=port,
+        passkey=str(passkey) if passkey else None,
+        username=str(username) if username else None,
+        password=str(password) if password else None,
+    )
+
+    async with BSBLAN(config) as bsblan:
+        await bsblan.initialize()
+        print("✓ BSB-LAN client initialized\n")
+
+        print(f"Running {NUM_TEST_RUNS} test runs with {NUM_WARMUP_RUNS} warmup runs\n")
+        print("-" * 60)
+
+        results = await run_all_benchmarks(bsblan)
+        print_results(results)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

{python_bsblan-4.1.0b0 → python_bsblan-4.1.0b1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-bsblan"
-version = "4.1.0-beta.0"
+version = "4.1.0-beta.1"
 description = "Asynchronous Python client for BSBLAN API"
 authors = [
     {name = "Willem-Jan van Rootselaar", email = "liudgervr@gmail.com"}

{python_bsblan-4.1.0b0 → python_bsblan-4.1.0b1}/src/bsblan/bsblan.py

@@ -171,7 +171,9 @@ class BSBLAN:
         # Initialize the API validator (but don't validate sections yet)
         self._api_validator = APIValidator(self._api_data)
 
-    async def _ensure_section_validated(self, section: SectionLiteral) -> None:
+    async def _ensure_section_validated(
+        self, section: SectionLiteral, include: list[str] | None = None
+    ) -> None:
         """Ensure a section is validated before use (lazy loading).
 
         This method validates a section on-demand when it's first accessed.
@@ -182,6 +184,8 @@ class BSBLAN:
 
         Args:
             section: The section name to validate
+            include: Optional list of parameter names to validate. If None,
+                validates all parameters for the section.
 
         """
         if not self._api_validator:
@@ -201,7 +205,7 @@ class BSBLAN:
                 return
 
             logger.debug("Lazy loading section: %s", section)
-            response_data = await self._validate_api_section(section)
+            response_data = await self._validate_api_section(section, include)
 
             # Extract temperature unit from heating section validation
             # (parameter 710 - target_temperature is always in heating section)
@@ -337,12 +341,14 @@ class BSBLAN:
                 self._extract_temperature_unit_from_response(response_data)
 
     async def _validate_api_section(
-        self, section: SectionLiteral
+        self, section: SectionLiteral, include: list[str] | None = None
     ) -> dict[str, Any] | None:
         """Validate a specific section of the API configuration.
 
         Args:
             section: The section name to validate
+            include: Optional list of parameter names to validate. If None,
+                validates all parameters for the section.
 
         Returns:
             dict[str, Any] | None: The response data from the device, or None if
@@ -371,6 +377,14 @@ class BSBLAN:
             error_msg = f"Section '{section}' not found in API data"
             raise BSBLANError(error_msg) from err
 
+        # Filter to only included params if specified
+        if include is not None:
+            section_data = {
+                param_id: name
+                for param_id, name in section_data.items()
+                if name in include
+            }
+
         try:
             # Request data from device for validation
             params = await self._extract_params_summary(section_data)
@@ -379,7 +393,7 @@ class BSBLAN:
             )
 
             # Validate the section against actual device response
-            api_validator.validate_section(section, response_data)
+            api_validator.validate_section(section, response_data, include)
             # Update API data with validated configuration
             if self._api_data:
                 self._api_data[section] = api_validator.get_section_params(section)
@@ -794,8 +808,8 @@ class BSBLAN:
                 are valid for this section.
 
         """
-        # Lazy load: validate section on first access
-        await self._ensure_section_validated(section)
+        # Lazy load: validate section on first access (only for included params)
+        await self._ensure_section_validated(section, include)
 
         section_params = self._api_validator.get_section_params(section)
 

{python_bsblan-4.1.0b0 → python_bsblan-4.1.0b1}/src/bsblan/utility.py

@@ -77,13 +77,20 @@ class APIValidator:
     api_config: Any  # intentionally permissive to support tests and dynamic data
     validated_sections: set[str] = field(default_factory=set)
 
-    def validate_section(self, section: str, request_data: dict[str, Any]) -> None:
+    def validate_section(
+        self,
+        section: str,
+        request_data: dict[str, Any],
+        include: list[str] | None = None,
+    ) -> None:
         """Validate and update a section of API config based on actual device support.
 
         Args:
             section: The section of the API config to validate
                 (e.g., 'heating', 'hot_water')
             request_data: Response data from the device for validation
+            include: Optional list of parameter names to validate. If None,
+                validates all parameters for the section.
 
         """
         # Check if the section exists in the APIConfig object
@@ -99,8 +106,12 @@ class APIValidator:
         section_config = self.api_config[section]
         params_to_remove = []
 
-        # Check each parameter in the section
+        # Check each parameter in the section (filtered by include if specified)
         for param_id, param_name in section_config.items():
+            # Skip params not in include list (if include is specified)
+            if include is not None and param_name not in include:
+                continue
+
             if param_id not in request_data:
                 logger.info(
                     "Parameter %s (%s) not found in device response",

{python_bsblan-4.1.0b0 → python_bsblan-4.1.0b1}/tests/test_api_validation.py

@@ -163,7 +163,10 @@ async def test_validate_api_section_validation_error(
         bsblan._api_validator = APIValidator(bsblan._api_data)
 
         def mock_validate(
-            _self: APIValidator, _section: str, _response: dict[str, Any]
+            _self: APIValidator,
+            _section: str,
+            _response: dict[str, Any],
+            _include: list[str] | None = None,
         ) -> NoReturn:
             error_message = "Validation error"
             raise BSBLANError(error_message)
@@ -296,7 +299,9 @@ async def test_ensure_section_validated_double_check_after_lock() -> None:
         # Track validation calls
         validation_count = 0
 
-        async def mock_validate(section: str) -> dict[str, Any]:
+        async def mock_validate(
+            section: str, _include: list[str] | None = None
+        ) -> dict[str, Any]:
             nonlocal validation_count
             validation_count += 1
             # Mark section as validated
@@ -329,7 +334,9 @@ async def test_ensure_section_validated_concurrent_double_check() -> None:
         validation_count = 0
         validation_started = asyncio.Event()
 
-        async def slow_validate(section: str) -> dict[str, Any]:
+        async def slow_validate(
+            section: str, _include: list[str] | None = None
+        ) -> dict[str, Any]:
             nonlocal validation_count
             validation_count += 1
             validation_started.set()
@@ -392,7 +399,9 @@ async def test_ensure_section_validated_heating_extracts_temp_unit() -> None:
         bsblan._api_validator = APIValidator(bsblan._api_data)
 
         # Mock _validate_api_section to return response with temp unit
-        async def mock_validate(section: str) -> dict[str, Any]:
+        async def mock_validate(
+            section: str, _include: list[str] | None = None
+        ) -> dict[str, Any]:
             bsblan._api_validator.validated_sections.add(section)
             if section == "heating":
                 return {"710": {"value": "20.0", "unit": "°F"}}

{python_bsblan-4.1.0b0 → python_bsblan-4.1.0b1}/tests/test_include_parameter.py

@@ -164,6 +164,86 @@ async def test_section_method_with_invalid_params(
         request_mock.assert_not_awaited()
 
 
+# ========== Tests for _validate_api_section with include parameter ==========
+
+
+@pytest.mark.asyncio
+async def test_validate_api_section_with_include_filter(monkeypatch: Any) -> None:
+    """Test _validate_api_section filters params when include is specified."""
+    async with aiohttp.ClientSession() as session:
+        config = BSBLANConfig(host="example.com")
+        bsblan = BSBLAN(config, session=session)
+
+        monkeypatch.setattr(bsblan, "_firmware_version", "1.0.38-20200730234859")
+        monkeypatch.setattr(bsblan, "_api_version", "v3")
+
+        # Set up API data with multiple params
+        api_data = {
+            "heating": {
+                "700": "hvac_mode",
+                "710": "target_temperature",
+                "8740": "current_temperature",
+            },
+            "sensor": {},
+            "staticValues": {},
+            "device": {},
+            "hot_water": {},
+        }
+        bsblan._api_data = api_data  # type: ignore[assignment]
+
+        api_validator = APIValidator(api_data)
+        bsblan._api_validator = api_validator
+
+        # Mock request to return only the filtered param
+        request_mock = AsyncMock(
+            return_value={"700": {"value": "1", "unit": "", "desc": "Auto"}}
+        )
+        monkeypatch.setattr(bsblan, "_request", request_mock)
+
+        # Validate with include filter - should only request hvac_mode
+        result = await bsblan._validate_api_section("heating", include=["hvac_mode"])
+
+        # Verify only filtered param was requested
+        request_mock.assert_awaited_once()
+        call_args = request_mock.call_args
+        assert call_args.kwargs["params"]["Parameter"] == "700"
+
+        # Result should contain the response data
+        assert result is not None
+        assert "700" in result
+
+
+@pytest.mark.asyncio
+async def test_validate_section_skips_params_not_in_include() -> None:
+    """Test validate_section skips params not in include list."""
+    # Set up API config with multiple params
+    api_config = {
+        "heating": {
+            "700": "hvac_mode",
+            "710": "target_temperature",
+            "8740": "current_temperature",
+        },
+    }
+
+    api_validator = APIValidator(api_config)
+
+    # Mock request data with only one param (simulating filtered response)
+    request_data = {"700": {"value": "1", "unit": "", "desc": "Auto"}}
+
+    # Validate with include filter - should skip params not in include
+    api_validator.validate_section("heating", request_data, include=["hvac_mode"])
+
+    # Section should be validated
+    assert api_validator.is_section_validated("heating")
+
+    # hvac_mode (700) should still be in config since it was valid
+    # Other params should NOT be removed since they weren't in include
+    assert "700" in api_validator.api_config["heating"]
+    # 710 and 8740 were not validated (skipped), so they remain
+    assert "710" in api_validator.api_config["heating"]
+    assert "8740" in api_validator.api_config["heating"]
+
+
 # ========== Additional state() specific tests ==========
 
 

{python_bsblan-4.1.0b0 → python_bsblan-4.1.0b1}/tests/test_info.py

@@ -46,6 +46,9 @@ async def test_info(aresponses: ResponsesMockServer, monkeypatch: Any) -> None:
 
         info: Info = await bsblan.info()
         assert info
+        assert info.controller_family is not None
+        assert info.controller_variant is not None
+        assert info.device_identification is not None
         assert info.controller_family.value == 211
         assert info.controller_variant.value == 127
         assert info.device_identification.value == "RVS21.831F/127"