// the find
njouanin/hbmqtt
MQTT client/broker using Python asynchronous I/O
HBMQTT is a pure-Python asyncio MQTT 3.1.1 client and broker in a single package. It covers the full protocol including QoS 0/1/2, WebSocket transport, SSL, and a plugin system for auth and topic ACLs. The README opens with a 'no longer maintained' notice pointing to the amqtt fork.
The protocol implementation is thorough — all three QoS levels, proper packet-by-packet codec in hbmqtt/mqtt/, and a clean separation between client handler and broker handler. The plugin architecture is a genuine design win: auth, topic checking, persistence, and $SYS stats are all swappable without touching core code. Having both client and broker in one library is useful for testing — you can spin up a local broker and a client in the same asyncio event loop without a separate process. The sample scripts cover the common cases clearly.
Dead upstream — last commit 2022, maintainer explicitly walked away. The active fork is amqtt, so adopting hbmqtt directly means inheriting any bugs with no upstream fixes coming. MQTT 5.0 is absent entirely; if you need shared subscriptions, message expiry, or reason codes, this won't do it. The test suite skips integration coverage — test_broker.py and test_client.py exist but the broker tests in particular are thin, which made the QoS 2 flow a known source of bugs in issues before the project went quiet. Python 3.10+ asyncio API changes (notably the removal of asyncio.coroutine and loop parameter deprecations) have also caused breakage that the fork has patched but this repo has not.