uns-kit 0.0.4__py3-none-any.whl → 0.0.5__py3-none-any.whl

uns_kit/proxy.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+import asyncio
+import json
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional
+
+from .client import UnsMqttClient
+from .packet import isoformat
+
+
+class UnsProxy:
+    """
+    Base proxy that tracks produced topics and periodically publishes the registry.
+    """
+
+    def __init__(self, client: UnsMqttClient, instance_status_topic: str, instance_name: str) -> None:
+        self._client = client
+        self._instance_status_topic = instance_status_topic
+        self._instance_name = instance_name
+        self._produced_topics: Dict[str, Dict[str, Any]] = {}
+        self._publish_task: Optional[asyncio.Task] = None
+        self._running = False
+
+    async def start(self) -> None:
+        if self._running:
+            return
+        self._running = True
+        self._publish_task = asyncio.create_task(self._publish_loop())
+
+    async def stop(self) -> None:
+        self._running = False
+        if self._publish_task and not self._publish_task.done():
+            self._publish_task.cancel()
+            try:
+                await self._publish_task
+            except asyncio.CancelledError:
+                pass
+
+    async def _publish_loop(self) -> None:
+        while self._running:
+            await self._emit_produced_topics()
+            await asyncio.sleep(60)
+
+    async def _emit_produced_topics(self) -> None:
+        if not self._produced_topics:
+            return
+        payload = json.dumps(list(self._produced_topics.values()), separators=(",", ":"))
+        await self._client.publish_raw(
+            f"{self._instance_status_topic}topics",
+            payload,
+            retain=True,
+        )
+
+    async def register_unique_topic(self, topic_object: Dict[str, Any]) -> None:
+        asset = topic_object.get("asset") or ""
+        object_type = topic_object.get("objectType") or ""
+        object_id = topic_object.get("objectId") or ""
+        attribute = topic_object.get("attribute") or ""
+        full_topic = f"{topic_object.get('topic', '')}{asset}/{object_type}/{object_id}/{attribute}"
+        if full_topic not in self._produced_topics:
+            topic_object.setdefault("timestamp", isoformat(datetime.now(timezone.utc)))
+            self._produced_topics[full_topic] = topic_object
+            await self._emit_produced_topics()

uns_kit/proxy_process.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+import asyncio
+import uuid
+from typing import List, Optional
+
+from .client import UnsMqttClient
+from .config import UnsConfig
+from .status_monitor import StatusMonitor
+from .topic_builder import TopicBuilder
+from .uns_mqtt_proxy import UnsMqttProxy
+
+
+class UnsProxyProcess:
+    """
+    Minimal Python equivalent of the TS UnsProxyProcess.
+    Manages process-level status publishing and creates instance proxies.
+    """
+
+    def __init__(self, host: str, config: UnsConfig, process_name: Optional[str] = None, activate_delay_s: float = 10.0) -> None:
+        self.config = config
+        self.process_name = process_name or config.process_name
+        self.process_id = uuid.uuid4().hex
+        self.active = False
+        self._activate_delay_s = activate_delay_s
+        self.topic_builder = TopicBuilder(config.package_name, config.package_version, self.process_name)
+        if config.client_id:
+            process_client_id = f"{config.client_id}-{self.process_id}"
+        else:
+            process_client_id = f"{self.process_name}-{self.process_id}"
+        self._client = UnsMqttClient(
+            host,
+            port=config.port,
+            username=config.username or None,
+            password=config.password or None,
+            tls=config.tls,
+            client_id=process_client_id,
+            keepalive=config.keepalive,
+            clean_session=config.clean_session,
+            topic_builder=self.topic_builder,
+            enable_status=False,
+        )
+        self._status_monitor = StatusMonitor(self._client, self.topic_builder, lambda: self.active)
+        self._proxies: List[UnsMqttProxy] = []
+        self._activate_task: Optional[asyncio.Task] = None
+
+    async def start(self) -> None:
+        await self._client.connect()
+        await self._status_monitor.start()
+        if self._activate_task is None or self._activate_task.done():
+            self._activate_task = asyncio.create_task(self._activate_after_delay())
+
+    async def stop(self) -> None:
+        if self._activate_task and not self._activate_task.done():
+            self._activate_task.cancel()
+            try:
+                await self._activate_task
+            except asyncio.CancelledError:
+                pass
+        await self._status_monitor.stop()
+        await self._client.close()
+
+    def set_active(self, active: bool) -> None:
+        self.active = active
+
+    async def _activate_after_delay(self) -> None:
+        await asyncio.sleep(self._activate_delay_s)
+        if not self.active:
+            self.active = True
+
+    async def create_mqtt_proxy(
+        self,
+        instance_name: str,
+        *,
+        host: Optional[str] = None,
+        port: Optional[int] = None,
+        username: Optional[str] = None,
+        password: Optional[str] = None,
+        tls: Optional[bool] = None,
+        client_id: Optional[str] = None,
+    ) -> UnsMqttProxy:
+        if client_id:
+            resolved_client_id = client_id
+        elif self.config.client_id:
+            resolved_client_id = f"{self.config.client_id}-{instance_name}-{self.process_id}"
+        else:
+            resolved_client_id = f"{self.process_name}-{instance_name}-{self.process_id}"
+        proxy = UnsMqttProxy(
+            host or self.config.host,
+            process_name=self.process_name,
+            instance_name=instance_name,
+            package_name=self.config.package_name,
+            package_version=self.config.package_version,
+            port=port if port is not None else self.config.port,
+            username=username if username is not None else self.config.username,
+            password=password if password is not None else self.config.password,
+            tls=tls if tls is not None else self.config.tls,
+            client_id=resolved_client_id,
+        )
+        await proxy.connect()
+        self._proxies.append(proxy)
+        return proxy

