tessl/pypi-halo

Beautiful terminal spinners in Python

—

Pending

Overview

Eval results

Files

Status and Result Handling

Name: tessl/pypi-halo
Author: tessl

Methods for completing spinners with status indicators and custom symbols. These methods stop the spinner and display a final status message that persists in the terminal.

Capabilities

Success Completion

Complete the spinner with a success indicator, typically used when operations complete successfully.

def succeed(self, text=None):
    """
    Stop spinner and show success symbol with text.
    
    Parameters:
    - text (str, optional): Text to display with success symbol.
                           If None, uses current spinner text.
    
    Returns:
    - Halo: Self for method chaining
    """

Usage Example:

from halo import Halo
import time

spinner = Halo(text='Downloading file', spinner='dots')
spinner.start()
time.sleep(2)

# Complete with success
spinner.succeed('✓ File downloaded successfully')
# Output: ✓ File downloaded successfully

Failure Completion

Complete the spinner with an error indicator for failed operations.

def fail(self, text=None):
    """
    Stop spinner and show error symbol with text.
    
    Parameters:
    - text (str, optional): Text to display with error symbol.
                           If None, uses current spinner text.
    
    Returns:
    - Halo: Self for method chaining
    """

Usage Example:

from halo import Halo
import time

spinner = Halo(text='Connecting to server', spinner='dots')
spinner.start()
time.sleep(2)

try:
    # Simulate operation that might fail
    raise ConnectionError("Unable to connect")
except ConnectionError as e:
    spinner.fail(f'✗ Connection failed: {e}')
    # Output: ✗ Connection failed: Unable to connect

Warning Completion

Complete the spinner with a warning indicator for operations that completed with issues.

def warn(self, text=None):
    """
    Stop spinner and show warning symbol with text.
    
    Parameters:
    - text (str, optional): Text to display with warning symbol.
                           If None, uses current spinner text.
    
    Returns:
    - Halo: Self for method chaining
    """

Usage Example:

from halo import Halo
import time

spinner = Halo(text='Processing data', spinner='dots')
spinner.start()
time.sleep(2)

# Complete with warning
spinner.warn('⚠ Data processed with 3 warnings')
# Output: ⚠ Data processed with 3 warnings

Info Completion

Complete the spinner with an info indicator for informational messages.

def info(self, text=None):
    """
    Stop spinner and show info symbol with text.
    
    Parameters:
    - text (str, optional): Text to display with info symbol.
                           If None, uses current spinner text.
    
    Returns:
    - Halo: Self for method chaining
    """

Usage Example:

from halo import Halo
import time

spinner = Halo(text='Scanning files', spinner='dots')
spinner.start()  
time.sleep(2)

# Complete with info
spinner.info('ℹ Scan completed - 42 files found')
# Output: ℹ Scan completed - 42 files found

Custom Symbol Completion

Complete the spinner with a custom symbol and text for specialized status indicators.

def stop_and_persist(self, symbol=" ", text=None):
    """
    Stop spinner and display custom symbol with text.
    
    Parameters:
    - symbol (str): Symbol to display (default: " ")
    - text (str, optional): Text to display with symbol.
                           If None, uses current spinner text.
    
    Returns:
    - Halo: Self for method chaining
    """

Usage Example:

from halo import Halo
import time

spinner = Halo(text='Deploying application', spinner='dots')
spinner.start()
time.sleep(3)

# Custom completion symbols
spinner.stop_and_persist('🚀', 'Application deployed to production')
# Output: 🚀 Application deployed to production

# Another example
spinner2 = Halo(text='Running tests', spinner='star')  
spinner2.start()
time.sleep(2)
spinner2.stop_and_persist('📊', 'Tests completed: 45 passed, 0 failed')
# Output: 📊 Tests completed: 45 passed, 0 failed

Status Symbols

The standard status symbols used by Halo (from the log_symbols package):

Success: ✓ (green checkmark)
Error: ✗ (red X)
Warning: ⚠ (yellow warning triangle)
Info: ℹ (blue info symbol)

These symbols automatically adapt to the terminal's capabilities and may display as ASCII alternatives on unsupported terminals.

Advanced Status Handling

Conditional Status

from halo import Halo
import time
import random

def process_data():
    spinner = Halo(text='Processing data', spinner='dots')
    spinner.start()
    
    # Simulate processing
    time.sleep(2)
    success_rate = random.random()
    
    if success_rate > 0.8:
        spinner.succeed('✓ Processing completed successfully')
    elif success_rate > 0.5:
        spinner.warn('⚠ Processing completed with warnings')
    else:
        spinner.fail('✗ Processing failed')

process_data()

Status with Details

from halo import Halo
import time

def backup_files():
    files = ['config.json', 'data.db', 'logs.txt']
    
    spinner = Halo(text='Starting backup', spinner='dots')
    spinner.start()
    
    backed_up = []
    failed = []
    
    for file in files:
        spinner.text = f'Backing up {file}'
        time.sleep(1)
        
        # Simulate success/failure
        if file != 'logs.txt':  # Simulate logs.txt failing
            backed_up.append(file)
        else:
            failed.append(file)
    
    if not failed:
        spinner.succeed(f'✓ Backup completed - {len(backed_up)} files backed up')
    elif backed_up:
        spinner.warn(f'⚠ Partial backup - {len(backed_up)} succeeded, {len(failed)} failed')
    else:
        spinner.fail('✗ Backup failed - no files backed up')

backup_files()

Status with Timing

from halo import Halo
import time

def timed_operation():
    start_time = time.time()
    
    spinner = Halo(text='Running operation', spinner='dots')
    spinner.start()
    
    # Simulate work
    time.sleep(3)
    
    end_time = time.time()
    duration = round(end_time - start_time, 2)
    
    spinner.succeed(f'✓ Operation completed in {duration}s')

timed_operation()

Chained Operations

from halo import Halo
import time

def multi_step_process():
    # Step 1
    spinner = Halo(text='Initializing', spinner='dots')
    spinner.start()
    time.sleep(1)
    spinner.succeed('✓ Initialization complete')
    
    # Step 2  
    spinner = Halo(text='Processing data', spinner='star')
    spinner.start()
    time.sleep(2)
    spinner.succeed('✓ Data processing complete')
    
    # Step 3
    spinner = Halo(text='Finalizing', spinner='dots')
    spinner.start() 
    time.sleep(1)
    spinner.succeed('✓ All operations completed successfully')

multi_step_process()

Install with Tessl CLI