datavo-cli 0.22.0__py3-none-any.whl

datavo_cli/commands/jobpool.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import sys
+
+import yaml
+
+from datavo_sdk import SampleStream, get_default_shard_cache
+from datavo_sdk.jobpool import render_dataset_cache
+
+from ..client_factory import build_client
+
+
+def _parse_tier(spec: str) -> dict[str, object]:
+    """Parse a ``--tier TYPE[,max_bytes][,name]`` value into a tier mapping."""
+    parts = [p.strip() for p in spec.split(",") if p.strip()]
+    if not parts:
+        raise ValueError("empty --tier value")
+    tier: dict[str, object] = {"type": parts[0]}
+    if len(parts) > 1:
+        tier["max_bytes"] = parts[1]
+    if len(parts) > 2:
+        tier["name"] = parts[2]
+    return tier
+
+
+def handle_render_dataset_cache_command(args) -> int:
+    tiers = [_parse_tier(spec) for spec in args.tiers]
+    rendered = render_dataset_cache(
+        disk=args.disk,
+        host_path=args.host_path,
+        mount=args.mount,
+        tiers=tiers,
+        token_alias=args.token_alias,
+    )
+    print(yaml.safe_dump(rendered, sort_keys=False).rstrip())
+    return 0
+
+
+def handle_warm_command(args) -> int:
+    cache = get_default_shard_cache(args.cache_config)
+    with build_client() as client:
+        dataset = SampleStream.from_dataset(
+            args.dataset,
+            keys=list(args.keys) if args.keys else None,
+            client=client,
+            cache=cache,
+        )
+        count = sum(1 for _ in dataset)
+    print(f"warmed {count} samples into the cache for {args.dataset!r}", file=sys.stderr)
+    return 0

datavo_cli/commands/sample.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from datetime import datetime
+
+from ..client_factory import build_client
+from ..render import render_output
+
+
+def _parse_datetime(value: str | None) -> datetime | None:
+    return datetime.fromisoformat(value) if value else None
+
+
+def handle_sample_command(args) -> int:
+    output_format = getattr(args, "format", "plain")
+    with build_client() as client:
+        if args.sample_command == "get":
+            response = client.get_sample(args.sample_id)
+            render_output(response, output_format=output_format)
+            return 0
+        if args.sample_command == "history":
+            response = client.get_sample_history(
+                args.sample_id,
+                key=args.key,
+                as_of=_parse_datetime(args.as_of),
+                producer_id=args.producer_id,
+            )
+            render_output(response, output_format=output_format)
+            return 0
+    raise RuntimeError("Missing sample subcommand.")

