datumhub-cli 0.1.0__py3-none-any.whl

datum/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

datum/commands/cache.py

@@ -0,0 +1,188 @@
+"""datum cache — manage the local dataset cache."""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+from typing import List, NamedTuple
+
+import typer
+from rich import box
+from rich.table import Table
+
+from datum.console import console, err_console
+from datum.state import OutputFormat, state
+
+cache_app = typer.Typer(help="Manage the local dataset cache.")
+
+
+def get_cache_root() -> Path:
+    return Path("~/.datum/cache").expanduser()
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+class CacheEntry(NamedTuple):
+    dataset_id: str   # publisher.namespace.dataset
+    version: str
+    files: List[Path]
+
+    @property
+    def size(self) -> int:
+        return sum(f.stat().st_size for f in self.files)
+
+
+def _scan_cache(root: Path) -> List[CacheEntry]:
+    """Walk cache root and return one entry per dataset version."""
+    entries: List[CacheEntry] = []
+    if not root.exists():
+        return entries
+    for pub_dir in sorted(root.iterdir()):
+        if not pub_dir.is_dir():
+            continue
+        for ns_dir in sorted(pub_dir.iterdir()):
+            if not ns_dir.is_dir():
+                continue
+            for ds_dir in sorted(ns_dir.iterdir()):
+                if not ds_dir.is_dir():
+                    continue
+                for ver_dir in sorted(ds_dir.iterdir()):
+                    if not ver_dir.is_dir():
+                        continue
+                    files = [f for f in ver_dir.iterdir() if f.is_file()]
+                    dataset_id = f"{pub_dir.name}.{ns_dir.name}.{ds_dir.name}"
+                    entries.append(CacheEntry(dataset_id, ver_dir.name, files))
+    return entries
+
+
+def _fmt_size(n: int) -> str:
+    for unit in ("B", "KB", "MB", "GB"):
+        if n < 1024:
+            return f"{n} {unit}" if unit == "B" else f"{n:.1f} {unit}"
+        n /= 1024
+    return f"{n:.1f} TB"
+
+
+# ---------------------------------------------------------------------------
+# Subcommands
+# ---------------------------------------------------------------------------
+
+
+@cache_app.command("list")
+def cache_list() -> None:
+    """List all cached datasets."""
+    output_fmt = state.output
+    quiet = state.quiet
+
+    entries = _scan_cache(get_cache_root())
+
+    if output_fmt == OutputFormat.json:
+        import json
+        payload = [
+            {
+                "id": e.dataset_id,
+                "version": e.version,
+                "files": [str(f) for f in e.files],
+                "size": e.size,
+            }
+            for e in entries
+        ]
+        print(json.dumps(payload, indent=2))
+        return
+
+    if quiet:
+        return
+
+    if not entries:
+        console.print()
+        console.print("  [muted]Cache is empty.[/muted]")
+        console.print(f"  [muted]{get_cache_root()}[/muted]")
+        console.print()
+        return
+
+    total_size = sum(e.size for e in entries)
+    total_files = sum(len(e.files) for e in entries)
+
+    console.print()
+    console.print(
+        f"  [bold]{len(entries)}[/bold] cached version(s)  "
+        f"[muted]·[/muted]  {_fmt_size(total_size)}  "
+        f"[muted]·[/muted]  {get_cache_root()}\n"
+    )
+
+    table = Table(box=box.SIMPLE, show_header=True, header_style="bold white")
+    table.add_column("Dataset", style="identifier", min_width=30)
+    table.add_column("Version", min_width=9)
+    table.add_column("Files", justify="right", min_width=5)
+    table.add_column("Size", justify="right", min_width=8)
+
+    for entry in entries:
+        table.add_row(
+            entry.dataset_id,
+            entry.version,
+            str(len(entry.files)),
+            _fmt_size(entry.size),
+        )
+
+    console.print(table)
+    console.print()
+
+
+@cache_app.command("size")
+def cache_size() -> None:
+    """Show total disk usage of the local cache."""
+    output_fmt = state.output
+    quiet = state.quiet
+
+    entries = _scan_cache(get_cache_root())
+    total_size = sum(e.size for e in entries)
+    total_files = sum(len(e.files) for e in entries)
+
+    if output_fmt == OutputFormat.json:
+        import json
+        print(json.dumps({"size_bytes": total_size, "files": total_files}, indent=2))
+        return
+
+    if quiet:
+        return
+
+    console.print()
+    console.print(f"  [bold]Cache:[/bold]  {get_cache_root()}")
+    console.print(f"  [bold]Total:[/bold]  {_fmt_size(total_size)}  [muted]({total_files} file(s))[/muted]")
+    console.print()
+
+
+@cache_app.command("clear")
+def cache_clear(
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt"),
+) -> None:
+    """Remove all cached datasets."""
+    root = get_cache_root()
+    entries = _scan_cache(root)
+
+    if not entries:
+        console.print()
+        console.print("  [muted]Cache is already empty.[/muted]")
+        console.print()
+        return
+
+    total_size = sum(e.size for e in entries)
+    total_files = sum(len(e.files) for e in entries)
+
+    if not yes:
+        confirmed = typer.confirm(
+            f"  Clear {_fmt_size(total_size)} ({total_files} file(s)) from cache?",
+            default=False,
+        )
+        if not confirmed:
+            console.print("  [muted]Aborted.[/muted]")
+            return
+
+    shutil.rmtree(root, ignore_errors=True)
+
+    console.print()
+    console.print(f"  [success]✓[/success] Cache cleared  [muted]({_fmt_size(total_size)} freed)[/muted]")
+    console.print()

