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

django_cfg/modules/django_logging/LOGGING_GUIDE.md

@@ -0,0 +1,504 @@
+# Django CFG Logging Strategy Guide
+
+## Overview
+
+Django CFG uses a sophisticated logging system that automatically adjusts based on the `debug` configuration setting. This guide explains the logging architecture, how to control logging output, and best practices.
+
+## Core Principles
+
+### 1. Debug-Aware Logging
+
+Logging verbosity is controlled by the `config.debug` setting:
+
+```python
+# config.py
+debug: bool = False  # Production
+debug: bool = True   # Development
+```
+
+**Log Levels by Mode:**
+
+| Mode | Level | What You See |
+|------|-------|--------------|
+| `debug=True` | DEBUG | Everything: DEBUG, INFO, WARNING, ERROR, CRITICAL |
+| `debug=False` | WARNING | Only important: WARNING, ERROR, CRITICAL |
+
+**Why This Matters:**
+- **Production** (`debug=False`): Clean logs, only warnings and errors → easier monitoring
+- **Development** (`debug=True`): Verbose logs → easier debugging
+
+### 2. Modular File Structure
+
+Logs are organized by module for easy troubleshooting:
+
+```
+logs/
+├── django.log                    # All Django logs (root logger)
+└── djangocfg/
+    ├── core.log                  # Core django_cfg functionality
+    ├── apps.log                  # Apps (payments, agents, etc.)
+    ├── models.log                # Data models
+    └── modules.log               # Modules (logging, tasks, etc.)
+```
+
+**Automatic Module Detection:**
+The logging system automatically routes logs based on the logger name:
+- `django_cfg.core.*` → `core.log`
+- `django_cfg.apps.payments.*` → `apps.log`
+- `django_cfg.modules.*` → `modules.log`
+
+### 3. Dual Handler System
+
+Each django-cfg logger has TWO handlers:
+
+1. **Console Handler** (stdout/stderr)
+   - Uses Rich formatting for pretty output
+   - Respects debug level
+   - Shows in terminal during development
+
+2. **File Handler** (modular)
+   - Plain text format for parsing
+   - Module-specific files
+   - Persists for analysis
+
+## Configuration
+
+### YAML Configuration
+
+```yaml
+# config.dev.yaml
+debug: true  # Verbose logging
+
+# config.prod.yaml
+debug: false  # Only warnings/errors
+```
+
+### Environment Variable Fallback
+
+If config is not available, uses `DEBUG` environment variable:
+
+```bash
+DEBUG=true python manage.py runserver  # Verbose
+DEBUG=false python manage.py runserver # Quiet
+```
+
+## Usage Examples
+
+### Basic Logging
+
+```python
+from django_cfg.modules.django_logging import get_logger
+
+logger = get_logger(__name__)
+
+# These only show when debug=True:
+logger.debug("Detailed debugging information")
+logger.info("General informational message")
+
+# These ALWAYS show:
+logger.warning("Something unexpected happened")
+logger.error("An error occurred")
+logger.critical("Critical system failure")
+```
+
+### Auto-Detected Module Names
+
+The `get_logger()` function automatically detects the module:
+
+```python
+# In: /django_cfg/apps/payments/services/provider.py
+logger = get_logger()  # Auto-detects as 'django_cfg.apps.payments'
+
+# Manual override:
+logger = get_logger('django_cfg.custom_module')
+```
+
+### Rich Console Output
+
+When `debug=True`, you get beautifully formatted console output:
+
+```
+[10/02/25 17:52:00] INFO     🚀 Generated DRF settings
+                    INFO     ✅ Dramatiq enabled with 7 queues
+```
+
+When `debug=False`, console is silent except for warnings/errors.
+
+## Logger Types
+
+### 1. Django Logger (`django_logger.py`)
+
+**NEW Simple Auto-Configuring Logger**
+
+```python
+from django_cfg.modules.django_logging.django_logger import get_logger
+
+logger = get_logger(__name__)
+logger.info("This message respects debug mode")
+```
+
+**Features:**
+- Automatically respects `config.debug`
+- Modular file output
+- Single source of truth for all django-cfg logging
+
+**When to Use:** For all new django-cfg code (PREFERRED)
+
+### 2. Legacy Rich Logger (`logger.py`)
+
+**OLD Rich-Formatted Logger**
+
+```python
+from django_cfg.modules.django_logging.logger import DjangoCfgLogger
+
+logger = DjangoCfgLogger()
+logger.info("Rich formatted message")
+```
+
+**Features:**
+- Fancy Rich console formatting
+- NOW respects `config.debug` (recently fixed)
+- Used in older code
+
+**When to Use:** Existing code that hasn't been migrated yet
+
+## How Debug Control Works
+
+### Architecture Flow
+
+```
+┌─────────────────────────────────────────────────────┐
+│ 1. config.debug = False                            │
+│    (Set in config.dev.yaml / config.prod.yaml)     │
+└────────────────────┬────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────┐
+│ 2. Logger Setup Detects Debug Mode                 │
+│    - Checks config.debug first                     │
+│    - Falls back to DEBUG env var                   │
+└────────────────────┬────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────┐
+│ 3. Sets Log Level Based on Debug                   │
+│    - debug=True  → logging.DEBUG (all messages)    │
+│    - debug=False → logging.WARNING (warn+ only)    │
+└────────────────────┬────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────┐
+│ 4. Configures Handlers                             │
+│    - Console Handler: level = log_level            │
+│    - File Handler: level = log_level               │
+│    - Both respect the same level                   │
+└────────────────────┬────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────┐
+│ 5. Runtime Filtering                               │
+│    - logger.info() → Filtered out if debug=False   │
+│    - logger.warning() → Always passes through       │
+└─────────────────────────────────────────────────────┘
+```
+
+## Code Examples
+
+### Example 1: Simple Usage
+
+```python
+from django_cfg.modules.django_logging import get_logger
+
+logger = get_logger(__name__)
+
+def process_payment(amount: float):
+    logger.debug(f"Processing payment: ${amount}")  # Only in debug
+
+    try:
+        result = payment_gateway.charge(amount)
+        logger.info(f"Payment processed: {result.id}")  # Only in debug
+        return result
+    except PaymentError as e:
+        logger.error(f"Payment failed: {e}")  # Always shown
+        raise
+```
+
+### Example 2: Module-Specific Logging
+
+```python
+# File: django_cfg/apps/payments/services/nowpayments.py
+from django_cfg.modules.django_logging import get_logger
+
+# Auto-detects as 'django_cfg.apps.payments'
+logger = get_logger()
+
+class NowPaymentsProvider:
+    def __init__(self, api_key: str):
+        logger.debug(f"Initializing NowPayments: {api_key[:10]}...")
+        # Logs to: logs/djangocfg/apps.log
+```
+
+### Example 3: Conditional Debug Code
+
+```python
+from django_cfg.core.state import get_current_config
+
+config = get_current_config()
+
+if config and config.debug:
+    # Expensive operation only in debug mode
+    from django_cfg.dashboard.debug import save_section_render
+    save_section_render('overview', html_content)
+else:
+    # Skip debug rendering in production
+    pass
+```
+
+## Troubleshooting
+
+### Issue: Still Seeing INFO Logs When debug=False
+
+**Possible Causes:**
+
+1. **Server not restarted** after changing config
+   ```bash
+   # Solution: Restart server
+   python manage.py runserver
+   ```
+
+2. **Wrong config file loaded**
+   ```bash
+   # Check which config is loaded
+   Loading config file: config.dev.ignore.yaml
+   [django-cfg] Modular logging configured successfully! Debug: False
+   ```
+
+3. **Using wrong logger**
+   ```python
+   # ❌ BAD: Standard logging (doesn't respect config)
+   import logging
+   logger = logging.getLogger(__name__)
+
+   # ✅ GOOD: Django CFG logger (respects config)
+   from django_cfg.modules.django_logging import get_logger
+   logger = get_logger(__name__)
+   ```
+
+### Issue: Logs Not Going to Files
+
+**Check:**
+
+1. **Directory permissions**
+   ```bash
+   ls -la logs/
+   # Should be writable
+   ```
+
+2. **Logger name prefix**
+   ```python
+   # Only 'django_cfg.*' loggers get modular files
+   logger = get_logger('django_cfg.my_module')  # ✅ Gets file
+   logger = get_logger('my_module')             # ❌ Console only
+   ```
+
+### Issue: No Console Output at All
+
+**Check debug status:**
+
+```python
+from django_cfg.core.state import get_current_config
+
+config = get_current_config()
+print(f"Debug: {config.debug}")
+
+# Expected output:
+# debug=True  → You'll see INFO, DEBUG, WARNING, ERROR
+# debug=False → You'll ONLY see WARNING, ERROR, CRITICAL
+```
+
+## Best Practices
+
+### 1. Use Appropriate Log Levels
+
+```python
+# DEBUG: Detailed diagnostic info
+logger.debug(f"SQL query: {query}")
+logger.debug(f"Function called with args: {args}")
+
+# INFO: Confirmation of expected behavior
+logger.info(f"User {user.id} logged in successfully")
+logger.info(f"Payment processor initialized")
+
+# WARNING: Something unexpected but handled
+logger.warning(f"API rate limit approaching: {count}/1000")
+logger.warning(f"Deprecated function called: {func.__name__}")
+
+# ERROR: Actual errors that need attention
+logger.error(f"Payment failed: {error}")
+logger.error(f"Database connection lost")
+
+# CRITICAL: System-level failures
+logger.critical(f"Redis connection failed - cache disabled")
+logger.critical(f"Unable to load configuration")
+```
+
+### 2. Structured Logging for Production
+
+```python
+# Include context for easier troubleshooting
+logger.error(
+    f"Payment processing failed",
+    extra={
+        'user_id': user.id,
+        'amount': amount,
+        'provider': 'nowpayments',
+        'error_code': error.code
+    }
+)
+```
+
+### 3. Performance Considerations
+
+```python
+# ❌ BAD: Expensive operation always runs
+debug_data = expensive_debug_operation()
+logger.debug(f"Debug data: {debug_data}")
+
+# ✅ GOOD: Only run when needed
+if logger.isEnabledFor(logging.DEBUG):
+    debug_data = expensive_debug_operation()
+    logger.debug(f"Debug data: {debug_data}")
+
+# ✅ BETTER: Check config directly
+config = get_current_config()
+if config and config.debug:
+    debug_data = expensive_debug_operation()
+    logger.debug(f"Debug data: {debug_data}")
+```
+
+### 4. Migration from Old Logging
+
+**Before (using standard logging):**
+```python
+import logging
+logger = logging.getLogger(__name__)
+
+logger.info("This always shows")  # Problem!
+```
+
+**After (using django-cfg logging):**
+```python
+from django_cfg.modules.django_logging import get_logger
+
+logger = get_logger(__name__)
+logger.info("This respects debug mode")  # Better!
+```
+
+## Quick Reference
+
+### Log Levels Cheat Sheet
+
+| Level | Numeric | When to Use | Shows in Production? |
+|-------|---------|-------------|---------------------|
+| DEBUG | 10 | Diagnostic details | ❌ No |
+| INFO | 20 | Confirmation messages | ❌ No |
+| WARNING | 30 | Unexpected but handled | ✅ Yes |
+| ERROR | 40 | Errors requiring attention | ✅ Yes |
+| CRITICAL | 50 | System-level failures | ✅ Yes |
+
+### Configuration Quick Check
+
+```python
+# In Python shell
+from django_cfg.core.state import get_current_config
+
+config = get_current_config()
+print(f"Debug mode: {config.debug}")
+print(f"Environment: {config.env_mode}")
+
+# Expected for production:
+# Debug mode: False
+# Environment: production
+```
+
+### File Location Quick Reference
+
+```bash
+# View recent logs
+tail -f logs/django.log                    # All logs
+tail -f logs/djangocfg/apps.log           # App-specific
+tail -f logs/djangocfg/core.log           # Core functionality
+
+# Search for errors
+grep ERROR logs/django.log
+grep CRITICAL logs/djangocfg/*.log
+```
+
+## Advanced Topics
+
+### Custom Log Formatting
+
+```python
+from django_cfg.modules.django_logging import get_logger
+import logging
+
+logger = get_logger(__name__)
+
+# Add custom formatter
+handler = logging.FileHandler('custom.log')
+formatter = logging.Formatter(
+    '%(asctime)s [%(levelname)s] %(name)s: %(message)s'
+)
+handler.setFormatter(formatter)
+logger.addHandler(handler)
+```
+
+### Logging in Async Code
+
+```python
+import asyncio
+from django_cfg.modules.django_logging import get_logger
+
+logger = get_logger(__name__)
+
+async def async_task():
+    logger.debug("Starting async task")
+    await asyncio.sleep(1)
+    logger.info("Async task completed")
+```
+
+### Integration with External Services
+
+```python
+from django_cfg.modules.django_logging import get_logger
+import sentry_sdk
+
+logger = get_logger(__name__)
+
+def process_with_sentry():
+    try:
+        result = risky_operation()
+        logger.info(f"Operation succeeded: {result}")
+    except Exception as e:
+        logger.error(f"Operation failed: {e}")
+        sentry_sdk.capture_exception(e)
+        raise
+```
+
+## Summary
+
+The Django CFG logging system provides:
+
+✅ **Automatic debug-aware logging** - Respects `config.debug`
+✅ **Modular file organization** - Easy to find relevant logs
+✅ **Rich console formatting** - Beautiful development experience
+✅ **Production-ready** - Clean, parseable logs in production
+✅ **Easy migration** - Simple `get_logger()` function
+
+**Remember:** When `debug=False`, only WARNING, ERROR, and CRITICAL messages appear. This keeps production logs clean and focused on what matters.
+
+---
+
+**Last Updated:** 2025-10-03
+**Django CFG Version:** 1.3.13
+**Python Version:** 3.10+

