Metadata-Version: 2.5
Name: lunatone-rest-api-client
Version: 0.11.0
Summary: A client library for accessing the Lunatone REST API
Project-URL: Homepage, https://www.lunatone.com
Project-URL: Source, https://gitlab.com/lunatone-public/lunatone-rest-api-client
Project-URL: Issues, https://gitlab.com/lunatone-public/lunatone-rest-api-client/-/issues
Author-email: David Bugl <bugl@lunatone.com>
License-Expression: GPL-3.0-only
License-File: LICENSE
Keywords: api,client,lunatone
Requires-Python: >=3.12
Requires-Dist: aiohttp[speedups]>=3.12.14
Requires-Dist: awesomeversion>=25.8.0
Requires-Dist: pydantic>=2.11.7
Description-Content-Type: text/markdown

# Lunatone REST API Client

`lunatone-rest-api-client` is a Python package providing access to the Lunatone REST API.

It includes async clients for Lunatones REST API endpoints.

The following devices are supported:

- [DALI-2 IoT Gateway (v1.14.1 or later)](https://www.lunatone.com/produkt/dali-2-iot-gateway/)
- [DALI-2 IoT4 Gateway (v1.14.1 or later)](https://www.lunatone.com/produkt/dali-2-iot4-gateway/)
- [DALI-2 Display 4'' (v1.14.1 or later)](https://www.lunatone.com/produkt/dali-2-display-4/)
- [DALI-2 Display 7'' (v1.14.1 or later)](https://www.lunatone.com/produkt/dali-2-display-7/)

## Installation

Use `pip` to install the latest stable version of `lunatone-rest-api-client`
```bash
pip install --upgrade lunatone-rest-api-client
```

The current development version is available on [GitLab.com]
(https://gitlab.com/lunatone-public/lunatone-rest-api-client) and can be
installed directly from the git repository:

```bash
pip install git+https://gitlab.com/lunatone-public/lunatone-rest-api-client.git
```

## Usage

```python
import asyncio

import aiohttp

from lunatone_rest_api_client import Auth, Devices


async def main() -> None:
    """Show example of fetching devices."""
    async with aiohttp.ClientSession() as session:
        auth = Auth(session, "http://10.0.0.31")
        devices = Devices(auth)
        await devices.async_update()
        print(devices.data)


if __name__ == "__main__":
    asyncio.run(main())
```

### WebSocket events

Register callbacks on the websocket client before opening the connection, then
close the connection when event updates are no longer needed. Use this inside
your async application after creating an `Auth` instance:

```python
import asyncio

import aiohttp

from lunatone_rest_api_client import Auth, Devices


async def main() -> None:
    """Show example of controlling a device combined with websocket push updates."""
    async with aiohttp.ClientSession() as session:
        auth = Auth(session, "http://10.0.0.31")
        devices = Devices(auth)

        def on_devices_update(device_id: int) -> None:
            print(devices.devices[device_id])

        devices.register_update_callback(on_devices_update)
        await auth.websocket.open()
        try:
            device = devices.devices[0]
            await device.fade_to_brightness(100.0)
        finally:
            await auth.websocket.close()

        print(devices.data)


if __name__ == "__main__":
    asyncio.run(main())
```

## Setting up development environment

This Python project is fully managed using the uv dependency manager.

### Requirements:

- uv (See https://docs.astral.sh/uv/getting-started/installation/)

To install all packages, including all development requirements:

```bash
uv sync
```

To run just the Python tests:

```bash
uv run pytest
```

## Scripts

### API tests:

This script sends a `POST` request and right after two `GET` requests to check if the status is changed immediately.

```bash
uv run ./scripts/api_tests.py --ip <ip-address>
```
