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!
