ohmqtt 0.0.3__tar.gz

ohmqtt-0.0.3/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2025 Matt Vollrath
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

ohmqtt-0.0.3/MANIFEST.in

@@ -0,0 +1,10 @@
+graft ohmqtt
+graft tests
+graft examples
+
+include pyproject.toml
+include noxfile.py
+include LICENSE
+include README.md
+
+global-exclude *.pyc

ohmqtt-0.0.3/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: ohmqtt
+Version: 0.0.3
+Summary: Persistent MQTT 5.0 client
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ohmqtt/ohmqtt_python
+Project-URL: Issues, https://github.com/ohmqtt/ohmqtt_python/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications
+Classifier: Topic :: Home Automation
+Classifier: Topic :: Internet
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typing-extensions>=4.12.2; python_version < "3.11"
+Dynamic: license-file
+
+# ΩQTT
+
+*pron. "ohm cue tee tee" or "omega cutie"*
+
+A reliable and persistent MQTT 5.0 client library for Python.
+
+## Features
+
+### QoS and Persistence
+
+ΩQTT supports publish and subscribing all QoS levels with optional persistence to disk for QoS >0.
+When not persisting QoS >0 messages, a fast (but volatile) in memory store is used.
+Either way, publishing a message returns a handle with a method to wait for the message to be fully acknowledged by the broker.
+
+### Connectivity
+
+Connect to a remote broker with optional TLS over TCP over IPV4 or IPV6.
+Connect to a local broker with either TCP or Unix domain socket.
+
+### Properties
+
+Access all optional properties of all MQTT control packet types.
+If you ever wanted to check the user properties of SUBACK and UNSUBACK (among others), welcome home.
+
+### Automatic Topic Alias
+
+Set an alias policy when publishing a message and a topic alias will be generated, if allowed by the broker.
+If bandwidth is tight, set your QoS 0 publications to require a topic alias.
+In this case, an error will be raised if the server does not offer enough alias values.
+
+### Toolkit
+
+ΩQTT is built on a toolkit for efficiently serializing MQTT control messages.
+Use it to build your own custom implementation, or to serialize your own payloads.
+
+### Portability
+
+ΩQTT is tested on Linux, Windows and MacOS with CPython versions 3.10-3.13.
+It should work on any platform that CPython runs on.
+
+### Reliability
+
+ΩQTT has been implemented to a high standard of test coverage and static analysis, from the beginning.
+It continues to improve.
+
+### Performance
+
+Every drop of pure Python performance has been squeezed out of serialization and the event loop.
+You're not using Python because it's fast, but it can't hurt.
+
+## TODO for 0.1
+
+* Auth
+* Instructions
+* Error handling and validation
+* Refactor Session
+
+## TODO for 1.0
+
+* E2E Tests
+* Autodoc
+* Publish automation
+
+## Development
+
+This project uses `nox` and `uv` to run the tests against all supported Python versions.
+
+To do all of this in a venv:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install nox uv
+nox
+```
+

ohmqtt-0.0.3/README.md

@@ -0,0 +1,76 @@
+# ΩQTT
+
+*pron. "ohm cue tee tee" or "omega cutie"*
+
+A reliable and persistent MQTT 5.0 client library for Python.
+
+## Features
+
+### QoS and Persistence
+
+ΩQTT supports publish and subscribing all QoS levels with optional persistence to disk for QoS >0.
+When not persisting QoS >0 messages, a fast (but volatile) in memory store is used.
+Either way, publishing a message returns a handle with a method to wait for the message to be fully acknowledged by the broker.
+
+### Connectivity
+
+Connect to a remote broker with optional TLS over TCP over IPV4 or IPV6.
+Connect to a local broker with either TCP or Unix domain socket.
+
+### Properties
+
+Access all optional properties of all MQTT control packet types.
+If you ever wanted to check the user properties of SUBACK and UNSUBACK (among others), welcome home.
+
+### Automatic Topic Alias
+
+Set an alias policy when publishing a message and a topic alias will be generated, if allowed by the broker.
+If bandwidth is tight, set your QoS 0 publications to require a topic alias.
+In this case, an error will be raised if the server does not offer enough alias values.
+
+### Toolkit
+
+ΩQTT is built on a toolkit for efficiently serializing MQTT control messages.
+Use it to build your own custom implementation, or to serialize your own payloads.
+
+### Portability
+
+ΩQTT is tested on Linux, Windows and MacOS with CPython versions 3.10-3.13.
+It should work on any platform that CPython runs on.
+
+### Reliability
+
+ΩQTT has been implemented to a high standard of test coverage and static analysis, from the beginning.
+It continues to improve.
+
+### Performance
+
+Every drop of pure Python performance has been squeezed out of serialization and the event loop.
+You're not using Python because it's fast, but it can't hurt.
+
+## TODO for 0.1
+
+* Auth
+* Instructions
+* Error handling and validation
+* Refactor Session
+
+## TODO for 1.0
+
+* E2E Tests
+* Autodoc
+* Publish automation
+
+## Development
+
+This project uses `nox` and `uv` to run the tests against all supported Python versions.
+
+To do all of this in a venv:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install nox uv
+nox
+```
+

