haaslab 0.1.0__py3-none-any.whl

haaslab/__init__.py

@@ -0,0 +1,19 @@
+from .client import Client
+from .models import Job, Token, CreatedToken, JobList, Pagination
+from .exceptions import HaasLabError, AuthError, NotFoundError, RateLimitError, ServerError
+
+__all__ = [
+    "Client",
+    "Job",
+    "Token",
+    "CreatedToken",
+    "JobList",
+    "Pagination",
+    "HaasLabError",
+    "AuthError",
+    "NotFoundError",
+    "RateLimitError",
+    "ServerError",
+]
+
+__version__ = "0.1.0"

haaslab/client.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import os
+
+import httpx
+
+from .jobs import JobsNamespace
+from .tokens import TokensNamespace
+
+DEFAULT_BASE_URL = "https://haas-lab.com"
+_SDK_VERSION = "0.1.0"
+
+
+class Client:
+    """haas-lab API client.
+
+    Usage::
+
+        from haaslab import Client
+        c = Client(token="pat_xxx")
+        job = c.jobs.create("blink.bin")
+        job = c.jobs.wait(job.id)
+        print(job.serial)  # not on Job; call c.jobs.serial(job.id)
+    """
+
+    def __init__(
+        self,
+        token: str | None = None,
+        base_url: str | None = None,
+        timeout: float = 30.0,
+    ) -> None:
+        # The docs page and the README promise these two variables (HAAS-389).
+        token = token or os.environ.get("HAASLAB_TOKEN")
+        if not token:
+            raise ValueError("no token: pass Client(token=...) or set HAASLAB_TOKEN")
+        base_url = base_url or os.environ.get("HAASLAB_BASE_URL") or DEFAULT_BASE_URL
+        api_base = base_url.rstrip("/") + "/api/v1"
+        self._http = httpx.Client(
+            base_url=api_base,
+            headers={
+                "Authorization": f"Bearer {token}",
+                "User-Agent": f"haaslab-python/{_SDK_VERSION}",
+            },
+            timeout=timeout,
+        )
+        self.jobs = JobsNamespace(self._http)
+        self.tokens = TokensNamespace(self._http)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "Client":
+        return self
+
+    def __exit__(self, *_) -> None:
+        self.close()

haaslab/exceptions.py

@@ -0,0 +1,20 @@
+class HaasLabError(Exception):
+    def __init__(self, message: str, status_code: int | None = None):
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class AuthError(HaasLabError):
+    """401 Unauthorized — invalid or missing PAT."""
+
+
+class NotFoundError(HaasLabError):
+    """404 Not Found."""
+
+
+class RateLimitError(HaasLabError):
+    """429 Too Many Requests."""
+
+
+class ServerError(HaasLabError):
+    """5xx Server Error."""