datavo_cli/commands/sample_store.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+from datavo_sdk import (
+    CopySamplesToNewStoreRequest,
+    HasKeys,
+    SampleStoreCreateRequest,
+    SampleStoreTransferRequest,
+)
+
+from ..client_factory import build_client
+from ..render import render_output
+
+
+def handle_sample_store_command(args) -> int:
+    output_format = getattr(args, "format", "plain")
+    with build_client() as client:
+        if args.sample_store_command == "create":
+            response = client.create_store(
+                SampleStoreCreateRequest(
+                    name=args.name,
+                    catalog_visibility="hidden" if args.hidden else "visible",
+                    team=getattr(args, "team", None),
+                )
+            )
+            render_output(response, output_format=output_format)
+            return 0
+        if args.sample_store_command == "list":
+            response = client.list_stores(
+                query=args.query,
+                include_archived=args.include_archived,
+                include_hidden=args.include_hidden,
+            )
+            render_output(response, output_format=output_format)
+            return 0
+        if args.sample_store_command == "get":
+            response = client.get_store(args.name)
+            render_output(response, output_format=output_format)
+            return 0
+        if args.sample_store_command == "delete":
+            response = client.delete_store(args.name)
+            render_output(response, output_format=output_format)
+            return 0
+        if args.sample_store_command == "copy":
+            source_filter = None
+            if args.source_store and args.has_keys:
+                source_filter = [HasKeys(args.has_keys)]
+            response = client.copy_samples_to_new_store(
+                CopySamplesToNewStoreRequest(
+                    target_sample_store=args.target,
+                    catalog_visibility="hidden" if args.hidden else "visible",
+                    source_sample_store=args.source_store,
+                    filter=source_filter,
+                    source_dataset=args.source_dataset,
+                    keys=args.keys or None,
+                    limit=args.limit,
+                    randomize=args.randomize,
+                    seed=args.seed,
+                    reason=args.reason,
+                    idempotency_key=args.idempotency_key,
+                )
+            )
+            render_output(response, output_format=output_format)
+            return 0
+        if args.sample_store_command == "transfer":
+            response = client.transfer_store(
+                args.source,
+                SampleStoreTransferRequest(
+                    target_sample_store=args.target,
+                    delete_source_store=not args.keep_source,
+                    reason=args.reason,
+                    created_event_id=args.created_event_id,
+                    idempotency_key=args.idempotency_key,
+                ),
+            )
+            render_output(response, output_format=output_format)
+            return 0
+        if args.sample_store_command == "archive":
+            response = client.archive_store(args.name)
+            render_output(response, output_format=output_format)
+            return 0
+        if args.sample_store_command == "restore":
+            response = client.restore_store(args.name)
+            render_output(response, output_format=output_format)
+            return 0
+        if args.sample_store_command == "operations":
+            if args.operations_command == "list":
+                response = client.list_store_operations(
+                    args.name, offset=args.offset, limit=args.limit, order=args.order
+                )
+                render_output(response, output_format=output_format)
+                return 0
+            if args.operations_command == "remove":
+                response = client.remove_store_operation(args.name, args.op_id)
+                render_output(response, output_format=output_format)
+                return 0
+            raise RuntimeError("Missing sample-store operations subcommand.")
+    raise RuntimeError("Missing sample-store subcommand.")

datavo_cli/commands/source_import.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+import sys
+
+from ..client_factory import build_client
+from ..render import render_output
+
+
+def _resolve_source_import_id(client, args) -> str:
+    if args.source_import_id:
+        return args.source_import_id
+    operation_id = getattr(args, "operation_id", None)
+    source_ref = getattr(args, "source_ref", None)
+    if args.sample_store and operation_id:
+        return client.get_source_import_by_operation_id(args.sample_store, operation_id).source_import_id
+    if args.sample_store and source_ref:
+        # Deprecated spelling: reads both columns, so an import written before the
+        # cutover still resolves by the value its caller sent. The notice goes to stderr —
+        # stdout carries the command's output, which callers parse as JSON.
+        print("--source-ref is deprecated; use --operation-id.", file=sys.stderr)
+        return client.get_source_import_by_source_ref(args.sample_store, source_ref).source_import_id
+    raise RuntimeError("Provide --id, or both --sample-store and --operation-id, to identify the source import.")
+
+
+def handle_source_import_command(args) -> int:
+    output_format = getattr(args, "format", "plain")
+    with build_client() as client:
+        if args.source_import_command == "delete":
+            source_import_id = _resolve_source_import_id(client, args)
+            # Default to a dry run unless --yes is given, so an accidental
+            # invocation reports the blast radius instead of deleting.
+            dry_run = args.dry_run or not args.yes
+            response = client.delete_source_import(source_import_id, dry_run=dry_run)
+            render_output(response, output_format=output_format)
+            if response.dry_run and not args.dry_run:
+                print("\nDry run only — re-run with --yes to actually delete.")
+            return 0
+    raise RuntimeError("Missing source-import subcommand.")

