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

django_cfg/apps/api/endpoints/urls_list/views.py

@@ -0,0 +1,279 @@
+"""
+Django CFG URLs List DRF View
+
+DRF browsable API view for listing all Django URLs with Tailwind theme support.
+"""
+
+from typing import Any, Dict, List
+from urllib.parse import urljoin
+
+from django.conf import settings
+from django.urls import URLPattern, URLResolver, get_resolver
+from rest_framework import status
+from rest_framework.permissions import IsAdminUser
+from rest_framework.response import Response
+from rest_framework.views import APIView
+
+from django_cfg.core.integration import get_current_version
+
+from .serializers import URLsListSerializer
+
+
+class DRFURLsListView(APIView):
+    """
+    Django CFG URLs list endpoint with DRF Browsable API.
+
+    Lists all registered Django URLs with their:
+    - Pattern
+    - Name
+    - View/ViewSet
+    - Full URL
+    - HTTP methods
+
+    This endpoint uses DRF Browsable API with Tailwind CSS theme! 🎨
+
+    **IMPORTANT**: Admin-only endpoint for security reasons.
+    """
+
+    permission_classes = [IsAdminUser]  # Admin-only for security
+    serializer_class = URLsListSerializer  # For schema generation
+
+    def get(self, request):
+        """
+        Return registered URLs (API endpoints by default).
+
+        Query Parameters:
+            filter (str): Filter URLs by prefix
+                - omit or 'api': Only API endpoints (/api/*) - DEFAULT
+                - 'all': All URLs (admin, api, cfg, etc.)
+                - 'admin': Only admin endpoints (/admin/*)
+                - 'cfg': Only django-cfg endpoints (/cfg/*)
+        """
+        try:
+            config = getattr(settings, 'config', None)
+
+            # Get base URL from config or settings
+            base_url = getattr(config, 'site_url', None) if config else None
+            if not base_url:
+                base_url = request.build_absolute_uri('/').rstrip('/')
+
+            # Get filter parameter (default: 'api')
+            url_filter = request.query_params.get('filter', 'api')
+
+            urls_data = {
+                "status": "success",
+                "service": config.project_name if config else "Django CFG",
+                "version": get_current_version(),
+                "base_url": base_url,
+                "filter": url_filter,
+                "total_urls": 0,
+                "urls": []
+            }
+
+            # Extract all URLs
+            all_urls = self._get_all_urls()
+
+            # Apply filter (default: api)
+            if url_filter == 'all':
+                # Show all URLs
+                urls_data["urls"] = all_urls
+                urls_data["total_urls"] = len(all_urls)
+            else:
+                # Filter by prefix (api, admin, cfg)
+                filtered_urls = self._filter_urls(all_urls, url_filter)
+                urls_data["urls"] = filtered_urls
+                urls_data["total_urls"] = len(filtered_urls)
+                urls_data["total_urls_unfiltered"] = len(all_urls)
+
+            return Response(urls_data, status=status.HTTP_200_OK)
+
+        except Exception as e:
+            return Response({
+                "status": "error",
+                "error": str(e)
+            }, status=status.HTTP_500_INTERNAL_SERVER_ERROR)
+
+    def _filter_urls(self, urls: List[Dict[str, Any]], filter_type: str) -> List[Dict[str, Any]]:
+        """
+        Filter URLs by prefix.
+
+        Args:
+            urls: List of URL dictionaries
+            filter_type: Filter type ('api', 'admin', 'cfg')
+
+        Returns:
+            Filtered list of URLs
+        """
+        if filter_type == 'api':
+            return [url for url in urls if url['pattern'].startswith('api/')]
+        elif filter_type == 'admin':
+            return [url for url in urls if url['pattern'].startswith('admin/')]
+        elif filter_type == 'cfg':
+            return [url for url in urls if url['pattern'].startswith('cfg/')]
+        else:
+            # Unknown filter - return all
+            return urls
+
+    def _get_all_urls(self, urlpatterns=None, prefix='', namespace=None) -> List[Dict[str, Any]]:
+        """
+        Recursively extract all URL patterns from Django URLconf.
+
+        Args:
+            urlpatterns: URL patterns to process
+            prefix: URL prefix from parent resolvers
+            namespace: Current namespace
+
+        Returns:
+            List of URL pattern dictionaries
+        """
+        if urlpatterns is None:
+            urlpatterns = get_resolver().url_patterns
+
+        url_list = []
+
+        for pattern in urlpatterns:
+            if isinstance(pattern, URLResolver):
+                # Recursively process URL resolver (include())
+                new_prefix = prefix + str(pattern.pattern)
+                new_namespace = f"{namespace}:{pattern.namespace}" if namespace and pattern.namespace else pattern.namespace or namespace
+
+                url_list.extend(
+                    self._get_all_urls(
+                        pattern.url_patterns,
+                        prefix=new_prefix,
+                        namespace=new_namespace
+                    )
+                )
+            elif isinstance(pattern, URLPattern):
+                # Extract URL pattern details
+                url_pattern = prefix + str(pattern.pattern)
+                url_name = pattern.name
+
+                # Build full name with namespace
+                if namespace and url_name:
+                    full_name = f"{namespace}:{url_name}"
+                else:
+                    full_name = url_name
+
+                # Get view information
+                view_info = self._get_view_info(pattern)
+
+                url_list.append({
+                    "pattern": url_pattern,
+                    "name": url_name,
+                    "full_name": full_name,
+                    "namespace": namespace,
+                    "view": view_info["view"],
+                    "view_class": view_info["view_class"],
+                    "methods": view_info["methods"],
+                    "module": view_info["module"],
+                })
+
+        return url_list
+
+    def _get_view_info(self, pattern: URLPattern) -> Dict[str, Any]:
+        """
+        Extract view information from URL pattern.
+
+        Args:
+            pattern: URLPattern instance
+
+        Returns:
+            Dictionary with view information
+        """
+        view_info = {
+            "view": None,
+            "view_class": None,
+            "methods": [],
+            "module": None,
+        }
+
+        try:
+            callback = pattern.callback
+
+            if callback is None:
+                return view_info
+
+            # Get view name
+            if hasattr(callback, '__name__'):
+                view_info["view"] = callback.__name__
+            elif hasattr(callback, '__class__'):
+                view_info["view"] = callback.__class__.__name__
+
+            # Get view class (for CBV/ViewSets)
+            if hasattr(callback, 'cls'):
+                view_info["view_class"] = callback.cls.__name__
+
+                # Get HTTP methods from ViewSet/APIView
+                if hasattr(callback.cls, 'http_method_names'):
+                    view_info["methods"] = callback.cls.http_method_names
+
+                # Get module
+                if hasattr(callback.cls, '__module__'):
+                    view_info["module"] = callback.cls.__module__
+
+            # For function-based views
+            elif hasattr(callback, '__module__'):
+                view_info["module"] = callback.__module__
+
+                # Try to determine methods from decorator
+                if hasattr(callback, 'methods'):
+                    view_info["methods"] = list(callback.methods)
+                else:
+                    view_info["methods"] = ['GET']  # Default for FBV
+
+        except Exception:
+            pass
+
+        return view_info
+
+
+class DRFURLsListCompactView(APIView):
+    """
+    Compact URLs list endpoint - just patterns and names.
+
+    This endpoint uses DRF Browsable API with Tailwind CSS theme! 🎨
+
+    **IMPORTANT**: Admin-only endpoint for security reasons.
+    """
+
+    permission_classes = [IsAdminUser]  # Admin-only for security
+
+    def get(self, request):
+        """Return compact URL list."""
+        try:
+            url_patterns = self._get_compact_urls()
+
+            return Response({
+                "status": "success",
+                "total": len(url_patterns),
+                "urls": url_patterns
+            }, status=status.HTTP_200_OK)
+
+        except Exception as e:
+            return Response({
+                "status": "error",
+                "error": str(e)
+            }, status=status.HTTP_500_INTERNAL_SERVER_ERROR)
+
+    def _get_compact_urls(self, urlpatterns=None, prefix='') -> List[Dict[str, str]]:
+        """Extract URLs in compact format."""
+        if urlpatterns is None:
+            urlpatterns = get_resolver().url_patterns
+
+        url_list = []
+
+        for pattern in urlpatterns:
+            if isinstance(pattern, URLResolver):
+                new_prefix = prefix + str(pattern.pattern)
+                url_list.extend(
+                    self._get_compact_urls(pattern.url_patterns, prefix=new_prefix)
+                )
+            elif isinstance(pattern, URLPattern):
+                url_pattern = prefix + str(pattern.pattern)
+                url_list.append({
+                    "pattern": url_pattern,
+                    "name": pattern.name or "unnamed",
+                })
+
+        return url_list

