xoople-cli 0.2.0__tar.gz → 0.3.0__tar.gz

{xoople_cli-0.2.0 → xoople_cli-0.3.0}/PKG-INFO

@@ -1,15 +1,15 @@
 Metadata-Version: 2.4
 Name: xoople-cli
-Version: 0.2.0
+Version: 0.3.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.3.0
+Requires-Dist: xoople-sdk>=0.5.0
 Requires-Dist: cyclopts>=4.18,<5
 Requires-Dist: rich>=13.7
-Requires-Dist: xoople-sdk[entra]>=0.3.0 ; extra == 'entra'
+Requires-Dist: xoople-sdk[entra]>=0.5.0 ; extra == 'entra'
 Requires-Python: >=3.12
 Project-URL: Homepage, https://xoople.com
 Provides-Extra: entra
@@ -41,6 +41,26 @@ output pipes into `jq`.
 | `usage` | `history` `limits` |
 | `catalog` | `products` `measures` `designs` |
 | `access` | `me` `token` `features` |
+| `auth` | `login` `logout` `status` |
+
+## Signing in
+
+`auth login` signs in through the browser with PKCE and stores the session at
+`$XDG_CONFIG_HOME/xoople/session.json` (`~/.config/xoople/session.json` by
+default), readable only by you. Every later command uses that session when
+neither `--token` nor `--entra-scope` is given, and refreshes it when the
+access token is close to expiry.
+
+```console
+$ export XOOPLE_API_URL=https://api.xoople.com XOOPLE_CIAM_CLIENT_ID=client_...
+$ xoople auth login
+$ xoople analyses list
+```
+
+`auth status` exits `3` when there is no stored session, so a script can test
+for a sign-in. `--ciam-redirect-uri` (`XOOPLE_CIAM_REDIRECT_URI`) overrides the
+loopback URI the browser returns to; it must match a URI registered for the
+CIAM client.
 
 ## Submitting an analysis
 
@@ -59,7 +79,8 @@ non-zero if it does not reach `COMPLETE`.
 
 ## Exit codes
 
-`0` success · `1` unexpected CLI error · `2` usage error · `3` unauthenticated · `4` forbidden ·
+`0` success · `1` unexpected CLI error · `2` usage error ·
+`3` unauthenticated, including a failed or absent sign-in · `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.2.0 → xoople_cli-0.3.0}/README.md

@@ -24,6 +24,26 @@ output pipes into `jq`.
 | `usage` | `history` `limits` |
 | `catalog` | `products` `measures` `designs` |
 | `access` | `me` `token` `features` |
+| `auth` | `login` `logout` `status` |
+
+## Signing in
+
+`auth login` signs in through the browser with PKCE and stores the session at
+`$XDG_CONFIG_HOME/xoople/session.json` (`~/.config/xoople/session.json` by
+default), readable only by you. Every later command uses that session when
+neither `--token` nor `--entra-scope` is given, and refreshes it when the
+access token is close to expiry.
+
+```console
+$ export XOOPLE_API_URL=https://api.xoople.com XOOPLE_CIAM_CLIENT_ID=client_...
+$ xoople auth login
+$ xoople analyses list
+```
+
+`auth status` exits `3` when there is no stored session, so a script can test
+for a sign-in. `--ciam-redirect-uri` (`XOOPLE_CIAM_REDIRECT_URI`) overrides the
+loopback URI the browser returns to; it must match a URI registered for the
+CIAM client.
 
 ## Submitting an analysis
 
@@ -42,7 +62,8 @@ non-zero if it does not reach `COMPLETE`.
 
 ## Exit codes
 
-`0` success · `1` unexpected CLI error · `2` usage error · `3` unauthenticated · `4` forbidden ·
+`0` success · `1` unexpected CLI error · `2` usage error ·
+`3` unauthenticated, including a failed or absent sign-in · `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.2.0 → xoople_cli-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "xoople-cli"
-version = "0.2.0"
+version = "0.3.0"
 description = "Command-line interface for the Xoople Products API."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -11,13 +11,13 @@ classifiers = [
     "Programming Language :: Python :: 3.12",
 ]
 dependencies = [
-    "xoople-sdk>=0.3.0",
+    "xoople-sdk>=0.5.0",
     "cyclopts>=4.18,<5",
     "rich>=13.7",
 ]
 
 [project.optional-dependencies]
-entra = ["xoople-sdk[entra]>=0.3.0"]
+entra = ["xoople-sdk[entra]>=0.5.0"]
 
 [project.scripts]
 xoople = "xoople.cli.main:main"

