asyncio-mqtt 0.4.0

Idomatic asyncio wrapper around paho-mqtt.

MQTT client with idiomatic asyncio interface 🙌

Write code like this:

async with Client('test.mosquitto.org') as client:
    await client.subscribe('floors/#')

    async with client.filtered_messages('floors/+/humidity') as messages:
        async for message in messages:
            print(message.payload.decode())

asyncio-mqtt combines the stability of the time-proven paho-mqtt library with a modern, asyncio-based interface.

• No more callbacks! 👍
• No more return codes (welcome to the MqttError)
• Graceful disconnection (forget about on_unsubscribe, on_disconnect, etc.)
• Compatible with async code
• Did we mention no more callbacks?

The whole thing is less than 250 lines of code.

Installation 📚

pip install asyncio-mqtt

Advanced use ⚡

Let's make the example from before more interesting:

import asyncio
from random import randrange
from asyncio_mqtt import Client

async def log_filtered_messages(client, topic_filter):
    async with client.filtered_messages(topic_filter) as messages:
        async for message in messages:
            print(f'[topic_filter="{topic_filter}"]: {message.payload.decode()}')

async def log_unfiltered_messages(client):
    async with client.unfiltered_messages() as messages:
        async for message in messages:
            print(f'[unfiltered]: {message.payload.decode()}')

async def main():
    async with Client('test.mosquitto.org') as client:
        await client.subscribe('floors/#')

        # You can create any number of message filters
        asyncio.create_task(log_filtered_messages(client, 'floors/+/humidity'))
        asyncio.create_task(log_filtered_messages(client, 'floors/rooftop/#'))
        # 👉 Try to add more filters!

        # All messages that doesn't match a filter will get logged here
        asyncio.create_task(log_unfiltered_messages(client))

        # Publish a random value to each of these topics
        topics = [
            'floors/basement/humidity',
            'floors/rooftop/humidity',
            'floors/rooftop/illuminance',
            # 👉 Try to add more topics!
        ]
        while True:
            for topic in topics:
                message = randrange(100)
                print(f'[topic="{topic}"] Publishing message={message}')
                await client.publish(topic, message, qos=1)
                await asyncio.sleep(2)

asyncio.run(main())

Alternative asyncio-based MQTT clients

Is asyncio-mqtt not what you are looking for? Try another client:

• hbmqtt - Own protocol implementation. Includes a broker.
  
• gmqtt - Own protocol implementation. No dependencies.
  
• aiomqtt - Wrapper around paho-mqtt.
  
• mqttools - Own protocol implementation. No dependencies.
  
• aio-mqtt - Own protocol implementation. No dependencies.
  

This is not an exhaustive list.

Honorable mentions

• trio-paho-mqtt - Trio-based. Wrapper around paho-mqtt.
  

Requirements

Python 3.7 or later.

There is only a single dependency:

• paho-mqtt
  

Changelog

Please refer to the CHANGELOG document. It adheres to the principles of Keep a Changelog.

Versioning

This project adheres to Semantic Versioning.

Expect API changes until we reach version 1.0.0. After 1.0.0, breaking changes will only occur in major release (e.g., 2.0.0, 3.0.0, etc.).

License

Note that the underlying paho-mqtt library is dual-licensed. One of the licenses is the so-called Eclipse Distribution License v1.0. It is almost word-for-word identical to the BSD 3-clause License. The only differences are:

• One use of "COPYRIGHT OWNER" (EDL) instead of "COPYRIGHT HOLDER" (BSD)
• One use of "Eclipse Foundation, Inc." (EDL) instead of "copyright holder" (BSD)