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

uns_kit/packet.py

@@ -1,13 +1,16 @@
 from __future__ import annotations
 
-from dataclasses import dataclass, asdict
+from dataclasses import dataclass
 from datetime import datetime, timezone
 from typing import Any, Dict, Optional
 import json
 
 
 def isoformat(dt: datetime) -> str:
-    return dt.astimezone(timezone.utc).isoformat()
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    dt = dt.astimezone(timezone.utc)
+    return dt.strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "Z"
 
 
 @dataclass
@@ -16,40 +19,138 @@ class DataPayload:
     uom: Optional[str] = None
     time: Optional[str] = None
     dataGroup: Optional[str] = None
-    createdAt: Optional[str] = None
-    expiresAt: Optional[str] = None
+    intervalStart: Optional[str | int] = None
+    intervalEnd: Optional[str | int] = None
+    windowStart: Optional[str | int] = None
+    windowEnd: Optional[str | int] = None
+    eventId: Optional[str] = None
+    deleted: Optional[bool] = None
+    deletedAt: Optional[str | int] = None
+    lastSeen: Optional[str | int] = None
+    foreignEventKey: Optional[str] = None
 
 
 @dataclass
 class TablePayload:
-    table: Any
+    time: str
+    columns: Any
     dataGroup: Optional[str] = None
-    createdAt: Optional[str] = None
-    expiresAt: Optional[str] = None
+    intervalStart: Optional[str | int] = None
+    intervalEnd: Optional[str | int] = None
+    windowStart: Optional[str | int] = None
+    windowEnd: Optional[str | int] = None
+    eventId: Optional[str] = None
+    deleted: Optional[bool] = None
+    deletedAt: Optional[str | int] = None
+    lastSeen: Optional[str | int] = None
+
+
+def _value_type(value: Any) -> str:
+    if value is None:
+        return "null"
+    if isinstance(value, bool):
+        return "boolean"
+    if isinstance(value, (int, float)):
+        return "number"
+    if isinstance(value, str):
+        return "string"
+    return "object"
+
+
+def _normalize_payload_fields(payload: Dict[str, Any], extra: Dict[str, Any]) -> None:
+    mapping = {
+        "data_group": "dataGroup",
+        "interval_start": "intervalStart",
+        "interval_end": "intervalEnd",
+        "window_start": "windowStart",
+        "window_end": "windowEnd",
+        "event_id": "eventId",
+        "deleted_at": "deletedAt",
+        "last_seen": "lastSeen",
+        "foreign_event_key": "foreignEventKey",
+    }
+    for key, value in extra.items():
+        target = mapping.get(key, key)
+        payload[target] = value
+
+
+def _prune_none(payload: Dict[str, Any]) -> None:
+    for key in list(payload.keys()):
+        if payload[key] is None:
+            payload.pop(key, None)
 
 
 class UnsPacket:
-    version: int = 1
+    version: str = "1.3.0"
 
     @staticmethod
     def data(
         value: Any,
         uom: Optional[str] = None,
-        time: Optional[datetime] = None,
+        time: Optional[datetime | str] = None,
         data_group: Optional[str] = None,
+        created_at: Optional[datetime | str] = None,
+        expires_at: Optional[datetime | str] = None,
+        **extra: Any,
     ) -> Dict[str, Any]:
-        payload = DataPayload(
-          value=value,
-          uom=uom,
-          time=isoformat(time or datetime.utcnow()),
-          dataGroup=data_group,
+        resolved_time = (
+            time if isinstance(time, str) else isoformat(time or datetime.now(timezone.utc))
         )
-        return {"version": UnsPacket.version, "message": {"data": asdict(payload)}}
+        payload = {
+            "value": value,
+            "uom": uom,
+            "time": resolved_time,
+            "dataGroup": data_group,
+            "valueType": _value_type(value),
+        }
+        _normalize_payload_fields(payload, extra)
+        _prune_none(payload)
+        message: Dict[str, Any] = {"data": payload}
+        if created_at is not None:
+            message["createdAt"] = created_at if isinstance(created_at, str) else isoformat(created_at)
+        if expires_at is not None:
+            message["expiresAt"] = expires_at if isinstance(expires_at, str) else isoformat(expires_at)
+        return {"version": UnsPacket.version, "message": message}
 
     @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)}}
+    def table(
+        table: Optional[Dict[str, Any]] = None,
+        *,
+        columns: Optional[Any] = None,
+        time: Optional[datetime | str] = None,
+        data_group: Optional[str] = None,
+        created_at: Optional[datetime | str] = None,
+        expires_at: Optional[datetime | str] = None,
+        **extra: Any,
+    ) -> Dict[str, Any]:
+        if table is None:
+            if columns is None:
+                raise ValueError("table() requires either table dict or columns list")
+            resolved_time = (
+                time if isinstance(time, str) else isoformat(time or datetime.now(timezone.utc))
+            )
+            payload = {
+                "time": resolved_time,
+                "columns": columns,
+                "dataGroup": data_group,
+            }
+        else:
+            payload = dict(table)
+            if "time" not in payload:
+                payload["time"] = (
+                    time if isinstance(time, str) else isoformat(time or datetime.now(timezone.utc))
+                )
+            if data_group is not None and "dataGroup" not in payload:
+                payload["dataGroup"] = data_group
+
+        _normalize_payload_fields(payload, extra)
+        _prune_none(payload)
+        message: Dict[str, Any] = {"table": payload}
+        if created_at is not None:
+            message["createdAt"] = created_at if isinstance(created_at, str) else isoformat(created_at)
+        if expires_at is not None:
+            message["expiresAt"] = expires_at if isinstance(expires_at, str) else isoformat(expires_at)
+        return {"version": UnsPacket.version, "message": message}
 
     @staticmethod
     def to_json(packet: Dict[str, Any]) -> str:
@@ -61,3 +162,14 @@ class UnsPacket:
             return json.loads(packet_str)
         except Exception:
             return None
+
+    @staticmethod
+    def from_message(message: Dict[str, Any]) -> Dict[str, Any]:
+        msg = dict(message)
+        data = msg.get("data")
+        if isinstance(data, dict):
+            if "valueType" not in data and "value" in data:
+                data = dict(data)
+                data["valueType"] = _value_type(data.get("value"))
+                msg["data"] = data
+        return {"version": UnsPacket.version, "message": msg}

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

@@ -0,0 +1,39 @@
+# UNS Python App Template
+
+## Setup
+```bash
+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

@@ -0,0 +1,24 @@
+[tool.poetry]
+name = "uns-py-app"
+version = "0.1.0"
+description = "Example UNS Python application"
+authors = ["Your Name <you@example.com>"]
+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())