{xoople_cli-0.2.0 → xoople_cli-0.3.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "xoople-cli"
-version = "0.2.0"
+version = "0.3.0"
 description = "Command-line interface for the Xoople Products API."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -13,7 +13,7 @@ classifiers = [
   "Programming Language :: Python :: 3.12",
 ]
 dependencies = [
-  "xoople-sdk>=0.3.0",
+  "xoople-sdk>=0.5.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
@@ -26,7 +26,7 @@ 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.3.0",
+  "xoople-sdk[entra]>=0.5.0",
 ]
 
 [project.scripts]

xoople_cli-0.3.0/src/xoople/cli/_ciam.py

@@ -0,0 +1,190 @@
+"""The browser half of a CIAM sign-in, and where the session is stored.
+
+The SDK owns the protocol. It holds the endpoints, PKCE, both grants and the
+refresh. This module holds what needs a terminal. It opens a browser, binds the
+loopback port and writes the session file.
+"""
+
+import os
+import secrets
+import tempfile
+import time
+import urllib.parse
+import webbrowser
+from collections.abc import Callable
+from dataclasses import dataclass
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from pathlib import Path
+from typing import Protocol, Self
+
+from pydantic import ValidationError
+from xoople.cli._errors import LoginFailed
+from xoople.sdk.auth import (
+    CiamUserSession,
+    ciam_authorize_url,
+    ciam_exchange_code,
+    ciam_pkce_pair,
+)
+from xoople.sdk.errors import CredentialError
+
+DEFAULT_REDIRECT_URI = "http://localhost:8976/callback"
+"""Fixed, because CIAM matches a redirect URI exactly and must hold this one."""
+
+_CALLBACK_TIMEOUT_SECONDS = 300
+
+_DONE_PAGE = b"<html><body><p>Xoople sign-in is complete. Close this tab.</p></body></html>"
+
+
+class _Listener(Protocol):
+    def __call__(self, redirect_uri: str, timeout: float) -> dict[str, str]: ...
+
+
+class _Exchanger(Protocol):
+    def __call__(self, *, client_id: str, code: str, verifier: str) -> CiamUserSession: ...
+
+
+@dataclass(frozen=True, slots=True)
+class CiamConfig:
+    """What a login needs: the CIAM client and the URI the browser comes back to."""
+
+    client_id: str
+    redirect_uri: str = DEFAULT_REDIRECT_URI
+
+    @classmethod
+    def resolve(cls, client_id: str | None, redirect_uri: str | None) -> Self:
+        if not client_id:
+            raise LoginFailed("no CIAM client: pass --ciam-client-id or set XOOPLE_CIAM_CLIENT_ID")
+        return cls(client_id=client_id, redirect_uri=redirect_uri or DEFAULT_REDIRECT_URI)
+
+
+def session_path() -> Path:
+    """Where the session file lives, honouring `XDG_CONFIG_HOME`."""
+    root = os.environ.get("XDG_CONFIG_HOME")
+    base = Path(root) if root else Path.home() / ".config"
+    return base / "xoople" / "session.json"
+
+
+def read_session(path: Path | None = None) -> CiamUserSession | None:
+    """The stored session, or None when there is none this CLI can read."""
+    target = path or session_path()
+    try:
+        raw = target.read_bytes()
+    except OSError:
+        return None
+    try:
+        return CiamUserSession.model_validate_json(raw)
+    except ValidationError:
+        return None
+
+
+def write_session(session: CiamUserSession, path: Path | None = None) -> Path:
+    """Store the session so only this user can read it.
+
+    The mode argument of `os.open` applies to a new file only, so a rewrite of
+    an existing permissive file would keep its mode. This writes a private
+    temporary file and renames it over the target.
+    """
+    target = path or session_path()
+    target.parent.mkdir(parents=True, exist_ok=True)
+    handle, temporary = tempfile.mkstemp(dir=target.parent, prefix=".session-")
+    try:
+        os.fchmod(handle, 0o600)
+        with os.fdopen(handle, "w", encoding="utf-8") as stream:
+            stream.write(session.model_dump_json())
+        # Rename is atomic within one directory, so a reader never sees a
+        # half-written session.
+        os.replace(temporary, target)
+    except BaseException:
+        Path(temporary).unlink(missing_ok=True)
+        raise
+    return target
+
+
+def clear_session(path: Path | None = None) -> bool:
+    """Remove the stored session. False when there was nothing to remove."""
+    target = path or session_path()
+    try:
+        target.unlink()
+    except OSError:
+        return False
+    return True
+
+
+class _CallbackHandler(BaseHTTPRequestHandler):
+    """Reads the query off one browser redirect and answers with a closing page."""
+
+    captured: dict[str, str]
+    callback_path: str
+
+    def do_GET(self) -> None:
+        parsed = urllib.parse.urlsplit(self.path)
+        if parsed.path != self.callback_path:
+            self.send_error(404)
+            return
+        for key, values in urllib.parse.parse_qs(parsed.query).items():
+            self.captured[key] = values[0]
+        self.send_response(200)
+        self.send_header("Content-Type", "text/html; charset=utf-8")
+        self.send_header("Content-Length", str(len(_DONE_PAGE)))
+        self.end_headers()
+        self.wfile.write(_DONE_PAGE)
+
+    def log_message(self, format: str, *args: object) -> None:
+        del format, args  # The server must not write to the CLI's streams.
+
+
+def await_callback(redirect_uri: str, timeout: float) -> dict[str, str]:
+    """Serve the redirect URI until the browser returns, and give back its query."""
+    parsed = urllib.parse.urlsplit(redirect_uri)
+    if parsed.hostname is None or parsed.port is None:
+        raise LoginFailed(f"redirect URI needs an explicit host and port: {redirect_uri}")
+    captured: dict[str, str] = {}
+    handler = type(
+        "_BoundCallbackHandler",
+        (_CallbackHandler,),
+        {"captured": captured, "callback_path": parsed.path or "/"},
+    )
+    deadline = time.monotonic() + timeout
+    with HTTPServer((parsed.hostname, parsed.port), handler) as server:
+        # A browser also asks for /favicon.ico, so serve until the callback lands.
+        while not captured and time.monotonic() < deadline:
+            server.timeout = max(1.0, deadline - time.monotonic())
+            server.handle_request()
+    if not captured:
+        raise LoginFailed("the browser did not return a sign-in result in time")
+    return captured
+
+
+def login(
+    config: CiamConfig,
+    *,
+    announce: Callable[[str], None],
+    listener: _Listener = await_callback,
+    open_browser: Callable[[str], bool] = webbrowser.open,
+    exchange: _Exchanger = ciam_exchange_code,
+    callback_timeout: float = _CALLBACK_TIMEOUT_SECONDS,
+) -> CiamUserSession:
+    """Run one browser login and return the session it produced."""
+    verifier, challenge = ciam_pkce_pair()
+    state = secrets.token_urlsafe(16)
+    url = ciam_authorize_url(
+        client_id=config.client_id,
+        redirect_uri=config.redirect_uri,
+        challenge=challenge,
+        state=state,
+    )
+    announce(url)
+    open_browser(url)
+    captured = listener(config.redirect_uri, callback_timeout)
+    if "error" in captured:
+        raise LoginFailed(f"CIAM refused the sign-in: {captured['error']}")
+    if captured.get("state") != state:
+        raise LoginFailed("the sign-in result does not match this request")
+    code = captured.get("code")
+    if not code:
+        raise LoginFailed("the sign-in result carries no authorization code")
+    try:
+        return exchange(client_id=config.client_id, code=code, verifier=verifier)
+    except CredentialError as exc:
+        # One exit code covers every sign-in failure. The SDK message says which.
+        raise LoginFailed(str(exc)) from None

{xoople_cli-0.2.0 → xoople_cli-0.3.0}/src/xoople/cli/_context.py

@@ -1,11 +1,17 @@
 from collections.abc import Callable
 from dataclasses import dataclass, field
-from typing import Annotated
+from typing import Annotated, Protocol
 
 from cyclopts import Parameter
+from xoople.cli import _ciam
 from xoople.cli._errors import UsageError
 from xoople.sdk import Config, CredentialProvider, XoopleClient
-from xoople.sdk.auth import EntraCredential, StaticToken
+from xoople.sdk.auth import (
+    CiamUserCredentials,
+    CiamUserSession,
+    EntraCredential,
+    StaticToken,
+)
 
 
 @dataclass(frozen=True)
@@ -15,6 +21,8 @@ class Credentials:
     base_url: str | None = None
     token: str | None = None
     entra_scope: str | None = None
+    ciam_client_id: str | None = None
+    ciam_redirect_uri: str | None = None
     timeout: float = 30.0
     max_retries: int = 3
 
@@ -22,6 +30,15 @@ class Credentials:
 # The client factory is swapped for a fake in tests.
 type ClientFactory = Callable[[Credentials], XoopleClient]
 
+
+class LoginRunner(Protocol):
+    """Runs one browser sign-in. Tests supply one that opens no browser."""
+
+    def __call__(
+        self, config: _ciam.CiamConfig, *, announce: Callable[[str], None]
+    ) -> CiamUserSession: ...
+
+
 # The launcher injects ``Settings`` via ``parse=False``; commands stay plain
 # functions and tests drive them over a fake transport.
 type SettingsParam = Annotated[Settings, Parameter(parse=False)]
@@ -45,6 +62,7 @@ class Settings:
 
     credentials: Credentials
     factory: ClientFactory
+    login: LoginRunner = _ciam.login
     as_json: bool = False
     _client: XoopleClient | None = field(default=None, repr=False)
 
@@ -59,12 +77,24 @@ class Settings:
             self._client = None
 
 
+def _persist_session(session: CiamUserSession) -> None:
+    _ciam.write_session(session)
+
+
 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)
