Configuration and Settings

class Configurator:
    """
    Main configuration class for managing matplotlib and proplot settings.
    
    Features:
    - Dictionary-like and attribute-style parameter access
    - Automatic synchronization of related parameters
    - Context management for temporary settings
    - File loading and saving capabilities
    - Intelligent parameter validation and conversion
    """
    
    def __init__(self, local=True, user=True, default=True, **kwargs):
        """
        Initialize configurator with settings from multiple sources.
        
        Parameters:
        - local (bool): Load settings from local .proplotrc files
        - user (bool): Load settings from user home directory config
        - default (bool): Load built-in default proplot settings
        - **kwargs: Initial parameter settings
        """
    
    def __getitem__(self, key):
        """Get configuration parameter value."""
    
    def __setitem__(self, key, value):
        """Set configuration parameter value with validation."""
    
    def context(self, *args, mode=0, file=None, **kwargs):
        """
        Create temporary configuration context for settings changes.
        
        Parameters:
        - *args: Parameter dictionaries to temporarily apply
        - mode (int): Context behavior (0=all, 1=proplot-only, 2=changed-only)
        - file (str): Configuration file to temporarily load
        - **kwargs: Parameter settings to temporarily apply
        
        Returns:
        Context manager for temporary configuration changes
        
        Usage:
        with rc.context(fontsize=14, style='seaborn'):
            # Plot with temporary settings
            fig, ax = pplt.subplots()
        """
    
    def load(self, path):
        """
        Load configuration settings from file.
        
        Parameters:
        - path (str): Path to configuration file (.proplotrc format)
        """
    
    def save(self, path=None, user=True, comment=None, backup=True, description=False):
        """
        Save current configuration settings to file.
        
        Parameters:
        - path (str): Output file path (default: user config file)
        - user (bool): Save to user configuration directory
        - comment (str): Header comment for file
        - backup (bool): Create backup of existing file
        - description (bool): Include parameter descriptions in file
        """
    
    def update(self, *args, **kwargs):
        """
        Update multiple configuration parameters.
        
        Parameters:
        - *args: Parameter dictionaries to update
        - **kwargs: Individual parameter updates
        """
    
    def reset(self, local=True, user=True, default=True):
        """
        Reset configuration to initial state.
        
        Parameters:
        - local (bool): Reload local configuration files
        - user (bool): Reload user configuration file
        - default (bool): Reload default proplot settings
        """
    
    def category(self, cat, trimcat=True, context=False):
        """
        Get all settings in a category.
        
        Parameters:
        - cat (str): Category name ('font', 'grid', 'axes', etc.)
        - trimcat (bool): Remove category prefix from keys
        - context (bool): Include context-specific parameters
        
        Returns:
        dict: Settings dictionary for the category
        """
    
    def find(self, key, context=False):
        """
        Find configuration parameter by partial key match.
        
        Parameters:
        - key (str): Partial parameter name to search for
        - context (bool): Include context-specific parameters
        
        Returns:
        dict: Matching parameters and their values
        """
    
    def fill(self, props, context=False):
        """
        Fill dictionary with configuration values.
        
        Parameters:
        - props (dict): Dictionary to fill with configuration values
        - context (bool): Include context-specific parameters
        
        Returns:
        dict: Input dictionary updated with configuration values
        """
    
    @property
    def changed(self):
        """dict: Settings that differ from defaults."""
    
    @staticmethod
    def local_files():
        """list: Local configuration file paths in priority order."""
    
    @staticmethod
    def user_file():
        """str: User configuration file path."""
    
    @staticmethod
    def user_folder(subfolder=None):
        """str: User configuration directory path."""

rc: Configurator
"""
Global configuration instance for all proplot and matplotlib settings.

Main interface for configuration management with support for:
- Dictionary access: rc['font.size'] = 12
- Attribute access: rc.fontsize = 12  
- Context management: with rc.context(fontsize=14): ...
- Category access: rc.category('font')
"""

rc_proplot: dict
"""
Dictionary-like container of proplot-specific settings.

Contains 183 proplot-specific parameters organized by category:
- Style and appearance settings
- Axes and layout configuration  
- Color and colormap defaults
- Geographic feature controls
- Grid and tick formatting
- Text and label styling
"""

rc_matplotlib: dict
"""
Dictionary-like container of matplotlib settings.

Direct reference to matplotlib.rcParams with proplot enhancements:
- All matplotlib parameters accessible
- Synchronized with proplot settings where applicable
- Enhanced with proplot-specific validators
"""

def register_cmaps(*args, user=None, default=False):
    """
    Register named colormaps from files or objects.
    
    Parameters:
    - *args: Colormap specifications (files, arrays, Colormap objects)
    - user (bool): Save to user directory vs. proplot installation
    - default (bool): Use when rebuilding proplot colormaps
    
    Supported Formats:
    - .json: JSON colormap definition files
    - .hex: Hex color lists (one per line)
    - .rgb: RGB color lists (comma or space separated)
    - .txt: Generic text color files
    - Arrays: Color data arrays
    - Colormap objects: Matplotlib/proplot colormap instances
    
    Usage:
    register_cmaps('my_colormap.json')
    register_cmaps(colormap_array, name='custom')
    """

