kontra 0.5.2__py3-none-any.whl

kontra/rules/builtin/disallowed_values.py

@@ -0,0 +1,140 @@
+# src/kontra/rules/builtin/disallowed_values.py
+"""
+Disallowed values rule - Column must NOT contain any of the specified values.
+
+Inverse of allowed_values: fails if value IS in the list.
+
+Usage:
+    - name: disallowed_values
+      params:
+        column: status
+        values: ["deleted", "banned", "spam"]
+
+Fails when:
+    - The column value IS in the disallowed values list
+
+Passes when:
+    - The column value is NOT in the disallowed values list
+    - The column value is NULL (NULL is not in any list)
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Sequence, 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
+
+
+@register_rule("disallowed_values")
+class DisallowedValuesRule(BaseRule):
+    """
+    Fails where column value IS in the disallowed set.
+
+    params:
+      - column: str (required) - Column to check
+      - values: list (required) - Values that are NOT allowed
+
+    NULL handling:
+      - NULL values are NOT failures (NULL is not in any list)
+    """
+
+    def __init__(self, name: str, params: Dict[str, Any]):
+        super().__init__(name, params)
+        self._column = 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"
+            )
+        self._values: Sequence[Any] = self.params["values"]
+
+    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
+
+        # Failure = value IS in the disallowed list (not including NULL)
+        # is_in returns NULL for NULL values, we want NULL -> not a failure
+        mask = df[self._column].is_in(list(self._values)).fill_null(False)
+
+        res = super()._failures(df, mask, f"{self._column} contains disallowed values")
+        res["rule_id"] = self.rule_id
+
+        if res["failed_count"] > 0:
+            res["failure_mode"] = str(FailureMode.NOVEL_CATEGORY)
+            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."""
+        # Find which disallowed values were found and their counts
+        found_values = (
+            df.filter(mask)
+            .group_by(self._column)
+            .agg(pl.len().alias("count"))
+            .sort("count", descending=True)
+            .head(10)
+        )
+
+        found_list: List[Dict[str, Any]] = []
+        for row in found_values.iter_rows(named=True):
+            found_list.append({
+                "value": row[self._column],
+                "count": row["count"],
+            })
+
+        return {
+            "disallowed": [str(v) for v in self._values],
+            "found_values": found_list,
+        }
+
+    def compile_predicate(self) -> Optional[Predicate]:
+        # Failure = value IS in the disallowed list
+        expr = pl.col(self._column).is_in(self._values).fill_null(False)
+        return Predicate(
+            rule_id=self.rule_id,
+            expr=expr,
+            message=f"{self._column} contains disallowed values",
+            columns={self._column},
+        )
+
+    def to_sql_spec(self) -> Optional[Dict[str, Any]]:
+        """Generate SQL pushdown specification."""
+        return {
+            "kind": "disallowed_values",
+            "rule_id": self.rule_id,
+            "column": self._column,
+            "values": list(self._values),
+        }
+
+    def to_sql_filter(self, dialect: str = "postgres") -> str | None:
+        """Generate SQL filter for sampling failing rows."""
+        col = f'"{self._column}"'
+
+        # Build IN list (exclude None values)
+        quoted_values = []
+        for v in self._values:
+            if v is None:
+                continue
+            elif isinstance(v, str):
+                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 not quoted_values:
+            return None  # No values to check
+
+        in_list = ", ".join(quoted_values)
+        # Failure = value IS in the disallowed list (not null)
+        return f"{col} IN ({in_list})"

kontra/rules/builtin/dtype.py

