philiprehberger-mqtt-client

Simplified MQTT pub/sub wrapper with auto-reconnect.

Installation

pip install philiprehberger-mqtt-client

Usage

Basic Pub/Sub

from philiprehberger_mqtt_client import MQTTClient

client = MQTTClient("mqtt://localhost:1883", client_id="my-app")

@client.on("home/temperature")
def on_temperature(topic, payload):
    print(f"Temperature: {float(payload)}C")

@client.on("home/+/status")  # wildcard
def on_device_status(topic, payload):
    device = topic.split("/")[1]
    print(f"{device}: {payload}")

# Publish
client.publish("home/lights/living", "on")
client.publish_json("home/sensors/data", {"temp": 22.5, "humidity": 45})

# Connect (blocks with auto-reconnect)
client.connect()

# Or background mode
client.connect(background=True)

Batch publishing

Publish multiple messages with shared QoS and retain flags in a single call.

client.publish_many(
    [
        ("home/lights/living", "on"),
        ("home/lights/kitchen", "off"),
        ("home/lights/bedroom", "on"),
    ],
    qos=1,
    retain=True,
)

Offline Message Queue

Messages published while disconnected are automatically queued and sent when the connection is re-established.

client = MQTTClient("mqtt://localhost:1883", offline_queue_size=500)

# These are queued if not yet connected
client.publish("sensors/temp", "22.5")
client.publish_json("sensors/data", {"humidity": 45})

# Check queue status
print(f"Pending messages: {client.pending_count()}")

# Connect — queued messages are flushed automatically
client.connect(background=True)

# Discard queued messages if needed
client.clear_queue()

API

Development

pip install -e .
python -m pytest tests/ -v

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT