Implement required dependency injection for event handlers (#191)

* use new event classes instead of old casting

* move some stuff down so we don't have to wrap in strings

* fix accessors by using states.StateUnion, cast, and improve some return types

* add accessors for state old/new

* initial addition of dependency injection logic

* these do not need to be generic, no benefit

* improve DI

* remove ability to pass positional args

* majorly simplify handler types, remove all annotations from bus signatures

* add back ability to be None

* make base HassetteError, add new exception type

* do not autodetect apps during tests

* remove option no longer supported by pyright

* fix tests

* fix incorrect annotation

* remove old args

* remove args from test app handlers

* remove unreachable code

* move to module, split into files, rename to dependencies to match convention

* update docs

* update examples

* fix examples

* fix orphan docstring

* change fallback logic

* enforce no var args/positional only args regardlesss of using DI

* simplify is_event_type check

* add some missing exports

* handle possibility of param type not having __name__

* check and warn on collisions

* make it explicit that we don't handle unions or optionals

* add a file full of test events

* add another file of test events

* switch to session scope since needed for DI test fixtures at session scope

* use defined handler instead of asyncmock so it doesn't raise due to accepting args

* add DI tests

* make entity/domain accessors more robust

* correct return type for context

* remove unnecessary logic from get_service_data

* formatting + comment

* add logger

* improve tests

* flip validation order

* remove Annotated: pattern is to use Annotated[type, D], so these shouldn't already be Anontated

* fix tests

* update documentation and examples

* simplify annotations, excepting attr ones

* remove redundant type

* add assertion

* fix tests

* remove references to Depends

* remove bold

* bump minor

Author: NodeJSmith

.github/copilot-instructions.md

@@ -22,10 +22,12 @@ These notes make AI coding agents productive quickly in this repo. Focus on the
 ## App Pattern (typed)
 
 - Base classes: `src/hassette/core/resources/app/app.py` exposes `App[AppConfigT]` (async) and `AppSync`. Override lifecycle hooks (`before_initialize`, `on_initialize`, `after_initialize`, and matching shutdown hooks); `initialize()` / `shutdown()` are final.
-- Example async app:
+- Example async app with dependency injection:
 
   ```python
-  from hassette import App, AppConfig
+  from typing import Annotated
+  from hassette import App, AppConfig, states
+  from hassette import dependencies as D
 
   class MyConfig(AppConfig):
       light: str
@@ -38,12 +40,43 @@ These notes make AI coding agents productive quickly in this repo. Focus on the
               changed_to="on",
           )
 
-      async def on_light_change(self, event):
-          await self.api.call_service("notify", "mobile_app_me", message="Light turned on")
+      async def on_light_change(
+          self,
+          new_state: D.StateNew[states.LightState],
+          entity_id: D.EntityId,
+      ):
+          friendly_name = new_state.attributes.friendly_name or entity_id
+          await self.api.call_service("notify", "mobile_app_me", message=f"{friendly_name} turned on")
   ```
 
 - Sync apps inherit `AppSync` and implement `on_initialize_sync` / `on_shutdown_sync`; use `self.api.sync.*` for blocking calls. `self.task_bucket` offers helpers (`spawn`, `run_in_thread`, `run_sync`) for background work.
 
+## Dependency Injection for Event Handlers
+
+- **Module**: `src/hassette/dependencies/` provides DI system for event handlers
+- **Purpose**: Automatically extract and inject event data into handler parameters using `Annotated` type hints
+- **Key files**:
+  - `__init__.py` - Public API and examples
+  - `classes.py` - Dependency marker classes (`StateNew`, `StateOld`, `AttrNew`, etc.)
+  - `extraction.py` - Signature inspection and parameter extraction logic
+- **Usage pattern**:
+
+  ```python
+  from typing import Annotated
+  from hassette import dependencies as D, states
+
+  async def handler(
+      new_state: D.StateNew[states.LightState],
+      brightness: Annotated[int | None, D.AttrNew("brightness")],
+      entity_id: D.EntityId,
+  ):
+      # Parameters automatically extracted and injected
+      pass
+  ```
+
+- **Available dependencies**: `StateNew`, `StateOld`, `StateOldAndNew`, `AttrNew(name)`, `AttrOld(name)`, `AttrOldAndNew(name)`, `EntityId`, `Domain`, `Service`, `StateValueNew`, `StateValueOld`, `ServiceData`, `EventContext`
+- **Integration**: `Bus` resource (`core/resources/bus/bus.py`) uses `extract_from_signature` and `validate_di_signature` to process handler signatures and inject values at call time
+
 ## Event Bus Usage
 
 - Topics are defined in `src/hassette/topics.py` (`HASS_EVENT_STATE_CHANGED`, `HASSETTE_EVENT_SERVICE_STATUS`, `HASSETTE_EVENT_APP_LOAD_COMPLETED`, etc.).

CHANGELOG.md

@@ -7,10 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+## [0.16.0] - 2025-11-16
+
 ### Added
 - Added `ANY_VALUE` sentinel for clearer semantics in predicates - use this to indicate "any value is acceptable"
+- **Dependency Injection for Event Handlers** - Handlers can now use `Annotated` type hints with dependency markers from `hassette.dependencies` to automatically extract and inject event data as parameters. This provides a cleaner, more type-safe alternative to manually accessing event payloads.
+  - Available dependencies include `StateNew`, `StateOld`, `AttrNew(name)`, `AttrOld(name)`, `EntityId`, `Domain`, `Service`, `ServiceData`, `StateValueNew`, `StateValueOld`, `EventContext`, and more
+  - Handlers can mix DI parameters with custom kwargs
+  - See `hassette.dependencies` module documentation and updated examples for details
 
 ### Changed
+- **Breaking:** - Event handlers can no longer receive positional only args or variadic positional args
 - `NOT_PROVIDED` predicate is now used only to indicate that a parameter was not provided to a function
 
 ## [0.15.5] - 2025-11-14

README.md

@@ -19,6 +19,7 @@ A simple, modern, async-first Python framework for building Home Assistant autom
 
 - **Type Safe**: Full type annotations with Pydantic models and comprehensive IDE support
 - **Async-First**: Built for modern Python with async/await throughout
+- **Dependency Injection**: Clean handler signatures with automatic parameter extraction
 - **Simple & Focused**: Just Home Assistant automations - no complexity creep
 - **Developer Experience**: Clear error messages, proper logging, hot-reloading, and intuitive APIs
 
@@ -33,7 +34,9 @@ pip install hassette
 Create a simple app (`apps/hello.py`):
 
 ```python
-from hassette import App
+from typing import Annotated
+from hassette import App, states
+from hassette import dependencies as D
 
 class HelloApp(App):
     async def on_initialize(self):
@@ -43,11 +46,15 @@ class HelloApp(App):
             changed_to="on"
         )
 
-    async def on_door_open(self, event):
-        self.logger.info("Front door opened!")
+    async def on_door_open(
+        self,
+        new_state: D.StateNew[states.BinarySensorState],
+        entity_id: D.EntityId,
+    ):
+        self.logger.info("%s opened!", entity_id)
         await self.api.call_service(
             "notify", "mobile_app_phone",
-            message="Front door opened!"
+            message=f"{new_state.attributes.friendly_name or entity_id} opened!"
         )
 ```
 

agents.md

@@ -42,7 +42,9 @@ API calls reuse both the shared WebSocket and REST client managed by `ApiResourc
 Apps inherit from `App[AppConfigT]` (async) or `AppSync` (sync) and implement lifecycle hooks:
 
 ```python
-from hassette import App, AppConfig
+from typing import Annotated
+from hassette import App, AppConfig, states
+from hassette import dependencies as D
 
 class MyConfig(AppConfig):
     light: str
@@ -55,8 +57,13 @@ class MyApp(App[MyConfig]):
             changed_to="on",
         )
 
