An opinionated framework for writing MQTT applications.
Project description
Gourd - An MQTT framework
Gourd is an opinionated framework for writing MQTT applications.
Simple example
Create a file gourd_example.py
:
from gourd import Gourd
app = Gourd(app_name='my_app', mqtt_host='localhost', mqtt_port=1883, username='mqtt', password='my_password')
@app.subscribe('#')
def print_all_messages(message):
app.log.info(f'{message.topic}: {message.payload}')
Run it:
$ gourd gourd_example: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 functions
- JSON dictionary payloads automatically decoded to
msg.json
.
Documentation
Installation
Gourd is available on pypi and can be installed with pip:
python3 -m pip install gourd
API Reference
Gourd
objects
To create your app you'll need an instance of the Gourd class. Unless your MQTT server is running on your local machine with no authentication you'll need to pass in some arguments:
class Gourd:
def __init__(self, app_name, *, mqtt_host='localhost', mqtt_port=1883, username='', password='', qos=1, timeout=30, log_mqtt=True, log_topic=None, status_enabled=True, status_topic=None, status_online='ON', status_offline='OFF', max_inflight_messages=20, max_queued_messages=0, message_retry_sec=5):
Recommended arguments
These are the arguments you should almost always use:
- mqtt_host
- Default:
localhost
- The MQTT server to connect to
- Default:
- username
- Default: ``
- The username to connect to the MQTT server with
- password
- Default: ``
- The password to connect to the MQTT server with
Optional arguments
These are the arguments that only need to be set if the default behavior does not work for your application:
- mqtt_port
- Default:
1883
- The port number to connect to
- Default:
- qos
- Default:
1
- Default QOS Level for messages
- Default:
- timeout
- Default:
30
- The timeout for the MQTT connection
- Default:
- log_mqtt
- Default:
True
- Set to false to disable mqtt logging
- Default:
- log_topic
- Default: Generated based on app_name and hostname:
{app_name}/{gethostname()}/debug
- The MQTT topic to send debug logs to
- Default: Generated based on app_name and hostname:
- status_enabled
- Default: ``
- Set to false to disable the status topic
- status_topic
- Default: Generated based app_name and hostname:
{app_name}/{gethostname()}/status
- The topic to publish application status (ON/OFF) to
- Default: Generated based app_name and hostname:
- status_online
- Default:
ON
- The payload to publish to status_topic when we are running
- Default:
- status_offline
- Default:
OFF
- The payload to publish to status_topic when we are not running
- Default:
- max_inflight_messages
- Default:
20
- How many messages can be in-flight. See Paho MQTT documentation for more details.
- Default:
- max_queued_messages
- Default:
0
- How many messages can be queued at a time. See Paho MQTT documentation for more details.
- Default:
- message_retry_sec
- Default:
5
- How long to wait before retrying messages. See Paho MQTT documentation for more details.
- Default:
Useful functions
Gourd.publish(topic, payload=None, *, qos=None, **kwargs)
This function will let you publish messages to MQTT. You can delete a retained message by passing a payload of None.
All kwargs are passed directly to PaHo MQTT's publish()
..
Gourd.loop_start()
This function will kick off Gourd in a separate thread, useful when you need to do something else in the main thread.
Normally you do not need to use this, you will run your program using gourd my_module:my_app
. However, if you need to control the main thread instead of gourd this function will spawn a separate thread for gourd to run in.
subscribe
Decorators
Once you've instaniated your gourd object you can use the subscribe
decorator to subscribe to a topic. This will both subscribe to the specified topic and register your function to be called when a message for that topic is received. You can register multiple functions for the same topic and they will be called in the order they were registered.
def subscribe(self, topic):
Logging
By default all logging will be sent to both the console and to the status_topic
on the MQTT server.
Logging to a file
You can also log to a file with gourd --log-file <path>
. There are more ways to control the log output, see gourd --help
for details.
Logging to the MQTT server
By default your app will log to the topic {app_name}/{gethostname()}/debug
. You can disable this behavior by passing log_mqtt=False
when you instaniate Gourd
.
Sending Log Messages
A logger has been provided for you to use, no setup needed. Just use app.log.<level>()
to log your messages.
Last Will and Testament
By default your app will publish its online status and a LWT to {app_name}/{gethostname()}/status
. You can disable this behavior by passing status_enabled=False
when instaniating Gourd
.
Reporting Bugs and Requesting Features
Please let us know about any bugs and/or feature requests you have: https://github.com/clueboard/gourd/issues
Contributing
Contributions are welcome! You don't need to open an issue first, if you've developed a new feature or fixed a bug in Gourd simply open a PR and we'll review it.
Please follow this checklist before submitting a PR:
- Format your code:
yapf -i -r .
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
Built Distribution
Hashes for gourd-0.1.3-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | d00325d1717ce9405ed4fde0b166f2a6163308f820de98337d9fce776e4a9be1 |
|
MD5 | 628c39a4aeff7faeb5fef9e8c31d656b |
|
BLAKE2b-256 | cb225e40a2482c98cae6a3fd658d4ae0d6db20dc573335cfec8ee03f90f97146 |