dj-queue 0.5.1__tar.gz → 0.6.1__tar.gz

{dj_queue-0.5.1 → dj_queue-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dj-queue
-Version: 0.5.1
+Version: 0.6.1
 Summary: Database-backed task queue backend for Django’s Tasks framework.
 License-Expression: MIT
 License-File: LICENSE
@@ -105,6 +105,12 @@ TASKS = {
 The router is optional when using the default database, but harmless to include
 and required for [multi-database setups](#multi-database-setup).
 
+`dj_queue` can coexist with other Django task backends in the same `TASKS`
+setting. It only manages aliases whose `BACKEND` is
+`"dj_queue.backend.DjQueueBackend"`. If a `TASKS` alias points at some other
+backend, `dj_queue` ignores that alias for runtime commands, admin/dashboard
+selection, and observability.
+
 Run migrations:
 
 ```bash
@@ -266,15 +272,17 @@ Useful command variants:
 ```bash
 python manage.py dj_queue
 python manage.py dj_queue --mode async
+python manage.py dj_queue --backend <alias>
 python manage.py dj_queue --only-work
 python manage.py dj_queue --only-dispatch
 python manage.py dj_queue --skip-recurring
 ```
 
-Mode and topology notes:
+Notes:
 
 - `fork` is the default standalone mode
 - `async` is also supported as a standalone mode and runs supervised actors in threads inside one process
+- `--backend` targets a non-default backend alias
 - `--only-work` starts workers without dispatchers or scheduler
 - `--only-dispatch` starts dispatchers without workers or scheduler
 - `--skip-recurring` starts without the scheduler
@@ -303,8 +311,7 @@ across queues. Prefer one primary scheduling mechanism per worker when you can.
 
 ### Signals and recovery
 
-In standalone mode, both `fork` and `async` `python manage.py dj_queue`
-supervisors own runtime signal handling:
+In standalone mode, both `fork` and `async` `python manage.py dj_queue` supervisors own runtime signal handling:
 
 - `SIGTERM` and `SIGINT` request graceful shutdown
 - `SIGQUIT` takes the immediate hard-exit path
@@ -461,7 +468,7 @@ orders.resume()
 orders.clear()
 ```
 
-Queue control notes:
+Notes:
 
 - pausing a queue stops future claims, not enqueueing or already-claimed work
 - pause rows are scoped per backend alias
@@ -480,8 +487,7 @@ python manage.py dj_queue_prune --task-path myapp.tasks.cleanup
 python manage.py dj_queue_prune --task-key nightly_cleanup
 ```
 
-The runtime, health, and prune commands all accept `--backend` to target a
-non-default backend alias.
+The health and prune commands both accept `--backend` to target a non-default backend alias.
 
 For `dj_queue_prune`, `--task-path` filters finished and failed job cleanup by
 task import path, while `--task-key` filters recurring execution cleanup by
@@ -578,7 +584,7 @@ Available hook helpers:
 - scheduler: `on_scheduler_start`, `on_scheduler_stop`, `on_scheduler_exit`
 - generic events: `register_hook("worker.start")`, `register_hook("dispatcher.stop")`, and so on
 
-Hook notes:
+Notes:
 
 - hooks fire in registration order
 - hook failures do not block later hooks
@@ -586,9 +592,7 @@ Hook notes:
 
 ## Multi-Database Setup
 
-`dj_queue` can keep queue tables on a dedicated database alias.
-
-Example configuration:
+`dj_queue` can keep queue tables on a dedicated database alias:
 
 ```python
 DATABASES = {
@@ -626,6 +630,38 @@ python manage.py migrate dj_queue --database queue
 With this setup, `dj_queue`'s ORM queries and raw SQL helpers stay on the queue
 database.
 
+## Backend Coexistence
+
+Projects can mix `dj_queue` with other Django task backends in the same `TASKS` mapping:
+
+```python
+TASKS = {
+  "default": {
+    "BACKEND": "dj_queue.backend.DjQueueBackend",
+    "QUEUES": [],
+    "OPTIONS": {
+      "database_alias": "queue",
+    },
+  },
+  "external": {
+    "BACKEND": "some_other_backend.Backend",
+    "QUEUES": [],
+    "OPTIONS": {},
+  },
+}
+```
+
+In that setup:
+
+- jobs with `backend="default"` are `dj_queue`'s responsibility
+- jobs with `backend="external"` are the other backend's responsibility
+- `dj_queue` admin, dashboard, `/dj_queue/stats.json`, `/dj_queue/metrics`, and `manage.py dj_queue --backend ...` only operate on `dj_queue` aliases
+
+Notes:
+
+- if `TASKS` is empty or unset, `dj_queue` still exposes one implicit `default` alias using built-in defaults
+- if `TASKS` is non-empty, `dj_queue` only manages aliases whose `BACKEND` is explicitly `"dj_queue.backend.DjQueueBackend"`
+
 ## Postgres Queue Health
 
 Operational and configuration guidance for scaling with `dj_queue` in
@@ -869,6 +905,9 @@ become failed jobs instead.
 Queue statistics are available in JSON via `/dj_queue/stats.json` and in
 Prometheus text format via `/dj_queue/metrics`.
 
+These observability endpoints only report `dj_queue`-managed backend aliases and
+ignore aliases configured for some other task backend.
+
 Include `dj_queue.urls` to expose them:
 
 ```python

{dj_queue-0.5.1 → dj_queue-0.6.1}/README.md

@@ -77,6 +77,12 @@ TASKS = {
 The router is optional when using the default database, but harmless to include
 and required for [multi-database setups](#multi-database-setup).
 
+`dj_queue` can coexist with other Django task backends in the same `TASKS`
+setting. It only manages aliases whose `BACKEND` is
+`"dj_queue.backend.DjQueueBackend"`. If a `TASKS` alias points at some other
+backend, `dj_queue` ignores that alias for runtime commands, admin/dashboard
+selection, and observability.
+
 Run migrations:
 
 ```bash
@@ -238,15 +244,17 @@ Useful command variants:
 ```bash
 python manage.py dj_queue
 python manage.py dj_queue --mode async
+python manage.py dj_queue --backend <alias>
 python manage.py dj_queue --only-work
 python manage.py dj_queue --only-dispatch
 python manage.py dj_queue --skip-recurring
 ```
 
-Mode and topology notes:
+Notes:
 
 - `fork` is the default standalone mode
 - `async` is also supported as a standalone mode and runs supervised actors in threads inside one process
+- `--backend` targets a non-default backend alias
 - `--only-work` starts workers without dispatchers or scheduler
 - `--only-dispatch` starts dispatchers without workers or scheduler
 - `--skip-recurring` starts without the scheduler
@@ -275,8 +283,7 @@ across queues. Prefer one primary scheduling mechanism per worker when you can.
 
 ### Signals and recovery
 
-In standalone mode, both `fork` and `async` `python manage.py dj_queue`
-supervisors own runtime signal handling:
+In standalone mode, both `fork` and `async` `python manage.py dj_queue` supervisors own runtime signal handling:
 
 - `SIGTERM` and `SIGINT` request graceful shutdown
 - `SIGQUIT` takes the immediate hard-exit path
@@ -433,7 +440,7 @@ orders.resume()
 orders.clear()
 ```
 
-Queue control notes:
+Notes:
 
 - pausing a queue stops future claims, not enqueueing or already-claimed work
 - pause rows are scoped per backend alias
@@ -452,8 +459,7 @@ python manage.py dj_queue_prune --task-path myapp.tasks.cleanup
 python manage.py dj_queue_prune --task-key nightly_cleanup
 ```
 
-The runtime, health, and prune commands all accept `--backend` to target a
-non-default backend alias.
+The health and prune commands both accept `--backend` to target a non-default backend alias.
 
 For `dj_queue_prune`, `--task-path` filters finished and failed job cleanup by
 task import path, while `--task-key` filters recurring execution cleanup by
@@ -550,7 +556,7 @@ Available hook helpers:
 - scheduler: `on_scheduler_start`, `on_scheduler_stop`, `on_scheduler_exit`
 - generic events: `register_hook("worker.start")`, `register_hook("dispatcher.stop")`, and so on
 
-Hook notes:
+Notes:
 
 - hooks fire in registration order
 - hook failures do not block later hooks
@@ -558,9 +564,7 @@ Hook notes:
 
 ## Multi-Database Setup
 
-`dj_queue` can keep queue tables on a dedicated database alias.
-
-Example configuration:
+`dj_queue` can keep queue tables on a dedicated database alias:
 
 ```python
 DATABASES = {
@@ -598,6 +602,38 @@ python manage.py migrate dj_queue --database queue
 With this setup, `dj_queue`'s ORM queries and raw SQL helpers stay on the queue
 database.
 
+## Backend Coexistence
+
+Projects can mix `dj_queue` with other Django task backends in the same `TASKS` mapping:
+
+```python
+TASKS = {
+  "default": {
+    "BACKEND": "dj_queue.backend.DjQueueBackend",
+    "QUEUES": [],
+    "OPTIONS": {
+      "database_alias": "queue",
+    },
+  },
+  "external": {
+    "BACKEND": "some_other_backend.Backend",
+    "QUEUES": [],
+    "OPTIONS": {},
+  },
+}
+```
+
+In that setup:
+
+- jobs with `backend="default"` are `dj_queue`'s responsibility
+- jobs with `backend="external"` are the other backend's responsibility
+- `dj_queue` admin, dashboard, `/dj_queue/stats.json`, `/dj_queue/metrics`, and `manage.py dj_queue --backend ...` only operate on `dj_queue` aliases
+
+Notes:
+
+- if `TASKS` is empty or unset, `dj_queue` still exposes one implicit `default` alias using built-in defaults
+- if `TASKS` is non-empty, `dj_queue` only manages aliases whose `BACKEND` is explicitly `"dj_queue.backend.DjQueueBackend"`
+
 ## Postgres Queue Health
 
 Operational and configuration guidance for scaling with `dj_queue` in
@@ -841,6 +877,9 @@ become failed jobs instead.
 Queue statistics are available in JSON via `/dj_queue/stats.json` and in
 Prometheus text format via `/dj_queue/metrics`.
 
+These observability endpoints only report `dj_queue`-managed backend aliases and
+ignore aliases configured for some other task backend.
+
 Include `dj_queue.urls` to expose them:
 
 ```python

{dj_queue-0.5.1 → dj_queue-0.6.1}/dj_queue/config.py

@@ -54,6 +54,8 @@ DEFAULT_OPTIONS = {
   "on_thread_error": None,
 }
 
+DJ_QUEUE_BACKEND_PATH = "dj_queue.backend.DjQueueBackend"
+
 TRUTHY_ENV_VALUES = {"1", "true", "yes", "on"}
 FALSY_ENV_VALUES = {"0", "false", "no", "off"}
 CONFIG_ENV_KEYS = ("DJ_QUEUE_CONFIG", "DJ_QUEUE_MODE", "DJ_QUEUE_SKIP_RECURRING")
@@ -163,6 +165,7 @@ def _load_backend_config_cached(
   cli_overrides = json.loads(cli_overrides_key)
   env = json.loads(env_key)
   tasks_settings = json.loads(tasks_settings_key)
+  ensure_dj_queue_backend_alias(tasks_settings, backend_alias)
   backend_block = _backend_block(tasks_settings, backend_alias)
   resolved_options = _resolved_options(backend_alias, backend_block, cli_overrides, env)
 
@@ -241,12 +244,56 @@ def _backend_block(
   if resolved_tasks_settings is None:
     resolved_tasks_settings = getattr(settings, "TASKS", {})
 
-  backend_block = resolved_tasks_settings.get(backend_alias, {})
+  if not resolved_tasks_settings:
+    if backend_alias == "default":
+      return {}
+    raise ImproperlyConfigured(f"dj_queue backend alias {backend_alias!r} is not configured")
+
+  if backend_alias not in resolved_tasks_settings:
+    raise ImproperlyConfigured(f"dj_queue backend alias {backend_alias!r} is not configured")
+
+  backend_block = resolved_tasks_settings[backend_alias]
   if not isinstance(backend_block, Mapping):
     raise ImproperlyConfigured(f"TASKS[{backend_alias!r}] must be a mapping")
   return backend_block
 
 
+def configured_backend_aliases(
+  tasks_settings: Mapping[str, Any] | None = None,
+) -> tuple[str, ...]:
+  resolved_tasks_settings = tasks_settings
+  if resolved_tasks_settings is None:
+    resolved_tasks_settings = getattr(settings, "TASKS", {})
+
+  if not resolved_tasks_settings:
+    return ("default",)
+
+  aliases = []
+  for alias, backend_block in resolved_tasks_settings.items():
+    if not isinstance(backend_block, Mapping):
+      raise ImproperlyConfigured(f"TASKS[{alias!r}] must be a mapping")
+    if is_dj_queue_backend_alias(backend_block):
+      aliases.append(alias)
+  return tuple(aliases)
+
+
+def ensure_dj_queue_backend_alias(
+  tasks_settings: Mapping[str, Any] | None,
+  backend_alias: str,
+) -> None:
+  aliases = configured_backend_aliases(tasks_settings)
+  if backend_alias in aliases:
+    return
+  raise ImproperlyConfigured(
+    f"dj_queue backend alias {backend_alias!r} is not configured for DjQueueBackend"
+  )
+
+
+def is_dj_queue_backend_alias(backend_block: Mapping[str, Any]) -> bool:
+  backend_path = backend_block.get("BACKEND")
+  return backend_path == DJ_QUEUE_BACKEND_PATH
+
+
 def _resolved_options(
   backend_alias: str,
   backend_block: Mapping[str, Any],

{dj_queue-0.5.1 → dj_queue-0.6.1}/dj_queue/management/commands/dj_queue.py

@@ -1,4 +1,6 @@
+from django.core.exceptions import ImproperlyConfigured
 from django.core.management.base import BaseCommand
+from django.core.management.base import CommandError
 
 from dj_queue.config import load_backend_config
 from dj_queue.runtime.supervisor import AsyncSupervisor, ForkSupervisor
@@ -32,8 +34,11 @@ class Command(BaseCommand):
       "only_dispatch": options["only_dispatch"],
       "skip_recurring": options["skip_recurring"],
     }
-    supervisor = build_supervisor(
-      backend_alias=options["backend"],
-      cli_overrides=cli_overrides,
-    )
+    try:
+      supervisor = build_supervisor(
+        backend_alias=options["backend"],
+        cli_overrides=cli_overrides,
+      )
+    except ImproperlyConfigured as exc:
+      raise CommandError(str(exc)) from exc
     supervisor.run()

{dj_queue-0.5.1 → dj_queue-0.6.1}/dj_queue/observability.py

@@ -9,6 +9,7 @@ from django.db.models import Count, Max, Min
 from django.db.models.functions import Coalesce
 from django.utils import timezone
 
+from dj_queue.config import configured_backend_aliases as configured_dj_queue_backend_aliases
 from dj_queue.config import load_backend_config
 from dj_queue.db import get_database_alias
 from dj_queue.models import (
@@ -33,11 +34,7 @@ class BackendChoice:
 
 
 def configured_backend_aliases():
-  tasks = getattr(settings, "TASKS", {})
-  aliases = tuple(tasks)
-  if aliases:
-    return aliases
-  return ("default",)
+  return configured_dj_queue_backend_aliases(getattr(settings, "TASKS", {}))
 
 
 def backend_choices():

{dj_queue-0.5.1 → dj_queue-0.6.1}/dj_queue/operations/recurring.py

@@ -1,4 +1,4 @@
-from django.db import IntegrityError, transaction
+from django.db import transaction
 from django.utils.module_loading import import_string
 
 from dj_queue.db import get_database_alias
@@ -62,13 +62,12 @@ def fire_recurring_task(recurring_task, run_at, *, backend_alias="default"):
   alias = get_database_alias(backend_alias)
 
   with transaction.atomic(using=alias):
-    try:
-      execution = RecurringExecution.objects.using(alias).create(
-        backend_alias=backend_alias,
-        task_key=recurring_task.key,
-        run_at=run_at,
-      )
-    except IntegrityError:
+    execution, created = RecurringExecution.objects.using(alias).get_or_create(
+      backend_alias=backend_alias,
+      task_key=recurring_task.key,
+      run_at=run_at,
+    )
+    if not created:
       # treat an existing reservation row as authoritative even if its job backfill
       # has not happened yet, so duplicate scheduler ticks never enqueue twice
       return None

{dj_queue-0.5.1 → dj_queue-0.6.1}/dj_queue/runtime/scheduler.py

@@ -21,6 +21,10 @@ class Scheduler(BaseRunner):
   process_kind = "Scheduler"
   hook_prefix = "scheduler"
 
+  @property
+  def polling_interval(self):
+    return self.config.scheduler.polling_interval
+
   def __init__(
     self,
     config,

{dj_queue-0.5.1 → dj_queue-0.6.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "dj-queue"
-version = "0.5.1"
+version = "0.6.1"
 description = "Database-backed task queue backend for Django’s Tasks framework."
 readme = "README.md"
 license = "MIT"