API Reference¶
mqtt_codec.packet Package¶
A collection of classes used to represent MQTT control packets as described in the specification. The classes are, in general, immutable; once a class has been instantiated its properties cannot be changed.
-
class
mqtt_codec.packet.
ConnackResult
[source]¶ Bases:
enum.IntEnum
ConnackResult codes as enumerated in Table 3.1 (line 709) of the MQTT 3.1.1 specification.
-
accepted
= 0¶
-
fail_bad_client_id
= 2¶
-
fail_bad_protocol_version
= 1¶
-
fail_bad_username_or_password
= 4¶
-
-
class
mqtt_codec.packet.
MqttConnack
(session_present, return_code)[source]¶ Bases:
mqtt_codec.packet.MqttPacketBody
An immutable representation of an MQTT Connack packet as described in MQTT 3.2 (line 655).
Parameters: - session_present (bool) – Session present.
- return_code (ConnackResult) –
-
classmethod
decode_body
(header, f)[source]¶ Parameters: - header (MqttFixedHeader) –
- f (file) – Object with a read method.
Raises: DecodeError
– When bytes have values incompatible with a MqttConnack packet.UnderflowDecodeError
– When not enough bytes are available to decode a complete packet.
Returns: - int – Number of bytes consumed from
f
. - MqttConnack – Object extracted from
f
.
-
encode_body
(f)[source]¶ Parameters: f (file) – File-like object with write method. Returns: Number of bytes written to file. Return type: int
-
return_code
¶ ConnackResult – Result of the connect as described in MQTT 3.2.2.3 line 701.
-
session_present
¶ bool – Session present flag as described in MQTT 3.2.2.2 line 676.
-
class
mqtt_codec.packet.
MqttConnect
(client_id, clean_session, keep_alive, username=None, password=None, will=None)[source]¶ Bases:
mqtt_codec.packet.MqttPacketBody
An immutable representation of an MQTT connect object as in MQTT 3.1 (line 364).
The value of str(self) will have the username and password obscured so that it can be placed in logfiles without compromising the connection username and password. The value or repr(self) does not obscure the username and password.
Raises: mqtt_codec.io.TooBigEncodeError
– The parameters are impossible large to create an MQTT packet for. It encoded length must be greater thanMqttFixedHeader.MAX_REMAINING_LEN
(=268435455 bytes) in order to cause this error.Parameters: - client_id (str) –
- clean_session (bool) –
- keep_alive (int) – 0 <= keep_alive <= 2**16-1
- username (str or None) –
- password (str or None) –
- will (MqttWill or None) –
-
CONNECT_HEADER
= '\x00\x04MQTT'¶
-
PROTOCOL_LEVEL
= '\x04'¶
-
clean_session
¶ bool – MQTT password.
-
client_id
¶ str – Client id.
-
classmethod
decode_body
(header, f)[source]¶ Parameters: - header (MqttFixedHeader) –
- f (file) – File-like object with a read method.
Returns: - int – Number of bytes consumed from
f
. - MqttConnect – Object extracted from
f
.
-
encode_body
(f)[source]¶ Parameters: f (file) – File-like object with a write method. Returns: Number of bytes written to f
.Return type: int
-
keep_alive
¶ int – Keep alive period as described in MQTT 3.1.1 specification 3.1.2.10. When zero keep-alive is disabled. If positive then after self.keep_alive seconds of inactivity the client will send a ping to the server.
-
password
¶ str or None – MQTT password.
-
username
¶ str or None – MQTT username.
-
will
¶ MqttWill or None – A message that will be published on behalf of the client by the server in case of an unexpected disconnect. If None then the server does not publish any message on behalf of the client.
-
class
mqtt_codec.packet.
MqttControlPacketType
[source]¶ Bases:
enum.IntEnum
An enumeration of MQTT control packet types as described in the MQTT 3.1.1 specification in Table 2.1 (line 239).
-
connack
= 2¶
-
connect
= 1¶
-
disconnect
= 14¶
-
pingreq
= 12¶
-
pingresp
= 13¶
-
puback
= 4¶
-
pubcomp
= 7¶
-
publish
= 3¶
-
pubrec
= 5¶
-
pubrel
= 6¶
-
suback
= 9¶
-
subscribe
= 8¶
-
unsuback
= 11¶
-
unsubscribe
= 10¶
-
-
class
mqtt_codec.packet.
MqttDisconnect
[source]¶ Bases:
mqtt_codec.packet.MqttPacketBody
An immutable representation of an MQTT Disconnect packet as described in MQTT 3.14 (line 1138).
-
classmethod
decode_body
(header, f)[source]¶ Generates a
MqttDisconnect
packet given aMqttFixedHeader
. This method asserts that header.packet_type isMqttControlPacketType.disconnect
.Parameters: - header (MqttFixedHeader) –
- f (file) – Object with a read method.
Raises: DecodeError
– When there are extra bytes at the end of the packet.Returns: - int – Number of bytes consumed from
f
. - MqttDisconnect – Object extracted from
f
.
-
classmethod
-
class
mqtt_codec.packet.
MqttFixedHeader
(packet_type, flags, remaining_len)[source]¶ Bases:
object
An immutable class that represents an MQTT fixed header as described in MQTT Version 3.1.1 section 2.2 (line 233).
The serialized byte format is summarized as follows:
Bit 7 6 5 4 3 2 1 0 byte 1 control type flags byte 2 remaining length Raises: mqtt_codec.io.TooBigEncodeError
– The remaining_len exceeds the maximum ofMqttFixedHeader.MAX_REMAINING_LEN
(=268435455 bytes).Parameters: - packet_type (MqttControlPacketType) –
- flags (int) – An assert statement verifies that are_flags_valid(packet_type, flags) is True.
- remaining_len (int) – Asserted to be 0 <= remaining_len <=
MqttFixedHeader.MAX_REMAINING_LEN
-
MAX_REMAINING_LEN
= 268435455¶
-
static
decode
(f)[source]¶ Extract a MqttFixedHeader from
f
.Parameters: f (file) – Object with read method.
Raises: DecodeError
– When bytes decoded have values incompatible with a MqttFixedHeader object.UnderflowDecodeError
– When end-of-stream is encountered before the end of the fixed header.
Returns: - int – Number of bytes consumed from
f
. - MqttFixedHeader – Header object extracted from
f
.
-
encode
(f)[source]¶ Parameters: f (file) – file-like object Returns: Number of bytes written. Return type: int
-
flags
¶ int – A value 0 <= flags <= 15 representing the 4-bit MQTT header flags field. The property is guaranteed to comply with [MQTT-2.2.2-1] requirements based on
self.packet_type
.
-
packet_type
¶ MqttControlPacketType – MQTT packet type of
self
.
-
remaining_len
¶ int – Number bytes in packet that follow the packet header.
-
size
¶ int – Number bytes required to encode the packet
self
.
-
class
mqtt_codec.packet.
MqttPacketBody
(packet_type, flags)[source]¶ Bases:
mqtt_codec.packet.MqttFixedHeader
Raises: mqtt_codec.io.TooBigEncodeError
– The message body is impossibly large to create an MQTT packet for. It must be greater thanMqttFixedHeader.MAX_REMAINING_LEN
(=268435455 bytes) in order to cause this error.Parameters: - packet_type (MqttControlPacketType) –
- flags (int) – Flags 0 <= flags <= 2**8-1.
-
classmethod
decode
(f)[source]¶ Parameters: f (file) – Object with a read method. Returns: - int – Number of bytes consumed from
f
. - MqttFixedHeader – Header object extracted from
f
.
- int – Number of bytes consumed from
-
class
mqtt_codec.packet.
MqttPingreq
[source]¶ Bases:
mqtt_codec.packet.MqttPacketBody
An immutable representation of an MQTT Pingreq packet as described in MQTT 3.12 (line 1109).
-
classmethod
decode_body
(header, f)[source]¶ Generates a MqttPingreq packet given a MqttFixedHeader. This method asserts that header.packet_type is pingreq.
Parameters: - header (MqttFixedHeader) –
- f (file) – Object with a read method.
Raises: DecodeError
– When there are extra bytes at the end of the packet.Returns: - int – Number of bytes consumed from
f
. - MqttPingreq – Object extracted from
f
.
-
classmethod
-
class
mqtt_codec.packet.
MqttPingresp
[source]¶ Bases:
mqtt_codec.packet.MqttPacketBody
An immutable representation of an MQTT Pingresp packet as described in MQTT 3.13 (line 1126).
-
classmethod
decode_body
(header, f)[source]¶ Generates a MqttPingresp packet given a MqttFixedHeader. This method asserts that header.packet_type is pingresp.
Parameters: - header (MqttFixedHeader) –
- f (file) – Object with a read method.
Raises: DecodeError
– When there are extra bytes at the end of the packet.Returns: - int – Number of bytes consumed from
f
. - MqttPingresp – Object extracted from
f
.
-
classmethod
-
class
mqtt_codec.packet.
MqttPuback
(packet_id)[source]¶ Bases:
mqtt_codec.packet.MqttPacketBody
An immutable representation of an MQTT Puback packet as described in MQTT 3.4 (line 838).
Parameters: packet_id (int) – 0 <= packet_id <= 2**16 -1 -
classmethod
decode_body
(header, f)[source]¶ Generates a MqttPuback packet given a MqttFixedHeader. This method asserts that header.packet_type is puback.
Parameters: - header (MqttFixedHeader) –
- f (file) – Object with a read method.
Raises: DecodeError
– When there are extra bytes at the end of the packet.Returns: - int – Number of bytes consumed from
f
. - MqttPuback – Object extracted from
f
.
-
encode_body
(f)[source]¶ Parameters: f (file) – File-like object with write method. Returns: Number of bytes written to file. Return type: int
-
packet_id
¶ int – packet id such that 0 <= packet_id <= 2**16-1.
-
classmethod
-
class
mqtt_codec.packet.
MqttPubcomp
(packet_id)[source]¶ Bases:
mqtt_codec.packet.MqttPacketBody
An immutable representation of MQTT Pubrec packet as described in MQTT 3.7 (line 890).
Parameters: packet_id (int) – 0 <= packet_id <= 2**16 -1 -
classmethod
decode_body
(header, f)[source]¶ Generates a MqttPubcomp packet given a MqttFixedHeader. This method asserts that header.packet_type is pubcomp.
Parameters: - header (MqttFixedHeader) –
- f (file) – Object with a read method.
Raises: DecodeError
– When there are extra bytes at the end of the packet.Returns: - int – Number of bytes consumed from
f
. - MqttPubcomp – Object extracted from
f
.
-
encode_body
(f)[source]¶ Parameters: f (file) – File-like object with write method. Returns: Number of bytes written to file. Return type: int
-
packet_id
¶ int – packet id such that 0 <= packet_id <= 2**16-1.
-
classmethod
-
class
mqtt_codec.packet.
MqttPublish
(packet_id, topic, payload, dupe, qos, retain)[source]¶ Bases:
mqtt_codec.packet.MqttPacketBody
An immutable representation of an MQTT Publish packet as described in MQTT 3.3 (line 715).
Raises: mqtt_codec.io.TooBigEncodeError
– The encoded length of parameters is too long to create an MQTT packet for. The encoded length must be greater thanMqttFixedHeader.MAX_REMAINING_LEN
(=268435455 bytes) in order to cause this error.Shorten the payload or topic to allow the message to fit.
Parameters: - packet_id (int) –
Integer such that 0 <= packet_id <= (2**16)-1.
When this object is constructed by the decoder and the QoS is 0 then the decoder will assign this property a value of zero. This property is not used by the encoder. These behaviours are in accordance with the MQTT 3.1.1 specification at 3.3.1-2.
This property is fully encodec/decoded for QoS=1 and QoS=2, again, according to the MQTT specification.
- topic (str) –
- payload (bytes) –
- dupe (bool) –
Represents the DUP flag as described by the MQTT specification:
If the DUP flag is set to 0, it indicates that this is the first occasion that the Client or Server has attempted to send this MQTT PUBLISH Packet. If the DUP flag is set to 1, it indicates that this might be re-delivery of an earlier attempt to send the Packet.The DUP flag MUST be set to 1 by the Client or Server when it attempts to re-deliver a PUBLISH Packet [MQTT-3.3.1-1]. The DUP flag MUST be set to 0 for all QoS 0 messages [MQTT-3.3.1-2].
The value of the DUP flag from an incoming PUBLISH packet is not propagated when the PUBLISH Packet is sent to subscribers by the Server. The DUP flag in the outgoing PUBLISH packet is set independently to the incoming PUBLISH packet, its value MUST be determined solely by whether the outgoing PUBLISH packet is a retransmission [MQTT-3.3.1-3].
- qos (int) – 0 <= qos <= 2
- retain (bool) –
-
packet_id
¶ int – Integer such that 0 <= packet_id <= (2**16)-1.
When this object is constructed by the decoder and the QoS is 0 then the decoder will assign this property a value of zero. This property is not used by the encoder. These behaviours are in accordance with the MQTT 3.1.1 specification at 3.3.1-2.
This property is fully encodec/decoded for QoS=1 and QoS=2, again, according to the MQTT specification.
-
topic
¶ str
-
payload
¶ bytes
-
dupe
¶ bool – Represents the DUP flag as described by the MQTT specification:
If the DUP flag is set to 0, it indicates that this is the first occasion that the Client or Server has attempted to send this MQTT PUBLISH Packet. If the DUP flag is set to 1, it indicates that this might be re-delivery of an earlier attempt to send the Packet.
The DUP flag MUST be set to 1 by the Client or Server when it attempts to re-deliver a PUBLISH Packet [MQTT-3.3.1-1]. The DUP flag MUST be set to 0 for all QoS 0 messages [MQTT-3.3.1-2].
The value of the DUP flag from an incoming PUBLISH packet is not propagated when the PUBLISH Packet is sent to subscribers by the Server. The DUP flag in the outgoing PUBLISH packet is set independently to the incoming PUBLISH packet, its value MUST be determined solely by whether the outgoing PUBLISH packet is a retransmission [MQTT-3.3.1-3].
-
qos
¶ int – Integer such that 0 <= qos <= 2.
-
retain
¶ bool
-
classmethod
decode_body
(header, f)[source]¶ Generates a MqttPublish packet given a MqttFixedHeader. This method asserts that header.packet_type is publish.
Parameters: - header (MqttFixedHeader) –
- f (file) – Object with a read method.
Raises: DecodeError
– When there are extra bytes at the end of the packet.Returns: - int – Number of bytes consumed from
f
. - MqttPublish – Object extracted from
f
.
-
dupe
-
encode_body
(f)[source]¶ Parameters: f (file) – File-like object with write method. Returns: Number of bytes written to file. Return type: int
-
packet_id
int – packet id such that 0 <= packet_id <= 2**16-1.
MQTT does not use this property for QoS=0 packets. The deserializers will set this field to zero for QoS=0 packets. When serializing QoS=0 packets this property’s value is not placed in the output.
For non-QoS=0 packets (ie. QoS=1, QoS=2) this property is serialized and deserialized as expected.
-
payload
-
qos
-
retain
-
topic
- packet_id (int) –
-
class
mqtt_codec.packet.
MqttPubrec
(packet_id)[source]¶ Bases:
mqtt_codec.packet.MqttPacketBody
An immutable representation of MQTT Pubrec packet as described in MQTT 3.5 (line 853).
Parameters: packet_id (int) – 0 <= packet_id <= 2**16 -1 -
classmethod
decode_body
(header, f)[source]¶ Generates a MqttPubrec packet given a MqttFixedHeader. This method asserts that header.packet_type is pubrec.
Parameters: - header (MqttFixedHeader) –
- f (file) – Object with a read method.
Raises: DecodeError
– When there are extra bytes at the end of the packet.Returns: - int – Number of bytes consumed from
f
. - MqttPubrec – Object extracted from
f
.
-
encode_body
(f)[source]¶ Parameters: f (file) – File-like object with write method. Returns: Number of bytes written to file. Return type: int
-
packet_id
¶ int – packet id such that 0 <= packet_id <= 2**16-1.
-
classmethod
-
class
mqtt_codec.packet.
MqttPubrel
(packet_id)[source]¶ Bases:
mqtt_codec.packet.MqttPacketBody
An immutable representation of MQTT Pubrel packet as described in MQTT 3.6 (line 869).
Parameters: packet_id (int) – 0 <= packet_id <= 2**16 -1 -
classmethod
decode_body
(header, f)[source]¶ Generates a MqttPubrel packet given a MqttFixedHeader. This method asserts that header.packet_type is pubrel.
Parameters: - header (MqttFixedHeader) –
- f (file) – Object with a read method.
Raises: DecodeError
– When there are extra bytes at the end of the packet.Returns: - int – Number of bytes consumed from
f
. - MqttPubrel – Object extracted from
f
.
-
encode_body
(f)[source]¶ Parameters: f (file) – File-like object with write method. Returns: Number of bytes written to file. Return type: int
-
packet_id
¶ int – packet id such that 0 <= packet_id <= 2**16-1.
-
classmethod
-
class
mqtt_codec.packet.
MqttSuback
(packet_id, results)[source]¶ Bases:
mqtt_codec.packet.MqttPacketBody
An immutable representation of an MQTT Subscribe packet as described in MQTT 3.9 (line 1007).
Raises: mqtt_codec.io.TooBigEncodeError
– There are too many results to create an MQTT packet for. The encoded lenght must be greater thanMqttFixedHeader.MAX_REMAINING_LEN
(=268435455 bytes) in order to cause this error.Parameters: - packet_id (int) – 0 <= packet_id <= 2**16-1
- results (iterable of SubscribeResult) –
-
classmethod
decode_body
(header, f)[source]¶ Generates a MqttSuback packet given a MqttFixedHeader. This method asserts that header.packet_type is suback.
Parameters: - header (MqttFixedHeader) –
- f (file) – Object with a read method.
Raises: DecodeError
– When there are extra bytes at the end of the packet.Returns: - int – Number of bytes consumed from
f
. - MqttSuback – Object extracted from
f
.
-
encode_body
(f)[source]¶ Parameters: f (file) – File-like object with write method. Returns: Number of bytes written to file. Return type: int
-
packet_id
¶ int – packet_id such that 0 <= packet_id <= 2**16-1.
-
results
¶ tuple of SubscribeResult – Tuple of return codes specifying the maximum QoS level that was granted in each or fail if the subscription failed.
-
class
mqtt_codec.packet.
MqttSubscribe
(packet_id, topics)[source]¶ Bases:
mqtt_codec.packet.MqttPacketBody
An immutable representation of an MQTT Subscribe packet as described in MQTT 3.8 (line 908).
Raises: mqtt_codec.io.TooBigEncodeError
– The parameters are impossibly large to create an MQTT packet for. The encoded length must be greater thanMqttFixedHeader.MAX_REMAINING_LEN
(=268435455 bytes) in order to cause this error.Parameters: - packet_id (int) – 0 <= packet_id <= 2**16-1
- topics (iterable of MqttTopic) –
-
classmethod
decode_body
(header, f)[source]¶ Generates a MqttSubscribe packet given a MqttFixedHeader. This method asserts that header.packet_type is subscribe.
Parameters: - header (MqttFixedHeader) –
- f (file) – Object with a read method.
Raises: DecodeError
– When there are extra bytes at the end of the packet.Returns: - int – Number of bytes consumed from
f
. - MqttSubscribe – Object extracted from
f
.
-
encode_body
(f)[source]¶ Parameters: f (file) – File-like object with write method. Returns: Number of bytes written to file. Return type: int
-
packet_id
¶ int – packet id such that 0 <= packet_id <= 2**16-1.
-
topics
¶ tuple of MqttTopic – Topics requested in subscribe.
-
class
mqtt_codec.packet.
MqttTopic
(name, max_qos)[source]¶ Bases:
object
Parameters: - name (str) –
- max_qos (int) – Maximum qos to be granted by server to client.
-
max_qos
¶ int – Maximum qos to be granted by server to client.
-
name
¶ str – Topic name.
-
class
mqtt_codec.packet.
MqttUnsuback
(packet_id)[source]¶ Bases:
mqtt_codec.packet.MqttPacketBody
An immutable representation of an MQTT Unsuback packet as described in MQTT 3.11 (line 1093).
Parameters: packet_id (int) – 0 <= packet_id <= 2**16-1 -
classmethod
decode_body
(header, f)[source]¶ Generates a MqttUnsuback packet given a MqttFixedHeader. This method asserts that header.packet_type is unsuback.
Parameters: - header (MqttFixedHeader) –
- f (file) – Object with a read method.
Raises: DecodeError
– When there are extra bytes at the end of the packet.Returns: - int – Number of bytes consumed from
f
. - MqttUnsuback – Object extracted from
f
.
-
encode_body
(f)[source]¶ Parameters: f (file) – File-like object with write method. Returns: Number of bytes written to file. Return type: int
-
packet_id
¶ int – packet id such that 0 <= packet_id <= 2**16-1.
-
classmethod
-
class
mqtt_codec.packet.
MqttUnsubscribe
(packet_id, topics)[source]¶ Bases:
mqtt_codec.packet.MqttPacketBody
An immutable representation of MQTT Unsubscribe packet as described in MQTT 3.10 (line 1044).
Raises: mqtt_codec.io.TooBigEncodeError
– The encoded length of topic parameters is too long to create an MQTT packet for. The encoded lenghth must be greater thanMqttFixedHeader.MAX_REMAINING_LEN
(=268435455 bytes) in order to cause this error.Shorten the number of topics or the length of the topic strings.
Parameters: - packet_id (int) – 0 <= packet_id <= 2**16 -1
- topics (iterable of str) –
-
classmethod
decode_body
(header, f)[source]¶ Generates a MqttUnsubscribe packet given a MqttFixedHeader. This method asserts that header.packet_type is unsubscribe.
Parameters: - header (MqttFixedHeader) –
- f (file) – Object with a read method.
Raises: DecodeError
– When there are extra bytes at the end of the packet.Returns: - int – Number of bytes consumed from
f
. - MqttUnsubscribe – Object extracted from
f
.
-
encode_body
(f)[source]¶ Parameters: f (file) – File-like object with write method. Returns: Number of bytes written to file. Return type: int
-
packet_id
¶ int – packet id such that 0 <= packet_id <= 2**16-1.
-
topics
¶ tuple of str – Topics to be unsubscribed.
-
class
mqtt_codec.packet.
MqttWill
(qos, topic, message, retain)[source]¶ Bases:
object
An immutable class representing an MQTT Will message as described beginning in [MQTT-3.1.2-8, line 471].
Parameters: - qos (int) – 0 <= qos <= 2
- topic (str) –
- message (bytes) –
- retain (bool) –
-
message
¶ bytes – Will message.
-
qos
¶ int – A number such that 0 <=
self.qos
<= 2.
-
retain
¶ bool – Will retain flag as described in MQTT spec line 504 section 3.1.2.7. In general, with the retain flag set the will message will be saved and published to clients as they connect to the server.
-
topic
¶ str – Topic name.
-
class
mqtt_codec.packet.
SubscribeResult
[source]¶ Bases:
enum.IntEnum
-
fail
= 128¶
-
qos0
= 0¶
-
qos1
= 1¶
-
qos2
= 2¶
-
-
mqtt_codec.packet.
are_flags_valid
(packet_type, flags)[source]¶ True when flags comply with [MQTT-2.2.2-1] requirements based on packet_type; False otherwise.
Parameters: - packet_type (MqttControlPacketType) –
- flags (int) – Integer representation of 4-bit MQTT header flags field. Values outside of the range [0, 15] will certainly cause the function to return False.
Returns: Return type: bool
mqtt_codec.io Package¶
A collection of helper functions and classes used to read MQTT control packets.
-
class
mqtt_codec.io.
BytesReader
(buf)[source]¶ Bases:
object
Creates a file-like object that reads from a buffer.
Parameters: buf (bytes or bytearray) – Object to read from. -
close
()[source]¶ Read operations conducted after this method is called will raise ValueError. This makes the object behave like other read objects even though no resources are freed.
-
closed
¶ bool –
True
if self.close() has been called;False
otherwise.
-
read
(max_bytes=1)[source]¶ Read at most max_bytes from internal buffer.
Parameters: max_bytes (int) – Maximum number of bytes to read. Raises: ValueError
– If read is called after close has been called.Returns: Bytes extracted from internal buffer. Length may be less than max_bytes. On end-of file returns a bytes object with zero-length. Return type: bytes
-
-
class
mqtt_codec.io.
FileDecoder
(f)[source]¶ Bases:
object
Creates an object that extracts values from the file-like object f.
Parameters: f (file) – Object with read method. -
num_bytes_consumed
¶ int – number of bytes consumed from underlying stream.
-
read
(num_bytes)[source]¶ Read num_bytes and return them.
Parameters: num_bytes (int) – Number of bytes to extract from the underlying stream. Raises: UnderflowDecodeError
– Raised when a read failed to extract enough bytes from the underlying stream to extract the bytes.Returns: A bytes object extracted from underlying stream. Return type: bytes
-
unpack
(struct)[source]¶ Read as many bytes as are required to extract struct then unpack and return a tuple of the values.
Raises: UnderflowDecodeError
– Raised when a read failed to extract enough bytes from the underlying stream to extract the bytes.Parameters: struct (struct.Struct) – Returns: Tuple of extracted values. Return type: tuple
-
unpack_bytes
()[source]¶ Unpack a utf-8 string encoded as described in MQTT Version 3.1.1 section 1.5.3 line 177. This is a 16-bit unsigned length followed by a utf-8 encoded string.
Returns: - int – Number of bytes consumed
- bytes – A bytes object extracted from the underlying stream.
-
unpack_utf8
()[source]¶ Decode a utf-8 string encoded as described in MQTT Version 3.1.1 section 1.5.3 line 177. This is a 16-bit unsigned length followed by a utf-8 encoded string.
Raises: UnderflowDecodeError
– Raised when a read failed to extract enough bytes from the underlying stream to decode the string.DecodeError
– When any code point in the utf-8 string is invalid.
Returns: - int – Number of bytes consumed.
- str – A string utf-8 decoded from the underlying stream.
-
unpack_varint
(max_bytes)[source]¶ Decode variable integer using algorithm similar to that described in MQTT Version 3.1.1 line 297.
Parameters: max_bytes (int or None) – If a varint cannot be constructed using max_bytes or fewer from f then raises a DecodeError. If None then there is no maximum number of bytes.
Raises: DecodeError
– When length is greater than max_bytes.UnderflowDecodeError
– When file ends before enough bytes can be read to construct the varint.
Returns: - int – Number of bytes consumed.
- int – Value extracted from f.
-
-
class
mqtt_codec.io.
LimitReader
(f, limit=None)[source]¶ Bases:
object
Reads up to
limit
bytes from the underlying file. Iflimit
is none then reads to the end of the file.Parameters: - f (file) – File-like object with read method.
- limit (int optional) – Maximum number of bytes to read from the underlying file or
None
the reader should continue until the end of the file.
-
limit
¶ int or None – maximum number of bytes to read from underlying stream.
-
exception
mqtt_codec.io.
OverflowEncodeError
[source]¶ Bases:
mqtt_codec.io.EncodeError
-
exception
mqtt_codec.io.
OversizePacketEncodeError
[source]¶ Bases:
mqtt_codec.io.EncodeError
Raised when the parameters used to create the MQTT packet would result in an impossibly large packet.
-
exception
mqtt_codec.io.
UnderflowDecodeError
[source]¶ Bases:
mqtt_codec.io.DecodeError
-
exception
mqtt_codec.io.
Utf8DecodeError
(e)[source]¶ Bases:
mqtt_codec.io.DecodeError
-
mqtt_codec.io.
decode_bytes
(f)[source]¶ Decode a buffer length from a 2-byte unsigned int then read the subsequent bytes.
Parameters: f (file) – File-like object with read method. Raises: UnderflowDecodeError
– When the end of stream is encountered before the end of the encoded bytes.Returns: - int – Number of bytes read from f.
- bytes – Value bytes decoded from f.
-
mqtt_codec.io.
decode_utf8
(f)[source]¶ Decode a utf-8 string encoded as described in MQTT Version 3.1.1 section 1.5.3 line 177. This is a 16-bit unsigned length followed by a utf-8 encoded string.
Parameters: f (file) – File-like object with read method.
Raises: UnderflowDecodeError
– Raised when a read failed to extract enough bytes from the underlying stream to decode the string.Utf8DecodeError
– When any code point in the utf-8 string is invalid.
Returns: - int – Number of bytes consumed.
- str – A string utf-8 decoded from
f
.
-
mqtt_codec.io.
decode_varint
(f, max_bytes=4)[source]¶ Decode variable integer using algorithm similar to that described in MQTT Version 3.1.1 line 297.
Parameters: - f (file) – Object with a read method.
- max_bytes (int or None) – If a varint cannot be constructed using max_bytes or fewer from f then raises a DecodeError. If None then there is no maximum number of bytes.
Raises: DecodeError
– When length is greater than max_bytes.UnderflowDecodeError
– When file ends before enough bytes can be read to construct the varint.
Returns: - int – Number of bytes consumed.
- int – Value extracted from f.
-
mqtt_codec.io.
encode_bytes
(src_buf, dst_file)[source]¶ Encode a buffer length followed by the bytes of the buffer itself.
Parameters: - src_buf (bytes) – Source bytes to be encoded. Function asserts that 0 <= len(src_buf) <= 2**16-1.
- dst_file (file) – File-like object with write method.
Returns: Number of bytes written to dst_file.
Return type: int
-
mqtt_codec.io.
encode_utf8
(s, f)[source]¶ UTF-8 encodes string s to file-like object f according to the MQTT Version 3.1.1 specification in section 1.5.3.
The maximum length for the encoded string is 2**16-1 (65535) bytes. An assertion error will result if the encoded string is longer.
Parameters: - s (str) – String to be encoded.
- f (file) – File-like object.
Returns: Number of bytes written to f.
Return type: int