kontra 0.5.2__py3-none-any.whl

kontra/cli/commands/history.py

@@ -0,0 +1,196 @@
+# src/kontra/cli/commands/history.py
+"""History command for Kontra CLI."""
+
+from __future__ import annotations
+
+from typing import Literal, Optional
+
+import typer
+
+from kontra.cli.constants import (
+    EXIT_CONFIG_ERROR,
+    EXIT_RUNTIME_ERROR,
+    EXIT_SUCCESS,
+)
+
+
+def register(app: typer.Typer) -> None:
+    """Register the history command with the app."""
+
+    @app.command("history")
+    def history(
+        contract: str = typer.Argument(
+            ..., help="Path to the contract.yml file"
+        ),
+        since: Optional[str] = typer.Option(
+            None,
+            "--since",
+            "-s",
+            help="Time filter: '24h', '7d', or date like '2026-01-15' (default: all)",
+        ),
+        limit: int = typer.Option(
+            20,
+            "--limit",
+            "-n",
+            help="Maximum runs to show (default: 20)",
+        ),
+        failed_only: bool = typer.Option(
+            False,
+            "--failed-only",
+            "-f",
+            help="Only show failed runs",
+        ),
+        output_format: Literal["table", "json"] = typer.Option(
+            "table",
+            "--output-format",
+            "-o",
+            help="Output format (default: table)",
+        ),
+        verbose: bool = typer.Option(
+            False, "--verbose", "-v", help="Show additional details"
+        ),
+    ) -> None:
+        """
+        Show validation history for a contract.
+
+        Displays past validation runs with timestamps, pass/fail status,
+        and violation counts. Useful for tracking data quality over time.
+
+        Examples:
+            kontra history contract.yml
+            kontra history contract.yml --since 7d
+            kontra history contract.yml --failed-only
+            kontra history contract.yml -o json
+        """
+        import json
+        import os
+
+        if verbose:
+            os.environ["KONTRA_VERBOSE"] = "1"
+
+        try:
+            import kontra
+
+            runs = kontra.get_history(
+                contract,
+                limit=limit,
+                since=since,
+                failed_only=failed_only,
+            )
+
+            if not runs:
+                typer.echo("No validation history found for this contract.")
+                raise typer.Exit(code=EXIT_SUCCESS)
+
+            if output_format == "json":
+                typer.echo(json.dumps(runs, indent=2, default=str))
+            else:
+                _render_table(runs, contract, verbose)
+
+            raise typer.Exit(code=EXIT_SUCCESS)
+
+        except typer.Exit:
+            raise
+
+        except FileNotFoundError as e:
+            from kontra.errors import format_error_for_cli
+
+            msg = format_error_for_cli(e)
+            typer.secho(f"Error: {msg}", fg=typer.colors.RED)
+            raise typer.Exit(code=EXIT_CONFIG_ERROR)
+
+        except ValueError as e:
+            typer.secho(f"Error: {e}", fg=typer.colors.RED)
+            raise typer.Exit(code=EXIT_CONFIG_ERROR)
+
+        except Exception as e:
+            from kontra.errors import format_error_for_cli
+
+            msg = format_error_for_cli(e)
+            if verbose:
+                import traceback
+
+                typer.secho(
+                    f"Error: {msg}\n\n{traceback.format_exc()}", fg=typer.colors.RED
+                )
+            else:
+                typer.secho(f"Error: {msg}", fg=typer.colors.RED)
+                typer.secho("Use --verbose for full traceback.", fg=typer.colors.YELLOW)
+            raise typer.Exit(code=EXIT_RUNTIME_ERROR)
+
+
+def _render_table(runs: list, contract: str, verbose: bool) -> None:
+    """Render history as a Rich table."""
+    from datetime import datetime
+
+    try:
+        from rich.console import Console
+        from rich.table import Table
+
+        console = Console()
+
+        # Header
+        contract_name = runs[0].get("contract_name", contract) if runs else contract
+        console.print(f"\n[bold]Validation History: {contract_name}[/bold]")
+        console.print(f"Showing {len(runs)} most recent runs\n")
+
+        # Table
+        table = Table(show_header=True, header_style="bold")
+        table.add_column("Timestamp", style="dim")
+        table.add_column("Status", justify="center")
+        table.add_column("Failed", justify="right")
+        table.add_column("Rows", justify="right")
+        if verbose:
+            table.add_column("Run ID", style="dim")
+
+        for run in runs:
+            # Parse timestamp
+            ts = run.get("timestamp", "")
+            if isinstance(ts, str):
+                try:
+                    dt = datetime.fromisoformat(ts.replace("Z", "+00:00"))
+                    ts_display = dt.strftime("%Y-%m-%d %H:%M")
+                except Exception:
+                    ts_display = ts[:16]
+            else:
+                ts_display = str(ts)[:16]
+
+            # Status
+            passed = run.get("passed", False)
+            if passed:
+                status = "[green]PASS[/green]"
+            else:
+                status = "[red]FAIL[/red]"
+
+            # Failed count
+            failed_count = run.get("failed_count", 0)
+            failed_display = str(failed_count) if failed_count > 0 else "-"
+
+            # Rows
+            total_rows = run.get("total_rows")
+            if total_rows is not None:
+                rows_display = f"{total_rows:,}"
+            else:
+                rows_display = "-"
+
+            if verbose:
+                run_id = run.get("run_id", "-")
+                table.add_row(ts_display, status, failed_display, rows_display, run_id)
+            else:
+                table.add_row(ts_display, status, failed_display, rows_display)
+
+        console.print(table)
+
+    except ImportError:
+        # Fallback to plain text if Rich not available
+        typer.echo(f"\nValidation History: {contract}")
+        typer.echo(f"Showing {len(runs)} most recent runs\n")
+        typer.echo(f"{'Timestamp':<20} {'Status':<8} {'Failed':<8} {'Rows':<12}")
+        typer.echo("-" * 50)
+
+        for run in runs:
+            ts = run.get("timestamp", "")[:16]
+            passed = "PASS" if run.get("passed", False) else "FAIL"
+            failed = str(run.get("failed_count", 0))
+            rows = str(run.get("total_rows", "-"))
+            typer.echo(f"{ts:<20} {passed:<8} {failed:<8} {rows:<12}")