haaslab/jobs.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+import time
+from pathlib import Path
+from typing import Iterator, Union
+
+import httpx
+
+from .models import Job, JobList, Pagination, TERMINAL_STATUSES
+from .exceptions import HaasLabError
+
+
+class JobsNamespace:
+    def __init__(self, http: httpx.Client) -> None:
+        self._http = http
+
+    def create(
+        self,
+        firmware: Union[str, Path, bytes],
+        name: str | None = None,
+        *,
+        profile_key: str | None = None,
+        device_id: str | None = None,
+        expected_runtime_s: int | None = None,
+    ) -> Job:
+        """Submit a firmware and book its window.
+
+        ``expected_runtime_s`` is the run time you book; the job's booked window
+        is that plus the profile's flash allowance, and it is what the escrow
+        is reserved against. ``profile_key`` asks for any board of that
+        profile, ``device_id`` for one board in particular; neither means any
+        board that is online. Returns the Job in QUEUED status.
+        """
+        if isinstance(firmware, (str, Path)):
+            path = Path(firmware)
+            data = path.read_bytes()
+            filename = path.name
+        else:
+            data = firmware
+            filename = name or "firmware.bin"
+
+        files = {"firmware": (filename, data, "application/octet-stream")}
+        fields: dict[str, str] = {}
+        if profile_key is not None:
+            fields["profile_key"] = profile_key
+        if device_id is not None:
+            fields["device_id"] = device_id
+        if expected_runtime_s is not None:
+            fields["expected_runtime_s"] = str(expected_runtime_s)
+        resp = self._http.post("/jobs", files=files, data=fields)
+        _raise_for_status(resp)
+        return Job.from_dict(resp.json())
+
+    def get(self, job_id: str) -> Job:
+        resp = self._http.get(f"/jobs/{job_id}")
+        _raise_for_status(resp)
+        return Job.from_dict(resp.json())
+
+    def list(self, limit: int = 20, page: int = 1) -> list[Job]:
+        resp = self._http.get("/jobs", params={"page": page})
+        _raise_for_status(resp)
+        body = resp.json()
+        jobs = [Job.from_dict(j) for j in body["data"]]
+        return jobs[:limit]
+
+    def serial(self, job_id: str) -> str:
+        """Return the full archived serial log as a string."""
+        resp = self._http.get(f"/jobs/{job_id}/serial")
+        _raise_for_status(resp)
+        return resp.text
+
+    def stream_serial(self, job_id: str) -> Iterator[str]:
+        """Yield lines from the live SSE serial stream."""
+        from httpx_sse import connect_sse
+
+        with connect_sse(self._http, "GET", f"/jobs/{job_id}/stream") as event_source:
+            for event in event_source.iter_sse():
+                if event.event == "done":
+                    break
+                if event.data:
+                    yield event.data
+
+    def wait(self, job_id: str, timeout: float = 120, poll_interval: float = 2.0) -> Job:
+        """Poll until the job reaches a terminal status or timeout expires."""
+        deadline = time.monotonic() + timeout
+        while True:
+            job = self.get(job_id)
+            if job.is_terminal:
+                return job
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise HaasLabError(
+                    f"Job {job_id} did not reach terminal status within {timeout}s "
+                    f"(current status: {job.status})"
+                )
+            time.sleep(min(poll_interval, remaining))
+
+
+def _raise_for_status(resp: httpx.Response) -> None:
+    from .exceptions import AuthError, NotFoundError, RateLimitError, ServerError
+
+    if resp.status_code < 400:
+        return
+    try:
+        msg = resp.json().get("error", resp.text)
+    except Exception:
+        msg = resp.text
+
+    if resp.status_code == 401:
+        raise AuthError(msg, resp.status_code)
+    if resp.status_code == 404:
+        raise NotFoundError(msg, resp.status_code)
+    if resp.status_code == 429:
+        raise RateLimitError(msg, resp.status_code)
+    if resp.status_code >= 500:
+        raise ServerError(msg, resp.status_code)
+    raise HaasLabError(msg, resp.status_code)

haaslab/models.py