@@ -0,0 +1,203 @@
+from __future__ import annotations
+from typing import Dict, Any, Optional, Set, Tuple
+
+import polars as pl
+
+from kontra.rules.base import BaseRule
+from kontra.rules.registry import register_rule
+from kontra.state.types import FailureMode
+
+
+@register_rule("dtype")
+class DtypeRule(BaseRule):
+    """
+    Dtype — schema-level type check for a single column.
+
+    Params
+    ------
+      - column: str            # required
+      - type:   str            # required
+        Accepts either:
+          * exact physical types: int8/int16/int32/int64, uint8/uint16/uint32/uint64,
+                                  float32/float64 (or float/double as aliases),
+                                  boolean/bool, utf8/string/str/text, date, datetime, time
+          * logical families:    int/integer, float, numeric, string/str
+
+      - mode: "strict"         # optional (default). Future: may support relaxed modes.
+
+    Semantics
+    ---------
+    - Exact types require an exact match (e.g., "int16" passes only if the column is Int16).
+    - Family types accept any member of the family (e.g., "int" accepts Int8/16/32/64).
+    - Strings: "utf8", "string", "str", "text" are treated as the same family (Utf8 or String).
+    - We do NOT cast — we only validate. (Casting hints may come via planner/materializers later.)
+
+    Results
+    -------
+    - On mismatch or invalid config, `failed_count == nrows` (schema-level violation).
+    - Message is deterministic: "<col> expected <expected>, found <ActualDtype>".
+    """
+
+    # Valid type names (for error message)
+    _VALID_TYPES = [
+        # Exact types
+        "int8", "int16", "int32", "int64",
+        "uint8", "uint16", "uint32", "uint64",
+        "float32", "float64", "float", "double",
+        "bool", "boolean",
+        "date", "datetime", "time",
+        "utf8", "string", "str", "text",
+        # Family types
+        "int", "integer", "numeric",
+    ]
+
+    # ---- Aliases / Maps -----------------------------------------------------
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        from kontra.errors import RuleParameterError
+
+        expected_type = self.params.get("type")
+        if expected_type is not None:
+            label, allowed = self._normalize_expected(str(expected_type))
+            if allowed is None:
+                raise RuleParameterError(
+                    "dtype", "type",
+                    f"unknown type '{expected_type}'. Valid types: {', '.join(sorted(self._VALID_TYPES))}"
+                )
+
+    _STRING_ALIASES = {"utf8", "string", "str", "text"}
+
+    # Exact physical types (single-member sets treated as "exact")
+    _EXACT_MAP = {
+        # signed ints
+        "int8": {pl.Int8}, "int16": {pl.Int16}, "int32": {pl.Int32}, "int64": {pl.Int64},
+        # unsigned ints
+        "uint8": {pl.UInt8}, "uint16": {pl.UInt16}, "uint32": {pl.UInt32}, "uint64": {pl.UInt64},
+        # floats
+        "float32": {pl.Float32}, "float64": {pl.Float64},
+        "float": {pl.Float64}, "double": {pl.Float64},  # common aliases treated as exact Float64
+        # booleans
+        "bool": {pl.Boolean}, "boolean": {pl.Boolean},
+        # temporal
+        "date": {pl.Date}, "datetime": {pl.Datetime}, "time": {pl.Time},
+    }
+
+    # Logical families (multi-member sets)
+    _FAMILY_MAP = {
+        "int": {pl.Int8, pl.Int16, pl.Int32, pl.Int64},
+        "integer": {pl.Int8, pl.Int16, pl.Int32, pl.Int64},
+        "float": {pl.Float32, pl.Float64},
+        "numeric": {pl.Int8, pl.Int16, pl.Int32, pl.Int64, pl.Float32, pl.Float64},
+        "string": {pl.Utf8, getattr(pl, "String", pl.Utf8)},  # tolerate both Utf8 and String
+        "str": {pl.Utf8, getattr(pl, "String", pl.Utf8)},
+        "text": {pl.Utf8, getattr(pl, "String", pl.Utf8)},
+        "utf8": {pl.Utf8, getattr(pl, "String", pl.Utf8)},
+    }
+
+    # ---- Normalization ------------------------------------------------------
+
+    @staticmethod
+    def _dtype_label(dt: pl.DataType) -> str:
+        """Stable, user-friendly label for actual dtype in messages."""
+        # Polars dtypes stringify nicely (e.g., "Int64", "Utf8").
+        # Keep that behavior, but ensure Utf8/String variants read cleanly.
+        if dt == pl.Utf8:
+            return "Utf8"
+        # Some Polars versions may have pl.String; prefer "Utf8" in messages for consistency.
+        if getattr(pl, "String", None) and dt == getattr(pl, "String"):
+            return "Utf8"
+        return str(dt)
+
+    def _normalize_expected(self, typ: str) -> Tuple[str, Optional[set]]:
+        """
+        Returns (label, allowed_set).
+          - label: string echoed in error messages ("int16", "int", "date", ...)
+          - allowed_set: a set of acceptable Polars dtypes (None if unknown)
+        """
+        t = (typ or "").strip().lower()
+        if not t:
+            return "<unspecified>", None
+
+        # tolerate hyphen variants like "utf-8"
+        t_no_dash = t.replace("-", "")
+
+        # Family first (covers "string", "str", "utf8", etc.)
+        if t in self._FAMILY_MAP:
+            return t, self._FAMILY_MAP[t]
+        if t_no_dash in self._FAMILY_MAP:
+            return t_no_dash, self._FAMILY_MAP[t_no_dash]
+
+        # Exact physical types (single-member sets)
+        if t in self._EXACT_MAP:
+            return t, self._EXACT_MAP[t]
+
+        return t, None
+
+    # ---- Rule contract ------------------------------------------------------
+
+    def validate(self, df: pl.DataFrame) -> Dict[str, Any]:
+        column = self.params.get("column")
+        expected_type = self.params.get("type")
+        mode = (self.params.get("mode") or "strict").lower()
+
+        if mode != "strict":
+            return {
+                "rule_id": self.rule_id,
+                "passed": False,
+                "failed_count": int(df.height),
+                "message": f"Unsupported dtype mode '{mode}'; only 'strict' is implemented.",
+            }
+
+        if not isinstance(column, str) or not column:
+            return {
+                "rule_id": self.rule_id,
+                "passed": False,
+                "failed_count": int(df.height),
+                "message": "Missing required 'column' parameter for dtype rule",
+            }
+
+        if column not in df.columns:
+            return {
+                "rule_id": self.rule_id,
+                "passed": False,
+                "failed_count": int(df.height),
+                "message": f"Column '{column}' not found for dtype check",
+            }
+
+        label, allowed = self._normalize_expected(str(expected_type) if expected_type is not None else "")
+        if allowed is None:
+            return {
+                "rule_id": self.rule_id,
+                "passed": False,
+                "failed_count": int(df.height),
+                "message": f"Invalid expected dtype '{expected_type}'",
+            }
+
+        actual = df[column].dtype
+        # Use equality comparison instead of set membership because parametric
+        # types like Datetime(time_unit='us') have different hashes than pl.Datetime
+        # but are equal via __eq__
+        passed = any(actual == a for a in allowed)
+
+        result: Dict[str, Any] = {
+            "rule_id": self.rule_id,
+            "passed": bool(passed),
+            "failed_count": 0 if passed else int(df.height),
+            "message": "Passed" if passed else f"{column} expected {label}, found {self._dtype_label(actual)}",
+        }
+
+        if not passed:
+            result["failure_mode"] = str(FailureMode.SCHEMA_DRIFT)
+            result["details"] = {
+                "expected_type": label,
+                "actual_type": self._dtype_label(actual),
+                "column": column,
+            }
+
+        return result
+
+    def required_columns(self) -> Set[str]:
+        # dtype check inspects the column’s dtype; ensure it is loaded (for projection).
+        col = self.params.get("column")
+        return {col} if isinstance(col, str) else set()

