truthound 1.0.8__py3-none-any.whl

truthound/report.py

@@ -0,0 +1,280 @@
+"""Report generation for validation results."""
+
+import json
+from dataclasses import dataclass, field
+
+from rich.console import Console
+from rich.table import Table
+
+from truthound.types import Severity
+from truthound.validators.base import ValidationIssue
+
+
+@dataclass
+class Report:
+    """Validation report containing all issues found."""
+
+    issues: list[ValidationIssue] = field(default_factory=list)
+    source: str = "unknown"
+    row_count: int = 0
+    column_count: int = 0
+
+    def __str__(self) -> str:
+        """Return a formatted string representation using Rich."""
+        console = Console(force_terminal=True, width=80)
+        with console.capture() as capture:
+            self._print_to_console(console)
+        return capture.get()
+
+    def _print_to_console(self, console: Console) -> None:
+        """Print the report to a Rich console."""
+        console.print()
+        console.print("[bold]Truthound Report[/bold]")
+        console.print("━" * 52)
+
+        if not self.issues:
+            console.print("[green]✓ No issues found[/green]")
+            console.print()
+            return
+
+        table = Table(show_header=True, header_style="bold")
+        table.add_column("Column", style="cyan")
+        table.add_column("Issue", style="white")
+        table.add_column("Count", justify="right")
+        table.add_column("Severity", justify="center")
+
+        # Sort issues by severity (highest first)
+        severity_order = {
+            Severity.CRITICAL: 0,
+            Severity.HIGH: 1,
+            Severity.MEDIUM: 2,
+            Severity.LOW: 3,
+        }
+        sorted_issues = sorted(self.issues, key=lambda x: severity_order[x.severity])
+
+        for issue in sorted_issues:
+            severity_style = self._get_severity_style(issue.severity)
+            table.add_row(
+                issue.column,
+                issue.issue_type,
+                f"{issue.count:,}",
+                f"[{severity_style}]{issue.severity.value}[/{severity_style}]",
+            )
+
+        console.print(table)
+        console.print()
+
+        # Summary
+        unique_columns = len({i.column for i in self.issues if i.column != "*"})
+        console.print(f"Summary: {len(self.issues)} issues found in {unique_columns} columns")
+        console.print()
+
+    def _get_severity_style(self, severity: Severity) -> str:
+        """Get Rich style for severity level."""
+        return {
+            Severity.CRITICAL: "bold red",
+            Severity.HIGH: "red",
+            Severity.MEDIUM: "yellow",
+            Severity.LOW: "dim",
+        }[severity]
+
+    def print(self) -> None:
+        """Print the report to stdout."""
+        console = Console()
+        self._print_to_console(console)
+
+    def to_dict(self) -> dict:
+        """Convert report to dictionary for JSON serialization."""
+        return {
+            "source": self.source,
+            "row_count": self.row_count,
+            "column_count": self.column_count,
+            "issue_count": len(self.issues),
+            "issues": [issue.to_dict() for issue in self.issues],
+        }
+
+    def to_json(self, indent: int = 2) -> str:
+        """Convert report to JSON string."""
+        return json.dumps(self.to_dict(), indent=indent)
+
+    def filter_by_severity(self, min_severity: Severity) -> "Report":
+        """Return a new report with only issues at or above the given severity.
+
+        Args:
+            min_severity: Minimum severity level to include.
+
+        Returns:
+            New Report with filtered issues.
+        """
+        filtered_issues = [i for i in self.issues if i.severity >= min_severity]
+        return Report(
+            issues=filtered_issues,
+            source=self.source,
+            row_count=self.row_count,
+            column_count=self.column_count,
+        )
+
+    @property
+    def has_issues(self) -> bool:
+        """Check if the report contains any issues."""
+        return len(self.issues) > 0
+
+    @property
+    def has_critical(self) -> bool:
+        """Check if the report contains critical issues."""
+        return any(i.severity == Severity.CRITICAL for i in self.issues)
+
+    @property
+    def has_high(self) -> bool:
+        """Check if the report contains high severity issues."""
+        return any(i.severity >= Severity.HIGH for i in self.issues)
+
+
+@dataclass
+class PIIReport:
+    """Report for PII scan results."""
+
+    findings: list[dict] = field(default_factory=list)
+    source: str = "unknown"
+    row_count: int = 0
+
+    def __str__(self) -> str:
+        """Return a formatted string representation using Rich."""
+        console = Console(force_terminal=True, width=80)
+        with console.capture() as capture:
+            self._print_to_console(console)
+        return capture.get()
+
+    def _print_to_console(self, console: Console) -> None:
+        """Print the PII report to a Rich console."""
+        console.print()
+        console.print("[bold]Truthound PII Scan[/bold]")
+        console.print("━" * 52)
+
+        if not self.findings:
+            console.print("[green]✓ No PII detected[/green]")
+            console.print()
+            return
+
+        table = Table(show_header=True, header_style="bold")
+        table.add_column("Column", style="cyan")
+        table.add_column("PII Type", style="white")
+        table.add_column("Count", justify="right")
+        table.add_column("Confidence", justify="center")
+
+        for finding in self.findings:
+            table.add_row(
+                finding["column"],
+                finding["pii_type"],
+                f"{finding['count']:,}",
+                f"{finding['confidence']}%",
+            )
+
+        console.print(table)
+        console.print()
+
+        console.print(f"[yellow]Warning: Found {len(self.findings)} columns with potential PII[/yellow]")
+        console.print()
+
+    def print(self) -> None:
+        """Print the report to stdout."""
+        console = Console()
+        self._print_to_console(console)
+
+    def to_dict(self) -> dict:
+        """Convert report to dictionary."""
+        return {
+            "source": self.source,
+            "row_count": self.row_count,
+            "finding_count": len(self.findings),
+            "findings": self.findings,
+        }
+
+    def to_json(self, indent: int = 2) -> str:
+        """Convert report to JSON string."""
+        return json.dumps(self.to_dict(), indent=indent)
+
+    @property
+    def has_pii(self) -> bool:
+        """Check if PII was detected."""
+        return len(self.findings) > 0
+
+
+@dataclass
+class ProfileReport:
+    """Report for dataset profiling."""
+
+    source: str = "unknown"
+    row_count: int = 0
+    column_count: int = 0
+    size_bytes: int = 0
+    columns: list[dict] = field(default_factory=list)
+
+    def __str__(self) -> str:
+        """Return a formatted string representation using Rich."""
+        console = Console(force_terminal=True, width=80)
+        with console.capture() as capture:
+            self._print_to_console(console)
+        return capture.get()
+
+    def _print_to_console(self, console: Console) -> None:
+        """Print the profile report to a Rich console."""
+        console.print()
+        console.print("[bold]Truthound Profile[/bold]")
+        console.print("━" * 52)
+
+        size_str = self._format_size(self.size_bytes)
+        console.print(f"Dataset: {self.source}")
+        console.print(f"Rows: {self.row_count:,} | Columns: {self.column_count} | Size: {size_str}")
+        console.print()
+
+        if not self.columns:
+            return
+
+        table = Table(show_header=True, header_style="bold")
+        table.add_column("Column", style="cyan")
+        table.add_column("Type", style="white")
+        table.add_column("Nulls", justify="right")
+        table.add_column("Unique", justify="right")
+        table.add_column("Min", justify="right")
+        table.add_column("Max", justify="right")
+
+        for col in self.columns:
+            table.add_row(
+                col["name"],
+                col["dtype"],
+                col["null_pct"],
+                col["unique_pct"],
+                col.get("min", "-"),
+                col.get("max", "-"),
+            )
+
+        console.print(table)
+        console.print()
+
+    def _format_size(self, size_bytes: int) -> str:
+        """Format byte size to human readable string."""
+        for unit in ["B", "KB", "MB", "GB"]:
+            if size_bytes < 1024:
+                return f"{size_bytes:.1f} {unit}"
+            size_bytes /= 1024
+        return f"{size_bytes:.1f} TB"
+
+    def print(self) -> None:
+        """Print the report to stdout."""
+        console = Console()
+        self._print_to_console(console)
+
+    def to_dict(self) -> dict:
+        """Convert report to dictionary."""
+        return {
+            "source": self.source,
+            "row_count": self.row_count,
+            "column_count": self.column_count,
+            "size_bytes": self.size_bytes,
+            "columns": self.columns,
+        }
+
+    def to_json(self, indent: int = 2) -> str:
+        """Convert report to JSON string."""
+        return json.dumps(self.to_dict(), indent=indent)

