python-bsblan 3.1.1__tar.gz → 3.1.3__tar.gz

python_bsblan-3.1.3/.github/copilot-instructions.md

@@ -0,0 +1,205 @@
+# GitHub Copilot Instructions for python-bsblan
+
+This repository contains the `python-bsblan` library, an asynchronous Python client for BSB-LAN devices (heating controllers).
+
+## Project Overview
+
+- **Language**: Python 3.12+
+- **Type**: Async library using `aiohttp`
+- **Purpose**: Communicate with BSB-LAN devices to read/write heating parameters
+- **License**: MIT
+
+## Code Quality Standards
+
+### Required Before Committing
+
+Always run these commands after making changes:
+
+```bash
+# Run all pre-commit hooks (ruff, mypy, pylint, pytest)
+uv run pre-commit run --all-files
+```
+
+### Pre-commit Includes
+- **Ruff**: Linting and formatting (88 char line limit)
+- **MyPy**: Static type checking
+- **Pylint**: Code analysis
+- **Pytest**: Test execution with coverage
+
+### Coverage Requirements
+- Maintain **95%+ total test coverage**
+- **Patch coverage must be 100%** - all new/modified code must be fully tested
+- GitHub Actions will fail if patch coverage is below 100%
+- Run coverage check: `uv run pytest --cov=src/bsblan --cov-report=term-missing`
+
+## Project Structure
+
+```
+src/bsblan/
+├── __init__.py          # Package exports
+├── bsblan.py            # Main BSBLAN client class
+├── constants.py         # Parameter IDs and mappings
+├── models.py            # Dataclass models for API responses
+├── utility.py           # Helper utilities
+├── exceptions.py        # Custom exceptions
+└── py.typed             # PEP-561 marker
+
+tests/
+├── conftest.py          # Pytest fixtures
+├── fixtures/            # JSON test data
+└── test_*.py            # Test files
+```
+
+## Parameter Naming Conventions
+
+### BSB-LAN Parameters
+Parameters are identified by numeric IDs and mapped to readable names in `constants.py`.
+
+**Naming Rules:**
+- Use `snake_case` for all parameter names
+- Group related parameters with common prefixes
+- Legionella-related parameters use `legionella_function_*` prefix:
+  - `legionella_function_setpoint` (ID: 1645)
+  - `legionella_function_periodicity` (ID: 1641)
+  - `legionella_function_day` (ID: 1642)
+  - `legionella_function_time` (ID: 1644)
+  - `legionella_function_dwelling_time` (ID: 1646)
+- DHW (Domestic Hot Water) parameters use `dhw_*` prefix
+
+### Adding New Parameters
+
+1. **Add to `constants.py`**:
+   ```python
+   BASE_HOT_WATER_PARAMS: Final[dict[str, str]] = {
+       "1645": "legionella_function_setpoint",  # Parameter ID: name
+   }
+   ```
+
+2. **Add to model in `models.py`**:
+   ```python
+   @dataclass
+   class HotWaterConfig(DataClassORJSONMixin):
+       legionella_function_setpoint: ParameterValue | None = None
+   ```
+
+3. **Update method in `bsblan.py`** if the parameter is settable:
+   ```python
+   async def set_hot_water(
+       self,
+       legionella_function_setpoint: float | None = None,
+   ) -> None:
+   ```
+
+4. **Add tests in `tests/test_*.py`**
+
+## Polling Categories
+
+Parameters are organized into polling categories based on how frequently they change:
+
+### Fast Poll (State - every update)
+- Current temperatures
+- HVAC action/state
+- Pump states
+
+### Slow Poll (Config - every 5 minutes)
+- Operating modes
+- Setpoints
+- Legionella function settings
+- Time programs
+
+### Static (rarely changes)
+- Device identification
+- Min/max temperature limits
+
+## Data Models
+
+### Model Pattern
+All models use `mashumaro` for JSON serialization:
+
+```python
+from dataclasses import dataclass
+from mashumaro.mixins.orjson import DataClassORJSONMixin
+
+@dataclass
+class HotWaterConfig(DataClassORJSONMixin):
+    """Hot water configuration parameters."""
+    operating_mode: ParameterValue | None = None
+    nominal_setpoint: ParameterValue | None = None
+```
+
+### ParameterValue Structure
+Each parameter returns a `ParameterValue` with:
+- `value`: The actual value
+- `unit`: Unit of measurement
+- `desc`: Human-readable description
+- `dataType`: Data type information
+
+## Async Patterns
+
+### Client Usage
+```python
+async with BSBLAN(host="192.168.1.100") as client:
+    state = await client.state()
+    await client.set_hot_water(nominal_setpoint=55.0)
+```
+
+### Error Handling
+- Use `BSBLANError` for general errors
+- Use `BSBLANConnectionError` for connection issues
+- Always validate only one parameter is set per API call
+
+## Testing Patterns
+
+### Test Structure
+```python
+@pytest.mark.asyncio
+async def test_set_hot_water(mock_bsblan: BSBLAN) -> None:
+    """Test setting BSBLAN hot water state."""
+    await mock_bsblan.set_hot_water(nominal_setpoint=60.0)
+    mock_bsblan._request.assert_awaited_with(
+        base_path="/JS",
+        data={"Parameter": "1610", "Value": "60.0", "Type": "1"},
+    )
+```
+
+### Fixtures Location
+Test fixtures (JSON responses) are in `tests/fixtures/`
+
+## Common Tasks
+
+### Adding a New Settable Parameter
+
+1. Add parameter ID mapping in `constants.py`
+2. Add field to appropriate model in `models.py`
+3. Add parameter to method signature in `bsblan.py`
+4. Update docstring with parameter description
+5. Add state preparation logic in `_prepare_*_state()` method
+6. Add tests for the new parameter
+7. Run `uv run pre-commit run --all-files`
+
+### Renaming a Parameter
+
+When renaming parameters for consistency:
+1. Update `constants.py` - parameter mapping
+2. Update `models.py` - dataclass field
+3. Update `bsblan.py` - method parameters and state handling
+4. Update `tests/` - all test files using the parameter
+5. Update `examples/` - any example code
+6. Run `uv run pre-commit run --all-files`
+
+## API Versions
+
+The library supports BSB-LAN API versions:
+- **v1**: Original API
+- **v3**: Extended API with additional parameters
+
+Version-specific parameters are handled in `constants.py` with extension dictionaries.
+
+## Don't Forget
+
+- ✅ Run `uv run pre-commit run --all-files` after every change
+- ✅ Maintain 95%+ test coverage
+- ✅ Use type hints on all functions
+- ✅ Add docstrings to public methods
+- ✅ Keep line length under 88 characters
+- ✅ Use consistent parameter naming (check existing patterns)

