mqttwrapper 0.2.0__py3-none-any.whl

mqttwrapper/__init__.py

@@ -0,0 +1 @@
+from .paho_backend import run_script

mqttwrapper/hbmqtt_backend.py

@@ -0,0 +1,43 @@
+import os
+import logging
+import asyncio
+from warnings import warn
+
+from hbmqtt.client import MQTTClient, ClientException
+from hbmqtt.mqtt.constants import QOS_0
+
+log = logging.getLogger("mqttwrapper.hbmqtt_backend")
+
+warn("hbmqtt backend is deprecated and will be removed in the future.", DeprecationWarning)
+log.warn("hbmqtt backend is deprecated and will be removed in the future.")
+
+async def mqtt_loop(broker, topics, callback, context_callback, **kwargs):
+    if context_callback is not None:
+        kwargs.update(await context_callback())
+    client = MQTTClient()
+    await client.connect(broker, cleansession=True)
+    log.debug("Connected")
+    await client.subscribe([(topic, QOS_0) for topic in topics])
+    log.debug("Subscribed to %s", topics)
+    try:
+        while True:
+            message = await client.deliver_message()
+            packet = message.publish_packet
+            topic = packet.variable_header.topic_name
+            payload = bytes(packet.payload.data)
+            replies = await callback(topic, payload, **kwargs)
+            if replies is not None:
+                for reply_topic, reply_payload in replies:
+                    await client.publish(reply_topic, reply_payload)
+    except ClientException:
+        log.exception("hbmqtt.client.ClientException:")
+        raise
+
+
+def run_script(callback, broker=None, topics=None, context_callback=None, **kwargs):
+    if not broker:
+        broker = os.environ['MQTT_BROKER']
+    if not topics:
+        topics = os.environ['MQTT_TOPICS'].split(",")
+
+    asyncio.get_event_loop().run_until_complete(mqtt_loop(broker, topics, callback, context_callback, **kwargs))

mqttwrapper/paho_backend.py

@@ -0,0 +1,64 @@
+import os
+import logging
+import paho.mqtt.client as mqtt
+import threading
+
+log = logging.getLogger("mqttwrapper.paho_backend")
+
+def on_connect(client, userdata, flags, rc):
+    log.debug("Connected")
+    for topic in userdata['topics']:
+        client.subscribe(topic)
+        log.debug("Subscribed to %s", topic)
+
+def on_message(client, userdata, msg):
+    log.debug("Received message on %s", msg.topic)
+    if msg.retain and userdata['ignore_retained']:
+        log.debug("Ignoring retained message")
+        return
+    replies = None
+    try:
+        replies = userdata['callback'](msg.topic, msg.payload, **userdata['kwargs'])
+    except Exception as e:
+        log.error("Callback caused exception", exc_info = True)
+    log.debug("Callback completed.")
+    if replies is not None:
+        replies = list(replies)
+        log.debug("Received %s replies", len(replies))
+        for reply in replies:
+            try:
+                topic, payload, retain = reply
+            except ValueError:
+                topic, payload = reply
+                retain = False
+            log.debug("Publishing '%s' to %s (retain: %s)", payload, topic, retain)
+            client.publish(topic, payload, retain=retain)
+            log.debug("Published '%s' to %s (retain: %s)", payload, topic, retain)
+
+def mqtt_thread(client):
+    client.loop_forever()
+
+def run_script(callback, broker=None, topics=None, ignore_retained=False, blocking=True, **kwargs):
+    if not broker:
+        broker = os.environ['MQTT_BROKER']
+    if not topics:
+        topics = os.environ['MQTT_TOPICS'].split(",")
+
+    userdata = {
+        'topics': topics,
+        'callback': callback,
+        'ignore_retained': ignore_retained,
+        'kwargs': kwargs
+    }
+
+    client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION1, userdata=userdata)
+    client.on_connect = on_connect
+    client.on_message = on_message
+    if "//"  in broker: # mqtt:// prefix is optional (NB mqtts:// is not supported)
+        broker = broker.split("//")[1]
+    client.connect(broker)
+    if blocking:
+        client.loop_forever()
+    else:
+        t = threading.Thread(target=mqtt_thread, args=(client,), daemon=True)
+        t.start()

