nirs4all.core.logging.progress module

Progress bar support for nirs4all logging.

This module provides TTY-aware progress bars for tracking long-running operations at multiple levels: run, pipeline, evaluation, and training.

class nirs4all.core.logging.progress.EvaluationProgress(total_pipelines: int, metric_name: str = 'score', higher_is_better: bool = False, description: str = 'Evaluating pipelines', config: ProgressConfig | None = None, disable: bool = False)

Bases: object

Specialized progress tracker for pipeline evaluation.

Provides ML-specific tracking with best score updates and automatic milestone reporting.

Example

>>> progress = EvaluationProgress(
...     total_pipelines=42,
...     metric_name="RMSE",
...     higher_is_better=False
... )
>>>
>>> with progress:
...     for pipeline in pipelines:
...         score = evaluate(pipeline)
...         progress.update(score=score, pipeline_name="SavGol+PLS")

__enter__() → EvaluationProgress

Enter context manager.

__exit__(exc_type: Any, exc_val: Any, exc_tb: Any) → None

Exit context manager.

property best_pipeline: str | None

Get the name of the best pipeline.

property best_score: float | None

Get the current best score.

update(score: float | None = None, pipeline_name: str | None = None, n: int = 1) → bool

Update progress with optional score.

Parameters:

• score – Score for the completed pipeline.

• pipeline_name – Name of the pipeline.

• n – Number of pipelines completed.

Returns:

True if this was a new best score.

class nirs4all.core.logging.progress.MultiLevelProgress(run_total: int | None = None, run_description: str = 'Run progress', config: ProgressConfig | None = None, disable: bool = False)

Bases: object

Multi-level progress tracking for nested operations.

Supports tracking progress at multiple levels: - Run level (overall run progress) - Pipeline level (pipeline evaluation within run) - Fold level (CV folds within pipeline) - Training level (epochs/batches within training)

Example

>>> progress = MultiLevelProgress(
...     run_total=5,
...     run_description="Evaluating datasets"
... )
>>>
>>> with progress.run_level() as run_pbar:
...     for dataset in datasets:
...         with progress.pipeline_level(total=10) as pipe_pbar:
...             for pipeline in pipelines:
...                 # evaluate
...                 pipe_pbar.update(1)
...         run_pbar.update(1)

close_all() → None

Close all active progress bars.

fold_level(total: int, description: str = 'Cross-validation') → ProgressBar

Get fold-level progress bar.

Parameters:

• total – Total number of folds.

• description – Description text.

Returns:

ProgressBar for fold level.

pipeline_level(total: int, description: str = 'Evaluating pipelines') → ProgressBar

Get pipeline-level progress bar.

Parameters:

• total – Total number of pipelines.

• description – Description text.

Returns:

ProgressBar for pipeline level.

run_level(total: int | None = None, description: str | None = None) → ProgressBar

Get run-level progress bar.

Parameters:

• total – Override total (uses init value if None).

• description – Override description.

Returns:

ProgressBar for run level.

training_level(total: int, description: str = 'Training') → ProgressBar

Get training-level progress bar.

Parameters:

• total – Total epochs or batches.

• description – Description text.

Returns:

ProgressBar for training level.

class nirs4all.core.logging.progress.ProgressBar(total: int, description: str = '', config: ProgressConfig | None = None, leave: bool = True, disable: bool = False, unit: str = 'it', file: Any = None, initial: int = 0, ncols: int | None = None)

Bases: object

TTY-aware progress bar for tracking iterations.

Provides a clean progress display that automatically adapts to terminal capabilities. Falls back to periodic line-based updates when not in a TTY.

Example

>>> with ProgressBar(total=100, description="Processing") as pbar:
...     for i in range(100):
...         # do work
...         pbar.update(1)

>>> # Or with iterator
>>> for item in ProgressBar.wrap(items, description="Processing"):
...     # do work with item

COLOR_CYAN = '\x1b[36m'

COLOR_DIM = '\x1b[2m'

COLOR_GREEN = '\x1b[32m'

COLOR_RESET = '\x1b[0m'

COLOR_YELLOW = '\x1b[33m'

EMPTY_ASCII = '-'

EMPTY_UNICODE = '░'

FILLED_ASCII = '#'

FILLED_UNICODE = '█'

__enter__() → ProgressBar

Enter context manager.

__exit__(exc_type: Any, exc_val: Any, exc_tb: Any) → None

Exit context manager.

close() → None

Close the progress bar.

set_description(description: str) → None

Update description text.

Parameters:

description – New description text.

