feat: add Python client package and CI

Author: integrii

.github/workflows/build.yml

@@ -0,0 +1,22 @@
+name: Build
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: "3.x"
+      - name: Build package
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+          python -m build
+      - name: Build example container
+        run: |
+          make build IMG=kuberhealthy-client:test

.github/workflows/publish.yml

@@ -0,0 +1,28 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: "3.x"
+      - name: Build package
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+          python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          user: __token__
+          password: ${{ secrets.PYPI_API_TOKEN }}
+      - name: Attach artifacts to release
+        uses: softprops/action-gh-release@v1
+        with:
+          files: dist/*

Dockerfile

@@ -1,6 +1,7 @@
 FROM python:3.11-alpine
 
 WORKDIR /app
+COPY kuberhealthy_client kuberhealthy_client
 COPY client.py .
 
 CMD ["python3", "/app/client.py"]

README.md

@@ -1,10 +1,26 @@
 # Python Kuberhealthy Client
 
-This directory contains a minimal Python application that demonstrates how to
-report status back to [Kuberhealthy](https://github.com/kuberhealthy/kuberhealthy).
-The example loads the `KH_REPORTING_URL` and `KH_RUN_UUID` environment variables
-provided to checker pods and includes commented calls to `report_ok` and
-`report_error`.
+This repository provides a small Python library for reporting check results back to [Kuberhealthy](https://github.com/kuberhealthy/kuberhealthy). It also includes a runnable example program and container configuration.
+
+## Installing
+
+Install the client into your own project:
+
+```bash
+pip install kuberhealthy-client
+```
+
+The library exposes two helpers:
+
+```python
+from kuberhealthy_client import report_ok, report_error
+
+# Environment variables KH_REPORTING_URL and KH_RUN_UUID are read automatically.
+report_ok()
+report_error("something went wrong")
+```
+
+Both functions accept optional `url` and `run_uuid` keyword arguments if you prefer to supply values directly.
 
 ## Running the example
 
@@ -30,9 +46,8 @@ make push IMG=myrepo/example-check:latest
 
 ## Using in your own checks
 
-1. Add your check logic to `client.py` by replacing the placeholder in `main`.
-   Call `report_ok()` when the check succeeds or `report_error("message")`
-   when it fails.
+1. Add your check logic to `client.py` or your own script. Call `report_ok()`
+   when the check succeeds or `report_error("message")` when it fails.
 2. Build and push your image as shown above.
 3. Create a `KuberhealthyCheck` resource pointing at your image and apply it to any
    cluster where Kuberhealthy runs:

client.py

@@ -1,45 +1,7 @@
 #!/usr/bin/env python3
-"""Example Kuberhealthy client in Python."""
+"""Example Kuberhealthy client using the :mod:`kuberhealthy_client` package."""
 
-import json
-import os
-import urllib.request
-
-
-KH_REPORTING_URL = "KH_REPORTING_URL"
-KH_RUN_UUID = "KH_RUN_UUID"
-
-
-def _get_env(name: str) -> str:
-    """Return the value of the environment variable *name* or raise an error."""
-    value = os.getenv(name)
-    if not value:
-        raise EnvironmentError(f"{name} must be set")
-    return value
-
-
-def _post_status(payload: dict) -> None:
-    """Send *payload* to the Kuberhealthy reporting URL."""
-    url = _get_env(KH_REPORTING_URL)
-    run_uuid = _get_env(KH_RUN_UUID)
-    data = json.dumps(payload).encode("utf-8")
-    request = urllib.request.Request(
-        url,
-        data=data,
-        headers={"content-type": "application/json", "kh-run-uuid": run_uuid},
-    )
-    with urllib.request.urlopen(request, timeout=10) as response:  # nosec B310
-        response.read()
-
-
-def report_ok() -> None:
-    """Report a successful check to Kuberhealthy."""
-    _post_status({"OK": True, "Errors": []})
-
-
-def report_error(message: str) -> None:
-    """Report a failure to Kuberhealthy with *message* as the error."""
-    _post_status({"OK": False, "Errors": [message]})
+from kuberhealthy_client import report_ok, report_error
 
 
 def main() -> None:

kuberhealthy_client/__init__.py

@@ -0,0 +1,41 @@
+"""Lightweight client for reporting check results to Kuberhealthy."""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.request
+from typing import Optional
+
+KH_REPORTING_URL = "KH_REPORTING_URL"
+KH_RUN_UUID = "KH_RUN_UUID"
+
+def _get_env(name: str) -> str:
+    """Return the value of the environment variable *name* or raise an error."""
+    value = os.getenv(name)
+    if not value:
+        raise EnvironmentError(f"{name} must be set")
+    return value
+
+def _post_status(payload: dict, *, url: Optional[str] = None, run_uuid: Optional[str] = None) -> None:
+    """Send *payload* to the Kuberhealthy reporting URL."""
+    url = url or _get_env(KH_REPORTING_URL)
+    run_uuid = run_uuid or _get_env(KH_RUN_UUID)
+    data = json.dumps(payload).encode("utf-8")
+    request = urllib.request.Request(
+        url,
+        data=data,
+        headers={"content-type": "application/json", "kh-run-uuid": run_uuid},
+    )
+    with urllib.request.urlopen(request, timeout=10) as response:  # nosec B310
+        response.read()
+
+def report_ok(*, url: Optional[str] = None, run_uuid: Optional[str] = None) -> None:
+    """Report a successful check to Kuberhealthy."""
+    _post_status({"OK": True, "Errors": []}, url=url, run_uuid=run_uuid)
+
+def report_error(message: str, *, url: Optional[str] = None, run_uuid: Optional[str] = None) -> None:
+    """Report a failure to Kuberhealthy with *message* as the error."""
+    _post_status({"OK": False, "Errors": [message]}, url=url, run_uuid=run_uuid)
+
+__all__ = ["report_ok", "report_error", "KH_REPORTING_URL", "KH_RUN_UUID"]

pyproject.toml

@@ -0,0 +1,16 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "kuberhealthy-client"
+version = "0.1.0"
+description = "Python client for reporting check results to Kuberhealthy"
+readme = "README.md"
+authors = [{name = "Kuberhealthy"}]
+license = {text = "Apache-2.0"}
+requires-python = ">=3.8"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["kuberhealthy_client"]