Test and documentation for decorators.

ChangeLog.txt

@@ -11,6 +11,7 @@ v1.6.0 - 2021-xx-xx
   the server. They will *not* be retried when the client is still connected.
 - The `rc` parameter in the `on_disconnect` callback now has meaningful values
   in the case of an error. Closes #441.
+- Callbacks can now be applied to client instances using decorators.
 
 
 v1.5.1 - 2020-09-22

src/paho/mqtt/client.py

@@ -437,6 +437,14 @@ class Client(object):
 
     client.on_connect = on_connect
 
+    Callbacks can also be attached using decorators:
+
+    client = paho.mqtt.Client()
+
+    @client.connect_callback()
+    def on_connect(client, userdata, flags, rc, properties=None):
+        print("Connection returned " + str(rc))
+
     All of the callbacks as described below have a "client" and an "userdata"
     argument. "client" is the Client instance that is calling the callback.
     "userdata" is user data of any type and can be set when creating a new client
@@ -464,6 +472,9 @@ class Client(object):
         5: Connection refused - not authorised
         6-255: Currently unused.
 
+      Decorator: @client.connect_callback() (```client``` is the name of the
+        instance which this callback is being attached to)
+
     on_disconnect(client, userdata, rc): called when the client disconnects from the broker.
       The rc parameter indicates the disconnection state:
         MQTT_ERR_SUCCESS: the callback was called in response to a disconnect() call.
@@ -476,10 +487,16 @@ class Client(object):
       message can contain a reason code and MQTT V5 properties.  The properties parameter could be
       None if they do not exist in the disconnect message.
 
+      Decorator: @client.disconnect_callback() (```client``` is the name of the
+        instance which this callback is being attached to)
+
     on_message(client, userdata, message): called when a message has been received on a
       topic that the client subscribes to. The message variable is a
       MQTTMessage that describes all of the message parameters.
 
+      Decorator: @client.message_callback() (```client``` is the name of the
+        instance which this callback is being attached to)
+
     on_publish(client, userdata, mid): called when a message that was to be sent using the
       publish() call has completed transmission to the broker. For messages
       with QoS levels 1 and 2, this means that the appropriate handshakes have
@@ -489,34 +506,58 @@ class Client(object):
       This callback is important because even if the publish() call returns
       success, it does not always mean that the message has been sent.
 
+      Decorator: @client.publish_callback() (```client``` is the name of the
+        instance which this callback is being attached to)
+
     on_subscribe(client, userdata, mid, granted_qos, properties=None): called when the broker responds to a
       subscribe request. The mid variable matches the mid variable returned
       from the corresponding subscribe() call. The granted_qos variable is a
       list of integers that give the QoS level the broker has granted for each
       of the different subscription requests.
 
+      Decorator: @client.subscribe_callback() (```client``` is the name of the
+        instance which this callback is being attached to)
+
     on_unsubscribe(client, userdata, mid): called when the broker responds to an unsubscribe
       request. The mid variable matches the mid variable returned from the
       corresponding unsubscribe() call.
 
+      Decorator: @client.unsubscribe_callback() (```client``` is the name of the
+        instance which this callback is being attached to)
+
     on_log(client, userdata, level, buf): called when the client has log information. Define
       to allow debugging. The level variable gives the severity of the message
       and will be one of MQTT_LOG_INFO, MQTT_LOG_NOTICE, MQTT_LOG_WARNING,
       MQTT_LOG_ERR, and MQTT_LOG_DEBUG. The message itself is in buf.
 
+      Decorator: @client.log_callback() (```client``` is the name of the
+        instance which this callback is being attached to)
+
     on_socket_open(client, userdata, sock): Called when the socket has been opened. Use this
       to register the socket with an external event loop for reading.
 
+      Decorator: @client.socket_open_callback() (```client``` is the name of the
+        instance which this callback is being attached to)
+
     on_socket_close(client, userdata, sock): Called when the socket is about to be closed.
       Use this to unregister a socket from an external event loop for reading.
 
+      Decorator: @client.socket_close_callback() (```client``` is the name of the
+        instance which this callback is being attached to)
+
     on_socket_register_write(client, userdata, sock): Called when a write operation to the
       socket failed because it would have blocked, e.g. output buffer full. Use this to
       register the socket with an external event loop for writing.
 
