Improve doc for on_message vs message_callback_add

README.rst

@@ -850,9 +850,9 @@ on_message()
     on_message(client, userdata, message)
     
 Called when a message has been received on a topic that the client subscribes
-to. This callback will be called for every message received. Use
-``message_callback_add()`` to define multiple callbacks that will be called for
-specific topic filters.
+to and the message does not match an existing topic filter callback.
+Use ``message_callback_add()`` to define a callback that will be called for
+specific topic filters. ``on_message`` will serve as fallback when none matched.
 
 client
     the client instance for this callback
@@ -899,6 +899,10 @@ If using ``message_callback_add()`` and ``on_message``, only messages that do
 not match a subscription specific filter will be passed to the ``on_message``
 callback.
 
+If multiple sub match a topic, each callback will be called (e.g. sub ``sensors/#``
+and sub ``+/humidity`` both match a message with a topic ``sensors/humidity``, so both
+callbacks will handle this message).
+
 message_callback_remove()
 '''''''''''''''''''''''''
 

tests/test_client.py

@@ -146,3 +146,92 @@ def on_message(client, userdata, msg):
 
         packet_in = fake_broker.receive_packet(1)
         assert not packet_in  # Check connection is closed
+
+    def test_message_callback(self, fake_broker):
+        mqttc = client.Client("client-id")
+        userdata = {
+            'on_message': 0,
+            'callback1': 0,
+            'callback2': 0,
+        }
+        mqttc.user_data_set(userdata)
+
+        def on_message(client, userdata, msg):
+            assert msg.topic == 'topic/value'
+            userdata['on_message'] += 1
+
+        def callback1(client, userdata, msg):
+            assert msg.topic == 'topic/callback/1'
+            userdata['callback1'] += 1
+
+        def callback2(client, userdata, msg):
+            assert msg.topic in ('topic/callback/3', 'topic/callback/1')
+            userdata['callback2'] += 1
+
+        mqttc.on_message = on_message
+        mqttc.message_callback_add('topic/callback/1', callback1)
+        mqttc.message_callback_add('topic/callback/+', callback2)
+
+        mqttc.connect_async("localhost", 1888)
+        mqttc.loop_start()
+
+        try:
+            fake_broker.start()
+
+            connect_packet = paho_test.gen_connect("client-id")
+            packet_in = fake_broker.receive_packet(len(connect_packet))
+            assert packet_in  # Check connection was not closed
+            assert packet_in == connect_packet
+
+            connack_packet = paho_test.gen_connack(rc=0)
+            count = fake_broker.send_packet(connack_packet)
+            assert count  # Check connection was not closed
+            assert count == len(connack_packet)
+
+            publish_packet = paho_test.gen_publish(b"topic/value", qos=1, mid=1)
+            count = fake_broker.send_packet(publish_packet)
+            assert count  # Check connection was not closed
+            assert count == len(publish_packet)
+
+            publish_packet = paho_test.gen_publish(b"topic/callback/1", qos=1, mid=2)
+            count = fake_broker.send_packet(publish_packet)
+            assert count  # Check connection was not closed
+            assert count == len(publish_packet)
+
+            publish_packet = paho_test.gen_publish(b"topic/callback/3", qos=1, mid=3)
+            count = fake_broker.send_packet(publish_packet)
+            assert count  # Check connection was not closed
+            assert count == len(publish_packet)
+
+
+            puback_packet = paho_test.gen_puback(mid=1)
+            packet_in = fake_broker.receive_packet(len(puback_packet))
+            assert packet_in  # Check connection was not closed
+            assert packet_in == puback_packet
+
+            puback_packet = paho_test.gen_puback(mid=2)
+            packet_in = fake_broker.receive_packet(len(puback_packet))
+            assert packet_in  # Check connection was not closed
+            assert packet_in == puback_packet
+
+            puback_packet = paho_test.gen_puback(mid=3)
+            packet_in = fake_broker.receive_packet(len(puback_packet))
+            assert packet_in  # Check connection was not closed
+            assert packet_in == puback_packet
+
+            mqttc.disconnect()
+
+            disconnect_packet = paho_test.gen_disconnect()
+            packet_in = fake_broker.receive_packet(len(disconnect_packet))
+            assert packet_in  # Check connection was not closed
+            assert packet_in == disconnect_packet
+
+        finally:
+            mqttc.loop_stop()
+
+        packet_in = fake_broker.receive_packet(1)
+        assert not packet_in  # Check connection is closed
+
+        assert userdata['on_message'] == 1
+        assert userdata['callback1'] == 1
+        assert userdata['callback2'] == 2