-    async def on_light_change(self, event):
-        await self.api.call_service("notify", "mobile_app_me", message="Light turned on")
+    async def on_light_change(
+        self,
+        new_state: D.StateNew[states.LightState],
+        entity_id: D.EntityId,
+    ):
+        friendly_name = new_state.attributes.friendly_name or entity_id
+        await self.api.call_service("notify", "mobile_app_me", message=f"{friendly_name} turned on")
 ```
 
 ### Key Lifecycle Hooks
@@ -103,6 +110,64 @@ config = {threshold = 10, always_send = false}
 **Required fields**: `filename`, `class_name`
 **Optional fields**: `app_dir`, `enabled`, `display_name`, `config`
 
+## Dependency Injection System
+
+**Location**: `src/hassette/dependencies/`
+
+Hassette provides a dependency injection system for event handlers, allowing automatic extraction and injection of event data as handler parameters.
+
+### Key Components
+
+**Files**:
+- `dependencies/__init__.py` - Public API and documentation
+- `dependencies/classes.py` - Dependency marker classes
+- `dependencies/extraction.py` - Signature inspection and extraction logic
+
+**Integration**: The `Bus` resource (`core/resources/bus/bus.py`) uses `extract_from_signature` and `validate_di_signature` to process handler signatures and inject values at runtime.
+
+### Available Dependencies
+
+**State Extractors**:
+- `StateNew` - Extract new state object from state change events
+- `StateOld` - Extract old state object (may be None)
+- `StateOldAndNew` - Extract both states as tuple
+
+**Attribute Extractors**:
+- `AttrNew("attribute_name")` - Extract attribute from new state
+- `AttrOld("attribute_name")` - Extract attribute from old state
+- `AttrOldAndNew("attribute_name")` - Extract from both states
+
+**Value & Identity Extractors**:
+- `EntityId` - Extract entity ID from any event
+- `Domain` - Extract domain (e.g., "light", "sensor")
+- `Service` - Extract service name from service call events
+- `StateValueNew` / `StateValueOld` - Extract state value strings
+- `ServiceData` - Extract service_data dict from service calls
+- `EventContext` - Extract Home Assistant event context
+
+### Usage Pattern
+
+```python
+from typing import Annotated
+from hassette import states
+from hassette import dependencies as D
+
+async def handler(
+    new_state: D.StateNew[states.LightState],
+    brightness: Annotated[int | None, D.AttrNew("brightness")],
+    entity_id: D.EntityId,
+):
+    # Parameters automatically extracted and injected
+    if brightness and brightness > 200:
+        self.logger.info("%s is bright: %d", entity_id, brightness)
+```
+
+### Restrictions
+
+- Handlers cannot use positional-only parameters (before `/`)
+- Handlers cannot use variadic positional args (`*args`)
+- All DI parameters must have type annotations
+
 ## Event Bus Usage
 
 ### Topics and Events
@@ -111,7 +176,7 @@ config = {threshold = 10, always_send = false}
 
 ### Bus Helpers
 ```python
