Gourd

Gourd is an opinionated Python framework for writing MQTT applications. It handles connection management, status reporting, and logging so you can focus on your application logic.

Quick Start

Install with pip:

pip install gourd

Create my_app.py:

from gourd import Gourd

app = Gourd(app_name='my_app', mqtt_host='localhost')

@app.subscribe('#')
def print_all(message):
    app.log.info(f'{message.topic}: {message.payload}')

Run it:

gourd my_app:app

Features

• Create a fully-functional MQTT app in minutes
• Status published to <app_name>/<hostname>/status with a Last Will and Testament
• Debug logs published to <app_name>/<hostname>/debug
• Use decorators to associate topics with one or more handler functions
• JSON dictionary payloads automatically decoded to msg.json

Documentation

• Getting Started — prerequisites, your first app, and what Gourd does automatically
• Configuration — all Gourd() constructor arguments
• API Reference — subscribe, publish, GourdMessage, and more
• Examples — copy-paste patterns for common tasks
• Upgrading — migration guide for breaking changes