Skip to content

Secure, Fast, and Extensible Sandbox runtime for AI agents.

10.9 KB
Raw Blame
# Copyright 2026 The OpenSandbox Authors.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

"""Output formatting: table (rich), JSON, YAML."""

from __future__ import annotations

import json
import sys
from collections.abc import Generator, Sequence
from contextlib import contextmanager
from typing import Any

import click

try:
    import yaml
except ImportError:  # pragma: no cover
    yaml = None  # type: ignore[assignment]

from pydantic import BaseModel
from rich import box
from rich.console import Console
from rich.panel import Panel
from rich.status import Status
from rich.table import Table
from rich.text import Text

_STATUS_STYLES: dict[str, tuple[str, str]] = {
    "running": ("bold green", "●"),
    "ready": ("bold green", "●"),
    "healthy": ("bold green", "●"),
    "pending": ("bold yellow", "◐"),
    "creating": ("bold yellow", "◐"),
    "starting": ("bold yellow", "◐"),
    "paused": ("bold blue", "⏸"),
    "stopped": ("dim", "○"),
    "terminated": ("dim", "○"),
    "killed": ("dim", "○"),
    "error": ("bold red", "✗"),
    "failed": ("bold red", "✗"),
    "unhealthy": ("bold red", "✗"),
    "created": ("bold cyan", "✦"),
}

_STATUS_COLUMNS = {"status", "state", "healthy"}
_DIM_COLUMNS = {"created_at", "expires_at", "modified_at", "updated_at"}
_ID_COLUMNS = {"id", "sandbox_id", "execution_id", "context_id"}


def _stdout_can_encode(text: str) -> bool:
    """Return whether stdout can represent ``text`` without substitution."""
    encoding = getattr(sys.stdout, "encoding", None)
    if encoding is None:
        return True
    try:
        text.encode(encoding)
    except (LookupError, UnicodeEncodeError):
        return False
    return True


def _style_value(col: str, value: str) -> Text:
    """Apply contextual styling to a cell value."""
    lower = value.lower()

    if col in _STATUS_COLUMNS:
        style, icon = _STATUS_STYLES.get(lower, ("", ""))
        if style:
            return Text(f"{icon} {value}", style=style)

    if col in _DIM_COLUMNS:
        return Text(value, style="dim")

    if col in _ID_COLUMNS:
        return Text(value, style="bold cyan")

    return Text(value)


