Skip to content

Commit

Permalink
Merge pull request #788 from akx/typo-fixes-1
Browse files Browse the repository at this point in the history 
Fix grammar, typos
  • Loading branch information
@PierreF
PierreF authored Jan 13, 2024
2 parents 91316e6 + fb418e1 commit e9f3815
Show file tree
Hide file tree
Showing 2 changed files with 31 additions and 30 deletions.
35 changes: 18 additions & 17 deletions README.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ Eclipse Paho™ MQTT Python Client

This document describes the source code for the `Eclipse Paho <http://eclipse.org/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 <http://mqtt.org/>`_ 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 <http://mqtt.org/>`_ 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+.

Expand Down Expand Up @@ -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
Expand All @@ -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
-------------
Expand Down
26 changes: 13 additions & 13 deletions src/paho/mqtt/client.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1985,7 +1985,7 @@ def on_log(self, func: CallbackOnLog | None) -> None:
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.
Expand Down Expand Up @@ -2016,7 +2016,7 @@ def on_pre_connect(self, func: CallbackOnPreConnect | None) -> None:
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)
Expand Down Expand Up @@ -2050,7 +2050,7 @@ def on_connect(self, func: CallbackOnConnect | None) -> None:
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.
Expand Down Expand Up @@ -2105,7 +2105,7 @@ def on_connect_fail(self, func: CallbackOnConnectFail | None) -> None:
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)
Expand Down Expand Up @@ -2139,7 +2139,7 @@ def on_subscribe(self, func: CallbackOnSubscribe | None) -> None:
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
Expand Down Expand Up @@ -2181,7 +2181,7 @@ def on_message(self, func: CallbackOnMessage | None) -> None:
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.
Expand Down Expand Up @@ -2220,7 +2220,7 @@ def on_publish(self, func: CallbackOnPublish | None) -> None:
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.
Expand Down Expand Up @@ -2256,7 +2256,7 @@ def on_unsubscribe(self, func: CallbackOnUnsubscribe | None) -> None:
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
Expand Down Expand Up @@ -2295,7 +2295,7 @@ def on_disconnect(self, func: CallbackOnDisconnect | None) -> None:
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
Expand Down Expand Up @@ -2332,7 +2332,7 @@ def on_socket_open(self, func: CallbackOnSocket | None) -> None:
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
Expand Down Expand Up @@ -2379,7 +2379,7 @@ def on_socket_close(self, func: CallbackOnSocket | None) -> None:
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
Expand Down Expand Up @@ -2426,7 +2426,7 @@ def on_socket_register_write(self, func: CallbackOnSocket | None) -> None:
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
Expand Down Expand Up @@ -2480,7 +2480,7 @@ def on_socket_unregister_write(
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
Expand Down

0 comments on commit e9f3815

Please sign in to comment.