additory 0.1.0a3__py3-none-any.whl → 0.1.1a1__py3-none-any.whl

additory/common/backend.py

@@ -1,371 +0,0 @@
-"""
-Unified Backend Detection System
-
-Provides consistent backend detection across all additory modules.
-"""
-
-import pandas as pd
-from typing import Any, Literal, Dict
-
-# Optional imports
-try:
-    import polars as pl
-    HAS_POLARS = True
-except ImportError:
-    HAS_POLARS = False
-    pl = None
-
-try:
-    import cudf
-    HAS_CUDF = True
-except (ImportError, Exception):
-    HAS_CUDF = False
-    cudf = None
-
-
-BackendType = Literal['pandas', 'polars', 'cudf']
-ExecutionMode = Literal['cpu', 'gpu']
-
-
-def detect_backend(df: Any) -> BackendType:
-    """
-    Detect the specific backend type of a dataframe.
-    
-    Args:
-        df: Dataframe to detect
-        
-    Returns:
-        'pandas', 'polars', or 'cudf'
-        
-    Raises:
-        TypeError: If not a supported dataframe type
-        
-    Usage:
-        - Use this when you need to know the SPECIFIC backend
-        - For utilities that need native operations
-        - For type-specific conversions
-        
-    Examples:
-        >>> backend = detect_backend(df)
-        >>> if backend == 'polars':
-        ...     result = df.select(...)
-        >>> elif backend == 'pandas':
-        ...     result = df[...]
-    """
-    if isinstance(df, pd.DataFrame):
-        return 'pandas'
-    elif HAS_POLARS and isinstance(df, pl.DataFrame):
-        return 'polars'
-    elif HAS_CUDF and isinstance(df, cudf.DataFrame):
-        return 'cudf'
-    else:
-        raise TypeError(
-            f"Unsupported dataframe type: {type(df)}. "
-            f"Supported types: pandas.DataFrame"
-            f"{', polars.DataFrame' if HAS_POLARS else ''}"
-            f"{', cudf.DataFrame' if HAS_CUDF else ''}"
-        )
-
-
-def detect_execution_mode(df: Any, preference: str = None) -> ExecutionMode:
-    """
-    Detect execution mode (CPU vs GPU) for expression processing.
-    
-    Args:
-        df: Dataframe to detect
-        preference: User preference ('cpu', 'gpu', or None for auto)
-        
-    Returns:
-        'cpu' or 'gpu'
-        
-    Usage:
-        - Use this for expression execution routing
-        - Respects user preferences
-        - Falls back intelligently
-        
-    Examples:
-        >>> mode = detect_execution_mode(df, preference='gpu')
-        >>> if mode == 'gpu':
-        ...     # Use GPU-accelerated execution
-    """
-    backend = detect_backend(df)
-    
-    # User preference takes priority
-    if preference == 'gpu' and HAS_CUDF:
-        return 'gpu'
-    elif preference == 'cpu':
-        return 'cpu'
-    
-    # Auto-detect based on dataframe type
-    if backend == 'cudf':
-        return 'gpu'
-    else:
-        return 'cpu'
-
-
-def is_dataframe(obj: Any) -> bool:
-    """
-    Check if object is any supported dataframe type.
-    
-    Args:
-        obj: Object to check
-        
-    Returns:
-        True if supported dataframe type
-        
-    Usage:
-        - Use for simple boolean checks
-        - Fast validation without exceptions
-        
-    Examples:
-        >>> if is_dataframe(obj):
-        ...     process(obj)
-    """
-    return (
-        isinstance(obj, pd.DataFrame) or
-        (HAS_POLARS and isinstance(obj, pl.DataFrame)) or
-        (HAS_CUDF and isinstance(obj, cudf.DataFrame))
-    )
-
-
-def get_available_backends() -> Dict[str, bool]:
-    """
-    Get availability status of all backends.
-    
-    Returns:
-        Dictionary mapping backend name to availability
-        
-    Examples:
-        >>> backends = get_available_backends()
-        >>> if backends['polars']:
-        ...     # Use polars-specific features
-    """
-    return {
-        'pandas': True,  # Always available
-        'polars': HAS_POLARS,
-        'cudf': HAS_CUDF
-    }
-
-
-def check_backend_available(backend: BackendType) -> bool:
-    """
-    Check if a specific backend is available.
-    
-    Args:
-        backend: Backend to check ('pandas', 'polars', 'cudf')
-        
-    Returns:
-        True if backend is available
-        
-    Examples:
-        >>> if check_backend_available('polars'):
-        ...     # Safe to use polars
-    """
-    availability = get_available_backends()
-    return availability.get(backend, False)
-
-
-# ============================================================================
-# Arrow Bridge Helpers - Polars-Only Architecture
-# ============================================================================
-
-def get_arrow_bridge():
-    """
-    Get singleton instance of Arrow bridge.
-    
-    Returns:
-        EnhancedArrowBridge instance
-        
-    Usage:
-        - Use for all cross-backend conversions
-        - Handles pandas/polars/cuDF via Arrow
-    """
-    from additory.core.backends.arrow_bridge import EnhancedArrowBridge, ArrowBridgeError
-    
-    # Singleton pattern
-    if not hasattr(get_arrow_bridge, '_instance'):
-        try:
-            get_arrow_bridge._instance = EnhancedArrowBridge()
-        except ArrowBridgeError:
-            get_arrow_bridge._instance = None
-    
-    return get_arrow_bridge._instance
-
-
-def to_polars(df: Any, backend_type: BackendType = None) -> 'pl.DataFrame':
-    """
-    Convert any dataframe to Polars via Arrow bridge.
-    
-    This is the primary conversion function for the Polars-only architecture.
-    All operations (expressions, synthetic, etc.) use this to convert input
-    dataframes to Polars for processing.
-    
-    Args:
-        df: Input dataframe (pandas, polars, or cuDF)
-        backend_type: Source backend type (auto-detected if None)
-        
-    Returns:
-        Polars DataFrame
-        
-    Raises:
-        TypeError: If df is not a supported dataframe type
-        RuntimeError: If conversion fails
-        
-    Examples:
-        >>> # Convert pandas to polars
-        >>> pl_df = to_polars(pandas_df)
-        
-        >>> # Convert cuDF to polars
-        >>> pl_df = to_polars(cudf_df)
-        
-        >>> # Already polars (no-op)
-        >>> pl_df = to_polars(polars_df)
-    """
-    if not HAS_POLARS:
-        raise RuntimeError(
-            "Polars is not available. Install with: pip install polars"
-        )
-    
-    # Fast path: already Polars
-    if HAS_POLARS and isinstance(df, pl.DataFrame):
-        return df
-    
-    # Validate input
-    if not is_dataframe(df):
-        raise TypeError(
-            f"Expected pandas, polars, or cuDF DataFrame, got {type(df)}"
-        )
-    
-    # Auto-detect backend if not provided
-    if backend_type is None:
-        backend_type = detect_backend(df)
-    
-    # Convert via Arrow bridge
-    try:
-        bridge = get_arrow_bridge()
-        if bridge is None:
-            # Fallback: direct conversion for pandas
-            if backend_type == "pandas":
-                if isinstance(df, pd.DataFrame):
-                    return pl.from_pandas(df)
-            raise RuntimeError("Arrow bridge not available and cannot convert non-pandas DataFrame")
-        
-        arrow_table = bridge.to_arrow(df, backend_type)
-        pl_df = bridge.from_arrow(arrow_table, "polars")
-        return pl_df
-    except Exception as e:
-        raise RuntimeError(
-            f"Failed to convert {backend_type} DataFrame to Polars: {e}"
-        ) from e
-
-
-def from_polars(pl_df: 'pl.DataFrame', target_backend: BackendType) -> Any:
-    """
-    Convert Polars dataframe back to target backend via Arrow bridge.
-    
-    This is used to convert results back to the user's original format
-    after processing in Polars.
-    
-    Args:
-        pl_df: Polars DataFrame
-        target_backend: Target backend ('pandas', 'polars', or 'cudf')
-        
-    Returns:
-        DataFrame in target format
-        
-    Raises:
-        TypeError: If pl_df is not a Polars DataFrame
-        ValueError: If target_backend is not supported
-        RuntimeError: If conversion fails
-        
-    Examples:
-        >>> # Convert back to pandas
-        >>> pandas_df = from_polars(pl_df, 'pandas')
-        
-        >>> # Convert back to cuDF
-        >>> cudf_df = from_polars(pl_df, 'cudf')
-        
-        >>> # Keep as polars (no-op)
-        >>> pl_df = from_polars(pl_df, 'polars')
-    """
-    if not HAS_POLARS:
-        raise RuntimeError(
-            "Polars is not available. Install with: pip install polars"
-        )
-    
-    # Validate input
-    if not isinstance(pl_df, pl.DataFrame):
-        raise TypeError(
-            f"Expected Polars DataFrame, got {type(pl_df)}"
-        )
-    
-    # Validate target backend
-    if target_backend not in ('pandas', 'polars', 'cudf'):
-        raise ValueError(
-            f"Invalid target_backend: {target_backend}. "
-            f"Must be 'pandas', 'polars', or 'cudf'"
-        )
-    
-    # Fast path: already target format
-    if target_backend == 'polars':
-        return pl_df
-    
-    # Check target backend availability
-    if target_backend == 'cudf' and not HAS_CUDF:
-        raise RuntimeError(
-            "cuDF is not available. Install with: pip install cudf"
-        )
-    
-    # Convert via Arrow bridge
-    try:
-        bridge = get_arrow_bridge()
-        if bridge is None:
-            # Fallback: direct conversion for pandas
-            if target_backend == "pandas":
-                return pl_df.to_pandas()
-            raise RuntimeError("Arrow bridge not available and cannot convert to non-pandas DataFrame")
-        
-        arrow_table = bridge.to_arrow(pl_df, "polars")
-        result_df = bridge.from_arrow(arrow_table, target_backend)
-        return result_df
-    except Exception as e:
-        raise RuntimeError(
-            f"Failed to convert Polars DataFrame to {target_backend}: {e}"
-        ) from e
-
-
-def convert_via_polars(df: Any, target_backend: BackendType = None) -> Any:
-    """
-    Convert dataframe to target backend via Polars (round-trip conversion).
-    
-    This is a convenience function that combines to_polars() and from_polars().
-    Useful for format conversions without processing.
-    
-    Args:
-        df: Input dataframe
-        target_backend: Target backend (defaults to input backend)
-        
-    Returns:
-        DataFrame in target format
-        
-    Examples:
-        >>> # Convert pandas to cuDF via Polars
-        >>> cudf_df = convert_via_polars(pandas_df, 'cudf')
-        
-        >>> # Round-trip (normalize via Polars)
-        >>> normalized_df = convert_via_polars(df)
-    """
-    # Detect input backend
-    input_backend = detect_backend(df)
-    
-    # Default to same backend
-    if target_backend is None:
-        target_backend = input_backend
-    
-    # Fast path: same backend
-    if input_backend == target_backend:
-        return df
-    
-    # Convert via Polars
-    pl_df = to_polars(df, input_backend)
-    return from_polars(pl_df, target_backend)

