python-bsblan 5.1.5__tar.gz → 5.2.0__tar.gz

{python_bsblan-5.1.5 → python_bsblan-5.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-bsblan
-Version: 5.1.5
+Version: 5.2.0
 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-5.1.5 → python_bsblan-5.2.0}/docs/api/client.md

@@ -19,6 +19,8 @@ The main entry point for interacting with BSB-LAN devices.
         - time
         - set_time
         - thermostat
+        - heating_schedule
+        - set_heating_schedule
         - hot_water_state
         - hot_water_config
         - hot_water_schedule

{python_bsblan-5.1.5 → python_bsblan-5.2.0}/docs/api/models.md

@@ -26,6 +26,10 @@ Data models for BSB-LAN API responses.
 
 ::: bsblan.Sensor
 
+### HeatingTimeSwitchPrograms
+
+::: bsblan.HeatingTimeSwitchPrograms
+
 ## Hot water
 
 ### HotWaterState
@@ -46,6 +50,10 @@ Data models for BSB-LAN API responses.
 
 ## Schedules
 
+### HeatingSchedule
+
+::: bsblan.HeatingSchedule
+
 ### DHWSchedule
 
 ::: bsblan.DHWSchedule

{python_bsblan-5.1.5 → python_bsblan-5.2.0}/pyproject.toml

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

{python_bsblan-5.1.5 → python_bsblan-5.2.0}/src/bsblan/__init__.py

