dotenvmodel 0.1.1__py3-none-any.whl

dotenvmodel/fields.py

@@ -0,0 +1,298 @@
+"""Field descriptor and Required sentinel for dotenvmodel."""
+
+import re
+from collections.abc import Callable
+from decimal import Decimal
+from typing import Any, TypeVar
+
+# Type variable for generic field types
+T = TypeVar("T")
+
+
+class _MissingSentinel:
+    """Sentinel to indicate a required field with no default."""
+
+    def __repr__(self) -> str:
+        return "..."
+
+
+_MISSING = _MissingSentinel()
+
+
+class _RequiredSentinel:
+    """Sentinel to indicate a required field (explicit alternative to no default)."""
+
+    def __repr__(self) -> str:
+        return "Required"
+
+
+# Public sentinel value for required fields
+# Type checkers will see this as Any to avoid type errors
+Required: Any = _RequiredSentinel()
+
+
+class FieldInfo:
+    """
+    Information about a configuration field.
+
+    This class holds all metadata about a field including its default value,
+    validation constraints, and documentation.
+    """
+
+    def __init__(
+        self,
+        default: Any = _MISSING,
+        *,
+        default_factory: Callable[[], Any] | None = None,
+        alias: str | None = None,
+        description: str | None = None,
+        # Numeric validation
+        ge: int | float | None = None,
+        le: int | float | None = None,
+        gt: int | float | None = None,
+        lt: int | float | None = None,
+        # String validation
+        min_length: int | None = None,
+        max_length: int | None = None,
+        regex: str | None = None,
+        # General validation
+        choices: list[Any] | None = None,
+        # Collection validation
+        min_items: int | None = None,
+        max_items: int | None = None,
+        # UUID validation
+        uuid_version: int | None = None,
+        # Collection parsing
+        separator: str = ",",
+        # SecretStr options
+        url_unquote: bool = True,
+    ) -> None:
+        # Validate that only one default mechanism is used
+        if default is not _MISSING and default is not ... and default_factory is not None:
+            raise ValueError("Cannot specify both 'default' and 'default_factory'")
+
+        # Treat ellipsis as _MISSING (Pydantic-style required indicator)
+        if default is ...:
+            default = _MISSING
+
+        # Validate numeric constraint types
+        for param_name, param_value in [("ge", ge), ("le", le), ("gt", gt), ("lt", lt)]:
+            if param_value is not None and not isinstance(param_value, (int, float, Decimal)):
+                raise TypeError(
+                    f"{param_name} must be int, float, or Decimal, got {type(param_value).__name__}"
+                )
+
+        # Validate length/size constraint types
+        for param_name, param_value in [
+            ("min_length", min_length),
+            ("max_length", max_length),
+            ("min_items", min_items),
+            ("max_items", max_items),
+        ]:
+            if param_value is not None and (not isinstance(param_value, int) or param_value < 0):
+                raise ValueError(
+                    f"{param_name} must be a non-negative integer, got {param_value!r}"
+                )
+
+        # Validate UUID version
+        if uuid_version is not None and uuid_version not in (1, 3, 4, 5):
+            raise ValueError(f"uuid_version must be 1, 3, 4, or 5, got {uuid_version}")
+
+        # Validate contradictory constraints
+        if ge is not None and le is not None and ge > le:
+            raise ValueError(f"ge ({ge}) cannot be greater than le ({le})")
+        if gt is not None and lt is not None and gt >= lt:
+            raise ValueError(f"gt ({gt}) must be less than lt ({lt})")
+        if min_length is not None and max_length is not None and min_length > max_length:
+            raise ValueError(
+                f"min_length ({min_length}) cannot be greater than max_length ({max_length})"
+            )
+        if min_items is not None and max_items is not None and min_items > max_items:
+            raise ValueError(
+                f"min_items ({min_items}) cannot be greater than max_items ({max_items})"
+            )
+
+        self.default = default
+        self.default_factory = default_factory
+        self.alias = alias
+        self.description = description
+
+        # Numeric constraints
+        self.ge = ge
+        self.le = le
+        self.gt = gt
+        self.lt = lt
+
+        # String constraints
+        self.min_length = min_length
+        self.max_length = max_length
+        self.regex = regex
+        # Compile regex pattern with error handling
+        if regex:
+            try:
+                self._compiled_regex = re.compile(regex)
+            except re.error as e:
+                raise ValueError(f"Invalid regex pattern: {regex!r} - {e}") from e
+        else:
+            self._compiled_regex = None
+
+        # General constraints
+        self.choices = choices
+
+        # Collection constraints
+        self.min_items = min_items
+        self.max_items = max_items
+
+        # UUID constraints
+        self.uuid_version = uuid_version
+
+        # Collection parsing
+        self.separator = separator
+
+        # SecretStr options
+        self.url_unquote = url_unquote
+
+        # Mark if field is required
+        self.required = default is _MISSING and default_factory is None
+
+    def get_default(self) -> Any:
+        """Get the default value for this field."""
+        if self.default_factory is not None:
+            return self.default_factory()
+        if self.default is _MISSING:
+            return _MISSING
+        return self.default
+
+    @property
+    def has_default(self) -> bool:
+        """Check if this field has a default value."""
+        return not self.required
+
+    def __repr__(self) -> str:
+        parts = []
+        if self.default is not _MISSING:
+            parts.append(f"default={self.default!r}")
+        if self.default_factory is not None:
+            parts.append(f"default_factory={self.default_factory!r}")
+        if self.alias:
+            parts.append(f"alias={self.alias!r}")
+        if self.description:
+            parts.append(f"description={self.description!r}")
+
+        # Add constraints
+        if self.ge is not None:
+            parts.append(f"ge={self.ge}")
+        if self.le is not None:
+            parts.append(f"le={self.le}")
+        if self.gt is not None:
+            parts.append(f"gt={self.gt}")
+        if self.lt is not None:
+            parts.append(f"lt={self.lt}")
+        if self.min_length is not None:
+            parts.append(f"min_length={self.min_length}")
+        if self.max_length is not None:
+            parts.append(f"max_length={self.max_length}")
+        if self.regex is not None:
+            parts.append(f"regex={self.regex!r}")
+        if self.choices is not None:
+            parts.append(f"choices={self.choices!r}")
+        if self.min_items is not None:
+            parts.append(f"min_items={self.min_items}")
+        if self.max_items is not None:
+            parts.append(f"max_items={self.max_items}")
+        if self.uuid_version is not None:
+            parts.append(f"uuid_version={self.uuid_version}")
+        if self.separator != ",":  # Only show if non-default
+            parts.append(f"separator={self.separator!r}")
+
+        return f"FieldInfo({', '.join(parts)})"
+
+
+def Field(
+    default: Any = _MISSING,
+    *,
+    default_factory: Callable[[], Any] | None = None,
+    alias: str | None = None,
+    description: str | None = None,
+    ge: int | float | None = None,
+    le: int | float | None = None,
+    gt: int | float | None = None,
+    lt: int | float | None = None,
+    min_length: int | None = None,
+    max_length: int | None = None,
+    regex: str | None = None,
+    choices: list[Any] | None = None,
+    min_items: int | None = None,
+    max_items: int | None = None,
+    uuid_version: int | None = None,
+    separator: str = ",",
+    url_unquote: bool = True,
+) -> Any:
+    """
+    Define a configuration field with validation and default values.
+
+    Args:
+        default: Default value if environment variable not set
+        default_factory: Callable that returns default value (for mutable defaults)
+        alias: Alternative environment variable name to read from
+        description: Human-readable description for documentation
+        ge: Greater than or equal to (>=)
+        le: Less than or equal to (<=)
+        gt: Greater than (>)
+        lt: Less than (<)
+        min_length: Minimum string length
+        max_length: Maximum string length
+        regex: Regular expression pattern to match
+        choices: List of allowed values
+        min_items: Minimum number of items in collection (list, set, tuple, dict)
+        max_items: Maximum number of items in collection (list, set, tuple, dict)
+        uuid_version: Required UUID version (1, 3, 4, or 5)
+        separator: Separator for list/set/tuple parsing (default: ",")
+
+    Returns:
+        FieldInfo instance containing field metadata
+
+    Example:
+        ```python
+        class Config(DotEnvConfig):
+            # Required field (no default)
+            database_url: str = Field()
+
+            # Optional with default
+            debug: bool = Field(default=False)
+
+            # With validation
+            port: int = Field(default=8000, ge=1, le=65535)
+
+            # With alias
+            postgres_dsn: str = Field(alias="DATABASE_URL")
+
+            # List with custom separator
+            tags: list[str] = Field(default_factory=list, separator=";")
+
+            # Collection size constraints
+            allowed_ips: list[str] = Field(min_items=1, max_items=10)
+
+            # UUID version constraint
+            tenant_id: UUID = Field(uuid_version=4)
+        ```
+    """
+    return FieldInfo(
+        default=default,
+        default_factory=default_factory,
+        alias=alias,
+        description=description,
+        ge=ge,
+        le=le,
+        gt=gt,
+        lt=lt,
+        min_length=min_length,
+        max_length=max_length,
+        regex=regex,
+        choices=choices,
+        min_items=min_items,
+        max_items=max_items,
+        uuid_version=uuid_version,
+        separator=separator,
+        url_unquote=url_unquote,
+    )

