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

quilt_hp_python-0.3.0/CHANGELOG.md

@@ -0,0 +1,78 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.3.0] - 2026-05-12
+
+### Added
+- `NotifierStream` health properties: `is_connected`, `last_event_at`, `stream_state`
+- `NotifierStream` `debounce_s` parameter to coalesce rapid update bursts
+- `MetricBucketStatus` enum exposed on `EnergyBucket.status` (was untyped `int`)
+- `grpc_call()` context manager in `services` for consistent gRPC error translation and optional retry
+- Structured `logging.getLogger(__name__)` across all modules (auth, client, transport, services, CLI)
+- `QuiltStreamError` re-exported from the top-level `quilt_hp` package
+- Shared model helpers (`_helpers.py`) for WiFi signal parsing and hardware lookup
+
+### Changed
+- `ScheduleEvent.hvac_mode` is now typed as `HVACMode` (was `int`)
+- Token temp file created with `os.open(..., 0o600)` so permissions are secure from creation (no transient world-readable window)
+- Signature cache in transport layer uses `weakref.WeakKeyDictionary` instead of `dict[int, bool]` — prevents unbounded growth and id-reuse bugs after GC
+- `login()` clears the token cache so a re-login always fetches fresh credentials
+- `_GrpcCallContext` avoids self-chaining when re-raising a `QuiltError` unchanged
+
+### Fixed
+- `EnergyBucket.has_missing_energy_value` now treats `None` (absent proto field) as missing, not just `NaN`; prevents `TypeError` in `SpaceEnergyMetrics.total_kwh`
+- `MetricBucketStatus()` conversion in `get_energy_metrics` catches `ValueError` for unknown server values and falls back to `UNSPECIFIED` instead of raising
+- `WeakKeyDictionary.get()` for the refresh-callback signature cache is now guarded against `TypeError` for non-weakrefable callables
+- AUTO mode setpoint deadband clamp now runs before setpoint selection, ensuring the correct (clamped) value is sent to the device
+- CLI settings `bool` coercion uses `isinstance(v, bool)` to avoid `bool("false") == True`
+- Zero-value proto3 fields (0 °C temperature, 0 dBm WiFi signal, 0% humidity) are now preserved instead of being dropped as falsy
+- `NotifierStream` reconnect subscription is now protected by an `asyncio.Lock` to prevent concurrent subscribe/reconnect races
+- CLI enum lookups raise a clear error showing valid options on invalid input
+- `auth.py` narrows broad `except Exception` to `except (QuiltAuthError, ClientError)` to avoid swallowing unexpected errors
+
+## [0.2.2] - 2026-05-11
+
+### Fixed
+- Corrected mapping of outdoor units to indoor units in SystemSnapshot
+- Fixed TUI interaction issues with button handling and bindings
+
+## [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
+- `boto3.client()` was called synchronously inside async functions, causing a
+  blocking HTTP request to the EC2 instance metadata service (IMDS) at
+  `169.254.169.254` during credential resolution. This manifested as an
+  `HTTPClientError` in Home Assistant's async event loop. The client is now
+  created via `loop.run_in_executor()` like the subsequent API calls.
+
+## [0.1.3] - 2026-05-08
+
+### Fixed
+- Regenerated gRPC stubs with `grpcio-tools==1.78.0` so the library works
+  inside Home Assistant, which hard-pins `grpcio==1.78.0` in its package
+  constraints. Previously the stubs were generated with 1.80.0 and raised
+  `RuntimeError` at import time on older grpcio versions.
+
+## [0.1.2] - 2026-05-08
+
+## [0.1.1] - 2026-05-08
+
+## [0.1.0]
+
+### Added
+- GitHub Actions release automation for SemVer tags (`vX.Y.Z`) that enforces quality gates, creates a GitHub Release, and publishes distribution artifacts to PyPI via trusted publishing
+- Initial async client for Quilt cloud gRPC API
+- Cognito OTP authentication with token caching
+- HomeDatastoreService: spaces, indoor units, comfort settings, schedules
+- SystemInformationService: system listing, energy metrics
+- NotifierService: real-time streaming subscriptions
+- CLI for interactive use (`quilt` command)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quilt-hp-python
-Version: 0.2.1
+Version: 0.3.0
 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.2.1 → quilt_hp_python-0.3.0}/docs/how-to/automation-daemon.md

@@ -56,19 +56,24 @@ _snapshot: SystemSnapshot | None = None
 async def on_space_update(space: Space) -> None:
     global _snapshot
     if _snapshot is not None:
-        _snapshot.spaces[space.id] = space
+        space = _snapshot.apply_space(space)
 
     temp = (
-        f"{space.state.current_temp_c:.1f}°C"
-        if space.state.current_temp_c is not None
+        f"{space.state.ambient_temperature_c:.1f}°C"
+        if space.state.ambient_temperature_c is not None
         else "unknown"
     )
-    LOG.info("[space] %s — mode=%s temp=%s", space.name, space.controls.mode.value, temp)
+    LOG.info(
+        "[space] %s — mode=%s temp=%s",
+        space.name,
+        space.controls.hvac_mode.value,
+        temp,
+    )
 
     if (
-        space.state.current_temp_c is not None
-        and space.state.current_temp_c > 27.0
-        and space.controls.mode.value in ("auto", "cool")
+        space.state.ambient_temperature_c is not None
+        and space.state.ambient_temperature_c > 27.0
+        and space.controls.hvac_mode.value in ("auto", "cool")
     ):
         LOG.warning("[space] %s is above 27°C — check cooling", space.name)
 
@@ -76,8 +81,8 @@ async def on_space_update(space: Space) -> None:
 async def on_idu_update(idu: IndoorUnit) -> None:
     global _snapshot
     if _snapshot is not None:
-        _snapshot.indoor_units[idu.id] = idu
-    LOG.debug("[idu] %s — fan=%s online=%s", idu.id, idu.controls.fan_speed.value, idu.state.is_online)
+        idu = _snapshot.apply_indoor_unit(idu)
+    LOG.debug("[idu] %s — fan=%s online=%s", idu.id, idu.controls.fan_speed.value, idu.is_online)
 
 
 async def run() -> None:
@@ -91,7 +96,7 @@ async def run() -> None:
         _snapshot = await client.get_snapshot()
         LOG.info(
             "Snapshot loaded: system=%s rooms=%d idus=%d",
-            _snapshot.system_id,
+            client.system_name,
             len(_snapshot.rooms),
             len(_snapshot.indoor_units),
         )
@@ -100,8 +105,7 @@ async def run() -> None:
         stream = client.stream(topics, max_reconnects=-1, reconnect_delay_s=2.0)
         stream.on_space_update(on_space_update)
         stream.on_indoor_unit_update(on_idu_update)
-        stream.on_connected(lambda: LOG.info("Stream connected"))
-        stream.on_disconnected(lambda: LOG.warning("Stream disconnected; will reconnect automatically"))
+        stream.on_error(lambda exc: LOG.error("Stream stopped: %s", exc))
 
         async with stream:
             LOG.info("Daemon running. Send SIGINT or SIGTERM to stop.")

{quilt_hp_python-0.2.1 → quilt_hp_python-0.3.0}/docs/how-to/configure-comfort-settings.md

@@ -11,14 +11,14 @@ To retrieve all comfort presets:
 ```python
 settings = await client.list_comfort_settings()
 for s in settings:
-    print(f"{s.name}: mode={s.hvac_mode}, heat={s.heat_setpoint_c}°C, cool={s.cool_setpoint_c}°C, fan={s.fan_speed}")
+    print(f"{s.name}: mode={s.hvac_mode}, heat={s.heating_setpoint_c}°C, cool={s.cooling_setpoint_c}°C, fan={s.fan_speed}")
 ```
 
 Alternatively, comfort settings are embedded in `SystemSnapshot`:
 
 ```python
 snapshot = await client.get_snapshot()
-for cs in snapshot.comfort_settings.values():
+for cs in snapshot.comfort_settings:
     print(f"{cs.name}: {cs.hvac_mode}")
 ```
 
@@ -40,7 +40,7 @@ updated = await client.update_comfort_setting(
     cool_setpoint_c=25.0,
     fan_speed=FanSpeed.AUTO,
 )
