ReticulumTelemetryHub 0.1.0__py3-none-any.whl → 0.143.0__py3-none-any.whl

reticulum_telemetry_hub/atak_cot/detail.py

@@ -0,0 +1,235 @@
+"""Detail payload helpers for ATAK Cursor on Target events."""
+
+from __future__ import annotations
+
+import xml.etree.ElementTree as ET
+from dataclasses import dataclass, field
+from typing import Optional, Union
+
+from reticulum_telemetry_hub.atak_cot.base import Contact
+from reticulum_telemetry_hub.atak_cot.base import Group
+from reticulum_telemetry_hub.atak_cot.base import Status
+from reticulum_telemetry_hub.atak_cot.base import Takv
+from reticulum_telemetry_hub.atak_cot.base import Track
+from reticulum_telemetry_hub.atak_cot.base import Uid
+from reticulum_telemetry_hub.atak_cot.chat import Chat
+from reticulum_telemetry_hub.atak_cot.chat import ChatGroup
+from reticulum_telemetry_hub.atak_cot.chat import Link
+from reticulum_telemetry_hub.atak_cot.chat import Marti
+from reticulum_telemetry_hub.atak_cot.chat import ServerDestination
+from reticulum_telemetry_hub.atak_cot.chat import Remarks
+
+
+@dataclass
+class Detail:  # pylint: disable=too-many-instance-attributes
+    """Additional information such as contact, group, and movement."""
+
+    contact: Optional[Contact] = None
+    group: Optional[Group] = None
+    groups: list[Group] = field(default_factory=list)
+    track: Optional[Track] = None
+    takv: Optional[Takv] = None
+    chat: Optional[Chat] = None
+    chat_group: Optional[ChatGroup] = None
+    uid: Optional[Uid] = None
+    links: list[Link] = field(default_factory=list)
+    remarks: Optional[Union[str, Remarks]] = None
+    marti: Optional[Marti] = None
+    status: Optional[Status] = None
+    server_destination: bool = False
+
+    @classmethod
+    # pylint: disable=too-many-locals,too-many-branches
+    def from_xml(cls, elem: ET.Element) -> "Detail":
+        """Create a :class:`Detail` from a ``<detail>`` element."""
+
+        contact_el = elem.find("contact")
+        group_elems = elem.findall("__group")
+        track_el = elem.find("track")
+        takv_el = elem.find("takv")
+        chat_el = elem.find("__chat")
+        chatgrp_el = elem.find("chatgrp")
+        uid_el = elem.find("uid")
+        link_elems = elem.findall("link")
+        remarks_el = elem.find("remarks")
+        marti_el = elem.find("marti")
+        server_destination_el = elem.find("__serverdestination")
+        status_el = elem.find("status")
+        groups = [Group.from_xml(item) for item in group_elems]
+        primary_group = groups[0] if groups else None
+        extra_groups = groups[1:] if len(groups) > 1 else []
+        remarks: Optional[Union[str, Remarks]] = None
+        if remarks_el is not None:
+            if remarks_el.attrib:
+                remarks = Remarks.from_xml(remarks_el)
+            else:
+                remarks = remarks_el.text
+        return cls(
+            contact=(Contact.from_xml(contact_el) if contact_el is not None else None),
+            group=primary_group,
+            groups=extra_groups,
+            track=(Track.from_xml(track_el) if track_el is not None else None),
+            takv=Takv.from_xml(takv_el) if takv_el is not None else None,
+            chat=Chat.from_xml(chat_el) if chat_el is not None else None,
+            chat_group=(
+                ChatGroup.from_xml(chatgrp_el) if chatgrp_el is not None else None
+            ),
+            uid=Uid.from_xml(uid_el) if uid_el is not None else None,
+            links=[Link.from_xml(item) for item in link_elems],
+            remarks=remarks,
+            marti=Marti.from_xml(marti_el) if marti_el is not None else None,
+            status=Status.from_xml(status_el) if status_el is not None else None,
+            server_destination=server_destination_el is not None,
+        )
+
+    def to_element(self) -> Optional[ET.Element]:  # pylint: disable=too-many-branches
+        """Return an XML detail element or ``None`` if empty."""
+
+        if not any(
+            [
+                self.contact,
+                self.group,
+                self.groups,
+                self.track,
+                self.takv,
+                self.chat,
+                self.chat_group,
+                self.uid,
+                self.links,
+                self.remarks,
+                self.marti,
+                self.status,
+                self.server_destination,
+            ]
+        ):
+            return None
+        detail_el = ET.Element("detail")
+        if self.takv:
+            detail_el.append(self.takv.to_element())
+        if self.contact:
+            detail_el.append(self.contact.to_element())
+        if self.group:
+            detail_el.append(self.group.to_element())
+        for group in self.groups:
+            detail_el.append(group.to_element())
+        if self.track:
+            detail_el.append(self.track.to_element())
+        if self.chat:
+            detail_el.append(self.chat.to_element())
+        if self.chat_group:
+            detail_el.append(self.chat_group.to_element())
+        if self.uid:
+            detail_el.append(self.uid.to_element())
+        for link in self.links:
+            detail_el.append(link.to_element())
+        if self.remarks:
+            if isinstance(self.remarks, Remarks):
+                detail_el.append(self.remarks.to_element())
+            else:
+                remarks_el = ET.SubElement(detail_el, "remarks")
+                remarks_el.text = self.remarks
+        if self.marti:
+            marti_element = self.marti.to_element()
+            if marti_element is not None:
+                detail_el.append(marti_element)
+        if self.server_destination:
+            detail_el.append(ServerDestination.to_element())
+        if self.status:
+            detail_el.append(self.status.to_element())
+        return detail_el
+
+    def to_dict(self) -> dict:  # pylint: disable=too-many-branches
+        """Return a dictionary containing populated fields only."""
+
+        data: dict = {}
+        if self.contact:
+            data["contact"] = self.contact.to_dict()
+        if self.group:
+            data["group"] = self.group.to_dict()
+        if self.groups:
+            data["groups"] = [group.to_dict() for group in self.groups]
+        if self.track:
+            data["track"] = self.track.to_dict()
+        if self.takv:
+            data["takv"] = self.takv.to_dict()
+        if self.chat:
+            data["chat"] = self.chat.to_dict()
+        if self.chat_group:
+            data["chat_group"] = self.chat_group.to_dict()
+        if self.uid:
+            data["uid"] = self.uid.to_dict()
+        if self.links:
+            data["links"] = [link.to_dict() for link in self.links]
+        if self.remarks:
+            data["remarks"] = (
+                self.remarks.to_dict()
+                if isinstance(self.remarks, Remarks)
+                else self.remarks
+            )
+        if self.marti:
+            marti_dict = self.marti.to_dict()
+            if marti_dict:
+                data["marti"] = marti_dict
+        if self.status:
+            data["status"] = self.status.to_dict()
+        if self.server_destination:
+            data["server_destination"] = True
+        return data
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "Detail":  # pylint: disable=too-many-locals
+        """Create a :class:`Detail` from a dictionary."""
+
+        contact = None
+        if "contact" in data:
+            contact = Contact.from_dict(data["contact"])
+        group = None
+        if "group" in data:
+            group = Group.from_dict(data["group"])
+        groups_data = data.get("groups", [])
+        groups = [Group.from_dict(item) for item in groups_data]
+        track = None
+        if "track" in data:
+            track = Track.from_dict(data["track"])
+        takv = None
+        if "takv" in data:
+            takv = Takv.from_dict(data["takv"])
+        chat = None
+        if "chat" in data:
+            chat = Chat.from_dict(data["chat"])
+        chat_group = None
+        if "chat_group" in data:
+            chat_group = ChatGroup.from_dict(data["chat_group"])
+        uid = None
+        if "uid" in data:
+            uid = Uid.from_dict(data["uid"])
+        links_data = data.get("links", [])
+        links = [Link.from_dict(item) for item in links_data]
+        remarks_data = data.get("remarks")
+        remarks = None
+        if isinstance(remarks_data, dict):
+            remarks = Remarks.from_dict(remarks_data)
+        elif remarks_data is not None:
+            remarks = str(remarks_data)
+        marti = None
+        if "marti" in data:
+            marti = Marti.from_dict(data.get("marti", {}))
+        status = None
+        if "status" in data:
+            status = Status.from_dict(data.get("status", {}))
+        server_destination = data.get("server_destination", False) is True
+        return cls(
+            contact=contact,
+            group=group,
+            groups=groups,
+            track=track,
+            takv=takv,
+            chat=chat,
+            chat_group=chat_group,
+            uid=uid,
+            links=links,
+            remarks=remarks,
+            marti=marti,
+            status=status,
+            server_destination=server_destination,
+        )