truthound/reporters/__init__.py

@@ -0,0 +1,46 @@
+"""Reporters module for generating validation reports.
+
+This module provides a unified interface for generating reports in various
+formats (JSON, HTML, Console, CI/CD platforms) from validation results.
+
+Example:
+    >>> from truthound.reporters import get_reporter
+    >>>
+    >>> # Use factory function
+    >>> reporter = get_reporter("json", output_path="report.json")
+    >>> reporter.report(validation_result)
+    >>>
+    >>> # CI reporter (auto-detect platform)
+    >>> reporter = get_reporter("ci")
+    >>> exit_code = reporter.report_to_ci(validation_result)
+    >>>
+    >>> # Specific CI platform
+    >>> reporter = get_reporter("github")
+    >>> reporter.report_to_ci(validation_result)
+
+Supported CI Platforms:
+    - GitHub Actions: "github"
+    - GitLab CI: "gitlab"
+    - Jenkins: "jenkins"
+    - Azure DevOps: "azure"
+    - CircleCI: "circleci"
+    - Bitbucket Pipelines: "bitbucket"
+    - Auto-detect: "ci"
+"""
+
+from truthound.reporters.base import (
+    BaseReporter,
+    ReporterConfig,
+    ReporterError,
+)
+from truthound.reporters.factory import get_reporter, register_reporter
+
+__all__ = [
+    # Base classes
+    "BaseReporter",
+    "ReporterConfig",
+    "ReporterError",
+    # Factory functions
+    "get_reporter",
+    "register_reporter",
+]

