kontra 0.5.2__py3-none-any.whl

kontra/rules/builtin/freshness.py

@@ -0,0 +1,240 @@
+from __future__ import annotations
+
+"""
+Freshness Rule - validates that a timestamp column has recent data.
+
+Usage in contract:
+  - name: freshness
+    params:
+      column: updated_at
+      max_age: "24h"  # or "1d", "30m", "7d", etc.
+
+Supported time units:
+  - s, sec, second(s): seconds
+  - m, min, minute(s): minutes
+  - h, hr, hour(s): hours
+  - d, day(s): days
+  - w, week(s): weeks
+
+The rule passes if MAX(column) >= NOW() - max_age.
+"""
+
+import re
+from datetime import datetime, timedelta, timezone
+from typing import Any, Dict, Optional, Set
+
+import polars as pl
+
+from kontra.rules.base import BaseRule
+from kontra.rules.predicates import Predicate
+from kontra.rules.registry import register_rule
+from kontra.state.types import FailureMode
+
+
+def parse_duration(duration_str: str) -> timedelta:
+    """
+    Parse a human-readable duration string into a timedelta.
+
+    Examples:
+        "24h" -> 24 hours
+        "1d" -> 1 day
+        "30m" -> 30 minutes
+        "7 days" -> 7 days
+        "2w" -> 2 weeks
+        "1h30m" -> 1 hour 30 minutes
+        "2d12h" -> 2 days 12 hours
+    """
+    duration_str = duration_str.strip().lower()
+
+    # Map unit variations to timedelta kwargs
+    unit_map = {
+        's': 'seconds', 'sec': 'seconds', 'second': 'seconds', 'seconds': 'seconds',
+        'm': 'minutes', 'min': 'minutes', 'minute': 'minutes', 'minutes': 'minutes',
+        'h': 'hours', 'hr': 'hours', 'hour': 'hours', 'hours': 'hours',
+        'd': 'days', 'day': 'days', 'days': 'days',
+        'w': 'weeks', 'week': 'weeks', 'weeks': 'weeks',
+    }
+
+    # Find all number+unit pairs (e.g., "1h30m" -> [("1", "h"), ("30", "m")])
+    pattern = r'(\d+(?:\.\d+)?)\s*([a-z]+)'
+    matches = re.findall(pattern, duration_str)
+
+    if not matches:
+        raise ValueError(f"Invalid duration format: '{duration_str}'. Expected format like '24h', '1d', '30m', '1h30m'")
+
+    # Verify that the matches cover the entire string (no unmatched parts)
+    reconstructed = ''.join(f'{v}{u}' for v, u in matches)
+    # Remove spaces from original for comparison
+    original_no_spaces = re.sub(r'\s+', '', duration_str)
+    if reconstructed != original_no_spaces:
+        raise ValueError(f"Invalid duration format: '{duration_str}'. Expected format like '24h', '1d', '30m', '1h30m'")
+
+    # Accumulate timedelta components
+    total = timedelta()
+    for value_str, unit in matches:
+        value = float(value_str)
+        if unit not in unit_map:
+            raise ValueError(f"Unknown time unit: '{unit}'. Supported: s, m, h, d, w (or full names)")
+        total += timedelta(**{unit_map[unit]: value})
+
+    return total
+
+
+@register_rule("freshness")
+class FreshnessRule(BaseRule):
+    """
+    Validates that a timestamp column contains recent data.
+
+    The rule checks if the maximum value in the timestamp column
+    is within the specified max_age from the current time.
+
+    Parameters:
+        column: The timestamp column to check
+        max_age: Maximum age allowed (e.g., "24h", "1d", "30m")
+    """
+
+    def __init__(self, name: str, params: Dict[str, Any]):
+        super().__init__(name, params)
+        self._validate_params()
+
+    def _validate_params(self) -> None:
+        if "column" not in self.params:
+            raise ValueError("freshness rule requires 'column' parameter")
+        if "max_age" not in self.params:
+            raise ValueError("freshness rule requires 'max_age' parameter")
+        # Validate max_age is parseable
+        parse_duration(str(self.params["max_age"]))
+
+    def required_columns(self) -> Set[str]:
+        return {self.params["column"]}
+
+    def validate(self, df: pl.DataFrame) -> Dict[str, Any]:
+        column = self.params["column"]
+        max_age = parse_duration(str(self.params["max_age"]))
+
+        # Check column exists before accessing
+        col_check = self._check_columns(df, {column})
+        if col_check is not None:
+            return col_check
+
+        # Check column dtype is datetime-compatible
+        col_dtype = df[column].dtype
+        datetime_types = (pl.Datetime, pl.Date)
+        is_datetime_type = isinstance(col_dtype, datetime_types) or col_dtype in datetime_types
+
+        if not is_datetime_type:
+            # Check if it's a string that might be parseable
+            if col_dtype not in (pl.Utf8, getattr(pl, "String", pl.Utf8)):
+                return {
+                    "rule_id": self.rule_id,
+                    "passed": False,
+                    "failed_count": df.height,
+                    "message": f"Column '{column}' must be a datetime type for freshness check (found {col_dtype})",
+                }
+
+        # Get the maximum timestamp
+        max_ts = df[column].max()
+
+        if max_ts is None:
+            return {
+                "rule_id": self.rule_id,
+                "passed": False,
+                "failed_count": df.height,
+                "message": f"Column '{column}' has no non-null timestamps",
+            }
+
+        # Convert to datetime if needed
+        if isinstance(max_ts, datetime):
+            max_datetime = max_ts
+        else:
+            # Try to handle various timestamp types (including strings)
+            try:
+                max_datetime = datetime.fromisoformat(str(max_ts).replace('Z', '+00:00'))
+            except (ValueError, AttributeError):
+                return {
+                    "rule_id": self.rule_id,
+                    "passed": False,
+                    "failed_count": df.height,
+                    "message": f"Column '{column}' contains values that cannot be parsed as datetime (got: {type(max_ts).__name__})",
+                }
+
+        # Get current time (use UTC for consistency)
+        now = datetime.now(timezone.utc)
+
+        # Make max_datetime timezone-aware if it isn't
+        if hasattr(max_datetime, 'tzinfo') and max_datetime.tzinfo is None:
+            max_datetime = max_datetime.replace(tzinfo=timezone.utc)
+
+        threshold = now - max_age
+
+        # Check if the most recent data is fresh enough
+        is_fresh = max_datetime >= threshold
+
+        if is_fresh:
+            return {
+                "rule_id": self.rule_id,
+                "passed": True,
+                "failed_count": 0,
+                "message": "Passed",
+            }
+        else:
+            age = now - max_datetime
+            return {
+                "rule_id": self.rule_id,
+                "passed": False,
+                "failed_count": 1,
+                "message": f"Data is stale: most recent record is {_format_timedelta(age)} old (max allowed: {self.params['max_age']})",
+                "failure_mode": str(FailureMode.FRESHNESS_LAG),
+                "details": {
+                    "latest_timestamp": max_datetime.isoformat(),
+                    "threshold_timestamp": threshold.isoformat(),
+                    "actual_age_seconds": int(age.total_seconds()),
+                    "max_age_seconds": int(max_age.total_seconds()),
+                    "max_age_spec": str(self.params["max_age"]),
+                },
+            }
+
+    def compile_predicate(self) -> Optional[Predicate]:
+        # Freshness is an aggregate check (MAX), not row-level
+        # Cannot be vectorized as a per-row predicate
+        return None
+
+    def to_sql_spec(self) -> Optional[Dict[str, Any]]:
+        """Generate SQL spec for pushdown execution."""
+        column = self.params.get("column")
+        max_age = self.params.get("max_age")
+
+        if not (column and max_age):
+            return None
+
+        try:
+            td = parse_duration(str(max_age))
+            # Convert to total seconds for SQL
+            total_seconds = int(td.total_seconds())
+        except ValueError:
+            return None
+
+        return {
+            "kind": "freshness",
+            "rule_id": self.rule_id,
+            "column": column,
+            "max_age_seconds": total_seconds,
+        }
+
+
+def _format_timedelta(td: timedelta) -> str:
+    """Format a timedelta in human-readable form."""
+    total_seconds = int(td.total_seconds())
+
+    if total_seconds < 60:
+        return f"{total_seconds}s"
+    elif total_seconds < 3600:
+        return f"{total_seconds // 60}m"
+    elif total_seconds < 86400:
+        hours = total_seconds // 3600
+        mins = (total_seconds % 3600) // 60
+        return f"{hours}h {mins}m" if mins else f"{hours}h"
+    else:
+        days = total_seconds // 86400
+        hours = (total_seconds % 86400) // 3600
+        return f"{days}d {hours}h" if hours else f"{days}d"

