dj-queue 0.1.0__py3-none-any.whl

dj_queue/log.py

@@ -0,0 +1,27 @@
+import logging
+from typing import Any
+
+from dj_queue.config import load_backend_config
+
+logger = logging.getLogger("dj_queue")
+
+
+def log_event(
+  event: str,
+  *,
+  level: int = logging.INFO,
+  backend_alias: str = "default",
+  polling: bool = False,
+  **fields: Any,
+):
+  if polling and load_backend_config(backend_alias).silence_polling:
+    return
+
+  logger.log(
+    level,
+    event,
+    extra={
+      "event": event,
+      "dj_queue": fields,
+    },
+  )

dj_queue/management/__init__.py

@@ -0,0 +1 @@
+"""Management package for dj_queue."""

dj_queue/management/commands/__init__.py

@@ -0,0 +1 @@
+"""Management commands for dj_queue."""

dj_queue/management/commands/dj_queue.py

@@ -0,0 +1,39 @@
+from django.core.management.base import BaseCommand
+
+from dj_queue.config import load_backend_config
+from dj_queue.runtime.supervisor import AsyncSupervisor, ForkSupervisor
+
+
+def build_supervisor(*, backend_alias, cli_overrides):
+  mode = load_backend_config(backend_alias, cli_overrides=cli_overrides).mode
+  supervisor_class = AsyncSupervisor if mode == "async" else ForkSupervisor
+  return supervisor_class.from_backend_config(
+    backend_alias=backend_alias,
+    cli_overrides=cli_overrides,
+  )
+
+
+class Command(BaseCommand):
+  help = "Start the dj_queue supervisor"
+
+  def add_arguments(self, parser):
+    parser.add_argument("--backend", default="default")
+    parser.add_argument("--config")
+    parser.add_argument("--mode", choices=("fork", "async"))
+    parser.add_argument("--only-work", action="store_true")
+    parser.add_argument("--only-dispatch", action="store_true")
+    parser.add_argument("--skip-recurring", action="store_true")
+
+  def handle(self, *args, **options):
+    cli_overrides = {
+      "config": options["config"],
+      "mode": options["mode"],
+      "only_work": options["only_work"],
+      "only_dispatch": options["only_dispatch"],
+      "skip_recurring": options["skip_recurring"],
+    }
+    supervisor = build_supervisor(
+      backend_alias=options["backend"],
+      cli_overrides=cli_overrides,
+    )
+    supervisor.run()

dj_queue/management/commands/dj_queue_health.py

@@ -0,0 +1,32 @@
+from datetime import timedelta
+
+from django.core.management.base import BaseCommand
+from django.utils import timezone
+
+from dj_queue.config import load_backend_config
+from dj_queue.db import get_database_alias
+from dj_queue.models import Process
+
+
+class Command(BaseCommand):
+  help = "Check dj_queue process health"
+
+  def add_arguments(self, parser):
+    parser.add_argument("--backend", default="default")
+    parser.add_argument("--max-age", type=int)
+
+  def handle(self, *args, **options):
+    backend_alias = options["backend"]
+    config = load_backend_config(backend_alias)
+    max_age = options["max_age"]
+    if max_age is None:
+      max_age = config.process_alive_threshold
+
+    cutoff = timezone.now() - timedelta(seconds=max_age)
+    alias = get_database_alias(backend_alias)
+    healthy = Process.objects.using(alias).filter(last_heartbeat_at__gte=cutoff).exists()
+    if healthy:
+      self.stdout.write("healthy")
+      return
+
+    raise SystemExit(1)

dj_queue/management/commands/dj_queue_prune.py

@@ -0,0 +1,22 @@
+from django.core.management.base import BaseCommand
+
+from dj_queue.operations.cleanup import clear_finished_jobs
+
+
+class Command(BaseCommand):
+  help = "Prune finished dj_queue jobs"
+
+  def add_arguments(self, parser):
+    parser.add_argument("--backend", default="default")
+    parser.add_argument("--older-than", type=int)
+    parser.add_argument("--batch-size", type=int, default=500)
+    parser.add_argument("--task-path")
+
+  def handle(self, *args, **options):
+    deleted = clear_finished_jobs(
+      older_than=options["older_than"],
+      task_path=options["task_path"],
+      batch_size=options["batch_size"],
+      backend_alias=options["backend"],
+    )
+    self.stdout.write(f"deleted {deleted} finished jobs")

dj_queue/migrations/0001_initial.py

