`blackbull.mqtt.messages`¶

`blackbull.mqtt.messages` ¶

Pure MQTT 5 packet codec, without I/O or broker state.

Decoded messages also unpack as (message, bytes_consumed) for buffer walking. Packet property and direction rules follow the MQTT 5 OASIS specification.

`ConnectFlags` ¶

Bases: IntFlag

Single-bit flags in the CONNECT flags byte (§3.1.2.3).

The Will QoS field is the two-bit subfield at WILL_QOS_SHIFT (mask WILL_QOS_MASK), not a flag here.

`IncompletePacket` ¶

Bases: Exception

The buffer does not yet hold a complete packet — read more bytes.

`MQTTAuth` `dataclass` ¶

Bases: MQTTMessage

AUTH — one exchange of an enhanced-authentication conversation (§3.15).

The method and any challenge or response data travel in properties; the reason code says whether authentication is complete or another round is expected. None with no properties encodes as an empty body, which the spec reads as Success (0).

`MQTTConnack` `dataclass` ¶

Bases: MQTTMessage

CONNACK — the broker's answer to CONNECT (§3.2).

session_present tells the client whether the broker resumed its stored session or started a fresh one; a non-zero reason_code means the connection was refused and the broker closes it.

`MQTTConnect` `dataclass` ¶

Bases: MQTTMessage

CONNECT — the client's opening packet (§3.1).

Carries the session identity (client_id, clean_start), the keep-alive interval in seconds, optional credentials, and the Will the broker publishes if the connection ends without a DISCONNECT.

Construction rejects two shapes the spec forbids: a client_id containing a null character (§1.5.4.2), and a password without a username (§3.1.2.9).

`MQTTDecodeError` ¶

Bases: ValueError

A buffer could not be decoded as a valid MQTT control packet.

`MQTTDisconnect` `dataclass` ¶

Bases: MQTTMessage

DISCONNECT — either side announcing the connection is ending (§3.14).

Sent by a client, it also suppresses the Will unless the reason code says otherwise. reason_code of None with no properties encodes as an empty body, which the spec reads as Normal disconnection (0).

`MQTTMessage` ¶

Base for all MQTT control-packet dataclasses.

Provides the dual decode contract: a decoded message unpacks into (message, bytes_consumed). The byte count is set by decode_packet via _set_consumed; messages built by hand report 0.

`MQTTPacketType` ¶

Bases: IntEnum

The 15 MQTT 5.0 control packet types (§2.1.1 Table 2-1).

`MQTTPingreq` `dataclass` ¶

Bases: MQTTMessage

PINGREQ — the client's keep-alive probe; two octets, no body (§3.12).

`MQTTPingresp` `dataclass` ¶

Bases: MQTTMessage

PINGRESP — the broker's answer to PINGREQ; two octets, no body (§3.13).

`MQTTPuback` `dataclass` ¶

Bases: _PacketIdAck

PUBACK — the QoS 1 acknowledgement that completes a delivery (§3.4).

`MQTTPubcomp` `dataclass` ¶

Bases: _PacketIdAck

PUBCOMP — the QoS 2 handshake is finished and the packet id is free to reuse (§3.7).

`MQTTPublish` `dataclass` ¶

Bases: MQTTMessage

PUBLISH — an application message on a topic (§3.3).

qos selects the delivery handshake that follows: none for 0, PUBACK for 1, PUBREC/PUBREL/PUBCOMP for 2. retain asks the broker to keep this message as the topic's last known value; dup marks a redelivery.

Construction enforces what the payload and properties must agree on: a QoS 1 or 2 packet needs a packet_id (§3.3.2-2), a topic_alias of 0 is prohibited (§3.3.2.3.4), and payload_format_indicator 1 requires the payload to decode as UTF-8 (§3.3.2.3.2).

`MQTTPubrec` `dataclass` ¶

Bases: _PacketIdAck

PUBREC — first leg of the QoS 2 handshake: the PUBLISH was received and a PUBREL is now expected for that packet id (§3.5).

`MQTTPubrel` `dataclass` ¶

Bases: _PacketIdAck

PUBREL — second leg of the QoS 2 handshake: release the packet id, to be answered with PUBCOMP (§3.6).

`MQTTReasonCode` ¶

Bases: int

