vi-api-client 6.1.1__py3-none-any.whl

vi_api_client/__init__.py

@@ -0,0 +1,74 @@
+"""Viessmann API Client."""
+
+import logging
+
+from ._types import FeatureValue, JsonValue, ValidationDetail
+from .auth import AbstractAuth, OAuth
+from .client import ViClient
+from .const import DEFAULT_SCOPES, ENDPOINT_AUTHORIZE, ENDPOINT_TOKEN
+from .exceptions import (
+    ViAuthError,
+    ViConnectionError,
+    ViError,
+    ViNotFoundError,
+    ViRateLimitError,
+    ViResponseError,
+    ViServerInternalError,
+    ViValidationError,
+)
+from .fixture_client import FixtureViClient
+from .models import (
+    CommandResponse,
+    Device,
+    EventHistoryPage,
+    Feature,
+    FeatureControl,
+    Gateway,
+    GatewayDeviceRefreshResult,
+    Installation,
+    InstallationEvent,
+    ScheduleConstraints,
+)
+from .privacy import redact_device, redact_feature, redact_sensitive
+from .utils import format_feature
+from .validation import validate_json_value
+
+# Library best practice: consume the package logger without requiring
+# consumer-side logging configuration.
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+
+__all__ = [
+    "DEFAULT_SCOPES",
+    "ENDPOINT_AUTHORIZE",
+    "ENDPOINT_TOKEN",
+    "AbstractAuth",
+    "CommandResponse",
+    "Device",
+    "EventHistoryPage",
+    "Feature",
+    "FeatureControl",
+    "FeatureValue",
+    "FixtureViClient",
+    "Gateway",
+    "GatewayDeviceRefreshResult",
+    "Installation",
+    "InstallationEvent",
+    "JsonValue",
+    "OAuth",
+    "ScheduleConstraints",
+    "ValidationDetail",
+    "ViAuthError",
+    "ViClient",
+    "ViConnectionError",
+    "ViError",
+    "ViNotFoundError",
+    "ViRateLimitError",
+    "ViResponseError",
+    "ViServerInternalError",
+    "ViValidationError",
+    "format_feature",
+    "redact_device",
+    "redact_feature",
+    "redact_sensitive",
+    "validate_json_value",
+]

vi_api_client/_adapter.py

