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

provide/foundation/config/schema.py

@@ -0,0 +1,284 @@
+"""
+Configuration schema and validation.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from attrs import Attribute, define, fields
+
+from provide.foundation.config.base import BaseConfig
+from provide.foundation.config.types import ConfigDict
+from provide.foundation.errors import ConfigValidationError
+
+
+@define
+class SchemaField:
+    """Schema definition for a configuration field."""
+
+    name: str
+    type: type | None = None
+    required: bool = False
+    default: Any = None
+    description: str | None = None
+    validator: Callable[[Any], bool | Awaitable[bool]] | None = None
+    choices: list[Any] | None = None
+    min_value: Any = None
+    max_value: Any = None
+    pattern: str | None = None
+    sensitive: bool = False
+
+    async def validate(self, value: Any) -> None:
+        """
+        Validate a value against this schema field.
+
+        Args:
+            value: Value to validate
+
+        Raises:
+            ConfigValidationError: If validation fails
+        """
+        # Check required
+        if self.required and value is None:
+            raise ConfigValidationError(
+                "Field is required", field=self.name, value=value
+            )
+
+        # Skip further validation for None values
+        if value is None:
+            return
+
+        # Check type
+        if self.type is not None and not isinstance(value, self.type):
+            raise ConfigValidationError(
+                f"Expected type {self.type.__name__}, got {type(value).__name__}",
+                field=self.name,
+                value=value,
+            )
+
+        # Check choices
+        if self.choices is not None and value not in self.choices:
+            raise ConfigValidationError(
+                f"Value must be one of {self.choices}", field=self.name, value=value
+            )
+
+        # Check min/max
+        if self.min_value is not None and value < self.min_value:
+            raise ConfigValidationError(
+                f"Value must be >= {self.min_value}", field=self.name, value=value
+            )
+
+        if self.max_value is not None and value > self.max_value:
+            raise ConfigValidationError(
+                f"Value must be <= {self.max_value}", field=self.name, value=value
+            )
+
+        # Check pattern
+        if self.pattern is not None and isinstance(value, str):
+            import re
+
+            if not re.match(self.pattern, value):
+                raise ConfigValidationError(
+                    f"Value does not match pattern: {self.pattern}",
+                    field=self.name,
+                    value=value,
+                )
+
+        # Custom validator
+        if self.validator is not None:
+            try:
+                result = self.validator(value)
+                # Handle both sync and async validators
+                if asyncio.iscoroutine(result) or asyncio.isfuture(result):
+                    result = await result
+                if not result:
+                    raise ConfigValidationError(
+                        "Custom validation failed", field=self.name, value=value
+                    )
+            except ConfigValidationError:
+                raise
+            except Exception as e:
+                raise ConfigValidationError(
+                    f"Validation error: {e}", field=self.name, value=value
+                )
+
+
+class ConfigSchema:
+    """Schema definition for configuration classes."""
+
+    def __init__(self, fields: list[SchemaField] | None = None) -> None:
+        """
+        Initialize configuration schema.
+
+        Args:
+            fields: List of schema fields
+        """
+        self.fields = fields or []
+        self._field_map = {field.name: field for field in self.fields}
+
+    def add_field(self, field: SchemaField) -> None:
+        """Add a field to the schema."""
+        self.fields.append(field)
+        self._field_map[field.name] = field
+
+    async def validate(self, data: ConfigDict) -> None:
+        """
+        Validate configuration data against schema.
+
+        Args:
+            data: Configuration data to validate
+
+        Raises:
+            ConfigValidationError: If validation fails
+        """
+        # Check required fields
+        for field in self.fields:
+            if field.required and field.name not in data:
+                raise ConfigValidationError("Required field missing", field=field.name)
+
+        # Validate each field
+        for key, value in data.items():
+            if key in self._field_map:
+                await self._field_map[key].validate(value)
+
+    def apply_defaults(self, data: ConfigDict) -> ConfigDict:
+        """
+        Apply default values to configuration data.
+
+        Args:
+            data: Configuration data
+
+        Returns:
+            Data with defaults applied
+        """
+        result = data.copy()
+
+        for field in self.fields:
+            if field.name not in result and field.default is not None:
+                result[field.name] = field.default
+
+        return result
+
+    def filter_extra_fields(self, data: ConfigDict) -> ConfigDict:
+        """
+        Remove fields not defined in schema.
+
+        Args:
+            data: Configuration data
+
+        Returns:
+            Filtered data
+        """
+        return {k: v for k, v in data.items() if k in self._field_map}
+
+    @classmethod
+    def from_config_class(cls, config_class: type[BaseConfig]) -> ConfigSchema:
+        """
+        Generate schema from configuration class.
+
+        Args:
+            config_class: Configuration class
+
+        Returns:
+            Generated schema
+        """
+        schema_fields = []
+
+        for attr in fields(config_class):
+            schema_field = cls._attr_to_schema_field(attr)
+            schema_fields.append(schema_field)
+
+        return cls(schema_fields)
+
+    @staticmethod
+    def _attr_to_schema_field(attr: Attribute) -> SchemaField:
+        """Convert attrs attribute to schema field."""
+        # Determine if required
+        required = attr.default is None and attr.factory is None
+
+        # Get type from attribute
+        field_type = getattr(attr, "type", None)
+
+        # Extract metadata
+        description = attr.metadata.get("description")
+        sensitive = attr.metadata.get("sensitive", False)
+
+        # Create schema field
+        return SchemaField(
+            name=attr.name,
+            type=field_type,
+            required=required,
+            default=attr.default if attr.default is not None else None,
+            description=description,
+            sensitive=sensitive,
+        )
+
+
+async def validate_schema(config: BaseConfig, schema: ConfigSchema) -> None:
+    """
+    Validate configuration instance against schema.
+
+    Args:
+        config: Configuration instance
+        schema: Schema to validate against
+
+    Raises:
+        ConfigValidationError: If validation fails
+    """
+    data = config.to_dict(include_sensitive=True)
+    await schema.validate(data)
+
+
+# Common validators (all sync since they're simple checks)
+def validate_port(value: int) -> bool:
+    """Validate port number."""
+    return 1 <= value <= 65535
+
+
+def validate_url(value: str) -> bool:
+    """Validate URL format."""
+    from urllib.parse import urlparse
+
+    try:
+        result = urlparse(value)
+        return all([result.scheme, result.netloc])
+    except Exception:
+        return False
+
+
+def validate_email(value: str) -> bool:
+    """Validate email format."""
+    import re
+
+    pattern = r"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$"
+    return bool(re.match(pattern, value))
+
+
+def validate_path(value: str) -> bool:
+    """Validate file path."""
+    from pathlib import Path
+
+    try:
+        Path(value)
+        return True
+    except Exception:
+        return False
+
+
+def validate_version(value: str) -> bool:
+    """Validate semantic version."""
+    import re
+
+    pattern = r"^\d+\.\d+\.\d+(-[a-zA-Z0-9.-]+)?(\+[a-zA-Z0-9.-]+)?$"
+    return bool(re.match(pattern, value))
+
+
+# Example async validator for complex checks
+async def validate_url_accessible(value: str) -> bool:
+    """Validate URL is accessible (example async validator)."""
+    # This is just an example - in real use you'd use aiohttp or similar
+    # For now, just do basic URL validation
+    return validate_url(value)

provide/foundation/config/sync.py

@@ -0,0 +1,281 @@
+"""
+Synchronous wrappers for the async configuration system.
+
+These wrappers allow using the async config system in synchronous contexts
+like CLI tools, scripts, and frameworks that don't support async.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+from typing import Any, TypeVar
+
+from provide.foundation.config.base import BaseConfig
+from provide.foundation.config.env import RuntimeConfig
+from provide.foundation.config.loader import (
+    DictConfigLoader,
+    FileConfigLoader,
+    MultiSourceLoader,
+)
+from provide.foundation.config.manager import ConfigManager
+from provide.foundation.config.types import ConfigDict, ConfigSource
+
+T = TypeVar("T", bound=BaseConfig)
+
+
+def run_async(coro):
+    """
+    Run an async coroutine in a sync context.
+
+    Creates a new event loop if needed or uses the existing one.
+    """
+    try:
+        # Try to get the current event loop
+        asyncio.get_running_loop()
+        # If we're here, we're already in an async context
+        # This shouldn't happen in sync code, but handle it gracefully
+        import concurrent.futures
+
+        with concurrent.futures.ThreadPoolExecutor() as executor:
+            future = executor.submit(asyncio.run, coro)
+            return future.result()
+    except RuntimeError:
+        # No event loop, create one
+        return asyncio.run(coro)
+
+
+def load_config(
+    config_class: type[T],
+    data: ConfigDict | None = None,
+    source: ConfigSource = ConfigSource.RUNTIME,
+) -> T:
+    """
+    Load configuration from dictionary (sync wrapper).
+
+    Args:
+        config_class: Configuration class
+        data: Configuration data
+        source: Source of the configuration
+
+    Returns:
+        Configuration instance
+    """
+    if data is None:
+        data = {}
+    return run_async(config_class.from_dict(data, source))
+
+
+def load_config_from_env(
+    config_class: type[T],
+    prefix: str = "",
+    delimiter: str = "_",
+    case_sensitive: bool = False,
+) -> T:
+    """
+    Load configuration from environment variables (sync wrapper).
+
+    Args:
+        config_class: Configuration class (must inherit from RuntimeConfig)
+        prefix: Prefix for environment variables
+        delimiter: Delimiter between prefix and field name
+        case_sensitive: Whether variable names are case-sensitive
+
+    Returns:
+        Configuration instance
+    """
+    if not issubclass(config_class, RuntimeConfig):
+        raise TypeError(f"{config_class.__name__} must inherit from RuntimeConfig")
+
+    return run_async(
+        config_class.from_env(
+            prefix=prefix,
+            delimiter=delimiter,
+            case_sensitive=case_sensitive,
+            use_async_secrets=False,  # Use sync I/O in sync context
+        )
+    )
+
+
+def load_config_from_file(
+    path: str | Path,
+    config_class: type[T],
+    format: str | None = None,
+    encoding: str = "utf-8",
+) -> T:
+    """
+    Load configuration from file (sync wrapper).
+
+    Args:
+        path: Path to configuration file
+        config_class: Configuration class
+        format: File format (auto-detected if None)
+        encoding: File encoding
+
+    Returns:
+        Configuration instance
+    """
+    loader = FileConfigLoader(path, format=format, encoding=encoding)
+    return run_async(loader.load(config_class))
+
+
+def load_config_from_multiple(
+    config_class: type[T],
+    *sources: tuple[str, Any],
+) -> T:
+    """
+    Load configuration from multiple sources (sync wrapper).
+
+    Args:
+        config_class: Configuration class
+        *sources: Tuples of (source_type, source_data) where:
+            - source_type: "file", "env", "dict"
+            - source_data: Path for file, prefix for env, dict for dict
+
+    Returns:
+        Configuration instance merged from all sources
+    """
+    loaders = []
+
+    for source_type, source_data in sources:
+        if source_type == "file":
+            loaders.append(FileConfigLoader(source_data))
+        elif source_type == "env":
+            from provide.foundation.config.loader import RuntimeConfigLoader
+
+            loaders.append(RuntimeConfigLoader(prefix=source_data))
+        elif source_type == "dict":
+            loaders.append(DictConfigLoader(source_data))
+        else:
+            raise ValueError(f"Unknown source type: {source_type}")
+
+    multi_loader = MultiSourceLoader(*loaders)
+    return run_async(multi_loader.load(config_class))
+
+
+def validate_config(config: BaseConfig) -> None:
+    """
+    Validate a configuration instance (sync wrapper).
+
+    Args:
+        config: Configuration instance to validate
+    """
+    run_async(config.validate())
+
+
+def update_config(
+    config: BaseConfig, updates: ConfigDict, source: ConfigSource = ConfigSource.RUNTIME
+) -> None:
+    """
+    Update configuration with new values (sync wrapper).
+
+    Args:
+        config: Configuration instance
+        updates: Dictionary of updates
+        source: Source of the updates
+    """
+    run_async(config.update(updates, source))
+
+
+def config_to_dict(config: BaseConfig, include_sensitive: bool = False) -> ConfigDict:
+    """
+    Convert configuration to dictionary (sync wrapper).
+
+    Args:
+        config: Configuration instance
+        include_sensitive: Whether to include sensitive fields
+
+    Returns:
+        Dictionary representation
+    """
+    return run_async(config.to_dict(include_sensitive))
+
+
+def clone_config(config: T) -> T:
+    """
+    Create a deep copy of configuration (sync wrapper).
+
+    Args:
+        config: Configuration instance
+
+    Returns:
+        Cloned configuration
+    """
+    return run_async(config.clone())
+
+
+def diff_configs(
+    config1: BaseConfig, config2: BaseConfig
+) -> dict[str, tuple[Any, Any]]:
+    """
+    Compare two configurations (sync wrapper).
+
+    Args:
+        config1: First configuration
+        config2: Second configuration
+
+    Returns:
+        Dictionary of differences
+    """
+    return run_async(config1.diff(config2))
+
+
+class SyncConfigManager:
+    """
+    Synchronous wrapper for ConfigManager.
+
+    Provides a sync interface to the async ConfigManager.
+    """
+
+    def __init__(self) -> None:
+        """Initialize sync config manager."""
+        self._async_manager = ConfigManager()
+
+    def register(self, name: str, config: BaseConfig | None = None, **kwargs) -> None:
+        """Register a configuration (sync)."""
+        run_async(self._async_manager.register(name, config, **kwargs))
+
+    def get(self, name: str) -> BaseConfig | None:
+        """Get a configuration by name (sync)."""
+        return run_async(self._async_manager.get(name))
+
+    def load(self, name: str, config_class: type[T], loader=None) -> T:
+        """Load a configuration (sync)."""
+        return run_async(self._async_manager.load(name, config_class, loader))
+
+    def update(
+        self,
+        name: str,
+        updates: ConfigDict,
+        source: ConfigSource = ConfigSource.RUNTIME,
+    ) -> None:
+        """Update a configuration (sync)."""
+        run_async(self._async_manager.update(name, updates, source))
+
+    def export(self, name: str, include_sensitive: bool = False) -> ConfigDict:
+        """Export a configuration as dictionary (sync)."""
+        return run_async(self._async_manager.export(name, include_sensitive))
+
+    def export_all(self, include_sensitive: bool = False) -> dict[str, ConfigDict]:
+        """Export all configurations (sync)."""
+        return run_async(self._async_manager.export_all(include_sensitive))
+
+
+# Global sync manager instance
+sync_manager = SyncConfigManager()
+
+
+# Convenience functions using the global sync manager
+def get_config(name: str) -> BaseConfig | None:
+    """Get a configuration from the global sync manager."""
+    return sync_manager.get(name)
+
+
+def set_config(name: str, config: BaseConfig) -> None:
+    """Set a configuration in the global sync manager."""
+    sync_manager.register(name, config=config)
+
+
+def register_config(name: str, **kwargs) -> None:
+    """Register a configuration with the global sync manager."""
+    sync_manager.register(name, **kwargs)