{python_bsblan-3.1.1 → python_bsblan-3.1.3}/.github/workflows/codeql.yaml

@@ -17,8 +17,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: ⤵️ Check out code from GitHub
-        uses: actions/checkout@v5.0.0
+        uses: actions/checkout@v5.0.1
       - name: 🏗 Initialize CodeQL
-        uses: github/codeql-action/init@v3.30.3
+        uses: github/codeql-action/init@v3.31.6
       - name: 🚀 Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@v3.30.3
+        uses: github/codeql-action/analyze@v3.31.6

{python_bsblan-3.1.1 → python_bsblan-3.1.3}/.github/workflows/labels.yaml

@@ -16,7 +16,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: ⤵️ Check out code from GitHub
-        uses: actions/checkout@v5.0.0
+        uses: actions/checkout@v5.0.1
       - name: 🚀 Run Label Syncer
         uses: micnncim/action-label-syncer@v1.3.0
         env:

{python_bsblan-3.1.1 → python_bsblan-3.1.3}/.github/workflows/linting.yaml

@@ -8,7 +8,7 @@ on:
   workflow_dispatch:
 
 env:
-  DEFAULT_PYTHON: "3.11"
+  DEFAULT_PYTHON: "3.13"
 
 jobs:
   codespell:
@@ -16,7 +16,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: ⤵️ Check out code from GitHub
-        uses: actions/checkout@v5.0.0
+        uses: actions/checkout@v5.0.1
       - name: 🏗 Set up uv
         uses: astral-sh/setup-uv@v6
         with:
@@ -36,7 +36,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: ⤵️ Check out code from GitHub
-        uses: actions/checkout@v5.0.0
+        uses: actions/checkout@v5.0.1
       - name: 🏗 Set up uv
         uses: astral-sh/setup-uv@v6
         with:
@@ -58,7 +58,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: ⤵️ Check out code from GitHub
-        uses: actions/checkout@v5.0.0
+        uses: actions/checkout@v5.0.1
       - name: 🏗 Set up uv
         uses: astral-sh/setup-uv@v6
         with:
@@ -102,7 +102,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: ⤵️ Check out code from GitHub
-        uses: actions/checkout@v5.0.0
+        uses: actions/checkout@v5.0.1
       - name: 🏗 Set up uv
         uses: astral-sh/setup-uv@v6
         with:
@@ -122,7 +122,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: ⤵️ Check out code from GitHub
-        uses: actions/checkout@v5.0.0
+        uses: actions/checkout@v5.0.1
       - name: 🏗 Set up uv
         uses: astral-sh/setup-uv@v6
         with:
@@ -142,7 +142,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: ⤵️ Check out code from GitHub
-        uses: actions/checkout@v5.0.0
+        uses: actions/checkout@v5.0.1
       - name: 🏗 Set up uv
         uses: astral-sh/setup-uv@v6
         with:

{python_bsblan-3.1.1 → python_bsblan-3.1.3}/.github/workflows/release.yaml

@@ -8,7 +8,7 @@ on:
       - published
 
 env:
-  DEFAULT_PYTHON: "3.11"
+  DEFAULT_PYTHON: "3.13"
 
 jobs:
   release:
@@ -22,7 +22,7 @@ jobs:
       id-token: write
     steps:
       - name: ⤵️ Check out code from GitHub
-        uses: actions/checkout@v5.0.0
+        uses: actions/checkout@v5.0.1
       - name: 🏗 Set up uv
         uses: astral-sh/setup-uv@v6
         with:
@@ -48,7 +48,7 @@ jobs:
           verbose: true
           print-hash: true
       - name: ✍️ Sign published artifacts