-print(f"Updated '{updated.name}': heat={updated.heat_setpoint_c}°C cool={updated.cool_setpoint_c}°C")
+print(f"Updated '{updated.name}': heat={updated.heating_setpoint_c}°C cool={updated.cooling_setpoint_c}°C")
 ```
 
 Omit any parameter to keep its current value. You can also update by comfort setting ID string:
@@ -73,11 +73,11 @@ async def main() -> None:
         snapshot = await client.get_snapshot()
 
         preset = next(
-            (cs for cs in snapshot.comfort_settings.values() if cs.name == PRESET_NAME),
+            (cs for cs in snapshot.comfort_settings if cs.name == PRESET_NAME),
             None,
         )
         if preset is None:
-            names = [cs.name for cs in snapshot.comfort_settings.values()]
+            names = [cs.name for cs in snapshot.comfort_settings]
             print(f"Preset '{PRESET_NAME}' not found. Available: {names}")
             return
 
@@ -85,8 +85,8 @@ async def main() -> None:
             updated = await client.set_space(
                 space,
                 mode=preset.hvac_mode,
-                heat_setpoint_c=preset.heat_setpoint_c,
-                cool_setpoint_c=preset.cool_setpoint_c,
+                heat_setpoint_c=preset.heating_setpoint_c,
+                cool_setpoint_c=preset.cooling_setpoint_c,
             )
             print(f"  {updated.name}: mode={updated.controls.hvac_mode}")
 

{quilt_hp_python-0.2.1 → quilt_hp_python-0.3.0}/docs/how-to/configure-schedules.md

@@ -13,19 +13,31 @@ To create a day program with timed comfort-setting transitions:
 ```python
 from quilt_hp.models.schedule import ScheduleEvent
 
-# Get a comfort setting ID from the snapshot
+# Get comfort settings for one room from the snapshot
 snapshot = await client.get_snapshot()
 space = snapshot.space_by_name("Bedroom")