additory/common/column_utils.py

@@ -1,191 +0,0 @@
-"""
-Common Column Utilities
-
-Provides column name handling utilities shared across modules.
-"""
-
-import re
-from typing import List
-from .exceptions import ValidationError
-
-
-def sanitize_column_name(col_name: str) -> str:
-    """
-    Convert column name to Python-friendly identifier.
-    
-    Rules:
-    - Replace spaces and special chars with underscores
-    - Remove consecutive underscores  
-    - Remove leading/trailing underscores
-    - Ensure doesn't start with number
-    - Convert to lowercase for consistency
-    
-    Args:
-        col_name: Original column name
-        
-    Returns:
-        Sanitized column name safe for Python identifiers
-        
-    Examples:
-        >>> sanitize_column_name("height collected on site")
-        'height_collected_on_site'
-        >>> sanitize_column_name("Patient Height - Site A")
-        'patient_height_site_a'
-        >>> sanitize_column_name("Weight (kg)")
-        'weight_kg'
-        >>> sanitize_column_name("temp@location#1")
-        'temp_location_1'
-    """
-    # Convert to string and handle None/empty
-    if not col_name:
-        return "unnamed_column"
-    
-    col_str = str(col_name)
-    
-    # Replace non-alphanumeric chars with underscores
-    sanitized = re.sub(r'[^a-zA-Z0-9_]', '_', col_str)
-    
-    # Remove consecutive underscores
-    sanitized = re.sub(r'_+', '_', sanitized)
-    
-    # Remove leading/trailing underscores
-    sanitized = sanitized.strip('_')
-    
-    # Ensure doesn't start with number
-    if sanitized and sanitized[0].isdigit():
-        sanitized = f"col_{sanitized}"
-    
-    # Convert to lowercase for consistency
-    sanitized = sanitized.lower()
-    
-    return sanitized if sanitized else "unnamed_column"
-
-
-def generate_safe_column_name(base_name: str, existing_columns: List[str]) -> str:
-    """
-    Generate a safe column name that doesn't conflict with existing columns.
-    
-    Args:
-        base_name: Desired column name
-        existing_columns: List of existing column names
-        
-    Returns:
-        Safe column name with _1, _2, etc. suffix if needed
-        
-    Examples:
-        >>> generate_safe_column_name("value", ["value", "value_1"])
-        'value_2'
-        >>> generate_safe_column_name("new_col", ["col1", "col2"])
-        'new_col'
-    """
-    if base_name not in existing_columns:
-        return base_name
-    
-    counter = 1
-    while f"{base_name}_{counter}" in existing_columns:
-        counter += 1
-    
-    return f"{base_name}_{counter}"
-
-
-def validate_column_name(name: str) -> None:
-    """
-    Validate column name format.
-    
-    Args:
-        name: Column name to validate
-        
-    Raises:
-        ValidationError: If name is invalid
-        
-    Examples:
-        >>> validate_column_name("valid_column")
-        >>> validate_column_name("")  # Raises ValidationError
-    """
-    if not isinstance(name, str):
-        raise ValidationError(f"Column name must be a string, got {type(name)}")
-    
-    if not name.strip():
-        raise ValidationError("Column name cannot be empty")
-
-
-def truncate_column_name(name: str, max_length: int = 63, 
-                        preserve_end: bool = True) -> str:
-    """
-    Truncate column name to maximum length while preserving uniqueness.
-    
-    Args:
-        name: Column name to truncate
-        max_length: Maximum length (default 63 for SQL compatibility)
-        preserve_end: If True, preserve end of name (where differences often are)
-        
-    Returns:
-        Truncated column name
-        
-    Examples:
-        >>> truncate_column_name("very_long_column_name_with_suffix_01", max_length=20)
-        'very_lon_suffix_01'
-        >>> truncate_column_name("short", max_length=20)
-        'short'
-    """
-    if len(name) <= max_length:
-        return name
-    
-    if preserve_end:
-        # Keep start and end, truncate middle
-        keep_start = max_length // 2
-        keep_end = max_length - keep_start
-        return name[:keep_start] + name[-keep_end:]
-    else:
-        # Simple truncation from start
-        return name[:max_length]
-
-
-def generate_column_names_with_prefix_suffix(
-    base_name: str,
-    values: List[str],
-    prefix: str = None,
-    suffix: str = None,
-    max_length: int = 63
-) -> List[str]:
-    """
-    Generate column names with optional prefix/suffix.
-    
-    Args:
-        base_name: Base column name
-        values: List of values to create column names for
-        prefix: Optional prefix
-        suffix: Optional suffix
-        max_length: Maximum column name length
-        
-    Returns:
-        List of generated column names
-        
-    Examples:
-        >>> generate_column_names_with_prefix_suffix(
-        ...     "color", ["red", "blue"], prefix="ohe"
-        ... )
-        ['ohe_color_red', 'ohe_color_blue']
-    """
-    column_names = []
-    
-    for value in values:
-        # Build parts
-        parts = []
-        if prefix:
-            parts.append(prefix)
-        parts.append(base_name)
-        parts.append(str(value))
-        if suffix:
-            parts.append(suffix)
-        
-        # Join with underscores
-        full_name = "_".join(parts)
-        
-        # Truncate if needed
-        if len(full_name) > max_length:
-            full_name = truncate_column_name(full_name, max_length)
-        
-        column_names.append(full_name)
-    
-    return column_names

