django-class-based-admin-actions 0.1.0__tar.gz

django_class_based_admin_actions-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,31 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

django_class_based_admin_actions-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+.idea/
+__pycache__/
+.pytest_cache/
+*.egg-info/
+dist/
+uv.lock

django_class_based_admin_actions-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alejandro Rebecchi
+
+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_class_based_admin_actions-0.1.0/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.5
+Name: django-class-based-admin-actions
+Version: 0.1.0
+Summary: Class-based Django admin actions: compose reusable actions from mixins, like class-based views.
+Project-URL: Homepage, https://github.com/cheverebe/class-based-admin-actions
+Project-URL: Issues, https://github.com/cheverebe/class-based-admin-actions/issues
+Author: Alejandro Rebecchi
+License-Expression: MIT
+License-File: LICENSE
+Keywords: actions,admin,class-based,django
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 5.1
+Classifier: Framework :: Django :: 5.2
+Classifier: Framework :: Django :: 6.0
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: django>=4.2
+Description-Content-Type: text/markdown
+
+# django-class-based-admin-actions
+
+Django admin actions written as classes and composed from mixins, the way class-based views are.
+`AdminAction.as_action()` is to admin actions what `View.as_view()` is to views.
+
+```python
+INSTALLED_APPS = [..., "class_based_admin_actions"]   # needed for the confirmation template
+```
+
+```python
+from class_based_admin_actions import (
+    ClassActionsMixin, ConfirmationMixin, CsvExportAction, FormUpdateAction, UpdateAction,
+)
+
+class PublishAction(UpdateAction):
+    description = "Publish selected %(verbose_name_plural)s"
+    update_fields = {"status": "published"}
+    success_message = "Published %(count)d %(name)s."
+    allowed_permissions = ("change",)
+
+class ArchiveAction(ConfirmationMixin, PublishAction):      # reuse + ask first
+    update_fields = {"status": "archived"}
+
+class SetStatusAction(FormUpdateAction):                    # ask for values in a form
+    form_class = StatusForm
+
+@admin.register(Article)
+class ArticleAdmin(ClassActionsMixin, admin.ModelAdmin):
+    actions = [PublishAction, ArchiveAction, SetStatusAction,
+               CsvExportAction.as_action(fields=["title", "status"])]
+```
+
+Classes can go straight in `actions` with `ClassActionsMixin`; without it use `X.as_action(**overrides)`
+(also fine for `admin.site.add_action`).
+
+## Hierarchy
+
+```
+AdminAction                       setup / dispatch / has_permission / handle / run / perform / finish
+├─ BulkAction = QuerysetMixin + SuccessMessageMixin + AtomicMixin + AdminAction
+│   ├─ ObjectAction               process_object(obj), skip_errors, log_message
+│   └─ UpdateAction               update_fields -> queryset.update()
+│       └─ FormUpdateAction       FormMixin + UpdateAction
+└─ CsvExportAction                fields, filename, CSV-injection safe
+```
+
+| Mixin | Adds |
+|---|---|
+| `QuerysetMixin` | `select_related`, `prefetch_related`, `max_objects` |
+| `SuccessMessageMixin` | `success_message` with `%(count)d`, `%(name)s` |
+| `AtomicMixin` | transaction around the run, `using` |
+| `TemplateResponseMixin` | admin-context intermediate page |
+| `ConfirmationMixin` | confirm page before `perform()` |
+| `FormMixin` | form on the confirm page (`form_class`, `initial`, `form_valid/invalid`) |
+
+All hooks call `super()`, so mixins combine in any order; put them before the base class.
+Write your own by overriding a hook (`check_preconditions`, `get_queryset`, `run`, `on_success`, ...).
+Raise `ActionError("msg")` anywhere to abort with an error message (and roll back under `AtomicMixin`).
+
+## Notes
+
+- Permissions: `allowed_permissions` is Django's mechanism (action hidden unless *any* listed
+  `has_<perm>_permission` passes) and is re-checked on dispatch. Override `has_permission()` for more.
+- `description` is `%`-formatted by Django with `verbose_name`/`verbose_name_plural`; escape literal `%` as `%%`.
+- The confirmation page posts back to the changelist; the form must not define fields named
+  `action`, `select_across` or `_selected_action`.
+- `UpdateAction` uses `QuerySet.update()` (no `save()`, signals, or `auto_now`); use `ObjectAction` if you need them.
+
+## Development
+
+```
+uv pip install -e . pytest pytest-django && pytest
+```

django_class_based_admin_actions-0.1.0/README.md

