nirs4all.core.logging.handlers module

Custom log handlers for nirs4all logging.

This module provides specialized handlers for throttled progress updates, file rotation, and other custom logging behaviors.

class nirs4all.core.logging.handlers.BufferedHandler(max_size: int = 1000)

Bases: Handler

Handler that buffers log records for batch processing.

Useful for collecting logs during a phase and outputting them together, e.g., for branch comparison summaries.

clear() → None

Clear the buffer.

emit(record: LogRecord) → None

Buffer the log record.

Parameters:

record – Log record to buffer.

flush_to(handler: Handler) → None

Flush buffered records to another handler.

Parameters:

handler – Handler to send buffered records to.

get_records() → list[LogRecord]

Get buffered records.

Returns:

List of buffered log records.

class nirs4all.core.logging.handlers.NullHandler(level=0)

Bases: Handler

Handler that discards all log records.

Used when logging should be completely silent.

emit(record: LogRecord) → None

Discard the log record.

Parameters:

record – Log record (ignored).

class nirs4all.core.logging.handlers.RotatingRunFileHandler(log_dir: Path, run_id: str, max_runs: int = 100, max_age_days: int | None = 30, max_bytes: int | None = None, compress_rotated: bool = True, json_output: bool = False)

Bases: Handler

Handler that writes logs to run-specific files with rotation.

Creates a new log file for each run, with optional rotation to limit total log storage. Supports both count-based and age-based rotation policies.

Features:

• Separate log files per run

• Count-based rotation (max_runs)

• Age-based rotation (max_age_days)

• Size-based rotation (max_bytes)

• Optional gzip compression for rotated logs

• Optional JSON Lines output

close() → None

Close file handles.

emit(record: LogRecord) → None

Write log record to file(s).

Parameters:

record – Log record to write.

get_json_file_path() → Path | None

Get the path to the current JSON log file.

Returns:

Path to JSON log file, or None if not enabled.

get_log_file_path() → Path

Get the path to the current log file.

Returns:

Path to the current log file.

class nirs4all.core.logging.handlers.ThrottledHandler(base_handler: Handler, min_interval: float = 5.0)

Bases: Handler

Handler that throttles progress messages to avoid flooding.

Uses time-based and percentage-based throttling to limit progress updates while still reporting important milestones.

MILESTONES = {10, 25, 50, 75, 90, 100}

close() → None

Close this handler and the base handler.

emit(record: LogRecord) → None

Emit a log record, throttling progress messages.

Parameters:

record – Log record to potentially emit.

reset() → None

Reset throttle state for a new operation.