Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 19 additions & 2 deletions pyhilo/api.py
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@

import asyncio
import base64
from collections.abc import Mapping
from datetime import datetime, timedelta
import json
import random
Expand Down Expand Up @@ -48,6 +49,20 @@
from pyhilo.signalr import SignalRHub, SignalRManager
from pyhilo.util.state import AndroidDeviceDict, StateDict, get_state, set_state

_TRACE_REDACTED_KEYS = frozenset(
{"authorization", "ocp-apim-subscription-key", "accesstoken"}
)


def _redact_trace(values: object) -> object:
"""Mask credentials so users can share trace logs when reporting issues."""
if not isinstance(values, Mapping):
return values
return {
key: "***" if str(key).lower() in _TRACE_REDACTED_KEYS else value
for key, value in values.items()
}


class API:
"""An API object to interact with the Hilo cloud.
Expand Down Expand Up @@ -288,7 +303,7 @@ async def _async_request(
data: dict[str, Any] = {}
url = parse.urljoin(f"https://{host}", endpoint)
if self.log_traces:
LOG.debug("[TRACE] Headers: %s", kwargs["headers"])
LOG.debug("[TRACE] Headers: %s", _redact_trace(kwargs["headers"]))
LOG.debug("[TRACE] Async request: %s %s", method, url)

async with self.session.request(method, url, **kwargs) as resp:
Expand All @@ -302,7 +317,9 @@ async def _async_request(
else:
data = {"message": await resp.text()}
if self.log_traces:
LOG.debug("[TRACE] Data received from /%s: %s", endpoint, data)
LOG.debug(
"[TRACE] Data received from /%s: %s", endpoint, _redact_trace(data)
)
resp.raise_for_status()
return data

Expand Down
59 changes: 57 additions & 2 deletions pyhilo/event.py
Original file line number Diff line number Diff line change
Expand Up @@ -3,13 +3,22 @@
from datetime import datetime, timedelta, timezone
import logging
import re
from typing import Any, cast
from typing import Any, TypedDict, cast

from pyhilo.util import camel_to_snake, from_utc_timestamp

LOG = logging.getLogger(__package__)


class OptOutDevice(TypedDict):
"""A device leaving Hilo's control, e.g. when its setpoint is changed during an event."""

id: int
eventDateUtc: str
triggerTypeId: int
triggerApplicationId: int | None


class Event:
"""This class is used to populate the data of a Hilo Challenge Event, contains datetime info and consumption data"""

Expand Down Expand Up @@ -38,7 +47,11 @@ def __init__(self, **event: dict[str, Any]):
self.period: str = (cast(str, event.get("period", "")) or "").lower()
self.event_id: int = cast(int, event["id"])
self.total_devices: int = len(devices)
self.opt_out_devices: int = len([x for x in devices if x["optOut"]])
self._opt_out_device_ids: set[int] = {x["id"] for x in devices if x["optOut"]}
self.opt_out_devices: int = 0
self._record_opt_outs(
cast(list[OptOutDevice], event.get("optOutDevices") or [])
)
self.pre_heat_devices: int = len([x for x in devices if x["preheat"]])
self.progress: str = cast(str, event.get("progress", "unknown"))
self.mode: str = cast(str, params.get("mode", "Unknown"))
Expand Down Expand Up @@ -68,6 +81,48 @@ def __init__(self, **event: dict[str, Any]):
"reward",
]

def update(self, data: dict[str, Any]) -> None:
"""Update the event in place from a partial Hilo message.

Hilo sends partial updates: a field it isn't changing is either
missing or None (an opt-out notice carries only the opted-out
devices, with progress, parameters, etc. set to None). Only the
fields that carry a value are applied; everything else keeps its
current value. Consumption progress arrives in separate messages
handled by update_wh().
"""
if (phases := data.get("phases")) is not None:
self._convert_phases(phases)
if (progress := data.get("progress")) is not None:
self.progress = progress
if (participating := data.get("isParticipating")) is not None:
self.participating = participating
if (configurable := data.get("isConfigurable")) is not None:
self.configurable = configurable
if (period := data.get("period")) is not None:
self.period = period.lower()
if (params := data.get("parameters")) is not None:
devices: list[dict[str, Any]] = params.get("devices", [])
self.total_devices = len(devices)
self._opt_out_device_ids.update(x["id"] for x in devices if x["optOut"])
self.pre_heat_devices = len([x for x in devices if x["preheat"]])
self.mode = params.get("mode", self.mode)
self._record_opt_outs(data.get("optOutDevices") or [])
if (reward := data.get("reward")) is not None:
self.reward = reward
consumption: dict[str, Any] = data.get("consumption") or {}
# Hilo reports a baseline of 0 until it has computed one; skip it so
# a known baseline is never wiped.
if allowed_wH := consumption.get("baselineWh"):
self.update_allowed_wh(allowed_wH)
self.last_update = datetime.now(timezone.utc).astimezone()

