dataspring-cli 0.3.0__py3-none-any.whl

cli/output.py

@@ -0,0 +1,266 @@
+"""CLI Output Formatters - Rich tables, JSON, CSV output.
+
+Provides consistent output formatting across all CLI commands.
+"""
+
+import csv
+import io
+import json
+from typing import Any, Literal
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+
+# Shared console instance
+console = Console()
+
+OutputFormat = Literal["table", "json", "yaml", "csv"]
+
+
+def print_table(
+    data: list[dict],
+    columns: list[str] | None = None,
+    title: str | None = None,
+):
+    """Print data as a Rich table.
+
+    Args:
+        data: List of row dictionaries
+        columns: Column names (defaults to keys from first row)
+        title: Optional table title
+    """
+    if not data:
+        console.print("[dim]No data to display[/]")
+        return
+
+    if columns is None:
+        columns = list(data[0].keys())
+
+    table = Table(title=title, show_header=True, header_style="bold")
+
+    for col in columns:
+        # Don't wrap ID columns so users can copy-paste full IDs
+        if col.lower() == "id":
+            table.add_column(col, no_wrap=True, overflow="fold")
+        else:
+            table.add_column(col)
+
+    for row in data:
+        table.add_row(*[_format_cell(row.get(col)) for col in columns])
+
+    console.print(table)
+
+
+def _format_cell(value: Any) -> str:
+    """Format a cell value for display."""
+    if value is None:
+        return ""
+    if isinstance(value, bool):
+        return "Yes" if value else "No"
+    if isinstance(value, float):
+        # Format floats nicely
+        if value == int(value):
+            return str(int(value))
+        return f"{value:,.2f}"
+    return str(value)
+
+
+def print_json(data: Any):
+    """Print data as formatted JSON.
+
+    Args:
+        data: Any JSON-serializable data
+    """
+    console.print_json(json.dumps(data, indent=2, default=str))
+
+
+def print_yaml(data: Any):
+    """Print data as YAML.
+
+    Args:
+        data: Any data to format as YAML
+    """
+    try:
+        import yaml
+
+        console.print(yaml.dump(data, default_flow_style=False, sort_keys=False))
+    except ImportError:
+        # Fall back to JSON if PyYAML not installed
+        console.print("[yellow]PyYAML not installed, showing as JSON:[/]")
+        print_json(data)
+
+
+def print_csv(data: list[dict], columns: list[str] | None = None):
+    """Print data as CSV.
+
+    Args:
+        data: List of row dictionaries
+        columns: Column names (defaults to keys from first row)
+    """
+    if not data:
+        return
+
+    if columns is None:
+        columns = list(data[0].keys())
+
+    output = io.StringIO()
+    writer = csv.DictWriter(output, fieldnames=columns, extrasaction="ignore")
+    writer.writeheader()
+    writer.writerows(data)
+
+    console.print(output.getvalue(), highlight=False)
+
+
+def format_output(
+    data: Any,
+    format: OutputFormat = "table",
+    columns: list[str] | None = None,
+    title: str | None = None,
+):
+    """Format and print data according to output format.
+
+    Args:
+        data: Data to output (list of dicts for table/csv, any for json/yaml)
+        format: Output format
+        columns: Column names for table/csv output
+        title: Title for table output
+    """
+    if format == "table":
+        if isinstance(data, list):
+            print_table(data, columns=columns, title=title)
+        else:
+            # Single item - show as key-value pairs
+            print_key_value(data)
+    elif format == "json":
+        print_json(data)
+    elif format == "yaml":
+        print_yaml(data)
+    elif format == "csv":
+        if isinstance(data, list):
+            print_csv(data, columns=columns)
+        else:
+            console.print("[red]CSV format requires list data[/]")
+    else:
+        console.print(f"[red]Unknown format: {format}[/]")
+
+
+def print_key_value(data: dict, title: str | None = None):
+    """Print a single object as key-value pairs.
+
+    Args:
+        data: Dictionary to display
+        title: Optional panel title
+    """
+    table = Table(show_header=False, box=None, padding=(0, 2))
+    table.add_column(style="bold cyan")
+    table.add_column()
+
+    for key, value in data.items():
+        table.add_row(key, _format_cell(value))
+
+    if title:
+        console.print(Panel(table, title=title))
+    else:
+        console.print(table)
+
+
+def print_success(message: str):
+    """Print a success message.
+
+    Args:
+        message: Success message
+    """
+    console.print(f"[green]✓[/] {message}")
+
+
+def print_error(message: str, hint: str | None = None):
+    """Print an error message.
+
+    Args:
+        message: Error message
+        hint: Optional hint for resolving the error
+    """
+    console.print(f"[red]✗ Error:[/] {message}")
+    if hint:
+        console.print(f"[dim]  Hint: {hint}[/]")
+
+
+def print_warning(message: str):
+    """Print a warning message.
+
+    Args:
+        message: Warning message
+    """
+    console.print(f"[yellow]⚠[/] {message}")
+
+
+def print_info(message: str):
+    """Print an info message.
+
+    Args:
+        message: Info message
+    """
+    console.print(f"[blue]ℹ[/] {message}")
+
+
+def print_user_context(email: str, org_id: str, role: str, org_name: str | None = None):
+    """Print user context in a nice format.
+
+    Args:
+        email: User email
+        org_id: Organization ID
+        role: User's role
+        org_name: Optional organization name
+    """
+    org_display = org_name if org_name else org_id
+
+    table = Table(show_header=False, box=None, padding=(0, 2))
+    table.add_column(style="bold")
+    table.add_column()
+
+    table.add_row("Email", email)
+    table.add_row("Organization", org_display)
+    table.add_row("Role", _format_role(role))
+
+    console.print(Panel(table, title="[bold]Current User[/]"))
+
+
+def _format_role(role: str) -> str:
+    """Format role with color."""
+    colors = {
+        "owner": "magenta",
+        "admin": "red",
+        "member": "blue",
+        "viewer": "dim",
+    }
+    color = colors.get(role, "white")
+    return f"[{color}]{role}[/{color}]"
+
+
+def print_report_hint(command: str, error_message: str):
+    """Print a hint about submitting an error report.
+
+    Args:
+        command: The command that failed
+        error_message: The error that occurred
+    """
+    safe_error = error_message.replace('"', '\\"')
+    safe_command = command.replace('"', '\\"')
+    console.print(
+        f'\n[dim]If this seems wrong, you can report it:[/]\n'
+        f'[dim]  dataspring report "{safe_command}" "{safe_error}" --expected "..." --context "..."[/]'
+    )
+
+
+def print_visualization_suggestion(widget_type: str, rationale: str):
+    """Print a visualization suggestion.
+
+    Args:
+        widget_type: Suggested widget type
+        rationale: Reason for the suggestion
+    """
+    console.print()
+    console.print(f"[bold]Suggested visualization:[/] {widget_type}")
+    console.print(f"[dim]{rationale}[/]")