+    if credentials.token:
+        return StaticToken(credentials.token)
+    session = _ciam.read_session()
+    if session is not None:
+        # The credential refreshes a user token itself. Store what it mints, so
+        # the next run does not spend another refresh token.
+        return CiamUserCredentials(session, on_refresh=_persist_session)
+    raise UsageError(
+        "no credentials: run `xoople auth login`, pass --token, set XOOPLE_TOKEN, "
+        "or pass --entra-scope"
+    )
 
 
 def build_client(credentials: Credentials) -> XoopleClient:

{xoople_cli-0.2.0 → xoople_cli-0.3.0}/src/xoople/cli/_errors.py

@@ -32,6 +32,16 @@ class UsageError(CliError):
     exit_code = USAGE_EXIT
 
 
+class LoginFailed(CliError):
+    """A CIAM sign-in did not produce a session.
+
+    Takes the API's unauthenticated code: the outcome a caller must handle is
+    the same, so a script does not need a second number for it.
+    """
+
+    exit_code = EXIT_CODES[errors.AuthenticationError]
+
+
 class RunFailed(CliError):
     """``--wait`` finished, but the run ended in a non-``COMPLETE`` state."""
 

{xoople_cli-0.2.0 → xoople_cli-0.3.0}/src/xoople/cli/_output.py

