labtab 0.1.0__py3-none-any.whl

labtab/__init__.py

@@ -0,0 +1,5 @@
+"""labtab — command-line interface for LabTab (Wetware Ltd)."""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

labtab/auth.py

@@ -0,0 +1,178 @@
+"""Device-pairing primitives for the labtab CLI.
+
+The flow implemented by this module is:
+
+1. ``POST /cli/pair/start/`` with ``{client_info: {user_agent, hostname}}``.
+2. The server returns ``{pairing_code, confirm_url, expires_in}``.
+3. The user opens ``confirm_url`` in their browser (we try to open it for them
+   via :mod:`webbrowser`) and approves the pairing.
+4. Meanwhile the CLI polls ``GET /cli/pair/poll/?code=<pairing_code>`` every
+   ``poll_interval`` seconds. On ``status == "confirmed"`` the server returns
+   an API key plus a user profile which we persist to the config file.
+5. If the server reports ``expired`` or ``denied``, or we exceed ``timeout``
+   seconds of polling, we raise :class:`PairingError`.
+
+Agent L's backend endpoints are what we consume here. Until those endpoints
+land, tests mock the HTTP responses via :mod:`pytest_httpx`.
+"""
+
+from __future__ import annotations
+
+import platform
+import socket
+import time
+import webbrowser
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from . import __version__
+from .client import LabtabClient
+from .config import Config
+from .errors import APIError, PairingError
+from .models import CLIPairConfirm, CLIPairStart
+
+DEFAULT_POLL_INTERVAL = 2.0
+DEFAULT_TIMEOUT_SECONDS = 600  # 10 minutes
+
+
+def client_info() -> dict[str, str]:
+    """Metadata sent to ``/cli/pair/start/`` so users can identify a terminal."""
+
+    return {
+        "user_agent": f"labtab/{__version__} ({platform.system().lower()})",
+        "hostname": socket.gethostname(),
+    }
+
+
+@dataclass
+class PairingResult:
+    """Result of a successful pairing — used to populate the config."""
+
+    api_key: str
+    user_email: str | None
+    default_lab_id: int | None
+    default_lab_slug: str | None
+
+
+def start_pairing(client: LabtabClient) -> CLIPairStart:
+    """Initiate the pairing flow. Does not require authentication."""
+
+    payload = client.request(
+        "POST",
+        "/cli/pair/start/",
+        json={"client_info": client_info()},
+        require_auth=False,
+    )
+    try:
+        return CLIPairStart.model_validate(payload)
+    except Exception as exc:  # pragma: no cover - validation details
+        raise PairingError(f"Unexpected response from /cli/pair/start/: {exc}") from exc
+
+
+def poll_pairing(client: LabtabClient, code: str) -> CLIPairConfirm:
+    """Poll once for the pairing status."""
+
+    payload = client.request(
+        "GET",
+        "/cli/pair/poll/",
+        params={"code": code},
+        require_auth=False,
+    )
+    try:
+        return CLIPairConfirm.model_validate(payload)
+    except Exception as exc:  # pragma: no cover - validation details
+        raise PairingError(f"Unexpected response from /cli/pair/poll/: {exc}") from exc
+
+
+def maybe_open_browser(url: str, *, enabled: bool) -> None:
+    """Open ``url`` in the default browser unless ``enabled`` is False."""
+
+    if not enabled:
+        return
+    try:
+        webbrowser.open(url)
+    except webbrowser.Error:  # pragma: no cover - platform specific
+        pass
+
+
+def run_pairing(
+    client: LabtabClient,
+    *,
+    open_browser: bool = True,
+    poll_interval: float = DEFAULT_POLL_INTERVAL,
+    timeout: float = DEFAULT_TIMEOUT_SECONDS,
+    on_start: Callable[[CLIPairStart], None] | None = None,
+    sleep: Callable[[float], None] = time.sleep,
+    now: Callable[[], float] = time.monotonic,
+) -> PairingResult:
+    """Drive the full pairing flow.
+
+    ``on_start`` is called once with the start payload so callers can print the
+    confirmation URL and code. ``sleep`` and ``now`` are injectable for tests.
+    """
+
+    try:
+        start = start_pairing(client)
+    except APIError as exc:
+        raise PairingError(f"Could not start pairing: {exc.message}") from exc
+
+    if on_start is not None:
+        on_start(start)
+    maybe_open_browser(start.confirm_url, enabled=open_browser)
+
+    deadline = now() + min(timeout, start.expires_in or timeout)
+
+    while True:
+        try:
+            poll = poll_pairing(client, start.pairing_code)
+        except APIError as exc:
+            raise PairingError(f"Pairing poll failed: {exc.message}") from exc
+
+        status = (poll.status or "").lower()
+        if status == "confirmed":
+            if not poll.api_key:
+                raise PairingError(
+                    "Pairing confirmed but server did not return an API key.",
+                )
+            return PairingResult(
+                api_key=poll.api_key,
+                user_email=poll.user_email,
+                default_lab_id=poll.default_lab_id,
+                default_lab_slug=poll.default_lab_slug,
+            )
+        if status == "expired":
+            raise PairingError("Pairing code expired. Run `labtab auth login` again.")
+        if status == "denied":
+            raise PairingError("Pairing was denied in the browser.")
+
+        if now() >= deadline:
+            raise PairingError(
+                "Timed out waiting for browser confirmation. Run `labtab auth login` again.",
+            )
+
+        sleep(poll_interval)
+
+
+def persist_pairing(config: Config, result: PairingResult) -> Config:
+    """Write ``result`` into ``config`` and save to disk."""
+
+    config.api_key = result.api_key
+    config.user_email = result.user_email
+    config.default_lab_id = result.default_lab_id
+    config.default_lab_slug = result.default_lab_slug
+    config.save()
+    return config
+
+
+def summarise_identity(config: Config) -> dict[str, Any]:
+    """Return a plain dict describing the current signed-in identity."""
+
+    return {
+        "signed_in": bool(config.api_key),
+        "user_email": config.user_email,
+        "default_lab_id": config.default_lab_id,
+        "default_lab_slug": config.default_lab_slug,
+        "base_url": config.base_url,
+        "config_path": str(config.path),
+    }

