quilt-hp-python 0.1.4__tar.gz → 0.2.1__tar.gz

quilt_hp_python-0.2.1/.github/copilot-instructions.md

@@ -0,0 +1,145 @@
+# Copilot Instructions
+
+## What this library is
+
+`quilt-hp-python` is an async Python client library for [Quilt](https://www.quilt.com/) mini-split HVAC systems. It communicates with the Quilt cloud API over gRPC to control and monitor Quilt installations.
+
+The main entry point is `QuiltClient`. Consumers use it to:
+
+- **Authenticate** — email OTP via AWS Cognito; tokens are cached automatically.
+- **Read state** — fetch a full `SystemSnapshot` containing spaces (rooms), indoor units (wall-mounted heads), outdoor units, controllers, sensors, comfort presets, and schedules.
+- **Control devices** — set HVAC mode, temperature setpoints, fan speed, louver position, comfort preset, boost mode, schedules, and LED settings on spaces and indoor units.
+- **Stream real-time updates** — subscribe to the Quilt `NotifierService` bidirectional gRPC stream and receive push notifications within milliseconds of any state change.
+
+Typical consumers: Home Assistant custom integrations, CLI tools, automation daemons, and dashboards.
+
+### Domain model overview
+
+| Entity | Description |
+|---|---|
+| `Space` | A room or zone. Has HVAC controls (mode, setpoints), state (ambient temp, hvac state), comfort preset, and occupancy automation. |
+| `IndoorUnit` | A wall-mounted mini-split head. Controls: fan speed, louver, LED. |
+| `OutdoorUnit` | The outdoor compressor unit. Mostly read-only telemetry. |
+| `Controller` | The Quilt Dial in-room controller. Read-only hardware info + remote sensor. |
+| `ComfortSetting` | A named preset (Active, Sleep, Away, Standby, Custom) with mode + setpoints. |
+| `ScheduleWeek` / `ScheduleDay` | Weekly HVAC schedules for a space. |
+| `SystemSnapshot` | The full state of one Quilt installation at a point in time, returned by a single `GetHomeDatastoreSystem` RPC. |
+
+### Snapshot + stream pattern
+
+The correct pattern for live integrations is **snapshot once, stream updates**:
+
+```python
+snapshot = await client.get_snapshot()          # full state at time T
+
+async with client.stream(snapshot.stream_topics()) as stream:
+    stream.on_space_update(
+        lambda space: snapshot.apply_space(space)   # merge sparse diff
+    )
+    await asyncio.sleep(...)
+```
+
+Stream events are **sparse diffs** (proto3 — only changed fields are set; absent fields default to zero/`UNSPECIFIED`). Never use a raw stream `Space` directly — always merge via `snapshot.apply_space()` (and the corresponding `apply_*` methods for other entity types), otherwise controls, setpoints, and names will read as zero/empty.
+
+## Commands
+
+```bash
+# Install dev dependencies
+pip install -e ".[dev,cli]"
+
+# Lint
+ruff check src/ tests/
+ruff format --check src/ tests/
+
+# Type check
+mypy src/quilt_hp/
+
+# Tests (full suite)
+pytest
+
+# Run a single test file
+pytest tests/test_models.py
+
+# Run a single test by name
+pytest tests/test_models.py -k "test_space_is_off"
+
+# Docs
+python scripts/check_docs_nav.py
+mkdocs build --strict
+
+# Regenerate protobuf stubs (after editing proto/cleaned/*.proto)
+./scripts/regen_protos.sh
+```
+
+Requires Python 3.14. Run checks in order: lint → type → tests → docs.
+
+## Architecture
+
+Five layers, each with a single responsibility:
+
+```
+CLI/TUI  (src/quilt_hp/cli/)
+  └─► QuiltClient facade  (client.py)
+        ├─► Service layer  (src/quilt_hp/services/)
+        │     ├── HomeDatastoreService   — spaces, IDUs, comfort, schedules
+        │     ├── SystemInformationService — system listing, energy
+        │     ├── UserService            — user attributes
+        │     └── NotifierStream         — real-time push stream (bidirectional gRPC)
+        └─► Transport/auth  (transport.py · auth.py · tokens.py)
+              └─► Wire stubs  (src/quilt_hp/_proto/)  ← generated, never edit by hand
+```
+
+**QuiltClient** is the only public API surface. It owns the single `grpc.aio.Channel`, stores the current JWT, and implements `CurrentTokenProvider`. Service classes receive the channel and translate Python objects ↔ proto messages.
+
+**Auth** flow (in `auth.py`): cache → Cognito `REFRESH_TOKEN_AUTH` → email OTP (`CUSTOM_AUTH`). The `TokenStore` protocol is injectable; the CLI's implementation is `cli/store.py:FileStore`. The OTP prompt is an injectable `otp_callback`.
+
+**Transport** (`transport.py`): TLS `grpc.aio.secure_channel` with `_AuthInterceptor` attached. The interceptor patches `authorization` and `x-quilt-app-version` metadata on every call and retries once on `UNAUTHENTICATED` for unary RPCs. Streaming RPCs handle reconnect in `NotifierStream`.
+
+**Wire stubs** in `_proto/` are generated by `./scripts/regen_protos.sh` from `proto/cleaned/`. They are committed so the package installs without `protoc`. They are excluded from ruff and mypy entirely (`pyproject.toml` has the relevant overrides).
+
+The library is **async-only** (`grpc.aio` throughout). There is no sync wrapper and no global state — all channel/token/cache state lives on the `QuiltClient` instance.
+
+## Key Conventions
+
+### Models
+
+All domain models are `@dataclass(slots=True)`. Each model has a `@classmethod from_proto(cls, proto: object) -> ModelType` that accepts the proto object typed as `object` (not the generated proto type) to keep mypy happy while the proto stubs are ignored.
+
+```python
+@dataclass(slots=True)
+class Space:
+    id: str
+    ...
+
+    @classmethod
+    def from_proto(cls, proto: object) -> Space:
+        return _space_from_proto(proto)
+```
+
+### Enums
+
+All enums live in `models/enums.py` and subclass `IntEnum`, mirroring proto integer values exactly. Enums that require non-trivial wire encoding (e.g. `FanSpeed`, `LouverAngle`) carry `to_wire()` / `from_wire()` methods — do not inline this logic elsewhere.
+
+### Imports
+
+Every source file starts with `from __future__ import annotations`. Type-only imports go under `if TYPE_CHECKING:`.
+
+### Callbacks
+
+Public APIs that accept callbacks (OTP, stream events, token refresh) support both sync and async callables. Async-ness is detected with `inspect.iscoroutinefunction` or by inspecting `inspect.signature` parameters.
+
+### Tests
+
+Tests use `types.SimpleNamespace` (aliased as `_ns(...)`) as a lightweight proto stub — no real gRPC connections are made. `asyncio_mode = "auto"` is set in `pyproject.toml` so async test functions need no decorator.
+
+### Proto changes
+
+When editing `.proto` files in `proto/cleaned/`:
+1. Run `./scripts/regen_protos.sh`
+2. Update the service wrapper in `src/quilt_hp/services/`
+3. Update `QuiltClient` if the change is part of the public API
+4. Commit proto sources, regenerated stubs, and source changes together
+
+### Documentation
+
+`docs/` uses MkDocs Material + mkdocstrings. When changing source, update the corresponding reference doc in the same PR (see the table in `docs/how-to/contribute.md`). Validate with `python scripts/check_docs_nav.py` before `mkdocs build --strict`.

{quilt_hp_python-0.1.4 → quilt_hp_python-0.2.1}/CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.1] - 2026-05-10
+
+### Fixed
+- Restored CI/release quality-gate stability by applying required `ruff format`
+  updates in model files.
+
+## [0.2.0] - 2026-05-10
+
 ## [0.1.4] - 2026-05-08
 
 ### Fixed

