django-admin-background-task 0.3.2__tar.gz → 0.4.1__tar.gz

{django_admin_background_task-0.3.2 → django_admin_background_task-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: django-admin-background-task
-Version: 0.3.2
+Version: 0.4.1
 Summary: A set of tools for django apps to persist and monitor the status of background tasks
 Home-page: https://github.com/daphtdazz/django-bgtask
 License: Apache-2.0
@@ -58,4 +58,5 @@ urlpatterns = [
 from bgtask.models import BackgroundTask
 
 BackgroundTask.new(name)
+```
 

{django_admin_background_task-0.3.2 → django_admin_background_task-0.4.1}/README.md

@@ -39,3 +39,4 @@ urlpatterns = [
 from bgtask.models import BackgroundTask
 
 BackgroundTask.new(name)
+```

{django_admin_background_task-0.3.2 → django_admin_background_task-0.4.1}/bgtask/backends/thread_pool.py

@@ -4,9 +4,9 @@ from concurrent.futures import ThreadPoolExecutor
 SHARED_THREAD_POOL = None
 
 
-def dispatch(func, bg_task, *args, **kwargs):
+def dispatch(func, *args, **kwargs):
     global SHARED_THREAD_POOL
     if SHARED_THREAD_POOL is None:
         SHARED_THREAD_POOL = ThreadPoolExecutor()
 
-    SHARED_THREAD_POOL.submit(func, bg_task, *args, **kwargs)
+    SHARED_THREAD_POOL.submit(func, *args, **kwargs)

{django_admin_background_task-0.3.2 → django_admin_background_task-0.4.1}/bgtask/migrations/0001_initial.py

@@ -21,7 +21,7 @@ class Migration(migrations.Migration):
                 ('updated', models.DateTimeField(auto_now=True)),
                 ('id', models.UUIDField(default=uuid.uuid4, editable=False, primary_key=True, serialize=False)),
                 ('name', models.CharField(max_length=1000)),
-                ('state', models.CharField(choices=[('not_started', 'not_started'), ('running', 'running'), ('success', 'success'), ('partial_success', 'partial_success'), ('failed', 'failed')], default='not_started', max_length=16)),
+                ('state', models.CharField(choices=[('not_started', 'not_started'), ('queued', 'queued'), ('running', 'running'), ('success', 'success'), ('partial_success', 'partial_success'), ('failed', 'failed')], default='not_started', max_length=16)),
                 ('steps_to_complete', models.PositiveIntegerField(blank=True, help_text='The number of steps in the task for it to be completed.', null=True)),
                 ('steps_completed', models.PositiveIntegerField(blank=True, help_text='The number of steps completed so far by this task', null=True)),
                 ('started_at', models.DateTimeField(blank=True, null=True)),

django_admin_background_task-0.4.1/bgtask/migrations/0003_backgroundtask_queued_at.py

@@ -0,0 +1,18 @@
+# Generated by Django 4.2.11 on 2025-02-07 21:57
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("bgtask", "0002_backgroundtask_namespace_alter_backgroundtask_name"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="backgroundtask",
+            name="queued_at",
+            field=models.DateTimeField(blank=True, null=True),
+        ),
+    ]

{django_admin_background_task-0.3.2 → django_admin_background_task-0.4.1}/bgtask/model_admin.py

@@ -13,9 +13,14 @@ from .models import BackgroundTask
 class BGTaskModelAdmin(admin.ModelAdmin):
     # This is not overridden to avoid messing with the implicit logic for finding change list
     # templates that ModelAdmin uses. So you either need to specify this yourself on your
-    # subclass or you need to extend from this in your custom template.
+    # subclass or you need to extend from this in your custom template (which you can install at
+    # <your-app>/templates/admin/<your-app>/<your-model>/change_list.html)
     #
     # change_list_template = "bgtask/admin/change_list.html"
+    #
+    # Set this to tell the admin change list page which background tasks to show in the table.
+    #
+    # bgtask_names = ["task a", "task b"]
 
     # ----------------------------------------------------------------------------------------------
     # Class API
@@ -41,14 +46,15 @@ class BGTaskModelAdmin(admin.ModelAdmin):
     # API for subclasses
     # ----------------------------------------------------------------------------------------------
     def start_bgtask(self, name, **kwargs):
-        bgtask = BackgroundTask.objects.create(
-            name=name,
-            namespace=self._bgtask_namespace,
-            **kwargs,
-        )
+        bgtask = self._create_bgtask(name=name, **kwargs)
         bgtask.start()
         return bgtask
 
+    def queue_bgtask(self, name, **kwargs):
+        bgtask = self._create_bgtask(name=name, **kwargs)
+        bgtask.queue()
+        return bgtask
+
     # ----------------------------------------------------------------------------------------------
     # Superclass overrides
     # ----------------------------------------------------------------------------------------------
@@ -78,6 +84,12 @@ class BGTaskModelAdmin(admin.ModelAdmin):
 
             next_action = next_action.__wrapped__
 
+    def _create_bgtask(self, **kwargs):
+        return BackgroundTask.objects.create(
+            namespace=self._bgtask_namespace,
+            **kwargs,
+        )
+
     def _admin_bg_tasks(self, request):
         task_name_to_desc = {}
         for action, action_name, action_description in self.get_actions(request).values():
@@ -100,12 +112,16 @@ class BGTaskModelAdmin(admin.ModelAdmin):
                     Q(state=BackgroundTask.STATES.running)
                     & Q(started_at__gt=timezone.now() - timedelta(days=1))
                 )
