Configuration

config_handler.set_global(**options):
    """
    Update global configuration for all subsequent alive bars.
    
    Parameters:
    - **options: Configuration options (see Configuration Options below)
    
    Raises:
    - ValueError: If invalid configuration keys or values are provided
    """

config_handler.reset():
    """Reset global configuration to factory defaults."""

config_handler.create_context(**options):
    """
    Create immutable configuration context with optional customization.
    
    Parameters:  
    - **options: Configuration options to override
    
    Returns:
    Config object with current global settings plus overrides
    """

from alive_progress import config_handler

# Set global defaults
config_handler.set_global(
    length=50,
    theme='smooth',
    dual_line=True,
    receipt_text=True
)

# All subsequent bars use these defaults
with alive_bar(1000) as bar:
    # Uses global configuration
    pass

# Reset to factory defaults
config_handler.reset()

# Display configuration options
title: Optional[str] = None  # Bar title
length: int = 40  # Bar length in characters  
max_cols: int = 80  # Maximum columns if terminal size unavailable
dual_line: bool = False  # Place text below bar instead of inline

# Custom bar appearance
with alive_bar(1000, 
               title='Processing Data',
               length=60, 
               dual_line=True) as bar:
    for i in range(1000):
        bar.text = f'Processing record {i+1}'
        process_record(i)
        bar()

# Style configuration options  
spinner: Union[str, object, None] = None  # Spinner style or factory
bar: Union[str, object, None] = None  # Bar style or factory
unknown: Union[str, object] = None  # Unknown mode spinner style
theme: str = 'smooth'  # Predefined theme name

# Using predefined theme
with alive_bar(1000, theme='classic') as bar:
    pass

# Custom spinner and bar
with alive_bar(1000, 
               spinner='dots',
               bar='filling') as bar:
    pass

# Custom factories
from alive_progress.animations import scrolling_spinner_factory

custom_spinner = scrolling_spinner_factory(['◐', '◓', '◑', '◒'])
with alive_bar(1000, spinner=custom_spinner) as bar:
    pass

# Behavior configuration options
manual: bool = False  # Enable manual percentage mode
force_tty: Optional[bool] = None  # Force terminal mode (None=auto, True=force, False=disable)
disable: bool = False  # Disable all output completely
calibrate: Optional[int] = None  # Calibration value for animation speed

# Manual percentage mode
with alive_bar(manual=True, title='Training Model') as bar:
    for epoch in range(100):
        loss = train_epoch()
        bar(epoch / 100)  # Set percentage directly

# Force animations in Jupyter
with alive_bar(1000, force_tty=True) as bar:
    pass

# Disable in production
with alive_bar(1000, disable=PRODUCTION_MODE) as bar:
    pass

# Widget configuration options
monitor: Union[bool, str] = True  # Progress monitor widget
elapsed: Union[bool, str] = True  # Elapsed time widget
stats: Union[bool, str] = True  # Statistics widget (rate/ETA)
receipt: bool = True  # Show final receipt
receipt_text: bool = False  # Include text in receipt

# Widget format strings
monitor_end: Union[bool, str] = True  # Monitor widget in receipt
elapsed_end: Union[bool, str] = True  # Elapsed widget in receipt  
stats_end: Union[bool, str] = True  # Stats widget in receipt

# Custom widget formats
with alive_bar(1000,
               monitor='{count} of {total} [{percent:.1%}]',
               stats='Rate: {rate} | ETA: {eta}') as bar:
    pass

# Disable specific widgets
with alive_bar(1000, 
               elapsed=False,
               stats=False) as bar:
    pass

# Output configuration options
file: TextIOWrapper = sys.stdout  # Output file object
enrich_print: bool = True  # Enrich print/logging output with bar position
enrich_offset: int = 0  # Offset for enriched messages

import sys

# Output to stderr
with alive_bar(1000, file=sys.stderr) as bar:
    pass

# Disable print enrichment
with alive_bar(1000, enrich_print=False) as bar:
    print("This won't show bar position")
    bar()

# Custom enrichment offset
with alive_bar(1000, enrich_offset=500) as bar:
    bar(400)
    print("This shows 'on 901:' instead of 'on 401:'")

# Formatting configuration options
unit: str = ''  # Unit label for values
scale: Optional[str] = None  # Scaling mode: 'SI', 'IEC', 'SI2', or None
precision: int = 1  # Decimal precision for scaled values
title_length: int = 0  # Fixed title length (0 for unlimited)
spinner_length: int = 0  # Fixed spinner length (0 for natural)

# File processing with byte units
with alive_bar(total_bytes, 
               unit='B',
               scale='IEC',
               precision=2) as bar:
    for chunk in file_chunks:
        process_chunk(chunk)
        bar(len(chunk))

# Fixed title length
with alive_bar(1000,
               title='Very Long Processing Title',
               title_length=20) as bar:
    pass  # Title truncated to 20 chars with ellipsis

# Advanced configuration options  
refresh_secs: float = 0  # Refresh period in seconds (0 for reactive)
ctrl_c: bool = True  # Allow CTRL+C interruption

# Slower refresh rate for very fast processing
with alive_bar(1000000, refresh_secs=0.1) as bar:
    for i in range(1000000):
        fast_operation(i)
        bar()

# Disable keyboard interruption
with alive_bar(1000, ctrl_c=False) as bar:
    try:
        for i in range(1000):
            critical_operation(i)
            bar()
    except KeyboardInterrupt:
        pass  # CTRL+C captured but ignored

# Invalid configuration examples
try:
    config_handler.set_global(length='invalid')
except ValueError as e:
    print(e)  # Expected an int between 3 and 1000

try:
    with alive_bar(1000, theme='nonexistent') as bar:
        pass
except ValueError as e:
    print(e)  # invalid theme name=nonexistent

try:
    with alive_bar(1000, monitor='{invalid_field}') as bar:
        pass
except ValueError as e:
    print(e)  # Expected only the fields: ('count', 'total', 'percent')

# Save current configuration
original_config = config_handler.create_context()

# Modify global settings
config_handler.set_global(theme='ascii', length=60)

# Use bars with modified settings
with alive_bar(1000) as bar:
    pass

# Restore original settings  
config_handler.set_global(**original_config._asdict())

# Or reset to factory defaults
config_handler.reset()

# Set global defaults
config_handler.set_global(theme='smooth', length=40)

# This bar uses global settings
with alive_bar(1000) as bar:
    pass

# This bar overrides specific options
with alive_bar(1000, theme='classic', length=60) as bar:
    pass

# Next bar uses global settings again
with alive_bar(1000) as bar:
    pass