uns_kit/status_monitor.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+import asyncio
+import tracemalloc
+from datetime import datetime, timezone
+from typing import Callable, Optional
+
+from .client import UnsMqttClient
+from .packet import UnsPacket
+from .topic_builder import TopicBuilder
+
+
+class StatusMonitor:
+    """
+    Periodically publishes process-level status topics:
+    - active
+    - heap-used
+    - heap-total
+    """
+
+    def __init__(
+        self,
+        client: UnsMqttClient,
+        topic_builder: TopicBuilder,
+        active_supplier: Callable[[], bool],
+        interval_s: float = 10.0,
+    ) -> None:
+        self._client = client
+        self._topic_builder = topic_builder
+        self._active_supplier = active_supplier
+        self._interval_s = interval_s
+        self._memory_task: Optional[asyncio.Task] = None
+        self._status_task: Optional[asyncio.Task] = None
+        self._running = False
+
+    async def start(self) -> None:
+        if self._running:
+            return
+        if not tracemalloc.is_tracing():
+            tracemalloc.start()
+        self._running = True
+        self._memory_task = asyncio.create_task(self._publish_memory_loop())
+        self._status_task = asyncio.create_task(self._publish_active_loop())
+
+    async def stop(self) -> None:
+        self._running = False
+        for task in (self._memory_task, self._status_task):
+            if task and not task.done():
+                task.cancel()
+                try:
+                    await task
+                except asyncio.CancelledError:
+                    pass
+
+    async def _publish_memory_loop(self) -> None:
+        topic_base = self._topic_builder.process_status_topic
+        heap_used_topic = f"{topic_base}heap-used"
+        heap_total_topic = f"{topic_base}heap-total"
+        while self._running:
+            current, peak = tracemalloc.get_traced_memory()
+            time = datetime.now(timezone.utc)
+            heap_used = round(current / 1048576)
+            heap_total = round(peak / 1048576)
+            heap_used_packet = UnsPacket.data(
+                value=heap_used,
+                uom="MB",
+                time=time,
+            )
+            heap_total_packet = UnsPacket.data(
+                value=heap_total,
+                uom="MB",
+                time=time,
+            )
+            await self._client.publish_raw(heap_used_topic, UnsPacket.to_json(heap_used_packet))
+            await self._client.publish_raw(heap_total_topic, UnsPacket.to_json(heap_total_packet))
+            await asyncio.sleep(self._interval_s)
+
+    async def _publish_active_loop(self) -> None:
+        topic = self._topic_builder.active_topic()
+        while self._running:
+            time = datetime.now(timezone.utc)
+            active_packet = UnsPacket.data(
+                value=1 if self._active_supplier() else 0,
+                uom="bit",
+                time=time,
+            )
+            await self._client.publish_raw(topic, UnsPacket.to_json(active_packet))
+            await asyncio.sleep(self._interval_s)

uns_kit/templates/default/README.md