labtab/cli.py

@@ -0,0 +1,77 @@
+"""Top-level typer app for the labtab CLI.
+
+This module wires every command sub-app together. The entry point
+``labtab = "labtab.cli:app"`` is declared in ``pyproject.toml``.
+"""
+
+from __future__ import annotations
+
+import typer
+
+from . import __version__
+from .commands import (
+    auth,
+    export,
+    grants,
+    labs,
+    meetings,
+    papers,
+    people,
+    projects,
+    tasks,
+)
+from .errors import LabtabError
+from .output import print_error
+
+app = typer.Typer(
+    name="labtab",
+    help="LabTab CLI (Wetware Ltd) — manage your lab from the terminal.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+app.add_typer(auth.app, name="auth")
+app.add_typer(labs.app, name="labs")
+app.add_typer(grants.app, name="grants")
+app.add_typer(papers.app, name="papers")
+app.add_typer(meetings.app, name="meetings")
+app.add_typer(tasks.app, name="tasks")
+app.add_typer(projects.app, name="projects")
+app.add_typer(people.app, name="people")
+
+# ``export`` is a bare command rather than a nested group — we register its
+# sub-app with ``invoke_without_command`` so ``labtab export`` works directly.
+app.add_typer(export.app, name="export")
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"labtab {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def _root(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show the labtab version and exit.",
+    ),
+) -> None:
+    """Root callback — only exists to host the ``--version`` flag."""
+
+
+def main() -> None:
+    """Entrypoint wrapper that converts :class:`LabtabError` to a clean exit."""
+
+    try:
+        app()
+    except LabtabError as exc:
+        print_error(exc.message)
+        raise typer.Exit(code=exc.exit_code) from exc
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

