jump2-client 0.1.0__py3-none-any.whl

jump2_client/__init__.py

@@ -0,0 +1,49 @@
+"""
+jump2_client — Jump 2.0 Python client.
+
+Lightweight, standalone, pip-installable.  Works in JupyterHub (picks up
+credentials from the environment automatically) or locally (provide
+``base_url`` and ``api_key``, or use :meth:`~jump2_client.client.Client.login`).
+
+Quick start::
+
+    from jump2_client import Client
+
+    # In JupyterHub — zero config needed, credentials injected at spawn:
+    c = Client()
+    c.status()                               # connectivity + ACL check
+    c.discover()                             # browse the API
+
+    # Locally:
+    c = Client(base_url="https://jump2.example.org", api_key="...")
+    # or:
+    c = Client(base_url="https://jump2.example.org").login("user", "pass")
+
+    # Data access (RLS invisible — server handles authorisation):
+    df = c.data.query("SELECT url_slug, vmag FROM core_star LIMIT 20")
+    files = c.data.files("hd-209458")
+
+    # Jobs:
+    result = c.jobs.poll(42)
+
+    # Admin (requires elevated permissions):
+    job = c.admin.ingest.launch(instruments=["apf"])
+    c.admin.schedules.list()
+"""
+
+from .client import Client
+from .errors import AuthError, Jump2Error, NotFoundError, ServerError, ValidationError
+from .query import QueryBuilder
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Client",
+    "Jump2Error",
+    "AuthError",
+    "NotFoundError",
+    "ServerError",
+    "ValidationError",
+    "QueryBuilder",
+    "__version__",
+]

jump2_client/_pretty.py

@@ -0,0 +1,44 @@
+"""
+jump2_client._pretty — rich rendering helpers.
+
+Kept in a private module so the public API stays clean.  The ``rich``
+library is always available (it is a declared dependency), but callers
+never need to import it themselves — just call the public methods on the
+client objects and they print formatted tables automatically.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+
+def _rich() -> Any:
+    """Lazy import of rich.console.Console to avoid import-time overhead."""
+    from rich.console import Console
+    return Console()
+
+
+def print_table(title: str, columns: list[str], rows: list[list[Any]]) -> None:
+    """Print a labelled rich table to stdout."""
+    from rich.table import Table
+
+    console = _rich()
+    table = Table(title=title, show_header=True, header_style="bold cyan")
+    for col in columns:
+        table.add_column(col, overflow="fold")
+    for row in rows:
+        table.add_row(*[str(v) if v is not None else "" for v in row])
+    console.print(table)
+
+
+def print_dict(title: str, data: dict[str, Any]) -> None:
+    """Print a two-column key/value rich table."""
+    print_table(title, ["Key", "Value"], [[k, v] for k, v in data.items()])
+
+
+def format_bytes(n: int | float) -> str:
+    """Human-readable byte size (e.g. ``"3.2 GiB"``)."""
+    for unit in ("B", "KiB", "MiB", "GiB", "TiB"):
+        if abs(n) < 1024.0:
+            return f"{n:.1f} {unit}"
+        n /= 1024.0
+    return f"{n:.1f} PiB"

jump2_client/admin/__init__.py

@@ -0,0 +1,57 @@
+"""
+jump2_client.admin — admin-only operations.
+
+All actions in this submodule require elevated permissions (``run_jobs``,
+``manage_schedules``, ``manage_users`` etc.).  Authorisation is enforced
+server-side — calling these without the required tokens raises
+:exc:`~jump2_client.errors.AuthError`.
+
+Submodules
+----------
+``ingest``
+    Preview and launch ad-hoc ingest coordinator jobs.
+
+``schedules``
+    CRUD for Celery-Beat ingest schedules.
+
+``users``
+    Admin user and resource-usage views.
+
+Example::
+
+    from jump2_client import Client
+    c = Client()
+
+    # Preview what would be ingested
+    preview = c.admin.ingest.preview()
+
+    # Launch a manual ingest
+    job = c.admin.ingest.launch()
+    result = c.jobs.poll(job["id"])
+
+    # Manage schedules
+    c.admin.schedules.list()
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .ingest import AdminIngest
+from .schedules import AdminSchedules
+from .users import AdminUsers
+
+if TYPE_CHECKING:
+    from ..session import Session
+
+
+class Admin:
+    """
+    Admin-only client namespace.
+
+    Attached to :class:`~jump2_client.client.Client` as ``client.admin``.
+    """
+
+    def __init__(self, session: Session) -> None:
+        self.ingest = AdminIngest(session)
+        self.schedules = AdminSchedules(session)
+        self.users = AdminUsers(session)

