kontra 0.5.2__py3-none-any.whl

kontra/scout/dtype_mapping.py

@@ -0,0 +1,150 @@
+# src/kontra/scout/dtype_mapping.py
+"""
+Unified dtype mapping for Scout profiler.
+
+Provides consistent type normalization across all backends (DuckDB, PostgreSQL, SQL Server).
+This module consolidates dtype mappings that were previously duplicated across backend files.
+"""
+
+from __future__ import annotations
+
+from typing import Dict
+
+# Normalized type categories
+NUMERIC_TYPES = {"int", "float"}
+TEMPORAL_TYPES = {"date", "time", "datetime", "interval"}
+STRING_TYPES = {"string"}
+BOOLEAN_TYPES = {"bool"}
+BINARY_TYPES = {"binary"}
+
+# Master dtype mapping (lowercase keys for case-insensitive lookup)
+# Maps raw database types to normalized Kontra types
+DTYPE_MAP: Dict[str, str] = {
+    # Integer types (common)
+    "tinyint": "int",
+    "smallint": "int",
+    "integer": "int",
+    "int": "int",
+    "bigint": "int",
+    "hugeint": "int",
+    "int2": "int",
+    "int4": "int",
+    "int8": "int",
+    "int16": "int",
+    "int32": "int",
+    "int64": "int",
+    "int128": "int",
+    "serial": "int",
+    "bigserial": "int",
+    # Unsigned integers (DuckDB)
+    "utinyint": "int",
+    "usmallint": "int",
+    "uinteger": "int",
+    "ubigint": "int",
+    "uint8": "int",
+    "uint16": "int",
+    "uint32": "int",
+    "uint64": "int",
+    # Float types (common)
+    "float": "float",
+    "float4": "float",
+    "float8": "float",
+    "real": "float",
+    "double": "float",
+    "double precision": "float",
+    "decimal": "float",
+    "numeric": "float",
+    # Float types (SQL Server)
+    "money": "float",
+    "smallmoney": "float",
+    # Boolean types
+    "boolean": "bool",
+    "bool": "bool",
+    "bit": "bool",  # SQL Server
+    # String types (common)
+    "varchar": "string",
+    "char": "string",
+    "bpchar": "string",  # PostgreSQL blank-padded char
+    "text": "string",
+    "string": "string",
+    "character varying": "string",
+    "character": "string",
+    # String types (SQL Server)
+    "nvarchar": "string",
+    "nchar": "string",
+    "ntext": "string",
+    # Date types
+    "date": "date",
+    # Time types
+    "time": "time",
+    "time without time zone": "time",
+    "time with time zone": "time",
+    # Datetime types (common)
+    "timestamp": "datetime",
+    "timestamp with time zone": "datetime",
+    "timestamp without time zone": "datetime",
+    "timestamptz": "datetime",
+    # Datetime types (SQL Server)
+    "datetime": "datetime",
+    "datetime2": "datetime",
+    "smalldatetime": "datetime",
+    "datetimeoffset": "datetime",
+    # Interval
+    "interval": "interval",
+    # Binary types (common)
+    "blob": "binary",
+    "bytea": "binary",  # PostgreSQL
+    # Binary types (SQL Server)
+    "binary": "binary",
+    "varbinary": "binary",
+    "image": "binary",
+    # UUID / special string types
+    "uuid": "string",
+    "json": "string",
+    "jsonb": "string",
+    "uniqueidentifier": "string",  # SQL Server UUID
+    "xml": "string",  # SQL Server
+}
+
+
+def normalize_dtype(raw_type: str) -> str:
+    """
+    Normalize a raw database type to a simplified Kontra type name.
+
+    Args:
+        raw_type: Raw type string from database (e.g., "VARCHAR(255)", "BIGINT")
+
+    Returns:
+        Normalized type: "int", "float", "string", "bool", "date", "datetime",
+                        "time", "interval", "binary", or "unknown"
+
+    Examples:
+        >>> normalize_dtype("VARCHAR(255)")
+        'string'
+        >>> normalize_dtype("DECIMAL(10,2)")
+        'float'
+        >>> normalize_dtype("bigint")
+        'int'
+    """
+    # Lowercase and strip whitespace for case-insensitive matching
+    lower = raw_type.lower().strip()
+
+    # Handle parameterized types like DECIMAL(10,2) or VARCHAR(255)
+    base = lower.split("(")[0].strip()
+
+    return DTYPE_MAP.get(base, "unknown")
+
+
+def is_numeric_type(normalized_type: str) -> bool:
+    """Check if a normalized type is numeric."""
+    return normalized_type in NUMERIC_TYPES
+
+
+def is_temporal_type(normalized_type: str) -> bool:
+    """Check if a normalized type is temporal (date/time)."""
+    return normalized_type in TEMPORAL_TYPES
+
+
+def is_string_type(normalized_type: str) -> bool:
+    """Check if a normalized type is a string."""
+    return normalized_type in STRING_TYPES

kontra/scout/patterns.py

@@ -0,0 +1,69 @@
+# src/kontra/scout/patterns.py
+"""
+Pattern detection for common data formats.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import List
+
+
+# Common patterns to detect
+PATTERNS = {
+    "email": re.compile(r"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$"),
+    "uuid": re.compile(
+        r"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
+    ),
+    "phone_us": re.compile(
+        r"^\+?1?[-.\s]?\(?[0-9]{3}\)?[-.\s]?[0-9]{3}[-.\s]?[0-9]{4}$"
+    ),
+    "phone_intl": re.compile(r"^\+[1-9]\d{6,14}$"),
+    "url": re.compile(r"^https?://[^\s]+$"),
+    "ipv4": re.compile(r"^(?:[0-9]{1,3}\.){3}[0-9]{1,3}$"),
+    "ipv6": re.compile(r"^([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}$"),
+    "iso_date": re.compile(r"^\d{4}-\d{2}-\d{2}$"),
+    "iso_datetime": re.compile(r"^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}"),
+    "hex_color": re.compile(r"^#[0-9A-Fa-f]{6}$"),
+    "credit_card": re.compile(r"^[0-9]{4}[- ]?[0-9]{4}[- ]?[0-9]{4}[- ]?[0-9]{4}$"),
+    "ssn": re.compile(r"^\d{3}-\d{2}-\d{4}$"),
+    "zip_us": re.compile(r"^\d{5}(-\d{4})?$"),
+    "slug": re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$"),
+    "json": re.compile(r"^[\[\{].*[\]\}]$", re.DOTALL),
+}
+
+
+def detect_patterns(sample_values: List[str], threshold: float = 0.8) -> List[str]:
+    """
+    Detect common patterns in a sample of string values.
+
+    Args:
+        sample_values: List of string values to analyze
+        threshold: Minimum fraction of values that must match (default: 80%)
+
+    Returns:
+        List of pattern names where >= threshold of non-null values match.
+    """
+    if not sample_values:
+        return []
+
+    # Filter out empty strings for pattern matching
+    non_empty = [v for v in sample_values if v and v.strip()]
+    if not non_empty:
+        return []
+
+    matches = []
+    for pattern_name, regex in PATTERNS.items():
+        match_count = sum(1 for v in non_empty if regex.match(str(v)))
+        if match_count / len(non_empty) >= threshold:
+            matches.append(pattern_name)
+
+    return matches
+
+
+def get_pattern_regex(pattern_name: str) -> str:
+    """Get the regex pattern string for a pattern name."""
+    pattern = PATTERNS.get(pattern_name)
+    if pattern:
+        return pattern.pattern
+    return ""