zmqtt 0.0.1__tar.gz

zmqtt-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Boris Alekseev
+
+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.

zmqtt-0.0.1/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: zmqtt
+Version: 0.0.1
+Summary: Pure asyncio MQTT 3.1.1/5.0 client library
+Keywords: mqtt,mqtt5,iot,python-mqtt,zmqtt
+Author: borisalekseev
+Author-email: borisalekseev <i.borisalekseev@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Framework :: AsyncIO
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/faststream-community/zMQTT
+Project-URL: Repository, https://github.com/faststream-community/zMQTT
+Project-URL: Documentation, https://faststream-community.github.io/zMQTT/
+Project-URL: Issues, https://github.com/faststream-community/zMQTT/issues
+Description-Content-Type: text/markdown
+
+# zmqtt
+
+Pure asyncio MQTT 3.1.1 and 5.0 client library. No paho dependency, no threading, no god classes. See [documentation](https://faststream-community.github.io/zMQTT/).
+
+## Why not aiomqtt?
+
+[aiomqtt](https://github.com/sbtinstruments/aiomqtt) is a thin async wrapper around paho-mqtt.
+You inherit paho's threading model, 10 000-line files, and implicit global state — just with `async/await` painted on top.
+
+zmqtt is built from scratch:
+
+|                  | zmqtt                                | aiomqtt (paho)                |
+| ---------------- | ------------------------------------ | ----------------------------- |
+| I/O model        | pure asyncio                         | paho threads + asyncio bridge |
+| Packet codec     | pure functions, I/O-free             | paho internals                |
+| MQTT 5.0         | native, typed properties dataclasses | partial                       |
+| Type annotations | strict mypy                          | partial                       |
+| Backpressure     | bounded subscription queues          | none                          |
+
+## Installation
+
+```bash
+pip install zmqtt
+```
+
+## Quick start
+
+```python
+import asyncio
+from zmqtt import MQTTClient
+
+async def main():
+    async with MQTTClient("broker.example.com") as client:
+        async with client.subscribe("sensors/#") as messages:
+            async for msg in messages:
+                print(msg.topic, msg.payload)
+
+asyncio.run(main())
+```
+
+Or manage connections and subscriptions manually:
+
+```python
+import asyncio
+from zmqtt import MQTTClient
+
+async def main():
+    client = MQTTClient("broker.example.com")
+    await client.connect()
+
+    subscription = client.subscribe("sensors/#")
+    await subscription.start()
+
+    msg = await subscription.get_message()
+    print(msg.topic, msg.payload)
+
+    await subscription.stop()
+    await client.disconnect()
+
+asyncio.run(main())
+```
+
+## Publish
+
+```python
+async with MQTTClient("broker.example.com") as client:
+    await client.publish("sensors/temperature", b"23.5", qos=1)
+```
+
+## QoS levels
+
+```python
+from zmqtt import QoS
+
+await client.publish("topic", b"data", qos=QoS.AT_LEAST_ONCE)   # QoS 1
+await client.publish("topic", b"data", qos=QoS.EXACTLY_ONCE)    # QoS 2
+```
+
+## Manual acknowledgement
+
+Hold the PUBACK/PUBREC until your application has durably processed the message:
+
+```python
+async with client.subscribe("orders/#", auto_ack=False) as messages:
+    async for msg in messages:
+        await save_to_database(msg)
+        await msg.ack()  # broker will redeliver if we crash before this
+```
+
+## Subscription as explicit get
+
+Useful when interleaving message handling with other async work:
+
+```python
+async with client.subscribe("sensors/#") as messages:
+    msg = await messages.get_message()
+    print(msg.topic, msg.payload)
+```
+
+## Reconnection
+
+`MQTTClient` reconnects automatically with exponential backoff. Active subscriptions
+are transparently re-registered after reconnect — your `async for` loop keeps running.
+
+## MQTT 5.0
+
+Pass `version=5` to use MQTT 5.0. Properties are typed dataclasses:
+
+```python
+from zmqtt import MQTTClient
+from zmqtt._internal.packets.properties import PublishProperties
+
+async with MQTTClient("broker.example.com", version=5) as client:
+    props = PublishProperties(content_type="application/json")
+    await client.publish("topic", b'{"value": 42}', properties=props)
+```

zmqtt-0.0.1/README.md

@@ -0,0 +1,116 @@
+# zmqtt
+
+Pure asyncio MQTT 3.1.1 and 5.0 client library. No paho dependency, no threading, no god classes. See [documentation](https://faststream-community.github.io/zMQTT/).
+
+## Why not aiomqtt?
+
+[aiomqtt](https://github.com/sbtinstruments/aiomqtt) is a thin async wrapper around paho-mqtt.
+You inherit paho's threading model, 10 000-line files, and implicit global state — just with `async/await` painted on top.
+
+zmqtt is built from scratch:
+
+|                  | zmqtt                                | aiomqtt (paho)                |
+| ---------------- | ------------------------------------ | ----------------------------- |
+| I/O model        | pure asyncio                         | paho threads + asyncio bridge |
+| Packet codec     | pure functions, I/O-free             | paho internals                |
+| MQTT 5.0         | native, typed properties dataclasses | partial                       |
+| Type annotations | strict mypy                          | partial                       |
+| Backpressure     | bounded subscription queues          | none                          |
+
+## Installation
+
+```bash
+pip install zmqtt
+```
+
+## Quick start
+
+```python
+import asyncio
+from zmqtt import MQTTClient
+
+async def main():
+    async with MQTTClient("broker.example.com") as client:
+        async with client.subscribe("sensors/#") as messages:
+            async for msg in messages:
+                print(msg.topic, msg.payload)
+
+asyncio.run(main())
+```
+
+Or manage connections and subscriptions manually:
+
+```python
+import asyncio
+from zmqtt import MQTTClient
+
+async def main():
+    client = MQTTClient("broker.example.com")
+    await client.connect()
+
+    subscription = client.subscribe("sensors/#")
+    await subscription.start()
+
+    msg = await subscription.get_message()
+    print(msg.topic, msg.payload)
+
+    await subscription.stop()
+    await client.disconnect()
+
+asyncio.run(main())
+```
+
+## Publish
+
+```python
+async with MQTTClient("broker.example.com") as client:
+    await client.publish("sensors/temperature", b"23.5", qos=1)
+```
+
+## QoS levels
+
+```python
+from zmqtt import QoS
+
+await client.publish("topic", b"data", qos=QoS.AT_LEAST_ONCE)   # QoS 1
+await client.publish("topic", b"data", qos=QoS.EXACTLY_ONCE)    # QoS 2
+```
+
+## Manual acknowledgement
+
+Hold the PUBACK/PUBREC until your application has durably processed the message:
+
+```python
+async with client.subscribe("orders/#", auto_ack=False) as messages:
+    async for msg in messages:
+        await save_to_database(msg)
+        await msg.ack()  # broker will redeliver if we crash before this
+```
+
+## Subscription as explicit get
+
+Useful when interleaving message handling with other async work:
+
+```python
+async with client.subscribe("sensors/#") as messages:
+    msg = await messages.get_message()
+    print(msg.topic, msg.payload)
+```
+
+## Reconnection
+
+`MQTTClient` reconnects automatically with exponential backoff. Active subscriptions
+are transparently re-registered after reconnect — your `async for` loop keeps running.
+
+## MQTT 5.0
+
+Pass `version=5` to use MQTT 5.0. Properties are typed dataclasses:
+
+```python
+from zmqtt import MQTTClient
+from zmqtt._internal.packets.properties import PublishProperties
+
+async with MQTTClient("broker.example.com", version=5) as client:
+    props = PublishProperties(content_type="application/json")
+    await client.publish("topic", b'{"value": 42}', properties=props)
+```

zmqtt-0.0.1/pyproject.toml

@@ -0,0 +1,98 @@
+[project]
+name = "zmqtt"
+version = "0.0.1"
+description = "Pure asyncio MQTT 3.1.1/5.0 client library"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "borisalekseev", email = "i.borisalekseev@gmail.com" }
+]
+requires-python = ">=3.10"
+dependencies = []
+keywords = ["mqtt", "mqtt5", "iot", "python-mqtt", "zmqtt"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Framework :: AsyncIO",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/faststream-community/zMQTT"
+Repository = "https://github.com/faststream-community/zMQTT"
+Documentation = "https://faststream-community.github.io/zMQTT/"
+Issues = "https://github.com/faststream-community/zMQTT/issues"
+
+[build-system]
+requires = ["uv_build>=0.9.7,<0.11.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "bandit>=1.9.4",
+    "mypy>=1.19.1",
+    "pytest>=9.0.2",
+    "pytest-asyncio>=1.3.0",
+    "pytest-cov>=7.0.0",
+    "ruff>=0.15.5",
+    "semgrep>=1.156.0",
+    "zizmor>=1.23.1",
+    {include-group = "docs"},
+]
+docs = [
+    "mkdocs>=1.6.1",
+    "mkdocs-material>=9.7.5",
+    "mkdocstrings[python]>=1.0.3",
+]
+
+[tool.mypy]
+strict = true
+files = ["src", "tests"]
+python_version = "3.10"
+
+[tool.ruff]
+src = ["src"]
+include = ["src/**.py", "tests/**.py"]
+target-version = "py310"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = ["D", "COM812", "TC001"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["S101", "D", "PLR2004", "SLF001", "FBT001"]
+"src/zmqtt/_internal/protocol.py" = ["SLF001", "PLR2004"]
+"src/zmqtt/_internal/packets/codec.py" = ["PLR", "C901"]
+"src/zmqtt/client.py" = ["PLR0913", "SLF001", "FBT"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+addopts = "--strict-markers"
+log_cli_level = "DEBUG"
+markers = [
+    "broker: requires a live MQTT broker (run with --broker or docker compose up artemis)",
+]
+
+[tool.semantic_release]
+version_toml = ["pyproject.toml:project.version"]
+allow_zero_version = true
+
+[tool.semantic_release.commit_parser_options]
+minor_tags = []
+major_tags = ["feat!"]
+patch_tags = ["fix", "feat", "perf", "chore"]
+
+[tool.semantic_release.branches.main]
+match = "master"
+prerelease_token = "alpha"
+prerelease = false

zmqtt-0.0.1/src/zmqtt/__init__.py

@@ -0,0 +1,39 @@
+from zmqtt._internal.packets.properties import AuthProperties, ConnectProperties, PublishProperties
+from zmqtt._internal.types.message import Message
+from zmqtt._internal.types.qos import QoS
+from zmqtt._internal.types.retain_handling import RetainHandling
+from zmqtt.client import (
+    MQTTClient,
+    MQTTClientV5,
+    MQTTClientV311,
+    ReconnectConfig,
+    Subscription,
+    create_client,
+)
+from zmqtt.errors import (
+    MQTTConnectError,
+    MQTTDisconnectedError,
+    MQTTError,
+    MQTTProtocolError,
+    MQTTTimeoutError,
+)
+
+__all__ = (
+    "AuthProperties",
+    "ConnectProperties",
+    "MQTTClient",
+    "MQTTClientV5",
+    "MQTTClientV311",
+    "MQTTConnectError",
+    "MQTTDisconnectedError",
+    "MQTTError",
+    "MQTTProtocolError",
+    "MQTTTimeoutError",
+    "Message",
+    "PublishProperties",
+    "QoS",
+    "ReconnectConfig",
+    "RetainHandling",
+    "Subscription",
+    "create_client",
+)

zmqtt-0.0.1/src/zmqtt/_internal/_compat.py

@@ -0,0 +1,30 @@
+"""Python version compatibility helpers."""
+
+import asyncio
+import contextlib
+import sys
+from collections.abc import AsyncGenerator
+
+if sys.version_info >= (3, 11):
+
+    @contextlib.asynccontextmanager
+    async def defer_cancellation() -> AsyncGenerator[None, None]:
+        """Temporarily remove pending cancellations, restore them after cleanup."""
+        task = asyncio.current_task()
+        cancels = task.cancelling() if task else 0
+        for _ in range(cancels):
+            if task:
+                task.uncancel()
+        try:
+            yield
+        finally:
+            for _ in range(cancels):
+                if task:
+                    task.cancel()
+
+else:
+
+    @contextlib.asynccontextmanager
+    async def defer_cancellation() -> AsyncGenerator[None, None]:
+        """No-op on Python < 3.11: cancelling()/uncancel() are not available."""
+        yield

zmqtt-0.0.1/src/zmqtt/_internal/packets/__init__.py

@@ -0,0 +1,62 @@
+"""MQTT packet dataclasses."""
+
+from zmqtt._internal.packets.auth import Auth
+from zmqtt._internal.packets.connect import ConnAck, Connect, Will
+from zmqtt._internal.packets.disconnect import Disconnect
+from zmqtt._internal.packets.ping import PingReq, PingResp
+from zmqtt._internal.packets.properties import (
+    AuthProperties,
+    ConnAckProperties,
+    ConnectProperties,
+    DisconnectProperties,
+    PubAckProperties,
+    PublishProperties,
+    SubAckProperties,
+    SubscribeProperties,
+    UnsubAckProperties,
+    UnsubscribeProperties,
+    WillProperties,
+)
+from zmqtt._internal.packets.publish import PubAck, PubComp, Publish, PubRec, PubRel
+from zmqtt._internal.packets.subscribe import (
+    SubAck,
+    Subscribe,
+    SubscriptionRequest,
+    UnsubAck,
+    Unsubscribe,
+)
+from zmqtt._internal.packets.types import FixedHeader, Packet, PacketType
+
+__all__ = [
+    "Auth",
+    "AuthProperties",
+    "ConnAck",
+    "ConnAckProperties",
+    "Connect",
+    "ConnectProperties",
+    "Disconnect",
+    "DisconnectProperties",
+    "FixedHeader",
+    "Packet",
+    "PacketType",
+    "PingReq",
+    "PingResp",
+    "PubAck",
+    "PubAckProperties",
+    "PubComp",
+    "PubRec",
+    "PubRel",
+    "Publish",
+    "PublishProperties",
+    "SubAck",
+    "SubAckProperties",
+    "Subscribe",
+    "SubscribeProperties",
+    "SubscriptionRequest",
+    "UnsubAck",
+    "UnsubAckProperties",
+    "Unsubscribe",
+    "UnsubscribeProperties",
+    "Will",
+    "WillProperties",
+]

zmqtt-0.0.1/src/zmqtt/_internal/packets/_wire.py

@@ -0,0 +1,78 @@
+"""Internal wire-format helpers: variable-length integers, UTF-8 strings, binary data."""
+
+import struct
+from typing import Final
+
+_MAX_MQTT_VARINT: Final = 268_435_455
+
+
+def encode_varint(value: int) -> bytes:
+    """Encode a non-negative integer as MQTT variable-length integer (1-4 bytes)."""
+    if value < 0 or value > _MAX_MQTT_VARINT:
+        msg = f"Value {value} out of varint range"
+        raise ValueError(msg)
+    result = bytearray()
+    while True:
+        byte = value & 0x7F
+        value >>= 7
+        if value:
+            byte |= 0x80
+        result.append(byte)
+        if not value:
+            break
+    return bytes(result)
+
+
+def decode_varint(buf: bytes | memoryview, offset: int = 0) -> tuple[int, int]:
+    """Decode MQTT variable-length integer.
+
+    Returns (value, bytes_consumed). Raises ValueError if buffer is incomplete
+    or the encoding exceeds 4 bytes.
+    """
+    multiplier = 1
+    value = 0
+    for i in range(4):
+        pos = offset + i
+        if pos >= len(buf):
+            msg = "Buffer too short for varint"
+            raise ValueError(msg)
+        byte = buf[pos]
+        value += (byte & 0x7F) * multiplier
+        if byte & 0x80 == 0:
+            return value, i + 1
+        multiplier *= 128
+    msg = "Varint exceeds 4 bytes"
+    raise ValueError(msg)
+
+
+def encode_str(s: str) -> bytes:
+    encoded = s.encode("utf-8")
+    return struct.pack("!H", len(encoded)) + encoded
+
+
+def decode_str(buf: bytes | memoryview, offset: int) -> tuple[str, int]:
+    if offset + 2 > len(buf):
+        msg = "Buffer too short for string length prefix"
+        raise ValueError(msg)
+    (length,) = struct.unpack_from("!H", buf, offset)
+    end = offset + 2 + length
+    if end > len(buf):
+        msg = "Buffer too short for string data"
+        raise ValueError(msg)
+    return bytes(buf[offset + 2 : end]).decode("utf-8"), 2 + length
+
+
+def encode_bytes_field(data: bytes) -> bytes:
+    return struct.pack("!H", len(data)) + data
+
+
+def decode_bytes_field(buf: bytes | memoryview, offset: int) -> tuple[bytes, int]:
+    if offset + 2 > len(buf):
+        msg = "Buffer too short for bytes length prefix"
+        raise ValueError(msg)
+    (length,) = struct.unpack_from("!H", buf, offset)
+    end = offset + 2 + length
+    if end > len(buf):
+        msg = "Buffer too short for bytes data"
+        raise ValueError(msg)
+    return bytes(buf[offset + 2 : end]), 2 + length

zmqtt-0.0.1/src/zmqtt/_internal/packets/auth.py

@@ -0,0 +1,15 @@
+from dataclasses import dataclass
+from typing import ClassVar
+
+from zmqtt._internal.packets.properties import AuthProperties
+from zmqtt._internal.packets.types import Packet, PacketType
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Auth(Packet):
+    """AUTH packet is MQTT 5.0 only, used for enhanced authentication."""
+
+    packet_type: ClassVar[PacketType] = PacketType.AUTH
+
+    reason_code: int = 0x00  # 0x00 = success, 0x18 = continue, 0x19 = re-authenticate
+    properties: AuthProperties | None = None