{quilt_hp_python-0.1.4 → quilt_hp_python-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quilt-hp-python
-Version: 0.1.4
+Version: 0.2.1
 Summary: Async Python client for Quilt mini-split HVAC systems
 Project-URL: Repository, https://github.com/eman/quilt-hp-python
 Project-URL: Issues, https://github.com/eman/quilt-hp-python/issues

{quilt_hp_python-0.1.4 → quilt_hp_python-0.2.1}/docs/how-to/home-assistant.md

@@ -19,7 +19,8 @@ HA event loop
     ├── QuiltClient (gRPC channel + token store)
     ├── SystemSnapshot  ← full state in-memory
     └── NotifierStream  ← real-time diffs → async_set_updated_data()
-        └── on_space_update, on_indoor_unit_update
+        └── on_space_update, on_indoor_unit_update,
+            on_controller_update, on_qsm_update
 ```
 
 ---
@@ -74,6 +75,108 @@ For the `TokenStore` protocol definition, see [Token management reference](../re
 
 ---
 
+## Device and entity modeling
+
+Before writing entity classes, you need a clear mental model of which API objects become HA *devices* and which become *entities* under those devices.
+
+### Why Spaces are not HA devices
+
+A `Space` is a logical zone (room) in the Quilt data model. It carries the writable HVAC state — mode, setpoints, occupancy timeouts — but it has no serial number, no hardware model identifier, and no physical form. Home Assistant's device registry is designed for physical hardware that can be identified by manufacturer, model, and serial number.
+
+The Quilt mobile app does not differentiate between a room and its indoor unit: controlling the room and controlling the head unit are the same action. Use `snapshot.rooms` (which filters to leaf spaces only — those with a `parent_space_id`) when setting up entities. Never create entities for floor-level or home-level parent spaces.
+
+### IDU and QSM share one HA device
+
+The `QuiltSmartModule` (QSM) is embedded inside the `IndoorUnit` enclosure — users never see it as a separate piece of hardware. Because the Quilt app presents them as one unit and the QSM has no user-visible serial number, map them to a **single HA device** identified by the IDU's hardware identifiers.
+
+Use `snapshot.qsm_for_idu(idu)` to resolve the QSM for a given IDU when you need radar or ambient-light sensor data.
+
+```python
+from homeassistant.helpers.entity import DeviceInfo
+
+DOMAIN = "quilt_hp"
+
+def idu_device_info(idu, snapshot) -> DeviceInfo:
+    """Build HA DeviceInfo for an IDU (and its embedded QSM)."""
+    space = next(
+        s for s in snapshot.rooms if s.id == idu.space_id
+    )
+    return DeviceInfo(
+        identifiers={(DOMAIN, idu.id)},
+        name=space.name,          # room name, e.g. "Living Room"
+        manufacturer="Quilt",
+        model=idu.settings.name or "Indoor Unit",
+        serial_number=None,       # serial_number not currently exposed via API
+    )
+```
+
+The `climate` entity for the room belongs to this device. It reads setpoint and mode from `Space.controls` and writes via `client.set_space()`, but it is registered as a child of the IDU device because the IDU is the physical hardware.
+
+### Controller (Quilt Dial) as a separate linked device
+
+The Quilt Dial (`Controller`) is physically separate from the IDU — it is a standalone circular thermostat with its own Wi-Fi radio, temperature sensor, and display. It is associated with the same `space_id` as the IDU it works with, but it has its own serial number and model SKU.
+
+Create a **separate HA device** for each Dial, linked to the IDU device for the same space using `via_device`:
+
+```python
+def controller_device_info(ctrl, snapshot) -> DeviceInfo:
+    """Build HA DeviceInfo for a Quilt Dial (Controller)."""
+    # Find the IDU in the same space so we can set via_device.
+    idu = next(
+        (u for u in snapshot.indoor_units if u.space_id == ctrl.space_id),
+        None,
+    )
+    return DeviceInfo(
+        identifiers={(DOMAIN, ctrl.id)},
+        name=ctrl.name or "Quilt Dial",
+        manufacturer="Quilt",
+        model=ctrl.model_sku or "Dial",
+        serial_number=ctrl.serial_number,
+        via_device=(DOMAIN, idu.id) if idu else None,
+    )
+```
+
+`via_device` tells HA that the Dial is physically associated with (and accessed through) the IDU device, which correctly groups them in the HA UI by room.
+
+### Entity-to-object mapping
+
+| HA platform | Entity name example | Source model | Key fields | Writable? |
+|-------------|---------------------|--------------|------------|-----------|
+| `climate` | Living Room | `Space.controls` + `IndoorUnit.controls` | `hvac_mode`, `heating_setpoint_c`, `cooling_setpoint_c`, `fan_speed` | Yes — `client.set_space()` / `client.set_indoor_unit()` |
+| `sensor` (temperature) | Living Room Temperature | `IndoorUnit.state` | `ambient_temperature_c` | No |
+| `sensor` (humidity) | Living Room Humidity | `IndoorUnit.state` | `ambient_humidity_percent` | No |
+| `binary_sensor` (presence) | Living Room Presence | `IndoorUnit.effective_occupancy_state` | `occupancy_state != 0` | No |
+| `light` | Living Room Light | `IndoorUnit.controls` | `led_state`, `led_brightness`, `led_color_code` | Yes — `client.set_indoor_unit()` |
+| `select` (fan speed) | Living Room Fan Speed | `IndoorUnit.controls` | `fan_speed` | Yes — `client.set_indoor_unit()` |
+| `select` (louver) | Living Room Louver | `IndoorUnit.controls` | `louver_mode` | Yes — `client.set_indoor_unit()` |
+| `sensor` (Dial temperature) | Living Room Dial Temperature | `Controller` | `ambient_temperature_c` | No |
+
+> **Presence note**: Use `idu.effective_occupancy_state` rather than reading `idu.occupancy` directly. The property returns `None` when the IDU is offline, avoiding stale occupancy data being presented as current.
+
+### Resolving IDUs and Controllers for a space
+
+A space always has at most one IDU in a typical Quilt installation. Use these patterns when setting up platforms:
+
+```python
+# All rooms (leaf spaces only — no floor/home-level spaces)
+rooms = snapshot.rooms
+
+# Map space_id → IndoorUnit (for the common single-IDU-per-room case)
+idu_by_space: dict[str, IndoorUnit] = {
+    idu.space_id: idu for idu in snapshot.indoor_units
+}
+
+# Map space_id → Controller (Dial), if one is installed in that room
+ctrl_by_space: dict[str, Controller] = {
+    ctrl.space_id: ctrl for ctrl in snapshot.controllers
+}
+
+# Resolve the QSM embedded in an IDU
+qsm = snapshot.qsm_for_idu(idu)  # returns QuiltSmartModule | None
+```
+
+---
+
 ## Step 2: Build the coordinator
 
 ```python
@@ -82,9 +185,11 @@ import logging
 from datetime import timedelta
 from homeassistant.helpers.update_coordinator import DataUpdateCoordinator, UpdateFailed
 from quilt_hp import QuiltClient
-from quilt_hp.models.system import SystemSnapshot
-from quilt_hp.models.space import Space
+from quilt_hp.models.controller import Controller
 from quilt_hp.models.indoor_unit import IndoorUnit
+from quilt_hp.models.qsm import QuiltSmartModule
+from quilt_hp.models.space import Space
+from quilt_hp.models.system import SystemSnapshot
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -110,24 +215,40 @@ class QuiltCoordinator(DataUpdateCoordinator[SystemSnapshot]):
     async def _start_stream(self, snapshot: SystemSnapshot) -> None:
         topics = snapshot.stream_topics()
         self._stream = self._client.stream(topics, max_reconnects=-1)
+        # Space updates drive climate entity state (mode, setpoints, occupancy).
         self._stream.on_space_update(self._on_space_update)
+        # IDU updates drive temperature/humidity sensors, fan speed, LED, and
+        # presence binary sensor.
         self._stream.on_indoor_unit_update(self._on_idu_update)
+        # Controller updates drive Dial temperature sensor entities.
+        self._stream.on_controller_update(self._on_controller_update)
+        # QSM updates provide raw radar and ALS diagnostic sensor data.
+        self._stream.on_qsm_update(self._on_qsm_update)
         self._stream.on_disconnected(lambda: _LOGGER.warning("Quilt stream disconnected"))
         await self._stream.start()
 
     def _on_space_update(self, space: Space) -> None:
         if self.data is not None:
-            self.data.spaces[space.id] = space
+            self.data.apply_space(space)
             self.async_set_updated_data(self.data)
 
     def _on_idu_update(self, idu: IndoorUnit) -> None:
         if self.data is not None:
-            self.data.indoor_units[idu.id] = idu
+            self.data.apply_indoor_unit(idu)
+            self.async_set_updated_data(self.data)
+
+    def _on_controller_update(self, ctrl: Controller) -> None:
+        if self.data is not None:
+            self.data.apply_controller(ctrl)
+            self.async_set_updated_data(self.data)
+
+    def _on_qsm_update(self, qsm: QuiltSmartModule) -> None:
+        if self.data is not None:
+            self.data.apply_qsm(qsm)
             self.async_set_updated_data(self.data)
 
     async def _async_update_data(self) -> SystemSnapshot:
         try:
-            self._client.invalidate_snapshot()
             return await self._client.get_snapshot()
         except Exception as err:
             raise UpdateFailed(f"Error fetching Quilt snapshot: {err}") from err
@@ -142,6 +263,8 @@ class QuiltCoordinator(DataUpdateCoordinator[SystemSnapshot]):
 
 ## Step 3: Create the climate entity
 
+The climate entity reads mode and setpoints from the `Space` but is registered under the IDU device. The `device_info` property links it to the physical hardware in the HA device registry.
+
 ```python
 from homeassistant.components.climate import (
     ClimateEntity,
@@ -149,8 +272,11 @@ from homeassistant.components.climate import (
     HVACMode as HAHVACMode,
 )
 from homeassistant.const import UnitOfTemperature
+from homeassistant.helpers.entity import DeviceInfo
 from quilt_hp.models.enums import HVACMode as QHVACMode
 
+DOMAIN = "quilt_hp"
+
 _MODE_MAP: dict[QHVACMode, HAHVACMode] = {
     QHVACMode.STANDBY: HAHVACMode.OFF,
     QHVACMode.COOL: HAHVACMode.COOL,
@@ -170,13 +296,23 @@ class QuiltClimateEntity(ClimateEntity):
     )
     _attr_hvac_modes = list(_MODE_MAP.values())
 
-    def __init__(self, coordinator, space_id: str) -> None:
+    def __init__(self, coordinator, space_id: str, idu_id: str) -> None:
         self._coordinator = coordinator
         self._space_id = space_id
+        self._idu_id = idu_id
 
     @property
     def space(self):
-        return self._coordinator.data.spaces[self._space_id]
+        return next(s for s in self._coordinator.data.spaces if s.id == self._space_id)
+
+    @property
+    def device_info(self) -> DeviceInfo:
+        return DeviceInfo(
+            identifiers={(DOMAIN, self._idu_id)},
+            name=self.space.name,
+            manufacturer="Quilt",
+            model="Indoor Unit",
+        )
 
     @property
     def name(self) -> str:
@@ -184,32 +320,34 @@ class QuiltClimateEntity(ClimateEntity):
 
     @property
     def unique_id(self) -> str:
-        return f"quilt_space_{self._space_id}"
+        # Keyed on space_id because the climate entity represents the room,
+        # not the physical IDU.
+        return f"quilt_climate_{self._space_id}"
 
     @property
     def hvac_mode(self) -> HAHVACMode:
-        return _MODE_MAP.get(self.space.controls.mode, HAHVACMode.OFF)
+        return _MODE_MAP.get(self.space.controls.hvac_mode, HAHVACMode.OFF)
 
     @property
     def current_temperature(self) -> float | None:
-        return self.space.state.current_temp_c
+        return self.space.state.ambient_temperature_c
 
     @property
     def target_temperature(self) -> float | None:
-        mode = self.space.controls.mode
+        mode = self.space.controls.hvac_mode
         if mode == QHVACMode.COOL:
-            return self.space.controls.cool_setpoint_c
+            return self.space.controls.cooling_setpoint_c
         if mode == QHVACMode.HEAT:
-            return self.space.controls.heat_setpoint_c
+            return self.space.controls.heating_setpoint_c
         return None
 
     @property
     def target_temperature_high(self) -> float | None:
-        return self.space.controls.cool_setpoint_c
+        return self.space.controls.cooling_setpoint_c
 
     @property
     def target_temperature_low(self) -> float | None:
-        return self.space.controls.heat_setpoint_c
+        return self.space.controls.heating_setpoint_c
 
     async def async_set_hvac_mode(self, hvac_mode: HAHVACMode) -> None:
         mode = _HA_TO_QUILT[hvac_mode]
@@ -228,9 +366,14 @@ class QuiltClimateEntity(ClimateEntity):
 
 ## Step 4: Create a temperature sensor entity
 
+The IDU temperature sensor entity is also registered under the IDU device using the same `device_info` identifiers:
+
 ```python
 from homeassistant.components.sensor import SensorEntity, SensorDeviceClass
 from homeassistant.const import UnitOfTemperature
+from homeassistant.helpers.entity import DeviceInfo
+
+DOMAIN = "quilt_hp"
 
 
 class QuiltIndoorTempSensor(SensorEntity):
@@ -243,11 +386,26 @@ class QuiltIndoorTempSensor(SensorEntity):
 
     @property
     def idu(self):
-        return self._coordinator.data.indoor_units[self._idu_id]
+        return next(u for u in self._coordinator.data.indoor_units if u.id == self._idu_id)
+
+    @property
+    def device_info(self) -> DeviceInfo:
+        space = next(
+            (s for s in self._coordinator.data.spaces if s.id == self.idu.space_id), None
+        )
+        return DeviceInfo(
+            identifiers={(DOMAIN, self._idu_id)},
+            name=space.name if space else self._idu_id,
+            manufacturer="Quilt",
+            model="Indoor Unit",
+        )
 
     @property
     def name(self) -> str:
-        return f"IDU {self._idu_id} temperature"
+        space = next(
+            (s for s in self._coordinator.data.spaces if s.id == self.idu.space_id), None
+        )
+        return f"{space.name} Temperature" if space else f"IDU {self._idu_id} Temperature"
 
     @property
     def unique_id(self) -> str:
@@ -255,11 +413,69 @@ class QuiltIndoorTempSensor(SensorEntity):
 
     @property
     def native_value(self) -> float | None:
-        return self.idu.state.actual_temp_c
+        return self.idu.state.ambient_temperature_c
+
+    @property
+    def available(self) -> bool:
+        return self.idu.is_online
+```
+
+### Dial temperature sensor
+
+Create a parallel sensor class for the `Controller` (Quilt Dial). It is registered under a **separate device** linked to the IDU device via `via_device`:
+
+```python
+from homeassistant.helpers.entity import DeviceInfo
+
+DOMAIN = "quilt_hp"
+
+
+class QuiltDialTempSensor(SensorEntity):
+    _attr_device_class = SensorDeviceClass.TEMPERATURE
+    _attr_native_unit_of_measurement = UnitOfTemperature.CELSIUS
+
+    def __init__(self, coordinator, controller_id: str) -> None:
+        self._coordinator = coordinator
+        self._controller_id = controller_id
+
+    @property
+    def controller(self):
+        return next(
+            c for c in self._coordinator.data.controllers if c.id == self._controller_id
+        )
+
+    @property
+    def device_info(self) -> DeviceInfo:
+        ctrl = self.controller
+        # Find the IDU in the same space so we can set via_device.
+        idu = next(
+            (u for u in self._coordinator.data.indoor_units if u.space_id == ctrl.space_id),
+            None,
+        )
+        return DeviceInfo(
+            identifiers={(DOMAIN, self._controller_id)},
+            name=ctrl.name or "Quilt Dial",
+            manufacturer="Quilt",
+            model=ctrl.model_sku or "Dial",
+            serial_number=ctrl.serial_number,
+            via_device=(DOMAIN, idu.id) if idu else None,
+        )
+
+    @property
+    def name(self) -> str:
+        return f"{self.controller.name or 'Quilt Dial'} Temperature"
+
+    @property
+    def unique_id(self) -> str:
+        return f"quilt_dial_temp_{self._controller_id}"
+
+    @property
+    def native_value(self) -> float | None:
+        return self.controller.ambient_temperature_c
 
     @property
     def available(self) -> bool:
-        return self.idu.state.is_online
+        return self.controller.is_online
 ```
 
 ---

{quilt_hp_python-0.1.4 → quilt_hp_python-0.2.1}/docs/reference/client.md

@@ -69,7 +69,7 @@ Raised when a requested resource does not exist (gRPC `NOT_FOUND`).
 ### `__version__`
 
 ```python
-__version__: str  # e.g. "0.1.2"
+__version__: str  # e.g. "0.2.1"
 ```
 
 ---

{quilt_hp_python-0.1.4 → quilt_hp_python-0.2.1}/docs/reference/hds-entities.md

@@ -38,6 +38,24 @@ A Space is a zone within a Quilt installation, typically a room. Spaces are hier
 
 **Temperature setpoint routing**: The wire `temperature_setpoint_c` field is the "mode-relevant" setpoint. It is the heating setpoint when mode is HEAT and the cooling setpoint otherwise. Both `heating_temperature_setpoint_c` and `cooling_temperature_setpoint_c` are always sent.
 
+### Sentinel and placeholder values (UI handling)
+
+The Quilt apps use several placeholder values to represent "not set", "ignored in this mode", or missing data. Treat these as metadata, not literal user targets.
+
+| Sentinel | Where it appears | Python handling |
+| --- | --- | --- |
+| `heating=8.0`, `cooling=40.0` | `SpaceControls`/`ComfortSetting` for STANDBY | `SpaceControls.has_standby_sentinel_setpoints`, `ComfortSetting.has_standby_sentinel_setpoints` |
+| `heating=0.0`, `cooling=0.0` | `ComfortSettingType.UNSPECIFIED` placeholder | `ComfortSetting.has_unspecified_setpoint_sentinels`, `ComfortSetting.has_placeholder_setpoints` |
+| `comfort_setting_id=""` | Manual/direct-control mode (no preset bound) | `SpaceControls.has_linked_comfort_setting`, `SpaceControls.comfort_setting_id_or_none` |
+| `louver_fixed_position=0.0` with non-`FIXED` mode | Louver position ignored for AUTO/SWEEP/CLOSED | `IndoorUnitControls.louver_position_is_placeholder`, `ComfortSetting.louver_position_is_placeholder` |
+| `fan_speed_mode=0` | Proto3 default = fan fields absent / unknown in sparse diff | `IndoorUnitControls.fan_speed_is_placeholder` |
+| `fanSpeedMaxRpm=0.0` | Indoor-unit hardware spec missing/unpopulated (KMP model) | Reserved constant: `UNSET_MAX_FAN_SPEED_RPM_SENTINEL` |
+| `NaN` in temperatures/energy | Missing or invalid measurement samples | `SpaceState.has_missing_ambient_temperature`, `SpaceState.has_missing_setpoint`, `EnergyBucket.has_missing_energy_value` |
+| timestamp seconds `0` | Proto timestamp unset (no check-in yet) | Parsed as `None` for model datetimes (`updated_at`, `wifi_last_seen`) |
+| unknown schedule weekday | Invalid/unknown day in ordering logic | `ScheduleWeekDay.weekday_sort_order` maps to tail sentinel |
+
+For display code, prefer the `*_or_none` helpers and sentinel predicates over direct field formatting.
+
 ---
 
 ## IndoorUnit

{quilt_hp_python-0.1.4 → quilt_hp_python-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "quilt-hp-python"
-version = "0.1.4"
+version = "0.2.1"
 description = "Async Python client for Quilt mini-split HVAC systems"
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -136,7 +136,7 @@ ignore_missing_imports = true
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
-addopts = "-ra -q --cov=quilt_hp --cov-report=term-missing --cov-fail-under=80"
+addopts = "-ra -q --cov=quilt_hp --cov-report=term-missing --cov-fail-under=80 -p no:homeassistant"
 asyncio_mode = "auto"
 
 

{quilt_hp_python-0.1.4 → quilt_hp_python-0.2.1}/scripts/bump_version.py

@@ -10,18 +10,28 @@ Usage:
 
 import argparse
 import re
-import sys
 from datetime import date
 from pathlib import Path
 
 ROOT = Path(__file__).resolve().parent.parent
 
-# Files where the bare version string (e.g. "0.1.0") should be replaced.
-VERSIONED_FILES = [
-    ROOT / "pyproject.toml",
-    ROOT / "src/quilt_hp/__init__.py",
-    ROOT / "docs/reference/client.md",
-    ROOT / "tests/test_cli_surfaces_extra.py",
+VERSION_TARGETS = [
+    (
+        ROOT / "pyproject.toml",
+        re.compile(r'(?P<pre>^version\s*=\s*")(?P<version>\d+\.\d+\.\d+)(?P<post>")', re.MULTILINE),
+    ),
+    (
+        ROOT / "src/quilt_hp/__init__.py",
+        re.compile(r'(?P<pre>^__version__\s*=\s*")(?P<version>\d+\.\d+\.\d+)(?P<post>")', re.MULTILINE),
+    ),
+    (
+        ROOT / "docs/reference/client.md",
+        re.compile(r'(?P<pre>__version__:\s*str\s*#\s*e\.g\.\s*")(?P<version>\d+\.\d+\.\d+)(?P<post>")'),
+    ),
+    (
+        ROOT / "tests/test_cli_surfaces_extra.py",
+        re.compile(r'(?P<pre>result\.stdout\.strip\(\)\s*==\s*")(?P<version>\d+\.\d+\.\d+)(?P<post>")'),
+    ),
 ]
 
 CHANGELOG = ROOT / "CHANGELOG.md"
@@ -44,14 +54,15 @@ def next_semver(version: str, part: str) -> str:
     return f"{major}.{minor}.{patch + 1}"
 
 
-def update_files(old: str, new: str) -> None:
-    for path in VERSIONED_FILES:
+def update_files(new: str) -> None:
+    replacement = rf"\g<pre>{new}\g<post>"
+    for path, pattern in VERSION_TARGETS:
         text = path.read_text(encoding="utf-8")
-        count = text.count(old)
+        updated, count = pattern.subn(replacement, text)
         if count == 0:
             print(f"  SKIP     {path.relative_to(ROOT)}  (version string not found)")
             continue
-        path.write_text(text.replace(old, new), encoding="utf-8")
+        path.write_text(updated, encoding="utf-8")
         print(f"  updated  {path.relative_to(ROOT)}  ({count} occurrence{'s' if count > 1 else ''})")
 
 
@@ -106,9 +117,9 @@ def main() -> None:
         raise SystemExit(f"ERROR: New version is the same as current ({old})")
 
     print(f"Bumping {old} → {new}\n")
-    update_files(old, new)
+    update_files(new)
     update_changelog(old, new)
-    print(f"\nNext steps:")
+    print("\nNext steps:")
     print(f"  1. Fill in the ## [{new}] section in CHANGELOG.md")
     print(f"  2. git add -A && git commit -m 'chore: bump version to {new}'")
     print(f"  3. git tag v{new} && git push origin main v{new}")