django-cfg 1.4.107__py3-none-any.whl → 1.4.109__py3-none-any.whl

django_cfg/apps/tasks/serializers/task_log.py

@@ -0,0 +1,249 @@
+"""
+TaskLog DRF Serializers.
+
+Serializers for TaskLog model with filtering and statistics.
+"""
+from rest_framework import serializers
+from ..models import TaskLog
+
+
+class TaskLogSerializer(serializers.ModelSerializer):
+    """
+    Basic TaskLog serializer.
+
+    Used for list views with essential fields only.
+    Includes computed properties matching ReArq response format.
+    """
+
+    duration_seconds = serializers.SerializerMethodField()
+    is_completed = serializers.BooleanField(read_only=True)
+    is_successful = serializers.BooleanField(read_only=True)
+    is_failed = serializers.BooleanField(read_only=True)
+
+    class Meta:
+        model = TaskLog
+        fields = [
+            'id',
+            'job_id',
+            'task_name',
+            'queue_name',
+            'status',
+            'success',
+            'duration_ms',
+            'duration_seconds',
+            'job_retry',
+            'job_retries',
+            'enqueue_time',
+            'expire_time',
+            'start_time',
+            'finish_time',
+            'is_completed',
+            'is_successful',
+            'is_failed',
+        ]
+        read_only_fields = fields
+
+    def get_duration_seconds(self, obj) -> float:
+        """Convert duration from ms to seconds."""
+        if obj.duration_ms is not None:
+            return round(obj.duration_ms / 1000, 2)
+        return None
+
+
+class TaskLogListSerializer(serializers.ModelSerializer):
+    """
+    Compact serializer for list views.
+
+    Minimal fields for performance, matching ReArq Job list format.
+    """
+
+    status_display = serializers.CharField(source='get_status_display', read_only=True)
+
+    class Meta:
+        model = TaskLog
+        fields = [
+            'id',
+            'job_id',
+            'task_name',
+            'queue_name',
+            'status',
+            'status_display',
+            'success',
+            'job_retries',
+            'duration_ms',
+            'enqueue_time',
+            'start_time',
+            'finish_time',
+        ]
+        read_only_fields = fields
+
+
+class TaskLogDetailSerializer(serializers.ModelSerializer):
+    """
+    Detailed TaskLog serializer.
+
+    Includes all fields including args, kwargs, result, error messages.
+    Combines ReArq Job + JobResult data.
+    """
+
+    status_display = serializers.CharField(source='get_status_display', read_only=True)
+    duration_seconds = serializers.SerializerMethodField()
+    user_display = serializers.SerializerMethodField()
+
+    class Meta:
+        model = TaskLog
+        fields = [
+            # Job identification
+            'id',
+            'job_id',
+            'task_name',
+            'queue_name',
+            # Status
+            'status',
+            'status_display',
+            'success',
+            # Arguments
+            'args',
+            'kwargs',
+            # Result
+            'result',
+            'error_message',
+            # Performance
+            'duration_ms',
+            'duration_seconds',
+            # Retry info (from ReArq Job)
+            'job_retry',
+            'job_retries',
+            'job_retry_after',
+            # Worker
+            'worker_id',
+            # Timestamps (from ReArq)
+            'enqueue_time',
+            'expire_time',
+            'start_time',
+            'finish_time',
+            # Django timestamps
+            'created_at',
+            'updated_at',
+            # User
+            'user',
+            'user_display',
+        ]
+        read_only_fields = fields
+
+    def get_duration_seconds(self, obj) -> float:
+        """Convert duration from ms to seconds."""
+        if obj.duration_ms is not None:
+            return round(obj.duration_ms / 1000, 2)
+        return None
+
+    def get_user_display(self, obj) -> str:
+        """Get user display name."""
+        if obj.user:
+            return f"{obj.user.username} ({obj.user.email})"
+        return None
+
+
+class TaskLogStatsSerializer(serializers.Serializer):
+    """
+    Statistics serializer for task metrics.
+
+    Not tied to a model - used for aggregated data.
+    """
+
+    total = serializers.IntegerField(help_text="Total number of task executions")
+    successful = serializers.IntegerField(help_text="Number of successful executions")
+    failed = serializers.IntegerField(help_text="Number of failed executions")
+    in_progress = serializers.IntegerField(help_text="Number of tasks currently running")
+    success_rate = serializers.FloatField(help_text="Success rate percentage")
+    avg_duration_ms = serializers.IntegerField(help_text="Average duration in milliseconds")
+    avg_duration_seconds = serializers.FloatField(help_text="Average duration in seconds")
+    period_hours = serializers.IntegerField(help_text="Statistics period in hours", required=False)
+
+
+class TasksByQueueSerializer(serializers.Serializer):
+    """
+    Tasks count by queue.
+
+    Used in overview endpoint for tasks_by_queue list.
+    """
+    queue_name = serializers.CharField(help_text="Queue name")
+    count = serializers.IntegerField(help_text="Number of tasks in this queue")
+
+
+class TasksByStatusSerializer(serializers.Serializer):
+    """
+    Tasks count by status.
+
+    Used in overview endpoint for tasks_by_status list.
+    """
+    status = serializers.CharField(help_text="Task status")
+    count = serializers.IntegerField(help_text="Number of tasks with this status")
+
+
+class TaskLogOverviewSerializer(serializers.Serializer):
+    """
+    Overview of task system with proper structure.
+
+    Provides high-level statistics about the entire task system:
+    - Total tasks count (all-time)
+    - Active queues list
+    - Recent failures (last 24h)
+    - Tasks distribution by queue (as array)
+    - Tasks distribution by status (as array)
+
+    Used by /cfg/tasks/logs/overview/ endpoint.
+    """
+    total_tasks = serializers.IntegerField(help_text="Total number of tasks all-time")
+    active_queues = serializers.ListField(
+        child=serializers.CharField(),
+        help_text="List of active queue names"
+    )
+    recent_failures = serializers.IntegerField(help_text="Failed tasks in last 24 hours")
+    tasks_by_queue = TasksByQueueSerializer(
+        many=True,
+        help_text="Tasks grouped by queue name"
+    )
+    tasks_by_status = TasksByStatusSerializer(
+        many=True,
+        help_text="Tasks grouped by status"
+    )
+
+
+class TaskLogTimelineItemSerializer(serializers.Serializer):
+    """
+    Single timeline data point.
+
+    Represents aggregated task statistics for a specific time period.
+    """
+    timestamp = serializers.DateTimeField(help_text="Time bucket start")
+    total = serializers.IntegerField(help_text="Total tasks in this period")
+    successful = serializers.IntegerField(help_text="Successful tasks")
+    failed = serializers.IntegerField(help_text="Failed tasks")
+    in_progress = serializers.IntegerField(help_text="Tasks currently in progress", required=False)
+    avg_duration_ms = serializers.FloatField(help_text="Average duration in milliseconds", required=False)
+
+
+class TaskLogTimelineSerializer(serializers.Serializer):
+    """
+    Timeline response wrapper.
+
+    Returns timeline data as array of time-bucketed statistics.
+    Used by /cfg/tasks/logs/timeline/ endpoint.
+    """
+    period_hours = serializers.IntegerField(help_text="Time period covered in hours")
+    interval = serializers.CharField(help_text="Time bucket interval (hour/day)")
+    data = TaskLogTimelineItemSerializer(many=True, help_text="Timeline data points")
+
+
+__all__ = [
+    "TaskLogSerializer",
+    "TaskLogListSerializer",
+    "TaskLogDetailSerializer",
+    "TaskLogStatsSerializer",
+    "TasksByQueueSerializer",
+    "TasksByStatusSerializer",
+    "TaskLogOverviewSerializer",
+    "TaskLogTimelineItemSerializer",
+    "TaskLogTimelineSerializer",
+]

