kontra 0.5.2__py3-none-any.whl

kontra/rules/builtin/range.py

@@ -0,0 +1,222 @@
+from __future__ import annotations
+from typing import Dict, Any, Optional, Union
+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("range")
+class RangeRule(BaseRule):
+    """
+    Fails where `column` is outside the specified range [min, max].
+    At least one of `min` or `max` must be provided.
+
+    params:
+      - column: str (required)
+      - min: numeric (optional) - minimum allowed value (inclusive)
+      - max: numeric (optional) - maximum allowed value (inclusive)
+
+    NULLs are treated as failures (out of range).
+
+    Examples:
+      - name: range
+        params:
+          column: age
+          min: 0
+          max: 120
+
+      - name: range
+        params:
+          column: price
+          min: 0  # Only minimum, no upper bound
+    """
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        from kontra.errors import RuleParameterError
+
+        # Validate required column param
+        self._get_required_param("column", str)
+
+        min_val = self.params.get("min")
+        max_val = self.params.get("max")
+
+        # Validate at least one bound is provided
+        if min_val is None and max_val is None:
+            raise RuleParameterError(
+                "range", "min/max",
+                "at least one of 'min' or 'max' must be provided"
+            )
+
+        # Validate min <= max at construction time
+        if min_val is not None and max_val is not None:
+            if min_val > max_val:
+                raise RuleParameterError(
+                    "range", "min/max",
+                    f"min ({min_val}) must be <= max ({max_val})"
+                )
+
+    def validate(self, df: pl.DataFrame) -> Dict[str, Any]:
+        column = self.params["column"]
+        min_val = self.params.get("min")
+        max_val = self.params.get("max")
+
+        # Check column exists before accessing
+        col_check = self._check_columns(df, {column})
+        if col_check is not None:
+            return col_check
+
+        # Note: min/max validation is done in __init__, so we know at least one is set
+        try:
+            col = df[column]
+
+            # Build condition for out-of-range values
+            if min_val is not None and max_val is not None:
+                mask = (col < min_val) | (col > max_val)
+            elif min_val is not None:
+                mask = col < min_val
+            else:
+                mask = col > max_val
+
+            # NULLs are also failures
+            mask = mask.fill_null(True)
+
+            res = super()._failures(df, mask, self._build_message(column, min_val, max_val))
+            res["rule_id"] = self.rule_id
+
+            # Add failure details
+            if res["failed_count"] > 0:
+                res["failure_mode"] = str(FailureMode.RANGE_VIOLATION)
+                res["details"] = self._explain_failure(df, column, min_val, max_val)
+
+            return res
+        except Exception as e:
+            return {
+                "rule_id": self.rule_id,
+                "passed": False,
+                "failed_count": int(df.height),
+                "message": f"Rule execution failed: {e}",
+            }
+
+    def _explain_failure(
+        self,
+        df: pl.DataFrame,
+        column: str,
+        min_val: Optional[Union[int, float]],
+        max_val: Optional[Union[int, float]],
+    ) -> Dict[str, Any]:
+        """Generate detailed failure explanation."""
+        col = df[column]
+        details: Dict[str, Any] = {}
+
+        # Get actual min/max
+        actual_min = col.min()
+        actual_max = col.max()
+        if actual_min is not None:
+            details["actual_min"] = actual_min
+        if actual_max is not None:
+            details["actual_max"] = actual_max
+
+        # Expected bounds
+        if min_val is not None:
+            details["expected_min"] = min_val
+        if max_val is not None:
+            details["expected_max"] = max_val
+
+        # Count below min
+        if min_val is not None:
+            below_min = (col < min_val).sum()
+            if below_min > 0:
+                details["below_min_count"] = int(below_min)
+
+        # Count above max
+        if max_val is not None:
+            above_max = (col > max_val).sum()
+            if above_max > 0:
+                details["above_max_count"] = int(above_max)
+
+        # Count nulls
+        null_count = col.null_count()
+        if null_count > 0:
+            details["null_count"] = int(null_count)
+
+        return details
+
+    def compile_predicate(self) -> Optional[Predicate]:
+        column = self.params["column"]
+        min_val = self.params.get("min")
+        max_val = self.params.get("max")
+
+        if min_val is None and max_val is None:
+            return None
+
+        col = pl.col(column)
+
+        # Build expression for out-of-range values
+        if min_val is not None and max_val is not None:
+            expr = (col < min_val) | (col > max_val)
+        elif min_val is not None:
+            expr = col < min_val
+        else:
+            expr = col > max_val
+
+        # NULLs are also failures
+        expr = expr.fill_null(True)
+
+        return Predicate(
+            rule_id=self.rule_id,
+            expr=expr,
+            message=self._build_message(column, min_val, max_val),
+            columns={column},
+        )
+
+    def to_sql_spec(self) -> Optional[Dict[str, Any]]:
+        """Generate SQL pushdown specification."""
+        column = self.params.get("column")
+        min_val = self.params.get("min")
+        max_val = self.params.get("max")
+
+        if not column or (min_val is None and max_val is None):
+            return None
+
+        return {
+            "kind": "range",
+            "rule_id": self.rule_id,
+            "column": column,
+            "min": min_val,
+            "max": max_val,
+        }
+
+    def _build_message(
+        self, column: str, min_val: Optional[Union[int, float]], max_val: Optional[Union[int, float]]
+    ) -> str:
+        if min_val is not None and max_val is not None:
+            return f"{column} values outside range [{min_val}, {max_val}]"
+        elif min_val is not None:
+            return f"{column} values below minimum {min_val}"
+        else:
+            return f"{column} values above maximum {max_val}"
+
+    def to_sql_filter(self, dialect: str = "postgres") -> str | None:
+        column = self.params.get("column")
+        min_val = self.params.get("min")
+        max_val = self.params.get("max")
+
+        if not column or (min_val is None and max_val is None):
+            return None
+
+        col = f'"{column}"'
+        conditions = []
+
+        if min_val is not None:
+            conditions.append(f"{col} < {min_val}")
+        if max_val is not None:
+            conditions.append(f"{col} > {max_val}")
+
+        # NULL is also a failure
+        conditions.append(f"{col} IS NULL")
+
+        return " OR ".join(conditions)

