django-cfg 1.4.114__py3-none-any.whl → 1.5.8__py3-none-any.whl

django_cfg/apps/{centrifugo → integrations/centrifugo}/admin/centrifugo_log.py

@@ -96,7 +96,7 @@ class CentrifugoLogAdmin(PydanticAdmin):
 
         try:
             formatted = json.dumps(obj.data, indent=2)
-            return f'<pre style="background: #f5f5f5; padding: 10px; border-radius: 4px; max-height: 400px; overflow: auto; font-size: 12px; line-height: 1.5;">{formatted}</pre>'
+            return self.html.code_block(formatted, language="json", max_height="400px")
         except Exception:
             return str(obj.data)
 
@@ -106,37 +106,22 @@ class CentrifugoLogAdmin(PydanticAdmin):
         """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.span("No errors", "text-green-600"),
-                ]
+                self.html.icon(Icons.CHECK_CIRCLE, size="sm"),
+                self.html.text("No errors", variant="success"),
+                separator=" "
             )
 
-        details = []
-
-        if obj.error_code:
-            details.append(
-                self.html.inline(
-                    [
-                        self.html.span("Error Code:", "font-semibold"),
-                        self.html.badge(obj.error_code, variant="danger", icon=Icons.ERROR),
-                    ],
-                    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
 
-        if obj.error_message:
-            details.append(
-                self.html.inline(
-                    [
-                        self.html.span("Message:", "font-semibold"),
-                        self.html.span(obj.error_message, "text-red-600"),
-                    ],
-                    separator=" ",
-                )
-            )
+        error_msg_line = self.html.key_value(
+            "Message",
+            self.html.text(obj.error_message, variant="danger")
+        ) if obj.error_message else None
 
-        return "<br>".join(details) if details else self.html.empty()
+        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"
 
@@ -145,57 +130,34 @@ class CentrifugoLogAdmin(PydanticAdmin):
         if not obj.wait_for_ack:
             return self.html.empty("No ACK tracking")
 
-        stats = []
-
         # ACK timeout
-        if obj.ack_timeout:
-            stats.append(
-                self.html.inline(
-                    [
-                        self.html.span("Timeout:", "font-semibold"),
-                        self.html.span(f"{obj.ack_timeout}s", "text-gray-600"),
-                    ],
-                    separator=" ",
-                )
-            )
+        timeout_line = self.html.key_value(
+            "Timeout",
+            f"{obj.ack_timeout}s"
+        ) if obj.ack_timeout else None
 
         # ACKs received
-        stats.append(
-            self.html.inline(
-                [
-                    self.html.span("ACKs Received:", "font-semibold"),
-                    self.html.badge(str(obj.acks_received), variant="info"),
-                ],
-                separator=" ",
-            )
+        received_line = self.html.key_value(
+            "ACKs Received",
+            self.html.badge(str(obj.acks_received), variant="info")
         )
 
         # ACKs expected (if known)
-        if obj.acks_expected:
-            stats.append(
-                self.html.inline(
-                    [
-                        self.html.span("ACKs Expected:", "font-semibold"),
-                        self.html.span(str(obj.acks_expected), "text-gray-600"),
-                    ],
-                    separator=" ",
-                )
+        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="%")
             )
 
-            # Delivery rate
-            if obj.delivery_rate is not None:
-                rate_pct = obj.delivery_rate * 100
-                stats.append(
-                    self.html.inline(
-                        [
-                            self.html.span("Delivery Rate:", "font-semibold"),
-                            self.html.span(f"{rate_pct:.1f}%", "text-blue-600"),
-                        ],
-                        separator=" ",
-                    )
-                )
-
-        return "<br>".join(stats) if stats else self.html.empty()
+        return self.html.breakdown(timeout_line, received_line, expected_line, rate_line)
 
     delivery_stats_display.short_description = "Delivery Statistics"
 

django_cfg/apps/integrations/centrifugo/apps.py

@@ -0,0 +1,100 @@
+"""
+Django app configuration for Centrifugo module.
+
+Provides Centrifugo pub/sub client with ACK tracking.
+"""
+
+from __future__ import annotations
+
+import os
+
+from django.apps import AppConfig
+
+
+class CentrifugoConfig(AppConfig):
+    """
+    Centrifugo application configuration.
+
+    Provides:
+    - Async client for publishing messages to Centrifugo
+    - ACK tracking for delivery confirmation
+    - Logging of all publish operations
+    - Migration-friendly API (mirrors legacy WebSocket solution patterns)
+    """
+
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "django_cfg.apps.integrations.centrifugo"
+    label = "django_cfg_centrifugo"
+    verbose_name = "Centrifugo WebSocket"
+
+    def ready(self):
+        """
+        Initialize app when Django starts.
+
+        Validates that all required Centrifugo dependencies are installed.
+        """
+        from django_cfg.modules.django_logging import get_logger
+
+        logger = get_logger("centrifugo.apps")
+
+        # Check dependencies if needed (only when using Centrifugo features)
+        self._check_dependencies_if_needed()
+
+        logger.info("Centrifugo app initialized")
+
+    def _check_dependencies_if_needed(self):
+        """
+        Check Centrifugo dependencies only when needed.
+
+        Skips check for:
+        - Migrations (makemigrations, migrate)
+        - Shell commands (shell, shell_plus)
+        - Test discovery (test --help)
+        - Django checks (check)
+        - Management command listing (help)
+        """
+        import sys
+
+        # Get command name from sys.argv
+        if len(sys.argv) < 2:
+            return
+
+        command = sys.argv[1]
+
+        # Commands that don't need Centrifugo dependencies
+        skip_commands = [
+            'makemigrations',
+            'migrate',
+            'shell',
+            'shell_plus',
+            'check',
+            'help',
+            'test',
+            'collectstatic',
+            'createsuperuser',
+            'changepassword',
+            'showmigrations',
+            'sqlmigrate',
+            'inspectdb',
+        ]
+
+        # Skip check for these commands
+        if command in skip_commands:
+            return
+
+        # Also skip if running tests (pytest, nose, etc.)
+        if 'test' in sys.argv or 'pytest' in sys.argv[0]:
+            return
+
+        # Skip if DJANGO_SKIP_CENTRIFUGO_CHECK environment variable is set
+        if os.environ.get('DJANGO_SKIP_CENTRIFUGO_CHECK', '').lower() in ('1', 'true', 'yes'):
+            return
+
+        # For commands that may use Centrifugo, perform silent check
+        from ._cfg import check_centrifugo_dependencies
+        try:
+            # Silent check - only validates that checker itself works
+            check_centrifugo_dependencies(raise_on_missing=False)
+        except Exception:
+            # Silently ignore - don't break other commands
+            pass

django_cfg/apps/{centrifugo → integrations/centrifugo}/management/commands/generate_centrifugo_clients.py

@@ -13,11 +13,11 @@ from typing import List
 from django.core.management.base import BaseCommand, CommandError
 from django.utils.termcolors import colorize
 
-from django_cfg.apps.centrifugo.codegen.discovery import discover_rpc_methods_from_router
-from django_cfg.apps.centrifugo.codegen.generators.python_thin import PythonThinGenerator
-from django_cfg.apps.centrifugo.codegen.generators.typescript_thin import TypeScriptThinGenerator
-from django_cfg.apps.centrifugo.codegen.generators.go_thin import GoThinGenerator
-from django_cfg.apps.centrifugo.router import get_global_router
+from django_cfg.apps.integrations.centrifugo.codegen.discovery import discover_rpc_methods_from_router
+from django_cfg.apps.integrations.centrifugo.codegen.generators.python_thin import PythonThinGenerator
+from django_cfg.apps.integrations.centrifugo.codegen.generators.typescript_thin import TypeScriptThinGenerator
+from django_cfg.apps.integrations.centrifugo.codegen.generators.go_thin import GoThinGenerator
+from django_cfg.apps.integrations.centrifugo.router import get_global_router
 
 logger = logging.getLogger(__name__)
 

django_cfg/apps/{centrifugo → integrations/centrifugo}/serializers/__init__.py

@@ -17,12 +17,12 @@ from .admin_api import (
 from .channels import ChannelListSerializer, ChannelStatsSerializer
 from .health import HealthCheckSerializer
 from .publishes import RecentPublishesSerializer
-from .stats import OverviewStatsSerializer
+from .stats import CentrifugoOverviewStatsSerializer
 
 __all__ = [
     # Monitoring API (Django logs)
     "HealthCheckSerializer",
-    "OverviewStatsSerializer",
+    "CentrifugoOverviewStatsSerializer",
     "RecentPublishesSerializer",
     "ChannelStatsSerializer",
     "ChannelListSerializer",

django_cfg/apps/{centrifugo → integrations/centrifugo}/serializers/stats.py

@@ -5,7 +5,7 @@ Statistics serializers for Centrifugo monitoring API.
 from pydantic import BaseModel, Field
 
 
-class OverviewStatsSerializer(BaseModel):
+class CentrifugoOverviewStatsSerializer(BaseModel):
     """Overview statistics for Centrifugo publishes."""
 
     total: int = Field(description="Total publishes in period")
@@ -18,4 +18,4 @@ class OverviewStatsSerializer(BaseModel):
     period_hours: int = Field(description="Statistics period in hours")
 
 
-__all__ = ["OverviewStatsSerializer"]
+__all__ = ["CentrifugoOverviewStatsSerializer"]

django_cfg/apps/{centrifugo → integrations/centrifugo}/services/client/client.py

@@ -54,7 +54,7 @@ class CentrifugoClient:
     - Mirrors DjangoCfgRPCClient interface for migration
 
     Example:
-        >>> from django_cfg.apps.centrifugo import get_centrifugo_client
+        >>> from django_cfg.apps.integrations.centrifugo import get_centrifugo_client
         >>>
         >>> client = get_centrifugo_client()
         >>>
@@ -525,7 +525,7 @@ def get_centrifugo_client(force_new: bool = False) -> CentrifugoClient:
         CentrifugoClient instance
 
     Example:
-        >>> from django_cfg.apps.centrifugo import get_centrifugo_client
+        >>> from django_cfg.apps.integrations.centrifugo import get_centrifugo_client
         >>> client = get_centrifugo_client()
         >>> result = await client.publish_with_ack(...)
     """

