dj-queue 0.5.0__tar.gz → 0.5.1__tar.gz

{dj_queue-0.5.0 → dj_queue-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dj-queue
-Version: 0.5.0
+Version: 0.5.1
 Summary: Database-backed task queue backend for Django’s Tasks framework.
 License-Expression: MIT
 License-File: LICENSE
@@ -549,6 +549,41 @@ except EnqueueError as exc:
 Task execution errors are different: they become failed jobs and stay
 inspectable in the queue database.
 
+## Lifecycle Hooks
+
+Register hooks before starting the runtime, typically during Django startup.
+Each callback receives the live supervisor or runner instance.
+
+```python
+from dj_queue.hooks import on_start, on_worker_start, register_hook
+
+@on_start
+def supervisor_started(process):
+  print(process.name)
+
+@on_worker_start
+def worker_started(process):
+  print(process.metadata)
+
+@register_hook("scheduler.exit")
+def scheduler_exited(process):
+  print(process.name)
+```
+
+Available hook helpers:
+
+- supervisor: `on_start`, `on_stop`, `on_exit`
+- worker: `on_worker_start`, `on_worker_stop`, `on_worker_exit`
+- dispatcher: `on_dispatcher_start`, `on_dispatcher_stop`, `on_dispatcher_exit`
+- scheduler: `on_scheduler_start`, `on_scheduler_stop`, `on_scheduler_exit`
+- generic events: `register_hook("worker.start")`, `register_hook("dispatcher.stop")`, and so on
+
+Hook notes:
+
+- hooks fire in registration order
+- hook failures do not block later hooks
+- hook failures are isolated and routed through `on_thread_error`
+
 ## Multi-Database Setup
 
 `dj_queue` can keep queue tables on a dedicated database alias.
@@ -644,6 +679,21 @@ signal handling to the host server.
 
 ## Configuration
 
+### Queues, backends, and databases
+
+`dj_queue` has three separate routing concepts. Keep them distinct:
+
+- `queue_name`: what kind of work this job is. Use it to route lanes inside one backend, such as `email`, `webhooks`, or `search-index`.
+- `backend_alias`: which logical queue system owns the work. Use it when you want separate runtime config, recurring tasks, pause and process visibility, retention, or admin scoping.
+- `database_alias`: where that backend's queue tables and runtime activity live. Use it when you want a dedicated database connection path or stronger storage isolation.
+
+Common setup choices:
+
+- one backend, one database: simplest and usually enough
+- one backend, separate queue database: good when you want dedicated queue connections
+- multiple backends, same database: good for logical and operational separation without another database
+- multiple backends, multiple databases: use when you need stronger isolation and accept more migration and deployment complexity
+
 ### Deployment topology
 
 Once migrations are in place, start processing jobs with `python manage.py dj_queue`
@@ -792,41 +842,6 @@ Environment overrides currently supported by `dj_queue` itself:
 - `DJ_QUEUE_MODE`
 - `DJ_QUEUE_SKIP_RECURRING`
 
-## Lifecycle Hooks
-
-Register hooks before starting the runtime, typically during Django startup.
-Each callback receives the live supervisor or runner instance.
-
-```python
-from dj_queue.hooks import on_start, on_worker_start, register_hook
-
-@on_start
-def supervisor_started(process):
-  print(process.name)
-
-@on_worker_start
-def worker_started(process):
-  print(process.metadata)
-
-@register_hook("scheduler.exit")
-def scheduler_exited(process):
-  print(process.name)
-```
-
-Available hook helpers:
-
-- supervisor: `on_start`, `on_stop`, `on_exit`
-- worker: `on_worker_start`, `on_worker_stop`, `on_worker_exit`
-- dispatcher: `on_dispatcher_start`, `on_dispatcher_stop`, `on_dispatcher_exit`
-- scheduler: `on_scheduler_start`, `on_scheduler_stop`, `on_scheduler_exit`
-- generic events: `register_hook("worker.start")`, `register_hook("dispatcher.stop")`, and so on
-
-Hook notes:
-
-- hooks fire in registration order
-- hook failures do not block later hooks
-- hook failures are isolated and routed through `on_thread_error`
-
 ### Runtime infrastructure errors
 
 Set `on_thread_error` to a dotted callable path when you want custom handling
@@ -852,7 +867,7 @@ become failed jobs instead.
 ## Monitoring
 
 Queue statistics are available in JSON via `/dj_queue/stats.json` and in
-Prometheus text format via `/dj_queue/metrics`. 
+Prometheus text format via `/dj_queue/metrics`.
 
 Include `dj_queue.urls` to expose them:
 

{dj_queue-0.5.0 → dj_queue-0.5.1}/README.md

@@ -521,6 +521,41 @@ except EnqueueError as exc:
 Task execution errors are different: they become failed jobs and stay
 inspectable in the queue database.
 
+## Lifecycle Hooks
+
+Register hooks before starting the runtime, typically during Django startup.
+Each callback receives the live supervisor or runner instance.
+
+```python
+from dj_queue.hooks import on_start, on_worker_start, register_hook
+
+@on_start
+def supervisor_started(process):
+  print(process.name)
+
+@on_worker_start
+def worker_started(process):
+  print(process.metadata)
+
+@register_hook("scheduler.exit")
+def scheduler_exited(process):
+  print(process.name)
+```
+
+Available hook helpers:
+
+- supervisor: `on_start`, `on_stop`, `on_exit`
+- worker: `on_worker_start`, `on_worker_stop`, `on_worker_exit`
+- dispatcher: `on_dispatcher_start`, `on_dispatcher_stop`, `on_dispatcher_exit`
+- scheduler: `on_scheduler_start`, `on_scheduler_stop`, `on_scheduler_exit`
+- generic events: `register_hook("worker.start")`, `register_hook("dispatcher.stop")`, and so on
+
+Hook notes:
+
+- hooks fire in registration order
+- hook failures do not block later hooks
+- hook failures are isolated and routed through `on_thread_error`
+
 ## Multi-Database Setup
 
 `dj_queue` can keep queue tables on a dedicated database alias.
@@ -616,6 +651,21 @@ signal handling to the host server.
 
 ## Configuration
 
+### Queues, backends, and databases
+
+`dj_queue` has three separate routing concepts. Keep them distinct:
+
+- `queue_name`: what kind of work this job is. Use it to route lanes inside one backend, such as `email`, `webhooks`, or `search-index`.
+- `backend_alias`: which logical queue system owns the work. Use it when you want separate runtime config, recurring tasks, pause and process visibility, retention, or admin scoping.
+- `database_alias`: where that backend's queue tables and runtime activity live. Use it when you want a dedicated database connection path or stronger storage isolation.
+
+Common setup choices:
+
+- one backend, one database: simplest and usually enough
+- one backend, separate queue database: good when you want dedicated queue connections
+- multiple backends, same database: good for logical and operational separation without another database
+- multiple backends, multiple databases: use when you need stronger isolation and accept more migration and deployment complexity
+
 ### Deployment topology
 
 Once migrations are in place, start processing jobs with `python manage.py dj_queue`
@@ -764,41 +814,6 @@ Environment overrides currently supported by `dj_queue` itself:
 - `DJ_QUEUE_MODE`
 - `DJ_QUEUE_SKIP_RECURRING`
 
-## Lifecycle Hooks
-
-Register hooks before starting the runtime, typically during Django startup.
-Each callback receives the live supervisor or runner instance.
-
-```python
-from dj_queue.hooks import on_start, on_worker_start, register_hook
-
-@on_start
-def supervisor_started(process):
-  print(process.name)
-
-@on_worker_start
-def worker_started(process):
-  print(process.metadata)
-
-@register_hook("scheduler.exit")
-def scheduler_exited(process):
-  print(process.name)
-```
-
-Available hook helpers:
-
-- supervisor: `on_start`, `on_stop`, `on_exit`
-- worker: `on_worker_start`, `on_worker_stop`, `on_worker_exit`
-- dispatcher: `on_dispatcher_start`, `on_dispatcher_stop`, `on_dispatcher_exit`
-- scheduler: `on_scheduler_start`, `on_scheduler_stop`, `on_scheduler_exit`
-- generic events: `register_hook("worker.start")`, `register_hook("dispatcher.stop")`, and so on
-
-Hook notes:
-
-- hooks fire in registration order
-- hook failures do not block later hooks
-- hook failures are isolated and routed through `on_thread_error`
-
 ### Runtime infrastructure errors
 
 Set `on_thread_error` to a dotted callable path when you want custom handling
@@ -824,7 +839,7 @@ become failed jobs instead.
 ## Monitoring
 
 Queue statistics are available in JSON via `/dj_queue/stats.json` and in
-Prometheus text format via `/dj_queue/metrics`. 
+Prometheus text format via `/dj_queue/metrics`.
 
 Include `dj_queue.urls` to expose them:
 

{dj_queue-0.5.0 → dj_queue-0.5.1}/dj_queue/admin.py

@@ -458,8 +458,9 @@ class JobAdmin(HiddenSidebarAdminMixin, admin.ModelAdmin):
   )
   readonly_fields = (
     "task_path",
-    "queue_name",
+    "queue_name_link",
     "priority",
+    "display_status",
     "payload",
     "backend_alias",
     "scheduled_at",
@@ -475,6 +476,9 @@ class JobAdmin(HiddenSidebarAdminMixin, admin.ModelAdmin):
   )
   search_fields = ("id", "task_path", "queue_name", "concurrency_key")
 
