truthound 1.0.8__py3-none-any.whl

truthound/validators/query/__init__.py

@@ -0,0 +1,91 @@
+"""Query-based validators for flexible data validation.
+
+This module provides 15 query-based validators for SQL and expression-based validation:
+
+Query Result Validators:
+- QueryReturnsSingleValueValidator: Check query returns expected value
+- QueryReturnsNoRowsValidator: Check query returns no rows
+- QueryReturnsRowsValidator: Check query returns rows within bounds
+- QueryResultMatchesValidator: Check query result matches expected DataFrame
+
+Row Count Validators:
+- QueryRowCountValidator: Check row count from query
+- QueryRowCountRatioValidator: Check row count ratio
+- QueryRowCountCompareValidator: Compare row counts between queries
+
+Column Validators:
+- QueryColumnValuesValidator: Check column values from query
+- QueryColumnUniqueValidator: Check column uniqueness in query result
+- QueryColumnNotNullValidator: Check no nulls in query column
+
+Aggregate Validators:
+- QueryAggregateValidator: Check aggregate value bounds
+- QueryGroupAggregateValidator: Check group-level aggregates
+- QueryAggregateCompareValidator: Compare aggregates between queries
+
+Expression Validators:
+- CustomExpressionValidator: Validate with custom Polars expression
+- ConditionalExpressionValidator: IF-THEN validation logic
+- MultiConditionValidator: Multiple conditions with AND/OR
+- RowLevelValidator: Per-row Python function validation
+"""
+
+from truthound.validators.query.base import (
+    QueryValidator,
+    ExpressionValidator,
+)
+from truthound.validators.query.result import (
+    QueryReturnsSingleValueValidator,
+    QueryReturnsNoRowsValidator,
+    QueryReturnsRowsValidator,
+    QueryResultMatchesValidator,
+)
+from truthound.validators.query.row_count import (
+    QueryRowCountValidator,
+    QueryRowCountRatioValidator,
+    QueryRowCountCompareValidator,
+)
+from truthound.validators.query.column import (
+    QueryColumnValuesValidator,
+    QueryColumnUniqueValidator,
+    QueryColumnNotNullValidator,
+)
+from truthound.validators.query.aggregate import (
+    QueryAggregateValidator,
+    QueryGroupAggregateValidator,
+    QueryAggregateCompareValidator,
+)
+from truthound.validators.query.expression import (
+    CustomExpressionValidator,
+    ConditionalExpressionValidator,
+    MultiConditionValidator,
+    RowLevelValidator,
+)
+
+__all__ = [
+    # Base classes
+    "QueryValidator",
+    "ExpressionValidator",
+    # Result validators
+    "QueryReturnsSingleValueValidator",
+    "QueryReturnsNoRowsValidator",
+    "QueryReturnsRowsValidator",
+    "QueryResultMatchesValidator",
+    # Row count validators
+    "QueryRowCountValidator",
+    "QueryRowCountRatioValidator",
+    "QueryRowCountCompareValidator",
+    # Column validators
+    "QueryColumnValuesValidator",
+    "QueryColumnUniqueValidator",
+    "QueryColumnNotNullValidator",
+    # Aggregate validators
+    "QueryAggregateValidator",
+    "QueryGroupAggregateValidator",
+    "QueryAggregateCompareValidator",
+    # Expression validators
+    "CustomExpressionValidator",
+    "ConditionalExpressionValidator",
+    "MultiConditionValidator",
+    "RowLevelValidator",
+]

truthound/validators/query/aggregate.py

