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

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

@@ -5,7 +5,46 @@ 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
+
+### Fixed
+
+- `tags.last_position()` now parses the body the server actually sends.
+  `GET /trackable_objects/position_from_state/{uid}` nests the coordinates
+  under `position` and spells the area `sublocation_uid`; `Position` knew
+  only the embedded (`sl_uid`/`dev_id`/`mac`) and standalone
+  (`area_uid`/`trackable_uid`/`mac_address`) forms, so it produced a
+  `Position` with `x`/`y`/`z` all `None` — and, because models allow extra
+  keys, did so silently. Callers polling "has a fix been computed yet?" read
+  that as "no position" while the server was serving one. `Position` now
+  lifts the nested `position` object and maps `sublocation_uid` → `area_uid`
+  (explicit top-level values still win).
+- `tags.last_position()` returns `None` instead of an all-`None` `Position`
+  when the body carries no coordinates — including `{}`, which the route
+  returns when its state worker is unreachable.
+
+### Notes
+
+- `position_from_state` sends **no** timestamp, MAC or tag identity, so
+  `pos.ts` / `pos.mac_address` / `pos.tag_uid` are always `None` on a fix
+  from this call. It cannot answer "has the fix advanced?"; read the tag
+  object's own `position` property or the `pos` WebSocket channel for that.
+  Documented on the method and in `docs/entities/tags.md`.
 
 ## [0.6.2] — 2026-07-09
 

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: rtls-sdk
-Version: 0.6.2
+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.2 → rtls_sdk-0.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "rtls-sdk"
-version = "0.6.2"
+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.2 → 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.2 → 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.6.2 → rtls_sdk-0.7.0}/src/rtls_sdk/models/position.py

@@ -1,9 +1,18 @@
 """Position model with embedded-vs-standalone normalization.
 
-The server emits position data under two wire formats (RESEARCH §3):
+The server emits position data under three wire formats:
 
 - **Embedded** inside a tag: ``sl_uid``, ``sl_id``, ``dev_id``, ``mac``, ``ts``.
 - **Standalone** under ``/positions``: ``area_uid``, ``trackable_uid``, ``mac_address``, ``ts``.
+- **State**, from ``/trackable_objects/position_from_state/{uid}``: the
+  coordinates are NESTED under ``position``, the area key is
+  ``sublocation_uid``, and there is **no** ``ts``/``mac``/tag identity at all::
+
+      {"position": {"x": 3800, "y": 3800, "z": 1000},
+       "sublocation_uid": "Izuz…", "location_uid": "TR2D…"}
+
+  (rtls-frontend ``routes/trackable_objects/utils.js::getTrackablePositionFromState``;
+  documented in its ``docs/internal/api/trackable_objects.md``.)
 
 The SDK normalizes both into one canonical shape with the SDK-canonical
 field names. Callers see ``area_uid`` / ``tag_uid``, never the wire aliases.
@@ -24,10 +33,17 @@ class Position(_BaseModel):
     """A position fix for a tag.
 
     Field names are SDK-canonical. Wire-format aliases ``sl_uid`` /
