threadmill 0.8.4__tar.gz → 0.9.0__tar.gz

{threadmill-0.8.4 → threadmill-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: threadmill
-Version: 0.8.4
+Version: 0.9.0
 Summary: The most reliable backend for Django's task framework.
 Keywords: Django,tasks,worker
 Author-email: Johannes Maron <johannes@maron.family>
@@ -171,6 +171,47 @@ uv add "threadmill[inspector]"
 uv run manage.py threadmill inspector
 ```
 
+### Autoscaling
+
+Threadmill exposes queue stats as JSON for KEDA's `metrics-api` scaler.
+KEDA is a CNCF autoscaler for Kubernetes.
+
+The `ready` value is the number of queued tasks that a worker can pick up now.
+
+Include the URL in your project:
+
+```python
+# urls.py
+from django.urls import include, path
+
+urlpatterns = [
+    path("threadmill/", include("threadmill.urls")),
+]
+```
+
+Create the ScaledObject with the public URL and both queues:
+
+```yaml
+apiVersion: keda.sh/v1alpha1
+kind: ScaledObject
+metadata:
+  name: threadmill-workers
+spec:
+  scaleTargetRef:
+    name: threadmill-workers
+  triggers:
+    - type: metrics-api
+      metadata:
+        url: "https://example.com/threadmill/queue-stats/?queue=emails&queue=reports"
+        valueLocation: "ready"
+        targetValue: "1000"
+```
+
+Use one endpoint per worker group.
+Set `backend` to use another backend alias. It defaults to `default`.
+
+Set `targetValue` to the ready backlog one replica can drain during your scale-up window.
+
 ### Redis Backend Options
 
 > [!IMPORTANT]

{threadmill-0.8.4 → threadmill-0.9.0}/README.md

@@ -131,6 +131,47 @@ uv add "threadmill[inspector]"
 uv run manage.py threadmill inspector
 ```
 
+### Autoscaling
+
+Threadmill exposes queue stats as JSON for KEDA's `metrics-api` scaler.
+KEDA is a CNCF autoscaler for Kubernetes.
+
+The `ready` value is the number of queued tasks that a worker can pick up now.
+
+Include the URL in your project:
+
+```python
+# urls.py
+from django.urls import include, path
+
+urlpatterns = [
+    path("threadmill/", include("threadmill.urls")),
+]
+```
+
+Create the ScaledObject with the public URL and both queues:
+
+```yaml
+apiVersion: keda.sh/v1alpha1
+kind: ScaledObject
+metadata:
+  name: threadmill-workers
+spec:
+  scaleTargetRef:
+    name: threadmill-workers
+  triggers:
+    - type: metrics-api
+      metadata:
+        url: "https://example.com/threadmill/queue-stats/?queue=emails&queue=reports"
+        valueLocation: "ready"
+        targetValue: "1000"
+```
+
+Use one endpoint per worker group.
+Set `backend` to use another backend alias. It defaults to `default`.
+
+Set `targetValue` to the ready backlog one replica can drain during your scale-up window.
+
 ### Redis Backend Options
 
 > [!IMPORTANT]

{threadmill-0.8.4 → threadmill-0.9.0}/threadmill/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.8.4'
-__version_tuple__ = version_tuple = (0, 8, 4)
+__version__ = version = '0.9.0'
+__version_tuple__ = version_tuple = (0, 9, 0)
 
-__commit_id__ = commit_id = 'g071a4ce76'
+__commit_id__ = commit_id = 'gf1d9fc31e'

{threadmill-0.8.4 → threadmill-0.9.0}/threadmill/backends/redis.py

@@ -242,7 +242,6 @@ class RedisTaskBackend(ThreadmillTaskBackend):
                 redis.default_backoff(), self.redis_connection_retries
             ),
         )
-        self._async_client: redis.asyncio.Redis | None = None
         self.redis_url = redis_url
         self.key_prefix = f"threadmill:{{{alias}}}"
         self.telemetry_channel = self.TELEMETRY_CHANNEL.format(prefix=self.key_prefix)
