dj-queue 0.2.2__tar.gz → 0.2.3__tar.gz

{dj_queue-0.2.2 → dj_queue-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dj-queue
-Version: 0.2.2
+Version: 0.2.3
 Summary: Database-backed task queue backend for Django's django.tasks framework
 License-Expression: MIT
 License-File: LICENSE
@@ -27,11 +27,11 @@ Description-Content-Type: text/markdown
 # dj_queue
 
 [![CI](https://github.com/coriocactus/dj_queue/actions/workflows/ci.yml/badge.svg)](https://github.com/coriocactus/dj_queue/actions/workflows/ci.yml)
-![PyPI](https://img.shields.io/pypi/v/dj-queue.svg)
+[![PyPI](https://img.shields.io/pypi/v/dj-queue.svg)](https://pypi.org/project/dj-queue/)
 [![Latest on Django Packages](https://img.shields.io/badge/pypi/dj-queue-tags.svg)](https://djangopackages.org/packages/p/dj-queue/)
 ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/dj-queue.svg)
 ![PyPI - Status](https://img.shields.io/pypi/status/dj-queue.svg)
-![PyPI - License](https://img.shields.io/pypi/l/dj-queue.svg)
+[![PyPI - License](https://img.shields.io/pypi/l/dj-queue.svg)](https://github.com/coriocactus/dj_queue/blob/main/LICENSE)
 
 `dj_queue` is a database-backed task queue backend for the `django.tasks` framework.
 
@@ -59,7 +59,7 @@ It has a narrow, explicit shape:
 - polling remains the correctness path on every supported database
 
 For detailed comparisons with Celery, RQ, Procrastinate, and other alternatives,
-see [COMPARISONS.md](COMPARISONS.md).
+see [COMPARISONS.md](docs/COMPARISONS.md).
 
 ## Installation
 
@@ -156,6 +156,25 @@ print(fresh_result.return_value)
 
 When the worker has executed the job, `fresh_result.return_value` will be `10`.
 
+## Admin Integration
+
+If Django admin is installed, `dj_queue` adds an operator dashboard at
+`/admin/dj_queue/dashboard/`.
+
+- queue, process, recurring-task, and semaphore overview
+- backend-aware dashboard and raw changelists
+- queue controls: pause, resume, clear ready
+- failed-job actions: retry and discard from list and detail views
+- queue drill-down pages for state-specific inspection
+
+**Dashboard overview**
+
+![dj_queue admin dashboard](docs/dashboard.png)
+
+**Queue drill-down**
+
+![dj_queue admin dashboard - queue](docs/dashboard-queue.png)
+
 ## Common Patterns
 
 ### Scheduled jobs
@@ -406,10 +425,6 @@ python manage.py dj_queue_prune --older-than 86400
 python manage.py dj_queue_prune --task-path myapp.tasks.cleanup
 ```
 
-If Django admin is installed, `dj_queue` also registers the main operational
-models there, including jobs, failed executions, processes, recurring tasks,
-pauses, and semaphores.
-
 ## Failed Jobs
 
 When a task raises, `dj_queue` keeps the job and its failed execution row in the

{dj_queue-0.2.2 → dj_queue-0.2.3}/README.md

@@ -1,11 +1,11 @@
 # dj_queue
 
 [![CI](https://github.com/coriocactus/dj_queue/actions/workflows/ci.yml/badge.svg)](https://github.com/coriocactus/dj_queue/actions/workflows/ci.yml)
-![PyPI](https://img.shields.io/pypi/v/dj-queue.svg)
+[![PyPI](https://img.shields.io/pypi/v/dj-queue.svg)](https://pypi.org/project/dj-queue/)
 [![Latest on Django Packages](https://img.shields.io/badge/pypi/dj-queue-tags.svg)](https://djangopackages.org/packages/p/dj-queue/)
 ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/dj-queue.svg)
 ![PyPI - Status](https://img.shields.io/pypi/status/dj-queue.svg)
-![PyPI - License](https://img.shields.io/pypi/l/dj-queue.svg)
+[![PyPI - License](https://img.shields.io/pypi/l/dj-queue.svg)](https://github.com/coriocactus/dj_queue/blob/main/LICENSE)
 
 `dj_queue` is a database-backed task queue backend for the `django.tasks` framework.
 
@@ -33,7 +33,7 @@ It has a narrow, explicit shape:
 - polling remains the correctness path on every supported database
 
 For detailed comparisons with Celery, RQ, Procrastinate, and other alternatives,
-see [COMPARISONS.md](COMPARISONS.md).
+see [COMPARISONS.md](docs/COMPARISONS.md).
 
 ## Installation
 
@@ -130,6 +130,25 @@ print(fresh_result.return_value)
 
 When the worker has executed the job, `fresh_result.return_value` will be `10`.
 
+## Admin Integration
+
+If Django admin is installed, `dj_queue` adds an operator dashboard at
+`/admin/dj_queue/dashboard/`.
+
+- queue, process, recurring-task, and semaphore overview
+- backend-aware dashboard and raw changelists
+- queue controls: pause, resume, clear ready
+- failed-job actions: retry and discard from list and detail views
+- queue drill-down pages for state-specific inspection
+
+**Dashboard overview**
+
+![dj_queue admin dashboard](docs/dashboard.png)
+
+**Queue drill-down**
+
+![dj_queue admin dashboard - queue](docs/dashboard-queue.png)
+
 ## Common Patterns
 
 ### Scheduled jobs
@@ -380,10 +399,6 @@ python manage.py dj_queue_prune --older-than 86400
 python manage.py dj_queue_prune --task-path myapp.tasks.cleanup
 ```
 
-If Django admin is installed, `dj_queue` also registers the main operational
-models there, including jobs, failed executions, processes, recurring tasks,
-pauses, and semaphores.
-
 ## Failed Jobs
 
 When a task raises, `dj_queue` keeps the job and its failed execution row in the

{dj_queue-0.2.2 → dj_queue-0.2.3}/dj_queue/dashboard.py

@@ -15,7 +15,7 @@ from django.utils import timezone
 
 from dj_queue.api import QueueInfo
 from dj_queue.config import load_backend_config
-from dj_queue.db import get_database_alias
+from dj_queue.db import database_capabilities, get_database_alias
 from dj_queue.models import (
   BlockedExecution,
   ClaimedExecution,
@@ -44,12 +44,14 @@ QUEUE_STATE_LABELS = dict(QUEUE_STATES)
 PAGE_SIZE = 100
 OVERVIEW_PAGE_SIZES = {
   "queues": 18,
+  "shared_queues": 5,
   "processes": 10,
   "recurring": 12,
   "semaphores": 12,
 }
 OVERVIEW_COUNT_LABELS = {
   "queues": ("queue", "queues"),
+  "shared_queues": ("shared queue", "shared queues"),
   "processes": ("process", "processes"),
   "recurring": ("recurring task", "recurring tasks"),
   "semaphores": ("semaphore", "semaphores"),
@@ -80,6 +82,19 @@ OVERVIEW_SORTS = {
       },
     },
   },
+  "shared_queues": {
+    "default": "name",
+    "fields": {
+      "name": {"label": "name", "key": "name", "default_desc": False, "css_class": "djq-col-name"},
+      "shared_via": {
+        "label": "shared via",
+        "key": "shared_source_labels",
+        "default_desc": False,
+        "css_class": "djq-col-shared-via",
+      },
+      "paused": {"label": "paused", "key": "paused", "default_desc": True},
+    },
+  },
   "processes": {
     "default": "status",
     "fields": {
@@ -272,6 +287,7 @@ def dashboard_context(*, backend_alias, query_params=None):
     query_params = {}
 
   queue_rows = _queue_rows(backend_alias=backend_alias, now=now, process_cutoff=process_cutoff)
+  backend_queue_rows, shared_queue_rows = _split_queue_rows(queue_rows)
   process_rows = _process_rows(
     backend_alias=backend_alias,
     now=now,
@@ -287,7 +303,7 @@ def dashboard_context(*, backend_alias, query_params=None):
     "queue_database_alias": queue_database_alias,
     "summary_cards": _summary_cards(
       backend_alias=backend_alias,
-      queue_rows=queue_rows,
+      queue_rows=backend_queue_rows,
       process_rows=process_rows,
       recurring_rows=recurring_rows,
       semaphore_rows=semaphore_rows,
@@ -300,13 +316,22 @@ def dashboard_context(*, backend_alias, query_params=None):
     ),
     "queue_section": _overview_section(
       section="queues",
-      rows=queue_rows,
+      rows=backend_queue_rows,
       page_param="queues_page",
       page_size=OVERVIEW_PAGE_SIZES["queues"],
       sort_param="queues_sort",
       query_params=query_params,
       anchor="queue-summary",
     ),
+    "shared_queue_section": _overview_section(
+      section="shared_queues",
+      rows=shared_queue_rows,
+      page_param="shared_queues_page",
+      page_size=OVERVIEW_PAGE_SIZES["shared_queues"],
+      sort_param="shared_queues_sort",
+      query_params=query_params,
+      anchor="shared-queue-summary",
+    ),
     "process_section": _overview_section(
       section="processes",
       rows=process_rows,
@@ -374,7 +399,7 @@ def queue_page_context(*, backend_alias, queue_name, state, page_number, query_p
   if sum(state_counts.values()):
     raw_links.append(
       {
-        "label": "raw jobs",
+        "label": "Raw jobs",
         "url": _job_changelist_url(
           backend_alias,
           queue_name=queue_name,
@@ -385,7 +410,7 @@ def queue_page_context(*, backend_alias, queue_name, state, page_number, query_p
   if state_counts["failed"]:
     raw_links.append(
       {
-        "label": "failed executions",
+        "label": "Failed executions",
         "url": _failed_execution_changelist_url(
           backend_alias,
           job__queue_name=queue_name,
@@ -448,6 +473,9 @@ def apply_queue_action(*, backend_alias, queue_name, action):
 
 
 def apply_job_action(*, backend_alias, queue_name, state, action, job_ids):
+  if not action:
+    raise ValueError("No action selected.")
+
   if not job_ids:
     raise ValueError("select at least one job")
 
@@ -557,17 +585,42 @@ def _summary_cards(*, backend_alias, queue_rows, process_rows, recurring_rows, s
   )
 
 
+def _split_queue_rows(queue_rows):
+  backend_queue_rows = []
+  shared_queue_rows = []
+  for row in queue_rows:
+    if row["has_backend_jobs"]:
+      backend_queue_rows.append(row)
+      continue
+    shared_queue_rows.append(row)
+  return backend_queue_rows, shared_queue_rows
+
+
 def _backend_facts(*, config, queue_database_alias, recurring_count, semaphore_count):
   retention = "disabled"
   if config.clear_finished_jobs_after is not None:
     retention = f"{config.clear_finished_jobs_after}s"
 
+  capabilities = database_capabilities(queue_database_alias)
+
   return (
     {"label": "mode", "value": config.mode},
     {"label": "queue db", "value": queue_database_alias},
     {"label": "scheduler", "value": "enabled" if config.has_scheduler_work else "disabled"},
-    {"label": "notify", "value": "on" if config.listen_notify else "off"},
-    {"label": "skip locked", "value": "on" if config.use_skip_locked else "off"},
+    {
+      "label": "notify",
+      "value": _capability_fact_value(
+        enabled=config.listen_notify,
+        supported=capabilities.supports_listen_notify,
+      ),
+    },
+    {
+      "label": "skip locked",
+      "value": _capability_fact_value(
+        enabled=config.use_skip_locked,
+        supported=capabilities.supports_skip_locked,
+      ),
+    },
     {"label": "heartbeat", "value": f"{config.process_alive_threshold}s"},
     {"label": "retention", "value": retention},
     {"label": "recurring", "value": str(recurring_count)},
@@ -575,6 +628,14 @@ def _backend_facts(*, config, queue_database_alias, recurring_count, semaphore_c
   )
 
 
+def _capability_fact_value(*, enabled, supported):
+  if not supported:
+    return "unsupported"
+  if enabled:
+    return "on"
+  return "off"
+
+
 def _overview_section(*, section, rows, page_param, page_size, sort_param, query_params, anchor):
   raw_sort = query_params.get(sort_param)
   sort, explicit_sort = _resolve_overview_sort(section=section, raw_sort=raw_sort)
@@ -1168,19 +1229,43 @@ def _queue_rows(*, backend_alias, now, process_cutoff):
     if oldest_ready_at is not None:
       latency_seconds = max((now - oldest_ready_at).total_seconds(), 0.0)
 
+    ready_count = ready_counts.get(queue_name, 0)
+    claimed_count = claimed_counts.get(queue_name, 0)
+    scheduled_count = scheduled_counts.get(queue_name, 0)
+    blocked_count = blocked_counts.get(queue_name, 0)
+    failed_count = failed_counts.get(queue_name, 0)
+    finished_count = finished_counts.get(queue_name, 0)
+    shared_sources = []
+    if queue_name in paused_queues:
+      shared_sources.append("pause")
+    if queue_name in recurring_queues:
+      shared_sources.append("recurring task")
+
     rows.append(
       {
         "name": queue_name,
-        "ready_count": ready_counts.get(queue_name, 0),
-        "claimed_count": claimed_counts.get(queue_name, 0),
-        "scheduled_count": scheduled_counts.get(queue_name, 0),
-        "blocked_count": blocked_counts.get(queue_name, 0),
-        "failed_count": failed_counts.get(queue_name, 0),
-        "finished_count": finished_counts.get(queue_name, 0),
+        "ready_count": ready_count,
+        "claimed_count": claimed_count,
+        "scheduled_count": scheduled_count,
+        "blocked_count": blocked_count,
+        "failed_count": failed_count,
+        "finished_count": finished_count,
         "paused": queue_name in paused_queues,
         "latency_seconds": latency_seconds,
         "oldest_scheduled_at": oldest_scheduled.get(queue_name),
         "oldest_blocked_at": oldest_blocked.get(queue_name),
+        "has_backend_jobs": any(
+          (
+            ready_count,
+            claimed_count,
+            scheduled_count,
+            blocked_count,
+            failed_count,
+            finished_count,
+          )
+        ),
+        "shared_sources": tuple(shared_sources),
+        "shared_source_labels": ", ".join(shared_sources),
         "live_worker_count": sum(
           1
           for worker in live_workers

{dj_queue-0.2.2 → dj_queue-0.2.3}/dj_queue/templates/admin/dj_queue/dashboard.html

@@ -332,6 +332,27 @@
       min-width: 48rem;
     }
 
+    .djq-table-shared-queues {
+      min-width: 56rem;
+      table-layout: fixed;
+    }
+
+    .djq-table-shared-queues col.djq-shared-col-name {
+      width: 20%;
+    }
+
+    .djq-table-shared-queues col.djq-shared-col-via {
+      width: 20%;
+    }
+
+    .djq-table-shared-queues col.djq-shared-col-paused {
+      width: 20%;
+    }
+
+    .djq-table-shared-queues col.djq-shared-col-controls {
+      width: 20%;
+    }
+
     .djq-table th,
     .djq-table td {
       white-space: nowrap;
@@ -367,6 +388,15 @@
       white-space: normal;
     }
 
+    .djq-col-shared-via {
+      min-width: 16rem;
+    }
+
+    .djq-table-shared-queues .djq-col-controls,
+    .djq-table-shared-queues td.djq-col-controls {
+      min-width: 13rem;
+    }
+
     .djq-process-row-group {
       background: var(--selected-bg);
     }
@@ -435,6 +465,26 @@
       line-height: 1.45;
     }
 
+    .djq-reason-list {
+      display: flex;
+      gap: 0.45rem;
+      flex-wrap: wrap;
+    }
+
+    .djq-reason-pill {
+      display: inline-flex;
+      align-items: center;
+      min-height: 1.6rem;
+      padding: 0 0.6rem;
+      border: 1px solid var(--hairline-color);
+      border-radius: 999px;
+      background: var(--body-bg);
+      color: var(--body-quiet-color);
+      font-size: 0.76rem;
+      font-weight: 600;
+      line-height: 1;
+    }
+
     @media (max-width: 900px) {
       .djq-summary-grid {
         grid-template-columns: repeat(2, minmax(0, 1fr));
@@ -475,7 +525,7 @@
             <form method="get" action="{% url 'admin:dj_queue_dashboard_changelist' %}">
               <select id="id_backend" name="backend" onchange="this.form.submit()">
                 {% for choice in backend_choices %}
-                  <option value="{{ choice.alias }}"{% if choice.alias == backend_alias %} selected{% endif %}>{{ choice.alias }} (db {{ choice.database_alias }})</option>
+                  <option value="{{ choice.alias }}"{% if choice.alias == backend_alias %} selected{% endif %}>{{ choice.alias }}</option>
                 {% endfor %}
               </select>
               <noscript><button type="submit" class="button">Switch</button></noscript>
@@ -521,7 +571,7 @@
 
     <section class="module djq-section" id="queue-summary">
       <div class="djq-section-banner"><h2>queues</h2></div>
-      <p class="djq-section-copy">Live queue pressure, pause state, and first-line controls for this backend.</p>
+      <p class="djq-section-copy">Live queue pressure, pause state, and first-line controls for this backend.{% if shared_queue_section.total_count %} Shared pause or recurring-only queues are available in a separate section below.{% endif %}</p>
       {% if queue_section.rows %}
         <div class="djq-table-wrap">
           <table class="djq-table djq-table-queues" id="result_list">
@@ -800,6 +850,88 @@
       {% endif %}
     </section>
 
+    {% if shared_queue_section.total_count %}
+      <section class="module djq-section" id="shared-queue-summary">
+        <div class="djq-section-banner"><h2>shared queues</h2></div>
+        <p class="djq-section-copy">These queues have no jobs for backend <strong>{{ backend_alias }}</strong> and are shown separately because pause and recurring-task rows are shared on queue database <strong>{{ queue_database_alias }}</strong>.</p>
+        <div class="djq-table-wrap">
+          <table class="djq-table djq-table-shared-queues">
+            <colgroup>
+              <col class="djq-shared-col-name">
+              <col class="djq-shared-col-via">
+              <col class="djq-shared-col-paused">
+              <col class="djq-shared-col-controls">
+            </colgroup>
+            <thead>
+              <tr>
+                {% for header in shared_queue_section.headers %}
+                  <th scope="col"{{ header.class_attrib|safe }}>
+                    {% if header.sortable and header.sorted %}
+                      <div class="sortoptions">
+                        <a class="sortremove" href="{{ header.url_remove }}" title="Remove from sorting"></a>
+                        {% if shared_queue_section.num_sorted_fields > 1 %}<span class="sortpriority" title="Sorting priority: {{ header.sort_priority }}">{{ header.sort_priority }}</span>{% endif %}
+                        <a href="{{ header.url_toggle }}" class="toggle {{ header.ascending|yesno:'ascending,descending' }}" title="Toggle sorting"></a>
+                      </div>
+                    {% endif %}
+                    <div class="text"><a role="button" href="{{ header.url_primary }}">{{ header.text|capfirst }}</a></div>
+                    <div class="clear"></div>
+                  </th>
+                {% endfor %}
+                <th scope="col" class="djq-col-controls"><div class="text">Controls</div></th>
+              </tr>
+            </thead>
+            <tbody>
+              {% for queue in shared_queue_section.rows %}
+                <tr class="{% cycle 'row1' 'row2' %}">
+                  <th class="djq-col-name"><a href="{% url 'admin:dj_queue_dashboard_queue' queue.name %}?backend={{ backend_alias }}&state=ready">{{ queue.name }}</a></th>
+                  <td>
+                    <div class="djq-reason-list">
+                      {% for source in queue.shared_sources %}
+                        <span class="djq-reason-pill">{{ source }}</span>
+                      {% endfor %}
+                    </div>
+                  </td>
+                  <td>{{ queue.paused|yesno:"yes,no" }}</td>
+                  <td class="djq-col-controls">
+                    <div class="djq-queue-controls">
+                      <form method="post" action="{% url 'admin:dj_queue_dashboard_queue_action' queue.name %}">
+                        {% csrf_token %}
+                        <input type="hidden" name="backend" value="{{ backend_alias }}">
+                        <input type="hidden" name="next" value="{{ request.get_full_path }}">
+                        <input type="hidden" name="action" value="{% if queue.paused %}resume{% else %}pause{% endif %}">
+                        <button type="submit" class="button {% if queue.paused %}djq-button-resume{% else %}djq-button-pause{% endif %}">{% if queue.paused %}resume{% else %}pause{% endif %}</button>
+                      </form>
+                    </div>
+                  </td>
+                </tr>
+              {% endfor %}
+            </tbody>
+          </table>
+        </div>
+        <div class="djq-table-footer">
+          <nav class="paginator" aria-labelledby="pagination-shared-queues">
+            <h2 id="pagination-shared-queues" class="visually-hidden">Pagination shared queues</h2>
+            {% if shared_queue_section.pagination_required %}
+              <ul>
+                {% for link in shared_queue_section.page_links %}
+                  <li>
+                    {% if link.is_ellipsis %}
+                      {{ link.label }}
+                    {% elif link.is_current %}
+                      <span aria-current="page">{{ link.number }}</span>
+                    {% else %}
+                      <a role="button" href="{{ link.url }}">{{ link.number }}</a>
+                    {% endif %}
+                  </li>
+                {% endfor %}
+              </ul>
+            {% endif %}
+            {{ shared_queue_section.result_count_text }}
+          </nav>
+        </div>
+      </section>
+    {% endif %}
+
     <section class="module djq-section" id="raw-summary">
       <div class="djq-section-banner"><h2>inspect raw rows</h2></div>
       <p class="djq-section-copy">Use the model changelists for exhaustive filtering, lower-level debugging, and record-by-record inspection.</p>

{dj_queue-0.2.2 → dj_queue-0.2.3}/dj_queue/templates/admin/dj_queue/queue_jobs.html

@@ -55,6 +55,10 @@
       margin: 0;
     }
 
+    #toolbar .queue-toolbar-meta strong {
+      text-transform: uppercase;
+    }
+
     #toolbar .queue-toolbar-actions button {
       border: none;
       border-radius: 15px;
@@ -210,8 +214,9 @@
           <div id="toolbar">
             <div class="queue-toolbar-row">
               <div class="queue-toolbar-meta">
-                <span><strong>backend:</strong> {{ backend_alias }} (db {{ queue_database_alias }})</span>
-                <span><strong>paused:</strong> {{ queue_paused|yesno:"yes,no" }}</span>
+                <span><strong>Backend:</strong> {{ backend_alias }}</span>
+                <span><strong>Database:</strong> {{ queue_database_alias }}</span>
+                <span><strong>Paused:</strong> {{ queue_paused|yesno:"yes,no" }}</span>
               </div>
               <div class="queue-toolbar-actions">
                 <form method="post" action="{% url 'admin:dj_queue_dashboard_queue_action' queue_name %}">
@@ -265,6 +270,7 @@
               <div class="actions">
                 <label for="action">Action:
                   <select name="action" id="action">
+                    <option value="" selected>---------</option>
                     {% for action in job_actions %}
                       <option value="{{ action.name }}">{{ action.label }}</option>
                     {% endfor %}

{dj_queue-0.2.2 → dj_queue-0.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "dj-queue"
-version = "0.2.2"
+version = "0.2.3"
 description = "Database-backed task queue backend for Django's django.tasks framework"
 readme = "README.md"
 license = "MIT"