kontra/rules/builtin/ends_with.py

@@ -0,0 +1,129 @@
+# src/kontra/rules/builtin/ends_with.py
+"""
+Ends with rule - Column must end with the specified suffix.
+
+Uses LIKE pattern matching for maximum efficiency (faster than regex).
+
+Usage:
+    - name: ends_with
+      params:
+        column: filename
+        suffix: ".csv"
+
+Fails when:
+    - Value does NOT end with the suffix
+    - 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("ends_with")
+class EndsWithRule(BaseRule):
+    """
+    Fails where column value does NOT end with the suffix.
+
+    params:
+      - column: str (required) - Column to check
+      - suffix: str (required) - Suffix 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._suffix = self._get_required_param("suffix", str)
+
+        if not self._suffix:
+            raise ValueError("Rule 'ends_with' suffix 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.ends_with for efficiency
+        ends_result = df[self._column].cast(pl.Utf8).str.ends_with(self._suffix)
+
+        # Failure = does NOT end with OR is NULL
+        mask = (~ends_result).fill_null(True)
+
+        msg = f"{self._column} does not end with '{self._suffix}'"
+        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_suffix": self._suffix,
+        }
+
+        # 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]:
+        ends_expr = pl.col(self._column).cast(pl.Utf8).str.ends_with(self._suffix)
+        expr = (~ends_expr).fill_null(True)
+
+        return Predicate(
+            rule_id=self.rule_id,
+            expr=expr,
+            message=f"{self._column} does not end with '{self._suffix}'",
+            columns={self._column},
+        )
+
+    def to_sql_spec(self) -> Optional[Dict[str, Any]]:
+        """Generate SQL pushdown specification."""
+        return {
+            "kind": "ends_with",
+            "rule_id": self.rule_id,
+            "column": self._column,
+            "suffix": self._suffix,
+        }
+
+    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._suffix)
+        pattern = f"%{escaped}"
+
+        # Failure = does NOT end with OR is NULL
+        return f"{col} IS NULL OR {col} NOT LIKE '{pattern}' ESCAPE '\\'"