datum/commands/check.py

@@ -0,0 +1,233 @@
+"""datum check — validate a datapackage.json file."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+import typer
+from pydantic import ValidationError
+from rich.panel import Panel
+from rich.table import Table
+
+from datum.console import console, err_console
+from datum.models import DataPackage
+from datum.state import OutputFormat, state
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _pydantic_errors(exc: ValidationError) -> list[dict[str, str]]:
+    """Flatten Pydantic v2 errors into simple field/message dicts."""
+    out: list[dict[str, str]] = []
+    for err in exc.errors():
+        loc_parts = []
+        for part in err["loc"]:
+            if isinstance(part, int):
+                loc_parts.append(f"[{part}]")
+            else:
+                loc_parts.append(str(part))
+        field = ".".join(loc_parts).replace(".[", "[")
+        out.append({"field": field, "message": err["msg"]})
+    return out
+
+
+# ---------------------------------------------------------------------------
+# Command
+# ---------------------------------------------------------------------------
+
+
+def cmd_check(
+    file: Path = typer.Argument(
+        Path("datapackage.json"),
+        help="Path to the datapackage.json to validate",
+        show_default=True,
+    ),
+) -> None:
+    """
+    Validate a datapackage.json file.
+
+    Checks that the file exists, is valid JSON, and conforms to the
+    Datum datapackage schema. Exits with code 0 on success, 1 on
+    validation errors, and 2 on file or parse errors.
+
+    Use [bold]--output json[/bold] for machine-readable output:
+
+        datum check --output json | jq .
+    """
+    output_fmt = state.output
+    quiet = state.quiet
+
+    # -----------------------------------------------------------------------
+    # 1. File existence
+    # -----------------------------------------------------------------------
+    if not file.exists():
+        if output_fmt == OutputFormat.json:
+            _emit_json(
+                valid=False,
+                file=str(file),
+                errors=[{"field": "file", "message": f"File not found: {file}"}],
+            )
+        else:
+            err_console.print(
+                f"\n[error]✗[/error] File not found: [bold]{file}[/bold]\n\n"
+                "Run [bold]datum init[/bold] to create a datapackage.json, "
+                "or pass a path: [bold]datum check path/to/datapackage.json[/bold]"
+            )
+        raise typer.Exit(code=2)
+
+    # -----------------------------------------------------------------------
+    # 2. JSON parse
+    # -----------------------------------------------------------------------
+    try:
+        raw: dict[str, Any] = json.loads(file.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        if output_fmt == OutputFormat.json:
+            _emit_json(
+                valid=False,
+                file=str(file),
+                errors=[{"field": "json", "message": f"Invalid JSON: {exc}"}],
+            )
+        else:
+            err_console.print(
+                f"\n[error]✗[/error] [bold]{file}[/bold] is not valid JSON.\n\n"
+                f"  {exc}\n"
+            )
+        raise typer.Exit(code=2)
+
+    # -----------------------------------------------------------------------
+    # 3. Schema validation
+    # -----------------------------------------------------------------------
+    try:
+        pkg = DataPackage.model_validate(raw)
+    except ValidationError as exc:
+        errors = _pydantic_errors(exc)
+
+        if output_fmt == OutputFormat.json:
+            _emit_json(valid=False, file=str(file), errors=errors)
+        else:
+            _print_failure(file=file, errors=errors, quiet=quiet)
+
+        raise typer.Exit(code=1)
+
+    # -----------------------------------------------------------------------
+    # 4. Success
+    # -----------------------------------------------------------------------
+    if output_fmt == OutputFormat.json:
+        _emit_json(valid=True, file=str(file), errors=[], package=pkg.to_dict())
+    else:
+        _print_success(file=file, pkg=pkg, quiet=quiet)
+
+
+# ---------------------------------------------------------------------------
+# Output renderers
+# ---------------------------------------------------------------------------
+
+
+def _emit_json(
+    *,
+    valid: bool,
+    file: str,
+    errors: list[dict[str, str]],
+    package: dict | None = None,
+) -> None:
+    payload: dict[str, Any] = {
+        "valid": valid,
+        "file": file,
+        "errors": errors,
+    }
+    if package is not None:
+        payload["package"] = package
+    print(json.dumps(payload, indent=2, ensure_ascii=False))
+
+
+def _print_success(file: Path, pkg: DataPackage, quiet: bool) -> None:
+    if quiet:
+        return
+
+    console.print()
+    console.print(
+        Panel(
+            f"[success]✓ Valid[/success]  [muted]·[/muted]  [bold]{file}[/bold]",
+            border_style="green",
+            padding=(0, 2),
+        )
+    )
+
+    # Summary table
+    table = Table(show_header=False, box=None, padding=(0, 2, 0, 0))
+    table.add_column("key", style="key", min_width=14)
+    table.add_column("value")
+
+    table.add_row("Identifier", f"[identifier]{pkg.id}[/identifier]")
+    table.add_row("Version", pkg.version)
+    table.add_row("Title", pkg.title)
+    table.add_row("Publisher", pkg.publisher.name)
+    table.add_row(
+        "Sources",
+        f"{len(pkg.sources)} file(s)  "
+        + "  ".join(
+            f"[muted]{s.format.upper()}[/muted]" for s in pkg.sources
+        ),
+    )
+    if pkg.license:
+        table.add_row("License", pkg.license)
+    if pkg.tags:
+        table.add_row("Tags", ", ".join(pkg.tags))
+
+    # Checksum coverage
+    sources_with_checksum = sum(1 for s in pkg.sources if s.checksum)
+    if sources_with_checksum == 0:
+        table.add_row(
+            "Checksums",
+            "[warning]None — add sha256 checksums to your sources for integrity verification[/warning]",
+        )
+    elif sources_with_checksum < len(pkg.sources):
+        missing = len(pkg.sources) - sources_with_checksum
+        table.add_row(
+            "Checksums",
+            f"[warning]{missing} source(s) missing a checksum[/warning]",
+        )
+    else:
+        table.add_row("Checksums", "[success]✓ All sources have checksums[/success]")
+
+    console.print(table)
+    console.print()
+
+
+def _print_failure(file: Path, errors: list[dict[str, str]], quiet: bool) -> None:
+    n = len(errors)
+
+    if not quiet:
+        console.print()
+        console.print(
+            Panel(
+                f"[error]✗ Invalid[/error]  [muted]·[/muted]  [bold]{file}[/bold]  "
+                f"[muted]·[/muted]  [error]{n} error{'s' if n != 1 else ''}[/error]",
+                border_style="red",
+                padding=(0, 2),
+            )
+        )
+
+    table = Table(show_header=False, box=None, padding=(0, 2, 0, 0))
+    table.add_column("field", style="key", min_width=20)
+    table.add_column("message")
+
+    for err in errors:
+        table.add_row(
+            f"[error]✗[/error] {err['field']}",
+            err["message"],
+        )
+
+    if not quiet:
+        console.print(table)
+        console.print()
+        console.print(
+            "  Fix the errors above and run [bold]datum check[/bold] again."
+        )
+        console.print()

datum/commands/config.py

@@ -0,0 +1,171 @@
+"""datum config — manage local Datum configuration."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Optional
+
+import typer
+from rich import box
+from rich.table import Table
+
+from datum.console import console, err_console
+from datum.state import OutputFormat, state
+
+config_app = typer.Typer(help="Manage local Datum configuration.")
+
+# Keys with descriptions shown in `datum config list`
+KNOWN_KEYS = {
+    "registry": "Default registry URL or local path",
+    "output":   "Default output format  (table | json | plain)",
+}
+
+
+def get_config_path() -> Path:
+    return Path("~/.datum/config.json").expanduser()
+
+
+def load_config() -> dict:
+    p = get_config_path()
+    if not p.exists():
+        return {}
+    try:
+        return json.loads(p.read_text(encoding="utf-8"))
+    except Exception:
+        return {}
+
+
+def save_config(cfg: dict) -> None:
+    p = get_config_path()
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(json.dumps(cfg, indent=2, ensure_ascii=False), encoding="utf-8")
+
+
+# Keep private aliases for backwards compat within this module
+_load = load_config
+_save = save_config
+
+
+# ---------------------------------------------------------------------------
+# Subcommands
+# ---------------------------------------------------------------------------
+
+
+@config_app.command("get")
+def config_get(
+    key: str = typer.Argument(..., help="Configuration key"),
+) -> None:
+    """Print the value of a configuration key."""
+    _show_one(key)
+
+
+@config_app.command("set")
+def config_set(
+    key: str = typer.Argument(..., help="Configuration key"),
+    value: str = typer.Argument(..., help="Configuration value"),
+) -> None:
+    """Set a configuration value."""
+    output_fmt = state.output
+    quiet = state.quiet
+
+    cfg = _load()
+    cfg[key] = value
+    _save(cfg)
+
+    if output_fmt == OutputFormat.json:
+        print(json.dumps({"key": key, "value": value}, indent=2))
+    elif not quiet:
+        console.print(f"  [success]✓[/success]  [bold]{key}[/bold] = {value}")
+
+
+@config_app.command("show")
+def config_show(
+    key: Optional[str] = typer.Argument(None, help="Key to show (omit to show all)"),
+) -> None:
+    """Show one key or all configuration values."""
+    if key is not None:
+        return _show_one(key)
+    _show_all()
+
+
+@config_app.command("list")
+def config_list() -> None:
+    """List all configuration values."""
+    _show_all()
+
+
+def _show_one(key: str) -> None:
+    output_fmt = state.output
+    cfg = _load()
+
+    if key not in cfg:
+        if output_fmt == OutputFormat.json:
+            print(json.dumps({"key": key, "value": None}, indent=2))
+        else:
+            err_console.print(f"\n[error]✗[/error] Key [bold]{key}[/bold] is not set.\n")
+        raise typer.Exit(code=1)
+
+    value = cfg[key]
+    if output_fmt == OutputFormat.json:
+        print(json.dumps({"key": key, "value": value}, indent=2))
+    else:
+        console.print(value)
+
+
+def _show_all() -> None:
+    output_fmt = state.output
+    quiet = state.quiet
+    cfg = _load()
+
+    if output_fmt == OutputFormat.json:
+        print(json.dumps(cfg, indent=2, ensure_ascii=False))
+        return
+
+    if quiet:
+        return
+
+    console.print()
+
+    if not cfg:
+        console.print("  [muted]No configuration set.[/muted]")
+        console.print(f"  [muted]{get_config_path()}[/muted]")
+        console.print()
+        return
+
+    table = Table(box=box.SIMPLE, show_header=True, header_style="bold white")
+    table.add_column("Key", style="key", min_width=16)
+    table.add_column("Value", min_width=20)
+    table.add_column("Description", style="muted")
+
+    for k, v in sorted(cfg.items()):
+        desc = KNOWN_KEYS.get(k, "")
+        table.add_row(k, str(v), desc)
+
+    console.print(table)
+    console.print()
+
+
+@config_app.command("unset")
+def config_unset(
+    key: str = typer.Argument(..., help="Configuration key to remove"),
+) -> None:
+    """Remove a configuration key."""
+    output_fmt = state.output
+    quiet = state.quiet
+    cfg = _load()
+
+    if key not in cfg:
+        if output_fmt == OutputFormat.json:
+            print(json.dumps({"key": key, "removed": False}, indent=2))
+        else:
+            err_console.print(f"\n[error]✗[/error] Key [bold]{key}[/bold] is not set.\n")
+        raise typer.Exit(code=1)
+
+    del cfg[key]
+    _save(cfg)
+
+    if output_fmt == OutputFormat.json:
+        print(json.dumps({"key": key, "removed": True}, indent=2))
+    elif not quiet:
+        console.print(f"  [success]✓[/success]  [bold]{key}[/bold] removed")