django_cfg/apps/api/health/drf_views.py

@@ -13,6 +13,7 @@ import psutil
 from django.conf import settings
 from django.core.cache import cache
 from django.db import connections
+from django.urls import reverse
 from django.utils import timezone
 from rest_framework import status
 from rest_framework.permissions import AllowAny
@@ -102,6 +103,17 @@ class DRFHealthCheckView(APIView):
             "python_version": f"{os.sys.version_info.major}.{os.sys.version_info.minor}.{os.sys.version_info.micro}",
         }
 
+        # Add useful links using reverse()
+        health_data["links"] = {
+            "urls_list": request.build_absolute_uri(reverse('urls_list')),
+            "urls_list_compact": request.build_absolute_uri(reverse('urls_list_compact')),
+            "endpoints_status": request.build_absolute_uri(reverse('endpoints_status_drf')),
+            "quick_health": request.build_absolute_uri(reverse('django_cfg_drf_quick_health')),
+        }
+
+        # Add OpenAPI schema links
+        health_data["links"]["openapi_schemas"] = self._get_openapi_schema_links(request)
+
         # Return appropriate HTTP status
         http_status = status.HTTP_200_OK
         if health_data["status"] == "unhealthy":
@@ -191,6 +203,30 @@ class DRFHealthCheckView(APIView):
                 "error": str(e)
             }
 
