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

additory/core/backend.py

@@ -0,0 +1,258 @@
+"""
+Backend detection and conversion utilities for Additory.
+
+Handles automatic conversion between pandas, Polars, and cuDF DataFrames.
+All processing happens in Polars, with transparent conversions at boundaries.
+"""
+
+from typing import Any
+import polars as pl
+
+
+# Global default backend setting
+_DEFAULT_BACKEND = 'polars'
+
+
+def detect_backend(df: Any) -> str:
+    """
+    Detect the backend type of a DataFrame.
+    
+    Args:
+        df: DataFrame to detect
+        
+    Returns:
+        Backend string ('polars', 'pandas', 'cudf', 'dask', 'spark')
+        
+    Raises:
+        TypeError: If df is not a supported DataFrame type
+        
+    Example:
+        backend = detect_backend(df)
+        # Returns: 'pandas' or 'polars' or 'cudf'
+    """
+    # Check Polars
+    if isinstance(df, pl.DataFrame):
+        return 'polars'
+    
+    # Check pandas
+    try:
+        import pandas as pd
+        if isinstance(df, pd.DataFrame):
+            return 'pandas'
+    except ImportError:
+        pass
+    
+    # Check cuDF
+    if is_cudf(df):
+        return 'cudf'
+    
+    # Check Dask (future support)
+    if is_dask(df):
+        return 'dask'
+    
+    # Check Spark (future support)
+    if is_spark(df):
+        return 'spark'
+    
+    # Unsupported type
+    raise TypeError(
+        f"Unsupported DataFrame type: {type(df).__name__}. "
+        f"Supported types: pandas.DataFrame, polars.DataFrame, cudf.DataFrame"
+    )
+
+
+def to_polars(df: Any) -> pl.DataFrame:
+    """
+    Convert any DataFrame to Polars.
+    
+    Args:
+        df: DataFrame to convert
+        
+    Returns:
+        Polars DataFrame
+        
+    Raises:
+        TypeError: If df is not a supported DataFrame type
+        
+    Example:
+        polars_df = to_polars(df)  # Works with pandas, polars, cuDF
+    """
+    # Already Polars
+    if isinstance(df, pl.DataFrame):
+        return df
+    
+    # From pandas
+    try:
+        import pandas as pd
+        if isinstance(df, pd.DataFrame):
+            return pl.from_pandas(df)
+    except ImportError:
+        pass
+    
+    # From cuDF
+    if is_cudf(df):
+        try:
+            return pl.from_arrow(df.to_arrow())
+        except Exception as e:
+            raise TypeError(f"Failed to convert cuDF DataFrame to Polars: {e}")
+    
+    # From Dask (future support)
+    if is_dask(df):
+        raise NotImplementedError("Dask support is not yet implemented")
+    
+    # From Spark (future support)
+    if is_spark(df):
+        raise NotImplementedError("Spark support is not yet implemented")
+    
+    # Unsupported type
+    raise TypeError(
+        f"Unsupported DataFrame type: {type(df).__name__}. "
+        f"Supported types: pandas.DataFrame, polars.DataFrame, cudf.DataFrame"
+    )
+
+
+def from_polars(df: pl.DataFrame, target_backend: str) -> Any:
+    """
+    Convert Polars DataFrame back to target backend.
+    
+    Args:
+        df: Polars DataFrame to convert
+        target_backend: Target backend ('polars', 'pandas', 'cudf')
+        
+    Returns:
+        DataFrame in target backend
+        
+    Raises:
+        TypeError: If target_backend is not supported
+        
+    Example:
+        result = from_polars(polars_df, 'pandas')  # Returns pandas DataFrame
+    """
+    if not isinstance(df, pl.DataFrame):
+        raise TypeError(f"Input must be a Polars DataFrame, got {type(df).__name__}")
+    
+    # To Polars (no conversion needed)
+    if target_backend == 'polars':
+        return df
+    
+    # To pandas
+    if target_backend == 'pandas':
+        return df.to_pandas()
+    
+    # To cuDF
+    if target_backend == 'cudf':
+        try:
+            import cudf
+            return cudf.from_arrow(df.to_arrow())
+        except ImportError:
+            raise ImportError("cuDF is not installed. Install with: pip install cudf")
+        except Exception as e:
+            raise TypeError(f"Failed to convert Polars DataFrame to cuDF: {e}")
+    
+    # To Dask (future support)
+    if target_backend == 'dask':
+        raise NotImplementedError("Dask support is not yet implemented")
+    
+    # To Spark (future support)
+    if target_backend == 'spark':
+        raise NotImplementedError("Spark support is not yet implemented")
+    
+    # Unsupported backend
+    raise TypeError(
+        f"Unsupported backend: {target_backend}. "
+        f"Supported backends: polars, pandas, cudf"
+    )
+
+
+def is_cudf(df: Any) -> bool:
+    """
+    Check if DataFrame is cuDF.
+    
+    Args:
+        df: Object to check
+        
+    Returns:
+        True if cuDF DataFrame, False otherwise
+        
+    Example:
+        if is_cudf(df):
+            # Handle cuDF-specific logic
+    """
+    try:
+        import cudf
+        return isinstance(df, cudf.DataFrame)
+    except ImportError:
+        return False
+
+
+def is_dask(df: Any) -> bool:
+    """
+    Check if DataFrame is Dask (future support).
+    
+    Args:
+        df: Object to check
+        
+    Returns:
+        True if Dask DataFrame, False otherwise
+    """
+    try:
+        import dask.dataframe as dd
+        return isinstance(df, dd.DataFrame)
+    except ImportError:
+        return False
+
+
+def is_spark(df: Any) -> bool:
+    """
+    Check if DataFrame is Spark (future support).
+    
+    Args:
+        df: Object to check
+        
+    Returns:
+        True if Spark DataFrame, False otherwise
+    """
+    try:
+        from pyspark.sql import DataFrame as SparkDataFrame
+        return isinstance(df, SparkDataFrame)
+    except ImportError:
+        return False
+
+
+def get_default_backend() -> str:
+    """
+    Get the default backend setting.
+    
+    Returns:
+        Default backend string ('polars', 'pandas', 'cudf')
+        
+    Example:
+        backend = get_default_backend()  # Returns 'polars' by default
+    """
+    return _DEFAULT_BACKEND
+
+
+def set_default_backend(backend: str) -> None:
+    """
+    Set the default backend for operations.
+    
+    Args:
+        backend: Backend to set ('polars', 'pandas', 'cudf')
+        
+    Raises:
+        ValueError: If backend is not supported
+        
+    Example:
+        import additory
+        additory.add.set_default_backend('cudf')  # For GPU users
+    """
+    global _DEFAULT_BACKEND
+    
+    supported_backends = ['polars', 'pandas', 'cudf']
+    if backend not in supported_backends:
+        raise ValueError(
+            f"Unsupported backend: {backend}. "
+            f"Supported backends: {', '.join(supported_backends)}"
+        )
+    
+    _DEFAULT_BACKEND = backend