From 0516ef127de503403fe699612f66c621aedeb3c4 Mon Sep 17 00:00:00 2001 From: Aarni Koskela Date: Wed, 3 Jan 2024 10:13:59 +0200 Subject: [PATCH 1/2] Fix grammar and typos in README Closes #614 Co-authored-by: alexander-minchin <83529885+alexander-minchin@users.noreply.github.com> Signed-off-by: Aarni Koskela --- README.rst | 35 ++++++++++++++++++----------------- 1 file changed, 18 insertions(+), 17 deletions(-) diff --git a/README.rst b/README.rst index c80e6854..e2e698ea 100644 --- a/README.rst +++ b/README.rst @@ -3,7 +3,7 @@ Eclipse Paho™ MQTT Python Client This document describes the source code for the `Eclipse Paho `_ MQTT Python client library, which implements versions 5.0, 3.1.1, and 3.1 of the MQTT protocol. -This code provides a client class which enable applications to connect to an `MQTT `_ broker to publish messages, and to subscribe to topics and receive published messages. It also provides some helper functions to make publishing one off messages to an MQTT server very straightforward. +This code provides a client class which enables applications to connect to an `MQTT `_ broker to publish messages, and to subscribe to topics and receive published messages. It also provides some helper functions to make publishing one off messages to an MQTT server very straightforward. It supports Python 3.7+. @@ -69,7 +69,7 @@ Once you have the code, it can be installed from your repository as well: cd paho.mqtt.python pip install -e . -To perform all test (including MQTT v5 test), you also need to clone paho.mqtt.testing in paho.mqtt.python folder:: +To perform all tests (including MQTT v5 tests), you also need to clone paho.mqtt.testing in paho.mqtt.python folder:: git clone https://github.com/eclipse/paho.mqtt.testing.git cd paho.mqtt.testing @@ -78,32 +78,33 @@ To perform all test (including MQTT v5 test), you also need to clone paho.mqtt.t Known limitations ----------------- -The following are the known unimplemented MQTT feature. +The following are the known unimplemented MQTT features. -When clean_session is False, the session is only stored in memory not persisted. This means that -when client is restarted (not just reconnected, the object is recreated usually because the -program was restarted) the session is lost. This result in possible message lost. +When ``clean_session`` is False, the session is only stored in memory and not persisted. This means that +when the client is restarted (not just reconnected, the object is recreated usually because the +program was restarted) the session is lost. This results in a possible message loss. -The following part of client session is lost: +The following part of the client session is lost: -* QoS 2 messages which have been received from the Server, but have not been completely acknowledged. +* QoS 2 messages which have been received from the server, but have not been completely acknowledged. Since the client will blindly acknowledge any PUBCOMP (last message of a QoS 2 transaction), it - won't hang but will lost this QoS 2 message. + won't hang but will lose this QoS 2 message. -* QoS 1 and QoS 2 messages which have been sent to the Server, but have not been completely acknowledged. +* QoS 1 and QoS 2 messages which have been sent to the server, but have not been completely acknowledged. - This means that message passed to publish() may be lost. This could be mitigated by taking care - that all message passed to publish() has a corresponding on_publish() call. + This means that messages passed to ``publish()`` may be lost. This could be mitigated by taking care + that all messages passed to ``publish()`` have a corresponding on_publish() call. - It also means that the broker may have the Qos2 message in the session. Since the client start + It also means that the broker may have the Qos2 message in the session. Since the client starts with an empty session it don't know it and will reuse the mid. This is not yet fixed. -Also when clean_session is True, this library will republish QoS > 0 message across network -reconnection. This means that QoS > 0 message won't be lost. But the standard say that -if we should discard any message for which the publish packet was sent. Our choice means that +Also, when ``clean_session`` is True, this library will republish QoS > 0 message accross network +reconnection. This means that QoS > 0 message won't be lost. But the standard says that +we should discard any message for which the publish packet was sent. Our choice means that we are not compliant with the standard and it's possible for QoS 2 to be received twice. -You should you clean_session = False if you need the QoS 2 guarantee of only one delivery. + +You should set ``clean_session = False`` if you need the QoS 2 guarantee of only one delivery. Usage and API ------------- From fb418e1d5976fc4cf412b3ee503a2888620132af Mon Sep 17 00:00:00 2001 From: Aarni Koskela Date: Wed, 3 Jan 2024 10:38:48 +0200 Subject: [PATCH 2/2] Correct `userdata_set` to `user_data_set` Co-authored-by: jalotra Signed-off-by: Aarni Koskela --- src/paho/mqtt/client.py | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/src/paho/mqtt/client.py b/src/paho/mqtt/client.py index 722f0b5e..ea6d2198 100644 --- a/src/paho/mqtt/client.py +++ b/src/paho/mqtt/client.py @@ -1838,7 +1838,7 @@ def on_log(self, func): 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() + userdata: the private user data as set in Client() or user_data_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. @@ -1869,7 +1869,7 @@ def on_pre_connect(self, func): connect_callback(client, userdata) client: the client instance for this callback - userdata: the private user data as set in Client() or userdata_set() + userdata: the private user data as set in Client() or user_data_set() Decorator: @client.pre_connect_callback() (```client``` is the name of the instance which this callback is being attached to) @@ -1901,7 +1901,7 @@ def on_connect(self, func): connect_callback(client, userdata, flags, reasonCode, properties) client: the client instance for this callback - userdata: the private user data as set in Client() or userdata_set() + userdata: the private user data as set in Client() or user_data_set() flags: response flags sent by the broker rc: the connection result reasonCode: the MQTT v5.0 reason code: an instance of the ReasonCode class. @@ -1954,7 +1954,7 @@ def on_connect_fail(self, func): on_connect_fail(client, userdata) client: the client instance for this callback - userdata: the private user data as set in Client() or userdata_set() + userdata: the private user data as set in Client() or user_data_set() Decorator: @client.connect_fail_callback() (```client``` is the name of the instance which this callback is being attached to) @@ -1986,7 +1986,7 @@ def on_subscribe(self, func): subscribe_callback(client, userdata, mid, reasonCodes, properties) client: the client instance for this callback - userdata: the private user data as set in Client() or userdata_set() + userdata: the private user data as set in Client() or user_data_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 @@ -2026,7 +2026,7 @@ def on_message(self, func): 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() + userdata: the private user data as set in Client() or user_data_set() message: an instance of MQTTMessage. This is a class with members topic, payload, qos, retain. @@ -2063,7 +2063,7 @@ def on_publish(self, func): 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() + userdata: the private user data as set in Client() or user_data_set() mid: matches the mid variable returned from the corresponding publish() call, to allow outgoing messages to be tracked. @@ -2097,7 +2097,7 @@ def on_unsubscribe(self, func): unsubscribe_callback(client, userdata, mid, properties, reasonCodes) client: the client instance for this callback - userdata: the private user data as set in Client() or userdata_set() + userdata: the private user data as set in Client() or user_data_set() mid: matches the mid variable returned from the corresponding unsubscribe() call. properties: the MQTT v5.0 properties received from the broker. A @@ -2134,7 +2134,7 @@ def on_disconnect(self, func): disconnect_callback(client, userdata, reasonCode, properties) client: the client instance for this callback - userdata: the private user data as set in Client() or userdata_set() + userdata: the private user data as set in Client() or user_data_set() rc: the disconnection result The rc parameter indicates the disconnection state. If MQTT_ERR_SUCCESS (0), the callback was called in response to @@ -2169,7 +2169,7 @@ def on_socket_open(self, func): socket_open_callback(client, userdata, socket) client: the client instance for this callback - userdata: the private user data as set in Client() or userdata_set() + userdata: the private user data as set in Client() or user_data_set() sock: the socket which was just opened. Decorator: @client.socket_open_callback() (```client``` is the name of the @@ -2214,7 +2214,7 @@ def on_socket_close(self, func): socket_close_callback(client, userdata, socket) client: the client instance for this callback - userdata: the private user data as set in Client() or userdata_set() + userdata: the private user data as set in Client() or user_data_set() sock: the socket which is about to be closed. Decorator: @client.socket_close_callback() (```client``` is the name of the @@ -2259,7 +2259,7 @@ def on_socket_register_write(self, func): socket_register_write_callback(client, userdata, socket) client: the client instance for this callback - userdata: the private user data as set in Client() or userdata_set() + userdata: the private user data as set in Client() or user_data_set() sock: the socket which should be registered for writing Decorator: @client.socket_register_write_callback() (```client``` is the name of the @@ -2307,7 +2307,7 @@ def on_socket_unregister_write(self, func): socket_unregister_write_callback(client, userdata, socket) client: the client instance for this callback - userdata: the private user data as set in Client() or userdata_set() + userdata: the private user data as set in Client() or user_data_set() sock: the socket which should be unregistered for writing Decorator: @client.socket_unregister_write_callback() (```client``` is the name of the