pyhearth 1.0.0__py3-none-any.whl

pyhearth/__init__.py

@@ -0,0 +1,3 @@
+__copyright__ = "Copyright (c) 2026 Alex Laird"
+__license__ = "MIT"
+__version__ = "1.0.0"

pyhearth/client.py

@@ -0,0 +1,148 @@
+__copyright__ = "Copyright (c) 2026 Alex Laird"
+__license__ = "MIT"
+
+import json
+from dataclasses import dataclass, field
+from typing import Any, Final
+
+import aiohttp
+
+from pyhearth.exception import (
+    HearthAuthError,
+    HearthConnectionError,
+    HearthDemoHomeError,
+    HearthRateLimitedError,
+    HearthRejectedError,
+)
+
+#: Where Hearth's API is.
+DEFAULT_API_URL: Final = "https://api.meethearth.app"
+#: The version of the bridge protocol Hearth's ``/v1/bridge`` endpoint speaks.
+PROTOCOL: Final = 1
+#: How long one request to Hearth may take, in seconds.
+REQUEST_TIMEOUT: Final = 15
+#: How many seconds to wait when Hearth asks to slow down without saying for how long.
+DEFAULT_RETRY_AFTER: Final = 60
+
+
+@dataclass(frozen=True)
+class ReadingsResult:
+    """
+    What Hearth said about a readings post.
+    """
+
+    #: The posted sensors that aren't added to a room in the Hearth app yet (Hearth drops their readings).
+    not_added: list[str] = field(default_factory=list)
+
+
+class HearthClient:
+    """
+    A connection to one Hearth home through its API key: ``/v1/bridge`` for the thermostat and ``/v1/readings`` for
+    room sensors.
+    """
+
+    def __init__(self,
+                 session: aiohttp.ClientSession,
+                 api_key: str,
+                 base_url: str = DEFAULT_API_URL,
+                 *,
+                 source: str | None = None,
+                 source_name: str | None = None) -> None:
+        self._session = session
+        self._api_key = api_key
+
+        #: Where Hearth's API is (Hearth's own unless pointed at another backend).
+        self.base_url: str = base_url.rstrip("/")
+        #: The readings source this client posts as (Hearth's default, ``api``, if not given): Hearth keeps each
+        #: source's sensors and outages apart.
+        self.source: str | None = source
+        #: How the Hearth app names the source, if given.
+        self.source_name: str | None = source_name
+
+    async def check_key(self) -> None:
+        """
+        Check that Hearth takes the API key, with an empty readings post (which changes nothing).
+
+        :raises: :class:`~pyhearth.exception.HearthError`: When Hearth doesn't take the key or can't be reached.
+        """
+        await self._post("/v1/readings", self._readings_payload([], named=False))
+
+    async def sync_thermostat(self,
+                              thermostat: dict[str, Any],
+                              refused: dict[str, Any] | None = None) -> dict[str, Any] | None:
+        """
+        Post the thermostat to Hearth.
+
+        :param thermostat: The thermostat, as ``/v1/bridge`` takes it.
+        :param refused: The last setting that couldn't be applied (as Hearth answered it), why, and who refused it.
+        :return: The setting Hearth wants applied, if any.
+        :raises: :class:`~pyhearth.exception.HearthError`: When Hearth refuses the post or can't be reached.
+        """
+        payload: dict[str, Any] = {"protocol": PROTOCOL, "thermostat": thermostat}
+        if refused is not None:
+            payload["refused"] = refused
+        status, body = await self._post("/v1/bridge", payload)
+        desired = body.get("desired") if status == 200 and isinstance(body, dict) else None
+        return desired if isinstance(desired, dict) else None
+
+    async def post_readings(self, sensors: list[dict[str, Any]]) -> ReadingsResult:
+        """
+        Post room sensors' readings to Hearth, which keeps only those of sensors added in its app.
+
+        :param sensors: The readings, as ``/v1/readings`` takes them.
+        :return: What Hearth said about them.
+        :raises: :class:`~pyhearth.exception.HearthError`: When Hearth refuses the post or can't be reached.
+        """
+        status, body = await self._post("/v1/readings", self._readings_payload(sensors, named=True))
+        if status == 422:
+            return ReadingsResult([str(sensor["id"]) for sensor in sensors])
+        not_added = body.get("not_added") if isinstance(body, dict) else None
+        return ReadingsResult([str(name) for name in not_added] if isinstance(not_added, list) else [])
+
+    def _readings_payload(self, sensors: list[dict[str, Any]], named: bool) -> dict[str, Any]:
+        payload: dict[str, Any] = {}
+        if self.source is not None:
+            payload["source"] = self.source
+        if named and self.source_name is not None:
+            payload["name"] = self.source_name
+        payload["sensors"] = sensors
+        return payload
+
+    async def _post(self, path: str, payload: dict[str, Any]) -> tuple[int, Any]:
+        try:
+            async with self._session.post(f"{self.base_url}{path}",
+                                          json=payload,
+                                          headers={"Authorization": f"Bearer {self._api_key}"},
+                                          timeout=aiohttp.ClientTimeout(total=REQUEST_TIMEOUT)) as response:
+                text = await response.text()
+                status = response.status
+                retry_after = response.headers.get("Retry-After")
+        except (aiohttp.ClientError, TimeoutError) as e:
+            raise HearthConnectionError(f"Couldn't reach Hearth: {e}") from e
+
+        if status in (200, 204, 422):
+            return status, _json(text) if text else None
+        elif status == 401:
+            raise HearthAuthError("Hearth didn't accept the API key.")
+        elif status == 403:
+            raise HearthDemoHomeError(text or "The API key belongs to a demo home.")
+        elif status == 429:
+            raise HearthRateLimitedError("Hearth asked for fewer posts.", {"retry_after": _seconds(retry_after)})
+        elif status >= 500:
+            raise HearthConnectionError(f"Hearth answered {status}.")
+        else:
+            raise HearthRejectedError(text[:300] or f"Hearth answered {status}.")
+
+
+def _json(text: str) -> Any:
+    try:
+        return json.loads(text)
+    except ValueError:
+        return None
+
+
+def _seconds(value: str | None) -> int:
+    try:
+        return max(1, int(value)) if value is not None else DEFAULT_RETRY_AFTER
+    except ValueError:
+        return DEFAULT_RETRY_AFTER

