nirs4all.core.logging.formatters module

Console and file formatters for nirs4all logging.

This module provides formatters for human-readable console output and structured file logging, with ASCII and Unicode mode support.

class nirs4all.core.logging.formatters.ConsoleFormatter(use_colors: bool = True, show_elapsed: bool = False, use_unicode: bool = True)[source]

Bases: Formatter

Human-readable console formatter for nirs4all logs.

Produces clean, scannable output optimized for terminal viewing with proper indentation for hierarchy, status symbols, and optional elapsed time.

COLORS = {'BLUE': '\x1b[34m', 'BOLD': '\x1b[1m', 'CYAN': '\x1b[36m', 'DIM': '\x1b[2m', 'GREEN': '\x1b[32m', 'MAGENTA': '\x1b[35m', 'RED': '\x1b[31m', 'RESET': '\x1b[0m', 'WHITE': '\x1b[37m', 'YELLOW': '\x1b[33m'}
LEVEL_COLORS = {'CRITICAL': 'RED', 'DEBUG': 'DIM', 'ERROR': 'RED', 'INFO': 'RESET', 'WARNING': 'YELLOW'}
format(record: LogRecord) → str[source]

Format a log record for console output.

Parameters:

record – Log record to format.

Returns:

Formatted log message.

set_run_start(start_time: datetime) → None[source]

Set the run start time for elapsed time calculation.

Parameters:

start_time – Datetime when the run started.

class nirs4all.core.logging.formatters.FileFormatter[source]

Bases: Formatter

File formatter for human-readable log files.

Produces timestamped, leveled output suitable for file storage and later analysis.

format(record: LogRecord) → str[source]

Format a log record for file output.

Parameters:

record – Log record to format.

Returns:

Formatted log message with timestamp and level.

class nirs4all.core.logging.formatters.JsonFormatter(run_id: str | None = None)[source]

Bases: Formatter

JSON Lines formatter for machine-readable log files.

Produces one JSON object per line for easy parsing by log aggregation systems like ELK, Loki, etc.

format(record: LogRecord) → str[source]

Format a log record as JSON.

Parameters:

record – Log record to format.

Returns:

JSON string representation of the log record.

set_run_id(run_id: str) → None[source]

Set the run ID for log entries.

Parameters:

run_id – Unique run identifier.

class nirs4all.core.logging.formatters.Symbols(use_unicode: bool = True)[source]

Bases: object

Symbol system for log output with ASCII/Unicode modes.

Provides consistent symbols for status indicators, hierarchy markers, and other visual elements in log output.

property arrow: str

Flow/result arrow.

property branch: str

Branch indicator.

property branch_item: str

Branch item prefix.

property error: str

Fatal error.

get_status_symbol(status: Status | None) → str[source]

Get symbol for a status indicator.

Parameters:

status – Status to get symbol for.

Returns:

Appropriate symbol string.

property indent: str

Hierarchy level indent.

property progress: str

In progress.

property separator_heavy: str

Heavy separator line (80 chars).

property separator_light: str

Light separator line (76 chars).

property skipped: str

Skipped (cached).

property starting: str

Starting/beginning of a phase.

property sub_item: str

Sub-item prefix.

property success: str

Successful completion.

property warning: str

Non-fatal issue.

nirs4all.core.logging.formatters.configure_symbols(use_unicode: bool = True) → None[source]

Configure the global symbols instance.

Parameters:

use_unicode – If True, use Unicode symbols. If False, use ASCII-only.

nirs4all.core.logging.formatters.format_duration(seconds: float) → str[source]

Format a duration in seconds to human-readable string.

Parameters:

seconds – Duration in seconds.

Returns:

Human-readable duration string (e.g., “2m 5.9s”, “1h 23m 45s”).

nirs4all.core.logging.formatters.format_number(value: float | int, precision: int = 3) → str[source]

Format a number for display.

Uses thousands separators for large integers and appropriate precision for floats.

Parameters:

  • value – Number to format.

  • precision – Decimal precision for floats.

Returns:

Formatted number string.

Format the run footer block.

Parameters:

  • status – Final run status.

  • duration_seconds – Total run duration in seconds.

  • best_pipeline – Description of best pipeline (optional).

  • metrics – Final metrics dict (optional).

  • use_unicode – If True, use Unicode symbols.

Returns:

Formatted footer block string.

nirs4all.core.logging.formatters.format_run_header(run_name: str, start_time: datetime, environment_info: dict[str, str] | None = None, reproducibility_info: dict[str, str] | None = None, use_unicode: bool = True) → str[source]

Format the run header block.

Parameters:

  • run_name – Name of the run.

  • start_time – Run start timestamp.

  • environment_info – Optional environment details (Python version, etc.).

  • reproducibility_info – Optional reproducibility info (seed, git hash, etc.).

  • use_unicode – If True, use Unicode symbols.

Returns:

Formatted header block string.

nirs4all.core.logging.formatters.format_table(headers: list[str], rows: list[list[str]], use_unicode: bool = True) → str[source]

Format a simple ASCII table.

Parameters:

  • headers – Column headers.

  • rows – Table rows (list of lists).

  • use_unicode – Unused, kept for API consistency.

Returns:

Formatted table string.

nirs4all.core.logging.formatters.get_symbols() → Symbols[source]

Get the global symbols instance.