Metadata-Version: 2.4
Name: pyatccala
Version: 0.1.0
Summary: Async client for the ATC Cala / Grupo Ferroli WiFi radiator cloud API
Author: belamadar
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://gitlab.com/belamadar/pyatccala
Project-URL: Repository, https://gitlab.com/belamadar/pyatccala
Project-URL: Issues, https://gitlab.com/belamadar/pyatccala/-/issues
Keywords: atc,cala,ferroli,radiator,heating,home-assistant
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Home Automation
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp>=3.9
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Requires-Dist: pytest-asyncio>=0.23; extra == "test"
Dynamic: license-file

# pyatccala

Async Python client for the **ATC Cala** / Grupo Ferroli WiFi radiator cloud API
(`gateway.grupoferroli.es`). It powers a companion ATC Cala Home Assistant integration but has no
Home Assistant dependency and can be used standalone.

The reverse-engineered protocol is documented in the companion integration repo's `API.md`.

## Install

```bash
pip install pyatccala
```

## Usage

```python
import asyncio
from pyatccala import AtcCalaClient

async def main():
    async with AtcCalaClient("you@example.com", "password") as client:
        await client.login()                      # OAuth password grant
        installations = await client.get_installations()
        inst = installations[0]

        for radiator in await client.get_radiators(inst.id_installation):
            print(radiator.name, radiator.mode, radiator.current_temperature)

        # Change the Comfort setpoint on one radiator (values sent as strings automatically).
        await client.put_radiator_changes(
            heaters=[radiator.id_radiator],
            cambios=[("TempComfort", 21.5)],
        )

        # Start a 60-minute boost to 22°C (expiry computed from the server clock).
        await client.async_start_boost(inst.id_installation, [radiator.id_radiator], 22.0, 60)

asyncio.run(main())
```

## Auth handling

`AtcCalaClient` manages the OAuth token transparently:

- The access token lasts ~20 minutes. `async_ensure_token()` refreshes it before expiry using the
  **refresh grant**, falling back to a full password login if the refresh is rejected.
- Any `401` from a data call triggers one automatic re-auth and retry.
- Errors are typed: `AtcCalaAuthError` (re-login required) vs `AtcCalaConnectionError` (transient).

Pass your own `aiohttp.ClientSession` via `session=` (recommended inside a larger app), or let the
client create and own one. `api_base=` can point at a mock/proxy for testing.

## Development

```bash
pip install -e .[test]
pytest -p no:homeassistant   # (the flag only matters if HA test plugins share the venv)
```
