django-cfg 1.3.13__py3-none-any.whl → 1.4.0__py3-none-any.whl

django_cfg/models/infrastructure/database/config.py

@@ -0,0 +1,265 @@
+"""
+Database configuration model for django_cfg.
+
+Type-safe database connection configuration with validation.
+"""
+
+from typing import Dict, List, Optional, Any, Literal
+from pydantic import BaseModel, Field, field_validator, model_validator, PrivateAttr
+
+from . import validators
+from . import converters
+from . import routing
+from .parsers import detect_engine_from_url
+
+
+class DatabaseConfig(BaseModel):
+    """
+    Type-safe database connection configuration.
+
+    Supports both individual connection parameters and connection strings.
+    Automatically validates connection parameters and provides helpful error messages.
+    """
+
+    model_config = {
+        "str_strip_whitespace": True,
+        "validate_assignment": True,
+        "extra": "forbid",  # Prevent typos in field names
+    }
+
+    # Core connection parameters
+    engine: Optional[str] = Field(
+        default=None,
+        description="Django database engine (e.g., 'django.db.backends.postgresql'). If not provided, will be auto-detected from database URL scheme.",
+        min_length=1,
+    )
+
+    name: str = Field(
+        ...,
+        description="Database name or connection string",
+        min_length=1,
+    )
+
+    user: Optional[str] = Field(
+        default=None,
+        description="Database username",
+    )
+
+    password: Optional[str] = Field(
+        default=None,
+        description="Database password",
+        repr=False,  # Don't show in repr for security
+    )
+
+    host: str = Field(
+        default="localhost",
+        description="Database host",
+        min_length=1,
+    )
+
+    port: int = Field(
+        default=5432,
+        description="Database port",
+        ge=1,
+        le=65535,
+    )
+
+    # Connection options
+    connect_timeout: int = Field(
+        default=10,
+        description="Connection timeout in seconds",
+        ge=1,
+        le=300,  # Max 5 minutes
+    )
+
+    sslmode: str = Field(
+        default="prefer",
+        description="SSL mode for connection",
+    )
+
+    # Additional database options
+    options: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="Additional database-specific options",
+    )
+
+    # Database routing configuration
+    apps: List[str] = Field(
+        default_factory=list,
+        description="Django app labels that should use this database",
+    )
+
+    operations: List[Literal["read", "write", "migrate"]] = Field(
+        default_factory=lambda: ["read", "write", "migrate"],
+        description="Allowed operations for this database",
+        min_length=1,
+    )
+
+    migrate_to: Optional[str] = Field(
+        default=None,
+        description="Override database alias for migrations (if different from this database)",
+    )
+
+    routing_description: str = Field(
+        default="",
+        description="Human-readable description of the routing rule",
+    )
+
+    # Internal fields for parsed connection strings
+    _is_connection_string: bool = PrivateAttr(default=False)
+    _parsed_components: Optional[Dict[str, Any]] = PrivateAttr(default=None)
+
+    # Validators
+    @field_validator("engine")
+    @classmethod
+    def validate_engine(cls, v: Optional[str]) -> Optional[str]:
+        """Validate Django database engine format."""
+        return validators.validate_engine(v)
+
+    @field_validator("name")
+    @classmethod
+    def validate_name(cls, v: str) -> str:
+        """Validate database name or parse connection string."""
+        return validators.validate_name(v)
+
+    @field_validator("sslmode")
+    @classmethod
+    def validate_sslmode(cls, v: str) -> str:
+        """Validate SSL mode values."""
+        return validators.validate_sslmode(v)
+
+    @field_validator("apps")
+    @classmethod
+    def validate_apps(cls, v: List[str]) -> List[str]:
+        """Validate app labels format."""
+        return validators.validate_apps(v)
+
+    @field_validator("operations")
+    @classmethod
+    def validate_operations(cls, v: List[str]) -> List[str]:
+        """Validate operations list."""
+        return validators.validate_operations(v)
+
+    @model_validator(mode="before")
+    @classmethod
+    def validate_connection_consistency(cls, values: Dict[str, Any]) -> Dict[str, Any]:
+        """Validate connection parameter consistency and auto-detect engine."""
+        return validators.validate_connection_consistency(values)
+
+    @model_validator(mode="after")
+    def validate_connection_after(self) -> "DatabaseConfig":
+        """Validate connection after model creation."""
+        return validators.validate_connection_after(self)
+
+    # Converters
+    def to_django_config(self) -> Dict[str, Any]:
+        """
+        Convert to Django database configuration format.
+
+        Returns:
+            Django-compatible database configuration dictionary
+
+        Raises:
+            DatabaseError: If configuration cannot be converted
+        """
+        return converters.to_django_config(self)
+
+    # Routing methods
+    def matches_app(self, app_label: str) -> bool:
+        """
+        Check if this database should be used for the given app.
+
+        Args:
+            app_label: Django app label to check
+
+        Returns:
+            True if this database should be used for the app
+        """
+        return routing.matches_app(self, app_label)
+
+    def allows_operation(self, operation: str) -> bool:
+        """
+        Check if this database allows the given operation.
+
+        Args:
+            operation: Operation to check ('read', 'write', 'migrate')
+
+        Returns:
+            True if operation is allowed
+        """
+        return routing.allows_operation(self, operation)
+
+    def get_migration_database(self) -> Optional[str]:
+        """
+        Get the database alias to use for migrations.
+
+        Returns:
+            Database alias for migrations, or None to use this database
+        """
+        return routing.get_migration_database(self)
+
+    def has_routing_rules(self) -> bool:
+        """
+        Check if this database has any routing rules configured.
+
+        Returns:
+            True if apps list is not empty
+        """
+        return routing.has_routing_rules(self)
+
+    def test_connection(self) -> bool:
+        """
+        Test database connection (placeholder for future implementation).
+
+        Returns:
+            True if connection successful, False otherwise
+        """
+        return routing.test_connection(self)
+
+    # Factory methods
+    @classmethod
+    def from_url(
+        cls,
+        url: str,
+        *,
+        apps: Optional[List[str]] = None,
+        operations: Optional[List[Literal["read", "write", "migrate"]]] = None,
+        routing_description: str = "",
+        **kwargs
+    ) -> "DatabaseConfig":
+        """
+        Create DatabaseConfig from URL with automatic engine detection.
+
+        Args:
+            url: Database URL (e.g., 'postgresql://user:pass@host:port/db')
+            apps: Django app labels that should use this database
+            operations: Allowed operations for this database
+            routing_description: Human-readable description of the routing rule
+            **kwargs: Additional parameters to override defaults
+
+        Returns:
+            DatabaseConfig instance with auto-detected engine
+
+        Example:
+            # Simple SQLite database
+            db = DatabaseConfig.from_url("sqlite:///db.sqlite3")
+
+            # PostgreSQL with routing
+            blog_db = DatabaseConfig.from_url(
+                "postgresql://user:pass@localhost:5432/blog",
+                apps=["apps.blog"],
+                routing_description="Blog posts and comments"
+            )
+        """
+        return cls(
+            name=url,
+            apps=apps or [],
+            operations=operations or ["read", "write", "migrate"],
+            routing_description=routing_description,
+            **kwargs
+        )
+
+
+__all__ = [
+    "DatabaseConfig",
+]

