django-database-task 0.1.0__py3-none-any.whl

django_database_task/__init__.py

@@ -0,0 +1,27 @@
+"""
+django-database-task: A database-backed task queue backend for Django 6.0's task framework.
+"""
+
+__version__ = "0.1.0"
+
+
+def __getattr__(name):
+    """Lazy import to avoid AppRegistryNotReady errors."""
+    if name in (
+        "fetch_task",
+        "get_pending_task_count",
+        "process_one_task",
+        "process_tasks",
+    ):
+        from . import executor
+
+        return getattr(executor, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = [
+    "fetch_task",
+    "get_pending_task_count",
+    "process_one_task",
+    "process_tasks",
+]

django_database_task/admin.py

@@ -0,0 +1,211 @@
+from django.contrib import admin, messages
+from django.db import transaction
+from django.tasks import task_backends
+from django.tasks.base import TaskResultStatus
+from django.utils.html import format_html
+from django.utils.translation import gettext_lazy as _
+
+from .models import DatabaseTask
+
+
+@admin.register(DatabaseTask)
+class DatabaseTaskAdmin(admin.ModelAdmin):
+    list_display = [
+        "id_short",
+        "task_path_short",
+        "status_badge",
+        "priority",
+        "queue_name",
+        "enqueued_at",
+        "started_at",
+        "finished_at",
+    ]
+    list_filter = ["status", "queue_name", "backend_name"]
+    search_fields = ["id", "task_path"]
+    ordering = ["-created_at"]
+    readonly_fields = [
+        "id",
+        "created_at",
+        "updated_at",
+        "enqueued_at",
+        "started_at",
+        "finished_at",
+        "last_attempted_at",
+        "return_value_json",
+        "errors_json",
+        "worker_ids_json",
+    ]
+    fieldsets = [
+        (
+            "Basic Information",
+            {"fields": ["id", "task_path", "backend_name", "queue_name", "priority"]},
+        ),
+        (
+            "Status",
+            {"fields": ["status", "run_after"]},
+        ),
+        (
+            "Arguments",
+            {
+                "fields": ["args_json", "kwargs_json"],
+                "classes": ["collapse"],
+            },
+        ),
+        (
+            "Execution Result",
+            {
+                "fields": ["return_value_json", "errors_json", "worker_ids_json"],
+                "classes": ["collapse"],
+            },
+        ),
+        (
+            "Timestamps",
+            {
+                "fields": [
+                    "enqueued_at",
+                    "started_at",
+                    "finished_at",
+                    "last_attempted_at",
+                    "created_at",
+                    "updated_at",
+                ],
+                "classes": ["collapse"],
+            },
+        ),
+    ]
+
+    def id_short(self, obj):
+        """Display shortened ID."""
+        return str(obj.id)[:8]
+
+    id_short.short_description = "ID"
+
+    def task_path_short(self, obj):
+        """Display shortened task path."""
+        path = obj.task_path
+        if len(path) > 40:
+            return f"...{path[-37:]}"
+        return path
+
+    task_path_short.short_description = "Task"
+
+    def status_badge(self, obj):
+        """Display status as a colored badge."""
+        colors = {
+            "READY": "#6c757d",
+            "RUNNING": "#007bff",
+            "SUCCESSFUL": "#28a745",
+            "FAILED": "#dc3545",
+        }
+        color = colors.get(obj.status, "#6c757d")
+        return format_html(
+            '<span style="background-color: {}; color: white; padding: 3px 8px; '
+            'border-radius: 3px; font-size: 11px;">{}</span>',
+            color,
+            obj.status,
+        )
+
+    status_badge.short_description = "Status"
+
+    actions = ["run_selected_tasks", "retry_failed_tasks"]
+
+    def has_add_permission(self, request):
+        """Disable adding tasks from admin."""
+        return False
+
+    @admin.action(description=_("Run selected tasks"))
+    def run_selected_tasks(self, request, queryset):
+        """Execute selected tasks that are in READY status."""
+        ready_tasks = queryset.filter(status=TaskResultStatus.READY)
+        ready_count = ready_tasks.count()
+
+        if ready_count == 0:
+            self.message_user(
+                request,
+                "No tasks in READY status were selected.",
+                messages.WARNING,
+            )
+            return
+
+        success_count = 0
+        fail_count = 0
+
+        for db_task in ready_tasks:
+            try:
+                backend = task_backends[db_task.backend_name]
+                result = backend.run_task(db_task, worker_id="admin")
+                if result.status == TaskResultStatus.SUCCESSFUL:
+                    success_count += 1
+                else:
+                    fail_count += 1
+            except Exception:
+                fail_count += 1
+
+        skipped_count = queryset.count() - ready_count
+        msg_parts = []
+        if success_count:
+            msg_parts.append(f"{success_count} succeeded")
+        if fail_count:
+            msg_parts.append(f"{fail_count} failed")
+        if skipped_count:
+            msg_parts.append(f"{skipped_count} skipped (not READY)")
+
+        self.message_user(
+            request,
+            f"Task execution completed: {', '.join(msg_parts)}.",
+            messages.SUCCESS if fail_count == 0 else messages.WARNING,
+        )
+
+    @admin.action(description=_("Retry failed tasks"))
+    def retry_failed_tasks(self, request, queryset):
+        """Reset failed tasks to READY status and re-execute them."""
+        failed_tasks = queryset.filter(status=TaskResultStatus.FAILED)
+        failed_count = failed_tasks.count()
+
+        if failed_count == 0:
+            self.message_user(
+                request,
+                "No tasks in FAILED status were selected.",
+                messages.WARNING,
+            )
+            return
+
+        success_count = 0
+        fail_count = 0
+
+        for db_task in failed_tasks:
+            try:
+                with transaction.atomic():
+                    # Reset task status to READY
+                    db_task.status = TaskResultStatus.READY
+                    db_task.errors_json = []
+                    db_task.started_at = None
+                    db_task.finished_at = None
+                    db_task.return_value_json = None
+                    db_task.save()
+
+                    # Execute the task
+                    backend = task_backends[db_task.backend_name]
+                    result = backend.run_task(db_task, worker_id="admin-retry")
+
+                if result.status == TaskResultStatus.SUCCESSFUL:
+                    success_count += 1
+                else:
+                    fail_count += 1
+            except Exception:
+                fail_count += 1
+
+        skipped_count = queryset.count() - failed_count
+        msg_parts = []
+        if success_count:
+            msg_parts.append(f"{success_count} succeeded")
+        if fail_count:
+            msg_parts.append(f"{fail_count} failed again")
+        if skipped_count:
+            msg_parts.append(f"{skipped_count} skipped (not FAILED)")
+
+        self.message_user(
+            request,
+            f"Retry completed: {', '.join(msg_parts)}.",
+            messages.SUCCESS if fail_count == 0 else messages.WARNING,
+        )

django_database_task/apps.py

@@ -0,0 +1,7 @@
+from django.apps import AppConfig
+
+
+class DjangoDatabaseTaskConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "django_database_task"
+    verbose_name = "Django Database Task"

django_database_task/backends.py

@@ -0,0 +1,211 @@
+import asyncio
+import traceback
+from importlib import import_module
+from inspect import iscoroutinefunction
+
+from django.tasks.backends.base import BaseTaskBackend
+from django.tasks.base import Task, TaskContext, TaskError, TaskResult, TaskResultStatus
+from django.tasks.exceptions import TaskResultDoesNotExist
+from django.tasks.signals import task_enqueued, task_finished, task_started
+from django.utils import timezone
+from django.utils.json import normalize_json
+
+
+class DatabaseTaskBackend(BaseTaskBackend):
+    """A task backend that persists tasks in the database."""
+
+    supports_defer = True
+    supports_async_task = True
+    supports_get_result = True
+    supports_priority = True
+
+    def enqueue(self, task, args, kwargs):
+        """Enqueue a task to the database.
+
+        Args and kwargs must be JSON-serializable. Supported types are:
+        - str, int, float, bool, None
+        - dict (with JSON-serializable keys and values)
+        - list, tuple (with JSON-serializable elements)
+        - bytes (UTF-8 decodable)
+
+        Raises:
+            TypeError: If args or kwargs contain non-JSON-serializable types.
+        """
+        from .models import DatabaseTask
+
+        self.validate_task(task)
+
+        # Normalize args and kwargs to ensure JSON serialization
+        # This will raise TypeError for unsupported types (e.g., datetime, UUID)
+        normalized_args = normalize_json(list(args))
+        normalized_kwargs = normalize_json(dict(kwargs))
+
+        now = timezone.now()
+        db_task = DatabaseTask.objects.create(
+            task_path=self._get_task_path(task),
+            queue_name=task.queue_name,
+            priority=task.priority,
+            args_json=normalized_args,
+            kwargs_json=normalized_kwargs,
+            status=TaskResultStatus.READY,
+            run_after=task.run_after,
+            enqueued_at=now,
+            backend_name=self.alias,
+        )
+
+        task_result = self._db_task_to_result(db_task, task)
+        task_enqueued.send(sender=self.__class__, task_result=task_result)
+
+        return task_result
+
+    def get_result(self, result_id):
+        """Retrieve a task result from the database."""
+        from .models import DatabaseTask
+
+        try:
+            db_task = DatabaseTask.objects.get(id=result_id)
+        except DatabaseTask.DoesNotExist as e:
+            raise TaskResultDoesNotExist(result_id) from e
+
+        task = self._resolve_task(db_task.task_path)
+        return self._db_task_to_result(db_task, task)
+
+    def _get_task_path(self, task):
+        """Get the module path of the task function."""
+        func = task.func
+        return f"{func.__module__}.{func.__qualname__}"
+
+    def _resolve_task(self, task_path):
+        """Resolve a Task object from its module path."""
+        module_path, func_name = task_path.rsplit(".", 1)
+        module = import_module(module_path)
+        func = getattr(module, func_name)
+        if isinstance(func, Task):
+            return func
+        return func
+
+    def _db_task_to_result(self, db_task, task):
+        """Convert a DatabaseTask model to a TaskResult."""
+        errors = [
+            TaskError(
+                exception_class_path=e.get("exception_class_path", ""),
+                traceback=e.get("traceback", ""),
+            )
+            for e in db_task.errors_json
+        ]
+
+        result = TaskResult(
+            task=task if isinstance(task, Task) else task,
+            id=str(db_task.id),
+            status=TaskResultStatus(db_task.status),
+            enqueued_at=db_task.enqueued_at,
+            started_at=db_task.started_at,
+            finished_at=db_task.finished_at,
+            last_attempted_at=db_task.last_attempted_at,
+            args=db_task.args_json,
+            kwargs=db_task.kwargs_json,
+            backend=db_task.backend_name,
+            errors=errors,
+            worker_ids=db_task.worker_ids_json,
+        )
+
+        if db_task.return_value_json is not None:
+            object.__setattr__(result, "_return_value", db_task.return_value_json)
+
+        return result
+
+    def run_task(self, db_task, worker_id=None):
+        """Execute a task (called from management command)."""
+
+        now = timezone.now()
+
+        # Update status to RUNNING
+        worker_ids = db_task.worker_ids_json.copy()
+        if worker_id:
+            worker_ids.append(worker_id)
+
+        db_task.status = TaskResultStatus.RUNNING
+        db_task.started_at = db_task.started_at or now
+        db_task.last_attempted_at = now
+        db_task.worker_ids_json = worker_ids
+        db_task.save(
+            update_fields=[
+                "status",
+                "started_at",
+                "last_attempted_at",
+                "worker_ids_json",
+                "updated_at",
+            ]
+        )
+
+        task = self._resolve_task(db_task.task_path)
+        task_result = self._db_task_to_result(db_task, task)
+        task_started.send(sender=self.__class__, task_result=task_result)
+
+        try:
+            # Get task function
+            if isinstance(task, Task):
+                func = task.func
+                takes_context = task.takes_context
+            else:
+                func = task
+                takes_context = False
+
+            # Prepare arguments
+            args = db_task.args_json
+            kwargs = db_task.kwargs_json.copy()
+
+            if takes_context:
+                context = TaskContext(task_result=task_result)
+                kwargs["context"] = context
+
+            # Execute task
+            if iscoroutinefunction(func):
+                return_value = asyncio.run(func(*args, **kwargs))
+            else:
+                return_value = func(*args, **kwargs)
+
+            # Normalize return value for JSON serialization
+            # This will raise TypeError for unsupported types
+            normalized_return_value = normalize_json(return_value)
+
+            # Success
+            db_task.status = TaskResultStatus.SUCCESSFUL
+            db_task.return_value_json = normalized_return_value
+            db_task.finished_at = timezone.now()
+            db_task.save(
+                update_fields=[
+                    "status",
+                    "return_value_json",
+                    "finished_at",
+                    "updated_at",
+                ]
+            )
+
+        except Exception as e:
+            # Failure
+            error = TaskError(
+                exception_class_path=f"{type(e).__module__}.{type(e).__qualname__}",
+                traceback=traceback.format_exc(),
+            )
+            errors = db_task.errors_json.copy()
+            errors.append(
+                {
+                    "exception_class_path": error.exception_class_path,
+                    "traceback": error.traceback,
+                }
+            )
+
+            db_task.status = TaskResultStatus.FAILED
+            db_task.errors_json = errors
+            db_task.finished_at = timezone.now()
+            db_task.save(
+                update_fields=["status", "errors_json", "finished_at", "updated_at"]
+            )
+
+        # Get final result and send signal
+        db_task.refresh_from_db()
+        final_result = self._db_task_to_result(db_task, task)
+        task_finished.send(sender=self.__class__, task_result=final_result)
+
+        return final_result

django_database_task/executor.py

@@ -0,0 +1,181 @@
+"""
+Public API for executing database tasks.
+
+This module provides functions to process tasks stored in the database
+without using management commands.
+
+Example usage:
+    from django_database_task import process_tasks, process_one_task
+
+    # Process a single task
+    result = process_one_task()
+
+    # Process multiple tasks
+    results = process_tasks(max_tasks=10)
+
+    # Process tasks from a specific queue
+    results = process_tasks(queue_name="emails", max_tasks=5)
+"""
+
+import socket
+import uuid
+
+from django.db import transaction
+from django.db.models import Q
+from django.tasks import task_backends
+from django.tasks.base import TaskResultStatus
+from django.utils import timezone
+
+from .models import DatabaseTask
+
+
+def _generate_worker_id():
+    """Generate a unique worker ID."""
+    return f"{socket.gethostname()}-{uuid.uuid4().hex[:8]}"
+
+
+def fetch_task(queue_name=None, backend_name="default"):
+    """
+    Fetch and lock a single pending task with exclusive lock.
+
+    This function uses SELECT FOR UPDATE SKIP LOCKED to safely
+    fetch a task without conflicts in multi-worker environments.
+
+    Args:
+        queue_name: Optional queue name to filter tasks.
+        backend_name: Backend name (default: "default").
+
+    Returns:
+        DatabaseTask instance if a task is available, None otherwise.
+    """
+    now = timezone.now()
+
+    with transaction.atomic():
+        queryset = DatabaseTask.objects.select_for_update(skip_locked=True).filter(
+            status=TaskResultStatus.READY,
+            backend_name=backend_name,
+        )
+
+        # run_after condition: NULL or before current time
+        queryset = queryset.filter(Q(run_after__isnull=True) | Q(run_after__lte=now))
+
+        if queue_name:
+            queryset = queryset.filter(queue_name=queue_name)
+
+        # Order by priority descending, enqueued_at ascending
+        task = queryset.order_by("-priority", "enqueued_at").first()
+
+        return task
+
+
+def process_one_task(queue_name=None, backend_name="default", worker_id=None):
+    """
+    Fetch and execute a single pending task.
+
+    Args:
+        queue_name: Optional queue name to filter tasks.
+        backend_name: Backend name (default: "default").
+        worker_id: Optional worker ID. If not provided, one will be generated.
+
+    Returns:
+        TaskResult if a task was processed, None if no task was available.
+
+    Example:
+        >>> from django_database_task import process_one_task
+        >>> result = process_one_task()
+        >>> if result:
+        ...     print(f"Processed: {result.id}, status: {result.status}")
+        ... else:
+        ...     print("No tasks available")
+    """
+    if worker_id is None:
+        worker_id = _generate_worker_id()
+
+    task = fetch_task(queue_name=queue_name, backend_name=backend_name)
+
+    if task is None:
+        return None
+
+    backend = task_backends[backend_name]
+    return backend.run_task(task, worker_id=worker_id)
+
+
+def process_tasks(
+    queue_name=None,
+    backend_name="default",
+    max_tasks=0,
+    worker_id=None,
+):
+    """
+    Process multiple pending tasks.
+
+    Args:
+        queue_name: Optional queue name to filter tasks.
+        backend_name: Backend name (default: "default").
+        max_tasks: Maximum number of tasks to process (0 = unlimited).
+        worker_id: Optional worker ID. If not provided, one will be generated.
+
+    Returns:
+        List of TaskResult objects for all processed tasks.
+
+    Example:
+        >>> from django_database_task import process_tasks
+        >>> results = process_tasks(max_tasks=10)
+        >>> print(f"Processed {len(results)} tasks")
+        >>> for result in results:
+        ...     print(f"  {result.id}: {result.status}")
+    """
+    if worker_id is None:
+        worker_id = _generate_worker_id()
+
+    results = []
+    tasks_processed = 0
+
+    while True:
+        result = process_one_task(
+            queue_name=queue_name,
+            backend_name=backend_name,
+            worker_id=worker_id,
+        )
+
+        if result is None:
+            break
+
+        results.append(result)
+        tasks_processed += 1
+
+        if max_tasks and tasks_processed >= max_tasks:
+            break
+
+    return results
+
+
+def get_pending_task_count(queue_name=None, backend_name="default"):
+    """
+    Get the count of pending tasks.
+
+    Args:
+        queue_name: Optional queue name to filter tasks.
+        backend_name: Backend name (default: "default").
+
+    Returns:
+        Number of pending tasks.
+
+    Example:
+        >>> from django_database_task import get_pending_task_count
+        >>> count = get_pending_task_count()
+        >>> print(f"Pending tasks: {count}")
+    """
+    now = timezone.now()
+
+    queryset = DatabaseTask.objects.filter(
+        status=TaskResultStatus.READY,
+        backend_name=backend_name,
+    )
+
+    queryset = queryset.filter(Q(run_after__isnull=True) | Q(run_after__lte=now))
+
+    if queue_name:
+        queryset = queryset.filter(queue_name=queue_name)
+
+    return queryset.count()