django-cfg 1.1.82__py3-none-any.whl → 1.2.0__py3-none-any.whl

django_cfg/middleware/README.md

@@ -5,7 +5,6 @@ Custom Django middleware components for Django CFG applications.
 ## 📋 Contents
 
 - [UserActivityMiddleware](#useractivitymiddleware) - User activity tracking
-- [PublicEndpointsMiddleware](#publicendpointsmiddleware) - Ignore invalid JWT tokens on public endpoints
 
 ## UserActivityMiddleware
 
@@ -159,160 +158,3 @@ class MyProjectConfig(DjangoConfig):
 # GET /api/users/?format=json
 # PUT /cfg/newsletter/subscribe/
 ```
-
-## PublicEndpointsMiddleware
-
-Middleware that temporarily removes invalid JWT tokens from public endpoints to prevent authentication errors.
-
-### ✨ Features
-
-- ✅ **Automatic activation** - No configuration needed, works out of the box
-- ✅ **Smart endpoint detection** - Configurable regex patterns for public endpoints
-- ✅ **JWT token detection** - Only processes requests with Bearer tokens
-- ✅ **Temporary removal** - Auth headers are restored after request processing
-- ✅ **Performance optimized** - Compiled regex patterns for fast matching
-- ✅ **Detailed logging** - Debug information for troubleshooting
-- ✅ **Statistics tracking** - Monitor middleware usage and effectiveness
-
-### 🎯 Problem Solved
-
-When a frontend sends an invalid/expired JWT token to a public endpoint (like OTP request), Django's authentication middleware tries to authenticate the user and fails with "User not found" errors, even though the endpoint has `AllowAny` permissions.
-
-This middleware temporarily removes the `Authorization` header for public endpoints, allowing them to work without authentication errors.
-
-### 🚀 Automatic Integration
-
-The middleware is **automatically included** in all Django CFG projects:
-
-```python
-class MyConfig(DjangoConfig):
-    # No configuration needed - PublicEndpointsMiddleware is always active
-    pass
-```
-
-### 🎯 Default Public Endpoints
-
-The middleware protects these endpoints by default:
-
-```python
-DEFAULT_PUBLIC_PATTERNS = [
-    r'^/api/accounts/otp/',           # OTP endpoints (request, verify)
-    r'^/cfg/accounts/otp/',           # CFG OTP endpoints
-    r'^/api/accounts/token/refresh/', # Token refresh
-    r'^/cfg/accounts/token/refresh/', # CFG Token refresh
-    r'^/api/health/',                 # Health check endpoints
-    r'^/cfg/api/health/',             # CFG Health check endpoints
-    r'^/admin/login/',                # Django admin login
-    r'^/api/schema/',                 # API schema endpoints
-    r'^/api/docs/',                   # API documentation
-]
-```
-
-### ⚙️ Custom Configuration
-
-You can customize public endpoint patterns in your Django settings:
-
-```python
-# settings.py (optional)
-PUBLIC_ENDPOINT_PATTERNS = [
-    r'^/api/accounts/otp/',
-    r'^/api/public/',
-    r'^/api/webhooks/',
-    # Add your custom patterns here
-]
-```
-
-### 🔍 How It Works
-
-1. **Request Processing**: Middleware checks if the request path matches public endpoint patterns
-2. **Token Detection**: If a Bearer token is present, it's temporarily removed
-3. **Request Handling**: Django processes the request without authentication
-4. **Token Restoration**: The original Authorization header is restored after processing
-
-### 📊 Statistics
-
-Get middleware statistics for monitoring:
-
-```python
-from django_cfg.middleware import PublicEndpointsMiddleware
-
-# In your view or management command
-middleware = PublicEndpointsMiddleware()
-stats = middleware.get_stats()
-
-print(stats)
-# {
-#     'requests_processed': 1250,
-#     'tokens_ignored': 45,
-#     'public_endpoints_hit': 120,
-#     'public_patterns_count': 9,
-#     'middleware_active': True
-# }
-```
-
-### 🔍 Logging
-
-The middleware logs activity at DEBUG level:
-
-```python
-# settings.py
-LOGGING = {
-    'loggers': {
-        'django_cfg.middleware.public_endpoints': {
-            'level': 'DEBUG',
-            'handlers': ['console'],
-        },
-    },
-}
-```
-
-### 🎛️ Manual Integration
-
-If you need to include the middleware manually (not recommended):
-
-```python
-# settings.py
-MIDDLEWARE = [
-    'django.middleware.security.SecurityMiddleware',
-    'corsheaders.middleware.CorsMiddleware',
-    'django_cfg.middleware.PublicEndpointsMiddleware',  # Add early in stack
-    # ... other middleware
-]
-```
-
-### 🚨 Important Notes
-
-1. **Always Active**: Middleware is included by default in all Django CFG projects
-2. **Performance**: Uses compiled regex patterns for fast endpoint matching
-3. **Safety**: Only removes Authorization headers temporarily, restores them after processing
-4. **Logging**: All actions are logged for debugging and monitoring
-
-### 💡 Usage Examples
-
-The middleware works automatically with no configuration needed:
-
-```python
-# Your DjangoConfig
-class MyProjectConfig(DjangoConfig):
-    # PublicEndpointsMiddleware is automatically active
-    pass
-
-# These requests will work even with invalid tokens:
-# POST /api/accounts/otp/request/ (with expired Bearer token)
-# POST /cfg/accounts/otp/verify/ (with invalid Bearer token)
-# GET /api/health/ (with any Bearer token)
-```
-
-### 🔧 Frontend Integration
-
-Perfect companion to frontend error handling:
-
-```typescript
-// Frontend automatically clears invalid tokens on 401/403
-// Middleware ensures public endpoints work during token cleanup
-const response = await api.requestOTP({
-  identifier: "user@example.com",
-  channel: "email"
-});
-// ✅ Works even if localStorage has invalid token
-```

django_cfg/middleware/__init__.py

@@ -5,9 +5,7 @@ Provides middleware components for Django CFG applications.
 """
 
 from .user_activity import UserActivityMiddleware
-from .public_endpoints import PublicEndpointsMiddleware
 
 __all__ = [
     'UserActivityMiddleware',
-    'PublicEndpointsMiddleware',
 ]

django_cfg/middleware/user_activity.py

@@ -9,12 +9,12 @@ import logging
 from django.utils import timezone
 from django.contrib.auth import get_user_model
 from django.utils.deprecation import MiddlewareMixin
-from django_cfg.modules.base import BaseModule
+from django_cfg.modules.base import BaseCfgModule
 
 logger = logging.getLogger(__name__)
 
 
-class UserActivityMiddleware(MiddlewareMixin, BaseModule):
+class UserActivityMiddleware(MiddlewareMixin, BaseCfgModule):
     """
     Middleware to track user activity via last_login field.
     
@@ -31,7 +31,7 @@ class UserActivityMiddleware(MiddlewareMixin, BaseModule):
     def __init__(self, get_response=None):
         """Initialize the middleware."""
         super().__init__(get_response)
-        BaseModule.__init__(self)
+        BaseCfgModule.__init__(self)
         self.get_response = get_response
         
         # Cache for tracking last update times (in memory)

django_cfg/models/api.py

@@ -0,0 +1,145 @@
+"""
+API Configuration Model
+
+Django REST Framework and API settings with Pydantic 2.
+"""
+
+from typing import Dict, Any, List
+from pydantic import Field, field_validator
+from .base import BaseConfig
+
+
+class APIConfig(BaseConfig):
+    """
+    🌐 API Configuration - REST Framework and API settings
+    
+    Configures Django REST Framework, pagination, throttling,
+    and API documentation settings.
+    """
+    
+    # Pagination settings
+    page_size: int = Field(
+        default=20,
+        ge=1,
+        le=100,
+        description="Default API pagination page size"
+    )
+    
+    max_page_size: int = Field(
+        default=100,
+        ge=1,
+        le=1000,
+        description="Maximum API pagination page size"
+    )
+    
+    # Throttling settings
+    rate_limit_enabled: bool = Field(
+        default=True,
+        description="Enable API rate limiting"
+    )
+    
+    rate_limit_anon: str = Field(
+        default="100/hour",
+        description="Rate limit for anonymous users"
+    )
+    
+    rate_limit_user: str = Field(
+        default="1000/hour", 
+        description="Rate limit for authenticated users"
+    )
+    
+    # Documentation settings
+    docs_enabled: bool = Field(
+        default=True,
+        description="Enable API documentation"
+    )
+    
+    docs_title: str = Field(
+        default="API Documentation",
+        description="API documentation title"
+    )
+    
+    docs_version: str = Field(
+        default="v1",
+        description="API version"
+    )
+    
+    # CORS settings for API
+    api_cors_origins: List[str] = Field(
+        default_factory=list,
+        description="CORS origins specifically for API endpoints"
+    )
+    
+    @field_validator('page_size', 'max_page_size')
+    @classmethod
+    def validate_page_sizes(cls, v: int) -> int:
+        """Validate pagination sizes."""
+        if v <= 0:
+            raise ValueError("Page size must be positive")
+        return v
+    
+    @field_validator('rate_limit_anon', 'rate_limit_user')
+    @classmethod
+    def validate_rate_limits(cls, v: str) -> str:
+        """Validate rate limit format."""
+        import re
+        pattern = r'^\d+/(second|minute|hour|day)$'
+        if not re.match(pattern, v):
+            raise ValueError("Rate limit must be in format: number/(second|minute|hour|day)")
+        return v
+    
+    def to_django_settings(self) -> Dict[str, Any]:
+        """Convert to Django REST Framework settings."""
+        settings = {
+            'REST_FRAMEWORK': {
+                'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',
+                'PAGE_SIZE': self.page_size,
+                'MAX_PAGE_SIZE': self.max_page_size,
+                
+                'DEFAULT_AUTHENTICATION_CLASSES': [
+                    'rest_framework.authentication.SessionAuthentication',
+                    'rest_framework.authentication.TokenAuthentication',
+                    'rest_framework_simplejwt.authentication.JWTAuthentication',
+                ],
+                
+                'DEFAULT_PERMISSION_CLASSES': [
+                    'rest_framework.permissions.IsAuthenticated',
+                ],
+                
+                'DEFAULT_RENDERER_CLASSES': [
+                    'rest_framework.renderers.JSONRenderer',
+                    'rest_framework.renderers.BrowsableAPIRenderer',
+                ],
+                
+                'DEFAULT_FILTER_BACKENDS': [
+                    'django_filters.rest_framework.DjangoFilterBackend',
+                    'rest_framework.filters.OrderingFilter',
+                    'rest_framework.filters.SearchFilter',
+                ],
+            }
+        }
+        
+        # Add throttling if enabled
+        if self.rate_limit_enabled:
+            settings['REST_FRAMEWORK']['DEFAULT_THROTTLE_CLASSES'] = [
+                'rest_framework.throttling.AnonRateThrottle',
+                'rest_framework.throttling.UserRateThrottle',
+            ]
+            settings['REST_FRAMEWORK']['DEFAULT_THROTTLE_RATES'] = {
+                'anon': self.rate_limit_anon,
+                'user': self.rate_limit_user,
+            }
+        
+        # API documentation settings
+        if self.docs_enabled:
+            settings.update({
+                'SPECTACULAR_SETTINGS': {
+                    'TITLE': self.docs_title,
+                    'DESCRIPTION': 'API for Django application',
+                    'VERSION': self.docs_version,
+                    'SERVE_INCLUDE_SCHEMA': False,
+                    'SCHEMA_PATH_PREFIX': '/api/',
+                }
+            })
+        
+        return settings

django_cfg/models/base.py

@@ -0,0 +1,287 @@
+"""
+Base Configuration Model
+
+Foundation for all Django configuration models using Pydantic 2.
+"""
+
+import os
+from pathlib import Path
+from typing import Dict, Any, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from pydantic_settings.sources import DotEnvSettingsSource
+
+
+class ConfigValidationError(Exception):
+    """Configuration validation error with helpful developer messages."""
+    
+    def __init__(self, field: str, value: Any, message: str):
+        self.field = field
+        self.value = value
+        self.message = message
+        super().__init__(f"❌ Config error in '{field}': {message} (got: {value})")
+
+
+class BaseConfig(BaseSettings):
+    """
+    🔥 Base configuration model with amazing developer experience
+    
+    Features:
+    - Automatic .env file detection (.env.dev, .env.prod, etc.)
+    - Nested environment variables with __ delimiter  
+    - Type-safe validation with Pydantic 2
+    - Helpful error messages for developers
+    - Environment-specific configuration
+    """
+    
+    model_config = SettingsConfigDict(
+        # Environment file settings
+        env_file='.env',
+        env_file_encoding='utf-8',
+        env_nested_delimiter='__',
+        case_sensitive=False,
+        
+        # Validation settings
+        validate_assignment=True,
+        validate_default=True,
+        extra='ignore',
+        
+        # Performance settings
+        frozen=False,
+        arbitrary_types_allowed=False,
+        use_enum_values=True,
+    )
+    
+    @classmethod
+    def settings_customise_sources(
+        cls,
+        settings_cls,
+        init_settings,
+        env_settings,
+        dotenv_settings,
+        file_secret_settings,
+    ):
+        """Custom settings sources with automatic env file detection."""
+        env_file = cls._detect_env_file()
+        if env_file:
+            dotenv_settings = DotEnvSettingsSource(
+                settings_cls, 
+                env_file=env_file,
+                env_file_encoding='utf-8'
+            )
+        
+        return (
+            init_settings,
+            env_settings,
+            dotenv_settings,
+            file_secret_settings,
+        )
+
+    def __init__(self, **kwargs):
+        """Initialize with smart .env file detection."""
+        try:
+            super().__init__(**kwargs)
+        except Exception as e:
+            self._handle_validation_error(e)
+            raise
+    
+    @classmethod
+    def _detect_env_file(cls) -> Optional[str]:
+        """
+        🔍 Smart environment file detection
+        
+        Priority order:
+        1. .env.local (local overrides, should be git-ignored)
+        2. .env.dev / .env.development (development)
+        3. .env.prod / .env.production (production)
+        4. config.env.dev / config.env.prod (project-specific)
+        5. .env (fallback)
+        """
+        env_files = [
+            '.env.local',
+            '.env.dev',
+            '.env.development', 
+            '.env.prod',
+            '.env.production',
+            'config.env.dev',
+            'config.env.prod',
+            '.env'
+        ]
+        
+        for env_file in env_files:
+            if Path(env_file).exists():
+                return env_file
+        
+        return None
+    
+    def _show_debug(self) -> bool:
+        """Check if we should show debug info."""
+        return os.getenv('DEBUG', 'false').lower() in ('true', '1', 'yes')
+    
+    def _handle_validation_error(self, error: Exception):
+        """Provide helpful validation error messages for developers."""
+        if hasattr(error, 'errors'):
+            print("❌ Django Configuration Validation Errors:")
+            print("=" * 50)
+            
+            for err in error.errors():
+                field = '.'.join(str(x) for x in err['loc'])
+                message = err['msg']
+                input_val = err.get('input', 'N/A')
+                
+                print(f"🔴 Field: {field}")
+                print(f"   Error: {message}")
+                print(f"   Value: {input_val}")
+                print(f"   💡 Fix: Check your .env file or environment variables")
+                print()
+            
+            print("📚 Documentation: https://django-config-toolkit.readthedocs.io/")
+            print("=" * 50)
+    
+    def to_django_settings(self) -> Dict[str, Any]:
+        """Convert configuration to Django-compatible settings dictionary."""
+        return self.model_dump(exclude_none=True, by_alias=True)
+    
+    def get_field_info(self) -> Dict[str, Dict[str, Any]]:
+        """Get detailed field information for developers."""
+        field_info = {}
+        
+        for field_name, field in self.model_fields.items():
+            field_info[field_name] = {
+                'description': field.description or f"Configuration for {field_name}",
+                'type': str(field.annotation) if hasattr(field, 'annotation') else 'Any',
+                'default': field.default if field.default is not ... else None,
+                'required': field.is_required(),
+                'env_var': field_name.upper(),
+            }
+        
+        return field_info
+    
+    def print_field_help(self):
+        """Print helpful field information for developers."""
+        print(f"📋 {self.__class__.__name__} Configuration Fields:")
+        print("=" * 60)
+        
+        for field_name, info in self.get_field_info().items():
+            current_value = getattr(self, field_name, None)
+            
+            # Hide sensitive values
+            if any(word in field_name.lower() for word in ['secret', 'password', 'key', 'token']):
+                display_value = "***HIDDEN***" if current_value else "Not set"
+            else:
+                display_value = current_value
+            
+            print(f"🔧 {field_name}:")
+            print(f"   📝 {info['description']}")
+            print(f"   🏷️  Type: {info['type']}")
+            print(f"   🌍 Env: {info['env_var']}")
+            print(f"   💾 Current: {display_value}")
+            if info['default'] is not None:
+                print(f"   🎯 Default: {info['default']}")
+            if info['required']:
+                print(f"   ⚠️  Required: Yes")
+            print()
+    
+    @classmethod
+    def create_env_example(cls, filename: str = ".env.example") -> None:
+        """
+        🚀 Create example .env file for developers
+        
+        This generates a complete .env.example file with all fields,
+        descriptions, and example values.
+        """
+        lines = [
+            "# 🚀 Django Configuration Environment Variables",
+            "# Generated by Django Config Toolkit",
+            "# Copy this file to .env and customize your settings",
+            "",
+            f"# === {cls.__name__} Configuration ===",
+            "",
+        ]
+        
+        # Create temporary instance to get field info
+        try:
+            temp_instance = cls()
+            field_info = temp_instance.get_field_info()
+        except:
+            # Fallback if instance creation fails
+            field_info = {}
+            for field_name, field in cls.model_fields.items():
+                field_info[field_name] = {
+                    'description': field.description or f"Configure {field_name}",
+                    'default': field.default if field.default is not ... else None,
+                    'env_var': field_name.upper(),
+                }
+        
+        for field_name, info in field_info.items():
+            # Add description
+            lines.append(f"# {info['description']}")
+            
+            # Generate example value
+            default_val = info.get('default')
+            if default_val is not None:
+                example_value = default_val
+            elif 'secret' in field_name.lower() or 'key' in field_name.lower():
+                example_value = "your-secret-key-change-this-to-something-secure"
+            elif 'password' in field_name.lower():
+                example_value = "your-secure-password"
+            elif 'url' in field_name.lower():
+                if 'database' in field_name.lower():
+                    example_value = "postgresql://user:password@localhost:5432/dbname"
+                elif 'redis' in field_name.lower():
+                    example_value = "redis://localhost:6379/0"
+                else:
+                    example_value = "https://example.com"
+            elif 'debug' in field_name.lower():
+                example_value = "true"
+            elif 'port' in field_name.lower():
+                example_value = "5432"
+            elif 'timeout' in field_name.lower():
+                example_value = "30"
+            else:
+                example_value = "change-me"
+            
+            # Add environment variable
+            lines.append(f"{info['env_var']}={example_value}")
+            lines.append("")
+        
+        # Write file
+        with open(filename, 'w', encoding='utf-8') as f:
+            f.write('\n'.join(lines))
+        
+        print(f"✅ Created example environment file: {filename}")
+        print(f"💡 Copy it to .env and customize your settings!")
+        print(f"📚 More info: https://django-config-toolkit.readthedocs.io/")
+    
+    def validate_for_environment(self, environment: str = "development") -> bool:
+        """
+        🧪 Validate configuration for specific environment
+        
+        Args:
+            environment: Target environment (development/production/testing)
+            
+        Returns:
+            True if configuration is valid for the environment
+        """
+        try:
+            # Perform environment-specific validation
+            if environment == "production":
+                return self._validate_production()
+            elif environment == "development":
+                return self._validate_development()
+            else:
+                return True
+        except Exception as e:
+            print(f"❌ Validation failed for {environment}: {e}")
+            return False
+    
+    def _validate_production(self) -> bool:
+        """Validate production-specific requirements."""
+        # Override in subclasses for specific validation
+        return True
+    
+    def _validate_development(self) -> bool:
+        """Validate development-specific requirements."""
+        # Override in subclasses for specific validation  
+        return True

django_cfg/models/cache.py

@@ -12,10 +12,10 @@ from typing import Dict, Optional, Any, Literal, Union
 from pydantic import BaseModel, Field, field_validator, model_validator
 from urllib.parse import urlparse
 
-from django_cfg.exceptions import CacheError, ValidationError
+from django_cfg.core.exceptions import CacheError, ValidationError
 
 
-class CacheBackend(BaseModel):
+class CacheConfig(BaseModel):
     """
     Type-safe cache backend configuration.
     
@@ -160,7 +160,7 @@ class CacheBackend(BaseModel):
         return v
     
     @model_validator(mode='after')
-    def validate_configuration_consistency(self) -> 'CacheBackend':
+    def validate_configuration_consistency(self) -> 'CacheConfig':
         """Validate cache configuration consistency."""
         # Warn about compression with JSON serializer
         if self.compress and self.serializer == "json":
@@ -336,5 +336,5 @@ class CacheBackend(BaseModel):
 
 # Export all models
 __all__ = [
-    "CacheBackend",
+    "CacheConfig",
 ]