Exceptions

Exception hierarchy for Confii.

This module defines a comprehensive exception hierarchy for better error handling and debugging throughout the Confii library.

exception confii.exceptions.ConfigAccessError(message: str, source: str | None = None, operation: str | None = None, original_error: Exception | None = None)

Bases: ConfiiError

Raised when accessing configuration fails.

This exception is raised when configuration cannot be accessed due to permission issues, network problems, etc.

__init__(message: str, source: str | None = None, operation: str | None = None, original_error: Exception | None = None) → None

Initialize the configuration access error.

Parameters:

• message – Error message

• source – Source that cannot be accessed

• operation – Operation that failed (read, write, list, etc.)

• original_error – Original exception that caused this error

exception confii.exceptions.ConfigFormatError(message: str, source: str | None = None, line_number: int | None = None, column_number: int | None = None, format_type: str | None = None, original_error: Exception | None = None)

Bases: ConfiiError

Raised when a configuration file format is invalid.

This exception is raised when parsing configuration files fails due to format errors (e.g., invalid YAML, malformed JSON).

__init__(message: str, source: str | None = None, line_number: int | None = None, column_number: int | None = None, format_type: str | None = None, original_error: Exception | None = None) → None

Initialize the configuration format error.

Parameters:

• message – Error message

• source – Source file with format error

• line_number – Line number where error occurred

• column_number – Column number where error occurred

• format_type – Format type (yaml, json, toml, etc.)

• original_error – Original exception that caused this error

exception confii.exceptions.ConfigLoadError(message: str, source: str | None = None, loader_type: str | None = None, original_error: Exception | None = None)

Bases: ConfiiError

Raised when configuration loading fails.

This exception is raised when a loader cannot successfully load a configuration from its source (file, remote URL, etc.).

__init__(message: str, source: str | None = None, loader_type: str | None = None, original_error: Exception | None = None) → None

Initialize the configuration load error.

Parameters:

• message – Error message

• source – Source file/URL that failed to load

• loader_type – Type of loader that failed

• original_error – Original exception that caused this error

exception confii.exceptions.ConfigMergeConflictError(message: str, key: str, old_value: Any = None, new_value: Any = None, old_source: str | None = None, new_source: str | None = None)

Bases: ConfiiError

Raised when configuration merge conflicts occur.

This exception is raised when merging configurations results in unresolvable conflicts (e.g., incompatible types, conflicting values).

__init__(message: str, key: str, old_value: Any = None, new_value: Any = None, old_source: str | None = None, new_source: str | None = None) → None

Initialize the configuration merge conflict error.

Parameters:

• message – Error message

• key – Configuration key that has a conflict

• old_value – Value from the base/old configuration

• new_value – Value from the new configuration

• old_source – Source of the old value

• new_source – Source of the new value

exception confii.exceptions.ConfigNotFoundError(message: str, key: str, available_keys: list | None = None)

Bases: ConfiiError

Raised when a configuration key or value is not found.

This exception is raised when trying to access a configuration key that doesn’t exist.

__init__(message: str, key: str, available_keys: list | None = None) → None

Initialize the configuration not found error.

Parameters:

• message – Error message

• key – Configuration key that was not found

• available_keys – List of available keys (for helpful error messages)

exception confii.exceptions.ConfigValidationError(message: str, key: str | None = None, value: Any = None, schema_path: str | None = None, validation_errors: list | None = None, original_error: Exception | None = None)

Bases: ConfiiError

Raised when configuration validation fails.

This exception is raised when configuration values don’t match the expected schema or validation rules.

__init__(message: str, key: str | None = None, value: Any = None, schema_path: str | None = None, validation_errors: list | None = None, original_error: Exception | None = None) → None

Initialize the configuration validation error.

Parameters:

• message – Error message

• key – Configuration key that failed validation

• value – Value that failed validation

• schema_path – Path to schema definition (if applicable)

• validation_errors – List of detailed validation errors

• original_error – Original exception that caused this error

exception confii.exceptions.ConfiiError(message: str, context: Dict[str, Any] | None = None)

Bases: Exception

Base exception for all Confii errors.

All Confii specific exceptions inherit from this class, making it easy to catch any Confii related error.

__init__(message: str, context: Dict[str, Any] | None = None) → None

Initialize the exception.

Parameters:

• message – Human-readable error message

• context – Optional context dictionary with additional error information (e.g., file path, line number, key, value)

__str__() → str

Return formatted error message with context if available.