xoople-cli 0.1.0__py3-none-any.whl

xoople/cli/__init__.py

@@ -0,0 +1,5 @@
+from xoople.cli._version import version
+
+__version__ = version()
+
+__all__ = ["__version__"]

xoople/cli/__main__.py

@@ -0,0 +1,3 @@
+from xoople.cli.main import main
+
+main()

xoople/cli/_context.py

@@ -0,0 +1,87 @@
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Annotated
+
+from cyclopts import Parameter
+from xoople.cli._errors import UsageError
+from xoople.sdk import Config, CredentialProvider, XoopleClient
+from xoople.sdk.auth import EntraCredential, StaticToken
+
+
+@dataclass(frozen=True)
+class Credentials:
+    """The global options that decide which API and identity a command talks to."""
+
+    base_url: str | None = None
+    token: str | None = None
+    entra_scope: str | None = None
+    timeout: float = 30.0
+    max_retries: int = 3
+
+
+# How Credentials become a client — swapped for a fake in tests.
+type ClientFactory = Callable[[Credentials], XoopleClient]
+
+# Every command declares this keyword-only parameter; the meta-app launcher in
+# ``main.py`` injects the resolved ``Settings`` via ``parse=False``, so commands
+# stay plain functions and tests drive them over a fake transport.
+type SettingsParam = Annotated[Settings, Parameter(parse=False)]
+
+
+def at_least_one(_type: object, value: int | None) -> None:
+    """Cyclopts validator for ``--limit``: a sub-1 read pays for nothing and the
+    SDK would reject it anyway — fail it at parse time with a usage error."""
+    if value is not None and value < 1:
+        raise ValueError("must be at least 1")
+
+
+@dataclass
+class Settings:
+    """Resolved global options, injected into every command by the meta launcher.
+
+    The client is built lazily so ``--help`` and argument errors never require
+    credentials, and cached so a command making several calls reuses one
+    connection pool.
+    """
+
+    credentials: Credentials
+    factory: ClientFactory
+    as_json: bool = False
+    _client: XoopleClient | None = field(default=None, repr=False)
+
+    def client(self) -> XoopleClient:
+        if self._client is None:
+            self._client = self.factory(self.credentials)
+        return self._client
+
+    def close(self) -> None:
+        if self._client is not None:
+            self._client.close()
+            self._client = None
+
+
+def _credential_provider(credentials: Credentials) -> CredentialProvider:
+    if credentials.entra_scope:
+        return EntraCredential(credentials.entra_scope)
+    if not credentials.token:
+        raise UsageError("no credentials: pass --token, set XOOPLE_TOKEN, or pass --entra-scope")
+    return StaticToken(credentials.token)
+
+
+def build_client(credentials: Credentials) -> XoopleClient:
+    """Resolve credentials into a client.
+
+    The environment is read by Cyclopts' ``env_var=`` on the launcher options,
+    not here — a second `os.environ` fallback would be unreachable and would
+    drift from the names `--help` advertises.
+    """
+    if not credentials.base_url:
+        raise UsageError("no API URL: pass --api-url or set XOOPLE_API_URL")
+    return XoopleClient(
+        Config(
+            base_url=credentials.base_url,
+            credentials=_credential_provider(credentials),
+            timeout=credentials.timeout,
+            max_retries=credentials.max_retries,
+        )
+    )

xoople/cli/_errors.py