+                | (
+                    Q(state=BackgroundTask.STATES.queued)
+                    & Q(queued_at__gt=timezone.now() - timedelta(days=1))
+                )
                 | (
                     ~Q(state=BackgroundTask.STATES.not_started)
                     & Q(completed_at__gt=timezone.now() - timedelta(hours=2))
                 )
             )
-            .order_by("-started_at")
+            .order_by("-started_at", "-queued_at")
         )
         for bgt in bgts:
             bgt.admin_description = task_name_to_desc[bgt.name]

{django_admin_background_task-0.3.2 → django_admin_background_task-0.4.1}/bgtask/models.py

@@ -38,13 +38,16 @@ def locked(meth):
     return _locked_meth
 
 
-def only_if_state(state):
+def only_if_state(state, no_op_states=frozenset()):
     def only_if_state_decorator(meth):
-        def only_if_state_wrapper(self, *args, **kwargs):
-            if self.state != state:
+        def only_if_state_wrapper(self, *args, no_op_if_already_in_state=False, **kwargs):
+            if self.state in no_op_states:
+                return
+            states = (state,) if isinstance(state, str) else tuple(state)
+            if self.state not in states:
                 raise RuntimeError(
-                    "%s cannot execute %s as in state %s not %s"
-                    % (self, meth.__name__, self.state, state)
+                    "%s cannot execute %s as in state %s not one of %s"
+                    % (self, meth.__name__, self.state, states)
                 )
             return meth(self, *args, **kwargs)
 
@@ -72,7 +75,7 @@ class BackgroundTask(models.Model):
         ),
     )
 
-    STATES = Choices("not_started", "running", "success", "partial_success", "failed")
+    STATES = Choices("not_started", "queued", "running", "success", "partial_success", "failed")
     state = models.CharField(max_length=16, default=STATES.not_started, choices=STATES)
     steps_to_complete = models.PositiveIntegerField(
         null=True, blank=True, help_text="The number of steps in the task for it to be completed."
@@ -81,6 +84,7 @@ class BackgroundTask(models.Model):
         null=True, blank=True, help_text="The number of steps completed so far by this task"
     )
 
+    queued_at = models.DateTimeField(null=True, blank=True)
     started_at = models.DateTimeField(null=True, blank=True)
     completed_at = models.DateTimeField(null=True, blank=True)
     result = models.JSONField(null=True, blank=True, help_text="The result(s) of the task, if any")
@@ -104,7 +108,12 @@ class BackgroundTask(models.Model):
     @property
     def task_dict(self):
         task_dict = model_to_dict(self)
-        return {"id": str(self.id), "updated": self.updated.isoformat(), **task_dict}
+        return {
+            "id": str(self.id),
+            "updated": self.updated.isoformat(),
+            "position_in_queue": self.get_position_in_queue(),
+            **task_dict,
+        }
 
     @property
     def num_failed_steps(self):
@@ -114,6 +123,33 @@ class BackgroundTask(models.Model):
     def incomplete(self):
         return self.state in [self.STATES.not_started, self.STATES.running]
 
