django-celeryx 0.1.0a1__tar.gz

django_celeryx-0.1.0a1/.gitignore

@@ -0,0 +1,35 @@
+*.py[cod]
+__pycache__/
+.DS_Store
+*.sql
+*.bz2
+*~
+*.log
+*.json
+*.wsgi
+local_settings.py
+development_settings.py
+*.egg-info
+.project
+.pydevproject
+.settings
+versiontools*
+_build*
+doc/index.html
+/build/
+/dist/
+*.swp
+\#*
+.\#*
+.tox
+dump.rdb
+.idea
+.venv
+.coverage
+coverage.xml
+cobertura.xml
+CLAUDE.md
+site/
+*.sqlite3
+*.sqlite3-shm
+*.sqlite3-wal

django_celeryx-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oliver Haas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

django_celeryx-0.1.0a1/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: django-celeryx
+Version: 0.1.0a1
+Summary: Celery monitoring and management for Django admin
+Project-URL: Homepage, https://github.com/oliverhaas/django-celeryx
+Project-URL: Documentation, https://oliverhaas.github.io/django-celeryx/
+Project-URL: Repository, https://github.com/oliverhaas/django-celeryx.git
+Project-URL: Changelog, https://oliverhaas.github.io/django-celeryx/reference/changelog/
+Author-email: Oliver Haas <ohaas@e1plus.de>
+License: MIT
+License-File: LICENSE
+Keywords: admin,celery,django,flower,monitoring
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 5.2
+Classifier: Framework :: Django :: 6.0
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: django<7,>=5.2
+Provides-Extra: celery
+Requires-Dist: celery<6,>=5.4; extra == 'celery'
+Provides-Extra: celery-asyncio
+Requires-Dist: celery-asyncio>=6.0.0a1; extra == 'celery-asyncio'
+Provides-Extra: prometheus
+Requires-Dist: prometheus-client>=0.20.0; extra == 'prometheus'
+Provides-Extra: unfold
+Requires-Dist: django-unfold>=0.70.0; extra == 'unfold'
+Description-Content-Type: text/markdown
+
+# django-celeryx
+
+[![PyPI version](https://img.shields.io/pypi/v/django-celeryx.svg?style=flat)](https://pypi.org/project/django-celeryx/)
+[![Python versions](https://img.shields.io/pypi/pyversions/django-celeryx.svg)](https://pypi.org/project/django-celeryx/)
+[![CI](https://github.com/oliverhaas/django-celeryx/actions/workflows/ci.yml/badge.svg)](https://github.com/oliverhaas/django-celeryx/actions/workflows/ci.yml)
+
+Celery monitoring and management for Django admin. Like Flower, but embedded in your Django admin with htmx for real-time updates.
+
+## Installation
+
+```console
+pip install django-celeryx[celery]
+```
+
+Or with celery-asyncio:
+
+```console
+pip install django-celeryx[celery-asyncio]
+```
+
+## Quick Start
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "django_celeryx.admin",
+]
+```
+
+That's it. Start your Django server and navigate to the admin to see your Celery tasks and workers.
+
+## Features
+
+- **Real-time task monitoring** — Live task list with state, args, result, timing, auto-refreshing via htmx
+- **Worker management** — View worker status, pool info, active queues, configuration
+- **Control actions** — Revoke/terminate tasks, shutdown/restart workers, manage pools and queues
+- **Broker overview** — Queue names, routing keys, consumer counts
+- **Django admin native** — Looks and feels like standard Django admin, no separate service to run
+- **Database persistence** — All state persisted to database (dedicated SQLite file by default, or any Django database)
+- **Registered tasks** — Browse all registered task types, link to filtered task list
+
+## Task Monitoring
+
+The task list shows all Celery tasks with color-coded states:
+
+- **PENDING** (grey), **RECEIVED** (yellow), **STARTED** (blue), **SUCCESS** (green), **FAILURE** (red), **RETRY** (orange), **REVOKED** (purple)
+
+Configurable columns via `TASK_COLUMNS` setting.
+
+## Worker Management
+
+Worker detail view with tabbed interface (matching Flower):
+
+- **Pool** — Pool type, concurrency, processes. Controls: grow/shrink, autoscale
+- **Queues** — Active queues. Controls: add/cancel consumer
+- **Tasks** — Processed counts, active/scheduled/reserved/revoked tasks
+- **Limits** — Rate limits and timeouts
+- **Config** — Full worker Celery configuration
+- **Stats** — System resource usage, broker connection info
+
+## Control Actions
+
+Full control parity with Flower:
+
+- Revoke / terminate / abort tasks
+- Shutdown / restart worker pool
+- Grow / shrink pool, set autoscale
+- Add / cancel queue consumer
+- Set rate limits and time limits
+
+## Configuration
+
+```python
+CELERYX = {
+    "MAX_TASK_COUNT": 100_000,
+    "MAX_TASK_AGE": 86400,  # 24 hours
+    "AUTO_REFRESH_INTERVAL": 3,
+    "TASK_COLUMNS": ["name", "uuid", "state", "worker", "received", "started", "runtime"],
+}
+```
+
+## Unfold Theme
+
+For [django-unfold](https://github.com/unfoldadmin/django-unfold) users:
+
+```python
+INSTALLED_APPS = [
+    "unfold",
+    # ...
+    "django_celeryx.unfold",  # instead of django_celeryx.admin
+]
+```
+
+## Documentation
+
+Full documentation at [oliverhaas.github.io/django-celeryx](https://oliverhaas.github.io/django-celeryx/)
+
+## Requirements
+
+- Python 3.12+
+- Django 5.2+
+- Celery 5.4+ or celery-asyncio 6.0+
+
+## License
+
+MIT

django_celeryx-0.1.0a1/README.md

@@ -0,0 +1,106 @@
+# django-celeryx
+
+[![PyPI version](https://img.shields.io/pypi/v/django-celeryx.svg?style=flat)](https://pypi.org/project/django-celeryx/)
+[![Python versions](https://img.shields.io/pypi/pyversions/django-celeryx.svg)](https://pypi.org/project/django-celeryx/)
+[![CI](https://github.com/oliverhaas/django-celeryx/actions/workflows/ci.yml/badge.svg)](https://github.com/oliverhaas/django-celeryx/actions/workflows/ci.yml)
+
+Celery monitoring and management for Django admin. Like Flower, but embedded in your Django admin with htmx for real-time updates.
+
+## Installation
+
+```console
+pip install django-celeryx[celery]
+```
+
+Or with celery-asyncio:
+
+```console
+pip install django-celeryx[celery-asyncio]
+```
+
+## Quick Start
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "django_celeryx.admin",
+]
+```
+
+That's it. Start your Django server and navigate to the admin to see your Celery tasks and workers.
+
+## Features
+
+- **Real-time task monitoring** — Live task list with state, args, result, timing, auto-refreshing via htmx
+- **Worker management** — View worker status, pool info, active queues, configuration
+- **Control actions** — Revoke/terminate tasks, shutdown/restart workers, manage pools and queues
+- **Broker overview** — Queue names, routing keys, consumer counts
+- **Django admin native** — Looks and feels like standard Django admin, no separate service to run
+- **Database persistence** — All state persisted to database (dedicated SQLite file by default, or any Django database)
+- **Registered tasks** — Browse all registered task types, link to filtered task list
+
+## Task Monitoring
+
+The task list shows all Celery tasks with color-coded states:
+
+- **PENDING** (grey), **RECEIVED** (yellow), **STARTED** (blue), **SUCCESS** (green), **FAILURE** (red), **RETRY** (orange), **REVOKED** (purple)
+
+Configurable columns via `TASK_COLUMNS` setting.
+
+## Worker Management
+
+Worker detail view with tabbed interface (matching Flower):
+
+- **Pool** — Pool type, concurrency, processes. Controls: grow/shrink, autoscale
+- **Queues** — Active queues. Controls: add/cancel consumer
+- **Tasks** — Processed counts, active/scheduled/reserved/revoked tasks
+- **Limits** — Rate limits and timeouts
+- **Config** — Full worker Celery configuration
+- **Stats** — System resource usage, broker connection info
+
+## Control Actions
+
+Full control parity with Flower:
+
+- Revoke / terminate / abort tasks
+- Shutdown / restart worker pool
+- Grow / shrink pool, set autoscale
+- Add / cancel queue consumer
+- Set rate limits and time limits
+
+## Configuration
+
+```python
+CELERYX = {
+    "MAX_TASK_COUNT": 100_000,
+    "MAX_TASK_AGE": 86400,  # 24 hours
+    "AUTO_REFRESH_INTERVAL": 3,
+    "TASK_COLUMNS": ["name", "uuid", "state", "worker", "received", "started", "runtime"],
+}
+```
+
+## Unfold Theme
+
+For [django-unfold](https://github.com/unfoldadmin/django-unfold) users:
+
+```python
+INSTALLED_APPS = [
+    "unfold",
+    # ...
+    "django_celeryx.unfold",  # instead of django_celeryx.admin
+]
+```
+
+## Documentation
+
+Full documentation at [oliverhaas.github.io/django-celeryx](https://oliverhaas.github.io/django-celeryx/)
+
+## Requirements
+
+- Python 3.12+
+- Django 5.2+
+- Celery 5.4+ or celery-asyncio 6.0+
+
+## License
+
+MIT

django_celeryx-0.1.0a1/django_celeryx/__init__.py

@@ -0,0 +1,10 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("django-celeryx")
+except PackageNotFoundError:
+    __version__ = "0.0.0+unknown"
+
+__all__ = [
+    "__version__",
+]

django_celeryx-0.1.0a1/django_celeryx/admin/__init__.py

@@ -0,0 +1 @@
+"""Admin interface for Celery monitoring and management."""

django_celeryx-0.1.0a1/django_celeryx/admin/admin.py

@@ -0,0 +1,331 @@
+"""Django admin classes for Celery monitoring and management."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from django.contrib import admin, messages
+from django.contrib.admin.utils import unquote
+from django.core.exceptions import PermissionDenied
+from django.urls import path
+from django.utils.translation import gettext_lazy as _
+
+from .models import Dashboard, Queue, RegisteredTask, Task, Worker
+from .queryset import (
+    QueueAdminMixin,
+    RegisteredTaskAdminMixin,
+    TaskAdminMixin,
+    WorkerAdminMixin,
+)
+
+if TYPE_CHECKING:
+    from django.http import HttpRequest, HttpResponse
+
+    _TaskBase = admin.ModelAdmin[Task]
+    _WorkerBase = admin.ModelAdmin[Worker]
+    _QueueBase = admin.ModelAdmin[Queue]
+    _RegisteredTaskBase = admin.ModelAdmin[RegisteredTask]
+else:
+    _TaskBase = admin.ModelAdmin
+    _WorkerBase = admin.ModelAdmin
+    _QueueBase = admin.ModelAdmin
+    _RegisteredTaskBase = admin.ModelAdmin
+
+
+class LiveUpdateMixin:
+    """Mixin that adds htmx live update toggle to changelist views."""
+
+    change_list_template = "admin/django_celeryx/change_list.html"
+
+    def changelist_view(
+        self,
+        request: HttpRequest,
+        extra_context: dict[str, Any] | None = None,
+    ) -> HttpResponse:
+        from django_celeryx.settings import celeryx_settings
+
+        extra_context = extra_context or {}
+
+        live = request.GET.get("live") == "on"
+        extra_context["live"] = live
+        extra_context["refresh_interval"] = celeryx_settings.AUTO_REFRESH_INTERVAL
+
+        params = request.GET.copy()
+        if live:
+            params.pop("live", None)
+        else:
+            params["live"] = "on"
+        toggle_qs = params.urlencode()
+        extra_context["live_toggle_url"] = f"?{toggle_qs}" if toggle_qs else "?"
+        extra_context["live_url"] = request.get_full_path()
+
+        # Strip 'live' from request.GET so ChangeList doesn't treat it as a filter.
+        # Also update QUERY_STRING so get_full_path() stays consistent.
+        if "live" in request.GET:
+            request.GET = request.GET.copy()  # type: ignore[assignment]
+            request.GET.pop("live")  # type: ignore[misc]
+            request.META["QUERY_STRING"] = request.GET.urlencode()
+
+        return super().changelist_view(request, extra_context)  # type: ignore[misc]
+
+
+@admin.register(Task)
+class TaskAdmin(LiveUpdateMixin, TaskAdminMixin, _TaskBase):  # type: ignore[misc]
+    """Admin for Celery tasks."""
+
+    change_list_template = "admin/django_celeryx/task/change_list.html"  # type: ignore[misc]
+    actions = ["revoke_selected", "terminate_selected"]  # noqa: RUF012
+
+    def has_add_permission(self, request: HttpRequest) -> bool:
+        return False
+
+    def has_delete_permission(self, request: HttpRequest, obj: Task | None = None) -> bool:
+        return False
+
+    def get_urls(self) -> list:
+        urls = super().get_urls()
+        custom_urls = [
+            path(
+                "apply/",
+                self.admin_site.admin_view(self._apply_task_view),
+                name="django_celeryx_task_apply",
+            ),
+            path(
+                "<path:object_id>/change/",
+                self.admin_site.admin_view(self.change_view),
+                name="django_celeryx_task_change",
+            ),
+        ]
+        return custom_urls + urls
+
+    def _apply_task_view(self, request: HttpRequest) -> HttpResponse:
+        from .views.apply_task import apply_task_view
+
+        return apply_task_view(request)
+
+    def change_view(
+        self,
+        request: HttpRequest,
+        object_id: str,
+        form_url: str = "",
+        extra_context: dict[str, Any] | None = None,
+    ) -> HttpResponse:
+        if not self.has_view_or_change_permission(request):
+            raise PermissionDenied
+
+        from .views.task_detail import task_detail_view
+
+        return task_detail_view(request, unquote(object_id))
+
+    @admin.action(description=_("Revoke selected tasks"))
+    def revoke_selected(self, request: HttpRequest, queryset: Any) -> None:
+        from django_celeryx.control.tasks import revoke_task
+
+        count = 0
+        for task in queryset:
+            try:
+                revoke_task(task.uuid)
+                count += 1
+            except Exception as exc:
+                messages.error(request, f"Failed to revoke {task.uuid[:8]}: {exc}")
+        if count:
+            messages.success(request, f"Revoked {count} task(s).")
+
+    @admin.action(description=_("Terminate selected tasks"))
+    def terminate_selected(self, request: HttpRequest, queryset: Any) -> None:
+        from django_celeryx.control.tasks import revoke_task
+
+        count = 0
+        for task in queryset:
+            try:
+                revoke_task(task.uuid, terminate=True)
+                count += 1
+            except Exception as exc:
+                messages.error(request, f"Failed to terminate {task.uuid[:8]}: {exc}")
+        if count:
+            messages.success(request, f"Terminated {count} task(s).")
+
+
+@admin.register(Worker)
+class WorkerAdmin(LiveUpdateMixin, WorkerAdminMixin, _WorkerBase):  # type: ignore[misc]
+    """Admin for Celery workers."""
+
+    change_list_template = "admin/django_celeryx/worker/change_list.html"  # type: ignore[misc]
+
+    def has_add_permission(self, request: HttpRequest) -> bool:
+        return False
+
+    def has_delete_permission(self, request: HttpRequest, obj: Worker | None = None) -> bool:
+        return False
+
+    def get_urls(self) -> list:
+        urls = super().get_urls()
+        custom_urls = [
+            path(
+                "<path:object_id>/change/",
+                self.admin_site.admin_view(self.change_view),
+                name="django_celeryx_worker_change",
+            ),
+        ]
+        return custom_urls + urls
+
+    def change_view(
+        self,
+        request: HttpRequest,
+        object_id: str,
+        form_url: str = "",
+        extra_context: dict[str, Any] | None = None,
+    ) -> HttpResponse:
+        if not self.has_view_or_change_permission(request):
+            raise PermissionDenied
+
+        from .views.worker_detail import worker_detail_view
+
+        return worker_detail_view(request, unquote(object_id))
+
+
+@admin.register(Queue)
+class QueueAdmin(LiveUpdateMixin, QueueAdminMixin, _QueueBase):  # type: ignore[misc]
+    """Admin for Celery queues."""
+
+    def has_add_permission(self, request: HttpRequest) -> bool:
+        return False
+
+    def has_delete_permission(self, request: HttpRequest, obj: Queue | None = None) -> bool:
+        return False
+
+
+@admin.register(RegisteredTask)
+class RegisteredTaskAdmin(RegisteredTaskAdminMixin, _RegisteredTaskBase):  # type: ignore[misc]
+    """Admin for registered Celery task types."""
+
+    def has_add_permission(self, request: HttpRequest) -> bool:
+        return False
+
+    def has_delete_permission(self, request: HttpRequest, obj: RegisteredTask | None = None) -> bool:
+        return False
+
+
+class DashboardPeriodFilter(admin.SimpleListFilter):
+    title = _("time period")
+    parameter_name = "period"
+
+    def lookups(self, request: HttpRequest, model_admin: admin.ModelAdmin) -> list[tuple[str, str]]:
+        return [("today", str(_("Today"))), ("7d", str(_("Last 7 days"))), ("30d", str(_("Last 30 days")))]
+
+    def queryset(self, request: HttpRequest, queryset: Any) -> Any:
+        deltas = {"today": 1, "7d": 7, "30d": 30}
+        value = self.value()
+        if value is not None and value in deltas:
+            import time
+
+            cutoff = time.time() - deltas[value] * 86400
+            return queryset.filter(updated_at__gte=cutoff)
+        return queryset
+
+
+class DashboardQueueFilter(admin.SimpleListFilter):
+    title = _("queue")
+    parameter_name = "queue"
+
+    def lookups(self, request: HttpRequest, model_admin: admin.ModelAdmin) -> list[tuple[str, str]]:
+        from django_celeryx.db_models import TaskState
+        from django_celeryx.settings import get_db_alias
+
+        try:
+            return [
+                (q, q)
+                for q in sorted(
+                    TaskState.objects.using(get_db_alias())
+                    .exclude(routing_key="")
+                    .values_list("routing_key", flat=True)
+                    .distinct()
+                )
+            ]
+        except Exception:
+            return []
+
+    def queryset(self, request: HttpRequest, queryset: Any) -> Any:
+        if self.value():
+            return queryset.filter(routing_key=self.value())
+        return queryset
+
+
+class DashboardWorkerFilter(admin.SimpleListFilter):
+    title = _("worker")
+    parameter_name = "worker"
+
+    def lookups(self, request: HttpRequest, model_admin: admin.ModelAdmin) -> list[tuple[str, str]]:
+        from django_celeryx.db_models import TaskState
+        from django_celeryx.settings import get_db_alias
+
+        try:
+            return [
+                (w, w)
+                for w in sorted(
+                    TaskState.objects.using(get_db_alias())
+                    .exclude(worker="")
+                    .values_list("worker", flat=True)
+                    .distinct()
+                )
+            ]
+        except Exception:
+            return []
+
+    def queryset(self, request: HttpRequest, queryset: Any) -> Any:
+        if self.value():
+            return queryset.filter(worker=self.value())
+        return queryset
+
+
+if TYPE_CHECKING:
+    _DashboardBase = admin.ModelAdmin[Dashboard]
+else:
+    _DashboardBase = admin.ModelAdmin
+
+
+@admin.register(Dashboard)
+class DashboardAdmin(LiveUpdateMixin, _DashboardBase):
+    """Dashboard view using native Django admin filters."""
+
+    change_list_template = "admin/django_celeryx/dashboard/change_list.html"  # type: ignore[misc]
+    list_filter = [DashboardPeriodFilter, DashboardQueueFilter, DashboardWorkerFilter]  # noqa: RUF012
+    show_facets = admin.ShowFacets.NEVER
+
+    def has_add_permission(self, request: HttpRequest) -> bool:
+        return False
+
+    def has_delete_permission(self, request: HttpRequest, obj: Dashboard | None = None) -> bool:
+        return False
+
+    def has_change_permission(self, request: HttpRequest, obj: Dashboard | None = None) -> bool:
+        return False
+
+    def get_queryset(self, request: HttpRequest) -> Any:
+        # Return empty qs so ChangeList never queries the unmanaged Dashboard table.
+        # Actual data is computed manually in changelist_view.
+        from django_celeryx.db_models import TaskState
+
+        return TaskState.objects.none()
+
+    def changelist_view(
+        self,
+        request: HttpRequest,
+        extra_context: dict[str, Any] | None = None,
+    ) -> HttpResponse:
+        extra_context = extra_context or {}
+
+        # Build a filtered queryset by applying our filters to TaskState
+        from django_celeryx.db_models import TaskState as _TaskState
+        from django_celeryx.settings import get_db_alias
+
+        from .views.dashboard import compute_dashboard_context
+
+        qs = _TaskState.objects.using(get_db_alias()).all()
+        for f_cls in self.list_filter:
+            f = f_cls(request, request.GET.copy(), _TaskState, self)  # type: ignore[operator]
+            qs = f.queryset(request, qs) or qs
+
+        extra_context.update(compute_dashboard_context(qs, period=request.GET.get("period", "")))
+
+        return super().changelist_view(request, extra_context)