@@ -0,0 +1,75 @@
+from xoople.cli._output import note
+from xoople.sdk import errors
+
+EXIT_CODES: dict[type[errors.XoopleError], int] = {
+    errors.AuthenticationError: 3,
+    errors.PermissionDeniedError: 4,
+    errors.NotFoundError: 5,
+    errors.BadRequestError: 6,
+    errors.ValidationError: 6,
+    errors.ConflictError: 7,
+    errors.RateLimitError: 8,
+    errors.ServerError: 9,
+    errors.XoopleConnectionError: 10,
+    errors.XoopleResponseError: 11,
+}
+_FALLBACK_EXIT = 1
+# ``CliError`` with no specific subclass falls back to 1. Nothing raises a bare
+# ``CliError`` today; every CLI-detected outcome has its own subclass below.
+# Outcomes the CLI decides rather than the API. Kept here with the status map so
+# the README's exit-code table has one source.
+USAGE_EXIT = 2
+FAILED_RUN_EXIT = 12
+WAIT_TIMEOUT_EXIT = 13
+
+
+class CliError(Exception):
+    """A failure the CLI itself detects, reported the same way as an API error."""
+
+    exit_code = _FALLBACK_EXIT
+
+
+class UsageError(CliError):
+    """A bad flag or spec file: the user can fix it and re-run."""
+
+    exit_code = USAGE_EXIT
+
+
+class RunFailed(CliError):
+    """``--wait`` finished, but the run ended in a non-``COMPLETE`` state."""
+
+    exit_code = FAILED_RUN_EXIT
+
+
+class WaitTimeout(CliError):
+    """``--wait`` gave up before the run reached a terminal state."""
+
+    exit_code = WAIT_TIMEOUT_EXIT
+
+
+def exit_code(exc: errors.XoopleError) -> int:
+    for cls, code in EXIT_CODES.items():
+        if isinstance(exc, cls):
+            return code
+    return _FALLBACK_EXIT
+
+
+def _describe(exc: errors.XoopleError) -> str:
+    if isinstance(exc, errors.XoopleAPIError):
+        trace = f" [dim](trace {exc.trace_id})[/dim]" if exc.trace_id else ""
+        return f"[red]error[/red] {exc.status} {exc.code}: {exc.message}{trace}"
+    return f"[red]error[/red] {exc}"
+
+
+def report(exc: errors.XoopleError | CliError) -> int:
+    """Print an error as one line and return the exit code it maps to.
+
+    The meta-app launcher in ``main.py`` calls this for every exception that
+    escapes a command, so a stack trace never reaches the user and the API
+    status returns as an exit code instead of a generic 1.
+    """
+    if isinstance(exc, errors.XoopleError):
+        note(_describe(exc))
+        return exit_code(exc)
+    note(f"[red]error[/red] {exc}")
+    return exc.exit_code

xoople/cli/_output.py