django_cfg/modules/django_logging/__init__.py

@@ -0,0 +1,14 @@
+"""
+Django Logging Modules for django_cfg.
+
+Auto-configuring logging utilities.
+"""
+
+from .logger import logger
+from .django_logger import DjangoLogger, get_logger
+
+__all__ = [
+    "logger",
+    "DjangoLogger",
+    "get_logger",
+]

django_cfg/modules/{django_logger.py → django_logging/django_logger.py}

@@ -8,8 +8,8 @@ import logging
 from pathlib import Path
 from typing import Dict, Optional
 
-from . import BaseCfgModule
-from ..utils.smart_defaults import get_log_filename
+from ..base import BaseCfgModule
+from ...utils.smart_defaults import get_log_filename
 
 
 class DjangoLogger(BaseCfgModule):
@@ -46,7 +46,7 @@ class DjangoLogger(BaseCfgModule):
         
         # Get debug mode
         try:
-            from django_cfg.core.config import get_current_config
+            from django_cfg.core.state import get_current_config
             config = get_current_config()
             debug = config.debug if config else False
         except Exception:
@@ -57,20 +57,20 @@ class DjangoLogger(BaseCfgModule):
             # Handler for general Django logs
             django_log_path = logs_dir / 'django.log'
             django_handler = logging.FileHandler(django_log_path, encoding='utf-8')
