python-hilo 2026.10.1__tar.gz → 2026.11.1__tar.gz

{python_hilo-2026.10.1 → python_hilo-2026.11.1}/.devcontainer/devcontainer.json

@@ -47,7 +47,7 @@
     "ghcr.io/devcontainers/features/github-cli:1": {},
     "ghcr.io/jsburckhardt/devcontainer-features/uv:1": {}
   },
-  "image": "mcr.microsoft.com/devcontainers/python:3.11-bookworm",
+  "image": "mcr.microsoft.com/devcontainers/python:3-3.14-bookworm",
   "name": "A Python3, async interface to the Hilo API",
   "postCreateCommand": "uv sync --group dev --group test && uv run pre-commit install"
 }

{python_hilo-2026.10.1 → python_hilo-2026.11.1}/.github/workflows/tests.yaml

@@ -8,7 +8,7 @@ on:
   pull_request:
 
 env:
-  DEFAULT_PYTHON: 3.13
+  DEFAULT_PYTHON: "3.14"
 
 jobs:
   pre-commit:
@@ -19,12 +19,12 @@ jobs:
         uses: actions/checkout@v7
 
       - name: Set up Python ${{ env.DEFAULT_PYTHON }}
-        uses: actions/setup-python@v7.0.0
+        uses: actions/setup-python@v7.1.0
         with:
           python-version: ${{ env.DEFAULT_PYTHON }}
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v10.2.0
+        uses: astral-sh/setup-uv@v10.3.3
 
       - name: Install dependencies
         run: uv sync --group dev
@@ -36,21 +36,25 @@ jobs:
 
   tests:
     runs-on: "ubuntu-latest"
-    name: Tests
+    name: Tests (${{ matrix.python-version }})
+    strategy:
+      matrix:
+        # Mirrors the Hilo integration, which still supports Home Assistant releases on 3.13.
+        python-version: ["3.13", "3.14"]
     steps:
       - name: Check out the repository
         uses: actions/checkout@v7
 
-      - name: Set up Python ${{ env.DEFAULT_PYTHON }}
-        uses: actions/setup-python@v7.0.0
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v7.1.0
         with:
-          python-version: ${{ env.DEFAULT_PYTHON }}
+          python-version: ${{ matrix.python-version }}
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v10.2.0
+        uses: astral-sh/setup-uv@v10.3.3
 
       - name: Install dependencies
-        run: uv sync --group test
+        run: uv sync --python ${{ matrix.python-version }} --group test
 
       - name: Run tests
-        run: uv run pytest -v
+        run: uv run --python ${{ matrix.python-version }} pytest -v

{python_hilo-2026.10.1 → python_hilo-2026.11.1}/.pre-commit-config.yaml

@@ -14,10 +14,10 @@ repos:
     hooks:
       - id: ruff-format
         args: [--quiet]
-        files: ^pyhilo/.+\.py$
+        files: ^(pyhilo|tests)/.+\.py$
       - id: ruff
         args: [--fix, --exit-non-zero-on-fix]
-        files: ^pyhilo/.+\.py$
+        files: ^(pyhilo|tests)/.+\.py$
   - repo: https://github.com/codespell-project/codespell
     rev: v2.4.1
     hooks:

python_hilo-2026.11.1/AGENTS.md