@@ -0,0 +1,137 @@
+import json
+from collections.abc import Iterable, Sequence
+
+from pydantic import BaseModel
+from rich.console import Console
+from rich.table import Table
+
+type Column = tuple[str, str]
+
+# Fields holding a 0..1 fraction. A column headed PROGRESS showing `0.42` reads
+# as a bug, and `estimate_confidence` is the same unit, so both render as whole
+# percent. Keyed on the field name rather than declared per column: the unit
+# belongs to the field, so it must not depend on which emit function a command
+# happened to call. The generated models carry no `ge`/`le` metadata to infer it
+# from — if the spec ever declares bounds, read them instead of this set.
+_FRACTION_FIELDS = frozenset({"fraction", "estimate_confidence"})
+
+# Piped output must not depend on the terminal that happened to launch it, so a
+# non-tty stdout gets a width no table will wrap at. On a terminal, cells
+# truncate instead of folding: half a UUID on each of two lines cannot be copied.
+_PIPED_WIDTH = 10_000
+
+
+def _console_for(*, stderr: bool) -> Console:
+    # `is_terminal` rather than `isatty()`: it also honours TERM=dumb, NO_COLOR
+    # and FORCE_COLOR, which a caller redirecting output may well be setting.
+    console = Console(stderr=stderr)
+    if not console.is_terminal:
+        console.width = _PIPED_WIDTH
+    return console
+
+
+_console = _console_for(stderr=False)
+# Messages must stay greppable too: an error split across lines defeats
+# `2>&1 | grep`, and a wrapped URL cannot be clicked.
+_stderr = _console_for(stderr=True)
+
+
+def _scalar(value: object) -> str:
+    if value is None:
+        return "-"
+    if isinstance(value, bool):
+        return "yes" if value else "no"
+    # Credit and runtime figures carry full float precision; 15 decimal places of
+    # a unit count is noise in a table. `--json` is unaffected — it dumps the
+    # model, so anything doing arithmetic still gets the exact value.
+    if isinstance(value, float):
+        return f"{value:.2f}"
+    if isinstance(value, BaseModel):
+        return _scalar(value.model_dump(mode="json"))
+    if isinstance(value, dict):
+        return json.dumps(value, default=str)
+    if isinstance(value, list | tuple):
+        return ", ".join(_scalar(item) for item in value)
+    return str(value)
+
+
+def _percent(value: object) -> str:
+    return "-" if not isinstance(value, int | float) else f"{value:.0%}"
+
+
+def _dotted(model: BaseModel, path: str) -> object:
+    """Read ``a.b.c`` off nested models, treating a missing link as ``None``."""
+    current: object = model
+    for part in path.split("."):
+        if current is None:
+            return None
+        current = getattr(current, part, None)
+    return current
+
+
+def _cell(model: BaseModel, column: Column) -> str:
+    _, path = column
+    value = _dotted(model, path)
+    leaf = path.rsplit(".", 1)[-1]
+    return _percent(value) if leaf in _FRACTION_FIELDS else _scalar(value)
+
+
+def emit(models: Iterable[BaseModel], columns: Sequence[Column], *, as_json: bool) -> None:
+    """Render a collection: raw JSON array, or a table of ``(header, path)`` columns."""
+    items = list(models)
+    if as_json:
+        _raw_json([item.model_dump(mode="json", by_alias=True) for item in items])
+        return
+    if not items:
+        _stderr.print("[dim]no matching items[/dim]")
+        return
+    table = Table(box=None, pad_edge=False, header_style="bold")
+    for column in columns:
+        table.add_column(column[0], overflow="ellipsis", no_wrap=True)
+    for item in items:
+        table.add_row(*(_cell(item, column) for column in columns))
+    _console.print(table)
+
+
+def emit_one(model: BaseModel, fields: Sequence[Column], *, as_json: bool) -> None:
+    """Render a single resource: raw JSON object, or the named fields as rows."""
+    if as_json:
+        _raw_json(model.model_dump(mode="json", by_alias=True))
+        return
+    table = Table(box=None, pad_edge=False, show_header=False)
+    table.add_column(style="bold")
+    table.add_column(overflow="fold")
+    for field in fields:
+        table.add_row(field[0], _cell(model, field))
+    _console.print(table)
+
+
+def emit_model(model: BaseModel, *, as_json: bool) -> None:
+    """Render every declared field of a single resource.
+
+    For responses whose shape varies by product — the estimate union, whose
+    variants share almost no fields — deriving rows from the model beats a
+    hardcoded list that would be wrong for one of them.
+    """
+    fields = [(name.replace("_", " ").capitalize(), name) for name in type(model).model_fields]
+    emit_one(model, fields, as_json=as_json)
+
+
+def heading(text: str) -> None:
+    """A section label for a command that prints more than one table."""
+    _console.print(f"\n[bold]{text}[/bold]")
+
+
+def _raw_json(payload: object) -> None:
+    """Print JSON on stdout, unstyled.
+
+    Deliberately not rich's ``print_json``: it soft-wraps to the console width,
+    which breaks a long value across lines and can leave the piped output
+    unparseable. ``--json`` exists to be piped, so it stays plain.
+    """
+    print(json.dumps(payload, indent=2, default=str))
+
+
+def note(message: str) -> None:
+    """Progress and confirmation text — stderr, so ``--json`` stdout stays parseable."""
+    _stderr.print(message)

xoople/cli/_spec.py

