python-bsblan 6.0.1__tar.gz → 6.1.1__tar.gz

python_bsblan-6.1.1/.github/agents/security-reviewer.agent.md

@@ -0,0 +1,32 @@
+---
+description: "Use when you need a security review, threat modeling, vulnerability triage, secrets exposure checks, auth/session risk analysis, input validation review, dependency risk review, or secure coding feedback."
+name: "Security Reviewer"
+tools: [read, search]
+argument-hint: "Provide scope (files, PR, or feature), threat context, and any known attack surface."
+---
+You are a specialist security code reviewer. Your job is to find exploitable risks and provide precise, actionable remediation guidance.
+
+## Constraints
+- DO NOT refactor for style or performance unless it directly affects security.
+- DO NOT propose broad rewrites when a targeted fix is sufficient.
+- DO NOT claim an issue without explaining exploitability, impact, and preconditions.
+- ONLY report findings that are security-relevant or materially increase security risk.
+
+## Approach
+1. Map attack surface first: inputs, trust boundaries, secrets, authn/authz, network calls, file/system access, and third-party dependencies.
+2. Prioritize exploitability over code smell; assess realistic attacker paths and blast radius.
+3. Verify mitigations already present to avoid false positives.
+4. Provide concrete fixes with smallest safe change and validation steps.
+
+## Output Format
+1. Findings (ordered by severity: critical, high, medium, low)
+- Title
+- Severity
+- Location (file and line)
+- Why this is vulnerable
+- Exploit scenario
+- Recommended fix
+2. Open questions or assumptions
+3. Residual risk and security test gaps
+
+If no findings are discovered, explicitly state that and list residual risks or testing gaps.

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

@@ -0,0 +1,7 @@
+# Canonical Instructions
+
+The canonical instruction file for this repository is:
+
+- `AGENTS.md`
+
+Keep this file as a lightweight compatibility pointer to avoid duplicated guidance.

python_bsblan-6.1.1/.github/hooks/run-validation-after-edits.json

@@ -0,0 +1,11 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "type": "command",
+        "command": "./.github/hooks/run_validation_after_edits.sh",
+        "timeout": 1800
+      }
+    ]
+  }
+}

python_bsblan-6.1.1/.github/hooks/run_validation_after_edits.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+payload="$(cat)"
+
+should_run="$(HOOK_PAYLOAD="$payload" python3 - <<'PY'
+import json
+import os
+import sys
+
+edit_tool_tokens = {
+    "edit",
+    "write",
+    "multi_edit",
+    "multiedit",
+    "apply_patch",
+    "create_file",
+    "edit_notebook_file",
+    "create_new_jupyter_notebook",
+    "mcp_github_create_or_update_file",
+    "mcp_io_github_git_create_or_update_file",
+}
+
+def walk(value):
+    if isinstance(value, dict):
+        for key, item in value.items():
+            yield str(key)
+            yield from walk(item)
+    elif isinstance(value, list):
+        for item in value:
+            yield from walk(item)
+    elif isinstance(value, str):
+        yield value
+
+raw = os.environ.get("HOOK_PAYLOAD", "").strip()
+if not raw:
+    print("skip")
+    raise SystemExit(0)
+
+try:
+    data = json.loads(raw)
+except json.JSONDecodeError:
+    print("skip")
+    raise SystemExit(0)
+
+haystack = "\n".join(s.lower() for s in walk(data))
+if any(token in haystack for token in edit_tool_tokens):
+    print("run")
+else:
+    print("skip")
+PY
+)"
+
+if [[ "$should_run" != "run" ]]; then
+    exit 0
+fi
+
+echo "[hook] File edit detected. Running validation commands..."
+
+echo "[hook] Running tests"
+if ! uv run pytest --no-cov; then
+    echo "[hook] Tests failed"
+    exit 2
+fi
+
+echo "[hook] Running prek"
+if ! uv run prek run --all-files; then
+    echo "[hook] Prek failed"
+    exit 2
+fi
+
+echo "[hook] Validation passed"

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