@@ -7,12 +7,9 @@ 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.
+# Fields holding a 0..1 fraction, rendered as whole percent. Keyed on the field name
+# because the unit belongs to the field, not the emitting command. The generated models
+# carry no `ge`/`le` bounds to infer it from; if the spec adds them, read those instead.
 _FRACTION_FIELDS = frozenset({"fraction", "estimate_confidence"})
 
 # Piped output must not depend on the terminal that happened to launch it, so a

xoople_cli-0.3.0/src/xoople/cli/auth.py

@@ -0,0 +1,53 @@
+from cyclopts import App
+from pydantic import BaseModel
+from xoople.cli import _ciam
+from xoople.cli._context import SettingsParam
+from xoople.cli._errors import LoginFailed
+from xoople.cli._output import emit_one, note
+
+app = App(
+    name="auth",
+    help="Sign in to Xoople, and show or discard the stored session.",
+)
+
+FIELDS = [("EMAIL", "email"), ("ORGANIZATION", "org_id"), ("EXPIRES", "expires_at")]
+
+
+class _StatusRow(BaseModel):
+    """The part of a session that is safe to print. It carries no token."""
+
+    email: str | None
+    org_id: str | None
+    expires_at: int
+
+
+@app.command(name="login")
+def login(*, settings: SettingsParam) -> None:
+    """Sign in through the browser and store the session for later commands."""
+    config = _ciam.CiamConfig.resolve(
+        settings.credentials.ciam_client_id, settings.credentials.ciam_redirect_uri
+    )
+    note(f"Serving the sign-in callback on {config.redirect_uri}")
+    session = settings.login(config, announce=lambda url: note(f"Opening {url}"))
+    path = _ciam.write_session(session)
+    note(f"Signed in as {session.email or session.client_id}; session stored at {path}")
+
+
+@app.command(name="logout")
+def logout(*, settings: SettingsParam) -> None:
+    """Discard the stored session."""
+    del settings
+    if _ciam.clear_session():
+        note("Signed out.")
+        return
+    note("No stored session.")
+
+
+@app.command(name="status")
+def status(*, settings: SettingsParam) -> None:
+    """Show who the stored session belongs to, and when it expires."""
+    session = _ciam.read_session()
+    if session is None:
+        raise LoginFailed("no stored session: run `xoople auth login`")
+    row = _StatusRow(email=session.email, org_id=session.org_id, expires_at=session.expires_at)
+    emit_one(row, FIELDS, as_json=settings.as_json)