@@ -270,18 +269,14 @@ class RedisTaskBackend(ThreadmillTaskBackend):
             self._idle_backoffs.backoff = backoff
         return backoff
 
-    @property
     def async_client(self) -> redis.asyncio.Redis:
-        """Lazily-created async Redis client, reused across calls."""
-        if self._async_client is None:
-            self._async_client = redis.asyncio.Redis.from_url(
-                self.redis_url,
-                decode_responses=True,
-                retry=redis.asyncio.retry.Retry(
-                    redis.default_backoff(), self.redis_connection_retries
-                ),
-            )
-        return self._async_client
+        return redis.asyncio.Redis.from_url(
+            self.redis_url,
+            decode_responses=True,
+            retry=redis.asyncio.retry.Retry(
+                redis.default_backoff(), self.redis_connection_retries
+            ),
+        )
 
     def _compute_score(self, priority: int, enqueued_at: datetime.datetime) -> float:
         """
@@ -623,17 +618,19 @@ class RedisTaskBackend(ThreadmillTaskBackend):
     async def queue_stats(
         self, *, interval: datetime.timedelta = datetime.timedelta(seconds=60)
     ) -> BackendTelemetry:
-        client = self.async_client
-        pipe = client.pipeline()
-        for queue_name in self.queues:
-            pipe.zcard(self._segment_key(TaskResultStatus.READY, queue_name))
-            pipe.zcard(self._segment_key(TaskResultStatus.RUNNING, queue_name))
-            pipe.zcard(
-                self.DEFERRED_KEY.format(prefix=self.key_prefix, queue_name=queue_name)
-            )
-            pipe.zcard(self._segment_key(TaskResultStatus.SUCCESSFUL, queue_name))
-            pipe.zcard(self._segment_key(TaskResultStatus.FAILED, queue_name))
-        results = await pipe.execute()
+        async with self.async_client() as client:
+            pipe = client.pipeline()
+            for queue_name in self.queues:
+                pipe.zcard(self._segment_key(TaskResultStatus.READY, queue_name))
+                pipe.zcard(self._segment_key(TaskResultStatus.RUNNING, queue_name))
+                pipe.zcard(
+                    self.DEFERRED_KEY.format(
+                        prefix=self.key_prefix, queue_name=queue_name
+                    )
+                )
+                pipe.zcard(self._segment_key(TaskResultStatus.SUCCESSFUL, queue_name))
+                pipe.zcard(self._segment_key(TaskResultStatus.FAILED, queue_name))
+            results = await pipe.execute()
         zero_rates = QueueRates(interval=interval, ingress=0, egress=0)
         queues: dict[str, QueueStats] = {}
         for index, queue_name in enumerate(self.queues):
@@ -653,14 +650,13 @@ class RedisTaskBackend(ThreadmillTaskBackend):
     async def worker_telemetry(
         self,
     ) -> collections.abc.AsyncGenerator[TelemetryEvent]:
-        client = self.async_client
-        pubsub = client.pubsub()
-        await pubsub.subscribe(self.telemetry_channel)
-        pubsub.ignore_subscribe_messages = True
-        try:
-            async for message in pubsub.listen():
-                if (data := message.get("data")) is not None:
-                    direction, _, queue_name = data.partition(":")
+        async with self.async_client() as client:
+            pubsub = client.pubsub()
+            await pubsub.subscribe(self.telemetry_channel)
+            pubsub.ignore_subscribe_messages = True
+            try:
+                async for message in pubsub.listen():
+                    direction, _, queue_name = message["data"].partition(":")
                     try:
                         event = TelemetryEvent(
                             direction=TelemetryDirection(direction),
@@ -669,11 +665,10 @@ class RedisTaskBackend(ThreadmillTaskBackend):
                     except ValueError:
                         continue
                     yield event
-        finally:
-            await pubsub.unsubscribe(self.telemetry_channel)
-            await pubsub.aclose()
+            finally:
+                await pubsub.unsubscribe(self.telemetry_channel)
+                await pubsub.aclose()
 
     def close(self) -> None:
         """Close the Redis connections."""
         self.client.close()
-        self._async_client = None

threadmill-0.9.0/threadmill/exceptions.py

@@ -0,0 +1,13 @@
+"""Custom exceptions for the threadmill task framework."""
+
+
+class MissingExtraError(ImportError):
+    """Raised when an optional dependency extra is not installed."""
+
+    def __init__(self, extra: str) -> None:
+        self.extra = extra
+        super().__init__(f"Optional dependency missing. Install: threadmill[{extra}]")
+
+
+class AcknowledgementTimeoutError(Exception):
+    """Raised when a task's lease has expired before it could be acknowledged."""

