Package: gourd
Gourd - An MQTT frameworkGourd is an opinionated framework for writing MQTT applications.Simple exampleCreate a filegourd_example.py:fromgourdimportGourdapp=Gourd(app_name='my_app',mqtt_host='localhost',mqtt_port=1883,username='mqtt',password='my_password')@app.subscribe('#')defprint_all_messages(message):app.log.info(f'{message.topic}:{message.payload}')Run it:$gourdgourd_example:appFeaturesCreate a fully-functional MQTT app in minutesStatus published to<app_name>/<hostname>/statuswith a Last Will and TestamentDebug logs published to<app_name>/<hostname>/debugUse decorators to associate topics with one or more functionsJSON dictionary payloads automatically decoded tomsg.json.DocumentationInstallationGourd is available on pypi and can be installed with pip:python3 -m pip install gourdAPI ReferenceGourdobjectsTo 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:classGourd: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 argumentsThese are the arguments you should almost always use:mqtt_hostDefault:localhostThe MQTT server to connect tousernameDefault: ``The username to connect to the MQTT server withpasswordDefault: ``The password to connect to the MQTT server withOptional argumentsThese are the arguments that only need to be set if the default behavior does not work for your application:mqtt_portDefault:1883The port number to connect toqosDefault:1Default QOS Level for messagestimeoutDefault:30The timeout for the MQTT connectionlog_mqttDefault:TrueSet to false to disable mqtt logginglog_topicDefault: Generated based on app_name and hostname:{app_name}/{gethostname()}/debugThe MQTT topic to send debug logs tostatus_enabledDefault: ``Set to false to disable the status topicstatus_topicDefault: Generated based app_name and hostname:{app_name}/{gethostname()}/statusThe topic to publish application status (ON/OFF) tostatus_onlineDefault:ONThe payload to publish to status_topic when we are runningstatus_offlineDefault:OFFThe payload to publish to status_topic when we are not runningmax_inflight_messagesDefault:20How many messages can be in-flight. SeePaho MQTT documentationfor more details.max_queued_messagesDefault:0How many messages can be queued at a time. SeePaho MQTT documentationfor more details.message_retry_secDefault:5How long to wait before retrying messages. SeePaho MQTT documentationfor more details.Useful functionsGourd.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'spublish()..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 usinggourd 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.subscribeDecoratorsOnce you've instaniated your gourd object you can use thesubscribedecorator 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.defsubscribe(self,topic):LoggingBy default all logging will be sent to both the console and to thestatus_topicon the MQTT server.Logging to a fileYou can also log to a file withgourd --log-file <path>. There are more ways to control the log output, seegourd --helpfor details.Logging to the MQTT serverBy default your app will log to the topic{app_name}/{gethostname()}/debug. You can disable this behavior by passinglog_mqtt=Falsewhen you instaniateGourd.Sending Log MessagesA logger has been provided for you to use, no setup needed. Just useapp.log.<level>()to log your messages.Last Will and TestamentBy default your app will publish its online status and a LWT to{app_name}/{gethostname()}/status. You can disable this behavior by passingstatus_enabled=Falsewhen instaniatingGourd.Reporting Bugs and Requesting FeaturesPlease let us know about any bugs and/or feature requests you have:https://github.com/clueboard/gourd/issuesContributingContributions 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 .