Metadata-Version: 2.5
Name: evohome-async
Version: 3.3.0
Summary: An async client for Resideo's TCC v1 and v2 APIs.
Project-URL: Homepage, https://github.com/zxdavb/evohome-async
Project-URL: Bug Tracker, https://github.com/zxdavb/evohome-async/issues
Project-URL: Wiki, https://github.com/zxdavb/evohome-async/wiki
Author-email: David Bonnes <zxdavb@bonnes.me>
Maintainer-email: David Bonnes <zxdavb@bonnes.me>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: evohome,honeywell,resideo,round thermostat,tcc,vision pro
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Topic :: Home Automation
Requires-Python: >=3.13
Requires-Dist: aiohttp>=3.14.5
Requires-Dist: aiozoneinfo>=0.2.3
Requires-Dist: probatio>=0.13.0
Provides-Extra: cli
Requires-Dist: aiofiles>=25.1.0; extra == 'cli'
Requires-Dist: asyncclick>=8.4.2.1; extra == 'cli'
Requires-Dist: debugpy>=1.8.22; extra == 'cli'
Requires-Dist: keyring>=25.7.0; extra == 'cli'
Provides-Extra: dev
Requires-Dist: hatch>=1.18.2; extra == 'dev'
Requires-Dist: mypy>=2.4.1; extra == 'dev'
Requires-Dist: prek>=0.5.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=1.4.1.post1; extra == 'dev'
Requires-Dist: pytest-cov>=7.1.0; extra == 'dev'
Requires-Dist: pytest-freezer>=0.4.9; extra == 'dev'
Requires-Dist: pytest-sugar>=1.1.1; extra == 'dev'
Requires-Dist: pytest-xdist>=3.8.0; extra == 'dev'
Requires-Dist: pytest>=9.2.0; extra == 'dev'
Requires-Dist: pyyaml>=6.0.3; extra == 'dev'
Requires-Dist: ruff>=0.17.4; extra == 'dev'
Requires-Dist: syrupy>=6.1.1; extra == 'dev'
Requires-Dist: types-aiofiles>=25.1.0.20261107; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0.12.20261103; extra == 'dev'
Description-Content-Type: text/markdown

# evohome-async

![ruff](https://github.com/zxdavb/evohome-async/actions/workflows/check-lint.yml/badge.svg)
![mypy](https://github.com/zxdavb/evohome-async/actions/workflows/check-type.yml/badge.svg)
![pytest](https://github.com/zxdavb/evohome-async/actions/workflows/check-tests.yml/badge.svg)
![PyPI](https://img.shields.io/pypi/v/evohome-async?label=pypi%20package)
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/evohome-async)
![PyPI - Downloads](https://img.shields.io/pypi/dm/evohome-async)
![License](https://img.shields.io/pypi/l/evohome-async)

Python client to asynchronously access the [Total Connect Comfort](https://international.mytotalconnectcomfort.com/Account/Login) RESTful API.

It provides support for Resideo TCC-based systems, such as **Evohome**, **Round Thermostat**, **VisionPro** and others:

- it supports _only_ EU/EMEA-based systems, please use (e.g.) [somecomfort](https://github.com/mkmer/AIOSomecomfort) for US-based systems
- it provides Evohome support for [Home Assistant](https://www.home-assistant.io/integrations/evohome) and other automation platforms

> **NOTE:** the vendor API available to this library does not currently support cooling.

This client _requires_ the [aiohttp](https://pypi.org/project/aiohttp/) library. If you prefer a non-async client, [evohome-client](https://github.com/watchforstock/evohome-client) uses [requests](https://pypi.org/project/requests/) instead.

## CLI for schedules (currently WIP)

To install a basic CLI:

```bash
pip install 'evohome-async[cli]'

evo-client --help
```

For example, to backup schedules (including DHW, if any):

```bash
evo-client -u username@gmail.com -p password get-schedules --loc-idx 2 > schedules.json
```

... and to restore:

```bash
evo-client -u username@gmail.com -p password set-schedules --loc-idx 2 -f schedules.json
```

To avoid exceeding the vendor's API rate limit, it will restore the access token cache, unless you use the `--no-load-tokens` switch.

> **NOTE:** the client may save your access tokens to **.evo-cache.tmp**: this presents a small security concern.

## Example code

```python
websession = aiohttp.ClientSession()
token_manager = TokenManager(username, password, websession)
await token_manager.load_access_token()

evo = EvohomeClient(token_manager)
await evo.setup()  # usually only once: gets the config of the user's locations

loc = evo.locations[0]
await loc.get_status()  # e.g. every few minutes: gets the status of this location

comm_task = await loc.gateways[0].systems[0].set_mode(SystemMode.AUTO)
await comm_task.wait()  # until the system has the change (raises CommTaskFailedError if not)

await token_manager.save_access_token()
await websession.close()
```

## The vendor's rate limits

The vendor limits only **authentication**: requests made with a valid access token or session ID (e.g. getting a location's status) have not been rate-limited, even at many per second. In particular:

- a few **password** logins in quick succession (a v2 access token via the user's username/password, or a v1 session ID) are refused with a `429 Too Many Requests`: sometimes after as few as one or two, as the allowance takes hours to recover after earlier logins
- **refreshing** a v2 access token (via its refresh token) has not been limited, even while password logins were being refused
- the vendor's 429s have no `Retry-After` header, so `AuthRateLimitExceededError.retry_after` is a default of 15 minutes; a lockout usually lifts within 5 minutes, but has lasted longer than 10

So, save the access token (and refresh token) or session ID, and load it when you start, rather than logging in with the password each time (as in the example above, and as the CLI does), and wait `retry_after` seconds after a 429 before logging in again.

## Differences from non-async version

It is loosely based upon <https://github.com/watchforstock/evohome-client>, but async-aware.

The difference between the **evohome-async** and **evohome-client** libraries are significant, but it should be relatively straightforward to port your code over to this async library should you wish.

For example, entity ID attrs are `.id` and no longer `.dhwId`, `zoneId`, etc.

Other differences include (but are not limited to):

- namespace is refactored (simpler), and attrs are `snake_case` rather than `camelCase`
- all datetimes are now TZ-aware internally, and exposed as such
- can import schedule JSON by name as well as by zone/dhw id
- newer API exposes a **TokenManager** class (for authentication) and an **Auth** class (for authorization)
- older API exposes a **SessionManager** (for authentication) and an **Auth** class (for authorization)
- exceptions are parochial (e.g. `AuthenticationFailedError`) rather than generic (`TypeError`)
- improved logging: better error messages when things do go wrong
- additional logging: e.g. logs a warning for any active faults
- is now fully typed, including TypedDicts and py.typed
- uses best of class linting/typing via **ruff**/**mypy**
- more extensive testing via **pytest**
- (WIP) extended compatibility beyond pure evohome systems (e.g. VisionPro)

---

## Development

This is how to set up a development environment.

### Prerequisites

- Python 3.14 for local dev (HA stable requires 3.14); CI also tests the version before HA's, and the next one once it is released
- [uv](https://docs.astral.sh/uv/)

### Setup

```bash
git clone https://github.com/zxdavb/evohome-async
cd evohome-async

uv sync --all-extras  # creates .venv/ Python pinned via .python-version

prek install  # install pre-commit git hooks
```

### Running tests and linting

```bash
source .venv/bin/activate

ruff check .
ruff format --check .
mypy
pytest --cov=src --cov-report=term-missing
prek run --all-files  # all pre-commit hooks
```

Alternatively, prefix each command with `uv run` to skip activation.