jump2_client/admin/ingest.py

@@ -0,0 +1,193 @@
+"""
+jump2_client.admin.ingest — ad-hoc ingest job management.
+
+Wraps the ingest endpoints:
+  ``GET  /api/v1/jobs/ingest/preview/``  — dry-run manifest walk
+  ``POST /api/v1/jobs/ingest/``          — launch an ingest coordinator
+  ``GET  /api/v1/jobs/node-status/``     — remote node health
+
+Requires the ``run_jobs`` permission token.
+
+Backend contract note
+---------------------
+The backend endpoint accepts a *single* ``instrument`` (one job per instrument
+category).  Pass ``instrument=`` (singular) to :meth:`preview` and
+:meth:`launch`.  Valid choices: ``apf``, ``hires``, ``plots``, ``kpf_cal``,
+``kpf_l0``, ``kpf_qlp``.  To process multiple instruments, call
+:meth:`launch` in a loop or use :meth:`launch_and_poll` with a list (it
+iterates automatically).
+
+Example::
+
+    from jump2_client import Client
+    c = Client()
+
+    # Dry-run: see what would be ingested (no DB writes)
+    preview = c.admin.ingest.preview(instrument="kpf_l0")
+    print(f"{preview['file_count']} files ready to ingest")
+
+    # Launch one instrument
+    job = c.admin.ingest.launch(instrument="kpf_l0")
+    result = c.jobs.poll(job["id"])    # wait for completion
+    print(result["status"])
+
+    # Launch multiple instruments sequentially (one job each)
+    results = c.admin.ingest.launch_and_poll(instruments=["kpf_l0", "apf"])
+
+    # Check remote node health
+    c.admin.ingest.print_node_status()
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from .._pretty import print_dict, print_table
+
+if TYPE_CHECKING:
+    from ..session import Session
+
+_VALID_INSTRUMENTS = frozenset({"apf", "hires", "plots", "kpf_cal", "kpf_l0", "kpf_qlp"})
+
+
+class AdminIngest:
+    """
+    Ad-hoc ingest job management.
+
+    Attached to :class:`~jump2_client.admin.Admin` as ``client.admin.ingest``.
+    """
+
+    def __init__(self, session: Session) -> None:
+        self._s = session
+
+    def preview(self, instrument: str, max_scan: int | None = None, **params: Any) -> dict[str, Any]:
+        """
+        Dry-run manifest walk — returns what *would* be ingested without
+        creating any DB records or dispatching Celery tasks.
+
+        Args:
+            instrument: Instrument category to preview.  Must be one of:
+                        ``apf``, ``hires``, ``plots``, ``kpf_cal``, ``kpf_l0``,
+                        ``kpf_qlp``.
+            max_scan:   Limit the number of files scanned (optional).
+            **params:   Additional query parameters forwarded to the endpoint.
+
+        Returns:
+            Preview dict with ``file_count``, ``instrument``, etc.
+
+        Raises:
+            ValueError: If *instrument* is not a recognised instrument code.
+        """
+        if instrument not in _VALID_INSTRUMENTS:
+            raise ValueError(
+                f"Unknown instrument {instrument!r}. "
+                f"Valid choices: {', '.join(sorted(_VALID_INSTRUMENTS))}"
+            )
+        query: dict[str, Any] = {"instrument": instrument}
+        if max_scan is not None:
+            query["max_scan"] = max_scan
+        query.update(params)
+        return self._s.get("/jobs/ingest/preview/", params=query)
+
+    def launch(
+        self,
+        instrument: str,
+        max_files: int | None = None,
+        **extra: Any,
+    ) -> dict[str, Any]:
+        """
+        Launch a manual ingest coordinator job for one instrument category.
+
+        The backend creates one job per instrument; call :meth:`launch` in a
+        loop (or use :meth:`launch_and_poll` with a list) to ingest multiple
+        instruments.
+
+        Args:
+            instrument: Instrument category to ingest.  Must be one of:
+                        ``apf``, ``hires``, ``plots``, ``kpf_cal``, ``kpf_l0``,
+                        ``kpf_qlp``.
+            max_files:  Cap the number of files processed in this run.
+            **extra:    Additional payload fields forwarded verbatim.
+
+        Returns:
+            Job creation response dict including ``id`` (use with
+            :meth:`~jump2_client.jobs.Jobs.poll`).
+
+        Raises:
+            ValueError: If *instrument* is not a recognised instrument code.
+        """
+        if instrument not in _VALID_INSTRUMENTS:
+            raise ValueError(
+                f"Unknown instrument {instrument!r}. "
+                f"Valid choices: {', '.join(sorted(_VALID_INSTRUMENTS))}"
+            )
+        payload: dict[str, Any] = {"instrument": instrument}
+        if max_files is not None:
+            payload["max_files"] = max_files
+        payload.update(extra)
+        return self._s.post("/jobs/ingest/", json=payload)
+
+    def node_status(self) -> list[dict[str, Any]]:
+        """
+        Return remote ingest-node health status.
+
+        Returns:
+            List of node dicts, each with keys ``node``, ``reachable``,
+            ``latency_ms``, ``http_status``, ``error``.
+        """
+        resp = self._s.get("/jobs/node-status/")
+        raw: list[dict[str, Any]] = resp if isinstance(resp, list) else resp.get("nodes", [])
+        return raw
+
+    def print_node_status(self) -> None:
+        """Print remote node status as a rich table."""
+        nodes = self.node_status()
+        if not nodes:
+            print_dict("Node Status", {})
+            return
+        rows = [
+            [
+                str(n.get("node", "")),
+                "✓" if n.get("reachable") else "✗",
+                str(n.get("latency_ms", "")),
+                str(n.get("http_status", "")),
+                str(n.get("error", "") or ""),
+            ]
+            for n in nodes
+        ]
+        print_table(
+            "Remote Node Status",
+            ["Node", "Reachable", "Latency (ms)", "HTTP", "Error"],
+            rows,
+        )
+
+    def launch_and_poll(
+        self,
+        instruments: list[str],
+        max_files: int | None = None,
+        interval: float = 5.0,
+        timeout: float = 3600.0,
+        **extra: Any,
+    ) -> list[dict[str, Any]]:
+        """
+        Launch ingest jobs for multiple instruments and block until all complete.
+
+        Iterates over *instruments*, calling :meth:`launch` for each and then
+        waiting for completion.  Jobs run sequentially.
+
+        Args:
+            instruments: List of instrument codes (e.g. ``["kpf_l0", "apf"]``).
+            max_files:   Cap applied to every job in the list.
+            interval:    Polling interval in seconds (default 5).
+            timeout:     Maximum wait per job in seconds (default 3600).
+            **extra:     Forwarded to every :meth:`launch` call.
+
+        Returns:
+            List of final job detail dicts (one per instrument, in order).
+        """
+        from ..jobs import Jobs
+        results = []
+        for instrument in instruments:
+            job = self.launch(instrument=instrument, max_files=max_files, **extra)
+            final = Jobs(self._s).poll(job["id"], interval=interval, timeout=timeout)
+            results.append(final)
+        return results

jump2_client/admin/schedules.py

@@ -0,0 +1,164 @@
+"""
+jump2_client.admin.schedules — Celery-Beat ingest schedule management.
+
+Wraps ``/api/v1/ingest-schedules/`` CRUD endpoints.
+Requires the ``manage_schedules`` permission token.
+
+Example::
+
+    from jump2_client import Client
+    c = Client()
+
+    # List existing schedules
+    for s in c.admin.schedules.list():
+        print(s["instrument"], s.get("cron") or s.get("interval"), s["enabled"])
+
+    # Create a new cron schedule (daily at midnight UTC)
+    sched = c.admin.schedules.create(
+        instrument="apf",
+        cron="0 0 * * *",
+        max_files=500,
+        cooldown_minutes=60,
+    )
+
+    # Disable a schedule
+    c.admin.schedules.update(sched["id"], enabled=False)
+
+    # Delete a schedule
+    c.admin.schedules.delete(sched["id"])
+"""
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import TYPE_CHECKING, Any
+
+from .._pretty import print_table
+
+if TYPE_CHECKING:
+    from ..session import Session
+
+
+class AdminSchedules:
+    """
+    Ingest schedule management (Celery Beat).
+
+    Attached to :class:`~jump2_client.admin.Admin` as ``client.admin.schedules``.
+    """
+
+    def __init__(self, session: Session) -> None:
+        self._s = session
+
+    def list(self) -> Iterator[dict[str, Any]]:
+        """
+        Iterate over all ingest schedules.
+
+        Yields:
+            Schedule dicts with ``id``, ``instrument``, ``cron`` or
+            ``interval``, ``enabled``, ``cooldown_minutes``, ``max_files``,
+            ``last_run_at``.
+        """
+        yield from self._s.paginate("/ingest-schedules/")
+
+    def get(self, schedule_id: int) -> dict[str, Any]:
+        """
+        Return a single schedule by ID.
+
+        Args:
+            schedule_id: Integer schedule primary key.
+        """
+        return self._s.get(f"/ingest-schedules/{schedule_id}/")
+
+    def create(
+        self,
+        instrument: str,
+        cron: str | None = None,
+        interval: int | None = None,
+        max_files: int | None = None,
+        cooldown_minutes: int = 30,
+        enabled: bool = True,
+        **extra: Any,
+    ) -> dict[str, Any]:
+        """
+        Create a new ingest schedule.
+
+        Exactly one of *cron* or *interval* must be supplied.
+
+        Args:
+            instrument:       Instrument code (e.g. ``"kpf_l0"``).
+            cron:             5-field cron expression (e.g. ``"0 * * * *"``
+                              for hourly).
+            interval:         Interval in minutes (mutually exclusive with
+                              *cron*).
+            max_files:        Maximum files to process per run (0 = unlimited).
+            cooldown_minutes: Minimum minutes between consecutive runs.
+            enabled:          Whether the schedule is active immediately.
+            **extra:          Additional payload fields.
+
+        Returns:
+            Created schedule dict.
+
+        Raises:
+            :exc:`~jump2_client.errors.ValidationError`: If both or neither of
+                *cron*/*interval* are supplied, or the instrument is unknown.
+        """
+        if (cron is None) == (interval is None):
+            from ..errors import ValidationError
+            raise ValidationError(
+                "Exactly one of 'cron' or 'interval' must be supplied."
+            )
+        payload: dict[str, Any] = {
+            "instrument": instrument,
+            "cooldown_minutes": cooldown_minutes,
+            "enabled": enabled,
+            **extra,
+        }
+        if cron is not None:
+            payload["cron"] = cron
+        if interval is not None:
+            payload["interval"] = interval
+        if max_files is not None:
+            payload["max_files"] = max_files
+        return self._s.post("/ingest-schedules/", json=payload)
+
+    def update(self, schedule_id: int, **fields: Any) -> dict[str, Any]:
+        """
+        Partially update a schedule.
+
+        Args:
+            schedule_id: Integer schedule primary key.
+            **fields:    Fields to update (e.g. ``enabled=False``,
+                         ``cron="0 */6 * * *"``).
+
+        Returns:
+            Updated schedule dict.
+        """
+        return self._s.patch(f"/ingest-schedules/{schedule_id}/", json=fields)
+
+    def delete(self, schedule_id: int) -> None:
+        """
+        Delete a schedule by ID.
+
+        Args:
+            schedule_id: Integer schedule primary key.
+        """
+        self._s.delete(f"/ingest-schedules/{schedule_id}/")
+
+    def print_list(self) -> None:
+        """Print all schedules as a rich table to stdout."""
+        rows = []
+        for s in self.list():
+            schedule_val = s.get("cron") or f"{s.get('interval')}m"
+            rows.append([
+                str(s.get("id", "")),
+                s.get("instrument", ""),
+                schedule_val or "—",
+                "✓" if s.get("enabled") else "✗",
+                str(s.get("cooldown_minutes", "")),
+                str(s.get("max_files", "")),
+                (s.get("last_run_at") or "")[:19],
+            ])
+        print_table(
+            "Ingest Schedules",
+            ["ID", "Instrument", "Schedule", "Enabled", "Cooldown (min)", "Max files", "Last run"],
+            rows,
+        )

jump2_client/admin/users.py

@@ -0,0 +1,88 @@
+"""
+jump2_client.admin.users — admin user and resource-usage views.
+
+Wraps the IAM admin endpoints:
+  ``GET /api/v1/users/``         — paginated user list
+  ``GET /api/v1/users/<id>/``    — single user detail (with resource limits)
+  ``GET /api/v1/me/``            — own profile (for display)
+
+Requires the ``manage_users`` permission token for the user-list endpoint.
+
+Example::
+
+    from jump2_client import Client
+    c = Client()
+
+    for user in c.admin.users.list():
+        u = user
+        resources = u.get("resources", {})
+        print(u["username"], resources.get("storage_used_gb", 0), "GB used")
+"""
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import TYPE_CHECKING, Any
+
+from .._pretty import format_bytes, print_table
+
+if TYPE_CHECKING:
+    from ..session import Session
+
+
+class AdminUsers:
+    """
+    Admin user management.
+
+    Attached to :class:`~jump2_client.admin.Admin` as ``client.admin.users``.
+    """
+
+    def __init__(self, session: Session) -> None:
+        self._s = session
+
+    def list(self, **params: Any) -> Iterator[dict[str, Any]]:
+        """
+        Iterate over all users (admin view).
+
+        Args:
+            **params: Query parameters for ``GET /api/v1/users/``.
+
+        Yields:
+            User dicts including ``username``, ``email``, ``resources`` block.
+        """
+        yield from self._s.paginate("/users/", params=params)
+
+    def get(self, user_id: int) -> dict[str, Any]:
+        """
+        Return the admin detail dict for a single user.
+
+        Args:
+            user_id: Integer user primary key.
+
+        Returns:
+            User detail dict.
+        """
+        return self._s.get(f"/users/{user_id}/")
+
+    def print_usage(self, limit: int = 50) -> None:
+        """Print a resource-usage summary table for all users."""
+        rows = []
+        for i, user in enumerate(self.list()):
+            if i >= limit:
+                break
+            r = user.get("resources", {})
+            nb = user.get("notebook", {})
+            used = nb.get("used_bytes", 0)
+            quota = nb.get("quota_bytes", 0)
+            storage = f"{format_bytes(used)} / {format_bytes(quota)}" if quota else "n/a"
+            rows.append([
+                user.get("username", ""),
+                storage,
+                f"{r.get('cpu_limit', '?')} CPU",
+                str(r.get("mem_limit", "?")),
+                "✓" if user.get("is_staff") else "",
+            ])
+        print_table(
+            "User Resource Usage",
+            ["Username", "Storage", "CPU Limit", "Mem Limit", "Staff"],
+            rows,
+        )