tessl/pypi-enlighten

Enlighten Progress Bar is a console progress bar library for Python

—

Pending

Overview

Eval results

Files

Manager Operations

Name: tessl/pypi-enlighten
Author: tessl

Core manager functionality for creating and controlling progress bar displays. Managers handle TTY detection, coordinate multiple concurrent progress bars, and provide environment-specific rendering (terminal vs Jupyter notebook).

Capabilities

Manager Factory

Get the appropriate manager instance based on the environment, automatically detecting TTY capabilities and notebook contexts.

def get_manager(stream=None, counter_class=Counter, **kwargs):
    """
    Get a manager instance appropriate for the current environment.

    Parameters:
    - stream: Output stream (default: sys.__stdout__)
    - counter_class: Progress bar class (default: Counter)
    - **kwargs: Additional arguments passed to manager

    Returns:
    Manager or NotebookManager instance based on environment

    If running in a Jupyter notebook, returns NotebookManager.
    Otherwise returns Manager with TTY detection and auto-disable for non-TTY streams.
    """

Terminal Manager

Manager for terminal-based progress bar display with TTY integration, companion stream handling, and resize support.

class Manager:
    def __init__(self, stream=None, counter_class=Counter, status_bar_class=StatusBar, 
                 set_scroll=True, companion_stream=None, enabled=True, 
                 no_resize=False, threaded=None, width=None, **kwargs):
        """
        Terminal manager for progress bars.

        Parameters:
        - stream: Output stream (default: sys.__stdout__)
        - counter_class: Counter class for progress bars (default: Counter)
        - status_bar_class: Status bar class (default: StatusBar)
        - set_scroll: Enable scroll area redefinition (default: True)
        - companion_stream: Secondary stream for coordinate handling
        - enabled: Manager status (default: True)
        - no_resize: Disable window resize handling (default: False)
        - threaded: Defer resize handling until next write (default: auto-detect)
        - width: Static output width override
        - **kwargs: Default values for counter creation
        """

    def counter(self, **kwargs):
        """
        Create a new progress bar counter.

        Parameters:
        - total: Total expected count
        - desc: Description text
        - unit: Unit label for rate display
        - leave: Leave bar visible after completion (default: True)
        - **kwargs: Additional counter options

        Returns:
        Counter instance
        """

    def status_bar(self, *args, **kwargs):
        """
        Create a status bar for text updates.

        Parameters:
        - *args: Direct status text arguments
        - **kwargs: Status bar configuration options

        Returns:
        StatusBar instance
        """

    def stop(self):
        """
        Stop the manager and clean up all counters.
        Disables all associated counters and restores terminal state.
        """

    def write(self, output='', flush=True, counter=None, **kwargs):
        """
        Write output to the display.

        Parameters:
        - output: Text or callable to output
        - flush: Flush streams after writing (default: True)
        - counter: Associated counter for positioning
        - **kwargs: Arguments passed to callable output
        """

    def remove(self, counter):
        """
        Remove counter from manager.

        Parameters:
        - counter: Counter or StatusBar instance to remove

        Generally this method should not be called directly.
        Use counter.close() instead.
        """

    def __enter__(self):
        """
        Context manager entry.
        
        Returns:
        Manager instance
        """

    def __exit__(self, *args):
        """
        Context manager exit. Calls stop() to clean up.
        """

Notebook Manager

Manager optimized for Jupyter notebook environments with HTML output and DisplayHandle integration.

class NotebookManager:
    def __init__(self, counter_class=Counter, status_bar_class=StatusBar, 
                 enabled=True, width=100, **kwargs):
        """
        Notebook manager for Jupyter environments.

        Parameters:
        - counter_class: Counter class (default: Counter)
        - status_bar_class: Status bar class (default: StatusBar)
        - enabled: Manager status (default: True)
        - width: Static output width (default: 100)
        - **kwargs: Default values for counter creation

        Note: stream, set_scroll, companion_stream, no_resize, and threaded
        parameters are ignored in notebook environments.
        """

    def counter(self, **kwargs):
        """
        Create a progress bar counter for notebook display.

        Returns:
        Counter instance configured for HTML output
        """

    def status_bar(self, *args, **kwargs):
        """
        Create a status bar for notebook display.

        Returns:
        StatusBar instance configured for HTML output
        """

    def write(self, output='', flush=True, counter=None, **kwargs):
        """
        Write output to the display.

        Parameters:
        - output: Text or callable to output
        - flush: Flush streams after writing (default: True)
        - counter: Associated counter for positioning
        - **kwargs: Arguments passed to callable output
        """

    def remove(self, counter):
        """
        Remove counter from manager.

        Parameters:
        - counter: Counter or StatusBar instance to remove
        """

    def stop(self):
        """Stop the manager and finalize notebook display."""

    def __enter__(self):
        """
        Context manager entry.
        
        Returns:
        NotebookManager instance
        """

    def __exit__(self, *args):
        """
        Context manager exit. Calls stop() to clean up.
        """

Usage Examples

Basic Manager Usage

import enlighten
import time

# Auto-detect environment and get appropriate manager
manager = enlighten.get_manager()

# Create multiple progress bars
pbar1 = manager.counter(total=100, desc='Task 1', unit='items')
pbar2 = manager.counter(total=50, desc='Task 2', unit='files')
status = manager.status_bar()

# Update progress
for i in range(100):
    pbar1.update()
    if i % 2 == 0:
        pbar2.update()
    status.update(f'Processing item {i+1}')
    time.sleep(0.1)

# Clean up
manager.stop()

Custom Manager Configuration

import enlighten
import sys

# Create manager with custom configuration
manager = enlighten.Manager(
    stream=sys.stderr,          # Use stderr instead of stdout
    enabled=True,               # Force enable even if not TTY
    no_resize=True,            # Disable resize handling
    width=80                   # Fixed width
)

# Create counter with custom defaults
pbar = manager.counter(
    total=100,
    desc='Custom Task',
    unit='ops',
    leave=False,               # Don't leave bar after completion
    bar_format='{desc}{desc_pad}{percentage:3.0f}%|{bar}|'
)

Notebook Environment

# In Jupyter notebook - NotebookManager automatically used
import enlighten

manager = enlighten.get_manager()  # Returns NotebookManager
pbar = manager.counter(total=100, desc='Notebook Progress')

for i in range(100):
    pbar.update()
    # Progress displays as HTML with live updates

Install with Tessl CLI