@@ -0,0 +1,321 @@
+"""Private API adapters for live and fixture-backed client workflows."""
+
+import logging
+import math
+from collections.abc import Mapping
+from datetime import UTC, datetime
+from email.utils import parsedate_to_datetime
+from typing import Any, Protocol, cast
+from urllib.parse import urljoin
+
+import aiohttp
+
+from ._types import JsonValue, ValidationDetail
+from .auth import AbstractAuth
+from .const import (
+    API_BASE_URL,
+    ENDPOINT_EVENT_HISTORY,
+    ENDPOINT_FEATURES,
+    ENDPOINT_GATEWAYS,
+    ENDPOINT_INSTALLATIONS,
+)
+from .exceptions import (
+    ViAuthError,
+    ViConnectionError,
+    ViError,
+    ViNotFoundError,
+    ViRateLimitError,
+    ViResponseError,
+    ViServerInternalError,
+    ViValidationError,
+)
+from .models import Device, FeatureControl
+from .privacy import redact_sensitive
+from .validation import validate_json_value
+
+_LOGGER = logging.getLogger(__name__)
+
+# Failures while reading a response body after its headers arrived: the
+# request was not completed, unlike a complete body that is not valid JSON.
+_BODY_READ_ERRORS = (
+    TimeoutError,
+    aiohttp.ClientConnectionError,
+    aiohttp.ClientPayloadError,
+)
+
+
+class DiscoveryAdapter(Protocol):
+    """Return raw API responses; `ViClient` turns them into models.
+
+    Kept separate from `CommandAdapter` so fixture adapters and test doubles
+    implement only the role they exercise; `LiveAdapter` fulfills both.
+    """
+
+    async def get_installations(self) -> object: ...
+
+    async def get_gateways(self) -> object: ...
+
+    async def get_devices(
+        self, installation_id: str, gateway_serial: str
+    ) -> object: ...
+
+    async def get_features(
+        self, device: Device, payload: dict[str, bool]
+    ) -> object: ...
+
+    async def get_gateway_features(
+        self, installation_id: str, gateway_serial: str, payload: dict[str, bool]
+    ) -> object: ...
+
+    async def get_event_history(
+        self, installation_id: str, params: dict[str, int | str]
+    ) -> object: ...
+
+
+class CommandAdapter(Protocol):
+    """Execute feature commands without constructing domain objects.
+
+    Kept separate from `DiscoveryAdapter` so command-focused test doubles do
+    not need to stub discovery methods.
+    """
+
+    async def execute_command(
+        self, control: FeatureControl, parameters: dict[str, JsonValue]
+    ) -> object: ...
+
+
+class LiveAdapter:
+    """Return raw live API responses through an authenticated request provider."""
+
+    def __init__(self, auth: AbstractAuth) -> None:
+        """Initialize the adapter with the request provider."""
+        self._auth = auth
+
+    async def get_installations(self) -> object:
+        """Return the raw installations API response."""
+        return await self._request("GET", ENDPOINT_INSTALLATIONS)
+
+    async def get_gateways(self) -> object:
+        """Return the raw gateways API response."""
+        return await self._request("GET", ENDPOINT_GATEWAYS)
+
+    async def get_devices(self, installation_id: str, gateway_serial: str) -> object:
+        """Return the raw devices API response."""
+        return await self._request(
+            "GET",
+            f"{ENDPOINT_INSTALLATIONS}/{installation_id}/gateways/"
+            f"{gateway_serial}/devices",
+        )
+
+    async def get_features(self, device: Device, payload: dict[str, bool]) -> object:
+        """Return the raw feature API response for one device."""
+        return await self._request(
+            "POST",
+            f"{ENDPOINT_FEATURES}/{device.installation_id}/gateways/"
+            f"{device.gateway_serial}/devices/{device.id}/features/filter",
+            json=payload,
+        )
+
+    async def get_gateway_features(
+        self, installation_id: str, gateway_serial: str, payload: dict[str, bool]
+    ) -> object:
+        """Return the raw gateway-scoped feature API response."""
+        return await self._request(
+            "POST",
+            f"{ENDPOINT_FEATURES}/{installation_id}/gateways/"
+            f"{gateway_serial}/features/filter",
+            json=payload,
+        )
+
+    async def get_event_history(
+        self, installation_id: str, params: dict[str, int | str]
+    ) -> object:
+        """Return one raw event history API response."""
+        return await self._request(
+            "GET",
+            f"{ENDPOINT_EVENT_HISTORY}/{installation_id}/events",
+            params=params,
+        )
+
+    async def execute_command(
+        self, control: FeatureControl, parameters: dict[str, JsonValue]
+    ) -> object:
+        """Return the raw command API response."""
+        return await self._request("POST", control.uri, json=parameters)
+
+    async def _request(
+        self,
+        method: str,
+        url: str,
+        *,
+        params: Mapping[str, int | str] | None = None,
+        json: Mapping[str, object] | None = None,
+    ) -> object:
+        """Return the decoded JSON body of a successful response.
+
+        The body is untrusted JSON of any shape; callers validate it.
+
+        Raises:
+            ViConnectionError: If the response body cannot be read completely.
+            ViResponseError: If the URL is outside the Vi API or a successful
+                response is not valid JSON.
+        """
+        full_url = _api_url(url)
+        _LOGGER.debug("Request: %s %s", method, redact_sensitive(full_url))
+        async with await self._auth.request(
+            method, full_url, params=params, json=json
+        ) as response:
+            await _raise_for_status(response)
+            try:
+                return await response.json()
+            except _BODY_READ_ERRORS as error:
+                raise ViConnectionError(f"Network error: {error}") from error
+            except (aiohttp.ClientError, ValueError) as error:
+                raise ViResponseError(
+                    "Successful API response was not valid JSON"
+                ) from error
+
+
+def _api_url(url: str) -> str:
+    """Return the absolute Vi API URL for an endpoint path or command URI.
+
+    Command URIs come from API responses, and every request carries the
+    bearer token, so URLs outside the Vi API are refused rather than sent.
+
+    Raises:
+        ViResponseError: If the URL does not resolve inside the Vi API.
+    """
+    full_url = urljoin(API_BASE_URL, url)
+    if not full_url.startswith(f"{API_BASE_URL}/"):
+        raise ViResponseError(
+            f"Refusing request outside the Vi API: {redact_sensitive(full_url)}"
+        )
+    return full_url
+
+
+async def _raise_for_status(response: aiohttp.ClientResponse) -> None:
+    """Raise the matching library error for an unsuccessful API response.
+
+    The HTTP status decides the exception class. The JSON error body only
+    enriches it, so a missing or non-JSON body (such as a proxy error page)
+    falls back to HTTP-level defaults instead of masking the status.
+
+    Raises:
+        ViAuthError: For 401 and 403.
+        ViNotFoundError: For 404.
+        ViRateLimitError: For 429, with parsed Retry-After guidance.
+        ViValidationError: For 400 and 422, with validated details.
+        ViServerInternalError: For 5xx.
+        ViError: For any other unsuccessful status.
+    """
+    status = response.status
+    if status < 400:
+        return
+
+    error_message = f"HTTP {status}"
+    vi_error_id: str | None = None
+    error_type: str | None = None
+    validation_details: list[ValidationDetail] = []
+    try:
+        data = await response.json()
+    except TimeoutError, aiohttp.ClientError, ValueError:
+        data = None
+    if isinstance(data, dict):
+        # The untyped aiohttp JSON boundary yields an unknown container shape;
+        # each known error field is re-narrowed and validated below.
+        error_body = cast("dict[str, Any]", data)
+        vi_error_id = _text_or_none(error_body.get("viErrorId"))
+        error_type = _text_or_none(error_body.get("errorType"))
+        message = _text_or_none(error_body.get("message"))
+        if message is not None:
+            error_message = message
+        validation_details = _parse_validation_details(
+            error_body.get("validationErrors")
+        )
+
+    # The raised library exception carries all error details, so the log
+    # stays at debug level to avoid double-reporting normal control flow.
+    _LOGGER.debug(
+        "API Error %s (%s): %s (ID: %s)",
+        status,
+        error_type,
+        error_message,
+        vi_error_id,
+    )
+    if status in (401, 403):
+        description = "Unauthorized" if status == 401 else "Forbidden"
+        raise ViAuthError(f"{description}: {error_message}", vi_error_id, error_type)
+    if status == 404:
+        raise ViNotFoundError(f"Not Found: {error_message}", vi_error_id, error_type)
+    if status == 429:
+        raise ViRateLimitError(
+            "Rate Limit Exceeded",
+            vi_error_id,
+            error_type,
+            retry_after=_parse_retry_after(response.headers.get("Retry-After")),
+        )
+    # Vi reports unreachable devices as 400 DEVICE_COMMUNICATION_ERROR;
+    # ViClient.refresh_gateway_devices relies on this mapping for its
+    # per-device fallback.
+    if status in (400, 422):
+        raise ViValidationError(
+            error_message, vi_error_id, validation_details, error_type
+        )
+    if status >= 500:
+        raise ViServerInternalError(
+            f"Server Error {status}: {error_message}", vi_error_id, error_type
+        )
+    raise ViError(f"Unknown Error {status}: {error_message}", vi_error_id, error_type)
+
+
+def _text_or_none(value: object) -> str | None:
+    """Return the value if it is text, otherwise None."""
+    return value if isinstance(value, str) else None
+
+
+def _parse_validation_details(value: object) -> list[ValidationDetail]:
+    """Return validated validation details, dropping unusable collections.
+
+    Every exposed detail is a string-keyed JSON object and unknown detail
+    fields remain allowed. A collection that violates the shape — or that
+    JSON cannot represent — is dropped entirely rather than masking the
+    HTTP error being reported.
+    """
+    try:
+        validated = validate_json_value(value, path="API validationErrors")
+    except ViResponseError:
+        return []
+    if not isinstance(validated, list) or not all(
+        isinstance(entry, dict) for entry in validated
+    ):
+        return []
+    # Every entry was runtime-checked as a validated JSON object above.
+    return cast("list[ValidationDetail]", validated)
+
+
+def _parse_retry_after(value: str | None) -> float | None:
+    """Return a non-negative retry duration from an HTTP Retry-After value.
+
+    The header carries either delay seconds or an HTTP-date (RFC 9110). A
+    date without a time zone is not a valid HTTP-date and cannot be compared
+    with the current UTC time, so it yields None like any unusable value. A
+    date in the past yields 0.
+    """
+    if value is None:
+        return None
+
+    try:
+        numeric_delay = float(value)
+    except ValueError:
+        pass
+    else:
+        is_valid_delay = math.isfinite(numeric_delay) and numeric_delay >= 0
+        return numeric_delay if is_valid_delay else None
+
+    try:
+        retry_at = parsedate_to_datetime(value)
+    except IndexError, TypeError, ValueError:
+        return None
+    if retry_at.tzinfo is None:
+        return None
+    return max(0.0, (retry_at - datetime.now(UTC)).total_seconds())

