datavo-cli 0.22.0__py3-none-any.whl

datavo_cli/config_store.py

@@ -0,0 +1,200 @@
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field, replace
+from pathlib import Path
+from datavo_sdk.client._transport import DEFAULT_SERVER_URL
+from datavo_sdk.server_config import default_config_dir
+
+
+def config_path() -> Path:
+    # ``~/.datavo`` is resolved once, in the SDK (entra/plan_cache/server_config use it).
+    return default_config_dir() / "config.json"
+
+
+@dataclass(frozen=True)
+class DatavoProfile:
+    api_base_url: str | None = None
+    auth_token: str | None = None
+    msal_tenant_id: str | None = None
+    msal_client_id: str | None = None
+    msal_scopes: list[str] | None = None
+
+
+@dataclass(frozen=True)
+class DatavoConfig:
+    active_profile: str | None = None
+    profiles: dict[str, DatavoProfile] = field(default_factory=dict)
+
+
+def _parse_profile(value: object) -> DatavoProfile:
+    if not isinstance(value, dict):
+        return DatavoProfile()
+    api_base_url = value.get("api_base_url")
+    auth_token = value.get("auth_token")
+    msal_tenant_id = value.get("msal_tenant_id")
+    msal_client_id = value.get("msal_client_id")
+    msal_scopes = value.get("msal_scopes")
+    if not isinstance(api_base_url, str):
+        api_base_url = None
+    if not isinstance(auth_token, str):
+        auth_token = None
+    if not isinstance(msal_tenant_id, str):
+        msal_tenant_id = None
+    if not isinstance(msal_client_id, str):
+        msal_client_id = None
+    if isinstance(msal_scopes, list):
+        msal_scopes = [scope for scope in msal_scopes if isinstance(scope, str) and scope.strip()]
+    else:
+        msal_scopes = None
+    return DatavoProfile(
+        api_base_url=api_base_url,
+        auth_token=auth_token,
+        msal_tenant_id=msal_tenant_id,
+        msal_client_id=msal_client_id,
+        msal_scopes=msal_scopes,
+    )
+
+
+def load_config() -> DatavoConfig:
+    path = config_path()
+    if not path.exists():
+        return DatavoConfig()
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return DatavoConfig()
+    if not isinstance(payload, dict):
+        return DatavoConfig()
+    active_profile = payload.get("active_profile")
+    if not isinstance(active_profile, str):
+        active_profile = None
+    raw_profiles = payload.get("profiles")
+    profiles: dict[str, DatavoProfile] = {}
+    if isinstance(raw_profiles, dict):
+        for name, value in raw_profiles.items():
+            if isinstance(name, str) and name:
+                profiles[name] = _parse_profile(value)
+    return DatavoConfig(active_profile=active_profile, profiles=profiles)
+
+
+def save_config(config: DatavoConfig) -> None:
+    path = config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    payload = {
+        "active_profile": config.active_profile,
+        "profiles": {
+            name: {
+                key: value
+                for key, value in {
+                    "api_base_url": profile.api_base_url,
+                    "auth_token": profile.auth_token,
+                    "msal_tenant_id": profile.msal_tenant_id,
+                    "msal_client_id": profile.msal_client_id,
+                    "msal_scopes": profile.msal_scopes,
+                }.items()
+                if value is not None
+            }
+            for name, profile in sorted(config.profiles.items())
+        },
+    }
+    path.write_text(json.dumps(payload, indent=2), encoding="utf-8")
+
+
+#: Where an unconfigured CLI points — the SDK's default, imported rather than restated
+#: so the two cannot drift. Override via ``DATAVO_API_BASE_URL`` / ``datavo config set``.
+DEFAULT_API_BASE_URL = DEFAULT_SERVER_URL
+
+
+def get_active_profile_name(config: DatavoConfig | None = None) -> str | None:
+    config = config or load_config()
+    env_name = (os.environ.get("DATAVO_PROFILE") or "").strip()
+    if env_name:
+        return env_name
+    return config.active_profile
+
+
+def resolve_profile(config: DatavoConfig | None = None, *, profile_name: str | None = None) -> tuple[str, DatavoProfile]:
+    config = config or load_config()
+    profile_name = profile_name or get_active_profile_name(config)
+    if profile_name and profile_name in config.profiles:
+        return profile_name, config.profiles[profile_name]
+    env_url = (os.environ.get("DATAVO_API_BASE_URL") or "").strip()
+    if profile_name and not env_url:
+        # A named profile that does not exist is a typo, not an unconfigured CLI: fail
+        # rather than land somewhere the caller did not name.
+        raise RuntimeError(f"Unknown Datavo profile: {profile_name}")
+    # Unconfigured, or pointed by env. Start from the default instance and let
+    # apply_env_overrides layer DATAVO_API_BASE_URL over it — so the CLI runs out of the
+    # box, and one construction path serves both cases.
+    name = profile_name or ("env" if env_url else "prod")
+    return name, apply_env_overrides(DatavoProfile(api_base_url=DEFAULT_API_BASE_URL))
+
+
+def apply_env_overrides(profile: DatavoProfile) -> DatavoProfile:
+    api_base_url = (os.environ.get("DATAVO_API_BASE_URL") or "").strip() or profile.api_base_url
+    auth_token = (os.environ.get("DATAVO_AUTH_TOKEN") or "").strip() or profile.auth_token
+    msal_tenant_id = (os.environ.get("DATAVO_ENTRA_TENANT_ID") or "").strip() or profile.msal_tenant_id
+    msal_client_id = (os.environ.get("DATAVO_ENTRA_CLIENT_ID") or "").strip() or profile.msal_client_id
+    env_audience = (os.environ.get("DATAVO_ENTRA_AUDIENCE") or "").strip()
+    env_scopes_raw = (os.environ.get("DATAVO_ENTRA_SCOPES") or "").strip()
+    msal_scopes = profile.msal_scopes
+    if env_scopes_raw:
+        msal_scopes = [scope.strip() for scope in env_scopes_raw.split(",") if scope.strip()]
+    elif env_audience:
+        msal_scopes = [f"{env_audience}/access_as_user" if env_audience.startswith("api://") else f"api://{env_audience}/access_as_user"]
+    return DatavoProfile(
+        api_base_url=api_base_url,
+        auth_token=auth_token,
+        msal_tenant_id=msal_tenant_id,
+        msal_client_id=msal_client_id,
+        msal_scopes=msal_scopes,
+    )
+
+
+def save_profile(name: str, profile: DatavoProfile, *, set_active: bool = False) -> DatavoConfig:
+    config = load_config()
+    profiles = dict(config.profiles)
+    profiles[name] = profile
+    updated = DatavoConfig(
+        active_profile=name if set_active or config.active_profile is None else config.active_profile,
+        profiles=profiles,
+    )
+    save_config(updated)
+    return updated
+
+
+def update_profile(name: str, **changes) -> DatavoConfig:
+    config = load_config()
+    if name not in config.profiles:
+        raise RuntimeError(f"Unknown Datavo profile: {name}")
+    profile = replace(config.profiles[name], **changes)
+    profiles = dict(config.profiles)
+    profiles[name] = profile
+    updated = DatavoConfig(active_profile=config.active_profile, profiles=profiles)
+    save_config(updated)
+    return updated
+
+
+def set_active_profile(name: str) -> DatavoConfig:
+    config = load_config()
+    if name not in config.profiles:
+        raise RuntimeError(f"Unknown Datavo profile: {name}")
+    updated = DatavoConfig(active_profile=name, profiles=dict(config.profiles))
+    save_config(updated)
+    return updated
+
+
+def remove_profile(name: str) -> DatavoConfig:
+    config = load_config()
+    if name not in config.profiles:
+        raise RuntimeError(f"Unknown Datavo profile: {name}")
+    profiles = dict(config.profiles)
+    profiles.pop(name, None)
+    active_profile = config.active_profile
+    if active_profile == name:
+        active_profile = next(iter(sorted(profiles)), None)
+    updated = DatavoConfig(active_profile=active_profile, profiles=profiles)
+    save_config(updated)
+    return updated