additory/common/exceptions.py

@@ -1,62 +0,0 @@
-"""
-Unified Exception Hierarchy for Additory
-
-Provides consistent error handling across all modules.
-"""
-
-
-class AdditoryError(Exception):
-    """Base exception for all additory errors."""
-    pass
-
-
-class ValidationError(AdditoryError):
-    """Raised when validation fails."""
-    pass
-
-
-class BackendError(AdditoryError):
-    """Raised when backend operations fail."""
-    pass
-
-
-class ConversionError(AdditoryError):
-    """Raised when data conversion fails."""
-    pass
-
-
-class ExpressionError(AdditoryError):
-    """Raised when expression execution fails."""
-    pass
-
-
-class ConfigurationError(AdditoryError):
-    """Raised when configuration is invalid."""
-    pass
-
-
-# Specific error types for different modules
-
-class UnitConversionError(ConversionError):
-    """Raised when unit conversion fails."""
-    pass
-
-
-class EncodingError(ConversionError):
-    """Raised when encoding operations fail."""
-    pass
-
-
-class LookupError(AdditoryError):
-    """Raised when lookup operations fail."""
-    pass
-
-
-class SyntheticDataError(AdditoryError):
-    """Raised when synthetic data generation fails."""
-    pass
-
-
-class AugmentError(AdditoryError):
-    """Raised when data augmentation fails."""
-    pass