Metadata-Version: 2.4
Name: amgi-paho-mqtt
Version: 0.49.0
Summary: AMGI MQTT Server
Author: jack.burridge
Author-email: jack.burridge <jack.burridge@mail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: amgi-common==0.49.0
Requires-Dist: amgi-types==0.49.0
Requires-Dist: paho-mqtt>=2.1.0
Requires-Dist: typing-extensions>=4.15.0 ; python_full_version < '3.11'
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# amgi-paho-mqtt

amgi-paho-mqtt is an [AMGI](https://amgi.readthedocs.io/en/latest/) compatible server to run AMGI applications against
[MQTT](https://mqtt.org/).

## Installation

```
pip install amgi-paho-mqtt==0.49.0
```

## Example

This example uses [AsyncFast](https://pypi.org/project/asyncfast/):

```python
from dataclasses import dataclass

from amgi_paho_mqtt import run
from asyncfast import AsyncFast

app = AsyncFast()


@dataclass
class Order:
    item_ids: list[str]


@app.channel("order-topic")
async def order_topic(order: Order) -> None:
    # Makes an order
    ...


if __name__ == "__main__":
    run(app, "order-topic")
```

Or the application could be run via the commandline:

```commandline
asyncfast run amgi-paho-mqtt main:app order-topic
```

## Sending Messages

Messages can be sent from the application via the `message.send` event. The `mqtt` binding of the event controls the
send:

```python
await send(
    {
        "type": "message.send",
        "address": "order-topic",
        "headers": [(b"trace-id", b"abc123")],
        "payload": b"payload",
        "bindings": {"mqtt": {"qos": 1, "retain": False}},
    }
)
```

`qos` sets the MQTT QoS level (defaults to `0`), and `retain` marks the message as retained (defaults to `False`). With
MQTT v5, message headers are sent as user properties, with `content-type` mapped to the MQTT content type property.
MQTT v3.1.1 has no way to represent headers, so they are dropped.

## Contact

For questions or suggestions, please contact [jack.burridge@mail.com](mailto:jack.burridge@mail.com).

## License

Copyright 2025 AMGI
