MQTT 5 for Python (paho-mqtt 2.x) — feature parity

The parity document of weida-mqtt-py, the Python binding of the weida-mqtt MQTT 5.0 client, built on weida-py-core. Its reference implementation is paho-mqtt, because that is what a Python program that speaks MQTT uses today; the protocol-level parity against MQTT 5.0 itself is mqtt.md and is not repeated here — its §2 (the fifteen packet types), §3 (the 27 properties), §4 (QoS), §5 (filters and subscription options), §6 (retained messages and the Will) and §7 (the reason-code groups) are the rows a protocol reader wants. This document answers one question per row: what does a Python caller who knows paho-mqtt get, and what does that caller not get.

0. Why there is no server column

The same reason mqtt.md §0 gives, one layer up: MQTT's topology is strictly asymmetric and this is a client. Retained storage, the session store, subscription routing, shared-subscription selection and the Will's delay timer are all the server's, the server is Phase D (0014 §2), and there is no weida_mqtt.Broker — crates/mqtt/weida-mqtt-py/src/lib.rs:36-43 says so in the module's own documentation. paho-mqtt is a client too, so the two columns below line up: neither has a server half, and a row about server behaviour belongs in mqtt.md §6 and §10.

1. What a row means

Three verdicts and no others:

• present — implemented, with the module or test that proves it;
• refused — the call exists and fails at configuration time with a reason the code gives;
• absent — not implemented, with what is missing named.

"Partial" is not a verdict (0013 §4.7 clause 6). Where this binding's shape differs from paho's the row says so and §9 states why.

What this side was read from. Every verdict below names a module under crates/mqtt/weida-mqtt-py/src/ or a test function under crates/mqtt/weida-mqtt-py/tests/, and was read there. CPython 3.9 and up through PyO3 0.29 with abi3-py39 (Cargo.toml:113 at the workspace root, crates/mqtt/weida-mqtt-py/pyproject.toml:8), the library entered with default-features = false plus blocking (crates/mqtt/weida-mqtt-py/Cargo.toml:35-40), Linux x86-64.

Which broker the tests run against. One: rumqttd 0.20.0 on 127.0.0.1:21884, the listener of crates/mqtt/weida-mqtt/tests/interop/rumqttd.toml. tests/conftest.py:15-41 probes that port once per session and skips with the cargo install rumqttd --version 0.20.0 command where nothing answers — the Python half of what #[ignore] does for the Rust suites. The port is deliberately not 1883, so a developer's own broker cannot be measured by accident. The second broker of mqtt.md §1, rmqtt 0.23.1, is not used by the Python suite: no test in crates/mqtt/weida-mqtt-py/tests/ names it.

Which paho version. None. paho does not occur anywhere under crates/, nothing in pyproject.toml, develop.sh (which installs maturin, pytest and pytest-asyncio and nothing else), tests/conftest.py or tests/test_interop.py pins or imports it, and no test in this repository has ever run against it. The paho column below is therefore the documented public API of paho-mqtt 2.x, not a measurement, and it is the one column of this document that cannot be checked out of the repository — see §8 and the open question in §9.7. Where a claim about paho's behaviour rather than its API names appears, it is one the research sheet already carries with a citation: ../research/mqtt5.md §13 and its references [37] and [38].

2. The client surface

paho is one Client object with a callback for every event. This binding is a context, a client and a delivery stream — the three handles §9.2 measures the two surfaces by — plus a Session the caller holds and six value classes. 13 #[pyclass]es in all: ten in weida_mqtt and three in weida_mqtt.sync.

3. Transports

4. Mechanisms and authentication

5. Options

Everything a CONNECT declares is one frozen weida_mqtt.ConnectOptions, built with 19 keyword arguments (options.rs:152-173), and every refusal happens at construction rather than on the wire: ConnectOptions.new ends in inner.validate() and turns the library's message into a ValueError that names the option, "because a ValueError at the line that built the options names the option, and a Protocol Error from the broker names a byte" (options.rs:1-8, 234-240).

6. Observability

7. Helpers

8. Interop evidence

45 pytest functions in crates/mqtt/weida-mqtt-py/tests/: 12 in test_interop.py, 12 in test_sync.py and 21 in test_values.py. 23 of them ask for the broker fixture and skip with its install command where the port does not answer (conftest.py:36-41); the other 22 — the 21 in test_values.py and test_sync.py::test_no_event_loop_exists_in_this_process, which asserts the condition every other test in that file runs under — need nothing.

