uns-kit 0.0.2__tar.gz

uns_kit-0.0.2/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: uns-kit
+Version: 0.0.2
+Summary: Lightweight Python UNS MQTT client (pub/sub + infra topics)
+License: MIT
+Author: Aljoša Vister
+Author-email: aljosa.vister@gmail.com
+Requires-Python: >=3.10,<4.0
+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
+Requires-Dist: asyncio-mqtt (>=0.16.1,<0.17.0)
+Requires-Dist: click (>=8.1.7,<9.0.0)
+Description-Content-Type: text/markdown
+
+# uns-kit (Python)
+
+Lightweight UNS MQTT client for Python. Provides:
+- Topic builder compatible with UNS infra topics (`uns-infra/<package>/<version>/<process>/`).
+- Async publish/subscribe via MQTT v5 (using `asyncio-mqtt`).
+- Infra status topics (`alive`, `uptime`) with MQTT will.
+- Minimal UNS packet builder/parser (data/table).
+
+## Install (editable)
+```bash
+cd packages/uns-py
+poetry install
+```
+
+## CLI
+After `poetry install`, a `uns-kit` command is available:
+```bash
+poetry run uns-kit publish --host localhost:1883 --topic raw/data/ --value 1
+poetry run uns-kit subscribe --host localhost:1883 --topic 'uns-infra/#'
+poetry run uns-kit write-config --path config.json
+```
+
+## Quick start
+```python
+import asyncio
+from uns_kit import UnsMqttClient, TopicBuilder, UnsPacket
+
+async def main():
+    tb = TopicBuilder(package_name="uns-kit", package_version="0.0.1", process_name="py-demo")
+    client = UnsMqttClient(host="mqtt-broker", topic_builder=tb, reconnect_interval=1)
+    await client.connect()
+
+    # Subscribe
+    async with client.messages("uns-infra/#") as messages:
+        await client.publish_packet("raw/data/", UnsPacket.data(value=1, uom="count"))
+        msg = await messages.__anext__()
+        print(msg.topic, msg.payload.decode())
+
+    await client.close()
+
+asyncio.run(main())
+```
+
+### Resilient subscriber
+```python
+async for msg in client.resilient_messages("uns-infra/#"):
+    print(msg.topic, msg.payload.decode())
+```
+
+### Examples
+- `examples/publish.py` — publish 5 data packets.
+- `examples/subscribe.py` — resilient subscription with auto-reconnect.
+
+## Notes
+- Default QoS is 0; will message is retained on `<statusTopic>alive`.
+- Uptime is published every 10 seconds on `<statusTopic>uptime`.
+- Packet shape mirrors the TypeScript core: `{"version":1,"message":{"data":{...}},"sequenceId":0}`.
+

uns_kit-0.0.2/README.md

@@ -0,0 +1,57 @@
+# uns-kit (Python)
+
+Lightweight UNS MQTT client for Python. Provides:
+- Topic builder compatible with UNS infra topics (`uns-infra/<package>/<version>/<process>/`).
+- Async publish/subscribe via MQTT v5 (using `asyncio-mqtt`).
+- Infra status topics (`alive`, `uptime`) with MQTT will.
+- Minimal UNS packet builder/parser (data/table).
+
+## Install (editable)
+```bash
+cd packages/uns-py
+poetry install
+```
+
+## CLI
+After `poetry install`, a `uns-kit` command is available:
+```bash
+poetry run uns-kit publish --host localhost:1883 --topic raw/data/ --value 1
+poetry run uns-kit subscribe --host localhost:1883 --topic 'uns-infra/#'
+poetry run uns-kit write-config --path config.json
+```
+
+## Quick start
+```python
+import asyncio
+from uns_kit import UnsMqttClient, TopicBuilder, UnsPacket
+
+async def main():
+    tb = TopicBuilder(package_name="uns-kit", package_version="0.0.1", process_name="py-demo")
+    client = UnsMqttClient(host="mqtt-broker", topic_builder=tb, reconnect_interval=1)
+    await client.connect()
+
+    # Subscribe
+    async with client.messages("uns-infra/#") as messages:
+        await client.publish_packet("raw/data/", UnsPacket.data(value=1, uom="count"))
+        msg = await messages.__anext__()
+        print(msg.topic, msg.payload.decode())
+
+    await client.close()
+
+asyncio.run(main())
+```
+
+### Resilient subscriber
+```python
+async for msg in client.resilient_messages("uns-infra/#"):
+    print(msg.topic, msg.payload.decode())
+```
+
+### Examples
+- `examples/publish.py` — publish 5 data packets.
+- `examples/subscribe.py` — resilient subscription with auto-reconnect.
+
+## Notes
+- Default QoS is 0; will message is retained on `<statusTopic>alive`.
+- Uptime is published every 10 seconds on `<statusTopic>uptime`.
+- Packet shape mirrors the TypeScript core: `{"version":1,"message":{"data":{...}},"sequenceId":0}`.