@@ -0,0 +1,73 @@
+# django-class-based-admin-actions
+
+Django admin actions written as classes and composed from mixins, the way class-based views are.
+`AdminAction.as_action()` is to admin actions what `View.as_view()` is to views.
+
+```python
+INSTALLED_APPS = [..., "class_based_admin_actions"]   # needed for the confirmation template
+```
+
+```python
+from class_based_admin_actions import (
+    ClassActionsMixin, ConfirmationMixin, CsvExportAction, FormUpdateAction, UpdateAction,
+)
+
+class PublishAction(UpdateAction):
+    description = "Publish selected %(verbose_name_plural)s"
+    update_fields = {"status": "published"}
+    success_message = "Published %(count)d %(name)s."
+    allowed_permissions = ("change",)
+
+class ArchiveAction(ConfirmationMixin, PublishAction):      # reuse + ask first
+    update_fields = {"status": "archived"}
+
+class SetStatusAction(FormUpdateAction):                    # ask for values in a form
+    form_class = StatusForm
+
+@admin.register(Article)
+class ArticleAdmin(ClassActionsMixin, admin.ModelAdmin):
+    actions = [PublishAction, ArchiveAction, SetStatusAction,
+               CsvExportAction.as_action(fields=["title", "status"])]
+```
+
+Classes can go straight in `actions` with `ClassActionsMixin`; without it use `X.as_action(**overrides)`
+(also fine for `admin.site.add_action`).
+
+## Hierarchy
+
+```
+AdminAction                       setup / dispatch / has_permission / handle / run / perform / finish
+├─ BulkAction = QuerysetMixin + SuccessMessageMixin + AtomicMixin + AdminAction
+│   ├─ ObjectAction               process_object(obj), skip_errors, log_message
+│   └─ UpdateAction               update_fields -> queryset.update()
+│       └─ FormUpdateAction       FormMixin + UpdateAction
+└─ CsvExportAction                fields, filename, CSV-injection safe
+```
+
+| Mixin | Adds |
+|---|---|
+| `QuerysetMixin` | `select_related`, `prefetch_related`, `max_objects` |
+| `SuccessMessageMixin` | `success_message` with `%(count)d`, `%(name)s` |
+| `AtomicMixin` | transaction around the run, `using` |
+| `TemplateResponseMixin` | admin-context intermediate page |
+| `ConfirmationMixin` | confirm page before `perform()` |
+| `FormMixin` | form on the confirm page (`form_class`, `initial`, `form_valid/invalid`) |
+
+All hooks call `super()`, so mixins combine in any order; put them before the base class.
+Write your own by overriding a hook (`check_preconditions`, `get_queryset`, `run`, `on_success`, ...).
+Raise `ActionError("msg")` anywhere to abort with an error message (and roll back under `AtomicMixin`).
+
+## Notes
+
+- Permissions: `allowed_permissions` is Django's mechanism (action hidden unless *any* listed
+  `has_<perm>_permission` passes) and is re-checked on dispatch. Override `has_permission()` for more.
+- `description` is `%`-formatted by Django with `verbose_name`/`verbose_name_plural`; escape literal `%` as `%%`.
+- The confirmation page posts back to the changelist; the form must not define fields named
+  `action`, `select_across` or `_selected_action`.
+- `UpdateAction` uses `QuerySet.update()` (no `save()`, signals, or `auto_now`); use `ObjectAction` if you need them.
+
+## Development
+
+```
+uv pip install -e . pytest pytest-django && pytest
+```

