whiskops-sdk 0.1.0__tar.gz

whiskops_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.4
+Name: whiskops-sdk
+Version: 0.1.0
+Summary: Client SDK for the Whisk device External API (status, turn, stop).
+Author: Codemenschen GmbH
+License-Expression: MIT
+Keywords: whisk,iot,device-control,sdk
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28
+
+# whiskops-sdk (Python)
+
+Client SDK for the Whisk device External API. Wraps bearer-token auth,
+idempotency-key generation for `turn`, retry with backoff on 429/5xx, and
+client-side spacing between `turn` calls.
+
+## Usage
+
+```python
+import os
+from whiskops_sdk import WhiskClient
+
+client = WhiskClient(api_key=os.environ["WHISK_API_KEY"])
+
+status = client.status()
+if status["online"]:
+    client.turn(speed=80)
+    client.stop()
+```
+
+## Notes
+
+- `turn()` validates `speed` is an integer 1-500 before making a request.
+- A 409 response (active Time/Turns session) is not retried — it is raised
+  as a `WhiskApiError` since retrying would not resolve the conflict.
+- `base_url` defaults to `https://myremotedevice.com/api/v1/external` per the
+  published API docs; pass a different one to the constructor if the real
+  production host differs.
+
+## Tests
+
+```
+python -m venv .venv && .venv/bin/pip install -e . pytest
+.venv/bin/pytest
+```

whiskops_sdk-0.1.0/README.md

@@ -0,0 +1,35 @@
+# whiskops-sdk (Python)
+
+Client SDK for the Whisk device External API. Wraps bearer-token auth,
+idempotency-key generation for `turn`, retry with backoff on 429/5xx, and
+client-side spacing between `turn` calls.
+
+## Usage
+
+```python
+import os
+from whiskops_sdk import WhiskClient
+
+client = WhiskClient(api_key=os.environ["WHISK_API_KEY"])
+
+status = client.status()
+if status["online"]:
+    client.turn(speed=80)
+    client.stop()
+```
+
+## Notes
+
+- `turn()` validates `speed` is an integer 1-500 before making a request.
+- A 409 response (active Time/Turns session) is not retried — it is raised
+  as a `WhiskApiError` since retrying would not resolve the conflict.
+- `base_url` defaults to `https://myremotedevice.com/api/v1/external` per the
+  published API docs; pass a different one to the constructor if the real
+  production host differs.
+
+## Tests
+
+```
+python -m venv .venv && .venv/bin/pip install -e . pytest
+.venv/bin/pytest
+```

whiskops_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,17 @@
+[project]
+name = "whiskops-sdk"
+version = "0.1.0"
+description = "Client SDK for the Whisk device External API (status, turn, stop)."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+dependencies = ["requests>=2.28"]
+authors = [{ name = "Codemenschen GmbH" }]
+keywords = ["whisk", "iot", "device-control", "sdk"]
+
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["whiskops_sdk*"]

whiskops_sdk-0.1.0/setup.cfg

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

whiskops_sdk-0.1.0/tests/test_client.py

@@ -0,0 +1,76 @@
+import pytest
+
+from whiskops_sdk import WhiskClient, WhiskApiError
+
+
+class FakeResponse:
+    def __init__(self, status_code, json_data=None, text="", headers=None):
+        self.status_code = status_code
+        self._json = json_data
+        self.text = text
+        self.headers = headers or {}
+        self.content = text.encode() if text else (b"{}" if json_data is not None else b"")
+
+    @property
+    def ok(self):
+        return 200 <= self.status_code < 400
+
+    def json(self):
+        return self._json
+
+
+class FakeSession:
+    def __init__(self, responses):
+        self._responses = list(responses)
+        self.calls = []
+
+    def request(self, method, url, headers=None, json=None, timeout=None):
+        self.calls.append({"method": method, "url": url, "headers": headers, "json": json})
+        return self._responses.pop(0)
+
+
+def make_client(responses, **kwargs):
+    session = FakeSession(responses)
+    client = WhiskClient(api_key="twk_test", session=session, **kwargs)
+    return client, session
+
+
+def test_status_sends_bearer_auth():
+    client, session = make_client([FakeResponse(200, json_data={"online": False})])
+    result = client.status()
+    assert result == {"online": False}
+    assert session.calls[0]["headers"]["Authorization"] == "Bearer twk_test"
+    assert session.calls[0]["url"] == "https://myremotedevice.com/api/v1/external/device/status"
+
+
+def test_turn_rejects_out_of_range_speed_without_request():
+    client, session = make_client([], min_turn_interval_s=0)
+    with pytest.raises(ValueError):
+        client.turn(speed=0)
+    with pytest.raises(ValueError):
+        client.turn(speed=501)
+    assert session.calls == []
+
+
+def test_turn_attaches_generated_idempotency_key():
+    client, session = make_client([FakeResponse(202)], min_turn_interval_s=0)
+    client.turn(speed=50)
+    key = session.calls[0]["headers"]["Idempotency-Key"]
+    assert key
+
+
+def test_retries_on_500_then_succeeds():
+    client, session = make_client(
+        [FakeResponse(500, text="boom"), FakeResponse(200, json_data={"online": True})],
+        max_retries=2,
+    )
+    result = client.status()
+    assert result == {"online": True}
+    assert len(session.calls) == 2
+
+
+def test_does_not_retry_409():
+    client, session = make_client([FakeResponse(409, text="conflict")], min_turn_interval_s=0)
+    with pytest.raises(WhiskApiError):
+        client.turn(speed=50)
+    assert len(session.calls) == 1