django_cfg/apps/tasks/services/__init__.py

@@ -0,0 +1,10 @@
+"""Task services module."""
+from .client import ReArqClient, get_rearq_client
+from .config_helper import get_tasks_config, get_tasks_config_or_default
+
+__all__ = [
+    "ReArqClient",
+    "get_rearq_client",
+    "get_tasks_config",
+    "get_tasks_config_or_default",
+]

django_cfg/apps/tasks/services/client/__init__.py

@@ -0,0 +1,7 @@
+"""ReArq client module."""
+from .client import ReArqClient, get_rearq_client
+
+__all__ = [
+    "ReArqClient",
+    "get_rearq_client",
+]

django_cfg/apps/tasks/services/client/client.py

@@ -0,0 +1,234 @@
+"""
+ReArq client wrapper for Django-CFG.
+
+Provides singleton access to ReArq with django-cfg configuration.
+"""
+from typing import TYPE_CHECKING, Optional
+
+from django_cfg.modules.django_logging import get_logger
+
+if TYPE_CHECKING:
+    from rearq import ReArq
+
+logger = get_logger("tasks.client")
+
+
+class ReArqClient:
+    """
+    Django wrapper for ReArq client.
+
+    Provides singleton access to ReArq with django-cfg configuration.
+
+    Features:
+    - Async task queue with Redis backend
+    - Job persistence with Tortoise ORM
+    - Built-in retry logic
+    - Cron task support
+    - Job result tracking
+
+    Example:
+        >>> from django_cfg.apps.tasks import get_rearq_client
+        >>>
+        >>> client = get_rearq_client()
+        >>>
+        >>> # Define task
+        >>> @client.task(queue="default")
+        >>> async def process_data(data_id: str):
+        ...     # Process data
+        ...     return {"status": "done"}
+        >>>
+        >>> # Execute task
+        >>> job = await process_data.delay(data_id="123")
+        >>> result = await job.result(timeout=30)
+    """
+
+    def __init__(
+        self,
+        redis_url: str,
+        db_url: str,
+        max_jobs: int = 10,
+        job_timeout: int = 300,
+        job_retry: int = 3,
+        job_retry_after: int = 60,
+        keep_job_days: int | None = 7,
+    ):
+        """
+        Initialize ReArq client.
+
+        Args:
+            redis_url: Redis connection URL for task queue
+            db_url: Database URL for job persistence (Tortoise ORM)
+            max_jobs: Maximum concurrent jobs per worker
+            job_timeout: Default job timeout in seconds
+            job_retry: Default number of retries for failed jobs
+            job_retry_after: Delay in seconds before retrying failed job
+            keep_job_days: Days to keep job history (None = forever)
+        """
+        self.redis_url = redis_url
+        self.db_url = db_url
+        self.max_jobs = max_jobs
+        self.job_timeout = job_timeout
+        self.job_retry = job_retry
+        self.job_retry_after = job_retry_after
+        self.keep_job_days = keep_job_days
+
+        # Lazy import ReArq to avoid distutils issues at startup
+        from rearq import ReArq
+
+        # Create ReArq instance
+        self.rearq = ReArq(
+            redis_url=redis_url,
+            job_retry=job_retry,
+            job_retry_after=job_retry_after,
+            max_jobs=max_jobs,
+            job_timeout=job_timeout,
+            keep_job_days=keep_job_days,
+        )
+
+        logger.info(f"ReArq client initialized: {redis_url}")
+
+    def task(self, queue: str = "default", **kwargs):
+        """
+        Task decorator for defining async tasks.
+
+        Args:
+            queue: Queue name for the task
+            **kwargs: Additional task options
+
+        Returns:
+            Task decorator
+
+        Example:
+            >>> @client.task(queue="default")
+            >>> async def my_task(arg1: str):
+            ...     return f"Processed {arg1}"
+        """
+        return self.rearq.task(queue=queue, **kwargs)
+
+    def cron_task(self, cron: str, **kwargs):
+        """
+        Cron task decorator for scheduled tasks.
+
+        Args:
+            cron: Cron expression (e.g., "0 * * * *" for hourly)
+            **kwargs: Additional task options
+
+        Returns:
+            Task decorator
+
+        Example:
+            >>> @client.cron_task(cron="0 0 * * *")  # Daily at midnight
+            >>> async def daily_cleanup():
+            ...     return "Cleanup complete"
+        """
+        return self.rearq.task(cron=cron, **kwargs)
+
+    async def close(self):
+        """
+        Close client connections.
+
+        Call this when shutting down application to clean up resources.
+
+        Example:
+            >>> await client.close()
+        """
+        await self.rearq.close()
+        logger.info("ReArq client closed")
+
+    def get_connection_info(self) -> dict:
+        """
+        Get connection information.
+
+        Returns:
+            Dictionary with connection details
+
+        Example:
+            >>> info = client.get_connection_info()
+            >>> print(info["redis_url"])
+        """
+        return {
+            "redis_url": self.redis_url,
+            "db_url": self.db_url,
+            "max_jobs": self.max_jobs,
+            "job_timeout": self.job_timeout,
+            "job_retry": self.job_retry,
+            "job_retry_after": self.job_retry_after,
+            "keep_job_days": self.keep_job_days,
+        }
+
+
+# ==================== Singleton Pattern ====================
+
+_rearq_client: Optional[ReArqClient] = None
+_rearq_client_lock = None
+
+
+def get_rearq_client(force_new: bool = False) -> ReArqClient:
+    """
+    Get global ReArq client instance (singleton).
+
+    Creates client from Django settings on first call.
+    Subsequent calls return the same instance (thread-safe).
+
+    Args:
+        force_new: Force create new instance (for testing)
+
+    Returns:
+        ReArqClient instance
+
+    Example:
+        >>> from django_cfg.apps.tasks import get_rearq_client
+        >>> client = get_rearq_client()
+        >>> @client.task(queue="default")
+        >>> async def my_task():
+        ...     pass
+    """
+    global _rearq_client, _rearq_client_lock
+
+    if force_new:
+        return _create_client_from_settings()
+
+    if _rearq_client is None:
+        # Thread-safe singleton creation
+        import threading
+
+        if _rearq_client_lock is None:
+            _rearq_client_lock = threading.Lock()
+
+        with _rearq_client_lock:
+            if _rearq_client is None:
+                _rearq_client = _create_client_from_settings()
+
+    return _rearq_client
+
+
+def _create_client_from_settings() -> ReArqClient:
+    """
+    Create ReArq client from django-cfg config.
+
+    Returns:
+        ReArqClient instance
+
+    Raises:
+        ConfigurationError: If settings not configured
+    """
+    from ..config_helper import get_tasks_config_or_default
+
+    cfg = get_tasks_config_or_default()
+    logger.debug(f"Creating ReArq client from config: {cfg.rearq.redis_url}")
+
+    return ReArqClient(
+        redis_url=cfg.rearq.redis_url,
+        db_url=cfg.rearq.db_url,
+        max_jobs=cfg.rearq.max_jobs,
+        job_timeout=cfg.rearq.job_timeout,
+        job_retry=cfg.rearq.job_retry,
+        job_retry_after=cfg.rearq.job_retry_after,
+        keep_job_days=cfg.rearq.keep_job_days,
+    )
+
+
+__all__ = [
+    "ReArqClient",
+    "get_rearq_client",
+]

