datavo-cli 0.22.0__py3-none-any.whl

datavo_cli/parsers.py

@@ -0,0 +1,411 @@
+from __future__ import annotations
+
+import argparse
+
+
+def _add_format_argument(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--format", choices=("plain", "json"), default="plain", help="output format")
+
+
+def _add_key_group_argument(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--key-group", action="append", dest="key_groups", help="repeatable key group selector")
+
+
+def build_root_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Datavo CLI", formatter_class=argparse.RawTextHelpFormatter)
+    parser.add_argument(
+        "--verbose",
+        "-v",
+        action="store_true",
+        help="show full error detail (raw response body) — also via DATAVO_VERBOSE=1",
+    )
+    subparsers = parser.add_subparsers(dest="command")
+
+    config = subparsers.add_parser("config", help="manage CLI profiles")
+    config_sub = config.add_subparsers(dest="config_command")
+    config_show = config_sub.add_parser("show", help="show the active or selected profile")
+    config_show.add_argument("profile", nargs="?", help="optional profile name")
+    _add_format_argument(config_show)
+    config_list = config_sub.add_parser("list", help="list profiles")
+    _add_format_argument(config_list)
+    config_use = config_sub.add_parser("use", help="set the active profile")
+    config_use.add_argument("profile", help="profile name")
+    _add_format_argument(config_use)
+    config_set = config_sub.add_parser("set", help="create or update a profile")
+    config_set.add_argument("profile", nargs="?", help="profile name (defaults to the URL hostname)")
+    config_set.add_argument("--url", required=True, help="Datavo API base URL")
+    _add_format_argument(config_set)
+    config_remove = config_sub.add_parser("remove", help="remove a profile")
+    config_remove.add_argument("profile", help="profile name")
+    _add_format_argument(config_remove)
+
+    auth = subparsers.add_parser("auth", help="manage authentication")
+    auth_sub = auth.add_subparsers(dest="auth_command")
+    auth_login = auth_sub.add_parser("login", help="log in")
+    auth_login.add_argument("--token", help="store a bearer token directly")
+    auth_login.add_argument("--msal", action="store_true", help="log in via MSAL (interactive browser by default; set DATAVO_MSAL_DEVICE_FLOW=1 to use device code)")
+    auth_login.add_argument("--msal-browser", action="store_true", help="force MSAL interactive browser flow (no device-code fallback)")
+    auth_login.add_argument("--tenant-id", help="Entra tenant id override")
+    auth_login.add_argument("--client-id", help="Entra public client id override")
+    auth_login.add_argument("--scope", action="append", help="repeatable MSAL scope override")
+    _add_format_argument(auth_login)
+    auth_status = auth_sub.add_parser("status", help="show current auth state")
+    _add_format_argument(auth_status)
+    auth_logout = auth_sub.add_parser("logout", help="clear the stored token and MSAL cache")
+    _add_format_argument(auth_logout)
+
+    sample_store = subparsers.add_parser("sample-store", help="manage sample stores")
+    sample_store_sub = sample_store.add_subparsers(dest="sample_store_command")
+    sample_store_create = sample_store_sub.add_parser("create", help="create a sample store")
+    sample_store_create.add_argument("name", help="sample store name")
+    sample_store_create.add_argument("--hidden", action="store_true", help="hide from default catalog lists")
+    sample_store_create.add_argument(
+        "--team", help="owning team (default: your default team)"
+    )
+    _add_format_argument(sample_store_create)
+    sample_store_list = sample_store_sub.add_parser("list", help="list sample stores")
+    sample_store_list.add_argument("--query", "-q", help="name search")
+    sample_store_list.add_argument("--include-archived", action="store_true", help="include archived stores")
+    sample_store_list.add_argument("--include-hidden", action="store_true", help="include hidden stores")
+    _add_format_argument(sample_store_list)
+    sample_store_get = sample_store_sub.add_parser("get", help="get sample store details")
+    sample_store_get.add_argument("name", help="sample store name")
+    _add_format_argument(sample_store_get)
+    sample_store_delete = sample_store_sub.add_parser("delete", help="delete a sample store")
+    sample_store_delete.add_argument("name", help="sample store name")
+    _add_format_argument(sample_store_delete)
+    sample_store_transfer = sample_store_sub.add_parser("transfer", help="transfer a whole sample store")
+    sample_store_transfer.add_argument("source", help="source sample store name")
+    sample_store_transfer.add_argument("--target", required=True, help="target sample store name")
+    sample_store_transfer.add_argument("--keep-source", action="store_true", help="leave the emptied source store in place")
+    sample_store_transfer.add_argument("--reason", help="transfer reason")
+    sample_store_transfer.add_argument("--event-id", dest="created_event_id", help="existing event to link")
+    sample_store_transfer.add_argument("--idempotency-key", help="idempotency key")
+    _add_format_argument(sample_store_transfer)
+
+    sample_store_copy = sample_store_sub.add_parser(
+        "copy",
+        help="copy a bounded set of samples into a brand-new store (quick tests / seeding)",
+    )
+    sample_store_copy.add_argument("target", help="new sample store name (must not exist)")
+    copy_source = sample_store_copy.add_mutually_exclusive_group(required=True)
+    copy_source.add_argument("--source-store", help="copy from this sample store")
+    copy_source.add_argument("--source-dataset", help="copy from this dataset (name or id)")
+    sample_store_copy.add_argument(
+        "--has-key",
+        dest="has_keys",
+        action="append",
+        default=[],
+        help="only samples that have this key (repeatable); filters --source-store",
+    )
+    sample_store_copy.add_argument(
+        "--key",
+        dest="keys",
+        action="append",
+        default=[],
+        help="restrict the copy to this key (repeatable); default copies all keys",
+    )
+    sample_store_copy.add_argument("--limit", type=int, required=True, help="max samples to copy")
+    sample_store_copy.add_argument("--randomize", action="store_true", help="take a random subset of the matches")
+    sample_store_copy.add_argument("--seed", type=int, default=0, help="seed for --randomize (repeatable picks)")
+    sample_store_copy.add_argument("--hidden", action="store_true", help="hide the new store from default catalog lists")
+    sample_store_copy.add_argument("--reason", help="copy reason")
+    sample_store_copy.add_argument("--idempotency-key", help="idempotency key")
+    _add_format_argument(sample_store_copy)
+
+    sample_store_archive = sample_store_sub.add_parser("archive", help="archive a sample store (required before delete)")
+    sample_store_archive.add_argument("name", help="sample store name")
+    _add_format_argument(sample_store_archive)
+    sample_store_restore = sample_store_sub.add_parser("restore", help="restore an archived sample store")
+    sample_store_restore.add_argument("name", help="sample store name")
+    _add_format_argument(sample_store_restore)
+    sample_store_operations = sample_store_sub.add_parser("operations", help="inspect and revert the store operation log")
+    operations_sub = sample_store_operations.add_subparsers(dest="operations_command")
+    operations_list = operations_sub.add_parser("list", help="list the store's operation log (oldest first)")
+    operations_list.add_argument("name", help="sample store name")
+    # The log is unbounded — one entry per grow or attach — so it can be paged. The
+    # defaults stay the whole log, oldest-first, which is what the guide teaches.
+    operations_list.add_argument("--offset", type=int, default=0, help="skip this many operations")
+    operations_list.add_argument(
+        "--limit", type=int, default=None, help="return at most this many (default: the whole log)"
+    )
+    operations_list.add_argument(
+        "--order",
+        choices=("oldest", "newest"),
+        default="oldest",
+        help="oldest first (default), or newest first to read what happened last",
+    )
+    _add_format_argument(operations_list)
+    operations_remove = operations_sub.add_parser("remove", help="remove/revert one operation by id")
+    operations_remove.add_argument("name", help="sample store name")
+    operations_remove.add_argument("op_id", help="operation id (from `operations list`)")
+    _add_format_argument(operations_remove)
+
+    source_import = subparsers.add_parser("source-import", help="manage source imports (admin surgery)")
+    source_import_sub = source_import.add_subparsers(dest="source_import_command")
+    source_import_delete = source_import_sub.add_parser(
+        "delete",
+        help="delete a single committed source import and all samples it owns",
+    )
+    source_import_delete.add_argument("--id", dest="source_import_id", help="source import id")
+    source_import_delete.add_argument(
+        "--sample-store", help="sample store (with --operation-id) to resolve the import"
+    )
+    source_import_delete.add_argument(
+        "--operation-id",
+        help="the import's operation id (with --sample-store) to resolve the import",
+    )
+    source_import_delete.add_argument(
+        "--source-ref",
+        help="deprecated spelling of --operation-id",
+    )
+    source_import_delete.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="report what would be deleted without deleting anything",
+    )
+    source_import_delete.add_argument(
+        "--yes",
+        action="store_true",
+        help="actually delete (without this the command only does a dry run)",
+    )
+    _add_format_argument(source_import_delete)
+
+    sample = subparsers.add_parser("sample", help="inspect samples")
+    sample_sub = sample.add_subparsers(dest="sample_command")
+    sample_get = sample_sub.add_parser("get", help="get sample details and available keys")
+    sample_get.add_argument("sample_id", help="sample id")
+    _add_format_argument(sample_get)
+    sample_history = sample_sub.add_parser("history", help="show sample key revision history")
+    sample_history.add_argument("sample_id", help="sample id")
+    sample_history.add_argument("--key", help="optional key filter")
+    sample_history.add_argument("--as-of", dest="as_of", help="resolve history at or before this ISO timestamp")
+    sample_history.add_argument("--producer-id", help="optional producer filter")
+    _add_format_argument(sample_history)
+
+    events = subparsers.add_parser("events", help="manage Datavo events")
+    events_sub = events.add_subparsers(dest="events_command")
+    events_create = events_sub.add_parser("create", help="create an event")
+    events_create.add_argument("--type", dest="event_type", required=True, help="event type")
+    events_create.add_argument("--source", default="external", help="event source")
+    events_create.add_argument("--jobpool-run-id", help="JobPool run id")
+    events_create.add_argument("--idempotency-key", help="idempotency key")
+    events_create.add_argument("--param", action="append", default=[], help="event param as key=value")
+    _add_format_argument(events_create)
+    events_list = events_sub.add_parser("list", help="list events")
+    events_list.add_argument("--type", dest="event_type", help="event type filter")
+    events_list.add_argument("--param", action="append", default=[], help="param filter as key=value")
+    _add_format_argument(events_list)
+    events_get = events_sub.add_parser("get", help="get one event")
+    events_get.add_argument("event_id", help="event id")
+    _add_format_argument(events_get)
+
+    stats = subparsers.add_parser("stats", help="manage persisted statistics")
+    stats_sub = stats.add_subparsers(dest="stats_command")
+    stats_rebuild = stats_sub.add_parser("rebuild", help="rebuild persisted stats projections")
+    stats_scope = stats_rebuild.add_mutually_exclusive_group(required=True)
+    stats_scope.add_argument("--sample-store", help="rebuild one sample store")
+
+    # ---- teams and sharing -------------------------------------------------
+    teams = subparsers.add_parser("teams", help="manage teams and your default team")
+    teams_sub = teams.add_subparsers(dest="teams_command")
+    teams_list = teams_sub.add_parser("list", help="list teams")
+    teams_list.add_argument("--include-archived", action="store_true")
+    _add_format_argument(teams_list)
+    teams_show = teams_sub.add_parser("show", help="show one team and its members")
+    teams_show.add_argument("team", help="team slug")
+    _add_format_argument(teams_show)
+    teams_create = teams_sub.add_parser("create", help="create a team (admin)")
+    teams_create.add_argument("team", help="team slug")
+    teams_create.add_argument("--display-name", help="human-readable name")
+    _add_format_argument(teams_create)
+    teams_rename = teams_sub.add_parser("rename", help="rename a team (admin)")
+    teams_rename.add_argument("team", help="team slug")
+    teams_rename.add_argument("--display-name", required=True)
+    _add_format_argument(teams_rename)
+    teams_archive = teams_sub.add_parser(
+        "archive", help="archive a team (admin; refused while it owns resources)"
+    )
+    teams_archive.add_argument("team", help="team slug")
+    _add_format_argument(teams_archive)
+    teams_members = teams_sub.add_parser("members", help="manage membership (admin)")
+    teams_members_sub = teams_members.add_subparsers(dest="members_command")
+    teams_members_add = teams_members_sub.add_parser("add", help="add a member")
+    teams_members_add.add_argument("team", help="team slug")
+    teams_members_add.add_argument("user", help="user id")
+    _add_format_argument(teams_members_add)
+    teams_members_remove = teams_members_sub.add_parser("remove", help="remove a member")
+    teams_members_remove.add_argument("team", help="team slug")
+    teams_members_remove.add_argument("user", help="user id")
+    _add_format_argument(teams_members_remove)
+
+    def _add_resource_target(sub) -> None:
+        sub.add_argument("resource", choices=["store", "dataset", "split-set"])
+        sub.add_argument("name", help="store name, dataset name, or split-set name")
+        sub.add_argument("--dataset", help="parent dataset (required for split-set)")
+
+    share = subparsers.add_parser("share", help="share a resource with a team")
+    _add_resource_target(share)
+    share.add_argument("--to", help="team slug to share with")
+    share.add_argument("--level", choices=["read", "write"], default="read")
+    share.add_argument("--list", action="store_true", help="show current grants instead")
+    _add_format_argument(share)
+
+    unshare = subparsers.add_parser("unshare", help="revoke a team's access to a resource")
+    _add_resource_target(unshare)
+    unshare.add_argument("--to", required=True, help="team slug to revoke")
+    _add_format_argument(unshare)
+
+    transfer = subparsers.add_parser(
+        "transfer",
+        help="hand ownership to another team — IRREVERSIBLE, the current team keeps nothing",
+    )
+    _add_resource_target(transfer)
+    transfer.add_argument("--to", required=True, help="destination team slug")
+    transfer.add_argument(
+        "--yes-i-understand-this-is-irreversible",
+        action="store_true",
+        help="skip the typed confirmation; the transfer still cannot be undone",
+    )
+    _add_format_argument(transfer)
+
+    # ---- user management ---------------------------------------------------
+    users = subparsers.add_parser("users", help="manage users and their role overrides (admin)")
+    users_sub = users.add_subparsers(dest="users_command")
+    users_list = users_sub.add_parser(
+        "list", help="list users with their baseline and effective role"
+    )
+    users_list.add_argument("--query", help="filter by name or address")
+    users_list.add_argument("--offset", type=int, default=0)
+    users_list.add_argument("--limit", type=int, default=100)
+    _add_format_argument(users_list)
+    users_show = users_sub.add_parser("show", help="show one user")
+    users_show.add_argument("user", help="user id")
+    _add_format_argument(users_show)
+    users_set_role = users_sub.add_parser("set-role", help="set a user's role override (admin)")
+    users_set_role.add_argument("user", help="user id")
+    users_set_role.add_argument(
+        "role", choices=["reader", "contributor", "sample_store_manager", "admin"]
+    )
+    _add_format_argument(users_set_role)
+    users_clear_role = users_sub.add_parser(
+        "clear-role", help="clear a user's override, back to the Entra baseline (admin)"
+    )
+    users_clear_role.add_argument("user", help="user id")
+    _add_format_argument(users_clear_role)
+
+    stats_scope.add_argument("--dataset", help="rebuild one dataset")
+    stats_scope.add_argument("--all", action="store_true", help="rebuild every sample store and dataset")
+    _add_format_argument(stats_rebuild)
+
+    dataset = subparsers.add_parser("dataset", help="manage datasets")
+    dataset_sub = dataset.add_subparsers(dest="dataset_command")
+    dataset_preview = dataset_sub.add_parser("preview", help="preview a dataset spec")
+    dataset_preview.add_argument("--spec", required=True, help="YAML or JSON request file, or - for stdin")
+    _add_format_argument(dataset_preview)
+    dataset_create = dataset_sub.add_parser("create", help="create a dataset")
+    dataset_create.add_argument("--spec", required=True, help="YAML or JSON request file, or - for stdin")
+    dataset_create.add_argument(
+        "--wait",
+        action="store_true",
+        help="poll until the dataset is materialized (ready) instead of returning the planning response",
+    )
+    _add_format_argument(dataset_create)
+    dataset_list = dataset_sub.add_parser("list", help="list datasets")
+    dataset_list.add_argument("--query", "-q", help="name search")
+    dataset_list.add_argument("--key", action="append", dest="keys", help="only datasets containing this key; repeatable (AND)")
+    dataset_list.add_argument("--include-archived", action="store_true", help="include archived datasets")
+    dataset_list.add_argument("--include-split-children", action="store_true", help="include split-set-generated datasets")
+    dataset_list.add_argument("--offset", type=int, default=0, help="pagination offset")
+    dataset_list.add_argument("--limit", type=int, default=20, help="max datasets to return")
+    _add_format_argument(dataset_list)
+    dataset_get = dataset_sub.add_parser("get", help="get dataset details")
+    dataset_get.add_argument("name", help="dataset name")
+    _add_format_argument(dataset_get)
+    dataset_archive = dataset_sub.add_parser("archive", help="archive a dataset (required before delete)")
+    dataset_archive.add_argument("name", help="dataset name")
+    _add_format_argument(dataset_archive)
+    dataset_restore = dataset_sub.add_parser("restore", help="restore an archived dataset")
+    dataset_restore.add_argument("name", help="dataset name")
+    _add_format_argument(dataset_restore)
+    dataset_delete = dataset_sub.add_parser("delete", help="delete an archived dataset")
+    dataset_delete.add_argument("name", help="dataset name")
+    _add_format_argument(dataset_delete)
+    dataset_add_key_group = dataset_sub.add_parser("add-key-group", help="add a key group to a dataset")
+    dataset_add_key_group.add_argument("name", help="dataset name")
+    dataset_add_key_group.add_argument("--spec", required=True, help="YAML or JSON request file, or - for stdin")
+    _add_format_argument(dataset_add_key_group)
+    dataset_pull = dataset_sub.add_parser("pull", help="download dataset shard tars")
+    dataset_pull.add_argument("name", help="dataset name")
+    dataset_pull.add_argument("--output-dir", required=True, help="local directory for downloaded shards")
+    dataset_pull.add_argument("--overwrite", action="store_true", help="overwrite existing files")
+    _add_key_group_argument(dataset_pull)
+    _add_format_argument(dataset_pull)
+
+    split_set = subparsers.add_parser("split-set", help="manage dataset train/validation/test split sets")
+    split_set_sub = split_set.add_subparsers(dest="split_set_command")
+    split_set_preview = split_set_sub.add_parser("preview", help="preview a split-set spec (no writes)")
+    split_set_preview.add_argument("dataset", help="parent dataset name")
+    split_set_preview.add_argument("--spec", required=True, help="YAML or JSON request file, or - for stdin")
+    _add_format_argument(split_set_preview)
+    split_set_create = split_set_sub.add_parser("create", help="create a split set from a spec")
+    split_set_create.add_argument("dataset", help="parent dataset name")
+    split_set_create.add_argument("--spec", required=True, help="YAML or JSON request file, or - for stdin")
+    _add_format_argument(split_set_create)
+    split_set_list = split_set_sub.add_parser("list", help="list split sets under a parent dataset")
+    split_set_list.add_argument("dataset", help="parent dataset name")
+    split_set_list.add_argument("--include-archived", action="store_true", help="include archived split sets")
+    _add_format_argument(split_set_list)
+    split_set_splits = split_set_sub.add_parser("splits", help="list the datasets generated by split sets")
+    split_set_splits.add_argument("dataset", help="parent dataset name")
+    split_set_splits.add_argument("--split-set", help="only show one split set's generated datasets")
+    split_set_splits.add_argument("--include-archived", action="store_true", help="include archived split sets")
+    _add_format_argument(split_set_splits)
+    split_set_get = split_set_sub.add_parser("get", help="get one split set's details")
+    split_set_get.add_argument("dataset", help="parent dataset name")
+    split_set_get.add_argument("split_set", help="split set name")
+    _add_format_argument(split_set_get)
+    split_set_archive = split_set_sub.add_parser("archive", help="archive a split set (required before delete)")
+    split_set_archive.add_argument("dataset", help="parent dataset name")
+    split_set_archive.add_argument("split_set", help="split set name")
+    _add_format_argument(split_set_archive)
+    split_set_restore = split_set_sub.add_parser("restore", help="restore an archived split set")
+    split_set_restore.add_argument("dataset", help="parent dataset name")
+    split_set_restore.add_argument("split_set", help="split set name")
+    _add_format_argument(split_set_restore)
+    split_set_delete = split_set_sub.add_parser("delete", help="delete an archived split set")
+    split_set_delete.add_argument("dataset", help="parent dataset name")
+    split_set_delete.add_argument("split_set", help="split set name")
+    _add_format_argument(split_set_delete)
+
+    render_cache = subparsers.add_parser(
+        "render-dataset-cache",
+        help="render the datavo adapters block (name + config) for a JobPool worker spec",
+    )
+    render_cache.add_argument("--disk", required=True, help="worker disk name backing the cache")
+    render_cache.add_argument("--host-path", required=True, help="host path of the cache disk")
+    render_cache.add_argument("--mount", required=True, help="in-container mount path of the cache disk")
+    render_cache.add_argument(
+        "--tier",
+        action="append",
+        dest="tiers",
+        required=True,
+        metavar="TYPE[,max_bytes][,name]",
+        help="cache tier, fastest-first; repeat for multiple (e.g. folder,32GB,local)",
+    )
+    render_cache.add_argument(
+        "--token-alias",
+        default="datavo_token",
+        help="accepted for backward compatibility; no longer emitted into the spec "
+        "(the adapter resolves the alias at runtime via DATAVO_TOKEN_ALIAS/default)",
+    )
+
+    warm = subparsers.add_parser("warm", help="pre-populate a cache tier for a dataset/selection")
+    warm.add_argument("dataset", help="dataset or split name to warm")
+    warm.add_argument("--key", action="append", dest="keys", help="key to warm; repeat for multiple")
+    warm.add_argument("--cache-config", help="path to a shards.yaml cache config (else the default)")
+
+    version = subparsers.add_parser("version", help="print version information")
+    _add_format_argument(version)
+
+    return parser