-# State change handlers
+# State change handlers with DI
 self.bus.on_state_change("binary_sensor.motion", handler=self.on_motion, changed_to="on")
 self.bus.on_attribute_change("mobile_device.me", "battery_level", handler=self.on_battery_drop)
 self.bus.on_call_service(domain="light", service="turn_on", handler=self.on_turn_on)

docs/pages/appdaemon-comparison.md

@@ -344,11 +344,57 @@ The event bus is accessed via the `self.bus` attribute. You can cancel a
 subscription using the `Subscription` object returned by the listen
 method, e.g., `subscription.cancel()`.
 
+!!! warning
+    Handlers **cannot** use positional-only parameters (parameters before `/`) or variadic positional arguments (`*args`).
 
-The event object is not a required argument - if you do not need it, simply
-omit it from your handler's signature. If you do include it, ensure it is the
-first unbound argument in your function signature and it is named event (adding
-some dependency injection logic is on the roadmap).
+**Dependency Injection for Handlers**
+
+Hassette supports dependency injection for event handlers, allowing you to extract
+specific data from events without manually accessing the event payload. Use the
+[Annotated][typing.Annotated] type
+hint with dependency markers from [dependencies][hassette.dependencies]:
+
+```python
+from typing import Annotated
+from hassette import App, states
+from hassette import dependencies as D
+from hassette.events import CallServiceEvent
+
+
+class ButtonHandler(App):
+    async def on_initialize(self):
+        # Handler with dependency injection
+        sub = self.bus.on_call_service(
+            service="press",
+            handler=self.minimal_callback,
+            where={"entity_id": "input_button.test_button"},
+        )
+        self.logger.info(f"Subscribed: {sub}")
+
+    # Extract only what you need from the event
+    async def minimal_callback(
+        self,
+        domain: D.Domain,
+        service: D.Service,
+        service_data: D.ServiceData,
+    ) -> None:
+        entity_id = service_data.get("entity_id", "unknown")
+        self.logger.info(f"Button {entity_id} pressed (domain={domain}, service={service})")
+```
+
+Available dependency markers include:
+- `StateNew`, `StateOld` - Extract state objects from state change events
+- `AttrNew("name")`, `AttrOld("name")` - Extract specific attributes
+- `EntityId`, `Domain`, `Service` - Extract identifiers
+- `StateValueNew`, `StateValueOld` - Extract state values (e.g., "on"/"off")
+- `ServiceData`, `EventContext` - Extract service data or event context
+
+You can also receive the full event object if you prefer:
+
+```python
+async def minimal_callback(self, event: CallServiceEvent) -> None:
+    self.logger.info(f"Button pressed: {event.payload.data.service_data}")
+```
 
 
 ```python
@@ -435,11 +481,11 @@ class ButtonPressed(Hass):
 
 State change handlers are the exact same as event handlers - we're only
 calling them out separately to align with AppDaemon. These can also be
-either async or sync functions and accept any arguments - including the event object, if desired.
-The event bus provides helpers for
-filtering entities and attributes. You can also provide additional
-predicates using the `where` parameter. In this example, we listen for
-any state change on the specified entity.
+either async or sync functions. You can receive the full event object or
+use dependency injection to extract only the data you need.
+
+The event bus provides helpers for filtering entities and attributes. You can
+also provide additional predicates using the `where` parameter.
 
 Like other objects, these are typed using Pydantic models -
 `StateChangeEvent` is a
@@ -451,14 +497,43 @@ Currently the repr of a StateChangeEvent is quite verbose, but it does
 show the full old and new state objects, which can be useful for
 debugging. Cleaning this up is on the roadmap.
 
+**With dependency injection** (recommended):
+
+```python
+from typing import Annotated
+from hassette import App, states
+from hassette import dependencies as D
+
+
+class ButtonPressed(App):
+    async def on_initialize(self):
+        sub = self.bus.on_state_change(
+            entity="input_button.test_button",
+            handler=self.button_pressed,
+        )
+        self.logger.info(f"Subscribed: {sub}")
+
+    async def button_pressed(
+        self,
+        new_state: D.StateNew[states.ButtonState],
+        entity_id: D.EntityId,
+    ) -> None:
+        friendly_name = new_state.attributes.friendly_name or entity_id
+        self.logger.info(f"Button {friendly_name} pressed at {new_state.last_changed}")
+```
+
+**With event object**:
+
 ```python
 from hassette import App, StateChangeEvent, states
 
 
 class ButtonPressed(App):
     async def on_initialize(self):
-        # Listen for a button press event with a specific entity_id
-        sub = self.bus.on_state_change(entity="input_button.test_button", handler=self.button_pressed)
+        sub = self.bus.on_state_change(
+            entity="input_button.test_button",
+            handler=self.button_pressed,
+        )
         self.logger.info(f"Subscribed: {sub}")
 
     def button_pressed(self, event: StateChangeEvent[states.ButtonState]) -> None:
@@ -571,11 +646,13 @@ entity will raise a `EntityNotFoundError` exception.
 
 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`. A state cache, similar to
-AppDaemon's, is on the roadmap. When you call
-`set_state()`, it uses the Home Assistant
+using `await`. When you call `set_state()`, it uses the Home Assistant
 REST API to update the state of the entity.
 
+!!! 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.
+
 ```python
 from hassette.models import states