django-admin-background-task 0.3.2__py3-none-any.whl → 0.4.1__py3-none-any.whl

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)

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)),

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),
+        ),
+    ]

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]

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(

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);
       }
     }

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>

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.dist-info → django_admin_background_task-0.4.1.dist-info}/METADATA

@@ -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.dist-info → django_admin_background_task-0.4.1.dist-info}/RECORD

@@ -2,17 +2,17 @@ bgtask/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 bgtask/admin.py,sha256=cOhbR__7WJ3rmjlbZjGKh_gJDpEz_c6Ll2zwHo7mpiM,965
 bgtask/apps.py,sha256=zZHsNaW9nnJgK7jnpty0IjM0TTpsk33xhpsGTa-x3iE,144
 bgtask/backends/__init__.py,sha256=zZlL7gHXL12heAhHD_7D7lEBihCE-LHYb07yIbk055s,57
-bgtask/backends/thread_pool.py,sha256=y5EtO9ltA5lc7GUtvqHPJuoo1brJPOurp1IQ7JdCUEI,304
+bgtask/backends/thread_pool.py,sha256=KD_RccLR1fSiPZGI_fbX4Rcic6mE21VUdrUkusuI9Zk,286
 bgtask/decorators.py,sha256=UsiCBhqaWm1Yn4n4hmFbauGQvNezoeDm7Iqpjbvxbjk,1119
-bgtask/migrations/0001_initial.py,sha256=YDTEy_hiXHru-1ZdIH-n3po82r5vyzbkyYIrF9_yiI8,2013
+bgtask/migrations/0001_initial.py,sha256=TPuplGYJtqHJ7h4-A-nINMmvRD9HYvfhOY4bZyinz2c,2035
 bgtask/migrations/0002_backgroundtask_namespace_alter_backgroundtask_name.py,sha256=XIG_gIvdA73tz0NRbNkGU_ieKde3ZtQltPeLdslD5Xo,968
+bgtask/migrations/0003_backgroundtask_queued_at.py,sha256=Hp0WeQLKP0R5jNeEAgVlsx-7jgIzbnIkqkPUGsenK8o,439
 bgtask/migrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-bgtask/model_admin.py,sha256=mwRoljw1CwMA-c3zbssmrRsV9l8xsgYJOBrkgVNilRs,4402
-bgtask/models.py,sha256=VulETkcBXJkyUgmExSx9fuOvpp1HnY2sLQLD5BUvbHk,9184
-bgtask/stack_contexts.py,sha256=2Hun6O5Mm949uAioC2E3i54Rg-_H8P7LsHdhJYc0w6E,231
+bgtask/model_admin.py,sha256=loEh9uPUZbC19_daPoPfHNuLrI42oAA930J5IEH_1-w,5057
+bgtask/models.py,sha256=HomYFivOW7176I2uq7Gk21wniJ29fIfv01Sz72DHjQI,11291
 bgtask/static/bgtask/js/bgtask-once.js,sha256=DBerpxPLP21IH--HpBxVFk3kN52FtBiuyJsDCjg7mCA,746
-bgtask/static/bgtask/js/bgtask.js,sha256=aYG02BY2F0aBlyRT_19turcC6RNLmyhJZUiuABUszoo,15026
-bgtask/templates/bgtask/admin/change_list.html,sha256=tynRFzVKIxqWMCO7BO18TefgTL2VpK4VKemZ0CJBuOg,1053
+bgtask/static/bgtask/js/bgtask.js,sha256=6fVepM6AY_a3-I5ZABfaCaf7_g8IkClOFq9ZxG9GsX4,15366
+bgtask/templates/bgtask/admin/change_list.html,sha256=pxajrUXZvsBfSM4Lh3HLjdjGNNO7lJPaTkUwZ_zbWEc,1080
 bgtask/templates/bgtask/bg_changelist_status_column.html,sha256=SA7EAL50oBrcRPGstXROXkFJ541vYA8RlHidM3srTPU,844
 bgtask/templates/bgtask/bg_completed_column.html,sha256=Q4l3EQaOXHYVOzv0jpx3ww3Wa2Bb33RyZp3RSWI1zog,788
 bgtask/templates/bgtask/bgtask_templates.html,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
@@ -20,10 +20,10 @@ bgtask/templates/bgtask/bgtask_view.html,sha256=AeubqERFF14PHWjInBD39wGImnRx4taS
 bgtask/templates/bgtask/progress.html,sha256=VVYbrunGasOshRlz8Nm8hFPxqcVtrpaW1e2QxzAMcMM,166
 bgtask/templatetags/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 bgtask/templatetags/bgtask.py,sha256=WUEWlQX5AarbXJBV6EGp-khT1zegVwGNigSKRF5mCTE,413
-bgtask/tests/test_bgtask.py,sha256=9AsBppPphaIdphuB-pHuQjgLhYNp8ySWtmcWF2uQl3Q,1090
+bgtask/tests/test_bgtask.py,sha256=pepgFBvRWNqmOdOFPkp4MC_ctWmYPYGpisb94OUUA9I,1882
 bgtask/urls.py,sha256=DXXjgj18LTSCq2-xZf23-pkgO4RmZglv67mgrp-fDyk,161
 bgtask/views.py,sha256=tPblidBq8mIv9cbyAfzJfNlM-I-Z11XVoobdA3DZBVM,1765
-django_admin_background_task-0.3.2.dist-info/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-django_admin_background_task-0.3.2.dist-info/METADATA,sha256=Vpt0K1yBf5RBdQyLw6-dVT0iT55dIaotn3VFHvmP9aI,1375
-django_admin_background_task-0.3.2.dist-info/WHEEL,sha256=FMvqSimYX_P7y0a7UY-_Mc83r5zkBZsCYPm7Lr0Bsq4,88
-django_admin_background_task-0.3.2.dist-info/RECORD,,
+django_admin_background_task-0.4.1.dist-info/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+django_admin_background_task-0.4.1.dist-info/METADATA,sha256=g-KSsxCt134tSJmO0wT_FwjPoVbHGo_rBHLR9fXdCbc,1379
+django_admin_background_task-0.4.1.dist-info/WHEEL,sha256=FMvqSimYX_P7y0a7UY-_Mc83r5zkBZsCYPm7Lr0Bsq4,88
+django_admin_background_task-0.4.1.dist-info/RECORD,,

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)