ohmqtt-0.0.3/examples/args.py

@@ -0,0 +1,10 @@
+import argparse
+
+
+parser = argparse.ArgumentParser(description="ohmqtt example")
+parser.add_argument(
+    "-a", "--address",
+    type=str,
+    default="localhost:1883",
+    help="MQTT broker address (default: localhost:1883)",
+)

ohmqtt-0.0.3/examples/publish.py

@@ -0,0 +1,34 @@
+#!/usr/bin/env python3
+"""This example demonstrates connecting to a broker, publishing messages to a topic, and then disconnecting."""
+
+import argparse
+import time
+
+from ohmqtt.client import Client
+
+
+def main(args: argparse.Namespace) -> None:
+    with Client() as client:
+
+        print("*** Connecting to broker...")
+        client.connect(args.address)
+
+        client.wait_for_connect(timeout=5.0)
+        print("*** Connected to broker")
+
+        for n in range(1, 9):
+            client.publish("ohmqtt/examples/publish", b"test_payload: " + str(n).encode(), qos=0)
+            print(f"*** Published message {n}")
+            time.sleep(1.0)
+
+        print("*** Disconnecting from broker...")
+        client.disconnect()
+
+        client.wait_for_disconnect(timeout=5.0)
+        print("*** Disconnected from broker")
+
+
+if __name__ == "__main__":
+    from .args import parser
+    args = parser.parse_args()
+    main(args)

ohmqtt-0.0.3/examples/publish_retain.py

@@ -0,0 +1,41 @@
+#!/usr/bin/env python3
+"""This example demonstrates publishing a retained message,
+    then subscribing to the topic and receiving the retained message."""
+
+import argparse
+from queue import Queue
+
+from ohmqtt.client import Client
+from ohmqtt.packet import MQTTPublishPacket
+
+
+def main(args: argparse.Namespace) -> None:
+    with Client() as client:
+
+        client.connect("localhost")
+        client.wait_for_connect(timeout=5.0)
+        print("*** Connected to broker")
+
+        pub = client.publish("ohmqtt/examples/publish_retain", b"test_payload", qos=1, retain=True)
+        assert pub.wait_for_ack()
+
+        q: Queue[MQTTPublishPacket] = Queue()
+        def callback(_: Client, msg: MQTTPublishPacket) -> None:
+            q.put(msg)
+        client.subscribe("ohmqtt/examples/publish_retain", callback)
+        msg = q.get(timeout=5.0)
+        assert msg.topic == "ohmqtt/examples/publish_retain"
+        assert msg.payload == b"test_payload"
+        assert msg.qos == 1
+        assert msg.retain
+        print(f"*** Received retained message: {msg!s}")
+
+        client.disconnect()
+        client.wait_for_disconnect(timeout=5.0)
+        print("*** Disconnected from broker")
+
+
+if __name__ == "__main__":
+    from .args import parser
+    args = parser.parse_args()
+    main(args)

ohmqtt-0.0.3/examples/publish_wait_for_ack.py

@@ -0,0 +1,32 @@
+#!/usr/bin/env python3
+"""This example demonstrates waiting for a published message to be fully acknowledged by the broker
+before proceeding to send the next message.
+
+It also demonstrates the debug logging output of the client.
+"""
+
+import argparse
+import logging
+
+from ohmqtt.client import Client
+
+
+def main(args: argparse.Namespace) -> None:
+    logging.basicConfig(level=logging.DEBUG)
+    with Client() as client:
+
+        client.connect(args.address)
+        client.wait_for_connect(timeout=5.0)
+
+        for n in range(1, 9):
+            publish_handle = client.publish("ohmqtt/examples/publish_wait_for_ack", b"test_payload: " + str(n).encode(), qos=2)
+            assert publish_handle.wait_for_ack()
+
+        client.disconnect()
+        client.wait_for_disconnect(timeout=5.0)
+
+
+if __name__ == "__main__":
+    from .args import parser
+    args = parser.parse_args()
+    main(args)

ohmqtt-0.0.3/examples/rpc_caller.py

