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

django_cfg/modules/django_telegram/management/commands/test_telegram.py

@@ -4,20 +4,13 @@ Test Telegram Command
 Tests Telegram notification functionality using django_cfg configuration.
 """
 
-from django.core.management.base import BaseCommand
+from django_cfg.management.utils import SafeCommand
 
-from django_cfg.modules.django_logging import get_logger
 
-logger = get_logger('test_telegram')
-
-class Command(BaseCommand):
+class Command(SafeCommand):
     """Command to test Telegram functionality."""
 
-    # Web execution metadata
-    web_executable = True
-    requires_input = False
-    is_destructive = False
-
+    command_name = 'test_telegram'
     help = "Test Telegram notification functionality"
 
     def add_arguments(self, parser):
@@ -29,7 +22,7 @@ class Command(BaseCommand):
         )
 
     def handle(self, *args, **options):
-        logger.info("Starting test_telegram command")
+        self.logger.info("Starting test_telegram command")
         message = options["message"]
 
         self.stdout.write("🚀 Testing Telegram notification service")

django_cfg/modules/django_telegram/service.py

@@ -4,7 +4,10 @@ Django Telegram Service for django_cfg.
 Auto-configuring Telegram notification service that integrates with DjangoConfig.
 """
 
-import logging
+import itertools
+import queue
+import threading
+import time
 from enum import Enum
 from typing import Any, BinaryIO, Dict, Optional, Union
 
@@ -12,8 +15,177 @@ import telebot
 import yaml
 
 from ..base import BaseCfgModule
+from ..django_logging import get_logger
 
