python-bsblan 5.1.4__py3-none-any.whl → 5.2.0__py3-none-any.whl

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",

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.
 

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",
+        },
+    }

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.1.4.dist-info → python_bsblan-5.2.0.dist-info}/METADATA

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: python-bsblan
-Version: 5.1.4
+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
-Project-URL: Documentation, https://github.com/liudger/python-bsblan
+Project-URL: Documentation, https://liudger.github.io/python-bsblan
 Project-URL: Bug Tracker, https://github.com/liudger/python-bsblan/issues
 Project-URL: Changelog, https://github.com/liudger/python-bsblan/releases
 Author-email: Willem-Jan van Rootselaar <liudgervr@gmail.com>
@@ -41,8 +41,9 @@ Description-Content-Type: text/markdown
 [![Build Status][build-shield]][build]
 [![Code Coverage][codecov-shield]][codecov]
 [![Quality Gate Status][sonarcloud-shield]][sonarcloud]
-
-[![Buy me a coffee][buymeacoffee-shield]][buymeacoffee]
+[![OpenSSF Scorecard][scorecard-shield]][scorecard]
+[![OpenSSF Best Practices][bestpractices-shield]][bestpractices]
+[![Documentation][docs-shield]][docs]
 
 Asynchronous Python client for BSBLan.
 
@@ -52,97 +53,36 @@ This package allows you to control and monitor a BSBLan device
 programmatically. It is mainly created to allow third-party programs to automate
 the behavior of [BSBLan][bsblanmodule].
 