@@ -6,5 +6,34 @@ poetry install
 poetry run python src/main.py
 ```
 
+## Data example
+```bash
+poetry run python src/data_example.py
+```
+Requires an upstream publisher sending `raw/data` payloads like `count,timestamp,value`.
+
+If you are developing inside the uns-kit monorepo, install the local package first:
+```bash
+poetry add -e ../packages/uns-py
+```
+
+Alternatively, use the script entry point:
+```bash
+poetry run run publish --host localhost:1883 --topic raw/data/ --value 1
+```
+
+## Load test
+```bash
+poetry run python src/load_test.py
+```
+The script will prompt for confirmation, iterations, delay, and topic.
+Tip: if you run multiple clients at once, avoid reusing the same MQTT clientId.
+
+## Status topics
+The default `main.py` uses `UnsProxyProcess` + `UnsMqttProxy`, which publish:
+- process status (`.../active`, `.../heap-used`, `.../heap-total`) every 10s
+- instance status (`.../<instance>/alive`, `.../<instance>/uptime`, `.../<instance>/t-publisher-active`, `.../<instance>/t-subscriber-active`) every 10s
+- transformation stats (`.../<instance>/published-message-*`, `.../<instance>/subscribed-message-*`) every 60s
+
 ## Config
 Edit `config.json` with your MQTT host/auth.

uns_kit/templates/default/pyproject.toml

@@ -8,10 +8,17 @@ package-mode = false
 [tool.poetry.dependencies]
 python = "^3.10"
 uns-kit = "*"
+# Pin MQTT libs to versions compatible with asyncio-mqtt 0.16.x
+paho-mqtt = "<2"
+asyncio-mqtt = "0.16.2"
 
 [tool.poetry.group.dev.dependencies]
 pytest = "^8.3.3"
 
+[tool.poetry.scripts]
+dev = "uns_kit.cli:main"
+run = "uns_kit.cli:main"
+
 [build-system]
 requires = ["poetry-core"]
 build-backend = "poetry.core.masonry.api"

uns_kit/templates/default/src/data_example.py

@@ -0,0 +1,110 @@
+import asyncio
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+from uns_kit import UnsConfig, UnsMqttClient, UnsProxyProcess
+from uns_kit.packet import isoformat
+
+
+async def main() -> None:
+    cfg = UnsConfig.load(Path("config.json"))
+    process = UnsProxyProcess(cfg.host, cfg)
+    await process.start()
+    print(f"[data-example] process client connected to {cfg.host}:{cfg.port or 1883}")
+
+    out = await process.create_mqtt_proxy("py-output")
+    out.client.publisher_active = True
+    print(f"[data-example] output proxy connected to {cfg.host}:{cfg.port or 1883}")
+
+    inp = UnsMqttClient(
+        cfg.host,
+        port=cfg.port,
+        username=cfg.username or None,
+        password=cfg.password or None,
+        tls=cfg.tls,
+        client_id=f"{cfg.process_name}-data-example-in",
+        topic_builder=cfg.topic_builder(),
+        instance_name="py-input",
+        subscriber_active=True,
+    )
+    await inp.connect()
+    print(f"[data-example] input client connected to {cfg.host}:{cfg.port or 1883}, subscribing to raw/#")
+
+    topic = "enterprise/site/area/line/"
+    asset = "asset"
+    asset_description = "Sample asset"
+    object_type = "energy-resource"
+    object_id = "main"
+    data_group = "sensor"
+
+    try:
+        async with inp.messages("raw/#") as messages:
+            await out.client.publish_raw("raw/data", "", retain=True)
+            print("[data-example] cleared retained raw/data; subscribed to 1 topic (raw/#); waiting for incoming raw/data...")
+
+            async for msg in messages:
+                payload = msg.payload.decode(errors="replace") if msg.payload else ""
+                if str(msg.topic) != "raw/data":
+                    continue
+
+                parts = payload.split(",")
+                if len(parts) < 3:
+                    print(f"[data-example] skip malformed raw/data: {payload}")
+                    continue
+                try:
+                    number_value = float(parts[0])
+                    event_time_ms = int(parts[1])
+                    sensor_value = float(parts[2])
+                except ValueError:
+                    print(f"[data-example] parse error, skip: {payload}")
+                    continue
+
+                event_time = datetime.fromtimestamp(event_time_ms / 1000, tz=timezone.utc)
+                interval_start = isoformat(event_time - timedelta(seconds=1))
+                interval_end = isoformat(event_time)
+                time = isoformat(event_time)
+
+                await out.publish_mqtt_message(
+                    {
+                        "topic": topic,
+                        "asset": asset,
+                        "assetDescription": asset_description,
+                        "objectType": object_type,
+                        "objectId": object_id,
+                        "attributes": [
+                            {
+                                "attribute": "current",
+                                "description": "Simulated current sensor value",
+                                "data": {
+                                    "dataGroup": data_group,
+                                    "time": time,
+                                    "intervalStart": interval_start,
+                                    "intervalEnd": interval_end,
+                                    "value": number_value,
+                                    "uom": "A",
+                                },
+                            },
+                            {
+                                "attribute": "voltage",
+                                "description": "Simulated voltage sensor value",
+                                "data": {
+                                    "dataGroup": data_group,
+                                    "time": time,
+                                    "intervalStart": interval_start,
+                                    "intervalEnd": interval_end,
+                                    "value": sensor_value,
+                                    "uom": "V",
+                                },
+                            },
+                        ],
+                    }
+                )
+                print(f"[data-example] published transform at {time}")
+    finally:
+        await inp.close()
+        await out.close()
+        await process.stop()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

uns_kit/templates/default/src/load_test.py

@@ -0,0 +1,103 @@
+import asyncio
+import math
+from datetime import datetime
+from pathlib import Path
+
+from uns_kit import UnsConfig, UnsMqttClient, TopicBuilder
+
+
+def load_config() -> UnsConfig:
+    cfg_path = Path("config.json")
+    if cfg_path.exists():
+        return UnsConfig.load(cfg_path)
+    return UnsConfig(host="localhost")
+
+
+def simulate_sensor_value(step: int) -> float:
+    base_value = 42.0
+    fast_cycle = math.sin(step / 5.0) * 3.0
+    slow_cycle = math.sin(step / 25.0) * 6.0
+    ripple = math.sin(step / 2.0 + math.pi / 4.0) * 0.5
+    value = base_value + fast_cycle + slow_cycle + ripple
+    return round(value, 2)
+
+
+def prompt_bool(prompt: str, default_yes: bool = True) -> bool:
+    suffix = " (Y/n) " if default_yes else " (y/N) "
+    answer = input(prompt + suffix).strip().lower()
+    if not answer:
+        return default_yes
+    return answer in ("y", "yes")
+
+
+def prompt_int(prompt: str, default: int, suffix: str = "") -> int:
+    answer = input(f"{prompt} (default {default}{suffix}) ").strip()
+    try:
+        return int(answer) if answer else default
+    except ValueError:
+        return default
+
+
+def prompt_topic(prompt: str, default: str) -> str:
+    answer = input(f"{prompt} (default {default}) ").strip()
+    return answer or default
+
+
+def log_info(message: str) -> None:
+    timestamp = datetime.now().isoformat(timespec="seconds")
+    print(f"{timestamp} [INFO] {message}")
+
+
+async def main() -> None:
+    cfg = load_config()
+    host = f"{cfg.host}:{cfg.port}" if cfg.port else cfg.host
+
+    if not prompt_bool(f"Would you like to continue with load-test on {host}?"):
+        print("Load test aborted.")
+        return
+
+    count = prompt_int("How many iterations should be run?", 100, "")
+    delay_ms = prompt_int("What should be the delay between intervals in milliseconds?", 0, " ms")
+    topic = prompt_topic("Topic to publish to", "raw/data")
+    retain = prompt_bool("Retain each published message so late subscribers see the last value?", True)
+    delay_s = delay_ms / 1000.0
+
+    log_info(f"Starting load test with {count} messages and {delay_ms} ms delay...")
+
+    # Use a dedicated identity for load testing to avoid clashing with app processes.
+    tb = TopicBuilder(package_name="uns-loadtest", package_version="0.0.0", process_name="load-tester")
+    client = UnsMqttClient(
+        cfg.host,
+        port=cfg.port,
+        username=cfg.username or None,
+        password=cfg.password or None,
+        tls=cfg.tls,
+        client_id="uns-loadtest-client",
+        topic_builder=tb,
+        instance_name="py-load-test",
+        reconnect_interval=1,
+    )
+    await client.connect()
+
+    start = asyncio.get_event_loop().time()
+    for i in range(count):
+        now = asyncio.get_event_loop().time()
+        sensor_value = simulate_sensor_value(i)
+        raw_payload = f"{i},{int(now * 1000)},{sensor_value}"
+        await client.publish_raw(topic, raw_payload, retain=retain)
+        if delay_s:
+            await asyncio.sleep(delay_s)
+
+    log_info("Sleeping for 50ms.")
+    await asyncio.sleep(0.05)
+    end = asyncio.get_event_loop().time()
+    duration = end - start
+    rate = count / duration if duration > 0 else 0
+    log_info(f"Load test completed in {duration:.2f} seconds.")
+    log_info(f"Message rate: {rate:.2f} msg/s.")
+
+    await client.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

uns_kit/topic_builder.py

@@ -33,6 +33,16 @@ class TopicBuilder:
     def handover_topic(self) -> str:
         return f"{self._base}handover"
 
+    def wildcard_active_topic(self) -> str:
+        parts = self._base.strip("/").split("/")
+        if len(parts) < 2:
+            raise ValueError("processStatusTopic must follow 'uns-infra/<package>/<version>/<process>/'")
+        return "/".join(parts[:2]) + "/+/+/active"
+
+    def instance_status_topic(self, instance_name: str) -> str:
+        sanitized = self.sanitize_topic_part(instance_name)
+        return f"{self._base}{sanitized}/"
+
     @staticmethod
     def extract_base_topic(full_topic: str) -> str:
         parts = full_topic.split("/")