kontra 0.5.2__py3-none-any.whl

kontra/reporters/json_reporter.py

@@ -0,0 +1,190 @@
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from typing import Any, Dict, Iterable, List, Optional
+
+# --- Version handling (robust to early-boot states) ---------------------------
+try:
+    from kontra.version import VERSION as _VERSION
+except Exception:  # pragma: no cover
+    _VERSION = "0.0.0-dev"
+
+SCHEMA_VERSION = "1.0"
+
+# --- Optional JSON Schema validation (non-fatal if missing) -------------------
+try:
+    import fastjsonschema  # type: ignore
+    _HAVE_VALIDATOR = True
+except Exception:  # pragma: no cover
+    _HAVE_VALIDATOR = False
+
+_VALIDATOR = None  # lazy-compiled validator
+
+
+def _utc_now_iso() -> str:
+    """UTC timestamp in stable ISO 8601 format with trailing Z."""
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _normalize_result(item: Dict[str, Any]) -> Dict[str, Any]:
+    passed = bool(item.get("passed", False))
+    msg = str(item.get("message", ""))
+
+    # Always compute from 'passed', ignore incoming 'severity' to keep outputs consistent.
+    severity = "INFO" if passed else "ERROR"
+
+    return {
+        "rule_id": str(item.get("rule_id", "")),
+        "passed": passed,
+        "message": msg,
+        "failed_count": int(item.get("failed_count", 0)),
+        "severity": severity,
+        "actions_executed": list(item.get("actions_executed", [])),
+    }
+
+
+
+def _sorted_results(results: Iterable[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    """Deterministic ordering by rule_id, then message for tie-breaks."""
+    normalized = [_normalize_result(r) for r in results]
+    return sorted(normalized, key=lambda r: (r["rule_id"], r["message"]))
+
+
+def _derive_exec_seconds(summary: Dict[str, Any], stats: Optional[Dict[str, Any]]) -> float:
+    # Prefer summary if provided; else fall back to stats.run_meta.duration_ms_total
+    val = summary.get("execution_time_seconds")
+    if isinstance(val, (int, float)) and val:
+        return float(val)
+    if stats:
+        try:
+            ms = stats.get("run_meta", {}).get("duration_ms_total")
+            if isinstance(ms, (int, float)):
+                return float(ms) / 1000.0
+        except Exception:
+            pass
+    return 0.0
+
+
+def _derive_rows_evaluated(summary: Dict[str, Any], stats: Optional[Dict[str, Any]]) -> int:
+    # Prefer summary if provided; else fall back to stats.dataset.nrows
+    val = summary.get("rows_evaluated")
+    if isinstance(val, int) and val >= 0:
+        return int(val)
+    if stats:
+        try:
+            n = stats.get("dataset", {}).get("nrows")
+            if isinstance(n, int) and n >= 0:
+                return int(n)
+        except Exception:
+            pass
+    return 0
+
+
+def build_payload(
+    *,
+    dataset_name: str,
+    summary: Dict[str, Any],
+    results: List[Dict[str, Any]],
+    stats: Optional[Dict[str, Any]] = None,
+    quarantine: Optional[Dict[str, Any]] = None,
+    schema_version: str = SCHEMA_VERSION,
+    engine_version: Optional[str] = None,
+) -> Dict[str, Any]:
+    """
+    Construct the stable, versioned JSON document for CI/CD and machines.
+    This function is side-effect free and ideal for unit tests.
+    """
+    total = int(summary.get("total_rules", len(results)))
+    passed_count = int(summary.get("rules_passed", sum(1 for r in results if r.get("passed"))))
+    failed_count = int(summary.get("rules_failed", total - passed_count))
+
+    payload: Dict[str, Any] = {
+        "schema_version": str(schema_version),
+        "dataset_name": str(dataset_name),
+        "timestamp_utc": _utc_now_iso(),
+        "engine_version": str(engine_version or _VERSION),
+        "validation_passed": bool(summary.get("passed", failed_count == 0)),
+        "statistics": {
+            "execution_time_seconds": _derive_exec_seconds(summary, stats),
+            "rows_evaluated": _derive_rows_evaluated(summary, stats),
+            "rules_total": total,
+            "rules_passed": passed_count,
+            "rules_failed": failed_count,
+        },
+        "results": _sorted_results(results),
+    }
+
+    if quarantine:
+        payload["quarantine"] = {
+            "location": str(quarantine.get("location", "")),
+            "rows_quarantined": int(quarantine.get("rows_quarantined", 0)),
+        }
+
+    if stats is not None:
+        # Namespaced so the core schema remains stable as stats evolve
+        payload["stats"] = stats
+
+    return payload
+
+
+def render_json(
+    *,
+    dataset_name: str,
+    summary: Dict[str, Any],
+    results: List[Dict[str, Any]],
+    stats: Optional[Dict[str, Any]] = None,
+    quarantine: Optional[Dict[str, Any]] = None,
+    validate: bool = False,
+) -> str:
+    """
+    Build (+ optionally validate) and dump as compact, deterministic JSON.
+    """
+    payload = build_payload(
+        dataset_name=dataset_name,
+        summary=summary,
+        results=results,
+        stats=stats,
+        quarantine=quarantine,
+    )
+
+    if validate and _HAVE_VALIDATOR:
+        _validate_against_local_schema(payload)
+
+    # Deterministic string: stable key order & separators
+    return json.dumps(payload, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+
+
+# --- Optional local schema validation ----------------------------------------
+
+
+def _load_local_schema() -> Optional[Dict[str, Any]]:
+    """
+    Load the local JSON Schema if bundled. Silently returns None if absent.
+    """
+    try:
+        from importlib import resources
+        from importlib.resources import files
+
+        schema_pkg = "schemas"  # repository-level schema package
+        path = files(schema_pkg).joinpath("validation_output.schema.json")
+        with resources.as_file(path) as p:
+            with open(p, "r", encoding="utf-8") as f:
+                return json.load(f)
+    except Exception:
+        return None
+
+
+def _validate_against_local_schema(payload: Dict[str, Any]) -> None:
+    global _VALIDATOR
+    if not _HAVE_VALIDATOR:
+        return
+    if _VALIDATOR is None:
+        schema = _load_local_schema()
+        if not schema:
+            return  # schema not bundled; skip validation
+        _VALIDATOR = fastjsonschema.compile(schema)  # type: ignore
+    _VALIDATOR(payload)  # type: ignore
+
+
+__all__ = ["build_payload", "render_json", "SCHEMA_VERSION"]

kontra/reporters/rich_reporter.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from rich.console import Console
+
+_console = Console()
+
+def report_success(msg: str) -> None:
+    _console.print(f"[bold green]✅ {msg}[/bold green]")
+
+def report_failure(msg: str) -> None:
+    _console.print(f"[bold red]❌ {msg}[/bold red]")

kontra/rules/__init__.py

@@ -0,0 +1,35 @@
+# src/kontra/rules/__init__.py
+"""
+Kontra rules module - Rule definitions and execution planning.
+
+Public API:
+    - BaseRule: Abstract base class for custom rules
+    - RuleFactory: Creates rule instances from contract specs
+    - RuleExecutionPlan: Plans and executes rule validation
+
+Built-in rules are auto-registered when kontra.engine is imported.
+"""
+
+from kontra.rules.base import BaseRule
+from kontra.rules.factory import RuleFactory
+from kontra.rules.execution_plan import RuleExecutionPlan, CompiledPlan
+from kontra.rules.predicates import Predicate
+from kontra.rules.registry import (
+    register_rule,
+    get_rule,
+    get_all_rule_names,
+)
+
+__all__ = [
+    # Base classes
+    "BaseRule",
+    "Predicate",
+    # Factory and planning
+    "RuleFactory",
+    "RuleExecutionPlan",
+    "CompiledPlan",
+    # Registry
+    "register_rule",
+    "get_rule",
+    "get_all_rule_names",
+]

kontra/rules/base.py

@@ -0,0 +1,186 @@
+# src/contra/rules/base.py
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Set
+import polars as pl
+
+class BaseRule(ABC):
+    """
+    Abstract base class for all validation rules.
+    """
+
+    name: str
+    params: Dict[str, Any]
+
+    def __init__(self, name: str, params: Dict[str, Any]):
+        self.name = name
+        self.params = params
+        # rule_id is set by the factory (based on id/name/column)
+        self.rule_id: str = name
+        # severity is set by the factory (from contract spec)
+        self.severity: str = "blocking"
+        # context is set by the factory (from contract spec)
+        # Consumer-defined metadata, ignored by validation
+        self.context: Dict[str, Any] = {}
+    
+    def __str__(self) -> str:
+        return f"{self.name}({self.params})"
+
+    def __repr__(self) -> str:
+        return str(self)
+
+    @abstractmethod
+    def validate(self, df: pl.DataFrame) -> Dict[str, Any]:
+        """Executes validation on a Polars DataFrame and returns a result dict."""
+        ...
+
+    # NEW: rules can declare columns they need even if not vectorizable
+    def required_columns(self) -> Set[str]:
+        """
+        Columns this rule requires to run `validate()`.
+        Default: none. Override in dataset/column rules that read specific columns.
+        """
+        return set()
+
+    def _get_required_param(self, key: str, param_type: type = str) -> Any:
+        """
+        Get a required parameter, raising a clear error if missing or wrong type.
+
+        Args:
+            key: Parameter name
+            param_type: Expected type (default: str)
+
+        Returns:
+            The parameter value
+
+        Raises:
+            ValueError: If parameter is missing or has wrong type
+        """
+        if key not in self.params:
+            raise ValueError(
+                f"Rule '{self.name}' requires parameter '{key}' but it was not provided"
+            )
+        value = self.params[key]
+        if not isinstance(value, param_type):
+            raise ValueError(
+                f"Rule '{self.name}' parameter '{key}' must be {param_type.__name__}, "
+                f"got {type(value).__name__}"
+            )
+        return value
+
+    def _get_optional_param(self, key: str, default: Any = None) -> Any:
+        """
+        Get an optional parameter with a default value.
+
+        Args:
+            key: Parameter name
+            default: Default value if not provided
+
+        Returns:
+            The parameter value or default
+        """
+        return self.params.get(key, default)
+
+    def _failures(self, df: pl.DataFrame, mask: pl.Series, message: str) -> Dict[str, Any]:
+        """Utility to summarize failing rows."""
+        failed_count = mask.sum()
+        return {
+            "rule_id": getattr(self, "rule_id", self.name),
+            "passed": failed_count == 0,
+            "failed_count": int(failed_count),
+            "message": message if failed_count > 0 else "Passed",
+        }
+
+    def _check_columns(self, df: pl.DataFrame, columns: Set[str]) -> Dict[str, Any] | None:
+        """
+        Check if required columns exist in the DataFrame.
+
+        Returns a failure result dict if any columns are missing, None if all exist.
+        This allows rules to fail gracefully instead of raising exceptions.
+
+        Args:
+            df: The DataFrame to check
+            columns: Set of required column names
+
+        Returns:
+            Failure result dict if columns missing, None if all present
+        """
+        if not columns:
+            return None
+
+        available = set(df.columns)
+        missing = columns - available
+
+        if not missing:
+            return None
+
+        # Build helpful error message
+        missing_list = sorted(missing)
+        available_list = sorted(available)
+
+        if len(missing_list) == 1:
+            msg = f"Column '{missing_list[0]}' not found"
+        else:
+            msg = f"Columns not found: {', '.join(missing_list)}"
+
+        # Check if data might be nested (single column that looks like a wrapper)
+        nested_hint = ""
+        if len(available) == 1 and len(missing) > 0:
+            nested_hint = ". Data may be nested - Kontra requires flat tabular data"
+
+        from kontra.state.types import FailureMode
+
+        return {
+            "rule_id": getattr(self, "rule_id", self.name),
+            "passed": False,
+            "failed_count": df.height,  # All rows fail if column missing
+            "message": f"{msg}{nested_hint}",
+            "failure_mode": str(FailureMode.CONFIG_ERROR),  # Mark as config issue, not data issue
+            "details": {
+                "missing_columns": missing_list,
+                "available_columns": available_list[:20],  # Limit for readability
+            },
+        }
+
+    def to_sql_filter(self, dialect: str = "postgres") -> str | None:
+        """
+        Return a SQL WHERE clause that matches failing rows.
+
+        Used by sample_failures() to push filtering to the database instead of
+        loading the entire table. Returns None if the rule doesn't support SQL filters.
+
+        Args:
+            dialect: SQL dialect ("postgres", "mssql", "duckdb")
+
+        Returns:
+            SQL WHERE clause string (without "WHERE"), or None if not supported.
+
+        Example:
+            not_null rule returns: "email IS NULL"
+            range rule returns: "amount < 0 OR amount > 100 OR amount IS NULL"
+        """
+        return None
+
+    def to_sql_agg(self, dialect: str = "duckdb") -> str | None:
+        """
+        Return a SQL aggregate expression for counting violations.
+
+        This enables SQL pushdown for custom rules without modifying executors.
+        The executor wraps this as: {expr} AS "{rule_id}"
+
+        Args:
+            dialect: SQL dialect ("duckdb", "postgres", "mssql")
+
+        Returns:
+            SQL aggregate expression string, or None if not supported.
+
+        Example:
+            A "positive" rule checking col > 0:
+            return 'SUM(CASE WHEN "amount" IS NULL OR "amount" <= 0 THEN 1 ELSE 0 END)'
+
+        Note:
+            - Use double quotes for column names: "column"
+            - Return the full aggregate expression (SUM, COUNT, etc.)
+            - Handle NULL appropriately (usually NULL = violation)
+            - For dialect differences, check the dialect parameter
+        """
+        return None

kontra/rules/builtin/__init__.py

@@ -0,0 +1,40 @@
+# Import all builtin rules to register them
+from kontra.rules.builtin.not_null import NotNullRule
+from kontra.rules.builtin.unique import UniqueRule
+from kontra.rules.builtin.dtype import DtypeRule
+from kontra.rules.builtin.range import RangeRule
+from kontra.rules.builtin.allowed_values import AllowedValuesRule
+from kontra.rules.builtin.disallowed_values import DisallowedValuesRule
+from kontra.rules.builtin.regex import RegexRule
+from kontra.rules.builtin.length import LengthRule
+from kontra.rules.builtin.contains import ContainsRule
+from kontra.rules.builtin.starts_with import StartsWithRule
+from kontra.rules.builtin.ends_with import EndsWithRule
+from kontra.rules.builtin.min_rows import MinRowsRule
+from kontra.rules.builtin.max_rows import MaxRowsRule
+from kontra.rules.builtin.freshness import FreshnessRule
+from kontra.rules.builtin.custom_sql_check import CustomSQLCheck
+from kontra.rules.builtin.compare import CompareRule
+from kontra.rules.builtin.conditional_not_null import ConditionalNotNullRule
+from kontra.rules.builtin.conditional_range import ConditionalRangeRule
+
+__all__ = [
+    "NotNullRule",
+    "UniqueRule",
+    "DtypeRule",
+    "RangeRule",
+    "AllowedValuesRule",
+    "DisallowedValuesRule",
+    "RegexRule",
+    "LengthRule",
+    "ContainsRule",
+    "StartsWithRule",
+    "EndsWithRule",
+    "MinRowsRule",
+    "MaxRowsRule",
+    "FreshnessRule",
+    "CustomSQLCheck",
+    "CompareRule",
+    "ConditionalNotNullRule",
+    "ConditionalRangeRule",
+]

kontra/rules/builtin/allowed_values.py

@@ -0,0 +1,156 @@
+from __future__ import annotations
+from typing import Dict, Any, List, Optional, Sequence
+import polars as pl
+
+from kontra.rules.base import BaseRule
+from kontra.rules.registry import register_rule
+from kontra.rules.predicates import Predicate
+from kontra.state.types import FailureMode
+
+@register_rule("allowed_values")
+class AllowedValuesRule(BaseRule):
+    def __init__(self, name: str, params: Dict[str, Any]):
+        super().__init__(name, params)
+        self._get_required_param("column", str)
+        if "values" not in self.params:
+            raise ValueError(
+                f"Rule '{self.name}' requires parameter 'values' but it was not provided"
+            )
+
+    def validate(self, df: pl.DataFrame) -> Dict[str, Any]:
+        column = self.params["column"]
+        values: Sequence[Any] = self.params["values"]
+
+        # Check column exists before accessing
+        col_check = self._check_columns(df, {column})
+        if col_check is not None:
+            return col_check
+
+        allowed_set = set(values)
+        # Check if NULL is explicitly allowed
+        null_allowed = None in allowed_set
+
+        # is_in returns NULL for NULL values, fill_null decides if NULL is violation
+        # If NULL is in allowed values, NULL should NOT be a violation (fill_null(False))
+        # If NULL is not allowed, NULL IS a violation (fill_null(True))
+        mask = (~df[column].is_in(list(values))).fill_null(not null_allowed)
+        res = super()._failures(df, mask, f"{column} contains disallowed values")
+        res["rule_id"] = self.rule_id
+
+        # Add detailed explanation for failures
+        if res["failed_count"] > 0:
+            res["failure_mode"] = str(FailureMode.NOVEL_CATEGORY)
+            res["details"] = self._explain_failure(df, column, allowed_set)
+
+        return res
+
+    def _explain_failure(self, df: pl.DataFrame, column: str, allowed: set) -> Dict[str, Any]:
+        """Generate detailed failure explanation."""
+        col = df[column]
+
+        # Find unexpected values and their counts
+        unexpected = (
+            df.filter(~col.is_in(list(allowed)) & col.is_not_null())
+            .group_by(column)
+            .agg(pl.len().alias("count"))
+            .sort("count", descending=True)
+            .head(10)  # Top 10 unexpected values
+        )
+
+        unexpected_values: List[Dict[str, Any]] = []
+        for row in unexpected.iter_rows(named=True):
+            val = row[column]
+            count = row["count"]
+            unexpected_values.append({
+                "value": val,
+                "count": count,
+            })
+
+        return {
+            "expected": sorted([str(v) for v in allowed]),
+            "unexpected_values": unexpected_values,
+            "suggestion": self._suggest_fix(unexpected_values, allowed) if unexpected_values else None,
+        }
+
+    def _suggest_fix(self, unexpected: List[Dict[str, Any]], allowed: set) -> str:
+        """Suggest how to fix the validation failure."""
+        if not unexpected:
+            return ""
+
+        top_unexpected = unexpected[0]
+        val = top_unexpected["value"]
+        count = top_unexpected["count"]
+
+        # Simple suggestions
+        if count > 100:
+            return f"Consider adding '{val}' to allowed values (found in {count:,} rows)"
+
+        return f"Found {len(unexpected)} unexpected value(s)"
+
+    def compile_predicate(self) -> Optional[Predicate]:
+        column = self.params["column"]
+        values: Sequence[Any] = self.params["values"]
+        # Check if NULL is explicitly allowed
+        null_allowed = None in set(values)
+        # If NULL is allowed, don't treat NULL as violation
+        expr = (~pl.col(column).is_in(values)).fill_null(not null_allowed)
+        return Predicate(
+            rule_id=self.rule_id,
+            expr=expr,
+            message=f"{column} contains disallowed values",
+            columns={column},
+        )
+
+    def to_sql_spec(self) -> Optional[Dict[str, Any]]:
+        """Generate SQL pushdown specification."""
+        column = self.params.get("column")
+        values = self.params.get("values")
+
+        if not column or values is None:
+            return None
+
+        return {
+            "kind": "allowed_values",
+            "rule_id": self.rule_id,
+            "column": column,
+            "values": list(values),
+        }
+
+    def to_sql_filter(self, dialect: str = "postgres") -> str | None:
+        column = self.params["column"]
+        values: Sequence[Any] = self.params["values"]
+
+        col = f'"{column}"'
+
+        # Check if NULL is explicitly allowed
+        null_allowed = None in set(values)
+
+        # Build IN list with proper quoting (exclude None)
+        quoted_values = []
+        for v in values:
+            if v is None:
+                continue  # NULL handled separately
+            elif isinstance(v, str):
+                # Escape single quotes
+                escaped = v.replace("'", "''")
+                quoted_values.append(f"'{escaped}'")
+            elif isinstance(v, bool):
+                quoted_values.append("TRUE" if v else "FALSE")
+            else:
+                quoted_values.append(str(v))
+
+        if quoted_values:
+            in_list = ", ".join(quoted_values)
+            if null_allowed:
+                # NULL is allowed, only non-null disallowed values are violations
+                return f"{col} NOT IN ({in_list}) AND {col} IS NOT NULL"
+            else:
+                # NULL is not allowed, both disallowed values AND NULL are violations
+                return f"{col} NOT IN ({in_list}) OR {col} IS NULL"
+        else:
+            # Only NULL in allowed values (no other values) - everything non-null fails
+            if null_allowed:
+                return f"{col} IS NOT NULL"
+            else:
+                # Empty allowed list, no NULL - everything fails (always true filter)
+                return "1=1"