@@ -0,0 +1,92 @@
+#!/usr/bin/env python3
+"""This example demonstrates a simple RPC caller.
+
+It sends an RPC request to a specific topic and waits for the response.
+
+The ResponseTopic property is used to specify the topic to which the response should be sent."""
+
+import argparse
+import threading
+import uuid
+from typing import Callable
+
+from ohmqtt.client import Client
+from ohmqtt.packet import MQTTPublishPacket
+from ohmqtt.property import MQTTPublishProps
+
+
+RPCCallback = Callable[[bytes], None]
+
+
+class RPCCaller:
+    """A simple RPC caller."""
+    def __init__(self, client: Client) -> None:
+        self.client = client
+        self.callbacks: dict[str, RPCCallback] = {}
+
+    def send_request(self, payload: bytes, callback: RPCCallback) -> None:
+        # Expect the response to be sent to a unique topic.
+        unique_id = str(uuid.uuid4())
+        response_topic = f"ohmqtt/examples/rpc/response/{unique_id}"
+
+        # Store the callback for this request.
+        self.callbacks[unique_id] = callback
+
+        # Subscribe to the response topic.
+        self.client.subscribe(response_topic, self.handle_response)
+
+        # Publish the request with the necessary properties.
+        self.client.publish(
+            "ohmqtt/examples/rpc/request",
+            payload,
+            qos=2,
+            properties=MQTTPublishProps(ResponseTopic=response_topic),
+        ).wait_for_ack()
+
+        print(f"Sent RPC request with response topic: {response_topic}")
+
+    def handle_response(self, client: Client, msg: MQTTPublishPacket) -> None:
+        """Handle incoming RPC responses."""
+        try:
+            callback = self.callbacks.pop(msg.topic.split("/")[-1])
+        except KeyError:
+            print("Couldn't find callback for response")
+            return
+        else:
+            # Call the callback with the response payload.
+            callback(msg.payload)
+        finally:
+            # Unsubscribe from the response topic.
+            client.unsubscribe(msg.topic, self.handle_response)
+
+
+def main(args: argparse.Namespace) -> None:
+    with Client() as client:
+        rpc_caller = RPCCaller(client)
+        client.connect(args.address)
+        print("*** Waiting for connection...")
+        client.wait_for_connect(timeout=5.0)
+
+        # Set up a callback which helps us block until a response is received.
+        recvd = threading.Event()
+        def callback(payload: bytes) -> None:
+            print(f"*** Received RPC response: {payload.decode()}")
+            recvd.set()  # Signal that the response has been received.
+
+        while True:
+            recvd.clear()  # Reset the event for the next request.
+            try:
+                payload = input("*** Enter something fun (or 'exit' to quit): ")
+                if payload.lower() == "exit":
+                    break
+                rpc_caller.send_request(payload.encode(), callback)
+                recvd.wait(timeout=5.0)  # Wait for the response to be received.
+            except (EOFError, KeyboardInterrupt):
+                print("\n*** Shutting down RPC caller...")
+                break
+
+
+if __name__ == "__main__":
+    from .args import parser
+    args = parser.parse_args()
+    main(args)

ohmqtt-0.0.3/examples/rpc_server.py

@@ -0,0 +1,62 @@
+#!/usr/bin/env python3
+"""This example demonstrates a simple RPC server.
+
+It listens for incoming RPC requests on a specific topic and responds with the result of the RPC call.
+
+The ResponseTopic property is used by the requestor to specify the topic to which the response should be sent.
+
+See the "rpc_caller" example for the request side of this RPC implementation.
+
+This also demonstrates running the client loop in the main thread."""
+
+import argparse
+
+from ohmqtt.client import Client
+from ohmqtt.packet import MQTTPublishPacket
+from ohmqtt.property import MQTTPublishProps
+
+
+class RPCServer:
+    """A simple stateless RPC server."""
+    def handle_request(self, client: Client, msg: MQTTPublishPacket) -> None:
+        """Handle incoming RPC requests."""
+        print(f"*** Received RPC request: {msg!s}")
+
+        # Find the response topic in the message properties.
+        if not msg.properties.ResponseTopic:
+            print("Request was missing required response topic property")
+            return
+        response_topic = msg.properties.ResponseTopic
+
+        response_props = MQTTPublishProps()
+        # If the request includes correlation data, send it back in the response.
+        if msg.properties.CorrelationData is not None:
+            response_props.CorrelationData = msg.properties.CorrelationData
+
+        # Simulate some processing.
+        response = f"This is a good day for {msg.payload.decode()}"
+
+        # Send the response back to the specified topic.
+        client.publish(response_topic, response.encode(), qos=2, properties=response_props)
+
+
+def main(args: argparse.Namespace) -> None:
+    rpc_server = RPCServer()
+    client = Client()
+    client.connect(args.address)
+    print("*** Waiting for connection...")
+    assert client.loop_until_connected(timeout=5.0), "Timeout waiting for connection"
+
+    client.subscribe("ohmqtt/examples/rpc/request", rpc_server.handle_request)
+    print("*** Waiting for RPC requests...")
+
+    try:
+        client.loop_forever()  # Wait indefinitely for incoming messages.
+    except KeyboardInterrupt:
+        print("\n*** Shutting down RPC server...")
+
+
+if __name__ == "__main__":
+    from .args import parser
+    args = parser.parse_args()
+    main(args)

ohmqtt-0.0.3/noxfile.py

@@ -0,0 +1,19 @@
+import nox
+import sys
+
+nox.options.default_venv_backend = "uv|virtualenv"
+py_versions = ("3.10", "3.11", "3.12", "3.13")
+
+
+@nox.session(python=py_versions)
+def tests(session):
+    session.install(".")
+    session.install("--group", "dev")
+    session.run("ruff", "check")
+    session.run("typos")
+    session.run("mypy")
+    if sys.platform != "win32":
+        session.run("complexipy", "-d", "low", "ohmqtt", "examples", "tests")
+    else:
+        session.log("Skipping complexipy check on Windows: https://github.com/rohaquinlop/complexipy/issues/67")
+    session.run("pytest", "--cov-report=term-missing")