@@ -0,0 +1,262 @@
+# Generated by Django 6.0.3 on 2026-04-06 15:03
+
+import django.db.models.deletion
+import uuid
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+  initial = True
+
+  dependencies = []
+
+  operations = [
+    migrations.CreateModel(
+      name="Job",
+      fields=[
+        (
+          "id",
+          models.UUIDField(default=uuid.uuid4, editable=False, primary_key=True, serialize=False),
+        ),
+        ("task_path", models.TextField()),
+        ("queue_name", models.CharField(default="default", max_length=64)),
+        ("priority", models.SmallIntegerField(default=0)),
+        ("payload", models.JSONField(default=dict)),
+        ("backend_name", models.CharField(max_length=64)),
+        ("scheduled_at", models.DateTimeField(blank=True, null=True)),
+        ("concurrency_key", models.CharField(blank=True, max_length=255, null=True)),
+        ("finished_at", models.DateTimeField(blank=True, null=True)),
+        ("return_value", models.JSONField(blank=True, null=True)),
+        ("created_at", models.DateTimeField(auto_now_add=True)),
+        ("updated_at", models.DateTimeField(auto_now=True)),
+      ],
+      options={
+        "db_table": "dj_queue_jobs",
+        "indexes": [
+          models.Index(
+            fields=["queue_name", "finished_at"], name="dj_queue_jo_queue_n_b824ac_idx"
+          ),
+          models.Index(
+            fields=["scheduled_at", "finished_at"], name="dj_queue_jo_schedul_92b51a_idx"
+          ),
+          models.Index(fields=["finished_at"], name="dj_queue_jo_finishe_9acb9a_idx"),
+        ],
+        "constraints": [
+          models.CheckConstraint(
+            condition=models.Q(("priority__gte", -100), ("priority__lte", 100)),
+            name="dj_queue_jobs_priority_range",
+          )
+        ],
+      },
+    ),
+    migrations.CreateModel(
+      name="FailedExecution",
+      fields=[
+        (
+          "id",
+          models.BigAutoField(
+            auto_created=True, primary_key=True, serialize=False, verbose_name="ID"
+          ),
+        ),
+        ("exception_class", models.CharField(max_length=255)),
+        ("message", models.TextField(default="")),
+        ("traceback", models.TextField(default="")),
+        ("created_at", models.DateTimeField(auto_now_add=True)),
+        (
+          "job",
+          models.OneToOneField(
+            on_delete=django.db.models.deletion.CASCADE,
+            related_name="failed_execution",
+            to="dj_queue.job",
+          ),
+        ),
+      ],
+      options={
+        "db_table": "dj_queue_failed_executions",
+      },
+    ),
+    migrations.CreateModel(
+      name="Process",
+      fields=[
+        (
+          "id",
+          models.BigAutoField(
+            auto_created=True, primary_key=True, serialize=False, verbose_name="ID"
+          ),
+        ),
+        ("kind", models.CharField(max_length=32)),
+        ("pid", models.IntegerField()),
+        ("hostname", models.CharField(max_length=255)),
+        ("name", models.CharField(max_length=255)),
+        ("metadata", models.JSONField(default=dict)),
+        ("last_heartbeat_at", models.DateTimeField()),
+        ("created_at", models.DateTimeField(auto_now_add=True)),
+        (
+          "supervisor",
+          models.ForeignKey(
+            blank=True,
+            null=True,
+            on_delete=django.db.models.deletion.SET_NULL,
+            related_name="children",
+            to="dj_queue.process",
+          ),
+        ),
+      ],
+      options={
+        "db_table": "dj_queue_processes",
+      },
+    ),
+    migrations.CreateModel(
+      name="ClaimedExecution",
+      fields=[
+        (
+          "id",
+          models.BigAutoField(
+            auto_created=True, primary_key=True, serialize=False, verbose_name="ID"
+          ),
+        ),
+        ("created_at", models.DateTimeField(auto_now_add=True)),
+        (
+          "job",
+          models.OneToOneField(
+            on_delete=django.db.models.deletion.CASCADE,
+            related_name="claimed_execution",
+            to="dj_queue.job",
+          ),
+        ),
+        (
+          "process",
+          models.ForeignKey(
+            blank=True,
+            null=True,
+            on_delete=django.db.models.deletion.SET_NULL,
+            related_name="claimed_executions",
+            to="dj_queue.process",
+          ),
+        ),
+      ],
+      options={
+        "db_table": "dj_queue_claimed_executions",
+      },
+    ),
+    migrations.CreateModel(
+      name="ReadyExecution",
+      fields=[
+        (
+          "id",
+          models.BigAutoField(
+            auto_created=True, primary_key=True, serialize=False, verbose_name="ID"
+          ),
+        ),
+        ("queue_name", models.CharField(max_length=64)),
+        ("priority", models.SmallIntegerField()),
+        ("created_at", models.DateTimeField(auto_now_add=True)),
+        (
+          "job",
+          models.OneToOneField(
+            on_delete=django.db.models.deletion.CASCADE,
+            related_name="ready_execution",
+            to="dj_queue.job",
+          ),
+        ),
+      ],
+      options={
+        "db_table": "dj_queue_ready_executions",
+      },
+    ),
+    migrations.CreateModel(
+      name="ScheduledExecution",
+      fields=[
+        (
+          "id",
+          models.BigAutoField(
+            auto_created=True, primary_key=True, serialize=False, verbose_name="ID"
+          ),
+        ),
+        ("queue_name", models.CharField(max_length=64)),
+        ("priority", models.SmallIntegerField()),
+        ("scheduled_at", models.DateTimeField()),
+        ("created_at", models.DateTimeField(auto_now_add=True)),
+        (
+          "job",
+          models.OneToOneField(
+            on_delete=django.db.models.deletion.CASCADE,
+            related_name="scheduled_execution",
+            to="dj_queue.job",
+          ),
+        ),
+      ],
+      options={
+        "db_table": "dj_queue_scheduled_executions",
+      },
+    ),
+    migrations.CreateModel(
+      name="BlockedExecution",
+      fields=[
+        (
+          "id",
+          models.BigAutoField(
+            auto_created=True, primary_key=True, serialize=False, verbose_name="ID"
+          ),
+        ),
+        ("queue_name", models.CharField(max_length=64)),
+        ("priority", models.SmallIntegerField()),
+        ("concurrency_key", models.CharField(max_length=255)),
+        ("expires_at", models.DateTimeField()),
+        ("created_at", models.DateTimeField(auto_now_add=True)),
+        (
+          "job",
+          models.OneToOneField(
+            on_delete=django.db.models.deletion.CASCADE,
+            related_name="blocked_execution",
+            to="dj_queue.job",
+          ),
+        ),
+      ],
+      options={
+        "db_table": "dj_queue_blocked_executions",
+        "indexes": [
+          models.Index(
+            fields=["concurrency_key", "priority", "id"], name="dj_queue_bl_concurr_1ce730_idx"
+          ),
+          models.Index(
+            fields=["expires_at", "concurrency_key"], name="dj_queue_bl_expires_ea27f7_idx"
+          ),
+        ],
+      },
+    ),
+    migrations.AddIndex(
+      model_name="process",
+      index=models.Index(fields=["name", "supervisor"], name="dj_queue_pr_name_d374d8_idx"),
+    ),
+    migrations.AddIndex(
+      model_name="process",
+      index=models.Index(fields=["last_heartbeat_at"], name="dj_queue_pr_last_he_813530_idx"),
+    ),
+    migrations.AddConstraint(
+      model_name="process",
+      constraint=models.UniqueConstraint(
+        fields=("name", "supervisor"), name="dj_queue_processes_name_supervisor_unique"
+      ),
+    ),
+    migrations.AddIndex(
+      model_name="claimedexecution",
+      index=models.Index(fields=["process", "job"], name="dj_queue_cl_process_647400_idx"),
+    ),
+    migrations.AddIndex(
+      model_name="readyexecution",
+      index=models.Index(fields=["priority", "id"], name="dj_queue_re_priorit_bfc737_idx"),
+    ),
+    migrations.AddIndex(
+      model_name="readyexecution",
+      index=models.Index(
+        fields=["queue_name", "priority", "id"], name="dj_queue_re_queue_n_9931e4_idx"
+      ),
+    ),
+    migrations.AddIndex(
+      model_name="scheduledexecution",
+      index=models.Index(
+        fields=["scheduled_at", "priority", "id"], name="dj_queue_sc_schedul_7e8dd0_idx"
+      ),
+    ),
+  ]