Against rumqttd 0.20.0, this client on both sides of the broker (test_interop.py):

• the QoS 2 publish awaited to its PUBCOMP, with QoS 0 and QoS 1 beside it so the three completions are distinguishable rather than asserted one at a time (test_a_qos_2_publish_is_awaited_to_its_pubcomp);
• the round trip with every PUBLISH property read back off the delivery — content type, response topic, correlation data and a User Property pair (test_the_whole_round_trip_from_python);
• the async iterator over three deliveries (test_the_async_iterator_yields_deliveries);
• a Subscription Identifier reported on the delivery it caused, plus the local-matcher fallback for a server that declares none (test_a_subscription_identifier_names_the_filter_that_matched);
• a retained topic through all three states including the zero-byte delete, and the origin() of a cached copy against a live one (test_a_retained_value_is_stored_and_then_deleted);
• session resumption across two connections on one Session (test_a_session_survives_a_reconnect), and the send quota being the server's number (test_the_send_quota_is_the_servers_receive_maximum);
• the CONNACK's declarations in Python, including is_encrypted is False (test_the_connack_reaches_python);
• three refusals that never reach the wire — an illegal filter, Subscription Identifier 0, an empty SUBSCRIBE (test_a_refusal_carries_the_code_the_server_would_have_sent);
• NotConnected after a DISCONNECT, and a cancelled publish leaving the client usable (test_a_cancelled_publish_leaves_the_client_usable).

The synchronous surface against the same broker (test_sync.py): B-151's QoS 2 round trip with the awaits removed and nothing else, the blocking iterator, the receive deadline where cancellation goes, the GIL released while blocked (asserted by a count a second thread raises), one thread publishing while another consumes, and the same refusal class arriving from both surfaces (test_a_refusal_is_the_asynchronous_surfaces_refusal).

One measured disagreement, and it was found from Python. rumqttd 0.20.0 answers a two-filter UNSUBSCRIBE with one reason code where [MQTT-3.11.3-1] requires one per filter in order. Position is the only thing binding a code to a filter, so a count that disagrees is unreadable rather than merely odd, and this client raises AcknowledgementLengthMismatch instead of zipping short and telling the caller the second filter was removed with the first filter's code. One filter per UNSUBSCRIBE interoperates, and the second half of test_an_unsubscribe_length_mismatch_is_reported_and_not_guessed shows it. This is the sixth entry of mqtt.md §10's disagreement list and the only one raised by the Python suite.

The wheel, with no Rust toolchain. package.sh builds the abi3 release wheel, refuses one whose name is not abi3, installs it into a fresh temporary virtualenv and runs smoke.py with PATH scrubbed to /usr/bin:/bin — so "the wheel needs no Rust toolchain" is established rather than expected (package.sh:1-48). smoke.py checks the eleven names of the module surface, both import spellings of weida_mqtt.sync, eleven exception classes under one base, the matcher and the grammar, the two refusals of Retain Handling 3 and QoS 3, and a connect to a closed port raising a named failure rather than hanging (smoke.py:26-160).

What has never been run: paho. No test in this repository imports paho-mqtt, and no pairing between this binding and paho has been measured — in either role. Everything in the paho column of this document is that library's documented API, and nothing here is evidence that paho and this client agree on the wire. What would close it is the shape zmq-py.md §8 has: a test_interop_paho.py publishing from one and subscribing with the other, both ways, skipped with pip install paho-mqtt where the package is absent.

Neither was this document's numbers re-measured by a run. The counts above were counted out of the tree with the commands in §11; the last recorded execution is B-152's merge note (docs/BACKLOG.md, "45 passed" with rumqttd under the supervisor), which matches the 45 functions the tree holds today.

9. Deliberate deviations and bounds

9.1 TLS is absent by construction, not unfinished

The library implements TLS behind a default-on tls feature, and this binding enters it with default-features = false (Cargo.toml:29-40). The reason is one line of the library's API: ConnectOptions::tls takes the caller's rustls::ClientConfig (crates/mqtt/weida-mqtt/src/options.rs:113-122), because which certificates an application trusts is the application's decision and a messaging library that picked for it is one that cannot be audited. A ClientConfig has no Python spelling, so this surface has no way to accept one, and a binding that linked a TLS stack it could not configure would be linking it for nothing.