@@ -0,0 +1,346 @@
+"""Query-based aggregate validators.
+
+Validators for checking aggregate query results.
+"""
+
+from typing import Any, Literal
+
+import polars as pl
+
+from truthound.types import Severity
+from truthound.validators.base import ValidationIssue
+from truthound.validators.query.base import QueryValidator
+from truthound.validators.registry import register_validator
+
+
+@register_validator
+class QueryAggregateValidator(QueryValidator):
+    """Validates aggregate values from a query.
+
+    Flexible validator for checking any aggregate result.
+
+    Example:
+        # Check average is within range
+        validator = QueryAggregateValidator(
+            query="SELECT AVG(price) as avg_price FROM data",
+            column="avg_price",
+            min_value=10.0,
+            max_value=100.0,
+        )
+
+        # Check sum equals expected
+        validator = QueryAggregateValidator(
+            query="SELECT SUM(quantity) as total FROM data",
+            column="total",
+            expected_value=1000,
+        )
+    """
+
+    name = "query_aggregate"
+    category = "query"
+
+    def __init__(
+        self,
+        query: str,
+        column: str,
+        expected_value: float | int | None = None,
+        min_value: float | int | None = None,
+        max_value: float | int | None = None,
+        tolerance: float | None = None,
+        **kwargs: Any,
+    ):
+        super().__init__(query=query, **kwargs)
+        self.column = column
+        self.expected_value = expected_value
+        self.min_value = min_value
+        self.max_value = max_value
+        self.tolerance = tolerance
+
+    def validate_query_result(
+        self, result: pl.DataFrame, original_lf: pl.LazyFrame
+    ) -> list[ValidationIssue]:
+        issues: list[ValidationIssue] = []
+
+        if len(result) == 0 or self.column not in result.columns:
+            issues.append(
+                ValidationIssue(
+                    column=self.column,
+                    issue_type="query_aggregate_missing",
+                    count=1,
+                    severity=Severity.HIGH,
+                    details=f"Aggregate column '{self.column}' not found or empty result",
+                    expected=f"Column '{self.column}' with value",
+                )
+            )
+            return issues
+
+        actual_value = result[self.column][0]
+
+        if actual_value is None:
+            issues.append(
+                ValidationIssue(
+                    column=self.column,
+                    issue_type="query_aggregate_null",
+                    count=1,
+                    severity=Severity.HIGH,
+                    details=f"Aggregate value is NULL",
+                    expected="Non-null value",
+                )
+            )
+            return issues
+
+        # Check expected value
+        if self.expected_value is not None:
+            if self.tolerance is not None:
+                is_match = abs(actual_value - self.expected_value) <= self.tolerance
+            else:
+                is_match = actual_value == self.expected_value
+
+            if not is_match:
+                issues.append(
+                    ValidationIssue(
+                        column=self.column,
+                        issue_type="query_aggregate_mismatch",
+                        count=1,
+                        severity=Severity.HIGH,
+                        details=f"Aggregate value {actual_value} != expected {self.expected_value}",
+                        expected=str(self.expected_value),
+                        sample_values=[str(actual_value)],
+                    )
+                )
+
+        # Check min value
+        if self.min_value is not None and actual_value < self.min_value:
+            issues.append(
+                ValidationIssue(
+                    column=self.column,
+                    issue_type="query_aggregate_below_min",
+                    count=1,
+                    severity=Severity.HIGH,
+                    details=f"Aggregate value {actual_value} < min {self.min_value}",
+                    expected=f">= {self.min_value}",
+                    sample_values=[str(actual_value)],
+                )
+            )
+
+        # Check max value
+        if self.max_value is not None and actual_value > self.max_value:
+            issues.append(
+                ValidationIssue(
+                    column=self.column,
+                    issue_type="query_aggregate_above_max",
+                    count=1,
+                    severity=Severity.MEDIUM,
+                    details=f"Aggregate value {actual_value} > max {self.max_value}",
+                    expected=f"<= {self.max_value}",
+                    sample_values=[str(actual_value)],
+                )
+            )
+
+        return issues
+
+
+@register_validator
+class QueryGroupAggregateValidator(QueryValidator):
+    """Validates aggregate values for each group in a GROUP BY query.
+
+    Example:
+        # Each category's average should be positive
+        validator = QueryGroupAggregateValidator(
+            query="SELECT category, AVG(price) as avg_price FROM data GROUP BY category",
+            group_column="category",
+            aggregate_column="avg_price",
+            min_value=0,
+        )
+    """
+
+    name = "query_group_aggregate"
+    category = "query"
+
+    def __init__(
+        self,
+        query: str,
+        group_column: str,
+        aggregate_column: str,
+        min_value: float | int | None = None,
+        max_value: float | int | None = None,
+        expected_groups: list[Any] | None = None,
+        **kwargs: Any,
+    ):
+        super().__init__(query=query, **kwargs)
+        self.group_column = group_column
+        self.aggregate_column = aggregate_column
+        self.min_value = min_value
+        self.max_value = max_value
+        self.expected_groups = set(expected_groups) if expected_groups else None
+
+    def validate_query_result(
+        self, result: pl.DataFrame, original_lf: pl.LazyFrame
+    ) -> list[ValidationIssue]:
+        issues: list[ValidationIssue] = []
+
+        # Check required columns exist
+        for col in [self.group_column, self.aggregate_column]:
+            if col not in result.columns:
+                issues.append(
+                    ValidationIssue(
+                        column=col,
+                        issue_type="query_column_not_found",
+                        count=1,
+                        severity=Severity.CRITICAL,
+                        details=f"Column '{col}' not found in query result",
+                        expected=f"Column '{col}' to exist",
+                    )
+                )
+                return issues
+
+        # Check expected groups
+        if self.expected_groups:
+            actual_groups = set(result[self.group_column].to_list())
+            missing = self.expected_groups - actual_groups
+            if missing:
+                issues.append(
+                    ValidationIssue(
+                        column=self.group_column,
+                        issue_type="query_missing_groups",
+                        count=len(missing),
+                        severity=Severity.HIGH,
+                        details=f"Missing expected groups: {list(missing)[:5]}",
+                        expected=f"Groups: {list(self.expected_groups)[:5]}",
+                    )
+                )
+
+        # Check aggregate bounds for each group
+        failing_groups = []
+        for i in range(len(result)):
+            group = result[self.group_column][i]
+            value = result[self.aggregate_column][i]
+
+            if value is None:
+                continue
+
+            failed = False
+            if self.min_value is not None and value < self.min_value:
+                failed = True
+            if self.max_value is not None and value > self.max_value:
+                failed = True
+
+            if failed:
+                failing_groups.append(f"{group}={value}")
+
+        if failing_groups:
+            issues.append(
+                ValidationIssue(
+                    column=self.aggregate_column,
+                    issue_type="query_group_aggregate_out_of_bounds",
+                    count=len(failing_groups),
+                    severity=Severity.HIGH,
+                    details=f"{len(failing_groups)} groups have out-of-bounds aggregate values",
+                    expected=f"Values in [{self.min_value}, {self.max_value}]",
+                    sample_values=failing_groups[: self.config.sample_size],
+                )
+            )
+
+        return issues
+
+
+@register_validator
+class QueryAggregateCompareValidator(QueryValidator):
+    """Compares aggregate values between two queries.
+
+    Example:
+        # Sum of debits should equal sum of credits
+        validator = QueryAggregateCompareValidator(
+            query="SELECT SUM(amount) as total FROM data WHERE type = 'debit'",
+            compare_query="SELECT SUM(amount) as total FROM data WHERE type = 'credit'",
+            column="total",
+            relationship="equal",
+            tolerance=0.01,
+        )
+    """
+
+    name = "query_aggregate_compare"
+    category = "query"
+
+    RELATIONSHIPS = {
+        "equal": lambda a, b, t: abs(a - b) <= t if t else a == b,
+        "greater_than": lambda a, b, t: a > b,
+        "greater_than_or_equal": lambda a, b, t: a >= b,
+        "less_than": lambda a, b, t: a < b,
+        "less_than_or_equal": lambda a, b, t: a <= b,
+    }
+
+    def __init__(
+        self,
+        query: str,
+        compare_query: str,
+        column: str,
+        relationship: Literal[
+            "equal", "greater_than", "greater_than_or_equal", "less_than", "less_than_or_equal"
+        ] = "equal",
+        tolerance: float | None = None,
+        **kwargs: Any,
+    ):
+        super().__init__(query=query, **kwargs)
+        self.compare_query = compare_query
+        self.column = column
+        self.relationship = relationship
+        self.tolerance = tolerance
+
+    def validate_query_result(
+        self, result: pl.DataFrame, original_lf: pl.LazyFrame
+    ) -> list[ValidationIssue]:
+        issues: list[ValidationIssue] = []
+
+        if len(result) == 0 or self.column not in result.columns:
+            issues.append(
+                ValidationIssue(
+                    column=self.column,
+                    issue_type="query_aggregate_missing",
+                    count=1,
+                    severity=Severity.HIGH,
+                    details="First query returned no result",
+                    expected="Aggregate value",
+                )
+            )
+            return issues
+
+        value_a = result[self.column][0]
+
+        # Execute compare query
+        ctx = pl.SQLContext()
+        ctx.register(self.table_name, original_lf)
+        compare_result = ctx.execute(self.compare_query).collect()
+
+        if len(compare_result) == 0 or self.column not in compare_result.columns:
+            issues.append(
+                ValidationIssue(
+                    column=self.column,
+                    issue_type="query_aggregate_missing",
+                    count=1,
+                    severity=Severity.HIGH,
+                    details="Compare query returned no result",
+                    expected="Aggregate value",
+                )
+            )
+            return issues
+
+        value_b = compare_result[self.column][0]
+
+        comparator = self.RELATIONSHIPS[self.relationship]
+        is_valid = comparator(value_a, value_b, self.tolerance)
+
+        if not is_valid:
+            issues.append(
+                ValidationIssue(
+                    column=self.column,
+                    issue_type="query_aggregate_comparison_failed",
+                    count=1,
+                    severity=Severity.HIGH,
+                    details=f"Query A: {value_a}, Query B: {value_b}. Expected A {self.relationship} B",
+                    expected=f"A {self.relationship} B",
+                    sample_values=[f"A={value_a}", f"B={value_b}"],
+                )
+            )
+
+        return issues

