Add new exception types for unsupported features and responses

[liudger]

This pull request introduces a new exception taxonomy to the library, allowing consumers to distinguish between permanent unsupported-feature errors and transient malformed-response errors. Two new exception classes are added—BSBLANUnsupportedFeatureError for permanent conditions and BSBLANMalformedResponseError for transient errors—both subclassing the existing BSBLANError to preserve backward compatibility. The changes affect schedule read paths, transport error handling, documentation, and tests.

Exception taxonomy improvements:

• Added BSBLANUnsupportedFeatureError and BSBLANMalformedResponseError as subclasses of BSBLANError in src/bsblan/exceptions.py, with docstrings describing their semantics (permanent vs. transient).
• Updated src/bsblan/__init__.py to import and re-export the new exceptions, and included them in __all__ for top-level package access. [1] [2]

Schedule read path changes (permanent error):

• In src/bsblan/_schedules.py and src/bsblan/_hot_water.py, replaced bare BSBLANError raises with BSBLANUnsupportedFeatureError when schedule parameters are absent, and updated docstrings accordingly. [1] [2] [3] [4] [5] [6]

Transport parse path changes (transient error):

• In src/bsblan/_transport.py, replaced the generic error raise with BSBLANMalformedResponseError for decode/parse failures, and updated docstrings to document the new exception. [1] [2] [3]

Documentation and specification:

• Documented the new exceptions in docs/api/exceptions.md and updated the specification and design documentation to reflect the new taxonomy and requirements. [1] [2] [3] [4] [5]

Testing and validation:

• Added and updated tests to assert the correct exception types are raised in all relevant scenarios, and ensured no regressions in unrelated error handling.

These changes are fully backward compatible: existing except BSBLANError handlers will continue to catch all library exceptions, while consumers can now opt into finer-grained error handling by catching the new exception types.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (1f0a3d6) to head (b12418a).

Additional details and impacted files

@@            Coverage Diff            @@
##              main     #1556   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           14        14           
  Lines         1334      1338    +4     
  Branches       142       143    +1     
=========================================
+ Hits          1334      1338    +4     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

This PR adds a clearer exception taxonomy to python-bsblan so callers can distinguish permanent unsupported-feature failures from transient malformed-response failures, while preserving backward compatibility via BSBLANError subclassing.

Changes:

• Introduces BSBLANUnsupportedFeatureError and BSBLANMalformedResponseError (both subclass BSBLANError) and re-exports them at the top-level package.
• Reclassifies schedule “no params available” cases as unsupported feature errors, and transport JSON decode/parse failures as malformed response errors.
• Updates documentation/spec artifacts and expands tests to assert the new concrete exception types (and that they remain catchable as BSBLANError).

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/bsblan/exceptions.py	Adds the two new exception subclasses with documented permanent/transient semantics.
src/bsblan/__init__.py	Re-exports the new exceptions and adds them to __all__ for public API access.
src/bsblan/_schedules.py	Raises BSBLANUnsupportedFeatureError when heating schedule params can’t be mapped.
src/bsblan/_hot_water.py	Raises BSBLANUnsupportedFeatureError only for the hot-water schedule group when params are absent.
src/bsblan/_transport.py	Raises BSBLANMalformedResponseError when response JSON decoding/parsing fails.
tests/test_heating_schedule.py	Updates schedule “no params” test to assert BSBLANUnsupportedFeatureError (+ still a BSBLANError).
tests/test_hot_water_additional.py	Updates hot-water schedule “no params” test to assert BSBLANUnsupportedFeatureError, and ensures state stays generic.
tests/test_bsblan_edge_cases.py	Updates malformed-response test to assert BSBLANMalformedResponseError (+ still a BSBLANError).
docs/api/exceptions.md	Documents the new exceptions in the public API docs.
openspec/specs/error-classification/spec.md	Adds a spec describing the new error-classification requirements and scenarios.
openspec/changes/archive/2026-07-12-distinguish-schedule-error-types/tasks.md	Archives the implementation task checklist for this change.
openspec/changes/archive/2026-07-12-distinguish-schedule-error-types/specs/error-classification/spec.md	Archives the delta spec content for the change.
openspec/changes/archive/2026-07-12-distinguish-schedule-error-types/proposal.md	Archives the proposal rationale and scope for the taxonomy change.
openspec/changes/archive/2026-07-12-distinguish-schedule-error-types/design.md	Archives the design decisions and trade-offs behind the taxonomy.
openspec/changes/archive/2026-07-12-distinguish-schedule-error-types/.openspec.yaml	Records the archived change metadata.