@@ -0,0 +1,45 @@
+import json
+import sys
+from pathlib import Path
+
+from pydantic import ValidationError
+from xoople.cli._errors import UsageError
+from xoople.sdk import create_request_from, models
+
+
+def _read(path: Path) -> object:
+    raw = sys.stdin.read() if str(path) == "-" else path.read_text()
+    try:
+        return json.loads(raw)
+    except ValueError as exc:
+        source = "stdin" if str(path) == "-" else str(path)
+        raise UsageError(f"{source} is not valid JSON: {exc}") from exc
+
+
+def _explain(exc: ValidationError) -> str:
+    lines = []
+    for error in exc.errors():
+        location = ".".join(str(part) for part in error["loc"]) or "(root)"
+        lines.append(f"  {location}: {error['msg']}")
+    return "the spec does not match the API schema:\n" + "\n".join(lines)
+
+
+def load_create_request(
+    path: Path, display_name: str | None = None
+) -> models.CreateAnalysisRequest:
+    """Read a create/estimate body from a JSON file (``-`` for stdin).
+
+    Which document shapes are accepted is the SDK's rule, not the CLI's; this
+    adds only what a CLI owes its user — reading the file and turning a
+    validation error into a message that points at the offending field.
+    """
+    document = _read(path)
+    if not isinstance(document, dict):
+        raise UsageError("the spec file must contain a JSON object")
+    # A JSON object's keys are strings by construction; `json.loads` just does not
+    # say so in its return type.
+    body: dict[str, object] = {str(key): value for key, value in document.items()}
+    try:
+        return create_request_from(body, display_name)
+    except ValidationError as exc:
+        raise UsageError(_explain(exc)) from exc

xoople/cli/_version.py

@@ -0,0 +1,17 @@
+from functools import cache
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _distribution_version
+
+
+@cache
+def version() -> str:
+    """The installed distribution version, reported by ``xoople --version``.
+
+    Read from installed metadata so ``pyproject.toml`` stays the only place the
+    version is written. Falls back to ``0.0.0`` when the package is imported
+    from a source tree that was never installed.
+    """
+    try:
+        return _distribution_version("xoople-cli")
+    except PackageNotFoundError:
+        return "0.0.0"

xoople/cli/access.py

@@ -0,0 +1,47 @@
+from cyclopts import App
+from pydantic import BaseModel
+from xoople.cli._context import SettingsParam
+from xoople.cli._output import emit, emit_model
+
+app = App(
+    name="access",
+    help="Delta Sharing credentials and feature flags for your account.",
+)
+
+
+class _FlagRow(BaseModel):
+    """A flat row for the flag map, which is a dict rather than a list on the wire."""
+
+    flag: str
+    value: bool
+    reason: str
+
+
+@app.command(name="me")
+def me(*, settings: SettingsParam) -> None:
+    """Show your Delta Sharing recipient and the share it reads."""
+    emit_model(settings.client().data_access.me(), as_json=settings.as_json)
+
+
+@app.command(name="token")
+def token(*, settings: SettingsParam) -> None:
+    """Print your Delta Sharing bearer token and host."""
+    emit_model(settings.client().data_access.token(), as_json=settings.as_json)
+
+
+@app.command(name="features")
+def features(*, settings: SettingsParam) -> None:
+    """Show which feature flags are on for you, and why."""
+    result = settings.client().features.get()
+    if settings.as_json:
+        emit_model(result, as_json=True)
+        return
+    flags = [
+        _FlagRow(flag=name, value=flag.value, reason=flag.reason)
+        for name, flag in result.flags.items()
+    ]
+    emit(
+        flags,
+        [("FLAG", "flag"), ("ON", "value"), ("REASON", "reason")],
+        as_json=False,
+    )

xoople/cli/analyses.py