@@ -0,0 +1,65 @@
+---
+name: Code Review
+agent: agent
+description: Review python-bsblan changes with findings first and repo quality gates
+argument-hint: "Scope to review (staged changes, PR #, or file paths)"
+---
+
+# Code Review
+
+Review the requested scope for regressions, correctness issues, and missing
+tests.
+
+Prioritize findings over summaries and order findings by severity.
+Use this output format:
+
+1. Findings
+- Severity (`high`, `medium`, `low`), location, and impact.
+- Include precise file references and actionable fixes.
+
+2. Open Questions / Assumptions
+- Unknowns that block confidence in the review.
+
+3. Change Summary
+- Brief recap only after findings.
+
+Reference these standards while reviewing:
+- [CONTRIBUTING](../CONTRIBUTING.md)
+- [Copilot instructions](../copilot-instructions.md)
+
+## Review Checks
+
+### 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
+- [ ] Total coverage remains 95%+
+- [ ] Patch coverage for changed code is 100%
+
+### Patterns
+- [ ] Response models use `pydantic` `BaseModel`
+- [ ] Set-parameter models use `@dataclass`
+- [ ] Uses `aiohttp` for async HTTP
+- [ ] Follows existing parameter naming conventions
+- [ ] Error handling uses custom exceptions (`BSBLANError`,
+	  `BSBLANConnectionError`)
+
+### Prek
+- [ ] Ruff passes (linting + formatting)
+- [ ] ty passes (type checking)
+- [ ] Pylint passes (code analysis)
+- [ ] Pytest passes (tests)
+
+## Validation Commands
+
+```bash
+uv run prek run --all-files
+uv run pytest --cov=src/bsblan --cov-report=term-missing
+```
+
+If no findings are discovered, explicitly say so and list any residual testing
+gaps.

{python_bsblan-6.0.1 → python_bsblan-6.1.1}/.github/skills/bsblan-testing/SKILL.md

@@ -39,7 +39,16 @@ Test fixtures (JSON responses) are in `tests/fixtures/`. Common fixtures:
 - `hot_water_state.json` - Hot water state
 - `sensor.json` - Sensor readings
 
-Load fixtures using the `load_fixture` helper from `conftest.py`.
+Load fixtures using `load_fixture(filename: str) -> str` from `tests/__init__.py`.
+
+```python
+import json
+
+from tests import load_fixture
+
+raw = load_fixture("device.json")
+data = json.loads(raw)  # parsed dict[str, Any]
+```
 
 ## Coverage Requirements
 
@@ -84,6 +93,8 @@ CI enforces:
 - Patch coverage = 100% (Codecov checks new/modified lines)
 
 If CI fails with coverage issues, check the Codecov report in the PR for uncovered lines.
+If a line is genuinely untestable (for example defensive guards), mark it with
+`# pragma: no cover` and justify that choice in the PR description.
 
 ## Running Tests
 
