rtls-sdk 0.4.0

Python SDK for the RTLS REST API

RTLS SDK

A Python SDK for the RTLS REST API. Three-step usage:

from rtls_sdk import RtlsClient

client = RtlsClient.from_env()
tags = client.tags.list()

That's it — token, refresh, scoping headers, 401 re-login are all internal. The first method call performs a lazy login; subsequent calls reuse the session.

What you get

• Compound workflows. One Python call replaces the multi-call REST sagas the JS reference client makes you script — e.g. tags.create(name="X", attached_zone="Z", groups=[...]) runs the three-step create-and-attach with rollback on partial failure.
• One exception hierarchy. Everything under RtlsError: NotFound, ValidationError, RateLimited, ServerError, PartialFailureError, ReportFailed / ReportTimeout, …
• Typed models. Pydantic v2 under the hood; mypy --strict clean out of the box; ships py.typed.
• Mandatory redaction. No password, token, refresh-token, cookie, or Authorization header ever reaches a log handler. There is no opt-out flag.
• Sync-only for v1. Async surface and WebSocket support are on the v2 roadmap.

Install

pip install rtls-sdk

Python 3.10+ supported. See docs/install.md for dev install and verification.

Quickstart

export RTLS_USERNAME="[e-mail]"
export RTLS_PASSWORD="hunter2"
export RTLS_BASE_URL="https://rtls.example.com"

from rtls_sdk import RtlsClient

with RtlsClient.from_env() as client:
    for tag in client.tags.list():
        print(tag.uid, tag.name)

For the full 5-minute walkthrough see docs/quickstart.md.

Documentation

The full docs site (mkdocs build):

Start here

• Entity catalog — one page per entity (tags, sites, areas, floorplans, anchors, zones, nodes, users, reports, …) with methods, examples, and model fields. The fastest path to "what can I do with X?".
• Install · Quickstart

Cross-cutting guides

• Compound workflows · Reports · Floorplans
• Error handling · Scope switching · Pagination
• Rate limiting · Timestamps · Credential rotation

Advanced

• BYO token · Raw REST methods · Logging · HTTP client override · Security

Reference

• Migrating from the JS client
• API reference — auto-generated from docstrings via mkdocstrings.

Build locally:

pip install -e ".[docs]"
mkdocs serve

Status

v0.2.0 — adds M9 places CRUD (sites / areas / anchors), M10 floorplans

• image lifecycle, M11 entity-oriented documentation reorganisation, and M12 schema-audit fixes (canonical bare-12-hex MACs; tags.create no longer accepts the silently-stripped mac_address argument). See CHANGELOG.md.

License

MIT — see LICENSE.