pyhearth/exception.py

@@ -0,0 +1,53 @@
+__copyright__ = "Copyright (c) 2026 Alex Laird"
+__license__ = "MIT"
+
+from typing import Any
+
+
+class HearthError(Exception):
+    """
+    Raised when a general Hearth API error has occurred.
+    """
+
+    def __init__(self,
+                 error: str | BaseException,
+                 meta: dict[str, Any] | None = None) -> None:
+        super(HearthError, self).__init__(error)
+
+        #: Metadata for context around the error that was raised.
+        self.meta: dict[str, Any] | None = meta
+
+
+class HearthAuthError(HearthError):
+    """
+    Raised when Hearth doesn't accept the API key (it's wrong, it was replaced, or its home is gone).
+    """
+    pass
+
+
+class HearthDemoHomeError(HearthError):
+    """
+    Raised when the API key belongs to a demo home, which runs on a simulated thermostat and takes no posts.
+    """
+    pass
+
+
+class HearthRateLimitedError(HearthError):
+    """
+    Raised when Hearth asks for fewer posts. ``meta["retry_after"]`` is how many seconds to wait.
+    """
+    pass
+
+
+class HearthRejectedError(HearthError):
+    """
+    Raised when Hearth can't read a post. The error's message is Hearth's reason.
+    """
+    pass
+
+
+class HearthConnectionError(HearthError):
+    """
+    Raised when Hearth can't be reached (the network, a timeout, or an error on Hearth's side).
+    """
+    pass