truthound/reporters/_protocols.py

@@ -0,0 +1,30 @@
+"""Protocol definitions for reporter dependencies.
+
+This module defines structural typing protocols for external library clients,
+allowing type-safe code without requiring type stubs packages.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class Jinja2TemplateProtocol(Protocol):
+    """Protocol for Jinja2 Template."""
+
+    def render(self, **context: Any) -> str:
+        """Render the template with given context."""
+        ...
+
+
+@runtime_checkable
+class Jinja2EnvironmentProtocol(Protocol):
+    """Protocol for Jinja2 Environment.
+
+    Defines the minimal interface used by HTMLReporter.
+    """
+
+    def get_template(self, name: str) -> Jinja2TemplateProtocol:
+        """Get a template by name."""
+        ...

truthound/reporters/base.py

@@ -0,0 +1,324 @@
+"""Base classes and interfaces for reporters.
+
+This module defines the abstract base classes and protocols that all reporter
+implementations must follow. Reporters are responsible for transforming
+validation results into human-readable or machine-parseable formats.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Generic, TypeVar
+
+if TYPE_CHECKING:
+    from truthound.stores.results import ValidationResult
+    from truthound.report import Report
+
+
+# =============================================================================
+# Exceptions
+# =============================================================================
+
+
+class ReporterError(Exception):
+    """Base exception for all reporter-related errors."""
+
+    pass
+
+
+class RenderError(ReporterError):
+    """Raised when rendering a report fails."""
+
+    pass
+
+
+class WriteError(ReporterError):
+    """Raised when writing a report to file fails."""
+
+    pass
+
+
+# =============================================================================
+# Configuration
+# =============================================================================
+
+
+@dataclass
+class ReporterConfig:
+    """Base configuration for all reporters.
+
+    Subclasses can extend this with format-specific options.
+
+    Attributes:
+        output_path: Optional path to write the report to.
+        title: Title for the report.
+        include_metadata: Whether to include metadata in the report.
+        include_statistics: Whether to include statistics in the report.
+        include_details: Whether to include detailed issue information.
+        timestamp_format: Format string for timestamps.
+        max_sample_values: Maximum number of sample values to include.
+    """
+
+    output_path: str | Path | None = None
+    title: str = "Truthound Validation Report"
+    include_metadata: bool = True
+    include_statistics: bool = True
+    include_details: bool = True
+    timestamp_format: str = "%Y-%m-%d %H:%M:%S"
+    max_sample_values: int = 5
+
+    def get_output_path(self) -> Path | None:
+        """Get the output path as a Path object."""
+        if self.output_path is None:
+            return None
+        return Path(self.output_path)
+
+
+# =============================================================================
+# Type Variables
+# =============================================================================
+
+ConfigT = TypeVar("ConfigT", bound=ReporterConfig)
+InputT = TypeVar("InputT")
+
+
+# =============================================================================
+# Abstract Base Reporter
+# =============================================================================
+
+
+class BaseReporter(ABC, Generic[ConfigT, InputT]):
+    """Abstract base class for all reporters.
+
+    Reporters transform validation results into various output formats.
+    They can render to strings or write directly to files.
+
+    Type Parameters:
+        ConfigT: The configuration type for this reporter.
+        InputT: The input type this reporter accepts.
+
+    Example:
+        >>> class MyReporter(BaseReporter[MyConfig, ValidationResult]):
+        ...     def render(self, result: ValidationResult) -> str:
+        ...         return f"Status: {result.status}"
+    """
+
+    # Class-level attributes
+    name: str = "base"
+    file_extension: str = ".txt"
+    content_type: str = "text/plain"
+
+    def __init__(self, config: ConfigT | None = None, **kwargs: Any) -> None:
+        """Initialize the reporter with optional configuration.
+
+        Args:
+            config: Reporter configuration. If None, uses default configuration.
+            **kwargs: Additional configuration options to override.
+        """
+        self._config = config or self._default_config()
+
+        # Apply kwargs to config
+        for key, value in kwargs.items():
+            if hasattr(self._config, key):
+                setattr(self._config, key, value)
+
+    @classmethod
+    @abstractmethod
+    def _default_config(cls) -> ConfigT:
+        """Create default configuration for this reporter type."""
+        pass
+
+    @property
+    def config(self) -> ConfigT:
+        """Get the reporter configuration."""
+        return self._config
+
+    # -------------------------------------------------------------------------
+    # Abstract Methods
+    # -------------------------------------------------------------------------
+
+    @abstractmethod
+    def render(self, data: InputT) -> str:
+        """Render the input data to a string.
+
+        Args:
+            data: The data to render.
+
+        Returns:
+            The rendered report as a string.
+
+        Raises:
+            RenderError: If rendering fails.
+        """
+        pass
+
+    # -------------------------------------------------------------------------
+    # Concrete Methods
+    # -------------------------------------------------------------------------
+
+    def render_to_bytes(self, data: InputT, encoding: str = "utf-8") -> bytes:
+        """Render the input data to bytes.
+
+        Args:
+            data: The data to render.
+            encoding: The encoding to use.
+
+        Returns:
+            The rendered report as bytes.
+        """
+        return self.render(data).encode(encoding)
+
+    def write(self, data: InputT, path: str | Path | None = None) -> Path:
+        """Write the rendered report to a file.
+
+        Args:
+            data: The data to render.
+            path: Optional path to write to. Uses config.output_path if not specified.
+
+        Returns:
+            The path where the report was written.
+
+        Raises:
+            WriteError: If no path is specified and config.output_path is None.
+            WriteError: If writing fails.
+        """
+        output_path = Path(path) if path else self._config.get_output_path()
+
+        if output_path is None:
+            raise WriteError(
+                "No output path specified. Either pass a path argument "
+                "or set output_path in the reporter configuration."
+            )
+
+        try:
+            # Create parent directories if needed
+            output_path.parent.mkdir(parents=True, exist_ok=True)
+
+            # Render and write
+            content = self.render(data)
+            output_path.write_text(content, encoding="utf-8")
+
+            return output_path
+
+        except (OSError, IOError) as e:
+            raise WriteError(f"Failed to write report to {output_path}: {e}")
+
+    def report(self, data: InputT, path: str | Path | None = None) -> str:
+        """Generate a report, optionally writing to file.
+
+        This is a convenience method that renders the report and optionally
+        writes it to a file if a path is specified.
+
+        Args:
+            data: The data to render.
+            path: Optional path to write to.
+
+        Returns:
+            The rendered report as a string.
+        """
+        content = self.render(data)
+
+        output_path = Path(path) if path else self._config.get_output_path()
+        if output_path:
+            self.write(data, output_path)
+
+        return content
+
+    def generate_filename(
+        self,
+        data: InputT,
+        timestamp: bool = True,
+    ) -> str:
+        """Generate a filename for the report.
+
+        Args:
+            data: The data being reported (used for naming).
+            timestamp: Whether to include a timestamp in the filename.
+
+        Returns:
+            A generated filename with the appropriate extension.
+        """
+        base_name = self.name
+
+        if timestamp:
+            ts = datetime.now().strftime("%Y%m%d_%H%M%S")
+            base_name = f"{base_name}_{ts}"
+
+        return f"{base_name}{self.file_extension}"
+
+
+# =============================================================================
+# Specialized Reporter Types
+# =============================================================================
+
+
+class ValidationReporter(BaseReporter[ConfigT, "ValidationResult"], Generic[ConfigT]):
+    """Reporter specialized for ValidationResult objects.
+
+    Provides additional helper methods for working with validation results.
+    """
+
+    def get_severity_counts(self, result: "ValidationResult") -> dict[str, int]:
+        """Get counts of issues by severity.
+
+        Args:
+            result: The validation result.
+
+        Returns:
+            Dictionary mapping severity to count.
+        """
+        counts: dict[str, int] = {
+            "critical": 0,
+            "high": 0,
+            "medium": 0,
+            "low": 0,
+        }
+
+        for validator_result in result.results:
+            if not validator_result.success and validator_result.severity:
+                severity = validator_result.severity.lower()
+                if severity in counts:
+                    counts[severity] += 1
+
+        return counts
+
+    def get_column_issues(
+        self,
+        result: "ValidationResult",
+    ) -> dict[str, list[dict[str, Any]]]:
+        """Get issues grouped by column.
+
+        Args:
+            result: The validation result.
+
+        Returns:
+            Dictionary mapping column names to lists of issues.
+        """
+        column_issues: dict[str, list[dict[str, Any]]] = {}
+
+        for validator_result in result.results:
+            if not validator_result.success:
+                column = validator_result.column or "_table_"
+                if column not in column_issues:
+                    column_issues[column] = []
+                column_issues[column].append({
+                    "validator": validator_result.validator_name,
+                    "issue_type": validator_result.issue_type,
+                    "count": validator_result.count,
+                    "severity": validator_result.severity,
+                    "message": validator_result.message,
+                })
+
+        return column_issues
+
+
+class ReportReporter(BaseReporter[ConfigT, "Report"], Generic[ConfigT]):
+    """Reporter specialized for Report objects (legacy format).
+
+    Provides compatibility with the existing Report class.
+    """
+
+    pass