Configuration Management

# Import options module
import itables.options as opts

# Layout configuration
opts.layout: dict  # Table layout specification (topStart, topEnd, bottomStart, bottomEnd)

# Display options
opts.showIndex: str | bool  # Index display control ("auto", True, False)
opts.classes: str | list  # CSS classes for table styling
opts.style: str | dict  # CSS styles for table appearance

# Data limits and downsampling
opts.maxBytes: str | int  # Maximum data size before downsampling ("64KB")
opts.maxRows: int  # Maximum rows before downsampling (0 = unlimited)
opts.maxColumns: int  # Maximum columns before downsampling (200)

# Table features
opts.column_filters: str | bool  # Column filtering location (False, "header", "footer")
opts.footer: bool  # Show table footer
opts.allow_html: bool  # Allow HTML content in cells

# Behavior options
opts.warn_on_unexpected_types: bool  # Warning for unexpected data types
opts.warn_on_selected_rows_not_rendered: bool  # Warning for selection issues
opts.display_logo_when_loading: bool  # Show ITables logo during loading
opts.text_in_header_can_be_selected: bool  # Make header text selectable

# DataTables library configuration
opts.dt_url: str  # DataTables JavaScript bundle URL for connected mode
opts.dt_bundle: str | Path  # Local DataTables bundle path for offline mode

def get_config_file(path=None):
    """
    Find ITables configuration file.

    Parameters:
    - path (Path, optional): Starting directory for search (default: current directory)

    Returns:
    Path | None: Path to config file if found, None otherwise

    Search order:
    1. ITABLES_CONFIG environment variable path
    2. itables.toml in current/parent directories  
    3. tool.itables section in pyproject.toml
    4. itables.toml in user config directory
    """

def load_config_file(config_file):
    """
    Load and validate configuration from TOML file.

    Parameters:
    - config_file (Path): Path to configuration file

    Returns:
    dict: Validated configuration options

    Raises:
    ImportError: If tomllib/tomli not available
    ValueError: If file contains invalid configuration
    """

def set_options_from_config_file(options):
    """
    Apply configuration file settings to options dictionary.

    Parameters:
    - options (dict): Options dictionary to update

    Returns:
    None (modifies options in-place)
    """

def show_config(path):
    """
    Display ITables configuration file location and content.

    Parameters:
    - path (Path): Directory to search for config file

    Returns:
    None (prints configuration information)
    """

# Table layout (DataTables layout option)
opts.layout = {
    "topStart": "pageLength",    # Page length selector position
    "topEnd": "search",          # Search box position  
    "bottomStart": "info",       # Info text position
    "bottomEnd": "paging"        # Pagination controls position
}

# CSS styling
opts.classes = "display nowrap"  # Space-separated CSS classes
opts.style = "table-layout:auto;width:auto;margin:auto;caption-side:bottom"

# Index display control
opts.showIndex = "auto"  # "auto": hide if unnamed RangeIndex, True/False: force show/hide

# Size limits for automatic downsampling
opts.maxBytes = "64KB"      # String format: "64KB", "1MB" or integer bytes
opts.maxRows = 0            # 0 = unlimited, positive integer = row limit
opts.maxColumns = 200       # Column limit before downsampling

# Default sorting (empty = no sorting)
opts.order = []             # List of [column_index, "asc"/"desc"] pairs

# Interactive features
opts.column_filters = False         # False, "header", or "footer"
opts.footer = False                 # Show table footer
opts.allow_html = False             # Allow HTML in table cells (security risk)

# Behavioral options  
opts.warn_on_unexpected_types = True              # Warn about unexpected data types
opts.warn_on_selected_rows_not_rendered = True    # Warn about selection issues
opts.display_logo_when_loading = True             # Show ITables logo while loading
opts.text_in_header_can_be_selected = True        # Allow header text selection

# Library loading configuration
opts.dt_url = "https://www.unpkg.com/dt_for_itables@2.4.0/dt_bundle.js"
opts.dt_bundle = Path("html/dt_bundle.js")  # Local bundle for offline mode

import itables.options as opts

# Modify global options
opts.classes = "display compact stripe"
opts.pageLength = 25
opts.column_filters = "header"
opts.maxRows = 1000

# These settings affect all subsequent show() calls
from itables import show
show(df)  # Uses updated options

# Override options for specific display
show(df, 
     pageLength=50,           # Override global pageLength
     scrollX=True,            # Enable horizontal scrolling
     classes="display hover") # Override global classes

classes = "display compact"
pageLength = 20
column_filters = "header"
maxRows = 2000
showIndex = false
display_logo_when_loading = false

[tool.itables]
classes = "display compact"
pageLength = 20
column_filters = "header"

# Use specific config file
export ITABLES_CONFIG="/path/to/custom/itables.toml"

# Disable config file loading
export ITABLES_CONFIG=""

from itables.show_config import show_config
from pathlib import Path

# Display current configuration
show_config(Path.cwd())

# Custom DataTables layout
opts.layout = {
    "topStart": "buttons",      # Export buttons
    "topEnd": "search", 
    "bottomStart": None,        # Remove info display
    "bottomEnd": "paging"
}

# DataTables native options can be passed through
show(df,
     buttons=['copy', 'csv', 'excel'],  # Export buttons
     fixedColumns={'left': 1},          # Fix first column
     searchPanes={'cascadePanes': True}, # Search panes
     select={'style': 'multi'})          # Multi-row selection

# Enable strict validation (requires typeguard package)
opts.warn_on_undocumented_option = True
opts.warn_on_unexpected_option_type = True

# This will warn about unknown or incorrectly typed options
show(df, unknown_option=True)  # Triggers warning