lightfall-utils 0.1.0__py3-none-any.whl

lightfall_utils/config/layers.py

@@ -0,0 +1,317 @@
+"""Priority-layered configuration system.
+
+Implements a priority-based configuration system where settings from
+different sources are merged, with higher-priority layers overriding
+lower-priority ones.
+
+Priority order (lowest to highest):
+    Defaults -> Global -> Beamline -> User -> Session
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from copy import deepcopy
+from dataclasses import dataclass, field
+from enum import IntEnum
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from lightfall_utils.logging import logger
+
+
+class ConfigPriority(IntEnum):
+    """Configuration layer priorities."""
+
+    DEFAULTS = 0
+    GLOBAL = 10
+    BEAMLINE = 20
+    USER = 30
+    SESSION = 40
+
+
+@dataclass
+class ConfigLayer:
+    """
+    A single configuration layer.
+
+    Attributes:
+        name: Human-readable layer name.
+        priority: Layer priority (higher overrides lower).
+        data: Configuration data dictionary.
+        source: Optional path or identifier for the data source.
+        mutable: Whether this layer can be modified at runtime.
+    """
+
+    name: str
+    priority: ConfigPriority | int
+    data: dict[str, Any] = field(default_factory=dict)
+    source: Path | str | None = None
+    mutable: bool = False
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Get a value from this layer using dot notation.
+
+        Args:
+            key: Dot-separated key path (e.g., "ui.theme").
+            default: Default value if key not found.
+
+        Returns:
+            The value or default.
+        """
+        parts = key.split(".")
+        value = self.data
+        for part in parts:
+            if isinstance(value, dict) and part in value:
+                value = value[part]
+            else:
+                return default
+        return value
+
+    def set(self, key: str, value: Any) -> None:
+        """Set a value in this layer using dot notation.
+
+        Args:
+            key: Dot-separated key path.
+            value: Value to set.
+
+        Raises:
+            RuntimeError: If layer is not mutable.
+        """
+        if not self.mutable:
+            raise RuntimeError(f"Cannot modify immutable layer '{self.name}'")
+
+        parts = key.split(".")
+        data = self.data
+        for part in parts[:-1]:
+            if part not in data:
+                data[part] = {}
+            data = data[part]
+        data[parts[-1]] = value
+
+    @classmethod
+    def from_file(
+        cls,
+        path: Path | str,
+        name: str | None = None,
+        priority: ConfigPriority | int = ConfigPriority.USER,
+        mutable: bool = False,
+    ) -> ConfigLayer:
+        """
+        Create a config layer from a YAML file.
+
+        Args:
+            path: Path to YAML configuration file.
+            name: Layer name (defaults to filename).
+            priority: Layer priority.
+            mutable: Whether layer is mutable.
+
+        Returns:
+            A new ConfigLayer instance.
+        """
+        path = Path(path)
+        layer_name = name or path.stem
+
+        if not path.exists():
+            logger.debug("Config file not found: {}", path)
+            return cls(name=layer_name, priority=priority, source=path, mutable=mutable)
+
+        try:
+            with path.open() as f:
+                data = yaml.safe_load(f) or {}
+            logger.debug("Loaded config layer '{}' from {}", layer_name, path)
+            return cls(
+                name=layer_name,
+                priority=priority,
+                data=data,
+                source=path,
+                mutable=mutable,
+            )
+        except Exception as e:
+            logger.warning("Failed to load config from {}: {}", path, e)
+            return cls(name=layer_name, priority=priority, source=path, mutable=mutable)
+
+    def save(self) -> None:
+        """Save this layer to its source file.
+
+        Raises:
+            RuntimeError: If no file source is set.
+        """
+        if not isinstance(self.source, Path):
+            raise RuntimeError(f"Cannot save layer '{self.name}': no file source")
+
+        self.source.parent.mkdir(parents=True, exist_ok=True)
+        with self.source.open("w") as f:
+            yaml.safe_dump(self.data, f, default_flow_style=False, sort_keys=False)
+        logger.debug("Saved config layer '{}' to {}", self.name, self.source)
+
+
+class LayeredConfig:
+    """
+    Manages multiple configuration layers with priority-based merging.
+
+    Configuration values from higher-priority layers override those from
+    lower-priority layers. Deep merging is performed for nested dictionaries.
+
+    Example:
+        >>> config = LayeredConfig()
+        >>> config.add_layer(ConfigLayer("defaults", ConfigPriority.DEFAULTS, {"ui": {"theme": "light"}}))
+        >>> config.add_layer(ConfigLayer("user", ConfigPriority.USER, {"ui": {"theme": "dark"}}))
+        >>> config.get("ui.theme")  # Returns "dark"
+    """
+
+    def __init__(self) -> None:
+        self._layers: list[ConfigLayer] = []
+        self._merged: dict[str, Any] = {}
+        self._dirty = True
+
+    def add_layer(self, layer: ConfigLayer) -> None:
+        """
+        Add a configuration layer.
+
+        Args:
+            layer: The layer to add.
+        """
+        # Remove existing layer with same name
+        self._layers = [lyr for lyr in self._layers if lyr.name != layer.name]
+        self._layers.append(layer)
+        self._layers.sort(key=lambda lyr: lyr.priority)
+        self._dirty = True
+        logger.debug(
+            "Added config layer '{}' at priority {}",
+            layer.name,
+            layer.priority,
+        )
+
+    def remove_layer(self, name: str) -> bool:
+        """
+        Remove a layer by name.
+
+        Args:
+            name: Name of the layer to remove.
+
+        Returns:
+            True if layer was found and removed.
+        """
+        original_count = len(self._layers)
+        self._layers = [lyr for lyr in self._layers if lyr.name != name]
+        if len(self._layers) < original_count:
+            self._dirty = True
+            logger.debug("Removed config layer '{}'", name)
+            return True
+        return False
+
+    def get_layer(self, name: str) -> ConfigLayer | None:
+        """
+        Get a layer by name.
+
+        Args:
+            name: Layer name.
+
+        Returns:
+            The layer or None if not found.
+        """
+        for layer in self._layers:
+            if layer.name == name:
+                return layer
+        return None
+
+    def layers(self) -> Iterator[ConfigLayer]:
+        """Iterate over layers in priority order (lowest first)."""
+        yield from self._layers
+
+    def _merge(self) -> dict[str, Any]:
+        """Merge all layers into a single configuration dict."""
+        if not self._dirty:
+            return self._merged
+
+        result: dict[str, Any] = {}
+        for layer in self._layers:
+            result = self._deep_merge(result, layer.data)
+
+        self._merged = result
+        self._dirty = False
+        return result
+
+    @staticmethod
+    def _deep_merge(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+        """Deep merge two dictionaries.
+
+        Args:
+            base: Base dictionary.
+            override: Override dictionary (takes precedence).
+
+        Returns:
+            Merged dictionary.
+        """
+        result = deepcopy(base)
+        for key, value in override.items():
+            if key in result and isinstance(result[key], dict) and isinstance(value, dict):
+                result[key] = LayeredConfig._deep_merge(result[key], value)
+            else:
+                result[key] = deepcopy(value)
+        return result
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """
+        Get a configuration value using dot notation.
+
+        Args:
+            key: Dot-separated key path (e.g., "ui.theme").
+            default: Default value if key not found.
+
+        Returns:
+            The configuration value or default.
+        """
+        merged = self._merge()
+        parts = key.split(".")
+        value = merged
+        for part in parts:
+            if isinstance(value, dict) and part in value:
+                value = value[part]
+            else:
+                return default
+        return value
+
+    def set(self, key: str, value: Any, *, layer_name: str | None = None) -> None:
+        """
+        Set a configuration value.
+
+        If no layer is specified, uses the highest-priority mutable layer.
+
+        Args:
+            key: Dot-separated key path.
+            value: Value to set.
+            layer_name: Target layer name (optional).
+
+        Raises:
+            RuntimeError: If no mutable layer is available.
+        """
+        target_layer: ConfigLayer | None = None
+
+        if layer_name:
+            target_layer = self.get_layer(layer_name)
+            if target_layer is None:
+                raise RuntimeError(f"Layer '{layer_name}' not found")
+        else:
+            # Find highest-priority mutable layer
+            for layer in reversed(self._layers):
+                if layer.mutable:
+                    target_layer = layer
+                    break
+
+        if target_layer is None:
+            raise RuntimeError("No mutable configuration layer available")
+
+        target_layer.set(key, value)
+        self._dirty = True
+
+    def as_dict(self) -> dict[str, Any]:
+        """Return the merged configuration as a dictionary."""
+        return deepcopy(self._merge())
+
+    def mark_dirty(self) -> None:
+        """Mark the configuration as needing re-merge."""
+        self._dirty = True

lightfall_utils/config/manager.py

@@ -0,0 +1,246 @@
+"""High-level configuration manager.
+
+Wraps LayeredConfig with pydantic validation and automatic loading from
+platform-standard locations. The validating model class, application
+directory name, and bundled-defaults location are supplied by the host
+application.
+
+Standard configuration locations (in priority order):
+    1. Bundled defaults (``defaults_path``, if given)
+    2. Global config (``/etc/<app_name>/`` or ``%PROGRAMDATA%/<app_name>/``)
+    3. User config (``~/.config/<app_name>/`` or ``%APPDATA%/<app_name>/``)
+    4. Session overrides (runtime-only)
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from pydantic import BaseModel, ValidationError
+
+from lightfall_utils.config.layers import ConfigLayer, ConfigPriority, LayeredConfig
+from lightfall_utils.logging import logger
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+
+class PermissiveModel(BaseModel):
+    """Default schema: accepts any keys, validates nothing."""
+
+    model_config = {"extra": "allow"}
+
+
+def _user_config_dir(app_name: str) -> Path:
+    """Per-user configuration directory for *app_name*."""
+    if os.name == "nt":
+        base = Path(os.environ.get("APPDATA", Path.home() / "AppData" / "Roaming"))
+    else:
+        base = Path(os.environ.get("XDG_CONFIG_HOME", Path.home() / ".config"))
+    return base / app_name
+
+
+def _global_config_dir(app_name: str) -> Path:
+    """System-wide configuration directory for *app_name*."""
+    if os.name == "nt":
+        return Path(os.environ.get("PROGRAMDATA", "C:/ProgramData")) / app_name
+    return Path("/etc") / app_name
+
+
+class ConfigManager:
+    """Layered configuration with pydantic validation.
+
+    Example:
+        >>> config = ConfigManager(model_class=MyConfig, app_name="myapp")
+        >>> config.get("ui.theme")
+        "dark"
+        >>> config.model.ui.theme
+        "dark"
+        >>> config.set("ui.theme", "light", persist=True)
+    """
+
+    DEFAULT_CONFIG_FILENAME = "application.yaml"
+
+    def __init__(
+        self,
+        *,
+        model_class: type[BaseModel] = PermissiveModel,
+        app_name: str = "lightfall-utils",
+        defaults_path: Path | str | None = None,
+        default_filename: str | None = None,
+        extra_paths: Sequence[Path | str] | None = None,
+        skip_standard_paths: bool = False,
+    ) -> None:
+        """Initialize the ConfigManager.
+
+        Args:
+            model_class: Pydantic model the merged config validates against.
+            app_name: Directory name under the platform config locations.
+            defaults_path: Directory holding the bundled defaults file
+                (loaded as the lowest-priority layer when given).
+            default_filename: Config filename (default "application.yaml").
+            extra_paths: Additional configuration files to load.
+            skip_standard_paths: Skip standard locations (useful for testing).
+        """
+        self._model_class = model_class
+        self._app_name = app_name
+        self._defaults_path = Path(defaults_path) if defaults_path is not None else None
+        self._filename = default_filename or self.DEFAULT_CONFIG_FILENAME
+        self._layered = LayeredConfig()
+        self._model: BaseModel | None = None
+        self._validation_errors: list[str] = []
+
+        if not skip_standard_paths:
+            self._load_standard_layers()
+
+        if extra_paths:
+            for i, path in enumerate(extra_paths):
+                self._layered.add_layer(
+                    ConfigLayer.from_file(
+                        Path(path),
+                        name=f"extra_{i}",
+                        priority=ConfigPriority.USER + 1 + i,
+                    )
+                )
+
+        # Add session layer (mutable, runtime-only)
+        self._layered.add_layer(
+            ConfigLayer(
+                name="session",
+                priority=ConfigPriority.SESSION,
+                mutable=True,
+            )
+        )
+
+        # Initialize model
+        self._rebuild_model()
+
+    def _load_standard_layers(self) -> None:
+        """Load configuration from standard locations."""
+        # 1. Bundled defaults
+        if self._defaults_path is not None:
+            self._layered.add_layer(
+                ConfigLayer.from_file(
+                    self._defaults_path / self._filename,
+                    name="defaults",
+                    priority=ConfigPriority.DEFAULTS,
+                )
+            )
+
+        # 2. Global config
+        global_path = _global_config_dir(self._app_name) / self._filename
+        self._layered.add_layer(
+            ConfigLayer.from_file(global_path, name="global", priority=ConfigPriority.GLOBAL)
+        )
+
+        # 3. User config
+        user_path = _user_config_dir(self._app_name) / self._filename
+        self._layered.add_layer(
+            ConfigLayer.from_file(
+                user_path, name="user", priority=ConfigPriority.USER, mutable=True
+            )
+        )
+
+    def _rebuild_model(self) -> None:
+        """Rebuild the pydantic model from current configuration."""
+        data = self._layered.as_dict()
+        self._validation_errors.clear()
+
+        try:
+            self._model = self._model_class.model_validate(data)
+        except ValidationError as e:
+            self._validation_errors = [str(err) for err in e.errors()]
+            logger.warning("Configuration validation errors: {}", self._validation_errors)
+            # Fall back to defaults
+            self._model = self._model_class()
+
+    @property
+    def model(self) -> BaseModel:
+        """Get the validated configuration model."""
+        if self._model is None:
+            self._rebuild_model()
+        return self._model  # type: ignore[return-value]
+
+    def get_user_config_path(self) -> Path:
+        """Get the path to the user configuration file."""
+        return _user_config_dir(self._app_name) / self._filename
+
+    def ensure_user_config_dir(self) -> Path:
+        """Ensure user config directory exists and return its path."""
+        path = _user_config_dir(self._app_name)
+        path.mkdir(parents=True, exist_ok=True)
+        return path
+
+    @property
+    def validation_errors(self) -> list[str]:
+        """Get any validation errors from the last model rebuild."""
+        return list(self._validation_errors)
+
+    @property
+    def layers(self) -> LayeredConfig:
+        """Access the underlying LayeredConfig."""
+        return self._layered
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """
+        Get a configuration value using dot notation.
+
+        Args:
+            key: Dot-separated key path (e.g., "ui.theme").
+            default: Default value if key not found.
+
+        Returns:
+            The configuration value.
+        """
+        return self._layered.get(key, default)
+
+    def set(self, key: str, value: Any, *, persist: bool = False) -> None:
+        """
+        Set a configuration value.
+
+        By default, sets in the session layer (runtime-only).
+        Use persist=True to save to the user configuration file.
+
+        Args:
+            key: Dot-separated key path.
+            value: Value to set.
+            persist: If True, save to user config file.
+        """
+        if persist:
+            self._layered.set(key, value, layer_name="user")
+            user_layer = self._layered.get_layer("user")
+            if user_layer:
+                user_layer.save()
+        else:
+            self._layered.set(key, value, layer_name="session")
+
+        self._model = None  # Invalidate cached model
+
+    def reload(self) -> None:
+        """Reload configuration from all sources."""
+        # Re-load file-based layers
+        for layer in self._layered.layers():
+            if isinstance(layer.source, Path) and layer.source.exists():
+                reloaded = ConfigLayer.from_file(
+                    layer.source,
+                    name=layer.name,
+                    priority=layer.priority,
+                    mutable=layer.mutable,
+                )
+                self._layered.add_layer(reloaded)
+
+        self._rebuild_model()
+        logger.info("Configuration reloaded")
+
+    def save_user_config(self) -> None:
+        """Save user layer to file."""
+        user_layer = self._layered.get_layer("user")
+        if user_layer:
+            user_layer.save()
+            logger.info("User configuration saved")
+
+    def as_dict(self) -> dict[str, Any]:
+        """Return the merged configuration as a dictionary."""
+        return self._layered.as_dict()