django_cfg/models/infrastructure/database/converters.py

@@ -0,0 +1,91 @@
+"""
+Database configuration converters.
+
+Convert DatabaseConfig to Django settings format.
+"""
+
+from typing import Dict, Any
+
+
+def to_django_config(config: "DatabaseConfig") -> Dict[str, Any]:  # type: ignore
+    """
+    Convert DatabaseConfig to Django database configuration format.
+
+    Args:
+        config: DatabaseConfig instance
+
+    Returns:
+        Django-compatible database configuration dictionary
+
+    Raises:
+        DatabaseError: If configuration cannot be converted
+    """
+    try:
+        # Base configuration
+        django_config = {
+            "ENGINE": config.engine,
+            "OPTIONS": {**config.options},
+        }
+
+        # Add database-specific options
+        if config.engine == "django.db.backends.postgresql":
+            # PostgreSQL supports connect_timeout and sslmode
+            django_config["OPTIONS"]["connect_timeout"] = config.connect_timeout
+            django_config["OPTIONS"]["sslmode"] = config.sslmode
+        elif config.engine == "django.db.backends.mysql":
+            # MySQL supports connect_timeout but not sslmode
+            django_config["OPTIONS"]["connect_timeout"] = config.connect_timeout
+        # SQLite doesn't support connect_timeout or sslmode, so we skip them
+
+        # Handle connection string vs individual parameters
+        if config._is_connection_string:
+            # For connection strings, use the full string as NAME
+            django_config["NAME"] = config.name
+
+            # Add parsed components if available
+            if config._parsed_components:
+                parsed = config._parsed_components
+                if parsed.get("database"):
+                    django_config["NAME"] = parsed["database"]
+                if parsed.get("user"):
+                    django_config["USER"] = parsed["user"]
+                if parsed.get("password"):
+                    django_config["PASSWORD"] = parsed["password"]
+                if parsed.get("host"):
+                    django_config["HOST"] = parsed["host"]
+                if parsed.get("port"):
+                    django_config["PORT"] = parsed["port"]
+                if parsed.get("options"):
+                    django_config["OPTIONS"].update(parsed["options"])
+        else:
+            # Individual parameters
+            django_config["NAME"] = config.name
+
+            if config.user:
+                django_config["USER"] = config.user
+
+            if config.password:
+                django_config["PASSWORD"] = config.password
+
+            if config.host:
+                django_config["HOST"] = config.host
+
+            if config.port:
+                django_config["PORT"] = config.port
+
+        return django_config
+
+    except Exception as e:
+        # Import here to avoid circular dependency
+        from django_cfg.core.exceptions import DatabaseError
+
+        raise DatabaseError(
+            f"Failed to convert database configuration: {e}",
+            database_alias=getattr(config, "_alias", "unknown"),
+            context={"config": config.model_dump()}
+        ) from e
+
+
+__all__ = [
+    "to_django_config",
+]

