Source code for kaxanuk.attribution_analysis.input_handlers.portfolio_input_handler_interface

"""
Abstract interface for portfolio file input handlers.

Define the contract that all portfolio input handlers (CSV, Excel, etc.)
must implement to provide consistent portfolio data loading across
different file formats.
"""

import abc

import pyarrow as pa



class PortfolioInputHandlerInterface(metaclass=abc.ABCMeta):
    """
    Abstract base class for portfolio input handlers.

    Concrete implementations must provide a ``read_portfolio`` method that
    reads a portfolio file and returns a PyArrow Table with ticker identifiers
    and allocation weights indexed by rebalance dates.
    """



    @abc.abstractmethod
    def read_portfolio(self,
                       *,
                       file_name: str
                       ) -> pa.Table:
        """
        Reads a portfolio file and returns a DataFrame with:
        - Index: tickers
        - Columns: rebalance dates as datetime
        - Values: weights (floats between 0 and 1)

        Parameters
        ----------
        file_name : str
            File name of the portfolio to read

        Returns
        -------
        pa.Table
        """
        ...