Metadata-Version: 2.4
Name: kerbl-iot
Version: 0.1.5
Summary: Async client for the Kerbl IoT web API
Project-URL: Source, https://github.com/derjoerg/kerbl-iot
Project-URL: Issues, https://github.com/derjoerg/kerbl-iot/issues
Author: derjoerg
License: MIT
License-File: LICENSE
Keywords: home-assistant,iot,kerbl,poultry,smartcoop
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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
Requires-Python: >=3.11
Requires-Dist: aiohttp<4,>=3.10
Requires-Dist: python-socketio[asyncio-client]<6,>=5.11
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == 'dev'
Requires-Dist: coverage[toml]<8,>=7.6; extra == 'dev'
Requires-Dist: pytest<9,>=8.3; extra == 'dev'
Requires-Dist: ruff<1,>=0.11; extra == 'dev'
Requires-Dist: twine<7,>=6; extra == 'dev'
Description-Content-Type: text/markdown

# Kerbl IoT

Async Python client for Kerbl IoT devices.

`KerblIOTApi` owns authentication, HTTP, token refresh, and Socket.IO transport.
`KerblIOT` loads devices and dispatches their live updates. Device actions belong to
their respective model classes.

```python
import asyncio
import os

from kerbl_iot import KerblIOT, KerblIOTApi


async def main() -> None:
    async with KerblIOT(
        KerblIOTApi(
            email=os.environ["KERBL_EMAIL"],
            password=os.environ["KERBL_PASSWORD"],
        )
    ) as kerbl:
        await kerbl.connect_websocket()

        coop = kerbl.smart_coops[0]
        print(coop.name, coop.air_temperature, coop.door.state)
        await coop.light.turn_on()
        await coop.door.close()


asyncio.run(main())
```

## Releasing to PyPI

When a version change is pushed to `main`, GitHub Actions first runs the complete
`ci.yml` workflow. Only after CI succeeds does `release.yml` create a matching tag,
GitHub Release, and publish the package to PyPI. Configure PyPI Trusted Publishing
for the `derjoerg/kerbl-iot` repository and the `.github/workflows/release.yml`
workflow, using the `pypi` environment.

`publish.yml` remains available for manually publishing an existing tag from the
GitHub Actions UI, for example when recovering a failed upload. Supply the tag as
the `workflow_dispatch` input.

To release a new version, update the `version` in `pyproject.toml` and merge that
change into `main`. The version must not already exist on PyPI, and the matching
`vX.Y.Z` tag must not already exist in GitHub.

## Error reason reference

`SmartCoopLog` exposes the API's raw `error_key` and `error_code`. Applications
should translate the key in their own presentation layer. The following table
preserves the German translations previously included in this library for
reference:

| API error key | Former German translation |
| --- | --- |
| `errorReason.doorLocked` | Klappe verriegelt |
| `errorReason.doorClosingSoon` | Klappe schliesst bald |
| `errorReason.feederLocked` | Futterautomat gesperrt |
| `errorReason.batteryLow` | Akku schwach |
| `errorReason.waterHeaterActive` | Wasserheizung aktiv |
| `errorReason.waterEmpty` | Wasser leer |
| `errorReason.feederError` | Futterautomatenstoerung |
| `errorReason.feedEmpty` | Futter leer |
| `errorReason.batteryEmpty` | Akku leer |
| `errorReason.doorError` | Klappenstoerung |
| `errorReason.waterTemperatureLow` | Wassertemperatur zu niedrig |
| `errorReason.externalLightError` | Fremdlichtstoerung |
| `errorReason.timeError` | Uhrzeit muss eingestellt werden |
| `errorReason.flashError` | Flash-Fehler |