django_cfg/models/infrastructure/database/parsers.py

@@ -0,0 +1,96 @@
+"""
+Database connection string parsers.
+
+Utilities for parsing and detecting database engines from URLs.
+"""
+
+from typing import Dict, Any
+from urllib.parse import urlparse
+
+
+def detect_engine_from_url(url: str) -> str:
+    """
+    Automatically detect Django database engine from URL scheme.
+
+    Args:
+        url: Database URL (e.g., 'postgresql://...', 'sqlite:///...')
+
+    Returns:
+        Django database engine string
+
+    Raises:
+        ValueError: If URL scheme is not supported
+    """
+    if "://" not in url:
+        # Assume SQLite for file paths without scheme
+        return "django.db.backends.sqlite3"
+
+    scheme = url.split("://")[0].lower()
+
+    # Map URL schemes to Django engines
+    scheme_to_engine = {
+        "postgresql": "django.db.backends.postgresql",
+        "postgres": "django.db.backends.postgresql",
+        "mysql": "django.db.backends.mysql",
+        "sqlite": "django.db.backends.sqlite3",
+        "sqlite3": "django.db.backends.sqlite3",
+        "oracle": "django.db.backends.oracle",
+    }
+
+    if scheme in scheme_to_engine:
+        return scheme_to_engine[scheme]
+
+    raise ValueError(
+        f"Unsupported database scheme '{scheme}'. "
+        f"Supported schemes: {', '.join(scheme_to_engine.keys())}"
+    )
+
+
+def parse_connection_string(connection_string: str) -> Dict[str, Any]:
+    """
+    Parse database connection string into components.
+
+    Args:
+        connection_string: Database URL to parse
+
+    Returns:
+        Dictionary with parsed components (scheme, user, password, host, port, database, options)
+
+    Raises:
+        DatabaseError: If connection string cannot be parsed
+    """
+    try:
+        parsed = urlparse(connection_string)
+
+        components = {
+            "scheme": parsed.scheme,
+            "user": parsed.username,
+            "password": parsed.password,
+            "host": parsed.hostname,
+            "port": parsed.port,
+            "database": parsed.path.lstrip("/") if parsed.path else None,
+        }
+
+        # Parse query parameters as options
+        if parsed.query:
+            from urllib.parse import parse_qs
+
+            query_params = parse_qs(parsed.query)
+            components["options"] = {k: v[0] if len(v) == 1 else v for k, v in query_params.items()}
+
+        return components
+
+    except Exception as e:
+        # Import here to avoid circular dependency
+        from django_cfg.core.exceptions import DatabaseError
+
+        raise DatabaseError(
+            f"Failed to parse connection string: {e}",
+            context={"connection_string": connection_string}
+        ) from e
+
+
+__all__ = [
+    "detect_engine_from_url",
+    "parse_connection_string",
+]

