Metadata-Version: 2.4
Name: py-unifi-access
Version: 1.3.0
Summary: Async Python client for the UniFi Access local API with WebSocket event support
Author: imhotep
License: MIT
Project-URL: Homepage, https://github.com/imhotep/py-unifi-access
Project-URL: Repository, https://github.com/imhotep/py-unifi-access
Project-URL: Issues, https://github.com/imhotep/py-unifi-access/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: cli
Requires-Dist: typer>=0.12.0; extra == "cli"
Provides-Extra: dev
Requires-Dist: typer>=0.12.0; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=1.0; extra == "dev"
Requires-Dist: pytest-cov>=6.0; extra == "dev"
Requires-Dist: aioresponses>=0.7; extra == "dev"
Requires-Dist: pre-commit>=4.0; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: ruff>=0.8; extra == "dev"
Dynamic: license-file

# py-unifi-access

[![CI](https://github.com/imhotep/py-unifi-access/actions/workflows/ci.yml/badge.svg)](https://github.com/imhotep/py-unifi-access/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)

Async Python client for the UniFi Access local API with WebSocket event support. Designed for Home Assistant Core integrations.

## Features

- Async REST client (`aiohttp`) for doors, lock rules, emergency status
- WebSocket with auto-reconnect and exponential backoff
- Typed Pydantic v2 models for all API responses and 13 WebSocket event types
- Stateless design for Home Assistant's `DataUpdateCoordinator` pattern

## Installation

```bash
pip install py-unifi-access
```

## Usage

```python
import aiohttp
from unifi_access_api import UnifiAccessApiClient

async with aiohttp.ClientSession() as session:
    client = UnifiAccessApiClient("192.168.1.1", "your-api-token", session)

    # Authenticate
    await client.authenticate()

    # Get all doors (keyed by ID for quick lookup)
    doors = {d.id: d for d in await client.get_doors()}
    for door in doors.values():
        print(f"{door.name}: {door.door_position_status}")

    # Unlock a specific door by ID
    await client.unlock_door("your-door-id")

    # WebSocket for real-time events
    ws = client.start_websocket({
        "access.data.device.update": lambda msg: print(msg),
    })
```

## Capturing WebSocket Messages

If you encounter parsing errors or unexpected behaviour with WebSocket events,
capturing the raw message stream helps narrow down the issue.
The CLI (included in the `cli` extra) writes two files to the current directory:

| File | Content |
|---|---|
| `events_<datetime>_raw.jsonl` | All raw events, written **before** parsing |
| `events_<datetime>_parsed.jsonl` | Successfully parsed events only |

```bash
# 1. Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate

# 2. Install the package with CLI dependencies
pip install "py-unifi-access[cli]"

# 3. Record events (60 seconds, for example)
unifi-access -H 192.168.1.1 -t <TOKEN> --no-verify-ssl listen -d 60
```

Trigger the action you want to inspect (e.g. an access request) during the
capture window, then review the `events_*_raw.jsonl` file before sharing it
when reporting an issue. Raw payloads may contain sensitive data such as
tokens or identifiers (for example MAC addresses and device/user names), so
please redact secrets/identifiers first or share the file privately if needed.

## Development

```bash
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pre-commit install
pytest tests/ --cov
```

## Releases

Merges to `main` now trigger an automatic release when the version in `pyproject.toml`
changes. The workflow will:

- run CI
- build the package
- publish it to PyPI
- create and push a matching Git tag
- create a GitHub release with generated notes

To make PyPI publishing work, configure a PyPI trusted publisher for this GitHub
repository and environment:

- repository: `imhotep/py-unifi-access`
- workflow file: `ci.yml`
- environment: `pypi`