Migrations
==========

Change between version 1.x and 2.0
----------------------------------

Most breaking change should break loudly and should not be missed. The
most significant one which affect everyone is the versioned user callbacks.
Other breaking change might not effect your usage of paho-mqtt.

The list of breaking change (detailed below) are:

* Add version to user callbacks (on_publish, on_connect...).
  tl; dr: add ``mqtt.CallbackAPIVersion.VERSION1`` as first argument to `Client()`
* Drop support for older Python.
* Dropped some deprecated and no used argument or method. If you used them, you can just drop them.
* Removed from public interface few function/class
* Renamed ReasonCodes to ReasonCode
* Improved typing which resulted in few type change. It might no affect you, see below for detail.
* Fixed connect_srv, which changed its signature.
* Added new properties, which could conflict with sub-class

Versioned the user callbacks
****************************

Version 2.0 of paho-mqtt introduced versioning of the user-callback. To fix some inconsistency in callback
arguments and to provide better support for MQTTv5, version 2.0 changed the arguments passed to the user-callback.

You can still use the old version of the callback, you are just required to tell paho-mqtt that you opt for this
version. For that just change your client creation from::

    # OLD code
    >>> mqttc = mqtt.Client()

to::

    # NEW code
    >>> mqttc = mqtt.Client(mqtt.CallbackAPIVersion.VERSION1)


That's it, the remaining of the code can stay unchanged.

Version 1 of the callback is deprecated, but is still supported in version 2.x. If you want to upgrade to the newer version of the API callback, you will need to update your callbacks:

on_connect
``````````

::

    # OLD code for MQTTv3
    def on_connect(client, userdata, flags, rc):
        if flags["session present"] == 1:
            # ...
        if rc == 0:
            # success connect
        if rc > 0:
            # error processing

    # OLD code for MQTTv5
    def on_connect(client, userdata, flags, reason_code, properties):
        if flags["session present"] == 1:
            # ...
        if reason_code == 0:
            # success connect

    # NEW code for both version
    def on_connect(client, userdata, flags, reason_code, properties):
        if flags.session_present:
            # ...
        if reason_code == 0:
            # success connect
        if reason_code > 0:
            # error processing


Be careful that for MQTTv3, ``rc`` (an integer) changed to ``reason_code`` (an instance of `ReasonCode`), and the numeric value changed.
The numeric value 0 means success for both, so as in above example, using ``reason_code == 0``, ``reason_code != 0`` or other comparison with zero
is fine.
But if you had comparison with other value, you will need to update the code. It's recommended to compare to string value::

    # OLD code for MQTTv3
    def on_connect(client, userdata, flags, rc):
        if rc == 1:
            # handle bad protocol version
        if rc == CONNACK_REFUSED_IDENTIFIER_REJECTED:
            # handle bad identifier

    # NEW code
    def on_connect(client, userdata, flags, reason_code, properties):
        if reason_code == "Unsupported protocol version":
            # handle bad protocol version
        if reason_code == "Client identifier not valid":
            # handle bad identifier

on_disconnect
`````````````

::

    # OLD code for MQTTv3
    def on_disconnect(client, userdata, rc):
        if rc == 0:
            # success disconnect
        if rc > 0:
            # error processing

    # OLD code for MQTTv5
    def on_disconnect(client, userdata, reason_code, properties):
        if reason_code:
            # error processing

    # NEW code for both version
    def on_disconnect(client, userdata, flags, reason_code, properties):
        if reason_code == 0:
            # success disconnect
        if reason_code > 0:
            # error processing



on_subscribe
````````````

::

    # OLD code for MQTTv3
    def on_subscribe(client, userdata, mid, granted_qos):
        for sub_result in granted_qos:
            if sub_result == 1:
                # process QoS == 1
            if sub_result == 0x80:
                # error processing

    # OLD code for MQTTv5
    def on_disconnect(client, userdata, mid, reason_codes, properties):
        for sub_result in reason_codes:
            if sub_result == 1:
                # process QoS == 1
            # Any reason code >= 128 is a failure.
            if sub_result >= 128:
                # error processing

    # NEW code for both version
    def on_subscribe(client, userdata, mid, reason_codes, properties):
        for sub_result in reason_codes:
            if sub_result == 1:
                # process QoS == 1
            # Any reason code >= 128 is a failure.
            if sub_result >= 128:
                # error processing



on_unsubscribe
``````````````

::

    # OLD code for MQTTv3
    def on_unsubscribe(client, userdata, mid):
        # ...

    # OLD code for MQTTv5
    def on_unsubscribe(client, userdata, mid, properties, reason_codes):
        # In OLD version, reason_codes could be a list or a single ReasonCode object
        if isinstance(reason_codes, list):
            for unsub_result in reason_codes:
                # Any reason code >= 128 is a failure.
                if reason_codes[0] >= 128:
                    # error processing
        else:
            # Any reason code >= 128 is a failure.
            if reason_codes > 128:
                # error processing


    # NEW code for both version
    def on_subscribe(client, userdata, mid, reason_codes, properties):
        # In NEW version, reason_codes is always a list. Empty for MQTTv3
        for unsub_result in reason_codes:
            # Any reason code >= 128 is a failure.
            if reason_codes[0] >= 128:
                # error processing


on_publish
``````````

::

    # OLD code
    def on_publish(client, userdata, mid):
        # ...


    # NEW code
    def on_publish(client, userdata, mid, reason_codes, properties):
        # ...



on_message
``````````

No change for this callback::

    # OLD & NEW code
    def on_message(client, userdata, message):
        # ...


Drop support for older Python
*****************************

paho-mqtt support Python 3.7 to 3.12. If you are using an older Python version, including
Python 2.x you will need to kept running the 1.x version of paho-mqtt.

Drop deprecated argument and method
***********************************

The following are dropped:

* ``max_packets`` argument in `loop()`, `loop_write()` and `loop_forever()` is removed
* ``force`` argument in `loop_stop()` is removed
* method ``message_retry_set()`` is removed

They were not used in previous version, so you can just remove them if you used them.

Stop exposing private function/class
************************************

Some private function or class are not longer exposed. The following are removed:

* function base62
* class WebsocketWrapper
* enum ConnectionState

Renamed ReasonCodes to ReasonCode
*********************************

The class ReasonCodes that was used to represent one reason code response from
broker or generated by the library is now named `ReasonCode`.

This should work without any change as ReasonCodes (plural, the old name) is still
present but deprecated.

Improved typing
***************

Version 2.0 improved typing, but this would be compatible with existing code.
The most likely issue are some integer that are now better type, like `dup` on MQTTMessage.

That means that code that used ``if msg.dup == 1:`` will need to be change to ``if msg.dup:`` (the later version
for with both paho-mqtt 1.x and 2.0).

Fix connect_srv
***************

`connect_srv()` didn't took the same argument as `connect()`. Fixed this, which means the signaure
changed. But since connect_srv was broken in previous version, this should not have any negative impact.

Added new properties
********************

The Client class added few new properties. If you are using a sub-class of Client and also defined a
attribute, method or properties with the same name, it will conflict.

The added properties are:

* `host`
* `port`
* `keepalive`
* `transport`
* `protocol`
* `connect_timeout`
* `username`
* `password`
* `max_inflight_messages`
* `max_queued_messages`
* `will_topic`
* `will_payload`
* `logger`