django_class_based_admin_actions-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "django-class-based-admin-actions"
+version = "0.1.0"
+description = "Class-based Django admin actions: compose reusable actions from mixins, like class-based views."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Alejandro Rebecchi" }]
+keywords = ["django", "admin", "actions", "class-based"]
+dependencies = ["django>=4.2"]
+classifiers = [
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Framework :: Django",
+    "Framework :: Django :: 4.2",
+    "Framework :: Django :: 5.0",
+    "Framework :: Django :: 5.1",
+    "Framework :: Django :: 5.2",
+    "Framework :: Django :: 6.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/cheverebe/class-based-admin-actions"
+Issues = "https://github.com/cheverebe/class-based-admin-actions/issues"
+
+[dependency-groups]
+dev = ["pytest", "pytest-django"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/class_based_admin_actions"]
+
+[tool.pytest.ini_options]
+DJANGO_SETTINGS_MODULE = "tests.settings"
+pythonpath = [".", "src"]

django_class_based_admin_actions-0.1.0/src/class_based_admin_actions/__init__.py

@@ -0,0 +1,17 @@
+from .admin import ClassActionsMixin
+from .base import ActionError, AdminAction
+from .generic import BulkAction, CsvExportAction, FormUpdateAction, ObjectAction, UpdateAction
+from .mixins import (
+    AtomicMixin,
+    ConfirmationMixin,
+    FormMixin,
+    QuerysetMixin,
+    SuccessMessageMixin,
+    TemplateResponseMixin,
+)
+
+__all__ = [
+    "ActionError", "AdminAction", "AtomicMixin", "BulkAction", "ClassActionsMixin",
+    "ConfirmationMixin", "CsvExportAction", "FormMixin", "FormUpdateAction", "ObjectAction",
+    "QuerysetMixin", "SuccessMessageMixin", "TemplateResponseMixin", "UpdateAction",
+]

django_class_based_admin_actions-0.1.0/src/class_based_admin_actions/admin.py

@@ -0,0 +1,16 @@
+from .base import AdminAction
+
+
+class ClassActionsMixin:
+    """``ModelAdmin`` mixin allowing action *classes* directly in ``actions``::
+
+        class ArticleAdmin(ClassActionsMixin, admin.ModelAdmin):
+            actions = [PublishAction, ArchiveAction.as_action(name="archive_now")]
+    """
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.actions = [
+            a.as_action() if isinstance(a, type) and issubclass(a, AdminAction) else a
+            for a in self.actions or ()
+        ]

django_class_based_admin_actions-0.1.0/src/class_based_admin_actions/base.py

@@ -0,0 +1,163 @@
+"""The core of the plugin: ``AdminAction``, the analogue of ``django.views.generic.View``.
+
+A Django admin action is a plain callable ``(modeladmin, request, queryset)`` with a few
+attributes (``__name__``, ``short_description``, ``allowed_permissions``).
+``AdminAction.as_action()`` builds such a callable from a class, exactly like
+``View.as_view()`` builds a view function. A new instance is created per call, so
+instance state is never shared between requests.
+
+Behaviour is layered with cooperative mixins: every hook calls ``super()``.
+"""
+import re
+
+from django.contrib import messages
+from django.core.exceptions import PermissionDenied
+from django.http import HttpResponseRedirect
+from django.http.response import HttpResponseBase
+from django.utils.text import capfirst
+
+_SNAKE_RE = re.compile(r"(?<=[a-z0-9])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])")
+
+
+def camel_to_snake(name):
+    return _SNAKE_RE.sub("_", name).lower()
+
+
+class ActionError(Exception):
+    """Raise anywhere inside an action to abort it.
+
+    The message is shown to the user as an error and the changelist is re-displayed.
+    Inside ``AtomicMixin`` the transaction is rolled back.
+    """
+
+
+class AdminAction:
+    """Minimal action. Subclasses implement ``perform()``.
+
+    Request lifecycle::
+
+        as_action()() -> setup() -> dispatch()
+            dispatch: has_permission() -> check_preconditions() -> handle()
+            handle:   run() -> perform() -> finish() -> on_success() -> get_success_response()
+
+    ``ActionError`` raised in any of these is reported through ``handle_error()``.
+    """
+
+    name = None
+    description = None
+    #: Passed to Django, which hides the action unless ``modeladmin.has_<perm>_permission``
+    #: passes for at least one entry (Django's rule). Enforced again in ``has_permission()``.
+    allowed_permissions = ()
+
+    def __init__(self, **kwargs):
+        for key, value in kwargs.items():
+            setattr(self, key, value)
+
+    # -- construction ---------------------------------------------------------------
+
+    @classmethod
+    def as_action(cls, **initkwargs):
+        """Return a callable usable in ``ModelAdmin.actions``.
+
+        ``initkwargs`` override class attributes, e.g.
+        ``PublishAction.as_action(update_fields={"status": "live"}, name="go_live")``.
+        """
+        for key in initkwargs:
+            if key in ("modeladmin", "request", "queryset"):
+                raise TypeError(f"{cls.__name__}.as_action() received reserved argument '{key}'.")
+            if not hasattr(cls, key):
+                raise TypeError(
+                    f"{cls.__name__}.as_action() received an invalid keyword '{key}': "
+                    "it must be an attribute of the class."
+                )
+
+        def action(modeladmin, request, queryset):
+            self = cls(**initkwargs)
+            self.setup(modeladmin, request, queryset)
+            return self.dispatch()
+
+        meta = cls(**initkwargs)
+        action.__name__ = meta.get_name()
+        action.__qualname__ = f"{cls.__qualname__}.as_action.<locals>.action"
+        action.__doc__ = cls.__doc__
+        action.__module__ = cls.__module__
+        action.short_description = meta.get_description()
+        if meta.allowed_permissions:  # Django hides actions whose (even empty) tuple has no match
+            action.allowed_permissions = tuple(meta.allowed_permissions)
+        action.action_class = cls
+        action.initkwargs = initkwargs
+        return action
+
+    def get_name(self):
+        return self.name or camel_to_snake(type(self).__name__)
+
+    def get_description(self):
+        if self.description is not None:
+            return self.description
+        return capfirst(self.get_name().replace("_", " "))
+
+    def setup(self, modeladmin, request, queryset):
+        self.modeladmin = modeladmin
+        self.request = request
+        self.queryset = queryset
+        self.model = modeladmin.model
+        self.opts = modeladmin.opts
+
+    # -- request lifecycle ----------------------------------------------------------
+
+    def dispatch(self):
+        try:
+            if not self.has_permission():
+                return self.handle_no_permission()
+            self.check_preconditions()
+            return self.handle()
+        except ActionError as exc:
+            return self.handle_error(exc)
+
+    def has_permission(self):
+        return not self.allowed_permissions or any(
+            getattr(self.modeladmin, f"has_{perm}_permission")(self.request)
+            for perm in self.allowed_permissions
+        )
+
+    def handle_no_permission(self):
+        raise PermissionDenied
+
+    def check_preconditions(self):
+        """Hook for validations that must run before anything else (raise ``ActionError``)."""
+
+    def get_queryset(self):
+        return self.queryset
+
+    def handle(self):
+        return self.finish(self.run())
+
+    def run(self):
+        """Executes ``perform()``; wrappers such as ``AtomicMixin`` hook here."""
+        return self.perform()
+
+    def perform(self):
+        raise NotImplementedError(f"{type(self).__name__} must implement perform().")
+
+    def finish(self, result):
+        if isinstance(result, HttpResponseBase):
+            return result
+        self.on_success(result)
+        return self.get_success_response()
+
+    def on_success(self, result):
+        """Hook run after ``perform()`` returned a non-response result."""
+
+    def get_success_url(self):
+        return None
+
+    def get_success_response(self):
+        url = self.get_success_url()
+        return HttpResponseRedirect(url) if url else None  # None: stay on the changelist
+
+    def handle_error(self, exc):
+        self.message_user(str(exc) or "The action could not be completed.", messages.ERROR)
+        return None
+
+    def message_user(self, message, level=messages.SUCCESS):
+        self.modeladmin.message_user(self.request, message, level)

django_class_based_admin_actions-0.1.0/src/class_based_admin_actions/generic.py

@@ -0,0 +1,137 @@
+"""Ready-to-subclass actions, the analogue of ``django.views.generic``.
+
+    AdminAction
+      └─ BulkAction (QuerysetMixin, SuccessMessageMixin, AtomicMixin)
+           ├─ ObjectAction        process_object(obj) for each selected object
+           ├─ UpdateAction        queryset.update(**update_fields)
+           │    └─ FormUpdateAction   (+ FormMixin) update with values from a form
+           └─ ...
+      └─ CsvExportAction (QuerysetMixin)
+
+Add ``ConfirmationMixin`` / ``FormMixin`` in front of any of them to ask the user first.
+"""
+import csv
+
+from django.contrib import messages
+from django.db import transaction
+
+from django.core.exceptions import ImproperlyConfigured
+from django.http import HttpResponse
+from django.utils.http import content_disposition_header
+
+from .base import ActionError, AdminAction
+from .mixins import AtomicMixin, FormMixin, QuerysetMixin, SuccessMessageMixin
+
+
+class BulkAction(QuerysetMixin, SuccessMessageMixin, AtomicMixin, AdminAction):
+    """Batteries-included base for actions that modify the selected rows."""
+
+
+class ObjectAction(BulkAction):
+    """Calls ``process_object(obj)`` for every selected object.
+
+    With ``skip_errors`` an ``ActionError`` only skips that object (its own writes are rolled
+    back to a savepoint) and is reported as a warning; otherwise the whole run is aborted.
+    ``log_message`` adds a ``LogEntry`` (admin history) per processed object.
+    """
+
+    skip_errors = False
+    log_message = None
+
+    def process_object(self, obj):
+        raise NotImplementedError(f"{type(self).__name__} must implement process_object().")
+
+    def perform(self):
+        count, self.failures = 0, []
+        for obj in self.get_queryset().iterator(chunk_size=self.iterator_chunk_size):
+            label = str(obj)  # before process_object() mutates it
+            try:
+                if self.skip_errors:
+                    with transaction.atomic(using=self.get_using()):
+                        self.process_object(obj)
+                else:
+                    self.process_object(obj)
+            except ActionError as exc:
+                if not self.skip_errors:
+                    raise
+                self.failures.append((label, exc))
+                continue
+            if self.log_message:
+                self.modeladmin.log_change(self.request, obj, self.log_message)
+            count += 1
+        return count
+
+    def on_success(self, result):
+        super().on_success(result)
+        for label, exc in self.failures:
+            self.message_user(f"{label}: {exc}", level=messages.WARNING)
+
+
+class UpdateAction(BulkAction):
+    """Sets ``update_fields`` on the selected rows with a single ``UPDATE`` query.
+
+    Note ``QuerySet.update()`` skips ``save()``, signals and ``auto_now`` fields. Use
+    ``ObjectAction`` when those matter.
+    """
+
+    update_fields = None
+
+    def get_update_fields(self):
+        if not self.update_fields:
+            raise ImproperlyConfigured(f"{type(self).__name__} requires update_fields.")
+        return dict(self.update_fields)
+
+    def perform(self):
+        return self.get_queryset().update(**self.get_update_fields())
+
+
+class FormUpdateAction(FormMixin, UpdateAction):
+    """Asks for values in a form, then updates the selection with them.
+
+    By default every cleaned value is written; narrow it with ``update_fields`` (a list of
+    form field names) or override ``get_update_fields()``.
+    """
+
+    update_fields = None
+
+    def get_update_fields(self):
+        data = self.form.cleaned_data
+        return {k: data[k] for k in (self.update_fields or data)}
+
+
+class CsvExportAction(QuerysetMixin, AdminAction):
+    """Downloads the selection as CSV. ``fields`` may name model fields, attributes or
+    methods (callables are called). String cells that start with a formula character are
+    prefixed with ``'`` (``escape_formulas``) to prevent CSV injection in spreadsheets."""
+
+    allowed_permissions = ("view",)
+    fields = None
+    filename = None
+    header = True
+    escape_formulas = True
+
+    def get_fields(self):
+        return self.fields or [f.name for f in self.opts.concrete_fields]
+
+    def get_filename(self):
+        return self.filename or f"{self.opts.model_name}.csv"
+
+    def get_value(self, obj, field):
+        value = getattr(obj, field)
+        if callable(value):
+            value = value()
+        value = "" if value is None else value
+        if self.escape_formulas and isinstance(value, str) and value[:1] in ("=", "+", "-", "@", "\t", "\r"):
+            value = "'" + value
+        return value
+
+    def perform(self):
+        response = HttpResponse(content_type="text/csv; charset=utf-8")
+        response.headers["Content-Disposition"] = content_disposition_header(True, self.get_filename())
+        fields = self.get_fields()
+        writer = csv.writer(response)
+        if self.header:
+            writer.writerow(fields)
+        for obj in self.get_queryset().iterator(chunk_size=self.iterator_chunk_size):
+            writer.writerow([self.get_value(obj, f) for f in fields])
+        return response

django_class_based_admin_actions-0.1.0/src/class_based_admin_actions/mixins.py

@@ -0,0 +1,200 @@
+"""Reusable behaviours. Combine them with ``AdminAction`` (mixins first), like view mixins."""
+from django.contrib import messages
+from django.contrib.admin import helpers
+from django.contrib.admin.utils import model_format_dict, model_ngettext
+from django.core.exceptions import ImproperlyConfigured
+from django.db import router, transaction
+from django.template.response import TemplateResponse
+from django.utils.translation import gettext_lazy as _
+
+from .base import ActionError
+
+CONFIRM_FIELD = "_cba_confirm"
+
+
+class QuerysetMixin:
+    """Refines the selected queryset and guards against huge selections."""
+
+    select_related = None  # True, or a list of field names
+    prefetch_related = ()
+    max_objects = None
+    iterator_chunk_size = 2000
+
+    def get_queryset(self):
+        queryset = super().get_queryset()
+        if self.select_related is True:
+            queryset = queryset.select_related()
+        elif self.select_related:
+            queryset = queryset.select_related(*self.select_related)
+        if self.prefetch_related:
+            queryset = queryset.prefetch_related(*self.prefetch_related)
+        return queryset
+
+    def check_preconditions(self):
+        super().check_preconditions()
+        if self.max_objects is not None:
+            count = self.queryset.count()
+            if count > self.max_objects:
+                raise ActionError(
+                    _("This action can process at most %(max)d items at once; %(count)d were selected.")
+                    % {"max": self.max_objects, "count": count}
+                )
+
+
+class SuccessMessageMixin:
+    """Flashes ``success_message`` after a successful run.
+
+    The message may use ``%(count)d`` and ``%(name)s`` (the singular or plural verbose name
+    matching the count). ``count`` is the integer returned by ``perform()``, if any.
+    """
+
+    success_message = None
+
+    def on_success(self, result):
+        super().on_success(result)
+        message = self.get_success_message(result)
+        if message:
+            self.message_user(message, messages.SUCCESS)
+
+    def get_success_message(self, result):
+        if not self.success_message:
+            return None
+        count = result if isinstance(result, int) and not isinstance(result, bool) else None
+        if count is None:
+            count = self.get_queryset().count()
+        return self.success_message % {"count": count, "name": model_ngettext(self.opts, count)}
+
+
+class AtomicMixin:
+    """Runs the action in a transaction; any exception rolls everything back."""
+
+    using = None
+
+    def get_using(self):
+        return self.using or router.db_for_write(self.model)
+
+    def run(self):
+        with transaction.atomic(using=self.get_using()):
+            return super().run()
+
+
+class TemplateResponseMixin:
+    """Renders an intermediate admin page with the usual admin context."""
+
+    template_name = None
+    title = None
+    extra_context = None
+    preview_limit = 50
+
+    def get_template_names(self):
+        if self.template_name is None:
+            raise ImproperlyConfigured(f"{type(self).__name__} requires template_name.")
+        return [self.template_name]
+
+    def get_title(self):
+        return self.title or self.get_description() % model_format_dict(self.opts)
+
+    def get_context_data(self, **kwargs):
+        queryset = self.get_queryset()
+        count = queryset.count()
+        shown = list(queryset[: self.preview_limit])
+        post = self.request.POST
+        context = {
+            **self.modeladmin.admin_site.each_context(self.request),
+            "title": self.get_title(),
+            "subtitle": None,
+            "opts": self.opts,
+            "media": self.modeladmin.media,
+            "action_name": self.get_name(),
+            "objects": shown,
+            "object_count": count,
+            "hidden_count": max(count - len(shown), 0),
+            "selected_values": post.getlist(helpers.ACTION_CHECKBOX_NAME),
+            "select_across": post.get("select_across", "0"),
+            "action_checkbox_name": helpers.ACTION_CHECKBOX_NAME,
+            "confirm_field": CONFIRM_FIELD,
+            **(self.extra_context or {}),
+            **kwargs,
+        }
+        return context
+
+    def render_to_response(self, context):
+        self.request.current_app = self.modeladmin.admin_site.name
+        return TemplateResponse(self.request, self.get_template_names(), context)
+
+
+class ConfirmationMixin(TemplateResponseMixin):
+    """Asks for confirmation on an intermediate page before running the action.
+
+    The page re-submits the same selection to the changelist with ``CONFIRM_FIELD`` set; the
+    second request is the one that reaches ``perform()``. Subclasses hook the two phases
+    through ``unconfirmed()`` and ``confirmed()``.
+    """
+
+    template_name = "class_based_admin_actions/confirmation.html"
+    confirm_message = _("Are you sure you want to apply this action to the selected items?")
+    confirm_button = _("Confirm")
+
+    def is_confirmed(self):
+        return CONFIRM_FIELD in self.request.POST
+
+    def handle(self):
+        if self.is_confirmed():
+            return self.confirmed()
+        return self.unconfirmed()
+
+    def unconfirmed(self):
+        return self.render_to_response(self.get_context_data())
+
+    def confirmed(self):
+        return super().handle()
+
+    def get_context_data(self, **kwargs):
+        return super().get_context_data(
+            confirm_message=self.confirm_message, confirm_button=self.confirm_button, **kwargs
+        )
+
+
+class FormMixin(ConfirmationMixin):
+    """Like ``django.views.generic.edit.FormMixin``: collects input on the confirmation page.
+
+    The validated form is available as ``self.form`` once ``perform()`` runs.
+    """
+
+    form_class = None
+    initial = None
+    prefix = None
+
+    def get_form_class(self):
+        if self.form_class is None:
+            raise ImproperlyConfigured(f"{type(self).__name__} requires form_class.")
+        return self.form_class
+
+    def get_form_kwargs(self):
+        kwargs = {"initial": dict(self.initial or {}), "prefix": self.prefix}
+        if self.is_confirmed():
+            kwargs.update(data=self.request.POST, files=self.request.FILES)
+        return kwargs
+
+    def get_form(self):
+        return self.get_form_class()(**self.get_form_kwargs())
+
+    def unconfirmed(self):
+        self.form = self.get_form()
+        return self.render_to_response(self.get_context_data())
+
+    def confirmed(self):
+        self.form = self.get_form()
+        if self.form.is_valid():
+            return self.form_valid(self.form)
+        return self.form_invalid(self.form)
+
+    def form_valid(self, form):
+        return super().confirmed()
+
+    def form_invalid(self, form):
+        return self.render_to_response(self.get_context_data())
+
+    def get_context_data(self, **kwargs):
+        kwargs.setdefault("media", self.modeladmin.media + self.form.media)
+        return super().get_context_data(form=self.form, **kwargs)

django_class_based_admin_actions-0.1.0/src/class_based_admin_actions/templates/class_based_admin_actions/confirmation.html

@@ -0,0 +1,30 @@
+{% extends "admin/base_site.html" %}
+{% load i18n admin_urls %}
+
+{% block extrahead %}{{ block.super }}{{ media }}{% endblock %}
+
+{% block breadcrumbs %}
+<div class="breadcrumbs">
+<a href="{% url 'admin:index' %}">{% translate 'Home' %}</a>
+&rsaquo; <a href="{% url 'admin:app_list' app_label=opts.app_label %}">{{ opts.app_config.verbose_name }}</a>
+&rsaquo; <a href="{% url opts|admin_urlname:'changelist' %}">{{ opts.verbose_name_plural|capfirst }}</a>
+&rsaquo; {{ title }}
+</div>
+{% endblock %}
+
+{% block content %}
+<form method="post">{% csrf_token %}
+  <p>{{ confirm_message }}</p>
+  <ul>
+    {% for obj in objects %}<li>{{ obj }}</li>{% endfor %}
+  </ul>
+  {% if hidden_count %}<p>{% blocktranslate with n=hidden_count %}…and {{ n }} more.{% endblocktranslate %}</p>{% endif %}
+  {% if form %}{{ form.as_p }}{% endif %}
+  {% for value in selected_values %}<input type="hidden" name="{{ action_checkbox_name }}" value="{{ value }}">{% endfor %}
+  <input type="hidden" name="action" value="{{ action_name }}">
+  <input type="hidden" name="select_across" value="{{ select_across }}">
+  <input type="hidden" name="{{ confirm_field }}" value="1">
+  <input type="submit" value="{{ confirm_button }}">
+  <a href="{% url opts|admin_urlname:'changelist' %}" class="button cancel-link">{% translate "No, take me back" %}</a>
+</form>
+{% endblock %}

django_class_based_admin_actions-0.1.0/tests/conftest.py

@@ -0,0 +1,25 @@
+import pytest
+from django.contrib.auth import get_user_model
+from django.urls import reverse
+
+from tests.testapp.models import Article
+
+
+@pytest.fixture
+def articles(db):
+    return [Article.objects.create(title=t, views=v) for t, v in [("a", 1), ("b", 500), ("=cmd", 3)]]
+
+
+@pytest.fixture
+def admin_client(client, db):
+    client.force_login(get_user_model().objects.create_superuser("root", "r@x.io", "pw"))
+    return client
+
+
+@pytest.fixture
+def run(admin_client):
+    """POST an action to the changelist like the admin dropdown does."""
+    def _run(action, objs, **extra):
+        data = {"action": action, "_selected_action": [o.pk for o in objs], **extra}
+        return admin_client.post(reverse("admin:testapp_article_changelist"), data, follow=False)
+    return _run

django_class_based_admin_actions-0.1.0/tests/settings.py

@@ -0,0 +1,30 @@
+SECRET_KEY = "test"
+DEBUG = True
+USE_TZ = True
+ROOT_URLCONF = "tests.urls"
+DEFAULT_AUTO_FIELD = "django.db.models.BigAutoField"
+DATABASES = {"default": {"ENGINE": "django.db.backends.sqlite3", "NAME": ":memory:"}}
+INSTALLED_APPS = [
+    "django.contrib.admin",
+    "django.contrib.auth",
+    "django.contrib.contenttypes",
+    "django.contrib.sessions",
+    "django.contrib.messages",
+    "class_based_admin_actions",
+    "tests.testapp",
+]
+MIDDLEWARE = [
+    "django.contrib.sessions.middleware.SessionMiddleware",
+    "django.middleware.csrf.CsrfViewMiddleware",
+    "django.contrib.auth.middleware.AuthenticationMiddleware",
+    "django.contrib.messages.middleware.MessageMiddleware",
+]
+TEMPLATES = [{
+    "BACKEND": "django.template.backends.django.DjangoTemplates",
+    "APP_DIRS": True,
+    "OPTIONS": {"context_processors": [
+        "django.template.context_processors.request",
+        "django.contrib.auth.context_processors.auth",
+        "django.contrib.messages.context_processors.messages",
+    ]},
+}]

django_class_based_admin_actions-0.1.0/tests/test_actions.py

@@ -0,0 +1,182 @@
+import csv
+import io
+
+import pytest
+from django.contrib.admin.models import LogEntry
+from django.contrib.auth import get_user_model
+from django.contrib.messages import get_messages
+from django.urls import reverse
+
+from class_based_admin_actions import AdminAction, UpdateAction
+from class_based_admin_actions.mixins import CONFIRM_FIELD
+from tests.testapp.admin import ArticleAdmin, PublishAction
+from tests.testapp.models import Article
+
+
+def messages_of(response):
+    return [str(m) for m in get_messages(response.wsgi_request)]
+
+
+def statuses():
+    return {a.title: a.status for a in Article.objects.all()}
+
+
+# -- construction -------------------------------------------------------------------
+
+
+def test_as_action_metadata():
+    action = PublishAction.as_action(name="go_live")
+    assert action.__name__ == "go_live"
+    assert action.short_description == "Publish selected %(verbose_name_plural)s"
+    assert action.allowed_permissions == ("change",)
+    assert not hasattr(AdminAction.as_action(), "allowed_permissions")
+    assert action.action_class is PublishAction
+
+
+def test_default_name_and_description():
+    class CSVExportAllAction(AdminAction):
+        pass
+
+    action = CSVExportAllAction.as_action()
+    assert action.__name__ == "csv_export_all_action"
+    assert action.short_description == "Csv export all action"
+
+
+def test_as_action_rejects_unknown_and_reserved_kwargs():
+    with pytest.raises(TypeError, match="invalid keyword"):
+        PublishAction.as_action(nope=1)
+    with pytest.raises(TypeError, match="reserved"):
+        PublishAction.as_action(request=1)
+
+
+def test_initkwargs_override_class_attributes(articles, run):
+    class Custom(PublishAction):
+        pass
+
+    assert Custom.as_action(update_fields={"status": "x"}).initkwargs == {"update_fields": {"status": "x"}}
+    assert Custom.update_fields == {"status": "published"}
+
+
+def test_class_in_actions_is_converted():
+    from django.contrib import admin
+    names = [getattr(a, "__name__", a) for a in ArticleAdmin(Article, admin.site).actions]
+    assert "publish_action" in names and "archive_action" in names
+
+
+def test_lazy_description_formatted_by_django(admin_client, articles):
+    html = admin_client.get(reverse("admin:testapp_article_changelist")).content.decode()
+    assert "Publish selected articles" in html
+
+
+# -- update / messages --------------------------------------------------------------
+
+
+def test_update_action_updates_only_selection_and_flashes(articles, run):
+    response = run("publish_action", articles[:2])
+    assert response.status_code == 302
+    assert statuses() == {"a": "published", "b": "published", "=cmd": "draft"}
+    assert messages_of(response) == ["Published 2 articles."]
+
+
+def test_singular_name(articles, run):
+    assert messages_of(run("publish_action", articles[:1])) == ["Published 1 article."]
+
+
+# -- object action ------------------------------------------------------------------
+
+
+def test_object_action_skip_errors_rolls_back_failed_object_only(articles, run):
+    response = run("reset_views_action", articles)
+    titles = {a.title: a.views for a in Article.objects.all()}
+    assert titles == {"a (reset)": 0, "b": 500, "=cmd (reset)": 0}  # 'b' fully rolled back
+    msgs = messages_of(response)
+    assert "Reset 2 articles." in msgs and "b: too popular" in msgs
+    assert LogEntry.objects.count() == 2
+
+
+def test_object_action_without_skip_errors_aborts_everything(articles, run):
+    response = run("strict_reset_action", articles)
+    assert all(a.title != "touched" for a in Article.objects.all())  # whole run rolled back
+    assert messages_of(response) == ["too popular"]
+
+
+# -- confirmation & forms -----------------------------------------------------------
+
+
+def test_confirmation_page_then_perform(articles, run):
+    response = run("archive_action", articles[:1], select_across="0")
+    assert response.status_code == 200
+    body = response.content.decode()
+    assert CONFIRM_FIELD in body and 'name="action" value="archive_action"' in body
+    assert statuses()["a"] == "draft"  # nothing happened yet
+
+    response = run("archive_action", articles[:1], **{CONFIRM_FIELD: "1"})
+    assert response.status_code == 302
+    assert statuses()["a"] == "archived"
+    assert messages_of(response) == ["Archived 1 article."]
+
+
+def test_confirmation_preserves_select_across(articles, run):
+    body = run("archive_action", articles[:1], select_across="1").content.decode()
+    assert 'name="select_across" value="1"' in body
+
+
+def test_form_flow_invalid_then_valid(articles, run):
+    first = run("set_status_action", articles[:2])
+    assert first.status_code == 200 and "<select" in first.content.decode()
+
+    invalid = run("set_status_action", articles[:2], **{CONFIRM_FIELD: "1", "status": "bogus"})
+    assert invalid.status_code == 200
+    assert "Select a valid choice" in invalid.content.decode()
+    assert set(statuses().values()) == {"draft"}
+
+    valid = run("set_status_action", articles[:2], **{CONFIRM_FIELD: "1", "status": "published"})
+    assert valid.status_code == 302
+    assert statuses() == {"a": "published", "b": "published", "=cmd": "draft"}
+    assert messages_of(valid) == ["Status set on 2 articles."]
+
+
+# -- preconditions, permissions -----------------------------------------------------
+
+
+def test_max_objects(articles, run):
+    response = run("two_at_most_action", articles)
+    assert "at most 2 items" in messages_of(response)[0]
+    assert set(statuses().values()) == {"draft"}
+    run("two_at_most_action", articles[:2])
+    assert list(statuses().values()).count("published") == 2
+
+
+def test_action_hidden_and_denied_without_permission(articles, client):
+    user = get_user_model().objects.create_user("staff", password="pw", is_staff=True)
+    from django.contrib.auth.models import Permission
+    user.user_permissions.add(*Permission.objects.filter(codename__in=["view_article", "change_article"]))
+    client.force_login(user)
+    url = reverse("admin:testapp_article_changelist")
+    html = client.get(url).content.decode()
+    assert "Admin only action" not in html and "Publish selected" in html
+    client.post(url, {"action": "admin_only_action", "_selected_action": [articles[0].pk]})
+    assert set(statuses().values()) == {"draft"}
+
+
+def test_has_permission_enforced_even_if_action_is_called_directly(articles, rf):
+    from django.core.exceptions import PermissionDenied
+    from django.contrib import admin
+
+    request = rf.post("/")
+    request.user = get_user_model().objects.create_user("nobody", password="pw")
+    action = UpdateAction.as_action(update_fields={"status": "x"}, allowed_permissions=("change",))
+    with pytest.raises(PermissionDenied):
+        action(ArticleAdmin(Article, admin.site), request, Article.objects.all())
+
+
+# -- export -------------------------------------------------------------------------
+
+
+def test_csv_export_escapes_formulas(articles, run):
+    response = run("export_action", articles)
+    assert response["Content-Type"].startswith("text/csv")
+    assert 'filename="article.csv"' in response["Content-Disposition"]
+    rows = list(csv.reader(io.StringIO(response.content.decode())))
+    assert rows[0] == ["title", "status", "views"]
+    assert ["'=cmd", "draft", "3"] in rows and ["a", "draft", "1"] in rows

django_class_based_admin_actions-0.1.0/tests/testapp/admin.py

@@ -0,0 +1,77 @@
+from django import forms
+from django.contrib import admin
+
+from class_based_admin_actions import (
+    ActionError, ClassActionsMixin, ConfirmationMixin, CsvExportAction, FormUpdateAction,
+    ObjectAction, UpdateAction,
+)
+
+from .models import Article
+
+
+class StatusForm(forms.Form):
+    status = forms.ChoiceField(choices=[("draft", "Draft"), ("published", "Published")])
+
+
+class PublishAction(UpdateAction):
+    description = "Publish selected %(verbose_name_plural)s"
+    update_fields = {"status": "published"}
+    success_message = "Published %(count)d %(name)s."
+    allowed_permissions = ("change",)
+
+
+class ArchiveAction(ConfirmationMixin, PublishAction):
+    update_fields = {"status": "archived"}
+    success_message = "Archived %(count)d %(name)s."
+
+
+class SetStatusAction(FormUpdateAction):
+    form_class = StatusForm
+    success_message = "Status set on %(count)d %(name)s."
+
+
+class ResetViewsAction(ObjectAction):
+    skip_errors = True
+    log_message = "Views reset."
+    success_message = "Reset %(count)d %(name)s."
+
+    def process_object(self, obj):
+        obj.title = obj.title + " (reset)"
+        obj.save()
+        if obj.views > 100:
+            raise ActionError("too popular")
+        obj.views = 0
+        obj.save()
+
+
+class StrictResetAction(ObjectAction):
+    def process_object(self, obj):
+        obj.title = "touched"
+        obj.save()
+        if obj.views > 100:
+            raise ActionError("too popular")
+
+
+class TwoAtMostAction(UpdateAction):
+    update_fields = {"status": "published"}
+    max_objects = 2
+
+
+class ExportAction(CsvExportAction):
+    fields = ["title", "status", "views"]
+
+
+class AdminOnlyAction(UpdateAction):
+    update_fields = {"status": "published"}
+    allowed_permissions = ("publish",)
+
+
+@admin.register(Article)
+class ArticleAdmin(ClassActionsMixin, admin.ModelAdmin):
+    actions = [
+        PublishAction, ArchiveAction, SetStatusAction, ResetViewsAction, StrictResetAction,
+        TwoAtMostAction, ExportAction, AdminOnlyAction,
+    ]
+
+    def has_publish_permission(self, request):
+        return request.user.is_superuser

django_class_based_admin_actions-0.1.0/tests/testapp/models.py

@@ -0,0 +1,10 @@
+from django.db import models
+
+
+class Article(models.Model):
+    title = models.CharField(max_length=100)
+    status = models.CharField(max_length=20, default="draft")
+    views = models.PositiveIntegerField(default=0)
+
+    def __str__(self):
+        return self.title

django_class_based_admin_actions-0.1.0/tests/urls.py

@@ -0,0 +1,4 @@
+from django.contrib import admin
+from django.urls import path
+
+urlpatterns = [path("admin/", admin.site.urls)]