-            django_handler.setLevel(logging.DEBUG if debug else logging.INFO)
-            
+            django_handler.setLevel(logging.DEBUG if debug else logging.WARNING)
+
             # Console handler
             console_handler = logging.StreamHandler()
-            console_handler.setLevel(logging.DEBUG if debug else logging.INFO)
-            
+            console_handler.setLevel(logging.DEBUG if debug else logging.WARNING)
+
             # Set format for handlers
             formatter = logging.Formatter('[%(asctime)s] %(levelname)s in %(name)s [%(filename)s:%(lineno)d]: %(message)s')
             django_handler.setFormatter(formatter)
             console_handler.setFormatter(formatter)
-            
+
             # Configure root logger
             root_logger = logging.getLogger()
-            root_logger.setLevel(logging.DEBUG if debug else logging.INFO)
+            root_logger.setLevel(logging.DEBUG if debug else logging.WARNING)
             
             # Clear existing handlers
             root_logger.handlers.clear()
@@ -86,7 +86,7 @@ class DjangoLogger(BaseCfgModule):
             print(f"[django-cfg] ERROR setting up modular logging: {e}")
             # Fallback to console only
             logging.basicConfig(
-                level=logging.DEBUG if debug else logging.INFO,
+                level=logging.DEBUG if debug else logging.WARNING,
                 format='[%(asctime)s] %(levelname)s in %(name)s [%(filename)s:%(lineno)d]: %(message)s',
                 handlers=[logging.StreamHandler()],
                 force=True
@@ -123,13 +123,13 @@ class DjangoLogger(BaseCfgModule):
                 
                 # Get debug mode
                 try:
-                    from django_cfg.core.config import get_current_config
+                    from django_cfg.core.state import get_current_config
                     config = get_current_config()
                     debug = config.debug if config else False
                 except Exception:
                     debug = os.getenv('DEBUG', 'false').lower() in ('true', '1', 'yes')
-                
-                file_handler.setLevel(logging.DEBUG if debug else logging.INFO)
+
+                file_handler.setLevel(logging.DEBUG if debug else logging.WARNING)
                 
                 # Set format
                 formatter = logging.Formatter('[%(asctime)s] %(levelname)s in %(name)s [%(filename)s:%(lineno)d]: %(message)s')

django_cfg/modules/{logger.py → django_logging/logger.py}

@@ -23,7 +23,7 @@ class LoggerConfig:
     """Configuration for django_cfg logger."""
 
     # Default settings
-    DEFAULT_LEVEL = logging.INFO
+    DEFAULT_LEVEL = logging.WARNING  # Only show warnings and above when debug=False
     DEFAULT_FORMAT = (
         "%(levelname)s %(asctime)s %(name)s %(process)d %(processName)s %(message)s"
     )
@@ -84,7 +84,14 @@ class DjangoCfgLogger:
     def _setup_logger(self, debug: bool = None, use_rich: bool = True) -> None:
         """Setup logger with appropriate configuration."""
         if debug is None:
-            debug = os.environ.get("DEBUG", "false").lower() == "true"
+            # Try to get debug from django_cfg config first
+            try:
+                from django_cfg.core.state import get_current_config
+                config = get_current_config()
+                debug = config.debug if config and hasattr(config, 'debug') else False
+            except Exception:
+                # Fallback to environment variable
+                debug = os.environ.get("DEBUG", "false").lower() == "true"
 
         # Determine log level
         log_level = logging.DEBUG if debug else LoggerConfig.DEFAULT_LEVEL
@@ -104,6 +111,7 @@ class DjangoCfgLogger:
                     show_path=False,
                     markup=True,
                     rich_tracebacks=True,
+                    level=log_level,  # Respect debug mode
                 )
             except Exception:
                 # Fallback to standard handler if rich fails