def register_cycles(*args, user=None, default=False):
    """
    Register named color cycles from files or objects.
    
    Parameters:
    - *args: Color cycle specifications (files, lists, Cycle objects)
    - user (bool): Save to user directory vs. proplot installation
    - default (bool): Use when rebuilding proplot cycles
    
    Supported Formats:
    - .hex: Hex color lists
    - .rgb: RGB color lists  
    - .txt: Generic color text files
    - Lists: Color name/specification lists
    - Cycle objects: Proplot Cycle instances
    
    Usage:
    register_cycles('my_colors.hex')
    register_cycles(['red', 'blue', 'green'], name='rgb')
    """

def register_colors(*args, user=None, default=False, space=None, margin=None, **kwargs):
    """
    Register named colors from files or dictionaries.
    
    Parameters:
    - *args: Color specifications (files, dictionaries)
    - user (bool): Save to user directory vs. proplot installation  
    - default (bool): Use when rebuilding proplot colors
    - space (str): Colorspace for perceptual filtering ('hcl', 'hsl', etc.)
    - margin (float): Minimum perceptual distance for color filtering
    - **kwargs: Direct color name-value pairs
    
    Supported Formats:
    - Files: Text files with 'name : hex' pairs
    - Dictionaries: {name: color_spec} mappings
    - Built-in databases: XKCD colors with filtering
    
    Usage:
    register_colors('my_colors.txt')
    register_colors({'myred': '#FF0000', 'myblue': '#0000FF'})
    register_colors(mygreen='#00FF00')
    """

def register_fonts(*args, user=True, default=False):
    """
    Register font files for use in plotting.
    
    Parameters:
    - *args: Font file paths (.ttf, .otf formats)
    - user (bool): Install to user directory vs. system
    - default (bool): Use when rebuilding proplot fonts
    
    Supported Formats:
    - .ttf: TrueType font files
    - .otf: OpenType font files
    - Automatic font family detection and registration
    - Font cache rebuilding for immediate availability
    
    Usage:
    register_fonts('my_font.ttf')
    register_fonts('/path/to/font/directory/*.ttf')
    """

def use_style(style):
    """
    Apply matplotlib styles with proplot parameter inference.
    
    Parameters:
    - style (str/sequence): Style name(s) to apply
    
    Supported Styles:
    - Built-in matplotlib styles: 'seaborn', 'ggplot', 'classic', etc.
    - Special proplot styles: 'default' (proplot defaults), 'original' (matplotlib defaults)
    - Style composition: Multiple styles applied in sequence
    - Automatic proplot parameter inference from matplotlib settings
    
    Usage:
    use_style('seaborn')
    use_style(['seaborn', 'whitegrid'])
    use_style('default')  # Reset to proplot defaults
    """

def config_inline_backend(fmt=None):
    """
    Configure IPython/Jupyter inline display backend.
    
    Parameters:
    - fmt (str): Output format for inline figures
    
    Supported Formats:
    - 'svg': Scalable vector graphics (default for high DPI)
    - 'pdf': Portable document format
    - 'png': Portable network graphics  
    - 'jpg'/'jpeg': JPEG compressed format
    - 'retina': High-resolution PNG for retina displays
    
    Features:
    - Automatic format detection from rc['inlinefmt']
    - Ensures consistency between inline and saved figures
    - Optimizes display quality for different environments
    
    Usage:
    config_inline_backend('svg')  # High quality vector output
    config_inline_backend('retina')  # High DPI displays
    """

FONT_SETTINGS = {
    'font.size': "Base font size for all text elements",
    'font.smallsize': "Small text (ticks, legends, etc.)",
    'font.largesize': "Large text (titles, abc labels, etc.)",
    'font.family': "Font family name or generic family",
    'font.name': "Specific font name (alias for font.family)",
    
    # Automatic size relationships
    'tick.labelsize': "Inherits from font.smallsize",
    'axes.labelsize': "Inherits from font.smallsize", 
    'legend.fontsize': "Inherits from font.smallsize",
    'title.size': "Inherits from font.largesize",
    'suptitle.size': "Inherits from font.largesize"
}

COLOR_SETTINGS = {
    'meta.color': "Universal color affecting axes, ticks, labels",
    'cmap.sequential': "Default sequential colormap",
    'cmap.diverging': "Default diverging colormap", 
    'cmap.cyclic': "Default cyclic colormap",
    'cmap.qualitative': "Default qualitative colormap",
    'cycle': "Default color cycle for line plots",
    'negcolor': "Color for negative values",
    'poscolor': "Color for positive values"
}