{threadmill-0.8.4 → threadmill-0.9.0}/threadmill/management/commands/threadmill.py

@@ -8,10 +8,10 @@ from django.core.management.base import BaseCommand as DjangoBaseCommand
 from django.tasks import (
     DEFAULT_TASK_BACKEND_ALIAS,
     DEFAULT_TASK_QUEUE_NAME,
-    InvalidTaskBackend,
     task_backends,
 )
 
+from ...exceptions import MissingExtraError
 from ...executor import JsonFormatter, TaskExecutor
 
 
@@ -22,18 +22,36 @@ def kill_softly(signum, frame):
     raise KeyboardInterrupt(message)
 
 
-class WorkerCommand(DjangoBaseCommand):
-    """Run task workers to process enqueued tasks from the specified backends and queues."""
-
-    help = __doc__
-
+class ThreadmillCommand(DjangoBaseCommand):
     def add_arguments(self, parser):
         parser.add_argument(
             "-b",
             "--backend",
             default=DEFAULT_TASK_BACKEND_ALIAS,
-            help="Alias of the tasks backend to use.",
+            help="Alias of the tasks backend.",
         )
+
+    @staticmethod
+    def parse_duration(value: str) -> datetime.timedelta:
+        return datetime.timedelta(seconds=float(value))
+
+    def install_signal_handlers(self) -> None:
+        match sys.platform:
+            case "win32":
+                signal.signal(signal.SIGBREAK, kill_softly)
+            case _:
+                signal.signal(signal.SIGHUP, kill_softly)
+        signal.signal(signal.SIGTERM, kill_softly)
+        signal.signal(signal.SIGINT, kill_softly)
+
+
+class WorkerCommand(ThreadmillCommand):
+    """Run task workers to process enqueued tasks from the specified backends and queues."""
+
+    help = __doc__
+
+    def add_arguments(self, parser):
+        super().add_arguments(parser)
         parser.add_argument(
             "-q",
             "--queues",
@@ -80,14 +98,14 @@ class WorkerCommand(DjangoBaseCommand):
         )
         parser.add_argument(
             "--poll-interval",
-            type=float,
-            default=0.01,
+            type=self.parse_duration,
+            default=datetime.timedelta(seconds=0.01),
             help="Base wait between idle acquire attempts in seconds.",
         )
         parser.add_argument(
             "--poll-max-interval",
-            type=float,
-            default=1,
+            type=self.parse_duration,
+            default=datetime.timedelta(seconds=1),
             help="Maximum wait between idle acquire attempts in seconds.",
         )
         parser.add_argument(
@@ -120,19 +138,9 @@ class WorkerCommand(DjangoBaseCommand):
         log_format,
         **options,
     ):
-        match sys.platform:
-            case "win32":
-                signal.signal(signal.SIGBREAK, kill_softly)
-            case _:
-                signal.signal(signal.SIGHUP, kill_softly)
-        signal.signal(signal.SIGTERM, kill_softly)
-        signal.signal(signal.SIGINT, kill_softly)
+        self.install_signal_handlers()
         self.stdout.write(self.style.SUCCESS("Starting workers…"))
-        try:
-            backend = task_backends[backend]
-        except InvalidTaskBackend:
-            message = f"Invalid backend: {backend!r}"
-            raise CommandError(message)
+        backend = task_backends[backend]
         if _non_queues := set(queues) - set(backend.queues):
             message = f"Backend does not support all specified queues: {_non_queues!r}"
             raise CommandError(message)