uns_kit-0.0.2/pyproject.toml

@@ -0,0 +1,26 @@
+[tool.poetry]
+name = "uns-kit"
+version = "0.0.2"
+description = "Lightweight Python UNS MQTT client (pub/sub + infra topics)"
+authors = ["Aljoša Vister <aljosa.vister@gmail.com>"]
+license = "MIT"
+readme = "README.md"
+packages = [{ include = "uns_kit", from = "src" }]
+
+[tool.poetry.dependencies]
+python = "^3.10"
+asyncio-mqtt = "^0.16.1"
+click = "^8.1.7"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.3.3"
+pytest-asyncio = "^0.24.0"
+ruff = "^0.6.9"
+mypy = "^1.11.2"
+
+[tool.poetry.scripts]
+uns-kit = "uns_kit.cli:main"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

uns_kit-0.0.2/src/uns_kit/__init__.py

@@ -0,0 +1,13 @@
+from .topic_builder import TopicBuilder
+from .packet import UnsPacket, DataPayload, TablePayload
+from .client import UnsMqttClient
+from .config import UnsConfig
+
+__all__ = [
+    "TopicBuilder",
+    "UnsPacket",
+    "DataPayload",
+    "TablePayload",
+    "UnsMqttClient",
+    "UnsConfig",
+]

uns_kit-0.0.2/src/uns_kit/cli.py

