python-hilo 2025.2.2__tar.gz → 2025.4.1__tar.gz

python_hilo-2025.4.1/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.3
+Name: python-hilo
+Version: 2025.4.1
+Summary: A Python3, async interface to the Hilo API
+License: MIT
+Author: David Vallee Delisle
+Author-email: me@dvd.dev
+Maintainer: David Vallee Delisle
+Maintainer-email: me@dvd.dev
+Requires-Python: >=3.9.0,<4.0.0
+Classifier: Framework :: aiohttp
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: Topic :: Home Automation
+Requires-Dist: aiofiles (>=23.2.1)
+Requires-Dist: aiohttp (>=3.8.0)
+Requires-Dist: aiosignal (>=1.2.0)
+Requires-Dist: async-timeout (>=4.0.0)
+Requires-Dist: attrs (>=21.2.0)
+Requires-Dist: backoff (>=1.11.1)
+Requires-Dist: gql (>=3.5.2,<4.0.0)
+Requires-Dist: python-dateutil (>=2.8.2)
+Requires-Dist: pyyaml (>=6.0.2,<7.0.0)
+Requires-Dist: voluptuous (>=0.13.1)
+Requires-Dist: websockets (>=8.1,<16.0)
+Project-URL: Repository, https://github.com/dvd-dev/python-hilo
+Description-Content-Type: text/markdown
+
+# python-hilo
+
+[![GitHub Release][releases-shield]][releases]
+[![License][license-shield]](LICENSE)
+
+[![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
+Hilo API from Hydro Quebec. This is meant to be integrated into Home Assistant but can also
+be used as a standalone library.
+
+Home assistant integration is available [here](https://github.com/dvd-dev/hilo)
+
+## TODO
+- Type everything: almost done, got a few "type: ignore" to fix
+
+## Later?
+- Full docstrings and doc generation
+- Unit testing
+- Functional testing
+
+If anyone wants to contribute, feel free to submit a PR. If you'd like to sync up first, you can
+fire me an email me@dvd.dev
+
+## Setting up development environment
+
+The easiest way to start, is by opening a CodeSpace here on GitHub, or by using
+the [Dev Container][devcontainer] feature of Visual Studio Code.
+
+[![Open in Dev Containers][devcontainer-shield]][devcontainer]
+
+This Python project is fully managed using the [Poetry][poetry] dependency
+manager. But also relies on the use of NodeJS for certain checks during
+development.
+
+You need at least:
+
+- Python 3.11+
+- [Poetry][poetry-install]
+- NodeJS 20+ (including NPM)
+
+To install all packages, including all development requirements:
+
+```bash
+npm install
+poetry install
+```
+
+As this repository uses the [pre-commit][pre-commit] framework, all changes
+are linted and tested with each commit. You can run all checks and tests
+manually, using the following command:
+
+```bash
+poetry run pre-commit run --all-files
+```
+
+To run just the Python tests:
+
+```bash
+poetry run pytest
+```
+
+## Authors & contributors
+
+The original setup of this repository is by [David Vallée Delisle][dvd-dev].
+
+Credits to [@frenck][frenck] for the base container configuration.
+The license of python-wled can be found in
+[third_party/python-wled/LICENSE](third_party/python-wled/LICENSE).
+
+For a full list of all authors and contributors,
+check [the contributor's page][contributors].
+
+
+
+[build-shield]: https://github.com/dvd-dev/python-hilo/actions/workflows/tests.yaml/badge.svg
+[build]: https://github.com/dvd-dev/python-hilo/actions/workflows/tests.yaml
+[releases-shield]: https://img.shields.io/github/release/dvd-dev/python-hilo.svg
+[releases]: https://github.com/dvd-dev/python-hilo/releases
+[license-shield]: https://img.shields.io/github/license/dvd-dev/python-hilo.svg
+[devcontainer-shield]: https://img.shields.io/static/v1?label=Dev%20Containers&message=Open&color=blue&logo=visualstudiocode
+[devcontainer]: https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/dvd-dev/python-hilo
+[poetry-install]: https://python-poetry.org/docs/#installation
+[poetry]: https://python-poetry.org
+[pre-commit]: https://pre-commit.com/
+[dvd-dev]: https://github.com/dvd-dev
+[frenck]: https://github.com/frenck
+[contributors]: https://github.com/dvd-dev/python-hilo/graphs/contributors

python_hilo-2025.4.1/README.md

@@ -0,0 +1,89 @@
+# python-hilo
+
+[![GitHub Release][releases-shield]][releases]
+[![License][license-shield]](LICENSE)
+
+[![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
+Hilo API from Hydro Quebec. This is meant to be integrated into Home Assistant but can also
+be used as a standalone library.
+
+Home assistant integration is available [here](https://github.com/dvd-dev/hilo)
+
+## TODO
+- Type everything: almost done, got a few "type: ignore" to fix
+
+## Later?
+- Full docstrings and doc generation
+- Unit testing
+- Functional testing
+
+If anyone wants to contribute, feel free to submit a PR. If you'd like to sync up first, you can
+fire me an email me@dvd.dev
+
+## Setting up development environment
+
+The easiest way to start, is by opening a CodeSpace here on GitHub, or by using
+the [Dev Container][devcontainer] feature of Visual Studio Code.
+
+[![Open in Dev Containers][devcontainer-shield]][devcontainer]
+
+This Python project is fully managed using the [Poetry][poetry] dependency
+manager. But also relies on the use of NodeJS for certain checks during
+development.
+
+You need at least:
+
+- Python 3.11+
+- [Poetry][poetry-install]
+- NodeJS 20+ (including NPM)
+
+To install all packages, including all development requirements:
+
+```bash
+npm install
+poetry install
+```
+
+As this repository uses the [pre-commit][pre-commit] framework, all changes
+are linted and tested with each commit. You can run all checks and tests
+manually, using the following command:
+
+```bash
+poetry run pre-commit run --all-files
+```
+
+To run just the Python tests:
+
+```bash
+poetry run pytest
+```
+
+## Authors & contributors
+
+The original setup of this repository is by [David Vallée Delisle][dvd-dev].
+
+Credits to [@frenck][frenck] for the base container configuration.
+The license of python-wled can be found in
+[third_party/python-wled/LICENSE](third_party/python-wled/LICENSE).
+
+For a full list of all authors and contributors,
+check [the contributor's page][contributors].
+
+
+
+[build-shield]: https://github.com/dvd-dev/python-hilo/actions/workflows/tests.yaml/badge.svg
+[build]: https://github.com/dvd-dev/python-hilo/actions/workflows/tests.yaml
+[releases-shield]: https://img.shields.io/github/release/dvd-dev/python-hilo.svg
+[releases]: https://github.com/dvd-dev/python-hilo/releases
+[license-shield]: https://img.shields.io/github/license/dvd-dev/python-hilo.svg
+[devcontainer-shield]: https://img.shields.io/static/v1?label=Dev%20Containers&message=Open&color=blue&logo=visualstudiocode
+[devcontainer]: https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/dvd-dev/python-hilo
+[poetry-install]: https://python-poetry.org/docs/#installation
+[poetry]: https://python-poetry.org
+[pre-commit]: https://pre-commit.com/
+[dvd-dev]: https://github.com/dvd-dev
+[frenck]: https://github.com/frenck
+[contributors]: https://github.com/dvd-dev/python-hilo/graphs/contributors

python_hilo-2025.4.1/pyhilo/__init__.py

@@ -0,0 +1,27 @@
+"""Define the hilo package."""
+from pyhilo.api import API
+from pyhilo.const import UNMONITORED_DEVICES
+from pyhilo.device import HiloDevice
+from pyhilo.device.switch import Switch
+from pyhilo.devices import Devices
+from pyhilo.event import Event
+from pyhilo.exceptions import HiloError, InvalidCredentialsError, WebsocketError
+from pyhilo.oauth2 import AuthCodeWithPKCEImplementation
+from pyhilo.util import from_utc_timestamp, time_diff
+from pyhilo.websocket import WebsocketEvent
+
+__all__ = [
+    "API",
+    "Devices",
+    "HiloDevice",
+    "Event",
+    "HiloError",
+    "InvalidCredentialsError",
+    "WebsocketError",
+    "AuthCodeWithPKCEImplementation",
+    "from_utc_timestamp",
+    "time_diff",
+    "WebsocketEvent",
+    "UNMONITORED_DEVICES",
+    "Switch",
+]

{python_hilo-2025.2.2 → python_hilo-2025.4.1}/pyhilo/api.py

@@ -12,7 +12,6 @@ from urllib import parse
 from aiohttp import ClientSession
 from aiohttp.client_exceptions import ClientResponseError
 import backoff
-from homeassistant.helpers import config_entry_oauth2_flow
 
 from pyhilo.const import (
     ANDROID_CLIENT_ENDPOINT,
@@ -67,7 +66,7 @@ class API:
         self,
         *,
         session: ClientSession,
-        oauth_session: config_entry_oauth2_flow.OAuth2Session,
+        oauth_session,
         request_retries: int = REQUEST_RETRY,
         log_traces: bool = False,
     ) -> None:
@@ -98,7 +97,7 @@ class API:
         cls,
         *,
         session: ClientSession,
-        oauth_session: config_entry_oauth2_flow.OAuth2Session,
+        oauth_session,
         request_retries: int = REQUEST_RETRY,
         log_traces: bool = False,
     ) -> API:
@@ -141,7 +140,7 @@ class API:
             await self._oauth_session.async_ensure_token_valid()
 
         access_token = str(self._oauth_session.token["access_token"])
-        LOG.debug(f"ic-dev21 access token is {access_token}")
+        LOG.debug(f"Websocket access token is {access_token}")
 
         return str(self._oauth_session.token["access_token"])
 
@@ -239,9 +238,8 @@ class API:
             kwargs["headers"]["authorization"] = f"Bearer {access_token}"
         kwargs["headers"]["Host"] = host
 
-        # ic-dev21 trying Leicas suggestion
         if endpoint.startswith(AUTOMATION_CHALLENGE_ENDPOINT):
-            # remove Ocp-Apim-Subscription-Key header to avoid 401 error
+            # remove Ocp-Apim-Subscription-Key header to avoid 401 error (Thanks Leicas)
             kwargs["headers"].pop("Ocp-Apim-Subscription-Key", None)
             kwargs["headers"]["authorization"] = f"Bearer {access_token}"
 
@@ -370,7 +368,7 @@ class API:
 
     async def _async_post_init(self) -> None:
         """Perform some post-init actions."""
-        LOG.debug("Websocket postinit")
+        LOG.debug("Websocket _async_post_init running")
         await self._get_fid()
         await self._get_device_token()
 
@@ -494,11 +492,11 @@ class API:
             },
         )
 
-    async def get_location_id(self) -> int:
+    async def get_location_ids(self) -> tuple[int, str]:
         url = f"{API_AUTOMATION_ENDPOINT}/Locations"
         LOG.debug(f"LocationId URL is {url}")
         req: list[dict[str, Any]] = await self.async_request("get", url)
-        return int(req[0]["id"])
+        return (req[0]["id"], req[0]["locationHiloId"])
 
     async def get_devices(self, location_id: int) -> list[dict[str, Any]]:
         """Get list of all devices"""

{python_hilo-2025.2.2 → python_hilo-2025.4.1}/pyhilo/const.py

@@ -3,12 +3,11 @@ import platform
 from typing import Final
 
 import aiohttp
-import homeassistant.core
 
 LOG: Final = logging.getLogger(__package__)
 DEFAULT_STATE_FILE: Final = "hilo_state.yaml"
 REQUEST_RETRY: Final = 9
-PYHILO_VERSION: Final = "2025.2.02"
+PYHILO_VERSION: Final = "2025.4.01"
 # TODO: Find a way to keep previous line in sync with pyproject.toml automatically
 
 CONTENT_TYPE_FORM: Final = "application/x-www-form-urlencoded"
@@ -46,7 +45,7 @@ AUTOMATION_CHALLENGE_ENDPOINT: Final = "/ChallengeHub"
 
 
 # Request constants
-DEFAULT_USER_AGENT: Final = f"PyHilo/{PYHILO_VERSION} HomeAssistant/{homeassistant.core.__version__} aiohttp/{aiohttp.__version__} Python/{platform.python_version()}"
+DEFAULT_USER_AGENT: Final = f"PyHilo/{PYHILO_VERSION} aiohttp/{aiohttp.__version__} Python/{platform.python_version()}"
 
 
 # NOTE(dvd): Not sure how to get new ones so I'm using the ones from my emulator
@@ -196,7 +195,7 @@ HILO_DEVICE_TYPES: Final = {
 }
 
 HILO_UNIT_CONVERSION: Final = {
-    "Celcius": "°C",
+    "Celsius": "°C",
     "DB": "dB",
     "Integer": "dB",
     "Mbar": "mbar",
@@ -209,7 +208,7 @@ HILO_READING_TYPES: Final = {
     "BatteryPercent": "Percentage",
     "Co2": "PPM",
     "ColorTemperature": "Integer",
-    "CurrentTemperature": "Celcius",
+    "CurrentTemperature": "Celsius",
     "Disconnected": "null",
     "DrmsState": "OnOff",
     "firmwareVersion": "null",
@@ -217,8 +216,8 @@ HILO_READING_TYPES: Final = {
     "Hue": "Integer",
     "Humidity": "Percentage",
     "Intensity": "Percentage",
-    "MaxTempSetpoint": "Celcius",
-    "MinTempSetpoint": "Celcius",
+    "MaxTempSetpoint": "Celsius",
+    "MinTempSetpoint": "Celsius",
     "Noise": "DB",
     "onlineStatus": "null",
     "OnOff": "OnOff",
@@ -226,7 +225,7 @@ HILO_READING_TYPES: Final = {
     "Pressure": "Mbar",
     "Saturation": "Integer",
     "Status": "OnOff",
-    "TargetTemperature": "Celcius",
+    "TargetTemperature": "Celsius",
     "Unpaired": "null",
     "WifiStatus": "Integer",
     "zigBeePairingActivated": "OnOff",
@@ -269,3 +268,5 @@ UNMONITORED_DEVICES: Final = [
     "43094",
     "43100",
 ]
+
+STATE_UNKNOWN: Final = "unknown"

{python_hilo-2025.2.2 → python_hilo-2025.4.1}/pyhilo/device/__init__.py

@@ -1,12 +1,11 @@
 """Define devices"""
+
 from __future__ import annotations
 
 from dataclasses import dataclass, field
 from datetime import datetime
 from typing import TYPE_CHECKING, Any, Dict, Union, cast
 
-from homeassistant.const import STATE_UNKNOWN
-
 from pyhilo.const import (
     HILO_DEVICE_ATTRIBUTES,
     HILO_LIST_ATTRIBUTES,
@@ -16,6 +15,7 @@ from pyhilo.const import (
     JASCO_MODELS,
     JASCO_OUTLETS,
     LOG,
+    STATE_UNKNOWN,
 )
 from pyhilo.util import camel_to_snake, from_utc_timestamp
 
@@ -32,10 +32,11 @@ def get_device_attributes() -> list[DeviceAttribute]:
 
 class HiloDevice:
     def __init__(
-        self, api: API, **kwargs: Dict[str, Union[str, int, Dict[Any, Any]]]
+        self, api: API, **kwargs: Dict[str, str | int | Dict[Any, Any]]
     ) -> None:
         self._api = api
         self.id = 0
+        self.hilo_id: str = ""
         self.location_id = 0
         self.type = "Unknown"
         self.name = "Unknown"
@@ -59,6 +60,7 @@ class HiloDevice:
                     value = val.get("value")
                 reading = {
                     "deviceId": self.id,
+                    "hiloId": self.hilo_id,
                     "locationId": self.location_id,
                     "timeStampUTC": datetime.utcnow().isoformat(),
                     "value": value,
@@ -234,6 +236,7 @@ class DeviceReading:
         self.id = 0
         self.value: Union[int, bool, str] = 0
         self.device_id = 0
+        self.hilo_id: str = ""
         self.device_attribute: DeviceAttribute
         self.__dict__.update({camel_to_snake(k): v for k, v in kwargs.items()})
         self.unit_of_measurement = (

python_hilo-2025.4.1/pyhilo/device/climate.py

@@ -0,0 +1,99 @@
+"""Climate object."""
+from __future__ import annotations
+
+from typing import Any, cast
+
+from pyhilo import API
+from pyhilo.const import LOG
+from pyhilo.device import HiloDevice
+
+
+class Climate(HiloDevice):
+    """
+    Represents a climate device within the Hilo ecosystem.
+
+    This class provides methods to interact with and control climate-related
+    devices such as thermostats.
+    """
+
+    def __init__(
+        self, api: API, **kwargs: dict[str, str | int | dict[Any, Any]]
+    ) -> None:
+        """Initialize the Climate object.
+
+        Args:
+            api: The Hilo API instance.
+            **kwargs: Keyword arguments containing device data.
+        """
+        super().__init__(api, **kwargs)
+        LOG.debug("Setting up Climate device: %s", self.name)
+
+    @property
+    def current_temperature(self) -> float:
+        """
+        Gets the current temperature reported by the device.
+
+        Returns:
+            float: The current temperature.
+        """
+        return cast(float, self.get_value("current_temperature", 0))
+
+    @property
+    def target_temperature(self) -> float:
+        """
+        Gets the target temperature set for the device.
+
+        Returns:
+            float: The target temperature.
+        """
+        return cast(float, self.get_value("target_temperature", 0))
+
+    @property
+    def max_temp(self) -> float:
+        """
+        Gets the maximum temperature setpoint allowed for the device.
+
+        Returns:
+            float: The maximum temperature. Defaults to 36.0 if not defined.
+        """
+        value = self.get_value("max_temp_setpoint", 0)
+
+        if value is None or value == 0:
+            return 36.0
+        return float(value)
+
+    @property
+    def min_temp(self) -> float:
+        """
+        Gets the minimum temperature setpoint allowed for the device.
+
+        Returns:
+            float: The minimum temperature. Defaults to 5.0 if not defined.
+        """
+        value = self.get_value("min_temp_setpoint", 0)
+
+        if value is None or value == 0:
+            return 5.0
+        return float(value)
+
+    @property
+    def hvac_action(self) -> str:
+        """
+        Gets the current HVAC action of the device.
+
+        Returns:
+            str: 'heating' if heating is active, 'idle' otherwise.
+        """
+        attr = self.get_value("heating", 0)
+        return "heating" if attr > 0 else "idle"
+
+    async def async_set_temperature(self, temperature: float) -> None:
+        """
+        Sets the target temperature of the device.
+
+        Args:
+            temperature: The desired target temperature.
+        """
+        if temperature != self.target_temperature:
+            LOG.info("%s Setting temperature to %s", self._tag, temperature)
+            await self.set_attribute("target_temperature", str(temperature))