mqttwrapper/run.py

@@ -0,0 +1,11 @@
+import sys
+
+from .paho_backend import run_script
+
+if __name__ == "__main__":
+    try:
+        from callback import callback
+        run_script(callback)
+    except ImportError:
+        print("""Couldn't import callback function from callback module.
+Please ensure there is a function called 'callback' defined in a file called callback.py in the current directory.""", file=sys.stderr)

mqttwrapper-0.2.0.dist-info/METADATA

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: mqttwrapper
+Version: 0.2.0
+Summary: MQTT utility scripts made easy
+Home-page: https://github.com/davea/mqttwrapper
+Author: Dave Arter
+Author-email: pypi@davea.me
+License: MIT
+Keywords: mqtt
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.5
+Classifier: Programming Language :: Python :: 3.6
+Classifier: Programming Language :: Python :: 3.7
+License-File: LICENSE
+Requires-Dist: paho-mqtt>=2.0.0
+Provides-Extra: hbmqtt
+Requires-Dist: hbmqtt; extra == "hbmqtt"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: summary
+
+mqttwrapper
+===========
+
+A little glue package to make it simple to quickly put together scripts that
+bridge MQTT and other libraries. See examples below.
+
+Installation
+------------
+
+Install from PyPI::
+
+  $ pip install mqttwrapper
+
+By default ``paho-mqtt`` will be used as the MQTT library, but you can use
+``hbmqtt`` if you wish, though support for this is deprecated and will be
+removed in the future. To install, use::
+
+  $ pip install mqttwrapper[hbmqtt]
+
+Usage
+-----
+
+``mqttwrapper.run_script`` handles the setup/maintenance of the MQTT connection
+and subscriptions to topics, and calls a callback function when messages are
+received. It can run in blocking mode where it will take care of the MQTT
+client handling or in non blocking mode where a new thread takes care this
+leaving your main thread free for other things.
+
+The simplest script looks something like this::
+
+  from mqttwrapper import run_script
+
+  def callback(topic, payload):
+      print("Received payload {} on topic {}".format(payload, topic))
+
+  def main():
+      run_script(callback, broker="mqtt://127.0.0.1", topics=["my/awesome/topic1", "another/awesome/topic2"])
+
+or in non blocking mode::
+
+  def main():
+      run_script(callback, broker="mqtt://127.0.0.1", topics=["my/awesome/topic1", "another/awesome/topic2"], blocking=False)
+      while True:
+          echo "Alive and kicking"
+          time.sleep(1)
+
+Any extra keyword arguments passed to ``run_script`` are passed back to the
+callback function when it's called::
+
+  from mqttwrapper import run_script
+
+  def callback(topic, payload, context, foo):
+      assert context == "hello"
+      assert foo == "bar"
+      print("Received payload {} on topic {}".format(payload, topic))
+
+  def main():
+      run_script(callback, broker="mqtt://127.0.0.1", topics=["my/awesome/topic1", "another/awesome/topic2"], context="hello", foo="bar")
+
+
+If you don't need any context passed to your callback, just the topic and
+payload of messages, you can run in 'importless' mode by creating a `callback`
+module which has a `callback` function defined, then execute the
+`mqttwrapper.run` module::
+
+  $ cat callback.py
+  def callback(topic, payload):
+      print(topic, payload)
+  
+  $ python -m mqttwrapper.run
+
+Retained messages
+-----------------
+
+You can ignore MQTT retained messages by passing ``ignore_retained=True`` when
+calling ``run_script``. NB this is currently not supported by the hbmqtt
+backend.
+
+Publishing messages from the callback
+-------------------------------------
+
+Sometimes your callback function might want to publish its own MQTT messages,
+perhaps in reply to or an acknowledgement of a received message. This is
+possible by returning an iterable of ``(topic, payload)`` tuples from the callback,
+e.g.::
+
+    def callback(topic, payload):
+      print("Received payload {} on topic {}".format(payload, topic))
+      return [
+        ("{}/ack".format(topic), payload)
+      ]
+
+
+``mqttwrapper`` will take care of publishing these messages to the broker.
+
+These tuples can optionally take the form ``(topic, payload, True)`` if you want
+the published message to be marked as retained.
+
+Configuration
+-------------
+
+``broker`` and ``topics`` can be omitted from the ``run_script`` call and
+environment variables used instead:
+
+- ``MQTT_BROKER``: MQTT broker to connect to, e.g. ``mqtt://127.0.0.1/``
+- ``MQTT_TOPICS``: Comma-separated list of topics to subscribe to, e.g. ``my/topic1,my/topic2``
+
+asyncio/hbmqtt
+--------------
+
+NB This feature is deprecated and will be removed in the future.
+
+The asyncio-powered ``hbmqtt`` MQTT library can be used instead, if you like::
+
+  from mqttwrapper.hbmqtt_backend import run_script
+
+  async def callback(topic, payload):
+      print("Received payload {} on topic {}".format(payload, topic))
+
+
+Note that your callback must be an awaitable in this case.
+
+Your callback may require context arguments which themselves are async objects
+or awaitables which poses a challenge: how to set these up outside of an asyncio
+event loop before calling ``run_script``? In this case, you can pass a
+``context_callback`` awaitable as a kwarg to ``run_script``. This is run at the
+start of the MQTT loop, and should return a dict which will be merged into the
+kwargs which are passed to your callback. For example::
+
+  from mqttwrapper.hbmqtt_backend import run_script
+
+  async def setup_db():
+    return {
+      "query_db": query_db
+    }
+
+  async def query_db(value):
+    # pretend this is some slow DB query, for example.
+    await asyncio.sleep(3)
+    return value * 2
+
+  async def callback(topic, payload, query_db):
+      db_result = await query_db(int(payload))
+      print("Received payload {} on topic {}, db result: {}".format(payload, topic, db_result))
+
+  def main():
+      run_script(callback, context_callback=setup_db)
+
+
+NB hbmqtt's reconnection handling does not resubscribe to topics upon
+reconnection, and ``mqttwrapper`` does not yet work around this.
+
+Examples
+--------
+
+- rxv2mqtt_
+- tradfri-mqtt_ (uses asyncio)
+
+.. _rxv2mqtt: https://github.com/davea/rxv2mqtt/blob/master/main.py
+.. _tradfri-mqtt: https://github.com/davea/tradfri-mqtt/blob/master/main.py

