xoople-cli 0.1.0__tar.gz

xoople_cli-0.1.0/LICENSE

@@ -0,0 +1,23 @@
+Xoople SDK License
+
+Copyright (c) 2026 Xoople S.L. All rights reserved.
+
+This software is the confidential and proprietary property of Xoople S.L.
+
+Permission is granted, free of charge, to any person or organisation holding a
+valid subscription to the Xoople Products API to use, copy, and distribute this
+software, and to modify it for their own internal use, solely for the purpose of
+accessing that API.
+
+No other rights are granted. In particular, no right is granted to sell,
+sublicense, or otherwise distribute this software or any derivative work as a
+standalone product, or to use it to develop, operate, or market a service that
+competes with the Xoople Products API. The Xoople name and marks are not
+licensed hereunder.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL XOOPLE S.L. BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
+CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

xoople_cli-0.1.0/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: xoople-cli
+Version: 0.1.0
+Summary: Command-line interface for the Xoople Products API.
+License-Expression: LicenseRef-Xoople-Proprietary
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: xoople-sdk>=0.2.0
+Requires-Dist: cyclopts>=4.18,<5
+Requires-Dist: rich>=13.7
+Requires-Dist: xoople-sdk[entra]>=0.1.0 ; extra == 'entra'
+Requires-Python: >=3.12
+Project-URL: Homepage, https://xoople.com
+Provides-Extra: entra
+Description-Content-Type: text/markdown
+
+# xoople-cli
+
+Command-line interface for the Xoople Products API, over [`xoople-sdk`](../xoople-sdk).
+
+```console
+$ uv tool install xoople-cli
+$ export XOOPLE_API_URL=https://api.xoople.com XOOPLE_TOKEN=...
+$ xoople analyses list
+```
+
+Every command reads `--api-url` and `--token` from `XOOPLE_API_URL` and
+`XOOPLE_TOKEN`. `--json` prints the API response verbatim instead of a table, so
+output pipes into `jq`.
+
+## Commands
+
+| Group | Commands |
+| --- | --- |
+| `analyses` | `list` `get` `create` `update` `cancel` `estimate` |
+| `runs` | `list` `get` |
+| `outputs` | `list` `get` `access-url` |
+| `schedules` | `list` `get` `create` `pause` `resume` `cancel` `run` `estimate-run` |
+| `events` | `list` `get` |
+| `usage` | `history` `limits` |
+| `catalog` | `products` `measures` `designs` |
+| `access` | `me` `token` `features` |
+
+## Submitting an analysis
+
+The product spec is deeply nested and differs per product, so `create` and
+`estimate` take it as JSON rather than as flags:
+
+```console
+$ xoople catalog designs --json | jq '.designs[0].spec_fragment' > spec.json
+$ # fill in period and aoi, then:
+$ xoople analyses create -f spec.json --display-name "South Wales NDVI" --wait
+```
+
+The file holds either the bare spec or a whole create request (anything with a
+`spec` key). `-f -` reads stdin. `--wait` polls the initial run and exits
+non-zero if it does not reach `COMPLETE`.
+
+## Exit codes
+
+`0` success · `1` unexpected CLI error · `2` usage error · `3` unauthenticated · `4` forbidden ·
+`5` not found · `6` bad request or validation · `7` conflict · `8` rate limited ·
+`9` server error · `10` connection failure · `11` unreadable response ·
+`12` run finished in a non-`COMPLETE` state · `13` `--wait` timed out.

xoople_cli-0.1.0/README.md