django_cfg/models/infrastructure/database/routing.py

@@ -0,0 +1,85 @@
+"""
+Database routing utilities.
+
+Methods for database routing and operation checks.
+"""
+
+from typing import Optional
+
+
+def matches_app(config: "DatabaseConfig", app_label: str) -> bool:  # type: ignore
+    """
+    Check if this database should be used for the given app.
+
+    Args:
+        config: DatabaseConfig instance
+        app_label: Django app label to check
+
+    Returns:
+        True if this database should be used for the app
+    """
+    return app_label in config.apps
+
+
+def allows_operation(config: "DatabaseConfig", operation: str) -> bool:  # type: ignore
+    """
+    Check if this database allows the given operation.
+
+    Args:
+        config: DatabaseConfig instance
+        operation: Operation to check ('read', 'write', 'migrate')
+
+    Returns:
+        True if operation is allowed
+    """
+    return operation in config.operations
+
+
+def get_migration_database(config: "DatabaseConfig") -> Optional[str]:  # type: ignore
+    """
+    Get the database alias to use for migrations.
+
+    Args:
+        config: DatabaseConfig instance
+
+    Returns:
+        Database alias for migrations, or None to use this database
+    """
+    return config.migrate_to
+
+
+def has_routing_rules(config: "DatabaseConfig") -> bool:  # type: ignore
+    """
+    Check if this database has any routing rules configured.
+
+    Args:
+        config: DatabaseConfig instance
+
+    Returns:
+        True if apps list is not empty
+    """
+    return bool(config.apps)
+
+
+def test_connection(config: "DatabaseConfig") -> bool:  # type: ignore
+    """
+    Test database connection (placeholder for future implementation).
+
+    Args:
+        config: DatabaseConfig instance
+
+    Returns:
+        True if connection successful, False otherwise
+    """
+    # TODO: Implement actual connection testing
+    # This would require Django to be available and configured
+    return True
+
+
+__all__ = [
+    "matches_app",
+    "allows_operation",
+    "get_migration_database",
+    "has_routing_rules",
+    "test_connection",
+]

django_cfg/models/infrastructure/database/validators.py

