evohome-async 1.2.0

An async client for connecting to Honeywell's TCC RESTful API.

evohome-async

Python client to asynchronously access the Total Connect Comfort 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 for US-based systems
• it provides Evohome support for Home Assistant and other automation platforms

NOTE: the TCC API available to this library does not currently support cooling.

This client requires the aiohttp library. If you prefer a non-async client, evohome-client uses requests instead.

CLI for schedules (currently WIP)

To install a basic CLI:

pip install 'evohome-async[cli]'

evo-client --help

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

evo-client -u [e-mail] -p password get-schedules --loc-idx 2 > schedules.json

... and to restore:

evo-client -u [e-mail] -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 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...

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

evo = EvohomeClient(token_manager)
await evo.update()

...

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

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)

TIP: the non-async documentation (from evohome-client) is available at http://evohome-client.readthedocs.org/en/latest/

---

Development

Prerequisites

• Python 3.13.2+ (on *nix recommended, use WSL on Windows)
• uv (recommended) or pip

Setup

Clone the repository and set up your development environment (using uv):

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

# Create virtual environment and install dependencies
uv venv --python 3.13  # or: python3.13 -m venv venv
source .venv/bin/activate

uv pip install -e '.[cli,dev]'

prek install  # install pre-commit git hooks

Running tests and linting

# Run linting
ruff check .
ruff format --check .

# Run type checking
mypy

# Run tests
pytest --cov=src --cov-report=term-missing  # --log-cli-level=DEBUG

# Run pre-commit hooks (includes ruff)
prek run --all-files