rtls-sdk 0.2.0__py3-none-any.whl

rtls_sdk/compounds/context.py

@@ -0,0 +1,159 @@
+"""Session-bootstrap compound — DESIGN §4.2.
+
+``collect_session_context(client, scope=...)`` fans out the ~20 sub-calls
+that hydrate the deployment view used by every operator UI. Sequential
+in v1 (sync SDK); a v2 async surface would parallelize.
+
+Continue-on-error: per-sub-call ``RtlsError`` lands on
+``SessionContext.errors`` keyed by stable sub-resource name. Transport
+failures (``ConnectionError`` and other non-``RtlsError`` exceptions)
+propagate — there's no point assembling a partial snapshot if the
+network is down.
+
+Conditional sub-resources (handled specially):
+
+- **anchors**: module may not be installed. ``NotFound`` /
+  ``PermissionDenied`` on that endpoint is treated as "feature absent",
+  NOT as an error — anchors stays empty and the error is not recorded.
+- **nodes**: must be fetched at company-scope (RESEARCH §4 "Load all
+  entities for current scope"). The SDK uses ``_call_with_scope(
+  company_uid=..., clear_project=True)`` to strip ``X-User-Project``
+  and add ``X-User-Subcontractor`` for that one call only.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Any
+
+from ..errors import (
+    ConnectionError as RtlsConnectionError,
+)
+from ..errors import (
+    NotFound,
+    PermissionDenied,
+    RtlsError,
+)
+from ..models import SessionContext
+
+if TYPE_CHECKING:
+    from .._client import RtlsClient
+
+
+logger = logging.getLogger("rtls_sdk.compounds.context")
+
+
+# Sub-resources whose 404 / 403 is treated as "module absent", not as
+# a hard error. Currently just anchors; documented stably so callers
+# can rely on the absence-of-an-errors-entry signal.
+_SOFT_OPTIONAL: frozenset[str] = frozenset({"anchors"})
+
+
+def collect_session_context(client: RtlsClient, *, scope: str | None = None) -> SessionContext:
+    """Hydrate a :class:`SessionContext` under the active project scope.
+
+    Only ``scope="project"`` (or ``None``, equivalent) is implemented in
+    v1. ``"company"`` / ``"system"`` variants raise
+    :class:`NotImplementedError`.
+    """
+    if scope not in (None, "project"):
+        raise NotImplementedError(
+            f"context.load(scope={scope!r}) is not implemented in v1. "
+            "Only the default project scope is supported; company / "
+            "system bundles are a v2 candidate (DESIGN §9 R4)."
+        )
+
+    result = SessionContext()
+
+    # Each sub-resource: (name, fetcher, setter).
+    # The setter writes onto ``result``; we keep it explicit so mypy
+    # doesn't need to verify a getattr-based generic assignment.
+    sub_resources: list[tuple[str, Callable[[], Any], Callable[[SessionContext, Any], None]]] = [
+        ("sites", client.sites.list, _setter("sites")),
+        ("areas", client.areas.list, _setter("areas")),
+        ("floorplans", client.floorplans.list, _setter("floorplans")),
+        ("tags", client.tags.list, _setter("tags")),
+        ("associations", client.associations.list, _setter("associations")),
+        ("zones", client.zones.list, _setter("zones")),
+        (
+            "zone_prototypes",
+            client.zones.list_custom_prototypes,
+            _setter("zone_prototypes"),
+        ),
+        ("groups", client.groups.list, _setter("groups")),
+        ("alarms", client.alarms.list_active, _setter("alarms")),
+        ("notifications", client.notifications.list, _setter("notifications")),
+        (
+            "notification_types",
+            client.notifications.list_types,
+            _setter("notification_types"),
+        ),
+        ("subscribers", client.subscribers.list, _setter("subscribers")),
+        (
+            "system_subscribers",
+            client.subscribers.list_system_notification_subscribers,
+            _setter("system_subscribers"),
+        ),
+        ("users", client.users.list, _setter("users")),
+        ("user_roles", client.users.list_roles, _setter("user_roles")),
+        ("tag_templates", client.tags.list_templates, _setter("tag_templates")),
+        ("helper_link", client.system.helper_link, _setter("helper_link")),
+        ("monitor_link", client.system.monitor_link, _setter("monitor_link")),
+    ]
+
+    for name, fetcher, setter in sub_resources:
+        try:
+            value = fetcher()
+        except RtlsConnectionError:
+            # Transport-level failure (DNS, refused, timeout) — propagate.
+            # There's no point assembling a partial snapshot when the
+            # network is down (DESIGN §4.2).
+            raise
+        except RtlsError as exc:
+            logger.warning("context.load: %s failed: %s", name, exc)
+            result.errors[name] = exc
+            continue
+        setter(result, value)
+
+    # -- anchors (optional module) -----------------------------------
+    try:
+        result.anchors = client.anchors.list()
+    except (NotFound, PermissionDenied):
+        # Module not installed on this deployment — silent skip.
+        # Crucially we do NOT add this to result.errors; callers use
+        # the absence of an "anchors" entry as the "module not present"
+        # signal (DESIGN §4.2 / RESEARCH §4 "Load all entities").
+        logger.debug("context.load: anchors module not present, skipped")
+    except RtlsConnectionError:
+        raise
+    except RtlsError as exc:
+        logger.warning("context.load: anchors failed: %s", exc)
+        result.errors["anchors"] = exc
+
+    # -- nodes (cross-scope: company, not project) -------------------
+    company_uid = client._auth_state.company_uid
+    try:
+        with client._call_with_scope(company_uid=company_uid or "", clear_project=True):
+            result.nodes = client.nodes.list()
+    except RtlsConnectionError:
+        raise
+    except RtlsError as exc:
+        logger.warning("context.load: nodes failed: %s", exc)
+        result.errors["nodes"] = exc
+
+    # Stamp completion time and the partial flag.
+    result.loaded_at = datetime.now(timezone.utc)
+    result.partial = bool(result.errors)
+    return result
+
+
+def _setter(field_name: str) -> Callable[[SessionContext, Any], None]:
+    def assign(ctx: SessionContext, value: Any) -> None:
+        setattr(ctx, field_name, value)
+
+    return assign
+
+
+__all__ = ["collect_session_context"]

rtls_sdk/compounds/groups.py

@@ -0,0 +1,126 @@
+"""Compound group workflows.
+
+Step-name conventions:
+
+- ``delete``: ``load_member_tags``, ``detach_from_tag``, ``delete_group``.
+- ``add_tags`` / ``remove_tags``: per-tag continue-on-error; no shared
+  step-names — the BulkResult carries per-row errors.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from ..errors import PartialFailureError, RtlsError
+from ..models import BulkFailure, BulkResult
+
+if TYPE_CHECKING:
+    from .._client import RtlsClient
+
+
+logger = logging.getLogger("rtls_sdk.compounds.groups")
+
+
+def delete_group(client: RtlsClient, uid: str) -> None:
+    """Delete a group, detaching its trackable memberships first.
+
+    The server has no dedicated "tags in group X" endpoint per the JS
+    reference client (RESEARCH §4 "Delete group") — the SDK lists all
+    tags and filters client-side. For each member, ``replace_groups`` is
+    called with the group removed.
+
+    Detach failures are aggregated but do NOT abort the cascade — the
+    group is still deleted afterwards. The exception's ``partial_result``
+    names every tag that still carries a stale reference, so the caller
+    can clean up.
+    """
+    completed: list[str] = []
+
+    # Step 1: find member trackables.
+    try:
+        all_tags = client.tags.list()
+    except RtlsError as exc:
+        raise PartialFailureError(
+            f"groups.delete: load_member_tags failed: {exc}",
+            completed_steps=completed,
+            failed_step="load_member_tags",
+            cause=exc,
+        ) from exc
+    completed.append("load_member_tags")
+    members = [tag for tag in all_tags if uid in tag.groups]
+
+    # Step 2: detach each member from this group.
+    stale: list[str] = []
+    for tag in members:
+        new_groups = [g for g in tag.groups if g != uid]
+        try:
+            client.tags.replace_groups(tag.uid, new_groups, no_notify=True)
+        except RtlsError as exc:
+            logger.warning("groups.delete: detach from tag %s failed: %s", tag.uid, exc)
+            stale.append(tag.uid)
+
+    # Step 3: delete the group itself.
+    try:
+        client.groups.delete_raw(uid)
+    except RtlsError as exc:
+        raise PartialFailureError(
+            f"groups.delete: delete_group failed: {exc}",
+            completed_steps=completed,
+            failed_step="delete_group",
+            cause=exc,
+            partial_result={"group_uid": uid, "stale_members": stale},
+        ) from exc
+
+    if stale:
+        # We succeeded in deleting the group, but some members couldn't
+        # be detached cleanly — surface that as a soft failure so the
+        # caller can reconcile.
+        raise PartialFailureError(
+            f"groups.delete: deleted group {uid!r} but {len(stale)} tag(s) "
+            f"still carry a stale group reference",
+            completed_steps=[*completed, "delete_group"],
+            failed_step="detach_from_tag",
+            cause=RtlsError(f"stale references on tags: {stale}"),
+            partial_result={"group_uid": uid, "stale_members": stale},
+        )
+
+
+def add_tags(client: RtlsClient, group_uid: str, tag_uids: list[str]) -> BulkResult[None]:
+    """Add a group to each tag's membership list, continue-on-error.
+
+    Per-tag: load → append → ``replace_groups``. Already-member tags are
+    no-ops (the result counts them as succeeded).
+    """
+    result: BulkResult[None] = BulkResult()
+    for tag_uid in tag_uids:
+        try:
+            tag = client.tags.get(tag_uid)
+            if group_uid in tag.groups:
+                result.succeeded.append(None)
+                continue
+            client.tags.replace_groups(tag_uid, [*tag.groups, group_uid], no_notify=True)
+            result.succeeded.append(None)
+        except RtlsError as exc:
+            result.failures.append(BulkFailure(error=exc, input=tag_uid, uid=tag_uid))
+    return result
+
+
+def remove_tags(client: RtlsClient, group_uid: str, tag_uids: list[str]) -> BulkResult[None]:
+    """Remove a group from each tag's membership list, continue-on-error."""
+    result: BulkResult[None] = BulkResult()
+    for tag_uid in tag_uids:
+        try:
+            tag = client.tags.get(tag_uid)
+            if group_uid not in tag.groups:
+                result.succeeded.append(None)
+                continue
+            new_groups = [g for g in tag.groups if g != group_uid]
+            client.tags.replace_groups(tag_uid, new_groups, no_notify=True)
+            result.succeeded.append(None)
+        except RtlsError as exc:
+            result.failures.append(BulkFailure(error=exc, input=tag_uid, uid=tag_uid))
+    return result
+
+
+__all__ = ["add_tags", "delete_group", "remove_tags"]

