rtls-sdk 0.6.3__tar.gz → 0.7.0__tar.gz

{rtls_sdk-0.6.3 → rtls_sdk-0.7.0}/CHANGELOG.md

@@ -5,7 +5,20 @@ All notable changes to the RTLS SDK will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
-## [Unreleased]
+## [0.7.0] — 2026-10-20
+
+### Added
+
+- `zones.download_request(tag_uids, *, action="UPDATE")` — trigger (or
+  verify) the SZM→tag zone-download wire push (`POST /api/zone_download_request`).
+- `zones.download_status(tag_uid=None)` — per-tag zone-download sync status
+  (`GET /api/zone_download_status[/:uid]`), returned as a list of the new
+  `ZoneDownloadStatus` model (`download_status` one of `OUTDATED`,
+  `IN_PROCESS`, `UPDATED`, `OOSYNC`; `tag_uid` is the SDK-canonical name
+  for the server's `trackable_uid`, mapped on read per the `0.6.2`
+  trackable→tag convention). Both endpoints already existed server-side
+  (`rtls-frontend`'s `zone_manager` addon) — the SDK simply had no client
+  for them.
 
 ## [0.6.3] — 2026-09-10
 

{rtls_sdk-0.6.3 → rtls_sdk-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: rtls-sdk
-Version: 0.6.3
+Version: 0.7.0
 Summary: Python SDK for the RTLS REST API
 Project-URL: Documentation, https://rtls-sdk.pages.dev
 Author: RTLS SDK Maintainers
@@ -26,7 +26,7 @@ Requires-Dist: pytest-httpserver>=1.0; extra == 'dev'
 Requires-Dist: pytest>=7.4; extra == 'dev'
 Requires-Dist: python-dotenv>=1.0; extra == 'dev'
 Requires-Dist: respx>=0.20; extra == 'dev'
-Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: ruff<0.13,>=0.12.7; extra == 'dev'
 Provides-Extra: docs
 Requires-Dist: mkdocs-material>=9; extra == 'docs'
 Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'

{rtls_sdk-0.6.3 → rtls_sdk-0.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "rtls-sdk"
-version = "0.6.3"
+version = "0.7.0"
 description = "Python SDK for the RTLS REST API"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -33,7 +33,12 @@ dev = [
     "pytest-cov>=4.1",
     "respx>=0.20",
     "pytest-httpserver>=1.0",
-    "ruff>=0.4",
+    # Pinned deliberately, not floored. CI installs `[dev]` fresh on every run, so an
+    # unpinned linter makes the gate a function of the release calendar: ruff 0.16
+    # turned on rules this code has never satisfied and changed the formatter, and
+    # CI went red on a commit nobody had touched since July. Bump this on purpose,
+    # in its own PR, with the resulting fixes.
+    "ruff>=0.12.7,<0.13",
     "mypy>=1.8",
     "python-dotenv>=1.0",
 ]
@@ -67,6 +72,11 @@ extend-select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
 ignore = [
     "B008",   # function call in default argument — pydantic uses this idiom
     "SIM108", # ternary not always more readable
+    # `isinstance(x, (A, B))` over `isinstance(x, A | B)`. Ruff removed this rule
+    # after 0.12 — the tuple form is faster at runtime and reads no worse — so this
+    # ignore matches what the rule's own authors concluded, and keeps the pinned
+    # gate green without rewriting three call sites to be slower.
+    "UP038",
 ]
 
 [tool.ruff.lint.per-file-ignores]

{rtls_sdk-0.6.3 → rtls_sdk-0.7.0}/src/rtls_sdk/__init__.py

@@ -75,6 +75,8 @@ from .models import (
     Version,
     WsHost,
     Zone,
+    ZoneDownloadState,
+    ZoneDownloadStatus,
     ZoneEvent,
 )
 from .models.ws import (
@@ -173,5 +175,7 @@ __all__ = [  # noqa: RUF022 — grouped logically, not alphabetically
     "Version",
     "WsHost",
     "Zone",
+    "ZoneDownloadState",
+    "ZoneDownloadStatus",
     "ZoneEvent",
 ]

{rtls_sdk-0.6.3 → rtls_sdk-0.7.0}/src/rtls_sdk/models/__init__.py

@@ -31,6 +31,7 @@ from .tag_association import TagAssociation
 from .tag_template import TagTemplate
 from .user import Role, User, UserFlags
 from .zone import Zone
+from .zone_download_status import ZoneDownloadState, ZoneDownloadStatus
 from .zone_event import ZoneEvent
 
 __all__ = [
@@ -81,5 +82,7 @@ __all__ = [
     "Version",
     "WsHost",
     "Zone",
+    "ZoneDownloadState",
+    "ZoneDownloadStatus",
     "ZoneEvent",
 ]

rtls_sdk-0.7.0/src/rtls_sdk/models/zone_download_status.py

@@ -0,0 +1,51 @@
+"""Zone-download sync-status model.
+
+Tracks whether a tag's zone-download push (SZM → tag LZM) has synced.
+The server's own status vocabulary (``server/addons/zone_manager/constants.js``)
+is kept verbatim rather than translated to an SDK-canonical spelling,
+since callers compare against it directly (e.g. polling until
+``"UPDATED"``).
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Literal
+
+from pydantic import model_validator
+
+from ._base import _BaseModel
+
+ZoneDownloadState = Literal["OUTDATED", "IN_PROCESS", "UPDATED", "OOSYNC"]
+
+
+class ZoneDownloadStatus(_BaseModel):
+    """A tag's current zone-download sync status.
+
+    ``tag_uid`` is the SDK-canonical name for the server's
+    ``trackable_uid`` wire field (mirroring :class:`Alarm` / :class:`Zone`);
+    the raw wire payload remains available via ``.raw``. ``download_status``
+    is one of the server's literal ``ZONE_DOWNLOAD_STATUS`` values.
+    ``reason`` and ``sync_requested`` are present on some rows and absent
+    on others (server returns whatever the underlying row has); both
+    default to ``None``.
+    """
+
+    tag_uid: str
+    download_status: ZoneDownloadState
+    ts: datetime | None = None
+    reason: str | None = None
+    sync_requested: bool | None = None
+
+    @model_validator(mode="before")
+    @classmethod
+    def _map_wire_aliases(cls, data: Any) -> Any:
+        if not isinstance(data, dict):
+            return data
+        out = dict(data)
+        if out.get("tag_uid") is None and out.get("trackable_uid") is not None:
+            out["tag_uid"] = out["trackable_uid"]
+        return out
+
+
+__all__ = ["ZoneDownloadState", "ZoneDownloadStatus"]

{rtls_sdk-0.6.3 → rtls_sdk-0.7.0}/src/rtls_sdk/resources/zones.py

@@ -10,7 +10,7 @@ from .._time import to_epoch_ms
 from ..compounds import zones as _compound
 from ..compounds.tags import UNSET, _Unset
 from ..errors import NotFound
-from ..models import Zone
+from ..models import Zone, ZoneDownloadStatus
 from ._base import ResourceAPI
 
 
@@ -209,6 +209,52 @@ class ZonesAPI(ResourceAPI):
         """
         _compound.delete_zone(self._client, uid)
 
+    def download_request(self, tag_uids: list[str], *, action: str = "UPDATE") -> str:
+        """Trigger (or verify) a zone-download push to one or more tags.
+
+        Wraps ``POST /api/zone_download_request`` — the SZM→tag LZM
+        wire push, same action the SiteWise "start zone download"
+        button performs. ``action`` is ``"UPDATE"`` (the default, push
+        the current zone set) or ``"VERIFY"`` (ask the tag to report
+        back without pushing). The server contract is batch-shaped
+        (one or more tags per request) — pass a single-element list
+        for one tag.
+
+        Returns the server's own human-readable ``message`` string
+        (which entities were processed / rejected); poll
+        :meth:`download_status` for the actual per-tag sync outcome
+        rather than parsing this message.
+        """
+        body = {
+            "zone_download_request": {
+                "action": action,
+                "trackables": [{"trackable_uid": uid} for uid in tag_uids],
+            }
+        }
+        response = self._post("/api/zone_download_request", json=body)
+        payload = response.json()
+        return payload.get("message", "") if isinstance(payload, dict) else ""
+
+    def download_status(self, tag_uid: str | None = None) -> list[ZoneDownloadStatus]:
+        """Return per-tag zone-download sync status.
+
+        Wraps ``GET /api/zone_download_status`` (all tags) or
+        ``GET /api/zone_download_status/{uid}`` (one tag, still
+        returned as a list — the server's own query is filtered, not
+        reshaped). Poll this after :meth:`download_request` until the
+        relevant row's ``download_status`` reads ``"UPDATED"`` (or
+        times out) — the request call itself does not block on the
+        wire push completing.
+        """
+        path = (
+            "/api/zone_download_status"
+            if tag_uid is None
+            else f"/api/zone_download_status/{tag_uid}"
+        )
+        response = self._get(path)
+        items = unwrap_resource(response.json(), "zone_download_status")
+        return [ZoneDownloadStatus.from_wire(item) for item in items]
+
     def list(self) -> list[Zone]:
         """Return zones and buffers for the current project.