everypixel-cli 0.1.0__py3-none-any.whl

everypixel_cli/openapi.py

@@ -0,0 +1,338 @@
+"""OpenAPI schema support for the generic `run` command.
+
+The CLI tries live API schema first, then cache, then the bundled snapshot.
+This keeps `everypixel run ...` usable offline and up to date when API exists.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from contextlib import suppress
+from dataclasses import dataclass
+from importlib.resources import files
+from pathlib import Path
+from typing import Any
+
+from jsonschema import Draft202012Validator
+from jsonschema.exceptions import ValidationError as JSONSchemaValidationError
+from jsonschema.exceptions import best_match
+from referencing import Registry, Resource
+from referencing.jsonschema import DRAFT202012
+
+from .config import config_dir
+from .errors import CLIError, EXIT_VALIDATION, FileWriteError
+
+
+SCHEMA_TTL_SECONDS = 24 * 60 * 60
+
+
+@dataclass(frozen=True)
+class Operation:
+    """Resolved OpenAPI operation: HTTP method, path, and schema fragment."""
+
+    method: str
+    path: str
+    schema: dict[str, Any]
+    document: dict[str, Any] | None = None
+
+
+def schema_cache_path(base_url: str) -> Path:
+    """Return the OpenAPI schema cache path for a base URL."""
+
+    safe = base_url.replace("://", "_").replace("/", "_").replace(":", "_")
+    return config_dir() / "schemas" / f"{safe}.json"
+
+
+def read_cached_schema(
+    base_url: str, *, ttl_seconds: int = SCHEMA_TTL_SECONDS
+) -> dict[str, Any] | None:
+    """Read a fresh cached schema or return None."""
+
+    path = schema_cache_path(base_url)
+    try:
+        if not path.exists():
+            return None
+        if time.time() - path.stat().st_mtime > ttl_seconds:
+            return None
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+
+
+def write_cached_schema(base_url: str, schema: dict[str, Any]) -> Path:
+    """Save an OpenAPI schema to local cache."""
+
+    path = schema_cache_path(base_url)
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(
+            json.dumps(schema, ensure_ascii=False, indent=2),
+            encoding="utf-8",
+        )
+    except OSError as exc:
+        raise FileWriteError(
+            "Unable to write OpenAPI schema cache",
+            details={"path": str(path)},
+        ) from exc
+    return path
+
+
+def bundled_schema() -> dict[str, Any]:
+    """Read the bundled OpenAPI snapshot from package resources."""
+
+    resource = files("everypixel_cli.resources").joinpath("openapi.json")
+    return json.loads(resource.read_text(encoding="utf-8"))
+
+
+def load_schema(client, *, refresh: bool = False) -> tuple[dict[str, Any], str]:
+    """Load schema from cache/live/bundled and return its source."""
+
+    if not refresh:
+        cached = read_cached_schema(client.base_url)
+        if cached is not None:
+            return cached, "cache"
+    try:
+        live = client.request("GET", "/v1/openapi.json", auth_required=False)
+    except CLIError:
+        cached = read_cached_schema(
+            client.base_url, ttl_seconds=10 * 365 * 24 * 60 * 60
+        )
+        if cached is not None:
+            return cached, "cache_stale"
+        return bundled_schema(), "bundled"
+    with suppress(FileWriteError):
+        write_cached_schema(client.base_url, live)
+    return live, "live"
+
+
+def refresh_schema(client) -> tuple[dict[str, Any], Path]:
+    """Force-load live OpenAPI schema and update cache."""
+
+    schema = client.request("GET", "/v1/openapi.json", auth_required=False)
+    path = write_cached_schema(client.base_url, schema)
+    return schema, path
+
+
+def find_operation(
+    schema: dict[str, Any], endpoint: str, requested_method: str | None = None
+) -> Operation | None:
+    """Find an operation by path, short endpoint name, or operationId."""
+
+    paths = schema.get("paths")
+    if not isinstance(paths, dict):
+        return None
+
+    normalized_endpoint = endpoint.strip()
+    if normalized_endpoint.startswith("/"):
+        candidates = [normalized_endpoint]
+    else:
+        candidates = [f"/v1/{normalized_endpoint}", normalized_endpoint]
+
+    requested = requested_method.lower() if requested_method else None
+    for path, operations in paths.items():
+        if not isinstance(operations, dict):
+            continue
+        for method, operation_schema in operations.items():
+            if requested and method.lower() != requested:
+                continue
+            if (
+                path in candidates
+                or path.rstrip("/").split("/")[-1] == normalized_endpoint
+            ):
+                return Operation(
+                    method=method.upper(),
+                    path=path,
+                    schema=operation_schema,
+                    document=schema,
+                )
+            operation_id = (
+                operation_schema.get("operationId")
+                if isinstance(operation_schema, dict)
+                else None
+            )
+            if operation_id == normalized_endpoint:
+                return Operation(
+                    method=method.upper(),
+                    path=path,
+                    schema=operation_schema,
+                    document=schema,
+                )
+    return None
+
+
+def operation_help(
+    operation: Operation | None,
+    *,
+    endpoint: str,
+    method: str,
+    path: str,
+    schema_source: str | None,
+) -> dict[str, Any]:
+    """Build a help payload for a resolved OpenAPI operation."""
+
+    schema = operation.schema if operation else None
+    return {
+        "endpoint": endpoint,
+        "schema_source": schema_source,
+        "method": method,
+        "path": path,
+        "summary": schema.get("summary") if isinstance(schema, dict) else None,
+        "operation_id": schema.get("operationId") if isinstance(schema, dict) else None,
+        "parameters": summarize_parameters(schema),
+        "request_body": summarize_request_body(schema),
+        "schema": schema,
+    }
+
+
+def summarize_parameters(schema: dict[str, Any] | None) -> list[dict[str, Any]]:
+    """Simplify OpenAPI parameters for user output."""
+
+    if not isinstance(schema, dict) or not isinstance(schema.get("parameters"), list):
+        return []
+    parameters = []
+    for item in schema["parameters"]:
+        if isinstance(item, dict):
+            parameters.append(
+                {
+                    "name": item.get("name"),
+                    "in": item.get("in"),
+                    "required": item.get("required", False),
+                    "schema": item.get("schema"),
+                    "description": item.get("description"),
+                }
+            )
+    return parameters
+
+
+def summarize_request_body(schema: dict[str, Any] | None) -> dict[str, Any] | None:
+    """Simplify requestBody description for user output."""
+
+    if not isinstance(schema, dict):
+        return None
+    request_body = schema.get("requestBody")
+    if not isinstance(request_body, dict):
+        return None
+    content = request_body.get("content")
+    if not isinstance(content, dict):
+        return {"required": request_body.get("required", False), "content_types": []}
+    return {
+        "required": request_body.get("required", False),
+        "content_types": [
+            {
+                "content_type": content_type,
+                "schema": content_schema.get("schema")
+                if isinstance(content_schema, dict)
+                else None,
+            }
+            for content_type, content_schema in content.items()
+        ],
+    }
+
+
+def validate_payload_against_operation(
+    operation: Operation | None, payload: dict[str, Any]
+) -> None:
+    """Validate a payload against an OpenAPI 3.1 JSON request schema."""
+
+    if operation is None:
+        return
+    schema = json_request_body_schema(operation.schema)
+    if schema is None:
+        return
+    validator = openapi_validator(schema, operation.document)
+    error = best_match(validator.iter_errors(payload))
+    if error is None:
+        return
+    message, details = format_openapi_validation_error(error)
+    raise CLIError(
+        message,
+        code="validation_error",
+        exit_code=EXIT_VALIDATION,
+        details=details,
+    )
+
+
+def json_request_body_schema(operation_schema: dict[str, Any]) -> dict[str, Any] | None:
+    """Return the application/json schema for an OpenAPI operation."""
+
+    request_body = operation_schema.get("requestBody")
+    if not isinstance(request_body, dict):
+        return None
+    content = request_body.get("content")
+    if not isinstance(content, dict):
+        return None
+    json_content = content.get("application/json")
+    if not isinstance(json_content, dict):
+        return None
+    schema = json_content.get("schema")
+    return schema if isinstance(schema, dict) else None
+
+
+def openapi_validator(
+    schema: dict[str, Any], document: dict[str, Any] | None
+) -> Draft202012Validator:
+    """Build a JSON Schema validator with local OpenAPI references available."""
+
+    if document is None:
+        return Draft202012Validator(schema)
+    document_uri = "urn:everypixel:openapi"
+    resource = Resource.from_contents(
+        document,
+        default_specification=DRAFT202012,
+    )
+    registry = Registry().with_resource(document_uri, resource)
+    return Draft202012Validator(
+        absolute_document_refs(schema, document_uri),
+        registry=registry,
+    )
+
+
+def absolute_document_refs(value: Any, document_uri: str) -> Any:
+    """Point fragment refs from a detached request schema at its document."""
+
+    if isinstance(value, dict):
+        result = {
+            key: absolute_document_refs(item, document_uri)
+            for key, item in value.items()
+        }
+        ref = result.get("$ref")
+        if isinstance(ref, str) and ref.startswith("#/"):
+            result["$ref"] = f"{document_uri}{ref}"
+        return result
+    if isinstance(value, list):
+        return [absolute_document_refs(item, document_uri) for item in value]
+    return value
+
+
+def format_openapi_validation_error(
+    error: JSONSchemaValidationError,
+) -> tuple[str, dict[str, Any]]:
+    """Return a stable error without echoing arbitrary user payload values."""
+
+    path = ".".join(str(part) for part in error.absolute_path)
+    label = path or "payload"
+    rule = str(error.validator)
+    if error.validator == "required" and isinstance(error.validator_value, list):
+        instance = error.instance if isinstance(error.instance, dict) else {}
+        missing = [key for key in error.validator_value if key not in instance]
+        message = f"Missing required input(s): {', '.join(map(str, missing))}"
+    elif error.validator == "type":
+        message = f"Invalid type for input '{label}': expected {error.validator_value}"
+    elif error.validator == "enum":
+        message = f"Invalid value for input '{label}': expected an allowed enum value"
+    elif error.validator in {"oneOf", "anyOf"}:
+        message = "Payload does not match an allowed request schema"
+    elif error.validator in {
+        "minimum",
+        "maximum",
+        "exclusiveMinimum",
+        "exclusiveMaximum",
+    }:
+        message = f"Input '{label}' is outside the allowed range"
+    else:
+        message = f"Input '{label}' does not satisfy the OpenAPI schema"
+    details = {"rule": rule}
+    if path:
+        details["path"] = path
+    return message, details

everypixel_cli/output.py

@@ -0,0 +1,159 @@
+"""CLI output rendering in JSON or human-readable mode."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from rich.console import Console
+from rich.table import Table
+from rich.text import Text
+
+from .errors import CLIError, JqExpressionError, SerializationError, serialize_error
+
+
+def apply_jq(data: Any, expr: str | None) -> Any:
+    """Apply a jq expression or simple dot selector fallback."""
+
+    if not expr:
+        return data
+    try:
+        import jq  # type: ignore
+    except ModuleNotFoundError:
+        return apply_simple_selector(data, expr)
+    try:
+        return jq.compile(expr).input(data).first()
+    except Exception as exc:  # jq does not expose stable public exception classes.
+        raise JqExpressionError(
+            "Unable to apply jq expression", details={"expression": expr}
+        ) from exc
+
+
+def apply_simple_selector(data: Any, expr: str) -> Any:
+    """Minimal fallback for `.field.subfield` expressions."""
+
+    if not expr.startswith("."):
+        raise JqExpressionError(
+            "Unable to apply jq expression", details={"expression": expr}
+        )
+    current = data
+    try:
+        for part in expr[1:].split("."):
+            if not part:
+                continue
+            if not isinstance(current, dict):
+                raise TypeError("selector target is not an object")
+            current = current[part]
+        return current
+    except (KeyError, TypeError) as exc:
+        raise JqExpressionError(
+            "Unable to apply jq expression", details={"expression": expr}
+        ) from exc
+
+
+def emit_json(data: Any, jq_expr: str | None = None) -> None:
+    """Print JSON output."""
+
+    try:
+        selected = apply_jq(data, jq_expr)
+        print(json.dumps(selected, ensure_ascii=False, indent=2))
+    except CLIError:
+        raise
+    except (TypeError, ValueError) as exc:
+        raise SerializationError("Unable to serialize CLI response") from exc
+
+
+def emit_human(data: Any, *, title: str | None = None, no_color: bool = False) -> None:
+    """Print output using Rich tables or a simple fallback."""
+
+    console = Console(no_color=no_color)
+    if title:
+        console.print(f"[bold]{title}[/bold]")
+    if isinstance(data, dict) and render_known_table(console, data):
+        return
+    if isinstance(data, dict):
+        table = Table(show_header=False, box=None)
+        table.add_column("Key", style="cyan")
+        table.add_column("Value")
+        for key, value in data.items():
+            table.add_row(
+                str(key),
+                json.dumps(value, ensure_ascii=False)
+                if isinstance(value, (dict, list))
+                else str(value),
+            )
+        console.print(table)
+    else:
+        console.print(data)
+
+
+def render_known_table(console: Console, data: dict[str, Any]) -> bool:
+    """Render specialized tables for known API responses."""
+
+    if isinstance(data.get("keywords"), list):
+        table = Table(title="Keywords")
+        table.add_column("Keyword", style="cyan")
+        table.add_column("Score", justify="right")
+        for item in data["keywords"]:
+            if isinstance(item, dict):
+                table.add_row(
+                    str(item.get("keyword", "")), format_score(item.get("score"))
+                )
+        console.print(table)
+        return True
+
+    if isinstance(data.get("faces"), list):
+        table = Table(title="Faces")
+        table.add_column("#", justify="right")
+        table.add_column("Score", justify="right")
+        table.add_column("BBox")
+        table.add_column("Age")
+        table.add_column("Gender")
+        for index, item in enumerate(data["faces"], start=1):
+            if isinstance(item, dict):
+                table.add_row(
+                    str(index),
+                    format_score(item.get("score")),
+                    json.dumps(item.get("bbox", ""), ensure_ascii=False),
+                    str(item.get("age", "")),
+                    str(item.get("gender", "")),
+                )
+        console.print(table)
+        return True
+
+    if isinstance(data.get("quality"), dict):
+        table = Table(title="Quality")
+        table.add_column("Metric", style="cyan")
+        table.add_column("Value", justify="right")
+        for key, value in data["quality"].items():
+            table.add_row(
+                str(key),
+                format_score(value) if isinstance(value, float) else str(value),
+            )
+        console.print(table)
+        return True
+
+    return False
+
+
+def format_score(value: Any) -> str:
+    """Format score/metric values for human output."""
+
+    if isinstance(value, float):
+        return f"{value:.4f}"
+    if value is None:
+        return ""
+    return str(value)
+
+
+def emit_error(error: CLIError, *, output_json: bool, no_color: bool = False) -> None:
+    """Print a JSON error to stdout or a human error to stderr."""
+
+    if output_json:
+        # JSON output has one machine-readable stream, including failures.
+        print(serialize_error(error))
+        return
+    console = Console(stderr=True, no_color=no_color)
+    console.print(Text(f"Error [{error.code}]: {error.message}", style="red"))
+    for key, value in error.details.items():
+        console.print(f"{key.replace('_', ' ').title()}: {value}")

everypixel_cli/resources/__init__.py

@@ -0,0 +1 @@
+"""Bundled package resources."""