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

additory/functions/to/lookup.py

@@ -0,0 +1,351 @@
+"""
+Lookup and add columns from reference DataFrame.
+
+This module provides lookup functionality for the to function.
+"""
+
+import polars as pl
+from typing import Union, List, Optional, Dict
+
+from additory.common.validation import validate_dataframe, validate_not_empty
+from additory.common.column_selector import select_columns
+from additory.core.logging import Logger
+
+
+def perform_lookup(
+    df: pl.DataFrame,
+    from_df: pl.DataFrame,
+    bring: Union[str, List[str]],
+    against: Union[str, List[str]],
+    bring_at: Optional[str] = None,
+    strategy: Optional[Dict] = None
+) -> pl.DataFrame:
+    """
+    Perform lookup and add columns from reference DataFrame.
+    
+    Args:
+        df: Input DataFrame
+        from_df: Reference DataFrame
+        bring: Column(s) to bring from reference
+        against: Key column(s) for matching
+        bring_at: Position to insert columns ('start', 'end', 'after:col', 'before:col')
+        strategy: Strategy dictionary for advanced control
+        
+    Returns:
+        DataFrame with added columns
+        
+    Example:
+        >>> result = perform_lookup(
+        ...     df=orders,
+        ...     from_df=products,
+        ...     bring='price',
+        ...     against='product_id'
+        ... )
+    """
+    logger = Logger()
+    
+    # Validate parameters
+    validate_lookup_parameters(df, from_df, bring, against)
+    
+    # Normalize parameters
+    bring_list = [bring] if isinstance(bring, str) else bring
+    against_list = [against] if isinstance(against, str) else against
+    
+    # Log operation
+    logger.info(f"Lookup: bringing {bring_list} against {against_list}")
+    
+    # Detect lookup mode based on cardinality
+    mode = detect_lookup_mode(df, from_df, against_list)
+    logger.info(f"Detected lookup mode: {mode}")
+    
+    # Perform the join
+    result = perform_join(df, from_df, bring_list, against_list, mode)
+    
+    # Apply strategy if provided
+    if strategy:
+        result = apply_strategy(result, bring_list, strategy)
+    
+    # Position columns if specified
+    if bring_at:
+        result = position_columns(result, bring_list, bring_at)
+    
+    logger.info(f"Lookup complete: {len(result)} rows, {len(result.columns)} columns")
+    
+    return result
+
+
+def validate_lookup_parameters(
+    df: pl.DataFrame,
+    from_df: pl.DataFrame,
+    bring: Union[str, List[str]],
+    against: Union[str, List[str]]
+) -> None:
+    """
+    Validate lookup parameters.
+    
+    Args:
+        df: Input DataFrame
+        from_df: Reference DataFrame
+        bring: Column(s) to bring
+        against: Key column(s)
+        
+    Raises:
+        ValueError: If validation fails
+    """
+    # Validate DataFrames
+    validate_dataframe(df)
+    validate_not_empty(df)
+    validate_dataframe(from_df)
+    validate_not_empty(from_df)
+    
+    # Normalize to lists
+    bring_list = [bring] if isinstance(bring, str) else bring
+    against_list = [against] if isinstance(against, str) else against
+    
+    # Check that bring columns exist in from_df
+    missing_bring = [col for col in bring_list if col not in from_df.columns]
+    if missing_bring:
+        raise ValueError(
+            f"Bring columns not found in reference DataFrame: {missing_bring}. "
+            f"Available columns: {from_df.columns}"
+        )
+    
+    # Check that against columns exist in both DataFrames
+    missing_in_df = [col for col in against_list if col not in df.columns]
+    if missing_in_df:
+        raise ValueError(
+            f"Key columns not found in input DataFrame: {missing_in_df}. "
+            f"Available columns: {df.columns}"
+        )
+    
+    missing_in_from = [col for col in against_list if col not in from_df.columns]
+    if missing_in_from:
+        raise ValueError(
+            f"Key columns not found in reference DataFrame: {missing_in_from}. "
+            f"Available columns: {from_df.columns}"
+        )
+
+
+def detect_lookup_mode(
+    df: pl.DataFrame,
+    from_df: pl.DataFrame,
+    against: List[str]
+) -> str:
+    """
+    Detect lookup mode based on cardinality.
+    
+    Args:
+        df: Input DataFrame
+        from_df: Reference DataFrame
+        against: Key columns
+        
+    Returns:
+        Lookup mode string ('fetch_if_unique', 'first', etc.)
+    """
+    logger = Logger()
+    
+    # Check cardinality
+    cardinality = check_cardinality(df, from_df, against)
+    
+    if cardinality['type'] == 'one_to_one':
+        return 'fetch_if_unique'
+    elif cardinality['type'] == 'many_to_one':
+        return 'fetch_if_unique'
+    elif cardinality['type'] == 'one_to_many':
+        logger.warning(
+            f"One-to-many relationship detected. "
+            f"Using 'first' mode (taking first match). "
+            f"Max matches per key: {cardinality['max_matches']}"
+        )
+        return 'first'
+    else:  # many_to_many
+        raise ValueError(
+            "Many-to-many relationship detected. "
+            "Cannot perform lookup with many-to-many relationships. "
+            "Consider using a different key or aggregating the reference data first."
+        )
+
+
+def check_cardinality(
+    df: pl.DataFrame,
+    from_df: pl.DataFrame,
+    against: List[str]
+) -> Dict:
+    """
+    Check cardinality of relationship between DataFrames.
+    
+    Args:
+        df: Input DataFrame
+        from_df: Reference DataFrame
+        against: Key columns
+        
+    Returns:
+        Dictionary with cardinality information
+    """
+    # Check if keys are unique in each DataFrame
+    left_unique = df.select(against).n_unique() == len(df)
+    right_unique = from_df.select(against).n_unique() == len(from_df)
+    
+    # Calculate max matches
+    if right_unique:
+        max_matches = 1
+    else:
+        # Group by keys and count
+        counts = from_df.group_by(against).agg(pl.len().alias('count'))
+        max_matches = counts['count'].max()
+    
+    # Determine relationship type
+    if left_unique and right_unique:
+        rel_type = 'one_to_one'
+    elif not left_unique and right_unique:
+        rel_type = 'many_to_one'
+    elif left_unique and not right_unique:
+        rel_type = 'one_to_many'
+    else:
+        rel_type = 'many_to_many'
+    
+    return {
+        'type': rel_type,
+        'left_unique': left_unique,
+        'right_unique': right_unique,
+        'max_matches': max_matches
+    }
+
+
+def perform_join(
+    df: pl.DataFrame,
+    from_df: pl.DataFrame,
+    bring: List[str],
+    against: List[str],
+    mode: str
+) -> pl.DataFrame:
+    """
+    Perform the actual join operation.
+    
+    Args:
+        df: Input DataFrame
+        from_df: Reference DataFrame
+        bring: Columns to bring
+        against: Key columns
+        mode: Lookup mode
+        
+    Returns:
+        DataFrame with joined columns
+    """
+    # Select only needed columns from reference
+    ref_cols = list(set(against + bring))
+    ref_df = from_df.select(ref_cols)
+    
+    # For 'first' mode, take first occurrence of each key
+    if mode == 'first':
+        ref_df = ref_df.unique(subset=against, keep='first')
+    
+    # Perform left join
+    result = df.join(ref_df, on=against, how='left')
+    
+    return result
+
+
+def apply_strategy(
+    df: pl.DataFrame,
+    bring: List[str],
+    strategy: Dict
+) -> pl.DataFrame:
+    """
+    Apply strategy to lookup results.
+    
+    Args:
+        df: DataFrame with joined columns
+        bring: Columns that were brought
+        strategy: Strategy dictionary
+        
+    Returns:
+        DataFrame with strategy applied
+        
+    Note:
+        Strategy can include fill_null, position, etc.
+    """
+    result = df
+    
+    for col in bring:
+        if col in strategy:
+            col_strategy = strategy[col]
+            
+            # Handle fill_null
+            if isinstance(col_strategy, dict) and 'fill_null' in col_strategy:
+                fill_value = col_strategy['fill_null']
+                result = result.with_columns(
+                    pl.col(col).fill_null(fill_value)
+                )
+    
+    return result
+
+
+def position_columns(
+    df: pl.DataFrame,
+    bring: List[str],
+    bring_at: str
+) -> pl.DataFrame:
+    """
+    Position brought columns at specified location.
+    
+    Args:
+        df: DataFrame with new columns
+        bring: Columns to position
+        bring_at: Position specification
+        
+    Returns:
+        DataFrame with repositioned columns
+        
+    Position Specifications:
+        - 'start' - At beginning
+        - 'end' - At end (default)
+        - 'after:column_name' - After specified column
+        - 'before:column_name' - Before specified column
+    """
+    if bring_at == 'start':
+        # Move to start
+        other_cols = [col for col in df.columns if col not in bring]
+        return df.select(bring + other_cols)
+    
+    elif bring_at == 'end':
+        # Already at end (default join behavior)
+        return df
+    
+    elif bring_at.startswith('after:'):
+        # Insert after specified column
+        target_col = bring_at.split(':', 1)[1]
+        if target_col not in df.columns:
+            raise ValueError(f"Target column '{target_col}' not found in DataFrame")
+        
+        # Build new column order
+        new_order = []
+        for col in df.columns:
+            if col not in bring:
+                new_order.append(col)
+                if col == target_col:
+                    new_order.extend(bring)
+        
+        return df.select(new_order)
+    
+    elif bring_at.startswith('before:'):
+        # Insert before specified column
+        target_col = bring_at.split(':', 1)[1]
+        if target_col not in df.columns:
+            raise ValueError(f"Target column '{target_col}' not found in DataFrame")
+        
+        # Build new column order
+        new_order = []
+        for col in df.columns:
+            if col not in bring:
+                if col == target_col:
+                    new_order.extend(bring)
+                new_order.append(col)
+        
+        return df.select(new_order)
+    
+    else:
+        raise ValueError(
+            f"Invalid bring_at specification: {bring_at}. "
+            f"Valid options: 'start', 'end', 'after:column', 'before:column'"
+        )