datavo_cli/diagnostics.py

@@ -0,0 +1,77 @@
+"""Version-skew diagnostics for the CLI error path.
+
+A stale CLI meeting a newer server is the most likely thing to go wrong for a
+user who installed once and came back later. When a command fails with a 422 or
+a response the client cannot parse, the handler appends one actionable line
+comparing the client's version to the server's ``release_version`` (fetched only
+on the error path, so the happy path stays at one round trip).
+"""
+
+from __future__ import annotations
+
+import importlib.metadata
+from urllib.parse import urlsplit, urlunsplit
+
+from datavo_sdk import fetch_server_config
+
+_CLI_DISTRIBUTION = "datavo-cli"
+_UPGRADE_HINT = "uv tool upgrade datavo-cli"
+
+
+def resolve_client_version() -> str:
+    """The CLI's real installed version.
+
+    Reads the published distribution version (injected at build time), not the
+    hard-coded ``datavo_cli.__version__`` placeholder — a skew line is only worth
+    printing if the client version is real. Falls back to ``__version__`` when the
+    distribution metadata is absent (e.g. running from a source checkout).
+    """
+    try:
+        return importlib.metadata.version(_CLI_DISTRIBUTION)
+    except importlib.metadata.PackageNotFoundError:
+        from . import __version__
+
+        return __version__
+
+
+def server_root_from_request_url(url: str) -> str | None:
+    """The server root (where ``/config`` lives) for a failing request URL.
+
+    Mirrors the transport: the API is mounted under ``/api``, while ``/config``
+    sits at the root. Returns ``None`` if the URL is not absolute.
+    """
+    try:
+        parts = urlsplit(url)
+    except Exception:
+        return None
+    if not parts.scheme or not parts.netloc:
+        return None
+    idx = parts.path.find("/api")
+    base_path = parts.path[:idx] if idx != -1 else ""
+    return urlunsplit((parts.scheme, parts.netloc, base_path, "", ""))
+
+
+def version_skew_line(
+    server_root: str,
+    *,
+    client_version: str | None = None,
+    timeout: float = 5.0,
+) -> str | None:
+    """One actionable upgrade line when client and server versions differ, else ``None``.
+
+    Best-effort and never raises: it fetches ``GET /config`` for the server's
+    ``release_version`` and returns ``None`` when the versions match or the server
+    version cannot be determined, so no misleading upgrade line is printed.
+    """
+    client = client_version or resolve_client_version()
+    try:
+        config = fetch_server_config(server_root, timeout=timeout)
+    except Exception:
+        return None
+    server = getattr(config, "release_version", None)
+    if not server or server == client:
+        return None
+    return (
+        f"datavo CLI {client} is talking to server {server} — "
+        f"upgrade with `{_UPGRADE_HINT}`"
+    )