@@ -0,0 +1,48 @@
+# xoople-cli
+
+Command-line interface for the Xoople Products API, over [`xoople-sdk`](../xoople-sdk).
+
+```console
+$ uv tool install xoople-cli
+$ export XOOPLE_API_URL=https://api.xoople.com XOOPLE_TOKEN=...
+$ xoople analyses list
+```
+
+Every command reads `--api-url` and `--token` from `XOOPLE_API_URL` and
+`XOOPLE_TOKEN`. `--json` prints the API response verbatim instead of a table, so
+output pipes into `jq`.
+
+## Commands
+
+| Group | Commands |
+| --- | --- |
+| `analyses` | `list` `get` `create` `update` `cancel` `estimate` |
+| `runs` | `list` `get` |
+| `outputs` | `list` `get` `access-url` |
+| `schedules` | `list` `get` `create` `pause` `resume` `cancel` `run` `estimate-run` |
+| `events` | `list` `get` |
+| `usage` | `history` `limits` |
+| `catalog` | `products` `measures` `designs` |
+| `access` | `me` `token` `features` |
+
+## Submitting an analysis
+
+The product spec is deeply nested and differs per product, so `create` and
+`estimate` take it as JSON rather than as flags:
+
+```console
+$ xoople catalog designs --json | jq '.designs[0].spec_fragment' > spec.json
+$ # fill in period and aoi, then:
+$ xoople analyses create -f spec.json --display-name "South Wales NDVI" --wait
+```
+
+The file holds either the bare spec or a whole create request (anything with a
+`spec` key). `-f -` reads stdin. `--wait` polls the initial run and exits
+non-zero if it does not reach `COMPLETE`.
+
+## Exit codes
+
+`0` success · `1` unexpected CLI error · `2` usage error · `3` unauthenticated · `4` forbidden ·
+`5` not found · `6` bad request or validation · `7` conflict · `8` rate limited ·
+`9` server error · `10` connection failure · `11` unreadable response ·
+`12` run finished in a non-`COMPLETE` state · `13` `--wait` timed out.

xoople_cli-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "xoople-cli"
+version = "0.1.0"
+description = "Command-line interface for the Xoople Products API."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "LicenseRef-Xoople-Proprietary"
+license-files = ["LICENSE"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "xoople-sdk>=0.2.0",
+    "cyclopts>=4.18,<5",
+    "rich>=13.7",
+]
+
+[project.optional-dependencies]
+entra = ["xoople-sdk[entra]>=0.1.0"]
+
+[project.scripts]
+xoople = "xoople.cli.main:main"
+
+[project.urls]
+Homepage = "https://xoople.com"
+
+[build-system]
+requires = ["uv_build>=0.11.6,<0.12"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "xoople.cli"
+
+[tool.uv.sources.xoople-sdk]
+workspace = true
+
+[dependency-groups]
+dev = [
+    "ruff>=0.15.7",
+    "pytest>=8.0",
+    "pytest-cov>=6.0",
+]

xoople_cli-0.1.0/pyproject.toml.orig

@@ -0,0 +1,53 @@
+[project]
+name = "xoople-cli"
+version = "0.1.0"
+description = "Command-line interface for the Xoople Products API."
+readme = "README.md"
+requires-python = ">=3.12"
+# Proprietary: licensed for use against the Xoople Products API, not
+# redistribution. `license-files` ships the text inside the wheel.
+license = "LicenseRef-Xoople-Proprietary"
+license-files = ["LICENSE"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+  "xoople-sdk>=0.2.0",
+  # Cyclopts parses docstrings for parameter help so signatures stay plain,
+  # supports union types and Pydantic models natively, and owns its parser.
+  # Global options + dependency injection go through the meta-app launcher
+  # in `main.py`.
+  "cyclopts>=4.18,<5",
+  "rich>=13.7",
+]
+
+[project.optional-dependencies]
+# Mirrors xoople-sdk[entra]: internal callers authenticating with Entra ID via
+# `--entra-scope`. Not needed for the token path.
+entra = [
+  "xoople-sdk[entra]>=0.1.0",
+]
+
+[project.scripts]
+xoople = "xoople.cli.main:main"
+
+[project.urls]
+Homepage = "https://xoople.com"
+
+[build-system]
+requires = ["uv_build>=0.11.6,<0.12"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "xoople.cli"
+
+[tool.uv.sources]
+xoople-sdk = { workspace = true }
+
+[dependency-groups]
+dev = [
+  "ruff>=0.15.7",
+  "pytest>=8.0",
+  "pytest-cov>=6.0",
+]

xoople_cli-0.1.0/src/xoople/cli/__init__.py

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

xoople_cli-0.1.0/src/xoople/cli/__main__.py

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

xoople_cli-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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,
+    )