+**[Full documentation](https://liudger.github.io/python-bsblan)**
+
 ## Installation
 
 ```bash
 pip install python-bsblan
 ```
 
-## Usage
+## Quick start
 
 ```python
-# pylint: disable=W0621
-"""Asynchronous Python client for BSBLan."""
-
 import asyncio
-import os
-
-from bsblan import BSBLAN, BSBLANConfig, Device, Info, Sensor, State, StaticState
-
-
-async def print_state(state: State) -> None:
-    """Print the current state of the BSBLan device."""
-    print(f"HVAC Action: {state.hvac_action.desc}")
-    print(f"HVAC Mode: {state.hvac_mode.desc}")
-    print(f"Current Temperature: {state.current_temperature.value}")
-
-
-async def print_sensor(sensor: Sensor) -> None:
-    """Print sensor information from the BSBLan device."""
-    print(f"Outside Temperature: {sensor.outside_temperature.value}")
-
-
-async def print_device_info(device: Device, info: Info) -> None:
-    """Print device and general information."""
-    print(f"Device Name: {device.name}")
-    print(f"Version: {device.version}")
-    print(f"Device Identification: {info.device_identification.value}")
-
-
-async def print_static_state(static_state: StaticState) -> None:
-    """Print static state information."""
-    print(f"Min Temperature: {static_state.min_temp.value}")
-    print(f"Max Temperature: {static_state.max_temp.value}")
-
+from bsblan import BSBLAN, BSBLANConfig
 
 async def main() -> None:
-    """Show example on controlling your BSBLan device.
-
-    Options:
-    - passkey (http://url/"passkey"/) if your device is setup for passkey authentication
-    - username and password if your device is setup for username/password authentication
-
-    """
-    # Create a configuration object
-    config = BSBLANConfig(
-        host="192.0.2.1",
-        passkey=None,
-        username=os.getenv("USERNAME"),  # Compliant
-        password=os.getenv("PASSWORD"),  # Compliant
-    )
-
-    # Initialize BSBLAN with the configuration object
-    async with BSBLAN(config) as bsblan:
-        # Get and print state
-        state: State = await bsblan.state()
-        await print_state(state)
+    config = BSBLANConfig(host="192.168.1.100")
+    async with BSBLAN(config) as client:
+        # Read current state
+        state = await client.state()
+        print(f"Current temperature: {state.current_temperature.value}")
 
         # Set thermostat temperature
-        print("\nSetting temperature to 18°C")
-        await bsblan.thermostat(target_temperature="18")
-
-        # Set HVAC mode (using raw integer: 0=off, 1=auto, 2=eco, 3=heat)
-        print("Setting HVAC mode to heat")
-        await bsblan.thermostat(hvac_mode=3)
-
-        # Get and print sensor information
-        sensor: Sensor = await bsblan.sensor()
-        await print_sensor(sensor)
-
-        # Get and print device and general info
-        device: Device = await bsblan.device()
-        info: Info = await bsblan.info()
-        await print_device_info(device, info)
-
-        # Get and print static state
-        static_state: StaticState = await bsblan.static_values()
-        await print_static_state(static_state)
+        await client.thermostat(target_temperature="21.5")
 
-
-if __name__ == "__main__":
-    asyncio.run(main())
+asyncio.run(main())
 ```
 
+For more examples, including hot water control, multi-circuit support, and
+authentication setup, see the [Getting Started][docs-getting-started] guide.
+
 ## Changelog & Releases
 
 This repository keeps a change log using [GitHub's releases][releases]
@@ -190,12 +130,14 @@ make setup
 A `Makefile` is provided for common development tasks. Run `make help` to
 see all available targets:
 
-| Command         | Description                          |
-|-----------------|--------------------------------------|
-| `make setup`    | Install dev dependencies & git hooks |
-| `make lint`     | Run all pre-commit hooks             |
-| `make test`     | Run tests                            |
-| `make coverage` | Run tests with coverage report       |
+| Command            | Description                          |
+|--------------------|--------------------------------------|
+| `make setup`       | Install dev dependencies & git hooks |
+| `make lint`        | Run all pre-commit hooks             |
+| `make test`        | Run tests                            |
+| `make coverage`    | Run tests with coverage report       |
+| `make docs`        | Build documentation                  |
+| `make docs-serve`  | Serve documentation locally          |
 
 As this repository uses [prek][prek] (a faster, Rust-based drop-in replacement
 for pre-commit), all changes are linted and tested with each commit. You can
@@ -243,9 +185,16 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
+---
+
+[![Buy me a coffee][buymeacoffee-shield]][buymeacoffee]
+
 [bsblanmodule]: https://github.com/fredlcore/bsb_lan
 [build-shield]: https://github.com/liudger/python-bsblan/actions/workflows/tests.yaml/badge.svg
 [build]: https://github.com/liudger/python-bsblan/actions
+[docs]: https://liudger.github.io/python-bsblan
+[docs-getting-started]: https://liudger.github.io/python-bsblan/getting-started/
+[docs-shield]: https://img.shields.io/badge/docs-GitHub%20Pages-blue
 [buymeacoffee-shield]: https://www.buymeacoffee.com/assets/img/guidelines/download-assets-sm-2.svg
 [buymeacoffee]: https://www.buymeacoffee.com/liudger
 [codecov-shield]: https://codecov.io/gh/liudger/python-bsblan/branch/main/graph/badge.svg?token=ypos87GGxv
@@ -259,11 +208,15 @@ SOFTWARE.
 [uv]: https://docs.astral.sh/uv/
 [uv-install]: https://docs.astral.sh/uv/getting-started/installation/
 [prek]: https://github.com/j178/prek
-[project-stage-shield]: https://img.shields.io/badge/project%20stage-experimental-yellow.svg
+[project-stage-shield]: https://img.shields.io/badge/project%20stage-stable-green.svg
 [pypi]: https://pypi.org/project/python-bsblan/
 [python-versions-shield]: https://img.shields.io/pypi/pyversions/python-bsblan
 [releases-shield]: https://img.shields.io/github/v/release/liudger/python-bsblan.svg
 [releases]: https://github.com/liudger/python-bsblan/releases
 [semver]: http://semver.org/spec/v2.0.0.html
+[scorecard-shield]: https://api.scorecard.dev/projects/github.com/liudger/python-bsblan/badge
+[scorecard]: https://scorecard.dev/viewer/?uri=github.com/liudger/python-bsblan
+[bestpractices-shield]: https://www.bestpractices.dev/projects/12561/badge
+[bestpractices]: https://www.bestpractices.dev/projects/12561
 [sonarcloud-shield]: https://sonarcloud.io/api/project_badges/measure?project=liudger_python-bsblan&metric=alert_status
 [sonarcloud]: https://sonarcloud.io/summary/new_code?id=liudger_python-bsblan

python_bsblan-5.2.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+bsblan/__init__.py,sha256=YD_edvxHL5ocUE2iLWhdinqpsRYWJkVrcds0b6aKp9U,1288
+bsblan/bsblan.py,sha256=PCNForRgeJFHwZRE_mEcvySQxiYLA2JCIzMJu429Fq4,63034
+bsblan/constants.py,sha256=LoMSrEdZj2zohDFxOQ2JT7J4jIH9clXh7sfkNnnjl5A,22864
+bsblan/exceptions.py,sha256=jL7qohIMmuVTsdWBB_trKPg5Yzim6JxaOT13h6EJPlk,1770
+bsblan/models.py,sha256=qEycc2eVkCK2CXWDXBSqtTyM-to6pH7jX6aKvXeH3R8,20705
+bsblan/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+bsblan/utility.py,sha256=sS0wWJoqvLAHzwaSLIqQEQ-boHsYFLKAHw8KNTSmdX8,5772
+python_bsblan-5.2.0.dist-info/METADATA,sha256=MjhQBz4cjiRwunT2OH4X-gRFsprNSIpLBMNu7kam24Y,8529
+python_bsblan-5.2.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+python_bsblan-5.2.0.dist-info/licenses/LICENSE.md,sha256=Shv8HPcD1WbZjBPvfb5r3h_cwaPeVaUZMUqU_XQGwGw,1092
+python_bsblan-5.2.0.dist-info/RECORD,,

python_bsblan-5.1.4.dist-info/RECORD

@@ -1,11 +0,0 @@
-bsblan/__init__.py,sha256=t_RF_90ManstXJBdoL8n98KK9tnTTvwezntJxk7GfBY,1180
-bsblan/bsblan.py,sha256=Pn240e7BXjWGS60Zq8jYBlR_umXuiVYDxoGCu_Usdlk,59973
-bsblan/constants.py,sha256=Q6lqnx1YFlPZZYpZrm8Ytx8HgmhTtO4U88EZmnPZTds,22089
-bsblan/exceptions.py,sha256=jL7qohIMmuVTsdWBB_trKPg5Yzim6JxaOT13h6EJPlk,1770
-bsblan/models.py,sha256=ZqztmI90aDODKJ06SHue2cU5AMqp0chjT8r_B1FUbxg,19409
-bsblan/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-bsblan/utility.py,sha256=sS0wWJoqvLAHzwaSLIqQEQ-boHsYFLKAHw8KNTSmdX8,5772
-python_bsblan-5.1.4.dist-info/METADATA,sha256=0SguR6h4-8P6HHJdzlCeZMsxJe36N7BC21MAMsfUtso,9728
-python_bsblan-5.1.4.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-python_bsblan-5.1.4.dist-info/licenses/LICENSE.md,sha256=Shv8HPcD1WbZjBPvfb5r3h_cwaPeVaUZMUqU_XQGwGw,1092
-python_bsblan-5.1.4.dist-info/RECORD,,