django_cfg/apps/{centrifugo → integrations/centrifugo}/services/client/config.py

@@ -17,7 +17,7 @@ class DjangoCfgCentrifugoConfig(BaseModel):
 
     Example:
         >>> from django_cfg import DjangoConfig
-        >>> from django_cfg.apps.centrifugo import DjangoCfgCentrifugoConfig
+        >>> from django_cfg.apps.integrations.centrifugo import DjangoCfgCentrifugoConfig
         >>>
         >>> config = DjangoConfig(
         ...     centrifugo=DjangoCfgCentrifugoConfig(

django_cfg/apps/{centrifugo → integrations/centrifugo}/views/monitoring.py

@@ -19,10 +19,10 @@ from rest_framework.response import Response
 from django_cfg.mixins import AdminAPIMixin
 from ..models import CentrifugoLog
 from ..serializers import (
+    CentrifugoOverviewStatsSerializer,
     ChannelListSerializer,
     ChannelStatsSerializer,
     HealthCheckSerializer,
-    OverviewStatsSerializer,
     RecentPublishesSerializer,
 )
 from ..services import get_centrifugo_config
@@ -94,7 +94,7 @@ class CentrifugoMonitorViewSet(AdminAPIMixin, viewsets.ViewSet):
             ),
         ],
         responses={
-            200: OverviewStatsSerializer,
+            200: CentrifugoOverviewStatsSerializer,
             400: {"description": "Invalid parameters"},
         },
     )
