python-bsblan 3.1.6__tar.gz → 4.0.0__tar.gz

{python_bsblan-3.1.6 → python_bsblan-4.0.0}/.github/copilot-instructions.md

@@ -111,6 +111,21 @@ Parameters are organized into polling categories based on how frequently they ch
 - Device identification
 - Min/max temperature limits
 
+## Hot Water Parameter Groups
+
+Hot water parameters are split into groups for granular lazy loading:
+
+| Group | Params | Method | Use Case |
+|-------|--------|--------|----------|
+| essential | 5 | `hot_water_state()` | Frequent polling |
+| config | 16 | `hot_water_config()` | Advanced settings |
+| schedule | 8 | `hot_water_schedule()` | Time programs |
+
+Defined in `constants.py`:
+- `HOT_WATER_ESSENTIAL_PARAMS` - operating_mode, nominal_setpoint, etc.
+- `HOT_WATER_CONFIG_PARAMS` - legionella settings, eco mode, etc.
+- `HOT_WATER_SCHEDULE_PARAMS` - daily time programs
+
 ## Data Models
 
 ### Model Pattern
@@ -143,6 +158,39 @@ async with BSBLAN(host="192.168.1.100") as client:
     await client.set_hot_water(nominal_setpoint=55.0)
 ```
 
+### Lazy Loading Architecture
+The library uses lazy loading for optimal performance:
+- **Initialization**: Only fetches firmware version (fast startup)
+- **Section validation**: Deferred until section is first accessed
+- **Hot water granular loading**: Each method validates only its param group
+- **Race condition prevention**: Per-section/group asyncio locks
+
+```python
+# Initialize() is fast - only fetches firmware
+await client.initialize()  # ~0.02s
+
+# Section validated on first access
+await client.state()  # Validates heating section on first call
+
+# Hot water methods validate only their param groups:
+await client.hot_water_state()    # 5 essential params only
+await client.hot_water_config()   # 16 config params only
+await client.hot_water_schedule() # 8 schedule params only
+```
+
+### Concurrency & Locking
+The library uses asyncio locks to prevent race conditions during lazy loading:
+- `_section_locks`: Per-section locks (heating, sensor, etc.)
+- `_hot_water_group_locks`: Per-group locks (essential, config, schedule)
+
+Double-checked locking pattern:
+1. Fast path: Check if validated (no lock)
+2. Acquire lock for specific section/group
+3. Double-check after acquiring lock
+4. Perform validation inside the lock
+
+This prevents duplicate network requests when concurrent calls access the same section before validation completes.
+
 ### Error Handling
 - Use `BSBLANError` for general errors
 - Use `BSBLANConnectionError` for connection issues

python_bsblan-4.0.0/.github/prompts/add-parameter.prompt.md

@@ -0,0 +1,32 @@
+---
+agent: agent
+description: Add a new BSB-LAN parameter to the library
+---
+
+# Add BSB-LAN Parameter
+
+Add a new parameter to the python-bsblan library following the established patterns.
+
+## Required Information
+
+- Parameter ID (numeric, e.g., "1645")
+- Parameter name (snake_case, e.g., "legionella_function_setpoint")
+- Category: state (fast poll), config (slow poll), or static
+- Is it settable? (yes/no)
+- Data type (float, int, string, enum)
+
+## Files to Modify
+
+1. `src/bsblan/constants.py` - Add parameter ID mapping
+2. `src/bsblan/models.py` - Add field to appropriate model
+3. `src/bsblan/bsblan.py` - Add to setter method if settable
+4. `tests/test_*.py` - Add tests for the new parameter
+
+## Validation
+
+After changes, run:
+```bash
+uv run pre-commit run --all-files
+```
+
+Coverage must be 95%+ total and 100% for new code.

python_bsblan-4.0.0/.github/prompts/code-review.prompt.md

@@ -0,0 +1,40 @@
+---
+agent: agent
+description: Review code changes for python-bsblan library
+---
+
+# Code Review Checklist
+
+Review the changes against the python-bsblan coding standards.
+
+## Checklist
+
+### Code Quality
+- [ ] Type hints on all functions
+- [ ] Docstrings on public methods
+- [ ] Line length under 88 characters
+- [ ] Consistent parameter naming (snake_case)
+
+### Testing
+- [ ] Tests added for new functionality
+- [ ] Test coverage 95%+ total
+- [ ] Patch coverage 100%
+
+### Patterns
+- [ ] Uses `mashumaro` for JSON serialization
+- [ ] Uses `aiohttp` for async HTTP
+- [ ] Follows existing parameter naming conventions
+- [ ] Error handling uses custom exceptions (`BSBLANError`, `BSBLANConnectionError`)
+
+### Pre-commit
+- [ ] Ruff passes (linting + formatting)
+- [ ] MyPy passes (type checking)
+- [ ] Pylint passes (code analysis)
+- [ ] Pytest passes (tests)
+
+## Run Validation
+
+```bash
+uv run pre-commit run --all-files
+uv run pytest --cov=src/bsblan --cov-report=term-missing
+```

python_bsblan-4.0.0/.github/skills/bsblan-parameters/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: bsblan-parameters
+description: Add new BSB-LAN parameters to the python-bsblan library. Use this skill when adding parameter IDs, updating models, or extending the API to support new heating controller parameters.
+---
+
+# Adding BSB-LAN Parameters
+
+This skill guides you through adding new parameters to the python-bsblan library.
+
+## Parameter Naming Conventions
+
+- Use `snake_case` for all parameter names
+- Group related parameters with common prefixes
+- Legionella-related parameters use `legionella_function_*` prefix
+- DHW (Domestic Hot Water) parameters use `dhw_*` prefix
+
+## Steps to Add a New Parameter
+
+### 1. Add to `constants.py`
+
+Add the parameter ID mapping:
+
+```python
+BASE_HOT_WATER_PARAMS: Final[dict[str, str]] = {
+    "1645": "legionella_function_setpoint",  # Parameter ID: name
+}
+```
+
+### 2. Add to Model in `models.py`
+
+Add the field to the appropriate dataclass:
+
+```python
+@dataclass
+class HotWaterConfig(DataClassORJSONMixin):
+    legionella_function_setpoint: ParameterValue | None = None
+```
+
+### 3. Update Method in `bsblan.py` (if settable)
+
+Add parameter to the method signature:
+
+```python
+async def set_hot_water(
+    self,
+    legionella_function_setpoint: float | None = None,
+) -> None:
+```
+
+### 4. Add Tests
+
+Create tests in `tests/test_*.py`:
+
+```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"},
+    )
+```
+
+## Polling Categories
+
+Parameters are organized by update frequency:
+
+- **Fast Poll (State)**: Current temperatures, HVAC action/state, pump states
+- **Slow Poll (Config)**: Operating modes, setpoints, legionella settings, time programs
+- **Static**: Device identification, min/max temperature limits
+
+## Hot Water Parameter Groups
+
+Hot water parameters use granular lazy loading. When adding a new hot water param, add it to the appropriate group in `constants.py`:
+
+| Group                | Constant                      | Method                 |
+| -------------------- | ----------------------------- | ---------------------- |
+| Essential (5 params) | `HOT_WATER_ESSENTIAL_PARAMS`  | `hot_water_state()`    |
+| Config (16 params)   | `HOT_WATER_CONFIG_PARAMS`     | `hot_water_config()`   |
+| Schedule (8 params)  | `HOT_WATER_SCHEDULE_PARAMS`   | `hot_water_schedule()` |
+
+```python
+# In constants.py - add to appropriate group set:
+HOT_WATER_ESSENTIAL_PARAMS: Final[set[str]] = {"1600", "1610", ...}
+HOT_WATER_CONFIG_PARAMS: Final[set[str]] = {"1601", "1614", ...}
+```
+
+## Concurrency Safety
+
+The library uses asyncio locks to prevent race conditions:
+
+- `_section_locks`: Per-section locks for lazy loading
+- `_hot_water_group_locks`: Per-group locks for hot water validation
+
+When adding new sections or groups, the lock is created automatically on first access.
+
+## Validation
+
+Always run after changes:
+
+```bash
+uv run pre-commit run --all-files
+uv run pytest --cov=src/bsblan --cov-report=term-missing
+```
+
+**Coverage requirements**: 95%+ total, 100% patch coverage.

python_bsblan-4.0.0/.github/skills/bsblan-testing/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: bsblan-testing
+description: Write and run tests for the python-bsblan library. Use this skill when creating unit tests, working with fixtures, or ensuring code coverage requirements are met.
+---
+
+# Testing python-bsblan
+
+This skill guides you through testing practices for the python-bsblan library.
+
+## Test Structure
+
+Tests are located in `tests/` and use pytest with async support.
+
+### Basic Test Pattern
+
+```python
+import pytest
+from bsblan import BSBLAN
+
+@pytest.mark.asyncio
+async def test_feature_name(mock_bsblan: BSBLAN) -> None:
+    """Test description."""
+    # Arrange
+    expected_value = "expected"
+
+    # Act
+    result = await mock_bsblan.some_method()
+
+    # Assert
+    assert result == expected_value
+```
+
+### Using Fixtures
+
+Test fixtures (JSON responses) are in `tests/fixtures/`. Common fixtures:
+
+- `device.json` - Device information
+- `state.json` - Current state
+- `hot_water_state.json` - Hot water state
+- `sensor.json` - Sensor readings
+
+Load fixtures using the `load_fixture` helper from `conftest.py`.
+
+## Coverage Requirements
+
+- **Total coverage**: 95%+ required
+- **Patch coverage**: 100% required (all new/modified code must be tested)
+
+Check coverage:
+
+```bash
+uv run pytest --cov=src/bsblan --cov-report=term-missing
+```
+
+## Running Tests
+
+```bash
+# Run all tests
+uv run pytest
+
+# Run specific test file
+uv run pytest tests/test_bsblan.py
+
+# Run with verbose output
+uv run pytest -v
+
+# Run specific test
+uv run pytest tests/test_bsblan.py::test_function_name
+```
+
+## Pre-commit Hooks
+
+Always run before committing:
+
+```bash
+uv run pre-commit run --all-files
+```
+
+This runs:
+
+- **Ruff**: Linting and formatting (88 char line limit)
+- **MyPy**: Static type checking
+- **Pylint**: Code analysis
+- **Pytest**: Test execution with coverage
+
+## Mock Patterns
+
+For API calls, use `mock_bsblan` fixture and verify calls:
+
+```python
+mock_bsblan._request.assert_awaited_with(
+    base_path="/JS",
+    data={"Parameter": "1610", "Value": "60.0", "Type": "1"},
+)
+```
+
+## Testing Lazy Loading
+
+When testing hot water methods, mark param groups as validated to skip network calls:
+
+```python
+@pytest.mark.asyncio
+async def test_hot_water_no_params_error(monkeypatch: Any) -> None:
+    """Test error when no parameters available."""
+    bsblan = BSBLAN(config, session=session)
+
+    # Set empty cache and mark group as validated
+    bsblan.set_hot_water_cache({})
+    bsblan._validated_hot_water_groups.add("essential")  # Skip validation
+
+    with pytest.raises(BSBLANError, match="No essential hot water"):
+        await bsblan.hot_water_state()
+```
+
+For full integration tests with mocked responses:
+
+```python
+# Mark group as validated to use cached params
+bsblan._validated_hot_water_groups.add("config")
+bsblan.set_hot_water_cache({"1601": "eco_mode_selection", ...})
+```
+
+## Testing Concurrent Access
+
+The library uses asyncio locks for race condition prevention. When testing:
+
+- Locks are created per-section/group automatically
+- Access `_section_locks` and `_hot_water_group_locks` dicts if needed
+- The double-checked locking pattern prevents duplicate validations
+
+```python
+# Locks are stored in these dictionaries:
+bsblan._section_locks  # {"heating": Lock(), "sensor": Lock(), ...}
+bsblan._hot_water_group_locks  # {"essential": Lock(), ...}
+```

{python_bsblan-3.1.6 → python_bsblan-4.0.0}/.github/workflows/codeql.yaml

@@ -19,6 +19,6 @@ jobs:
       - name: ⤵️ Check out code from GitHub
         uses: actions/checkout@v6.0.1
       - name: 🏗 Initialize CodeQL
-        uses: github/codeql-action/init@v3.31.9
+        uses: github/codeql-action/init@v4.31.9
       - name: 🚀 Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@v3.31.9
+        uses: github/codeql-action/analyze@v4.31.9

python_bsblan-4.0.0/.github/workflows/release-drafter.yaml

@@ -0,0 +1,37 @@
+---
+name: Release Drafter
+
+# yamllint disable-line rule:truthy
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+    inputs:
+      prerelease:
+        description: "Create a pre-release (beta)"
+        required: false
+        type: boolean
+        default: false
+      prerelease_identifier:
+        description: "Pre-release identifier"
+        required: false
+        type: choice
+        default: "beta"
+        options:
+          - beta
+          - alpha
+          - rc
+
+jobs:
+  update_release_draft:
+    name: ✏️ Draft release
+    runs-on: ubuntu-latest
+    steps:
+      - name: 🚀 Run Release Drafter
+        uses: release-drafter/release-drafter@v6.1.0
+        with:
+          prerelease: ${{ github.event.inputs.prerelease == 'true' }}
+          prerelease-identifier: ${{ github.event.inputs.prerelease_identifier }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

{python_bsblan-3.1.6 → python_bsblan-4.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-bsblan
-Version: 3.1.6
+Version: 4.0.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
@@ -10,6 +10,7 @@ Project-URL: Changelog, https://github.com/liudger/python-bsblan/releases
 Author-email: Willem-Jan van Rootselaar <liudgervr@gmail.com>
 Maintainer-email: Willem-Jan van Rootselaar <liudgervr@gmail.com>
 License: MIT
+License-File: LICENSE.md
 Keywords: api,async,bsblan,client,thermostat
 Classifier: Development Status :: 3 - Alpha
 Classifier: Framework :: AsyncIO

{python_bsblan-3.1.6 → python_bsblan-4.0.0}/examples/control.py

@@ -12,7 +12,6 @@ This three-tier approach reduces API calls by 79% for regular monitoring.
 from __future__ import annotations
 
 import asyncio
-import os
 from datetime import datetime
 from typing import Any
 
@@ -33,6 +32,7 @@ from bsblan import (
     get_hvac_action_category,
 )
 from bsblan.models import DHWTimeSwitchPrograms
+from discovery import get_bsblan_host, get_config_from_env
 
 
 async def get_attribute(
@@ -302,12 +302,19 @@ async def print_hot_water_schedule(hot_water_schedule: HotWaterSchedule) -> None
 
 async def main() -> None:
     """Show example on controlling your BSBLan device."""
+    # Get host from environment variable or mDNS discovery
+    host, port = await get_bsblan_host()
+
+    # Get credentials from environment
+    env_config = get_config_from_env()
+
     # Create a configuration object
     config = BSBLANConfig(
-        host="10.0.2.60",
-        passkey=None,
-        username=os.getenv("BSBLAN_USER"),  # Compliant
-        password=os.getenv("BSBLAN_PASS"),  # Compliant
+        host=host,
+        port=port,
+        passkey=env_config.get("passkey"),  # type: ignore[arg-type]
+        username=env_config.get("username"),  # type: ignore[arg-type]
+        password=env_config.get("password"),  # type: ignore[arg-type]
     )
 
     # Initialize BSBLAN with the configuration object