Metadata-Version: 2.4
Name: yama-client
Version: 0.1.0
Summary: The official Python client for the Yama access-control API
Keywords: yama,access control,intercom,api,client
Author: Yama Access Software Systems Ltd.
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Typing :: Typed
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.7
Requires-Python: >=3.10
Project-URL: Homepage, https://yamasystems.com
Project-URL: Documentation, https://yass-ltd.github.io/yama-python/
Project-URL: Source, https://github.com/YASS-Ltd/yama-python
Project-URL: Issues, https://github.com/YASS-Ltd/yama-python/issues
Project-URL: Release notes, https://github.com/YASS-Ltd/yama-python/releases
Description-Content-Type: text/markdown

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset=".github/assets/yama-logo-dark.svg">
    <img src=".github/assets/yama-logo-light.svg" alt="Yama" width="280">
  </picture>
</p>

<p align="center">
  <em>The official Python client for the Yama access-control API.</em>
</p>

<p align="center">
  <a href="https://pypi.org/project/yama-client/"><img src="https://img.shields.io/pypi/v/yama-client?style=flat-square" alt="PyPI"></a>
  <a href="https://pypi.org/project/yama-client/"><img src="https://img.shields.io/pypi/pyversions/yama-client?style=flat-square" alt="Python versions"></a>
  <a href="https://github.com/YASS-Ltd/yama-python/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/YASS-Ltd/yama-python/ci.yml?branch=main&style=flat-square&label=CI" alt="CI"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/licence-MIT-21212B?style=flat-square" alt="MIT licence"></a>
</p>

---

**Docs:** <https://yass-ltd.github.io/yama-python/> · **REST API:** <https://app.yamasystems.com/api/v2/docs/> · **Source:** <https://github.com/YASS-Ltd/yama-python>

---

Manage a building's access codes and read its call log from Python. The client handles auth, pagination, retries and errors, and gives you typed objects back.

> [!NOTE]
> **In development.** Nothing is on PyPI yet. Until then, use the [REST API](https://app.yamasystems.com/api/v2/docs/) directly.

## Install

```console
uv add yama-client  # or: pip install yama-client
```

<!-- --8<-- [start:quick-start] -->
## Quick start

Create an API key in the Yama portal under **Settings › API keys**, with read access to access codes and the call log, and set it as `YAMA_API_KEY`. Keep it out of source control.

```python
from datetime import datetime, timezone

from yama import Yama

client = Yama()  # reads YAMA_API_KEY

for code in client.codes.list():
    print(code.name, code.expires_at)

start = datetime(2026, 10, 1, tzinfo=timezone.utc)
end = datetime(2026, 11, 1, tzinfo=timezone.utc)  # exclusive: all of October
for call in client.calls.list(start=start, end=end):
    print(call.started_at, call.result)
```
<!-- --8<-- [end:quick-start] -->

## What you get

- **Typed:** Pydantic models with UTC-aware datetimes, so your editor autocompletes.
- **Every item:** iterating a list yields every item, and each call in the call log comes once.
- **Safe retries:** on 429 (honouring `Retry-After`), 5xx and network errors, for every call, creates included: a code is never created twice.
- **Clear errors:** one exception class per kind of failure, listed in the [docs](https://yass-ltd.github.io/yama-python/errors/).
- **Forward-compatible:** new fields and enum values from the API don't break your code.
- **Small:** two dependencies, httpx and Pydantic. Python 3.10 and newer.

## Versioning

SemVer, targeting version 2 of the Yama API (`/api/v2/`). Release notes are on [GitHub Releases](https://github.com/YASS-Ltd/yama-python/releases).

## Contributing

Bug reports and ideas are welcome in [issues](https://github.com/YASS-Ltd/yama-python/issues). Development uses [uv](https://docs.astral.sh/uv/) and [just](https://just.systems/): `just check` runs everything CI does. Report security issues privately; see [SECURITY.md](SECURITY.md).

## Licence

[MIT](LICENSE) © Yama Access Software Systems Ltd.
