django-cfg 1.4.48__py3-none-any.whl → 1.5.7__py3-none-any.whl

django_cfg/apps/integrations/centrifugo/__init__.py

@@ -0,0 +1,57 @@
+"""
+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.config import DjangoCfgCentrifugoConfig
+from .services.client.exceptions import (
+    CentrifugoBaseException,
+    CentrifugoConfigurationError,
+    CentrifugoConnectionError,
+    CentrifugoPublishError,
+    CentrifugoTimeoutError,
+    CentrifugoValidationError,
+)
+from .services.logging import CentrifugoLogContext, CentrifugoLogger
+
+# 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",
+    "get_centrifugo_client",
+    "PublishResponse",
+    # Logging
+    "CentrifugoLogger",
+    "CentrifugoLogContext",
+    # Exceptions
+    "CentrifugoBaseException",
+    "CentrifugoTimeoutError",
+    "CentrifugoPublishError",
+    "CentrifugoConnectionError",
+    "CentrifugoConfigurationError",
+    "CentrifugoValidationError",
+]

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)

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",
+]