Input Handlers#

Concrete input handlers for loading portfolio and benchmark weights from CSV, Excel, and returns files, plus the contract they implement. See Data Formats for the expected file layouts.

CSV portfolio input handler for reading portfolio allocation files.

Read portfolio weight files in CSV format, supporting both horizontal (Ticker | Date1 | Date2 | …) and vertical (Date | Ticker1 | Ticker2 | …) layouts with automatic format detection and transposition.

class CsvPortfolioInputHandler(base_dir: str)[source]#

Bases: PortfolioInputHandlerInterface

Handles reading and parsing of CSV portfolio files.

This class reads a portfolio CSV file, infers decimal precision dynamically for numeric columns, and converts them into a typed PyArrow table suitable for financial pipelines.

Supports both horizontal and vertical formats:

  • Horizontal: Ticker | Date1 | Date2 | …

  • Vertical: Date | Ticker1 | Ticker2 | … (auto-transposes to horizontal)

base_dir#

Directory where portfolio CSV files are located.

Type:

Path

read_portfolio(*, file_name: str) → Table[source]#

Reads a portfolio from a CSV file and converts it into a typed PyArrow Table.

Automatically detects horizontal vs vertical format and returns horizontal format.

Parameters:

file_name (str) – Name of the CSV file (with or without .csv extension).

Returns:

Processed PyArrow table containing portfolio tickers and weights in horizontal format.

Return type:

pa.Table

Raises:

  • FileNotFoundError – If the file does not exist in the specified base directory.

  • ReadingCsvPortfolioError – If the CSV cannot be read or processed correctly.

Excel portfolio input handler for reading .xlsx portfolio allocation files.

Read portfolio weight files in Excel format, supporting both horizontal (Ticker | Date1 | Date2 | …) and vertical (Date | Ticker1 | Ticker2 | …) layouts with automatic format detection, transposition, and decimal precision inference.

class ExcelPortfolioInputHandler(base_dir: str)[source]#

Bases: PortfolioInputHandlerInterface

Professional Excel portfolio file handler for financial systems.

This class provides a robust interface for reading and processing Excel-based portfolio files (.xlsx format). It automatically handles data type inference, decimal precision detection for financial data, and converts portfolio information into optimized PyArrow tables for high-performance analytics.

Supports both horizontal and vertical formats:

  • Horizontal: Ticker | Date1 | Date2 | …

  • Vertical: Date | Ticker1 | Ticker2 | … (auto-transposes to horizontal)

base_dir#

The base directory path where Excel portfolio files are stored.

Type:

pathlib.Path

read_portfolio(*, file_name: str) → Table[source]#

Read and process an Excel portfolio file into a typed PyArrow table.

This method performs comprehensive processing of Excel portfolio files, including automatic file extension handling, data type inference, decimal precision detection, and conversion to an optimized PyArrow table format.

Automatically detects horizontal vs vertical format and returns horizontal format.

Parameters:

file_name (str) – The name of the Excel portfolio file to read. Can be provided with or without the .xlsx extension.

Returns:

A typed PyArrow table containing the processed portfolio data in horizontal format.

Return type:

pyarrow.Table

Raises:

  • MissingPortfolioError – If the file does not exist in the specified base directory.

  • ReadingExcelPortfolioError – If the Excel file cannot be read or processed correctly.

class WeightsInputHandler(input_base_dir: str, input_subdir: str, file_name: str, dates_column_name: str = 'm_date')[source]#

Bases: InputHandlerInterface

Read portfolio weights input.

Parameters:

  • input_base_dir (str) – The path that will contain all the input subdirectories

  • input_subdir (str) – The subdirectory to which the input data files will be readed

input_data(*, ticker: str) → PortfolioDailyWeights[source]#
Parameters:

ticker (str) – The ticker of the stock, on which the output csv file will be named.

Return type:

Pandas DataFrame

read_csv_intersection(path, wanted_cols, index_col=0, **kwargs)[source]#
class PortfolioReturnsInputHandler(*, input_base_dir: str, input_subdir: str)[source]#

Bases: InputHandlerInterface

Read portfolio weights input.

Parameters:

  • input_base_dir (str) – The path that will contain all the input subdirectories

  • input_subdir (str) – The subdirectory to which the input data files will be readed

input_data(*, ticker: str) → PortfolioReturns[source]#

Output the ticker’s processed data to a csv file.

Parameters:

ticker (str) – The ticker of the stock, on which the output csv file will be named.

Return type:

Pandas DataFrame

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.

class PortfolioInputHandlerInterface[source]#

Bases: object

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.

abstractmethod read_portfolio(*, file_name: str) → Table[source]#

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

Return type:

pa.Table