Metadata-Version: 2.4
Name: python-homely
Version: 0.1.0
Summary: Async Python client for the Homely cloud API, built for Home Assistant but usable anywhere.
Author: Ludvik Blichfeldt Rød
License-Expression: MIT
Project-URL: Homepage, https://github.com/ludvikroed/python-homely
Project-URL: Documentation, https://github.com/ludvikroed/python-homely#readme
Project-URL: Source, https://github.com/ludvikroed/python-homely
Project-URL: Issues, https://github.com/ludvikroed/python-homely/issues
Project-URL: Changelog, https://github.com/ludvikroed/python-homely/blob/main/CHANGELOG.md
Keywords: homely,api,websocket,asyncio,home-automation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Home Automation
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp<4.0.0,>=3.9.0
Requires-Dist: python-socketio<6.0.0,>=5.11.0
Provides-Extra: dev
Requires-Dist: build>=1.2.2; extra == "dev"
Requires-Dist: pytest>=8.3.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24.0; extra == "dev"
Requires-Dist: ruff>=0.8.0; extra == "dev"
Requires-Dist: twine>=6.0.0; extra == "dev"
Dynamic: license-file

# Python-homely

Async Python client for the Homely cloud API and realtime websocket updates.

This package was created for the Homely Home Assistant integration, but it is framework-independent and can be used in any Python project that needs to talk to Homely.

## Features

- Login and token refresh
- Location and home-data fetches
- Realtime websocket updates
- Typed exceptions
- Async API built on `aiohttp`

## Installation

```bash
python3 -m pip install python-homely
```

## Quick Start

```python
import aiohttp
from homely import HomelyClient


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        client = HomelyClient(session)

        token = await client.authenticate("user@example.com", "password")
        locations = await client.get_locations_or_raise(token.access_token)
        location_id = locations[0]["locationId"]

        data = await client.get_home_data_or_raise(token.access_token, location_id)
        print(data["name"])
```

## Websocket Example

```python
import aiohttp
from homely import HomelyClient, HomelyWebSocket


async def on_update(event: dict) -> None:
    print(event)


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        client = HomelyClient(session)
        token = await client.authenticate("user@example.com", "password")
        locations = await client.get_locations_or_raise(token.access_token)
        location_id = locations[0]["locationId"]

        websocket = HomelyWebSocket(
            location_id=location_id,
            token=token.access_token,
            on_data_update=on_update,
            context_id="example",
        )

        await websocket.connect_or_raise()
```

## Main API

- `authenticate(username, password) -> TokenResponse`
- `refresh_access_token(refresh_token) -> TokenResponse`
- `get_locations_or_raise(token) -> list[dict]`
- `get_home_data_or_raise(token, location_id) -> dict`
- `HomelyWebSocket(...).connect_or_raise()`

Main exports:

- `HomelyClient`
- `HomelyWebSocket`
- `TokenResponse`
- `HomelyConnectionError`
- `HomelyAuthError`
- `HomelyResponseError`
- `HomelyWebSocketError`

## Exceptions

- `HomelyConnectionError`: network or service unavailable
- `HomelyAuthError`: invalid credentials or rejected token
- `HomelyResponseError`: unexpected response or HTTP failure
- `HomelyWebSocketError`: websocket could not be established

## License

MIT. See [LICENSE](LICENSE).


⭐ If you find this integration useful, please consider giving it a star on [GitHub](https://github.com/ludvikroed/python-homely)! ⭐

