added v3

venv/lib/python3.11/site-packages/paho/mqtt/__init__.py

@@ -0,0 +1,5 @@
+__version__ = "1.6.1"
+
+
+class MQTTException(Exception):
+    pass

venv/lib/python3.11/site-packages/paho/mqtt/matcher.py

@@ -0,0 +1,78 @@
+class MQTTMatcher(object):
+    """Intended to manage topic filters including wildcards.
+
+    Internally, MQTTMatcher use a prefix tree (trie) to store
+    values associated with filters, and has an iter_match()
+    method to iterate efficiently over all filters that match
+    some topic name."""
+
+    class Node(object):
+        __slots__ = '_children', '_content'
+
+        def __init__(self):
+            self._children = {}
+            self._content = None
+
+    def __init__(self):
+        self._root = self.Node()
+
+    def __setitem__(self, key, value):
+        """Add a topic filter :key to the prefix tree
+        and associate it to :value"""
+        node = self._root
+        for sym in key.split('/'):
+            node = node._children.setdefault(sym, self.Node())
+        node._content = value
+
+    def __getitem__(self, key):
+        """Retrieve the value associated with some topic filter :key"""
+        try:
+            node = self._root
+            for sym in key.split('/'):
+                node = node._children[sym]
+            if node._content is None:
+                raise KeyError(key)
+            return node._content
+        except KeyError:
+            raise KeyError(key)
+
+    def __delitem__(self, key):
+        """Delete the value associated with some topic filter :key"""
+        lst = []
+        try:
+            parent, node = None, self._root
+            for k in key.split('/'):
+                 parent, node = node, node._children[k]
+                 lst.append((parent, k, node))
+            # TODO
+            node._content = None
+        except KeyError:
+            raise KeyError(key)
+        else:  # cleanup
+            for parent, k, node in reversed(lst):
+                if node._children or node._content is not None:
+                     break
+                del parent._children[k]
+
+    def iter_match(self, topic):
+        """Return an iterator on all values associated with filters
+        that match the :topic"""
+        lst = topic.split('/')
+        normal = not topic.startswith('$')
+        def rec(node, i=0):
+            if i == len(lst):
+                if node._content is not None:
+                    yield node._content
+            else:
+                part = lst[i]
+                if part in node._children:
+                    for content in rec(node._children[part], i + 1):
+                        yield content
+                if '+' in node._children and (normal or i > 0):
+                    for content in rec(node._children['+'], i + 1):
+                        yield content
+            if '#' in node._children and (normal or i > 0):
+                content = node._children['#']._content
+                if content is not None:
+                    yield content
+        return rec(self._root)

venv/lib/python3.11/site-packages/paho/mqtt/packettypes.py

@@ -0,0 +1,43 @@
+"""
+*******************************************************************
+  Copyright (c) 2017, 2019 IBM Corp.
+
+  All rights reserved. This program and the accompanying materials
+  are made available under the terms of the Eclipse Public License v2.0
+  and Eclipse Distribution License v1.0 which accompany this distribution.
+
+  The Eclipse Public License is available at
+     http://www.eclipse.org/legal/epl-v10.html
+  and the Eclipse Distribution License is available at
+    http://www.eclipse.org/org/documents/edl-v10.php.
+
+  Contributors:
+     Ian Craggs - initial implementation and/or documentation
+*******************************************************************
+"""
+
+
+class PacketTypes:
+
+    """
+    Packet types class.  Includes the AUTH packet for MQTT v5.0.
+
+    Holds constants for each packet type such as PacketTypes.PUBLISH
+    and packet name strings: PacketTypes.Names[PacketTypes.PUBLISH].
+
+    """
+
+    indexes = range(1, 16)
+
+    # Packet types
+    CONNECT, CONNACK, PUBLISH, PUBACK, PUBREC, PUBREL, \
+        PUBCOMP, SUBSCRIBE, SUBACK, UNSUBSCRIBE, UNSUBACK, \
+        PINGREQ, PINGRESP, DISCONNECT, AUTH = indexes
+
+    # Dummy packet type for properties use - will delay only applies to will
+    WILLMESSAGE = 99
+
+    Names = [ "reserved", \
+    "Connect", "Connack", "Publish", "Puback", "Pubrec", "Pubrel", \
+    "Pubcomp", "Subscribe", "Suback", "Unsubscribe", "Unsuback", \
+    "Pingreq", "Pingresp", "Disconnect", "Auth"]

venv/lib/python3.11/site-packages/paho/mqtt/properties.py