kontra/cli/commands/profile.py

@@ -0,0 +1,289 @@
+"""Profile command for Kontra CLI."""
+
+from __future__ import annotations
+
+from typing import Literal, Optional
+
+import typer
+
+from kontra.cli.constants import (
+    EXIT_CONFIG_ERROR,
+    EXIT_RUNTIME_ERROR,
+    EXIT_SUCCESS,
+)
+
+
+def register(app: typer.Typer) -> None:
+    """Register the profile command with the app."""
+
+    @app.command("profile")
+    def profile(
+        source: str = typer.Argument(
+            ..., help="Path or URI to the dataset (local file, s3://..., https://...)"
+        ),
+        output_format: Optional[Literal["rich", "json", "markdown", "llm"]] = typer.Option(
+            None, "--output-format", "-o", help="Output format (default: 'rich')."
+        ),
+        # Config-aware options
+        preset: Optional[Literal["scout", "scan", "interrogate"]] = typer.Option(
+            None,
+            "--preset",
+            "-p",
+            help="Profiling depth (default: from config or 'scan').",
+        ),
+        list_values_threshold: Optional[int] = typer.Option(
+            None,
+            "--list-values-threshold",
+            "-l",
+            help="List all values if distinct count <= threshold.",
+        ),
+        top_n: Optional[int] = typer.Option(
+            None,
+            "--top-n",
+            "-t",
+            help="Show top N most frequent values per column.",
+        ),
+        sample: Optional[int] = typer.Option(
+            None,
+            "--sample",
+            "-s",
+            help="Sample N rows for profiling (default: all rows).",
+        ),
+        include_patterns: Optional[bool] = typer.Option(
+            None,
+            "--include-patterns",
+            help="Detect common patterns (default: from config or False).",
+        ),
+        columns: Optional[str] = typer.Option(
+            None,
+            "--columns",
+            "-c",
+            help="Comma-separated list of columns to profile (default: all).",
+        ),
+        draft: bool = typer.Option(
+            False,
+            "--draft",
+            help="Generate draft validation rules based on profile.",
+        ),
+        save_profile: Optional[bool] = typer.Option(
+            None,
+            "--save-profile",
+            help="Save profile to state storage (default: from config or False).",
+        ),
+        # Environment selection
+        env: Optional[str] = typer.Option(
+            None,
+            "--env",
+            "-e",
+            help="Environment profile from .kontra/config.yml.",
+            envvar="KONTRA_ENV",
+        ),
+        storage_options: Optional[str] = typer.Option(
+            None,
+            "--storage-options",
+            help='Cloud storage credentials as JSON, e.g. \'{"aws_access_key_id": "...", "aws_region": "us-east-1"}\'',
+        ),
+        verbose: bool = typer.Option(
+            False, "--verbose", "-v", help="Enable verbose output."
+        ),
+    ) -> None:
+        """
+        Profile a dataset (Kontra Profile).
+
+        Generates comprehensive column-level statistics optimized for
+        developer exploration and LLM context compression.
+
+        Presets control profiling depth:
+          - scout: Quick recon. Metadata only (schema, row count, null/distinct counts).
+          - scan: Systematic pass. Full stats with moderate top values. [default]
+          - interrogate: Deep investigation. Everything including percentiles.
+
+        Examples:
+            kontra profile data.parquet
+            kontra profile s3://bucket/data.csv --sample 10000
+            kontra profile data.parquet -o json --preset interrogate
+            kontra profile data.parquet --draft > rules.yml
+            kontra profile data.parquet --save-profile  # Save for diffing
+        """
+        _run_profile(
+            source=source,
+            output_format=output_format,
+            preset=preset,
+            list_values_threshold=list_values_threshold,
+            top_n=top_n,
+            sample=sample,
+            include_patterns=include_patterns,
+            columns=columns,
+            draft=draft,
+            save_profile=save_profile,
+            env=env,
+            storage_options=storage_options,
+            verbose=verbose,
+        )
+
+
+
+def _run_profile(
+    source: str,
+    output_format: Optional[str],
+    preset: Optional[str],
+    list_values_threshold: Optional[int],
+    top_n: Optional[int],
+    sample: Optional[int],
+    include_patterns: Optional[bool],
+    columns: Optional[str],
+    draft: bool,
+    save_profile: Optional[bool],
+    env: Optional[str],
+    storage_options: Optional[str],
+    verbose: bool,
+) -> None:
+    """Shared implementation for profile and scout commands."""
+    import os
+
+    if verbose:
+        os.environ["KONTRA_VERBOSE"] = "1"
+
+    try:
+        from kontra.config.settings import resolve_effective_config
+
+        # --- LOAD CONFIG ---
+        cli_overrides = {
+            "preset": preset,
+            "save_profile": save_profile,
+            "list_values_threshold": list_values_threshold,
+            "top_n": top_n,
+            "include_patterns": include_patterns,
+        }
+
+        try:
+            config = resolve_effective_config(
+                env_name=env, cli_overrides=cli_overrides
+            )
+        except Exception as e:
+            from kontra.errors import format_error_for_cli
+
+            typer.secho(
+                f"Config error: {format_error_for_cli(e)}", fg=typer.colors.RED
+            )
+            raise typer.Exit(code=EXIT_CONFIG_ERROR)
+
+        # Resolve effective values from config
+        effective_preset = config.scout_preset
+        effective_save_profile = config.scout_save_profile
+        effective_list_values_threshold = config.scout_list_values_threshold
+        effective_top_n = config.scout_top_n
+        effective_include_patterns = config.scout_include_patterns
+
+        # --- RESOLVE DATASOURCE ---
+        from kontra.config.settings import resolve_datasource
+
+        try:
+            resolved_source = resolve_datasource(source)
+        except ValueError as e:
+            typer.secho(f"Datasource error: {e}", fg=typer.colors.RED)
+            raise typer.Exit(code=EXIT_CONFIG_ERROR)
+
+        # Parse columns filter
+        cols_filter = None
+        if columns:
+            cols_filter = [c.strip() for c in columns.split(",") if c.strip()]
+
+        # Output format defaults
+        effective_output_format = output_format or "rich"
+
+        from kontra.scout.profiler import ScoutProfiler
+
+        # Parse storage_options JSON if provided
+        parsed_storage_options = None
+        if storage_options:
+            import json
+            try:
+                parsed_storage_options = json.loads(storage_options)
+            except json.JSONDecodeError as e:
+                typer.secho(
+                    f"Invalid --storage-options JSON: {e}",
+                    fg=typer.colors.RED,
+                )
+                raise typer.Exit(code=EXIT_CONFIG_ERROR)
+
+        profiler = ScoutProfiler(
+            resolved_source,
+            preset=effective_preset,
+            list_values_threshold=effective_list_values_threshold,
+            top_n=effective_top_n,
+            sample_size=sample,
+            include_patterns=effective_include_patterns,
+            columns=cols_filter,
+            storage_options=parsed_storage_options,
+        )
+
+        profile_result = profiler.profile()
+
+        # Save profile if requested
+        if effective_save_profile:
+            from kontra.scout.store import (
+                create_profile_state,
+                get_default_profile_store,
+            )
+
+            state = create_profile_state(profile_result)
+            store = get_default_profile_store()
+            store.save(state)
+            typer.secho(
+                f"Profile saved (fingerprint: {state.source_fingerprint})",
+                fg=typer.colors.GREEN,
+            )
+
+        # Handle rule draft/suggestions
+        if draft:
+            from kontra.scout.suggest import generate_rules_yaml
+
+            output = generate_rules_yaml(profile_result)
+        else:
+            from kontra.scout.reporters import render_profile
+
+            output = render_profile(profile_result, format=effective_output_format)
+
+        typer.echo(output)
+        raise typer.Exit(code=EXIT_SUCCESS)
+
+    except typer.Exit:
+        raise
+
+    except FileNotFoundError as e:
+        from kontra.errors import format_error_for_cli
+
+        msg = format_error_for_cli(e)
+        typer.secho(f"Error: {msg}", fg=typer.colors.RED)
+        if verbose:
+            import traceback
+
+            typer.secho(f"\n{traceback.format_exc()}", fg=typer.colors.YELLOW)
+        raise typer.Exit(code=EXIT_CONFIG_ERROR)
+
+    except ConnectionError as e:
+        from kontra.errors import format_error_for_cli
+
+        msg = format_error_for_cli(e)
+        typer.secho(f"Error: {msg}", fg=typer.colors.RED)
+        if verbose:
+            import traceback
+
+            typer.secho(f"\n{traceback.format_exc()}", fg=typer.colors.YELLOW)
+        raise typer.Exit(code=EXIT_RUNTIME_ERROR)
+
+    except Exception as e:
+        from kontra.errors import format_error_for_cli
+
+        msg = format_error_for_cli(e)
+        if verbose:
+            import traceback
+
+            typer.secho(
+                f"Error: {msg}\n\n{traceback.format_exc()}", fg=typer.colors.RED
+            )
+        else:
+            typer.secho(f"Error: {msg}", fg=typer.colors.RED)
+            typer.secho("Use --verbose for full traceback.", fg=typer.colors.YELLOW)
+        raise typer.Exit(code=EXIT_RUNTIME_ERROR)