labtab/client.py

@@ -0,0 +1,316 @@
+"""HTTP client for the labtab CLI.
+
+:class:`LabtabClient` wraps :class:`httpx.Client`, attaches the API key from
+the config as a bearer token, and exposes typed helpers that return validated
+pydantic models. Error responses are translated into the typed exception
+hierarchy defined in :mod:`labtab.errors`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+import httpx
+from pydantic import BaseModel, TypeAdapter, ValidationError
+
+from . import __version__
+from .config import Config
+from .errors import (
+    APIError,
+    NotAuthenticatedError,
+    NotFoundError,
+    PermissionDeniedError,
+)
+from .models import (
+    ExportStatus,
+    Grant,
+    Lab,
+    Meeting,
+    Paper,
+    Person,
+    Project,
+    Task,
+    User,
+)
+
+USER_AGENT = f"labtab/{__version__}"
+
+
+def _unwrap_list(payload: Any) -> list[Any]:
+    """Return a list of items from either a bare list or a DRF paginated dict."""
+
+    if isinstance(payload, list):
+        return payload
+    if isinstance(payload, Mapping):
+        results = payload.get("results")
+        if isinstance(results, list):
+            return results
+    return []
+
+
+def _parse_list(model: type[BaseModel], payload: Any) -> list[Any]:
+    adapter = TypeAdapter(list[model])  # type: ignore[valid-type]
+    try:
+        return adapter.validate_python(_unwrap_list(payload))
+    except ValidationError as exc:
+        raise APIError(f"Could not parse response: {exc}") from exc
+
+
+def _parse(model: type[BaseModel], payload: Any) -> Any:
+    try:
+        return model.model_validate(payload)
+    except ValidationError as exc:
+        raise APIError(f"Could not parse response: {exc}") from exc
+
+
+class LabtabClient:
+    """Minimal typed wrapper over :class:`httpx.Client`.
+
+    Callers should use the :meth:`from_config` constructor so that the base URL
+    and API key are loaded consistently. The client may be used as a context
+    manager, but that is optional — ``close()`` is safe to call on an
+    already-closed instance.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str | None,
+        *,
+        client: httpx.Client | None = None,
+        timeout: float = 30.0,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        headers = {"User-Agent": USER_AGENT, "Accept": "application/json"}
+        if api_key:
+            headers["Authorization"] = f"Bearer {api_key}"
+        self._client = client or httpx.Client(
+            base_url=self.base_url,
+            headers=headers,
+            timeout=timeout,
+        )
+
+    # -- lifecycle ----------------------------------------------------------
+
+    @classmethod
+    def from_config(
+        cls,
+        config: Config,
+        *,
+        client: httpx.Client | None = None,
+    ) -> LabtabClient:
+        return cls(config.base_url, config.api_key, client=client)
+
+    def __enter__(self) -> LabtabClient:
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._client.close()
+
+    # -- low-level ---------------------------------------------------------
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        json: Any = None,
+        require_auth: bool = True,
+    ) -> Any:
+        """Send a request and return decoded JSON, raising on error."""
+
+        if require_auth and not self.api_key:
+            raise NotAuthenticatedError()
+        if params is not None:
+            params = {k: v for k, v in params.items() if v is not None}
+
+        try:
+            resp = self._client.request(method, path, params=params, json=json)
+        except httpx.TimeoutException as exc:
+            raise APIError(f"Request timed out talking to {self.base_url}") from exc
+        except httpx.TransportError as exc:
+            raise APIError(f"Network error talking to {self.base_url}: {exc}") from exc
+
+        return self._handle(resp, path=path)
+
+    def get(self, path: str, **kwargs: Any) -> Any:
+        return self.request("GET", path, **kwargs)
+
+    def post(self, path: str, **kwargs: Any) -> Any:
+        return self.request("POST", path, **kwargs)
+
+    def stream_to_file(self, url: str, destination: Any, *, chunk_size: int = 1 << 15) -> int:
+        """Stream ``url`` into ``destination`` (a writable binary stream).
+
+        ``url`` is used as-is — this is intended for signed S3-style URLs, not
+        authenticated API calls. Returns the total byte count written.
+        """
+
+        total = 0
+        try:
+            with httpx.stream("GET", url, timeout=60.0) as resp:
+                if resp.status_code >= 400:
+                    raise APIError(
+                        f"Download failed with status {resp.status_code}"
+                    )
+                for chunk in resp.iter_bytes(chunk_size):
+                    destination.write(chunk)
+                    total += len(chunk)
+        except httpx.TransportError as exc:
+            raise APIError(f"Download transport error: {exc}") from exc
+        return total
+
+    # -- error handling ----------------------------------------------------
+
+    @staticmethod
+    def _handle(resp: httpx.Response, *, path: str) -> Any:
+        status = resp.status_code
+        if status == 204:
+            return None
+        if 200 <= status < 300:
+            if not resp.content:
+                return None
+            try:
+                return resp.json()
+            except ValueError as exc:
+                raise APIError(f"Invalid JSON from {path}") from exc
+        if status == 401:
+            raise NotAuthenticatedError()
+        if status == 403:
+            raise PermissionDeniedError(
+                "Permission denied. Your account may not have access to this resource.",
+            )
+        if status == 404:
+            raise NotFoundError(f"Not found: {path}")
+        if 400 <= status < 500:
+            detail = _extract_detail(resp) or f"Request failed with status {status}"
+            raise APIError(detail)
+        raise APIError(f"API error ({status}) from {path} — try again later.")
+
+    # -- typed helpers -----------------------------------------------------
+
+    def whoami(self) -> User:
+        data = self.get("/users/me/")
+        return _parse(User, data)
+
+    def list_labs(self) -> list[Lab]:
+        data = self.get("/labs/")
+        return _parse_list(Lab, data)
+
+    def list_grants(
+        self,
+        *,
+        lab: str | int | None = None,
+        status: str | None = None,
+    ) -> list[Grant]:
+        params = {"lab": lab, "status": status}
+        return _parse_list(Grant, self.get("/grants/", params=params))
+
+    def get_grant(self, grant_id: str | int) -> Grant:
+        return _parse(Grant, self.get(f"/grants/{grant_id}/"))
+
+    def list_papers(
+        self,
+        *,
+        lab: str | int | None = None,
+        year: int | None = None,
+    ) -> list[Paper]:
+        params = {"lab": lab, "year": year}
+        return _parse_list(Paper, self.get("/papers/", params=params))
+
+    def get_paper(self, paper_id: str | int) -> Paper:
+        return _parse(Paper, self.get(f"/papers/{paper_id}/"))
+
+    def list_meetings(
+        self,
+        *,
+        lab: str | int | None = None,
+        upcoming_days: int | None = None,
+    ) -> list[Meeting]:
+        params = {"lab": lab, "upcoming_days": upcoming_days}
+        return _parse_list(Meeting, self.get("/meetings/", params=params))
+
+    def get_meeting(self, meeting_id: str | int) -> Meeting:
+        return _parse(Meeting, self.get(f"/meetings/{meeting_id}/"))
+
+    def list_tasks(
+        self,
+        *,
+        lab: str | int | None = None,
+        status: str | None = None,
+        assigned_to_me: bool | None = None,
+    ) -> list[Task]:
+        params: dict[str, Any] = {"lab": lab, "status": status}
+        if assigned_to_me:
+            params["assigned_to_me"] = "true"
+        return _parse_list(Task, self.get("/tasks/", params=params))
+
+    def get_task(self, task_id: str | int) -> Task:
+        return _parse(Task, self.get(f"/tasks/{task_id}/"))
+
+    def list_projects(self, *, lab: str | int | None = None) -> list[Project]:
+        return _parse_list(Project, self.get("/projects/", params={"lab": lab}))
+
+    def get_project(self, project_id: str | int) -> Project:
+        return _parse(Project, self.get(f"/projects/{project_id}/"))
+
+    def list_people(self, *, lab: str | int | None = None) -> list[Person]:
+        return _parse_list(Person, self.get("/people/", params={"lab": lab}))
+
+    def get_person(self, person_id: str | int) -> Person:
+        return _parse(Person, self.get(f"/people/{person_id}/"))
+
+    def start_export(
+        self,
+        *,
+        lab_id: str | int,
+        fmt: str = "zip",
+    ) -> ExportStatus:
+        payload = self.post(f"/labs/{lab_id}/export/", json={"format": fmt})
+        return _parse(ExportStatus, payload)
+
+    def get_export_status(
+        self,
+        *,
+        lab_id: str | int,
+        export_id: str | int,
+    ) -> ExportStatus:
+        data = self.get(f"/labs/{lab_id}/export/{export_id}/")
+        return _parse(ExportStatus, data)
+
+
+def _extract_detail(resp: httpx.Response) -> str | None:
+    try:
+        body = resp.json()
+    except ValueError:
+        return None
+    if isinstance(body, Mapping):
+        for key in ("detail", "message", "error"):
+            value = body.get(key)
+            if isinstance(value, str):
+                return value
+    return None
+
+
+def build_client(config: Config, *, timeout: float = 30.0) -> httpx.Client:
+    """Return a raw :class:`httpx.Client` configured with the user's auth.
+
+    Complements :class:`LabtabClient` for call sites that need lower-level
+    access (multipart uploads, streaming downloads) without the parsed-model
+    layer.
+    """
+
+    headers = {"User-Agent": USER_AGENT, "Accept": "application/json"}
+    if config.api_key:
+        headers["Authorization"] = f"Bearer {config.api_key}"
+    return httpx.Client(
+        base_url=config.base_url.rstrip("/"),
+        headers=headers,
+        timeout=timeout,
+    )