pyhearth-1.0.0.dist-info/METADATA

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: pyhearth
+Version: 1.0.0
+Summary: A Python client for Hearth's home API: post a thermostat and room sensor readings to a Hearth home
+Author-email: Alex Laird <contact@alexlaird.com>
+Maintainer-email: Alex Laird <contact@alexlaird.com>
+License-Expression: MIT
+Project-URL: Changelog, https://github.com/alexdlaird/pyhearth/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://github.com/alexdlaird/pyhearth#readme
+Project-URL: Sponsor, https://github.com/sponsors/alexdlaird
+Project-URL: Source Code, https://github.com/alexdlaird/pyhearth
+Keywords: hearth,thermostat,climate,room-sensors,home-automation,daikin,asyncio
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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 :: 3.14
+Classifier: Topic :: Home Automation
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.9
+Provides-Extra: dev
+Requires-Dist: coverage[toml]; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: flake8-pyproject; extra == "dev"
+Requires-Dist: pep8-naming; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Dynamic: license-file
+
+[![Version](https://img.shields.io/pypi/v/pyhearth)](https://pypi.org/project/pyhearth)
+[![Python Versions](https://img.shields.io/pypi/pyversions/pyhearth.svg)](https://pypi.org/project/pyhearth)
+[![Coverage](https://img.shields.io/codecov/c/github/alexdlaird/pyhearth)](https://codecov.io/gh/alexdlaird/pyhearth)
+[![Build](https://img.shields.io/github/actions/workflow/status/alexdlaird/pyhearth/build.yml)](https://github.com/alexdlaird/pyhearth/actions/workflows/build.yml)
+[![GitHub License](https://img.shields.io/github/license/alexdlaird/pyhearth)](https://github.com/alexdlaird/pyhearth/blob/main/LICENSE)
+
+`pyhearth` is a Python client for [Hearth](https://www.meethearth.app)'s home API. It posts room sensor readings, and
+optionally a thermostat, to a Hearth home with the home's API key, and returns the thermostat setting Hearth answers
+with. It's what [`ha-hearth`](https://github.com/alexdlaird/ha-hearth), Hearth's Home Assistant integration, uses to
+talk to Hearth.
+
+## Installation
+
+`pyhearth` is available on [PyPI](https://pypi.org/project/pyhearth/) and can be installed using `pip`:
+
+```sh
+pip install pyhearth
+```
+
+## Basic Usage
+
+In the Hearth app, create the home's API key in Settings, then Manage home, then Sensors, then "Other sensors (Hearth
+API)". Then post readings:
+
+```python
+import asyncio
+
+import aiohttp
+
+from pyhearth.client import HearthClient
+
+
+async def main():
+    async with aiohttp.ClientSession() as session:
+        client = HearthClient(session, "<your API key>", source="my-hub", source_name="My hub")
+        result = await client.post_readings([
+            {"id": "office", "name": "Office", "temperature": 20.8, "humidity": 41}
+        ])
+        print(result.not_added)
+
+
+asyncio.run(main())
+```
+
+A sensor's readings are kept once it's added to a room in the Hearth app; until then, it's listed in `not_added`. The
+fields each endpoint takes are in [Hearth's API docs](https://www.meethearth.app/support.html#hearth-api).
+
+Errors are raised as subclasses of `HearthError` (in `pyhearth.exception`): `HearthAuthError` when Hearth doesn't take
+the key, `HearthRateLimitedError` when it asks for fewer posts (`meta["retry_after"]` says how many seconds to wait),
+`HearthRejectedError` when it can't read a post, and `HearthConnectionError` when it can't be reached.
+
+## Contributing
+
+If you would like to get involved, be sure to review
+the [Contribution Guide](https://github.com/alexdlaird/pyhearth/blob/main/CONTRIBUTING.rst).
+
+Want to contribute financially? If you've found `pyhearth` useful, [sponsorship](https://github.com/sponsors/alexdlaird)
+would also be greatly appreciated!

pyhearth-1.0.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+pyhearth/__init__.py,sha256=5rtuFu5MRgQ1gHCXL0bWgH7oYD_eCj5k-Px7srvfAbo,90
+pyhearth/client.py,sha256=k_R_FlE42enlUPiMEZgl7QjvgCTzM0nM3mpY5vAuKqM,6131
+pyhearth/exception.py,sha256=-xMKjXPBq-nds__Kfpd6ucdikl9UlGNo6gdWQSmR95s,1315
+pyhearth/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyhearth-1.0.0.dist-info/licenses/LICENSE,sha256=DH_vojkclcvS70LqmgQH3kdwpjEw_0_IAu9KfSniq98,1067
+pyhearth-1.0.0.dist-info/METADATA,sha256=q8w7zlKwmNOlQUrp_PD16woq6ikhLy23GwCNZdxVQSg,4252
+pyhearth-1.0.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+pyhearth-1.0.0.dist-info/top_level.txt,sha256=hjXrHO0pUJUxh12yFRjvdHb09XzWAK_jFQHh0W-qxj0,9
+pyhearth-1.0.0.dist-info/RECORD,,

pyhearth-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pyhearth-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Laird
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyhearth-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pyhearth