From dc85ee568fb91330b9681ff97fded85eae0bbc77 Mon Sep 17 00:00:00 2001 From: Alexis BRENON Date: Wed, 20 Apr 2016 16:10:32 +0200 Subject: [PATCH] Fix/update comments for calbacks Signed-off-by: Alexis BRENON --- src/paho/mqtt/client.py | 145 +++++++++++++++++++++++++--------------- 1 file changed, 90 insertions(+), 55 deletions(-) diff --git a/src/paho/mqtt/client.py b/src/paho/mqtt/client.py index 3dcf691..7130f6d 100644 --- a/src/paho/mqtt/client.py +++ b/src/paho/mqtt/client.py @@ -1323,27 +1323,41 @@ class Client(object): @property def on_log(self): - """Called when the client has log information if implemented. - - Define to allow debugging. - - level: 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. - buf: the message itself - """ + """If implemented, called when the client has log information. + Defined to allow debugging.""" return self._on_log @on_log.setter def on_log(self, func): + """ Define the logging callback implementation. + + Expected signature is: + log_callback(client, userdata, level, buf) + + client: the client instance for this callback + userdata: the private user data as set in Client() or userdata_set() + level: 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. + buf: the message itself + """ self._on_log = func @property def on_connect(self): - """Called when the broker responds to our connection request if implemented. + """If implemented, called when the broker responds to our connection + request.""" + return self._on_connect + + @on_connect.setter + def on_connect(self, func): + """ Define the connect callback implementation. - self: the client instance for this callback - userdata: the private user data as set in ``Client()`` or ``userdata_set()`` + Expected signature is: + connect_callback(client, userdata, flags, rc) + + client: the client instance for this callback + userdata: the private user data as set in Client() or userdata_set() flags: response flags sent by the broker rc: the connection result @@ -1363,100 +1377,121 @@ class Client(object): 5: Connection refused - not authorised 6-255: Currently unused. """ - return self._on_connect - - @on_connect.setter - def on_connect(self, func): self._on_connect = func @property def on_subscribe(self): - """Called when the broker responds to a subscribe request if implemented. + """If implemented, called when the broker responds to a subscribe + request.""" + return self._on_subscribe + + @on_subscribe.setter + def on_subscribe(self, func): + """ Define the suscribe callback implementation. + Expected signature is: + subscribe_callback(client, userdata, mid, granted_qos) + + client: the client instance for this callback + userdata: the private user data as set in Client() or userdata_set() mid: matches the mid variable returned from the corresponding subscribe() call. granted_qos: list of integers that give the QoS level the broker has granted for each of the different subscription requests. """ - return self._on_subscribe - - @on_subscribe.setter - def on_subscribe(self, func): self._on_subscribe = func @property def on_message(self): - """Called when a message has been received on a topic that the client - subscribes to if implemented. + """If implemented, 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. + message_callback_add() to define multiple callbacks that will be called + for specific topic filters.""" + return self._on_message + + @on_message.setter + def on_message(self, func): + """ Define the message received callback implementation. - self: the client instance for this callback + Expected signature is: + on_message_callback(client, userdata, message) + + client: the client instance for this callback userdata: the private user data as set in Client() or userdata_set() message: an instance of MQTTMessage. This is a class with members topic, payload, qos, retain. """ - return self._on_message - - @on_message.setter - def on_message(self, func): self._on_message = func @property def on_publish(self): - """Called when a message that was to be sent using the publish() call - has completed transmission to the broker. - This function may be overridden by sub-classes. + """If implemented, 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 completed. For QoS 0, this simply means that the message has left the client. This callback is important because even if the publish() call returns - success, it does not always mean that the message has been sent. - - mid: matches the mid variable returned from the corresponding - publish() call, to allow outgoing messages to be tracked. - """ + success, it does not always mean that the message has been sent.""" return self._on_publish @on_publish.setter def on_publish(self, func): + """ Define the published message callback implementation. + + Expected signature is: + on_publish_callback(client, userdata, mid) + + client: the client instance for this callback + userdata: the private user data as set in Client() or userdata_set() + mid: matches the mid variable returned from the corresponding + publish() call, to allow outgoing messages to be tracked. + """ self._on_publish = func @property def on_unsubscribe(self): - """Called when the broker responds to an unsubscribe request. - This function may be overridden by sub-classes. - - mid: matches the mid variable returned from the corresponding - unsubscribe() call. - """ + """If implemented, called when the broker responds to an unsubscribe + request.""" return self._on_unsubscribe @on_unsubscribe.setter def on_unsubscribe(self, func): - self._on_unsubscribe = func + """ Define the unsubscribe callback implementation. - @property - def on_disconnect(self): - """Called when the client disconnects from the broker. - This function may be overridden by sub-classes. + Expected signature is: + unsubscribe_callback(client, userdata, mid) - self: the client instance for this callback + client: the client instance for this callback userdata: the private user data as set in Client() or userdata_set() - rc: the disconnection result + mid: matches the mid variable returned from the corresponding + unsubscribe() call. + """ + self._on_unsubscribe = func - The rc parameter indicates the disconnection state. If MQTT_ERR_SUCCESS - (0), the callback was called in response to a disconnect() call. If any - other value the disconnection was unexpected, such as might be caused by - a network error. + @property + def on_disconnect(self): + """If implemented, called when the client disconnects from the broker. """ return self._on_disconnect @on_disconnect.setter def on_disconnect(self, func): + """ Define the disconnect callback implementation. + + Expected signature is: + disconnect_callback(client, userdata, self) + + client: the client instance for this callback + userdata: the private user data as set in Client() or userdata_set() + rc: the disconnection result + The rc parameter indicates the disconnection state. If + MQTT_ERR_SUCCESS (0), the callback was called in response to + a disconnect() call. If any other value the disconnection + was unexpected, such as might be caused by a network error. + """ self._on_disconnect = func def message_callback_add(self, sub, callback): -- GitLab