@@ -108,7 +108,7 @@ class CentrifugoMonitorViewSet(AdminAPIMixin, viewsets.ViewSet):
             stats = CentrifugoLog.objects.get_statistics(hours=hours)
             stats["period_hours"] = hours
 
-            serializer = OverviewStatsSerializer(**stats)
+            serializer = CentrifugoOverviewStatsSerializer(**stats)
             return Response(serializer.model_dump())
 
         except ValueError as e:

django_cfg/apps/integrations/grpc/__init__.py

@@ -0,0 +1,9 @@
+"""
+django_cfg.apps.integrations.grpc
+
+gRPC integration for django-cfg with Django ORM, JWT auth, monitoring, and admin interface.
+"""
+
+default_app_config = 'django_cfg.apps.integrations.grpc.apps.GRPCAppConfig'
+
+__version__ = '1.0.0'

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

@@ -0,0 +1,307 @@
+# gRPC Dependency Checker
+
+Automatic dependency checking for gRPC integration in django-cfg.
+
+## 🎯 Purpose
+
+Checks for all required libraries before starting the gRPC server and provides a clear message with installation instructions if anything is missing.
+
+## 📦 Dependencies Checked
+
+### Required
+- `grpcio` - Core gRPC framework
+- `grpcio-tools` - Protocol Buffer compiler and tools
+- `protobuf` - Protocol Buffers runtime
+
+### Optional (Recommended)
+- `grpcio-reflection` - Server reflection API (for grpcurl/grpcui)
+- `grpcio-health-checking` - Health check service
+
+## 🚀 Usage
+
+### Automatic check on startup
+
+The check happens automatically when running the command:
+
+```bash
+python manage.py rungrpc
+```
+
+If dependencies are missing, you will see a detailed message:
+
+```
+================================================================================
+❌ MISSING gRPC DEPENDENCIES
+================================================================================
+
+Django-CFG's gRPC integration requires additional dependencies that are not installed.
+
+📦 REQUIRED (missing):
+
+  ❌ grpcio                        - Core gRPC framework
+  ❌ grpcio-tools                  - Protocol Buffer compiler and tools
+  ❌ protobuf                      - Protocol Buffers runtime
+
+================================================================================
+🔧 HOW TO FIX
+================================================================================
+
+Option 1: Install all gRPC dependencies at once (RECOMMENDED):
+
+  pip install django-cfg[grpc]
+
+  # or with poetry:
+  poetry add django-cfg[grpc]
+
+Option 2: Install dependencies manually:
+
+  pip install grpcio grpcio-tools protobuf
+
+================================================================================
+```
+
+### Manual check
+
+#### In Python code:
+
+```python
+from django_cfg.apps.grpc.utils.dependencies import check_grpc_dependencies
+
+# Check with error on missing
+try:
+    check_grpc_dependencies(raise_on_missing=True)
+    print("✅ All dependencies installed")
+except Exception as e:
+    print(f"❌ Error: {e}")
+
+# Check without raising error
+status = check_grpc_dependencies(raise_on_missing=False)
+print(status)  # {'grpcio': True, 'grpcio-tools': True, ...}
+```
+
+#### Print status of all dependencies:
+
+```python
+from django_cfg.apps.grpc.utils.dependencies import print_dependency_status
+
+print_dependency_status()
+```
+
+Output:
+```
+gRPC Dependencies Status:
+============================================================
+
+Required:
+  ✅ grpcio                     1.60.0          - Core gRPC framework
+  ✅ grpcio-tools               1.60.0          - Protocol Buffer compiler and tools
+  ✅ protobuf                   5.27.0          - Protocol Buffers runtime
+
+Optional (recommended):
+  ✅ grpcio-reflection          1.60.0          - Server reflection API (for grpcurl/grpcui)
+  ✅ grpcio-health-checking     1.60.0          - Health check service
+
+============================================================
+```
+
+#### Standalone script:
+
+```bash
+# From project root
+poetry run python -m django_cfg.apps.grpc.utils.check_deps
+
+# Or directly
+poetry run python src/django_cfg/apps/grpc/utils/check_deps.py
+```
+
+### Get library versions
+
+```python
+from django_cfg.apps.grpc.utils.dependencies import DependencyChecker
+
+versions = DependencyChecker.get_version_info()
+print(f"gRPC version: {versions['grpcio']}")
+```
+
+## ⚙️ Configuration
+
+### Disable checking
+
+If you need to temporarily disable checking (for example, for testing):
+
+```bash
+export DJANGO_SKIP_GRPC_CHECK=1
+python manage.py rungrpc
+```
+
+Or in code:
+```python
+import os
+os.environ['DJANGO_SKIP_GRPC_CHECK'] = '1'
+```
+
+### Commands where checking is NOT performed
+
+Checking is automatically skipped for:
+- `makemigrations`, `migrate`
+- `shell`, `shell_plus`
+- `test`
+- `check`
+- `help`
+- `collectstatic`
+- `createsuperuser`
+- And other administrative commands
+
+For the `rungrpc` command, checking is **always** performed (strict check).
+
+## 🔧 Integration in your code
+
+### In Django AppConfig
+
+```python
+from django.apps import AppConfig
+from django_cfg.apps.grpc.utils.dependencies import check_grpc_dependencies
+
+class MyAppConfig(AppConfig):
+    name = 'myapp'
+
+    def ready(self):
+        # Check dependencies on app startup
+        try:
+            check_grpc_dependencies(raise_on_missing=True)
+        except Exception as e:
+            print(e)
+            import sys
+            sys.exit(1)
+```
+
+### In management command
+
+```python
+from django.core.management.base import BaseCommand
+from django_cfg.apps.grpc.utils.dependencies import check_grpc_dependencies
+
+class Command(BaseCommand):
+    def handle(self, *args, **options):
+        # Check before running command
+        check_grpc_dependencies(raise_on_missing=True)
+
+        # Your code
+        ...
+```
+
+## 🎯 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_grpc_dependencies(raise_on_missing=True)`
+Checks all gRPC dependencies.
+
+**Parameters:**
+- `raise_on_missing` (bool): Raise `GRPCDependencyError` when dependencies are missing
+
+**Returns:** `Dict[str, bool]` - status of each dependency
+
+**Raises:** `GRPCDependencyError` 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.
+
+### `GRPCDependencyError`
+Exception that is raised when required dependencies are missing.
+
+## 🧪 Testing
+
+```python
+import pytest
+from django_cfg.apps.grpc.utils.dependencies import (
+    check_grpc_dependencies,
+    GRPCDependencyError
+)
+
+def test_grpc_dependencies_installed():
+    """Test: all dependencies installed"""
+    status = check_grpc_dependencies(raise_on_missing=False)
+    assert status['grpcio'] is True
+    assert status['grpcio-tools'] is True
+    assert status['protobuf'] is True
+
+def test_missing_dependencies_raises_error():
+    """Test: error is raised when dependencies are missing"""
+    # This test should run in an environment without grpc
+    with pytest.raises(GRPCDependencyError):
+        check_grpc_dependencies(raise_on_missing=True)
+```
+
+## 📖 Usage Examples
+
+### Example 1: Check in CI/CD
+
+```yaml
+# .github/workflows/test.yml
+- name: Check gRPC dependencies
+  run: |
+    poetry run python -m django_cfg.apps.grpc.utils.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.grpc.utils.check_deps
+if [ $? -ne 0 ]; then
+    echo "❌ gRPC dependencies missing. Run: pip install django-cfg[grpc]"
+    exit 1
+fi
+```
+
+### Example 3: Docker healthcheck
+
+```dockerfile
+# Dockerfile
+HEALTHCHECK --interval=30s --timeout=3s \
+  CMD python -m django_cfg.apps.grpc.utils.check_deps || exit 1
+```
+
+## 🐛 Troubleshooting
+
+### False positives
+
+If the check shows libraries are missing but they are installed:
+
+```bash
+# Check current environment
+which python
+pip list | grep grpc
+
+# Make sure you're using the correct interpreter
+poetry env info
+```
+
+### Check not triggering
+
+Make sure that:
+1. `django_cfg.apps.grpc` is added to `INSTALLED_APPS`
+2. You are running the `rungrpc` command
+3. The `DJANGO_SKIP_GRPC_CHECK` variable is not set
+
+## 🔗 See also
+
+- [gRPC Integration Overview](../../../@docs/architecture/integration-overview.md)
+- [Getting Started with gRPC](../../../@docs/guides/getting-started.md)
+- [Troubleshooting Guide](../../../@docs/guides/troubleshooting.md)

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

@@ -0,0 +1,25 @@
+"""
+gRPC System Configuration.
+
+Internal system utilities for configuration, dependency checking, and validation.
+This module is for system/internal use. For public API, use `utils/` instead.
+"""
+
+from .dependencies import (
+    DependencyChecker,
+    GRPCDependencyError,
+    check_grpc_available,
+    check_grpc_dependencies,
+    print_dependency_status,
+    require_grpc_feature,
+)
+
+__all__ = [
+    # Dependency checking
+    "DependencyChecker",
+    "GRPCDependencyError",
+    "check_grpc_available",
+    "check_grpc_dependencies",
+    "require_grpc_feature",
+    "print_dependency_status",
+]