vi_api_client/_feature_diff.py

@@ -0,0 +1,250 @@
+"""Compare two raw API feature documents for the diff-features CLI command."""
+
+import json
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from typing import Any, cast
+
+_ARROW = "→"
+
+
+@dataclass(frozen=True)
+class FeatureDiff:
+    """The differences between a left and a right set of raw API features.
+
+    ``structure`` and ``state`` map each changed feature name to its change
+    lines, sorted by feature name.
+    """
+
+    left_count: int
+    right_count: int
+    added: list[str] = field(default_factory=list[str])
+    removed: list[str] = field(default_factory=list[str])
+    structure: dict[str, list[str]] = field(default_factory=dict[str, list[str]])
+    state: dict[str, list[str]] = field(default_factory=dict[str, list[str]])
+
+    @property
+    def has_differences(self) -> bool:
+        """Return whether any section lists a difference."""
+        return bool(self.added or self.removed or self.structure or self.state)
+
+
+def feature_entries(document: object) -> dict[str, Mapping[str, Any]]:
+    """Return a feature document's raw API features keyed by feature name.
+
+    Args:
+        document: A fixture file or device export with a ``data`` list.
+
+    Raises:
+        ValueError: If the document has no ``data`` list of features with
+            unique, non-empty names.
+    """
+    data = _as_mapping(document).get("data")
+    if not isinstance(data, list):
+        raise ValueError("A feature document must be an object with a 'data' list")
+    entries: dict[str, Mapping[str, Any]] = {}
+    for item in cast("list[object]", data):
+        entry = _as_mapping(item)
+        name = entry.get("feature")
+        if not isinstance(name, str) or not name:
+            raise ValueError("Every feature needs a non-empty 'feature' name")
+        if name in entries:
+            raise ValueError(f"Duplicate feature in document: {name}")
+        entries[name] = entry
+    return entries
+
+
+def diff_features(
+    left: Mapping[str, Mapping[str, Any]], right: Mapping[str, Mapping[str, Any]]
+) -> FeatureDiff:
+    """Compare raw API features by name without comparing their values.
+
+    Properties and commands are compared only when the feature is enabled on
+    both sides: the API returns a disabled feature without them, which is a
+    state difference rather than a structure difference.
+    """
+    diff = FeatureDiff(
+        left_count=len(left),
+        right_count=len(right),
+        added=sorted(set(right) - set(left)),
+        removed=sorted(set(left) - set(right)),
+    )
+    for name in sorted(set(left) & set(right)):
+        structure = _structure_changes(left[name], right[name])
+        if structure:
+            diff.structure[name] = structure
+        state = _state_changes(left[name], right[name])
+        if state:
+            diff.state[name] = state
+    return diff
+
+
+def format_feature_diff(
+    diff: FeatureDiff, left_label: str, right_label: str
+) -> list[str]:
+    """Return the text report of a feature comparison."""
+    lines = [
+        f"Comparing {left_label} ({diff.left_count} features) "
+        f"with {right_label} ({diff.right_count} features)"
+    ]
+    if not diff.has_differences:
+        lines.append("No differences.")
+        return lines
+    if diff.added:
+        lines.extend(["", f"Added ({len(diff.added)}):"])
+        lines.extend(f"  + {name}" for name in diff.added)
+    if diff.removed:
+        lines.extend(["", f"Removed ({len(diff.removed)}):"])
+        lines.extend(f"  - {name}" for name in diff.removed)
+    for title, changes in (
+        ("Structure changed", diff.structure),
+        ("State changed", diff.state),
+    ):
+        if changes:
+            lines.extend(["", f"{title} ({len(changes)}):"])
+            for name, change_lines in changes.items():
+                lines.append(f"  {name}")
+                lines.extend(f"    {line}" for line in change_lines)
+    return lines
+
+
+def _structure_changes(left: Mapping[str, Any], right: Mapping[str, Any]) -> list[str]:
+    """Return the property, command, and deprecation changes of one feature."""
+    changes: list[str] = []
+    if left.get("isEnabled") is True and right.get("isEnabled") is True:
+        changes.extend(
+            _property_changes(
+                _mapping(left, "properties"), _mapping(right, "properties")
+            )
+        )
+        changes.extend(
+            _command_changes(_mapping(left, "commands"), _mapping(right, "commands"))
+        )
+    if left.get("deprecated") != right.get("deprecated"):
+        changes.append(
+            f"deprecated: {_render(left.get('deprecated'))} {_ARROW} "
+            f"{_render(right.get('deprecated'))}"
+        )
+    return changes
+
+
+def _command_changes(left: Mapping[str, Any], right: Mapping[str, Any]) -> list[str]:
+    """Return added and removed commands and their parameter changes."""
+    changes = [f"+ command {name}" for name in sorted(set(right) - set(left))]
+    changes.extend(f"- command {name}" for name in sorted(set(left) - set(right)))
+    for name in sorted(set(left) & set(right)):
+        changes.extend(
+            _parameter_changes(
+                name,
+                _mapping(_as_mapping(left[name]), "params"),
+                _mapping(_as_mapping(right[name]), "params"),
+            )
+        )
+    return changes
+
+
+def _property_changes(left: Mapping[str, Any], right: Mapping[str, Any]) -> list[str]:
+    """Return added and removed properties and their type and unit changes."""
+    changes = [f"+ property {name}" for name in sorted(set(right) - set(left))]
+    changes.extend(f"- property {name}" for name in sorted(set(left) - set(right)))
+    for name in sorted(set(left) & set(right)):
+        left_property = _as_mapping(left[name])
+        right_property = _as_mapping(right[name])
+        changes.extend(
+            _field_changes(
+                f"property {name}", left_property, right_property, ("type", "unit")
+            )
+        )
+    return changes
+
+
+def _parameter_changes(
+    command: str, left: Mapping[str, Any], right: Mapping[str, Any]
+) -> list[str]:
+    """Return added and removed parameters and their contract changes."""
+    changes = [f"+ {command}.{name}" for name in sorted(set(right) - set(left))]
+    changes.extend(f"- {command}.{name}" for name in sorted(set(left) - set(right)))
+    for name in sorted(set(left) & set(right)):
+        label = f"{command}.{name}"
+        left_parameter = _as_mapping(left[name])
+        right_parameter = _as_mapping(right[name])
+        changes.extend(
+            _field_changes(label, left_parameter, right_parameter, ("type", "required"))
+        )
+        left_constraints = _mapping(left_parameter, "constraints")
+        right_constraints = _mapping(right_parameter, "constraints")
+        changes.extend(
+            _field_changes(
+                label,
+                left_constraints,
+                right_constraints,
+                sorted(set(left_constraints) | set(right_constraints)),
+            )
+        )
+    return changes
+
+
+def _state_changes(left: Mapping[str, Any], right: Mapping[str, Any]) -> list[str]:
+    """Return the enabled, ready, and command executability changes."""
+    changes = _field_changes("", left, right, ("isEnabled", "isReady"))
+    left_commands = _mapping(left, "commands")
+    right_commands = _mapping(right, "commands")
+    for name in sorted(set(left_commands) & set(right_commands)):
+        changes.extend(
+            _field_changes(
+                f"{name}.",
+                _as_mapping(left_commands[name]),
+                _as_mapping(right_commands[name]),
+                ("isExecutable",),
+            )
+        )
+    return changes
+
+
+def _field_changes(
+    label: str,
+    left: Mapping[str, Any],
+    right: Mapping[str, Any],
+    fields: Sequence[str],
+) -> list[str]:
+    """Return one ``label field: old → new`` line per differing field.
+
+    A label ending in ``.`` is joined to the field name without a space.
+    """
+    changes: list[str] = []
+    for field_name in fields:
+        left_value = left.get(field_name)
+        right_value = right.get(field_name)
+        if left_value == right_value:
+            continue
+        prefix = (
+            f"{label}{field_name}"
+            if label.endswith(".") or not label
+            else (f"{label} {field_name}")
+        )
+        if field_name not in left:
+            changes.append(f"{prefix}: + {_render(right_value)}")
+        elif field_name not in right:
+            changes.append(f"{prefix}: - {_render(left_value)}")
+        else:
+            changes.append(
+                f"{prefix}: {_render(left_value)} {_ARROW} {_render(right_value)}"
+            )
+    return changes
+
+
+def _mapping(entry: Mapping[str, Any], key: str) -> Mapping[str, Any]:
+    """Return a nested object of a raw entry, or an empty one if it is missing."""
+    return _as_mapping(entry.get(key))
+
+
+def _as_mapping(value: object) -> Mapping[str, Any]:
+    """Return a raw JSON object, or an empty one for any other value."""
+    return cast("Mapping[str, Any]", value) if isinstance(value, Mapping) else {}
+
+
+def _render(value: object) -> str:
+    """Return a compact JSON rendering of a raw value, ``none`` when absent."""
+    if value is None:
+        return "none"
+    return json.dumps(value, ensure_ascii=False, sort_keys=True)

vi_api_client/_types.py

@@ -0,0 +1,12 @@
+"""Public dynamic value contracts shared across client API boundaries."""
+
+type JsonValue = (
+    bool | int | float | str | list[JsonValue] | dict[str, JsonValue] | None
+)
+"""A recursively JSON-compatible value retaining standard Python shapes."""
+
+type FeatureValue = JsonValue
+"""The dynamic value reported by a device feature."""
+
+type ValidationDetail = dict[str, JsonValue]
+"""One dictionary-shaped API validation detail."""