python-bsblan 6.1.6__tar.gz → 6.1.8__tar.gz

{python_bsblan-6.1.6 → python_bsblan-6.1.8}/.github/workflows/codeql.yaml

@@ -23,10 +23,10 @@ jobs:
       security-events: write
     steps:
       - name: ⤵️ Check out code from GitHub
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
         with:
           persist-credentials: false
       - name: 🏗 Initialize CodeQL
-        uses: github/codeql-action/init@54f647b7e1bb85c95cddabcd46b0c578ec92bc1a # v4.36.3
+        uses: github/codeql-action/init@e4fba868fa4b1b91e1fdab776edc8cfbe6e9fb81 # v4.37.3
       - name: 🚀 Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@54f647b7e1bb85c95cddabcd46b0c578ec92bc1a # v4.36.3
+        uses: github/codeql-action/analyze@e4fba868fa4b1b91e1fdab776edc8cfbe6e9fb81 # v4.37.3

{python_bsblan-6.1.6 → python_bsblan-6.1.8}/.github/workflows/dependency-review.yaml

@@ -13,7 +13,7 @@ jobs:
     steps:
       - name: ⤵️ Check out code from GitHub
         # yamllint disable-line rule:line-length
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
         with:
           persist-credentials: false
       - name: 👀 Dependency review

{python_bsblan-6.1.6 → python_bsblan-6.1.8}/.github/workflows/docs.yaml

@@ -23,11 +23,11 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: ⤵️ Check out code from GitHub
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
         with:
           persist-credentials: false
       - name: 🏗 Set up uv
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
         with:
           enable-cache: true
       - name: 🏗 Set up Python ${{ env.DEFAULT_PYTHON }}

{python_bsblan-6.1.6 → python_bsblan-6.1.8}/.github/workflows/labels.yaml

@@ -21,7 +21,7 @@ jobs:
       issues: write
     steps:
       - name: ⤵️ Check out code from GitHub
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
         with:
           persist-credentials: false
       - name: 🚀 Run Label Syncer

{python_bsblan-6.1.6 → python_bsblan-6.1.8}/.github/workflows/linting.yaml

@@ -21,11 +21,11 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: ⤵️ Check out code from GitHub
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
         with:
           persist-credentials: false
       - name: 🏗 Set up uv
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
         with:
           enable-cache: true
       - name: 🏗 Set up Python ${{ env.DEFAULT_PYTHON }}
@@ -45,11 +45,11 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: ⤵️ Check out code from GitHub
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
         with:
           persist-credentials: false
       - name: 🏗 Set up uv
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
         with:
           enable-cache: true
       - name: 🏗 Set up Python ${{ env.DEFAULT_PYTHON }}
@@ -60,7 +60,7 @@ jobs:
       - name: 🏗 Install Python dependencies
         run: uv sync --dev
       - name: 🏗 Set up Node.js
-        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6.5.0
         with:
           node-version-file: ".nvmrc"
           cache: "npm"

{python_bsblan-6.1.6 → python_bsblan-6.1.8}/.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@4d75298e00d9e34c483e5ff8c68d0ea1c1940c1e # v7.5.1
+        uses: release-drafter/release-drafter@eada3c96a64734dd381cfbda23511034e328ddb0 # v7.6.0
         with:
           prerelease: ${{ github.event.inputs.prerelease == 'true' }}
           prerelease-identifier: ${{ github.event.inputs.prerelease_identifier }}

{python_bsblan-6.1.6 → python_bsblan-6.1.8}/.github/workflows/release.yaml

@@ -25,11 +25,11 @@ jobs:
       id-token: write
     steps:
       - name: ⤵️ Check out code from GitHub
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
         with:
           persist-credentials: false
       - name: 🏗 Set up uv
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
         with:
           enable-cache: false
       - name: 🏗 Set up Python ${{ env.DEFAULT_PYTHON }}