+    def _get_openapi_schema_links(self, request) -> Dict[str, str]:
+        """Get OpenAPI schema links for all configured groups."""
+        try:
+            from django_cfg.modules.django_client.core import get_openapi_service
+
+            service = get_openapi_service()
+
+            if not service.config or not service.is_enabled():
+                return {}
+
+            schema_links = {}
+            for group_name in service.get_group_names():
+                try:
+                    schema_url_name = f'openapi-schema-{group_name}'
+                    schema_links[group_name] = request.build_absolute_uri(reverse(schema_url_name))
+                except Exception:
+                    # Skip if URL name doesn't exist
+                    continue
+
+            return schema_links
+
+        except Exception:
+            return {}
+
     def _check_system_resources(self) -> Dict[str, Any]:
         """Check system resource usage."""
         try:

django_cfg/apps/api/health/serializers.py

@@ -10,6 +10,9 @@ from rest_framework import serializers
 class HealthCheckSerializer(serializers.Serializer):
     """Serializer for health check response."""
 
+    class Meta:
+        ref_name = 'DRFHealthCheck'  # Unique name for OpenAPI schema
+
     status = serializers.CharField(
         help_text="Overall health status: healthy, degraded, or unhealthy"
     )
@@ -28,6 +31,10 @@ class HealthCheckSerializer(serializers.Serializer):
     environment = serializers.DictField(
         help_text="Environment information"
     )
+    links = serializers.DictField(
+        required=False,
+        help_text="Useful API endpoint links"
+    )
 
 
 class QuickHealthSerializer(serializers.Serializer):

django_cfg/apps/integrations/centrifugo/__init__.py

@@ -0,0 +1,74 @@
+"""
+Django-CFG Centrifugo Integration.
+
+Provides Django integration with Centrifugo WebSocket server for real-time
+notifications with delivery confirmation (ACK tracking).
+
+Main Components:
+- CentrifugoClient: Django client for publishing messages
+- CentrifugoLog: Model for tracking publish operations
+- CentrifugoLogger: Helper for automatic logging
+- DjangoCfgCentrifugoConfig: Pydantic configuration model
+
+Example:
+    >>> from django_cfg.apps.integrations.centrifugo import get_centrifugo_client
+    >>>
+    >>> client = get_centrifugo_client()
+    >>> result = await client.publish_with_ack(
+    ...     channel="user#123",
+    ...     data={"title": "Hello", "message": "World"},
+    ...     ack_timeout=10
+    ... )
+    >>> print(f"Delivered: {result.delivered}")
+"""
+
+from .services.client.client import CentrifugoClient, get_centrifugo_client, PublishResponse
+from .services.client.direct_client import DirectCentrifugoClient
+from .services.client.config import DjangoCfgCentrifugoConfig
+from .services.client.exceptions import (
+    CentrifugoBaseException,
+    CentrifugoConfigurationError,
+    CentrifugoConnectionError,
+    CentrifugoPublishError,
+    CentrifugoTimeoutError,
+    CentrifugoValidationError,
+)
+from .services.logging import CentrifugoLogContext, CentrifugoLogger
+from .decorators import websocket_rpc, centrifugo_channel
+from .registry import (
+    get_global_registry,
+    get_global_channel_registry,
+    RegisteredHandler,
+    RegisteredChannel,
+)
+
+# Note: CentrifugoLog model is not imported here to avoid AppRegistryNotReady errors
+# Import it directly from .models when needed: from django_cfg.apps.integrations.centrifugo.models import CentrifugoLog
+
+__all__ = [
+    # Config
+    "DjangoCfgCentrifugoConfig",
+    # Client
+    "CentrifugoClient",
+    "DirectCentrifugoClient",
+    "get_centrifugo_client",
+    "PublishResponse",
+    # Logging
+    "CentrifugoLogger",
+    "CentrifugoLogContext",
+    # Exceptions
+    "CentrifugoBaseException",
+    "CentrifugoTimeoutError",
+    "CentrifugoPublishError",
+    "CentrifugoConnectionError",
+    "CentrifugoConfigurationError",
+    "CentrifugoValidationError",
+    # Decorators
+    "websocket_rpc",
+    "centrifugo_channel",
+    # Registry
+    "get_global_registry",
+    "get_global_channel_registry",
+    "RegisteredHandler",
+    "RegisteredChannel",
+]

