Skip to content

Logger

Logger module.

This module provides a pre-configured logger for the Perseo framework with support for custom log levels (TRACE, FAIL, SUCCESS), Rich-formatted console output, and plain file logging.

The logger is designed to be flexible and easy to use, with sensible defaults for console output and optional file logging. By default, it uses Rich handlers to provide visually appealing and informative log messages in the console, while file output is plain text for compatibility.

This module is the primary way to log throughout the Perseo ecosystem.

To initialize the logger with sensible defaults, use the initialize function. Otherwise, the logger has a null handler by default and it will be silent until configured.

For advanced usage, you can access the underlying logger instance via the get_logger() function and customize handlers, formatters, or log levels as needed.

Custom Log Levels

  • TRACE (5): hyper-detailed debugging, below DEBUG.
  • FAIL (21): indicates a failed validation or test.
  • SUCCESS (22): indicates a successful validation or test.

Console log default output streams

The logger separates output streams:

  • TRACE, DEBUG, INFO, WARNING, FAIL, SUCCESS -> stdout
  • ERROR, CRITICAL -> stderr

Examples

Basic usage:

Python
import logging
from perseo_core import logger

logger.initialize(log_file="perseo.log", log_level=logging.INFO)

logger.info("Processing started")
logger.error("An error occurred")
logger.fail("Operation failed")
logger.success("Operation completed")

Bypass initialization and add a different file handler:

Python
from perseo_core.logger import get_logger

get_logger().addHandler(handler)

Note

The logger is initialized with both stdout and stderr Rich handlers by default. To customize handlers or log levels, access the underlying logger via get_logger().

Attributes

TRACE module-attribute

Python
TRACE = 5

FAIL module-attribute

Python
FAIL = 21

SUCCESS module-attribute

Python
SUCCESS = 22

FILE_FORMAT module-attribute

Python
FILE_FORMAT = '| %(levelname)-9s @ %(module)-30.30s| %(asctime)s | %(message)s'

info module-attribute

Python
info = _PERSEO_LOGGER.info

debug module-attribute

Python
debug = _PERSEO_LOGGER.debug

warning module-attribute

Python
warning = _PERSEO_LOGGER.warning

error module-attribute

Python
error = _PERSEO_LOGGER.error

critical module-attribute

Python
critical = _PERSEO_LOGGER.critical

fail module-attribute

Python
fail = partial(_PERSEO_LOGGER.log, FAIL)

success module-attribute

Python
success = partial(_PERSEO_LOGGER.log, SUCCESS)

trace module-attribute

Python
trace = partial(_PERSEO_LOGGER.log, TRACE)

Classes

StdOutRichHandler

Bases: RichHandler

Rich console handler for stdout (non-error messages).

Methods:

__init__
Python
__init__() -> None

Initialize the StdOutRichHandler with a custom Rich theme and filter for non-error levels.

StdErrRichHandler

Bases: RichHandler

Rich console handler for stderr (error messages).

Methods:

__init__
Python
__init__() -> None

Initialize the StdErrRichHandler with a custom Rich theme and filter for error levels.

PlainFileFormatter

Bases: Formatter

Plain text formatter for file output (no Rich markup).

Methods:

__init__
Python
__init__() -> None

Initialize the PlainFileFormatter with a plain format string.

CustomFileHandler

Bases: FileHandler

File handler with plain text formatting and UTF-8 encoding.

Methods:

__init__
Python
__init__(filename: str) -> None

Initialize the CustomFileHandler with a plain text formatter and UTF-8 encoding.

Functions:

initialize

Python
initialize(log_file: str | None = None, log_level: int = logging.DEBUG) -> None

Initialize the Perseo logger with Rich console and optional file handler.

Parameters:

Name Type Description Default
log_file str or Path - like

If provided, a file handler will be added to write plain-text logs to this path. Parent directories are created automatically if they do not exist.

 None
log_level int

Logging level to set for the logger (default is logging.DEBUG).

 DEBUG

set_level

Python
set_level(level: int) -> None

Set the logging level for the Perseo logger.

Parameters:

Name Type Description Default
level int

One of TRACE (5), logging.DEBUG (10), logging.INFO (20), FAIL (21), SUCCESS (22), logging.WARNING (30), logging.ERROR (40), logging.CRITICAL (50).

 required

get_logger

Python
get_logger() -> logging.Logger

Get the Perseo logger instance.