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

provide/foundation/config/base.py

@@ -0,0 +1,295 @@
+"""
+Base configuration classes and utilities.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+import copy
+from typing import Any, TypeVar
+
+from attrs import NOTHING, Attribute, define, field as attrs_field, fields
+
+from provide.foundation.config.types import ConfigDict, ConfigSource
+
+T = TypeVar("T", bound="BaseConfig")
+
+
+def field(
+    *,
+    default: Any = NOTHING,
+    factory: Callable[[], Any] | None = None,
+    validator: Callable[[Any, Attribute, Any], None] | None = None,
+    converter: Callable[[Any], Any] | None = None,
+    metadata: dict[str, Any] | None = None,
+    description: str | None = None,
+    env_var: str | None = None,
+    env_prefix: str | None = None,
+    sensitive: bool = False,
+    **kwargs: Any,
+) -> Any:
+    """
+    Enhanced attrs field with configuration-specific metadata.
+
+    Args:
+        default: Default value for the field
+        factory: Factory function to generate default value
+        validator: Validation function
+        converter: Conversion function
+        metadata: Additional metadata
+        description: Human-readable description
+        env_var: Environment variable name override
+        env_prefix: Prefix for environment variable
+        sensitive: Whether this field contains sensitive data
+        **kwargs: Additional attrs field arguments
+    """
+    config_metadata = metadata or {}
+
+    # Add configuration-specific metadata
+    if description:
+        config_metadata["description"] = description
+    if env_var:
+        config_metadata["env_var"] = env_var
+    if env_prefix:
+        config_metadata["env_prefix"] = env_prefix
+    if sensitive:
+        config_metadata["sensitive"] = sensitive
+
+    # Handle factory vs default
+    if factory is not None:
+        return attrs_field(
+            factory=factory,
+            validator=validator,
+            converter=converter,
+            metadata=config_metadata,
+            **kwargs,
+        )
+    else:
+        return attrs_field(
+            default=default,
+            validator=validator,
+            converter=converter,
+            metadata=config_metadata,
+            **kwargs,
+        )
+
+
+@define(slots=True, repr=False)
+class BaseConfig:
+    """
+    Base configuration class with common functionality.
+
+    All configuration classes should inherit from this.
+    All methods are async to support async validation and I/O operations.
+    """
+
+    # These are instance attributes that need to be defined outside of slots
+    _source_map: dict[str, ConfigSource] = attrs_field(init=False, factory=lambda: {})
+    _original_values: dict[str, Any] = attrs_field(init=False, factory=lambda: {})
+
+    def __attrs_post_init__(self):
+        """Post-initialization hook for subclasses."""
+        # The _source_map and _original_values are now handled by attrs with factory
+        # Note: validate() is now async, so we can't call it here
+        # Users must explicitly call await config.validate() after creation
+        pass
+
+    async def validate(self) -> None:
+        """
+        Validate the configuration.
+
+        Override this method to add custom validation logic.
+        Can perform async operations like checking database connections.
+        """
+        pass
+
+    def to_dict(self, include_sensitive: bool = False) -> ConfigDict:
+        """
+        Convert configuration to dictionary.
+
+        Args:
+            include_sensitive: Whether to include sensitive fields
+
+        Returns:
+            Dictionary representation of the configuration
+        """
+        result = {}
+
+        for attr in fields(self.__class__):
+            value = getattr(self, attr.name)
+
+            # Skip sensitive fields if requested
+            if not include_sensitive and attr.metadata.get("sensitive", False):
+                continue
+
+            # Convert nested configs recursively
+            if isinstance(value, BaseConfig):
+                value = value.to_dict(include_sensitive)
+            elif isinstance(value, dict):
+                value = self._convert_dict_values(value, include_sensitive)
+            elif isinstance(value, list):
+                value = self._convert_list_values(value, include_sensitive)
+
+            result[attr.name] = value
+
+        return result
+
+    def _convert_dict_values(self, d: dict, include_sensitive: bool) -> dict:
+        """Convert dictionary values recursively."""
+        result = {}
+        for key, value in d.items():
+            if isinstance(value, BaseConfig):
+                value = value.to_dict(include_sensitive)
+            elif isinstance(value, dict):
+                value = self._convert_dict_values(value, include_sensitive)
+            elif isinstance(value, list):
+                value = self._convert_list_values(value, include_sensitive)
+            result[key] = value
+        return result
+
+    def _convert_list_values(self, lst: list, include_sensitive: bool) -> list:
+        """Convert list values recursively."""
+        result = []
+        for value in lst:
+            if isinstance(value, BaseConfig):
+                value = value.to_dict(include_sensitive)
+            elif isinstance(value, dict):
+                value = self._convert_dict_values(value, include_sensitive)
+            elif isinstance(value, list):
+                value = self._convert_list_values(value, include_sensitive)
+            result.append(value)
+        return result
+
+    @classmethod
+    def from_dict(
+        cls: type[T], data: ConfigDict, source: ConfigSource = ConfigSource.RUNTIME
+    ) -> T:
+        """
+        Create configuration from dictionary.
+
+        Args:
+            data: Configuration data
+            source: Source of the configuration
+
+        Returns:
+            Configuration instance
+        """
+        # Filter data to only include fields defined in the class
+        field_names = {f.name for f in fields(cls)}
+        filtered_data = {k: v for k, v in data.items() if k in field_names}
+
+        # Create instance
+        instance = cls(**filtered_data)
+
+        # Track sources
+        for key in filtered_data:
+            instance._source_map[key] = source
+            instance._original_values[key] = filtered_data[key]
+
+        return instance
+
+    def update(
+        self, updates: ConfigDict, source: ConfigSource = ConfigSource.RUNTIME
+    ) -> None:
+        """
+        Update configuration with new values.
+
+        Args:
+            updates: Dictionary of updates
+            source: Source of the updates
+        """
+        for key, value in updates.items():
+            if hasattr(self, key):
+                # Only update if new source has higher precedence
+                current_source = self._source_map.get(key, ConfigSource.DEFAULT)
+                if source >= current_source:
+                    setattr(self, key, value)
+                    self._source_map[key] = source
+                    self._original_values[key] = value
+
+        # Note: validate() is async, must be called separately if needed
+
+    def get_source(self, field_name: str) -> ConfigSource | None:
+        """
+        Get the source of a configuration field.
+
+        Args:
+            field_name: Name of the field
+
+        Returns:
+            Source of the field value or None
+        """
+        return self._source_map.get(field_name)
+
+    def reset_to_defaults(self) -> None:
+        """Reset all fields to their default values."""
+        for attr in fields(self.__class__):
+            # Skip internal fields
+            if attr.name.startswith("_"):
+                continue
+
+            if attr.default != NOTHING:
+                setattr(self, attr.name, attr.default)
+            elif attr.factory != NOTHING:
+                # attrs factory is always callable
+                setattr(self, attr.name, attr.factory())
+
+        self._source_map.clear()
+        self._original_values.clear()
+
+        # Note: validate() is async, must be called separately if needed
+
+    def clone(self: T) -> T:
+        """Create a deep copy of the configuration."""
+        cloned = copy.deepcopy(self)
+        # Note: validate() is async, must be called separately if needed
+        return cloned
+
+    def diff(self, other: BaseConfig) -> dict[str, tuple[Any, Any]]:
+        """
+        Compare with another configuration.
+
+        Args:
+            other: Configuration to compare with
+
+        Returns:
+            Dictionary of differences (field_name: (self_value, other_value))
+        """
+        if not isinstance(other, self.__class__):
+            raise TypeError(
+                f"Cannot compare {self.__class__.__name__} with {other.__class__.__name__}"
+            )
+
+        differences = {}
+
+        for attr in fields(self.__class__):
+            self_value = getattr(self, attr.name)
+            other_value = getattr(other, attr.name)
+
+            if self_value != other_value:
+                differences[attr.name] = (self_value, other_value)
+
+        return differences
+
+    def __repr__(self) -> str:
+        """String representation hiding sensitive fields."""
+        # Get the actual attrs fields
+        import attrs
+
+        attr_fields = attrs.fields(self.__class__)
+
+        parts = []
+        for attr in attr_fields:
+            # Skip internal fields
+            if attr.name.startswith("_"):
+                continue
+
+            value = getattr(self, attr.name)
+
+            # Hide sensitive values
+            if attr.metadata.get("sensitive", False):
+                value = "***SENSITIVE***"
+
+            parts.append(f"{attr.name}={value!r}")
+
+        return f"{self.__class__.__name__}({', '.join(parts)})"

provide/foundation/config/env.py

@@ -0,0 +1,369 @@
+"""
+Environment variable configuration utilities.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable
+import os
+from typing import Any, TypeVar
+
+try:
+    import aiofiles
+except ImportError:
+    aiofiles = None
+from attrs import fields
+
+from provide.foundation.config.base import BaseConfig, field
+from provide.foundation.config.types import ConfigSource
+from provide.foundation.utils.parsing import (
+    auto_parse,
+)
+
+T = TypeVar("T")
+
+
+async def get_env_async(
+    var_name: str,
+    default: str | None = None,
+    required: bool = False,
+    secret_file: bool = True,
+) -> str | None:
+    """
+    Get environment variable value with optional file-based secret support (async).
+
+    Args:
+        var_name: Environment variable name
+        default: Default value if not found
+        required: Whether the variable is required
+        secret_file: Whether to support file:// prefix for secrets
+
+    Returns:
+        Environment variable value or default
+
+    Raises:
+        ValueError: If required and not found
+    """
+    value = os.environ.get(var_name)
+
+    if value is None:
+        if required:
+            raise ValueError(f"Required environment variable '{var_name}' not found")
+        return default
+
+    # Handle file-based secrets asynchronously
+    if secret_file and value.startswith("file://"):
+        file_path = value[7:]  # Remove "file://" prefix
+        try:
+            async with aiofiles.open(file_path) as f:
+                value = await f.read()
+                value = value.strip()
+        except Exception as e:
+            raise ValueError(f"Failed to read secret from file '{file_path}': {e}")
+
+    return value
+
+
+def get_env(
+    var_name: str,
+    default: str | None = None,
+    required: bool = False,
+    secret_file: bool = True,
+) -> str | None:
+    """
+    Get environment variable value with optional file-based secret support (sync).
+
+    This is a compatibility function that uses sync I/O.
+    Prefer get_env_async for new code.
+
+    Args:
+        var_name: Environment variable name
+        default: Default value if not found
+        required: Whether the variable is required
+        secret_file: Whether to support file:// prefix for secrets
+
+    Returns:
+        Environment variable value or default
+
+    Raises:
+        ValueError: If required and not found
+    """
+    value = os.environ.get(var_name)
+
+    if value is None:
+        if required:
+            raise ValueError(f"Required environment variable '{var_name}' not found")
+        return default
+
+    # Handle file-based secrets synchronously
+    if secret_file and value.startswith("file://"):
+        file_path = value[7:]  # Remove "file://" prefix
+        try:
+            with open(file_path) as f:
+                value = f.read().strip()
+        except Exception as e:
+            raise ValueError(f"Failed to read secret from file '{file_path}': {e}")
+
+    return value
+
+
+def env_field(
+    env_var: str | None = None,
+    env_prefix: str | None = None,
+    parser: Callable[[str], Any] | None = None,
+    **kwargs,
+) -> Any:
+    """
+    Create a field that can be loaded from environment variables.
+
+    Args:
+        env_var: Explicit environment variable name
+        env_prefix: Prefix for environment variable
+        parser: Custom parser function
+        **kwargs: Additional field arguments
+
+    Returns:
+        Field descriptor
+    """
+    metadata = kwargs.pop("metadata", {})
+
+    if env_var:
+        metadata["env_var"] = env_var
+    if env_prefix:
+        metadata["env_prefix"] = env_prefix
+    if parser:
+        metadata["env_parser"] = parser
+
+    return field(metadata=metadata, **kwargs)
+
+
+class RuntimeConfig(BaseConfig):
+    """
+    Configuration that can be loaded from environment variables.
+    All methods are async to support async secret fetching and validation.
+    """
+
+    @classmethod
+    def from_env(
+        cls: type[T],
+        prefix: str = "",
+        delimiter: str = "_",
+        case_sensitive: bool = False,
+    ) -> T:
+        """
+        Load configuration from environment variables synchronously.
+
+        Args:
+            prefix: Prefix for all environment variables
+            delimiter: Delimiter between prefix and field name
+            case_sensitive: Whether variable names are case-sensitive
+
+        Returns:
+            Configuration instance
+        """
+        data = {}
+
+        for attr in fields(cls):
+            # Determine environment variable name
+            env_var = attr.metadata.get("env_var")
+
+            if not env_var:
+                # Build from prefix and field name
+                field_prefix = attr.metadata.get("env_prefix", prefix)
+                field_name = attr.name.upper() if not case_sensitive else attr.name
+
+                if field_prefix:
+                    env_var = f"{field_prefix}{delimiter}{field_name}"
+                else:
+                    env_var = field_name
+
+            # Get value from environment
+            raw_value = os.environ.get(env_var)
+
+            if raw_value is not None:
+                value = raw_value
+                # Check if it's a file-based secret
+                if value.startswith("file://"):
+                    # Read synchronously
+                    file_path = value[7:]
+                    try:
+                        with open(file_path) as f:
+                            value = f.read().strip()
+                    except Exception as e:
+                        raise ValueError(
+                            f"Failed to read secret from file '{file_path}': {e}"
+                        )
+
+                # Apply parser if specified
+                parser = attr.metadata.get("env_parser")
+
+                if parser:
+                    try:
+                        value = parser(value)
+                    except Exception as e:
+                        raise ValueError(f"Failed to parse {env_var}: {e}")
+                else:
+                    # Try to infer parser from type
+                    value = RuntimeConfig._auto_parse(attr, value)
+
+                data[attr.name] = value
+
+        return cls.from_dict(data, source=ConfigSource.ENV)
+
+    @classmethod
+    async def from_env_async(
+        cls: type[T],
+        prefix: str = "",
+        delimiter: str = "_",
+        case_sensitive: bool = False,
+        use_async_secrets: bool = True,
+    ) -> T:
+        """
+        Load configuration from environment variables asynchronously.
+
+        Args:
+            prefix: Prefix for all environment variables
+            delimiter: Delimiter between prefix and field name
+            case_sensitive: Whether variable names are case-sensitive
+            use_async_secrets: Whether to use async I/O for file-based secrets
+
+        Returns:
+            Configuration instance
+        """
+        data = {}
+
+        # Collect all async operations
+        async_tasks = {}
+        sync_values = {}
+
+        for attr in fields(cls):
+            # Determine environment variable name
+            env_var = attr.metadata.get("env_var")
+
+            if not env_var:
+                # Build from prefix and field name
+                field_prefix = attr.metadata.get("env_prefix", prefix)
+                field_name = attr.name.upper() if not case_sensitive else attr.name
+
+                if field_prefix:
+                    env_var = f"{field_prefix}{delimiter}{field_name}"
+                else:
+                    env_var = field_name
+
+            # Get value from environment
+            raw_value = os.environ.get(env_var)
+
+            if raw_value is not None:
+                # Check if it's a file-based secret
+                if use_async_secrets and raw_value.startswith("file://"):
+                    # Schedule async read
+                    async_tasks[attr.name] = cls._read_secret_async(raw_value[7:])
+                else:
+                    # Store for sync processing
+                    sync_values[attr.name] = (attr, raw_value)
+
+        # Execute all async reads in parallel
+        if async_tasks:
+            async_results = await asyncio.gather(*async_tasks.values())
+            for field_name, value in zip(
+                async_tasks.keys(), async_results, strict=False
+            ):
+                # Find the attribute
+                attr = next(a for a in fields(cls) if a.name == field_name)
+                sync_values[field_name] = (attr, value)
+
+        # Process all values
+        for field_name, (attr, value) in sync_values.items():
+            # Apply parser if specified
+            parser = attr.metadata.get("env_parser")
+
+            if parser:
+                try:
+                    value = parser(value)
+                except Exception as e:
+                    raise ValueError(f"Failed to parse {env_var}: {e}")
+            else:
+                # Try to infer parser from type
+                value = RuntimeConfig._auto_parse(attr, value)
+
+            data[field_name] = value
+
+        return cls.from_dict(data, source=ConfigSource.ENV)
+
+    @staticmethod
+    async def _read_secret_async(file_path: str) -> str:
+        """Read secret from file asynchronously."""
+        try:
+            if aiofiles:
+                async with aiofiles.open(file_path) as f:
+                    content = await f.read()
+                    return content.strip()
+            else:
+                # Fallback to synchronous read
+                with open(file_path) as f:
+                    content = f.read()
+                    return content.strip()
+        except Exception as e:
+            raise ValueError(f"Failed to read secret from file '{file_path}': {e}")
+
+    @staticmethod
+    def _auto_parse(attr: Any, value: str) -> Any:
+        """
+        Automatically parse value based on field type.
+
+        Args:
+            attr: Field attribute
+            value: String value to parse
+
+        Returns:
+            Parsed value
+        """
+        # Use the utility function from utils.parsing
+        return auto_parse(attr, value)
+
+    def to_env_dict(self, prefix: str = "", delimiter: str = "_") -> dict[str, str]:
+        """
+        Convert configuration to environment variable dictionary.
+
+        Args:
+            prefix: Prefix for all environment variables
+            delimiter: Delimiter between prefix and field name
+
+        Returns:
+            Dictionary of environment variables
+        """
+        env_dict = {}
+
+        for attr in fields(self.__class__):
+            value = getattr(self, attr.name)
+
+            # Skip None values
+            if value is None:
+                continue
+
+            # Determine environment variable name
+            env_var = attr.metadata.get("env_var")
+
+            if not env_var:
+                field_prefix = attr.metadata.get("env_prefix", prefix)
+                field_name = attr.name.upper()
+
+                if field_prefix:
+                    env_var = f"{field_prefix}{delimiter}{field_name}"
+                else:
+                    env_var = field_name
+
+            # Convert value to string
+            if isinstance(value, bool):
+                str_value = "true" if value else "false"
+            elif isinstance(value, list):
+                str_value = ",".join(str(item) for item in value)
+            elif isinstance(value, dict):
+                str_value = ",".join(f"{k}={v}" for k, v in value.items())
+            else:
+                str_value = str(value)
+
+            env_dict[env_var] = str_value
+
+        return env_dict