My experience with the eclipse clients (paho, etc) is similar to yours in both python and C++, - it makes it overly complicated and seems very low level. It also is somewhat buggy because of the architecture.
I believe (perhaps wrongly), it's all basically maintained by one person or close to it (only one person has contributed to the C++ client in the past 6 months, for example, and nobody has contributed in the past 3), so i kind of understand how it's gotten this way over time.
I filed a simple PR (1 word change) to fix an obvious bug and it took 2 years to review it and accept it with no changes. Again not a complaint, just trying to portray how the state feels - a lot of libraries, bugs, and work, and few overworked people helping get it all done.
I moved to other clients and the experience is much much better in python, rust, C#, and C++.
Most of them have a good combination of high and low level API's, so if you just want to send a message on a topic, you don't have to worry about acks, retries, etc.
But if you need control, you can get it.
Honestly, i worry at this point that keeping paho/etc alive in this state is doing more harm than good - if they were officially dead it would at least force the issue. Right now you end up with users who have an experience like yours, and then either give up on MQTT or assume they are doing it wrong :)
Its a C89 MQTT library intended for embedded devices.
Everything about it rubs me the wrong way. The API design, the poor documentation, even the way they seem to not adhere to typical python conventions.
It looks like it's easy to start using it, but then the breadth of protocols and implementations start getting to you. At a point in time, I remember the only reliable way we had of knowing if we had successfully connected to a server was to try to subscribe to a topic twice and catch a specific error code on the on_connect message (which actually was documented as a success code at the time). I know how crazy it sounds and maybe there was a better way to do it, but, if there was, I don't think it was that easy to find.
It's easy to complain, though. I'm very grateful so many people have worked to create this library. If they hadn't, I wouldn't have built what we've built with it. I really admire people who take on these huge projects.
The only place where I was unable to do this effectively was with the last will and testament message (and I might not have tried hard enough.) It also doesn't work with microcontrollers that don't run something like Linux.
It tries to be the simplest way to send and receive events.
I'm not sure what the sweet spot is, unless it's just interfacing with projects that have already committed to MQTT.
If you're open to using Lua, you might find this client library more straightforward: https://realtimelogic.com/ba/doc/en/lua/MQTT.html. It’s designed to be simple to use and works with the BAS runtime, which supports many platforms, including microcontrollers like the ESP32: https://realtimelogic.com/downloads/bas/ESP32/
I totally disagree, your expectations for the protocol seems unusual. They are not frameworks, and need to game many options.
MQTT specification is like 3 pages.
For comparison try to read specification of HTTP3, or AMQP - those are hideously complicated.