rtls_sdk/compounds/nodes.py

@@ -0,0 +1,176 @@
+"""Compound node workflows.
+
+Step-name conventions (stable, part of the API contract):
+
+- ``release``: ``close_association``, ``release_node``.
+- ``import_``: per-row failures land in ``ImportResult.failures``; no
+  shared step names.
+- ``delete``: per-row failures land in ``BulkResult.failures``.
+
+The headline behaviour win for M5: ``release`` uses per-call scope
+override (``client._call_with_scope``) so it can target a project
+different from the client's default WITHOUT mutating shared state. The
+JS reference client juggles global axios defaults here and leaks the
+change on error (RESEARCH §4 "Release node and close its association",
+DESIGN §1 snippet 1.11).
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+from typing import TYPE_CHECKING
+
+from ..errors import PartialFailureError, RtlsError
+from ..models import BulkFailure, BulkResult, ImportResult
+
+if TYPE_CHECKING:
+    from .._client import RtlsClient
+
+
+logger = logging.getLogger("rtls_sdk.compounds.nodes")
+
+
+def release_node(
+    client: RtlsClient,
+    mac_address: str,
+    *,
+    project_uid: str | None = None,
+) -> None:
+    """Close any open association for ``mac_address``, then release.
+
+    All sub-calls run under the supplied ``project_uid`` (or the
+    client's default project if ``None`` is passed). The scope override
+    is per-thread and reverts on exit — concurrent calls on the same
+    client don't trample each other (the bug the JS reference client
+    has).
+
+    Step names:
+    - ``close_association`` (only when an open association exists)
+    - ``release_node``
+
+    Partial-failure rule: if ``close_association`` fails, raise without
+    attempting release. If ``release_node`` fails after a successful
+    close, raise :class:`PartialFailureError` with
+    ``completed_steps=["close_association"]`` — the association is now
+    closed but the node is still assigned; caller must reconcile.
+    """
+    target_project = project_uid or client._auth_state.project_uid
+
+    with client._call_with_scope(project_uid=target_project):
+        # Step 1: find an open association for this MAC.
+        open_assoc = None
+        try:
+            for assoc in client.associations.list():
+                if assoc.mac_address == mac_address and assoc.closed_at is None and assoc.uid:
+                    open_assoc = assoc
+                    break
+        except RtlsError:
+            # If we can't list associations, fall through to release —
+            # the server will surface any blocking constraint.
+            open_assoc = None
+
+        completed: list[str] = []
+
+        # Step 2: close the association if one was open.
+        if open_assoc is not None:
+            try:
+                # Pass the Association directly so close() doesn't have
+                # to re-list. The server identifies by mac_address /
+                # obj_uid in the body, not by the association uid.
+                client.associations.close(open_assoc)
+            except RtlsError as exc:
+                # Re-raise without attempting release — the association
+                # didn't close, releasing the node would orphan it.
+                raise PartialFailureError(
+                    f"nodes.release: close_association failed: {exc}",
+                    completed_steps=completed,
+                    failed_step="close_association",
+                    cause=exc,
+                ) from exc
+            completed.append("close_association")
+
+        # Step 3: release the node.
+        try:
+            client.nodes.release_raw(mac_address, project_uid=target_project or "")
+        except RtlsError as exc:
+            raise PartialFailureError(
+                f"nodes.release: release_node failed: {exc}",
+                completed_steps=completed,
+                failed_step="release_node",
+                cause=exc,
+            ) from exc
+
+
+def import_nodes(
+    client: RtlsClient,
+    mac_addresses: list[str],
+    *,
+    on_progress: Callable[[int, int], None] | None = None,
+) -> ImportResult:
+    """Validate MACs server-side, then create each valid row.
+
+    Short-circuits if any MAC is invalid or duplicate — DESIGN §4.9: the
+    server's validation step is treated as a hard gate, and the SDK
+    refuses to partially import a batch with known-bad rows.
+
+    ``on_progress(done, total)`` (optional) is invoked after each create
+    attempt, succeeded or not.
+    """
+    validation = client.nodes.validate(mac_addresses)
+    valid_raw = validation.get("valid")
+    invalid_raw = validation.get("invalid")
+    duplicate_raw = validation.get("duplicate")
+
+    valid = list(valid_raw) if isinstance(valid_raw, list) else []
+    invalid = list(invalid_raw) if isinstance(invalid_raw, list) else []
+    duplicate = list(duplicate_raw) if isinstance(duplicate_raw, list) else []
+
+    # Short-circuit: any invalid or duplicate row means we don't create.
+    if invalid or duplicate:
+        return ImportResult(
+            valid=valid,
+            invalid=invalid,
+            duplicate=duplicate,
+            imported_count=0,
+            failures=[],
+        )
+
+    failures: list[BulkFailure] = []
+    total = len(valid)
+    for i, mac in enumerate(valid, start=1):
+        try:
+            client.nodes.create(mac)
+        except RtlsError as exc:
+            failures.append(BulkFailure(error=exc, input=mac, uid=mac))
+        if on_progress is not None:
+            on_progress(i, total)
+
+    return ImportResult(
+        valid=valid,
+        invalid=invalid,
+        duplicate=duplicate,
+        imported_count=len(valid) - len(failures),
+        failures=failures,
+    )
+
+
+def delete_nodes(client: RtlsClient, uid_or_uids: str | list[str]) -> BulkResult[None]:
+    """Delete one or many nodes, continue-on-error.
+
+    Diverges from M3's :meth:`NodesAPI.delete_raw` which is fail-fast.
+    The compound :meth:`NodesAPI.delete` is the safer default for bulk
+    deletes; the raw variant remains for callers that want a hard fail.
+    """
+    uids = [uid_or_uids] if isinstance(uid_or_uids, str) else uid_or_uids
+    result: BulkResult[None] = BulkResult()
+    for uid in uids:
+        try:
+            client.nodes.delete_raw(uid)
+            result.succeeded.append(None)
+        except RtlsError as exc:
+            result.failures.append(BulkFailure(error=exc, input=uid, uid=uid))
+    return result
+
+
+__all__ = ["delete_nodes", "import_nodes", "release_node"]