Configuration#

The Excel configurator that reads and validates the run configuration, the abstract contracts it implements, and the configuration entity it produces. See Configuration Reference for the Excel parameters workbook this powers.

Loads and returns a Configuration entity from an Excel file

Functions#

init:

Loads and returns Configuration

class ExcelConfigurator(file_path: str, logger_format: str = '[%(levelname)s] %(message)s')[source]#

Bases: ConfiguratorInterface

Build a Configuration and dashboard port from an Excel parameters file.

On construction, the workbook at file_path is loaded and its General sheet is parsed according to SHEET_KEY_VALUES. The parameters_format_version cell is checked against the package’s __parameters_format_version__, method-flag cells (e.g. brinson_fachler_method) are coerced to booleans, and the dashboard_port cell is validated as an integer in range. Any ConfigurationError or ConfigurationHandlerError raised while parsing is logged as critical and terminates the process via sys.exit, rather than propagating to the caller.

Parameters:

  • file_path (str) – Path to the Excel configuration file.

  • logger_format (str) – Format string injected into the temporary bootstrap logger used while parsing file_path.

METHOD_FLAG_VALUES#

Accepted case-insensitive text values ('yes'/'no') for method-flag fields, mapped to their boolean equivalent.

Type:

Mapping[str, bool]

SHEET_KEY_VALUES#

Schema of required sheets and the key values to extract from each, passed to _extract_workbook_key_values_by_schema.

Type:

Mapping[str, tuple[str, …]]

METHOD_FLAG_VALUES = mappingproxy({'yes': True, 'no': False})#
SHEET_KEY_VALUES = mappingproxy({'General': ('input_directory', 'weights_portfolio_directory', 'weights_benchmark_directory', 'benchmark_returns_directory', 'investable_assets_directory', 'factor_returns_by_factor_directory', 'user_column_date', 'user_column_price', 'market_data_input_format', 'portfolio_input_format', 'start_date', 'end_date', 'portfolio_file_name', 'benchmark_file_name', 'benchmark_return_file_name', 'brinson_fachler_method', 'factor_model_method', 'dashboard_port', 'parameters_format_version')})#
get_configuration() → Configuration[source]#

Return the configuration parsed from the Excel parameters file.

Returns:

The configuration built during __init__.

Return type:

Configuration

get_dashboard_port() → int[source]#

Return the dashboard port parsed from the Excel configuration.

Returns:

A valid port number (1-9999).

Return type:

int

Interface for classes creating Configuration entities and related dependencies.

class ConfiguratorInterface[source]#

Bases: object

Abstract base class for classes that create Configuration entities.

Concrete implementations must provide the run Configuration and the port on which the dashboard should be served.

DASHBOARD_PORT_MIN#

Minimum allowed value for the dashboard port.

Type:

int

DASHBOARD_PORT_MAX#

Maximum allowed value for the dashboard port.

Type:

int

DASHBOARD_PORT_MAX = 9999#
DASHBOARD_PORT_MIN = 1#
abstractmethod get_configuration() → Configuration[source]#

Build and return the validated run configuration.

Returns:

The configuration for the current attribution analysis run.

Return type:

Configuration

abstractmethod get_dashboard_port() → int[source]#

Return the port on which the dashboard should be served.

Returns:

Port number between DASHBOARD_PORT_MIN and DASHBOARD_PORT_MAX.

Return type:

int

Interface for classes creating Configuration entities and their input handler.

class ConfiguratorInterface[source]#

Bases: object

Abstract base class for configurator implementations.

Concrete implementations must provide the run Configuration and the InputHandlerInterface used to load ticker data for that configuration.

abstractmethod get_configuration() → Configuration[source]#

Build and return the validated run configuration.

Returns:

The configuration for the current attribution analysis run.

Return type:

Configuration

abstractmethod get_input_handler() → InputHandlerInterface[source]#

Build and return the input handler matching the configuration.

Returns:

The input handler used to load ticker data.

Return type:

InputHandlerInterface

Interface for generating output from each ticker’s obtained and calculated columns

class InputHandlerInterface[source]#

Bases: object

Abstract base class for output-generating input handlers.

Concrete implementations must provide an input_data method that assembles a ticker’s obtained and calculated columns into a single pandas.DataFrame.

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

Load and return the obtained and calculated columns for a ticker.

Parameters:

ticker (str) – The ticker symbol for which to assemble output data.

Returns:

DataFrame containing the ticker’s obtained and calculated columns.

Return type:

DataFrame

Dataclass encapsulating the user’s selected configuration.

Configuration instances are typically built by config handlers (e.g. kaxanuk.attribution_analysis.config_handlers.excel_configurator) from user-supplied settings, and consumed by the attribution engine to locate input files and select processing options.

class Configuration(input_directory: str, weights_portfolio_directory: str, weights_benchmark_directory: str, benchmark_returns_directory: str, investable_assets_directory: str, factor_returns_by_factor_directory: str, portfolio_file_name: str, benchmark_file_name: str, benchmark_return_file_name: str, user_column_date: str, user_column_price: str, market_data_input_format: str, portfolio_input_format: str, start_date: DateConfig, end_date: DateConfig, brinson_fachler_method: bool, factor_model_method: bool)[source]#

Bases: object

Immutable, validated configuration for a single attribution analysis run.

All fields are validated in __post_init__, which raises ConfigurationError on the first invalid field found. start_date and end_date are additionally normalized from datetime.datetime to datetime.date if needed.

Parameters:

  • input_directory (str) – Base directory containing market data input files.

  • weights_portfolio_directory (str) – Directory containing portfolio weights files.

  • weights_benchmark_directory (str) – Directory containing benchmark weights files.

  • benchmark_returns_directory (str) – Directory containing benchmark returns files.

  • investable_assets_directory (str) – Directory containing investable assets market data files.

  • factor_returns_by_factor_directory (str) – Directory containing per-factor returns files, one file per factor.

  • portfolio_file_name (str) – File name (without extension) of the portfolio weights file, in weights_portfolio_directory.

  • benchmark_file_name (str) – File name (without extension) of the benchmark weights file, in weights_benchmark_directory.

  • benchmark_return_file_name (str) – File name (without extension) of the benchmark returns file, in benchmark_returns_directory.

  • user_column_date (str) – Name of the date column as it appears in the user’s input files.

  • user_column_price (str) – Name of the price column as it appears in the user’s input files.

  • market_data_input_format ({"csv", "parquet"}) – File format of the market data input files.

  • portfolio_input_format ({"csv", "excel"}) – File format of the portfolio/benchmark weights input files.

  • start_date (datetime.date or datetime.datetime or {"auto"}) – Start date of the analysis period, or "auto" to derive it from the portfolio data. datetime.datetime values are normalized to datetime.date after validation.

  • end_date (datetime.date or datetime.datetime or {"auto"}) – End date of the analysis period, or "auto" to derive it from the portfolio data. datetime.datetime values are normalized to datetime.date after validation.

  • brinson_fachler_method (bool) – Whether to run the Brinson-Fachler attribution method.

  • factor_model_method (bool) – Whether to run the factor model attribution method.

Raises:

ConfigurationError – If any field fails validation (see __post_init__).

benchmark_file_name: str#
benchmark_return_file_name: str#
benchmark_returns_directory: str#
brinson_fachler_method: bool#
end_date: DateConfig#
factor_model_method: bool#
factor_returns_by_factor_directory: str#
input_directory: str#
investable_assets_directory: str#
market_data_input_format: str#
portfolio_file_name: str#
portfolio_input_format: str#
start_date: DateConfig#
user_column_date: str#
user_column_price: str#
weights_benchmark_directory: str#
weights_portfolio_directory: str#
type DateConfig = date | Literal['auto']#