reticulum_telemetry_hub/atak_cot/event.py

@@ -0,0 +1,181 @@
+"""ATAK Cursor on Target event container and serialization helpers."""
+
+from __future__ import annotations
+
+import gzip
+import json
+import xml.etree.ElementTree as ET
+from dataclasses import dataclass
+from typing import Union, cast
+
+import msgpack
+
+from reticulum_telemetry_hub.atak_cot.base import Point
+from reticulum_telemetry_hub.atak_cot.detail import Detail
+
+Packable = Union["Event", dict]
+
+
+def _ensure_packable(obj: Packable) -> dict:
+    """Return a dictionary representation regardless of input type."""
+
+    if isinstance(obj, Event):
+        return obj.to_dict()
+    if isinstance(obj, dict):
+        return obj
+    raise TypeError(f"Unsupported packable type: {type(obj)!r}")
+
+
+def pack_data(obj: Packable) -> bytes:
+    """Return a compressed msgpack representation of ``obj`` or an Event."""
+
+    packed = msgpack.packb(_ensure_packable(obj), use_bin_type=True)
+    packed_bytes = cast(bytes, packed)
+    return gzip.compress(packed_bytes)
+
+
+def unpack_data(data: bytes) -> dict:
+    """Inverse of :func:`pack_data` returning the original object."""
+
+    return msgpack.unpackb(gzip.decompress(data), strict_map_key=False)
+
+
+@dataclass
+class Event:  # pylint: disable=too-many-instance-attributes
+    """Top level CoT event object."""
+
+    version: str
+    uid: str
+    type: str
+    how: str
+    time: str
+    start: str
+    stale: str
+    point: Point
+    access: str | None = None
+    detail: Detail | None = None
+
+    @classmethod
+    def from_xml(cls, xml: Union[str, bytes]) -> "Event":
+        """Parse an entire ``<event>`` XML string."""
+
+        if isinstance(xml, bytes):
+            xml = xml.decode("utf-8")
+        return cls.from_element(ET.fromstring(xml))
+
+    @classmethod
+    def from_element(cls, root: ET.Element) -> "Event":
+        """Construct an event from an ``<event>`` element."""
+
+        point_el = root.find("point")
+        detail_el = root.find("detail")
+        point = (
+            Point.from_xml(point_el) if point_el is not None else Point(0, 0, 0, 0, 0)
+        )
+        detail = Detail.from_xml(detail_el) if detail_el is not None else None
+        return cls(
+            version=root.get("version", ""),
+            uid=root.get("uid", ""),
+            type=root.get("type", ""),
+            how=root.get("how", ""),
+            time=root.get("time", ""),
+            start=root.get("start", ""),
+            stale=root.get("stale", ""),
+            point=point,
+            access=root.get("access"),
+            detail=detail,
+        )
+
+    @classmethod
+    def from_dict(cls, obj: dict) -> "Event":
+        """Construct an :class:`Event` from a dictionary rooted at ``event``."""
+
+        event_obj = obj.get("event") if isinstance(obj.get("event"), dict) else obj
+        point = Point.from_dict(event_obj.get("point", {}))
+        detail_obj = event_obj.get("detail")
+        detail = Detail.from_dict(detail_obj) if detail_obj else None
+        return cls(
+            version=event_obj.get("version", ""),
+            uid=event_obj.get("uid", ""),
+            type=event_obj.get("type", ""),
+            how=event_obj.get("how", ""),
+            time=event_obj.get("time", ""),
+            start=event_obj.get("start", ""),
+            stale=event_obj.get("stale", ""),
+            point=point,
+            access=event_obj.get("access"),
+            detail=detail,
+        )
+
+    @classmethod
+    def from_json(cls, data: str) -> "Event":
+        """Construct an Event from a JSON string."""
+
+        return cls.from_dict(json.loads(data))
+
+    def to_element(self) -> ET.Element:
+        """Return an XML element representing the event."""
+
+        attrib = {
+            "version": self.version,
+            "uid": self.uid,
+            "type": self.type,
+            "how": self.how,
+            "time": self.time,
+            "start": self.start,
+            "stale": self.stale,
+        }
+        if self.access:
+            attrib["access"] = self.access
+        event_el = ET.Element("event", attrib)
+        event_el.append(self.point.to_element())
+        detail_el = self.detail.to_element() if self.detail else None
+        if detail_el is not None:
+            event_el.append(detail_el)
+        return event_el
+
+    def to_xml(self) -> str:
+        """Return a Unicode XML string representing the event."""
+
+        return ET.tostring(self.to_element(), encoding="unicode")
+
+    def to_xml_bytes(self) -> bytes:
+        """Return UTF-8 encoded XML bytes representing the event."""
+
+        return ET.tostring(self.to_element())
+
+    def to_dict(self) -> dict:
+        """Return a dictionary representation of the event with an ``event`` root."""
+
+        event_data = {
+            "version": self.version,
+            "uid": self.uid,
+            "type": self.type,
+            "how": self.how,
+            "time": self.time,
+            "start": self.start,
+            "stale": self.stale,
+            "point": self.point.to_dict(),
+        }
+        if self.access:
+            event_data["access"] = self.access
+        if self.detail:
+            event_data["detail"] = self.detail.to_dict()
+        return {"event": event_data}
+
+    def to_json(self) -> str:
+        """Return a JSON representation of the event."""
+
+        return json.dumps(self.to_dict())
+
+    def to_datapack(self) -> bytes:
+        """Return a compressed datapack representation of the event."""
+
+        return pack_data(self)
+
+    @classmethod
+    def from_datapack(cls, data: bytes) -> "Event":
+        """Recreate an :class:`Event` instance from datapack bytes."""
+
+        unpacked = unpack_data(data)
+        return cls.from_dict(unpacked)