LAYOUT_SETTINGS = {
    'subplots.tight': "Enable tight layout by default",
    'subplots.pad': "Padding around subplot grid",
    'subplots.axpad': "Padding between individual subplots",
    'subplots.panelpad': "Padding around panels (colorbars, legends)",
    'axes.margin': "Default axes margin",
    'title.pad': "Title padding from axes",
    'title.above': "Place titles above rather than inside axes"
}

GRID_SETTINGS = {
    'grid': "Default grid visibility",
    'grid.alpha': "Grid line transparency",
    'grid.color': "Grid line color",
    'grid.linewidth': "Grid line width",
    'grid.linestyle': "Grid line style",
    'gridminor': "Minor grid visibility",
    'gridminor.alpha': "Minor grid transparency",
    'gridminor.color': "Minor grid color",
    'gridminor.linewidth': "Minor grid line width"
}

GEOGRAPHIC_SETTINGS = {
    'land': "Land feature visibility and styling",
    'ocean': "Ocean feature visibility and styling", 
    'coast': "Coastline feature visibility and styling",
    'rivers': "River feature visibility and styling",
    'lakes': "Lake feature visibility and styling",
    'borders': "Border feature visibility and styling",
    'reso': "Geographic feature resolution ('110m', '50m', '10m')"
}

# Configuration file format (YAML-style)
CONFIG_FORMAT = """
# Proplot configuration file
# Comments are supported with #

# Font settings
font.size: 12
font.family: sans-serif

# Color settings  
cmap.sequential: viridis
cycle: colorblind

# Layout settings
subplots.tight: True
grid: True

# Style application
style: seaborn
"""

# File locations (in priority order)
CONFIG_LOCATIONS = [
    "./proplotrc",           # Current directory
    "./.proplotrc",          # Hidden file in current directory
    "../proplotrc",          # Parent directory
    "~/.proplotrc",          # User home directory
    "~/.proplot/proplotrc",  # User config directory
    # XDG config directory on Linux
]

# Save current configuration
rc.save('my_style.proplotrc', 
        comment='Custom plotting style',
        description=True)  # Include parameter descriptions

# Load configuration from file
rc.load('my_style.proplotrc')

# Reset to various states
rc.reset()                    # Reset to all defaults
rc.reset(user=False)         # Skip user config file
rc.reset(local=False)        # Skip local config files

import proplot as pplt

# View current settings
print(pplt.rc['font.size'])
print(pplt.rc.fontsize)  # Equivalent attribute access

# Modify settings
pplt.rc['font.size'] = 14
pplt.rc.update(fontsize=14, grid=True, style='seaborn')

# Category-based updates  
pplt.rc.update('font', size=12, family='serif')

# Temporary configuration changes
with pplt.rc.context(fontsize=16, style='ggplot'):
    fig, ax = pplt.subplots()
    ax.plot([1, 2, 3], [1, 4, 9])
# Settings automatically restored after context

# Multiple parameter contexts
with pplt.rc.context({'font.size': 14, 'grid': True}, 
                     cmap='plasma'):
    # Create plots with temporary settings
    pass

# Apply built-in styles
pplt.use_style('seaborn')
pplt.use_style(['seaborn', 'whitegrid'])

# Reset to defaults
pplt.use_style('default')      # Proplot defaults
pplt.use_style('original')     # Matplotlib defaults

# Custom style from file
pplt.rc.load('journal_style.proplotrc')

# Register custom colormap
pplt.register_cmaps('scientific_colormap.json')
pplt.register_cmaps(custom_array, name='mymap')

# Register color cycle
pplt.register_cycles(['#FF0000', '#00FF00', '#0000FF'], 
                     name='rgb')

# Register named colors
pplt.register_colors({'corporate_blue': '#1f77b4',
                      'brand_red': '#d62728'})

# Register fonts
pplt.register_fonts('custom_font.ttf')

# Comprehensive style setup
pplt.rc.update({
    # Font configuration
    'font.size': 11,
    'font.family': 'serif',
    
    # Color scheme
    'meta.color': 'black',
    'cmap.sequential': 'plasma',
    'cycle': 'colorblind',
    
    # Layout  
    'subplots.tight': True,
    'axes.margin': 0.05,
    'grid': True,
    'grid.alpha': 0.3,
    
    # Geographic features
    'land': True,
    'ocean': True,
    'coast': {'linewidth': 0.5, 'color': 'gray'},
    
    # Inline backend
    'inlinefmt': 'svg'
})

# Save custom configuration
pplt.rc.save('publication_style.proplotrc',
             comment='Settings for publication figures')

# Find font-related settings
font_settings = pplt.rc.category('font')
print(font_settings)

# Search for grid parameters
grid_params = pplt.rc.find('grid')
print(grid_params)

# View changed settings
print(pplt.rc.changed)  # Only non-default values

# Get all colormap settings
cmap_settings = pplt.rc.category('cmap', trimcat=False)