provide/foundation/config/types.py

@@ -0,0 +1,78 @@
+"""
+Type definitions for the configuration system.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+# Basic type aliases
+ConfigValue = str | int | float | bool | None | list[Any] | dict[str, Any]
+ConfigDict = dict[str, ConfigValue]
+
+
+class ConfigSource(Enum):
+    """Sources for configuration values with precedence order."""
+
+    DEFAULT = 0  # Lowest precedence
+    FILE = 10
+    ENV = 20
+    RUNTIME = 30  # Highest precedence
+
+    def __lt__(self, other):
+        """Enable comparison for precedence."""
+        if not isinstance(other, ConfigSource):
+            return NotImplemented
+        return self.value < other.value
+
+    def __le__(self, other):
+        """Enable <= comparison for precedence."""
+        if not isinstance(other, ConfigSource):
+            return NotImplemented
+        return self.value <= other.value
+
+    def __gt__(self, other):
+        """Enable > comparison for precedence."""
+        if not isinstance(other, ConfigSource):
+            return NotImplemented
+        return self.value > other.value
+
+    def __ge__(self, other):
+        """Enable >= comparison for precedence."""
+        if not isinstance(other, ConfigSource):
+            return NotImplemented
+        return self.value >= other.value
+
+    def __eq__(self, other):
+        """Enable == comparison for precedence."""
+        if not isinstance(other, ConfigSource):
+            return NotImplemented
+        return self.value == other.value
+
+
+class ConfigFormat(Enum):
+    """Supported configuration file formats."""
+
+    JSON = "json"
+    YAML = "yaml"
+    TOML = "toml"
+    INI = "ini"
+    ENV = "env"  # .env files
+
+    @classmethod
+    def from_extension(cls, filename: str) -> ConfigFormat | None:
+        """Determine format from file extension."""
+        ext_map = {
+            ".json": cls.JSON,
+            ".yaml": cls.YAML,
+            ".yml": cls.YAML,
+            ".toml": cls.TOML,
+            ".ini": cls.INI,
+            ".env": cls.ENV,
+        }
+
+        for ext, format_type in ext_map.items():
+            if filename.lower().endswith(ext):
+                return format_type
+        return None