labtab/commands/__init__.py

@@ -0,0 +1,5 @@
+"""Typer sub-apps for the labtab CLI.
+
+Each module exposes a module-level :class:`typer.Typer` named ``app`` that is
+registered by :mod:`labtab.cli`.
+"""

labtab/commands/_common.py

@@ -0,0 +1,55 @@
+"""Shared helpers used by every command module.
+
+Each command follows the same shape:
+
+* Load :class:`Config` (with :func:`resolve_lab` layered on top).
+* Open a :class:`LabtabClient` against it.
+* Call a typed method, render via :mod:`labtab.output`, handle errors.
+
+The helpers in this module keep those commands terse without reaching for
+inheritance or decorators.
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from typing import Any
+
+import typer
+
+from ..client import LabtabClient
+from ..config import Config
+from ..errors import LabtabError
+from ..output import dump_json, print_error
+
+
+@contextmanager
+def client_session() -> Any:
+    """Yield a (config, client) pair, closing the client on exit."""
+
+    config = Config.load()
+    client = LabtabClient.from_config(config)
+    try:
+        yield config, client
+    finally:
+        client.close()
+
+
+def resolve_lab(config: Config, override: str | int | None) -> str | int | None:
+    """Resolve the ``--lab`` flag against the config's default."""
+
+    if override is not None:
+        return override
+    if config.default_lab_slug:
+        return config.default_lab_slug
+    return config.default_lab_id
+
+
+def bail(exc: LabtabError, *, json_mode: bool) -> None:
+    """Render a :class:`LabtabError` and exit with its exit code."""
+
+    if json_mode:
+        dump_json({"ok": False, "error": exc.message})
+    else:
+        print_error(exc.message)
+    raise typer.Exit(code=exc.exit_code)