An MQTT 5.0 reason code (§2.4) as received.

A thin int subclass so any byte value (0-255) is representable without raising — undefined codes report name == 'Unknown'. Known values name themselves through ReasonCode.

`MQTTSuback` `dataclass` ¶

Bases: MQTTMessage

SUBACK — one reason code per SUBSCRIBE filter, in the order they were requested; a code of 0-2 is the granted QoS and anything higher is a refusal of that filter alone (§3.9).

`MQTTSubscribe` `dataclass` ¶

Bases: MQTTMessage

Subscribe to (filter, max_qos) pairs with a required packet_id.

subscription_options carries per-entry no_local/retain_as_published/ retain_handling. Decoding fills it; None on hand-built packets uses defaults.

`MQTTUnsuback` `dataclass` ¶

Bases: MQTTMessage

UNSUBACK — one reason code per UNSUBSCRIBE filter, in the order they were listed (§3.11).

`MQTTUnsubscribe` `dataclass` ¶

Bases: MQTTMessage

Unsubscribe literal registered filters; packet_id is required.

`PropertyId` ¶

Bases: IntEnum

§2.2.2.2 Table 2-3 property identifiers.

`PropertyInfo` ¶

Bases: NamedTuple

Static description of one MQTT 5.0 property identifier (§2.2.2.2).

`ProtocolLevel` ¶

Bases: IntEnum

CONNECT Protocol Level (§3.1.2.2). This broker speaks V5_0.

`PublishFlagBits` ¶

Bases: IntFlag

Single-bit flags in the PUBLISH fixed header (§3.3.1).

QoS is the two-bit subfield at PUBLISH_QOS_SHIFT.

`PublishFlags` ¶

Bases: NamedTuple

Decoded PUBLISH fixed-header flags (§3.3.1).

`ReasonCode` ¶

Bases: IntEnum

§2.4 reason codes — the one definition of each value and name.

`SubscriptionOptions` ¶

Bases: IntFlag

Single-bit options in the SUBSCRIBE options byte (§3.8.3.1).

`decode_packet(data)` ¶

Decode the first MQTT control packet in data.

Returns the message; it also unpacks into (message, bytes_consumed). Raises IncompletePacket if the buffer is short, or MQTTDecodeError if the bytes are not a valid packet.

`decode_properties(data, offset=0)` ¶

§2.2.2 — Decode a properties block; return (props, consumed).

consumed counts the Property Length prefix plus the property bytes.

`decode_publish_flags(flags_byte)` ¶

Decode DUP/QoS/RETAIN (MQTT §3.3.1); reject QoS=3 as malformed.

`decode_variable_byte_integer(data)` ¶

§1.5.5 — Decode a Variable Byte Integer; return (value, consumed).

Trailing bytes beyond the integer are ignored (the caller tracks them).

`encode_packet(message)` ¶

Serialize an MQTT control packet to its wire representation.

`encode_properties(properties)` ¶

§2.2.2 — Encode a properties dict to Property Length + body.

`encode_variable_byte_integer(value)` ¶

§1.5.5 — Encode an int (0..268,435,455) as a Variable Byte Integer.

`extract_flags(first_byte)` ¶

§2.1.1 — Flags occupy bits 3-0 of the first fixed-header byte.

`extract_packet_type(first_byte)` ¶

§2.1.1 — Packet type is bits 7-4 of the first fixed-header byte.

Type 0 is Reserved/forbidden (§2.1.1 Table 2-1) and raises ValueError.

`get_property_info(identifier)` ¶

Return the PropertyInfo for a property identifier, or None.

`topic_matches_filter(topic, filter_str)` ¶

§4.7 — Return True if topic matches subscription filter_str.

Handles + (single level), # (multi level, terminal), the $ leading-character rule (§4.7.2), and $share/<group>/<filter> shared subscriptions (§4.8.2).

`validate_topic_filter(filter_str)` ¶

Validate MQTT §4.7.1/§4.8.2 wildcard and shared-subscription grammar.

Return True when valid, False on NUL; raise ValueError for other violations.

`validate_topic_name(topic)` ¶

§4.7.1 — A Topic Name (used in PUBLISH) is literal: non-empty, no wildcards (+/#) and no null character. Leading/trailing slashes are permitted (they denote zero-length levels).

blackbull.mqtt.messages¶