Metadata-Version: 2.4
Name: ha-mqtt-device
Version: 1.0.1
Summary: Thin library for Home Assistant devices discoverable via MQTT device discovery
Author: jellyhuck
Author-email: jellyhuck <64114609+jellyhuck@users.noreply.github.com>
License-Expression: MIT
Requires-Dist: aiomqtt>=2.3 ; extra == 'mqtt'
Requires-Python: >=3.11
Provides-Extra: mqtt
Description-Content-Type: text/markdown

# ha-mqtt-device

A thin Python library for creating and maintaining [Home Assistant](https://www.home-assistant.io/) devices that are discoverable via [MQTT device discovery](https://www.home-assistant.io/integrations/mqtt/#mqtt-discovery). Individual entities associated with a device can be added, updated, and removed through the same API.

## Features

- **Device discovery**: publish the discovery payload Home Assistant needs to automatically pick up your device over MQTT.
- **Entity management**: add and maintain multiple entities (sensors, switches, lights, binary sensors, dates, datetimes, humidifiers, cameras, device trackers, infrared emitters/receivers, etc.) that belong to a device.
- **Event subscriptions**: entities can subscribe to MQTT topics and deliver updates — for example switch commands from Home Assistant or infrared emitter signals — to your async callbacks as `Event` objects.
- **Thin and focused**: no heavy framework — just the abstractions needed to model a device and its entities.

## Requirements

- Python 3.14+
- [uv](https://docs.astral.sh/uv/) for development and dependency management
- [`aiomqtt`](https://aiomqtt.deroet.com/) for the MQTT provider (`pip install "ha-mqtt-device[mqtt]"`)

## Usage

Runnable examples — for the MQTT provider, device discovery, and every entity
(supported and planned) — can be found in [EXAMPLES.md](EXAMPLES.md).

## Development

This project is managed with `uv`. Common commands:

| Task          | Command                        |
| ------------- | ------------------------------ |
| Run tests     | `uv run pytest`                |
| Format code   | `uv format`                    |
| Lint          | `uv run ruff check`            |
| Type checking | `uv run mypy .`                |
| Build         | `uv build`                     |

### Project layout

```
src/ha_mqtt_device/   # library source
tests/                # test suite
examples/             # runnable entity examples
pyproject.toml        # project metadata and tool configuration
```

## License

[MIT](LICENSE)