@@ -0,0 +1,170 @@
+"""
+Database configuration validators.
+
+Field validators for DatabaseConfig model.
+"""
+
+from typing import Dict, List, Any, Optional
+from pathlib import Path
+from urllib.parse import urlparse
+
+from .parsers import detect_engine_from_url, parse_connection_string
+
+
+def validate_engine(v: Optional[str]) -> Optional[str]:
+    """Validate Django database engine format."""
+    if v is None:
+        return v
+
+    if not v.startswith("django.db.backends."):
+        raise ValueError(
+            f"Invalid database engine '{v}'. "
+            "Must start with 'django.db.backends.'"
+        )
+
+    # Common engines validation
+    valid_engines = {
+        "django.db.backends.postgresql",
+        "django.db.backends.mysql",
+        "django.db.backends.sqlite3",
+        "django.db.backends.oracle",
+    }
+
+    if v not in valid_engines and not v.startswith("django.db.backends."):
+        # Allow custom backends but warn about common typos
+        common_typos = {
+            "postgresql": "django.db.backends.postgresql",
+            "postgres": "django.db.backends.postgresql",
+            "mysql": "django.db.backends.mysql",
+            "sqlite": "django.db.backends.sqlite3",
+            "sqlite3": "django.db.backends.sqlite3",
+        }
+
+        if v in common_typos:
+            raise ValueError(
+                f"Invalid engine '{v}'. Did you mean '{common_typos[v]}'?"
+            )
+
+    return v
+
+
+def validate_name(v: str) -> str:
+    """Validate database name or parse connection string."""
+    # Check if it's a connection string
+    if "://" in v:
+        try:
+            parsed = urlparse(v)
+            if not parsed.scheme:
+                raise ValueError("Invalid connection string format")
+            return v
+        except Exception as e:
+            raise ValueError(f"Invalid connection string: {e}") from e
+
+    # Regular database name validation
+    if v in [":memory:", ""]:
+        return v  # Special cases for SQLite
+
+    # Check for path-like names (SQLite files)
+    if "/" in v or "\\" in v or v.endswith(".db") or v.endswith(".sqlite3"):
+        path = Path(v)
+        if path.is_absolute() or v.startswith("./") or v.startswith("../"):
+            return v  # Valid file path
+
+    return v
+
+
+def validate_sslmode(v: str) -> str:
+    """Validate SSL mode values."""
+    valid_modes = {"disable", "allow", "prefer", "require", "verify-ca", "verify-full"}
+
+    if v not in valid_modes:
+        raise ValueError(
+            f"Invalid SSL mode '{v}'. "
+            f"Valid options: {', '.join(sorted(valid_modes))}"
+        )
+
+    return v
+
+
+def validate_connection_consistency(values: Dict[str, Any]) -> Dict[str, Any]:
+    """Validate connection parameter consistency and auto-detect engine."""
+    # Auto-detect engine if not provided
+    if values.get("engine") is None and values.get("name"):
+        values["engine"] = detect_engine_from_url(values["name"])
+
+    return values
+
+
+def validate_connection_after(config: "DatabaseConfig") -> "DatabaseConfig":  # type: ignore
+    """Validate connection after model creation."""
+    # Parse connection string if present
+    if "://" in config.name:
+        object.__setattr__(config, '_is_connection_string', True)
+        parsed = parse_connection_string(config.name)
+        object.__setattr__(config, '_parsed_components', parsed)
+
+        # Override individual parameters with parsed values if not explicitly set
+        if parsed and not config.user and parsed.get("user"):
+            object.__setattr__(config, 'user', parsed["user"])
+        if parsed and not config.password and parsed.get("password"):
+            object.__setattr__(config, 'password', parsed["password"])
+        if parsed and config.host == "localhost" and parsed.get("host"):
+            object.__setattr__(config, 'host', parsed["host"])
+        if parsed and config.port == 5432 and parsed.get("port"):
+            object.__setattr__(config, 'port', parsed["port"])
+
+    # Validate SQLite-specific constraints
+    if config.engine == "django.db.backends.sqlite3":
+        if config.name not in [":memory:", ""] and not (
+            config.name.endswith((".db", ".sqlite", ".sqlite3"))
+            or "/" in config.name
+            or "\\" in config.name
+        ):
+            raise ValueError(
+                "SQLite database name must be ':memory:', a file path, "
+                "or end with .db, .sqlite, or .sqlite3"
+            )
+
+    # Validate PostgreSQL-specific constraints
+    elif config.engine == "django.db.backends.postgresql":
+        if not config._is_connection_string and not config.name:
+            raise ValueError("PostgreSQL database name is required")
+
+    return config
+
+
+def validate_apps(v: List[str]) -> List[str]:
+    """Validate app labels format."""
+    for app in v:
+        if not app or not app.replace("_", "").replace(".", "").isalnum():
+            raise ValueError(
+                f"Invalid app label '{app}'. "
+                "App labels must contain only letters, numbers, dots, and underscores"
+            )
+    return v
+
+
+def validate_operations(v: List[str]) -> List[str]:
+    """Validate operations list."""
+    if not v:
+        raise ValueError("At least one operation must be specified")
+
+    valid_ops = {"read", "write", "migrate"}
+    for op in v:
+        if op not in valid_ops:
+            raise ValueError(
+                f"Invalid operation '{op}'. "
+                f"Valid operations: {', '.join(sorted(valid_ops))}"
+            )
+    return v
+
+
+__all__ = [
+    "validate_engine",
+    "validate_name",
+    "validate_sslmode",
+    "validate_connection_consistency",
+    "validate_connection_after",
+    "validate_apps",
+    "validate_operations",
+]