kontra/rules/builtin/length.py

@@ -0,0 +1,193 @@
+# src/kontra/rules/builtin/length.py
+"""
+Length rule - Column string length must be within specified bounds.
+
+Usage:
+    - name: length
+      params:
+        column: username
+        min: 3
+        max: 50
+
+Fails when:
+    - String length < min (if min specified)
+    - String length > max (if max specified)
+    - Value is NULL (can't measure length of NULL)
+
+At least one of `min` or `max` must be specified.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Set, 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("length")
+class LengthRule(BaseRule):
+    """
+    Fails where string length is outside [min, max] bounds.
+
+    params:
+      - column: str (required) - Column to check
+      - min: int (optional) - Minimum length (inclusive)
+      - max: int (optional) - Maximum length (inclusive)
+
+    At least one of min or max must be provided.
+
+    NULL handling:
+      - NULL values are failures (can't measure length of NULL)
+    """
+
+    def __init__(self, name: str, params: Dict[str, Any]):
+        super().__init__(name, params)
+        self._column = self._get_required_param("column", str)
+        self._min_len: Optional[int] = params.get("min")
+        self._max_len: Optional[int] = params.get("max")
+
+        # Validate at least one bound is provided
+        if self._min_len is None and self._max_len is None:
+            raise ValueError(
+                f"Rule 'length' requires at least one of 'min' or 'max' parameters"
+            )
+
+        # Validate min <= max if both provided
+        if self._min_len is not None and self._max_len is not None:
+            if self._min_len > self._max_len:
+                raise ValueError(
+                    f"Rule 'length' min ({self._min_len}) must be <= max ({self._max_len})"
+                )
+
+        # Validate non-negative
+        if self._min_len is not None and self._min_len < 0:
+            raise ValueError(f"Rule 'length' min must be non-negative, got {self._min_len}")
+        if self._max_len is not None and self._max_len < 0:
+            raise ValueError(f"Rule 'length' max must be non-negative, got {self._max_len}")
+
+    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
+
+        # Get string length (cast to string first to handle non-string columns)
+        length_col = df[self._column].cast(pl.Utf8).str.len_chars()
+
+        # Build mask: True = failure
+        mask = df[self._column].is_null()  # NULL is failure
+
+        if self._min_len is not None:
+            mask = mask | (length_col < self._min_len)
+        if self._max_len is not None:
+            mask = mask | (length_col > self._max_len)
+
+        # Build message
+        if self._min_len is not None and self._max_len is not None:
+            msg = f"{self._column} length not in range [{self._min_len}, {self._max_len}]"
+        elif self._min_len is not None:
+            msg = f"{self._column} length < {self._min_len}"
+        else:
+            msg = f"{self._column} length > {self._max_len}"
+
+        res = super()._failures(df, mask, msg)
+        res["rule_id"] = self.rule_id
+
+        if res["failed_count"] > 0:
+            res["failure_mode"] = str(FailureMode.RANGE_VIOLATION)
+            res["details"] = self._explain_failure(df, length_col, mask)
+
+        return res
+
+    def _explain_failure(
+        self, df: pl.DataFrame, length_col: pl.Series, mask: pl.Series
+    ) -> Dict[str, Any]:
+        """Generate detailed failure explanation."""
+        details: Dict[str, Any] = {
+            "column": self._column,
+        }
+        if self._min_len is not None:
+            details["min_length"] = self._min_len
+        if self._max_len is not None:
+            details["max_length"] = self._max_len
+
+        # Sample failing values with their lengths
+        failed_df = df.filter(mask).with_columns(
+            length_col.filter(mask).alias("_length")
+        ).head(5)
+
+        samples: List[Dict[str, Any]] = []
+        for row in failed_df.iter_rows(named=True):
+            val = row[self._column]
+            length = row.get("_length")
+            samples.append({
+                "value": val,
+                "length": length,
+            })
+
+        if samples:
+            details["sample_failures"] = samples
+
+        return details
+
+    def compile_predicate(self) -> Optional[Predicate]:
+        # Get string length
+        length_expr = pl.col(self._column).cast(pl.Utf8).str.len_chars()
+
+        # Build mask: True = failure
+        expr = pl.col(self._column).is_null()
+
+        if self._min_len is not None:
+            expr = expr | (length_expr < self._min_len)
+        if self._max_len is not None:
+            expr = expr | (length_expr > self._max_len)
+
+        # Build message
+        if self._min_len is not None and self._max_len is not None:
+            msg = f"{self._column} length not in range [{self._min_len}, {self._max_len}]"
+        elif self._min_len is not None:
+            msg = f"{self._column} length < {self._min_len}"
+        else:
+            msg = f"{self._column} length > {self._max_len}"
+
+        return Predicate(
+            rule_id=self.rule_id,
+            expr=expr,
+            message=msg,
+            columns={self._column},
+        )
+
+    def to_sql_spec(self) -> Optional[Dict[str, Any]]:
+        """Generate SQL pushdown specification."""
+        return {
+            "kind": "length",
+            "rule_id": self.rule_id,
+            "column": self._column,
+            "min": self._min_len,
+            "max": self._max_len,
+        }
+
+    def to_sql_filter(self, dialect: str = "postgres") -> str | None:
+        """Generate SQL filter for sampling failing rows."""
+        col = f'"{self._column}"'
+
+        # SQL Server uses LEN(), others use LENGTH()
+        if dialect in ("mssql", "sqlserver"):
+            len_func = f"LEN({col})"
+        else:
+            len_func = f"LENGTH({col})"
+
+        conditions = [f"{col} IS NULL"]
+        if self._min_len is not None:
+            conditions.append(f"{len_func} < {self._min_len}")
+        if self._max_len is not None:
+            conditions.append(f"{len_func} > {self._max_len}")
+
+        return " OR ".join(conditions)

kontra/rules/builtin/max_rows.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+from typing import Dict, Any, Optional
+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("max_rows")
+class MaxRowsRule(BaseRule):
+    def validate(self, df: pl.DataFrame) -> Dict[str, Any]:
+        # Accept both 'value' and 'threshold' for backwards compatibility
+        max_count = int(self.params.get("value", self.params.get("threshold", 0)))
+        h = int(df.height)
+        passed = h <= max_count
+
+        result: Dict[str, Any] = {
+            "rule_id": self.rule_id,
+            "passed": passed,
+            "failed_count": 0 if passed else (h - max_count),
+            "message": f"Dataset has {h} rows, exceeds max {max_count}",
+        }
+
+        if not passed:
+            result["failure_mode"] = str(FailureMode.ROW_COUNT_HIGH)
+            result["details"] = {
+                "actual_rows": h,
+                "maximum_allowed": max_count,
+                "excess": h - max_count,
+            }
+
+        return result
+
+    def compile_predicate(self):
+        return None  # dataset-level scalar check

kontra/rules/builtin/min_rows.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+from typing import Dict, Any, Optional
+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("min_rows")
+class MinRowsRule(BaseRule):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        # Validate threshold at construction time
+        threshold = self.params.get("value", self.params.get("threshold", 0))
+        if threshold is not None and int(threshold) < 0:
+            from kontra.errors import RuleParameterError
+            raise RuleParameterError(
+                "min_rows", "threshold",
+                f"must be non-negative, got {threshold}"
+            )
+
+    def validate(self, df: pl.DataFrame) -> Dict[str, Any]:
+        # Accept both 'value' and 'threshold' for backwards compatibility
+        min_count = int(self.params.get("value", self.params.get("threshold", 0)))
+        h = int(df.height)
+        passed = h >= min_count
+
+        result: Dict[str, Any] = {
+            "rule_id": self.rule_id,
+            "passed": passed,
+            "failed_count": 0 if passed else (min_count - h),
+            "message": f"Dataset has {h} rows, requires at least {min_count}",
+        }
+
+        if not passed:
+            result["failure_mode"] = str(FailureMode.ROW_COUNT_LOW)
+            result["details"] = {
+                "actual_rows": h,
+                "minimum_required": min_count,
+                "shortfall": min_count - h,
+            }
+
+        return result
+
+    def compile_predicate(self):
+        return None  # dataset-level scalar check

kontra/rules/builtin/not_null.py

@@ -0,0 +1,121 @@
+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("not_null")
+class NotNullRule(BaseRule):
+    """
+    Fails where column contains NULL values.
+
+    params:
+      - column: str (required) - Column to check
+      - include_nan: bool (optional, default: False) - Also treat NaN as null
+
+    Note: By default, NaN values are NOT considered null (Polars behavior).
+    Set include_nan=True to catch both NULL and NaN values.
+    """
+
+    def __init__(self, name: str, params: Dict[str, Any]):
+        super().__init__(name, params)
+        # Validate required parameter at construction time
+        self._get_required_param("column", str)
+
+    def validate(self, df: pl.DataFrame) -> Dict[str, Any]:
+        column = self.params["column"]
+        include_nan = self.params.get("include_nan", False)
+
+        # Check column exists before accessing
+        col_check = self._check_columns(df, {column})
+        if col_check is not None:
+            return col_check
+
+        # Build mask for null (and optionally NaN) values
+        mask = df[column].is_null()
+        if include_nan:
+            # For numeric columns, also check for NaN
+            col = df[column]
+            if col.dtype.is_float():
+                mask = mask | col.is_nan()
+
+        message = f"{column} contains null values"
+        if include_nan:
+            message = f"{column} contains null or NaN values"
+
+        res = super()._failures(df, mask, message)
+        res["rule_id"] = self.rule_id
+
+        # Add failure details
+        if res["failed_count"] > 0:
+            res["failure_mode"] = str(FailureMode.NULL_VALUES)
+            res["details"] = self._explain_failure(df, column, res["failed_count"], include_nan)
+
+        return res
+
+    def _explain_failure(
+        self, df: pl.DataFrame, column: str, null_count: int, include_nan: bool = False
+    ) -> Dict[str, Any]:
+        """Generate detailed failure explanation."""
+        total_rows = df.height
+        null_rate = null_count / total_rows if total_rows > 0 else 0
+
+        details: Dict[str, Any] = {
+            "null_count": null_count,
+            "null_rate": round(null_rate, 4),
+            "total_rows": total_rows,
+        }
+
+        if include_nan:
+            details["includes_nan"] = True
+
+        # Find sample row positions with nulls (first 5)
+        if null_count > 0 and null_count <= 1000:
+            null_positions: List[int] = []
+            col = df[column]
+            for i, val in enumerate(col):
+                if val is None:
+                    null_positions.append(i)
+                    if len(null_positions) >= 5:
+                        break
+            if null_positions:
+                details["sample_positions"] = null_positions
+
+        return details
+
+    def compile_predicate(self) -> Optional[Predicate]:
+        column = self.params["column"]
+        include_nan = self.params.get("include_nan", False)
+
+        expr = pl.col(column).is_null()
+        message = f"{column} contains null values"
+
+        if include_nan:
+            # Note: is_nan() only works on float columns, but compile_predicate
+            # doesn't have access to the DataFrame schema. The expression will
+            # be evaluated at runtime where Polars handles type checking.
+            expr = expr | pl.col(column).is_nan()
+            message = f"{column} contains null or NaN values"
+
+        return Predicate(
+            rule_id=self.rule_id,
+            expr=expr,
+            message=message,
+            columns={column},
+        )
+
+    def to_sql_filter(self, dialect: str = "postgres") -> str | None:
+        column = self.params["column"]
+        include_nan = self.params.get("include_nan", False)
+
+        # Quote column name for safety
+        col = f'"{column}"'
+
+        if include_nan:
+            # NaN check: value != value is true for NaN
+            return f"{col} IS NULL OR {col} != {col}"
+        else:
+            return f"{col} IS NULL"