datavo_cli/commands/split_set.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+from datavo_sdk import (
+    DatasetSplitDraftRequest,
+    DatasetSplitSetCreateRequest,
+)
+
+from ..client_factory import build_client
+from ..render import render_output
+from ..utils import load_model
+
+
+def handle_split_set_command(args) -> int:
+    output_format = getattr(args, "format", "plain")
+    with build_client() as client:
+        if args.split_set_command == "preview":
+            response = client.preview_dataset_split_set(
+                args.dataset, load_model(args.spec, DatasetSplitDraftRequest)
+            )
+            render_output(response, output_format=output_format)
+            return 0
+        if args.split_set_command == "create":
+            response = client.create_dataset_split_set(
+                args.dataset, load_model(args.spec, DatasetSplitSetCreateRequest)
+            )
+            render_output(response, output_format=output_format)
+            return 0
+        if args.split_set_command == "get":
+            response = client.get_dataset_split_set(args.dataset, args.split_set)
+            render_output(response, output_format=output_format)
+            return 0
+        if args.split_set_command == "archive":
+            response = client.archive_dataset_split_set(args.dataset, args.split_set)
+            render_output(response, output_format=output_format)
+            return 0
+        if args.split_set_command == "restore":
+            response = client.restore_dataset_split_set(args.dataset, args.split_set)
+            render_output(response, output_format=output_format)
+            return 0
+        if args.split_set_command == "delete":
+            response = client.delete_dataset_split_set(args.dataset, args.split_set)
+            render_output(response, output_format=output_format)
+            return 0
+        if args.split_set_command == "list":
+            response = client.list_dataset_split_sets(
+                args.dataset, include_archived=args.include_archived
+            )
+            render_output(response, output_format=output_format)
+            return 0
+        if args.split_set_command == "splits":
+            response = client.list_dataset_split_sets(
+                args.dataset, include_archived=args.include_archived
+            )
+            if args.split_set is not None and args.split_set not in {item.name for item in response.items}:
+                raise RuntimeError(f"dataset {args.dataset} has no split set {args.split_set}")
+            split_datasets = []
+            for item in response.items:
+                if args.split_set is not None and item.name != args.split_set:
+                    continue
+                for dataset in item.datasets:
+                    split_datasets.append(
+                        {
+                            "split_set": item.name,
+                            "split_name": dataset.split_name,
+                            "dataset_name": dataset.dataset_name,
+                            "sample_count": dataset.sample_count,
+                            "shard_count": dataset.shard_count,
+                        }
+                    )
+            render_output(
+                {
+                    "parent_dataset": response.dataset_name,
+                    "split_set": args.split_set,
+                    "split_datasets": split_datasets,
+                },
+                output_format=output_format,
+            )
+            return 0
+    raise RuntimeError("Missing split-set subcommand.")

datavo_cli/commands/stats.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from datavo_sdk import StatsRebuildRequest
+
+from ..client_factory import build_client
+from ..render import render_output
+
+
+def handle_stats_command(args) -> int:
+    output_format = getattr(args, "format", "plain")
+    with build_client() as client:
+        if args.stats_command == "rebuild":
+            response = client.rebuild_stats(
+                StatsRebuildRequest(
+                    sample_store=args.sample_store,
+                    dataset=args.dataset,
+                    all=bool(args.all),
+                )
+            )
+            render_output(response, output_format=output_format)
+            return 0
+    raise RuntimeError("Missing stats subcommand.")

datavo_cli/commands/team.py