@@ -111,6 +119,8 @@ class DjangoCfgLogger:
         else:
             handler = self._create_standard_handler()
 
+        # Set handler level
+        handler.setLevel(log_level)
         self.logger.addHandler(handler)
 
     def _create_standard_handler(self, use_colors: bool = True) -> logging.Handler:
@@ -175,7 +185,7 @@ class DjangoCfgLogger:
 
     def init_complete(self, init_time_ms: float, environment: str) -> None:
         """Log when initialization is complete."""
-        self.info(f"🚀 ConfigToolkit initialized in {init_time_ms:.2f}ms")
+        self.info(f"🚀 Django-CFG initialized in {init_time_ms:.2f}ms")
         self.info(f"🌍 Environment: {environment}")
 
     def success(self, message: str) -> None:
@@ -240,7 +250,7 @@ class DjangoCfgLogger:
 logger = DjangoCfgLogger()
 
 
-# Convenience functions for backward compatibility
+# Convenience functions
 def get_logger(name: Optional[str] = None) -> DjangoCfgLogger:
     """Get logger instance."""
     return DjangoCfgLogger(name)

django_cfg/modules/django_ngrok/__init__.py

@@ -0,0 +1,39 @@
+"""
+Django Ngrok Module for django_cfg.
+
+Auto-configuring Ngrok integration for local development.
+"""
+
+from .service import (
+    DjangoNgrok,
+    NgrokManager,
+    NgrokError,
+    get_ngrok_service,
+    start_tunnel,
+    stop_tunnel,
+    get_tunnel_url,
+    get_webhook_url,
+    get_api_url,
+    get_tunnel_url_from_env,
+    get_ngrok_host_from_env,
+    is_ngrok_available_from_env,
+    is_tunnel_active,
+    get_effective_tunnel_url,
+)
+
+__all__ = [
+    "DjangoNgrok",
+    "NgrokManager",
+    "NgrokError",
+    "get_ngrok_service",
+    "start_tunnel",
+    "stop_tunnel",
+    "get_tunnel_url",
+    "get_webhook_url",
+    "get_api_url",
+    "get_tunnel_url_from_env",
+    "get_ngrok_host_from_env",
+    "is_ngrok_available_from_env",
+    "is_tunnel_active",
+    "get_effective_tunnel_url",
+]