@@ -0,0 +1,438 @@
+"""
+*******************************************************************
+  Copyright (c) 2017, 2019 IBM Corp.
+
+  All rights reserved. This program and the accompanying materials
+  are made available under the terms of the Eclipse Public License v2.0
+  and Eclipse Distribution License v1.0 which accompany this distribution.
+
+  The Eclipse Public License is available at
+     http://www.eclipse.org/legal/epl-v10.html
+  and the Eclipse Distribution License is available at
+    http://www.eclipse.org/org/documents/edl-v10.php.
+
+  Contributors:
+     Ian Craggs - initial implementation and/or documentation
+*******************************************************************
+"""
+
+import struct
+import sys
+
+from .packettypes import PacketTypes
+
+
+class MQTTException(Exception):
+    pass
+
+
+class MalformedPacket(MQTTException):
+    pass
+
+
+def writeInt16(length):
+    # serialize a 16 bit integer to network format
+    return bytearray(struct.pack("!H", length))
+
+
+def readInt16(buf):
+    # deserialize a 16 bit integer from network format
+    return struct.unpack("!H", buf[:2])[0]
+
+
+def writeInt32(length):
+    # serialize a 32 bit integer to network format
+    return bytearray(struct.pack("!L", length))
+
+
+def readInt32(buf):
+    # deserialize a 32 bit integer from network format
+    return struct.unpack("!L", buf[:4])[0]
+
+
+def writeUTF(data):
+    # data could be a string, or bytes.  If string, encode into bytes with utf-8
+    if sys.version_info[0] < 3:
+        data = bytearray(data, 'utf-8')
+    else:
+        data = data if type(data) == type(b"") else bytes(data, "utf-8")
+    return writeInt16(len(data)) + data
+
+
+def readUTF(buffer, maxlen):
+    if maxlen >= 2:
+        length = readInt16(buffer)
+    else:
+        raise MalformedPacket("Not enough data to read string length")
+    maxlen -= 2
+    if length > maxlen:
+        raise MalformedPacket("Length delimited string too long")
+    buf = buffer[2:2+length].decode("utf-8")
+    # look for chars which are invalid for MQTT
+    for c in buf: # look for D800-DFFF in the UTF string
+        ord_c = ord(c)
+        if ord_c >= 0xD800 and ord_c <= 0xDFFF:
+            raise MalformedPacket("[MQTT-1.5.4-1] D800-DFFF found in UTF-8 data")
+        if ord_c == 0x00: # look for null in the UTF string
+            raise MalformedPacket("[MQTT-1.5.4-2] Null found in UTF-8 data")
+        if ord_c == 0xFEFF:
+            raise MalformedPacket("[MQTT-1.5.4-3] U+FEFF in UTF-8 data")
+    return buf, length+2
+
+
+def writeBytes(buffer):
+    return writeInt16(len(buffer)) + buffer
+
+
+def readBytes(buffer):
+    length = readInt16(buffer)
+    return buffer[2:2+length], length+2
+
+
+class VariableByteIntegers:  # Variable Byte Integer
+    """
+    MQTT variable byte integer helper class.  Used
+    in several places in MQTT v5.0 properties.
+
+    """
+
+    @staticmethod
+    def encode(x):
+        """
+          Convert an integer 0 <= x <= 268435455 into multi-byte format.
+          Returns the buffer convered from the integer.
+        """
+        assert 0 <= x <= 268435455
+        buffer = b''
+        while 1:
+            digit = x % 128
+            x //= 128
+            if x > 0:
+                digit |= 0x80
+            if sys.version_info[0] >= 3:
+                buffer += bytes([digit])
+            else:
+                buffer += bytes(chr(digit))
+            if x == 0:
+                break
+        return buffer
+
+    @staticmethod
+    def decode(buffer):
+        """
+          Get the value of a multi-byte integer from a buffer
+          Return the value, and the number of bytes used.
+
+          [MQTT-1.5.5-1] the encoded value MUST use the minimum number of bytes necessary to represent the value
+        """
+        multiplier = 1
+        value = 0
+        bytes = 0
+        while 1:
+            bytes += 1
+            digit = buffer[0]
+            buffer = buffer[1:]
+            value += (digit & 127) * multiplier
+            if digit & 128 == 0:
+                break
+            multiplier *= 128
+        return (value, bytes)
+
+
+class Properties(object):
+    """MQTT v5.0 properties class.
+
+    See Properties.names for a list of accepted property names along with their numeric values.
+
+    See Properties.properties for the data type of each property.
+
+    Example of use:
+
+        publish_properties = Properties(PacketTypes.PUBLISH)
+        publish_properties.UserProperty = ("a", "2")
+        publish_properties.UserProperty = ("c", "3")
+
+    First the object is created with packet type as argument, no properties will be present at
+    this point.  Then properties are added as attributes, the name of which is the string property
+    name without the spaces.
+
+    """
+
+    def __init__(self, packetType):
+        self.packetType = packetType
+        self.types = ["Byte", "Two Byte Integer", "Four Byte Integer", "Variable Byte Integer",
+                      "Binary Data", "UTF-8 Encoded String", "UTF-8 String Pair"]
+
+        self.names = {
+            "Payload Format Indicator": 1,
+            "Message Expiry Interval": 2,
+            "Content Type": 3,
+            "Response Topic": 8,
+            "Correlation Data": 9,
+            "Subscription Identifier": 11,
+            "Session Expiry Interval": 17,
+            "Assigned Client Identifier": 18,
+            "Server Keep Alive": 19,
+            "Authentication Method": 21,
+            "Authentication Data": 22,
+            "Request Problem Information": 23,
+            "Will Delay Interval": 24,
+            "Request Response Information": 25,
+            "Response Information": 26,
+            "Server Reference": 28,
+            "Reason String": 31,
+            "Receive Maximum": 33,
+            "Topic Alias Maximum": 34,
+            "Topic Alias": 35,
+            "Maximum QoS": 36,
+            "Retain Available": 37,
+            "User Property": 38,
+            "Maximum Packet Size": 39,
+            "Wildcard Subscription Available": 40,
+            "Subscription Identifier Available": 41,
+            "Shared Subscription Available": 42
+        }
+
+        self.properties = {
+            # id:  type, packets
+            # payload format indicator
+            1: (self.types.index("Byte"), [PacketTypes.PUBLISH, PacketTypes.WILLMESSAGE]),
+            2: (self.types.index("Four Byte Integer"), [PacketTypes.PUBLISH, PacketTypes.WILLMESSAGE]),
+            3: (self.types.index("UTF-8 Encoded String"), [PacketTypes.PUBLISH, PacketTypes.WILLMESSAGE]),
+            8: (self.types.index("UTF-8 Encoded String"), [PacketTypes.PUBLISH, PacketTypes.WILLMESSAGE]),
+            9: (self.types.index("Binary Data"), [PacketTypes.PUBLISH, PacketTypes.WILLMESSAGE]),
+            11: (self.types.index("Variable Byte Integer"),
+                 [PacketTypes.PUBLISH, PacketTypes.SUBSCRIBE]),
+            17: (self.types.index("Four Byte Integer"),
+                 [PacketTypes.CONNECT, PacketTypes.CONNACK, PacketTypes.DISCONNECT]),
+            18: (self.types.index("UTF-8 Encoded String"), [PacketTypes.CONNACK]),
+            19: (self.types.index("Two Byte Integer"), [PacketTypes.CONNACK]),
+            21: (self.types.index("UTF-8 Encoded String"),
+                 [PacketTypes.CONNECT, PacketTypes.CONNACK, PacketTypes.AUTH]),
+            22: (self.types.index("Binary Data"),
+                 [PacketTypes.CONNECT, PacketTypes.CONNACK, PacketTypes.AUTH]),
+            23: (self.types.index("Byte"),
+                 [PacketTypes.CONNECT]),
+            24: (self.types.index("Four Byte Integer"), [PacketTypes.WILLMESSAGE]),
+            25: (self.types.index("Byte"), [PacketTypes.CONNECT]),
+            26: (self.types.index("UTF-8 Encoded String"), [PacketTypes.CONNACK]),
+            28: (self.types.index("UTF-8 Encoded String"),
+                 [PacketTypes.CONNACK, PacketTypes.DISCONNECT]),
+            31: (self.types.index("UTF-8 Encoded String"),
+                 [PacketTypes.CONNACK, PacketTypes.PUBACK, PacketTypes.PUBREC,
+                  PacketTypes.PUBREL, PacketTypes.PUBCOMP, PacketTypes.SUBACK,
+                  PacketTypes.UNSUBACK, PacketTypes.DISCONNECT, PacketTypes.AUTH]),
+            33: (self.types.index("Two Byte Integer"),
+                 [PacketTypes.CONNECT, PacketTypes.CONNACK]),
+            34: (self.types.index("Two Byte Integer"),
+                 [PacketTypes.CONNECT, PacketTypes.CONNACK]),
+            35: (self.types.index("Two Byte Integer"), [PacketTypes.PUBLISH]),
+            36: (self.types.index("Byte"), [PacketTypes.CONNACK]),
+            37: (self.types.index("Byte"), [PacketTypes.CONNACK]),
+            38: (self.types.index("UTF-8 String Pair"),
+                 [PacketTypes.CONNECT, PacketTypes.CONNACK,
+                  PacketTypes.PUBLISH, PacketTypes.PUBACK,
+                  PacketTypes.PUBREC, PacketTypes.PUBREL, PacketTypes.PUBCOMP,
+                  PacketTypes.SUBSCRIBE, PacketTypes.SUBACK,
+                  PacketTypes.UNSUBSCRIBE, PacketTypes.UNSUBACK,
+                  PacketTypes.DISCONNECT, PacketTypes.AUTH, PacketTypes.WILLMESSAGE]),
+            39: (self.types.index("Four Byte Integer"),
+                 [PacketTypes.CONNECT, PacketTypes.CONNACK]),
+            40: (self.types.index("Byte"), [PacketTypes.CONNACK]),
+            41: (self.types.index("Byte"), [PacketTypes.CONNACK]),
+            42: (self.types.index("Byte"), [PacketTypes.CONNACK]),
+        }
+
+    def allowsMultiple(self, compressedName):
+        return self.getIdentFromName(compressedName) in [11, 38]
+
+    def getIdentFromName(self, compressedName):
+        # return the identifier corresponding to the property name
+        result = -1
+        for name in self.names.keys():
+            if compressedName == name.replace(' ', ''):
+                result = self.names[name]
+                break
+        return result
+
+    def __setattr__(self, name, value):
+        name = name.replace(' ', '')
+        privateVars = ["packetType", "types", "names", "properties"]
+        if name in privateVars:
+            object.__setattr__(self, name, value)
+        else:
+            # the name could have spaces in, or not.  Remove spaces before assignment
+            if name not in [aname.replace(' ', '') for aname in self.names.keys()]:
+                raise MQTTException(
+                    "Property name must be one of "+str(self.names.keys()))
+            # check that this attribute applies to the packet type
+            if self.packetType not in self.properties[self.getIdentFromName(name)][1]:
+                raise MQTTException("Property %s does not apply to packet type %s"
+                                    % (name, PacketTypes.Names[self.packetType]))
+
+            # Check for forbidden values
+            if type(value) != type([]):
+                if name in ["ReceiveMaximum", "TopicAlias"] \
+                        and (value < 1 or value > 65535):
+
+                    raise MQTTException(
+                        "%s property value must be in the range 1-65535" % (name))
+                elif name in ["TopicAliasMaximum"] \
+                        and (value < 0 or value > 65535):
+
+                    raise MQTTException(
+                        "%s property value must be in the range 0-65535" % (name))
+                elif name in ["MaximumPacketSize", "SubscriptionIdentifier"] \
+                        and (value < 1 or value > 268435455):
+
+                    raise MQTTException(
+                        "%s property value must be in the range 1-268435455" % (name))
+                elif name in ["RequestResponseInformation", "RequestProblemInformation", "PayloadFormatIndicator"] \
+                        and (value != 0 and value != 1):
+
+                    raise MQTTException(
+                        "%s property value must be 0 or 1" % (name))
+
+            if self.allowsMultiple(name):
+                if type(value) != type([]):
+                    value = [value]
+                if hasattr(self, name):
+                    value = object.__getattribute__(self, name) + value
+            object.__setattr__(self, name, value)
+
+    def __str__(self):
+        buffer = "["
+        first = True
+        for name in self.names.keys():
+            compressedName = name.replace(' ', '')
+            if hasattr(self, compressedName):
+                if not first:
+                    buffer += ", "
+                buffer += compressedName + " : " + \
+                    str(getattr(self, compressedName))
+                first = False
+        buffer += "]"
+        return buffer
+
+    def json(self):
+        data = {}
+        for name in self.names.keys():
+            compressedName = name.replace(' ', '')
+            if hasattr(self, compressedName):
+                val = getattr(self, compressedName)
+                if compressedName == 'CorrelationData' and isinstance(val, bytes):
+                    data[compressedName] = val.hex()
+                else:
+                    data[compressedName] = val
+        return data
+
+    def isEmpty(self):
+        rc = True
+        for name in self.names.keys():
+            compressedName = name.replace(' ', '')
+            if hasattr(self, compressedName):
+                rc = False
+                break
+        return rc
+
+    def clear(self):
+        for name in self.names.keys():
+            compressedName = name.replace(' ', '')
+            if hasattr(self, compressedName):
+                delattr(self, compressedName)
+
+    def writeProperty(self, identifier, type, value):
+        buffer = b""
+        buffer += VariableByteIntegers.encode(identifier)  # identifier
+        if type == self.types.index("Byte"):  # value
+            if sys.version_info[0] < 3:
+                buffer += chr(value)
+            else:
+                buffer += bytes([value])
+        elif type == self.types.index("Two Byte Integer"):
+            buffer += writeInt16(value)
+        elif type == self.types.index("Four Byte Integer"):
+            buffer += writeInt32(value)
+        elif type == self.types.index("Variable Byte Integer"):
+            buffer += VariableByteIntegers.encode(value)
+        elif type == self.types.index("Binary Data"):
+            buffer += writeBytes(value)
+        elif type == self.types.index("UTF-8 Encoded String"):
+            buffer += writeUTF(value)
+        elif type == self.types.index("UTF-8 String Pair"):
+            buffer += writeUTF(value[0]) + writeUTF(value[1])
+        return buffer
+
+    def pack(self):
+        # serialize properties into buffer for sending over network
+        buffer = b""
+        for name in self.names.keys():
+            compressedName = name.replace(' ', '')
+            if hasattr(self, compressedName):
+                identifier = self.getIdentFromName(compressedName)
+                attr_type = self.properties[identifier][0]
+                if self.allowsMultiple(compressedName):
+                    for prop in getattr(self, compressedName):
+                        buffer += self.writeProperty(identifier,
+                                                     attr_type, prop)
+                else:
+                    buffer += self.writeProperty(identifier, attr_type,
+                                                 getattr(self, compressedName))
+        return VariableByteIntegers.encode(len(buffer)) + buffer
+
+    def readProperty(self, buffer, type, propslen):
+        if type == self.types.index("Byte"):
+            value = buffer[0]
+            valuelen = 1
+        elif type == self.types.index("Two Byte Integer"):
+            value = readInt16(buffer)
+            valuelen = 2
+        elif type == self.types.index("Four Byte Integer"):
+            value = readInt32(buffer)
+            valuelen = 4
+        elif type == self.types.index("Variable Byte Integer"):
+            value, valuelen = VariableByteIntegers.decode(buffer)
+        elif type == self.types.index("Binary Data"):
+            value, valuelen = readBytes(buffer)
+        elif type == self.types.index("UTF-8 Encoded String"):
+            value, valuelen = readUTF(buffer, propslen)
+        elif type == self.types.index("UTF-8 String Pair"):
+            value, valuelen = readUTF(buffer, propslen)
+            buffer = buffer[valuelen:]  # strip the bytes used by the value
+            value1, valuelen1 = readUTF(buffer, propslen - valuelen)
+            value = (value, value1)
+            valuelen += valuelen1
+        return value, valuelen
+
+    def getNameFromIdent(self, identifier):
+        rc = None
+        for name in self.names:
+            if self.names[name] == identifier:
+                rc = name
+        return rc
+
+    def unpack(self, buffer):
+        if sys.version_info[0] < 3:
+            buffer = bytearray(buffer)
+        self.clear()
+        # deserialize properties into attributes from buffer received from network
+        propslen, VBIlen = VariableByteIntegers.decode(buffer)
+        buffer = buffer[VBIlen:]  # strip the bytes used by the VBI
+        propslenleft = propslen
+        while propslenleft > 0:  # properties length is 0 if there are none
+            identifier, VBIlen2 = VariableByteIntegers.decode(
+                buffer)  # property identifier
+            buffer = buffer[VBIlen2:]  # strip the bytes used by the VBI
+            propslenleft -= VBIlen2
+            attr_type = self.properties[identifier][0]
+            value, valuelen = self.readProperty(
+                buffer, attr_type, propslenleft)
+            buffer = buffer[valuelen:]  # strip the bytes used by the value
+            propslenleft -= valuelen
+            propname = self.getNameFromIdent(identifier)
+            compressedName = propname.replace(' ', '')
+            if not self.allowsMultiple(compressedName) and hasattr(self, compressedName):
+                raise MQTTException(
+                    "Property '%s' must not exist more than once" % property)
+            setattr(self, propname, value)
+        return self, propslen + VBIlen