kontra/rules/builtin/regex.py

@@ -0,0 +1,143 @@
+from __future__ import annotations
+from typing import Dict, Any, List, Optional
+import re
+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
+from kontra.errors import RuleParameterError
+
+
+@register_rule("regex")
+class RegexRule(BaseRule):
+    """
+    Fails where `column` does not match the regex `pattern`. NULLs are failures.
+
+    params:
+      - column: str (required)
+      - pattern: str (required)
+
+    Notes:
+      - Uses vectorized `str.contains` (regex by default in this Polars version).
+      - No `regex=`/`strict=` kwargs are passed to maintain compatibility.
+    """
+
+    def __init__(self, name: str, params: Dict[str, Any]):
+        super().__init__(name, params)
+        # Validate regex pattern early to provide helpful error message
+        pattern = params.get("pattern", "")
+        try:
+            re.compile(pattern)
+        except re.error as e:
+            pos_info = f" at position {e.pos}" if e.pos is not None else ""
+            raise RuleParameterError(
+                "regex",
+                "pattern",
+                f"Invalid regex pattern{pos_info}: {e.msg}\n  Pattern: {pattern}"
+            )
+
+    def validate(self, df: pl.DataFrame) -> Dict[str, Any]:
+        column = self.params["column"]
+        pattern = self.params["pattern"]
+
+        # Check column exists before accessing
+        col_check = self._check_columns(df, {column})
+        if col_check is not None:
+            return col_check
+
+        try:
+            mask = (
+                ~df[column]
+                .cast(pl.Utf8)
+                .str.contains(pattern)  # regex by default
+            ).fill_null(True)
+            res = super()._failures(df, mask, f"{column} failed regex pattern {pattern}")
+            res["rule_id"] = self.rule_id
+
+            # Add failure details
+            if res["failed_count"] > 0:
+                res["failure_mode"] = str(FailureMode.PATTERN_MISMATCH)
+                res["details"] = self._explain_failure(df, column, pattern, mask)
+
+            return res
+        except Exception as e:
+            return {
+                "rule_id": self.rule_id,
+                "passed": False,
+                "failed_count": int(df.height),
+                "message": f"Rule execution failed: {e}",
+            }
+
+    def _explain_failure(
+        self, df: pl.DataFrame, column: str, pattern: str, mask: pl.Series
+    ) -> Dict[str, Any]:
+        """Generate detailed failure explanation."""
+        details: Dict[str, Any] = {
+            "pattern": pattern,
+        }
+
+        # Sample non-matching values (first 5)
+        failed_df = df.filter(mask)
+        if failed_df.height > 0:
+            sample_values: List[Any] = []
+            for val in failed_df[column].head(5):
+                sample_values.append(val)
+            if sample_values:
+                details["sample_mismatches"] = sample_values
+
+        return details
+
+    def compile_predicate(self) -> Optional[Predicate]:
+        column = self.params["column"]
+        pattern = self.params["pattern"]
+        expr = (
+            ~pl.col(column)
+            .cast(pl.Utf8)
+            .str.contains(pattern)  # regex by default
+        ).fill_null(True)
+        return Predicate(
+            rule_id=self.rule_id,
+            expr=expr,
+            message=f"{column} failed regex pattern {pattern}",
+            columns={column},
+        )
+
+    def to_sql_spec(self) -> Optional[Dict[str, Any]]:
+        """Generate SQL pushdown specification for regex rule."""
+        column = self.params.get("column")
+        pattern = self.params.get("pattern")
+
+        if not column or not pattern:
+            return None
+
+        return {
+            "kind": "regex",
+            "rule_id": self.rule_id,
+            "column": column,
+            "pattern": pattern,
+        }
+
+    def to_sql_filter(self, dialect: str = "postgres") -> str | None:
+        column = self.params.get("column")
+        pattern = self.params.get("pattern")
+
+        if not column or not pattern:
+            return None
+
+        col = f'"{column}"'
+        # Escape single quotes in pattern
+        escaped_pattern = pattern.replace("'", "''")
+
+        if dialect in ("postgres", "postgresql"):
+            # PostgreSQL uses ~ for regex match, !~ for non-match
+            return f"{col} !~ '{escaped_pattern}' OR {col} IS NULL"
+        elif dialect == "duckdb":
+            # DuckDB uses regexp_matches
+            return f"NOT regexp_matches({col}, '{escaped_pattern}') OR {col} IS NULL"
+        elif dialect == "mssql":
+            # SQL Server doesn't have native regex - skip SQL filter
+            return None
+        else:
+            return None