whiskops_sdk-0.1.0/tests/test_sandbox_integration.py

@@ -0,0 +1,60 @@
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+import pytest
+import requests
+
+from whiskops_sdk import WhiskClient, WhiskApiError
+
+PORT = 4179
+TOKEN = "twk_sandbox_demo_token"
+BASE_URL = f"http://localhost:{PORT}"
+SANDBOX_ENTRY = Path(__file__).resolve().parents[2] / "sandbox-api" / "server.mjs"
+
+
+@pytest.fixture(scope="module")
+def sandbox_server():
+    proc = subprocess.Popen(
+        ["node", str(SANDBOX_ENTRY)],
+        env={"PORT": str(PORT), "SANDBOX_TOKEN": TOKEN, "PATH": "/usr/bin:/bin:/usr/local/bin:/opt/homebrew/bin"},
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+    )
+    deadline = time.monotonic() + 5
+    while time.monotonic() < deadline:
+        try:
+            requests.get(f"{BASE_URL}/device/status", headers={"Authorization": f"Bearer {TOKEN}"}, timeout=1)
+            break
+        except requests.RequestException:
+            time.sleep(0.1)
+    else:
+        proc.kill()
+        raise RuntimeError("sandbox server did not start in time")
+    yield
+    proc.kill()
+
+
+def test_full_status_turn_stop_flow(sandbox_server):
+    client = WhiskClient(api_key=TOKEN, base_url=BASE_URL, min_turn_interval_s=0)
+
+    status = client.status()
+    assert status == {"online": True}
+
+    turn_result = client.turn(speed=120, idempotency_key="py-flow-key")
+    assert turn_result["status"] == "accepted"
+    assert turn_result["speed"] == 120
+
+    stop_result = client.stop()
+    assert stop_result == {"stopped": True}
+
+
+def test_second_turn_while_active_is_409(sandbox_server):
+    client = WhiskClient(api_key=TOKEN, base_url=BASE_URL, min_turn_interval_s=0)
+
+    client.turn(speed=30, idempotency_key="py-session-a")
+    with pytest.raises(WhiskApiError) as excinfo:
+        client.turn(speed=30, idempotency_key="py-session-b")
+    assert excinfo.value.status == 409
+    client.stop()

whiskops_sdk-0.1.0/whiskops_sdk/__init__.py

@@ -0,0 +1,5 @@
+"""Client SDK for the Whisk device External API."""
+
+from .client import WhiskClient, WhiskApiError
+
+__all__ = ["WhiskClient", "WhiskApiError"]