-active_cs = next(
-    cs for cs in snapshot.comfort_settings.values() if cs.name == "Active"
-)
-sleep_cs = next(
-    cs for cs in snapshot.comfort_settings.values() if cs.name == "Sleep"
-)
+assert space is not None
+space_settings = snapshot.comfort_settings_for_space(space)
+active_cs = next(cs for cs in space_settings if cs.name == "Active")
+sleep_cs = next(cs for cs in space_settings if cs.name == "Sleep")
 
 events = [
-    ScheduleEvent(time_of_day_s=7 * 3600, comfort_setting_id=active_cs.id),   # 07:00 → Active
-    ScheduleEvent(time_of_day_s=22 * 3600, comfort_setting_id=sleep_cs.id),   # 22:00 → Sleep
+    ScheduleEvent(
+        start_s=7 * 3600,
+        comfort_setting_id=active_cs.id,
+        hvac_mode=active_cs.hvac_mode,
+        heating_setpoint_c=active_cs.heating_setpoint_c,
+        cooling_setpoint_c=active_cs.cooling_setpoint_c,
+        precondition=False,
+    ),
+    ScheduleEvent(
+        start_s=22 * 3600,
+        comfort_setting_id=sleep_cs.id,
+        hvac_mode=sleep_cs.hvac_mode,
+        heating_setpoint_c=sleep_cs.heating_setpoint_c,
+        cooling_setpoint_c=sleep_cs.cooling_setpoint_c,
+        precondition=False,
+    ),
 ]
 
 day = await client.create_schedule_day(
@@ -36,7 +48,7 @@ day = await client.create_schedule_day(
 print(f"Created schedule day: {day.id} ({len(day.events)} events)")
 ```
 
-`time_of_day_s` is the number of seconds from midnight (e.g., `7 * 3600` = 07:00).
+`start_s` is the number of seconds from midnight (e.g., `7 * 3600` = 07:00).
 
 ---
 
@@ -47,17 +59,17 @@ To create a schedule week and assign day programs to each weekday:
 ```python
 from quilt_hp.models.schedule import ScheduleWeekDay
 
-# day_of_week: 0 = Monday, 6 = Sunday
+# weekday: 1 = Monday, 7 = Sunday
 week = await client.create_schedule_week(
     space_id=space.id,
     days=[
-        ScheduleWeekDay(day_of_week=0, schedule_day_id=weekday_program.id),  # Mon
-        ScheduleWeekDay(day_of_week=1, schedule_day_id=weekday_program.id),  # Tue
-        ScheduleWeekDay(day_of_week=2, schedule_day_id=weekday_program.id),  # Wed
-        ScheduleWeekDay(day_of_week=3, schedule_day_id=weekday_program.id),  # Thu
-        ScheduleWeekDay(day_of_week=4, schedule_day_id=weekday_program.id),  # Fri
-        ScheduleWeekDay(day_of_week=5, schedule_day_id=weekend_program.id),  # Sat
-        ScheduleWeekDay(day_of_week=6, schedule_day_id=weekend_program.id),  # Sun
+        ScheduleWeekDay(weekday=1, day_id=weekday_program.id),  # Mon
+        ScheduleWeekDay(weekday=2, day_id=weekday_program.id),  # Tue
+        ScheduleWeekDay(weekday=3, day_id=weekday_program.id),  # Wed
+        ScheduleWeekDay(weekday=4, day_id=weekday_program.id),  # Thu
+        ScheduleWeekDay(weekday=5, day_id=weekday_program.id),  # Fri
+        ScheduleWeekDay(weekday=6, day_id=weekend_program.id),  # Sat
+        ScheduleWeekDay(weekday=7, day_id=weekend_program.id),  # Sun
     ],
 )
 print(f"Created schedule week: {week.id}")
@@ -74,7 +86,7 @@ updated_week = await client.update_schedule_week(
     schedule_week_id=week.id,
     space_id=space.id,
     days=[
-        ScheduleWeekDay(day_of_week=0, schedule_day_id=new_monday_program.id),
+        ScheduleWeekDay(weekday=1, day_id=new_monday_program.id),
         # ... include all 7 days; omitted days are cleared
     ],
 )
@@ -114,4 +126,4 @@ To resume:
 await client.set_schedule_execution(paused=False)
 ```
 
-This is a global switch. It affects all schedule weeks across all spaces in the system. The current pause state is available as `snapshot.schedule_paused`.
+This is a global switch. It affects all schedule weeks across all spaces in the system. The current pause state is available as `snapshot.primary_location.schedule_paused` when a location is present.

{quilt_hp_python-0.2.1 → quilt_hp_python-0.3.0}/docs/how-to/control-spaces.md

@@ -88,7 +88,7 @@ To set the fan speed on an indoor unit:
 from quilt_hp.models.enums import FanSpeed
 
 snapshot = await client.get_snapshot()
-idu = snapshot.indoor_units[next(iter(snapshot.indoor_units))]  # first IDU
+idu = snapshot.indoor_units[0]  # first IDU
 
 updated = await client.set_indoor_unit(idu, fan_speed=FanSpeed.MEDIUM)
 print(f"Fan speed: {updated.controls.fan_speed}")

{quilt_hp_python-0.2.1 → quilt_hp_python-0.3.0}/docs/how-to/stream-updates.md

@@ -23,7 +23,13 @@ def on_idu(idu: IndoorUnit) -> None:
 
 async with client.stream(snapshot.stream_topics()) as stream:
     stream.on_space_update(on_space)
-    stream.on_indoor_unit_update(on_idu)
+    stream.on_indoor_unit_update(lambda idu: print(snapshot.apply_indoor_unit(idu).id))
+    stream.on_outdoor_unit_update(snapshot.apply_outdoor_unit)
+    stream.on_controller_update(snapshot.apply_controller)
+    stream.on_qsm_update(snapshot.apply_qsm)
+    stream.on_remote_sensor_update(snapshot.apply_remote_sensor)
+    stream.on_controller_remote_sensor_update(snapshot.apply_controller_remote_sensor)
+    stream.on_software_update_info(lambda info: print(f"Update info: {info.id}"))
     stream.on_error(lambda e: print(f"Fatal error: {e}"))
     await asyncio.sleep(3600)  # run for 1 hour
 ```
@@ -54,24 +60,59 @@ For indoor units:
 ```python
 def on_idu(idu: IndoorUnit) -> None:
     merged = snapshot.apply_indoor_unit(idu)
-    print(f"{merged.id}: online={merged.state.is_online}")
+    print(f"{merged.id}: online={merged.is_online}")
 ```
 
 For background on why sparse diffs require merging, see [Snapshot and stream data model](../explanation/snapshot-and-stream.md).
 
 ---
 
-## Run the stream as a background task
+## Callback registration methods
+
+`NotifierStream` accepts both synchronous and async callbacks. Register whichever entity types you care about:
+
+| Method | Callback argument | Typical use |
+| --- | --- | --- |
+| `on_space_update()` | `Space` | Merge room diffs with `snapshot.apply_space()` |
+| `on_indoor_unit_update()` | `IndoorUnit` | Merge IDU diffs with `snapshot.apply_indoor_unit()` |
+| `on_outdoor_unit_update()` | `OutdoorUnit` | Merge ODU diffs with `snapshot.apply_outdoor_unit()` |
+| `on_controller_update()` | `Controller` | Merge Dial diffs with `snapshot.apply_controller()` |
+| `on_qsm_update()` | `QuiltSmartModule` | Merge QSM diffs with `snapshot.apply_qsm()` |
+| `on_remote_sensor_update()` | `RemoteSensor` | Merge standalone sensor diffs with `snapshot.apply_remote_sensor()` |
+| `on_controller_remote_sensor_update()` | `ControllerRemoteSensor` | Merge Dial sensor diffs with `snapshot.apply_controller_remote_sensor()` |
+| `on_software_update_info()` | `SoftwareUpdateInfo` | Observe firmware/software update records |
+| `on_error()` | `Exception` | Handle fatal stream failure after reconnects are exhausted |
+
+---
+
+## Lifecycle methods
+
+Use these methods to control the stream explicitly:
+
+| Method / property | What it does |
+| --- | --- |
+| `await stream.start()` | Starts the listener in the background |
+| `await stream.run_forever()` | Runs inline until cancelled or a fatal error stops it |
+| `await stream.stop()` | Cancels the background task and closes the stream |
+| `await stream.subscribe(topics)` | Adds topic subscriptions after startup |
+| `await stream.unsubscribe(topics)` | Removes topic subscriptions |
+| `stream.error` | Last fatal exception, or `None` while healthy |
+
+### Run the stream as a background task
 
 To run the stream while doing other work concurrently:
 
 ```python
-async with client.stream(snapshot.stream_topics()) as stream:
-    stream.on_space_update(on_space)
-    # Stream runs in the background — do other work here
+stream = client.stream(snapshot.stream_topics())
+stream.on_space_update(on_space)
+await stream.start()
+try:
     result = await do_something_else()
     await asyncio.sleep(3600)
-# Stream is stopped when the async with block exits
+finally:
+    await stream.stop()
+    if stream.error is not None:
+        print(f"Stream stopped with error: {stream.error}")
 ```
 
 Use this pattern in integrations (Home Assistant, automation daemons) where the stream is just one part of a larger async application.
@@ -115,7 +156,7 @@ async with client.stream(snapshot.stream_topics()) as stream:
 
 ## Handle stream errors and reconnect
 
-The stream reconnects automatically with exponential back-off (1 s, 2 s, 4 s, … up to a 60 s cap). Use these options to configure the reconnect budget:
+The stream reconnects automatically with exponential back-off (1 s, 2 s, 4 s, … up to a 60 s cap). Use `on_error()` or the `error` property to observe only fatal failures after the reconnect budget is exhausted. Configure the reconnect budget like this:
 
 ```python
 # Unlimited reconnects (default: -1)
@@ -132,14 +173,16 @@ stream = client.stream(
 )
 ```
 
-To observe connection lifecycle events:
+To observe fatal stream failures:
 
 ```python
-stream.on_connected(lambda: print("Stream connected"))
-stream.on_disconnected(lambda: print("Stream disconnected; will reconnect"))
 stream.on_error(lambda e: print(f"Fatal error (budget exhausted): {e}"))
+
+await stream.run_forever()
+if stream.error is not None:
+    print(f"Last fatal error: {stream.error}")
 ```
 
-`on_error` is called only when the reconnect budget is exhausted. Until then, disconnects and errors trigger automatic reconnection without invoking `on_error`.
+`on_error()` is called only when the reconnect budget is exhausted. Until then, disconnects and transient errors trigger automatic reconnection without surfacing a fatal error to your callback.
 
 For the full reconnect state machine, see [The streaming protocol](../explanation/streaming-protocol.md).

{quilt_hp_python-0.2.1 → quilt_hp_python-0.3.0}/docs/how-to/tui-app.md

@@ -64,12 +64,10 @@ class IDUUpdate(Message):
         self.idu = idu
 
 
-class StreamConnected(Message):
-    pass
-
-
-class StreamDisconnected(Message):
-    pass
+class StreamError(Message):
+    def __init__(self, error: Exception) -> None:
+        super().__init__()
+        self.error = error
 
 
 class QuiltApp(App):
@@ -99,6 +97,7 @@ class QuiltApp(App):
 
         self._snapshot = await self._client.get_snapshot()
         self._refresh_table()
+        self.query_one("#status-bar", Label).update("● Streaming")
 
         self.run_worker(self._run_stream(), exclusive=True)
 
@@ -110,30 +109,26 @@ class QuiltApp(App):
         stream = self._client.stream(topics, max_reconnects=-1)
         stream.on_space_update(self._on_space)
         stream.on_indoor_unit_update(self._on_idu)
-        stream.on_connected(lambda: self.post_message(StreamConnected()))
-        stream.on_disconnected(lambda: self.post_message(StreamDisconnected()))
+        stream.on_error(lambda exc: self.post_message(StreamError(exc)))
 
         async with stream:
             await asyncio.Event().wait()
 
     def _on_space(self, space: Space) -> None:
         if self._snapshot is not None:
-            self._snapshot.spaces[space.id] = space
+            space = self._snapshot.apply_space(space)
         self.post_message(SpaceUpdate(space))
 
     def _on_idu(self, idu: IndoorUnit) -> None:
         if self._snapshot is not None:
-            self._snapshot.indoor_units[idu.id] = idu
+            idu = self._snapshot.apply_indoor_unit(idu)
         self.post_message(IDUUpdate(idu))
 
     def on_space_update(self, msg: SpaceUpdate) -> None:
         self._update_row(msg.space)
 
-    def on_stream_connected(self, msg: StreamConnected) -> None:
-        self.query_one("#status-bar", Label).update("● Connected")
-
-    def on_stream_disconnected(self, msg: StreamDisconnected) -> None:
-        self.query_one("#status-bar", Label).update("○ Disconnected — reconnecting…")
+    def on_stream_error(self, msg: StreamError) -> None:
+        self.query_one("#status-bar", Label).update(f"✕ Stream stopped: {msg.error}")
 
     def _refresh_table(self) -> None:
         if self._snapshot is None:
@@ -144,15 +139,15 @@ class QuiltApp(App):
     def _update_row(self, space: Space) -> None:
         table = self.query_one("#spaces-table", DataTable)
         temp = (
-            f"{space.state.current_temp_c:.1f}°C"
-            if space.state.current_temp_c is not None
+            f"{space.state.ambient_temperature_c:.1f}°C"
+            if space.state.ambient_temperature_c is not None
             else "—"
         )
         setpoints = (
-            f"{space.controls.heat_setpoint_c:.0f} / "
-            f"{space.controls.cool_setpoint_c:.0f}°C"
+            f"{space.controls.heating_setpoint_c:.0f} / "
+            f"{space.controls.cooling_setpoint_c:.0f}°C"
         )
-        row = (space.name, space.controls.mode.value, temp, setpoints)
+        row = (space.name, space.controls.hvac_mode.value, temp, setpoints)
 
         key = f"space-{space.id}"
         if key in table.rows:
@@ -203,8 +198,10 @@ async def action_set_mode(self) -> None:
     row_key = table.cursor_row_key
     if row_key is None:
         return
+    if self._snapshot is None:
+        return
     space_id = row_key.removeprefix("space-")
-    space = self._snapshot.spaces.get(space_id)
+    space = next((s for s in self._snapshot.spaces if s.id == space_id), None)
     if space is None:
         return
 

{quilt_hp_python-0.2.1 → quilt_hp_python-0.3.0}/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.2.1"
+__version__: str  # e.g. "0.3.0"
 ```
 
 ---
@@ -112,7 +112,7 @@ async def __aenter__(self) -> QuiltClient: ...
 async def __aexit__(self, *_: object) -> None: ...
 ```
 
-`__aexit__` closes the gRPC channel. Always use `QuiltClient` as an async context manager.
+`__aexit__` calls `close()` to close the gRPC channel. Prefer the async context manager, or call `await close()` yourself when managing lifecycle manually.
 
 ---
 
@@ -143,6 +143,16 @@ async def refresh_token(self, context: TokenRefreshContext | None = None) -> Non
 
 Silently refreshes the auth token using the refresh token. Does not attempt OTP. Called automatically by the transport interceptor on `UNAUTHENTICATED`; rarely needed directly.
 
+### `get_current_token`
+
+```python
+def get_current_token(self) -> str
+```
+
+Returns the current JWT access token held by the client.
+
+**Raises:** `QuiltAuthError` if the client is not authenticated yet.
+
 ---
 
 ## System discovery
@@ -155,7 +165,7 @@ async def list_systems(self) -> list[SystemInfo]
 
 Lists all Quilt systems the authenticated user has access to.
 
-**Returns:** List of `SystemInfo` objects with `id`, `name`, `timezone`, `location_id`.
+**Returns:** List of `SystemInfo` objects with `id`, `name`, and `timezone`.
 
 **Raises:** `QuiltError` if the gRPC call fails.
 
@@ -205,6 +215,14 @@ def invalidate_snapshot(self) -> None
 
 Discards the cached snapshot. The next `get_snapshot()` call fetches fresh data from the server.
 
+### `close`
+
+```python
+async def close(self) -> None
+```
+
+Closes the underlying gRPC channel and clears the client's open channel reference. Safe to call multiple times.
+
 ---
 
 ## Space control