-logger = logging.getLogger(__name__)
+logger = get_logger("django_cfg.telegram")
+
+
+class MessagePriority:
+    """Message priority levels for Telegram queue."""
+    CRITICAL = 1  # Security alerts, critical errors
+    HIGH = 2      # Errors, important warnings
+    NORMAL = 3    # Info, success messages
+    LOW = 4       # Debug, non-urgent notifications
+
+
+class TelegramMessageQueue:
+    """
+    Global singleton queue for all Telegram messages with rate limiting and auto-cleanup.
+
+    Ensures we don't hit Telegram API limits:
+    - 30 messages/sec to different chats
+    - 1 message/sec to same chat
+
+    We use conservative 20 msg/sec (0.05s delay) to be safe.
+
+    Queue protection:
+    - Max queue size: 1000 messages
+    - Auto-cleanup: drops LOW priority messages when > 800
+    - Emergency cleanup: drops NORMAL when > 900
+    - Critical always kept
+    """
+
+    _instance = None
+    _lock = threading.Lock()
+
+    # Queue size limits
+    MAX_QUEUE_SIZE = 1000
+    WARNING_THRESHOLD = 800  # Start dropping LOW priority
+    CRITICAL_THRESHOLD = 900  # Start dropping NORMAL priority
+
+    def __new__(cls):
+        if cls._instance is None:
+            with cls._lock:
+                if cls._instance is None:
+                    cls._instance = super().__new__(cls)
+                    cls._instance._initialized = False
+        return cls._instance
+
+    def __init__(self):
+        if self._initialized:
+            return
+
+        self._initialized = True
+        self._queue = queue.PriorityQueue()  # Priority queue for message ordering
+        self._counter = itertools.count()  # Tie-breaker for same-priority items
+        self._worker = threading.Thread(target=self._process_queue, daemon=True, name="TelegramQueueWorker")
+        self._dropped_count = 0  # Track dropped messages
+        self._last_cleanup_warning = 0  # Timestamp of last warning
+        self._worker.start()
+        logger.info(
+            f"Telegram priority queue started: "
+            f"rate_limit=20msg/sec, max_size={self.MAX_QUEUE_SIZE}, "
+            f"auto_cleanup_at={self.WARNING_THRESHOLD}"
+        )
+
+    def _process_queue(self):
+        """Worker thread that processes queued messages with rate limiting."""
+        while True:
+            try:
+                # PriorityQueue returns (priority, count, item)
+                priority, _count, (func, args, kwargs) = self._queue.get(timeout=1)
+
+                try:
+                    func(*args, **kwargs)
+                    logger.debug(f"Processed telegram message with priority {priority}")
+                except Exception as e:
+                    logger.error(f"Telegram queue processing error: {e}")
+                finally:
+                    self._queue.task_done()
+                    # Rate limit: 20 messages per second (0.05s delay)
+                    time.sleep(0.05)
+
+            except queue.Empty:
+                # No messages, continue waiting
+                continue
+            except Exception as e:
+                logger.error(f"Telegram queue worker error: {e}")
+                time.sleep(1)  # Back off on errors
+
+    def enqueue(self, func, priority=MessagePriority.NORMAL, *args, **kwargs):
+        """
+        Add a message to the queue with priority and smart cleanup.
+
+        Args:
+            func: Function to execute
+            priority: Message priority (1=CRITICAL, 2=HIGH, 3=NORMAL, 4=LOW)
+            *args: Positional arguments for func
+            **kwargs: Keyword arguments for func
+        """
+        current_size = self._queue.qsize()
+
+        # Check if we need to drop this message
+        if current_size >= self.MAX_QUEUE_SIZE:
+            # Queue is full - drop everything except CRITICAL
+            if priority > MessagePriority.CRITICAL:
+                self._dropped_count += 1
+                logger.warning(
+                    f"Queue FULL ({current_size}/{self.MAX_QUEUE_SIZE}): "
+                    f"Dropped priority={priority} message. Total dropped: {self._dropped_count}"
+                )
+                return
+            else:
+                logger.critical(
+                    f"Queue FULL but CRITICAL message queued anyway: {current_size}/{self.MAX_QUEUE_SIZE}"
+                )
+
+        elif current_size >= self.CRITICAL_THRESHOLD:
+            # Emergency mode: drop NORMAL and LOW
+            if priority >= MessagePriority.NORMAL:
+                self._dropped_count += 1
+                if time.time() - self._last_cleanup_warning > 60:  # Warn once per minute
+                    logger.warning(
+                        f"Queue CRITICAL ({current_size}/{self.MAX_QUEUE_SIZE}): "
+                        f"Dropping NORMAL/LOW priority messages. Dropped: {self._dropped_count}"
+                    )
+                    self._last_cleanup_warning = time.time()
+                return
+
+        elif current_size >= self.WARNING_THRESHOLD:
+            # Warning mode: drop only LOW priority
+            if priority == MessagePriority.LOW:
+                self._dropped_count += 1
+                if time.time() - self._last_cleanup_warning > 60:  # Warn once per minute
+                    logger.warning(
+                        f"Queue WARNING ({current_size}/{self.MAX_QUEUE_SIZE}): "
+                        f"Dropping LOW priority messages. Dropped: {self._dropped_count}"
+                    )
+                    self._last_cleanup_warning = time.time()
+                return
+
+        # Queue the message with counter for tie-breaking (avoids comparing functions)
+        count = next(self._counter)
+        self._queue.put((priority, count, (func, args, kwargs)))
+        logger.debug(
+            f"Telegram message queued with priority {priority} "
+            f"(size: {current_size + 1}/{self.MAX_QUEUE_SIZE})"
+        )
+
+    def size(self) -> int:
+        """Get current queue size."""
+        return self._queue.qsize()
+
+    def get_stats(self) -> dict:
+        """Get queue statistics."""
+        current_size = self._queue.qsize()
+        return {
+            "queue_size": current_size,
+            "max_size": self.MAX_QUEUE_SIZE,
+            "usage_percent": round((current_size / self.MAX_QUEUE_SIZE) * 100, 1),
+            "dropped_total": self._dropped_count,
+            "warning_threshold": self.WARNING_THRESHOLD,
+            "critical_threshold": self.CRITICAL_THRESHOLD,
+            "status": (
+                "FULL" if current_size >= self.MAX_QUEUE_SIZE
+                else "CRITICAL" if current_size >= self.CRITICAL_THRESHOLD
+                else "WARNING" if current_size >= self.WARNING_THRESHOLD
+                else "OK"
+            ),
+        }
+
+
+# Global singleton instance
+_telegram_queue = TelegramMessageQueue()
 
 
 class TelegramParseMode(Enum):