whiskops_sdk-0.1.0/whiskops_sdk/client.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+import time
+import uuid
+from typing import Any, Optional
+
+import requests
+
+DEFAULT_BASE_URL = "https://myremotedevice.com/api/v1/external"
+MIN_SPEED = 1
+MAX_SPEED = 500
+MIN_TURN_INTERVAL_S = 1.0
+
+
+class WhiskApiError(Exception):
+    def __init__(self, message: str, status: Optional[int] = None, body: Optional[str] = None):
+        super().__init__(message)
+        self.status = status
+        self.body = body
+
+
+class WhiskClient:
+    """Client for the Whisk device External API.
+
+    Wraps bearer-token auth, idempotency-key generation for ``turn``, and
+    retry with exponential backoff on transient failures (429 / 5xx). A 409
+    from ``turn`` (an active Time/Turns session) is not retried and is raised
+    as a :class:`WhiskApiError`.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        max_retries: int = 3,
+        min_turn_interval_s: float = MIN_TURN_INTERVAL_S,
+        session: Optional[requests.Session] = None,
+    ):
+        if not api_key:
+            raise ValueError("WhiskClient requires api_key")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.max_retries = max_retries
+        self.min_turn_interval_s = min_turn_interval_s
+        self._session = session or requests.Session()
+        self._last_turn_at = 0.0
+
+    def _request(self, method: str, path: str, headers: Optional[dict] = None, json: Optional[dict] = None) -> Any:
+        url = f"{self.base_url}{path}"
+        req_headers = {"Authorization": f"Bearer {self.api_key}", **(headers or {})}
+
+        attempt = 0
+        while True:
+            resp = self._session.request(method, url, headers=req_headers, json=json, timeout=10)
+
+            if resp.status_code == 429 or resp.status_code >= 500:
+                if attempt >= self.max_retries:
+                    raise WhiskApiError(
+                        f"{method} {path} failed after {attempt + 1} attempts: {resp.status_code}",
+                        status=resp.status_code,
+                        body=resp.text,
+                    )
+                retry_after = resp.headers.get("Retry-After")
+                try:
+                    backoff = float(retry_after) if retry_after else (2 ** attempt) * 0.5
+                except ValueError:
+                    backoff = (2 ** attempt) * 0.5
+                time.sleep(backoff)
+                attempt += 1
+                continue
+
+            if not resp.ok:
+                raise WhiskApiError(f"{method} {path} failed: {resp.status_code}", status=resp.status_code, body=resp.text)
+
+            if resp.status_code == 204 or not resp.content:
+                return None
+            return resp.json()
+
+    def status(self) -> dict:
+        """Read current device status. Offline devices return `{"online": false}` successfully."""
+        return self._request("GET", "/device/status")
+
+    def turn(self, speed: int, idempotency_key: Optional[str] = None) -> Any:
+        """Start a single turn.
+
+        :param speed: Integer 1-500.
+        :param idempotency_key: Supply your own to control retries/dedup explicitly;
+            otherwise one is generated per call.
+        """
+        if not isinstance(speed, int) or isinstance(speed, bool) or not (MIN_SPEED <= speed <= MAX_SPEED):
+            raise ValueError(f"speed must be an integer between {MIN_SPEED} and {MAX_SPEED}")
+
+        elapsed = time.monotonic() - self._last_turn_at
+        if elapsed < self.min_turn_interval_s:
+            time.sleep(self.min_turn_interval_s - elapsed)
+        self._last_turn_at = time.monotonic()
+
+        key = idempotency_key or str(uuid.uuid4())
+        return self._request("POST", "/device/turn", headers={"Idempotency-Key": key}, json={"speed": speed})
+
+    def stop(self) -> Any:
+        """Stop the device. Also ends any active Time/Turns session."""
+        return self._request("POST", "/device/stop")

whiskops_sdk-0.1.0/whiskops_sdk.egg-info/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.4
+Name: whiskops-sdk
+Version: 0.1.0
+Summary: Client SDK for the Whisk device External API (status, turn, stop).
+Author: Codemenschen GmbH
+License-Expression: MIT
+Keywords: whisk,iot,device-control,sdk
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28
+
+# whiskops-sdk (Python)
+
+Client SDK for the Whisk device External API. Wraps bearer-token auth,
+idempotency-key generation for `turn`, retry with backoff on 429/5xx, and
+client-side spacing between `turn` calls.
+
+## Usage
+
+```python
+import os
+from whiskops_sdk import WhiskClient
+
+client = WhiskClient(api_key=os.environ["WHISK_API_KEY"])
+
+status = client.status()
+if status["online"]:
+    client.turn(speed=80)
+    client.stop()
+```
+
+## Notes
+
+- `turn()` validates `speed` is an integer 1-500 before making a request.
+- A 409 response (active Time/Turns session) is not retried — it is raised
+  as a `WhiskApiError` since retrying would not resolve the conflict.
+- `base_url` defaults to `https://myremotedevice.com/api/v1/external` per the
+  published API docs; pass a different one to the constructor if the real
+  production host differs.
+
+## Tests
+
+```
+python -m venv .venv && .venv/bin/pip install -e . pytest
+.venv/bin/pytest
+```

whiskops_sdk-0.1.0/whiskops_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+tests/test_client.py
+tests/test_sandbox_integration.py
+whiskops_sdk/__init__.py
+whiskops_sdk/client.py
+whiskops_sdk.egg-info/PKG-INFO
+whiskops_sdk.egg-info/SOURCES.txt
+whiskops_sdk.egg-info/dependency_links.txt
+whiskops_sdk.egg-info/requires.txt
+whiskops_sdk.egg-info/top_level.txt

whiskops_sdk-0.1.0/whiskops_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

whiskops_sdk-0.1.0/whiskops_sdk.egg-info/requires.txt

@@ -0,0 +1 @@
+requests>=2.28

whiskops_sdk-0.1.0/whiskops_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+whiskops_sdk