pyhearth 1.0.0__tar.gz

pyhearth-1.0.0/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased](https://github.com/alexdlaird/pyhearth/compare/1.0.0...HEAD)
+
+## [1.0.0](https://github.com/alexdlaird/pyhearth/compare/0.0.0...1.0.0) - 2026-10-26
+
+### Added
+
+- First release of `pyhearth`: a client for Hearth's home API (`/v1/bridge` and `/v1/readings`).
+
+## [0.0.0](https://github.com/alexdlaird/pyhearth/tree/0.0.0) - 2026-10-26
+
+- Initial commit.

pyhearth-1.0.0/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/MANIFEST.in

@@ -0,0 +1,3 @@
+include LICENSE README.md CHANGELOG.md
+
+prune build

pyhearth-1.0.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,58 @@
+[![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/pyhearth/__init__.py

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

pyhearth-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-1.0.0/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/pyhearth.egg-info/PKG-INFO

@@ -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/pyhearth.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+CHANGELOG.md
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+pyhearth/__init__.py
+pyhearth/client.py
+pyhearth/exception.py
+pyhearth/py.typed
+pyhearth.egg-info/PKG-INFO
+pyhearth.egg-info/SOURCES.txt
+pyhearth.egg-info/dependency_links.txt
+pyhearth.egg-info/requires.txt
+pyhearth.egg-info/top_level.txt
+tests/test_client.py
+tests/testcase.py

pyhearth-1.0.0/pyhearth.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pyhearth-1.0.0/pyhearth.egg-info/requires.txt

@@ -0,0 +1,8 @@
+aiohttp>=3.9
+
+[dev]
+coverage[toml]
+flake8
+flake8-pyproject
+pep8-naming
+mypy

pyhearth-1.0.0/pyhearth.egg-info/top_level.txt

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

pyhearth-1.0.0/pyproject.toml

@@ -0,0 +1,82 @@
+[project]
+name = "pyhearth"
+dynamic = ["version"]
+description = "A Python client for Hearth's home API: post a thermostat and room sensor readings to a Hearth home"
+readme = "README.md"
+license = "MIT"
+keywords = ["hearth", "thermostat", "climate", "room-sensors", "home-automation", "daikin", "asyncio"]
+authors = [{ name = "Alex Laird", email = "contact@alexlaird.com" }]
+maintainers = [{ name = "Alex Laird", email = "contact@alexlaird.com" }]
+requires-python = ">=3.10"
+dependencies = [
+    "aiohttp>=3.9"
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Home Automation",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.optional-dependencies]
+dev = [
+    "coverage[toml]",
+    "flake8",
+    "flake8-pyproject",
+    "pep8-naming",
+    "mypy"
+]
+
+[project.urls]
+Changelog = "https://github.com/alexdlaird/pyhearth/blob/main/CHANGELOG.md"
+Documentation = "https://github.com/alexdlaird/pyhearth#readme"
+Sponsor = "https://github.com/sponsors/alexdlaird"
+"Source Code" = "https://github.com/alexdlaird/pyhearth"
+
+[tool.setuptools]
+package-dir = { pyhearth = "pyhearth" }
+
+[tool.setuptools.package-data]
+pyhearth = ["py.typed"]
+
+[tool.setuptools.dynamic]
+version = { attr = "pyhearth.__version__" }
+
+[tool.coverage.run]
+omit = [
+    "venv/**",
+    "*/tests/**"
+]
+
+[tool.coverage.report]
+precision = 2
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+]
+
+[tool.coverage.xml]
+output = "build/coverage/coverage.xml"
+
+[tool.coverage.html]
+title = "Coverage Report"
+directory = "build/coverage"
+
+[tool.mypy]
+strict = true
+
+[tool.flake8]
+max-line-length = 119
+statistics = true
+exclude = "venv/*,build/*,dist/*,.egg-info/*"

pyhearth-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pyhearth-1.0.0/tests/test_client.py

@@ -0,0 +1,226 @@
+__copyright__ = "Copyright (c) 2026 Alex Laird"
+__license__ = "MIT"
+
+import json
+
+from pyhearth.client import DEFAULT_RETRY_AFTER, PROTOCOL, HearthClient
+from pyhearth.exception import (
+    HearthAuthError,
+    HearthConnectionError,
+    HearthDemoHomeError,
+    HearthRateLimitedError,
+    HearthRejectedError,
+)
+from tests.testcase import HearthTestCase
+
+THERMOSTAT = {"entity_id": "climate.hallway", "hvac_mode": "heat", "current_temperature": 20.5}
+DESIRED = {"hvac_mode": "heat", "temperature": 21.0}
+READINGS = [{"id": "sensor.office", "temperature": 20.8}, {"id": "sensor.den", "temperature": 19.9}]
+
+
+class TestCheckKey(HearthTestCase):
+    async def test_check_key(self) -> None:
+        # GIVEN
+        client = self.given_client(source="home-assistant")
+
+        # WHEN
+        await client.check_key()
+
+        # THEN
+        self.assertEqual([{"source": "home-assistant", "sensors": []}], self.posted("readings"))
+        self.assertEqual([f"Bearer {self.API_KEY}"], self.authorizations)
+
+    async def test_check_key_refused(self) -> None:
+        # GIVEN
+        self.given_hearth_answers("readings", 401)
+        client = self.given_client()
+
+        # WHEN / THEN
+        with self.assertRaises(HearthAuthError):
+            await client.check_key()
+
+
+class TestSyncThermostat(HearthTestCase):
+    async def test_sync_thermostat_desired(self) -> None:
+        # GIVEN
+        self.given_hearth_answers("bridge", 200, json.dumps({"desired": DESIRED}))
+        client = self.given_client()
+
+        # WHEN
+        desired = await client.sync_thermostat(THERMOSTAT)
+
+        # THEN
+        self.assertEqual(DESIRED, desired)
+        self.assertEqual([{"protocol": PROTOCOL, "thermostat": THERMOSTAT}], self.posted("bridge"))
+
+    async def test_sync_thermostat_refused_setting(self) -> None:
+        # GIVEN
+        refused = {"setting": DESIRED, "reason": "out of range", "by": "thermostat"}
+        client = self.given_client()
+
+        # WHEN
+        await client.sync_thermostat(THERMOSTAT, refused)
+
+        # THEN
+        self.assertEqual(refused, self.posted("bridge")[0]["refused"])
+
+    async def test_sync_thermostat_nothing_desired(self) -> None:
+        # GIVEN
+        client = self.given_client()
+
+        # WHEN
+        desired = await client.sync_thermostat(THERMOSTAT)
+
+        # THEN
+        self.assertIsNone(desired)
+
+    async def test_sync_thermostat_desired_not_a_setting(self) -> None:
+        # GIVEN
+        self.given_hearth_answers("bridge", 200, json.dumps({"desired": "heat"}))
+        client = self.given_client()
+
+        # WHEN
+        desired = await client.sync_thermostat(THERMOSTAT)
+
+        # THEN
+        self.assertIsNone(desired)
+
+    async def test_sync_thermostat_unreadable_answer(self) -> None:
+        # GIVEN
+        self.given_hearth_answers("bridge", 200, "not json")
+        client = self.given_client()
+
+        # WHEN
+        desired = await client.sync_thermostat(THERMOSTAT)
+
+        # THEN
+        self.assertIsNone(desired)
+
+
+class TestPostReadings(HearthTestCase):
+    async def test_post_readings(self) -> None:
+        # GIVEN
+        self.given_hearth_answers("readings", 200, json.dumps({"not_added": ["sensor.den"]}))
+        client = self.given_client(source="home-assistant", source_name="Home Assistant")
+
+        # WHEN
+        result = await client.post_readings(READINGS)
+
+        # THEN
+        self.assertEqual(["sensor.den"], result.not_added)
+        self.assertEqual([{"source": "home-assistant", "name": "Home Assistant", "sensors": READINGS}],
+                         self.posted("readings"))
+
+    async def test_post_readings_default_source(self) -> None:
+        # GIVEN
+        client = self.given_client()
+
+        # WHEN
+        result = await client.post_readings(READINGS)
+
+        # THEN
+        self.assertEqual([], result.not_added)
+        self.assertEqual([{"sensors": READINGS}], self.posted("readings"), "Hearth's own default source applies")
+
+    async def test_post_readings_none_added(self) -> None:
+        # GIVEN
+        self.given_hearth_answers("readings", 422, json.dumps({"error": "no sensor of this home"}))
+        client = self.given_client()
+
+        # WHEN
+        result = await client.post_readings(READINGS)
+
+        # THEN
+        self.assertEqual(["sensor.office", "sensor.den"], result.not_added)
+
+
+class TestErrors(HearthTestCase):
+    async def test_demo_home(self) -> None:
+        # GIVEN
+        self.given_hearth_answers("bridge", 403, "This is a demo home.")
+        client = self.given_client()
+
+        # WHEN / THEN
+        with self.assertRaises(HearthDemoHomeError) as raised:
+            await client.sync_thermostat(THERMOSTAT)
+        self.assertEqual("This is a demo home.", str(raised.exception))
+
+    async def test_rate_limited(self) -> None:
+        # GIVEN
+        self.given_hearth_answers("bridge", 429, headers={"Retry-After": "30"})
+        client = self.given_client()
+
+        # WHEN / THEN
+        with self.assertRaises(HearthRateLimitedError) as raised:
+            await client.sync_thermostat(THERMOSTAT)
+        self.assertEqual({"retry_after": 30}, raised.exception.meta)
+
+    async def test_rate_limited_without_retry_after(self) -> None:
+        # GIVEN
+        self.given_hearth_answers("bridge", 429)
+        client = self.given_client()
+
+        # WHEN / THEN
+        with self.assertRaises(HearthRateLimitedError) as raised:
+            await client.sync_thermostat(THERMOSTAT)
+        self.assertEqual({"retry_after": DEFAULT_RETRY_AFTER}, raised.exception.meta)
+
+    async def test_rate_limited_unreadable_retry_after(self) -> None:
+        # GIVEN
+        self.given_hearth_answers("bridge", 429, headers={"Retry-After": "soon"})
+        client = self.given_client()
+
+        # WHEN / THEN
+        with self.assertRaises(HearthRateLimitedError) as raised:
+            await client.sync_thermostat(THERMOSTAT)
+        self.assertEqual({"retry_after": DEFAULT_RETRY_AFTER}, raised.exception.meta)
+
+    async def test_rejected(self) -> None:
+        # GIVEN
+        self.given_hearth_answers("readings", 400, "sensors must be a list")
+        client = self.given_client()
+
+        # WHEN / THEN
+        with self.assertRaises(HearthRejectedError) as raised:
+            await client.post_readings(READINGS)
+        self.assertEqual("sensors must be a list", str(raised.exception))
+
+    async def test_rejected_without_reason(self) -> None:
+        # GIVEN
+        self.given_hearth_answers("readings", 413)
+        client = self.given_client()
+
+        # WHEN / THEN
+        with self.assertRaises(HearthRejectedError) as raised:
+            await client.post_readings(READINGS)
+        self.assertEqual("Hearth answered 413.", str(raised.exception))
+
+    async def test_server_error(self) -> None:
+        # GIVEN
+        self.given_hearth_answers("bridge", 503)
+        client = self.given_client()
+
+        # WHEN / THEN
+        with self.assertRaises(HearthConnectionError):
+            await client.sync_thermostat(THERMOSTAT)
+
+    async def test_unreachable(self) -> None:
+        # GIVEN
+        url = str(self.server.make_url("/"))
+        await self.server.close()
+        client = HearthClient(self.session, self.API_KEY, url)
+
+        # WHEN / THEN
+        with self.assertRaises(HearthConnectionError):
+            await client.check_key()
+
+    async def test_base_url_trailing_slash(self) -> None:
+        # GIVEN
+        client = HearthClient(self.session, self.API_KEY, f"{self.server.make_url('/')}/")
+
+        # WHEN
+        await client.check_key()
+
+        # THEN
+        self.assertEqual(str(self.server.make_url("")).rstrip("/"), client.base_url)
+        self.assertEqual(1, len(self.posted("readings")))

pyhearth-1.0.0/tests/testcase.py

@@ -0,0 +1,50 @@
+__copyright__ = "Copyright (c) 2026 Alex Laird"
+__license__ = "MIT"
+
+import unittest
+from typing import Any
+
+import aiohttp
+from aiohttp import web
+from aiohttp.test_utils import TestServer
+
+from pyhearth.client import HearthClient
+
+
+class HearthTestCase(unittest.IsolatedAsyncioTestCase):
+    API_KEY = "test-hearth-api-key"
+
+    async def asyncSetUp(self) -> None:
+        self.answers: dict[str, tuple[int, str, dict[str, str]]] = {}
+        self.posts: dict[str, list[Any]] = {}
+        self.authorizations: list[str | None] = []
+
+        app = web.Application()
+        app.router.add_post("/v1/{endpoint}", self._answer)
+        self.server = TestServer(app)
+        await self.server.start_server()
+        self.session = aiohttp.ClientSession()
+
+    async def asyncTearDown(self) -> None:
+        await self.session.close()
+        await self.server.close()
+
+    def given_client(self, **options: Any) -> HearthClient:
+        return HearthClient(self.session, self.API_KEY, str(self.server.make_url("/")), **options)
+
+    def given_hearth_answers(self,
+                             endpoint: str,
+                             status: int = 200,
+                             body: str = "",
+                             headers: dict[str, str] | None = None) -> None:
+        self.answers[endpoint] = (status, body, headers or {})
+
+    def posted(self, endpoint: str) -> list[Any]:
+        return self.posts.get(endpoint, [])
+
+    async def _answer(self, request: web.Request) -> web.Response:
+        endpoint = request.match_info["endpoint"]
+        self.posts.setdefault(endpoint, []).append(await request.json())
+        self.authorizations.append(request.headers.get("Authorization"))
+        status, body, headers = self.answers.get(endpoint, (204, "", {}))
+        return web.Response(status=status, text=body, headers=headers)