Rename "completed" tasks to "succeeded" (#119)

* Rename "completed" tasks to "succeeded"

"completed" could be misread as completed unsuccessfully

Author: RealOrangeOne

README.md

@@ -159,7 +159,7 @@ Finally, you can run the `db_worker` command to run tasks as they're created. Ch
 
 ### Pruning old tasks
 
-After a while, tasks may start to build up in your database. This can be managed using the `prune_db_task_results` management command, which deletes completed and failed tasks according to the given retention policy. Check the `--help` for the available options.
+After a while, tasks may start to build up in your database. This can be managed using the `prune_db_task_results` management command, which deletes completed tasks according to the given retention policy. Check the `--help` for the available options.
 
 ### Retrieving task result
 
@@ -184,10 +184,10 @@ default_task_backend.get_result(result_id)
 
 ### Return values
 
-If your task returns something, it can be retrieved from the `.return_value` attribute on a `TaskResult`. Accessing this property on an unfinished task (ie not `COMPLETE` or `FAILED`) will raise a `ValueError`.
+If your task returns something, it can be retrieved from the `.return_value` attribute on a `TaskResult`. Accessing this property on an unfinished task (ie not `SUCCEEDED` or `FAILED`) will raise a `ValueError`.
 
 ```python
-assert result.status == ResultStatus.COMPLETE
+assert result.status == ResultStatus.SUCCEEDED
 assert result.return_value == 42
 ```
 
@@ -196,7 +196,7 @@ If a result has been updated in the background, you can call `refresh` on it to
 ```python
 assert result.status == ResultStatus.NEW
 result.refresh()
-assert result.status == ResultStatus.COMPLETE
+assert result.status == ResultStatus.SUCCEEDED
 ```
 
 #### Exceptions
@@ -240,7 +240,7 @@ A few [Signals](https://docs.djangoproject.com/en/stable/topics/signals/) are pr
 Whilst signals are available, they may not be the most maintainable approach.
 
 - `django_tasks.signals.task_enqueued`: Called when a task is enqueued. The sender is the backend class. Also called with the enqueued `task_result`.
-- `django_tasks.signals.task_finished`: Called when a task finishes (`COMPLETE` or `FAILED`). The sender is the backend class. Also called with the finished `task_result`.
+- `django_tasks.signals.task_finished`: Called when a task finishes (`SUCCEEDED` or `FAILED`). The sender is the backend class. Also called with the finished `task_result`.
 
 ## Contributing
 

django_tasks/backends/database/management/commands/db_worker.py

@@ -124,7 +124,7 @@ def start(self) -> None:
 
     def run_task(self, db_task_result: DBTaskResult) -> None:
         """
-        Run the given task, marking it as complete or failed.
+        Run the given task, marking it as succeeded or failed.
         """
         try:
             task = db_task_result.task
@@ -140,7 +140,7 @@ def run_task(self, db_task_result: DBTaskResult) -> None:
 
             # Setting the return and success value inside the error handling,
             # So errors setting it (eg JSON encode) can still be recorded
-            db_task_result.set_complete(return_value)
+            db_task_result.set_succeeded(return_value)
             task_finished.send(
                 sender=type(task.get_backend()), task_result=db_task_result.task_result
             )

django_tasks/backends/database/management/commands/prune_db_task_results.py

@@ -115,7 +115,7 @@ def handle(
             results = results.filter(finished_at__lte=min_age)
         else:
             results = results.filter(
-                Q(status=ResultStatus.COMPLETE, finished_at__lte=min_age)
+                Q(status=ResultStatus.SUCCEEDED, finished_at__lte=min_age)
                 | Q(status=ResultStatus.FAILED, finished_at__lte=failed_min_age)
             )
 

django_tasks/backends/database/migrations/0008_separate_results_field.py

@@ -12,9 +12,9 @@ def separate_results_field(
 ) -> None:
     DBTaskResult = apps.get_model("django_tasks_database", "DBTaskResult")
 
-    # If a task completed, the result is its return value
+    # If a task succeeded, the result is its return value
     DBTaskResult.objects.using(schema_editor.connection.alias).filter(
-        status=ResultStatus.COMPLETE
+        status=ResultStatus.SUCCEEDED
     ).update(return_value=models.F("result"))
 
     # If a task failed, the result is the exception data (or nothing)
@@ -28,9 +28,9 @@ def merge_results_field(
 ) -> None:
     DBTaskResult = apps.get_model("django_tasks_database", "DBTaskResult")
 
-    # If a task completed, the result is its return value
+    # If a task succeeded, the result is its return value
     DBTaskResult.objects.using(schema_editor.connection.alias).filter(
-        status=ResultStatus.COMPLETE
+        status=ResultStatus.SUCCEEDED
     ).update(result=models.F("return_value"))
 
     # If a task failed, the result is the exception data (or nothing)

django_tasks/backends/database/migrations/0010_alter_dbtaskresult_status.py

@@ -0,0 +1,27 @@
+# Generated by Django 4.2.13 on 2024-11-21 13:46
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("django_tasks_database", "0009_remove_results_field"),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name="dbtaskresult",
+            name="status",
+            field=models.CharField(
+                choices=[
+                    ("NEW", "New"),
+                    ("RUNNING", "Running"),
+                    ("FAILED", "Failed"),
+                    ("SUCCEEDED", "Succeeded"),
+                ],
+                default="NEW",
+                max_length=9,
+                verbose_name="status",
+            ),
+        ),
+    ]

django_tasks/backends/database/migrations/0011_rename_complete_status.py

@@ -0,0 +1,35 @@
+# Generated by Django 4.2.13 on 2024-08-23 14:38
+
+from django.db import migrations
+from django.db.backends.base.schema import BaseDatabaseSchemaEditor
+from django.db.migrations.state import StateApps
+
+from django_tasks import ResultStatus
+
+
+def separate_results_field(
+    apps: StateApps, schema_editor: BaseDatabaseSchemaEditor
+) -> None:
+    DBTaskResult = apps.get_model("django_tasks_database", "DBTaskResult")
+
+    DBTaskResult.objects.using(schema_editor.connection.alias).filter(
+        status="COMPLETE"
+    ).update(status=ResultStatus.SUCCEEDED)
+
+
+def merge_results_field(
+    apps: StateApps, schema_editor: BaseDatabaseSchemaEditor
+) -> None:
+    DBTaskResult = apps.get_model("django_tasks_database", "DBTaskResult")
+
+    DBTaskResult.objects.using(schema_editor.connection.alias).filter(
+        status=ResultStatus.SUCCEEDED
+    ).update(status="COMPLETE")
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("django_tasks_database", "0010_alter_dbtaskresult_status"),
+    ]
+
+    operations = [migrations.RunPython(separate_results_field, merge_results_field)]