+      Decorator: @client.socket_register_write_callback() (```client``` is the name of the
+        instance which this callback is being attached to)
+
     on_socket_unregister_write(client, userdata, sock): Called when a write operation to the
       socket succeeded after it had previously failed. Use this to unregister the socket
       from an external event loop for writing.
+
+      Decorator: @client.socket_unregister_write_callback() (```client``` is the name of the
+        instance which this callback is being attached to)
     """
 
     def __init__(self, client_id="", clean_session=None, userdata=None,

test/lib/01-decorators.py

+#!/usr/bin/env python3
+
+# Test whether callback decorators work
+
+import context
+import paho_test
+
+rc = 1
+keepalive = 60
+connect_packet = paho_test.gen_connect("decorators-test", keepalive=keepalive)
+connack_packet = paho_test.gen_connack(rc=0)
+
+subscribe_packet = paho_test.gen_subscribe(mid=1, topic=u"sub-test", qos=1)
+suback_packet = paho_test.gen_suback(mid=1, qos=1)
+
+unsubscribe_packet = paho_test.gen_unsubscribe(mid=2, topic=u"unsub-test")
+unsuback_packet = paho_test.gen_unsuback(mid=2)
+
+publish_packet = paho_test.gen_publish(u"b2c", qos=0, payload="msg".encode('utf-8'))
+
+publish_packet_in = paho_test.gen_publish(u"decorators", qos=1, mid=3, payload="message".encode('utf-8'))
+puback_packet_in = paho_test.gen_puback(mid=3)
+
+disconnect_packet = paho_test.gen_disconnect()
+
+sock = paho_test.create_server_socket()
+
+client = context.start_client()
+
+try:
+    (conn, address) = sock.accept()
+    conn.settimeout(10)
+
+    if paho_test.expect_packet(conn, "connect", connect_packet):
+        conn.send(connack_packet)
+
+        if paho_test.expect_packet(conn, "subscribe", subscribe_packet):
+            conn.send(suback_packet)
+
+            if paho_test.expect_packet(conn, "unsubscribe", unsubscribe_packet):
+                conn.send(unsuback_packet)
+                conn.send(publish_packet)
+
+                if paho_test.expect_packet(conn, "publish", publish_packet_in):
+                    conn.send(puback_packet_in)
+
+                    if paho_test.expect_packet(conn, "disconnect", disconnect_packet):
+                        rc = 0
+
+    conn.close()
+finally:
+    client.terminate()
+    client.wait()
+    sock.close()
+
+exit(rc)

test/lib/Makefile

@@ -6,6 +6,7 @@ PYTHON?=python3
 all :
 
 test :
+	$(PYTHON) ./01-decorators.py python/01-decorators.test
 	$(PYTHON) ./01-keepalive-pingreq.py python/01-keepalive-pingreq.test
 	$(PYTHON) ./01-no-clean-session.py python/01-no-clean-session.test
 	$(PYTHON) ./01-reconnect-on-failure.py python/01-reconnect-on-failure.test

test/lib/python/01-decorators.test

+#!/usr/bin/env python3
+
+import os
+import socket
+import subprocess
+import sys
+import time
+from struct import *
+
+import paho.mqtt.client as mqtt
+
+
+run = -1
+mqttc = mqtt.Client("decorators-test", run)
+payload = b""
+
+@mqttc.connect_callback()
+def on_connect(mqttc, obj, flags, rc):
+    mqttc.subscribe("sub-test", 1)
+
+@mqttc.subscribe_callback()
+def on_subscribe(mqttc, obj, mid, granted_qos):
+    mqttc.unsubscribe("unsub-test")
+
+@mqttc.unsubscribe_callback()
+def on_unsubscribe(mqttc, obj, mid):
+    global payload
+    payload = "message"
+
+@mqttc.message_callback()
+def on_message(mqttc, obj, msg):
+    global payload
+    mqttc.publish("decorators", qos=1, payload=payload)
+
+@mqttc.publish_callback()
+def on_publish(mqttc, obj, mid):
+    mqttc.disconnect()
+
+@mqttc.disconnect_callback()
+def on_disconnect(mqttc, obj, rc):
+    obj = rc
+
+mqttc.connect("localhost", 1888)
+while run == -1:
+    mqttc.loop()
+
+exit(run)