@@ -0,0 +1,161 @@
+from pathlib import Path
+from typing import Annotated
+
+from cyclopts import App, Parameter
+from xoople.cli._context import SettingsParam, at_least_one
+from xoople.cli._errors import RunFailed
+from xoople.cli._output import emit, emit_model, emit_one, note
+from xoople.cli._spec import load_create_request
+from xoople.cli.runs import FIELDS as RUN_FIELDS
+from xoople.cli.runs import wait_for_run
+from xoople.sdk import models
+
+app = App(
+    name="analyses",
+    help="Create, inspect and cancel analyses.",
+)
+
+COLUMNS = [
+    ("UID", "uid"),
+    ("DISPLAY NAME", "display_name"),
+    ("PRODUCT", "product"),
+    ("STATE", "state"),
+    ("AOI", "aoi_display_name"),
+    ("CREATED", "create_time"),
+]
+
+FIELDS = [
+    ("Name", "name"),
+    ("UID", "uid"),
+    ("Display name", "display_name"),
+    ("Product", "product"),
+    ("Product version", "product_version"),
+    ("State", "state"),
+    ("State message", "state_message"),
+    ("Owner", "owner"),
+    ("AOI", "aoi_display_name"),
+    ("AOI id", "aoi_id"),
+    ("Created", "create_time"),
+    ("Updated", "update_time"),
+]
+
+_SPEC_FILE = Parameter(name=["--spec-file", "-f"], allow_leading_hyphen=True)
+
+
+@app.command(name="list")
+def list_analyses(
+    *,
+    settings: SettingsParam,
+    aoi_id: str | None = None,
+    limit: Annotated[int | None, Parameter(validator=at_least_one)] = None,
+) -> None:
+    """List every analysis, following pagination to completion.
+
+    Parameters
+    ----------
+    aoi_id:
+        Only analyses over this AOI.
+    limit:
+        Stop after this many, instead of every page.
+    """
+    items = settings.client().analyses.list(aoi_id=aoi_id, limit=limit)
+    emit(items, COLUMNS, as_json=settings.as_json)
+
+
+@app.command(name="get")
+def get(analysis: str, *, settings: SettingsParam) -> None:
+    """Show one analysis.
+
+    Parameters
+    ----------
+    analysis:
+        The analysis to show.
+    """
+    emit_one(settings.client().analyses.get(analysis), FIELDS, as_json=settings.as_json)
+
+
+@app.command(name="create")
+def create(
+    *,
+    settings: SettingsParam,
+    spec_file: Annotated[Path, _SPEC_FILE],
+    display_name: str | None = None,
+    idempotency_key: str | None = None,
+    wait: bool = False,
+    poll_interval: float = 5.0,
+    wait_timeout: float | None = None,
+) -> None:
+    """Submit an analysis from a spec file.
+
+    Parameters
+    ----------
+    spec_file:
+        JSON spec, or a whole create request. Use - for stdin.
+    display_name:
+        Label for the analysis; overrides the spec file's.
+    idempotency_key:
+        Reuse a previous key to replay a submission instead of duplicating it.
+    wait:
+        Poll the analysis's newest run until it reaches a terminal state.
+    poll_interval:
+        Seconds between polls while waiting.
+    wait_timeout:
+        Give up waiting after this many seconds.
+    """
+    body = load_create_request(spec_file, display_name)
+    analysis = settings.client().analyses.create(body, idempotency_key=idempotency_key)
+    if not wait:
+        emit_one(analysis, FIELDS, as_json=settings.as_json)
+        return
+    note(f"[dim]submitted {analysis.uid}; waiting for the initial run[/dim]")
+    run = wait_for_run(
+        settings.client(), analysis.uid, poll_interval=poll_interval, timeout=wait_timeout
+    )
+    emit_one(run, RUN_FIELDS, as_json=settings.as_json)
+    if run.state is not models.RunState.COMPLETE:
+        raise RunFailed(f"run {run.uid} ended in {run.state}")
+
+
+@app.command(name="update")
+def update(
+    analysis: str,
+    *,
+    settings: SettingsParam,
+    display_name: str,
+) -> None:
+    """Rename an analysis.
+
+    Parameters
+    ----------
+    analysis:
+        The analysis to rename.
+    display_name:
+        The new label.
+    """
+    body = models.UpdateAnalysisRequest(display_name=display_name)
+    emit_one(settings.client().analyses.update(analysis, body), FIELDS, as_json=settings.as_json)
+
+
+@app.command(name="cancel")
+def cancel(analysis: str, *, settings: SettingsParam) -> None:
+    """Cancel an analysis.
+
+    Parameters
+    ----------
+    analysis:
+        The analysis to cancel.
+    """
+    emit_one(settings.client().analyses.cancel(analysis), FIELDS, as_json=settings.as_json)
+
+
+@app.command(name="estimate")
+def estimate(*, settings: SettingsParam, spec_file: Annotated[Path, _SPEC_FILE]) -> None:
+    """Estimate what a spec would cost, without submitting it.
+
+    Parameters
+    ----------
+    spec_file:
+        JSON spec, or a whole create request. Use - for stdin.
+    """
+    result = settings.client().analyses.estimate(load_create_request(spec_file))
+    emit_model(result, as_json=settings.as_json)