-    ``dev_id`` / ``mac`` (embedded) and ``trackable_uid`` (standalone) are
-    rewritten at parse time so consumers don't need to know which endpoint
-    produced the data. ``tag_uid`` is the SDK-canonical name for the
-    server's ``trackable_uid`` / ``dev_id``.
+    ``dev_id`` / ``mac`` (embedded), ``trackable_uid`` (standalone) and the
+    nested ``position`` / ``sublocation_uid`` (state) are rewritten at parse
+    time so consumers don't need to know which endpoint produced the data.
+    ``tag_uid`` is the SDK-canonical name for the server's
+    ``trackable_uid`` / ``dev_id``.
+
+    A state-form fix carries coordinates and an area, and nothing else: its
+    ``ts``, ``mac_address`` and ``tag_uid`` are ``None`` because that endpoint
+    does not send them. Do not use it to reason about fix recency — read the
+    trackable object's own ``position`` property, or the ``pos`` WebSocket
+    channel, when you need a timestamp.
     """
 
     area_uid: str | None = None
@@ -48,9 +64,23 @@ class Position(_BaseModel):
 
         out = dict(data)
 
+        # State form: lift the nested `position` object up to the top level.
+        # Top-level coordinates win — only the state endpoint nests them, and
+        # a payload carrying both is not something any server sends today.
+        nested = out.get("position")
+        if isinstance(nested, dict):
+            for axis in ("x", "y", "z"):
+                if out.get(axis) is None and nested.get(axis) is not None:
+                    out[axis] = nested[axis]
+            out.pop("position", None)
+
         # Wire-form → SDK-canonical renames.
         if "area_uid" not in out and "sl_uid" in out:
             out["area_uid"] = out["sl_uid"]
+        # State form spells the area `sublocation_uid` (the server's own wire
+        # key, kept verbatim by this endpoint).
+        if out.get("area_uid") is None and out.get("sublocation_uid") is not None:
+            out["area_uid"] = out["sublocation_uid"]
         # tag_uid <- standalone wire `trackable_uid`, else embedded `dev_id`.
         if out.get("tag_uid") is None:
             if out.get("trackable_uid") is not None:

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.2 → rtls_sdk-0.7.0}/src/rtls_sdk/resources/tags.py

@@ -14,6 +14,18 @@ from ..models import BulkResult, Position, Tag, TagTemplate
 from ._base import ResourceAPI
 
 
+def _position_or_none(wire: dict[str, Any]) -> Position | None:
+    """Parse a position payload, collapsing a coordinate-less result to ``None``.
+
+    A body with no x, y or z carries no fix — whatever else it holds — and the
+    caller asked "where is this tag?", so ``None`` is the honest answer.
+    """
+    position = Position.from_wire(wire)
+    if position.x is None and position.y is None and position.z is None:
+        return None
+    return position
+
+
 class TagsAPI(ResourceAPI):
     """List, get, and (later) mutate trackables.
 
@@ -92,11 +104,31 @@ class TagsAPI(ResourceAPI):
         return [TagTemplate.from_wire(item) for item in items]
 
     def last_position(self, uid: str) -> Position | None:
-        """Return the last cached position for a trackable, if known.
-
-        The response envelope is ``{trackablePositionFromState}`` — a
-        single position object, not a list (RESEARCH §3). Returns
-        ``None`` if the server has no cached position.
+        """Return the last cached ("state") position for a tag, if known.
+
+        The response envelope is ``{trackablePositionFromState}`` — a single
+        position object, not a list — and the server sends ``null`` there when
+        it holds no fix. The object itself nests its coordinates::
+
+            {"trackablePositionFromState": {
+               "position": {"x": 3800, "y": 3800, "z": 1000},
+               "sublocation_uid": "Izuz…", "location_uid": "TR2D…"}}
+
+        :class:`~rtls_sdk.models.position.Position` flattens that on parse.
+
+        .. note::
+           This endpoint returns **no timestamp**, MAC or tag identity — only
+           coordinates and the area. ``pos.ts`` is therefore always ``None``
+           here, so this is not the call to use for "has the fix advanced?".
+           Read the tag object's own ``position`` property, or the ``pos``
+           WebSocket channel, for a timestamped fix.
+
+        Returns ``None`` when the server holds no position — including the
+        empty-object body (``{"trackablePositionFromState": {}}``) it sends
+        when the state worker is unreachable, and any body that yields no
+        coordinates at all. Never returns a ``Position`` with nothing in it:
+        an all-``None`` object reads as a real fix at the call site and is how
+        a nested-payload regression stayed invisible before.
         """
         response = self._get(f"/api/v2/trackable_objects/position_from_state/{uid}")
         payload = response.json()
@@ -104,10 +136,10 @@ class TagsAPI(ResourceAPI):
             return None
         for key in ("trackablePositionFromState", "trackable_position_from_state"):
             if key in payload and isinstance(payload[key], dict):
-                return Position.from_wire(payload[key])
+                return _position_or_none(payload[key])
         # Some deployments return the position object directly.
-        if "x" in payload or "ts" in payload:
-            return Position.from_wire(payload)
+        if "x" in payload or "position" in payload or "ts" in payload:
+            return _position_or_none(payload)
         return None
 
     def create_raw(self, name: str, **fields: Any) -> Tag:

{rtls_sdk-0.6.2 → 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.