cli/runtime.py

@@ -0,0 +1,201 @@
+"""How a parsed command becomes one ``POST /api/dispatch/<key>`` call.
+
+The generated commands in ``cli/generated.py`` and the hand-written aliases
+in ``cli/main.py`` both end here, so there is one place that
+
+* decodes ``--<field>-json`` values (JSON text, or ``@path`` to a YAML/JSON
+  file) and ``--from-file`` (the whole body; flags override its keys);
+* keeps only the flags the user gave, so the server's defaults apply to the
+  rest and the body says nothing the user did not;
+* wraps an edit family's fields as ``{"action": {"action": <verb>, ...}}``;
+* validates the body against the contract model the server will validate
+  it against (``cli/contract.py``), so a wrong flag is a message here, not
+  a 400 in a terminal;
+* prints the manifest skew hint once per process when the server has
+  operations or fields this CLI does not know (``cli/version.py``), and
+  still runs what it can;
+* writes the answer's ``content`` or ``data_base64`` to ``--output``, or
+  prints the JSON answer.
+
+The HTTP client, the auth manager and the error formatting stay in
+``cli/main.py`` and are looked up there at call time, which is what lets
+the tests stand in a fake server and a fake login for every command.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+from pathlib import Path
+from typing import Any
+
+import typer
+import yaml
+from pydantic import BaseModel, ValidationError
+
+from cli.output import print_error, print_success
+
+EXIT_USAGE = 2
+
+#: Seconds a generated command waits for the server; renders and imports are
+#: the slow ones, and a query has its own byte and time caps on the server.
+DEFAULT_TIMEOUT = 180.0
+
+
+# ---------------------------------------------------------------------------
+# Values
+# ---------------------------------------------------------------------------
+
+
+def load_document(path: Path) -> Any:
+    """A YAML or JSON file, by suffix (YAML reads JSON too)."""
+    if not path.exists():
+        print_error(f"File not found: {path}")
+        raise typer.Exit(EXIT_USAGE)
+    text = path.read_text(encoding="utf-8")
+    try:
+        if path.suffix.lower() == ".json":
+            return json.loads(text)
+        return yaml.safe_load(text)
+    except (json.JSONDecodeError, yaml.YAMLError) as e:
+        print_error(f"{path} is not valid {'JSON' if path.suffix.lower() == '.json' else 'YAML'}: {e}")
+        raise typer.Exit(EXIT_USAGE)
+
+
+def J(raw: str | None) -> Any:  # noqa: N802 - short on purpose: it wraps every JSON flag in the generated file
+    """Decode a ``--<field>-json`` flag: JSON text, or ``@path`` to a YAML/JSON file."""
+    if raw is None:
+        return None
+    if raw.startswith("@"):
+        return load_document(Path(raw[1:]))
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError as e:
+        print_error(f"Not JSON: {raw!r} ({e})", hint="Pass JSON text, or @path to a .json/.yaml file")
+        raise typer.Exit(EXIT_USAGE)
+
+
+# ---------------------------------------------------------------------------
+# The body
+# ---------------------------------------------------------------------------
+
+
+def build_body(verb: str | None, fields: dict[str, Any], from_file: Path | None = None) -> dict:
+    """The wire body: the file's keys under the flags given (``None`` is "not
+    given"), wrapped as an action for an edit family."""
+    base: dict = {}
+    if from_file is not None:
+        loaded = load_document(from_file)
+        if not isinstance(loaded, dict):
+            print_error(f"{from_file} must hold a mapping of fields")
+            raise typer.Exit(EXIT_USAGE)
+        base = dict(loaded)
+        if verb is not None and isinstance(base.get("action"), str):
+            base.pop("action")  # the verb is the subcommand
+    merged = {**base, **{k: v for k, v in fields.items() if v is not None}}
+    if verb is None:
+        return merged
+    return {"action": {"action": verb, **merged}}
+
+
+def validate(model: type[BaseModel], body: dict, verb: str | None = None) -> None:
+    """Refuse locally what the server would refuse with a 400, in the same words."""
+    try:
+        model.model_validate(body)
+    except ValidationError as e:
+        for err in e.errors(include_url=False):
+            loc = ".".join(str(p) for p in err["loc"] if p not in ("action", verb))
+            print_error(f"{loc}: {err['msg']}" if loc else err["msg"])
+        raise typer.Exit(EXIT_USAGE)
+
+
+# ---------------------------------------------------------------------------
+# The call
+# ---------------------------------------------------------------------------
+
+
+def call_tool(
+    key: str,
+    verb: str | None,
+    fields: dict[str, Any],
+    *,
+    model: type[BaseModel] | None = None,
+    from_file: Path | None = None,
+    token: str | None = None,
+    timeout: float = DEFAULT_TIMEOUT,
+) -> dict:
+    """Build, validate and send one dispatch call; answers the handler's result.
+
+    Raises what ``cli.main.api_dispatch`` raises (``DispatchToolError`` for a
+    handler's ``{"error": ...}``, ``httpx`` errors for the transport) so a
+    caller formats failures its own way; ``typer.Exit`` for a local refusal.
+    """
+    from cli import main as cli  # at call time: the tests patch cli.main's auth and HTTP functions
+    from cli.auth import AuthenticationError
+    from cli.version import skew_hint
+
+    if token is None:
+        try:
+            token = cli.auth.get_access_token()
+        except AuthenticationError as e:
+            print_error(str(e), hint="Run 'dataspring login' to authenticate")
+            raise typer.Exit(1)
+    if model is None:
+        from cli.generated import MODELS
+
+        model = MODELS[key]
+    body = build_body(verb, fields, from_file)
+    validate(model, body, verb)
+    hint = skew_hint(cli.get_api_base(), token)
+    if hint:
+        typer.echo(hint, err=True)
+    return cli.api_dispatch(key, body, token, timeout=timeout)
+
+
+def run_tool(
+    key: str,
+    model: type[BaseModel],
+    verb: str | None,
+    fields: dict[str, Any],
+    *,
+    from_file: Path | None = None,
+    output: Path | None = None,
+    timeout: float = DEFAULT_TIMEOUT,
+) -> None:
+    """What every generated command does: ``call_tool`` and then print or write the answer."""
+    from cli import main as cli
+
+    try:
+        result = call_tool(key, verb, fields, model=model, from_file=from_file, timeout=timeout)
+    except Exception as e:
+        cli.fail(e)
+    emit(result, output)
+
+
+def emit(result: Any, output: Path | None) -> None:
+    """The JSON answer on stdout, or its document / rendered file at ``output``."""
+    if output is None:
+        typer.echo(json.dumps(result, indent=2, default=str))
+        return
+    output.parent.mkdir(parents=True, exist_ok=True)
+    if isinstance(result, dict) and result.get("data_base64"):
+        data = base64.b64decode(result["data_base64"])
+        output.write_bytes(data)
+        what = "file"
+    elif isinstance(result, dict) and isinstance(result.get("content"), str):
+        data = result["content"].encode("utf-8")
+        output.write_bytes(data)
+        what = "document"
+    else:
+        data = json.dumps(result, indent=2, default=str).encode("utf-8")
+        output.write_bytes(data)
+        what = "answer"
+    print_success(f"Wrote the {what} to {output} ({_size(len(data))})")
+
+
+def _size(size: int) -> str:
+    if size >= 1024 * 1024:
+        return f"{size / (1024 * 1024):.1f} MB"
+    if size >= 1024:
+        return f"{size / 1024:.1f} KB"
+    return f"{size} bytes"