xoople/cli/catalog.py

@@ -0,0 +1,98 @@
+from cyclopts import App
+from xoople.cli._context import SettingsParam
+from xoople.cli._output import emit, emit_model, heading
+
+app = App(
+    name="catalog",
+    help="Browse products, measures and analysis designs.",
+)
+
+
+@app.command(name="products")
+def products(*, settings: SettingsParam) -> None:
+    """List the products you may submit to."""
+    result = settings.client().catalog.products()
+    emit(
+        result.products,
+        [
+            ("ID", "product_id"),
+            ("NAME", "display_name"),
+            ("VERSION", "version"),
+            ("LIFECYCLE", "lifecycle"),
+            ("OUTPUTS", "output_kinds"),
+        ],
+        as_json=settings.as_json,
+    )
+
+
+@app.command(name="measures")
+def measures(
+    *,
+    settings: SettingsParam,
+    product: str | None = None,
+    domain: list[str] | None = None,
+) -> None:
+    """List the bands, indices and contrasts you can request.
+
+    Parameters
+    ----------
+    product:
+        Only measures this product offers.
+    domain:
+        Only these domains. Repeat to pass several.
+    """
+    result = settings.client().catalog.measures(product=product, domain=domain)
+    if settings.as_json:
+        emit_model(result, as_json=True)
+        return
+    heading("bands")
+    emit(
+        result.bands,
+        [
+            ("ABBREVIATION", "abbreviation"),
+            ("NAME", "band_name"),
+            ("SINCE", "since_version"),
+            ("EXPERIMENTAL", "experimental"),
+        ],
+        as_json=False,
+    )
+    for label, items in (
+        ("indices", result.indices),
+        ("contrasts", result.contrasts),
+        ("indicators", result.indicators),
+    ):
+        heading(label)
+        emit(
+            items or [],
+            [
+                ("ABBREVIATION", "abbreviation"),
+                ("DOMAIN", "domain"),
+                ("FORMULA", "formula"),
+                ("REQUIRED BANDS", "required_bands"),
+                ("SINCE", "since_version"),
+            ],
+            as_json=False,
+        )
+
+
+@app.command(name="designs")
+def designs(*, settings: SettingsParam, product: str | None = None) -> None:
+    """List the starting-point analysis designs. Their `spec_fragment` seeds a spec file.
+
+    Parameters
+    ----------
+    product:
+        Only designs for this product.
+    """
+    result = settings.client().analysis_designs.list(product=product)
+    emit(
+        result.designs,
+        [
+            ("ID", "design_id"),
+            ("NAME", "display_name"),
+            ("PRODUCT", "product_id"),
+            ("DOMAINS", "domains"),
+            ("OUTPUT", "output_kind"),
+        ],
+        as_json=settings.as_json,
+    )