Metadata-Version: 2.4
Name: rtls-sdk
Version: 0.3.0
Summary: Python SDK for the RTLS REST API
Project-URL: Homepage, https://github.com/rpplabs/rtls-sdk
Project-URL: Documentation, https://github.com/rpplabs/rtls-sdk/tree/master/docs
Project-URL: Issues, https://github.com/rpplabs/rtls-sdk/issues
Project-URL: Changelog, https://github.com/rpplabs/rtls-sdk/blob/master/CHANGELOG.md
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. 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

The full docs site (`mkdocs build`):

**Start here**

- **[Entity catalog](docs/entities/index.md)** — 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](docs/install.md) · [Quickstart](docs/quickstart.md)

**Cross-cutting guides**

- [Compound workflows](docs/guides/compound-workflows.md) · [Reports](docs/guides/reports.md) · [Floorplans](docs/guides/floorplans.md)
- [Error handling](docs/guides/error-handling.md) · [Scope switching](docs/guides/scope-switching.md) · [Pagination](docs/guides/pagination.md)
- [Rate limiting](docs/guides/rate-limiting.md) · [Timestamps](docs/guides/timestamps.md) · [Credential rotation](docs/guides/credential-rotation.md)

**Advanced**

- [BYO token](docs/advanced/byo-token.md) · [Raw REST methods](docs/advanced/raw-rest-methods.md) · [Logging](docs/advanced/logging.md) · [HTTP client override](docs/advanced/http-client-override.md) · [Security](docs/advanced/security.md)

**Reference**

- [Migrating from the JS client](docs/migration/from-js-client.md)
- API reference — auto-generated from docstrings via mkdocstrings.

Build locally:

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

## License

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