aiohortos 0.1.0__tar.gz

aiohortos-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test on Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+      - name: Install
+        run: uv sync --group dev
+      - name: Ruff check
+        run: uv run ruff check .
+      - name: Ruff format
+        run: uv run ruff format --check .
+      - name: Mypy
+        run: uv run mypy src
+      - name: Pytest
+        run: uv run pytest --cov-fail-under=100

aiohortos-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,48 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.13"
+      - name: Check the tag matches the project version
+        run: |
+          version="$(uv run --no-project python -c 'import tomllib,pathlib;print(tomllib.loads(pathlib.Path("pyproject.toml").read_text())["project"]["version"])')"
+          if [ "v${version}" != "${GITHUB_REF_NAME}" ]; then
+            echo "Tag ${GITHUB_REF_NAME} does not match version ${version}" >&2
+            exit 1
+          fi
+      - name: Build
+        run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/aiohortos
+    permissions:
+      # Required for PyPI trusted publishing; no API token is stored anywhere.
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

aiohortos-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/

aiohortos-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Willem Vooijs
+
+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.

aiohortos-0.1.0/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: aiohortos
+Version: 0.1.0
+Summary: Async client for the Ridder HortOS Automation API (HortiMaX greenhouse controllers)
+Project-URL: Homepage, https://github.com/wildekek/aiohortos
+Project-URL: Issues, https://github.com/wildekek/aiohortos/issues
+Project-URL: Changelog, https://github.com/wildekek/aiohortos/releases
+Author-email: Willem Vooijs <willem@vooijs.eu>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: asyncio,greenhouse,horticulture,hortimax,hortos,ridder
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Home Automation
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: yarl>=1.9
+Description-Content-Type: text/markdown
+
+# aiohortos
+
+Async Python client for the **Ridder HortOS Automation API**, the cloud API
+behind [HortiMaX](https://www.ridder.com/) greenhouse process controllers.
+
+The library is **read-only**: it authenticates with an API key and reads
+controllers, their health, and their readouts. It never writes setpoints.
+
+```bash
+pip install aiohortos
+```
+
+## Usage
+
+```python
+import asyncio
+
+from aiohortos import HortosClient
+
+
+async def main() -> None:
+    async with HortosClient("your-api-key") as client:
+        for device in await client.get_devices():
+            print(device.name, device.label)
+            for readout in await client.get_latest_readouts(device.name):
+                print(
+                    f"  {readout.source.display_name}: "
+                    f"{readout.identifier} = {readout.value} {readout.unit or ''}"
+                )
+
+
+asyncio.run(main())
+```
+
+Pass an existing session to share a connection pool — which is what you want
+inside an application that already has one:
+
+```python
+async with aiohttp.ClientSession() as session:
+    client = HortosClient("your-api-key", session=session)
+```
+
+The client also accepts a `base_url`, for on-premise HortOS installations that
+serve the same API from your own network.
+
+## API surface
+
+| Method | Returns |
+| --- | --- |
+| `authenticate()` | `TokenPair` — normally not needed; every call authenticates on demand |
+| `get_device_names()` | `list[str]` of controller identifiers |
+| `get_devices()` | `list[Device]` with the friendly label |
+| `get_devices_health()` | `list[DeviceHealth]` — online state, sync state |
+| `get_readout_definitions(device)` | `list[ReadoutDefinition]` |
+| `get_latest_readouts(device)` | `list[Readout]` with the newest value each |
+| `get_readout_history(...)` | `list[ReadoutValue]` over a window of ≤ 24 hours |
+
+Errors all derive from `HortosError`:
+
+- `HortosAuthenticationError` — the API key or token was rejected (HTTP 401/403)
+- `HortosConnectionError` — the API could not be reached, or timed out
+- `HortosResponseError` — an unexpected status or payload, with `.status`
+
+## Notes on the API
+
+- Tokens live 15 minutes and are renewed with a refresh token valid 7 days.
+  The client handles both, and re-authenticates when a token is rejected.
+- The API allows **100 requests per 15 seconds** per key. The library does not
+  throttle; pace your own polling.
+- Unchanged readouts are refreshed at most every 5 minutes, so polling faster
+  than that gains nothing.
+- Readout identifiers follow `<CamelCaseSubject>-<Kind>`, e.g.
+  `VentPositionLeewardSide-Measured`. One upstream typo exists in the wild:
+  `IrrigationVolume-Measuered`.
+- Some readouts have `unitIdentifier: "Scalar"` and a numeric value that is
+  really an enumeration member id from a table the API does not expose. They
+  are returned as-is; decoding them is the caller's problem.
+- `Readout.name` embeds the source's user-defined name and is a poor label on
+  its own — build names from `identifier` and `source` instead.
+
+Ridder's Swagger UI documents the API at
+<https://hortos.ridder.com/api/process-control/index.html>. The OpenAPI
+document lives at `{base_url}/v1/swagger.json` and needs a bearer token.
+
+## Development
+
+```bash
+uv venv && uv pip install -e . --group dev
+pytest
+ruff check . && ruff format --check . && mypy src
+```
+
+## Disclaimer
+
+Unofficial and not affiliated with Ridder. "HortOS" and "HortiMaX" are their
+trademarks.

aiohortos-0.1.0/README.md

@@ -0,0 +1,96 @@
+# aiohortos
+
+Async Python client for the **Ridder HortOS Automation API**, the cloud API
+behind [HortiMaX](https://www.ridder.com/) greenhouse process controllers.
+
+The library is **read-only**: it authenticates with an API key and reads
+controllers, their health, and their readouts. It never writes setpoints.
+
+```bash
+pip install aiohortos
+```
+
+## Usage
+
+```python
+import asyncio
+
+from aiohortos import HortosClient
+
+
+async def main() -> None:
+    async with HortosClient("your-api-key") as client:
+        for device in await client.get_devices():
+            print(device.name, device.label)
+            for readout in await client.get_latest_readouts(device.name):
+                print(
+                    f"  {readout.source.display_name}: "
+                    f"{readout.identifier} = {readout.value} {readout.unit or ''}"
+                )
+
+
+asyncio.run(main())
+```
+
+Pass an existing session to share a connection pool — which is what you want
+inside an application that already has one:
+
+```python
+async with aiohttp.ClientSession() as session:
+    client = HortosClient("your-api-key", session=session)
+```
+
+The client also accepts a `base_url`, for on-premise HortOS installations that
+serve the same API from your own network.
+
+## API surface
+
+| Method | Returns |
+| --- | --- |
+| `authenticate()` | `TokenPair` — normally not needed; every call authenticates on demand |
+| `get_device_names()` | `list[str]` of controller identifiers |
+| `get_devices()` | `list[Device]` with the friendly label |
+| `get_devices_health()` | `list[DeviceHealth]` — online state, sync state |
+| `get_readout_definitions(device)` | `list[ReadoutDefinition]` |
+| `get_latest_readouts(device)` | `list[Readout]` with the newest value each |
+| `get_readout_history(...)` | `list[ReadoutValue]` over a window of ≤ 24 hours |
+
+Errors all derive from `HortosError`:
+
+- `HortosAuthenticationError` — the API key or token was rejected (HTTP 401/403)
+- `HortosConnectionError` — the API could not be reached, or timed out
+- `HortosResponseError` — an unexpected status or payload, with `.status`
+
+## Notes on the API
+
+- Tokens live 15 minutes and are renewed with a refresh token valid 7 days.
+  The client handles both, and re-authenticates when a token is rejected.
+- The API allows **100 requests per 15 seconds** per key. The library does not
+  throttle; pace your own polling.
+- Unchanged readouts are refreshed at most every 5 minutes, so polling faster
+  than that gains nothing.
+- Readout identifiers follow `<CamelCaseSubject>-<Kind>`, e.g.
+  `VentPositionLeewardSide-Measured`. One upstream typo exists in the wild:
+  `IrrigationVolume-Measuered`.
+- Some readouts have `unitIdentifier: "Scalar"` and a numeric value that is
+  really an enumeration member id from a table the API does not expose. They
+  are returned as-is; decoding them is the caller's problem.
+- `Readout.name` embeds the source's user-defined name and is a poor label on
+  its own — build names from `identifier` and `source` instead.
+
+Ridder's Swagger UI documents the API at
+<https://hortos.ridder.com/api/process-control/index.html>. The OpenAPI
+document lives at `{base_url}/v1/swagger.json` and needs a bearer token.
+
+## Development
+
+```bash
+uv venv && uv pip install -e . --group dev
+pytest
+ruff check . && ruff format --check . && mypy src
+```
+
+## Disclaimer
+
+Unofficial and not affiliated with Ridder. "HortOS" and "HortiMaX" are their
+trademarks.

aiohortos-0.1.0/pyproject.toml

@@ -0,0 +1,86 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "aiohortos"
+version = "0.1.0"
+description = "Async client for the Ridder HortOS Automation API (HortiMaX greenhouse controllers)"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.13"
+authors = [{ name = "Willem Vooijs", email = "willem@vooijs.eu" }]
+keywords = ["hortos", "ridder", "hortimax", "greenhouse", "horticulture", "asyncio"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Framework :: AsyncIO",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Home Automation",
+  "Typing :: Typed",
+]
+dependencies = ["aiohttp>=3.9", "yarl>=1.9"]
+
+[project.urls]
+Homepage = "https://github.com/wildekek/aiohortos"
+Issues = "https://github.com/wildekek/aiohortos/issues"
+Changelog = "https://github.com/wildekek/aiohortos/releases"
+
+[dependency-groups]
+dev = [
+  "mypy==1.18.2",
+  "pytest==8.4.2",
+  "pytest-asyncio==1.2.0",
+  "pytest-cov==7.0.0",
+  "ruff==0.14.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/aiohortos"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+addopts = "--cov=aiohortos --cov-report=term-missing"
+
+[tool.ruff]
+target-version = "py313"
+line-length = 88
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+  "ANN401",  # Any is the honest type for raw JSON payloads
+  "COM812",  # conflicts with the formatter
+  "D203",    # incompatible with D211
+  "D213",    # incompatible with D212
+  "ISC001",  # conflicts with the formatter
+  "TRY003",  # long messages in raises read fine here
+  "EM101",   # ... and are clearer inline than via a variable
+  "EM102",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = [
+  "ANN201",  # test functions all return None
+  "C901",    # the fake server is branchy on purpose
+  "D103",    # test names say what they test
+  "D401",
+  "PLR2004", # literals in assertions are the point
+  "PT012",   # a few raises blocks set up their own input
+  "S101",    # pytest is built on assert
+  "S105",    # "tokens" in fixtures are not secrets
+  "SLF001",  # tests may reach into the client
+  "TC003",
+]
+
+[tool.mypy]
+python_version = "3.13"
+strict = true
+warn_unreachable = true
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_defs = false

aiohortos-0.1.0/src/aiohortos/__init__.py

@@ -0,0 +1,53 @@
+"""Async client for the Ridder HortOS Automation API."""
+
+from __future__ import annotations
+
+from .client import HortosClient
+from .const import (
+    DEFAULT_BASE_URL,
+    DEFAULT_TIMEOUT,
+    MAX_HISTORY_WINDOW,
+    RATE_LIMIT_REQUESTS,
+    RATE_LIMIT_WINDOW,
+)
+from .exceptions import (
+    HortosAuthenticationError,
+    HortosConnectionError,
+    HortosError,
+    HortosResponseError,
+)
+from .models import (
+    Device,
+    DeviceHealth,
+    OnlineStatus,
+    Organisation,
+    Readout,
+    ReadoutDefinition,
+    ReadoutValue,
+    ReadoutValueType,
+    Source,
+    TokenPair,
+)
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "DEFAULT_TIMEOUT",
+    "MAX_HISTORY_WINDOW",
+    "RATE_LIMIT_REQUESTS",
+    "RATE_LIMIT_WINDOW",
+    "Device",
+    "DeviceHealth",
+    "HortosAuthenticationError",
+    "HortosClient",
+    "HortosConnectionError",
+    "HortosError",
+    "HortosResponseError",
+    "OnlineStatus",
+    "Organisation",
+    "Readout",
+    "ReadoutDefinition",
+    "ReadoutValue",
+    "ReadoutValueType",
+    "Source",
+    "TokenPair",
+]