{xoople_cli-0.2.0 → xoople_cli-0.3.0}/src/xoople/cli/catalog.py

@@ -101,6 +101,25 @@ def projections(*, settings: SettingsParam, bbox: str) -> None:
     )
 
 
+@app.command(name="cloud-mask-presets")
+def cloud_mask_presets(*, settings: SettingsParam) -> None:
+    """List the scene-class masking presets, and the scene classes each one discards.
+
+    A preset name is what `cloud_mask_mode` accepts on an imagery request. The
+    classes are published here so a request never has to restate them.
+    """
+    result = settings.client().catalog.cloud_mask_presets()
+    emit(
+        result.presets,
+        [
+            ("MODE", "mode"),
+            ("EXCLUDED CLASSES", "excluded_classes"),
+            ("EXCLUDED CLASS NAMES", "excluded_class_names"),
+        ],
+        as_json=settings.as_json,
+    )
+
+
 @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.

{xoople_cli-0.2.0 → xoople_cli-0.3.0}/src/xoople/cli/main.py

@@ -4,6 +4,7 @@ from cyclopts import App, CycloptsError, Parameter
 from xoople.cli import (
     access,
     analyses,
+    auth,
     catalog,
     events,
     outputs,
@@ -12,18 +13,26 @@ from xoople.cli import (
     schedules,
     usage,
 )
-from xoople.cli._context import ClientFactory, Credentials, Settings, build_client
+from xoople.cli._ciam import login as ciam_login
+from xoople.cli._context import (
+    ClientFactory,
+    Credentials,
+    LoginRunner,
+    Settings,
+    build_client,
+)
 from xoople.cli._errors import USAGE_EXIT, CliError, report
 from xoople.cli._output import note
 from xoople.cli._version import version
 from xoople.sdk import errors
 
 
-def create_app(factory: ClientFactory = build_client) -> App:
-    """The command tree, bound to a way of building clients.
+def create_app(factory: ClientFactory = build_client, login: LoginRunner = ciam_login) -> App:
+    """The command tree, bound to a way of building clients and signing in.
 
     Tests build the tree over a fake transport rather than reaching into module
     globals, so every command runs its real argument parsing and rendering.
+    `login` is the same seam for the sign-in, which opens a browser.
     """
     app = App(
         name="xoople",
@@ -39,6 +48,7 @@ def create_app(factory: ClientFactory = build_client) -> App:
     app.command(usage.app)
     app.command(catalog.app)
     app.command(access.app)
+    app.command(auth.app)
 
     @app.meta.default
     def launcher(
@@ -46,6 +56,10 @@ def create_app(factory: ClientFactory = build_client) -> App:
         api_url: Annotated[str | None, Parameter(env_var="XOOPLE_API_URL")] = None,
         token: Annotated[str | None, Parameter(env_var="XOOPLE_TOKEN")] = None,
         entra_scope: Annotated[str | None, Parameter(env_var="XOOPLE_ENTRA_SCOPE")] = None,
+        ciam_client_id: Annotated[str | None, Parameter(env_var="XOOPLE_CIAM_CLIENT_ID")] = None,
+        ciam_redirect_uri: Annotated[
+            str | None, Parameter(env_var="XOOPLE_CIAM_REDIRECT_URI")
+        ] = None,
         timeout: Annotated[float, Parameter()] = 30.0,
         max_retries: Annotated[int, Parameter()] = 3,
         json_output: Annotated[bool, Parameter(name="--json")] = False,
@@ -61,6 +75,11 @@ def create_app(factory: ClientFactory = build_client) -> App:
         entra_scope:
             Authenticate with Entra ID for this scope instead of a token
             (internal use; needs the entra extra).
+        ciam_client_id:
+            Xoople CIAM client ID, used by `auth login`.
+        ciam_redirect_uri:
+            Loopback URI the browser returns the sign-in to. It must match the
+            URI registered for the CIAM client.
         timeout:
             Per-request timeout, in seconds.
         max_retries:
@@ -78,10 +97,13 @@ def create_app(factory: ClientFactory = build_client) -> App:
                 base_url=api_url,
                 token=token,
                 entra_scope=entra_scope,
+                ciam_client_id=ciam_client_id,
+                ciam_redirect_uri=ciam_redirect_uri,
                 timeout=timeout,
                 max_retries=max_retries,
             ),
             factory=factory,
+            login=login,
             as_json=json_output,
         )
         try:

{xoople_cli-0.2.0 → xoople_cli-0.3.0}/src/xoople/cli/outputs.py

@@ -75,3 +75,37 @@ def access_url(
         analysis, output, ttl_seconds=ttl_seconds
     )
     emit_model(result, as_json=settings.as_json)
+
+
+@app.command(name="summary")
+def summary(analysis: str, output: str, *, settings: SettingsParam) -> None:
+    """Show an output's summary: aggregate coverage, grain and pixel statistics.
+
+    Parameters
+    ----------
+    analysis:
+        The analysis the output belongs to.
+    output:
+        The output whose summary to show.
+    """
+    emit_model(
+        settings.client().analyses.outputs.get_summary(analysis, output),
+        as_json=settings.as_json,
+    )
+
+
+@app.command(name="refresh-summary")
+def refresh_summary(analysis: str, output: str, *, settings: SettingsParam) -> None:
+    """Start (or join) an asynchronous recomputation of an output's summary.
+
+    Parameters
+    ----------
+    analysis:
+        The analysis the output belongs to.
+    output:
+        The output whose summary to refresh.
+    """
+    emit_model(
+        settings.client().analyses.outputs.refresh_summary(analysis, output),
+        as_json=settings.as_json,
+    )

{xoople_cli-0.2.0 → xoople_cli-0.3.0}/src/xoople/cli/projects.py

@@ -20,6 +20,7 @@ FIELDS = [
     ("Name", "name"),
     ("UID", "uid"),
     ("Display name", "display_name"),
+    ("Description", "description"),
     ("Default", "is_default"),
     ("Archive time", "archive_time"),
     ("Create time", "create_time"),
@@ -44,15 +45,57 @@ def list_projects(
 
 
 @app.command(name="create")
-def create(name: str, *, settings: SettingsParam) -> None:
+def create(name: str, *, description: str | None = None, settings: SettingsParam) -> None:
     """Create a project.
 
     Parameters
     ----------
     name:
         The project's display name.
+    description:
+        The project's description, at most 500 characters.
     """
-    emit_one(settings.client().projects.create(name), FIELDS, as_json=settings.as_json)
+    emit_one(settings.client().projects.create(name, description), FIELDS, as_json=settings.as_json)
+
+
+@app.command(name="get")
+def get(project: str, *, settings: SettingsParam) -> None:
+    """Show one project, archived or not.
+
+    Parameters
+    ----------
+    project:
+        The project to show.
+    """
+    emit_one(settings.client().projects.get(project), FIELDS, as_json=settings.as_json)
+
+
+@app.command(name="update")
+def update(
+    project: str,
+    *,
+    display_name: str | None = None,
+    description: str | None = None,
+    settings: SettingsParam,
+) -> None:
+    """Change a project's display name, its description, or both.
+
+    Parameters
+    ----------
+    project:
+        The project to change.
+    display_name:
+        The new display name.
+    description:
+        The new description. Pass an empty string to clear it.
+    """
+    emit_one(
+        settings.client().projects.update(
+            project, display_name=display_name, description=description
+        ),
+        FIELDS,
+        as_json=settings.as_json,
+    )
 
 
 @app.command(name="add-member")
@@ -116,3 +159,32 @@ def archive(project: str, *, settings: SettingsParam) -> None:
     """
     settings.client().projects.archive(project)
     note(f"[dim]{project} is archived[/dim]")
+
+
+@app.command(name="record-access")
+def record_access(project: str, *, settings: SettingsParam) -> None:
+    """Record that you opened a project, which orders `projects recent`.
+
+    Parameters
+    ----------
+    project:
+        The project you opened.
+    """
+    settings.client().projects.record_access(project)
+    note(f"[dim]{project} is your most recent project[/dim]")
+
+
+@app.command(name="recent")
+def recent(
+    *,
+    settings: SettingsParam,
+    limit: Annotated[int | None, Parameter(validator=at_least_one)] = None,
+) -> None:
+    """List the projects you opened most recently.
+
+    Parameters
+    ----------
+    limit:
+        Return this many, instead of the default four.
+    """
+    emit(settings.client().projects.recent(limit=limit), COLUMNS, as_json=settings.as_json)