kontra/rules/builtin/starts_with.py

@@ -0,0 +1,129 @@
+# src/kontra/rules/builtin/starts_with.py
+"""
+Starts with rule - Column must start with the specified prefix.
+
+Uses LIKE pattern matching for maximum efficiency (faster than regex).
+
+Usage:
+    - name: starts_with
+      params:
+        column: url
+        prefix: "https://"
+
+Fails when:
+    - Value does NOT start with the prefix
+    - Value is NULL (can't check NULL)
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Set
+
+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
+
+
+def _escape_like_pattern(value: str, escape_char: str = "\\") -> str:
+    """Escape LIKE special characters: %, _, and the escape char."""
+    for c in (escape_char, "%", "_"):
+        value = value.replace(c, escape_char + c)
+    return value
+
+
+@register_rule("starts_with")
+class StartsWithRule(BaseRule):
+    """
+    Fails where column value does NOT start with the prefix.
+
+    params:
+      - column: str (required) - Column to check
+      - prefix: str (required) - Prefix that must be present
+
+    NULL handling:
+      - NULL values are failures (can't check NULL)
+    """
+
+    def __init__(self, name: str, params: Dict[str, Any]):
+        super().__init__(name, params)
+        self._column = self._get_required_param("column", str)
+        self._prefix = self._get_required_param("prefix", str)
+
+        if not self._prefix:
+            raise ValueError("Rule 'starts_with' prefix cannot be empty")
+
+    def required_columns(self) -> Set[str]:
+        return {self._column}
+
+    def validate(self, df: pl.DataFrame) -> Dict[str, Any]:
+        # Check column exists before accessing
+        col_check = self._check_columns(df, {self._column})
+        if col_check is not None:
+            return col_check
+
+        # Use Polars str.starts_with for efficiency
+        starts_result = df[self._column].cast(pl.Utf8).str.starts_with(self._prefix)
+
+        # Failure = does NOT start with OR is NULL
+        mask = (~starts_result).fill_null(True)
+
+        msg = f"{self._column} does not start with '{self._prefix}'"
+        res = super()._failures(df, mask, msg)
+        res["rule_id"] = self.rule_id
+
+        if res["failed_count"] > 0:
+            res["failure_mode"] = str(FailureMode.PATTERN_MISMATCH)
+            res["details"] = self._explain_failure(df, mask)
+
+        return res
+
+    def _explain_failure(self, df: pl.DataFrame, mask: pl.Series) -> Dict[str, Any]:
+        """Generate detailed failure explanation."""
+        details: Dict[str, Any] = {
+            "column": self._column,
+            "expected_prefix": self._prefix,
+        }
+
+        # Sample failing values
+        failed_df = df.filter(mask).head(5)
+        samples: List[Any] = []
+        for val in failed_df[self._column]:
+            samples.append(val)
+
+        if samples:
+            details["sample_failures"] = samples
+
+        return details
+
+    def compile_predicate(self) -> Optional[Predicate]:
+        starts_expr = pl.col(self._column).cast(pl.Utf8).str.starts_with(self._prefix)
+        expr = (~starts_expr).fill_null(True)
+
+        return Predicate(
+            rule_id=self.rule_id,
+            expr=expr,
+            message=f"{self._column} does not start with '{self._prefix}'",
+            columns={self._column},
+        )
+
+    def to_sql_spec(self) -> Optional[Dict[str, Any]]:
+        """Generate SQL pushdown specification."""
+        return {
+            "kind": "starts_with",
+            "rule_id": self.rule_id,
+            "column": self._column,
+            "prefix": self._prefix,
+        }
+
+    def to_sql_filter(self, dialect: str = "postgres") -> str | None:
+        """Generate SQL filter for sampling failing rows."""
+        col = f'"{self._column}"'
+
+        # Escape LIKE special characters
+        escaped = _escape_like_pattern(self._prefix)
+        pattern = f"{escaped}%"
+
+        # Failure = does NOT start with OR is NULL
+        return f"{col} IS NULL OR {col} NOT LIKE '{pattern}' ESCAPE '\\'"

kontra/rules/builtin/unique.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+from typing import Dict, Any, List, Optional
+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("unique")
+class UniqueRule(BaseRule):
+    def __init__(self, name: str, params: Dict[str, Any]):
+        super().__init__(name, params)
+        self._get_required_param("column", str)
+
+    def validate(self, df: pl.DataFrame) -> Dict[str, Any]:
+        column = self.params["column"]
+
+        # Check column exists before accessing
+        col_check = self._check_columns(df, {column})
+        if col_check is not None:
+            return col_check
+
+        col = df[column]
+
+        # SQL semantics: COUNT(*) - COUNT(DISTINCT col)
+        # This counts "extra" rows beyond one unique occurrence
+        # NULLs are excluded from DISTINCT count but included in total
+        total_count = len(df)
+        distinct_count = col.n_unique()  # includes NULL as one value if present
+
+        # Adjust for NULL handling: SQL COUNT(DISTINCT) excludes NULLs
+        # but n_unique() counts NULL as a distinct value
+        null_count = col.null_count()
+        if null_count > 0:
+            distinct_count -= 1  # Remove NULL from distinct count
+
+        failed_count = total_count - distinct_count - null_count
+
+        # For sampling, still identify duplicated rows (non-null)
+        non_null_mask = col.is_not_null()
+        duplicates = col.is_duplicated() & non_null_mask
+
+        # Build result manually to use SQL-semantics count
+        res = {
+            "rule_id": self.rule_id,
+            "name": self.name,
+            "passed": failed_count == 0,
+            "failed_count": failed_count,
+            "message": f"{column} has duplicate values" if failed_count > 0 else f"{column} values are unique",
+            "severity": self.params.get("severity", "blocking"),
+        }
+
+        # Add failure details and samples
+        if failed_count > 0:
+            res["failure_mode"] = str(FailureMode.DUPLICATE_VALUES)
+            res["details"] = self._explain_failure(df, column)
+            # Store mask for sampling (still shows all duplicate rows)
+            res["_failure_mask"] = duplicates
+
+        return res
+
+    def _explain_failure(self, df: pl.DataFrame, column: str) -> Dict[str, Any]:
+        """Generate detailed failure explanation."""
+        # Find duplicated values and their counts
+        duplicates_df = (
+            df.group_by(column)
+            .agg(pl.len().alias("count"))
+            .filter(pl.col("count") > 1)
+            .sort("count", descending=True)
+            .head(10)  # Top 10 duplicates
+        )
+
+        top_duplicates: List[Dict[str, Any]] = []
+        for row in duplicates_df.iter_rows(named=True):
+            val = row[column]
+            count = row["count"]
+            top_duplicates.append({
+                "value": val,
+                "count": count,
+            })
+
+        total_duplicates = (
+            df.group_by(column)
+            .agg(pl.len().alias("count"))
+            .filter(pl.col("count") > 1)
+            .height
+        )
+
+        return {
+            "duplicate_value_count": total_duplicates,
+            "top_duplicates": top_duplicates,
+        }
+
+    def compile_predicate(self) -> Optional[Predicate]:
+        # Return None to force fallback to validate() for COUNTING
+        # validate() uses SQL semantics: total - distinct (counts "extra" rows)
+        # Use sample_predicate() for identifying which rows are duplicates
+        return None
+
+    def sample_predicate(self) -> Optional[Predicate]:
+        """Return predicate for sampling duplicate rows (not for counting)."""
+        column = self.params["column"]
+        col = pl.col(column)
+        # Identifies all rows participating in duplicates for sampling
+        # NULLs are not considered duplicates (NULL != NULL in SQL)
+        expr = col.is_duplicated() & col.is_not_null()
+        return Predicate(
+            rule_id=self.rule_id,
+            expr=expr,
+            message=f"{column} has duplicate values",
+            columns={column},
+        )
+
+    def to_sql_filter(self, dialect: str = "postgres") -> str | None:
+        # Unique requires a subquery to find duplicated values
+        # This is more complex but still much faster than loading 1M rows
+        column = self.params["column"]
+        col = f'"{column}"'
+
+        # Find values that appear more than once, then select rows with those values
+        # Note: This requires knowing the table name, which we don't have here
+        # Return None to fall back to Polars for this rule
+        return None