Exceptions¶

Exception hierarchy for structured error handling in ezplog.

Overview¶

All ezplog exceptions inherit from EzplError. Each exception carries a message (human-readable) and an error_code (machine-readable category). Subclasses add context-specific attributes to help identify the source of the error.

from ezplog import EzplError, ValidationError, ConfigurationError

try:
    from ezplog import Ezpl
    ezpl = Ezpl(log_level="INVALID")
except ValidationError as exc:
    print(exc)              # [VALIDATION_ERROR] Invalid log level: INVALID
    print(exc.field_name)   # "level"
    print(exc.value)        # "INVALID"
except EzplError as exc:
    print(exc.error_code)   # fallback for any other ezplog error

Hierarchy¶

EzplError (base)
├── ConfigurationError   CONFIG_ERROR   — config load / validation failure
├── LoggingError         LOGGING_ERROR  — file write / handler init failure
├── ValidationError      VALIDATION_ERROR — invalid input (levels, patterns)
├── InitializationError  INIT_ERROR     — component startup failure
├── FileOperationError   FILE_ERROR     — read / write / create failure
└── HandlerError         HANDLER_ERROR  — handler operation failure

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.

Parameters:

Name	Type	Description	Default
`message`	`str`	Human-readable error message	required
`error_code`	`str \| None`	Optional error code for categorization and debugging	`None`

Note

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

options: show_source: false show_root_heading: true show_root_full_path: false show_symbol_type_heading: true members_order: source show_if_no_docstring: false show_signature_annotations: true separate_signature: true merge_init_into_class: true docstring_style: google docstring_section_style: table

Specific Exceptions¶

ConfigurationError¶

Raised when configuration loading or validation fails (e.g., corrupted config.json). The optional config_key attribute names the problematic configuration key.

ConfigurationError ¶

ConfigurationError(message: str, config_key: str | None = None)

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.

Parameters:

Name	Type	Description	Default
`message`	`str`	Human-readable error message	required
`config_key`	`str \| None`	Optional configuration key that caused the error	`None`

options: show_source: false show_root_heading: false members_order: source show_signature_annotations: true separate_signature: true merge_init_into_class: true docstring_style: google docstring_section_style: table

LoggingError¶

Raised when a log write or handler initialization fails. The optional handler_type attribute is "file" or "console".

LoggingError ¶

LoggingError(message: str, handler_type: str | None = None)

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.

Parameters:

Name	Type	Description	Default
`message`	`str`	Human-readable error message	required
`handler_type`	`str \| None`	Optional handler type that caused the error (e.g., "file", "console")	`None`

options: show_source: false show_root_heading: false members_order: source show_signature_annotations: true separate_signature: true merge_init_into_class: true docstring_style: google docstring_section_style: table

ValidationError¶

Raised when a caller passes an invalid value (e.g., an unrecognized log level string). The field_name and value attributes identify what failed validation.

ValidationError ¶

ValidationError(message: str, field_name: str | None = None, value: str | None = None)

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.

Parameters:

Name	Type	Description	Default
`message`	`str`	Human-readable error message	required
`field_name`	`str \| None`	Optional field name that failed validation	`None`
`value`	`str \| None`	Optional value that failed validation	`None`

options: show_source: false show_root_heading: false members_order: source show_signature_annotations: true separate_signature: true merge_init_into_class: true docstring_style: google docstring_section_style: table

InitializationError¶

Raised when a component fails to start. The component attribute names the component ("printer", "logger", "config").

InitializationError ¶

InitializationError(message: str, component: str | None = None)

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.

Parameters:

Name	Type	Description	Default
`message`	`str`	Human-readable error message	required
`component`	`str \| None`	Optional component that failed to initialize	`None`

options: show_source: false show_root_heading: false members_order: source show_signature_annotations: true separate_signature: true merge_init_into_class: true docstring_style: google docstring_section_style: table

FileOperationError¶

Raised when a file cannot be read, written, or created. The file_path and operation attributes identify which file and operation failed.

FileOperationError ¶

FileOperationError(message: str, file_path: str | None = None, operation: str | None = None)

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.

Parameters:

Name	Type	Description	Default
`message`	`str`	Human-readable error message	required
`file_path`	`str \| None`	Optional file path that caused the error	`None`
`operation`	`str \| None`	Optional operation that failed (e.g., "read", "write", "create")	`None`

options: show_source: false show_root_heading: false members_order: source show_signature_annotations: true separate_signature: true merge_init_into_class: true docstring_style: google docstring_section_style: table

HandlerError¶

Raised when a handler operation fails outside of normal logging flow. The handler_name attribute identifies the handler ("EzPrinter", "EzLogger").

HandlerError ¶

HandlerError(message: str, handler_name: str | None = None)

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.

Parameters:

Name	Type	Description	Default
`message`	`str`	Human-readable error message	required
`handler_name`	`str \| None`	Optional handler name that caused the error	`None`

options: show_source: false show_root_heading: false members_order: source show_signature_annotations: true separate_signature: true merge_init_into_class: true docstring_style: google docstring_section_style: table