The consequence is stated rather than hidden: Client.is_encrypted and sync.Client.is_encrypted exist and are always False (client.rs:457-469, sync.rs:259-264), asserted as such by test_the_connack_reaches_python. That matters because the User Name, the Password and every byte of Authentication Data travel inside the CONNECT: on this transport they travel in the clear, and the attribute is how a caller finds out. What adding TLS needs is a Python spelling of "these roots, this client certificate, this server name" — the same gap nats-py.md §8.5 and amqp-py.md record, and it is filed rather than guessed at.

9.2 Two surfaces, one set of values, three handles

weida_mqtt (asyncio) and weida_mqtt.sync (blocking) are the same client. Every value class is the same object in both — ConnectOptions, Will, Session, Message, Subscription, Delivery, Completion — and so is the whole exception family; a Session built for one surface is passed to the other unchanged (tests/test_sync.py::test_the_session_is_the_same_object_in_both_surfaces).

The three handles are the only difference: Context, Client and the delivery stream, which is Events on the asyncio surface and sync.Deliveries on the blocking one (sync.rs:33-38, sync.rs:344-360, and smoke.py:40 asserts the three names). They differ because only they can: an awaitable and a blocked thread are not the same object.

weida_mqtt.sync implements no protocol behaviour. It is Python argument conversion over weida-mqtt's own blocking module, which is a block_on around each asynchronous method, so the QoS state machines, the session, the send quota, the topic aliases, the keep-alive timer and every refusal are decided exactly once and the two surfaces cannot disagree (sync.rs:20-31; 0013 §4.4 item 3). test_a_refusal_is_the_asynchronous_surfaces_refusal is what keeps that honest. The GIL is released while blocked, through Python::detach on every call, so the usual shape of a synchronous MQTT program — one thread publishing, one consuming — is two threads and not one (tests/test_sync.py::test_the_gil_is_released_while_blocked).

Two honest riders. The blocking Client carries fewer accessors than the asyncio one: server, keep_alive, response_information, response_topic and session have no synchronous counterpart (sync.rs:247-264 against client.rs:444-567), and Deliveries has no next_event, so a resumed exchange's completion is not reachable from the blocking surface. And sync.rs:36 says "the four handles differ" while naming three — the count in the prose is wrong, the code registers three classes (sync.rs:344-348), and this document records three.

9.3 51 exception classes, where paho has one errno

Every acknowledgement in 5.0 carries a reason code, which is the protocol's largest single improvement over 3.1.1. paho hands that back as a value: an MQTTErrorCode return, or a ReasonCode object a caller inspects with .value and .is_failure. Here it is the class:

• 36 classes named for MQTT reason codes, de-duplicated across packets — NotAuthorized is 0x87 in CONNACK, PUBACK, SUBACK, UNSUBACK and DISCONNECT alike, and appears once, so except NotAuthorized catches it wherever it arrived (errors.rs:65-102);
• 14 classes for failures MQTT gives no byte — NotConnected, Timeout, InvalidTopic, AcknowledgementLengthMismatch, SessionPresentWithoutState and nine more (errors.rs:104-119);
• the base, MqttError, created by the shared foundation alongside the subclasses (crates/py/weida-py-core/src/errors.rs:117-133), so except MqttError catches the lot.

36 + 14 + 1 = 51 classes, each carrying errno (the name), cause (why) and reason_code (the byte, or None) — tests/test_values.py::test_every_reason_code_is_its_own_class_under_one_base and test_the_failures_with_no_reason_code_are_classes_too. B-185 and B-151's merge note say "36 coded plus 15 uncoded"; the code has 14 uncoded, so 51 is the right total only when the base class is counted, and that is how this document counts it (§11 gives the commands).

Two properties of the table are structural rather than tested. A duplicated name is refused at import by the foundation, which is what caught ProtocolError being listed twice in the first draft (errors.rs:27-31). And connect_name and disconnect_name are exhaustive matches over the codec's own enums (errors.rs:138-202), so a reason code added to the library that is not added here is a compile error in this file rather than a code that silently arrives as the base class.

One name in the table is not a failure at all: StopAsyncIteration, which is how the end of a delivery stream is spelled, because an iteration's end is not an error (errors.rs:255-284).

9.4 publish has no timeout argument on the synchronous surface, deliberately

sync.Deliveries.recv takes timeout= — that is where the asynchronous surface's cancellation goes, since a blocking caller has no task to cancel (sync.rs:283-305). publish does not, and the omission is the argued one (sync.rs:179-186):

A publish abandoned mid-exchange is still session state on both sides, so a deadline here would return control while the exchange continued.

