pydanfossally 1.0.2

Danfoss Ally API library

Danfoss Ally API

Async-first Python client for the Danfoss Ally OpenAPI.

Installation

pip install pydanfossally

Async usage

Long-lived client

This is the recommended pattern for smart-home systems and other integrations that keep one client alive and reuse it across many calls.

from pydanfossally import DanfossAlly

ally = DanfossAlly(
    timeout=30,
    refresh_device_concurrency=2,
    refresh_device_min_interval=0.35,
    refresh_device_timeout=600,
)

authorized = await ally.initialize(key, secret)
if not authorized:
    raise RuntimeError("Authorization failed")

devices = await ally.get_devices()
print(devices)

await ally.aclose()

Context-managed client

This is a good fit for small scripts, one-off tools, and examples where you want automatic resource cleanup.

import asyncio
import os

from pydanfossally import DanfossAlly


async def main() -> None:
    async with DanfossAlly(
        timeout=30,
        refresh_device_concurrency=2,
        refresh_device_min_interval=0.35,
        refresh_device_timeout=600,
    ) as ally:
        authorized = await ally.initialize(os.environ["KEY"], os.environ["SECRET"])
        if not authorized:
            raise RuntimeError("Authorization failed")

        devices = await ally.get_devices()
        print(devices)


asyncio.run(main())

Supported OpenAPI endpoints

• POST /oauth2/token
• GET /ally/devices
• GET /ally/devices/{device_id}
• GET /ally/devices/{device_id}/sub-devices
• GET /ally/devices/{device_id}/status
• POST /ally/devices/{device_id}/commands

Notes about the data model

The transport layer follows the OpenAPI file in docs/openapi-spec.

The parsed devices mapping is a best-effort convenience model built from observed status codes. The OpenAPI file documents generic {code, value} pairs, but it does not define all device-specific status or command codes. That means:

• request/response transport compatibility is covered by the library
• friendly parsed fields are based on current observed API behavior
• some status fields may vary between device types

Known gaps

• The OpenAPI file does not fully document which command code values are supported for all device types.
• The POST /commands response shape is inconsistent between schema and examples; this client accepts both {"result": true, "t": ...} and {"t": ...}.
• Live verification should be performed against read-only endpoints before enabling write flows in production integrations.

Refresh behavior

The library uses GET /ally/devices as its baseline refresh path. After a successful local write, the affected device temporarily stays on the near-realtime GET /ally/devices/{device_id} endpoint until the bulk endpoint reflects the written fields or a timeout is reached.

Both knobs are configurable through DanfossAlly(...):

• refresh_device_concurrency controls how many per-device refreshes may run at once
• refresh_device_min_interval controls the minimum delay in seconds between starting two per-device refreshes
• refresh_device_timeout controls how long a written device may stay on per-device refresh before the client falls back to the bulk endpoint only

Local verification

The repository includes test.py as a small async read-only example that uses credentials from the environment.