datavo_cli/errors.py

@@ -0,0 +1,49 @@
+"""Rendering CLI errors legibly, and appending a version-skew line when skew is the
+likely cause. Kept out of ``main`` so the entrypoint stays pure dispatch.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+
+from datavo_sdk import DatavoApiError, DatavoResponseParseError
+
+from .diagnostics import server_root_from_request_url, version_skew_line
+
+
+def verbose_enabled(args) -> bool:
+    if getattr(args, "verbose", False):
+        return True
+    return os.environ.get("DATAVO_VERBOSE", "").strip().lower() in ("1", "true", "yes")
+
+
+def report_cli_error(exc: Exception, *, verbose: bool) -> None:
+    """Render a CLI error and, on skew-shaped failures, append a version line.
+
+    A ``DatavoApiError`` already composes method/url/status in its message (so we
+    print the whole message, not the bare detail); a 422 or a client-side
+    ``DatavoResponseParseError`` is the case where a client/server version-skew line
+    is worth appending.
+    """
+    skew_url: str | None = None
+    if isinstance(exc, DatavoApiError):
+        print(str(exc), file=sys.stderr)
+        if verbose and exc.raw_detail is not None:
+            print(json.dumps(exc.raw_detail, indent=2), file=sys.stderr)
+        if exc.status_code == 422:
+            skew_url = exc.url
+    elif isinstance(exc, DatavoResponseParseError):
+        print(str(exc), file=sys.stderr)
+        if verbose:
+            print(str(exc.error), file=sys.stderr)
+        skew_url = exc.url
+    else:
+        print(str(exc), file=sys.stderr)
+
+    if skew_url is not None:
+        root = server_root_from_request_url(skew_url)
+        line = version_skew_line(root) if root else None
+        if line:
+            print(line, file=sys.stderr)

datavo_cli/main.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+import sys
+
+try:
+    import argcomplete
+except ImportError:  # pragma: no cover
+    argcomplete = None
+
+from .errors import report_cli_error, verbose_enabled
+
+from . import __version__
+from .commands import (
+    handle_auth_command,
+    handle_config_command,
+    handle_dataset_command,
+    handle_events_command,
+    handle_render_dataset_cache_command,
+    handle_sample_command,
+    handle_sample_store_command,
+    handle_source_import_command,
+    handle_split_set_command,
+    handle_share_command,
+    handle_stats_command,
+    handle_teams_command,
+    handle_transfer_command,
+    handle_unshare_command,
+    handle_users_command,
+    handle_warm_command,
+)
+from .parsers import build_root_parser
+
+
+def main() -> int:
+    parser = build_root_parser()
+    if argcomplete is not None:
+        argcomplete.autocomplete(parser)
+    args = parser.parse_args()
+    if args.command is None:
+        parser.print_help()
+        return 0
+    try:
+        if args.command == "config":
+            return handle_config_command(args)
+        if args.command == "auth":
+            return handle_auth_command(args)
+        if args.command == "sample-store":
+            return handle_sample_store_command(args)
+        if args.command == "source-import":
+            return handle_source_import_command(args)
+        if args.command == "sample":
+            return handle_sample_command(args)
+        if args.command == "stats":
+            return handle_stats_command(args)
+        if args.command == "dataset":
+            return handle_dataset_command(args)
+        if args.command == "split-set":
+            return handle_split_set_command(args)
+        if args.command == "teams":
+            return handle_teams_command(args)
+        if args.command == "share":
+            return handle_share_command(args)
+        if args.command == "unshare":
+            return handle_unshare_command(args)
+        if args.command == "transfer":
+            return handle_transfer_command(args)
+        if args.command == "users":
+            return handle_users_command(args)
+        if args.command == "events":
+            return handle_events_command(args)
+        if args.command == "render-dataset-cache":
+            return handle_render_dataset_cache_command(args)
+        if args.command == "warm":
+            return handle_warm_command(args)
+        if args.command == "version":
+            output_format = getattr(args, "format", "plain")
+            if output_format == "json":
+                print(f'{{"datavo_cli": "{__version__}"}}')
+            else:
+                print(__version__)
+            return 0
+        parser.error(f"Unknown command: {args.command}")
+        return 2
+    except Exception as exc:
+        report_cli_error(exc, verbose=verbose_enabled(args))
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())