+    def get_position_in_queue(self):
+        if self.state != self.STATES.queued:
+            return None
+
+        if (
+            BackgroundTask.objects.filter(
+                queued_at__gt=self.queued_at,
+            )
+            .exclude(state=self.STATES.not_started)
+            .exclude(state=self.STATES.queued)
+            .exists()
+        ):
+            # More recent tasks have started, assume we're next (either that or we're stuck)
+            return 0
+
+        # Otherwise approximate queue position as the number of tasks that were queued before us
+        # and are still in the queue. So if there is nothing in front of us we are 0 in the queue.
+        assert self.queued_at
+        return BackgroundTask.objects.filter(
+            queued_at__lt=self.queued_at, state=self.STATES.queued
+        ).count()
+
+    def set_steps_to_complete(self, steps_to_complete):
+        self.steps_to_complete = steps_to_complete
+        self.steps_completed = 0
+        self.save()
+
     @contextmanager
     def runs_single_step(self):
         try:
@@ -132,10 +168,32 @@ class BackgroundTask(models.Model):
         else:
             self.succeed()
 
+    @contextmanager
+    def fails_if_exception(self):
+        try:
+            yield
+        except Exception as exc:
+            self.fail(exc)
+            raise
+
     @locked
     @only_if_state(STATES.not_started)
+    def queue(self):
+        log.info("Background Task queueing: %s", self.id)
+        self.state = self.STATES.queued
+        self.queued_at = timezone.now()
+        self.save()
+
+    @locked
+    @only_if_state(
+        (STATES.not_started, STATES.queued),
+        # Allow start() to be called while running so that if a task's subtasks are queued and
+        # asynchronous each can call .start() independently so the first one that is executed will
+        # start the task.
+        no_op_states=(STATES.running,),
+    )
     def start(self):
-        log.info("%s starting", self)
+        log.info("Background Task starting: %s", self.id)
         self.state = self.STATES.running
         self.started_at = timezone.now()
         self.save()
@@ -144,7 +202,7 @@ class BackgroundTask(models.Model):
     @only_if_state(STATES.running)
     def fail(self, exc):
         """Call to indicate a complete and final failure of the task"""
