mqttwrapper 0.2.0__tar.gz → 0.3.0__tar.gz

{mqttwrapper-0.2.0 → mqttwrapper-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mqttwrapper
-Version: 0.2.0
+Version: 0.3.0
 Summary: MQTT utility scripts made easy
 Home-page: https://github.com/davea/mqttwrapper
 Author: Dave Arter
@@ -17,8 +17,6 @@ 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
@@ -27,7 +25,6 @@ Dynamic: home-page
 Dynamic: keywords
 Dynamic: license
 Dynamic: license-file
-Dynamic: provides-extra
 Dynamic: requires-dist
 Dynamic: summary
 
@@ -44,11 +41,7 @@ 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]
+``paho-mqtt`` is used as the underlying MQTT library.
 
 Usage
 -----
@@ -77,7 +70,7 @@ or in non blocking mode::
           echo "Alive and kicking"
           time.sleep(1)
 
-Any extra keyword arguments passed to ``run_script`` are passed back to the
+Most extra keyword arguments passed to ``run_script`` are passed back to the
 callback function when it's called::
 
   from mqttwrapper import run_script
@@ -91,6 +84,18 @@ callback function when it's called::
       run_script(callback, broker="mqtt://127.0.0.1", topics=["my/awesome/topic1", "another/awesome/topic2"], context="hello", foo="bar")
 
 
+However some are reserved and will be consumed by ```run_script``` to configure how the MQTT connection behaves:
+
+
+- ``broker`` (default ``MQTT_BROKER`` from environment, otherwise ``None``): broker URL, e.g ``mybroker``, ``mqtts://securebroker:8884``, ``mqtt://username:password@coolbroker.example.org``
+- ``topics`` (default ``MQTT_TOPICS`` from environment, otherwise ``None``): list of topics to subscribe to
+- ``ignore_retained`` (default ``False``): whether to ignore a received message if it was marked as retained
+- ``blocking`` (default ``True``): run in blocking or threaded mode
+- ``client_id`` (default ``"",``): client ID to use when connecting to broker
+- ``clean_session`` (default ``True``): whether to use a clean session upon (re)connect, or resume previous session. ``client_id`` must be provided if ``True``
+- ``qos`` (default ``0``): QoS to use for connection
+- ``raise_exceptions`` (default ``False``): whether to raise exceptions that occur during callback execution
+
 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
@@ -106,8 +111,7 @@ 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.
+calling ``run_script``.
 
 Publishing messages from the callback
 -------------------------------------
@@ -129,6 +133,8 @@ e.g.::
 These tuples can optionally take the form ``(topic, payload, True)`` if you want
 the published message to be marked as retained.
 
+NB any exceptions raised during execution of the callback will be logged and ignored, unless ``raise_exceptions=True`` is passed to ``run_script``.
+
 Configuration
 -------------
 
@@ -138,56 +144,10 @@ 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 → mqttwrapper-0.3.0}/README.rst

@@ -11,11 +11,7 @@ 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]
+``paho-mqtt`` is used as the underlying MQTT library.
 
 Usage
 -----
@@ -44,7 +40,7 @@ or in non blocking mode::
           echo "Alive and kicking"
           time.sleep(1)
 
-Any extra keyword arguments passed to ``run_script`` are passed back to the
+Most extra keyword arguments passed to ``run_script`` are passed back to the
 callback function when it's called::
 
   from mqttwrapper import run_script
@@ -58,6 +54,18 @@ callback function when it's called::
       run_script(callback, broker="mqtt://127.0.0.1", topics=["my/awesome/topic1", "another/awesome/topic2"], context="hello", foo="bar")
 
 
+However some are reserved and will be consumed by ```run_script``` to configure how the MQTT connection behaves:
+
+
+- ``broker`` (default ``MQTT_BROKER`` from environment, otherwise ``None``): broker URL, e.g ``mybroker``, ``mqtts://securebroker:8884``, ``mqtt://username:password@coolbroker.example.org``
+- ``topics`` (default ``MQTT_TOPICS`` from environment, otherwise ``None``): list of topics to subscribe to
+- ``ignore_retained`` (default ``False``): whether to ignore a received message if it was marked as retained
+- ``blocking`` (default ``True``): run in blocking or threaded mode
+- ``client_id`` (default ``"",``): client ID to use when connecting to broker
+- ``clean_session`` (default ``True``): whether to use a clean session upon (re)connect, or resume previous session. ``client_id`` must be provided if ``True``
+- ``qos`` (default ``0``): QoS to use for connection
+- ``raise_exceptions`` (default ``False``): whether to raise exceptions that occur during callback execution
+
 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
