EzLogger

Loguru-backed file logger handler.

🔍 API

EzLogger

EzLogger(log_file: Path | str, level: str = 'INFO', rotation: str | None = None, retention: str | None = None, compression: str | None = None)

Bases: LoggingHandler

File logger handler with advanced formatting and session management.

This handler provides file-based logging with: - Structured log format - Session separators - HTML tag sanitization - Automatic file creation

Initialize the file logger handler.

Parameters:

Name	Type	Description	Default
log_file	Path | str	Path to the log file	required
level	str	The desired logging level	'INFO'
rotation	str | None	Rotation size (e.g., "10 MB") or time (e.g., "1 day")	None
retention	str | None	Retention period (e.g., "7 days")	None
compression	str | None	Compression format (e.g., "zip", "gz")	None

Raises:

Type	Description
ValidationError	If the provided level is invalid
FileOperationError	If file operations fail

Attributes

level property

level: str

Return the current logging level.

level_manually_set property

level_manually_set: bool

Return whether level was set manually at runtime.

rotation property

rotation: str | None

Return current rotation setting.

retention property

retention: str | None

Return current retention setting.

compression property

compression: str | None

Return current compression setting.

Functions

mark_level_as_configured

mark_level_as_configured() -> None

Mark the current level as coming from configuration (not manual set).

set_level

set_level(level: str) -> None

Set the logging level.

Parameters:

Name	Type	Description	Default
level	str	The desired logging level	required

Raises:

Type	Description
ValidationError	If the provided level is invalid
LoggingError	If level update fails

log

log(level: str, message: Any) -> None

Log a message with the specified level.

Parameters:

Name	Type	Description	Default
level	str	The log level	required
message	Any	The message to log (any type, will be converted to string)	required

Raises:

Type	Description
ValidationError	If the level is invalid
LoggingError	If logging fails

trace

trace(message: Any, *args, **kwargs) -> None

Log a trace message.

debug

debug(message: Any, *args, **kwargs) -> None

Log a debug message.

info

info(message: Any, *args, **kwargs) -> None

Log an info message.

success

success(message: Any, *args, **kwargs) -> None

Log a success message.

warning

warning(message: Any, *args, **kwargs) -> None

Log a warning message.

error

error(message: Any, *args, **kwargs) -> None

Log an error message.

critical

critical(message: Any, *args, **kwargs) -> None

Log a critical message.

exception

exception(message: Any, *args, **kwargs) -> None

Log an exception with traceback.

bind

bind(**kwargs: Any) -> Any

Bind context variables to the logger.

opt

opt(**kwargs: Any) -> Any

Configure logger options.

patch

patch(patcher: Any) -> Any

Patch log records.

get_loguru

get_loguru() -> Logger

Get the underlying Loguru logger instance for advanced usage.

Returns:

* loguru.Logger: The loguru logger instance

Raises:

* LoggingError: If the logger is not initialized

get_log_file

get_log_file() -> Path

Get the current log file path.

Returns:

Type	Description
Path	Path to the log file

get_file_size

get_file_size() -> int

Get the current log file size in bytes.

Returns:

Type	Description
int	File size in bytes, or 0 if file doesn't exist or error occurs

close

close() -> None

Close the logger handler and release file handles.

This method removes the loguru handler to release file handles, which is especially important on Windows where files can remain locked.

add_separator

add_separator() -> None

Add a separator line to the log file for session distinction.

Raises:

Type	Description
FileOperationError	If writing to the log file fails