truthound/validators/query/base.py

@@ -0,0 +1,246 @@
+"""Base classes for query-based validators.
+
+Query validators allow validation using Polars SQL or expression-based queries,
+providing flexibility similar to Great Expectations' expect_query_* series.
+
+Design Principles:
+1. Use Polars SQL context for SQL-like queries
+2. Support both SQL strings and Polars expressions
+3. Provide clear error messages with query context
+4. Enable parameterized queries for reusability
+5. SQL Injection protection through query validation
+
+Security:
+    This module implements SQL injection protection for Polars SQL queries:
+    - Validates query structure before execution
+    - Blocks dangerous SQL patterns (DDL, DCL, multiple statements)
+    - Supports safe parameterized queries
+    - Whitelist-based table name validation
+
+    The security module (truthound.validators.security) provides:
+    - Multi-level security policies (STRICT, STANDARD, PERMISSIVE)
+    - Pluggable pattern registry for custom blocking rules
+    - Fluent SecureSQLBuilder API
+    - ParameterizedQuery for safe parameter substitution
+    - QueryAuditLogger for security monitoring
+"""
+
+from abc import abstractmethod
+from typing import Any
+
+import polars as pl
+
+from truthound.types import Severity
+from truthound.validators.base import ValidationIssue, Validator, ValidatorConfig
+from truthound.validators.registry import register_validator
+
+# Import from the comprehensive security module
+from truthound.validators.security import (
+    SQLSecurityError,
+    SQLInjectionError,
+    QueryValidationError,
+    SQLQueryValidator,
+    validate_sql_query,
+    SecureSQLBuilder,
+    ParameterizedQuery,
+    WhitelistValidator,
+    SchemaWhitelist,
+    SecurityPolicy,
+    SecurityLevel,
+    SecureQueryMixin,
+    QueryAuditLogger,
+    AuditEntry,
+)
+
+# Backward compatibility alias
+SQLValidationError = QueryValidationError
+
+
+class QueryValidator(Validator):
+    """Base class for query-based validators.
+
+    Provides infrastructure for executing Polars SQL queries and validating results.
+    Subclasses implement specific validation logic on query results.
+
+    Security:
+        SQL queries are validated before execution to prevent injection attacks.
+        Set validate_sql=False to disable validation (not recommended).
+
+    Example:
+        class MyQueryValidator(QueryValidator):
+            def validate_query_result(self, result: pl.DataFrame) -> list[ValidationIssue]:
+                # Custom validation logic
+                pass
+    """
+
+    name = "query_base"
+    category = "query"
+
+    def __init__(
+        self,
+        query: str | None = None,
+        expression: pl.Expr | None = None,
+        table_name: str = "data",
+        validate_sql: bool = True,
+        allowed_tables: list[str] | None = None,
+        **kwargs: Any,
+    ):
+        """Initialize query validator.
+
+        Args:
+            query: SQL query string (uses Polars SQL context)
+            expression: Polars expression as alternative to SQL
+            table_name: Name to use for the table in SQL context
+            validate_sql: Whether to validate SQL for security (default: True)
+            allowed_tables: Whitelist of allowed table names for SQL validation
+            **kwargs: Additional validator config
+        """
+        super().__init__(**kwargs)
+        self.query = query
+        self.expression = expression
+        self.table_name = table_name
+        self.validate_sql = validate_sql
+
+        # Set up allowed tables (always include the main table)
+        if allowed_tables:
+            self.allowed_tables = list(allowed_tables)
+            if table_name not in self.allowed_tables:
+                self.allowed_tables.append(table_name)
+        else:
+            self.allowed_tables = [table_name]
+
+        if query is None and expression is None:
+            raise ValueError("Either 'query' or 'expression' must be provided")
+
+        # Validate SQL query if provided
+        if query and validate_sql:
+            try:
+                validate_sql_query(query, self.allowed_tables)
+            except SQLValidationError as e:
+                raise ValueError(f"SQL query validation failed: {e}")
+
+    def _execute_query(self, lf: pl.LazyFrame) -> pl.DataFrame:
+        """Execute the query and return results.
+
+        Args:
+            lf: Input LazyFrame
+
+        Returns:
+            Query result as DataFrame
+        """
+        if self.query:
+            # Use Polars SQL context
+            ctx = pl.SQLContext()
+            ctx.register(self.table_name, lf)
+            return ctx.execute(self.query).collect()
+        elif self.expression:
+            # Use expression directly
+            return lf.select(self.expression).collect()
+        else:
+            raise ValueError("No query or expression provided")
+
+    def validate(self, lf: pl.LazyFrame) -> list[ValidationIssue]:
+        """Execute query and validate results."""
+        try:
+            result = self._execute_query(lf)
+            return self.validate_query_result(result, lf)
+        except Exception as e:
+            # Return validation issue for query execution errors
+            return [
+                ValidationIssue(
+                    column="_query",
+                    issue_type="query_execution_error",
+                    count=1,
+                    severity=Severity.CRITICAL,
+                    details=f"Query execution failed: {e}",
+                    expected="Valid query execution",
+                )
+            ]
+
+    @abstractmethod
+    def validate_query_result(
+        self, result: pl.DataFrame, original_lf: pl.LazyFrame
+    ) -> list[ValidationIssue]:
+        """Validate the query result.
+
+        Args:
+            result: Query execution result
+            original_lf: Original LazyFrame for context
+
+        Returns:
+            List of validation issues
+        """
+        pass
+
+
+class ExpressionValidator(Validator):
+    """Base class for expression-based validators.
+
+    Uses Polars expressions for flexible, composable validation logic.
+    More performant than SQL for simple validations.
+    """
+
+    name = "expression_base"
+    category = "query"
+
+    def __init__(
+        self,
+        filter_expr: pl.Expr,
+        description: str = "Expression validation",
+        **kwargs: Any,
+    ):
+        """Initialize expression validator.
+
+        Args:
+            filter_expr: Polars expression that returns boolean series
+                         True = valid, False = invalid
+            description: Human-readable description of the validation
+            **kwargs: Additional validator config
+        """
+        super().__init__(**kwargs)
+        self.filter_expr = filter_expr
+        self.description = description
+
+    def validate(self, lf: pl.LazyFrame) -> list[ValidationIssue]:
+        """Validate using the expression."""
+        issues: list[ValidationIssue] = []
+
+        try:
+            # Count rows that fail the expression (where expr is False)
+            result = lf.select([
+                pl.len().alias("_total"),
+                (~self.filter_expr).sum().alias("_failures"),
+            ]).collect()
+
+            total = result["_total"][0]
+            failures = result["_failures"][0]
+
+            if failures > 0:
+                if self._passes_mostly(failures, total):
+                    return issues
+
+                ratio = failures / total if total > 0 else 0
+
+                issues.append(
+                    ValidationIssue(
+                        column="_expression",
+                        issue_type="expression_validation_failed",
+                        count=failures,
+                        severity=self._calculate_severity(ratio),
+                        details=f"{failures}/{total} rows failed: {self.description}",
+                        expected=self.description,
+                    )
+                )
+        except Exception as e:
+            issues.append(
+                ValidationIssue(
+                    column="_expression",
+                    issue_type="expression_execution_error",
+                    count=1,
+                    severity=Severity.CRITICAL,
+                    details=f"Expression execution failed: {e}",
+                    expected="Valid expression execution",
+                )
+            )
+
+        return issues