@@ -0,0 +1,145 @@
+# synced from /api/v1/openapi.json
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Literal, Optional
+
+
+# Every status the server can answer with, from the schema's JobStatus enum;
+# the six the API document used to list were a subset, and SETTLED — the
+# state a successful job actually ends in, written by settlement in the same
+# request as completion — was not among them, so `wait` never returned on
+# success (review, 2026-09-05).
+JobStatus = Literal[
+    "DRAFT",
+    "STATIC_CHECK",
+    "STATIC_CHECK_FAILED",
+    "ESTIMATED",
+    "ESCROW_HELD",
+    "QUEUED",
+    "CLAIMED",
+    "FLASHING",
+    "RUNNING",
+    "COMPLETED",
+    "FAILED",
+    "CANCELLED",
+    "DAMAGE_REVIEW",
+    "SETTLED",
+]
+
+# Nothing moves a job out of these. COMPLETED is included because a job that
+# has no escrow to settle stays there; SETTLED is where a settled one ends.
+TERMINAL_STATUSES = {"COMPLETED", "FAILED", "CANCELLED", "SETTLED", "STATIC_CHECK_FAILED"}
+
+
+@dataclass
+class Job:
+    id: str
+    userId: str
+    status: JobStatus
+    firmwareUrl: str
+    firmwareSize: int
+    serialLogUrl: Optional[str]
+    createdAt: str
+    startedAt: Optional[str]
+    completedAt: Optional[str]
+    # One-based place among the jobs waiting for the same boards while the job is
+    # QUEUED; None in every other status, and None from a server older than the
+    # field. Jobs are taken oldest first, so it only falls, except when a job
+    # created earlier is confirmed late or requeued after a board failed it.
+    queuePosition: Optional[int] = None
+    # The booked window (HAAS-20): the board seconds chosen at submit, the
+    # moment the window closes once the job is on a board, and why it ended.
+    # None from a server older than the fields, and for jobs from before them.
+    bookedSeconds: Optional[int] = None
+    expiresAt: Optional[str] = None
+    endedReason: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "Job":
+        return cls(
+            id=d["id"],
+            userId=d["userId"],
+            status=d["status"],
+            firmwareUrl=d["firmwareUrl"],
+            firmwareSize=d["firmwareSize"],
+            serialLogUrl=d.get("serialLogUrl"),
+            createdAt=d["createdAt"],
+            startedAt=d.get("startedAt"),
+            completedAt=d.get("completedAt"),
+            queuePosition=d.get("queuePosition"),
+            bookedSeconds=d.get("bookedSeconds"),
+            expiresAt=d.get("expiresAt"),
+            endedReason=d.get("endedReason"),
+        )
+
+    @property
+    def is_terminal(self) -> bool:
+        return self.status in TERMINAL_STATUSES
+
+    @property
+    def is_queued(self) -> bool:
+        return self.status == "QUEUED"
+
+
+@dataclass
+class Token:
+    id: str
+    name: str
+    createdAt: str
+    lastUsedAt: Optional[str]
+    revokedAt: Optional[str]
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "Token":
+        return cls(
+            id=d["id"],
+            name=d["name"],
+            createdAt=d["createdAt"],
+            lastUsedAt=d.get("lastUsedAt"),
+            revokedAt=d.get("revokedAt"),
+        )
+
+
+@dataclass
+class CreatedToken:
+    """Returned once on token creation — includes the plaintext PAT."""
+    id: str
+    name: str
+    createdAt: str
+    lastUsedAt: Optional[str]
+    revokedAt: Optional[str]
+    token: str
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "CreatedToken":
+        return cls(
+            id=d["id"],
+            name=d["name"],
+            createdAt=d["createdAt"],
+            lastUsedAt=d.get("lastUsedAt"),
+            revokedAt=d.get("revokedAt"),
+            token=d["token"],
+        )
+
+
+@dataclass
+class Pagination:
+    page: int
+    pageSize: int
+    total: int
+    totalPages: int
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "Pagination":
+        return cls(
+            page=d["page"],
+            pageSize=d["pageSize"],
+            total=d["total"],
+            totalPages=d["totalPages"],
+        )
+
+
+@dataclass
+class JobList:
+    data: list[Job]
+    meta: Pagination

haaslab/tokens.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+import httpx
+
+from .models import Token, CreatedToken
+from .jobs import _raise_for_status
+
+
+class TokensNamespace:
+    def __init__(self, http: httpx.Client) -> None:
+        self._http = http
+
+    def list(self) -> list[Token]:
+        resp = self._http.get("/tokens")
+        _raise_for_status(resp)
+        return [Token.from_dict(t) for t in resp.json()]
+
+    def create(self, name: str) -> CreatedToken:
+        """Create a new PAT. The plaintext token is returned once in CreatedToken.token."""
+        resp = self._http.post("/tokens", json={"name": name})
+        _raise_for_status(resp)
+        return CreatedToken.from_dict(resp.json())
+
+    def revoke(self, token_id: str) -> None:
+        resp = self._http.delete(f"/tokens/{token_id}")
+        _raise_for_status(resp)

haaslab-0.1.0.dist-info/METADATA

