rtls-sdk 0.2.0__py3-none-any.whl

rtls_sdk/compounds/reports.py

@@ -0,0 +1,339 @@
+"""Compound report workflows — heatmap polling, PWS aggregation, CSV chunking.
+
+Step-name conventions (stable):
+
+- ``heatmap``: ``create_report``, ``poll``, ``build_image_url``. The
+  polling loop doesn't emit individual step names per poll; the whole
+  loop is one logical step.
+
+The CSV downloaders don't have step names (single linear sequence;
+failures surface as the underlying ``RtlsError``).
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+import urllib.parse
+from datetime import datetime
+from typing import IO, TYPE_CHECKING, Any
+
+from .._query import pack_array_param
+from .._time import to_epoch_ms
+from ..errors import ReportFailed, ReportTimeout
+from ..models import CsvBlob, Heatmap, PwsEvent, PwsReport
+
+if TYPE_CHECKING:
+    from .._client import RtlsClient
+
+
+logger = logging.getLogger("rtls_sdk.compounds.reports")
+
+
+# ---- heatmap ------------------------------------------------------
+
+
+def generate_heatmap(
+    client: RtlsClient,
+    *,
+    start: datetime,
+    end: datetime,
+    tag_uids: list[str],
+    names: list[str] | None = None,
+    poll_interval: float = 2.0,
+    timeout: float | None = None,
+) -> Heatmap:
+    """Create a heatmap report and poll until it completes.
+
+    Uses the live ``/api/v2/obsolete/report`` paths (RESEARCH
+    Discrepancy #5 — the documented ``/api/reports`` path isn't what
+    the frontend uses).
+
+    - Default ``timeout=None`` is **unbounded** (confirmed by maintainer,
+      DESIGN §9 R3). Pass a finite value to bound the wait.
+    - ``poll_interval`` defaults to 2.0s, matching the JS reference
+      client.
+    - ``ReportTimeout.report_uid`` exposes the in-flight uid so callers
+      can resume polling later via :meth:`ReportsAPI.get`.
+    """
+    body: dict[str, Any] = {
+        "type": "heatmap_report",
+        "start": to_epoch_ms(start, arg_name="start"),
+        "end": to_epoch_ms(end, arg_name="end"),
+        "uids": list(tag_uids),
+    }
+    if names is not None:
+        body["names"] = list(names)
+
+    response = client._request("POST", "/api/v2/obsolete/report", json=body)
+    payload = response.json()
+    uid = _extract_report_uid(payload)
+    if uid is None:
+        raise ReportFailed(
+            "heatmap: server response did not include a report uid",
+            response_body=payload,
+        )
+
+    deadline = time.monotonic() + timeout if timeout is not None else None
+    while True:
+        poll_response = client._request("GET", f"/api/v2/obsolete/report/{uid}")
+        poll_payload = poll_response.json()
+
+        if isinstance(poll_payload, dict):
+            error_field = poll_payload.get("error")
+            if isinstance(error_field, str) and error_field:
+                raise ReportFailed(
+                    f"heatmap: server reported error: {error_field}",
+                    response_body=poll_payload,
+                )
+            output = poll_payload.get("output")
+            if output is not None:
+                # Completed — build the image URL.
+                return _build_heatmap_model(client, uid, poll_payload)
+
+        if deadline is not None and time.monotonic() >= deadline:
+            raise ReportTimeout(
+                f"heatmap: timed out after {timeout}s — server still working",
+                report_uid=uid,
+            )
+        # Suppress noisy per-poll logging — the loop can run for minutes.
+        time.sleep(poll_interval)
+
+
+def _extract_report_uid(payload: Any) -> str | None:
+    """Pick out the report uid from a heatmap create/poll response."""
+    if isinstance(payload, dict):
+        if isinstance(payload.get("uid"), str):
+            return str(payload["uid"])
+        data = payload.get("data")
+        if isinstance(data, dict) and isinstance(data.get("uid"), str):
+            return str(data["uid"])
+        report = payload.get("report")
+        if isinstance(report, dict) and isinstance(report.get("uid"), str):
+            return str(report["uid"])
+    return None
+
+
+def _build_heatmap_model(client: RtlsClient, uid: str, payload: dict[str, Any]) -> Heatmap:
+    """Construct the user-facing :class:`Heatmap` from the poll payload."""
+    base = str(client._http.base_url).rstrip("/")
+    # The output may be a dict (e.g. {url, search}) or a string.
+    output = payload.get("output")
+    output_metadata: dict[str, Any] = {}
+    search = ""
+    if isinstance(output, dict):
+        output_metadata = dict(output)
+        raw_search = output.get("search") or output.get("query")
+        if isinstance(raw_search, str):
+            search = raw_search if raw_search.startswith("?") else f"?{raw_search}"
+        explicit_url = output.get("url")
+        if isinstance(explicit_url, str) and explicit_url:
+            image_url = explicit_url
+        else:
+            image_url = f"{base}/api/v2/heatmap/{uid}{search}"
+    elif isinstance(output, str):
+        image_url = output
+    else:
+        image_url = f"{base}/api/v2/heatmap/{uid}"
+
+    return Heatmap.from_wire(
+        {
+            "uid": uid,
+            "image_url": image_url,
+            "name": payload.get("name"),
+            "input": payload.get("input"),
+            "output_metadata": output_metadata,
+        }
+    )
+
+
+# ---- pws aggregate ------------------------------------------------
+
+
+def generate_pws_report(
+    client: RtlsClient,
+    *,
+    trackable_uid: str | list[str],
+    start: datetime,
+    end: datetime,
+    timezone: str | None = None,
+) -> PwsReport:
+    """Aggregate all PWS-event pages into a :class:`PwsReport`.
+
+    Holds the entire result set in memory. For large windows prefer
+    :meth:`EventsAPI.iter_pws` (lazy).
+    """
+    paginator = client.events._build_pws_paginator(trackable_uid, start, end, 1000)
+    events: list[PwsEvent] = []
+    total: int | None = None
+    for page in paginator.pages():
+        events.extend(page.items)
+        if page.total_count is not None:
+            total = page.total_count
+    return PwsReport(events=events, total_count=total, timezone=timezone)
+
+
+# ---- CSV downloads ------------------------------------------------
+
+
+_NEXT_PAGE_HEADER = "content-next-page"
+_FILENAME_HEADER = "response-filename"
+
+
+def download_zone_activity_csv(
+    client: RtlsClient,
+    *,
+    start: datetime,
+    end: datetime,
+    area_uids: list[str],
+    stream_to: IO[bytes] | None = None,
+    dedup_headers: bool = True,
+) -> CsvBlob | None:
+    """Download Zone-Activity CSV, following ``content-next-page`` chunks.
+
+    Each chunk after the first carries a duplicate header row by default
+    (the server treats each chunk as a self-contained CSV). The SDK
+    strips the duplicate so the concatenated bytes parse as one coherent
+    CSV. Pass ``dedup_headers=False`` to preserve raw chunks.
+
+    ``stream_to`` (file-like opened in binary mode) receives bytes as
+    they arrive; in that case the return value is ``None``. With
+    ``stream_to=None`` (default) the SDK accumulates in memory and
+    returns a :class:`CsvBlob`.
+    """
+    params: list[tuple[str, str]] = [
+        ("from", str(to_epoch_ms(start, arg_name="start"))),
+        ("to", str(to_epoch_ms(end, arg_name="end"))),
+        ("type", "information"),
+        ("format", "csv"),
+    ]
+    params.extend(pack_array_param("area_uid", area_uids))
+
+    return _download_csv_chunked(
+        client,
+        path="/api/v2/data/zone_events",
+        params=params,
+        stream_to=stream_to,
+        dedup_headers=dedup_headers,
+    )
+
+
+def download_alarms_csv(
+    client: RtlsClient,
+    *,
+    start: datetime,
+    end: datetime,
+    site_uid: str,
+    alarm_types: list[str] | None = None,
+    include_banner: bool = True,
+) -> CsvBlob:
+    """Download Alarms CSV; optionally prepend a multi-line header banner.
+
+    The banner mirrors the JS reference client's behaviour
+    (RESEARCH §4 "Download Alarms CSV with header banner"): a few
+    ``#Company / #Project / #From / #To`` lines stamped on top so
+    downstream tooling can identify the report. Pass
+    ``include_banner=False`` to get the bare server CSV.
+    """
+    params: list[tuple[str, str]] = [
+        ("from", str(to_epoch_ms(start, arg_name="start"))),
+        ("to", str(to_epoch_ms(end, arg_name="end"))),
+        ("location_uid", site_uid),
+        ("format", "csv"),
+        ("report", "1"),
+    ]
+    if alarm_types:
+        params.extend(pack_array_param("alarm_type_name", alarm_types))
+
+    # Single-call download — alarms CSV isn't chunked.
+    response = client._request("GET", "/api/v2/alarms", params=params)
+    content = response.content
+    filename = response.headers.get(_FILENAME_HEADER)
+
+    if include_banner:
+        banner_lines = [
+            f"#Site: {site_uid}",
+            f"#From: {start.isoformat()}",
+            f"#To: {end.isoformat()}",
+        ]
+        if alarm_types:
+            banner_lines.append(f"#Alarm-types: {','.join(alarm_types)}")
+        banner = ("\n".join(banner_lines) + "\n").encode("utf-8")
+        content = banner + content
+
+    return CsvBlob(content=content, filename=filename)
+
+
+def _download_csv_chunked(
+    client: RtlsClient,
+    *,
+    path: str,
+    params: list[tuple[str, str]],
+    stream_to: IO[bytes] | None,
+    dedup_headers: bool,
+) -> CsvBlob | None:
+    """Chase ``content-next-page`` chunks until exhausted.
+
+    Returns a :class:`CsvBlob` on in-memory mode (``stream_to=None``)
+    or ``None`` when streaming to a writable.
+    """
+    chunks: list[bytes] = []
+    filename: str | None = None
+    first = True
+    next_path: str | None = path
+    next_params: Any = params
+
+    while next_path is not None:
+        response = client._request("GET", next_path, params=next_params)
+        if filename is None:
+            filename = response.headers.get(_FILENAME_HEADER)
+
+        chunk = response.content
+        if not first and dedup_headers:
+            chunk = _strip_first_line(chunk)
+
+        if stream_to is not None:
+            stream_to.write(chunk)
+        else:
+            chunks.append(chunk)
+
+        first = False
+        next_url = response.headers.get(_NEXT_PAGE_HEADER)
+        if next_url and next_url != "null":
+            # The header carries an absolute or relative URL — feed it
+            # back as the next path. Strip the base_url if it's an
+            # absolute URL matching our own host (httpx will resolve
+            # both forms cleanly).
+            parsed = urllib.parse.urlparse(next_url)
+            if parsed.netloc:
+                # Absolute URL — pass it through unchanged.
+                next_path = next_url
+            else:
+                next_path = next_url
+            next_params = None  # URL already includes query string
+        else:
+            next_path = None
+
+    if stream_to is not None:
+        return None
+    return CsvBlob(content=b"".join(chunks), filename=filename)
+
+
+def _strip_first_line(blob: bytes) -> bytes:
+    """Drop the first newline-terminated line from a CSV chunk.
+
+    Used by :func:`download_zone_activity_csv` to dedup repeated header
+    rows when concatenating chunks. Tolerates ``\\r\\n`` and ``\\n``.
+    """
+    idx = blob.find(b"\n")
+    if idx == -1:
+        return b""
+    return blob[idx + 1 :]
+
+
+__all__ = [
+    "download_alarms_csv",
+    "download_zone_activity_csv",
+    "generate_heatmap",
+    "generate_pws_report",
+]

rtls_sdk/compounds/system.py

@@ -0,0 +1,43 @@
+"""Compound system / health workflows.
+
+Currently ships just :func:`health` — the aggregated
+host/uptime/connections snapshot from DESIGN §4.17. Continue-on-error:
+each sub-call's failure goes into ``SystemHealth.errors`` rather than
+aborting the whole snapshot.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ..errors import RtlsError
+from ..models import SystemHealth
+
+if TYPE_CHECKING:
+    from .._client import RtlsClient
+
+
+def collect_system_health(client: RtlsClient) -> SystemHealth:
+    """Fan out host / uptime / connections; tolerate per-call failure."""
+    result = SystemHealth()
+
+    try:
+        result.host = client.system.host()
+    except RtlsError as exc:
+        result.errors["host"] = exc
+
+    try:
+        result.uptime = client.system.uptime()
+    except RtlsError as exc:
+        result.errors["uptime"] = exc
+
+    try:
+        result.connections = client.system.connections()
+    except RtlsError as exc:
+        result.errors["connections"] = exc
+
+    result.partial = bool(result.errors)
+    return result
+
+
+__all__ = ["collect_system_health"]