@@ -0,0 +1,56 @@
+# Coding Assistant Instructions: python-hilo Library
+
+This repository contains `pyhilo`, a standalone asynchronous Python client library for Hilo energy services (SignalR WebSocket, GraphQL, and REST APIs).
+
+## Git Commit Guidelines
+
+- **First line**: Short, specific imperative sentence (e.g. "Add abstract auth interface for token provider"). No emojis in titles.
+- **Commit description**: Focus on the **WHY** (problem, context, and architectural rationale). Keep it concise, factual, and proportional.
+- **Do NOT amend, squash, or rebase commits that have already been pushed to the PR branch after the PR is opened**: Reviewers need to follow the commit history and see what changed since their last review.
+
+## Development Commands
+
+- Install dependencies: `uv sync`
+- Run test suite: `uv run pytest`
+- Run a specific test: `uv run pytest tests/test_device.py`
+- Check linting and formatting: `uv run ruff check .` and `uv run ruff format --check .`
+
+## Architecture & Boundaries
+
+- **Strict Decoupling from Home Assistant**:
+  - This library MUST NEVER import `homeassistant` or depend on Home Assistant Core modules, constants, or types.
+  - The library must be 100% installable, testable, and runnable independently in any standard Python 3.13+ environment.
+- **Authentication Contract**:
+  - Expose an abstract base class `AbstractAuth` (`pyhilo.auth`):
+    ```python
+    class AbstractAuth(ABC):
+        @abstractmethod
+        async def async_get_access_token(self) -> str:
+            """Return a valid access token, refreshing if necessary."""
+    ```
+  - The library calls this method whenever it needs a valid token, leaving token storage and refresh mechanisms to the consumer (such as the Hilo Home Assistant integration or CLI tools).
+- **Backwards Compatibility**: When modifying public API signatures, provide temporary shims with deprecation warnings for at least 1–2 minor versions to prevent breaking downstream consumers.
+- **Credential Protection**: Never log raw access tokens, refresh tokens, passwords, or decoded JWT claims in `DEBUG` or `INFO` logs.
+
+## Testing Standards
+
+- Verify library protocol behavior, event decoding, device mapping, and error handling.
+- When writing tests or implementation code, ensure all parameters have precise type annotations. **The use of `Any` is strictly forbidden in new code.**
+- **Single purpose tests**: Each test function must verify only one specific behavior or outcome. Avoid testing multiple unrelated scenarios in a single test; split them into focused tests or use parametrization.
+- Prefer standard library `unittest.mock` (`AsyncMock`, `MagicMock`) over large bespoke stub classes.
+- Prefer `@pytest.mark.usefixtures` over unused fixture arguments.
+- Avoid branching (`if`/`else`) in tests; use `@pytest.mark.parametrize` with `pytest.param(..., id="...")` for table-driven testing.
+- Tests must execute cleanly with `uv run pytest` without requiring network access.
+
+## Good practices
+
+- Built with `asyncio`, `aiohttp`, `pysignalr`, and `gql`.
+- Non-blocking I/O: avoid any synchronous disk reads/writes on active event loops. Accept explicit file paths when managing state.
+- Keep `try` clauses as small as possible.
+- When validation guarantees a dict key exists, prefer direct key access (`data["key"]`) instead of `.get("key")`.
+- Keep comments concise and explain only the WHY. Do not restate code or use divider comments (`# --- XYZ ---`).
+- CalVer format: Versions follow `vYYYY.MM.MICRO` (e.g. `v2026.10.1`).
+
+## AI policy
+
+Autonomous contributions are not accepted. Every change must be reviewed and understood by a human contributor before submission. Never open pull requests, create release tags, or post comments autonomously without explicit contributor instruction.