-        log.info("%s failed: %s", self, exc)
+        log.info("Background Task failed: %s %s", self.id, exc)
         self.state = self.STATES.failed
         self.completed_at = timezone.now()
         self.errors.append(

{django_admin_background_task-0.3.2 → django_admin_background_task-0.4.1}/bgtask/static/bgtask/js/bgtask.js

@@ -2,6 +2,7 @@ window.BG_TASK_ADDED = true;
 
 const STATE_TO_EMOJI = {
     "not_started": "⏱️",
+    "queued": "⋯",
     "running": "🏃🏽‍♀️",
     "success": "✅",
     "partial_success": "⚠️",
@@ -201,10 +202,14 @@ class TaskProgressDiv {
         this._showProgress();
         this._hideState();
         break;
+      case "queued":
+        this._hideProgress();
+        this._showState();
+        break;
     }
 
     const isOutOfDate = (
-      !["success", "partial_success", "not_started", "failed"].includes(task.state)
+      !["success", "queued", "partial_success", "not_started", "failed"].includes(task.state)
       && (new Date() - task.updated) > OUT_OF_DATE_PERIOD_S * 1000
     );
 
@@ -212,11 +217,21 @@ class TaskProgressDiv {
       this._addTitle("This task has not been updated for a while");
     }
 
-    this.stateEle.innerHTML = `${STATE_TO_EMOJI[task.state] || "❓"}`;
+    this._setStateEmoji(task);
 
     this.pgstate.update({ max: task.steps_to_complete, value: task.steps_completed, isOutOfDate });
   }
 
+  _setStateEmoji(task) {
+    this.stateEle.innerHTML = `${STATE_TO_EMOJI[task.state] || "❓"}`;
+
+    switch (task.state) {
+      case "queued":
+        this.stateEle.innerHTML += ` (${task.position_in_queue})`;
+        break;
+    }
+  }
+
   _addTitle(title) {
     if (!this.div.title) {
       this.div.title = title;
@@ -445,7 +460,7 @@ class BGTaskPoller {
       for (const cbk of (this.taskCallbacks[task.id] || [])) {
         cbk(task);
       }
-      if (task.state !== "running") {
+      if (!['running', 'queued'].includes(task.state)) {
         this.stopMonitoringTask(task.id);
       }
     }

{django_admin_background_task-0.3.2 → django_admin_background_task-0.4.1}/bgtask/templates/bgtask/admin/change_list.html

@@ -19,8 +19,11 @@
     <tbody>
       {% for bgt in admin_bg_tasks %}
       {% with bgtask=bgt.task_dict %}
-      <tr class="bgtask-row"><td><a href="{% url 'admin:bgtask_backgroundtask_change' bgtask.id %}">{{ bgt.admin_description }}</a></td><td>{{ bgt.started_at|timesince }} ago</td><td>{% include "bgtask/bg_completed_column.html" %}</td><td>
-      {% include "bgtask/bg_changelist_status_column.html" %}</td></tr>
+      <tr class="bgtask-row">
+        <td><a href="{% url 'admin:bgtask_backgroundtask_change' bgtask.id %}">{{ bgt.admin_description }}</a></td>
+        <td>{{ bgt.started_at|timesince }} ago</td><td>{% include "bgtask/bg_completed_column.html" %}</td>
+        <td>{% include "bgtask/bg_changelist_status_column.html" %}</td>
+      </tr>
       {% endwith %}
       {% endfor %}
     </tbody>

{django_admin_background_task-0.3.2 → django_admin_background_task-0.4.1}/bgtask/tests/test_bgtask.py

@@ -1,7 +1,11 @@
 import pytest
 
+from django.utils import timezone
+
 from bgtask.models import BackgroundTask
 
+pytestmark = pytest.mark.django_db
+
 
 @pytest.fixture
 def a_task():
@@ -30,6 +34,37 @@ def test_bgtask_immediate_failure(a_task):
     assert a_task.state == BackgroundTask.STATES.failed
 
     assert len(a_task.errors) == 1
-    assert a_task.errors[0]["datetime"] == "1970-01-01T00:00:00+00:00"
+    assert a_task.errors[0]["datetime"] == a_task.completed_at.isoformat()
     assert a_task.errors[0]["error_message"] == "Some global failure"
-    assert "test_bgtask_immediate_failure" in a_task.errors[0]["trackeback"]
+    assert "test_bgtask_immediate_failure" in a_task.errors[0]["traceback"]
+
+
+def test_bgtask_start_again(a_task):
+    a_task.start()
+    import time
+    time.sleep(0.001)
+
+    curr_started_at = a_task.started_at
+    assert timezone.now() > curr_started_at
+
+    # Starting again is no-op
+    a_task.start()
+    assert a_task.started_at == curr_started_at
+
+
+def test_fails_if_exception(a_task):
+    a_task.start()
+
+    with pytest.raises(Exception):
+        with a_task.fails_if_exception():
+            raise Exception("fail!")
+
+    assert a_task.state == BackgroundTask.STATES.failed
+
+
+def test_set_steps(a_task):
+    a_task.steps_completed = 10
+    a_task.set_steps_to_complete(20)
+    a_task.refresh_from_db()
+    assert a_task.steps_to_complete == 20
+    assert a_task.steps_completed == 0

{django_admin_background_task-0.3.2 → django_admin_background_task-0.4.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "django-admin-background-task"
-version = "0.3.2"
+version = "0.4.1"
 description = "A set of tools for django apps to persist and monitor the status of background tasks"
 authors = [
     "David Park <david@greenparksoftware.co.uk>",
@@ -36,6 +36,8 @@ black = ">=24.2.0"
 # Sphinx dependencies also in docs/requirements.txt for read the docs to pick up.
 sphinx = ">=7.1.2"
 sphinx-rtd-theme = ">=1.3.0"
+psycopg2 = ">=2.9.10"
+colorlog = ">=6.9.0"
 
 [tool.poetry.extras]
 # ℹ️ if you update any of these, be sure to update "all = [...]" as well, so that it's easy to get

django_admin_background_task-0.3.2/bgtask/stack_contexts.py

@@ -1,11 +0,0 @@
-from utils.stack_context import stack_context
-
-from .models import BackgroundTask
-
-
-__all__ = ["bgtask_context"]
-
-
-@stack_context(logging_param_name="bgtask_id")
-def bgtask_context(id):
-    return BackgroundTask.objects.get(id=id)