import pandas as pd
from typing import Optional, Tuple, Dict

from aboba.base import BaseDataProcessor


class BucketProcessor(BaseDataProcessor):
    """
    Processor that assigns rows to buckets based on a hash of a source column.

    This processor creates a new column with bucket assignments by hashing the
    values in a source column and taking the modulo with the number of buckets.
    This ensures consistent bucket assignment for the same source values.

    Examples:
        ```python
        import pandas as pd
        from aboba.processing.bucket_processor import BucketProcessor

        # Create sample data
        data = pd.DataFrame({
            'user_id': ['user1', 'user2', 'user3', 'user4', 'user5']
        })

        # Assign users to 3 buckets
        processor = BucketProcessor(
            source_column='user_id',
            result_column='bucket',
            n_buckets=3
        )
        processed_data, _ = processor.transform(data)
        print(processed_data)
        ```
    """

    def __init__(self, source_column: str, result_column: str, n_buckets: int):
        super().__init__()
        self.source_column = source_column
        self.result_column = result_column
        self.n_buckets = n_buckets

    def transform(self, data: pd.DataFrame) -> Tuple[pd.DataFrame, Optional[Dict]]:
        data = data.copy()
        data[self.result_column] = data[self.source_column].map(hash).abs() % self.n_buckets
        return data, None