@@ -0,0 +1,110 @@
+Metadata-Version: 2.5
+Name: haaslab
+Version: 0.1.0
+Summary: Python SDK for the haas-lab hardware-as-a-service API
+Project-URL: Homepage, https://haas-lab.com
+Project-URL: Documentation, https://haas-lab.com/docs
+License: MIT
+Requires-Python: >=3.9
+Requires-Dist: httpx-sse>=0.4.0
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: dev
+Requires-Dist: pytest-httpx>=0.30.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# haaslab Python SDK
+
+Python client for the [haas-lab](https://haas-lab.com) hardware-as-a-service API.
+
+## Install
+
+```bash
+pip install haaslab
+```
+
+Requires Python 3.9+. You need a Personal Access Token: create one at
+https://haas-lab.com/dashboard/tokens after signing in.
+
+## Quickstart
+
+```python
+from haaslab import Client
+
+c = Client(token="pat_xxx")              # or set HAASLAB_TOKEN and call Client()
+job = c.jobs.create("blink.bin")          # multipart upload
+job = c.jobs.wait(job.id, timeout=120)    # poll until terminal
+print(c.jobs.serial(job.id))              # full archived log
+```
+
+## Live streaming
+
+```python
+for line in c.jobs.stream_serial(job.id):
+    print(line)
+```
+
+## Token management
+
+```python
+tok = c.tokens.create("ci-bot")
+print(tok.token)          # plaintext PAT — shown once
+
+c.tokens.list()           # list all tokens
+c.tokens.revoke(tok.id)   # revoke a token
+```
+
+## API Reference
+
+### `Client(token, base_url, timeout)`
+
+| Param | Default | Description |
+|---|---|---|
+| `token` | `$HAASLAB_TOKEN` | Personal Access Token (`pat_xxx`); `ValueError` if neither is set |
+| `base_url` | `$HAASLAB_BASE_URL`, else `https://haas-lab.com` | Base URL of the server |
+| `timeout` | `30.0` | HTTP request timeout in seconds |
+
+### `client.jobs`
+
+| Method | Returns | Description |
+|---|---|---|
+| `create(firmware, name=None, *, profile_key=None, device_id=None, expected_runtime_s=None)` | `Job` | Upload a firmware `.bin` and queue it; `profile_key` asks for any board of that profile, `device_id` for one board, `expected_runtime_s` is the run time you book |
+| `get(job_id)` | `Job` | Fetch job by ID |
+| `list(limit=20, page=1)` | `list[Job]` | List jobs (paginated) |
+| `serial(job_id)` | `str` | Full archived serial log |
+| `stream_serial(job_id)` | `Iterator[str]` | Live SSE serial lines |
+| `wait(job_id, timeout=120)` | `Job` | Poll until COMPLETED/FAILED/CANCELLED |
+
+### `client.tokens`
+
+| Method | Returns | Description |
+|---|---|---|
+| `list()` | `list[Token]` | List PATs (no plaintext) |
+| `create(name)` | `CreatedToken` | Create PAT (plaintext in `.token`, shown once) |
+| `revoke(id)` | `None` | Revoke a PAT |
+
+### Exceptions
+
+| Exception | HTTP status |
+|---|---|
+| `AuthError` | 401 |
+| `NotFoundError` | 404 |
+| `RateLimitError` | 429 |
+| `ServerError` | 5xx |
+| `HaasLabError` | base class / other 4xx |
+
+## Environment variables
+
+`Client()` reads these when `token` or `base_url` is not passed:
+
+```bash
+export HAASLAB_TOKEN=pat_xxx                    # your Personal Access Token
+export HAASLAB_BASE_URL=http://localhost:3000   # optional; defaults to https://haas-lab.com
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest -v
+```

haaslab-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+haaslab/__init__.py,sha256=vTQwD0MGrIofmvkMg5HsiCNUO8IDjfRTAoGHd-qCwB0,432
+haaslab/client.py,sha256=yRp_vix1T2Sl38aM7p5S01w1jGONl7bSXezeXLM1V_s,1590
+haaslab/exceptions.py,sha256=jLGBMAcgWEes-ykXGcQFJCY8zfXdhnAy6lAXrfV2mJw,478
+haaslab/jobs.py,sha256=HNufo6tk754KO3NNf5v2npT8AzfahCwQk0FD5MC3XjI,4308
+haaslab/models.py,sha256=EgX_8xK1pgOd0ArrQjyJo-VoGzfttnv0OGkfYPup544,4201
+haaslab/tokens.py,sha256=9F5NArBmu4hT2dSAfCMJbfVncKgLXbz5Uu5OcT_DnrE,843
+haaslab-0.1.0.dist-info/METADATA,sha256=d0ghaQYagKsQxuNGhoLgQ8kKJG24iK63Ojk1wgAEwso,3170
+haaslab-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+haaslab-0.1.0.dist-info/RECORD,,

haaslab-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any