# simple-mqtt
Compact Python MQTT wrapper around **paho-mqtt**. Focus: clear builder pattern and an explicit split between MQTT v3.1.1 and MQTT v5.
## Installation
```bash
pip install simple-mqtt
```
## Builders
This package exposes two concrete builders:
- `MQTTBuilderV3(client_id, host)` → builds a `MQTTConnectionV3` (MQTT v3.1.1)
- `MQTTBuilderV5(client_id, host)` → builds a `MQTTConnectionV5` (MQTT v5.0)
Both builders provide the same fluent configuration API.
`build()` creates the connection wrapper and prepares the client.
`fast_build()` equals `build().connect()`.
---
## Quickstart: minimal setup
Connect, subscribe, print messages.
Identical for v3 and v5.
```python
from simplemqtt import MQTTBuilderV3, QualityOfService as QoS # for v5 swap to MQTTBuilderV5
conn = MQTTBuilderV3(client_id="demo-client", host="localhost").fast_build()
def on_msg(connection, client, userdata, msg):
print(f"[{msg.topic}] {msg.payload!r} retain={msg.retain} qos={msg.qos}")
conn.subscribe("test/topic", on_message=on_msg, qos=QoS.AtLeastOnce)
conn.publish("test/topic", "hello", qos=QoS.AtLeastOnce, retain=False)
conn.close()
```
---
## Defaults
- Port: `1883`, Keepalive: `60`
- Clean session: `True`
- For v5: `SessionExpiryInterval` = 0 by default (non‑persistent). If you call `.persistent_session(True)`, it is set to 3600 seconds.
---
## Build a connection
### 1) Minimal (constructor + connect)
```python
from simplemqtt import MQTTBuilderV3 # for v5 swap to MQTTBuilderV5
conn = (
MQTTBuilderV3("client-1", "broker.example.org")
.fast_build() # build().connect()
)
```
### 2) With username/password
```python
from simplemqtt import MQTTBuilderV3 # for v5 swap to MQTTBuilderV5
conn = (
MQTTBuilderV3("client-2", "broker.example.org")
.login("user", "password")
.fast_build()
)
```
### 3) Port + keepalive + persistent session + auto‑reconnect
```python
from simplemqtt import MQTTBuilderV3 # for v5 swap to MQTTBuilderV5
conn = (
MQTTBuilderV3("client-3", "broker.example.org")
.port(1884)
.keep_alive(120)
.persistent_session(True)
.auto_reconnect(min_delay=1, max_delay=30)
.fast_build()
)
```
### 4) Last Will (LWT)
```python
from simplemqtt import MQTTBuilderV3, QualityOfService as QoS # for v5 swap to MQTTBuilderV5
conn = (
MQTTBuilderV3("client-4", "broker.example.org")
.last_will("devices/dev42/availability", payload="offline", qos=QoS.AtLeastOnce, retain=True)
.fast_build()
)
```
### 5) Availability topic
```python
from simplemqtt import MQTTBuilderV3 # for v5 swap to MQTTBuilderV5
conn = (
MQTTBuilderV3("client-5", "broker.example.org")
.availability("devices/dev42/availability", payload_online="online", payload_offline="offline")
.fast_build()
)
```
### 6) TLS (defaults)
```python
from simplemqtt import MQTTBuilderV3 # for v5 swap to MQTTBuilderV5
conn = (
MQTTBuilderV3("client-6", "broker.example.org")
.tls() # verify certificates using system defaults
.fast_build()
)
```
### 7) TLS with custom CA
```python
from simplemqtt import MQTTBuilderV3 # for v5 swap to MQTTBuilderV5
conn = (
MQTTBuilderV3("client-7", "broker.example.org")
.own_tls("/etc/ssl/certs/ca-bundle.pem", allow_insecure=False)
.fast_build()
)
```
> **TLS capabilities (current):**
>
> - Supported: server TLS with system CAs (`.tls()`), server TLS with custom CA bundle (`.own_tls(ca_certs=...)`), optional hostname skip via `allow_insecure=True`.
> - Not yet wired in the builder: client certificates (`certfile`/`keyfile` mTLS), custom ciphers/TLS versions, WebSockets-specific TLS options. You can still access these via raw `paho-mqtt` if needed.
---
## Use a connection
### Connect
```python
from simplemqtt import MQTTBuilderV3 # for v5 swap to MQTTBuilderV5
conn = MQTTBuilderV3("client-1", "broker.example.org").build()
conn.connect()
# or
conn.connect(blocking=True)
```
### Callbacks (V3)
```python
import logging
from simplemqtt import MQTTBuilderV3
from simplemqtt.mqtt_connections import MQTTConnectionV3
logger = logging.getLogger("Info")
conn = MQTTBuilderV3("client-2", "broker.example.org").fast_build()
def on_connect_v3(connection: MQTTConnectionV3, client, userdata, flags):
connection.publish("say/hello", "hello :)")
def before_disconnect_v3(connection: MQTTConnectionV3):
connection.publish("say/hello", "bye :(")
def on_disconnect_v3(client, userdata, rc):
logger.info("Too late for publishing")
conn.add_on_connect(on_connect_v3)
conn.add_before_disconnect(before_disconnect_v3)
conn.add_on_disconnect(on_disconnect_v3)
```
### Callbacks (V5)
```python
import logging
from simplemqtt import MQTTBuilderV5
from simplemqtt.mqtt_connections import MQTTConnectionV5
logger = logging.getLogger("Info")
conn = MQTTBuilderV5("client-2", "broker.example.org").fast_build()
def on_connect_v5(connection: MQTTConnectionV5, client, userdata, flags, properties):
connection.publish("say/hello", "hello :)")
def before_disconnect_v5(connection: MQTTConnectionV5):
connection.publish("say/hello", "bye :(")
def on_disconnect_v5(client, userdata, rc, properties):
logger.info("Too late for publishing")
conn.add_on_connect(on_connect_v5)
conn.add_before_disconnect(before_disconnect_v5)
conn.add_on_disconnect(on_disconnect_v5)
```
### Subscribe
Identical for v3 and v5.
```python
from simplemqtt import QualityOfService as QoS
def on_msg(connection, client, userdata, msg):
print(msg.topic, msg.payload)
conn.subscribe("sensors/+/temp", on_message=on_msg, qos=QoS.AtLeastOnce)
```
### Unsubscribe
Identical for v3 and v5.
```python
# Remove one or more filters
conn.unsubscribe("sensors/+/temp", "actuators/#")
```
### Close
Identical for v3 and v5.
```python
conn.close() # loop_stop + disconnect
```
---
## Protocol specifics
### MQTT v3.1.1
**Publish**
```python
from simplemqtt import QualityOfService as QoS
# Simple
conn.publish("demo/topic", "payload")
# With QoS/retain
conn.publish("demo/topic", "payload", qos=QoS.AtLeastOnce, retain=True)
# Wait for publish completion
conn.publish("demo/topic", "payload", qos=QoS.AtLeastOnce, wait_for_publish=True)
```
**Subscribe**
```python
from simplemqtt import QualityOfService as QoS
def on_msg_v3(connection, client, userdata, msg):
print("v3:", msg.topic, msg.payload)
conn.subscribe("demo/v3/#", on_message=on_msg_v3, qos=QoS.ExactlyOnce)
```
### MQTT v5
**Build a v5 connection**
```python
from simplemqtt import MQTTBuilderV5
conn = MQTTBuilderV5("client-5", "broker.example.org").fast_build()
```
**Publish** with properties
```python
from paho.mqtt.properties import Properties
from paho.mqtt.packettypes import PacketTypes
from simplemqtt import QualityOfService as QoS
props = Properties(PacketTypes.PUBLISH)
props.MessageExpiryInterval = 30 # seconds
# Simple
conn.publish("demo5/topic", "payload-v5")
# With QoS/retain/properties
conn.publish("demo5/topic", "payload-v5", qos=QoS.AtLeastOnce, retain=False, properties=props)
# Wait for completion
conn.publish("demo5/topic", "payload-v5", qos=QoS.AtLeastOnce, wait_for_publish=True, properties=props)
```
**Subscribe** with options
```python
from simplemqtt import QualityOfService as QoS, RetainHandling
def on_msg_v5(connection, client, userdata, msg):
print("v5:", msg.topic, msg.payload, "retain:", msg.retain)
conn.subscribe(
"demo5/#",
on_message=on_msg_v5,
qos=QoS.AtLeastOnce,
no_local=True,
retain_as_published=True,
retain_handling=RetainHandling.SendRetainedOnNewSubscription,
)
```
---
## Logging
This package uses `logging` with a `NullHandler`. Enable it like this:
```python
import logging
logging.basicConfig(level=logging.INFO)
logging.getLogger("simplemqtt").setLevel(logging.DEBUG)
```
## Best practices
- Use a stable `client_id` per device.
- Set LWT (`.last_will(...)`) with QoS ≥ 1 and `retain=True`.
- Enable auto‑reconnect for production.
- For v5, use `retain_handling` and `no_local` to reduce retained floods and pub/sub loops.
## License
MIT (see `LICENSE`).
</file>
Raw data
{
"_id": null,
"home_page": null,
"name": "simple-mqtt",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "mqtt, iot",
"author": "Dev-CorliJoni",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/b9/6c/60555fb17118c9d1be76cb8324f8b0e4b177bab93773e9967d2d91556305/simple_mqtt-0.1.1.tar.gz",
"platform": null,
"description": "# simple-mqtt\n\nCompact Python MQTT wrapper around **paho-mqtt**. Focus: clear builder pattern and an explicit split between MQTT v3.1.1 and MQTT v5.\n\n## Installation\n\n```bash\npip install simple-mqtt\n```\n\n## Builders\n\nThis package exposes two concrete builders:\n\n- `MQTTBuilderV3(client_id, host)` \u2192 builds a `MQTTConnectionV3` (MQTT v3.1.1)\n- `MQTTBuilderV5(client_id, host)` \u2192 builds a `MQTTConnectionV5` (MQTT v5.0)\n\nBoth builders provide the same fluent configuration API.\n\n`build()` creates the connection wrapper and prepares the client. \n`fast_build()` equals `build().connect()`.\n\n---\n\n## Quickstart: minimal setup\n\nConnect, subscribe, print messages.\n\nIdentical for v3 and v5.\n```python\nfrom simplemqtt import MQTTBuilderV3, QualityOfService as QoS # for v5 swap to MQTTBuilderV5\n\nconn = MQTTBuilderV3(client_id=\"demo-client\", host=\"localhost\").fast_build()\n\ndef on_msg(connection, client, userdata, msg):\n print(f\"[{msg.topic}] {msg.payload!r} retain={msg.retain} qos={msg.qos}\")\n\nconn.subscribe(\"test/topic\", on_message=on_msg, qos=QoS.AtLeastOnce)\nconn.publish(\"test/topic\", \"hello\", qos=QoS.AtLeastOnce, retain=False)\n\nconn.close()\n```\n\n---\n\n## Defaults\n\n- Port: `1883`, Keepalive: `60` \n- Clean session: `True` \n- For v5: `SessionExpiryInterval` = 0 by default (non\u2011persistent). If you call `.persistent_session(True)`, it is set to 3600 seconds. \n\n---\n\n## Build a connection\n\n### 1) Minimal (constructor + connect)\n```python\nfrom simplemqtt import MQTTBuilderV3 # for v5 swap to MQTTBuilderV5\n\nconn = (\n MQTTBuilderV3(\"client-1\", \"broker.example.org\")\n .fast_build() # build().connect()\n)\n```\n\n### 2) With username/password\n```python\nfrom simplemqtt import MQTTBuilderV3 # for v5 swap to MQTTBuilderV5\n\nconn = (\n MQTTBuilderV3(\"client-2\", \"broker.example.org\")\n .login(\"user\", \"password\")\n .fast_build()\n)\n```\n\n### 3) Port + keepalive + persistent session + auto\u2011reconnect\n```python\nfrom simplemqtt import MQTTBuilderV3 # for v5 swap to MQTTBuilderV5\n\nconn = (\n MQTTBuilderV3(\"client-3\", \"broker.example.org\")\n .port(1884)\n .keep_alive(120)\n .persistent_session(True)\n .auto_reconnect(min_delay=1, max_delay=30)\n .fast_build()\n)\n```\n\n### 4) Last Will (LWT)\n```python\nfrom simplemqtt import MQTTBuilderV3, QualityOfService as QoS # for v5 swap to MQTTBuilderV5\n\nconn = (\n MQTTBuilderV3(\"client-4\", \"broker.example.org\")\n .last_will(\"devices/dev42/availability\", payload=\"offline\", qos=QoS.AtLeastOnce, retain=True)\n .fast_build()\n)\n```\n\n### 5) Availability topic\n```python\nfrom simplemqtt import MQTTBuilderV3 # for v5 swap to MQTTBuilderV5\n\nconn = (\n MQTTBuilderV3(\"client-5\", \"broker.example.org\")\n .availability(\"devices/dev42/availability\", payload_online=\"online\", payload_offline=\"offline\")\n .fast_build()\n)\n```\n\n### 6) TLS (defaults)\n```python\nfrom simplemqtt import MQTTBuilderV3 # for v5 swap to MQTTBuilderV5\n\nconn = (\n MQTTBuilderV3(\"client-6\", \"broker.example.org\")\n .tls() # verify certificates using system defaults\n .fast_build()\n)\n```\n\n### 7) TLS with custom CA\n```python\nfrom simplemqtt import MQTTBuilderV3 # for v5 swap to MQTTBuilderV5\n\nconn = (\n MQTTBuilderV3(\"client-7\", \"broker.example.org\")\n .own_tls(\"/etc/ssl/certs/ca-bundle.pem\", allow_insecure=False)\n .fast_build()\n)\n```\n\n> **TLS capabilities (current):**\n>\n> - Supported: server TLS with system CAs (`.tls()`), server TLS with custom CA bundle (`.own_tls(ca_certs=...)`), optional hostname skip via `allow_insecure=True`.\n> - Not yet wired in the builder: client certificates (`certfile`/`keyfile` mTLS), custom ciphers/TLS versions, WebSockets-specific TLS options. You can still access these via raw `paho-mqtt` if needed.\n\n---\n\n## Use a connection\n\n### Connect\n\n```python\nfrom simplemqtt import MQTTBuilderV3 # for v5 swap to MQTTBuilderV5\n\nconn = MQTTBuilderV3(\"client-1\", \"broker.example.org\").build()\nconn.connect()\n# or\nconn.connect(blocking=True)\n```\n\n### Callbacks (V3)\n```python\nimport logging\nfrom simplemqtt import MQTTBuilderV3\nfrom simplemqtt.mqtt_connections import MQTTConnectionV3\n\nlogger = logging.getLogger(\"Info\")\n\nconn = MQTTBuilderV3(\"client-2\", \"broker.example.org\").fast_build()\n\ndef on_connect_v3(connection: MQTTConnectionV3, client, userdata, flags):\n connection.publish(\"say/hello\", \"hello :)\")\n\ndef before_disconnect_v3(connection: MQTTConnectionV3):\n connection.publish(\"say/hello\", \"bye :(\")\n\ndef on_disconnect_v3(client, userdata, rc):\n logger.info(\"Too late for publishing\")\n\nconn.add_on_connect(on_connect_v3)\nconn.add_before_disconnect(before_disconnect_v3)\nconn.add_on_disconnect(on_disconnect_v3)\n```\n\n### Callbacks (V5)\n```python\nimport logging\nfrom simplemqtt import MQTTBuilderV5\nfrom simplemqtt.mqtt_connections import MQTTConnectionV5\n\nlogger = logging.getLogger(\"Info\")\n\nconn = MQTTBuilderV5(\"client-2\", \"broker.example.org\").fast_build()\n\ndef on_connect_v5(connection: MQTTConnectionV5, client, userdata, flags, properties):\n connection.publish(\"say/hello\", \"hello :)\")\n\ndef before_disconnect_v5(connection: MQTTConnectionV5):\n connection.publish(\"say/hello\", \"bye :(\")\n\ndef on_disconnect_v5(client, userdata, rc, properties):\n logger.info(\"Too late for publishing\")\n\nconn.add_on_connect(on_connect_v5)\nconn.add_before_disconnect(before_disconnect_v5)\nconn.add_on_disconnect(on_disconnect_v5)\n```\n\n### Subscribe\n\nIdentical for v3 and v5.\n```python\nfrom simplemqtt import QualityOfService as QoS\n\ndef on_msg(connection, client, userdata, msg):\n print(msg.topic, msg.payload)\n\nconn.subscribe(\"sensors/+/temp\", on_message=on_msg, qos=QoS.AtLeastOnce)\n```\n\n### Unsubscribe\n\nIdentical for v3 and v5.\n```python\n# Remove one or more filters\nconn.unsubscribe(\"sensors/+/temp\", \"actuators/#\")\n```\n\n### Close\n\nIdentical for v3 and v5.\n```python\nconn.close() # loop_stop + disconnect\n```\n\n---\n\n## Protocol specifics\n\n### MQTT v3.1.1\n\n**Publish**\n```python\nfrom simplemqtt import QualityOfService as QoS\n\n# Simple\nconn.publish(\"demo/topic\", \"payload\")\n\n# With QoS/retain\nconn.publish(\"demo/topic\", \"payload\", qos=QoS.AtLeastOnce, retain=True)\n\n# Wait for publish completion\nconn.publish(\"demo/topic\", \"payload\", qos=QoS.AtLeastOnce, wait_for_publish=True)\n```\n\n**Subscribe**\n```python\nfrom simplemqtt import QualityOfService as QoS\n\ndef on_msg_v3(connection, client, userdata, msg):\n print(\"v3:\", msg.topic, msg.payload)\n\nconn.subscribe(\"demo/v3/#\", on_message=on_msg_v3, qos=QoS.ExactlyOnce)\n```\n\n### MQTT v5\n\n**Build a v5 connection**\n```python\nfrom simplemqtt import MQTTBuilderV5\nconn = MQTTBuilderV5(\"client-5\", \"broker.example.org\").fast_build()\n```\n\n**Publish** with properties\n```python\nfrom paho.mqtt.properties import Properties\nfrom paho.mqtt.packettypes import PacketTypes\nfrom simplemqtt import QualityOfService as QoS\n\nprops = Properties(PacketTypes.PUBLISH)\nprops.MessageExpiryInterval = 30 # seconds\n\n# Simple\nconn.publish(\"demo5/topic\", \"payload-v5\")\n\n# With QoS/retain/properties\nconn.publish(\"demo5/topic\", \"payload-v5\", qos=QoS.AtLeastOnce, retain=False, properties=props)\n\n# Wait for completion\nconn.publish(\"demo5/topic\", \"payload-v5\", qos=QoS.AtLeastOnce, wait_for_publish=True, properties=props)\n```\n\n**Subscribe** with options\n```python\nfrom simplemqtt import QualityOfService as QoS, RetainHandling\n\ndef on_msg_v5(connection, client, userdata, msg):\n print(\"v5:\", msg.topic, msg.payload, \"retain:\", msg.retain)\n\nconn.subscribe(\n \"demo5/#\",\n on_message=on_msg_v5,\n qos=QoS.AtLeastOnce,\n no_local=True,\n retain_as_published=True,\n retain_handling=RetainHandling.SendRetainedOnNewSubscription,\n)\n```\n\n---\n\n## Logging\n\nThis package uses `logging` with a `NullHandler`. Enable it like this:\n\n```python\nimport logging\nlogging.basicConfig(level=logging.INFO)\nlogging.getLogger(\"simplemqtt\").setLevel(logging.DEBUG)\n```\n\n## Best practices\n\n- Use a stable `client_id` per device.\n- Set LWT (`.last_will(...)`) with QoS \u2265 1 and `retain=True`.\n- Enable auto\u2011reconnect for production.\n- For v5, use `retain_handling` and `no_local` to reduce retained floods and pub/sub loops.\n\n## License\n\nMIT (see `LICENSE`).\n</file>\n",
"bugtrack_url": null,
"license": null,
"summary": "Framework for building easy MQTT applications",
"version": "0.1.1",
"project_urls": {
"GitHub": "https://github.com/Dev-CorliJoni/simple-mqtt",
"Instagram": "https://www.instagram.com/dev.corlijoni/",
"Issues": "https://github.com/Dev-CorliJoni/simple-mqtt/issues",
"Source": "https://github.com/Dev-CorliJoni/simple-mqtt"
},
"split_keywords": [
"mqtt",
" iot"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e49a2d57db91ff793fc6a91f6acd2d214265b99d7fe68fc2aae2337a93c4f748",
"md5": "7ab94912d2e5d87bb30a99a35d76878d",
"sha256": "1b53301fba3a395ce4ce24f3a4321148e67ba67e134e341d162601841480e33d"
},
"downloads": -1,
"filename": "simple_mqtt-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7ab94912d2e5d87bb30a99a35d76878d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 15175,
"upload_time": "2025-10-27T00:01:43",
"upload_time_iso_8601": "2025-10-27T00:01:43.401132Z",
"url": "https://files.pythonhosted.org/packages/e4/9a/2d57db91ff793fc6a91f6acd2d214265b99d7fe68fc2aae2337a93c4f748/simple_mqtt-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b96c60555fb17118c9d1be76cb8324f8b0e4b177bab93773e9967d2d91556305",
"md5": "ec77c519a48a8a08a1cbcf6a68ff06d5",
"sha256": "1217583b4d190daea521bfc49d6b6ef7f7120a32a8992ac7a92519f001970e6b"
},
"downloads": -1,
"filename": "simple_mqtt-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "ec77c519a48a8a08a1cbcf6a68ff06d5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 10586,
"upload_time": "2025-10-27T00:01:44",
"upload_time_iso_8601": "2025-10-27T00:01:44.677619Z",
"url": "https://files.pythonhosted.org/packages/b9/6c/60555fb17118c9d1be76cb8324f8b0e4b177bab93773e9967d2d91556305/simple_mqtt-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-27 00:01:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Dev-CorliJoni",
"github_project": "simple-mqtt",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "paho-mqtt",
"specs": [
[
"<",
"3"
],
[
">=",
"1.6"
]
]
}
],
"lcname": "simple-mqtt"
}
JSON
