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

django_cfg/models/django/django_q2.py

@@ -0,0 +1,491 @@
+"""
+Django-Q2 Configuration for django-cfg.
+
+Type-safe configuration for django-q2 (modern fork of django-q) with automatic
+Django settings generation and support for scheduled tasks.
+
+Django-Q2 is the actively maintained fork: https://github.com/django-q2/django-q2
+
+Features:
+- Type-safe scheduled task definitions
+- Django management command support
+- Cron-style and interval-based scheduling
+- Redis/database broker configuration
+- Queue management
+- Task result storage
+- Monitoring and logging
+- Built-in admin interface
+- Python 3.8+ and Django 3.2+ support
+
+Migration from django-crontab to django-q2:
+1. Replace django-crontab with django-q2 in requirements
+2. Convert CrontabConfig to DjangoQ2Config
+3. Cron expressions stay the same
+4. Add additional features like intervals, hooks, retries
+5. Built-in admin interface for monitoring
+6. No need to run 'crontab add' - uses Django's own scheduler
+
+Example:
+    ```python
+    # Old django-crontab
+    crontab_config = CrontabConfig(
+        jobs=[
+            CrontabJobConfig(
+                name="Sync balances",
+                minute="0",
+                hour="*/1",  # Every hour
+                command="sync_account_balances",
+            )
+        ]
+    )
+
+    # New django-q2
+    django_q2_config = DjangoQ2Config(
+        schedules=[
+            DjangoQ2ScheduleConfig(
+                name="Sync balances",
+                schedule_type="hourly",  # Simpler!
+                command="sync_account_balances",
+            )
+        ]
+    )
+    ```
+"""
+
+from typing import Any, Dict, List, Literal, Optional, Union
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class DjangoQ2ScheduleConfig(BaseModel):
+    """
+    Configuration for a single Django-Q2 scheduled task.
+
+    Supports both cron-style and interval-based scheduling.
+
+    Schedule types:
+    - cron: Traditional cron expression (e.g., "0 0 * * *")
+    - minutes: Every N minutes (e.g., minutes=15)
+    - hourly: Every hour (at minute 0)
+    - daily: Every day (at midnight)
+    - weekly: Every week (Sunday at midnight)
+    - monthly: Every month (1st at midnight)
+    - yearly: Every year (Jan 1st at midnight)
+    - once: Run once at next scheduled time
+    """
+
+    model_config = ConfigDict(
+        validate_assignment=True,
+        extra="forbid",
+    )
+
+    # Task identification
+    name: str = Field(
+        ...,
+        description="Human-readable task name (unique identifier)",
+        min_length=1,
+        max_length=100,
+    )
+
+    # Schedule type
+    schedule_type: Literal["cron", "minutes", "hourly", "daily", "weekly", "monthly", "yearly", "once"] = Field(
+        default="cron",
+        description="Schedule type: cron, minutes, hourly, daily, weekly, monthly, yearly, once",
+    )
+
+    # Cron-style schedule (when schedule_type="cron")
+    cron: Optional[str] = Field(
+        default=None,
+        description="Cron expression (e.g., '0 0 * * *' for daily at midnight)",
+        pattern=r"^[\d\*\-\,\/\s]+$",
+    )
+
+    # Interval-based schedule (when schedule_type="minutes")
+    minutes: Optional[int] = Field(
+        default=None,
+        ge=1,
+        le=525600,  # Max 1 year in minutes
+        description="Run every N minutes (when schedule_type='minutes')",
+    )
+
+    # Task execution configuration
+    func: Optional[str] = Field(
+        default=None,
+        description="Function path (e.g., 'django.core.management.call_command' or 'myapp.tasks.my_task'). Auto-set when 'command' is provided.",
+    )
+
+    # Function arguments
+    args: Optional[List[Any]] = Field(
+        default=None,
+        description="Positional arguments for the function",
+    )
+
+    kwargs: Optional[Dict[str, Any]] = Field(
+        default=None,
+        description="Keyword arguments for the function",
+    )
+
+    # Management command support (shortcut)
+    command: Optional[str] = Field(
+        default=None,
+        description="Django management command name (auto-sets func to call_command)",
+    )
+
+    command_args: Optional[List[str]] = Field(
+        default=None,
+        description="Management command arguments",
+    )
+
+    command_kwargs: Optional[Dict[str, Any]] = Field(
+        default=None,
+        description="Management command keyword arguments",
+    )
+
+    # Task options
+    enabled: bool = Field(
+        default=True,
+        description="Whether task is enabled",
+    )
+
+    queue: Optional[str] = Field(
+        default=None,
+        description="Queue name (None = default queue)",
+    )
+
+    timeout: Optional[int] = Field(
+        default=None,
+        ge=1,
+        le=86400,  # Max 24 hours
+        description="Task timeout in seconds",
+    )
+
+    repeats: int = Field(
+        default=-1,
+        description="Number of times to repeat (-1 = infinite)",
+    )
+
+    hook: Optional[str] = Field(
+        default=None,
+        description="Hook function to call after task completion",
+    )
+
+    cluster: Optional[str] = Field(
+        default=None,
+        description="Cluster name (for multi-cluster setups)",
+    )
+
+    def model_post_init(self, __context: Any) -> None:
+        """Validate and setup configuration after initialization."""
+        # Validate that either func or command is provided
+        if not self.func and not self.command:
+            raise ValueError("Either 'func' or 'command' must be provided")
+
+        # Setup management command
+        if self.command:
+            self.func = "django.core.management.call_command"
+            args = [self.command]
+            if self.command_args:
+                args.extend(self.command_args)
+            self.args = args
+            if self.command_kwargs:
+                self.kwargs = self.command_kwargs
+
+        # Validate schedule configuration
+        if self.schedule_type == "cron" and not self.cron:
+            raise ValueError("'cron' must be set when schedule_type is 'cron'")
+
+        if self.schedule_type == "minutes" and not self.minutes:
+            raise ValueError("'minutes' must be set when schedule_type is 'minutes'")
+
+    def to_django_q_format(self) -> Dict[str, Any]:
+        """
+        Convert to Django-Q Schedule format.
+
+        Returns:
+            Dictionary for ORM.create() or schedule creation
+        """
+        # Map our schedule types to Django-Q2 constants
+        type_mapping = {
+            "once": "O",
+            "minutes": "I",
+            "hourly": "H",
+            "daily": "D",
+            "weekly": "W",
+            "monthly": "M",
+            "yearly": "Y",
+            "cron": "C",
+        }
+
+        config = {
+            "name": self.name,
+            "func": self.func,
+            "schedule_type": type_mapping.get(self.schedule_type, self.schedule_type.upper()),
+        }
+
+        if self.args:
+            config["args"] = str(self.args)
+
+        if self.kwargs:
+            config["kwargs"] = str(self.kwargs)
+
+        if self.schedule_type == "cron" and self.cron:
+            config["cron"] = self.cron
+
+        if self.schedule_type == "minutes" and self.minutes:
+            config["minutes"] = self.minutes
+
+        if self.queue:
+            config["queue"] = self.queue
+
+        if self.timeout:
+            config["timeout"] = self.timeout
+
+        if self.repeats != -1:
+            config["repeats"] = self.repeats
+
+        if self.hook:
+            config["hook"] = self.hook
+
+        if self.cluster:
+            config["cluster"] = self.cluster
+
+        return config
+
+
+class DjangoQ2Config(BaseModel):
+    """
+    Complete Django-Q2 configuration container.
+
+    Integrates with django-q2 (modern fork) for scheduled and async task execution.
+    Automatically adds django_q to INSTALLED_APPS when enabled.
+
+    Installation:
+        pip install django-q2[redis]
+
+    Example:
+        ```python
+        # MAGIC: broker_url automatically uses config.redis_url! 🎉
+        # Just set redis_url once in your DjangoConfig:
+        #   redis_url: Optional[str] = env.redis_url
+
+        django_q2_config = DjangoQ2Config(
+            enabled=True,
+            # broker_url is auto-detected from config.redis_url!
+            schedules=[
+                DjangoQ2ScheduleConfig(
+                    name="Sync balances every hour",
+                    schedule_type="hourly",
+                    command="sync_account_balances",
+                ),
+                DjangoQ2ScheduleConfig(
+                    name="Cleanup old data daily",
+                    schedule_type="cron",
+                    cron="0 2 * * *",  # 2 AM daily
+                    command="cleanup_old_data",
+                    command_kwargs={"days": 30},
+                ),
+                DjangoQ2ScheduleConfig(
+                    name="Quick check every 5 minutes",
+                    schedule_type="minutes",
+                    minutes=5,
+                    command="health_check",
+                ),
+            ],
+        )
+        ```
+
+    Admin interface:
+        - Visit /admin/django_q/ to view tasks and schedules
+        - Monitor task execution, failures, and performance
+        - Manually trigger scheduled tasks
+        - View task results and logs
+    """
+
+    model_config = ConfigDict(
+        validate_assignment=True,
+        extra="forbid",
+    )
+
+    enabled: bool = Field(
+        default=True,
+        description="Enable Django-Q (auto-adds django_q to INSTALLED_APPS)",
+    )
+
+    schedules: List[DjangoQ2ScheduleConfig] = Field(
+        default_factory=list,
+        description="List of scheduled tasks",
+    )
+
+    # Django-Q broker configuration
+    broker_url: str = Field(
+        default="redis://localhost:6379/0",
+        description="Broker URL (Redis recommended for production)",
+    )
+
+    broker_class: Literal["redis", "orm"] = Field(
+        default="redis",
+        description="Broker backend class (redis or orm)",
+    )
+
+    # Queue configuration
+    queue_limit: Optional[int] = Field(
+        default=50,
+        ge=1,
+        description="Maximum tasks in queue before rejecting new ones",
+    )
+
+    workers: int = Field(
+        default=4,
+        ge=1,
+        le=32,
+        description="Number of worker processes",
+    )
+
+    timeout: int = Field(
+        default=300,
+        ge=1,
+        le=86400,  # Max 24 hours
+        description="Default task timeout in seconds",
+    )
+
+    retry: int = Field(
+        default=3600,
+        ge=0,
+        description="Seconds to wait before retrying failed tasks (0 = no retry)",
+    )
+
+    # Task result configuration
+    save_limit: int = Field(
+        default=250,
+        ge=0,
+        description="Maximum number of successful tasks to save (0 = unlimited)",
+    )
+
+    cached: int = Field(
+        default=500,
+        ge=0,
+        description="Maximum number of tasks to cache (0 = disabled)",
+    )
+
+    # Monitoring
+    monitor_interval: int = Field(
+        default=30,
+        ge=1,
+        description="Seconds between monitor checks",
+    )
+
+    # Logging
+    log_level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] = Field(
+        default="INFO",
+        description="Django-Q log level",
+    )
+
+    # Advanced options
+    compress: bool = Field(
+        default=False,
+        description="Compress task data",
+    )
+
+    catch_up: bool = Field(
+        default=True,
+        description="Run missed scheduled tasks immediately",
+    )
+
+    sync: bool = Field(
+        default=False,
+        description="Run tasks synchronously (for testing)",
+    )
+
+    def get_enabled_schedules(self) -> List[DjangoQ2ScheduleConfig]:
+        """Get list of enabled schedules."""
+        return [schedule for schedule in self.schedules if schedule.enabled]
+
+    def to_django_settings(self, parent_config: Optional[Any] = None) -> Dict[str, Any]:
+        """
+        Convert to Django settings dictionary.
+
+        Generates Q_CLUSTER configuration for Django-Q2.
+
+        Args:
+            parent_config: Optional parent DjangoConfig for accessing redis_url
+
+        Note: Schedules are created via Django ORM, not settings.
+        Use management command: python manage.py qcluster
+        """
+        if not self.enabled:
+            return {}
+
+        # Auto-detect redis_url from parent config if not explicitly set
+        broker_url = self.broker_url
+        if broker_url == "redis://localhost:6379/0" and parent_config:
+            # Use redis_url from parent config if available
+            if hasattr(parent_config, 'redis_url') and parent_config.redis_url:
+                broker_url = parent_config.redis_url
+
+        # Map short broker names to full class paths
+        broker_class_map = {
+            "redis": "django_q.brokers.redis_broker.Redis",
+            "orm": "django_q.brokers.orm.ORM",
+        }
+
+        cluster_config = {
+            # Broker
+            "name": "django_cfg_cluster",
+            "broker": broker_url,
+            "broker_class": broker_class_map.get(self.broker_class, self.broker_class),
+
+            # Queue
+            "queue_limit": self.queue_limit,
+            "workers": self.workers,
+            "timeout": self.timeout,
+            "retry": self.retry,
+
+            # Results
+            "save_limit": self.save_limit,
+            "cached": self.cached,
+
+            # Monitoring
+            "monitor": self.monitor_interval,
+
+            # Logging
+            "log_level": self.log_level,
+
+            # Advanced
+            "compress": self.compress,
+            "catch_up": self.catch_up,
+            "sync": self.sync,
+
+            # Django integration
+            "orm": "default",
+        }
+
+        # Only add django_redis if broker is actually Redis
+        if self.broker_class == "redis":
+            # Don't set django_redis - let Django-Q2 connect directly via broker URL
+            pass
+
+        settings = {
+            "Q_CLUSTER": cluster_config
+        }
+
+        return settings
+
+    def get_schedule_by_name(self, name: str) -> Optional[DjangoQ2ScheduleConfig]:
+        """Get schedule by name."""
+        for schedule in self.schedules:
+            if schedule.name == name:
+                return schedule
+        return None
+
+    def get_schedules_by_command(self, command: str) -> List[DjangoQ2ScheduleConfig]:
+        """Get all schedules for a specific command."""
+        return [
+            schedule for schedule in self.schedules
+            if schedule.command == command
+        ]
+
+
+__all__ = [
+    "DjangoQ2ScheduleConfig",
+    "DjangoQ2Config",
+]