+  def get_fields(self, request, obj=None):
+    return self.get_readonly_fields(request, obj)
+
   def get_readonly_fields(self, request, obj=None):
     fields = super().get_readonly_fields(request, obj)
     if obj is None or obj.status != "failed":

{dj_queue-0.5.0 → dj_queue-0.5.1}/dj_queue/api.py

@@ -1,5 +1,6 @@
 from functools import partial
 
+from django.db.models import Case, DateTimeField, DurationField, ExpressionWrapper, F, Value, When
 from django.db.models.functions import Coalesce
 from django.db import transaction
 from django.utils import timezone
@@ -66,17 +67,29 @@ class QueueInfo:
 
       resumed_at = timezone.now()
       paused_at = pause.created_at
-      ready_rows = list(
-        ReadyExecution.objects.using(alias)
-        .filter(queue_name=self.queue_name)
-        .only("id", "created_at", "latency_started_at")
-      )
-      for ready_row in ready_rows:
-        started_at = ready_row.latency_started_at or ready_row.created_at
-        overlap_started_at = max(started_at, paused_at)
-        ready_row.latency_started_at = started_at + (resumed_at - overlap_started_at)
-      if ready_rows:
-        ReadyExecution.objects.using(alias).bulk_update(ready_rows, ["latency_started_at"])
+      pause_duration = Value(resumed_at - paused_at, output_field=DurationField())
+      ready_row_ids = list(self._ready_queryset().values_list("id", flat=True))
+      if ready_row_ids:
+        ReadyExecution.objects.using(alias).filter(pk__in=ready_row_ids).update(
+          latency_started_at=Case(
+            When(
+              latency_started_at__isnull=True,
+              created_at__lt=paused_at,
+              then=ExpressionWrapper(
+                F("created_at") + pause_duration, output_field=DateTimeField()
+              ),
+            ),
+            When(
+              latency_started_at__lt=paused_at,
+              then=ExpressionWrapper(
+                F("latency_started_at") + pause_duration,
+                output_field=DateTimeField(),
+              ),
+            ),
+            default=Value(resumed_at, output_field=DateTimeField()),
+            output_field=DateTimeField(),
+          ),
+        )
       pause.delete()
 
     log_event("queue.resumed", backend_alias=self.backend_alias, queue_name=self.queue_name)