@@ -158,8 +166,8 @@ class WorkerCommand(DjangoBaseCommand):
             max_tasks=max_tasks,
             max_tasks_jitter=max_tasks_jitter,
             prefetch_count=prefetch_count,
-            poll_interval=datetime.timedelta(seconds=poll_interval),
-            poll_max_interval=datetime.timedelta(seconds=poll_max_interval),
+            poll_interval=poll_interval,
+            poll_max_interval=poll_max_interval,
             exit_empty=exit_empty,
             queues=queues,
             log_formatter=log_formatter,
@@ -172,37 +180,17 @@ class WorkerCommand(DjangoBaseCommand):
             exe.shutdown()
 
 
-class InspectorCommand(DjangoBaseCommand):
+class InspectorCommand(ThreadmillCommand):
     """Launch the textual TUI inspector for task backends and queues."""
 
     help = __doc__
 
-    def add_arguments(self, parser):
-        parser.add_argument(
-            "-b",
-            "--backend",
-            default=DEFAULT_TASK_BACKEND_ALIAS,
-            help="Alias of the tasks backend to inspect.",
-        )
-
     def handle(self, *, backend, **options):
         try:
-            from ...backends.base import ThreadmillTaskBackend
             from ...inspector.app import InspectorApp
-        except ImportError:
-            message = "Optional dependency missing. Install: threadmill[inspector]"
-            raise CommandError(message)
-        try:
-            backend = task_backends[backend]
-        except InvalidTaskBackend as e:
-            message = f"Invalid backend: {backend!r}"
-            raise CommandError(message) from e
-
-        if not isinstance(backend, ThreadmillTaskBackend):
-            message = f"Backend {backend.alias!r} does not support inspection."
-            raise CommandError(message)
-
-        InspectorApp(backend=backend).run()
+        except ImportError as e:
+            raise MissingExtraError("inspector") from e
+        InspectorApp(backend=task_backends[backend]).run()
 
 
 class Command(BaseCommand):
@@ -223,4 +211,7 @@ class Command(BaseCommand):
 
     def handle(self, *args, **options):
         subcommand_name = options.pop("subcommand")
-        self.subcommands[subcommand_name]().execute(*args, **options)
+        try:
+            self.subcommands[subcommand_name]().execute(*args, **options)
+        except MissingExtraError as e:
+            raise CommandError(str(e)) from e

threadmill-0.9.0/threadmill/urls.py

@@ -0,0 +1,13 @@
+from django.urls import path
+
+from .views import QueueStatsView
+
+app_name = "threadmill"
+
+urlpatterns = [
+    path(
+        "queue-stats/",
+        QueueStatsView.as_view(),
+        name="queue-stats",
+    ),
+]

threadmill-0.9.0/threadmill/views.py

@@ -0,0 +1,32 @@
+from django.http import Http404, HttpRequest, JsonResponse
+from django.tasks import (
+    DEFAULT_TASK_BACKEND_ALIAS,
+    InvalidTaskBackend,
+    task_backends,
+)
+from django.views import View
+
+
+class QueueStatsView(View):
+    async def get(self, request: HttpRequest) -> JsonResponse:
+        try:
+            backend = task_backends[
+                request.GET.get("backend", DEFAULT_TASK_BACKEND_ALIAS)
+            ]
+        except InvalidTaskBackend as exception:
+            raise Http404 from exception
+        try:
+            telemetry = await backend.queue_stats()
+        except (AttributeError, NotImplementedError) as exception:
+            raise Http404 from exception
+        try:
+            return JsonResponse(
+                {
+                    "ready": sum(
+                        telemetry.queues[queue_name].counts.ready
+                        for queue_name in request.GET.getlist("queue", backend.queues)
+                    )
+                }
+            )
+        except (AttributeError, KeyError) as exception:
+            raise Http404 from exception

threadmill-0.8.4/threadmill/exceptions.py

@@ -1,5 +0,0 @@
-"""Custom exceptions for the threadmill task framework."""
-
-
-class AcknowledgementTimeoutError(Exception):
-    """Raised when a task's lease has expired before it could be acknowledged."""