"""
Column specification types for multi-feature registration.

This module provides the Col dataclass for specifying column-to-feature
mappings when registering multiple features from a single source table.
"""

from dataclasses import dataclass
from typing import List, Optional, Union


@dataclass(frozen=True)
class Col:
    """
    Column specification for feature registration.

    Col provides a way to map source columns to feature names when registering
    features. This is particularly useful when:
    - The source column name differs from the desired feature name
    - Registering multiple features from a single source table

    Attributes:
        column: The source column name in the dataset.
        name: The feature name (alias). If None, uses the column name.

    Example:
        ```python
        # Use column name as feature name
        Col("amount")  # feature_name = "amount"

        # Use custom name (alias)
        Col(column="transaction_amount", name="amt")  # feature_name = "amt"

        # In feature registration
        ff.Feature().from_dataset(
            source,
            entity="user_id",
            values=[Col("amount"), Col("total", name="total_amount")],
            timestamp="ts",
        )
        ```
    """

    column: str
    name: Optional[str] = None

    @property
    def feature_name(self) -> str:
        """Return the feature name (alias or column name)."""
        return self.name if self.name else self.column

    @property
    def source_column(self) -> str:
        """Return the source column name."""
        return self.column


def alias(column: str, name: str) -> Col:
    """
    Create a Col with an alias for the feature name.

    This is a convenience function for creating a Col with a custom feature name.
    It provides a more readable syntax than using Col directly with named arguments.

    Args:
        column: The source column name in the dataset.
        name: The feature name (alias) to use instead of the column name.

    Returns:
        A Col instance with the specified column and name.

    Example:
        ```python
        # Using alias()
        alias("transaction_amount", "amt")  # Equivalent to Col(column="transaction_amount", name="amt")

        # In feature registration
        ff.Feature().from_dataset(
            source,
            entity="user_id",
            values=["balance", alias("transaction_amount", "amt")],
            timestamp="ts",
        )
        ```
    """
    return Col(column=column, name=name)


# Type aliases for column specifications
ColumnSpec = Union[str, Col]
"""A column specification: either a column name string or a Col instance."""

ValuesSpec = Union[str, Col, List[Union[str, Col]]]
"""A values specification: a single column spec or a list of column specs."""