additory/functions/to/merge.py

@@ -0,0 +1,189 @@
+"""
+Merge multiple DataFrames.
+
+This module provides merging functionality for the to function.
+"""
+
+import polars as pl
+from typing import List, Union, Optional
+
+from additory.common.validation import validate_dataframe, validate_not_empty
+from additory.core.logging import Logger
+
+
+def perform_merge(
+    dfs: List[pl.DataFrame],
+    how: str = 'vertical',
+    on: Optional[Union[str, List[str]]] = None,
+    **kwargs
+) -> pl.DataFrame:
+    """
+    Merge multiple DataFrames.
+    
+    Args:
+        dfs: List of DataFrames to merge
+        how: Merge type ('vertical', 'horizontal', 'diagonal')
+        on: Key column(s) for horizontal merge (required for horizontal)
+        **kwargs: Additional parameters (reserved for future use)
+        
+    Returns:
+        Merged DataFrame
+        
+    Merge Types:
+        - 'vertical' - Stack vertically (union, concat)
+        - 'horizontal' - Join horizontally (requires key)
+        - 'diagonal' - Diagonal concat (fill missing columns)
+        
+    Example:
+        >>> result = perform_merge([df1, df2, df3], how='vertical')
+        >>> result = perform_merge([df1, df2], how='horizontal', on='id')
+    """
+    logger = Logger()
+    
+    # Validate parameters
+    validate_merge_parameters(dfs, how, on)
+    
+    # Log operation
+    logger.info(f"Merging {len(dfs)} DataFrames using '{how}' method")
+    
+    # Dispatch to appropriate merge function
+    if how == 'vertical':
+        result = merge_vertical(dfs)
+    elif how == 'horizontal':
+        result = merge_horizontal(dfs, on)
+    elif how == 'diagonal':
+        result = merge_diagonal(dfs)
+    else:
+        raise ValueError(f"Invalid merge type: {how}")
+    
+    logger.info(f"Merge complete: {len(result)} rows, {len(result.columns)} columns")
+    
+    return result
+
+
+def validate_merge_parameters(
+    dfs: List[pl.DataFrame],
+    how: str,
+    on: Optional[Union[str, List[str]]] = None
+) -> None:
+    """
+    Validate merge parameters.
+    
+    Args:
+        dfs: List of DataFrames to merge
+        how: Merge type
+        on: Key column(s) for horizontal merge
+        
+    Raises:
+        ValueError: If validation fails
+    """
+    # Check that dfs is a list
+    if not isinstance(dfs, list):
+        raise TypeError("dfs must be a list of DataFrames")
+    
+    # Check that we have at least 2 DataFrames
+    if len(dfs) < 2:
+        raise ValueError("Must provide at least 2 DataFrames to merge")
+    
+    # Validate each DataFrame
+    for i, df in enumerate(dfs):
+        validate_dataframe(df)
+        validate_not_empty(df)
+    
+    # Check that how is valid
+    valid_how = ['vertical', 'horizontal', 'diagonal']
+    if how not in valid_how:
+        raise ValueError(
+            f"Invalid merge type: {how}. "
+            f"Valid types: {valid_how}"
+        )
+    
+    # For horizontal merge, on is required
+    if how == 'horizontal' and on is None:
+        raise ValueError("Parameter 'on' is required for horizontal merge")
+    
+    # For horizontal merge, check that on columns exist in all DataFrames
+    if how == 'horizontal' and on is not None:
+        on_list = [on] if isinstance(on, str) else on
+        for i, df in enumerate(dfs):
+            missing_cols = [col for col in on_list if col not in df.columns]
+            if missing_cols:
+                raise ValueError(
+                    f"Key columns not found in DataFrame {i}: {missing_cols}. "
+                    f"Available columns: {df.columns}"
+                )
+
+
+def merge_vertical(dfs: List[pl.DataFrame]) -> pl.DataFrame:
+    """
+    Stack DataFrames vertically.
+    
+    Args:
+        dfs: List of DataFrames to stack
+        
+    Returns:
+        Vertically stacked DataFrame
+        
+    Note:
+        All DataFrames must have the same columns.
+    """
+    # Check that all DataFrames have the same columns
+    first_cols = set(dfs[0].columns)
+    for i, df in enumerate(dfs[1:], 1):
+        if set(df.columns) != first_cols:
+            raise ValueError(
+                f"DataFrame {i} has different columns than DataFrame 0. "
+                f"For vertical merge, all DataFrames must have the same columns. "
+                f"Use 'diagonal' merge to handle different columns."
+            )
+    
+    # Concatenate vertically
+    result = pl.concat(dfs, how='vertical')
+    
+    return result
+
+
+def merge_horizontal(
+    dfs: List[pl.DataFrame],
+    on: Union[str, List[str]]
+) -> pl.DataFrame:
+    """
+    Join DataFrames horizontally.
+    
+    Args:
+        dfs: List of DataFrames to join
+        on: Key column(s) for joining
+        
+    Returns:
+        Horizontally joined DataFrame
+        
+    Note:
+        Performs left joins sequentially.
+    """
+    # Start with first DataFrame
+    result = dfs[0]
+    
+    # Join each subsequent DataFrame
+    for i, df in enumerate(dfs[1:], 1):
+        result = result.join(df, on=on, how='left')
+    
+    return result
+
+
+def merge_diagonal(dfs: List[pl.DataFrame]) -> pl.DataFrame:
+    """
+    Diagonal concat (fill missing columns).
+    
+    Args:
+        dfs: List of DataFrames to concat
+        
+    Returns:
+        Diagonally concatenated DataFrame
+        
+    Note:
+        Missing columns are filled with nulls.
+    """
+    # Concatenate diagonally (Polars handles missing columns)
+    result = pl.concat(dfs, how='diagonal')
+    
+    return result