set_postfix(**kwargs: Any) → None

Set postfix values (shown after bar).

Parameters:

**kwargs – Key-value pairs to display.

start() → None

Start the progress bar.

update(n: int = 1, best_score: float | None = None, best_label: str = 'best') → None

Update progress by n items.

Parameters:

• n – Number of items completed.

• best_score – Current best score (for ML tracking).

• best_label – Label for best score display.

classmethod wrap(iterable: Sequence[T], description: str = '', **kwargs: Any) → Iterator[T]

Wrap an iterable with a progress bar.

Parameters:

• iterable – Iterable to wrap.

• description – Progress bar description.

• **kwargs – Additional ProgressBar arguments.

Yields:

Items from the iterable.

class nirs4all.core.logging.progress.ProgressConfig(bar_width: int = 30, show_percentage: bool = True, show_count: bool = True, show_elapsed: bool = True, show_eta: bool = True, show_rate: bool = False, refresh_rate: float = 0.1, use_unicode: bool = True, use_colors: bool = True)

Bases: object

Configuration for progress bar display.

bar_width

Width of the progress bar in characters.

Type:

int

show_percentage

Whether to show percentage.

Type:

bool

show_count

Whether to show current/total count.

Type:

bool

show_elapsed

Whether to show elapsed time.

Type:

bool

show_eta

Whether to show estimated time remaining.

Type:

bool

show_rate

Whether to show items per second.

Type:

bool

refresh_rate

Minimum seconds between updates.

Type:

float

use_unicode

Use Unicode box-drawing characters.

Type:

bool

use_colors

Use ANSI colors.

Type:

bool

bar_width: int = 30

refresh_rate: float = 0.1

show_count: bool = True

show_elapsed: bool = True

show_eta: bool = True

show_percentage: bool = True

show_rate: bool = False

use_colors: bool = True

use_unicode: bool = True

class nirs4all.core.logging.progress.SpinnerProgress(description: str = 'Processing', use_unicode: bool = True, use_colors: bool = True, disable: bool = False)

Bases: object

Spinner for indeterminate progress indication.

Use when the total number of items is unknown.

Example

>>> with SpinnerProgress("Loading data") as spinner:
...     data = load_large_dataset()
...     spinner.update("Parsing...")
...     parsed = parse(data)

FRAMES_ASCII = ['|', '/', '-', '\\']

FRAMES_UNICODE = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']

__enter__() → SpinnerProgress

Enter context manager.

__exit__(exc_type: Any, exc_val: Any, exc_tb: Any) → None

Exit context manager.

start() → None

Start the spinner.

stop(success: bool = True) → None

Stop the spinner.

Parameters:

success – Whether operation completed successfully.

update(description: str | None = None) → None

Update spinner with new description.

Parameters:

description – New description text.

nirs4all.core.logging.progress.configure_progress(bar_width: int = 30, show_percentage: bool = True, show_count: bool = True, show_elapsed: bool = True, show_eta: bool = True, show_rate: bool = False, refresh_rate: float = 0.1, use_unicode: bool = True, use_colors: bool = True) → None

Configure global progress bar settings.

Parameters:

• bar_width – Width of progress bar in characters.

• show_percentage – Show percentage completion.

• show_count – Show current/total count.

• show_elapsed – Show elapsed time.

• show_eta – Show estimated time remaining.

• show_rate – Show items per second.

• refresh_rate – Minimum seconds between display updates.

• use_unicode – Use Unicode characters for bar.

• use_colors – Use ANSI colors.

nirs4all.core.logging.progress.evaluation_progress(total_pipelines: int, metric_name: str = 'score', higher_is_better: bool = False, **kwargs: Any) → EvaluationProgress

Create an evaluation progress tracker.

Parameters:

• total_pipelines – Total pipelines to evaluate.

• metric_name – Name of optimization metric.

• higher_is_better – True if higher is better.

• **kwargs – Additional arguments.

Returns:

EvaluationProgress instance.

nirs4all.core.logging.progress.progress_bar(total: int, description: str = '', **kwargs: Any) → ProgressBar

Create a progress bar.

Parameters:

• total – Total number of items.

• description – Description text.

• **kwargs – Additional ProgressBar arguments.

Returns:

ProgressBar instance.

nirs4all.core.logging.progress.spinner(description: str = 'Processing', **kwargs: Any) → SpinnerProgress

Create a spinner for indeterminate progress.

Parameters:

• description – Description text.

• **kwargs – Additional SpinnerProgress arguments.

Returns:

SpinnerProgress instance.