dj-queue 0.8.1__tar.gz → 0.9.1__tar.gz

{dj_queue-0.8.1 → dj_queue-0.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dj-queue
-Version: 0.8.1
+Version: 0.9.1
 Summary: Database-backed task queue backend for Django’s Tasks framework.
 License-Expression: MIT
 License-File: LICENSE
@@ -13,9 +13,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Dist: croniter>=6.2.2
 Requires-Dist: django>=6.0.0
-Requires-Dist: pyyaml>=6.0.3
 Requires-Dist: psycopg>=3.3.3 ; extra == 'postgres'
 Requires-Dist: prometheus-client>=0.4.0 ; extra == 'prometheus'
 Requires-Python: >=3.12
@@ -408,15 +406,18 @@ unschedule_recurring_task("tenant_42_report")
 
 Dynamic recurring tasks require
 `TASKS[backend_alias]["OPTIONS"]["scheduler"]["dynamic_tasks_enabled"] = True`
-or the equivalent `scheduler.dynamic_tasks_enabled: true` in the optional YAML
+or the equivalent `scheduler.dynamic_tasks_enabled = true` in the optional TOML
 config.
 
-The scheduler is part of the normal `dj_queue` runtime. You do not run a
-separate recurring service.
+The scheduler is part of the normal `dj_queue` runtime. You do not run a separate recurring service.
 
 Notes:
 
-- schedules are cron expressions
+- schedules are [Fugit](https://github.com/floraison/fugit#fugitcron)-style cron or cronish natural-language expressions
+- cron supports five fields or an optional leading seconds field, presets like `@daily`, optional timezone suffixes, wraparound ranges, `L`/`last` and negative monthdays, weekday `#` and `%` extensions, and normal day-of-month/day-of-week OR semantics
+- add `&` to either day field to require day-of-month and day-of-week to both match
+- natural-language schedules support `every`, `at`, `on`, and `from` forms such as `every day at noon`, `every weekday at five`, `every 5 minutes`, `every month on day 2 at 10:00`, `from monday to friday at 9`, and `at minute 5`
+- natural-language schedules that expand to multiple cron expressions, such as `every day at 16:15 and 18:30`, are treated as the union of those schedules
 - recurring task keys are scoped per backend alias
 - only dynamic tasks can be unscheduled at runtime; unscheduling a static task returns `0`
 - Django admin exposes the same unschedule operation on recurring-task list and detail views
@@ -810,83 +811,83 @@ Configuration precedence is explicit:
 
 - CLI overrides
 - environment variables
-- YAML file pointed to by `DJ_QUEUE_CONFIG`
+- TOML file pointed to by `DJ_QUEUE_CONFIG`
 - Django `TASKS` settings
 
-### YAML file config
+### TOML file config
 
 ```bash
 # via cli
-python manage.py dj_queue --config /etc/dj_queue.yml
+python manage.py dj_queue --config /etc/dj_queue.toml
 
 # or via environment variable
-DJ_QUEUE_CONFIG=/etc/dj_queue.yml python manage.py dj_queue
+DJ_QUEUE_CONFIG=/etc/dj_queue.toml python manage.py dj_queue
 ```
 
-The YAML file is an overlay on `TASKS[backend_alias]["OPTIONS"]`. It supports
+The TOML file is an overlay on `TASKS[backend_alias]["OPTIONS"]`. It supports
 two shapes:
 
 - a flat mapping of option values for the selected backend alias
 - a `backends` mapping keyed by backend alias, where only the selected alias is applied
 
+TOML has no `null` value. Omit optional settings to keep their existing defaults.
+
 Flat mapping example:
 
-```yaml
-mode: async
-database_alias: queue
-preserve_finished_jobs: true
-clear_finished_jobs_after: 86400
-clear_failed_jobs_after: null
-clear_recurring_executions_after: null
-listen_notify: true
-silence_polling: true
-
-workers:
-  - queues: ["default", "email*"]
-    threads: 8
-    processes: 1
-    polling_interval: 0.1
-
-dispatchers:
-  - batch_size: 500
-    polling_interval: 1
-    concurrency_maintenance: true
-    concurrency_maintenance_interval: 600
-
-scheduler:
-  dynamic_tasks_enabled: true
-  polling_interval: 5
-
-recurring:
-  nightly_cleanup:
-    task_path: myapp.tasks.cleanup
-    schedule: "0 3 * * *"
-    queue_name: maintenance
-    priority: -5
-    description: nightly cleanup
+```toml
+mode = "async"
+database_alias = "queue"
+preserve_finished_jobs = true
+clear_finished_jobs_after = 86400
+listen_notify = true
+silence_polling = true
+
+[[workers]]
+queues = ["default", "email*"]
+threads = 8
+processes = 1
+polling_interval = 0.1
+
+[[dispatchers]]
+batch_size = 500
+polling_interval = 1
+concurrency_maintenance = true
+concurrency_maintenance_interval = 600
+
+[scheduler]
+dynamic_tasks_enabled = true
+polling_interval = 5
+
+[recurring.nightly_cleanup]
+task_path = "myapp.tasks.cleanup"
+schedule = "0 3 * * *"
+queue_name = "maintenance"
+priority = -5
+description = "nightly cleanup"
 ```
 
 Multi-backend overlay example:
 
-```yaml
-backends:
-  default:
-    mode: async
-    database_alias: default
-    workers:
-      - queues: ["default", "email*"]
-        threads: 8
-        processes: 1
-        polling_interval: 0.1
-
-  critical:
-    mode: fork
-    database_alias: queue
-    workers:
-      - queues: ["alerts", "critical-review"]
-        threads: 2
-        processes: 1
-        polling_interval: 0.05
+```toml
+[backends.default]
+mode = "async"
+database_alias = "default"
+
+[[backends.default.workers]]
+queues = ["default", "email*"]
+threads = 8
+processes = 1
+polling_interval = 0.1
+
+[backends.critical]
+mode = "fork"
+database_alias = "queue"
+
+[[backends.critical.workers]]
+queues = ["alerts", "critical-review"]
+threads = 2
+processes = 1
+polling_interval = 0.05
 ```
 
 Environment overrides currently supported by `dj_queue` itself:

{dj_queue-0.8.1 → dj_queue-0.9.1}/README.md

@@ -380,15 +380,18 @@ unschedule_recurring_task("tenant_42_report")
 
 Dynamic recurring tasks require
 `TASKS[backend_alias]["OPTIONS"]["scheduler"]["dynamic_tasks_enabled"] = True`
-or the equivalent `scheduler.dynamic_tasks_enabled: true` in the optional YAML
+or the equivalent `scheduler.dynamic_tasks_enabled = true` in the optional TOML
 config.
 
-The scheduler is part of the normal `dj_queue` runtime. You do not run a
-separate recurring service.
+The scheduler is part of the normal `dj_queue` runtime. You do not run a separate recurring service.
 
 Notes:
 
-- schedules are cron expressions
+- schedules are [Fugit](https://github.com/floraison/fugit#fugitcron)-style cron or cronish natural-language expressions
+- cron supports five fields or an optional leading seconds field, presets like `@daily`, optional timezone suffixes, wraparound ranges, `L`/`last` and negative monthdays, weekday `#` and `%` extensions, and normal day-of-month/day-of-week OR semantics
+- add `&` to either day field to require day-of-month and day-of-week to both match
+- natural-language schedules support `every`, `at`, `on`, and `from` forms such as `every day at noon`, `every weekday at five`, `every 5 minutes`, `every month on day 2 at 10:00`, `from monday to friday at 9`, and `at minute 5`
+- natural-language schedules that expand to multiple cron expressions, such as `every day at 16:15 and 18:30`, are treated as the union of those schedules
 - recurring task keys are scoped per backend alias
 - only dynamic tasks can be unscheduled at runtime; unscheduling a static task returns `0`
 - Django admin exposes the same unschedule operation on recurring-task list and detail views
@@ -782,83 +785,83 @@ Configuration precedence is explicit:
 
 - CLI overrides
 - environment variables
-- YAML file pointed to by `DJ_QUEUE_CONFIG`
+- TOML file pointed to by `DJ_QUEUE_CONFIG`
 - Django `TASKS` settings
 
-### YAML file config
+### TOML file config
 
 ```bash
 # via cli
-python manage.py dj_queue --config /etc/dj_queue.yml
+python manage.py dj_queue --config /etc/dj_queue.toml
 
 # or via environment variable
-DJ_QUEUE_CONFIG=/etc/dj_queue.yml python manage.py dj_queue
+DJ_QUEUE_CONFIG=/etc/dj_queue.toml python manage.py dj_queue
 ```
 
-The YAML file is an overlay on `TASKS[backend_alias]["OPTIONS"]`. It supports
+The TOML file is an overlay on `TASKS[backend_alias]["OPTIONS"]`. It supports
 two shapes:
 
 - a flat mapping of option values for the selected backend alias
 - a `backends` mapping keyed by backend alias, where only the selected alias is applied
 
+TOML has no `null` value. Omit optional settings to keep their existing defaults.
+
 Flat mapping example:
 
-```yaml
-mode: async
-database_alias: queue
-preserve_finished_jobs: true
-clear_finished_jobs_after: 86400
-clear_failed_jobs_after: null
-clear_recurring_executions_after: null
-listen_notify: true
-silence_polling: true
-
-workers:
-  - queues: ["default", "email*"]
-    threads: 8
-    processes: 1
-    polling_interval: 0.1
-
-dispatchers:
-  - batch_size: 500
-    polling_interval: 1
-    concurrency_maintenance: true
-    concurrency_maintenance_interval: 600
-
-scheduler:
-  dynamic_tasks_enabled: true
-  polling_interval: 5
-
-recurring:
-  nightly_cleanup:
-    task_path: myapp.tasks.cleanup
-    schedule: "0 3 * * *"
-    queue_name: maintenance
-    priority: -5
-    description: nightly cleanup
+```toml
+mode = "async"
+database_alias = "queue"
+preserve_finished_jobs = true
+clear_finished_jobs_after = 86400
+listen_notify = true
+silence_polling = true
+
+[[workers]]
+queues = ["default", "email*"]
+threads = 8
+processes = 1
+polling_interval = 0.1
+
+[[dispatchers]]
+batch_size = 500
+polling_interval = 1
+concurrency_maintenance = true
+concurrency_maintenance_interval = 600
+
+[scheduler]
+dynamic_tasks_enabled = true
+polling_interval = 5
+
+[recurring.nightly_cleanup]
+task_path = "myapp.tasks.cleanup"
+schedule = "0 3 * * *"
+queue_name = "maintenance"
+priority = -5
+description = "nightly cleanup"
 ```
 
 Multi-backend overlay example:
 
-```yaml
-backends:
-  default:
-    mode: async
-    database_alias: default
-    workers:
-      - queues: ["default", "email*"]
-        threads: 8
-        processes: 1
-        polling_interval: 0.1
-
-  critical:
-    mode: fork
-    database_alias: queue
-    workers:
-      - queues: ["alerts", "critical-review"]
-        threads: 2
-        processes: 1
-        polling_interval: 0.05
+```toml
+[backends.default]
+mode = "async"
+database_alias = "default"
+
+[[backends.default.workers]]
+queues = ["default", "email*"]
+threads = 8
+processes = 1
+polling_interval = 0.1
+
+[backends.critical]
+mode = "fork"
+database_alias = "queue"
+
+[[backends.critical.workers]]
+queues = ["alerts", "critical-review"]
+threads = 2
+processes = 1
+polling_interval = 0.05
 ```
 
 Environment overrides currently supported by `dj_queue` itself:

{dj_queue-0.8.1 → dj_queue-0.9.1}/dj_queue/admin.py

@@ -35,6 +35,7 @@ from dj_queue.operations.jobs import (
   retry_failed_job,
   retry_failed_jobs,
 )
+from dj_queue.queue_state import status_rank_expression
 
 
 class DjQueueFirstAdminSite(admin.AdminSite):
@@ -503,18 +504,7 @@ class JobAdmin(HiddenSidebarAdminMixin, admin.ModelAdmin):
 
   def get_queryset(self, request):
     queryset = super().get_queryset(request)
-    return queryset.annotate(
-      status_rank=Case(
-        When(ready_execution__isnull=False, then=Value(0)),
-        When(scheduled_execution__isnull=False, then=Value(1)),
-        When(claimed_execution__isnull=False, then=Value(2)),
-        When(blocked_execution__isnull=False, then=Value(3)),
-        When(failed_execution__isnull=False, then=Value(4)),
-        When(finished_at__isnull=False, then=Value(5)),
-        default=Value(99),
-        output_field=IntegerField(),
-      )
-    )
+    return queryset.annotate(status_rank=status_rank_expression())
 
   @admin.display(description="status", ordering="status_rank")
   def display_status(self, obj):

{dj_queue-0.8.1 → dj_queue-0.9.1}/dj_queue/config.py

@@ -1,6 +1,7 @@
 import json
 import math
 import os
+import tomllib
 import warnings
 from collections.abc import Mapping, Sequence
 from dataclasses import asdict, dataclass, field, replace
@@ -8,12 +9,12 @@ from functools import lru_cache
 from pathlib import Path
 from typing import Any
 
-import yaml
-from croniter import croniter
 from django.conf import settings
 from django.core.exceptions import ImproperlyConfigured
 from django.utils.module_loading import import_string
 
+from dj_queue.cron import is_valid_cron
+
 DEFAULT_WORKER = {
   "queues": "*",
   "threads": 3,
@@ -319,7 +320,7 @@ def _resolved_options(
   resolved_options.update(settings_options)
 
   config_path = cli_overrides.get("config") or env.get("DJ_QUEUE_CONFIG")
-  resolved_options.update(_load_yaml_options(config_path, backend_alias=backend_alias))
+  resolved_options.update(_load_toml_options(config_path, backend_alias=backend_alias))
 
   env_mode = env.get("DJ_QUEUE_MODE")
   if env_mode is not None:
@@ -332,15 +333,16 @@ def _resolved_options(
   return resolved_options
 
 
-def _load_yaml_options(config_path: Any, *, backend_alias: str) -> dict[str, Any]:
+def _load_toml_options(config_path: Any, *, backend_alias: str) -> dict[str, Any]:
   if not config_path:
     return {}
 
-  config_payload = yaml.safe_load(Path(config_path).read_text(encoding="utf-8"))
-  if config_payload is None:
-    return {}
+  try:
+    config_payload = tomllib.loads(Path(config_path).read_text(encoding="utf-8"))
+  except tomllib.TOMLDecodeError as exc:
+    raise ImproperlyConfigured(f"DJ_QUEUE_CONFIG TOML is invalid: {exc}") from exc
   if not isinstance(config_payload, dict):
-    raise ImproperlyConfigured("DJ_QUEUE_CONFIG must point to a YAML mapping")
+    raise ImproperlyConfigured("DJ_QUEUE_CONFIG must point to a TOML mapping")
 
   raw_backends = config_payload.get("backends")
   if raw_backends is None:
@@ -519,7 +521,7 @@ def _build_recurring_config(raw_recurring: Any) -> dict[str, RecurringTaskConfig
     schedule = raw_entry.get("schedule")
     if not task_path or not schedule:
       raise ImproperlyConfigured(f"recurring task {key!r} requires task_path and schedule")
-    if not croniter.is_valid(str(schedule)):
+    if not is_valid_cron(str(schedule)):
       raise ImproperlyConfigured(f"recurring task {key!r} has an invalid cron schedule")
 
     recurring[str(key)] = RecurringTaskConfig(

dj_queue-0.9.1/dj_queue/contrib/prometheus.py

@@ -0,0 +1,26 @@
+try:
+  from prometheus_client import CollectorRegistry, generate_latest
+  from prometheus_client.core import GaugeMetricFamily
+except ImportError:
+  DjQueueCollector = None
+  registry = None
+  generate_latest = None
+else:
+  from dj_queue.metrics import metric_families
+
+  class DjQueueCollector:
+    """Prometheus collector that exposes dj_queue metrics from the shared observability snapshot."""
+
+    def collect(self):
+      for family in metric_families():
+        gauge = GaugeMetricFamily(
+          family.name,
+          family.help_text,
+          labels=list(family.labels),
+        )
+        for sample in family.samples:
+          gauge.add_metric(list(sample.labels), sample.value)
+        yield gauge
+
+  registry = CollectorRegistry(auto_describe=False)
+  registry.register(DjQueueCollector())