-        uses: sigstore/gh-action-sigstore-python@v3.0.1
+        uses: sigstore/gh-action-sigstore-python@v3.1.0
         with:
           inputs: ./dist/*.tar.gz ./dist/*.whl
           release-signing-artifacts: false

{python_bsblan-3.1.1 → python_bsblan-3.1.3}/.github/workflows/tests.yaml

@@ -8,7 +8,7 @@ on:
   workflow_dispatch:
 
 env:
-  DEFAULT_PYTHON: "3.11"
+  DEFAULT_PYTHON: "3.13"
 
 jobs:
   pytest:
@@ -16,10 +16,10 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python: ["3.11", "3.12"]
+        python: ["3.12", "3.13", "3.14"]
     steps:
       - name: ⤵️ Check out code from GitHub
-        uses: actions/checkout@v5.0.0
+        uses: actions/checkout@v5.0.1
       - name: 🏗 Set up uv
         uses: astral-sh/setup-uv@v6
         with:
@@ -45,7 +45,7 @@ jobs:
     needs: pytest
     steps:
       - name: ⤵️ Check out code from GitHub
-        uses: actions/checkout@v5.0.0
+        uses: actions/checkout@v5.0.1
         with:
           fetch-depth: 0
       - name: ⬇️ Download coverage data

{python_bsblan-3.1.1 → python_bsblan-3.1.3}/.github/workflows/typing.yaml

@@ -8,7 +8,7 @@ on:
   workflow_dispatch:
 
 env:
-  DEFAULT_PYTHON: "3.11"
+  DEFAULT_PYTHON: "3.13"
 
 jobs:
   mypy:
@@ -16,7 +16,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: ⤵️ Check out code from GitHub
-        uses: actions/checkout@v5.0.0
+        uses: actions/checkout@v5.0.1
       - name: 🏗 Set up uv
         uses: astral-sh/setup-uv@v6
         with:

python_bsblan-3.1.3/.nvmrc

@@ -0,0 +1 @@
+22.21.1

python_bsblan-3.1.3/AGENTS.md

@@ -0,0 +1 @@
+.github/copilot-instructions.md

python_bsblan-3.1.3/CLAUDE.md

@@ -0,0 +1 @@
+.github/copilot-instructions.md

{python_bsblan-3.1.1 → python_bsblan-3.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-bsblan
-Version: 3.1.1
+Version: 3.1.3
 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
@@ -17,10 +17,11 @@ Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Natural Language :: English
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Python: >=3.11
+Requires-Python: >=3.12
 Requires-Dist: aiohttp>=3.8.1
 Requires-Dist: backoff>=2.2.1
 Requires-Dist: mashumaro>=3.13.1

{python_bsblan-3.1.1 → python_bsblan-3.1.3}/examples/control.py

@@ -26,6 +26,7 @@ from bsblan import (
     HotWaterState,
     Info,
     Sensor,
+    SetHotWaterParam,
     State,
     StaticState,
 )
@@ -199,10 +200,10 @@ async def print_hot_water_config(hot_water_config: HotWaterConfig) -> None:
             hot_water_config.legionella_function, "desc", "N/A"
         ),
         "Legionella Setpoint": await get_attribute(
-            hot_water_config.legionella_setpoint, "value", "N/A"
+            hot_water_config.legionella_function_setpoint, "value", "N/A"
         ),
         "Legionella Periodicity": await get_attribute(
-            hot_water_config.legionella_periodicity, "value", "N/A"
+            hot_water_config.legionella_function_periodicity, "value", "N/A"
         ),
         "Circulation Pump Release": await get_attribute(
             hot_water_config.dhw_circulation_pump_release, "desc", "N/A"
@@ -271,9 +272,9 @@ async def main() -> None:
         print("\nSetting temperature to 18°C")
         await bsblan.thermostat(target_temperature="18")
 
-        # Set HVAC mode
+        # 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="heat")
+        await bsblan.thermostat(hvac_mode=3)  # 3 = heat
 
         # Get and print sensor information
         sensor: Sensor = await bsblan.sensor()
@@ -316,7 +317,7 @@ async def main() -> None:
         dhw_programs = DHWTimeSwitchPrograms(
             monday="13:00-14:00 ##:##-##:## ##:##-##:##"
         )
-        await bsblan.set_hot_water(dhw_time_programs=dhw_programs)
+        await bsblan.set_hot_water(SetHotWaterParam(dhw_time_programs=dhw_programs))
 
         # Example: Set device time
         print("\nSetting device time to current system time")

{python_bsblan-3.1.1 → python_bsblan-3.1.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-bsblan"
-version = "3.1.1"
+version = "3.1.3"
 description = "Asynchronous Python client for BSBLAN API"
 authors = [
     {name = "Willem-Jan van Rootselaar", email = "liudgervr@gmail.com"}
@@ -17,12 +17,13 @@ classifiers = [
   "Framework :: AsyncIO",
   "Intended Audience :: Developers",
   "Natural Language :: English",
-  "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
   "Programming Language :: Python :: 3",
   "Topic :: Software Development :: Libraries :: Python Modules",
 ]
-requires-python = ">=3.11"
+requires-python = ">=3.12"
 dependencies = [
     "aiohttp>=3.8.1",
     "yarl>=1.7.2",
@@ -176,28 +177,28 @@ build-backend = "hatchling.build"
 [dependency-groups]
 dev = [
     "aresponses==3.0.0",
-    "bandit==1.8.6",
+    "bandit==1.9.2",
     "black==25.11.0",
     "blacken-docs==1.20.0",
     "codespell==2.4.1",
     "covdefaults==2.3.0",
-    "coverage==7.10.6",
+    "coverage==7.12.0",
     "darglint==1.8.1",
     "flake8==7.3.0",
     "flake8-simplify==0.22.0",
     # hatch is required to support type hinting and proper packaging of the py.typed file.
     "hatch>=1.14.1",
-    "isort==6.0.1",
+    "isort==6.1.0",
     "mypy==1.18.2",
-    "pre-commit==4.3.0",
+    "pre-commit==4.5.0",
     "pre-commit-hooks==6.0.0",
     "pylint==3.3.9",
     "pytest>=8.3.5",
     "pytest-asyncio==1.3.0",
     "pytest-cov==7.0.0",
-    "pyupgrade==3.20.0",
-    "ruff==0.14.4",
-    "safety==3.6.1",
+    "pyupgrade==3.21.2",
+    "ruff==0.14.6",
+    "safety==3.7.0",
     "vulture==2.14",
     "yamllint==1.37.1",
 ]

{python_bsblan-3.1.1 → python_bsblan-3.1.3}/src/bsblan/__init__.py

@@ -3,16 +3,20 @@
 from .bsblan import BSBLAN, BSBLANConfig
 from .exceptions import BSBLANAuthError, BSBLANConnectionError, BSBLANError
 from .models import (
+    DaySchedule,
     Device,
     DeviceTime,
+    DHWSchedule,
     DHWTimeSwitchPrograms,
     HotWaterConfig,
     HotWaterSchedule,
     HotWaterState,
     Info,
     Sensor,
+    SetHotWaterParam,
     State,
     StaticState,
+    TimeSlot,
 )
 
 __all__ = [
@@ -21,7 +25,9 @@ __all__ = [
     "BSBLANConfig",
     "BSBLANConnectionError",
     "BSBLANError",
+    "DHWSchedule",
     "DHWTimeSwitchPrograms",
+    "DaySchedule",
     "Device",
     "DeviceTime",
     "HotWaterConfig",
@@ -29,6 +35,8 @@ __all__ = [
     "HotWaterState",
     "Info",
     "Sensor",
+    "SetHotWaterParam",
     "State",
     "StaticState",
+    "TimeSlot",
 ]