Write documentation, update index name, add crontab tests

Author: dcwatson

README.md

@@ -1,3 +1,83 @@
 # django-dbtasks
 
 Database backend and runner for [Django tasks](https://docs.djangoproject.com/en/dev/topics/tasks/) (new in 6.0).
+
+
+## Quickstart
+
+Install the `django-dbtasks` package from PyPI, and configure your [TASKS setting](https://docs.djangoproject.com/en/dev/ref/settings/#std-setting-TASKS) as follows:
+
+```python
+TASKS = {
+    "default": {
+        "BACKEND": "dbtasks.backend.DatabaseBackend",
+        "OPTIONS": {
+            # Set this to True to execute tasks immediately (no need for a runner).
+            "immediate": False,
+            # How long to retain ScheduleTasks in the database. Forever if not set.
+            "retain": datetime.timedelta(days=7),
+            # Tasks to run periodically.
+            "periodic": {
+                # Runs at 3:30am every Monday through Friday.
+                "myproject.tasks.maintenance": "30 3 * * 1-5",
+            },
+        },
+    },
+}
+```
+
+## Runner
+
+`django-dbtasks` includes a dedicated `taskrunner` management command:
+
+```
+usage: manage.py taskrunner [-h] [-w WORKERS] [-i WORKER_ID] [--backend BACKEND] [--delay DELAY]
+```
+
+It is also straightforward to run the runner in a thread of its own:
+
+```python
+runner = Runner(workers=4, worker_id="in-process")
+t = threading.Thread(target=runner.run)
+t.start()
+...
+runner.stop()
+t.join()
+```
+
+`django-dbtasks` itself is tested on free-threading builds of Python 3.13 and 3.14, but compatibility will depend on your database driver and other packages.
+
+
+## Periodic Tasks
+
+As shown in the [quickstart](#quickstart), periodic tasks are specified as a mapping in the backend `OPTIONS` under the `periodic` key. The keys of the mapping should be dotted paths to the tasks, and the values should either be a string in [crontab format](https://crontab.guru), or an instance of `dbtasks.Periodic`. Using a `dbtasks.Periodic` allows you to specify `args` and `kwargs` (as values or callables) that will be passed to the task. For example, the `Runner` registers a periodic task to remove old tasks past the retention window, in a manner similar to:
+
+```python
+# Convert the `timedelta` to seconds, so as to be JSON-serializable.
+retain_secs = int(self.backend.options["retain"].total_seconds())
+# Clear old tasks every hour, on a random minute.
+self.periodic["dbtasks.runner.cleanup"] = Periodic("~ * * * *", args=[retain_secs])
+```
+
+_Note that this allows you to specify a custom `Periodic` for the `dbtasks.runner.cleanup` task in your `TASKS` setting if necessary._
+
+
+## Logging
+
+Be sure to add a `dbtasks` logger to your `LOGGING` setting:
+
+```python
+LOGGING = {
+    ...
+    "loggers": {
+        "dbtasks": {
+            "handlers": ["console"],
+            "level": "INFO",
+        },
+    },
+}
+```
+
+## Testing
+
+There is a `RunnerTestCase` that starts a runner for the duration of a test suite. See [test_tasks.py](tests/tests/test_tasks.py) for example usage.

src/dbtasks/management/commands/taskrunner.py

@@ -1,20 +1,50 @@
+import os
+import platform
+
+from dbtasks.runner import Runner
 from django.core.management import BaseCommand, CommandParser
 from django.tasks import DEFAULT_TASK_BACKEND_ALIAS
 
-from dbtasks.runner import Runner
+
+def cpus() -> int:
+    return os.cpu_count() or 4
 
 
 class Command(BaseCommand):
     help = "Runs the task runner."
 
     def add_arguments(self, parser: CommandParser):
-        parser.add_argument("--workers", default=4, type=int)
-        parser.add_argument("--worker-id", default=None)
-        parser.add_argument("--backend", default=DEFAULT_TASK_BACKEND_ALIAS)
+        default_cpus = cpus() - 1
+        default_node = platform.node()
+        parser.add_argument(
+            "-w",
+            "--workers",
+            type=int,
+            default=default_cpus,
+            help=f"Number of worker threads [default={default_cpus}]",
+        )
+        parser.add_argument(
+            "-i",
+            "--worker-id",
+            default=None,
+            help=f"Name of the worker node [default=`{default_node}`]",
+        )
+        parser.add_argument(
+            "--backend",
+            default=DEFAULT_TASK_BACKEND_ALIAS,
+            help=f"Task backend to use [default=`{DEFAULT_TASK_BACKEND_ALIAS}`]",
+        )
+        parser.add_argument(
+            "--delay",
+            type=float,
+            default=0.5,
+            help="Loop delay [default=0.5]",
+        )
 
     def handle(self, *args, **options):
         Runner(
             workers=options["workers"],
             worker_id=options["worker_id"],
             backend=options["backend"],
+            loop_delay=options["delay"],
         ).run()

src/dbtasks/migrations/0001_initial.py

@@ -1,8 +1,7 @@
 # Generated by Django 6.0 on 2025-12-20 02:16
 
-from django.db import migrations, models
-
 import dbtasks.models
+from django.db import migrations, models
 
 
 class Migration(migrations.Migration):
@@ -59,7 +58,7 @@ class Migration(migrations.Migration):
                         models.F("backend"),
                         models.F("queue"),
                         models.F("run_after"),
-                        name="idx_scheduledtask",
+                        name="idx_dbtasks_scheduledtask",
                     )
                 ],
             },

src/dbtasks/models.py

@@ -60,7 +60,7 @@ class Meta:
                 "backend",
                 "queue",
                 "run_after",
-                name="idx_scheduledtask",
+                name="idx_dbtasks_scheduledtask",
             ),
         ]
 

tests/tests/test_crontab.py

@@ -0,0 +1,24 @@
+import unittest
+from datetime import datetime, time
+
+from dbtasks.crontab import Crontab, hour, minute, month
+
+
+class CrontabTests(unittest.TestCase):
+    def test_parts(self):
+        self.assertEqual(minute.parse("30"), [30])
+        self.assertEqual(minute.parse("7-12,42"), [7, 8, 9, 10, 11, 12, 42])
+        self.assertEqual(len(minute.parse("~")), 1)
+        self.assertEqual(minute.parse("*/15"), [0, 15, 30, 45])
+        self.assertEqual(minute.parse("30-45/3"), [30, 33, 36, 39, 42, 45])
+        self.assertEqual(hour.parse("*/23"), [0, 23])
+        self.assertEqual(month.parse("oct,february,jun"), [2, 6, 10])
+        self.assertEqual(month.parse("jan-jun/2"), [1, 3, 5])
+
+    def test_crontab(self):
+        # 4:30am on the 1st and 15th of each month
+        c = Crontab("30 4 1,15 * *")
+        matches = list(c.dates(after=datetime(2025, 1, 1), until=datetime(2026, 1, 1)))
+        self.assertEqual(len(matches), 12 * 2)
+        self.assertTrue(all(d.day in (1, 15) for d in matches))
+        self.assertTrue(all(d.time() == time(4, 30) for d in matches))