@@ -17,6 +17,8 @@ from .models import (
     DHWTimeSwitchPrograms,
     EntityInfo,
     EntityValue,
+    HeatingSchedule,
+    HeatingTimeSwitchPrograms,
     HotWaterConfig,
     HotWaterSchedule,
     HotWaterState,
@@ -45,6 +47,8 @@ __all__ = [
     "EntityValue",
     "HVACActionCategory",
     "HeatingCircuitStatus",
+    "HeatingSchedule",
+    "HeatingTimeSwitchPrograms",
     "HotWaterConfig",
     "HotWaterSchedule",
     "HotWaterState",

{python_bsblan-5.1.5 → python_bsblan-5.2.0}/src/bsblan/bsblan.py

@@ -22,6 +22,7 @@ from .constants import (
     APIConfig,
     CircuitConfig,
     ErrorMsg,
+    HeatingScheduleParams,
     HotWaterParams,
     Validation,
 )
@@ -38,6 +39,8 @@ from .models import (
     DeviceTime,
     DHWSchedule,
     EntityInfo,
+    HeatingSchedule,
+    HeatingTimeSwitchPrograms,
     HotWaterConfig,
     HotWaterSchedule,
     HotWaterState,
@@ -1380,6 +1383,91 @@ class BSBLAN:
             include=include,
         )
 
+    async def heating_schedule(
+        self,
+        include: list[str] | None = None,
+        circuit: int = 1,
+    ) -> HeatingTimeSwitchPrograms:
+        """Get heating time switch programs for a specific circuit.
+
+        Args:
+            include: Optional list of day names to fetch. If None,
+                fetches all schedule parameters. Valid names include:
+                monday, tuesday, wednesday, thursday,
+                friday, saturday, sunday, standard_values.
+            circuit: The heating circuit number (1 or 2). Defaults to 1.
+
+        Returns:
+            HeatingTimeSwitchPrograms: Heating schedule information.
+
+        """
+        self._validate_circuit(circuit)
+        time_program_params = HeatingScheduleParams.TIME_PROGRAMS[circuit]
+
+        filtered_params = time_program_params
+        if include is not None:
+            if not include:
+                raise BSBLANError(ErrorMsg.EMPTY_INCLUDE_LIST)
+            filtered_params = {
+                param_id: name
+                for param_id, name in time_program_params.items()
+                if name in include
+            }
+            if not filtered_params:
+                raise BSBLANError(ErrorMsg.INVALID_INCLUDE_PARAMS)
+
+        params = self._extract_params_summary(filtered_params)
+        data = await self._request(params={"Parameter": params["string_par"]})
+        mapped_data = {
+            name: data[param_id]
+            for param_id, name in filtered_params.items()
+            if param_id in data
+        }
+
+        if not mapped_data:
+            raise BSBLANError(ErrorMsg.NO_HEATING_SCHEDULE_PARAMS)
+
+        return HeatingTimeSwitchPrograms.model_validate(mapped_data)
+
+    async def set_heating_schedule(
+        self,
+        schedule: HeatingSchedule,
+        circuit: int = 1,
+    ) -> None:
+        """Set heating time switch programs for a specific circuit.
+
+        This method allows setting weekly heating schedules using a type-safe
+        interface with TimeSlot and DaySchedule objects.
+
+        Args:
+            schedule: HeatingSchedule object containing the weekly schedule.
+            circuit: The heating circuit number (1 or 2). Defaults to 1.
+
+        Raises:
+            BSBLANError: If no schedule is provided.
+
+        """
+        self._validate_circuit(circuit)
+
+        if not schedule.has_any_schedule():
+            raise BSBLANError(ErrorMsg.NO_SCHEDULE)
+
+        day_param_map = {
+            v: k
+            for k, v in HeatingScheduleParams.TIME_PROGRAMS[circuit].items()
+            if v != "standard_values"
+        }
+
+        for day_name, param_id in day_param_map.items():
+            day_schedule: DaySchedule | None = getattr(schedule, day_name)
+            if day_schedule is not None:
+                state = {
+                    "Parameter": param_id,
+                    "Value": day_schedule.to_bsblan_format(),
+                    "Type": "1",
+                }
+                await self._set_device_state(state)
+
     async def set_hot_water(self, params: SetHotWaterParam) -> None:
         """Change the state of the hot water system through BSB-Lan.
 

{python_bsblan-5.1.5 → python_bsblan-5.2.0}/src/bsblan/constants.py

@@ -491,6 +491,7 @@ class ErrorMsg:
     EMPTY_INCLUDE_LIST = (
         "Empty include list provided. Use None to fetch all parameters."
     )
+    NO_HEATING_SCHEDULE_PARAMS = "No heating schedule parameters available"
 
 
 # Handle both ASCII and Unicode degree symbols
@@ -655,3 +656,30 @@ class HotWaterParams:
         "567": "sunday",
         "576": "standard_values",
     }
+
+
+class HeatingScheduleParams:
+    """Heating schedule parameter mappings per circuit."""
+
+    TIME_PROGRAMS: Final[dict[int, dict[str, str]]] = {
+        1: {
+            "501": "monday",
+            "502": "tuesday",
+            "503": "wednesday",
+            "504": "thursday",
+            "505": "friday",
+            "506": "saturday",
+            "507": "sunday",
+            "516": "standard_values",
+        },
+        2: {
+            "521": "monday",
+            "522": "tuesday",
+            "523": "wednesday",
+            "524": "thursday",
+            "525": "friday",
+            "526": "saturday",
+            "527": "sunday",
+            "536": "standard_values",
+        },
+    }

{python_bsblan-5.1.5 → python_bsblan-5.2.0}/src/bsblan/models.py

@@ -141,23 +141,10 @@ class DaySchedule:
 
 
 @dataclass
-class DHWSchedule:
-    """Weekly hot water schedule for setting time programs.
+class WeeklySchedule:
+    """Base weekly schedule with optional day schedules.
 
-    Use this dataclass to set DHW time programs via set_hot_water_schedule().
-    Each day can have up to 3 time slots.
-
-    Example:
-        >>> schedule = DHWSchedule(
-        ...     monday=DaySchedule(slots=[
-        ...         TimeSlot(time(6, 0), time(8, 0)),
-        ...         TimeSlot(time(17, 0), time(21, 0)),
-        ...     ]),
-        ...     tuesday=DaySchedule(slots=[
-        ...         TimeSlot(time(6, 0), time(8, 0)),
-        ...     ])
-        ... )
-        >>> await client.set_hot_water_schedule(schedule)
+    Each day can have up to 3 time slots (validated by DaySchedule).
 
     """
 
@@ -190,6 +177,38 @@ class DHWSchedule:
         )
 
 
+@dataclass
+class DHWSchedule(WeeklySchedule):
+    """Weekly hot water schedule for setting time programs.
+
+    Use this dataclass to set DHW time programs via set_hot_water_schedule().
+    Each day can have up to 3 time slots.
+
+    Example:
+        >>> schedule = DHWSchedule(
+        ...     monday=DaySchedule(slots=[
+        ...         TimeSlot(time(6, 0), time(8, 0)),
+        ...         TimeSlot(time(17, 0), time(21, 0)),
+        ...     ]),
+        ...     tuesday=DaySchedule(slots=[
+        ...         TimeSlot(time(6, 0), time(8, 0)),
+        ...     ])
+        ... )
+        >>> await client.set_hot_water_schedule(schedule)
+
+    """
+
+
+@dataclass
+class HeatingSchedule(WeeklySchedule):
+    """Weekly heating schedule for setting time programs.
+
+    Use this dataclass to set heating time programs via set_heating_schedule().
+    Each day can have up to 3 time slots.
+
+    """
+
+
 @dataclass
 class DHWTimeSwitchPrograms:
     """Dataclass for DHW time switch programs."""
@@ -554,6 +573,29 @@ class HotWaterSchedule(BaseModel):
     dhw_time_program_standard_values: EntityInfo[int] | None = None
 
 
+class HeatingTimeSwitchPrograms(BaseModel):
+    """Heating time switch programs for a specific heating circuit (READ).
+
+    The daily time programs (Monday-Sunday) use BSB-LAN dataType 9
+    (TIMEPROG) and return schedule strings like
+    ``"13:00-15:00 ##:##-##:## ##:##-##:##"`` where ``##:##`` marks
+    unused time slots.
+
+    ``standard_values`` is a YESNO enum (0=No, 1=Yes) that resets
+    all daily schedules back to the controller's factory defaults.
+
+    """
+
+    monday: EntityInfo[str | int] | None = None
+    tuesday: EntityInfo[str | int] | None = None
+    wednesday: EntityInfo[str | int] | None = None
+    thursday: EntityInfo[str | int] | None = None
+    friday: EntityInfo[str | int] | None = None
+    saturday: EntityInfo[str | int] | None = None
+    sunday: EntityInfo[str | int] | None = None
+    standard_values: EntityInfo[int] | None = None
+
+
 class DeviceTime(BaseModel):
     """Object holds device time information."""
 

python_bsblan-5.2.0/tests/test_heating_schedule.py

@@ -0,0 +1,145 @@
+"""Tests for heating_schedule method."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+from unittest.mock import AsyncMock
+
+import pytest
+
+from bsblan.exceptions import BSBLANError
+from bsblan.models import HeatingTimeSwitchPrograms
+
+if TYPE_CHECKING:
+    from bsblan import BSBLAN
+
+
+def _build_schedule_fixture(param_ids: list[str]) -> dict[str, dict[str, Any]]:
+    """Build fixture data for schedule parameter IDs."""
+    fixture: dict[str, dict[str, Any]] = {}
+    for param_id in param_ids:
+        if param_id in {"516", "536"}:
+            fixture[param_id] = {
+                "name": "Standard values",
+                "value": "0",
+                "unit": "",
+                "desc": "No",
+                "dataType": 1,
+            }
+        else:
+            fixture[param_id] = {
+                "name": f"Time switch {param_id}",
+                "value": "06:00-22:00 ##:##-##:## ##:##-##:##",
+                "unit": "",
+                "desc": "",
+                "dataType": 9,
+            }
+    return fixture
+
+
+@pytest.mark.asyncio
+async def test_heating_schedule_circuit1(mock_bsblan: BSBLAN) -> None:
+    """Test reading heating schedule for circuit 1."""
+    fixture_data = _build_schedule_fixture(
+        ["501", "502", "503", "504", "505", "506", "507", "516"]
+    )
+
+    def mock_request(**kwargs: Any) -> dict[str, Any]:
+        param_string = kwargs.get("params", {}).get("Parameter", "")
+        requested_param_ids = param_string.split(",") if param_string else []
+        return {
+            param_id: fixture_data[param_id]
+            for param_id in requested_param_ids
+            if param_id in fixture_data
+        }
+
+    request_mock = AsyncMock(side_effect=mock_request)
+    mock_bsblan._request = request_mock  # type: ignore[method-assign]
+
+    result = await mock_bsblan.heating_schedule(circuit=1)
+
+    assert isinstance(result, HeatingTimeSwitchPrograms)
+    assert result.monday is not None
+    assert result.monday.value == "06:00-22:00 ##:##-##:## ##:##-##:##"
+    assert result.standard_values is not None
+    assert result.standard_values.value == 0
+
+
+@pytest.mark.asyncio
+async def test_heating_schedule_circuit2(mock_bsblan: BSBLAN) -> None:
+    """Test reading heating schedule for circuit 2."""
+    fixture_data = _build_schedule_fixture(
+        ["521", "522", "523", "524", "525", "526", "527", "536"]
+    )
+
+    def mock_request(**kwargs: Any) -> dict[str, Any]:
+        param_string = kwargs.get("params", {}).get("Parameter", "")
+        requested_param_ids = param_string.split(",") if param_string else []
+        return {
+            param_id: fixture_data[param_id]
+            for param_id in requested_param_ids
+            if param_id in fixture_data
+        }
+
+    request_mock = AsyncMock(side_effect=mock_request)
+    mock_bsblan._request = request_mock  # type: ignore[method-assign]
+
+    result = await mock_bsblan.heating_schedule(circuit=2)
+
+    assert isinstance(result, HeatingTimeSwitchPrograms)
+    assert result.monday is not None
+    assert result.standard_values is not None
+
+
+@pytest.mark.asyncio
+async def test_heating_schedule_include_filter(mock_bsblan: BSBLAN) -> None:
+    """Test include filter for heating schedule."""
+    fixture_data = _build_schedule_fixture(["521", "536"])
+
+    def mock_request(**kwargs: Any) -> dict[str, Any]:
+        param_string = kwargs.get("params", {}).get("Parameter", "")
+        requested_param_ids = param_string.split(",") if param_string else []
+        return {
+            param_id: fixture_data[param_id]
+            for param_id in requested_param_ids
+            if param_id in fixture_data
+        }
+
+    request_mock = AsyncMock(side_effect=mock_request)
+    mock_bsblan._request = request_mock  # type: ignore[method-assign]
+
+    result = await mock_bsblan.heating_schedule(
+        include=["monday", "standard_values"],
+        circuit=2,
+    )
+
+    assert result.monday is not None
+    assert result.standard_values is not None
+    assert result.tuesday is None
+
+    call_args = request_mock.call_args
+    assert call_args is not None
+    assert call_args.kwargs["params"]["Parameter"] == "521,536"
+
+
+@pytest.mark.asyncio
+async def test_heating_schedule_empty_include_raises(mock_bsblan: BSBLAN) -> None:
+    """Test empty include list raises error."""
+    with pytest.raises(BSBLANError, match="Empty include list"):
+        await mock_bsblan.heating_schedule(include=[], circuit=1)
+
+
+@pytest.mark.asyncio
+async def test_heating_schedule_invalid_include_raises(mock_bsblan: BSBLAN) -> None:
+    """Test invalid include parameter raises error."""
+    with pytest.raises(BSBLANError, match="None of the requested parameters"):
+        await mock_bsblan.heating_schedule(include=["invalid_day"], circuit=1)
+
+
+@pytest.mark.asyncio
+async def test_heating_schedule_no_params_raises(mock_bsblan: BSBLAN) -> None:
+    """Test no schedule params in response raises error."""
+    mock_bsblan._request = AsyncMock(return_value={})  # type: ignore[method-assign]
+
+    with pytest.raises(BSBLANError, match="No heating schedule parameters available"):
+        await mock_bsblan.heating_schedule(circuit=1)

{python_bsblan-5.1.5 → python_bsblan-5.2.0}/tests/test_schedule_models.py

@@ -6,7 +6,7 @@ from datetime import time
 
 import pytest
 
-from bsblan.models import DaySchedule, DHWSchedule, TimeSlot
+from bsblan.models import DaySchedule, DHWSchedule, HeatingSchedule, TimeSlot
 
 
 class TestTimeSlot:
@@ -227,3 +227,34 @@ class TestDHWSchedule:
         assert schedule.sunday is not None
         assert schedule.monday is None
         assert schedule.has_any_schedule() is True
+
+
+class TestHeatingSchedule:
+    """Test cases for HeatingSchedule dataclass."""
+
+    def test_empty_heating_schedule(self) -> None:
+        """Test creating an empty heating schedule."""
+        schedule = HeatingSchedule()
+        assert schedule.monday is None
+        assert schedule.tuesday is None
+        assert schedule.has_any_schedule() is False
+
+    def test_heating_schedule_has_any_schedule_true(self) -> None:
+        """Test has_any_schedule returns True when a day is set."""
+        schedule = HeatingSchedule(
+            monday=DaySchedule(slots=[TimeSlot(time(6, 0), time(8, 0))])
+        )
+        assert schedule.has_any_schedule() is True
+
+    def test_heating_schedule_weekend_only(self) -> None:
+        """Test setting only weekend days."""
+        weekend = DaySchedule(
+            slots=[
+                TimeSlot(time(8, 0), time(10, 0)),
+                TimeSlot(time(18, 0), time(22, 0)),
+            ]
+        )
+        schedule = HeatingSchedule(saturday=weekend, sunday=weekend)
+        assert schedule.saturday is not None
+        assert schedule.sunday is not None
+        assert schedule.has_any_schedule() is True

python_bsblan-5.2.0/tests/test_set_heating_schedule.py

@@ -0,0 +1,150 @@
+"""Tests for set_heating_schedule method."""
+
+# pylint: disable=duplicate-code
+# pylint: disable=protected-access
+# file deepcode ignore W0212: this is a testfile
+
+from __future__ import annotations
+
+from datetime import time
+from typing import TYPE_CHECKING
+from unittest.mock import AsyncMock
+
+import pytest
+
+from bsblan.exceptions import BSBLANError
+from bsblan.models import DaySchedule, HeatingSchedule, TimeSlot
+
+if TYPE_CHECKING:
+    from bsblan import BSBLAN
+
+
+@pytest.mark.asyncio
+async def test_set_heating_schedule_circuit1_single_day(mock_bsblan: BSBLAN) -> None:
+    """Test setting heating schedule for circuit 1."""
+    schedule = HeatingSchedule(
+        monday=DaySchedule(
+            slots=[
+                TimeSlot(time(6, 0), time(8, 0)),
+                TimeSlot(time(17, 0), time(21, 0)),
+            ]
+        )
+    )
+
+    assert isinstance(mock_bsblan._request, AsyncMock)
+    await mock_bsblan.set_heating_schedule(schedule, circuit=1)
+
+    mock_bsblan._request.assert_awaited_with(
+        base_path="/JS",
+        data={
+            "Parameter": "501",
+            "Value": "06:00-08:00 17:00-21:00",
+            "Type": "1",
+        },
+    )
+
+
+@pytest.mark.asyncio
+async def test_set_heating_schedule_circuit2_single_day(mock_bsblan: BSBLAN) -> None:
+    """Test setting heating schedule for circuit 2."""
+    schedule = HeatingSchedule(
+        monday=DaySchedule(
+            slots=[
+                TimeSlot(time(6, 0), time(8, 0)),
+            ]
+        )
+    )
+
+    assert isinstance(mock_bsblan._request, AsyncMock)
+    await mock_bsblan.set_heating_schedule(schedule, circuit=2)
+
+    mock_bsblan._request.assert_awaited_with(
+        base_path="/JS",
+        data={
+            "Parameter": "521",
+            "Value": "06:00-08:00",
+            "Type": "1",
+        },
+    )
+
+
+@pytest.mark.asyncio
+async def test_set_heating_schedule_multiple_days(mock_bsblan: BSBLAN) -> None:
+    """Test setting heating schedule for multiple days."""
+    schedule = HeatingSchedule(
+        monday=DaySchedule(slots=[TimeSlot(time(6, 0), time(8, 0))]),
+        friday=DaySchedule(slots=[TimeSlot(time(7, 0), time(9, 0))]),
+    )
+
+    assert isinstance(mock_bsblan._request, AsyncMock)
+    await mock_bsblan.set_heating_schedule(schedule, circuit=1)
+
+    assert mock_bsblan._request.await_count == 2
+
+
+@pytest.mark.asyncio
+async def test_set_heating_schedule_empty_raises_error(mock_bsblan: BSBLAN) -> None:
+    """Test that empty schedule raises BSBLANError."""
+    schedule = HeatingSchedule()
+
+    with pytest.raises(BSBLANError, match="No schedule provided"):
+        await mock_bsblan.set_heating_schedule(schedule, circuit=1)
+
+
+@pytest.mark.asyncio
+async def test_set_heating_schedule_parameter_ids_per_circuit(
+    mock_bsblan: BSBLAN,
+) -> None:
+    """Test that correct parameter IDs are used per day and circuit."""
+    expected_params = {
+        1: {
+            "monday": "501",
+            "tuesday": "502",
+            "wednesday": "503",
+            "thursday": "504",
+            "friday": "505",
+            "saturday": "506",
+            "sunday": "507",
+        },
+        2: {
+            "monday": "521",
+            "tuesday": "522",
+            "wednesday": "523",
+            "thursday": "524",
+            "friday": "525",
+            "saturday": "526",
+            "sunday": "527",
+        },
+    }
+
+    for circuit, day_map in expected_params.items():
+        for day_name, param_id in day_map.items():
+            assert isinstance(mock_bsblan._request, AsyncMock)
+            mock_bsblan._request.reset_mock()
+
+            schedule = HeatingSchedule(
+                **{day_name: DaySchedule(slots=[TimeSlot(time(6, 0), time(8, 0))])}
+            )
+            await mock_bsblan.set_heating_schedule(schedule, circuit=circuit)
+
+            call_args = mock_bsblan._request.call_args
+            assert call_args is not None
+            assert call_args.kwargs["data"]["Parameter"] == param_id
+
+
+@pytest.mark.asyncio
+async def test_set_heating_schedule_empty_day_schedule(mock_bsblan: BSBLAN) -> None:
+    """Test setting an empty day schedule (clears the schedule)."""
+    schedule = HeatingSchedule(monday=DaySchedule(slots=[]))
+
+    assert isinstance(mock_bsblan._request, AsyncMock)
+    await mock_bsblan.set_heating_schedule(schedule, circuit=1)
+
+    mock_bsblan._request.assert_awaited_with(
+        base_path="/JS",
+        data={
+            "Parameter": "501",
+            "Value": "",
+            "Type": "1",
+        },
+    )