django_cfg/modules/django_admin/utils/html_builder.py

@@ -4,6 +4,7 @@ Universal HTML builder for Django Admin display methods.
 
 from pathlib import Path
 from typing import Any, List, Optional, Union
+import re
 
 from django.utils.html import escape, format_html
 from django.utils.safestring import SafeString
@@ -119,8 +120,17 @@ class HtmlBuilder:
         if css_class:
             classes += f" {css_class}"
 
-        # Join items with separator
-        joined = format_html(separator.join(['{}'] * len(items)), *items)
+        # Convert items to strings, keeping SafeString as-is
+        from django.utils.safestring import SafeString, mark_safe
+        processed_items = []
+        for item in items:
+            if isinstance(item, (SafeString, str)):
+                processed_items.append(item)
+            else:
+                processed_items.append(escape(str(item)))
+
+        # Join with separator
+        joined = mark_safe(separator.join(str(item) for item in processed_items))
 
         return format_html('<span class="{}">{}</span>', classes, joined)
 
@@ -320,6 +330,44 @@ class HtmlBuilder:
             enable_plugins=enable_plugins
         )
 
+    @staticmethod
+    def uuid_short(uuid_value: Any, length: int = 6, show_tooltip: bool = True) -> SafeString:
+        """
+        Shorten UUID to first N characters with optional tooltip.
+
+        Args:
+            uuid_value: UUID string or UUID object
+            length: Number of characters to show (default: 6)
+            show_tooltip: Show full UUID on hover (default: True)
+
+        Usage:
+            html.uuid_short(obj.id)  # "a1b2c3..."
+            html.uuid_short(obj.id, length=8)  # "a1b2c3d4..."
+            html.uuid_short(obj.id, show_tooltip=False)  # Just short version
+
+        Returns:
+            SafeString with shortened UUID
+        """
+        uuid_str = str(uuid_value)
+
+        # Remove dashes for cleaner display
+        uuid_clean = uuid_str.replace('-', '')
+
+        # Take first N characters
+        short_uuid = uuid_clean[:length]
+
+        if show_tooltip:
+            return format_html(
+                '<code class="font-mono text-xs bg-base-100 dark:bg-base-800 px-1.5 py-0.5 rounded cursor-help" title="{}">{}</code>',
+                uuid_str,
+                short_uuid
+            )
+
+        return format_html(
+            '<code class="font-mono text-xs bg-base-100 dark:bg-base-800 px-1.5 py-0.5 rounded">{}</code>',
+            short_uuid
+        )
+
     @staticmethod
     def markdown_docs(
         content: Union[str, Path],

django_cfg/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "hatchling.build"
 
 [project]
 name = "django-cfg"
-version = "1.4.111"
+version = "1.4.114"
 description = "Modern Django framework with type-safe Pydantic v2 configuration, Next.js admin integration, real-time WebSockets, and 8 enterprise apps. Replace settings.py with validated models, 90% less code. Production-ready with AI agents, auto-generated TypeScript clients, and zero-config features."
 readme = "README.md"
 keywords = [ "django", "configuration", "pydantic", "settings", "type-safety", "pydantic-settings", "django-environ", "startup-validation", "ide-autocomplete", "nextjs-admin", "react-admin", "websocket", "centrifugo", "real-time", "typescript-generation", "ai-agents", "enterprise-django", "django-settings", "type-safe-config", "modern-django",]
 classifiers = [ "Development Status :: 4 - Beta", "Framework :: Django", "Framework :: Django :: 5.2", "Intended Audience :: Developers", "License :: OSI Approved :: MIT License", "Operating System :: OS Independent", "Programming Language :: Python", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.12", "Programming Language :: Python :: 3.13", "Topic :: Internet :: WWW/HTTP", "Topic :: Internet :: WWW/HTTP :: Dynamic Content", "Topic :: Software Development :: Libraries :: Python Modules", "Topic :: System :: Systems Administration", "Typing :: Typed",]
 requires-python = ">=3.12,<3.14"
-dependencies = [ "pydantic>=2.11.0,<3.0", "pydantic[email]>=2.11.0,<3.0", "PyYAML>=6.0,<7.0", "click>=8.2.0,<9.0", "questionary>=2.1.0,<3.0", "rich>=14.0.0,<15.0", "cloudflare>=4.3.0,<5.0", "loguru>=0.7.0,<1.0", "colorlog>=6.9.0,<7.0", "cachetools>=5.3.0,<7.0", "toml>=0.10.2,<0.11.0", "ngrok>=1.5.1; python_version>='3.12'", "psycopg[binary,pool]>=3.2.0,<4.0", "dj-database-url>=3.0.0,<4.0", "whitenoise>=6.8.0,<7.0", "django-cors-headers>=4.7.0,<5.0", "djangorestframework>=3.16.0,<4.0", "djangorestframework-simplejwt>=5.5.0,<6.0", "djangorestframework-simplejwt[token-blacklist]>=5.5.0,<6.0", "drf-nested-routers>=0.94.0,<1.0", "django-filter>=25.0,<26.0", "django-ratelimit>=4.1.0,<5.0.0", "drf-spectacular>=0.28.0,<1.0", "drf-spectacular-sidecar>=2025.8.0,<2026.0", "django-json-widget>=2.0.0,<3.0", "django-import-export>=4.3.0,<5.0", "django-extensions>=4.1.0,<5.0", "django-constance>=4.3.0,<5.0", "django-unfold>=0.64.0,<1.0", "django-redis>=6.0.0,<7.0", "redis>=6.4.0,<7.0", "hiredis>=2.0.0,<4.0", "rearq>=0.2.0,<1.0", "setuptools>=75.0.0; python_version>='3.13'", "pyTelegramBotAPI>=4.28.0,<5.0", "coolname>=2.2.0,<3.0", "django-admin-rangefilter>=0.13.0,<1.0", "python-json-logger>=3.3.0,<4.0", "requests>=2.32.0,<3.0", "tiktoken>=0.11.0,<1.0", "openai>=1.107.0,<2.0", "twilio>=9.8.0,<10.0", "sendgrid>=6.12.0,<7.0", "beautifulsoup4>=4.13.0,<5.0", "lxml>=6.0.0,<7.0", "pgvector>=0.4.0,<1.0", "tenacity>=9.1.2,<10.0.0", "mypy (>=1.18.2,<2.0.0)", "django-tailwind[reload] (>=4.2.0,<5.0.0)", "jinja2 (>=3.1.6,<4.0.0)", "django-axes[ipware] (>=8.0.0,<9.0.0)", "pydantic-settings (>=2.11.0,<3.0.0)", "pytz>=2025.1", "httpx>=0.28.1,<1.0", "mistune>=3.1.4,<4.0",]
+dependencies = [ "pydantic>=2.11.0,<3.0", "pydantic[email]>=2.11.0,<3.0", "PyYAML>=6.0,<7.0", "click>=8.2.0,<9.0", "questionary>=2.1.0,<3.0", "rich>=14.0.0,<15.0", "cloudflare>=4.3.0,<5.0", "loguru>=0.7.0,<1.0", "colorlog>=6.9.0,<7.0", "cachetools>=5.3.0,<7.0", "toml>=0.10.2,<0.11.0", "ngrok>=1.5.1; python_version>='3.12'", "psycopg[binary,pool]>=3.2.0,<4.0", "dj-database-url>=3.0.0,<4.0", "whitenoise>=6.8.0,<7.0", "django-cors-headers>=4.7.0,<5.0", "django-q2==1.8.0", "croniter>=6.0.0,<7.0", "djangorestframework>=3.16.0,<4.0", "djangorestframework-simplejwt>=5.5.0,<6.0", "djangorestframework-simplejwt[token-blacklist]>=5.5.0,<6.0", "drf-nested-routers>=0.94.0,<1.0", "django-filter>=25.0,<26.0", "django-ratelimit>=4.1.0,<5.0.0", "drf-spectacular>=0.28.0,<1.0", "drf-spectacular-sidecar>=2025.8.0,<2026.0", "django-json-widget>=2.0.0,<3.0", "django-import-export>=4.3.0,<5.0", "django-extensions>=4.1.0,<5.0", "django-constance>=4.3.0,<5.0", "django-unfold>=0.64.0,<1.0", "django-redis>=6.0.0,<7.0", "redis>=6.4.0,<7.0", "hiredis>=2.0.0,<4.0", "rearq>=0.2.0,<1.0", "setuptools>=75.0.0; python_version>='3.13'", "pyTelegramBotAPI>=4.28.0,<5.0", "coolname>=2.2.0,<3.0", "django-admin-rangefilter>=0.13.0,<1.0", "python-json-logger>=3.3.0,<4.0", "requests>=2.32.0,<3.0", "tiktoken>=0.11.0,<1.0", "openai>=1.107.0,<2.0", "twilio>=9.8.0,<10.0", "sendgrid>=6.12.0,<7.0", "beautifulsoup4>=4.13.0,<5.0", "lxml>=6.0.0,<7.0", "pgvector>=0.4.0,<1.0", "tenacity>=9.1.2,<10.0.0", "mypy (>=1.18.2,<2.0.0)", "django-tailwind[reload] (>=4.2.0,<5.0.0)", "jinja2 (>=3.1.6,<4.0.0)", "django-axes[ipware] (>=8.0.0,<9.0.0)", "pydantic-settings (>=2.11.0,<3.0.0)", "pytz>=2025.1", "httpx>=0.28.1,<1.0", "mistune>=3.1.4,<4.0",]
 [[project.authors]]
 name = "Django-CFG Team"
 email = "info@djangocfg.com"

django_cfg/registry/core.py

@@ -38,6 +38,10 @@ CORE_REGISTRY = {
     # Security - Django Crypto Fields
     "CryptoFieldsConfig": ("django_cfg.models.django.crypto_fields", "CryptoFieldsConfig"),
 
+    # Scheduling - Django-Q2
+    "DjangoQ2Config": ("django_cfg.models.django.django_q2", "DjangoQ2Config"),
+    "DjangoQ2ScheduleConfig": ("django_cfg.models.django.django_q2", "DjangoQ2ScheduleConfig"),
+
     # Limits models
     "LimitsConfig": ("django_cfg.models.api.limits", "LimitsConfig"),