dotenvmodel/loading.py

@@ -0,0 +1,145 @@
+"""Environment variable and .env file loading logic."""
+
+import logging
+import os
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+# Module-level logger
+logger = logging.getLogger("dotenvmodel")
+
+
+def load_env_files(
+    env: str | None = None,
+    *,
+    override: bool = True,
+    env_dir: Path | None = None,
+) -> dict[str, str]:
+    """
+    Load environment variables from cascading .env files.
+
+    This function implements Node.js-style .env file cascading, loading files
+    in the following order (later files override earlier):
+    1. .env (base configuration)
+    2. .env.local (local base overrides)
+    3. .env.{env} (environment-specific)
+    4. .env.{env}.local (local environment overrides)
+
+    Args:
+        env: Environment name (e.g., "dev", "prod", "test"). If None, reads from
+            ENV environment variable, defaults to "dev"
+        override: If True, .env file values override existing environment variables.
+            If False, existing env vars take precedence
+        env_dir: Optional custom base directory for .env files. If None, uses
+            DOTENV_DIR environment variable or current working directory
+
+    Returns:
+        Dictionary of all environment variables after loading
+
+    Example:
+        >>> load_env_files(env="dev", override=True)
+        {'DATABASE_URL': 'postgresql://localhost/myapp_dev', ...}
+    """
+    # Determine environment
+    if env is None:
+        env = os.getenv("ENV", "dev")
+
+    # Validate env parameter to prevent path traversal attacks
+    # Only allow alphanumeric characters, hyphens, and underscores
+    if not env or not all(c.isalnum() or c in ("-", "_") for c in env):
+        raise ValueError(
+            f"Invalid environment name: {env!r}. "
+            "Environment names must only contain alphanumeric characters, hyphens, and underscores."
+        )
+
+    logger.info(f"Loading configuration for environment: {env}")
+
+    # Determine base directory
+    if env_dir is None:
+        env_dir_str = os.getenv("DOTENV_DIR")
+        base_dir = Path(env_dir_str) if env_dir_str else Path.cwd()
+    else:
+        base_dir = env_dir
+
+    logger.debug(f"Base directory for .env files: {base_dir}")
+
+    # Validate base directory exists
+    if not base_dir.exists():
+        logger.error(f"Environment file directory does not exist: {base_dir}")
+        raise FileNotFoundError(f"Environment file directory does not exist: {base_dir}")
+
+    # Define file loading order
+    env_files = [
+        base_dir / ".env",  # Base shared configuration
+        base_dir / ".env.local",  # Local base overrides
+        base_dir / f".env.{env}",  # Environment-specific config
+        base_dir / f".env.{env}.local",  # Local environment overrides
+    ]
+
+    logger.debug(f"Searching for .env files in order: {[str(f) for f in env_files]}")
+
+    # Load each file in order
+    loaded_files = []
+    missing_files = []
+
+    for file_path in env_files:
+        if file_path.exists():
+            logger.info(f"Loading environment variables from {file_path}")
+            load_dotenv(file_path, override=override)
+            loaded_files.append(str(file_path))
+        else:
+            logger.debug(f"{file_path} not found (skipping)")
+            missing_files.append(str(file_path))
+
+    if loaded_files:
+        logger.info(f"Successfully loaded {len(loaded_files)} file(s): {', '.join(loaded_files)}")
+    else:
+        logger.warning(f"No .env files found in {base_dir}")
+
+    # Return all current environment variables
+    return dict(os.environ)
+
+
+def get_env_var(field_name: str, alias: str | None = None, prefix: str | None = None) -> str | None:
+    """
+    Get environment variable value by field name or alias.
+
+    Args:
+        field_name: Name of the field
+        alias: Optional alias for the environment variable
+        prefix: Optional prefix to prepend to the environment variable name
+
+    Returns:
+        Environment variable value or None if not set
+    """
+    # Use alias if provided, otherwise convert field_name to UPPER_CASE
+    env_var_name = alias if alias else field_name.upper()
+
+    # Prepend prefix if provided (and alias is not used, since alias is absolute)
+    if prefix and not alias:
+        env_var_name = f"{prefix}{env_var_name}"
+
+    return os.getenv(env_var_name)
+
+
+def get_env_var_name(field_name: str, alias: str | None = None, prefix: str | None = None) -> str:
+    """
+    Get the environment variable name for a field.
+
+    Args:
+        field_name: Name of the field
+        alias: Optional alias for the environment variable
+        prefix: Optional prefix to prepend to the environment variable name
+
+    Returns:
+        Environment variable name
+    """
+    # Use alias if provided, otherwise convert field_name to UPPER_CASE
+    env_var_name = alias if alias else field_name.upper()
+
+    # Prepend prefix if provided (and alias is not used, since alias is absolute)
+    if prefix and not alias:
+        env_var_name = f"{prefix}{env_var_name}"
+
+    return env_var_name