@@ -45,6 +217,9 @@ class DjangoTelegram(BaseCfgModule):
 
     Provides Telegram messaging functionality with automatic configuration
     from the main DjangoConfig instance.
+
+    All messages are queued through a global singleton queue with rate limiting
+    (20 messages/second) to avoid hitting Telegram API limits.
     """
 
     # Emoji mappings for different message types
@@ -68,6 +243,17 @@ class DjangoTelegram(BaseCfgModule):
         """Get the DjangoConfig instance."""
         return self.get_config()
 
+    @property
+    def project_prefix(self) -> str:
+        """Get project name prefix for messages."""
+        try:
+            config = self.config
+            if config and hasattr(config, 'project_name') and config.project_name:
+                return f"[{config.project_name}] "
+        except Exception:
+            pass
+        return ""
+
     @property
     def is_configured(self) -> bool:
         """Check if Telegram is properly configured."""
@@ -98,13 +284,16 @@ class DjangoTelegram(BaseCfgModule):
         return self._bot
 
     def get_config_info(self) -> Dict[str, Any]:
-        """Get Telegram configuration information."""
+        """Get Telegram configuration information with queue stats."""
+        queue_stats = _telegram_queue.get_stats()
+
         if not self.is_configured:
             return {
                 "configured": False,
                 "bot_token": "Not configured",
                 "chat_id": "Not configured",
                 "enabled": False,
+                **queue_stats,
             }
 
         telegram_config = self.config.telegram
@@ -114,8 +303,32 @@ class DjangoTelegram(BaseCfgModule):
             "chat_id": telegram_config.chat_id or "Not set",
             "enabled": True,
             "parse_mode": telegram_config.parse_mode or "None",
+            "rate_limit": "20 messages/second",
+            **queue_stats,
         }
 
+    @staticmethod
+    def get_queue_size() -> int:
+        """Get current number of messages in the global queue."""
+        return _telegram_queue.size()
+
+    @staticmethod
+    def get_queue_stats() -> dict:
+        """Get detailed queue statistics."""
+        return _telegram_queue.get_stats()
+
+    def _enqueue_message(self, func, priority=MessagePriority.NORMAL, *args, **kwargs):
+        """
+        Add message to global queue with priority and rate limiting.
+
+        Args:
+            func: Function to execute
+            priority: Message priority (1=CRITICAL, 2=HIGH, 3=NORMAL, 4=LOW)
+            *args: Positional arguments for the function
+            **kwargs: Keyword arguments for the function
+        """
+        _telegram_queue.enqueue(func, priority, *args, **kwargs)
+
     def send_message(
         self,
         message: str,
@@ -124,9 +337,13 @@ class DjangoTelegram(BaseCfgModule):
         disable_notification: bool = False,
         reply_to_message_id: Optional[int] = None,
         fail_silently: bool = False,
+        priority: int = MessagePriority.NORMAL,
     ) -> bool:
         """
-        Send a text message to Telegram.
+        Send a text message to Telegram via global queue (non-blocking, rate-limited).
+
+        Messages are queued and sent at max 20 msg/sec to avoid Telegram API limits.
+        Higher priority messages (lower number) are sent first.
 
         Args:
             message: Message text to send
@@ -135,9 +352,10 @@ class DjangoTelegram(BaseCfgModule):
             disable_notification: Send silently
             reply_to_message_id: Reply to specific message
             fail_silently: Don't raise exceptions on failure
+            priority: Message priority (1=CRITICAL, 2=HIGH, 3=NORMAL, 4=LOW)
 
         Returns:
-            True if message sent successfully, False otherwise
+            True if message queued successfully, False otherwise
         """
         try:
             if not self.is_configured:
@@ -167,15 +385,21 @@ class DjangoTelegram(BaseCfgModule):
             else:
                 parse_mode_str = None
 
-            self.bot.send_message(
-                chat_id=target_chat_id,
-                text=message,
-                parse_mode=parse_mode_str,
-                disable_notification=disable_notification,
-                reply_to_message_id=reply_to_message_id,
-            )
-
-            logger.info(f"Telegram message sent successfully to chat {target_chat_id}")
+            def _do_send():
+                # Add project prefix to message
+                prefixed_message = f"{self.project_prefix}{message}"
+
+                self.bot.send_message(
+                    chat_id=target_chat_id,
+                    text=prefixed_message,
+                    parse_mode=parse_mode_str,
+                    disable_notification=disable_notification,
+                    reply_to_message_id=reply_to_message_id,
+                )
+                logger.info(f"Telegram message sent successfully to chat {target_chat_id}")
+
+            # Always enqueue to global queue with rate limiting
+            self._enqueue_message(_do_send, priority=priority)
             return True
 
         except Exception as e:
@@ -192,9 +416,13 @@ class DjangoTelegram(BaseCfgModule):
         chat_id: Optional[Union[int, str]] = None,
         parse_mode: Optional[TelegramParseMode] = None,
         fail_silently: bool = False,
+        priority: int = MessagePriority.NORMAL,
     ) -> bool:
         """
-        Send a photo to Telegram.
+        Send a photo to Telegram via global queue (non-blocking, rate-limited).
+
+        Messages are queued and sent at max 20 msg/sec to avoid Telegram API limits.
+        Higher priority messages (lower number) are sent first.
 
         Args:
             photo: Photo file path, URL, or file-like object
@@ -202,9 +430,10 @@ class DjangoTelegram(BaseCfgModule):
             chat_id: Target chat ID (uses config default if not provided)
             parse_mode: Caption parse mode
             fail_silently: Don't raise exceptions on failure
+            priority: Message priority (1=CRITICAL, 2=HIGH, 3=NORMAL, 4=LOW)
 
         Returns:
-            True if photo sent successfully, False otherwise
+            True if photo queued successfully, False otherwise
         """
         try:
             if not self.is_configured:
@@ -235,14 +464,20 @@ class DjangoTelegram(BaseCfgModule):
             else:
                 parse_mode_str = None
 
-            self.bot.send_photo(
-                chat_id=target_chat_id,
-                photo=photo,
-                caption=caption,
-                parse_mode=parse_mode_str,
-            )
+            def _do_send():
+                # Add project prefix to caption if present
+                prefixed_caption = f"{self.project_prefix}{caption}" if caption else self.project_prefix.strip() if self.project_prefix else None
+
+                self.bot.send_photo(
+                    chat_id=target_chat_id,
+                    photo=photo,
+                    caption=prefixed_caption,
+                    parse_mode=parse_mode_str,
+                )
+                logger.info(f"Telegram photo sent successfully to chat {target_chat_id}")
 
-            logger.info(f"Telegram photo sent successfully to chat {target_chat_id}")
+            # Always enqueue to global queue with rate limiting
+            self._enqueue_message(_do_send, priority=priority)
             return True
 
         except Exception as e:
@@ -259,9 +494,13 @@ class DjangoTelegram(BaseCfgModule):
         chat_id: Optional[Union[int, str]] = None,
         parse_mode: Optional[TelegramParseMode] = None,
         fail_silently: bool = False,
+        priority: int = MessagePriority.NORMAL,
     ) -> bool:
         """
-        Send a document to Telegram.
+        Send a document to Telegram via global queue (non-blocking, rate-limited).
+
+        Messages are queued and sent at max 20 msg/sec to avoid Telegram API limits.
+        Higher priority messages (lower number) are sent first.
 
         Args:
             document: Document file path, URL, or file-like object
@@ -269,9 +508,10 @@ class DjangoTelegram(BaseCfgModule):
             chat_id: Target chat ID (uses config default if not provided)
             parse_mode: Caption parse mode
             fail_silently: Don't raise exceptions on failure
+            priority: Message priority (1=CRITICAL, 2=HIGH, 3=NORMAL, 4=LOW)
 
         Returns:
-            True if document sent successfully, False otherwise
+            True if document queued successfully, False otherwise
         """
         try:
             if not self.is_configured:
@@ -302,14 +542,20 @@ class DjangoTelegram(BaseCfgModule):
             else:
                 parse_mode_str = None
 
-            self.bot.send_document(
-                chat_id=target_chat_id,
-                document=document,
-                caption=caption,
-                parse_mode=parse_mode_str,
-            )
+            def _do_send():
+                # Add project prefix to caption if present
+                prefixed_caption = f"{self.project_prefix}{caption}" if caption else self.project_prefix.strip() if self.project_prefix else None
+
+                self.bot.send_document(
+                    chat_id=target_chat_id,
+                    document=document,
+                    caption=prefixed_caption,
+                    parse_mode=parse_mode_str,
+                )
+                logger.info(f"Telegram document sent successfully to chat {target_chat_id}")
 
-            logger.info(f"Telegram document sent successfully to chat {target_chat_id}")
+            # Always enqueue to global queue with rate limiting
+            self._enqueue_message(_do_send, priority=priority)
             return True
 
         except Exception as e:
@@ -363,59 +609,59 @@ class DjangoTelegram(BaseCfgModule):
 
     @classmethod
     def send_error(cls, error: str, context: Optional[Dict[str, Any]] = None) -> None:
-        """Send error notification."""
+        """Send error notification with HIGH priority."""
         try:
             telegram = cls()
             text = f"{cls.EMOJI_MAP['error']} <b>Error</b>\n\n{error}"
             if context:
                 text += "\n\n<pre>" + cls._format_to_yaml(context) + "</pre>"
-            telegram.send_message(text, parse_mode=TelegramParseMode.HTML)
+            telegram.send_message(text, parse_mode=TelegramParseMode.HTML, priority=MessagePriority.HIGH)
         except Exception:
             # Silently fail - error notifications should not cause cascading failures
             pass
 
     @classmethod
     def send_success(cls, message: str, details: Optional[Dict[str, Any]] = None) -> None:
-        """Send success notification."""
+        """Send success notification with NORMAL priority."""
         try:
             telegram = cls()
             text = f"{cls.EMOJI_MAP['success']} <b>Success</b>\n\n{message}"
             if details:
                 text += "\n\n<pre>" + cls._format_to_yaml(details) + "</pre>"
-            telegram.send_message(text, parse_mode=TelegramParseMode.HTML)
+            telegram.send_message(text, parse_mode=TelegramParseMode.HTML, priority=MessagePriority.NORMAL)
         except Exception:
             # Silently fail - success notifications should not cause failures
             pass
 
     @classmethod
     def send_warning(cls, warning: str, context: Optional[Dict[str, Any]] = None) -> None:
-        """Send warning notification."""
+        """Send warning notification with HIGH priority."""
         try:
             telegram = cls()
             text = f"{cls.EMOJI_MAP['warning']} <b>Warning</b>\n\n{warning}"
             if context:
                 text += "\n\n<pre>" + cls._format_to_yaml(context) + "</pre>"
-            telegram.send_message(text, parse_mode=TelegramParseMode.HTML)
+            telegram.send_message(text, parse_mode=TelegramParseMode.HTML, priority=MessagePriority.HIGH)
         except Exception:
             # Silently fail - warning notifications should not cause failures
             pass
 
     @classmethod
     def send_info(cls, message: str, data: Optional[Dict[str, Any]] = None) -> None:
-        """Send informational message."""
+        """Send informational message with NORMAL priority."""
         telegram = cls()
         text = f"{cls.EMOJI_MAP['info']} <b>Info</b>\n\n{message}"
         if data:
             text += "\n\n<pre>" + cls._format_to_yaml(data) + "</pre>"
-        telegram.send_message(text, parse_mode=TelegramParseMode.HTML)
+        telegram.send_message(text, parse_mode=TelegramParseMode.HTML, priority=MessagePriority.NORMAL)
 
     @classmethod
     def send_stats(cls, title: str, stats: Dict[str, Any]) -> None:
-        """Send statistics data."""
+        """Send statistics data with LOW priority."""
         telegram = cls()
         text = f"{cls.EMOJI_MAP['stats']} <b>{title}</b>"
         text += "\n\n<pre>" + cls._format_to_yaml(stats) + "</pre>"
-        telegram.send_message(text, parse_mode=TelegramParseMode.HTML)
+        telegram.send_message(text, parse_mode=TelegramParseMode.HTML, priority=MessagePriority.LOW)
 
 
 __all__ = [
@@ -424,4 +670,5 @@ __all__ = [
     "TelegramConfigError",
     "TelegramSendError",
     "DjangoTelegram",
+    "MessagePriority",
 ]

django_cfg/modules/django_unfold/__init__.py

@@ -1,13 +1,12 @@
 """
 Django CFG Unfold Module
 