That is exactly what cancelling the asyncio publish does — and that surface is honest about it, because "the caller stops waiting" is what cancellation means and the exchange survives to be retransmitted on the next connection (client.rs:12-20, tests/test_interop.py::test_a_cancelled_publish_leaves_the_client_usable). An argument named timeout on a blocking publish would read as "give up on the publish", which is not something either end can do. A caller who wants the asyncio semantics runs the publish on its own thread. tests/test_sync.py::test_publish_has_no_timeout_argument_and_the_omission_is_deliberate pins the absence: passing timeout=1.0 is a TypeError.

9.5 What a Python caller does not get

• No automatic reconnect and no backoff, where paho defaults reconnect_on_failure to true with a 1..120 s doubling (../research/mqtt5.md §1 [37]). A loop that reconnected invisibly would decide the Clean Start flag on the caller's behalf, and that flag decides whether messages are lost. A reconnect is context.connect_session(address, session, options).
• No republish after a reconnect. paho's Python client republishes QoS > 0 messages after a network reconnect even with clean_session=True, calls that non-compliant itself and warns that QoS 2 messages can therefore arrive twice (sheet §13 [38]). Here retransmission happens once, just after a CONNACK with Session Present 1 ([MQTT-4.4.0-1]), and there is no retry timer at all (mqtt.md §4).
• No durable session store. Session is in memory (client.rs:199-205), as paho's is.
• No acting on Server Reference: it is readable as server["server_reference"] and following a redirection is the application's.
• No broker, per §0.

9.6 Bounds this binding inherits and exposes

The ceilings mqtt.md §9.1 adds because the protocol has none are keyword arguments here rather than constants: max_subscription_ids (32), incoming_queue (1024), connect_timeout (10 s) and ping_timeout (the Keep Alive). Two have no Python spelling — max_addresses (8) and max_user_properties (64), §5. Every duration in this surface is seconds as a float, and a negative or non-finite one is a ValueError at the call that wrote it (options.rs:18-29, values.rs:55-66, sync.rs:64-75).

9.7 Open questions this document could not close from the repository

1. The paho column is unmeasured. No paho version is pinned anywhere under crates/, and no test imports it (§1, §8). The API names in the left-hand column are paho-mqtt 2.x's documented surface; a reader who needs them load-bearing should run the interop suite §8 describes rather than trust this column.
2. sync.rs's module doc said "four handles" and named three; fixed with this document (§9.2 names the three).

10. The definition of done

The clauses of B-151, B-152 and B-185, each with its verdict and the section that proves it.

11. Sources, and the commands behind every count

Counts, each reproducible from the repository root:

Where the verdicts were read:

• Code: crates/mqtt/weida-mqtt-py/src/ — lib.rs (the module, the three functions, the TLS paragraph), client.rs (Context, Session, Client, Events), options.rs (ConnectOptions, Will), values.rs (Message, Delivery, Subscription, Completion), sync.rs (the three blocking handles), errors.rs (the 51 classes); crates/mqtt/weida-mqtt-py/Cargo.toml for the feature set and crates/mqtt/weida-mqtt-py/pyproject.toml for the wheel's metadata; crates/py/weida-py-core/src/ for the exception family, the asyncio bridge and the bytes boundary. Where a verdict depends on the library rather than the binding, the row names the file under crates/mqtt/weida-mqtt/src/.
• Tests: crates/mqtt/weida-mqtt-py/tests/ — test_interop.py, test_sync.py, test_values.py, with conftest.py for the broker fixture; smoke.py for the wheel; develop.sh and package.sh for how both are run.
• The library's own parity table: mqtt.md — §0 (why there is no server column), §2, §3, §4, §5, §6, §7, §8 (transports and the TLS trust anchors), §9 (the bounds), §10 (the broker disagreements). The protocol sheet it cites: ../research/mqtt5.md, whose §1, §11 and §13 carry the paho behaviour claims used above, with references [37] and [38].
• Decisions: 0014 §2 (one shared PyO3 foundation, asyncio first, the bytes boundary, the client/broker line), 0013 §4.4 (the three constructors, options honoured or refused, no second implementation in the binding) and §4.7 (the six clauses).
• Backlog: B-151 (the asyncio surface), B-152 (the synchronous surface, and the merge note this document's test count is compared against), B-185 (this document).
• paho-mqtt's surface: paho.mqtt.client, paho.mqtt.properties, paho.mqtt.reasoncodes, paho.mqtt.subscribeoptions, paho.mqtt.enums, paho.mqtt.publish and paho.mqtt.subscribe of eclipse-paho/paho.mqtt.python 2.x — read from that project's documentation, not from this repository and not from a run (§1, §9.7).