pydanfossally 1.0.4

Danfoss Ally API library

Danfoss Ally API

Async-first Python client for the Danfoss Ally OpenAPI.

Installation

pip install pydanfossally

Local development

For local development with Poetry and VS Code debugging, this repository is configured to use an in-project virtual environment at .venv.

poetry install
poetry run python example.py

If you already created a Poetry environment before this setting was added, recreate it once so Poetry installs dependencies into .venv for this repository.

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=5,
    refresh_device_min_interval=0.10,
    device_discovery_interval=3600,
    user_agent_prefix="HomeAssistant-DanfossAlly/2026.3.0",
)

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=5,
        refresh_device_min_interval=0.10,
        device_discovery_interval=3600,
        user_agent_prefix="HomeAssistant-DanfossAlly/2026.3.0",
    ) 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 keeps refresh_device() on the near-realtime GET /ally/devices/{device_id} endpoint. Bulk discovery through GET /ally/devices is used when the cache is empty and then again on a slower periodic interval so newly added devices can be discovered.

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
• device_discovery_interval controls how often the bulk /ally/devices endpoint is used to discover newly added devices

User-Agent

By default, the client sends a User-Agent header in the form pydanfossally/<version>. Integrations can prepend their own identifier through user_agent_prefix, resulting in a final header such as HomeAssistant-DanfossAlly/2026.3.0 pydanfossally/<version>.

Local verification

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