dj_queue/migrations/0002_pause_semaphore.py

@@ -0,0 +1,52 @@
+# Generated by Django 6.0.3 on 2026-04-06 15:16
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+  dependencies = [
+    ("dj_queue", "0001_initial"),
+  ]
+
+  operations = [
+    migrations.CreateModel(
+      name="Pause",
+      fields=[
+        (
+          "id",
+          models.BigAutoField(
+            auto_created=True, primary_key=True, serialize=False, verbose_name="ID"
+          ),
+        ),
+        ("queue_name", models.CharField(max_length=64, unique=True)),
+        ("created_at", models.DateTimeField(auto_now_add=True)),
+      ],
+      options={
+        "db_table": "dj_queue_pauses",
+      },
+    ),
+    migrations.CreateModel(
+      name="Semaphore",
+      fields=[
+        (
+          "id",
+          models.BigAutoField(
+            auto_created=True, primary_key=True, serialize=False, verbose_name="ID"
+          ),
+        ),
+        ("key", models.CharField(max_length=255, unique=True)),
+        ("value", models.IntegerField()),
+        ("limit", models.IntegerField()),
+        ("expires_at", models.DateTimeField()),
+        ("created_at", models.DateTimeField(auto_now_add=True)),
+        ("updated_at", models.DateTimeField(auto_now=True)),
+      ],
+      options={
+        "db_table": "dj_queue_semaphores",
+        "indexes": [
+          models.Index(fields=["key", "value"], name="dj_queue_se_key_7a5af2_idx"),
+          models.Index(fields=["expires_at"], name="dj_queue_se_expires_811b4d_idx"),
+        ],
+      },
+    ),
+  ]