@@ -126,6 +137,41 @@ mock_bsblan._request.assert_awaited_with(
 )
 ```
 
+### Fixture Setup and Registration
+
+Define shared fixtures in `tests/conftest.py` so pytest auto-discovers them.
+Use the `mock_bsblan` pattern for naming and setup:
+
+```python
+@pytest.fixture
+async def mock_bsblan(
+    aresponses: ResponsesMockServer,
+    monkeypatch: Any,
+) -> AsyncGenerator[BSBLAN, Any]:
+    ...
+```
+
+Add new JSON payloads in `tests/fixtures/` with descriptive, snake_case names
+that match the behavior under test.
+
+### Mocking HTTP Response Handling
+
+Use `monkeypatch` with `AsyncMock` to return fixture payloads when testing
+response parsing logic (not only outgoing request arguments):
+
+```python
+import json
+from unittest.mock import AsyncMock
+
+from tests import load_fixture
+
+request_mock = AsyncMock(return_value=json.loads(load_fixture("state.json")))
+monkeypatch.setattr(bsblan, "_request", request_mock)
+
+state = await bsblan.state()
+assert state.current_temperature is not None
+```
+
 ## Testing Lazy Loading
 
 When testing hot water methods, mark param groups as validated to skip network calls:

python_bsblan-6.1.1/.github/skills/feature-doc-updates/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: feature-doc-updates
+description: Ensure README and documentation are updated when adding features in python-bsblan. Use when implementing new behavior, parameters, API surface changes, or user-visible capabilities.
+argument-hint: What feature was added and which files changed?
+---
+
+# Feature Documentation Updates
+
+Use this skill after implementing a feature so user-facing documentation stays accurate.
+
+## When To Use
+
+Use this workflow when a change includes one or more of the following:
+- New public method, model field, parameter, or behavior.
+- Changed defaults, constraints, validation, or supported API versions.
+- New examples, setup steps, or migration considerations.
+- Any change that would alter how users call or understand the library.
+
+## Inputs
+
+Collect these inputs before writing docs:
+- Feature summary in one sentence.
+- Files changed in src and tests.
+- Any new parameter IDs and names.
+- Breaking changes or renamed fields.
+- Example usage snippet (if applicable).
+
+## Procedure
+
+1. Classify feature impact.
+- User-facing: update README and docs pages.
+- Internal-only refactor with identical behavior: docs update is optional; add a short rationale in PR notes.
+
+2. Determine documentation targets.
+- Update README when install, quick start, supported behavior, or public API usage changes.
+- Update docs under docs/ when API, constants, models, or behavior explanations changed.
+- Update examples/ when new behavior benefits from a runnable example.
+
+3. Apply documentation updates.
+- README: adjust feature lists, capability notes, usage snippets, and compatibility statements.
+- docs/: update the relevant page in docs/api or docs/getting-started to match the implementation.
+- Keep terms, parameter names, and types identical to source code.
+
+4. Validate consistency with code.
+- Confirm names in docs match constants and model fields exactly.
+- Confirm examples call real methods and use valid arguments.
+- Confirm version notes align with constants version-gating logic.
+
+5. Check deprecations and renames.
+- If a public field/parameter is renamed, document migration guidance.
+- Mention deprecation behavior and replacement names in docs where users will see it.
+
+6. Run quality checks.
+- Run project checks: uv run prek run --all-files
+- If API/docs behavior changed, run tests to verify examples and described behavior are still valid.
+
+7. Final completion check.
+- README updated if user-visible behavior changed.
+- Relevant docs pages updated if API or behavior changed.
+- Any required examples updated.
+- PR description includes a short Docs Updated section listing touched doc files.
+
+## Decision Rules
+
+- Update README is required when feature discovery or onboarding changes.
+- Update docs pages is required when API shape or semantics change.
+- If neither changed, explicitly state why docs were not updated.
+
+## Output Format
+
+When using this skill, produce:
+1. Documentation Impact Summary.
+2. Files updated (README, docs pages, examples).
+3. Any follow-up docs work still needed.
+4. Validation status for checks/tests.

{python_bsblan-6.0.1 → python_bsblan-6.1.1}/.github/workflows/lock.yaml

@@ -18,7 +18,7 @@ jobs:
       pull-requests: write
     steps:
       # yamllint disable-line rule:line-length
-      - uses: dessant/lock-threads@7266a7ce5c1df01b1c6db85bf8cd86c737dadbe7 # v6.0.0
+      - uses: dessant/lock-threads@89ae32b08ed1a541efecbab17912962a5e38981c # v6.0.2
         with:
           github-token: ${{ github.token }}
           issue-inactive-days: "30"

{python_bsblan-6.0.1 → python_bsblan-6.1.1}/.github/workflows/release-drafter.yaml

@@ -36,7 +36,7 @@ jobs:
     steps:
       - name: 🚀 Run Release Drafter
         # yamllint disable-line rule:line-length
-        uses: release-drafter/release-drafter@c2e2804cc59f45f57076a99af580d0fedb697927 # v7.3.0
+        uses: release-drafter/release-drafter@693d20e7c1ce1a81d3a41962f85914253b518449 # v7.3.1
         with:
           prerelease: ${{ github.event.inputs.prerelease == 'true' }}
           prerelease-identifier: ${{ github.event.inputs.prerelease_identifier }}

{python_bsblan-6.0.1 → python_bsblan-6.1.1}/.github/workflows/stale.yaml

@@ -18,7 +18,7 @@ jobs:
       pull-requests: write
     steps:
       - name: 🚀 Run stale
-        uses: actions/stale@b5d41d4e1d5dceea10e7104786b73624c18a190f # v10.2.0
+        uses: actions/stale@eb5cf3af3ac0a1aa4c9c45633dd1ae542a27a899 # v10.3.0
         with:
           repo-token: ${{ secrets.GITHUB_TOKEN }}
           days-before-stale: 30

{python_bsblan-6.0.1 → python_bsblan-6.1.1}/.github/workflows/tests.yaml

@@ -86,14 +86,22 @@ jobs:
         if: env.HAS_CODECOV_TOKEN == 'true'
         uses: codecov/codecov-action@e79a6962e0d4c0c17b229090214935d2e33f8354 # v6.0.1
         with:
+          fail_ci_if_error: true
+          files: coverage.xml
           token: ${{ secrets.CODECOV_TOKEN }}
+      - name: 🚀 Upload coverage report (tokenless)
+        if: env.HAS_CODECOV_TOKEN != 'true' && github.event_name == 'pull_request'
+        uses: codecov/codecov-action@e79a6962e0d4c0c17b229090214935d2e33f8354 # v6.0.1
+        with:
+          fail_ci_if_error: false
+          files: coverage.xml
       - name: ℹ️ Skip Codecov upload (missing token)
-        if: env.HAS_CODECOV_TOKEN != 'true'
+        if: env.HAS_CODECOV_TOKEN != 'true' && github.event_name != 'pull_request'
         run: echo "CODECOV_TOKEN is not set; skipping Codecov upload."
       - name: SonarQube Cloud Scan
         if: env.HAS_SONAR_TOKEN == 'true' && (github.event_name != 'pull_request' || !github.event.pull_request.head.repo.fork)
         # yamllint disable-line rule:line-length
-        uses: SonarSource/sonarqube-scan-action@59db25f34e16620e48ab4bb9e4a5dce155cb5432 # v8.0
+        uses: SonarSource/sonarqube-scan-action@7006c4492b2e0ee0f816d36501671557c97f5995 # v8.1
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}

python_bsblan-6.1.1/.nvmrc

@@ -0,0 +1 @@
+24.16.0

python_bsblan-6.1.1/AGENTS.md

@@ -0,0 +1,98 @@
+# Agent Instructions for python-bsblan
+
+This file is the canonical AI agent guide for this repository.
+
+## Scope
+
+- Applies to the whole workspace.
+- Prefer links to project docs instead of duplicating large policy text.
+
+## Environment
+
+- Python 3.12+
+- uv for Python dependency management
+- Node.js (used by formatting hooks)
+
+Setup commands:
+
+```bash
+npm install
+make setup
+```
+
+## Required Validation
+
+Before finishing changes, run:
+
+```bash
+uv run prek run --all-files
+```
+
+Useful test commands:
+
+```bash
+uv run pytest
+uv run pytest --cov=src/bsblan --cov-report=term-missing
+uv run pytest --no-cov tests/test_file.py -k test_name
+```
+
+Quality gate expectations:
+
+- Keep total coverage at 95%+.
+- Keep patch coverage at 100% for modified lines.
+
+## Code Map
+
+- `src/bsblan/bsblan.py`: main async client (`BSBLAN`), request handling, lazy loading
+- `src/bsblan/constants.py`: parameter IDs and name mappings
+- `src/bsblan/models.py`: response models (`pydantic`) and set-param models (`dataclass`)
+- `src/bsblan/utility.py`: helpers and API validation
+- `src/bsblan/exceptions.py`: library exceptions
+- `tests/conftest.py`: shared pytest fixtures (`mock_bsblan`)
+
+## Project Conventions
+
+- Use type hints on all functions.
+- Keep line length <= 88 chars (Ruff).
+- Response/state models use `pydantic.BaseModel`.
+- Set-parameter payload models use `@dataclass`.
+- Parameter names use `snake_case`.
+- For set operations, send one `/JS` request per populated parameter.
+- Treat API v3 as the supported baseline (do not reintroduce v1-only behavior).
+
+Naming patterns to preserve:
+
+- `legionella_function_*`
+- `dhw_*`
+
+## Parameter Change Workflow
+
+When adding or renaming parameters:
+
+1. Query real-device raw data with `examples/fetch_param.py`.
+2. Update mappings in `src/bsblan/constants.py`.
+3. Update response models in `src/bsblan/models.py`.
+4. If settable, update set dataclass and client setter logic.
+5. Add/adjust tests in `tests/`.
+6. Run full validation (`uv run prek run --all-files`).
+
+If raw responses are incomplete or `data_type` is unknown, prefer
+`EntityInfo[str] | None` and avoid guessing numeric types.
+
+## Common Pitfalls
+
+- Partial pytest runs can fail coverage gates; use `--no-cov` for focused checks.
+- Missing Node.js dependencies can break formatting hooks.
+- Do not confuse comfort/protective/cooling bounds when selecting IDs.
+
+## Source-of-Truth Docs
+
+- Contribution and development process: `.github/CONTRIBUTING.md`
+- User-facing usage and setup: `README.md`
+- Developer docs index: `docs/index.md`
+- Getting started examples: `docs/getting-started.md`
+- API reference: `docs/api/client.md`
+
+## Legacy Compatibility
+
+- `.github/copilot-instructions.md` and `CLAUDE.md` should reference this file.

python_bsblan-6.1.1/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

{python_bsblan-6.0.1 → python_bsblan-6.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-bsblan
-Version: 6.0.1
+Version: 6.1.1
 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-6.0.1 → python_bsblan-6.1.1}/docs/getting-started.md

@@ -63,6 +63,43 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
+## Temperature bounds
+
+For heating comfort setpoint writes (`target_temperature`), `min_temp` maps to
+the reduced setpoint (`712` for circuit 1, `1012` for circuit 2). The protective
+setpoints (`714` and `1014`) are exposed separately and are not used as the
+comfort setpoint lower bound. The upper heating bound is `716` for circuit 1 and
+`1016` for circuit 2 when the device exposes those parameters.
+
+## Cooling setpoint support
+
+Some BSB/LPB controllers expose a cooling comfort setpoint for each heating
+circuit. The client maps BSB-LAN parameter `902` for circuit 1 and `1202` for
+circuit 2 to `target_temperature_high`; the duplicate decimal parameters
+`902.1` and `902.2` are not used.
+
+When available, cooling setpoint validation uses `905`/`1205` (comfort setpoint
+minimum) as the lower bound and `903`/`1203` (room temperature reduced setpoint)
+as the upper bound. Parameters `908` and `1208` are flow setpoints and are not
+used for room setpoint validation.
+
+Cooling support is optional. During section validation, unsupported parameters
+are removed from the active API map, so integrations can detect support by
+checking whether `state.target_temperature_high` is present.
+
+```python
+async with BSBLAN(config) as client:
+    state = await client.state(include=["target_temperature_high"])
+
+    if state.target_temperature_high is not None:
+        print(f"Cooling setpoint: {state.target_temperature_high.value}")
+        await client.thermostat(target_temperature_high="24.0")
+```
+
+BSB-LAN writes one parameter at a time. If an application exposes a heat/cool
+temperature range, write `target_temperature` and `target_temperature_high` with
+separate `thermostat()` calls.
+
 ## PPS bus support
 
 PPS bus devices are detected from the device metadata returned by BSB-LAN. The

{python_bsblan-6.0.1 → python_bsblan-6.1.1}/docs/index.md

@@ -7,8 +7,9 @@ Asynchronous Python client for [BSB-LAN](https://github.com/fredlcore/bsb_lan) d
 - Async/await support using `aiohttp`
 - Read heating state, sensor data, and device information
 - Control thermostat settings and hot water parameters
+- Detect optional cooling setpoints for heat/cool range controls
 - Fully typed with PEP 561 support
-- Automatic API version detection (v1/v3)
+- API v3 parameter support
 - Lazy loading with per-section validation
 
 ## Quick example