additory/functions/to/sort.py

@@ -0,0 +1,91 @@
+"""
+Sort DataFrame.
+
+This module provides sorting functionality for the to function.
+"""
+
+import polars as pl
+from typing import Union, List
+
+from additory.common.validation import validate_dataframe, validate_not_empty
+from additory.core.logging import Logger
+
+
+def perform_sort(
+    df: pl.DataFrame,
+    by: Union[str, List[str]],
+    descending: Union[bool, List[bool]] = False,
+    nulls_last: bool = True
+) -> pl.DataFrame:
+    """
+    Sort DataFrame by specified columns.
+    
+    Args:
+        df: Input DataFrame
+        by: Column(s) to sort by
+        descending: Sort in descending order (single bool or list per column)
+        nulls_last: Place nulls at end
+        
+    Returns:
+        Sorted DataFrame
+        
+    Example:
+        >>> result = perform_sort(df, by='date', descending=True)
+        >>> result = perform_sort(df, by=['category', 'price'], 
+        ...                       descending=[False, True])
+    """
+    logger = Logger()
+    
+    # Validate parameters
+    validate_sort_parameters(df, by)
+    
+    # Normalize by to list
+    by_list = [by] if isinstance(by, str) else by
+    
+    # Normalize descending to list
+    if isinstance(descending, bool):
+        descending_list = [descending] * len(by_list)
+    else:
+        descending_list = descending
+        if len(descending_list) != len(by_list):
+            raise ValueError(
+                f"Length of descending ({len(descending_list)}) must match "
+                f"length of by ({len(by_list)})"
+            )
+    
+    # Log operation
+    logger.info(f"Sorting by {by_list}, descending={descending_list}")
+    
+    # Perform sort
+    result = df.sort(by=by_list, descending=descending_list, nulls_last=nulls_last)
+    
+    logger.info(f"Sort complete: {len(result)} rows")
+    
+    return result
+
+
+def validate_sort_parameters(df: pl.DataFrame, by: Union[str, List[str]]) -> None:
+    """
+    Validate sort parameters.
+    
+    Args:
+        df: Input DataFrame
+        by: Column(s) to sort by
+        
+    Raises:
+        ValueError: If validation fails
+    """
+    # Validate DataFrame
+    validate_dataframe(df)
+    validate_not_empty(df)
+    
+    # Normalize by to list
+    by_list = [by] if isinstance(by, str) else by
+    
+    # Check that all columns exist
+    missing_cols = [col for col in by_list if col not in df.columns]
+    if missing_cols:
+        raise ValueError(
+            f"Sort columns not found in DataFrame: {missing_cols}. "
+            f"Available columns: {df.columns}"
+        )