@@ -73,8 +81,7 @@ 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.
+calling ``run_script``.
 
 Publishing messages from the callback
 -------------------------------------
@@ -96,6 +103,8 @@ e.g.::
 These tuples can optionally take the form ``(topic, payload, True)`` if you want
 the published message to be marked as retained.
 
+NB any exceptions raised during execution of the callback will be logged and ignored, unless ``raise_exceptions=True`` is passed to ``run_script``.
+
 Configuration
 -------------
 
@@ -105,56 +114,10 @@ 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 → mqttwrapper-0.3.0}/mqttwrapper/paho_backend.py

@@ -1,16 +1,23 @@
-import os
 import logging
-import paho.mqtt.client as mqtt
+import os
 import threading
+from urllib.parse import urlsplit
+
+import paho.mqtt.client as mqtt
 
 log = logging.getLogger("mqttwrapper.paho_backend")
 
 def on_connect(client, userdata, flags, rc):
     log.debug("Connected")
     for topic in userdata['topics']:
-        client.subscribe(topic)
+        client.subscribe(topic, qos=userdata['qos'])
         log.debug("Subscribed to %s", topic)
 
+def on_disconnect(client, userdata, rc):
+    if rc != mqtt.MQTT_ERR_SUCCESS:
+        log.warning("Lost broker connection (%s), reconnecting",
+                    mqtt.error_string(rc))
+
 def on_message(client, userdata, msg):
     log.debug("Received message on %s", msg.topic)
     if msg.retain and userdata['ignore_retained']:
@@ -19,8 +26,10 @@ def on_message(client, userdata, msg):
     replies = None
     try:
         replies = userdata['callback'](msg.topic, msg.payload, **userdata['kwargs'])
-    except Exception as e:
-        log.error("Callback caused exception", exc_info = True)
+    except Exception:
+        if userdata['raise_exceptions']:
+            raise
+        log.exception("Callback caused exception")
     log.debug("Callback completed.")
     if replies is not None:
         replies = list(replies)
@@ -35,28 +44,54 @@ def on_message(client, userdata, msg):
             client.publish(topic, payload, retain=retain)
             log.debug("Published '%s' to %s (retain: %s)", payload, topic, retain)
 
+def parse_broker(broker):
+    if "//" not in broker:
+        broker = "mqtt://" + broker
+    url = urlsplit(broker)
+    if url.scheme not in ("mqtt", "mqtts"):
+        raise ValueError(f"Unsupported broker URL scheme: {url.scheme}")
+    tls = url.scheme == "mqtts"
+    port = url.port or (8883 if tls else 1883)
+    return url.hostname, port, tls, url.username, url.password
+
 def mqtt_thread(client):
     client.loop_forever()
 
-def run_script(callback, broker=None, topics=None, ignore_retained=False, blocking=True, **kwargs):
+def run_script(callback, broker=None, topics=None, ignore_retained=False, blocking=True,
+               client_id="", clean_session=True, qos=0, raise_exceptions=False, **kwargs):
     if not broker:
         broker = os.environ['MQTT_BROKER']
     if not topics:
         topics = os.environ['MQTT_TOPICS'].split(",")
+    if not clean_session and not client_id:
+        raise ValueError("client_id is required when using clean_session")
+    if raise_exceptions and not blocking:
+        raise ValueError("raise_exceptions can't be used with blocking=False")
 
     userdata = {
         'topics': topics,
+        'qos': qos,
         'callback': callback,
         'ignore_retained': ignore_retained,
+        'raise_exceptions': raise_exceptions,
         'kwargs': kwargs
     }
 
-    client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION1, userdata=userdata)
+    client = mqtt.Client(
+        mqtt.CallbackAPIVersion.VERSION1,
+        client_id=client_id,
+        clean_session=clean_session,
+        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)
+    client.on_disconnect = on_disconnect
+    host, port, tls, username, password = parse_broker(broker)
+    if tls:
+        client.tls_set()
+    if username:
+        client.username_pw_set(username, password)
+    client.connect(host, port)
     if blocking:
         client.loop_forever()
     else:

