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.

MqttFixedHeader <|-- MqttPacketBody
MqttPacketBody <|-- MqttConnect
MqttPacketBody <|-- MqttConnack
MqttPacketBody <|-- MqttDisconnect
MqttPacketBody <|-- MqttPingreq
MqttPacketBody <|-- MqttPingresp

Connection Packets

MqttFixedHeader <|-- MqttPacketBody
MqttPacketBody <|-- MqttSubscribe
MqttPacketBody <|-- MqttSuback
MqttPacketBody <|-- MqttUnsubscribe
MqttPacketBody <|-- MqttUnsuback

Subscrube/Unsubscribe Packets

MqttFixedHeader <|-- MqttPacketBody
MqttPacketBody <|-- MqttPublish
MqttPacketBody <|-- MqttPuback
MqttPacketBody <|-- MqttPubrec
MqttPacketBody <|-- MqttPubrel
MqttPacketBody <|-- MqttPubcomp

Publish Packets

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
fail_not_authorized = 5
fail_server_unavailable = 3
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:
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 than MqttFixedHeader.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 a MqttFixedHeader. This method asserts that header.packet_type is MqttControlPacketType.disconnect.

Parameters:
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.

encode_body(f)[source]
Parameters:f (file) – File-like object with write method.
Returns:Number of bytes written to file.
Return type:int
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 of MqttFixedHeader.MAX_REMAINING_LEN (=268435455 bytes).

Parameters:
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()[source]
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 than MqttFixedHeader.MAX_REMAINING_LEN (=268435455 bytes) in order to cause this error.

Parameters:
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.
classmethod decode_body(header, buf)[source]
encode(f)[source]
Parameters:f (file) – file-like object
Returns:Number of bytes written.
Return type:int
encode_body(f)[source]
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:
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.

encode_body(f)[source]
Parameters:f (file) – File-like object with write method.
Returns:Number of bytes written to file.
Return type:int
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:
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.

encode_body(f)[source]
Parameters:f (file) – File-like object with write method.
Returns:Number of bytes written to file.
Return type:int
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:
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.

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:
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.

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 than MqttFixedHeader.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:
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
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:
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.

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:
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.

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 than MqttFixedHeader.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:
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 than MqttFixedHeader.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:
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:
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.

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 than MqttFixedHeader.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:
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

boolTrue 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
exception mqtt_codec.io.DecodeError[source]

Bases: exceptions.Exception

exception mqtt_codec.io.EncodeError[source]

Bases: exceptions.Exception

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:
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. If limit 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.

read(max_bytes=1)[source]

Read at most max_bytes from internal buffer.

Parameters:max_bytes (int) – Maximum number of bytes to read.
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
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:
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

mqtt_codec.io.encode_varint(v, f)[source]

Encode integer v to file f.

Parameters:
  • v (int) – Integer v >= 0.
  • f (file) – Object containing a write method.
Returns:

Number of bytes written.

Return type:

int