Metadata-Version: 2.4
Name: nirahmq
Version: 0.1.2a0
Summary: A Home Assistant MQTT client library
Project-URL: Homepage, https://github.com/dionisis2014/nirahmq
Project-URL: Source, https://github.com/dionisis2014/nirahmq
Project-URL: Download, https://github.com/dionisis2014/nirahmq/releases
Project-URL: Documentation, https://github.com/dionisis2014/nirahmq
Project-URL: Issues, https://github.com/dionisis2014/nirahmq/issues
Author-email: Dionisis Toulatos <toulatosdionisis@gmail.com>
Maintainer-email: Dionisis Toulatos <toulatosdionisis@gmail.com>
License-Expression: AGPL-3.0-or-later
License-File: LICENSE
Keywords: home assistant,mqtt,mqtt client,mqtt discovery
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Pydantic
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Natural Language :: English
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications
Classifier: Topic :: Home Automation
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Requires-Dist: paho-mqtt
Requires-Dist: pydantic
Provides-Extra: docs
Requires-Dist: furo; extra == 'docs'
Requires-Dist: sphinx; extra == 'docs'
Requires-Dist: sphinx-copybutton; extra == 'docs'
Requires-Dist: sphinx-multiversion; extra == 'docs'
Description-Content-Type: text/markdown

# NirahMQ

A complete Home Assistant MQTT Python library with ease of use in mind

> [!WARNING]
> This library is currently in ALPHA! Expect things to change or break!

## ✨ Features

- Supports all Home Assistant MQTT components and all their features
- Use of device-based discovery instead of component-based for simpler organization
- Support for automatic cleanup of topics on exit
- Device wide and per component availability support
- MQTT birth and last will support for both device and Home Assistant
- Ease of use by simple static definitions, while allowing runtime modifications
- Full Python type hint support
- Validation of definitions and user inputs on load thanks to [pydantic](https://github.com/pydantic/pydantic)
- Extensible API through simple class inheritance

## 📦 Installation

NirahMQ requires Python 3.12 or later and can be installed simply with `pip install nirahmq`.

## 🚀 Simple example

Below is an example of a simple Text component that prints its contents on update:

<details>
<summary>Example code</summary>

```python
from nirahmq.components import Text
from nirahmq.device import Device, DeviceInfo, DiscoveryInfo, OriginInfo
from nirahmq.mqtt import MQTTClient


def callback(text: Text, payload: str) -> None:
    print(f"Got new text: `{payload}`")
    text.set_text(payload)


dinfo = DiscoveryInfo(
    device=DeviceInfo(
        name="NirahMQ Test Device",
        identifiers="NirahMQ-Test-Device"
    ),
    origin=OriginInfo(
        name="Python Program"
    ),
    components={
        'component1': Text(command_topic="~/cmd", state_topic="~/state", command_callback=callback)
    }
)

with (MQTTClient("homeassistant.lan", 1883, "user", r"password") as client,
      Device(client, dinfo, "node_id") as device):
    input("Press enter to continue...\n")
```
</details>

## 📝 License
Copyright © 2025 [Dionisis Toulatos](https://github.com/dionisis2014)

NirahMQ uses the [AGPL-3.0+](LICENSE) license