def _record_opt_outs(self, opt_outs: list[OptOutDevice]) -> None:
# Hilo emits an entry each time a device is taken over, so the same
# device can appear many times; count each device once.
self._opt_out_device_ids.update(x["id"] for x in opt_outs)
self.opt_out_devices = len(self._opt_out_device_ids)

def update_wh(self, used_wH: float) -> None:
"""This function is used to update the used_kWh attribute during a Hilo Challenge Event"""
LOG.debug("Updating Wh: %s", used_wH)
Expand Down
37 changes: 36 additions & 1 deletion tests/test_api_auth.py
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
import pytest

from pyhilo import API, AbstractAuth
from pyhilo.const import API_HOSTNAME
from pyhilo.const import API_HOSTNAME, SUBSCRIPTION_KEY

URN = "urn:hilo:crm:abc-123"

Expand Down Expand Up @@ -133,3 +133,38 @@ async def test_deprecated_oauth_session_still_works(
assert await api.async_get_access_token() == TOKEN
oauth_session.async_ensure_token_valid.assert_awaited_once()
assert api.urn == URN


@pytest.mark.parametrize(
"secret",
[
pytest.param(TOKEN, id="bearer_token"),
pytest.param(SUBSCRIPTION_KEY, id="subscription_key"),
],
)
async def test_trace_logs_redact_request_credentials(
mock_session: MagicMock, caplog: pytest.LogCaptureFixture, secret: str
) -> None:
auth = AsyncMock(spec=AbstractAuth)
auth.async_get_access_token.return_value = TOKEN
api = API(session=mock_session, auth=auth, log_traces=True)

with caplog.at_level(logging.DEBUG):
await api._async_request("get", "/endpoint")

assert secret not in caplog.text


async def test_trace_logs_redact_signalr_negotiate_token(
mock_session: MagicMock, caplog: pytest.LogCaptureFixture
) -> None:
response = mock_session.request.return_value.__aenter__.return_value
response.json.return_value = {"url": "https://hub", "accessToken": "hub-token"}
auth = AsyncMock(spec=AbstractAuth)
auth.async_get_access_token.return_value = TOKEN
api = API(session=mock_session, auth=auth, log_traces=True)

with caplog.at_level(logging.DEBUG):
await api._async_request("post", "/DeviceHub/negotiate")

assert "hub-token" not in caplog.text
179 changes: 179 additions & 0 deletions tests/test_event.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,179 @@
"""Tests for Event updates, using message shapes captured from a real Hilo event."""

import pytest

from pyhilo.event import Event, OptOutDevice

EVENT_ID = 101
THERMOSTAT_A = 1001
THERMOSTAT_B = 1002
CHARGER = 2001


def _device(device_id: int, opt_out: bool = False) -> dict[str, object]:
return {
"id": device_id,
"deviceUid": f"uid-{device_id}",
"deviceType": "Thermostat",
"name": f"Device {device_id}",
"roomName": "Room",
"optOut": opt_out,
"preheat": False,
}


def _initial_message(
devices: list[dict[str, object]], baseline_wh: float = 0.0
) -> dict[str, object]:
"""Shape of ChallengeDetailsInitialValuesReceived."""
return {
"id": EVENT_ID,
"progress": "scheduled",
"isParticipating": True,
"isConfigurable": False,
"period": "PM",
"phases": {
"settingsDeadlineUTC": "2026-11-17T05:00:00Z",
"preheatStartDateUTC": "2026-11-17T19:00:00Z",
"preheatEndDateUTC": "2026-11-17T21:00:00Z",
"reductionStartDateUTC": "2026-11-17T21:00:00Z",
"reductionEndDateUTC": "2026-11-18T01:00:00Z",
"recoveryStartDateUTC": "2026-11-18T01:00:00Z",
"recoveryEndDateUTC": "2026-11-18T02:00:00Z",
},
"parameters": {"mode": "Extreme", "devices": devices},
"consumption": {"baselineWh": baseline_wh},
"optOutDevices": [],
}


def _opt_out(device_id: int, trigger_type_id: int = 3) -> OptOutDevice:
return {
"id": device_id,
"eventDateUtc": "2026-11-17T21:00:00.4189642Z",
"triggerTypeId": trigger_type_id,
"triggerApplicationId": 1 if trigger_type_id == 3 else None,
}


def _opt_out_notice(*opt_outs: OptOutDevice) -> dict[str, object]:
"""Shape of ChallengeDetailsUpdatedValuesReceived: everything but the opt-outs is None."""
return {
"id": EVENT_ID,
"progress": None,
"isParticipating": None,
"isConfigurable": None,
"currentPhase": None,
"parameters": None,
"report": None,
"optOutDevices": list(opt_outs),
}


def _event(devices: list[dict[str, object]] | None = None) -> Event:
devices = (
devices
if devices is not None
else [_device(THERMOSTAT_A), _device(THERMOSTAT_B), _device(CHARGER)]
)
return Event(**_initial_message(devices))


@pytest.mark.parametrize(
("devices", "expected"),
[
pytest.param([_device(THERMOSTAT_A)], 0, id="none_opted_out"),
pytest.param(
[_device(THERMOSTAT_A, opt_out=True), _device(THERMOSTAT_B)],
1,
id="one_flagged",
),
],
)
def test_initial_opt_out_count_comes_from_device_flags(
devices: list[dict[str, object]], expected: int
) -> None:
assert _event(devices).opt_out_devices == expected


@pytest.mark.parametrize(
("notices", "expected"),
[
pytest.param([[_opt_out(THERMOSTAT_A)]], 1, id="single_notice"),
pytest.param(
[[_opt_out(THERMOSTAT_A)], [_opt_out(THERMOSTAT_A, trigger_type_id=1)]],
1,
id="same_device_repeated",
),
pytest.param(
[[_opt_out(THERMOSTAT_A)], [_opt_out(THERMOSTAT_B)]],
2,
id="distinct_devices",
),
pytest.param(
[[_opt_out(THERMOSTAT_A), _opt_out(THERMOSTAT_B)]],
2,
id="several_in_one_notice",
),
],
)
def test_opt_out_notices_count_each_device_once(
notices: list[list[OptOutDevice]], expected: int
) -> None:
event = _event()

for opt_outs in notices:
event.update(_opt_out_notice(*opt_outs))

assert event.opt_out_devices == expected


def test_opt_out_notice_and_device_flag_for_same_device_count_once() -> None:
event = _event([_device(THERMOSTAT_A, opt_out=True), _device(THERMOSTAT_B)])

event.update(_opt_out_notice(_opt_out(THERMOSTAT_A)))

assert event.opt_out_devices == 1


@pytest.mark.parametrize(
("attribute", "expected"),
[
pytest.param("progress", "scheduled", id="progress"),
pytest.param("participating", True, id="participating"),
pytest.param("total_devices", 3, id="total_devices"),
pytest.param("mode", "Extreme", id="mode"),
pytest.param("period", "pm", id="period"),
],
)
def test_opt_out_notice_keeps_other_fields(attribute: str, expected: object) -> None:
event = _event()

event.update(_opt_out_notice(_opt_out(THERMOSTAT_A)))

assert getattr(event, attribute) == expected


@pytest.mark.parametrize(
("baseline_wh", "expected_kwh"),
[
pytest.param(0.0, 14.76, id="zero_before_baseline_is_computed"),
pytest.param(14777.26, 14.78, id="revised_baseline"),
],
)
def test_update_baseline(baseline_wh: float, expected_kwh: float) -> None:
event = _event()
event.update_allowed_wh(14762.21)

event.update({"id": EVENT_ID, "consumption": {"baselineWh": baseline_wh}})

assert event.allowed_kWh == expected_kwh


def test_update_leaves_used_wh_to_consumption_messages() -> None:
event = _event()
event.update_wh(5987.98)

event.update({"id": EVENT_ID, "consumption": {"currentWh": 0.0}})

assert event.used_kWh == 5.99