Metadata-Version: 2.4
Name: mqtt-entity
Version: 1.1.3
Summary: MQTT client supporting Home Assistant MQTT entity auto-discovery
Keywords: asyncio,discovery,home-assistant,library,mqtt
Author: Johann Kellerman
Author-email: Johann Kellerman <kellerza@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: aiohttp>3.12,<4
Requires-Dist: cattrs>=25,<27
Requires-Dist: colorlog
Requires-Dist: paho-mqtt>=2.1,<3
Requires-Dist: pyyaml>=6,<7 ; extra == 'options'
Requires-Python: >=3.12
Project-URL: Homepage, https://github.com/kellerza/mqtt_entity
Provides-Extra: options
Description-Content-Type: text/markdown

# MQTT Entity helper library for Home Assistant

[![Workflow Status](https://github.com/kellerza/mqtt_entity/actions/workflows/main.yml/badge.svg?branch=master)](https://github.com/kellerza/mqtt_entity/actions)
[![codecov](https://codecov.io/gh/kellerza/mqtt_entity/branch/main/graph/badge.svg?token=PG4N1YBUGW)](https://codecov.io/gh/kellerza/mqtt_entity)

A Python helper library to manage Home Assistant entities over MQTT.

Updated for device based MQTT discovery.

Features:

- MQTT client based on paho-mqtt
  - Retrieve MQTT service info from the Home Assistant Supervisor
- Manage MQTT discovery info (adding/removing entities)
- MQTTDevice class to manage devices
  - Availability management
  - Manage entities per device
- Home Assistant Entities modelled as dataclasses:
  - Read-only: Sensor, BinarySensor
  - Read & write: Select, Switch, Number, Text, Light
  - MQTT device events
- Asyncio based
- Helpers for Home Assistant add-ons (optional)
  - Add-on configuration modeled as dataclasses
    - Load from environment variables, HA's options.yaml or options.json
    - Load MQTT connection settings from the Supervisor
  - Enable add-on logging (incl colors & debug by config)

## Why?

This MQTT code was included in several of my home Assistant addons (SMA-EM / Sunsynk). It is easier to update a single library & add new features, like discovery removal.

Alternative options (not based on asyncio)

- <https://pypi.org/project/ha-mqtt-discoverable/>
- <https://pypi.org/project/homeassistant-mqtt-binding/>

## Credits

@Ivan-L contributed some of the writable entities to the Sunsynk addon project

## Release

Semantic versioning is used for release.

To create a new release, include a commit with a :dolphin: emoji as a prefix in the commit message. This will trigger a release on the master branch.

```bash
# Patch
git commit -m ":dolphin: Release 0.0.x"

# Minor - any commit
```

### Development

To run the tests, you need to have Python 3.12+ installed.

The `--mqtt` connects to a live Home Assistant instance using the MQTT broker.

```bash
uv run pytest --mqtt
```
