Metadata-Version: 2.4
Name: rtls-sdk
Version: 0.6.1
Summary: Python SDK for the RTLS REST API
Project-URL: Documentation, https://rtls-sdk.pages.dev
Author: RTLS SDK Maintainers
License: MIT
License-File: LICENSE
Keywords: iot,rtls,sdk,tracking
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.5
Requires-Dist: websockets>=12.0
Provides-Extra: dev
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: pytest-cov>=4.1; extra == 'dev'
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'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
Description-Content-Type: text/markdown

# RTLS SDK

A Python SDK for the RTLS REST API.

📖 **Documentation:** https://rtls-sdk.pages.dev

Three-step usage:

```python
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

```bash
pip install rtls-sdk
```

Python 3.10+ supported. See [`docs/install.md`](docs/install.md) for
dev install and verification.

## Quickstart

```bash
export RTLS_USERNAME="qa@example.com"
export RTLS_PASSWORD="hunter2"
export RTLS_BASE_URL="https://rtls.example.com"
```

```python
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`](docs/quickstart.md).

## Documentation

Full documentation: **https://rtls-sdk.pages.dev**

- [Install](https://rtls-sdk.pages.dev/install/) · [Quickstart](https://rtls-sdk.pages.dev/quickstart/)
- [Entity catalog](https://rtls-sdk.pages.dev/entities/) — one page per entity
  (tags, sites, areas, floorplans, anchors, zones, nodes, users, reports, …)
  with methods, examples, and model fields.
- Guides — compound workflows, error handling, pagination, rate limiting,
  scope switching, timestamps, reports, floorplans, credential rotation.
- Advanced — BYO token, raw REST methods, logging, HTTP client override,
  security.
- Migrating from the JS client, plus an API reference auto-generated from
  docstrings.

## 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`](CHANGELOG.md).

## License

MIT — see [`LICENSE`](LICENSE).
