Metadata-Version: 2.3
Name: homecom_alt
Version: 1.6.4
Summary: Python wrapper for controlling devices managed by HomeCom Easy APP.
Author: serbanb11
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Typing :: Typed
Requires-Dist: aiohttp>=3.9.4
Requires-Dist: pyjwt>=2.1.0
Requires-Dist: tenacity
Requires-Python: >=3.12
Project-URL: Homepage, https://github.com/serbanb11/homecom_alt
Description-Content-Type: text/markdown

# homecom-alt

[![PyPI version](https://img.shields.io/pypi/v/homecom_alt)](https://pypi.org/project/homecom_alt/)
[![Python](https://img.shields.io/pypi/pyversions/homecom_alt)](https://pypi.org/project/homecom_alt/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

Async Python wrapper for controlling Bosch Thermotechnology devices managed by the **HomeCom Easy** app. Communicates with the `pointt-api.bosch-thermotechnology.com` REST API using OAuth2 (SingleKey ID) authentication.

## Installation

```bash
pip install homecom_alt
```

## Device support

| Device type | Class | Data model |
|---|---|---|
| `rac` | `HomeComRac` | `BHCDeviceRac` |
| `k40` / `k30` | `HomeComK40` | `BHCDeviceK40` |
| `icom` | `HomeComIcom` | `BHCDeviceIcom` |
| `rrc2` | `HomeComRrc2` | `BHCDeviceRrc2` |
| `wddw2` | `HomeComWddw2` | `BHCDeviceWddw2` |
| `commodule` | `HomeComCommodule` | `BHCDeviceCommodule` |
| `generic` | `HomeComGeneric` | `BHCDeviceGeneric` |

## Authentication

`ConnectionOptions` supports two auth flows:

- **OAuth2 code flow** (recommended): provide `username` and `code` obtained from the SingleKey ID authorization endpoint, and set `auth_provider=True` when calling `HomeComAlt.create()`.
- **Token reuse**: provide an existing `token` and optionally `refresh_token` to skip the login step.

The `brand` field defaults to `"bosch"` — use `"buderus"` for Buderus-branded devices.

## Usage

See [example.py](example.py) for a full working example.

## Error handling

| Exception | Raised when |
|---|---|
| `AuthFailedError` | OAuth2 authentication fails |
| `ApiError` | API returns an error response |
| `NotRespondingError` | Device does not respond (retried up to 5 times with exponential backoff) |
| `InvalidSensorDataError` | Sensor data cannot be parsed |

All exceptions inherit from `BhcError`.

## Development

[uv](https://docs.astral.sh/uv/) is required. Install it once, then:

```bash
git clone https://github.com/serbanb11/homecom_alt.git
cd homecom_alt
uv sync --group dev
uv run pre-commit install
```

Run the checks:

```bash
uv run pytest --timeout=30 --cov=homecom_alt tests/   # tests
uv run ruff check . && uv run ruff format --check .   # lint
uv run mypy homecom_alt                               # types
```

## License

MIT