{python_hilo-2026.10.1 → python_hilo-2026.11.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: python-hilo
-Version: 2026.10.1
+Version: 2026.11.1
 Summary: A Python3, async interface to the Hilo API
 Project-URL: Repository, https://github.com/dvd-dev/python-hilo
 Author-email: David Vallee Delisle <me@dvd.dev>
@@ -11,11 +11,12 @@ Classifier: Framework :: aiohttp
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy
 Classifier: Topic :: Home Automation
-Requires-Python: >=3.11
+Requires-Python: >=3.13
 Requires-Dist: aiofiles>=23.2.1
 Requires-Dist: aiohttp>=3.8.0
 Requires-Dist: backoff>=1.11.1
@@ -34,7 +35,7 @@ Description-Content-Type: text/markdown
 [![Build Status][build-shield]][build]
 [![Open in Dev Containers][devcontainer-shield]][devcontainer]
 
-`python-hilo` (aka `pyhilo`) is a Python 3.11, `asyncio`-driven interface to the unofficial
+`python-hilo` (aka `pyhilo`) is a Python 3.13+, `asyncio`-driven interface to the unofficial
 Hilo API from Hydro Quebec. This is meant to be integrated into Home Assistant but can also
 be used as a standalone library.
 
@@ -63,7 +64,7 @@ for formatting and linting.
 
 You need at least:
 
-- Python 3.11+
+- Python 3.13+
 - [uv][uv]
 
 To install all packages, including all development requirements:

{python_hilo-2026.10.1 → python_hilo-2026.11.1}/README.md

@@ -6,7 +6,7 @@
 [![Build Status][build-shield]][build]
 [![Open in Dev Containers][devcontainer-shield]][devcontainer]
 
-`python-hilo` (aka `pyhilo`) is a Python 3.11, `asyncio`-driven interface to the unofficial
+`python-hilo` (aka `pyhilo`) is a Python 3.13+, `asyncio`-driven interface to the unofficial
 Hilo API from Hydro Quebec. This is meant to be integrated into Home Assistant but can also
 be used as a standalone library.
 
@@ -35,7 +35,7 @@ for formatting and linting.
 
 You need at least:
 
-- Python 3.11+
+- Python 3.13+
 - [uv][uv]
 
 To install all packages, including all development requirements:

python_hilo-2026.11.1/doc/README.md

@@ -0,0 +1,92 @@
+# Hilo API reference payloads
+
+Captured responses from Hilo's services, grouped by transport to mirror the library modules.
+IDs, URNs and serial numbers in the payload files are anonymized.
+
+| Folder | Transport | Library module | Contents |
+|---|---|---|---|
+| [`rest/`](rest/) | HTTPS REST | `pyhilo/api.py` | Automation (`/Locations`, `/Weather`) and challenge season endpoints |
+| [`graphql/`](graphql/) | GraphQL subscription | `pyhilo/graphql.py` | `onAnyDeviceUpdated` payloads per device type |
+| [`signalr/devicehub/`](signalr/devicehub/) | SignalR WebSocket | `pyhilo/signalr.py` | DeviceHub messages |
+| [`signalr/challengehub/`](signalr/challengehub/) | SignalR WebSocket | `pyhilo/signalr.py` | ChallengeHub messages, 2025-26 season onward (CH = Winter Credits, Flex = Flex D) |
+| [`signalr/challengehub/legacy-pre-2025/`](signalr/challengehub/legacy-pre-2025/) | SignalR WebSocket | — | Challenge messages before the CH/Flex split; kept for reference |
+| [`postman/`](postman/) | — | — | Postman collection and environment for manual testing |
+
+## Adding a payload
+
+1. Strip tokens, location URNs, serial numbers and personal data before committing.
+2. Name REST files after the endpoint (`season_events_ch_2025.json`) and SignalR/GraphQL files after the message target (`EventCHDetailsInitialValuesReceived.json`).
+3. Add a short suffix for variants (`-during-event`, `-empty`, `-meter`).
+
+# Using Postman to query Hilo
+
+Import [`postman/hilo.postman_collection.json`](postman/hilo.postman_collection.json) and [`postman/hilo-prod.postman_environment.json`](postman/hilo-prod.postman_environment.json), then select the **Hilo Prod** environment.
+
+## Authentication
+
+The collection uses OAuth 2.0 at the collection level. Open the collection's **Authorization** tab, click **Get New Access Token**, log in with your Hilo credentials in the browser window, then click **Use Token**. Every request in the collection inherits that token.
+
+Tokens are short-lived and contain personally identifiable information. Do not share them or commit an exported environment that contains them.
+
+## REST requests
+
+With the access token set, the REST requests (`1-Get Locations`, `Get SeasonsSummary`, `Get CHEvents`, `Get FlexEvents`, ...) can be sent directly.
+
+## Connecting to a hub
+
+Each hub folder (`DeviceHub`, `ChallengeHub`) contains two negotiate requests. Send them in order:
+
+1. `1-API Hilo ... Hub Negotiate` stores the hub URL and hub access token in the environment (`_deviceHubUrl` / `_deviceHubAccessToken`, or `_challengeHubUrl` / `_challengeHubAccessToken`).
+2. `2-... Hub Negotiate` stores the connection token (`_deviceHubConnectionToken` or `_challengeHubConnectionToken`).
+
+Then open a new WebSocket request in Postman:
+
+1. Use the hub URL from the environment (`{{_deviceHubUrl}}` or `{{_challengeHubUrl}}`).
+2. In **Headers**, add `Authorization` with the value `Bearer {{_deviceHubAccessToken}}` (or `Bearer {{_challengeHubAccessToken}}`).
+3. Connect, then send the handshake below. The trailing record separator character `chr(30)` is required after every message.
+
+```
+{
+    "protocol": "json",
+    "version": 1
+}
+```
+
+### DeviceHub
+
+Invoke `SubscribeToLocation` with your location ID to get your device information:
+
+```
+{
+    "arguments": [
+        69420
+    ],
+    "invocationId": "0",
+    "target": "SubscribeToLocation",
+    "type": 1
+}
+```
+
+You should receive a [`DeviceListInitialValuesReceived`](signalr/devicehub/DeviceListInitialValuesReceived.json) message back.
+
+### ChallengeHub
+
+Since the 2025-2026 season and the addition of Flex D, messages are split between Winter Credits (Crédit Hivernal) and Flex D. Winter Credits targets contain `CH` and Flex D targets contain `Flex`. Each rate has its own event ID; for example, event 337 was for Winter Credits and event 338 for Flex D, both at the same time. You only have access to the one matching your rate.
+
+#### SubscribeToEventCH or SubscribeToEventFlex
+
+```
+{
+    "arguments": [
+        {
+            "locationHiloId": "urn:YOUR-URN",
+            "eventId": ID(numeric)
+        }
+    ],
+    "invocationId": "1",
+    "target": "SubscribeToEventCH",
+    "type": 1
+}
+```
+
+Returns [`EventCHDetailsInitialValuesReceived`](signalr/challengehub/EventCHDetailsInitialValuesReceived.json) or [`EventFlexDetailsInitialValuesReceived`](signalr/challengehub/EventFlexDetailsInitialValuesReceived.json).

python_hilo-2026.11.1/doc/graphql/onAnyDeviceUpdated-cee.json

@@ -0,0 +1,33 @@
+{
+  "data": {
+    "onAnyDeviceUpdated": {
+      "deviceType": "cee",
+      "locationHiloId": "urn:hilo:crm:00000-abcdef:0",
+      "transmissionTime": "2026-10-24T19:46:35.207Z",
+      "operationId": "00000000-0000-0000-0000-000000000002",
+      "status": "REPORT",
+      "device": {
+        "deviceType": "cee",
+        "hiloId": "urn:hilo:philo:4a5b6c7d8e9f0001:0",
+        "physicalAddress": "4A5B6C7D8E9F0001",
+        "connectionStatus": "CONNECTED",
+        "gDState": "EXCLUDED",
+        "version": "45",
+        "probeTemp": {
+          "value": 54,
+          "kind": "DEGREE_CELSIUS"
+        },
+        "zigbeeVersion": "45",
+        "state": "ON",
+        "ccrType": "WATER_HEATER",
+        "alerts": [
+          "0"
+        ],
+        "power": {
+          "value": 0,
+          "kind": "WATT"
+        }
+      }
+    }
+  }
+}

python_hilo-2026.11.1/doc/graphql/onAnyDeviceUpdated-meter.json

@@ -0,0 +1,22 @@
+{
+  "data": {
+    "onAnyDeviceUpdated": {
+      "deviceType": "meter",
+      "locationHiloId": "urn:hilo:crm:00000-abcdef:0",
+      "transmissionTime": "2026-10-24T19:48:54.966Z",
+      "operationId": "00000000-0000-0000-0000-000000000001",
+      "status": "REPORT",
+      "device": {
+        "deviceType": "meter",
+        "hiloId": "urn:hilo:philo:0x006baa0000000001-smart_meter:0",
+        "physicalAddress": "0x006BAA0000000001-smart_meter",
+        "connectionStatus": "CONNECTED",
+        "zigBeeChannel": 24,
+        "power": {
+          "value": 0.572,
+          "kind": "KILOWATT"
+        }
+      }
+    }
+  }
+}

python_hilo-2026.11.1/doc/graphql/onAnyDeviceUpdated-tstat.json

@@ -0,0 +1,52 @@
+{
+  "data": {
+    "onAnyDeviceUpdated": {
+      "deviceType": "tstat",
+      "locationHiloId": "urn:hilo:crm:00000-abcdef:0",
+      "transmissionTime": "2026-10-29T22:44:57.250Z",
+      "operationId": "00000000-0000-0000-0000-000000000003",
+      "status": "REPORT",
+      "device": {
+        "deviceType": "tstat",
+        "hiloId": "urn:hilo:philo:1a2b3c4d5e6f0001:0",
+        "physicalAddress": "1A2B3C4D5E6F0001",
+        "connectionStatus": "CONNECTED",
+        "ambientHumidity": 0,
+        "gDState": "EXCLUDED",
+        "version": "21",
+        "zigbeeVersion": "22",
+        "ambientTemperature": {
+          "value": 18,
+          "kind": "DEGREE_CELSIUS"
+        },
+        "ambientTempSetpoint": {
+          "value": 15,
+          "kind": "DEGREE_CELSIUS"
+        },
+        "maxAmbientTempSetpoint": {
+          "value": 30,
+          "kind": "DEGREE_CELSIUS"
+        },
+        "minAmbientTempSetpoint": {
+          "value": 5,
+          "kind": "DEGREE_CELSIUS"
+        },
+        "maxAmbientTempSetpointLimit": {
+          "value": 30,
+          "kind": "DEGREE_CELSIUS"
+        },
+        "minAmbientTempSetpointLimit": {
+          "value": 5,
+          "kind": "DEGREE_CELSIUS"
+        },
+        "heatDemand": 0,
+        "power": {
+          "value": null,
+          "kind": "WATT"
+        },
+        "mode": "UNKNOWN",
+        "allowedModes": []
+      }
+    }
+  }
+}

python_hilo-2026.11.1/doc/rest/location_weather.json

@@ -0,0 +1,7 @@
+{
+  "temperature": 10.0,
+  "time": "0001-01-01T00:00:00Z",
+  "condition": "Clear",
+  "icon": 0,
+  "humidity": 72.0
+}

python_hilo-2026.11.1/doc/rest/season_events_ch_2025.json

@@ -0,0 +1,42 @@
+{
+  "season": 2025,
+  "events": [
+    {
+      "id": 378,
+      "startDateUtc": "2026-03-18T08:00:00+00:00",
+      "period": "AM",
+      "reward": 11.68,
+      "energySavingsWh": 20570,
+      "status": "Success",
+      "isPreseasonEvent": false,
+      "isCredited": true,
+      "isFlatRate": false,
+      "isInsufficientReduction": false
+    },
+    {
+      "id": 377,
+      "startDateUtc": "2026-03-03T09:00:00+00:00",
+      "period": "AM",
+      "reward": 17.95,
+      "energySavingsWh": 31620,
+      "status": "Success",
+      "isPreseasonEvent": false,
+      "isCredited": true,
+      "isFlatRate": false,
+      "isInsufficientReduction": false
+    },
+    {
+      "id": 373,
+      "startDateUtc": "2026-02-08T09:00:00+00:00",
+      "period": "AM",
+      "reward": 20.56,
+      "energySavingsWh": 36220,
+      "status": "Success",
+      "isPreseasonEvent": false,
+      "isCredited": true,
+      "isFlatRate": false,
+      "isInsufficientReduction": false
+    }
+  ],
+  "periodId": "Q0h8dXJuOmhpbG86Y3JtOjAwMDAwLWFiY2RlZjowfDIwMjUtMTEtMDFUMTM6MDE6MTcuODA4Nzc4NVo="
+}

python_hilo-2026.11.1/doc/rest/season_events_ch_2026_empty.json

@@ -0,0 +1,5 @@
+{
+  "season": 2026,
+  "events": [],
+  "periodId": "Q0h8dXJuOmhpbG86Y3JtOjAwMDAwLWFiY2RlZjowfDIwMjUtMTEtMDFUMTM6MDE6MTcuODA4Nzc4NVo="
+}

python_hilo-2026.11.1/doc/rest/season_events_hilo_2024.json

@@ -0,0 +1,36 @@
+{
+  "season": 2024,
+  "events": [
+    {
+      "id": 303,
+      "startDateUtc": "2025-03-03T09:00:00+00:00",
+      "period": "AM",
+      "reportId": 1000000,
+      "reward": 20.39,
+      "energySavingsWh": 37081.6845703125,
+      "status": "Success",
+      "isPreseasonEvent": false
+    },
+    {
+      "id": 302,
+      "startDateUtc": "2025-02-19T09:00:00+00:00",
+      "period": "AM",
+      "reportId": 1000001,
+      "reward": 21.85,
+      "energySavingsWh": 39730.3349609375,
+      "status": "Success",
+      "isPreseasonEvent": false
+    },
+    {
+      "id": 301,
+      "startDateUtc": "2025-02-18T09:00:00+00:00",
+      "period": "AM",
+      "reportId": 1000002,
+      "reward": 23.91,
+      "energySavingsWh": 43477.09521484375,
+      "status": "Success",
+      "isPreseasonEvent": false
+    }
+  ],
+  "periodId": "SGlsb3x1cm46aGlsbzpjcm06MDAwMDAtYWJjZGVmOjB8MjAyMi0wNi0yMlQxOTo1MDozOC4wMDAwMDAwWg=="
+}

python_hilo-2026.11.1/doc/rest/seasons_summary.json

@@ -0,0 +1,27 @@
+[
+  {
+    "season": 2026,
+    "ratePlan": "CH",
+    "periodId": "Q0h8dXJuOmhpbG86Y3JtOjAwMDAwLWFiY2RlZjowfDIwMjUtMTEtMDFUMTM6MDE6MTcuODA4Nzc4NVo="
+  },
+  {
+    "season": 2025,
+    "ratePlan": "CH",
+    "periodId": "Q0h8dXJuOmhpbG86Y3JtOjAwMDAwLWFiY2RlZjowfDIwMjUtMTEtMDFUMTM6MDE6MTcuODA4Nzc4NVo="
+  },
+  {
+    "season": 2024,
+    "ratePlan": "Hilo",
+    "periodId": "SGlsb3x1cm46aGlsbzpjcm06MDAwMDAtYWJjZGVmOjB8MjAyMi0wNi0yMlQxOTo1MDozOC4wMDAwMDAwWg=="
+  },
+  {
+    "season": 2023,
+    "ratePlan": "Hilo",
+    "periodId": "SGlsb3x1cm46aGlsbzpjcm06MDAwMDAtYWJjZGVmOjB8MjAyMi0wNi0yMlQxOTo1MDozOC4wMDAwMDAwWg=="
+  },
+  {
+    "season": 2022,
+    "ratePlan": "Hilo",
+    "periodId": "SGlsb3x1cm46aGlsbzpjcm06MDAwMDAtYWJjZGVmOjB8MjAyMi0wNi0yMlQxOTo1MDozOC4wMDAwMDAwWg=="
+  }
+]

{python_hilo-2026.10.1 → python_hilo-2026.11.1}/pyhilo/__init__.py

@@ -1,6 +1,7 @@
 """Define the hilo package."""
 
 from pyhilo.api import API
+from pyhilo.auth import AbstractAuth
 from pyhilo.const import UNMONITORED_DEVICES
 from pyhilo.device import HiloDevice
 from pyhilo.device.switch import Switch
@@ -12,6 +13,7 @@ from pyhilo.util import from_utc_timestamp, time_diff
 
 __all__ = [
     "API",
+    "AbstractAuth",
     "Devices",
     "HiloDevice",
     "Event",