venv/lib/python3.11/site-packages/paho/mqtt/publish.py

@@ -0,0 +1,241 @@
+# Copyright (c) 2014 Roger Light <roger@atchoo.org>
+#
+# All rights reserved. This program and the accompanying materials
+# are made available under the terms of the Eclipse Public License v2.0
+# and Eclipse Distribution License v1.0 which accompany this distribution.
+#
+# The Eclipse Public License is available at
+#    http://www.eclipse.org/legal/epl-v10.html
+# and the Eclipse Distribution License is available at
+#   http://www.eclipse.org/org/documents/edl-v10.php.
+#
+# Contributors:
+#    Roger Light - initial API and implementation
+
+"""
+This module provides some helper functions to allow straightforward publishing
+of messages in a one-shot manner. In other words, they are useful for the
+situation where you have a single/multiple messages you want to publish to a
+broker, then disconnect and nothing else is required.
+"""
+from __future__ import absolute_import
+
+import collections
+
+try:
+    from collections.abc import Iterable
+except ImportError:
+    from collections import Iterable
+
+from .. import mqtt
+from . import client as paho
+
+
+def _do_publish(client):
+    """Internal function"""
+
+    message = client._userdata.popleft()
+
+    if isinstance(message, dict):
+        client.publish(**message)
+    elif isinstance(message, (tuple, list)):
+        client.publish(*message)
+    else:
+        raise TypeError('message must be a dict, tuple, or list')
+
+
+def _on_connect(client, userdata, flags, rc):
+    """Internal callback"""
+    #pylint: disable=invalid-name, unused-argument
+
+    if rc == 0:
+        if len(userdata) > 0:
+            _do_publish(client)
+    else:
+        raise mqtt.MQTTException(paho.connack_string(rc))
+
+def _on_connect_v5(client, userdata, flags, rc, properties):
+    """Internal v5 callback"""
+    _on_connect(client, userdata, flags, rc)
+
+def _on_publish(client, userdata, mid):
+    """Internal callback"""
+    #pylint: disable=unused-argument
+
+    if len(userdata) == 0:
+        client.disconnect()
+    else:
+        _do_publish(client)
+
+
+def multiple(msgs, hostname="localhost", port=1883, client_id="", keepalive=60,
+             will=None, auth=None, tls=None, protocol=paho.MQTTv311,
+             transport="tcp", proxy_args=None):
+    """Publish multiple messages to a broker, then disconnect cleanly.
+
+    This function creates an MQTT client, connects to a broker and publishes a
+    list of messages. Once the messages have been delivered, it disconnects
+    cleanly from the broker.
+
+    msgs : a list of messages to publish. Each message is either a dict or a
+           tuple.
+
+           If a dict, only the topic must be present. Default values will be
+           used for any missing arguments. The dict must be of the form:
+
+           msg = {'topic':"<topic>", 'payload':"<payload>", 'qos':<qos>,
+           'retain':<retain>}
+           topic must be present and may not be empty.
+           If payload is "", None or not present then a zero length payload
+           will be published.
+           If qos is not present, the default of 0 is used.
+           If retain is not present, the default of False is used.
+
+           If a tuple, then it must be of the form:
+           ("<topic>", "<payload>", qos, retain)
+
+    hostname : a string containing the address of the broker to connect to.
+               Defaults to localhost.
+
+    port : the port to connect to the broker on. Defaults to 1883.
+
+    client_id : the MQTT client id to use. If "" or None, the Paho library will
+                generate a client id automatically.
+
+    keepalive : the keepalive timeout value for the client. Defaults to 60
+                seconds.
+
+    will : a dict containing will parameters for the client: will = {'topic':
+           "<topic>", 'payload':"<payload">, 'qos':<qos>, 'retain':<retain>}.
+           Topic is required, all other parameters are optional and will
+           default to None, 0 and False respectively.
+           Defaults to None, which indicates no will should be used.
+
+    auth : a dict containing authentication parameters for the client:
+           auth = {'username':"<username>", 'password':"<password>"}
+           Username is required, password is optional and will default to None
+           if not provided.
+           Defaults to None, which indicates no authentication is to be used.
+
+    tls : a dict containing TLS configuration parameters for the client:
+          dict = {'ca_certs':"<ca_certs>", 'certfile':"<certfile>",
+          'keyfile':"<keyfile>", 'tls_version':"<tls_version>",
+          'ciphers':"<ciphers">, 'insecure':"<bool>"}
+          ca_certs is required, all other parameters are optional and will
+          default to None if not provided, which results in the client using
+          the default behaviour - see the paho.mqtt.client documentation.
+          Alternatively, tls input can be an SSLContext object, which will be
+          processed using the tls_set_context method.
+          Defaults to None, which indicates that TLS should not be used.
+
+    transport : set to "tcp" to use the default setting of transport which is
+          raw TCP. Set to "websockets" to use WebSockets as the transport.
+    proxy_args: a dictionary that will be given to the client.
+    """
+
+    if not isinstance(msgs, Iterable):
+        raise TypeError('msgs must be an iterable')
+
+
+    client = paho.Client(client_id=client_id, userdata=collections.deque(msgs),
+                         protocol=protocol, transport=transport)
+
+    client.on_publish = _on_publish
+    if protocol == mqtt.client.MQTTv5:
+        client.on_connect = _on_connect_v5
+    else:
+        client.on_connect = _on_connect
+
+    if proxy_args is not None:
+        client.proxy_set(**proxy_args)
+
+    if auth:
+        username = auth.get('username')
+        if username:
+            password = auth.get('password')
+            client.username_pw_set(username, password)
+        else:
+            raise KeyError("The 'username' key was not found, this is "
+                           "required for auth")
+
+    if will is not None:
+        client.will_set(**will)
+
+    if tls is not None:
+        if isinstance(tls, dict):
+            insecure = tls.pop('insecure', False)
+            client.tls_set(**tls)
+            if insecure:
+                # Must be set *after* the `client.tls_set()` call since it sets
+                # up the SSL context that `client.tls_insecure_set` alters.
+                client.tls_insecure_set(insecure)
+        else:
+            # Assume input is SSLContext object
+            client.tls_set_context(tls)
+
+    client.connect(hostname, port, keepalive)
+    client.loop_forever()
+
+
+def single(topic, payload=None, qos=0, retain=False, hostname="localhost",
+           port=1883, client_id="", keepalive=60, will=None, auth=None,
+           tls=None, protocol=paho.MQTTv311, transport="tcp", proxy_args=None):
+    """Publish a single message to a broker, then disconnect cleanly.
+
+    This function creates an MQTT client, connects to a broker and publishes a
+    single message. Once the message has been delivered, it disconnects cleanly
+    from the broker.
+
+    topic : the only required argument must be the topic string to which the
+            payload will be published.
+
+    payload : the payload to be published. If "" or None, a zero length payload
+              will be published.
+
+    qos : the qos to use when publishing,  default to 0.
+
+    retain : set the message to be retained (True) or not (False).
+
+    hostname : a string containing the address of the broker to connect to.
+               Defaults to localhost.
+
+    port : the port to connect to the broker on. Defaults to 1883.
+
+    client_id : the MQTT client id to use. If "" or None, the Paho library will
+                generate a client id automatically.
+
+    keepalive : the keepalive timeout value for the client. Defaults to 60
+                seconds.
+
+    will : a dict containing will parameters for the client: will = {'topic':
+           "<topic>", 'payload':"<payload">, 'qos':<qos>, 'retain':<retain>}.
+           Topic is required, all other parameters are optional and will
+           default to None, 0 and False respectively.
+           Defaults to None, which indicates no will should be used.
+
+    auth : a dict containing authentication parameters for the client:
+           auth = {'username':"<username>", 'password':"<password>"}
+           Username is required, password is optional and will default to None
+           if not provided.
+           Defaults to None, which indicates no authentication is to be used.
+
+    tls : a dict containing TLS configuration parameters for the client:
+          dict = {'ca_certs':"<ca_certs>", 'certfile':"<certfile>",
+          'keyfile':"<keyfile>", 'tls_version':"<tls_version>",
+          'ciphers':"<ciphers">, 'insecure':"<bool>"}
+          ca_certs is required, all other parameters are optional and will
+          default to None if not provided, which results in the client using
+          the default behaviour - see the paho.mqtt.client documentation.
+          Defaults to None, which indicates that TLS should not be used.
+          Alternatively, tls input can be an SSLContext object, which will be
+          processed using the tls_set_context method.
+
+    transport : set to "tcp" to use the default setting of transport which is
+          raw TCP. Set to "websockets" to use WebSockets as the transport.
+    proxy_args: a dictionary that will be given to the client.
+    """
+
+    msg = {'topic':topic, 'payload':payload, 'qos':qos, 'retain':retain}
+
+    multiple([msg], hostname, port, client_id, keepalive, will, auth, tls,
+             protocol, transport, proxy_args)