dotenvmodel/logging_config.py

@@ -0,0 +1,92 @@
+"""Logging configuration utilities for dotenvmodel."""
+
+import logging
+import os
+import sys
+
+
+def configure_logging(
+    level: str | int | None = None,
+    *,
+    format_string: str | None = None,
+    handler: logging.Handler | None = None,
+) -> None:
+    """
+    Configure logging for dotenvmodel.
+
+    This is a convenience function to quickly enable dotenvmodel logging.
+    For more control, configure the 'dotenvmodel' logger directly using
+    the standard logging module.
+
+    Args:
+        level: Logging level. Can be a string ("DEBUG", "INFO", "WARNING", "ERROR")
+            or an int (logging.DEBUG, etc.). If None, reads from DOTENVMODEL_LOG_LEVEL
+            environment variable, defaults to WARNING.
+        format_string: Custom format string for log messages. If None, uses a
+            default format with timestamp, level, and message.
+        handler: Custom logging handler. If None, uses StreamHandler (stdout).
+
+    Example:
+        ```python
+        from dotenvmodel.logging_config import configure_logging
+
+        # Enable INFO level logging
+        configure_logging("INFO")
+
+        # Or use DEBUG for more verbose output
+        configure_logging("DEBUG")
+
+        # Custom format
+        configure_logging(
+            "DEBUG",
+            format_string="[%(levelname)s] %(message)s"
+        )
+        ```
+    """
+    # Determine log level
+    if level is None:
+        env_level = os.getenv("DOTENVMODEL_LOG_LEVEL", "WARNING").upper()
+        level = getattr(logging, env_level, logging.WARNING)
+    elif isinstance(level, str):
+        level = getattr(logging, level.upper(), logging.WARNING)
+
+    # Get the dotenvmodel logger
+    logger = logging.getLogger("dotenvmodel")
+    logger.setLevel(level)
+
+    # Remove existing handlers to avoid duplicates
+    logger.handlers.clear()
+
+    # Create handler
+    if handler is None:
+        handler = logging.StreamHandler(sys.stdout)
+
+    # Set format
+    if format_string is None:
+        format_string = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+
+    formatter = logging.Formatter(format_string)
+    handler.setFormatter(formatter)
+
+    # Add handler to logger
+    logger.addHandler(handler)
+
+    # Prevent propagation to root logger to avoid duplicate logs
+    logger.propagate = False
+
+
+def disable_logging() -> None:
+    """
+    Disable all dotenvmodel logging.
+
+    Example:
+        ```python
+        from dotenvmodel.logging_config import disable_logging
+
+        disable_logging()
+        ```
+    """
+    logger = logging.getLogger("dotenvmodel")
+    logger.setLevel(logging.CRITICAL + 1)  # Above CRITICAL
+    logger.handlers.clear()
+    logger.propagate = False