@@ -54,7 +54,7 @@ jobs:
         with:
           subject-path: ./dist/*
       - name: 🚀 Publish to PyPi
-        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0
+        uses: pypa/gh-action-pypi-publish@ba38be9e461d3875417946c167d0b5f3d385a247 # v1.14.1
         with:
           verbose: true
           print-hash: true

{python_bsblan-6.1.6 → python_bsblan-6.1.8}/.github/workflows/scorecard.yml

@@ -34,13 +34,13 @@ jobs:
     steps:
       - name: "Checkout code"
         # yamllint disable-line rule:line-length
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
         with:
           persist-credentials: false
 
       - name: "Run analysis"
         # yamllint disable-line rule:line-length
-        uses: ossf/scorecard-action@4eaacf0543bb3f2c246792bd56e8cdeffafb205a # v2.4.3
+        uses: ossf/scorecard-action@2d1146689b8cda280b9bc96326124645441f03bc # v2.4.4
         with:
           results_file: results.sarif
           results_format: sarif
@@ -66,6 +66,6 @@ jobs:
       # Upload the results to GitHub's code scanning dashboard (optional).
       - name: "Upload to code-scanning"
         # yamllint disable-line rule:line-length
-        uses: github/codeql-action/upload-sarif@54f647b7e1bb85c95cddabcd46b0c578ec92bc1a # v4.36.3
+        uses: github/codeql-action/upload-sarif@e4fba868fa4b1b91e1fdab776edc8cfbe6e9fb81 # v4.37.3
         with:
           sarif_file: results.sarif

{python_bsblan-6.1.6 → python_bsblan-6.1.8}/.github/workflows/stale.yaml

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

{python_bsblan-6.1.6 → python_bsblan-6.1.8}/.github/workflows/tests.yaml

@@ -29,11 +29,11 @@ jobs:
         python: ["3.12", "3.13", "3.14"]
     steps:
       - name: ⤵️ Check out code from GitHub
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
         with:
           persist-credentials: false
       - name: 🏗 Set up uv
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
         with:
           enable-cache: true
       - name: 🏗 Set up Python ${{ matrix.python }}
@@ -61,14 +61,14 @@ jobs:
       pull-requests: read
     steps:
       - name: ⤵️ Check out code from GitHub
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
         with:
           fetch-depth: 0
           persist-credentials: false
       - name: ⬇️ Download coverage data
         uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
       - name: 🏗 Set up uv
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
         with:
           enable-cache: true
       - name: 🏗 Set up Python ${{ env.DEFAULT_PYTHON }}

{python_bsblan-6.1.6 → python_bsblan-6.1.8}/.github/workflows/typing.yaml

@@ -22,12 +22,12 @@ jobs:
     steps:
       - name: ⤵️ Check out code from GitHub
         # yamllint disable-line rule:line-length
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
         with:
           persist-credentials: false
       - name: 🏗 Set up uv
         # yamllint disable-line rule:line-length
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
         with:
           enable-cache: true
       - name: 🏗 Set up Python ${{ env.DEFAULT_PYTHON }}

{python_bsblan-6.1.6 → python_bsblan-6.1.8}/PKG-INFO

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

@@ -13,3 +13,11 @@ Custom exceptions raised by the library.
 ## BSBLANAuthError
 
 ::: bsblan.BSBLANAuthError
+
+## BSBLANUnsupportedFeatureError
+
+::: bsblan.BSBLANUnsupportedFeatureError
+
+## BSBLANMalformedResponseError
+
+::: bsblan.BSBLANMalformedResponseError

python_bsblan-6.1.8/openspec/changes/archive/2026-07-12-distinguish-schedule-error-types/.openspec.yaml

@@ -0,0 +1,3 @@
+---
+schema: spec-driven
+created: 2026-07-12

python_bsblan-6.1.8/openspec/changes/archive/2026-07-12-distinguish-schedule-error-types/design.md

@@ -0,0 +1,101 @@
+## Context
+
+`python-bsblan` currently exposes a single generic `BSBLANError` for a wide
+range of failure modes. Two of them are semantically opposite from a retry
+standpoint:
+
+- **Unsupported schedule** — the device does not expose the requested
+  time-program parameters. In `_schedules.heating_schedule()` this raises
+  `BSBLANError(ErrorMsg.NO_HEATING_SCHEDULE_PARAMS)`, and in
+  `_hot_water._get_filtered_data()` it raises `BSBLANError(error_msg)` for the
+  hot-water schedule group. This is a **permanent** condition.
+- **Malformed response** — the transport cannot decode or JSON-parse the body.
+  In `_transport.request_with_retry()` this is caught from `ValueError` /
+  `UnicodeDecodeError` and re-raised as
+  `BSBLANError(ErrorMsg.INVALID_RESPONSE.format(e))`. This is a **transient**
+  condition.
+
+Because both surface as `BSBLANError`, a downstream integration (Home Assistant)
+cannot decide whether to retry. It must either stop retrying (losing recovery
+from transient malformed responses) or retry forever (uselessly hammering a
+device that will never support a schedule after a write).
+
+The library's own `backoff` decorator only retries `TimeoutError` and
+`aiohttp.ClientError`, so `BSBLANError` is never retried inside the library; the
+retry decision lives in the consumer. The fix is therefore an additive exception
+taxonomy, not a change to the transport retry policy.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Let callers distinguish permanent unsupported-feature failures from transient
+  malformed-response failures by `except` type.
+- Keep the change fully backward compatible with existing `except BSBLANError`
+  handlers.
+- Reuse existing `ErrorMsg` strings; no message wording changes.
+
+**Non-Goals:**
+- Changing the transport-level `backoff` retry policy or which HTTP statuses are
+  retried (`client-retry-policy` is unchanged).
+- Adding automatic retry logic inside the library for schedules.
+- Reclassifying other existing `BSBLANError` raise sites beyond schedule reads
+  and malformed-response parsing.
+
+## Decisions
+
+**Decision: Two new subclasses of `BSBLANError`.**
+Add `BSBLANUnsupportedFeatureError` (permanent) and
+`BSBLANMalformedResponseError` (transient), both subclassing `BSBLANError`.
+Subclassing preserves backward compatibility: any existing `except BSBLANError`
+keeps catching them.
+- *Alternative considered:* a single new error with a `retryable: bool`
+  attribute. Rejected — attribute inspection is less idiomatic than `except`
+  type matching and easier to get wrong at call sites.
+- *Alternative considered:* schedule-specific name (e.g.
+  `BSBLANUnsupportedScheduleError`). Chose the more general
+  `BSBLANUnsupportedFeatureError` because the same permanent semantics apply to
+  both heating and hot-water schedule reads and can extend to other
+  unsupported-parameter cases later.
+
+**Decision: Raise the permanent error at the schedule-read guard sites.**
+Replace the bare `BSBLANError(...)` at
+`_schedules.heating_schedule()` (no mapped data) and the hot-water schedule
+branch in `_hot_water._get_filtered_data()` with
+`BSBLANUnsupportedFeatureError`, keeping the existing `ErrorMsg` text. The
+hot-water helper is shared by state/config/schedule reads, so scope the new
+error to the schedule group only (via `group_name == "schedule"`) to avoid
+reclassifying unrelated state/config failures.
+
+**Decision: Raise the transient error at the transport parse site.**
+In `_transport.request_with_retry()`, replace the
+`raise BSBLANError(msg)` in the `(ValueError, UnicodeDecodeError)` handler with
+`raise BSBLANMalformedResponseError(msg)`, reusing
+`ErrorMsg.INVALID_RESPONSE`.
+
+**Decision: Export the new exceptions from the package.**
+Add both classes to `bsblan.exceptions` and to the package `__all__` /
+re-exports so consumers can import them from the top-level `bsblan` namespace.
+
+## Risks / Trade-offs
+
+- **[Consumers catching the narrow generic message string]** → Mitigation:
+  messages are unchanged; only the concrete type is narrower. Broad
+  `except BSBLANError` still works.
+- **[Over-scoping the hot-water helper]** → Mitigation: gate the new error on the
+  schedule group so state/config reads keep raising the existing generic error
+  and existing tests stay green.
+- **[Missed raise site]** → Mitigation: grep for `NO_HEATING_SCHEDULE_PARAMS`,
+  the hot-water schedule `error_msg`, and `INVALID_RESPONSE` to confirm all
+  targeted sites are updated; add tests asserting the concrete types.
+
+## Migration Plan
+
+Additive, no migration required. Release as a minor version. Consumers may
+optionally add narrower `except BSBLANUnsupportedFeatureError` /
+`except BSBLANMalformedResponseError` handlers; existing code is unaffected.
+
+## Open Questions
+
+- Final class names: `BSBLANUnsupportedFeatureError` vs
+  `BSBLANUnsupportedScheduleError`. Proposed the broader name; confirm during
+  review.

python_bsblan-6.1.8/openspec/changes/archive/2026-07-12-distinguish-schedule-error-types/proposal.md

@@ -0,0 +1,49 @@
+## Why
+
+In python-bsblan 6.1.6 both an *unsupported schedule* (a device that will never
+return the requested time-program parameters) and a *malformed response* (a
+transient decode/parse failure) are surfaced as the same generic `BSBLANError`.
+Downstream integrations such as Home Assistant cannot tell them apart by
+exception type, so they must choose between stopping retries on a transient
+malformed response or retrying an unsupported schedule indefinitely after a
+write. A dedicated exception taxonomy is needed at the library level to make the
+permanent-vs-transient distinction explicit.
+
+## What Changes
+
+- Add a dedicated **permanent** exception `BSBLANUnsupportedFeatureError`
+  (subclass of `BSBLANError`) raised when a device does not expose the requested
+  schedule parameters, so callers know retrying will never succeed.
+- Add a dedicated **transient** exception `BSBLANMalformedResponseError`
+  (subclass of `BSBLANError`) raised when a response body cannot be decoded or
+  parsed as valid JSON, signalling that a retry may succeed.
+- Raise `BSBLANUnsupportedFeatureError` in the heating- and hot-water-schedule
+  read paths where a bare `BSBLANError` is currently raised for absent schedule
+  parameters.
+- Raise `BSBLANMalformedResponseError` in the transport layer where invalid
+  JSON / decode errors are currently wrapped in a bare `BSBLANError`.
+- Both new exceptions subclass `BSBLANError`, so existing `except BSBLANError`
+  handlers keep working (non-breaking).
+
+## Capabilities
+
+### New Capabilities
+- `error-classification`: A library exception taxonomy that distinguishes
+  permanent unsupported-feature failures from transient malformed-response
+  failures, letting callers make correct retry decisions.
+
+### Modified Capabilities
+<!-- No existing spec's requirements change; client-retry-policy behavior is unaffected. -->
+
+## Impact
+
+- `src/bsblan/exceptions.py`: two new exception classes.
+- `src/bsblan/_schedules.py` and `src/bsblan/_hot_water.py`: raise the new
+  unsupported-feature error for absent schedule parameters.
+- `src/bsblan/_transport.py`: raise the new malformed-response error for
+  decode/parse failures.
+- `src/bsblan/constants.py`: no new messages required; existing `ErrorMsg`
+  entries are reused.
+- `tests/`: new coverage asserting the specific exception types are raised.
+- Public API: additive only. Consumers relying on `BSBLANError` are unaffected;
+  consumers can opt into finer-grained handling.

python_bsblan-6.1.8/openspec/changes/archive/2026-07-12-distinguish-schedule-error-types/specs/error-classification/spec.md

@@ -0,0 +1,50 @@
+## ADDED Requirements
+
+### Requirement: Unsupported schedules raise a permanent error
+
+The client SHALL raise `BSBLANUnsupportedFeatureError` (a subclass of
+`BSBLANError`) when a schedule read cannot proceed because the device exposes no
+schedule parameters for the requested feature. This error MUST signal a
+permanent condition so callers know that retrying the same request will never
+succeed.
+
+#### Scenario: Heating schedule parameters absent
+
+- **WHEN** `heating_schedule()` is called for a circuit whose time-program
+  parameters are not present in the device response (no schedule parameters can
+  be mapped)
+- **THEN** the client raises `BSBLANUnsupportedFeatureError`
+- **AND** the raised exception is also an instance of `BSBLANError`
+
+#### Scenario: Hot water schedule parameters absent
+
+- **WHEN** `schedule()` is called on a device that exposes no hot-water
+  time-program parameters after include filtering
+- **THEN** the client raises `BSBLANUnsupportedFeatureError`
+- **AND** the raised exception is also an instance of `BSBLANError`
+
+### Requirement: Malformed responses raise a transient error
+
+The client SHALL raise `BSBLANMalformedResponseError` (a subclass of
+`BSBLANError`) when a device response body cannot be decoded or parsed as valid
+JSON. This error MUST signal a transient condition so callers know that a retry
+may succeed.
+
+#### Scenario: Response body is not valid JSON
+
+- **WHEN** a request receives an HTTP `200` response whose body cannot be parsed
+  as JSON
+- **THEN** the client raises `BSBLANMalformedResponseError`
+- **AND** the raised exception is also an instance of `BSBLANError`
+
+### Requirement: New exceptions preserve backward compatibility
+
+Both `BSBLANUnsupportedFeatureError` and `BSBLANMalformedResponseError` SHALL
+subclass `BSBLANError` so that existing `except BSBLANError` handlers continue to
+catch them without modification.
+
+#### Scenario: Existing broad handler still catches new errors
+
+- **WHEN** code catches `BSBLANError` around a call that raises either
+  `BSBLANUnsupportedFeatureError` or `BSBLANMalformedResponseError`
+- **THEN** the exception is caught by the `BSBLANError` handler

python_bsblan-6.1.8/openspec/changes/archive/2026-07-12-distinguish-schedule-error-types/tasks.md

@@ -0,0 +1,28 @@
+## 1. Exceptions
+
+- [x] 1.1 Add `BSBLANUnsupportedFeatureError(BSBLANError)` to `src/bsblan/exceptions.py` with a docstring describing it as a permanent (non-retryable) condition.
+- [x] 1.2 Add `BSBLANMalformedResponseError(BSBLANError)` to `src/bsblan/exceptions.py` with a docstring describing it as a transient (retryable) condition.
+- [x] 1.3 Import and re-export both new exceptions in `src/bsblan/__init__.py` and add them to `__all__`.
+
+## 2. Schedule read paths (permanent error)
+
+- [x] 2.1 In `src/bsblan/_schedules.py` `heating_schedule()`, raise `BSBLANUnsupportedFeatureError(ErrorMsg.NO_HEATING_SCHEDULE_PARAMS)` when no schedule parameters are mapped (replace the bare `BSBLANError`).
+- [x] 2.2 In `src/bsblan/_hot_water.py` `fetch_data()`, raise `BSBLANUnsupportedFeatureError(error_msg)` when the schedule group (`group_name == "schedule"`) has no filtered params, keeping other groups on the existing generic error.
+- [x] 2.3 Update the `Raises:` docstrings on the affected schedule methods to reference the new exception type.
+
+## 3. Transport parse path (transient error)
+
+- [x] 3.1 In `src/bsblan/_transport.py` `request_with_retry()`, raise `BSBLANMalformedResponseError(msg)` from the `(ValueError, UnicodeDecodeError)` handler (replace the bare `BSBLANError`), reusing `ErrorMsg.INVALID_RESPONSE`.
+- [x] 3.2 Update the `Raises:` docstring on `request_with_retry()` to reference the new exception type.
+
+## 4. Tests
+
+- [x] 4.1 Add a test asserting `heating_schedule()` raises `BSBLANUnsupportedFeatureError` when schedule params are absent, and that it is also a `BSBLANError`.
+- [x] 4.2 Add a test asserting hot-water `schedule()` raises `BSBLANUnsupportedFeatureError` when schedule params are absent.
+- [x] 4.3 Add a test asserting a non-JSON / undecodable response raises `BSBLANMalformedResponseError` and that it is also a `BSBLANError`.
+- [x] 4.4 Verify existing state/config hot-water tests still raise the generic `BSBLANError` (no regression from the group gating).
+
+## 5. Documentation & validation
+
+- [x] 5.1 Document the two new exceptions in `docs/api/exceptions.md`.
+- [x] 5.2 Run `uv run prek run --all-files` and `uv run pytest --cov=src/bsblan --cov-report=term-missing`; ensure total coverage stays >= 95% and patch coverage is 100%.

python_bsblan-6.1.8/openspec/changes/archive/2026-07-16-fix-partial-validation-state/.openspec.yaml

@@ -0,0 +1,3 @@
+---
+schema: spec-driven
+created: 2026-07-16

python_bsblan-6.1.8/openspec/changes/archive/2026-07-16-fix-partial-validation-state/design.md

@@ -0,0 +1,86 @@
+## Context
+
+`SectionValidator` lazily validates device parameter support before a section or
+hot-water group is read. It currently stores completion as a section-wide set in
+`APIValidator` and a group-wide set in `SectionValidator`. An `include` request
+validates only a subset but records that coarse completion state, so a later
+request for different names or all names can skip validation.
+
+The resulting configuration has not established whether every requested
+parameter is supported. For normal sections, an unvalidated parameter can remain
+in the configuration and later produce a strict response-mapping failure. For
+hot water, the cache contains only the first subset and later reads silently use
+that incomplete cache.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Record lazy-validation coverage by parameter ID for sections and hot-water
+  groups.
+- Revalidate only the parameter IDs required by a later request when they have
+  not already been covered.
+- Retain the existing public method signatures, include-filter validation, and
+  per-section/group locking model.
+- Add regression tests for sequential filtered and unfiltered access.
+
+**Non-Goals:**
+
+- Change the public `include` API or make it accept parameter IDs.
+- Alter device-response parsing, model serialization, or unsupported-parameter
+  rules.
+- Retry or cache failed validation requests.
+
+## Decisions
+
+### Track covered parameter IDs per validation owner
+
+`APIValidator` will maintain a mapping from section name to the set of parameter
+IDs whose support was checked. `SectionValidator` will maintain the equivalent
+mapping for hot-water group names. Completion for a request is determined by
+whether its requested IDs are a subset of that owner’s covered IDs.
+
+Parameter IDs are chosen over parameter names because they are the identifiers
+sent to BSB-LAN and remain unambiguous if a configuration ever aliases a name.
+When a response establishes an ID is unsupported, it is removed from the active
+configuration/cache but remains covered, preventing needless repeated probes.
+
+Alternative considered: avoid persisting any completion after an `include`
+request. This avoids the defect but discards useful knowledge and repeatedly
+validates already checked parameters. Parameter-level coverage keeps lazy
+loading efficient while remaining correct.
+
+### Derive requested IDs before the one-time gate
+
+Each ensure method will first resolve the configured IDs for its section or
+group, applying `include` when present. Its lock’s fast and post-lock checks will
+compare that specific requested-ID set to coverage rather than use a coarse
+section/group marker. A full request resolves all currently configured IDs and
+therefore completes only after each is covered.
+
+An include filter that matches no IDs will not add coverage or mark a group or
+section complete. Existing downstream include validation remains responsible for
+returning the appropriate invalid-include error.
+
+Alternative considered: retain a boolean for full validation plus a separate
+partial set. This duplicates state and makes configuration changes harder to
+reason about; one coverage mapping expresses both cases.
+
+### Preserve locks and recheck coverage after waiting
+
+The existing per-section and per-group locks remain in place. The completion
+predicate will calculate coverage for the current requested IDs both before and
+after lock acquisition. Concurrent calls requesting different subsets therefore
+serialize safely, and the second call still validates its uncovered IDs.
+
+## Risks / Trade-offs
+
+- [Configuration mutation during validation] → Derive the requested IDs from
+  the current configuration at each completion check; removed unsupported IDs
+  no longer need validation.
+- [Stale internal tests inspect completion sets] → Update tests to assert
+  parameter coverage and externally observable request/cache behavior instead
+  of obsolete whole-group completion.
+- [Additional first-read requests] → A later request for previously unrequested
+  parameters necessarily makes one validation request; already covered IDs are
+  not re-requested.

python_bsblan-6.1.8/openspec/changes/archive/2026-07-16-fix-partial-validation-state/proposal.md

@@ -0,0 +1,38 @@
+## Why
+
+Lazy validation currently records a section or hot-water group as fully
+validated after a request filtered with `include`. This can leave unsupported
+parameters in a section or leave the hot-water cache incomplete, causing later
+unfiltered reads to skip necessary validation and return incomplete data or fail
+while mapping a device response.
+
+## What Changes
+
+- Track validation coverage at the parameter level for sections and hot-water
+  groups instead of treating any successful filtered request as complete.
+- Ensure a later request validates parameter names that an earlier `include`
+  request did not cover.
+- Keep validation completion correct when an include filter has no matching
+  parameters.
+- Add focused regression coverage for filtered-then-unfiltered and
+  differently-filtered reads.
+
+## Capabilities
+
+### New Capabilities
+
+- `lazy-validation-completeness`: Lazy section and hot-water validation covers
+  every parameter required by each request before that request uses the cached
+  configuration.
+
+### Modified Capabilities
+
+- None.
+
+## Impact
+
+- Affected code: `src/bsblan/_validation.py`, `src/bsblan/utility.py`, and the
+  lazy section and hot-water read paths that use their validation state.
+- Affected tests: validation, include-filter, and hot-water regression tests.
+- Public API: no signature changes; `include` calls may perform an additional
+  validation request when they need parameters not checked by a prior call.