mqttwrapper-0.2.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+mqttwrapper/__init__.py,sha256=Hm2aRNZ--y78D7ec7IGQCHk_Zf-VE1sF4p0FnRkHokw,37
+mqttwrapper/hbmqtt_backend.py,sha256=mmDx2pT4fNrwcvu0CQ86X00kP26KyUAcHkm9h7YZz-4,1648
+mqttwrapper/paho_backend.py,sha256=_QKY88_j_dW3rOlHI7Xe3IeTpiPiysFJXz0znhG68CU,2183
+mqttwrapper/run.py,sha256=0ulC7Z6B-EDUDgFx3oYncRrmNlLB2y0o7j1EDmYPmiA,386
+mqttwrapper-0.2.0.dist-info/licenses/LICENSE,sha256=uWqObWrb6MDtetS3K8TmVXuB0w0lSKXSA4ByGm6Fy00,1067
+mqttwrapper-0.2.0.dist-info/METADATA,sha256=pRoUv_3e-Hz7YoBh2GnwbJDyAgdWX4oOe7V_0sBIigg,6095
+mqttwrapper-0.2.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+mqttwrapper-0.2.0.dist-info/top_level.txt,sha256=Jqxgldb4d5BWTJir7PIzTe5lYpDHx_MinoDnnECwMCw,12
+mqttwrapper-0.2.0.dist-info/RECORD,,

mqttwrapper-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mqttwrapper-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 Dave Arter
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mqttwrapper-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+mqttwrapper