django_cfg/apps/tasks/services/config_helper.py

@@ -0,0 +1,63 @@
+"""
+Task configuration helper.
+
+Provides access to task configuration from global state.
+"""
+from typing import Optional
+
+from django_cfg.modules.django_logging import get_logger
+
+logger = get_logger("tasks.config")
+
+
+def get_tasks_config():
+    """
+    Get tasks configuration from global state.
+
+    Returns:
+        TaskConfig instance if found, None otherwise
+
+    Example:
+        >>> from django_cfg.apps.tasks.services import get_tasks_config
+        >>> config = get_tasks_config()
+        >>> if config:
+        ...     print(config.rearq.redis_url)
+    """
+    from django_cfg.core import get_current_config
+
+    config = get_current_config()
+
+    if config and hasattr(config, "tasks") and config.tasks:
+        return config.tasks
+
+    return None
+
+
+def get_tasks_config_or_default():
+    """
+    Get tasks configuration or return default.
+
+    Returns:
+        TaskConfig instance (from global state or default)
+
+    Example:
+        >>> from django_cfg.apps.tasks.services import get_tasks_config_or_default
+        >>> config = get_tasks_config_or_default()
+        >>> print(config.rearq.redis_url)
+    """
+    config = get_tasks_config()
+
+    if config:
+        return config
+
+    # Fallback to default
+    from django_cfg.models.tasks import TaskConfig
+
+    logger.warning("Tasks config not found in global state, using default")
+    return TaskConfig()
+
+
+__all__ = [
+    "get_tasks_config",
+    "get_tasks_config_or_default",
+]