{mqttwrapper-0.2.0 → mqttwrapper-0.3.0}/mqttwrapper.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mqttwrapper
-Version: 0.2.0
+Version: 0.3.0
 Summary: MQTT utility scripts made easy
 Home-page: https://github.com/davea/mqttwrapper
 Author: Dave Arter
@@ -17,8 +17,6 @@ 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
@@ -27,7 +25,6 @@ Dynamic: home-page
 Dynamic: keywords
 Dynamic: license
 Dynamic: license-file
-Dynamic: provides-extra
 Dynamic: requires-dist
 Dynamic: summary
 
@@ -44,11 +41,7 @@ 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]
+``paho-mqtt`` is used as the underlying MQTT library.
 
 Usage
 -----
@@ -77,7 +70,7 @@ or in non blocking mode::
           echo "Alive and kicking"
           time.sleep(1)
 
-Any extra keyword arguments passed to ``run_script`` are passed back to the
+Most extra keyword arguments passed to ``run_script`` are passed back to the
 callback function when it's called::
 
   from mqttwrapper import run_script
@@ -91,6 +84,18 @@ callback function when it's called::
       run_script(callback, broker="mqtt://127.0.0.1", topics=["my/awesome/topic1", "another/awesome/topic2"], context="hello", foo="bar")
 
 
+However some are reserved and will be consumed by ```run_script``` to configure how the MQTT connection behaves:
+
+
+- ``broker`` (default ``MQTT_BROKER`` from environment, otherwise ``None``): broker URL, e.g ``mybroker``, ``mqtts://securebroker:8884``, ``mqtt://username:password@coolbroker.example.org``
+- ``topics`` (default ``MQTT_TOPICS`` from environment, otherwise ``None``): list of topics to subscribe to
+- ``ignore_retained`` (default ``False``): whether to ignore a received message if it was marked as retained
+- ``blocking`` (default ``True``): run in blocking or threaded mode
+- ``client_id`` (default ``"",``): client ID to use when connecting to broker
+- ``clean_session`` (default ``True``): whether to use a clean session upon (re)connect, or resume previous session. ``client_id`` must be provided if ``True``
+- ``qos`` (default ``0``): QoS to use for connection
+- ``raise_exceptions`` (default ``False``): whether to raise exceptions that occur during callback execution
+
 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
@@ -106,8 +111,7 @@ 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.
+calling ``run_script``.
 
 Publishing messages from the callback
 -------------------------------------
@@ -129,6 +133,8 @@ e.g.::
 These tuples can optionally take the form ``(topic, payload, True)`` if you want
 the published message to be marked as retained.
 
+NB any exceptions raised during execution of the callback will be logged and ignored, unless ``raise_exceptions=True`` is passed to ``run_script``.
+
 Configuration
 -------------
 
@@ -138,56 +144,10 @@ 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 → mqttwrapper-0.3.0}/mqttwrapper.egg-info/SOURCES.txt

@@ -2,7 +2,6 @@ LICENSE
 README.rst
 setup.py
 mqttwrapper/__init__.py
-mqttwrapper/hbmqtt_backend.py
 mqttwrapper/paho_backend.py
 mqttwrapper/run.py
 mqttwrapper.egg-info/PKG-INFO

{mqttwrapper-0.2.0 → mqttwrapper-0.3.0}/mqttwrapper.egg-info/requires.txt

@@ -1,4 +1 @@
 paho-mqtt>=2.0.0
-
-[hbmqtt]
-hbmqtt

{mqttwrapper-0.2.0 → mqttwrapper-0.3.0}/setup.py

@@ -1,14 +1,15 @@
-from setuptools import setup, find_packages
 from codecs import open
 from os import path
 
+from setuptools import find_packages, setup
+
 here = path.abspath(path.dirname(__file__))
 with open(path.join(here, 'README.rst'), encoding='utf-8') as f:
     long_description = f.read()
 
 setup(
     name='mqttwrapper',
-    version='0.2.0',
+    version='0.3.0',
     description='MQTT utility scripts made easy',
     long_description=long_description,
     url='https://github.com/davea/mqttwrapper',
@@ -28,7 +29,4 @@ setup(
     keywords='mqtt',
     packages=find_packages(),
     install_requires=['paho-mqtt>=2.0.0'],
-    extras_require={
-        'hbmqtt': ['hbmqtt'],
-    },
 )

mqttwrapper-0.2.0/mqttwrapper/hbmqtt_backend.py

@@ -1,43 +0,0 @@
-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))