@@ -0,0 +1,191 @@
+"""``datavo teams``, ``datavo share`` / ``unshare``, and ``datavo transfer``.
+
+Three things here are deliberate rather than incidental:
+
+**Transfer refuses locally.** ``datavo transfer`` will not send the request without an
+acknowledgement — it prints the cascade set first, then requires either
+``--yes-i-understand-this-is-irreversible`` or a typed confirmation of the resource name.
+Letting the server 400 would technically work, but the point of the acknowledgement is
+that the person typing the command has seen what it moves; a round trip that fails is not
+the same as a prompt that informs.
+
+**Capability check before send.** The team endpoints do not exist on an older server, so
+without a check the command dies on a bare 404 from a path that was never there. Reading
+``/config`` first turns version skew into a sentence.
+
+**Sharing is spelled share/unshare, ownership is spelled transfer.** They are different
+verbs on purpose: one is reversible, the other is not.
+"""
+
+from __future__ import annotations
+
+from datavo_sdk import TeamCreateRequest, TeamUpdateRequest
+
+from ..client_factory import build_client
+from ..render import render_output
+
+_CAPABILITY = "teams-and-sharing"
+
+# `datavo share store NAME`, `... dataset NAME`, `... split-set NAME --dataset PARENT`.
+_RESOURCE_KINDS = {
+    "store": "sample_store",
+    "dataset": "dataset",
+    "split-set": "split_set",
+}
+
+
+def _require_teams_capability(client) -> None:
+    """Refuse up front when the server predates this capability.
+
+    A missing route answers 404, which reads as "no such store" rather than "this server
+    is older than your CLI" — so the check happens here, once, before any command sends.
+    """
+    try:
+        config = client.get_public_config()
+    except Exception:
+        # If /config itself is unreachable the command's own error is the better message.
+        return
+    capabilities = list(getattr(config, "capabilities", None) or [])
+    if _CAPABILITY in capabilities:
+        return
+    raise RuntimeError(
+        f"this server does not support teams and sharing (missing the {_CAPABILITY!r} "
+        f"capability; server version {getattr(config, 'release_version', 'unknown')}). "
+        "Upgrade the server, or use a CLI matching it."
+    )
+
+
+def _resource_target(args) -> tuple[str, str, str | None]:
+    """``(resource_kind, name, parent)`` from the shared positional shape."""
+    kind = _RESOURCE_KINDS.get(args.resource)
+    if kind is None:
+        raise RuntimeError(
+            f"unknown resource {args.resource!r}; expected one of {', '.join(_RESOURCE_KINDS)}"
+        )
+    parent = getattr(args, "dataset", None)
+    if kind == "split_set" and not parent:
+        raise RuntimeError("a split set is addressed under its parent dataset: pass --dataset")
+    return kind, args.name, parent
+
+
+def handle_teams_command(args) -> int:
+    output_format = getattr(args, "format", "plain")
+    with build_client() as client:
+        _require_teams_capability(client)
+        command = args.teams_command
+        if command == "list":
+            render_output(
+                client.list_teams(include_archived=args.include_archived),
+                output_format=output_format,
+            )
+            return 0
+        if command == "show":
+            render_output(client.get_team(args.team), output_format=output_format)
+            return 0
+        if command == "create":
+            request = TeamCreateRequest(id=args.team, display_name=args.display_name)
+            render_output(client.create_team(request), output_format=output_format)
+            return 0
+        if command == "rename":
+            request = TeamUpdateRequest(display_name=args.display_name)
+            render_output(client.rename_team(args.team, request), output_format=output_format)
+            return 0
+        if command == "archive":
+            render_output(client.archive_team(args.team), output_format=output_format)
+            return 0
+        if command == "members":
+            if args.members_command == "add":
+                render_output(
+                    client.add_team_member(args.team, args.user),
+                    output_format=output_format,
+                )
+                return 0
+            if args.members_command == "remove":
+                render_output(
+                    client.remove_team_member(args.team, args.user),
+                    output_format=output_format,
+                )
+                return 0
+            raise RuntimeError(f"unknown members subcommand: {args.members_command}")
+        raise RuntimeError(f"unknown teams subcommand: {command}")
+
+
+def handle_share_command(args) -> int:
+    output_format = getattr(args, "format", "plain")
+    with build_client() as client:
+        _require_teams_capability(client)
+        kind, name, parent = _resource_target(args)
+        if getattr(args, "list", False):
+            render_output(
+                client.list_resource_grants(kind, name, parent=parent),
+                output_format=output_format,
+            )
+            return 0
+        response = client.grant_resource_access(
+            kind, name, team=args.to, level=args.level, parent=parent
+        )
+        render_output(response, output_format=output_format)
+        return 0
+
+
+def handle_unshare_command(args) -> int:
+    output_format = getattr(args, "format", "plain")
+    with build_client() as client:
+        _require_teams_capability(client)
+        kind, name, parent = _resource_target(args)
+        response = client.revoke_resource_access(kind, name, team=args.to, parent=parent)
+        render_output(response, output_format=output_format)
+        return 0
+
+
+def handle_transfer_command(args) -> int:
+    """Hand a resource to another team, after showing what moves and confirming."""
+    output_format = getattr(args, "format", "plain")
+    with build_client() as client:
+        _require_teams_capability(client)
+        kind, name, parent = _resource_target(args)
+
+        preview = client.preview_resource_ownership_transfer(kind, name, parent=parent)
+        _print_transfer_preview(preview, destination=args.to)
+        if not _transfer_acknowledged(args, name=name):
+            # Refused locally rather than sent and 400'd: the acknowledgement exists so the
+            # person running this has seen the cascade, and a failed round trip does not
+            # achieve that.
+            print(
+                "Refusing to transfer without acknowledgement. Re-run with "
+                "--yes-i-understand-this-is-irreversible, or confirm the resource name "
+                "when prompted."
+            )
+            return 1
+
+        response = client.transfer_resource_ownership(
+            kind, name, team=args.to, acknowledge_irreversible=True, parent=parent
+        )
+        render_output(response, output_format=output_format)
+        return 0
+
+
+def _print_transfer_preview(preview, *, destination: str) -> None:
+    moving = list(getattr(preview, "would_transfer", None) or [])
+    current = getattr(preview, "owner_team_id", None)
+    print(f"Transfer to team: {destination}")
+    print(f"Current owning team: {current or '(none)'}")
+    print(f"Resources that will move ({len(moving)}):")
+    for entry in moving:
+        label = entry.name or entry.resource_id
+        print(f"  - {entry.resource_kind} {label}")
+    print(
+        "\nThis is irreversible. The current owning team keeps NOTHING — no ownership and "
+        "no grant. Only the destination team can grant access back."
+    )
+
+
+def _transfer_acknowledged(args, *, name: str) -> bool:
+    if getattr(args, "yes_i_understand_this_is_irreversible", False):
+        return True
+    try:
+        typed = input(f"Type the resource name ({name}) to confirm: ").strip()
+    except (EOFError, KeyboardInterrupt):
+        print()
+        return False
+    return typed == name

