Metadata-Version: 2.4
Name: gkphomepython
Version: 0.3.0
Summary: Python API wrapper for GKP Wi-Fi radiators
Author-email: Théo BRILLAND <theo.brilland@wattswater.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/FRRO-WattsElectronics/gkphomepython
Project-URL: Documentation, https://github.com/FRRO-WattsElectronics/gkphomepython
Project-URL: Repository, https://github.com/FRRO-WattsElectronics/gkphomepython
Project-URL: Bug Tracker, https://github.com/FRRO-WattsElectronics/gkphomepython/issues
Project-URL: Changelog, https://github.com/FRRO-WattsElectronics/gkphomepython/blob/main/README.md#changelog
Keywords: gkp,radiator,thermostat,home automation,iot
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Home Automation
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp<4.0.0,>=3.8.0
Requires-Dist: PyJWT>=2.0.0
Provides-Extra: dev
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: mypy>=1.10.0; extra == "dev"
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Dynamic: license-file

# gkphomepython

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A Python API wrapper for GKP Wi-Fi radiators, providing easy Home Assistant integration with the GKP cloud.

## Features

- **OAuth2 authentication** - Secure token-based authentication with automatic refresh
- **Installation discovery** - Discovery of the installations where the user is the main administrator
- **Thermostat control** - Set temperature and modes, and read the current status
- **Device wake up** - Ask the radiators to report their current state
- **Rate limiting** - Expose the delay requested by the API when it rate limits the user

## Installation

### From source

```bash
pip install .
```

## Usage

```python
from gkphomepython import GkpAuth, GkpClient, GkpMode

auth = GkpAuth(oauth_session)  # object exposing `token` and `async_ensure_token_valid()`
client = GkpClient(auth, aiohttp_session)

installations = await client.get_installations()
for installation in installations:
    await client.notify_user_connected(installation.installation_id)

result = await client.get_thermostats(installations)
# result.thermostats: Thermostat by device ID, result.errors: GkpError by device ID

await client.set_mode(device_id, GkpMode.COMFORT)
await client.set_temperature(device_id, GkpMode.COMFORT, 21.5)
```

## Supported Device Types

### Thermostat
Control and monitor GKP Wi-Fi radiators.

**Available thermostat modes:**
- `OFF` - Turn off heating
- `ECO` - Energy saving mode
- `AUTO` - Follow programmed schedule
- `COMFORT` - Comfort mode
- `DEFROST` - Frost protection mode
- `BOOST` - Boost mode for a limited duration

Temperatures are exposed in °C; the firmware unit (1/10 °F) is converted by the
library. Setting a temperature in `AUTO` mode starts a boost.

## Requirements

- Python 3.12+
- aiohttp >= 3.8.0

## Development

```bash
uv venv .venv && uv pip install --python .venv/bin/python -e ".[dev]"
.venv/bin/python -m pytest --cov=gkphomepython
.venv/bin/python -m mypy gkphomepython
.venv/bin/python -m build
```

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Changelog

### 0.3.0 (2026-10-15)
- `get_thermostats` returns a `ThermostatsResult`, with the thermostats and the device errors apart
- `get_thermostats` raises `GkpAuthError` and `GkpRateLimitError`, which affect the whole account
- Add `GkpMode.setpoint_adjustable`
- Export `BOOST_DURATION_MIN` and `BOOST_DURATION_MAX`

### 0.2.0 (2026-10-01)
- Add `get_thermostats` to read every thermostat of the installations
- Move the online detection and the firmware timings to the library
- Always provide a delay when the API rate limits the user
- Add `GkpRateLimitError`
- Raise `GkpRateLimitError` instead of `GkpAuthError` when the APIM quota is exceeded (403 with `Retry-After`)
- Use the Home Assistant APIM subscription key

### 0.1.0 (2026-09-30)
- Initial release
- OAuth2 authentication support
- Installation discovery and thermostat control