@@ -0,0 +1,146 @@
+from __future__ import annotations
+
+import asyncio
+import json
+from pathlib import Path
+from typing import Optional
+
+import click
+
+from .client import UnsMqttClient
+from .packet import UnsPacket
+from .topic_builder import TopicBuilder
+
+
+def common_options(func):
+    func = click.option("--host", required=True, help="MQTT host (hostname or host:port)")(func)
+    func = click.option("--port", type=int, help="MQTT port override")(func)
+    func = click.option("--username", help="MQTT username")(func)
+    func = click.option("--password", help="MQTT password")(func)
+    func = click.option("--tls/--no-tls", default=False, show_default=True, help="Enable TLS")(func)
+    func = click.option("--client-id", help="MQTT clientId")(func)
+    func = click.option("--package-name", default="uns-kit", show_default=True, help="Package name for infra topics")(func)
+    func = click.option("--package-version", default="0.0.1", show_default=True, help="Package version for infra topics")(func)
+    func = click.option("--process-name", default="uns-process", show_default=True, help="Process name for infra topics")(func)
+    func = click.option("--reconnect-interval", default=1.0, show_default=True, type=float, help="Reconnect backoff start (s)")(func)
+    return func
+
+
+@click.group(help="Lightweight UNS MQTT helper (Python).")
+def cli():
+    pass
+
+
+@cli.command("publish", help="Publish a UNS data packet to a topic.")
+@common_options
+@click.option("--topic", required=True, help="MQTT topic (e.g. raw/data/)")
+@click.option("--value", required=False, help="Value to send (stringified if not JSON).")
+@click.option("--uom", default=None, help="Unit of measure.")
+@click.option("--json", "json_value", default=None, help="JSON string to use as value.")
+@click.option("--qos", type=int, default=0, show_default=True)
+@click.option("--retain/--no-retain", default=False, show_default=True)
+def publish_cmd(**opts):
+    asyncio.run(_run_publish(**opts))
+
+
+async def _run_publish(
+    host: str,
+    port: Optional[int],
+    username: Optional[str],
+    password: Optional[str],
+    tls: bool,
+    client_id: Optional[str],
+    package_name: str,
+    package_version: str,
+    process_name: str,
+    reconnect_interval: float,
+    topic: str,
+    value: Optional[str],
+    uom: Optional[str],
+    json_value: Optional[str],
+    qos: int,
+    retain: bool,
+):
+    tb = TopicBuilder(package_name, package_version, process_name)
+    client = UnsMqttClient(
+        host=host.split(":")[0],
+        port=int(host.split(":")[1]) if ":" in host and port is None else port,
+        username=username,
+        password=password,
+        tls=tls,
+        client_id=client_id,
+        topic_builder=tb,
+        reconnect_interval=reconnect_interval,
+    )
+    await client.connect()
+
+    payload_obj = json.loads(json_value) if json_value is not None else value
+    packet = UnsPacket.data(value=payload_obj, uom=uom)
+    await client.publish_packet(topic, packet, qos=qos, retain=retain)
+    await client.close()
+
+
+@cli.command("subscribe", help="Subscribe to one or more topics (resilient).")
+@common_options
+@click.option("--topic", "topic_filter", required=True, help="Topic filter (e.g. uns-infra/#)")
+def subscribe_cmd(**opts):
+    asyncio.run(_run_subscribe(**opts))
+
+
+async def _run_subscribe(
+    host: str,
+    port: Optional[int],
+    username: Optional[str],
+    password: Optional[str],
+    tls: bool,
+    client_id: Optional[str],
+    package_name: str,
+    package_version: str,
+    process_name: str,
+    reconnect_interval: float,
+    topic_filter: str,
+):
+    tb = TopicBuilder(package_name, package_version, process_name)
+    client = UnsMqttClient(
+        host=host.split(":")[0],
+        port=int(host.split(":")[1]) if ":" in host and port is None else port,
+        username=username,
+        password=password,
+        tls=tls,
+        client_id=client_id,
+        topic_builder=tb,
+        reconnect_interval=reconnect_interval,
+    )
+    await client.connect()
+
+    async for msg in client.resilient_messages(topic_filter):
+        try:
+            print(f"{msg.topic} {msg.payload.decode()}")
+        except Exception:
+            print(f"{msg.topic} <binary {len(msg.payload)} bytes>")
+
+
+@cli.command("write-config", help="Write a minimal config.json scaffold.")
+@click.option("--path", default="config.json", show_default=True)
+def write_config(path: str):
+    data = {
+        "host": "localhost",
+        "port": 1883,
+        "username": "",
+        "password": "",
+        "tls": False,
+        "clientId": "uns-py",
+        "packageName": "uns-kit",
+        "packageVersion": "0.0.1",
+        "processName": "uns-process",
+    }
+    Path(path).write_text(json.dumps(data, indent=2))
+    click.echo(f"Wrote {path}")
+
+
+def main():
+    cli()
+
+
+if __name__ == "__main__":
+    main()