django_tasks/backends/database/models.py

@@ -55,8 +55,8 @@ def ready(self) -> "DBTaskResultQuerySet":
             status=ResultStatus.NEW,
         ).filter(models.Q(run_after=None) | models.Q(run_after__lte=timezone.now()))
 
-    def complete(self) -> "DBTaskResultQuerySet":
-        return self.filter(status=ResultStatus.COMPLETE)
+    def succeeded(self) -> "DBTaskResultQuerySet":
+        return self.filter(status=ResultStatus.SUCCEEDED)
 
     def failed(self) -> "DBTaskResultQuerySet":
         return self.filter(status=ResultStatus.FAILED)
@@ -65,7 +65,7 @@ def running(self) -> "DBTaskResultQuerySet":
         return self.filter(status=ResultStatus.RUNNING)
 
     def finished(self) -> "DBTaskResultQuerySet":
-        return self.failed() | self.complete()
+        return self.failed() | self.succeeded()
 
     @retry()
     def get_locked(self) -> Optional["DBTaskResult"]:
@@ -173,8 +173,8 @@ def claim(self) -> None:
         self.save(update_fields=["status", "started_at"])
 
     @retry()
-    def set_complete(self, return_value: Any) -> None:
-        self.status = ResultStatus.COMPLETE
+    def set_succeeded(self, return_value: Any) -> None:
+        self.status = ResultStatus.SUCCEEDED
         self.finished_at = timezone.now()
         self.return_value = return_value
         self.exception_data = None

django_tasks/backends/immediate.py

@@ -62,7 +62,7 @@ def _execute_task(self, task_result: TaskResult) -> None:
             task_finished.send(type(self), task_result=task_result)
         else:
             object.__setattr__(task_result, "finished_at", timezone.now())
-            object.__setattr__(task_result, "status", ResultStatus.COMPLETE)
+            object.__setattr__(task_result, "status", ResultStatus.SUCCEEDED)
 
             task_finished.send(type(self), task_result=task_result)
 

django_tasks/task.py

@@ -46,7 +46,7 @@ class ResultStatus(TextChoices):
     NEW = ("NEW", _("New"))
     RUNNING = ("RUNNING", _("Running"))
     FAILED = ("FAILED", _("Failed"))
-    COMPLETE = ("COMPLETE", _("Complete"))
+    SUCCEEDED = ("SUCCEEDED", _("Succeeded"))
 
 
 T = TypeVar("T")
@@ -273,13 +273,13 @@ def return_value(self) -> Optional[T]:
         """
         Get the return value of the task.
 
-        If the task didn't complete successfully, an exception is raised.
+        If the task didn't succeed, an exception is raised.
         This is to distinguish against the task returning None.
         """
         if self.status == ResultStatus.FAILED:
             raise ValueError("Task failed")
 
-        elif self.status != ResultStatus.COMPLETE:
+        elif self.status != ResultStatus.SUCCEEDED:
             raise ValueError("Task has not finished yet")
 
         return cast(T, self._return_value)