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

django_cfg/apps/integrations/centrifugo/_cfg/__init__.py

@@ -0,0 +1,25 @@
+"""
+Centrifugo System Configuration.
+
+Internal system utilities for configuration, dependency checking, and validation.
+This module is for system/internal use. For public API, use other modules instead.
+"""
+
+from .dependencies import (
+    CentrifugoDependencyError,
+    DependencyChecker,
+    check_centrifugo_available,
+    check_centrifugo_dependencies,
+    print_dependency_status,
+    require_centrifugo_feature,
+)
+
+__all__ = [
+    # Dependency checking
+    "DependencyChecker",
+    "CentrifugoDependencyError",
+    "check_centrifugo_available",
+    "check_centrifugo_dependencies",
+    "require_centrifugo_feature",
+    "print_dependency_status",
+]

django_cfg/apps/integrations/centrifugo/_cfg/check_deps.py

@@ -0,0 +1,34 @@
+#!/usr/bin/env python
+"""
+Standalone script to check Centrifugo dependencies.
+
+Usage:
+    python -m django_cfg.apps.integrations.centrifugo._cfg.check_deps
+    python src/django_cfg/apps/centrifugo/_cfg/check_deps.py
+"""
+
+from __future__ import annotations
+
+import sys
+
+from .dependencies import print_dependency_status
+
+
+def main():
+    """Run dependency check and print status."""
+    print("\n" + "=" * 80)
+    print("Django-CFG Centrifugo Dependency Checker")
+    print("=" * 80)
+
+    try:
+        print_dependency_status()
+        print("✅ All required dependencies are installed!")
+        print("\nYou can now use Centrifugo integration in your Django project.")
+        return 0
+    except Exception as e:
+        print(f"\n❌ Dependency check failed:\n{e}")
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

django_cfg/apps/integrations/centrifugo/_cfg/dependencies.py