uns_kit-0.0.2/src/uns_kit/client.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+import asyncio
+import contextlib
+from contextlib import asynccontextmanager
+from typing import AsyncIterator, List, Optional
+
+from asyncio_mqtt import Client, MqttError, Message
+
+from .packet import UnsPacket
+from .topic_builder import TopicBuilder
+
+
+class UnsMqttClient:
+    def __init__(
+        self,
+        host: str,
+        *,
+        topic_builder: TopicBuilder,
+        port: Optional[int] = None,
+        username: Optional[str] = None,
+        password: Optional[str] = None,
+        client_id: Optional[str] = None,
+        tls: bool = False,
+        keepalive: int = 60,
+        clean_session: bool = True,
+        reconnect_interval: float = 2.0,
+        max_reconnect_interval: float = 30.0,
+    ):
+        self.host = host
+        self.port = port
+        self.username = username
+        self.password = password
+        self.client_id = client_id
+        self.tls = tls
+        self.keepalive = keepalive
+        self.clean_session = clean_session
+        self.reconnect_interval = reconnect_interval
+        self.max_reconnect_interval = max_reconnect_interval
+        self.topic_builder = topic_builder
+        self._client: Optional[Client] = None
+        self._status_task: Optional[asyncio.Task] = None
+        self._connected = asyncio.Event()
+        self._closing = False
+        self._connect_lock = asyncio.Lock()
+
+    async def _connect_once(self) -> None:
+        will = {
+            "topic": f"{self.topic_builder.process_status_topic}alive",
+            "payload": b"",
+            "qos": 0,
+            "retain": True,
+        }
+        client = Client(
+            hostname=self.host,
+            port=self.port,
+            username=self.username,
+            password=self.password,
+            client_id=self.client_id,
+            keepalive=self.keepalive,
+            clean_session=self.clean_session,
+            tls=self.tls,
+            will=will,
+        )
+        await client.connect()
+        self._client = client
+        self._connected.set()
+
+    async def _ensure_connected(self) -> None:
+        if self._connected.is_set():
+            return
+        async with self._connect_lock:
+            if self._connected.is_set():
+                return
+            backoff = self.reconnect_interval
+            while not self._closing:
+                try:
+                    await self._connect_once()
+                    if not self._status_task or self._status_task.done():
+                        self._status_task = asyncio.create_task(self._publish_status_loop())
+                    return
+                except MqttError:
+                    await asyncio.sleep(backoff)
+                    backoff = min(backoff * 2, self.max_reconnect_interval)
+
+    async def connect(self) -> None:
+        await self._ensure_connected()
+
+    async def close(self) -> None:
+        self._closing = True
+        if self._status_task:
+            self._status_task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await self._status_task
+        if self._client:
+            with contextlib.suppress(Exception):
+                await self._client.disconnect()
+        self._connected.clear()
+
+    async def publish_raw(self, topic: str, payload: str | bytes, *, qos: int = 0, retain: bool = False) -> None:
+        await self._ensure_connected()
+        for attempt in range(2):
+            try:
+                assert self._client
+                await self._client.publish(topic, payload, qos=qos, retain=retain)
+                return
+            except MqttError:
+                self._connected.clear()
+                if attempt == 0:
+                    await self._ensure_connected()
+                else:
+                    raise
+
+    async def publish_packet(self, topic: str, packet: dict, *, qos: int = 0, retain: bool = False) -> None:
+        payload = UnsPacket.to_json(packet)
+        await self.publish_raw(topic, payload, qos=qos, retain=retain)
+
+    @asynccontextmanager
+    async def messages(self, topics: str | List[str]) -> AsyncIterator[AsyncIterator[Message]]:
+        await self._ensure_connected()
+        assert self._client
+        manager = self._client.filtered_messages(topics) if isinstance(topics, str) else self._client.unfiltered_messages()
+        async with manager as messages:
+            if isinstance(topics, str):
+                await self._client.subscribe(topics)
+            else:
+                for t in topics:
+                    await self._client.subscribe(t)
+            yield messages
+
+    async def resilient_messages(self, topics: str | List[str]) -> AsyncIterator[Message]:
+        """
+        Async generator that keeps the subscription alive across disconnects.
+        """
+        while not self._closing:
+            await self._ensure_connected()
+            try:
+                async with self.messages(topics) as msgs:
+                    async for msg in msgs:
+                        yield msg
+            except MqttError:
+                self._connected.clear()
+                await asyncio.sleep(self.reconnect_interval)
+                continue
+
+    async def _publish_status_loop(self) -> None:
+        uptime_topic = f"{self.topic_builder.process_status_topic}uptime"
+        alive_topic = f"{self.topic_builder.process_status_topic}alive"
+        start = asyncio.get_event_loop().time()
+        try:
+            while not self._closing:
+                now = asyncio.get_event_loop().time()
+                uptime_minutes = int((now - start) / 60)
+                await self.publish_raw(alive_topic, b"", qos=0, retain=True)
+                await self.publish_raw(uptime_topic, str(uptime_minutes).encode(), qos=0, retain=True)
+                await asyncio.sleep(10)
+        except asyncio.CancelledError:
+            pass

