EzLogger

Loguru-backed file logger handler.

🔍 API

EzLogger

EzLogger(
    log_file: Path | str,
    level: str = "INFO",
    rotation: RotationSpec = None,
    retention: RetentionSpec = None,
    compression: CompressionSpec = None,
    *,
    backtrace: bool = True,
    diagnose: bool = False,
)

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	RotationSpec	Rotation trigger — size string ("10 MB"), byte count, datetime.time, datetime.timedelta, or a predicate callable	None
retention	RetentionSpec	Retention policy — duration string ("7 days"), number of files to keep (int), timedelta, or a cleanup callable	None
compression	CompressionSpec	Compression format name (see SUPPORTED_COMPRESSIONS) or a callable applied to the rotated file path	None
backtrace	bool	If True, extend tracebacks beyond the catching point	True
diagnose	bool	If True, include local variable values in tracebacks. Defaults to False, unlike loguru: locals routinely hold secrets, and log files are archived and shipped elsewhere.	False

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: RotationSpec

Return current rotation setting.

retention property

retention: RetentionSpec

Return current retention setting.

compression property

compression: CompressionSpec

Return current compression setting.

backtrace property

backtrace: bool

Return whether tracebacks extend beyond the catching point.

diagnose property

diagnose: bool

Return whether local variable values appear in tracebacks.

Methods:

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