Feature/state proxy; require python 3.13 (#192)

* rename services to core, move core.py back under here. didn't make sense as services since we have resources there too

* add priority to handlers finally

* reduce supported versions of python so we can use latest and greatest typing functionality

* add default to TypeVar, remove all StateUnion annotations

* clean up some types

* start working on state proxy

* use type

* Update src/hassette/models/states/base.py

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* simplify state proxy resource

* add comment about disabling UP040

* remove commented out code

* update lockfile

* Update src/hassette/core/state_proxy.py

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* rename config/core.py to config.py

* improve logging, add comment about not listening to registry updated event

* rename

* start adding instance level States class

* increase traceback level

* need to wait for new staty proxy to be ready

* add states

* start using self.states

* add state proxy to harness, use when app handler is used

* ensure we don't add state of None to dict

* start of tests for states/state_proxy by codex

* add method to get listeners by owner

* add classmethod to get domain from domain field

* fix mess of tests

* remove unused topic

* add back another test

* few more minor improvements

* remove old homeassistant docker compose and files

* remove entity updated registry event

* separate out DI annotations that can return None/MISSING_VALUE and those that cannot. add new exceptions. raise if type doesn't match, allow override in config

* add value as alias choice for value, in case we are getting it by converting a BaseState to a more specific one

* use Maybe DI annotations

* correct annotation type

* remove KnownType types, weren't being used any longer

* add more tests

* specific is None check

* get rid of AppMeta and move validate_app to load_app_class

* fix: fix bug where changed app was not re-imported

* bit more cleanup of method and comments

* ignore out of order events

* add more properties, make state_proxy private

* add test that we have full coverage of domains, fix missing domains

* fix failign tests

* update changelog

* update changelog

* add missing domains to states

* update documentation + add documentation for states

* bump minor version and update changelog

* Update src/hassette/bus/utils.py

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Update src/hassette/bus/utils.py

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: NodeJSmith

.github/workflows/test_and_lint.yml

@@ -14,7 +14,7 @@ jobs:
         strategy:
             fail-fast: false
             matrix:
-                python-version: ["3.11", "3.12", "3.13"]
+                python-version: ["3.13"]
 
         steps:
             - name: Checkout code
@@ -49,7 +49,7 @@ jobs:
             - name: Install uv and set the Python version
               uses: astral-sh/setup-uv@v6
               with:
-                  python-version: 3.12
+                  python-version: 3.13
 
             - name: Install coverage
               run: |

CHANGELOG.md

@@ -7,9 +7,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+## [0.17.0] - 2025-11-22
+
+### Changed
+- **Breaking:** - Requires Python 3.13 going forward, Python 3.12 and 3.11 are no longer supported.
+  - This allows use of `type`, defaults for TypeVars, and other new typing features.
+- Renamed `core_config.py` to `core.py`
+- Renamed `services` to `core` and move `core.py` under `core` directory
+  - Didn't make sense to keep named as `services` since we have resources in here as well
+
 ### Added
 - Add `diskcache` dependency and `cache` attribute to all resources
   - Each resource class has its own cache directory under the Hassette data directory
+- Add `states` attribute to `App` - provides access to current states in Home Assistant
+  - `states` is an instance of the new `States` class
+  - `States` provides domain-based access to entity states, e.g. `app.states.light.get("light.my_light")`
+  - `States` listens to state change events and keeps an up-to-date cache of states
+  - New states documentation page under core-concepts
+- Add `Maybe*` DI annotations for optional dependencies in event handlers
+  - `MaybeStateNew`, `MaybeStateOld`, `MaybeEntityId`, etc.
+  - These will allow `None` or `MISSING_VALUE` to be returned if the value is not available
+  - The original dependency annotations will raise an error if the value is not available
+- Add `raise_on_incorrect_dependency_type` to `HassetteConfig` to control whether to raise an error if a dependency cannot be provided due to type mismatch
+  - Default is `true` in production mode, `false` in dev mode
+  - When `false` a warning will be logged but the handler will still be called with whatever value was returned
+
+### Fixed
+- Fixed bug that caused apps to not be re-imported when code changed due to skipping cache check in app handler
+- Fixed missing domains in `DomainLiteral` in `hassette.models.states.base`
+  - Add tests to catch this in the future
 
 ## [0.16.0] - 2025-11-16
 

Dockerfile

@@ -1,7 +1,7 @@
 # syntax=docker/dockerfile:1
 
 # ---- Builder stage ----
-FROM python:3.12-alpine AS builder
+FROM python:3.13-alpine AS builder
 COPY --from=ghcr.io/astral-sh/uv:0.9.8 /uv /bin/
 
 # uncomment this if/when we need to build packages with native extensions
@@ -23,7 +23,7 @@ RUN --mount=type=cache,target=/root/.cache/uv \
     uv sync --locked --no-editable --active
 
 # ---- Final stage ----
-FROM python:3.12-alpine
+FROM python:3.13-alpine
 
 # System packages you want available at runtime
 RUN apk add --no-cache curl tini tzdata
@@ -44,7 +44,7 @@ RUN addgroup -S hassette \
     && chown -R hassette:hassette /config /data /apps /app
 
 # Copy uv binary
-COPY --from=ghcr.io/astral-sh/uv:0.8 /uv /bin/
+COPY --from=ghcr.io/astral-sh/uv:0.9.8 /uv /bin/
 
 # Copy app, venv, scripts
 COPY --from=builder --chown=hassette:hassette /app /app

README.md

@@ -98,7 +98,7 @@ Check out the [`examples/`](https://github.com/NodeJSmith/hassette/tree/main/exa
 
 **Configuration examples**:
 - [Docker Compose Guide](https://hassette.readthedocs.io/en/latest/pages/getting-started/docker/) - Docker deployment setup
-- [HassetteConfig](https://hassette.readthedocs.io/en/latest/reference/hassette/config/core/#hassette.config.core.HassetteConfig) - Complete configuration reference
+- [HassetteConfig](https://hassette.readthedocs.io/en/latest/reference/hassette/config/core/#hassette.config.config.HassetteConfig) - Complete configuration reference
 
 ## 🛣️ Status & Roadmap
 
@@ -110,7 +110,6 @@ Development is tracked in our [GitHub project](https://github.com/users/NodeJSmi
 
 - 🔐 **Enhanced type safety** - Fully typed service calls and additional state models
 - 🏗️ **Entity classes** - Rich entity objects with built-in methods (e.g., `await light.turn_on()`)
-- 💾 **State cache** - Local state caching for faster reads (similar to AppDaemon)
 - 🔄 **Enhanced error handling** - Better retry logic and error recovery
 - 🧪 **Testing improvements** - More comprehensive test coverage and user app testing framework
 

docker-compose.ci.yml

@@ -56,6 +56,7 @@ autocompletion and earlier error detection.
 | Monitor service calls             | `self.listen_event(self.on_service, "call_service", domain="light")`                | `self.bus.on_call_service(domain="light", handler=self.on_service)`                                             |
 | Schedule something in 60 seconds  | `self.run_in(self.turn_off, 60)`                                                    | `self.scheduler.run_in(self.turn_off, delay=60)`                                                                |
 | Run every morning at 07:30        | `self.run_daily(self.morning, time(7, 30, 0))`                                      | `self.scheduler.run_daily(self.morning, start=time(7, 30))`                                                     |
+| Get entity state (cached)         | `self.get_state("light.kitchen")`                                                   | `self.states.light.get("light.kitchen")`                                                                        |
 | Call a Home Assistant service     | `self.call_service("light/turn_on", entity_id="light.kitchen", brightness=200)`     | `await self.api.call_service("light", "turn_on", target={"entity_id": "light.kitchen"}, brightness=200)`        |
 | Access app configuration          | `self.args["entity"]`                                                               | `self.app_config.entity`                                                                                        |
 | Stop a listener                   | `self.cancel_listen_state(handle)`                                                  | `subscription.cancel()`                                                                                         |
@@ -639,28 +640,45 @@ class StateGetter(Hass):
 
 #### Hassette
 
-Hassette aims to provide a fully typed API client that uses Pydantic
-models for requests and responses. The client methods are async and
-return rich objects with attributes. Attempting to access a non-existent
-entity will raise a `EntityNotFoundError` exception.
+Hassette provides two ways to access entity states:
 
-The API client is accessed via the `self.api` attribute. This client
-makes direct calls to Home Assistant over REST API, which does require
-using `await`. When you call `set_state()`, it uses the Home Assistant
-REST API to update the state of the entity.
+1. **`self.states`** - Local state cache (similar to AppDaemon) that's automatically kept up-to-date via state change events. This is the preferred method for most reads.
+2. **`self.api`** - Direct API calls to Home Assistant for when you need to force a fresh read or perform writes.
 
-!!! info "State Cache Coming Soon"
-    A state cache similar to AppDaemon's is planned for a future release,
-    which will reduce API calls for frequently accessed states.
+**Using the State Cache (`self.states`)**
+
+The `self.states` attribute provides immediate access to all entity states without making API calls. It listens to state change events and maintains an up-to-date local cache, similar to AppDaemon's behavior.
 
 ```python
+from hassette import App
 from hassette.models import states
 
-from hassette import App
 
+class StateGetter(App):
+    async def on_initialize(self):
+        # Access via domain-specific property (no await needed)
+        office_light = self.states.light.get("light.office_light_1")
+
+        if office_light:
+            self.logger.info(f"Light state: {office_light.value}")
+            self.logger.info(f"Brightness: {office_light.attributes.brightness}")
+
+        # Iterate over all lights
+        for entity_id, light in self.states.light:
+            self.logger.info(f"{entity_id}: {light.value}")
+
+        # Typed access for any domain
+        my_light = self.states.get[states.LightState]("light.office_light_1")
+```
+
+**Using the API Client (`self.api`)**
 
+For cases where you need to force a fresh read from Home Assistant or perform writes:
+
+```python
 class StateGetter(App):
     async def on_initialize(self):
+        # Force fresh read from HA (requires await)
         office_light_state = await self.api.get_state("light.office_light_1", model=states.LightState)
         self.logger.info(f"{office_light_state=}")
 ```
@@ -916,18 +934,40 @@ def initialize(self):
 ```
 
 **Hassette**:
+
+Hassette provides two approaches - the **local cache** (preferred, similar to AppDaemon) and **direct API calls**:
+
 ```python
 from hassette.models import states
 
 async def on_initialize(self):
-    # Typed state object
+    # PREFERRED: Use local state cache (no await, no API call)
+    # This is most similar to AppDaemon's behavior
+    light = self.states.light.get("light.kitchen")
+    if light:
+        brightness = light.attributes.brightness  # Type-safe access
+        value = light.value  # State value as string
+
+    # Iterate over all lights in cache
+    for entity_id, light in self.states.light:
+        self.logger.info(f"{entity_id}: {light.value}")
+
+    # Typed access for any domain
+    my_light = self.states.get[states.LightState]("light.kitchen")
+
+    # ALTERNATIVE: Force fresh read from Home Assistant API
     light = await self.api.get_state("light.kitchen", states.LightState)
-    brightness = light.attributes.brightness  # Type-safe access
+    brightness = light.attributes.brightness
 
     # Or get just the value
     value = await self.api.get_state_value("light.kitchen")  # Returns string
 ```
 
+**When to use each approach:**
+
+- **`self.states`** (recommended): For reading current state in event handlers, scheduled tasks, or any time you need quick access to entity state. The cache is automatically kept up-to-date via state change events.
+- **`self.api.get_state()`**: Only when you specifically need to force a fresh read from Home Assistant (rare) or if you're outside the normal app lifecycle.
+
 #### Calling Services
 
 **AppDaemon**:
@@ -1052,7 +1092,8 @@ class MyApp(App):
     - In Hassette: `self.app_config.key`
     - Define all config keys in your `AppConfig` model for validation
 
-!!! info "State Cache"
-    - AppDaemon caches all states automatically
-    - Hassette currently makes direct API calls (cache coming in a future release)
-    - Use `get_states()` once and filter locally for better performance
+!!! tip "State Access"
+    - AppDaemon: `self.get_state()` returns cached state
+    - Hassette: `self.states.light.get()` returns cached state (no `await` needed)
+    - Both maintain automatic local caches updated via state change events
+    - Use `self.api.get_state()` only when you need to force a fresh read from HA

docker-compose.yml

@@ -281,15 +281,15 @@ async def check_climate(self):
 
 ### Common Attributes to Check
 
-| Attribute             | Found On               | Type            | Use Case                          |
-| --------------------- | ---------------------- | --------------- | --------------------------------- |
-| `battery_level`       | Many devices           | `int | None`   | Monitor device health             |
-| `brightness`          | Lights                 | `int | None`   | Check/set light intensity (0-255) |
-| `temperature`         | Climate                | `float | None` | Target temperature                |
-| `current_temperature` | Climate                | `float | None` | Actual temperature                |
-| `media_title`         | Media players          | `str | None`   | What's playing                    |
-| `friendly_name`       | All entities           | `str`           | Display name                      |
-| `device_class`        | Sensors/binary sensors | `str | None`   | Type classification               |
+| Attribute             | Found On               | Type   | Use Case     |
+| --------------------- | ---------------------- | ------ | ------------ |
+| `battery_level`       | Many devices           | `int   | None`        | Monitor device health             |
+| `brightness`          | Lights                 | `int   | None`        | Check/set light intensity (0-255) |
+| `temperature`         | Climate                | `float | None`        | Target temperature                |
+| `current_temperature` | Climate                | `float | None`        | Actual temperature                |
+| `media_title`         | Media players          | `str   | None`        | What's playing                    |
+| `friendly_name`       | All entities           | `str`  | Display name |
+| `device_class`        | Sensors/binary sensors | `str   | None`        | Type classification               |
 
 ## Error Handling
 
@@ -353,11 +353,32 @@ async def refresh_cache(self):
     self.config_entities = await self.api.get_states()
 ```
 
-### Use State Cache (Coming Soon)
+### Use `self.states` for Local State Access
 
-!!! info "Roadmap"
-    A built-in state cache similar to AppDaemon's is planned. This will automatically maintain
-    an up-to-date local copy of all entity states, eliminating most API calls for reads.
+Hassette maintains a local cache of all entity states via the `self.states` attribute. This cache is automatically updated by listening to state change events, providing instant access without API calls.
+
+```python
+async def on_initialize(self):
+    # Access cached state without API call
+    light = self.states.light.get("light.bedroom")
+    if light and light.attributes.brightness:
+        self.logger.info(f"Brightness: {light.attributes.brightness}")
+
+    # Iterate over all sensors
+    for entity_id, sensor in self.states.sensor:
+        if hasattr(sensor.attributes, "battery_level"):
+            if sensor.attributes.battery_level < 20:
+                self.logger.warning(f"{entity_id} battery low: {sensor.attributes.battery_level}%")
+
+    # Count entities by domain
+    light_count = len(self.states.light)
+    sensor_count = len(self.states.sensor)
+```
+
+**When to use `self.states` vs `self.api`:**
+
+- **Use `self.states`** (recommended): For reading current state in event handlers, scheduled tasks, or any synchronous state access. The cache is kept up-to-date automatically.
+- **Use `self.api.get_state()`**: Only when you need to force a fresh read from Home Assistant (rare), or during initial setup before the cache is populated.
 
 ## History and Time-Based Queries
 
@@ -456,7 +477,7 @@ except HomeAssistantError as e:
 | Get all states         | `get_states()`                              | `list[BaseState]`    |
 | Get single state       | `get_state(entity_id, model)`               | `StateT`             |
 | Get state value only   | `get_state_value(entity_id)`                | `str`                |
-| Check if entity exists | `get_state_or_none(entity_id, model)`       | `StateT | None`     |
+| Check if entity exists | `get_state_or_none(entity_id, model)`       | `StateT              | None` |
 | Call any service       | `call_service(domain, service, **data)`     | `ServiceResponse`    |
 | Turn on entity         | `turn_on(entity_id, **data)`                | `ServiceResponse`    |
 | Turn off entity        | `turn_off(entity_id, **data)`               | `ServiceResponse`    |

docs/pages/appdaemon-comparison.md

@@ -3,14 +3,21 @@
 
 class StatesExample(App):
     async def states_example(self):
-        # Bulk fetch every entity as a typed state union
-        all_states = await self.api.get_states()
+        # PREFERRED: Use state cache for instant access (no API call)
+        # Access all entities
+        all_states = self.states.all
 
-        # Target a specific device with a concrete model
-        climate = await self.api.get_state("climate.living_room", states.ClimateState)
-        if climate.attributes.hvac_action == "heating":
-            self.logger.debug("Living room is warming up (%.1f°C)", climate.attributes.current_temperature)
+        # Target a specific device with typed model (no await needed)
+        climate = self.states.climate.get("climate.living_room")
+        if climate and climate.attributes.hvac_action == "heating":
+            self.logger.debug("Living room is warming up (%.1f)", climate.attributes.current_temperature)
+
+        # Access state value directly
+        outdoor_sensor = self.states.sensor.get("sensor.outdoor_temp")
+        temperature = outdoor_sensor.value if outdoor_sensor else None
+
+        # ALTERNATIVE: Force fresh read from API (rare, requires await)
+        fresh_climate = await self.api.get_state("climate.living_room", states.ClimateState)
+        self.logger.debug("Fresh HVAC action: %s", fresh_climate.attributes.hvac_action)
 
-        # Raw access
-        temperature = await self.api.get_state_value("sensor.outdoor_temp")
         return all_states, climate, temperature