Hassette

A simple, modern, async-first Python framework for building Home Assistant automations.

Documentation: https://hassette.readthedocs.io

✨ Why Hassette?

• 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 FastAPI style dependency injection
• Simple & Focused: Just Home Assistant automations - no complexity creep
• Developer Experience: Clear error messages, proper logging, hot-reloading, and intuitive APIs

🚀 Quick Start

Install Hassette:

pip install hassette

Create a simple app (apps/hello.py):

from typing import Annotated

from hassette import App
from hassette import accessors as A
from hassette import dependencies as D


class HelloWorld(App):
    async def on_initialize(self):
        self.bus.on_state_change("binary_sensor.front_door", handler=self.on_door_open, changed_to="on")

        self.scheduler.run_minutely(self.check_front_door)

    async def on_door_open(
        self,
        entity_id: D.EntityId,
        friendly_name: Annotated[str | None, A.get_attr_new("friendly_name")],
    ):
        self.logger.info("%s opened!", entity_id)
        name = friendly_name or entity_id
        await self.api.call_service("notify", "mobile_app_phone", message=f"{name} opened!")

    async def check_front_door(self):
        state = self.states.binary_sensor["front_door"]
        self.logger.info("Front door is currently %s", state.value)

Configure it (config/hassette.toml):

[hassette]
base_url = "http://homeassistant.local:8123"

[apps.hello]
filename = "hello.py"
class_name = "HelloWorld"

Run it:

uv run hassette

See the Getting Started guide for detailed instructions.

🔄 Coming from AppDaemon?

Check out our dedicated comparison guide:

• AppDaemon Comparison

📖 More Examples

Check out the examples/ directory for complete working examples:

Based on AppDaemon's examples:

• Battery monitoring - Monitor device battery levels
• Presence detection - Track who's home
• Sensor notifications - Alert on sensor changes

Real-world apps:

• Office Button App - Multi-function button handler
• Laundry Room Lights - Motion-based lighting

Configuration examples:

• Docker Compose Guide - Docker deployment setup
• HassetteConfig - Complete configuration reference

🛣️ Status & Roadmap

Hassette is under active development. We follow semantic versioning and recommend pinning a minor version (e.g., hassette~=0.x.0) while the API stabilizes.

Development is tracked in our GitHub project. Open an issue or PR if you'd like to contribute!

What's Next?

• 🔐 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())
• 🔄 Enhanced error handling - Better retry logic and error recovery
• 🧪 Testing improvements - More comprehensive test coverage and user app testing framework

🤝 Contributing

Contributions are welcome! Whether you're:

• 🐛 Reporting bugs or issues
• 💡 Suggesting features or improvements
• 📝 Improving documentation
• 🔧 Contributing code

See CONTRIBUTING.md for guidelines on getting started.

📄 License

MIT