django-cfg 1.4.46__py3-none-any.whl → 1.5.181__py3-none-any.whl

django_cfg/core/builders/security_builder.py

@@ -49,6 +49,13 @@ class SecurityBuilder:
         """
         Build complete security settings dictionary.
 
+        Security mode priority:
+        1. Production mode (is_production=True) → strict security (whitelist only)
+        2. Development mode (is_development=True) → relaxed security (wide port ranges)
+
+        IMPORTANT: Production mode always uses strict security regardless of debug flag.
+        The debug flag should only affect logging/error pages, NOT security settings.
+
         Returns:
             Dictionary with all security-related Django settings
 
@@ -59,10 +66,15 @@ class SecurityBuilder:
             >>> 'ALLOWED_HOSTS' in settings
             True
         """
-        if self.config.is_development or self.config.debug:
-            return self._dev_mode_universal()
+        # Get all security domains including auto-extracted from api_url and site_url
+        all_domains = self._get_all_security_domains()
+
+        # Production mode has highest priority for security settings
+        # Debug flag should NOT weaken security in production
+        if self.config.is_production:
+            return self._prod_mode_universal(all_domains)
         else:
-            return self._prod_mode_universal(self.config.security_domains)
+            return self._dev_mode_universal()
 
     def build_allowed_hosts(self) -> List[str]:
         """
@@ -91,7 +103,9 @@ class SecurityBuilder:
         Returns:
             Dictionary with dev security settings
         """
-        normalized = self._normalize_domains(self.config.security_domains)
+        # Get all security domains including auto-extracted from api_url and site_url
+        all_domains = self._get_all_security_domains()
+        normalized = self._normalize_domains(all_domains)
 
         # Get all dev CORS origins (popular ports + security_domains)
         dev_cors_origins = self._get_dev_csrf_origins() + normalized['cors_origins']
@@ -123,6 +137,15 @@ class SecurityBuilder:
             'SECURE_CONTENT_TYPE_NOSNIFF': False,
             'SECURE_BROWSER_XSS_FILTER': False,
             'X_FRAME_OPTIONS': 'SAMEORIGIN',
+
+            # === Django-Axes: Brute-force protection ===
+            **self._get_axes_settings(is_dev=True),
+
+            # === Authentication backends (django-axes + default) ===
+            'AUTHENTICATION_BACKENDS': [
+                'axes.backends.AxesStandaloneBackend',  # django-axes must be first
+                'django.contrib.auth.backends.ModelBackend',  # Default Django auth
+            ],
         }
 
     def _prod_mode_universal(self, security_domains: List[str]) -> Dict[str, Any]:
@@ -154,12 +177,19 @@ class SecurityBuilder:
 
         normalized = self._normalize_domains(security_domains)
 
+        # Check if localhost is in security_domains for universal CORS regex
+        has_localhost = any(
+            domain in ('localhost', '127.0.0.1')
+            for domain in security_domains
+        )
+
         return {
             # === CORS: Only security_domains ===
             # Docker-to-Docker requests don't have Origin header - CORS doesn't apply
             'CORS_ALLOW_ALL_ORIGINS': False,
             'CORS_ALLOW_CREDENTIALS': True,
             'CORS_ALLOWED_ORIGINS': normalized['cors_origins'],
+            'CORS_ALLOWED_ORIGIN_REGEXES': self._get_localhost_cors_regexes() if has_localhost else [],
             'CORS_ALLOW_HEADERS': self.config.cors_allow_headers,
 
             # === ALLOWED_HOSTS: security_domains + Docker patterns ===
@@ -167,7 +197,9 @@ class SecurityBuilder:
             'ALLOWED_HOSTS': self._get_prod_allowed_hosts(normalized['allowed_hosts']),
 
             # === CSRF: Only security_domains ===
-            'CSRF_TRUSTED_ORIGINS': normalized['csrf_origins'],
+            'CSRF_TRUSTED_ORIGINS': normalized['csrf_origins'] + (
+                self._get_localhost_csrf_origins() if has_localhost else []
+            ),
 
             # === Security: All enabled ===
             'SECURE_SSL_REDIRECT': self._should_enable_ssl_redirect(),
@@ -179,6 +211,15 @@ class SecurityBuilder:
             'SECURE_CONTENT_TYPE_NOSNIFF': True,
             'SECURE_BROWSER_XSS_FILTER': True,
             'X_FRAME_OPTIONS': 'DENY',
+
+            # === Django-Axes: Brute-force protection ===
+            **self._get_axes_settings(is_dev=False),
+
+            # === Authentication backends (django-axes + default) ===
+            'AUTHENTICATION_BACKENDS': [
+                'axes.backends.AxesStandaloneBackend',  # django-axes must be first
+                'django.contrib.auth.backends.ModelBackend',  # Default Django auth
+            ],
         }
 
     def _get_prod_allowed_hosts(self, domain_hosts: List[str]) -> List[str]:
@@ -187,10 +228,11 @@ class SecurityBuilder:
 
         In production we're strict, but need to allow:
         - Public domains (security_domains)
+        - Docker internal service names (auto-detected)
         - Docker health checks (internal IPs, if needed)
 
         Problem: If we allow all IPs - insecure!
-        Solution: Allow only private IP ranges (RFC 1918).
+        Solution: Allow only private IP ranges (RFC 1918) + internal service names.
 
         Args:
             domain_hosts: List of normalized domain hostnames
@@ -202,6 +244,10 @@ class SecurityBuilder:
 
         # Check if running in Docker
         if self._is_running_in_docker():
+            # Auto-detect internal service names from configuration
+            internal_services = self._get_internal_service_names()
+            allowed_hosts.extend(internal_services)
+
             # Allow Docker/Kubernetes health checks
             # Use regex for private IPs (RFC 1918)
             allowed_hosts.extend([
@@ -218,6 +264,127 @@ class SecurityBuilder:
 
         return allowed_hosts
 
+    def _get_internal_service_names(self) -> List[str]:
+        """
+        Auto-detect Docker internal service names from configuration.
+
+        Extracts service hostnames from internal URLs:
+        - Centrifugo API URL (centrifugo_api_url)
+        - gRPC internal URL (grpc.internal_url if available)
+        - Any other internal service URLs
+
+        Example:
+            centrifugo_api_url = "http://djangocfg-centrifugo:8000/api"
+            → Extracts: "djangocfg-centrifugo"
+
+        Returns:
+            List of internal service hostnames (without port)
+        """
+        service_names = []
+
+        # Extract from Centrifugo config
+        if hasattr(self.config, 'centrifugo') and self.config.centrifugo:
+            centrifugo_cfg = self.config.centrifugo
+
+            # Extract from centrifugo_api_url (for Django → Centrifugo publishing)
+            if hasattr(centrifugo_cfg, 'centrifugo_api_url'):
+                api_url = centrifugo_cfg.centrifugo_api_url
+                hostname = self._extract_hostname_from_url(api_url)
+                if hostname and self._is_internal_service_name(hostname):
+                    service_names.append(hostname)
+
+        # Extract from gRPC config
+        if hasattr(self.config, 'grpc') and self.config.grpc:
+            grpc_cfg = self.config.grpc
+
+            # Extract from internal_url (for container-to-container gRPC)
+            if hasattr(grpc_cfg, 'internal_url'):
+                internal_url = grpc_cfg.internal_url
+                # Handle formats: "djangocfg-grpc:50051" or "http://djangocfg-grpc:50051"
+                hostname = self._extract_hostname_from_url(internal_url, allow_no_protocol=True)
+                if hostname and self._is_internal_service_name(hostname):
+                    service_names.append(hostname)
+
+        # Deduplicate while preserving order
+        return list(dict.fromkeys(service_names))
+
+    def _extract_hostname_from_url(self, url: str, allow_no_protocol: bool = False) -> str:
+        """
+        Extract hostname from URL.
+
+        Args:
+            url: URL string (e.g., "http://djangocfg-api:8000/path" or "djangocfg-grpc:50051")
+            allow_no_protocol: Allow URLs without protocol (for gRPC addresses)
+
+        Returns:
+            Hostname without port (e.g., "djangocfg-api")
+        """
+        if not url:
+            return ""
+
+        try:
+            # Handle URLs without protocol (e.g., "djangocfg-grpc:50051")
+            if allow_no_protocol and not url.startswith(("http://", "https://")):
+                # Split by : to get hostname:port
+                hostname_port = url.split('/')[0]  # Remove path if any
+                hostname = hostname_port.split(':')[0]  # Remove port
+                return hostname.strip()
+
+            # Standard URL parsing
+            parsed = urlparse(url if url.startswith(("http://", "https://")) else f"http://{url}")
+            hostname = parsed.hostname or parsed.netloc.split(':')[0]
+            return hostname.strip() if hostname else ""
+        except Exception:
+            return ""
+
+    def _is_internal_service_name(self, hostname: str) -> bool:
+        """
+        Check if hostname is an internal Docker/Kubernetes service name.
+
+        Internal service names typically:
+        - Don't contain dots (unlike domains: example.com)
+        - Are not IPs (172.x.x.x, 192.168.x.x)
+        - Are not localhost/127.0.0.1
+
+        Examples:
+            "djangocfg-api" → True (internal service)
+            "djangocfg-grpc" → True (internal service)
+            "api.example.com" → False (external domain)
+            "192.168.1.10" → False (IP address)
+            "localhost" → False (localhost)
+
+        Args:
+            hostname: Hostname to check
+
+        Returns:
+            True if internal service name, False otherwise
+        """
+        if not hostname:
+            return False
+
+        hostname = hostname.lower().strip()
+
+        # Exclude localhost
+        if hostname in ('localhost', '127.0.0.1'):
+            return False
+
+        # Exclude IP addresses (simple check)
+        if hostname.replace('.', '').isdigit():
+            return False
+
+        # Exclude domains with dots (external domains like api.example.com)
+        # Keep Kubernetes service names like service.namespace.svc.cluster.local
+        if '.' in hostname:
+            # Allow .cluster.local and .svc (Kubernetes)
+            if hostname.endswith(('.cluster.local', '.svc')):
+                return True
+            # Otherwise it's an external domain
+            return False
+
+        # If no dots and not excluded - it's an internal service name
+        # Examples: djangocfg-api, djangocfg-grpc, postgres, redis
+        return True
+
     def _is_running_in_docker(self) -> bool:
         """
         Detect if application is running in Docker.
@@ -281,7 +448,7 @@ class SecurityBuilder:
         Smart list of dev CSRF origins.
 
         Covers:
-        - Popular dev ports
+        - All dev ports from 3000 to 10000 (covers all common dev servers)
         - localhost and 127.0.0.1
 
         Docker IPs NOT needed - CSRF checks Referer from browser!
@@ -289,18 +456,59 @@ class SecurityBuilder:
         Returns:
             List of dev CSRF origins
         """
-        popular_ports = [
-            3000,  # React/Next.js default
-            5173,  # Vite default
-            5174,  # Vite preview
-            8080,  # Vue/Spring Boot
-            4200,  # Angular
-            8000,  # Django default
-            8001,  # Django alternative
+        # Wide port range for development (3000-10000)
+        # Covers: Next.js, React, Vite, Angular, Vue, Django, Flask, etc.
+        dev_ports = range(3000, 10001)
+
+        origins = []
+        for port in dev_ports:
+            origins.extend([
+                f"http://localhost:{port}",
+                f"http://127.0.0.1:{port}",
+            ])
+
+        return origins
+
+    def _get_localhost_cors_regexes(self) -> List[str]:
+        """
+        Universal localhost CORS regex for ANY port.
+
+        When localhost/127.0.0.1 is in security_domains, allow all ports via regex.
+        This is much simpler than maintaining a list of specific ports.
+
+        Matches:
+        - http://localhost:3000
+        - http://localhost:8000
+        - http://127.0.0.1:7301
+        - Any other localhost port
+
+        Returns:
+            List of regex patterns for CORS_ALLOWED_ORIGIN_REGEXES
+        """
+        return [
+            r'^http://localhost:\d+$',      # localhost with any port
+            r'^http://127\.0\.0\.1:\d+$',   # 127.0.0.1 with any port
         ]
 
+    def _get_localhost_csrf_origins(self) -> List[str]:
+        """
+        Localhost CSRF origins with wide port range for development.
+
+        CSRF doesn't support regex, so we need to list specific ports.
+        Covers all development ports from 3000 to 10000.
+
+        Note: CORS uses regex for ALL ports via CORS_ALLOWED_ORIGIN_REGEXES.
+        CSRF needs explicit port list - using same range as dev mode (3000-10000).
+
+        Returns:
+            List of localhost origins with development ports for CSRF
+        """
+        # Wide port range for development (3000-10000)
+        # Covers: Next.js, React, Vite, Angular, Vue, Django, Flask, etc.
+        dev_ports = range(3000, 10001)
+
         origins = []
-        for port in popular_ports:
+        for port in dev_ports:
             origins.extend([
                 f"http://localhost:{port}",
                 f"http://127.0.0.1:{port}",
@@ -308,6 +516,185 @@ class SecurityBuilder:
 
         return origins
 
+    def _get_axes_settings(self, is_dev: bool) -> Dict[str, Any]:
+        """
+        Get Django-Axes settings (custom config or smart defaults).
+
+        Args:
+            is_dev: Whether running in development mode
+
+        Returns:
+            Dictionary with Django-Axes settings
+        """
+        # If user provided custom AxesConfig, use it
+        if self.config.axes:
+            return self.config.axes.to_django_settings(
+                is_production=self.config.is_production,
+                debug=self.config.debug
+            )
+
+        # Otherwise, use smart defaults
+        return self._get_default_axes_settings(is_dev)
+
+    def _get_default_axes_settings(self, is_dev: bool) -> Dict[str, Any]:
+        """
+        Get default Django-Axes settings based on environment.
+
+        Args:
+            is_dev: Whether running in development mode
+
+        Returns:
+            Dictionary with default Django-Axes settings
+        """
+        if is_dev:
+            return {
+                'AXES_ENABLED': True,
+                'AXES_FAILURE_LIMIT': 10,  # More attempts in dev
+                'AXES_COOLOFF_TIME': 1,  # 1 hour lockout
+                'AXES_LOCK_OUT_AT_FAILURE': True,
+                'AXES_RESET_ON_SUCCESS': True,
+                # AXES_ONLY_USER_FAILURES deprecated in 8.0
+                'AXES_LOCKOUT_TEMPLATE': None,  # Use default lockout response
+                'AXES_LOCKOUT_URL': None,  # No custom lockout URL
+                'AXES_VERBOSE': True,  # Log lockout events in dev
+                'AXES_ENABLE_ACCESS_FAILURE_LOG': True,
+                'AXES_IPWARE_PROXY_COUNT': 1,
+                'AXES_IPWARE_META_PRECEDENCE_ORDER': [
+                    'HTTP_X_FORWARDED_FOR',
+                    'HTTP_X_REAL_IP',
+                    'REMOTE_ADDR',
+                ],
+            }
+        else:
+            return {
+                'AXES_ENABLED': True,
+                'AXES_FAILURE_LIMIT': 5,  # Stricter limit in production
+                'AXES_COOLOFF_TIME': 24,  # 24 hours lockout in production
+                'AXES_LOCK_OUT_AT_FAILURE': True,
+                'AXES_RESET_ON_SUCCESS': True,
+                # AXES_ONLY_USER_FAILURES deprecated in 8.0
+                'AXES_LOCKOUT_TEMPLATE': None,  # Use default lockout response
+                'AXES_LOCKOUT_URL': None,  # No custom lockout URL
+                'AXES_VERBOSE': False,  # Less verbose logging in production
+                'AXES_ENABLE_ACCESS_FAILURE_LOG': True,  # Log failures for security audit
+                # Proxy/Cloudflare support - get real IP from X-Forwarded-For
+                'AXES_IPWARE_PROXY_COUNT': 1,  # Number of proxies between client and server
+                'AXES_IPWARE_META_PRECEDENCE_ORDER': [
+                    'HTTP_X_FORWARDED_FOR',  # Cloudflare, nginx, traefik
+                    'HTTP_X_REAL_IP',        # Alternative proxy header
+                    'REMOTE_ADDR',           # Fallback to direct connection
+                ],
+            }
+
+    def _get_all_security_domains(self) -> List[str]:
+        """
+        Get all security domains including auto-extracted from api_url and site_url.
+
+        Automatically extracts domains from:
+        - config.security_domains (user-defined)
+        - config.api_url (backend URL)
+        - config.site_url (frontend URL)
+
+        Smart deduplication by hostname:port (ignoring protocol differences).
+
+        Returns:
+            List of all unique security domains
+
+        Example:
+            >>> config = DjangoConfig(
+            ...     api_url="https://api.example.com",
+            ...     site_url="https://example.com",
+            ...     security_domains=["localhost"]
+            ... )
+            >>> builder = SecurityBuilder(config)
+            >>> domains = builder._get_all_security_domains()
+            >>> len([d for d in domains if 'api.example.com' in d])
+            1
+            >>> len([d for d in domains if 'example.com' in d and 'api' not in d])
+            1
+        """
+        domains = list(self.config.security_domains)
+
+        # Extract domain from api_url
+        if self.config.api_url:
+            try:
+                parsed = urlparse(self.config.api_url)
+                if parsed.netloc:
+                    # Add full URL with protocol and port if present
+                    if parsed.port:
+                        domains.append(f"{parsed.scheme}://{parsed.hostname}:{parsed.port}")
+                    else:
+                        domains.append(f"{parsed.scheme}://{parsed.hostname}")
+            except Exception:
+                pass  # Ignore parsing errors
+
+        # Extract domain from site_url
+        if self.config.site_url:
+            try:
+                parsed = urlparse(self.config.site_url)
+                if parsed.netloc:
+                    # Add full URL with protocol and port if present
+                    if parsed.port:
+                        domains.append(f"{parsed.scheme}://{parsed.hostname}:{parsed.port}")
+                    else:
+                        domains.append(f"{parsed.scheme}://{parsed.hostname}")
+            except Exception:
+                pass  # Ignore parsing errors
+
+        # Smart deduplication: track by hostname:port, keep first occurrence with protocol
+        seen_hostports = {}  # hostname:port -> full domain string
+        unique_domains = []
+
+        for domain in domains:
+            if not domain or not domain.strip():
+                continue
+
+            domain = domain.strip()
+
+            # Normalize for comparison: parse to get hostname:port key
+            try:
+                # Add protocol if missing for parsing
+                if not domain.startswith(("http://", "https://")):
+                    parse_domain = f"http://{domain}"
+                else:
+                    parse_domain = domain
+
+                parsed = urlparse(parse_domain)
+                hostname = (parsed.hostname or parsed.netloc.split(':')[0]).lower()  # Lowercase for case-insensitive comparison
+                port = parsed.port
+
+                # Create unique key: hostname:port or just hostname (lowercase for case-insensitivity)
+                if port:
+                    hostport_key = f"{hostname}:{port}"
+                else:
+                    hostport_key = hostname
+
+                # Only add if we haven't seen this hostname:port combination
+                if hostport_key not in seen_hostports:
+                    # Normalize domain to lowercase but preserve original format (with/without protocol)
+                    # Reconstruct normalized domain
+                    if domain.startswith(("http://", "https://")):
+                        # Has protocol - normalize hostname part only
+                        if port:
+                            normalized_domain = f"{parsed.scheme}://{hostname}:{port}"
+                        else:
+                            normalized_domain = f"{parsed.scheme}://{hostname}"
+                    else:
+                        # No protocol - just lowercase the whole thing
+                        normalized_domain = domain.lower()
+
+                    seen_hostports[hostport_key] = normalized_domain
+                    unique_domains.append(normalized_domain)
+
+            except Exception:
+                # If parsing fails, use simple string deduplication with lowercase
+                domain_lower = domain.lower()
+                if domain_lower not in seen_hostports.values():
+                    seen_hostports[domain_lower] = domain_lower
+                    unique_domains.append(domain_lower)
+
+        return unique_domains
+
     def _normalize_domains(self, domains: List[str]) -> Dict[str, List[str]]:
         """
         Normalize domains in ANY format.
@@ -317,6 +704,7 @@ class SecurityBuilder:
         - "https://api.example.com" → https://api.example.com (as is)
         - "http://staging.com:8080" → http://staging.com:8080 (as is)
         - "192.168.1.10" → http://192.168.1.10
+        - "localhost" → http://localhost (regex handles all ports via CORS_ALLOWED_ORIGIN_REGEXES)
 
         Args:
             domains: List of domains in any format

django_cfg/core/constants.py

@@ -32,6 +32,7 @@ DEFAULT_APPS: List[str] = [
     "rest_framework_simplejwt",
     "rest_framework_simplejwt.token_blacklist",
     "rest_framework_nested",
+    "adrf",  # Async Django REST Framework
     "rangefilter",
     "django_filters",
     "drf_spectacular",
@@ -40,20 +41,27 @@ DEFAULT_APPS: List[str] = [
     "django_extensions",
     "constance",
     "constance.backends.database",
+    # Security
+    "axes",  # django-axes for brute-force protection
     # Django CFG Core
     "django_cfg",
     "django_cfg.modules.django_client",
+    "django_cfg.modules.django_admin",
 ]
 
 # Default middleware stack
 DEFAULT_MIDDLEWARE: List[str] = [
     "django.middleware.security.SecurityMiddleware",
     "whitenoise.middleware.WhiteNoiseMiddleware",
+    # Public API CORS - handles /cfg/leads/ and other public endpoints BEFORE corsheaders
+    "django_cfg.core.middleware.PublicAPICORSMiddleware",
     "corsheaders.middleware.CorsMiddleware",
     "django.contrib.sessions.middleware.SessionMiddleware",
     "django.middleware.common.CommonMiddleware",
     "django.middleware.csrf.CsrfViewMiddleware",
     "django.contrib.auth.middleware.AuthenticationMiddleware",
+    # Security: django-axes must be after AuthenticationMiddleware
+    "axes.middleware.AxesMiddleware",
     "django.contrib.messages.middleware.MessageMiddleware",
     "django.middleware.clickjacking.XFrameOptionsMiddleware",
 ]

django_cfg/core/debug/README.md

@@ -0,0 +1,116 @@
+# Django-CFG Debug Utilities
+
+Debug utilities to help troubleshoot Django-CFG issues.
+
+## Warnings Debug Helper
+
+Shows full stack traceback for specific warnings to help identify their source.
+
+### Quick Start
+
+**Method 1: Via Config (Recommended)**
+
+```python
+# In your config.py
+from django_cfg import DjangoConfig
+
+class MyConfig(DjangoConfig):
+    project_name: str = "My Project"
+    debug_warnings: bool = True  # ← Enable warnings traceback
+```
+
+**Method 2: Via Environment Variable**
+
+```bash
+export DJANGO_CFG_DEBUG_WARNINGS=1
+python manage.py runserver
+```
+
+This will show full traceback for:
+- RuntimeWarnings about database access during app initialization
+- APPS_NOT_READY warnings
+- Other app initialization warnings
+
+### Example Output
+
+```
+================================================================================
+⚠️  WARNING TRACEBACK (to help find the source)
+================================================================================
+  File "/path/to/your/code/apps.py", line 42, in ready
+    self.setup_database()
+  File "/path/to/your/code/apps.py", line 55, in setup_database
+    MyModel.objects.all()
+    ^^^^^^^^^^^^^^^^^^^^
+
+--------------------------------------------------------------------------------
+⚠️  WARNING MESSAGE:
+/usr/lib/python3.12/site-packages/django/db/backends/utils.py:98: RuntimeWarning:
+Accessing the database during app initialization is discouraged. To fix this
+warning, avoid executing queries in AppConfig.ready() or when your app modules
+are imported.
+================================================================================
+```
+
+### Manual Usage
+
+```python
+# In your manage.py or wsgi.py, BEFORE django.setup():
+from django_cfg.core.debug import setup_warnings_debug
+
+# Enable with default settings
+setup_warnings_debug(enabled=True)
+
+# Or customize:
+setup_warnings_debug(
+    enabled=True,
+    categories=[RuntimeWarning, DeprecationWarning],
+    patterns=['.*database.*', '.*deprecated.*']
+)
+```
+
+### Common Issues Found
+
+1. **Database access in AppConfig.ready()**
+   ```python
+   # ❌ Bad
+   def ready(self):
+       from .models import MyModel
+       MyModel.objects.create(...)
+
+   # ✅ Good - use post_migrate signal
+   def ready(self):
+       from django.db.models.signals import post_migrate
+       post_migrate.connect(self.setup_data, sender=self)
+   ```
+
+2. **Model queries at module level**
+   ```python
+   # ❌ Bad - runs during import
+   from .models import MyModel
+   DEFAULT_SETTINGS = MyModel.objects.first()
+
+   # ✅ Good - lazy evaluation
+   def get_default_settings():
+       from .models import MyModel
+       return MyModel.objects.first()
+   ```
+
+3. **Database connection in __init__.py**
+   ```python
+   # ❌ Bad
+   from django.db import connection
+   cursor = connection.cursor()
+
+   # ✅ Good - move to views/services
+   ```
+
+### Disabling
+
+Simply unset or set to 0:
+
+```bash
+export DJANGO_CFG_DEBUG_WARNINGS=0
+# or
+unset DJANGO_CFG_DEBUG_WARNINGS
+```

django_cfg/core/debug/__init__.py

@@ -0,0 +1,7 @@
+"""
+Debug utilities for Django-CFG.
+"""
+
+from .warnings_helper import setup_warnings_debug
+
+__all__ = ['setup_warnings_debug']