class OutputFormatter:
    """Renders data in table / json / yaml format."""

    def __init__(self, fmt: str = "table", *, color: bool = True) -> None:
        self.fmt = fmt
        self.color = color
        self.console = Console(stderr=False, no_color=not color)
        self._err_console = Console(stderr=True, no_color=not color)

    def _message(
        self,
        status: str,
        msg: str,
        *,
        icon: str,
        style: str,
        plain: str,
        stderr: bool,
    ) -> None:
        if self.fmt == "json":
            self._print_json({"status": status, "message": msg})
            return
        if self.fmt == "yaml":
            self._print_yaml({"status": status, "message": msg})
            return
        if self.color:
            console = self._err_console if stderr else self.console
            console.print(f"  [bold {style}]{icon} {msg}[/]")
        else:
            click.echo(f"{plain}: {msg}", err=stderr)

    def success(self, msg: str) -> None:
        """Print a success message with ✅ icon."""
        self._message("ok", msg, icon="✅", style="green", plain="OK", stderr=False)

    def info(self, msg: str) -> None:
        """Print an info message with ℹ️ icon."""
        self._message("info", msg, icon="ℹ️ ", style="blue", plain="INFO", stderr=False)

    def warning(self, msg: str) -> None:
        """Print a warning message with ⚠️ icon."""
        self._message("warning", msg, icon="⚠️ ", style="yellow", plain="WARN", stderr=True)

    def error(self, msg: str) -> None:
        """Print an error message with ❌ icon."""
        self._message("error", msg, icon="❌", style="red", plain="ERROR", stderr=True)

    def error_panel(self, msg: str, title: str = "Error") -> None:
        """Print an error with a bold header and message."""
        if self.color:
            self._err_console.print()
            self._err_console.print(f"  [bold red]{title}[/]")
            self._err_console.print(f"  [dim]{'─' * (len(title) + 2)}[/]")
            for line in msg.splitlines():
                self._err_console.print(f"  {line}")
            self._err_console.print()
        else:
            click.echo(f"ERROR [{title}]: {msg}", err=True)

    @contextmanager
    def spinner(self, msg: str) -> Generator[Status, None, None]:
        """Context manager that shows a spinner while work is in progress."""
        if self.color and self.fmt == "table":
            with self._err_console.status(f"[bold cyan]⏳ {msg}[/]", spinner="dots") as status:
                yield status
        else:
            yield None  # type: ignore[arg-type]

    def panel(self, content: str, *, title: str | None = None, style: str = "cyan") -> None:
        """Print content inside a styled panel."""
        if self.color:
            self.console.print(Panel(
                content,
                title=title,
                title_align="left",
                border_style=style,
                box=box.ROUNDED,
                padding=(0, 1),
            ))
        else:
            if title:
                click.echo(f"--- {title} ---")
            click.echo(content)

    def success_panel(self, data: dict[str, Any], *, title: str = "Success") -> None:
        """Print a success result with a header and indented key-value pairs."""
        if self.fmt != "table":
            if self.fmt == "json":
                self._print_json(data)
            elif self.fmt == "yaml":
                self._print_yaml(data)
            return

        if self.color:
            self.console.print()
            self.console.print(f"  [bold green]✓ {title}[/]")
            self.console.print(f"  [dim]{'─' * (len(title) + 2)}[/]")
            for k, v in data.items():
                self.console.print(f"  [bold]{k}:[/] [cyan]{v}[/]")
            self.console.print()
        else:
            click.echo(f"--- {title} ---")
            for k, v in data.items():
                click.echo(f"  {k}: {v}")

    def print_model(self, model: BaseModel, title: str | None = None) -> None:
        """Print a single Pydantic model as key-value panel or JSON/YAML."""
        data = model.model_dump(mode="json")
        if self.fmt == "json":
            self._print_json(data)
        elif self.fmt == "yaml":
            self._print_yaml(data)
        else:
            self._print_kv_table(data, title=title)

    def print_models(
        self,
        models: Sequence[BaseModel],
        columns: list[str],
        *,
        title: str | None = None,
    ) -> None:
        """Print a list of Pydantic models as a table or JSON/YAML."""
        rows = [m.model_dump(mode="json") for m in models]
        if self.fmt == "json":
            self._print_json(rows)
        elif self.fmt == "yaml":
            self._print_yaml(rows)
        else:
            self._print_table(rows, columns, title=title)

    def print_rows(
        self,
        rows: list[dict[str, Any]],
        columns: list[str],
        *,
        title: str | None = None,
    ) -> None:
        """Print pre-processed rows (list of dicts) as a table or JSON/YAML."""
        if self.fmt == "json":
            self._print_json(rows)
        elif self.fmt == "yaml":
            self._print_yaml(rows)
        else:
            self._print_table(rows, columns, title=title)

    def print_dict(self, data: dict[str, Any], title: str | None = None) -> None:
        """Print a flat dict."""
        if self.fmt == "json":
            self._print_json(data)
        elif self.fmt == "yaml":
            self._print_yaml(data)
        else:
            self._print_kv_table(data, title=title)

    def print_text(self, text: str) -> None:
        """Print raw text (ignores format)."""
        click.echo(text)

    def _print_json(self, data: Any) -> None:
        if self.color:
            self.console.print_json(json.dumps(data, default=str))
        else:
            click.echo(json.dumps(data, indent=2, default=str))

    def _print_yaml(self, data: Any) -> None:
        if yaml is None:
            click.secho(
                "PyYAML is not installed. Use --output json instead.", fg="red", err=True
            )
            sys.exit(1)
        text = yaml.dump(data, default_flow_style=False, allow_unicode=True).rstrip()
        if not _stdout_can_encode(text):
            # Keep machine-readable output valid on limited code pages: escape
            # non-ASCII into round-trippable sequences instead of letting the
            # stream replace characters with "?".
            text = yaml.dump(
                data, default_flow_style=False, allow_unicode=False
            ).rstrip()
        click.echo(text)

    def _print_kv_table(self, data: dict[str, Any], *, title: str | None = None) -> None:
        table = Table(
            title=title,
            show_header=True,
            header_style="bold magenta",
            title_style="bold cyan",
            box=box.ROUNDED,
            border_style="bright_black",
            padding=(0, 1),
            show_lines=True,
        )
        table.add_column("Key", style="bold cyan", no_wrap=True)
        table.add_column("Value")
        for k, v in data.items():
            val_text = _style_value(k, str(v)) if v is not None else Text("-", style="dim")
            table.add_row(str(k), val_text)
        self.console.print(table)

    def _print_table(
        self,
        rows: list[dict[str, Any]],
        columns: list[str],
        *,
        title: str | None = None,
    ) -> None:
        table = Table(
            title=title,
            show_header=True,
            header_style="bold magenta",
            title_style="bold cyan",
            box=box.ROUNDED,
            border_style="bright_black",
            padding=(0, 1),
            row_styles=["", "dim"],
        )
        for col in columns:
            style = ""
            if col in _ID_COLUMNS:
                style = "bold cyan"
            elif col in _DIM_COLUMNS:
                style = "dim"
            table.add_column(col.upper(), style=style, no_wrap=(col in _ID_COLUMNS))

        for row in rows:
            cells: list[Text | str] = []
            for col in columns:
                val = str(row.get(col, "-"))
                if col in _STATUS_COLUMNS:
                    cells.append(_style_value(col, val))
                else:
                    cells.append(val)
            table.add_row(*cells)
        self.console.print(table)