uns_kit-0.0.2/src/uns_kit/config.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List, Optional
+
+from .topic_builder import TopicBuilder
+
+
+@dataclass
+class UnsConfig:
+    host: str
+    port: Optional[int] = None
+    username: Optional[str] = None
+    password: Optional[str] = None
+    client_id: Optional[str] = None
+    tls: bool = False
+    keepalive: int = 60
+    clean_session: bool = True
+    mqtt_sub_to_topics: Optional[List[str]] = None
+    package_name: str = "uns-kit"
+    package_version: str = "0.0.1"
+    process_name: str = "uns-process"
+
+    @staticmethod
+    def load(path: Path) -> "UnsConfig":
+        data = json.loads(path.read_text())
+        return UnsConfig(**data)
+
+    def topic_builder(self) -> TopicBuilder:
+        return TopicBuilder(self.package_name, self.package_version, self.process_name)

uns_kit-0.0.2/src/uns_kit/packet.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, asdict
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional
+import json
+
+
+def isoformat(dt: datetime) -> str:
+    return dt.astimezone(timezone.utc).isoformat()
+
+
+@dataclass
+class DataPayload:
+    value: Any
+    uom: Optional[str] = None
+    time: Optional[str] = None
+    dataGroup: Optional[str] = None
+    createdAt: Optional[str] = None
+    expiresAt: Optional[str] = None
+
+
+@dataclass
+class TablePayload:
+    table: Any
+    dataGroup: Optional[str] = None
+    createdAt: Optional[str] = None
+    expiresAt: Optional[str] = None
+
+
+class UnsPacket:
+    version: int = 1
+
+    @staticmethod
+    def data(
+        value: Any,
+        uom: Optional[str] = None,
+        time: Optional[datetime] = None,
+        data_group: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        payload = DataPayload(
+          value=value,
+          uom=uom,
+          time=isoformat(time or datetime.utcnow()),
+          dataGroup=data_group,
+        )
+        return {"version": UnsPacket.version, "message": {"data": asdict(payload)}}
+
+    @staticmethod
+    def table(table: Any, data_group: Optional[str] = None) -> Dict[str, Any]:
+        payload = TablePayload(table=table, dataGroup=data_group)
+        return {"version": UnsPacket.version, "message": {"table": asdict(payload)}}
+
+    @staticmethod
+    def to_json(packet: Dict[str, Any]) -> str:
+        return json.dumps(packet, separators=(",", ":"))
+
+    @staticmethod
+    def parse(packet_str: str) -> Optional[Dict[str, Any]]:
+        try:
+            return json.loads(packet_str)
+        except Exception:
+            return None

uns_kit-0.0.2/src/uns_kit/topic_builder.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import re
+
+
+class TopicBuilder:
+    """
+    Mirrors the TypeScript MqttTopicBuilder for infra topics.
+    """
+
+    def __init__(self, package_name: str, package_version: str, process_name: str):
+        self.package_name = self.sanitize_topic_part(package_name)
+        self.package_version = self.sanitize_topic_part(package_version)
+        self.process_name = self.sanitize_topic_part(process_name)
+        self._base = f"uns-infra/{self.package_name}/{self.package_version}/{self.process_name}/"
+        if not re.match(r"^uns-infra/[^/]+/[^/]+/[^/]+/$", self._base):
+            raise ValueError("processStatusTopic must follow 'uns-infra/<package>/<version>/<process>/'")
+
+    @staticmethod
+    def sanitize_topic_part(name: str) -> str:
+        sanitized = re.sub(r"[^a-zA-Z0-9_-]+", "-", name)
+        sanitized = re.sub(r"-{2,}", "-", sanitized)
+        sanitized = sanitized.strip("-")
+        return sanitized or "uns-process"
+
+    @property
+    def process_status_topic(self) -> str:
+        return self._base
+
+    def active_topic(self) -> str:
+        return f"{self._base}active"
+
+    def handover_topic(self) -> str:
+        return f"{self._base}handover"
+
+    @staticmethod
+    def extract_base_topic(full_topic: str) -> str:
+        parts = full_topic.split("/")
+        if len(parts) < 4:
+            raise ValueError("Invalid topic format. Expected 'uns-infra/<package>/<version>/<process>/'.")
+        return "/".join(parts[:4]) + "/"