django_cfg/apps/integrations/centrifugo/_cfg/README_DEPENDENCIES.md

@@ -0,0 +1,260 @@
+# Centrifugo Dependency Checker
+
+Automatic dependency checking for Centrifugo integration in django-cfg.
+
+## 🎯 Purpose
+
+Checks for all required libraries before using the Centrifugo integration and provides clear messages with installation instructions if anything is missing.
+
+## 📦 Dependencies Checked
+
+### Required
+- `cent` - Python Centrifugo client library
+- `httpx` - HTTP client for async requests *(included in django-cfg core)*
+
+### Optional (Recommended)
+- `redis` - Redis backend for real-time messaging
+- `websockets` - WebSocket protocol implementation
+
+**Note:** `httpx` is already included in django-cfg core dependencies, but we verify it's available for Centrifugo integration.
+
+## 🚀 Usage
+
+### Automatic check on import
+
+The check happens automatically when you try to use Centrifugo features.
+
+If dependencies are missing, you will see a detailed message:
+
+```
+================================================================================
+❌ MISSING CENTRIFUGO DEPENDENCIES
+================================================================================
+
+Django-CFG's Centrifugo integration requires additional dependencies.
+
+📦 REQUIRED (missing):
+
+  ❌ cent                        - Python Centrifugo client library
+
+================================================================================
+🔧 HOW TO FIX
+================================================================================
+
+Install all Centrifugo dependencies at once (RECOMMENDED):
+
+  pip install django-cfg[centrifugo]
+
+  # or with poetry:
+  poetry add django-cfg[centrifugo]
+
+Or install manually:
+
+  pip install cent
+
+================================================================================
+```
+
+### Manual check
+
+#### In Python code:
+
+```python
+from django_cfg.apps.centrifugo._cfg import check_centrifugo_dependencies
+
+# Check with error on missing
+try:
+    check_centrifugo_dependencies()
+    print("✅ All dependencies installed")
+except Exception as e:
+    print(f"❌ Error: {e}")
+
+# Check without raising error
+status = check_centrifugo_dependencies(raise_on_missing=False)
+print(status)  # {'cent': True, 'httpx': True, 'redis': False, ...}
+```
+
+#### Print status of all dependencies:
+
+```python
+from django_cfg.apps.centrifugo._cfg import print_dependency_status
+
+print_dependency_status()
+```
+
+Output:
+```
+Centrifugo Dependencies Status:
+============================================================
+
+Required:
+  ✅ cent                     5.0.0           - Python Centrifugo client library
+  ✅ httpx                    0.28.1          - HTTP client for async requests
+
+Optional (recommended):
+  ✅ redis                    6.4.0           - Redis backend for real-time messaging
+  ⚠️  websockets              not installed   - WebSocket protocol implementation
+
+============================================================
+```
+
+#### Standalone script:
+
+```bash
+# From project root
+poetry run python -m django_cfg.apps.centrifugo._cfg.check_deps
+
+# Or directly
+poetry run python src/django_cfg/apps/centrifugo/_cfg/check_deps.py
+```
+
+### Get library versions
+
+```python
+from django_cfg.apps.centrifugo._cfg import DependencyChecker
+
+versions = DependencyChecker.get_version_info()
+print(f"Cent version: {versions['cent']}")
+```
+
+## ⚙️ Configuration
+
+### Disable checking
+
+If you need to temporarily disable checking (for example, for testing):
+
+```bash
+export DJANGO_SKIP_CENTRIFUGO_CHECK=1
+```
+
+Or in code:
+```python
+import os
+os.environ['DJANGO_SKIP_CENTRIFUGO_CHECK'] = '1'
+```
+
+## 🔧 Integration in your code
+
+### In Django AppConfig
+
+```python
+from django.apps import AppConfig
+from django_cfg.apps.centrifugo._cfg import check_centrifugo_dependencies
+
+class MyAppConfig(AppConfig):
+    name = 'myapp'
+
+    def ready(self):
+        # Check dependencies on app startup
+        try:
+            check_centrifugo_dependencies(raise_on_missing=True)
+        except Exception as e:
+            print(e)
+            import sys
+            sys.exit(1)
+```
+
+## 🎯 Benefits
+
+1. **Clear error messages** - user immediately sees what's missing and how to fix it
+2. **Automatic checking** - no need to remember to check manually
+3. **Flexibility** - can be disabled for tests or other scenarios
+4. **Doesn't break other commands** - checking is performed only where needed
+5. **Library versions** - can find out installed versions for debugging
+
+## 📚 API Reference
+
+### `check_centrifugo_dependencies(raise_on_missing=True)`
+Checks all Centrifugo dependencies.
+
+**Parameters:**
+- `raise_on_missing` (bool): Raise `CentrifugoDependencyError` when dependencies are missing
+
+**Returns:** `Dict[str, bool]` - status of each dependency
+
+**Raises:** `CentrifugoDependencyError` if `raise_on_missing=True` and dependencies are missing
+
+### `print_dependency_status()`
+Prints a formatted report of all dependency statuses.
+
+### `DependencyChecker.check_all(raise_on_missing=True)`
+Checks all dependencies (static method).
+
+### `DependencyChecker.get_version_info()`
+Returns a dictionary with versions of all installed libraries.
+
+### `CentrifugoDependencyError`
+Exception that is raised when required dependencies are missing.
+
+## 🧪 Testing
+
+```python
+import pytest
+from django_cfg.apps.centrifugo._cfg import (
+    check_centrifugo_dependencies,
+    CentrifugoDependencyError
+)
+
+def test_centrifugo_dependencies_installed():
+    """Test: all dependencies installed"""
+    status = check_centrifugo_dependencies(raise_on_missing=False)
+    assert status['cent'] is True
+    assert status['httpx'] is True
+
+def test_missing_dependencies_raises_error():
+    """Test: error is raised when dependencies are missing"""
+    # This test should run in an environment without centrifugo
+    with pytest.raises(CentrifugoDependencyError):
+        check_centrifugo_dependencies(raise_on_missing=True)
+```
+
+## 📖 Usage Examples
+
+### Example 1: Check in CI/CD
+
+```yaml
+# .github/workflows/test.yml
+- name: Check Centrifugo dependencies
+  run: |
+    poetry run python -m django_cfg.apps.centrifugo._cfg.check_deps
+```
+
+### Example 2: Pre-commit hook
+
+```bash
+#!/bin/bash
+# .git/hooks/pre-commit
+
+# Check dependencies before commit
+poetry run python -m django_cfg.apps.centrifugo._cfg.check_deps
+if [ $? -ne 0 ]; then
+    echo "❌ Centrifugo dependencies missing. Run: pip install django-cfg[centrifugo]"
+    exit 1
+fi
+```
+
+## 🐛 Troubleshooting
+
+### False positives
+
+If the check shows libraries are missing but they are installed:
+
+```bash
+# Check current environment
+which python
+pip list | grep -E '(cent|httpx)'
+
+# Make sure you're using the correct interpreter
+poetry env info
+```
+
+### Check not triggering
+
+Make sure that:
+1. `django_cfg.apps.centrifugo` is added to `INSTALLED_APPS`
+2. The `DJANGO_SKIP_CENTRIFUGO_CHECK` variable is not set
+
+## 🔗 See also
+
+- [Centrifugo Integration Overview](../../../@docs/overview.md)
+- [Django-CFG Documentation](https://djangocfg.com/docs)