Source code for kaxanuk.attribution_analysis.input_handlers.input_handler_interface

"""
Abstract base class interface for handling input data sources in the attribution analysis engine.

This module defines the contract that all input handlers must implement to provide
data loading capabilities for different data sources (CSV, Parquet, Excel, etc.).
Input handlers are responsible for loading and formatting ticker data.
"""

import abc

import pyarrow as pa

from kaxanuk.attribution_analysis.entities.configuration import Configuration



class InputHandlerInterface(metaclass=abc.ABCMeta):
    """
    Abstract base class for input data handlers.

    This interface defines the contract that all input handlers must implement
    to provide consistent data loading capabilities across different data sources.
    Input handlers are responsible for loading ticker data and checking data
    availability for the engine.

    All concrete implementations must provide methods to:
    - Load data for a specific ticker
    - Check if data exists for a ticker
    """



    @abc.abstractmethod
    def input_data(
            self,
            *,
            ticker: str,
            configuration: Configuration,
            equivalence_dict: dict[str, str]
    ) -> pa.Table:
        """
        Load and return data for a specific ticker.

        Parameters
        ----------
        ticker : str
            The ticker symbol for which to load data.
        configuration : Configuration
            Configuration object containing parameters and data source
            settings.
        equivalence_dict : dict[str, str]
            Dictionary mapping column names to standardized column names
            for data consistency.

        Returns
        -------
        pa.Table
            PyArrow Table containing the loaded ticker data with
            standardized column names and proper data types.
        """




    @abc.abstractmethod
    def file_exists(
            self,
            *,
            ticker: str,
            configuration: Configuration,
    ) -> bool:
        """
        Check if data exists for a specific ticker.

        Parameters
        ----------
        ticker : str
            The ticker symbol to check for data availability.
        configuration : Configuration
            Configuration object containing parameters and data source
            settings.

        Returns
        -------
        bool
            True if data exists for the ticker, False otherwise.
        """