@@ -0,0 +1,309 @@
+#!/usr/bin/env python
+"""
+Centrifugo dependency checker.
+
+Validates that all required dependencies for Centrifugo are installed.
+Provides beautiful Rich-formatted error messages with installation instructions.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import os
+from typing import Dict
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+
+class CentrifugoDependencyError(ImportError):
+    """Raised when required Centrifugo dependencies are missing."""
+    pass
+
+
+class DependencyChecker:
+    """
+    Check and validate Centrifugo dependencies.
+
+    Required dependencies:
+    - cent: Python client for Centrifugo
+    - httpx: HTTP client for async requests (included in django-cfg core)
+
+    Optional dependencies:
+    - redis: Redis backend for real-time messaging
+    - websockets: WebSocket protocol implementation
+    """
+
+    # Required dependencies (httpx is already in django-cfg core dependencies)
+    REQUIRED_DEPS = {
+        "cent": "cent>=5.0.0",
+        "httpx": "httpx>=0.28.0",  # Already in core, but verify it's available
+    }
+
+    # Optional dependencies
+    OPTIONAL_DEPS = {
+        "redis": "redis>=6.4.0",
+        "websockets": "websockets>=13.0",
+    }
+
+    # Package descriptions
+    DESCRIPTIONS = {
+        "cent": "Python client for Centrifugo",
+        "httpx": "HTTP client for async requests (included in django-cfg)",
+        "redis": "Redis backend for real-time messaging",
+        "websockets": "WebSocket protocol implementation",
+    }
+
+    @classmethod
+    def check_package(cls, package_name: str) -> bool:
+        """
+        Check if a package is installed.
+
+        Args:
+            package_name: Python package name (import name)
+
+        Returns:
+            True if installed, False otherwise
+        """
+        return importlib.util.find_spec(package_name) is not None
+
+    @classmethod
+    def check_all(cls, raise_on_missing: bool = True) -> Dict[str, bool]:
+        """
+        Check all Centrifugo dependencies.
+
+        Args:
+            raise_on_missing: If True, raise exception when required deps missing
+
+        Returns:
+            Dictionary mapping package names to availability status
+
+        Raises:
+            CentrifugoDependencyError: If required dependencies are missing and raise_on_missing=True
+        """
+        status = {}
+
+        # Check required dependencies
+        for package_name in cls.REQUIRED_DEPS:
+            status[package_name] = cls.check_package(package_name)
+
+        # Check optional dependencies
+        for package_name in cls.OPTIONAL_DEPS:
+            status[package_name] = cls.check_package(package_name)
+
+        # Check if any required dependencies are missing
+        missing_required = [
+            pkg for pkg in cls.REQUIRED_DEPS if not status.get(pkg, False)
+        ]
+
+        missing_optional = [
+            pkg for pkg in cls.OPTIONAL_DEPS if not status.get(pkg, False)
+        ]
+
+        if missing_required and raise_on_missing:
+            cls._raise_missing_error(missing_required, missing_optional)
+
+        return status
+
+    @classmethod
+    def _raise_missing_error(
+        cls,
+        missing_required: list[str],
+        missing_optional: list[str],
+    ) -> None:
+        """
+        Raise a formatted error for missing dependencies.
+
+        Args:
+            missing_required: List of missing required packages
+            missing_optional: List of missing optional packages
+        """
+        console = Console()
+
+        # Header
+        console.print()
+        console.print(Panel(
+            "[bold red]MISSING CENTRIFUGO DEPENDENCIES[/bold red]",
+            expand=True,
+        ))
+        console.print()
+        console.print("Django-CFG's Centrifugo integration requires additional dependencies")
+        console.print()
+
+        # Required dependencies table
+        if missing_required:
+            table = Table(title="📦 REQUIRED Dependencies (Missing)", show_header=True)
+            table.add_column("Package", style="cyan")
+            table.add_column("Description", style="white")
+
+            for pkg in missing_required:
+                pip_name = cls.REQUIRED_DEPS[pkg].split(">=")[0]
+                desc = cls.DESCRIPTIONS.get(pkg, "")
+                table.add_row(f"❌ {pip_name}", desc)
+
+            console.print(table)
+            console.print()
+
+        # Optional dependencies table
+        if missing_optional:
+            table = Table(title="📦 OPTIONAL Dependencies (Recommended)", show_header=True)
+            table.add_column("Package", style="cyan")
+            table.add_column("Description", style="white")
+
+            for pkg in missing_optional:
+                pip_name = cls.OPTIONAL_DEPS[pkg].split(">=")[0]
+                desc = cls.DESCRIPTIONS.get(pkg, "")
+                table.add_row(f"⚠️  {pip_name}", desc)
+
+            console.print(table)
+            console.print()
+
+        # Installation instructions
+        pkg_manager = _detect_package_manager()
+
+        if pkg_manager == "poetry":
+            console.print(Panel(
+                "[bold green]🔧 HOW TO FIX (POETRY)[/bold green]\n\n"
+                "Install all dependencies (RECOMMENDED)\n\n"
+                "[cyan]poetry add django-cfg[centrifugo][/cyan]",
+                expand=False,
+            ))
+            console.print()
+            console.print(Panel(
+                "Or install manually:\n\n"
+                "[cyan]poetry add cent httpx[/cyan]\n\n"
+                "Optional:\n"
+                "[dim]poetry add redis websockets[/dim]",
+                expand=False,
+            ))
+        else:  # pip
+            console.print(Panel(
+                "[bold green]🔧 HOW TO FIX (PIP)[/bold green]\n\n"
+                "Install all dependencies (RECOMMENDED)\n\n"
+                "[cyan]pip install django-cfg[centrifugo][/cyan]",
+                expand=False,
+            ))
+            console.print()
+            console.print(Panel(
+                "Or install manually:\n\n"
+                "[cyan]pip install cent httpx[/cyan]\n\n"
+                "Optional:\n"
+                "[dim]pip install redis websockets[/dim]",
+                expand=False,
+            ))
+
+        console.print()
+        console.print(Panel(
+            "[bold]📚 MORE INFORMATION[/bold]\n\n"
+            "Documentation: https://djangocfg.com/centrifugo\n"
+            "Report Issues: https://github.com/django-cfg/django-cfg/issues",
+            title="📚 MORE INFORMATION",
+            expand=False,
+        ))
+        console.print()
+
+        raise CentrifugoDependencyError("Centrifugo dependencies are missing. See details above.")
+
+    @classmethod
+    def print_status(cls) -> None:
+        """Print dependency status in a nice table."""
+        console = Console()
+        status = cls.check_all(raise_on_missing=False)
+
+        table = Table(title="Centrifugo Dependency Status", show_header=True)
+        table.add_column("Package", style="cyan")
+        table.add_column("Status", style="white")
+        table.add_column("Type", style="white")
+
+        # Required dependencies
+        for pkg, spec in cls.REQUIRED_DEPS.items():
+            pip_name = spec.split(">=")[0]
+            status_str = "✅ Installed" if status.get(pkg, False) else "❌ Missing"
+            table.add_row(pip_name, status_str, "Required")
+
+        # Optional dependencies
+        for pkg, spec in cls.OPTIONAL_DEPS.items():
+            pip_name = spec.split(">=")[0]
+            status_str = "✅ Installed" if status.get(pkg, False) else "⚠️  Missing"
+            table.add_row(pip_name, status_str, "Optional")
+
+        console.print(table)
+
+
+def _detect_package_manager() -> str:
+    """
+    Detect which package manager is being used.
+
+    Returns:
+        'poetry' if poetry.lock exists, 'pip' otherwise
+    """
+    current = os.getcwd()
+
+    # Check up to 5 parent directories for poetry.lock
+    for _ in range(5):
+        if os.path.exists(os.path.join(current, 'poetry.lock')):
+            return 'poetry'
+
+        parent = os.path.dirname(current)
+        if parent == current:  # Reached root
+            break
+        current = parent
+
+    return 'pip'
+
+
+def check_centrifugo_available() -> bool:
+    """
+    Lightweight check if Centrifugo is available.
+
+    Returns:
+        True if all required Centrifugo dependencies are installed
+    """
+    try:
+        status = DependencyChecker.check_all(raise_on_missing=False)
+        required_deps = ['cent', 'httpx']
+        return all(status.get(dep, False) for dep in required_deps)
+    except Exception:
+        # Fallback to simple import check
+        try:
+            import cent  # noqa: F401
+            import httpx  # noqa: F401
+            return True
+        except ImportError:
+            return False
+
+
+def require_centrifugo_feature() -> None:
+    """
+    Require Centrifugo dependencies with detailed error message.
+
+    Raises:
+        ImportError: If required dependencies are missing
+    """
+    try:
+        if not check_centrifugo_available():
+            DependencyChecker.check_all(raise_on_missing=True)
+    except CentrifugoDependencyError as e:
+        raise ImportError(str(e)) from e
+
+
+def check_centrifugo_dependencies(raise_on_missing: bool = True) -> Dict[str, bool]:
+    """
+    Check Centrifugo dependencies and optionally raise if missing.
+
+    Args:
+        raise_on_missing: If True, raise exception when required deps missing
+
+    Returns:
+        Dictionary mapping package names to availability status
+
+    Raises:
+        CentrifugoDependencyError: If dependencies missing and raise_on_missing=True
+    """
+    return DependencyChecker.check_all(raise_on_missing=raise_on_missing)
+
+
+def print_dependency_status() -> None:
+    """Print Centrifugo dependency status table."""
+    DependencyChecker.print_status()

django_cfg/apps/integrations/centrifugo/admin/__init__.py

@@ -0,0 +1,13 @@
+"""
+Django Admin for Centrifugo models.
+
+Uses PydanticAdmin with declarative configuration.
+"""
+
+from .centrifugo_log import CentrifugoLogAdmin
+from .config import centrifugolog_config
+
+__all__ = [
+    "centrifugolog_config",
+    "CentrifugoLogAdmin",
+]

django_cfg/apps/integrations/centrifugo/admin/centrifugo_log.py

@@ -0,0 +1,211 @@
+"""
+Centrifugo Log Admin.
+
+PydanticAdmin for CentrifugoLog model with custom computed fields.
+"""
+
+import json
+
+from django.contrib import admin
+from django_cfg.modules.django_admin import Icons, computed_field
+from django_cfg.modules.django_admin.base import PydanticAdmin
+
+from ..models import CentrifugoLog
+from .config import centrifugolog_config
+
+
+@admin.register(CentrifugoLog)
+class CentrifugoLogAdmin(PydanticAdmin):
+    """
+    Centrifugo log admin with analytics and filtering.
+
+    Features:
+    - Color-coded status badges
+    - ACK tracking visualization
+    - Duration display with performance indicators
+    - Formatted JSON for message data
+    - Error details with highlighted display
+    """
+
+    config = centrifugolog_config
+
+    @computed_field("Type", ordering="wait_for_ack")
+    def type_badge(self, obj):
+        """Display badge showing if this publish waited for ACK."""
+        if obj.wait_for_ack:
+            return self.html.badge("ACK", variant="success", icon=Icons.CHECK_CIRCLE)
+        else:
+            return self.html.badge("FIRE", variant="secondary", icon=Icons.NOTIFICATIONS)
+
+    @computed_field("ACKs", ordering="acks_received")
+    def acks_display(self, obj):
+        """Display ACK count with context."""
+        if not obj.wait_for_ack:
+            return self.html.empty()
+
+        # If we have expected count
+        if obj.acks_expected:
+            rate = obj.delivery_rate
+            if rate == 1.0:
+                variant = "success"
+                icon = Icons.CHECK_CIRCLE
+            elif rate > 0:
+                variant = "warning"
+                icon = Icons.TIMER
+            else:
+                variant = "danger"
+                icon = Icons.ERROR
+
+            return self.html.badge(
+                f"{obj.acks_received}/{obj.acks_expected}",
+                variant=variant,
+                icon=icon,
+            )
+
+        # Just show count
+        if obj.acks_received > 0:
+            return self.html.badge(
+                f"{obj.acks_received} ACKs", variant="success", icon=Icons.CHECK_CIRCLE
+            )
+        else:
+            return self.html.badge("0 ACKs", variant="danger", icon=Icons.ERROR)
+
+    @computed_field("Duration", ordering="duration_ms")
+    def duration_display(self, obj):
+        """Display duration with color coding based on speed."""
+        if obj.duration_ms is None:
+            return self.html.empty()
+
+        # Color code based on duration
+        if obj.duration_ms < 100:
+            variant = "success"  # Fast
+            icon = Icons.SPEED
+        elif obj.duration_ms < 500:
+            variant = "warning"  # Moderate
+            icon = Icons.TIMER
+        else:
+            variant = "danger"  # Slow
+            icon = Icons.ERROR
+
+        return self.html.badge(f"{obj.duration_ms}ms", variant=variant, icon=icon)
+
+    def data_display(self, obj):
+        """Display formatted JSON message data."""
+        if not obj.data:
+            return self.html.empty("No data")
+
+        try:
+            formatted = json.dumps(obj.data, indent=2)
+            return self.html.code_block(formatted, language="json", max_height="400px")
+        except Exception:
+            return str(obj.data)
+
+    data_display.short_description = "Message Data"
+
+    def error_details_display(self, obj):
+        """Display error information if publish failed."""
+        if obj.is_successful or obj.status == "pending":
+            return self.html.inline(
+                self.html.icon(Icons.CHECK_CIRCLE, size="sm"),
+                self.html.text("No errors", variant="success"),
+                separator=" "
+            )
+
+        error_code_line = self.html.key_value(
+            "Error Code",
+            self.html.badge(obj.error_code, variant="danger", icon=Icons.ERROR)
+        ) if obj.error_code else None
+
+        error_msg_line = self.html.key_value(
+            "Message",
+            self.html.text(obj.error_message, variant="danger")
+        ) if obj.error_message else None
+
+        return self.html.breakdown(error_code_line, error_msg_line) if (error_code_line or error_msg_line) else self.html.empty()
+
+    error_details_display.short_description = "Error Details"
+
+    def delivery_stats_display(self, obj):
+        """Display delivery statistics."""
+        if not obj.wait_for_ack:
+            return self.html.empty("No ACK tracking")
+
+        # ACK timeout
+        timeout_line = self.html.key_value(
+            "Timeout",
+            f"{obj.ack_timeout}s"
+        ) if obj.ack_timeout else None
+
+        # ACKs received
+        received_line = self.html.key_value(
+            "ACKs Received",
+            self.html.badge(str(obj.acks_received), variant="info")
+        )
+
+        # ACKs expected (if known)
+        expected_line = self.html.key_value(
+            "ACKs Expected",
+            str(obj.acks_expected)
+        ) if obj.acks_expected else None
+
+        # Delivery rate
+        rate_line = None
+        if obj.acks_expected and obj.delivery_rate is not None:
+            rate_pct = obj.delivery_rate * 100
+            rate_line = self.html.key_value(
+                "Delivery Rate",
+                self.html.number(rate_pct, precision=1, suffix="%")
+            )
+
+        return self.html.breakdown(timeout_line, received_line, expected_line, rate_line)
+
+    delivery_stats_display.short_description = "Delivery Statistics"
+
+    # Fieldsets for detail view
+    def get_fieldsets(self, request, obj=None):
+        """Dynamic fieldsets based on object state."""
+        fieldsets = [
+            (
+                "Publish Information",
+                {"fields": ("id", "message_id", "channel", "user", "status")},
+            ),
+            (
+                "Message Data",
+                {"fields": ("data_display",), "classes": ("collapse",)},
+            ),
+            ("Performance", {"fields": ("duration_ms", "created_at", "completed_at")}),
+            ("Metadata", {"fields": ("caller_ip", "user_agent"), "classes": ("collapse",)}),
+        ]
+
+        # Add ACK tracking section if enabled
+        if obj and obj.wait_for_ack:
+            fieldsets.insert(
+                2,
+                (
+                    "ACK Tracking",
+                    {
+                        "fields": (
+                            "delivery_stats_display",
+                            "wait_for_ack",
+                            "ack_timeout",
+                            "acks_received",
+                            "acks_expected",
+                        )
+                    },
+                ),
+            )
+
+        # Add error section only if failed
+        if obj and not obj.is_successful and obj.status != "pending":
+            fieldsets.insert(
+                3,
+                (
+                    "Error Details",
+                    {"fields": ("error_details_display", "error_code", "error_message")},
+                ),
+            )
+
+        return fieldsets
+
+
+__all__ = ["CentrifugoLogAdmin"]

django_cfg/apps/integrations/centrifugo/admin/config.py

@@ -0,0 +1,82 @@
+"""
+Admin configuration for Centrifugo models.
+
+Declarative AdminConfig using PydanticAdmin patterns.
+"""
+
+from django_cfg.modules.django_admin import (
+    AdminConfig,
+    BadgeField,
+    DateTimeField,
+    Icons,
+    UserField,
+)
+
+from ..models import CentrifugoLog
+
+
+# Declarative configuration for CentrifugoLog
+centrifugolog_config = AdminConfig(
+    model=CentrifugoLog,
+    # Performance optimization
+    select_related=["user"],
+
+    # List display
+    list_display=[
+        "channel",
+        "type_badge",
+        "status",
+        "user",
+        "acks_display",
+        "duration_display",
+        "created_at",
+        "completed_at"
+    ],
+
+    # Auto-generated display methods
+    display_fields=[
+        BadgeField(name="channel", title="Channel", variant="info", icon=Icons.NOTIFICATIONS),
+        BadgeField(
+            name="status",
+            title="Status",
+            label_map={
+                "pending": "warning",
+                "success": "success",
+                "failed": "danger",
+                "timeout": "danger",
+                "partial": "warning",
+            },
+        ),
+        UserField(name="user", title="User", header=True),
+        DateTimeField(name="created_at", title="Created", ordering="created_at"),
+        DateTimeField(name="completed_at", title="Completed", ordering="completed_at"),
+    ],
+    # Filters
+    list_filter=["status", "wait_for_ack", "channel", "created_at"],
+    search_fields=[
+        "message_id",
+        "channel",
+        "user__username",
+        "user__email",
+        "error_message",
+    ],
+    # Autocomplete for user field
+    autocomplete_fields=["user"],
+    # Readonly fields
+    readonly_fields=[
+        "id",
+        "message_id",
+        "created_at",
+        "completed_at",
+        "data_display",
+        "error_details_display",
+        "delivery_stats_display",
+    ],
+    # Date hierarchy
+    date_hierarchy="created_at",
+    # Per page
+    list_per_page=50,
+)
+
+
+__all__ = ["centrifugolog_config"]