dj_queue/migrations/0003_recurringtask_recurringexecution.py

@@ -0,0 +1,73 @@
+# Generated by Django 6.0.3 on 2026-04-06 15:34
+
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+  dependencies = [
+    ("dj_queue", "0002_pause_semaphore"),
+  ]
+
+  operations = [
+    migrations.CreateModel(
+      name="RecurringTask",
+      fields=[
+        (
+          "id",
+          models.BigAutoField(
+            auto_created=True, primary_key=True, serialize=False, verbose_name="ID"
+          ),
+        ),
+        ("key", models.CharField(max_length=255, unique=True)),
+        ("task_path", models.CharField(max_length=255)),
+        ("payload", models.JSONField(blank=True, null=True)),
+        ("schedule", models.CharField(max_length=255)),
+        ("queue_name", models.CharField(default="default", max_length=64)),
+        ("priority", models.SmallIntegerField(default=0)),
+        ("description", models.TextField(blank=True, default="")),
+        ("static", models.BooleanField(default=False)),
+        ("created_at", models.DateTimeField(auto_now_add=True)),
+        ("updated_at", models.DateTimeField(auto_now=True)),
+      ],
+      options={
+        "db_table": "dj_queue_recurring_tasks",
+      },
+    ),
+    migrations.CreateModel(
+      name="RecurringExecution",
+      fields=[
+        (
+          "id",
+          models.BigAutoField(
+            auto_created=True, primary_key=True, serialize=False, verbose_name="ID"
+          ),
+        ),
+        ("task_key", models.CharField(max_length=255)),
+        ("run_at", models.DateTimeField()),
+        ("created_at", models.DateTimeField(auto_now_add=True)),
+        (
+          "job",
+          models.OneToOneField(
+            blank=True,
+            null=True,
+            on_delete=django.db.models.deletion.CASCADE,
+            related_name="recurring_execution",
+            to="dj_queue.job",
+          ),
+        ),
+      ],
+      options={
+        "db_table": "dj_queue_recurring_executions",
+        "indexes": [
+          models.Index(fields=["task_key", "run_at"], name="dj_queue_re_task_ke_8e21b4_idx")
+        ],
+        "constraints": [
+          models.UniqueConstraint(
+            fields=("task_key", "run_at"),
+            name="dj_queue_recurring_executions_task_key_run_at_unique",
+          )
+        ],
+      },
+    ),
+  ]

dj_queue/models/__init__.py

@@ -0,0 +1,24 @@
+from dj_queue.models.jobs import (
+  BlockedExecution,
+  ClaimedExecution,
+  FailedExecution,
+  Job,
+  ReadyExecution,
+  ScheduledExecution,
+)
+from dj_queue.models.recurring import RecurringExecution, RecurringTask
+from dj_queue.models.runtime import Pause, Process, Semaphore
+
+__all__ = [
+  "BlockedExecution",
+  "ClaimedExecution",
+  "FailedExecution",
+  "Job",
+  "Pause",
+  "Process",
+  "ReadyExecution",
+  "RecurringExecution",
+  "RecurringTask",
+  "ScheduledExecution",
+  "Semaphore",
+]