provide-foundation 0.0.0.dev0__py3-none-any.whl

provide/foundation/config/loader.py

@@ -0,0 +1,311 @@
+"""
+Configuration loaders for various sources.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+import json
+import os
+from pathlib import Path
+from typing import TypeVar
+
+try:
+    import aiofiles
+except ImportError:
+    aiofiles = None
+
+from provide.foundation.config.base import BaseConfig
+from provide.foundation.config.env import RuntimeConfig
+from provide.foundation.config.types import ConfigDict, ConfigFormat, ConfigSource
+from provide.foundation.errors.config import ConfigurationError
+from provide.foundation.errors.decorators import with_error_handling
+from provide.foundation.errors.resources import NotFoundError
+
+T = TypeVar("T", bound=BaseConfig)
+
+
+class ConfigLoader(ABC):
+    """Abstract base class for configuration loaders."""
+
+    @abstractmethod
+    async def load(self, config_class: type[T]) -> T:
+        """
+        Load configuration.
+
+        Args:
+            config_class: Configuration class to instantiate
+
+        Returns:
+            Configuration instance
+        """
+        pass
+
+    @abstractmethod
+    def exists(self) -> bool:
+        """
+        Check if the configuration source exists.
+
+        Returns:
+            True if source exists
+        """
+        pass
+
+
+class FileConfigLoader(ConfigLoader):
+    """Load configuration from files."""
+
+    def __init__(
+        self,
+        path: str | Path,
+        format: ConfigFormat | None = None,
+        encoding: str = "utf-8",
+    ) -> None:
+        """
+        Initialize file configuration loader.
+
+        Args:
+            path: Path to configuration file
+            format: File format (auto-detected if None)
+            encoding: File encoding
+        """
+        self.path = Path(path)
+        self.encoding = encoding
+
+        if format is None:
+            format = ConfigFormat.from_extension(str(self.path))
+            if format is None:
+                raise ConfigurationError(
+                    f"Cannot determine format for file: {self.path}",
+                    code="CONFIG_FORMAT_UNKNOWN",
+                    path=str(self.path),
+                )
+
+        self.format = format
+
+    def exists(self) -> bool:
+        """Check if configuration file exists."""
+        return self.path.exists()
+
+    @with_error_handling(
+        context_provider=lambda: {"loader": "FileLoader"},
+        error_mapper=lambda e: ConfigurationError(
+            f"Failed to load configuration: {e}", code="CONFIG_LOAD_ERROR", cause=e
+        )
+        if not isinstance(e, ConfigurationError | NotFoundError)
+        else e,
+    )
+    async def load(self, config_class: type[T]) -> T:
+        """Load configuration from file."""
+        if not self.exists():
+            raise NotFoundError(
+                f"Configuration file not found: {self.path}",
+                code="CONFIG_FILE_NOT_FOUND",
+                path=str(self.path),
+            )
+
+        data = await self._read_file()
+        return config_class.from_dict(data, source=ConfigSource.FILE)
+
+    async def _read_file(self) -> ConfigDict:
+        """Read and parse configuration file."""
+        if aiofiles:
+            async with aiofiles.open(self.path, encoding=self.encoding) as f:
+                content = await f.read()
+        else:
+            # Fallback to synchronous read
+            with open(self.path, encoding=self.encoding) as f:
+                content = f.read()
+
+        if self.format == ConfigFormat.JSON:
+            return json.loads(content)
+        elif self.format == ConfigFormat.YAML:
+            import yaml
+
+            return yaml.safe_load(content)
+        elif self.format == ConfigFormat.TOML:
+            try:
+                import tomllib
+            except ImportError:
+                import tomli as tomllib
+            return tomllib.loads(content)
+        elif self.format == ConfigFormat.INI:
+            import configparser
+
+            parser = configparser.ConfigParser()
+            parser.read_string(content)
+            return self._ini_to_dict(parser)
+        elif self.format == ConfigFormat.ENV:
+            return self._parse_env_file(content)
+        else:
+            raise ConfigurationError(
+                f"Unsupported format: {self.format}",
+                code="CONFIG_FORMAT_UNSUPPORTED",
+                format=str(self.format),
+            )
+
+    def _ini_to_dict(self, parser) -> ConfigDict:
+        """Convert INI parser to dictionary."""
+        result = {}
+        for section in parser.sections():
+            result[section] = dict(parser.items(section))
+
+        # Include DEFAULT section if present
+        if parser.defaults():
+            result["DEFAULT"] = dict(parser.defaults())
+
+        return result
+
+    def _parse_env_file(self, content: str) -> ConfigDict:
+        """Parse .env file format."""
+        result = {}
+
+        for line in content.splitlines():
+            line = line.strip()
+
+            # Skip comments and empty lines
+            if not line or line.startswith("#"):
+                continue
+
+            # Parse key=value
+            if "=" in line:
+                key, value = line.split("=", 1)
+                key = key.strip().lower()  # Convert to lowercase for compatibility
+                value = value.strip()
+
+                # Remove quotes if present
+                if (value.startswith('"') and value.endswith('"')) or (
+                    value.startswith("'") and value.endswith("'")
+                ):
+                    value = value[1:-1]
+
+                result[key] = value
+
+        return result
+
+
+class RuntimeConfigLoader(ConfigLoader):
+    """Load configuration from environment variables."""
+
+    def __init__(
+        self, prefix: str = "", delimiter: str = "_", case_sensitive: bool = False
+    ) -> None:
+        """
+        Initialize environment configuration loader.
+
+        Args:
+            prefix: Prefix for environment variables
+            delimiter: Delimiter between prefix and field name
+            case_sensitive: Whether variable names are case-sensitive
+        """
+        self.prefix = prefix
+        self.delimiter = delimiter
+        self.case_sensitive = case_sensitive
+
+    def exists(self) -> bool:
+        """Check if any relevant environment variables exist."""
+        if self.prefix:
+            prefix_with_delim = f"{self.prefix}{self.delimiter}"
+            return any(key.startswith(prefix_with_delim) for key in os.environ)
+        return bool(os.environ)
+
+    async def load(self, config_class: type[T]) -> T:
+        """Load configuration from environment variables."""
+        if not issubclass(config_class, RuntimeConfig):
+            raise TypeError(f"{config_class.__name__} must inherit from RuntimeConfig")
+
+        return config_class.from_env(
+            prefix=self.prefix,
+            delimiter=self.delimiter,
+            case_sensitive=self.case_sensitive,
+        )
+
+
+class DictConfigLoader(ConfigLoader):
+    """Load configuration from a dictionary."""
+
+    def __init__(
+        self, data: ConfigDict, source: ConfigSource = ConfigSource.RUNTIME
+    ) -> None:
+        """
+        Initialize dictionary configuration loader.
+
+        Args:
+            data: Configuration data
+            source: Source of the configuration
+        """
+        self.data = data
+        self.source = source
+
+    def exists(self) -> bool:
+        """Check if configuration data exists."""
+        return self.data is not None
+
+    async def load(self, config_class: type[T]) -> T:
+        """Load configuration from dictionary."""
+        return config_class.from_dict(self.data, source=self.source)
+
+
+class MultiSourceLoader(ConfigLoader):
+    """Load configuration from multiple sources with precedence."""
+
+    def __init__(self, *loaders: ConfigLoader) -> None:
+        """
+        Initialize multi-source configuration loader.
+
+        Args:
+            *loaders: Configuration loaders in order of precedence (later overrides earlier)
+        """
+        self.loaders = loaders
+
+    def exists(self) -> bool:
+        """Check if any configuration source exists."""
+        return any(loader.exists() for loader in self.loaders)
+
+    async def load(self, config_class: type[T]) -> T:
+        """Load and merge configuration from multiple sources."""
+        if not self.exists():
+            raise ValueError("No configuration sources available")
+
+        config = None
+
+        for loader in self.loaders:
+            if loader.exists():
+                if config is None:
+                    config = await loader.load(config_class)
+                else:
+                    # Load and merge
+                    new_config = await loader.load(config_class)
+                    new_dict = new_config.to_dict(include_sensitive=True)
+                    # Update each field with its proper source
+                    for key, value in new_dict.items():
+                        source = new_config.get_source(key)
+                        if source is not None:
+                            config.update({key: value}, source=source)
+
+        return config
+
+
+class ChainedLoader(ConfigLoader):
+    """Try multiple loaders until one succeeds."""
+
+    def __init__(self, *loaders: ConfigLoader) -> None:
+        """
+        Initialize chained configuration loader.
+
+        Args:
+            *loaders: Configuration loaders to try in order
+        """
+        self.loaders = loaders
+
+    def exists(self) -> bool:
+        """Check if any configuration source exists."""
+        return any(loader.exists() for loader in self.loaders)
+
+    async def load(self, config_class: type[T]) -> T:
+        """Load configuration from first available source."""
+        for loader in self.loaders:
+            if loader.exists():
+                return await loader.load(config_class)
+
+        raise ValueError("No configuration source available")

provide/foundation/config/manager.py

@@ -0,0 +1,387 @@
+"""
+Configuration manager for centralized configuration management.
+"""
+
+from __future__ import annotations
+
+from typing import TypeVar
+
+from provide.foundation.config.base import BaseConfig
+from provide.foundation.config.loader import ConfigLoader
+from provide.foundation.config.schema import ConfigSchema
+from provide.foundation.config.types import ConfigDict, ConfigSource
+
+T = TypeVar("T", bound=BaseConfig)
+
+
+class ConfigManager:
+    """
+    Centralized configuration manager.
+
+    Manages multiple configuration objects and provides a unified interface.
+    """
+
+    def __init__(self) -> None:
+        """Initialize configuration manager."""
+        self._configs: dict[str, BaseConfig] = {}
+        self._schemas: dict[str, ConfigSchema] = {}
+        self._loaders: dict[str, ConfigLoader] = {}
+        self._defaults: dict[str, ConfigDict] = {}
+
+    async def register(
+        self,
+        name: str,
+        config: BaseConfig | None = None,
+        schema: ConfigSchema | None = None,
+        loader: ConfigLoader | None = None,
+        defaults: ConfigDict | None = None,
+    ) -> None:
+        """
+        Register a configuration.
+
+        Args:
+            name: Configuration name
+            config: Configuration instance
+            schema: Configuration schema
+            loader: Configuration loader
+            defaults: Default configuration values
+        """
+        if config is not None:
+            self._configs[name] = config
+
+        if schema is not None:
+            self._schemas[name] = schema
+
+        if loader is not None:
+            self._loaders[name] = loader
+
+        if defaults is not None:
+            self._defaults[name] = defaults
+
+    def unregister(self, name: str) -> None:
+        """
+        Unregister a configuration.
+
+        Args:
+            name: Configuration name
+        """
+        self._configs.pop(name, None)
+        self._schemas.pop(name, None)
+        self._loaders.pop(name, None)
+        self._defaults.pop(name, None)
+
+    # Alias for unregister
+    def remove(self, name: str) -> None:
+        """Remove a configuration. Alias for unregister."""
+        self.unregister(name)
+
+    async def get(self, name: str) -> BaseConfig | None:
+        """
+        Get a configuration by name.
+
+        Args:
+            name: Configuration name
+
+        Returns:
+            Configuration instance or None
+        """
+        return self._configs.get(name)
+
+    async def set(self, name: str, config: BaseConfig) -> None:
+        """
+        Set a configuration.
+
+        Args:
+            name: Configuration name
+            config: Configuration instance
+        """
+        self._configs[name] = config
+
+    async def load(
+        self, name: str, config_class: type[T], loader: ConfigLoader | None = None
+    ) -> T:
+        """
+        Load a configuration.
+
+        Args:
+            name: Configuration name
+            config_class: Configuration class
+            loader: Optional loader (uses registered if None)
+
+        Returns:
+            Configuration instance
+        """
+        # Use provided loader or registered one
+        if loader is None:
+            loader = self._loaders.get(name)
+            if loader is None:
+                raise ValueError(f"No loader registered for configuration: {name}")
+
+        # Load configuration
+        config = await loader.load(config_class)
+
+        # Apply defaults if available
+        if name in self._defaults:
+            defaults_dict = self._defaults[name]
+            for key, value in defaults_dict.items():
+                if not hasattr(config, key) or getattr(config, key) is None:
+                    setattr(config, key, value)
+
+        # Validate against schema if available
+        if name in self._schemas:
+            schema = self._schemas[name]
+            config_dict = config.to_dict(include_sensitive=True)
+            await schema.validate(config_dict)
+
+        # Store configuration
+        self._configs[name] = config
+
+        return config
+
+    async def reload(self, name: str) -> BaseConfig:
+        """
+        Reload a configuration.
+
+        Args:
+            name: Configuration name
+
+        Returns:
+            Reloaded configuration instance
+        """
+        if name not in self._configs:
+            raise ValueError(f"Configuration not found: {name}")
+
+        config = self._configs[name]
+        loader = self._loaders.get(name)
+
+        if loader is None:
+            raise ValueError(f"No loader registered for configuration: {name}")
+
+        # Reload from loader
+        new_config = await loader.load(config.__class__)
+
+        # Apply defaults
+        if name in self._defaults:
+            defaults_dict = self._defaults[name]
+            for key, value in defaults_dict.items():
+                if not hasattr(new_config, key) or getattr(new_config, key) is None:
+                    setattr(new_config, key, value)
+
+        # Validate
+        if name in self._schemas:
+            schema = self._schemas[name]
+            config_dict = new_config.to_dict(include_sensitive=True)
+            await schema.validate(config_dict)
+
+        # Update stored configuration
+        self._configs[name] = new_config
+
+        return new_config
+
+    async def update(
+        self,
+        name: str,
+        updates: ConfigDict,
+        source: ConfigSource = ConfigSource.RUNTIME,
+    ) -> None:
+        """
+        Update a configuration.
+
+        Args:
+            name: Configuration name
+            updates: Configuration updates
+            source: Source of updates
+        """
+        if name not in self._configs:
+            raise ValueError(f"Configuration not found: {name}")
+
+        config = self._configs[name]
+
+        # Validate updates against schema if available
+        if name in self._schemas:
+            schema = self._schemas[name]
+            # Validate only the updated fields
+            for key, value in updates.items():
+                if key in schema._field_map:
+                    await schema._field_map[key].validate(value)
+
+        # Apply updates
+        config.update(updates, source)
+
+    async def reset(self, name: str) -> None:
+        """
+        Reset a configuration to defaults.
+
+        Args:
+            name: Configuration name
+        """
+        if name not in self._configs:
+            raise ValueError(f"Configuration not found: {name}")
+
+        config = self._configs[name]
+        config.reset_to_defaults()
+
+        # Apply registered defaults
+        if name in self._defaults:
+            config.update(self._defaults[name], ConfigSource.DEFAULT)
+
+    def list_configs(self) -> list[str]:
+        """
+        List all registered configurations.
+
+        Returns:
+            List of configuration names
+        """
+        return list(self._configs.keys())
+
+    def get_all(self) -> dict[str, BaseConfig]:
+        """Get all registered configurations."""
+        return self._configs.copy()
+
+    def clear(self) -> None:
+        """Clear all configurations."""
+        self._configs.clear()
+        self._schemas.clear()
+        self._loaders.clear()
+        self._defaults.clear()
+
+    async def export(self, name: str, include_sensitive: bool = False) -> ConfigDict:
+        """
+        Export a configuration as dictionary.
+
+        Args:
+            name: Configuration name
+            include_sensitive: Whether to include sensitive fields
+
+        Returns:
+            Configuration dictionary
+        """
+        if name not in self._configs:
+            raise ValueError(f"Configuration not found: {name}")
+
+        return self._configs[name].to_dict(include_sensitive)
+
+    async def export_all(
+        self, include_sensitive: bool = False
+    ) -> dict[str, ConfigDict]:
+        """
+        Export all configurations.
+
+        Args:
+            include_sensitive: Whether to include sensitive fields
+
+        Returns:
+            Dictionary of all configurations
+        """
+        result = {}
+        for name, config in self._configs.items():
+            result[name] = config.to_dict(include_sensitive)
+        return result
+
+    # Alias for export_all
+    async def export_to_dict(
+        self, include_sensitive: bool = False
+    ) -> dict[str, ConfigDict]:
+        """Export all configs to dict. Alias for export_all."""
+        return await self.export_all(include_sensitive)
+
+    async def load_from_dict(
+        self, name: str, config_class: type[T], data: ConfigDict
+    ) -> T:
+        """Load config from dictionary."""
+        config = config_class.from_dict(data)
+        self._configs[name] = config
+        return config
+
+    def add_loader(self, name: str, loader: ConfigLoader) -> None:
+        """Add a loader for a configuration."""
+        self._loaders[name] = loader
+
+    async def validate_all(self) -> None:
+        """Validate all configurations."""
+        for name, config in self._configs.items():
+            if hasattr(config, "validate"):
+                await config.validate()
+            if name in self._schemas:
+                schema = self._schemas[name]
+                config_dict = config.to_dict(include_sensitive=True)
+                if hasattr(schema, "validate"):
+                    await schema.validate(config_dict)
+
+    async def get_or_create(
+        self, name: str, config_class: type[T], defaults: ConfigDict | None = None
+    ) -> T:
+        """Get existing config or create new one with defaults."""
+        existing = await self.get(name)
+        if existing is not None:
+            return existing
+
+        # Create new config with defaults
+        config = config_class.from_dict(defaults or {})
+        self._configs[name] = config
+        return config
+
+
+# Global configuration manager instance
+_manager = ConfigManager()
+
+
+async def get_config(name: str) -> BaseConfig | None:
+    """
+    Get a configuration from the global manager.
+
+    Args:
+        name: Configuration name
+
+    Returns:
+        Configuration instance or None
+    """
+    return await _manager.get(name)
+
+
+async def set_config(name: str, config: BaseConfig) -> None:
+    """
+    Set a configuration in the global manager.
+
+    Args:
+        name: Configuration name
+        config: Configuration instance
+    """
+    await _manager.set(name, config)
+
+
+async def register_config(
+    name: str,
+    config: BaseConfig | None = None,
+    schema: ConfigSchema | None = None,
+    loader: ConfigLoader | None = None,
+    defaults: ConfigDict | None = None,
+) -> None:
+    """
+    Register a configuration with the global manager.
+
+    Args:
+        name: Configuration name
+        config: Configuration instance
+        schema: Configuration schema
+        loader: Configuration loader
+        defaults: Default configuration values
+    """
+    await _manager.register(name, config, schema, loader, defaults)
+
+
+async def load_config(
+    name: str, config_class: type[T], loader: ConfigLoader | None = None
+) -> T:
+    """
+    Load a configuration using the global manager.
+
+    Args:
+        name: Configuration name
+        config_class: Configuration class
+        loader: Optional loader
+
+    Returns:
+        Configuration instance
+    """
+    return await _manager.load(name, config_class, loader)