venv/lib/python3.11/site-packages/paho/mqtt/reasoncodes.py

@@ -0,0 +1,192 @@
+"""
+*******************************************************************
+  Copyright (c) 2017, 2019 IBM Corp.
+
+  All rights reserved. This program and the accompanying materials
+  are made available under the terms of the Eclipse Public License v2.0
+  and Eclipse Distribution License v1.0 which accompany this distribution.
+
+  The Eclipse Public License is available at
+     http://www.eclipse.org/legal/epl-v10.html
+  and the Eclipse Distribution License is available at
+    http://www.eclipse.org/org/documents/edl-v10.php.
+
+  Contributors:
+     Ian Craggs - initial implementation and/or documentation
+*******************************************************************
+"""
+
+import sys
+
+from .packettypes import PacketTypes
+
+
+class ReasonCodes:
+    """MQTT version 5.0 reason codes class.
+
+    See ReasonCodes.names for a list of possible numeric values along with their
+    names and the packets to which they apply.
+
+    """
+
+    def __init__(self, packetType, aName="Success", identifier=-1):
+        """
+        packetType: the type of the packet, such as PacketTypes.CONNECT that
+            this reason code will be used with.  Some reason codes have different
+            names for the same identifier when used a different packet type.
+
+        aName: the String name of the reason code to be created.  Ignored
+            if the identifier is set.
+
+        identifier: an integer value of the reason code to be created.
+
+        """
+
+        self.packetType = packetType
+        self.names = {
+            0: {"Success": [PacketTypes.CONNACK, PacketTypes.PUBACK,
+                            PacketTypes.PUBREC, PacketTypes.PUBREL, PacketTypes.PUBCOMP,
+                            PacketTypes.UNSUBACK, PacketTypes.AUTH],
+                "Normal disconnection": [PacketTypes.DISCONNECT],
+                "Granted QoS 0": [PacketTypes.SUBACK]},
+            1: {"Granted QoS 1": [PacketTypes.SUBACK]},
+            2: {"Granted QoS 2": [PacketTypes.SUBACK]},
+            4: {"Disconnect with will message": [PacketTypes.DISCONNECT]},
+            16: {"No matching subscribers":
+                 [PacketTypes.PUBACK, PacketTypes.PUBREC]},
+            17: {"No subscription found": [PacketTypes.UNSUBACK]},
+            24: {"Continue authentication": [PacketTypes.AUTH]},
+            25: {"Re-authenticate": [PacketTypes.AUTH]},
+            128: {"Unspecified error": [PacketTypes.CONNACK, PacketTypes.PUBACK,
+                                        PacketTypes.PUBREC, PacketTypes.SUBACK, PacketTypes.UNSUBACK,
+                                        PacketTypes.DISCONNECT], },
+            129: {"Malformed packet":
+                  [PacketTypes.CONNACK, PacketTypes.DISCONNECT]},
+            130: {"Protocol error":
+                  [PacketTypes.CONNACK, PacketTypes.DISCONNECT]},
+            131: {"Implementation specific error": [PacketTypes.CONNACK,
+                                                    PacketTypes.PUBACK, PacketTypes.PUBREC, PacketTypes.SUBACK,
+                                                    PacketTypes.UNSUBACK, PacketTypes.DISCONNECT], },
+            132: {"Unsupported protocol version": [PacketTypes.CONNACK]},
+            133: {"Client identifier not valid": [PacketTypes.CONNACK]},
+            134: {"Bad user name or password": [PacketTypes.CONNACK]},
+            135: {"Not authorized": [PacketTypes.CONNACK, PacketTypes.PUBACK,
+                                     PacketTypes.PUBREC, PacketTypes.SUBACK, PacketTypes.UNSUBACK,
+                                     PacketTypes.DISCONNECT], },
+            136: {"Server unavailable": [PacketTypes.CONNACK]},
+            137: {"Server busy": [PacketTypes.CONNACK, PacketTypes.DISCONNECT]},
+            138: {"Banned": [PacketTypes.CONNACK]},
+            139: {"Server shutting down": [PacketTypes.DISCONNECT]},
+            140: {"Bad authentication method":
+                  [PacketTypes.CONNACK, PacketTypes.DISCONNECT]},
+            141: {"Keep alive timeout": [PacketTypes.DISCONNECT]},
+            142: {"Session taken over": [PacketTypes.DISCONNECT]},
+            143: {"Topic filter invalid":
+                  [PacketTypes.SUBACK, PacketTypes.UNSUBACK, PacketTypes.DISCONNECT]},
+            144: {"Topic name invalid":
+                  [PacketTypes.CONNACK, PacketTypes.PUBACK,
+                   PacketTypes.PUBREC, PacketTypes.DISCONNECT]},
+            145: {"Packet identifier in use":
+                  [PacketTypes.PUBACK, PacketTypes.PUBREC,
+                   PacketTypes.SUBACK, PacketTypes.UNSUBACK]},
+            146: {"Packet identifier not found":
+                  [PacketTypes.PUBREL, PacketTypes.PUBCOMP]},
+            147: {"Receive maximum exceeded": [PacketTypes.DISCONNECT]},
+            148: {"Topic alias invalid": [PacketTypes.DISCONNECT]},
+            149: {"Packet too large": [PacketTypes.CONNACK, PacketTypes.DISCONNECT]},
+            150: {"Message rate too high": [PacketTypes.DISCONNECT]},
+            151: {"Quota exceeded": [PacketTypes.CONNACK, PacketTypes.PUBACK,
+                                     PacketTypes.PUBREC, PacketTypes.SUBACK, PacketTypes.DISCONNECT], },
+            152: {"Administrative action": [PacketTypes.DISCONNECT]},
+            153: {"Payload format invalid":
+                  [PacketTypes.PUBACK, PacketTypes.PUBREC, PacketTypes.DISCONNECT]},
+            154: {"Retain not supported":
+                  [PacketTypes.CONNACK, PacketTypes.DISCONNECT]},
+            155: {"QoS not supported":
+                  [PacketTypes.CONNACK, PacketTypes.DISCONNECT]},
+            156: {"Use another server":
+                  [PacketTypes.CONNACK, PacketTypes.DISCONNECT]},
+            157: {"Server moved":
+                  [PacketTypes.CONNACK, PacketTypes.DISCONNECT]},
+            158: {"Shared subscription not supported":
+                  [PacketTypes.SUBACK, PacketTypes.DISCONNECT]},
+            159: {"Connection rate exceeded":
+                  [PacketTypes.CONNACK, PacketTypes.DISCONNECT]},
+            160: {"Maximum connect time":
+                  [PacketTypes.DISCONNECT]},
+            161: {"Subscription identifiers not supported":
+                  [PacketTypes.SUBACK, PacketTypes.DISCONNECT]},
+            162: {"Wildcard subscription not supported":
+                  [PacketTypes.SUBACK, PacketTypes.DISCONNECT]},
+        }
+        if identifier == -1:
+            if packetType == PacketTypes.DISCONNECT and aName == "Success":
+                aName = "Normal disconnection"
+            self.set(aName)
+        else:
+            self.value = identifier
+            self.getName()  # check it's good
+
+    def __getName__(self, packetType, identifier):
+        """
+        Get the reason code string name for a specific identifier.
+        The name can vary by packet type for the same identifier, which
+        is why the packet type is also required.
+
+        Used when displaying the reason code.
+        """
+        assert identifier in self.names.keys(), identifier
+        names = self.names[identifier]
+        namelist = [name for name in names.keys() if packetType in names[name]]
+        assert len(namelist) == 1
+        return namelist[0]
+
+    def getId(self, name):
+        """
+        Get the numeric id corresponding to a reason code name.
+
+        Used when setting the reason code for a packetType
+        check that only valid codes for the packet are set.
+        """
+        identifier = None
+        for code in self.names.keys():
+            if name in self.names[code].keys():
+                if self.packetType in self.names[code][name]:
+                    identifier = code
+                break
+        assert identifier is not None, name
+        return identifier
+
+    def set(self, name):
+        self.value = self.getId(name)
+
+    def unpack(self, buffer):
+        c = buffer[0]
+        if sys.version_info[0] < 3:
+            c = ord(c)
+        name = self.__getName__(self.packetType, c)
+        self.value = self.getId(name)
+        return 1
+
+    def getName(self):
+        """Returns the reason code name corresponding to the numeric value which is set.
+        """
+        return self.__getName__(self.packetType, self.value)
+
+    def __eq__(self, other):
+        if isinstance(other, int):
+            return self.value == other
+        if isinstance(other, str):
+            return self.value == str(self)
+        if isinstance(other, ReasonCodes):
+            return self.value == other.value
+        return False
+
+    def __str__(self):
+        return self.getName()
+
+    def json(self):
+        return self.getName()
+
+    def pack(self):
+        return bytearray([self.value])

