Exceptions

Exception hierarchy for error handling.

Base Exception

EzplError

EzplError(message: str, error_code: str | None = None)

Bases: Exception

Base exception class for all Ezpl-related errors.

All custom exceptions in the Ezpl framework inherit from this base class, enabling centralized exception handling and consistent error reporting. Each exception includes a message and optional error code for categorization.

Initialize the Ezpl error.

PARAMETER	DESCRIPTION
message	Human-readable error message TYPE: str
error_code	Optional error code for categorization and debugging TYPE: str | None DEFAULT: None

Note

Error codes follow the pattern: COMPONENT_ERROR or OPERATION_ERROR (e.g., "CONFIG_ERROR", "FILE_ERROR") for consistent error tracking.

Source code in src/ezpl/core/exceptions.py

def __init__(self, message: str, error_code: str | None = None) -> None:
    """
    Initialize the Ezpl error.

    Args:
        message: Human-readable error message
        error_code: Optional error code for categorization and debugging

    Note:
        Error codes follow the pattern: COMPONENT_ERROR or OPERATION_ERROR
        (e.g., "CONFIG_ERROR", "FILE_ERROR") for consistent error tracking.
    """
    super().__init__(message)
    self.message = message
    self.error_code = error_code

Specific Exceptions

ConfigurationError

Bases: EzplError

Exception raised for configuration-related errors.

This exception is raised when configuration loading, validation, or processing encounters issues. The optional config_key attribute helps identify which configuration parameter caused the problem.

Initialize the configuration error.

PARAMETER	DESCRIPTION
message	Human-readable error message TYPE: str
config_key	Optional configuration key that caused the error TYPE: str | None DEFAULT: None

Source code in src/ezpl/core/exceptions.py

def __init__(self, message: str, config_key: str | None = None) -> None:
    """
    Initialize the configuration error.

    Args:
        message: Human-readable error message
        config_key: Optional configuration key that caused the error
    """
    super().__init__(message, "CONFIG_ERROR")
    self.config_key = config_key

LoggingError

Bases: EzplError

Exception raised for logging-related errors.

This exception covers issues with logging operations such as file writing, format processing, or handler initialization. The optional handler_type attribute identifies which handler (console, file) caused the error.

Initialize the logging error.

PARAMETER	DESCRIPTION
message	Human-readable error message TYPE: str
handler_type	Optional handler type that caused the error (e.g., "file", "console") TYPE: str | None DEFAULT: None

Source code in src/ezpl/core/exceptions.py

def __init__(self, message: str, handler_type: str | None = None) -> None:
    """
    Initialize the logging error.

    Args:
        message: Human-readable error message
        handler_type: Optional handler type that caused the error (e.g., "file", "console")
    """
    super().__init__(message, "LOGGING_ERROR")
    self.handler_type = handler_type

ValidationError

Bases: EzplError

Exception raised for validation errors.

This exception is raised when input validation fails (e.g., invalid log levels, malformed configuration values). The optional field_name and value attributes help identify what was being validated when the error occurred.

Initialize the validation error.

PARAMETER	DESCRIPTION
message	Human-readable error message TYPE: str
field_name	Optional field name that failed validation TYPE: str | None DEFAULT: None
value	Optional value that failed validation TYPE: str | None DEFAULT: None

Source code in src/ezpl/core/exceptions.py

def __init__(
    self, message: str, field_name: str | None = None, value: str | None = None
) -> None:
    """
    Initialize the validation error.

    Args:
        message: Human-readable error message
        field_name: Optional field name that failed validation
        value: Optional value that failed validation
    """
    super().__init__(message, "VALIDATION_ERROR")
    self.field_name = field_name
    self.value = value

InitializationError

Bases: EzplError

Exception raised for initialization errors.

This exception is raised when Ezpl components fail to initialize properly. The optional component attribute identifies which component (printer, logger, config) encountered the initialization issue.

Initialize the initialization error.

PARAMETER	DESCRIPTION
message	Human-readable error message TYPE: str
component	Optional component that failed to initialize TYPE: str | None DEFAULT: None

Source code in src/ezpl/core/exceptions.py

def __init__(self, message: str, component: str | None = None) -> None:
    """
    Initialize the initialization error.

    Args:
        message: Human-readable error message
        component: Optional component that failed to initialize
    """
    super().__init__(message, "INIT_ERROR")
    self.component = component

FileOperationError

Bases: EzplError

Exception raised for file operation errors.

This exception covers issues with file operations (reading, writing, creating files). The optional file_path and operation attributes help identify which file and operation (read, write, create) failed.

Initialize the file operation error.

PARAMETER	DESCRIPTION
message	Human-readable error message TYPE: str
file_path	Optional file path that caused the error TYPE: str | None DEFAULT: None
operation	Optional operation that failed (e.g., "read", "write", "create") TYPE: str | None DEFAULT: None

Source code in src/ezpl/core/exceptions.py

def __init__(
    self, message: str, file_path: str | None = None, operation: str | None = None
) -> None:
    """
    Initialize the file operation error.

    Args:
        message: Human-readable error message
        file_path: Optional file path that caused the error
        operation: Optional operation that failed (e.g., "read", "write", "create")
    """
    super().__init__(message, "FILE_ERROR")
    self.file_path = file_path
    self.operation = operation

HandlerError

Bases: EzplError

Exception raised for handler-related errors.

This exception covers issues with logging handlers (initialization, configuration, operation failures). The optional handler_name attribute identifies which handler (EzPrinter, EzLogger) caused the problem.

Initialize the handler error.

PARAMETER	DESCRIPTION
message	Human-readable error message TYPE: str
handler_name	Optional handler name that caused the error TYPE: str | None DEFAULT: None

Source code in src/ezpl/core/exceptions.py

def __init__(self, message: str, handler_name: str | None = None) -> None:
    """
    Initialize the handler error.

    Args:
        message: Human-readable error message
        handler_name: Optional handler name that caused the error
    """
    super().__init__(message, "HANDLER_ERROR")
    self.handler_name = handler_name