-Provides complete Unfold admin interface integration with dashboard,
-navigation, theming, and callback support.
+Provides complete Unfold admin interface integration with
+navigation and theming support.
 """
 
-from .callbacks import UnfoldCallbacks
-from .dashboard import DashboardManager, get_dashboard_manager
 from .models import *
+from .navigation import NavigationManager, get_navigation_manager
 from .system_monitor import SystemMonitor
 from .tailwind import get_css_variables, get_unfold_colors
 
@@ -20,19 +19,10 @@ def get_system_monitor() -> SystemMonitor:
         globals()['_system_monitor'] = SystemMonitor()
     return globals()['_system_monitor']
 
-def get_unfold_callbacks() -> UnfoldCallbacks:
-    """Get the global unfold callbacks instance."""
-    global _unfold_callbacks
-    if '_unfold_callbacks' not in globals():
-        globals()['_unfold_callbacks'] = UnfoldCallbacks()
-    return globals()['_unfold_callbacks']
-
 # Export main components
 __all__ = [
-    'DashboardManager',
-    'get_dashboard_manager',
-    'UnfoldCallbacks',
-    'get_unfold_callbacks',
+    'NavigationManager',
+    'get_navigation_manager',
     'SystemMonitor',
     'get_system_monitor',
     'get_unfold_colors',
@@ -48,15 +38,6 @@ __all__ = [
     'NavigationSection',
     'NavigationItemType',
     'SiteDropdownItem',
-    'StatCard',
-    'SystemHealthItem',
-    'QuickAction',
-    'DashboardWidget',
-    'DashboardData',
-    'ChartDataset',
-    'ChartData',
-    'TabConfiguration',
-    'TabItem',
 ]
 
 # Version info

django_cfg/modules/django_unfold/forms/EXAMPLE.md

@@ -0,0 +1,48 @@
+# Login Autofill Example
+
+## Basic Usage (Development only)
+
+```python
+from django_cfg.models import UnfoldConfig
+
+class MyConfig(BaseConfig):
+    unfold: UnfoldConfig = Field(
+        default_factory=lambda: UnfoldConfig(
+            site_title="My Admin",
+
+            # Auto-enabled only in DEBUG mode
+            dev_autofill_email="admin@example.com",
+            dev_autofill_password="admin123",
+        )
+    )
+```
+
+## Force in Production (Demo/Staging)
+
+```python
+unfold: UnfoldConfig = Field(
+    default_factory=lambda: UnfoldConfig(
+        site_title="My Admin",
+
+        # Force autofill even in production
+        dev_autofill_email="demo@example.com",
+        dev_autofill_password="demo123",
+        dev_autofill_force=True,  # Works regardless of DEBUG
+    )
+)
+```
+
+## How it works
+
+1. If `dev_autofill_email` or `dev_autofill_password` is set → `DevAuthForm` is auto-enabled
+2. Autofill is enabled when ANY of these conditions are true:
+   - `DEBUG=True` (Django DEBUG mode)
+   - `environment.is_development=True` (django-cfg environment detection)
+   - `dev_autofill_force=True` (force in production)
+3. Prefills username/password fields on login page
+
+## Use Cases
+
+- ✅ Development: Auto-enabled via `DEBUG=True` or `environment="development"`
+- ✅ Demo/Staging: Use `dev_autofill_force=True`
+- ✅ Production: Don't set autofill fields

django_cfg/modules/django_unfold/forms/__init__.py

@@ -0,0 +1,5 @@
+"""Unfold custom forms."""
+
+from .auth import DevAuthForm
+
+__all__ = ["DevAuthForm"]