venv/lib/python3.11/site-packages/paho/mqtt/subscribe.py

@@ -0,0 +1,274 @@
+# Copyright (c) 2016 Roger Light <roger@atchoo.org>
+#
+# All rights reserved. This program and the accompanying materials
+# are made available under the terms of the Eclipse Public License v2.0
+# and Eclipse Distribution License v1.0 which accompany this distribution.
+#
+# The Eclipse Public License is available at
+#    http://www.eclipse.org/legal/epl-v10.html
+# and the Eclipse Distribution License is available at
+#   http://www.eclipse.org/org/documents/edl-v10.php.
+#
+# Contributors:
+#    Roger Light - initial API and implementation
+
+"""
+This module provides some helper functions to allow straightforward subscribing
+to topics and retrieving messages. The two functions are simple(), which
+returns one or messages matching a set of topics, and callback() which allows
+you to pass a callback for processing of messages.
+"""
+from __future__ import absolute_import
+
+from .. import mqtt
+from . import client as paho
+
+
+def _on_connect_v5(client, userdata, flags, rc, properties):
+    """Internal callback"""
+    if rc != 0:
+        raise mqtt.MQTTException(paho.connack_string(rc))
+
+    if isinstance(userdata['topics'], list):
+        for topic in userdata['topics']:
+            client.subscribe(topic, userdata['qos'])
+    else:
+        client.subscribe(userdata['topics'], userdata['qos'])
+
+def _on_connect(client, userdata, flags, rc):
+    """Internal v5 callback"""
+    _on_connect_v5(client, userdata, flags, rc, None)
+
+
+def _on_message_callback(client, userdata, message):
+    """Internal callback"""
+    userdata['callback'](client, userdata['userdata'], message)
+
+
+def _on_message_simple(client, userdata, message):
+    """Internal callback"""
+
+    if userdata['msg_count'] == 0:
+        return
+
+    # Don't process stale retained messages if 'retained' was false
+    if message.retain and not userdata['retained']:
+        return
+
+    userdata['msg_count'] = userdata['msg_count'] - 1
+
+    if userdata['messages'] is None and userdata['msg_count'] == 0:
+        userdata['messages'] = message
+        client.disconnect()
+        return
+
+    userdata['messages'].append(message)
+    if userdata['msg_count'] == 0:
+        client.disconnect()
+
+
+def callback(callback, topics, qos=0, userdata=None, hostname="localhost",
+             port=1883, client_id="", keepalive=60, will=None, auth=None,
+             tls=None, protocol=paho.MQTTv311, transport="tcp",
+             clean_session=True, proxy_args=None):
+    """Subscribe to a list of topics and process them in a callback function.
+
+    This function creates an MQTT client, connects to a broker and subscribes
+    to a list of topics. Incoming messages are processed by the user provided
+    callback.  This is a blocking function and will never return.
+
+    callback : function of the form "on_message(client, userdata, message)" for
+               processing the messages received.
+
+    topics : either a string containing a single topic to subscribe to, or a
+             list of topics to subscribe to.
+
+    qos : the qos to use when subscribing. This is applied to all topics.
+
+    userdata : passed to the callback
+
+    hostname : a string containing the address of the broker to connect to.
+               Defaults to localhost.
+
+    port : the port to connect to the broker on. Defaults to 1883.
+
+    client_id : the MQTT client id to use. If "" or None, the Paho library will
+                generate a client id automatically.
+
+    keepalive : the keepalive timeout value for the client. Defaults to 60
+                seconds.
+
+    will : a dict containing will parameters for the client: will = {'topic':
+           "<topic>", 'payload':"<payload">, 'qos':<qos>, 'retain':<retain>}.
+           Topic is required, all other parameters are optional and will
+           default to None, 0 and False respectively.
+           Defaults to None, which indicates no will should be used.
+
+    auth : a dict containing authentication parameters for the client:
+           auth = {'username':"<username>", 'password':"<password>"}
+           Username is required, password is optional and will default to None
+           if not provided.
+           Defaults to None, which indicates no authentication is to be used.
+
+    tls : a dict containing TLS configuration parameters for the client:
+          dict = {'ca_certs':"<ca_certs>", 'certfile':"<certfile>",
+          'keyfile':"<keyfile>", 'tls_version':"<tls_version>",
+          'ciphers':"<ciphers">, 'insecure':"<bool>"}
+          ca_certs is required, all other parameters are optional and will
+          default to None if not provided, which results in the client using
+          the default behaviour - see the paho.mqtt.client documentation.
+          Alternatively, tls input can be an SSLContext object, which will be
+          processed using the tls_set_context method.
+          Defaults to None, which indicates that TLS should not be used.
+
+    transport : set to "tcp" to use the default setting of transport which is
+          raw TCP. Set to "websockets" to use WebSockets as the transport.
+
+    clean_session : a boolean that determines the client type. If True,
+                    the broker will remove all information about this client
+                    when it disconnects. If False, the client is a persistent
+                    client and subscription information and queued messages
+                    will be retained when the client disconnects.
+                    Defaults to True.
+
+    proxy_args: a dictionary that will be given to the client.
+    """
+
+    if qos < 0 or qos > 2:
+        raise ValueError('qos must be in the range 0-2')
+
+    callback_userdata = {
+        'callback':callback,
+        'topics':topics,
+        'qos':qos,
+        'userdata':userdata}
+
+    client = paho.Client(client_id=client_id, userdata=callback_userdata,
+                         protocol=protocol, transport=transport,
+                         clean_session=clean_session)
+    client.on_message = _on_message_callback
+    if protocol == mqtt.client.MQTTv5:
+        client.on_connect = _on_connect_v5
+    else:
+        client.on_connect = _on_connect
+
+    if proxy_args is not None:
+        client.proxy_set(**proxy_args)
+
+    if auth:
+        username = auth.get('username')
+        if username:
+            password = auth.get('password')
+            client.username_pw_set(username, password)
+        else:
+            raise KeyError("The 'username' key was not found, this is "
+                           "required for auth")
+
+    if will is not None:
+        client.will_set(**will)
+
+    if tls is not None:
+        if isinstance(tls, dict):
+            insecure = tls.pop('insecure', False)
+            client.tls_set(**tls)
+            if insecure:
+                # Must be set *after* the `client.tls_set()` call since it sets
+                # up the SSL context that `client.tls_insecure_set` alters.
+                client.tls_insecure_set(insecure)
+        else:
+            # Assume input is SSLContext object
+            client.tls_set_context(tls)
+
+    client.connect(hostname, port, keepalive)
+    client.loop_forever()
+
+
+def simple(topics, qos=0, msg_count=1, retained=True, hostname="localhost",
+           port=1883, client_id="", keepalive=60, will=None, auth=None,
+           tls=None, protocol=paho.MQTTv311, transport="tcp",
+           clean_session=True, proxy_args=None):
+    """Subscribe to a list of topics and return msg_count messages.
+
+    This function creates an MQTT client, connects to a broker and subscribes
+    to a list of topics. Once "msg_count" messages have been received, it
+    disconnects cleanly from the broker and returns the messages.
+
+    topics : either a string containing a single topic to subscribe to, or a
+             list of topics to subscribe to.
+
+    qos : the qos to use when subscribing. This is applied to all topics.
+
+    msg_count : the number of messages to retrieve from the broker.
+                if msg_count == 1 then a single MQTTMessage will be returned.
+                if msg_count > 1 then a list of MQTTMessages will be returned.
+
+    retained : If set to True, retained messages will be processed the same as
+               non-retained messages. If set to False, retained messages will
+               be ignored. This means that with retained=False and msg_count=1,
+               the function will return the first message received that does
+               not have the retained flag set.
+
+    hostname : a string containing the address of the broker to connect to.
+               Defaults to localhost.
+
+    port : the port to connect to the broker on. Defaults to 1883.
+
+    client_id : the MQTT client id to use. If "" or None, the Paho library will
+                generate a client id automatically.
+
+    keepalive : the keepalive timeout value for the client. Defaults to 60
+                seconds.
+
+    will : a dict containing will parameters for the client: will = {'topic':
+           "<topic>", 'payload':"<payload">, 'qos':<qos>, 'retain':<retain>}.
+           Topic is required, all other parameters are optional and will
+           default to None, 0 and False respectively.
+           Defaults to None, which indicates no will should be used.
+
+    auth : a dict containing authentication parameters for the client:
+           auth = {'username':"<username>", 'password':"<password>"}
+           Username is required, password is optional and will default to None
+           if not provided.
+           Defaults to None, which indicates no authentication is to be used.
+
+    tls : a dict containing TLS configuration parameters for the client:
+          dict = {'ca_certs':"<ca_certs>", 'certfile':"<certfile>",
+          'keyfile':"<keyfile>", 'tls_version':"<tls_version>",
+          'ciphers':"<ciphers">, 'insecure':"<bool>"}
+          ca_certs is required, all other parameters are optional and will
+          default to None if not provided, which results in the client using
+          the default behaviour - see the paho.mqtt.client documentation.
+          Alternatively, tls input can be an SSLContext object, which will be
+          processed using the tls_set_context method.
+          Defaults to None, which indicates that TLS should not be used.
+
+    transport : set to "tcp" to use the default setting of transport which is
+          raw TCP. Set to "websockets" to use WebSockets as the transport.
+
+    clean_session : a boolean that determines the client type. If True,
+                    the broker will remove all information about this client
+                    when it disconnects. If False, the client is a persistent
+                    client and subscription information and queued messages
+                    will be retained when the client disconnects.
+                    Defaults to True.
+
+    proxy_args: a dictionary that will be given to the client.
+    """
+
+    if msg_count < 1:
+        raise ValueError('msg_count must be > 0')
+
+    # Set ourselves up to return a single message if msg_count == 1, or a list
+    # if > 1.
+    if msg_count == 1:
+        messages = None
+    else:
+        messages = []
+
+    userdata = {'retained':retained, 'msg_count':msg_count, 'messages':messages}
+
+    callback(_on_message_simple, topics, qos, userdata, hostname, port,
+             client_id, keepalive, will, auth, tls, protocol, transport,
+             clean_session, proxy_args)
+
+    return userdata['messages']