datavo_cli/commands/user.py

@@ -0,0 +1,67 @@
+"""``datavo users`` — the admin surface over who exists and the role each holds.
+
+Two things mirror ``datavo teams``:
+
+**Capability check before send.** The user routes do not exist on an older server, so
+without a check the command dies on a bare 404 from a path that was never there. Reading
+``/config`` first turns version skew into a sentence.
+
+**A role is an override.** ``set-role`` replaces the Entra baseline everywhere, not only
+here; ``clear-role`` returns the user to their directory role. The server refuses an
+admin's attempt to remove their own admin (self-demotion) with a 409 — surfaced as the
+request error rather than second-guessed locally, because unlike a transfer a role change
+is reversible.
+"""
+
+from __future__ import annotations
+
+from ..client_factory import build_client
+from ..render import render_output
+
+_CAPABILITY = "user-management"
+
+
+def _require_users_capability(client) -> None:
+    """Refuse up front when the server predates this capability.
+
+    A missing route answers 404, which reads as "no such user" rather than "this server
+    is older than your CLI" — so the check happens here, once, before any command sends.
+    """
+    try:
+        config = client.get_public_config()
+    except Exception:
+        # If /config itself is unreachable the command's own error is the better message.
+        return
+    capabilities = list(getattr(config, "capabilities", None) or [])
+    if _CAPABILITY in capabilities:
+        return
+    raise RuntimeError(
+        f"this server does not support user management (missing the {_CAPABILITY!r} "
+        f"capability; server version {getattr(config, 'release_version', 'unknown')}). "
+        "Upgrade the server, or use a CLI matching it."
+    )
+
+
+def handle_users_command(args) -> int:
+    output_format = getattr(args, "format", "plain")
+    with build_client() as client:
+        _require_users_capability(client)
+        command = args.users_command
+        if command == "list":
+            render_output(
+                client.list_users(query=args.query, offset=args.offset, limit=args.limit),
+                output_format=output_format,
+            )
+            return 0
+        if command == "show":
+            render_output(client.get_user(args.user), output_format=output_format)
+            return 0
+        if command == "set-role":
+            render_output(
+                client.set_user_role(args.user, args.role), output_format=output_format
+            )
+            return 0
+        if command == "clear-role":
+            render_output(client.clear_user_role(args.user), output_format=output_format)
+            return 0
+        raise RuntimeError(f"unknown users subcommand: {command}")