{dj_queue-0.5.0 → dj_queue-0.5.1}/dj_queue/contrib/asgi.py

@@ -12,6 +12,12 @@ class DjQueueLifespan:
     self.app = app
     self.backend_alias = backend_alias
     self.supervisor = None
+    self._poll_task = None
+
+  async def _poll_supervisor(self):
+    while self.supervisor is not None:
+      await asyncio.to_thread(self.supervisor.poll_once)
+      await asyncio.sleep(self.supervisor.polling_interval)
 
   async def __call__(self, scope, receive, send):
     if scope["type"] != "lifespan":
@@ -23,8 +29,17 @@ class DjQueueLifespan:
       if message["type"] == "lifespan.startup":
         self.supervisor = build_supervisor(self.backend_alias)
         await asyncio.to_thread(self.supervisor.start)
+        self._poll_task = asyncio.create_task(self._poll_supervisor())
         await send({"type": "lifespan.startup.complete"})
       elif message["type"] == "lifespan.shutdown":
+        poll_task = self._poll_task
+        self._poll_task = None
+        if poll_task is not None:
+          poll_task.cancel()
+          try:
+            await poll_task
+          except asyncio.CancelledError:
+            pass
         if self.supervisor is not None:
           await asyncio.to_thread(self.supervisor.stop)
           self.supervisor = None

{dj_queue-0.5.0 → dj_queue-0.5.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "dj-queue"
-version = "0.5.0"
+version = "0.5.1"
 description = "Database-backed task queue backend for Django’s Tasks framework."
 readme = "README.md"
 license = "MIT"