venv/lib/python3.11/site-packages/paho/mqtt/subscribeoptions.py

@@ -0,0 +1,110 @@
+"""
+*******************************************************************
+  Copyright (c) 2017, 2019 IBM Corp.
+
+  All rights reserved. This program and the accompanying materials
+  are made available under the terms of the Eclipse Public License v2.0
+  and Eclipse Distribution License v1.0 which accompany this distribution.
+
+  The Eclipse Public License is available at
+     http://www.eclipse.org/legal/epl-v10.html
+  and the Eclipse Distribution License is available at
+    http://www.eclipse.org/org/documents/edl-v10.php.
+
+  Contributors:
+     Ian Craggs - initial implementation and/or documentation
+*******************************************************************
+"""
+
+import sys
+
+
+class MQTTException(Exception):
+    pass
+
+
+class SubscribeOptions(object):
+    """The MQTT v5.0 subscribe options class.
+
+    The options are:
+        qos:                As in MQTT v3.1.1.
+        noLocal:            True or False. If set to True, the subscriber will not receive its own publications.
+        retainAsPublished:  True or False. If set to True, the retain flag on received publications will be as set
+                            by the publisher.
+        retainHandling:     RETAIN_SEND_ON_SUBSCRIBE, RETAIN_SEND_IF_NEW_SUB or RETAIN_DO_NOT_SEND
+                            Controls when the broker should send retained messages:
+                                - RETAIN_SEND_ON_SUBSCRIBE: on any successful subscribe request
+                                - RETAIN_SEND_IF_NEW_SUB: only if the subscribe request is new
+                                - RETAIN_DO_NOT_SEND: never send retained messages
+    """
+
+    # retain handling options
+    RETAIN_SEND_ON_SUBSCRIBE, RETAIN_SEND_IF_NEW_SUB, RETAIN_DO_NOT_SEND = range(
+        0, 3)
+
+    def __init__(self, qos=0, noLocal=False, retainAsPublished=False, retainHandling=RETAIN_SEND_ON_SUBSCRIBE):
+        """
+        qos:                0, 1 or 2.  0 is the default.
+        noLocal:            True or False. False is the default and corresponds to MQTT v3.1.1 behavior.
+        retainAsPublished:  True or False. False is the default and corresponds to MQTT v3.1.1 behavior.
+        retainHandling:     RETAIN_SEND_ON_SUBSCRIBE, RETAIN_SEND_IF_NEW_SUB or RETAIN_DO_NOT_SEND
+                            RETAIN_SEND_ON_SUBSCRIBE is the default and corresponds to MQTT v3.1.1 behavior.
+        """
+        object.__setattr__(self, "names",
+                           ["QoS", "noLocal", "retainAsPublished", "retainHandling"])
+        self.QoS = qos  # bits 0,1
+        self.noLocal = noLocal  # bit 2
+        self.retainAsPublished = retainAsPublished  # bit 3
+        self.retainHandling = retainHandling  # bits 4 and 5: 0, 1 or 2
+        assert self.QoS in [0, 1, 2]
+        assert self.retainHandling in [
+            0, 1, 2], "Retain handling should be 0, 1 or 2"
+
+    def __setattr__(self, name, value):
+        if name not in self.names:
+            raise MQTTException(
+                name + " Attribute name must be one of "+str(self.names))
+        object.__setattr__(self, name, value)
+
+    def pack(self):
+        assert self.QoS in [0, 1, 2]
+        assert self.retainHandling in [
+            0, 1, 2], "Retain handling should be 0, 1 or 2"
+        noLocal = 1 if self.noLocal else 0
+        retainAsPublished = 1 if self.retainAsPublished else 0
+        data = [(self.retainHandling << 4) | (retainAsPublished << 3) |
+                (noLocal << 2) | self.QoS]
+        if sys.version_info[0] >= 3:
+            buffer = bytes(data)
+        else:
+            buffer = bytearray(data)
+        return buffer
+
+    def unpack(self, buffer):
+        b0 = buffer[0]
+        self.retainHandling = ((b0 >> 4) & 0x03)
+        self.retainAsPublished = True if ((b0 >> 3) & 0x01) == 1 else False
+        self.noLocal = True if ((b0 >> 2) & 0x01) == 1 else False
+        self.QoS = (b0 & 0x03)
+        assert self.retainHandling in [
+            0, 1, 2], "Retain handling should be 0, 1 or 2, not %d" % self.retainHandling
+        assert self.QoS in [
+            0, 1, 2], "QoS should be 0, 1 or 2, not %d" % self.QoS
+        return 1
+
+    def __repr__(self):
+        return str(self)
+
+    def __str__(self):
+        return "{QoS="+str(self.QoS)+", noLocal="+str(self.noLocal) +\
+            ", retainAsPublished="+str(self.retainAsPublished) +\
+            ", retainHandling="+str(self.retainHandling)+"}"
+
+    def json(self):
+        data = {
+            "QoS": self.QoS,
+            "noLocal": self.noLocal,
+            "retainAsPublished": self.retainAsPublished,
+            "retainHandling": self.retainHandling,
+        }
+        return data