django-admin-inline-controls 0.1.0__py3-none-any.whl

django_admin_inline_controls/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

django_admin_inline_controls/actions.py

@@ -0,0 +1,176 @@
+"""Inline actions: like the changelist's, for the rows of one inline.
+
+An action is called as ``action(inline, request, queryset)``, where
+``queryset`` holds the selected rows (always children of the parent object
+being edited) and ``request.inline_controls_parent`` is that parent. Return
+``None`` to re-render the inline with the messages sent through
+``inline.message_user()``, or an ``HttpResponse`` (a file download or a
+redirect).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from typing import TYPE_CHECKING, Any
+
+from django.contrib import admin, messages
+from django.db import router, transaction
+from django.db.models import ProtectedError, QuerySet
+from django.http import HttpRequest
+from django.utils.translation import gettext_lazy as _
+from django.utils.translation import ngettext
+
+if TYPE_CHECKING:
+    from django.utils.functional import _StrOrPromise as StrOrPromise
+
+InlineAction = Callable[[Any, HttpRequest, QuerySet], Any]
+
+
+def inline_action(
+    function: InlineAction | None = None,
+    *,
+    permissions: Sequence[str] | None = None,
+    description: StrOrPromise | None = None,
+    confirmation: StrOrPromise | None = None,
+) -> Any:
+    """``@admin.action`` plus an optional confirmation prompt::
+
+        @inline_action(
+            description="Mark selected %(verbose_name_plural)s as published",
+            confirmation="Publish the selected %(verbose_name_plural)s?",
+        )
+        def publish(inline, request, queryset):
+            queryset.update(status="published")
+
+    ``description`` and ``confirmation`` may use ``%(verbose_name)s`` and
+    ``%(verbose_name_plural)s``; ``confirmation`` also ``%(count)s``, the
+    number of rows the action will run on. Plain ``@admin.action`` functions
+    work too.
+    """
+
+    def decorator(func: InlineAction) -> InlineAction:
+        func = admin.action(permissions=permissions, description=description)(func)
+        if confirmation is not None:
+            func.confirmation = confirmation  # type: ignore[attr-defined]
+        return func
+
+    return decorator if function is None else decorator(function)
+
+
+@inline_action(
+    permissions=["delete"],
+    description=_("Delete selected %(verbose_name_plural)s"),
+    confirmation=_(
+        "Delete %(count)s selected %(verbose_name_plural)s? This cannot be undone."
+    ),
+)
+def delete_selected(inline: Any, request: HttpRequest, queryset: QuerySet) -> None:
+    """Delete the selected rows one by one (so ``delete()`` overrides and
+    signals run, as when they're deleted from the change form) and record
+    it in the parent's history."""
+    objects = list(queryset)
+    opts = queryset.model._meta
+    parent = getattr(request, "inline_controls_parent", None)
+    try:
+        with transaction.atomic(using=router.db_for_write(queryset.model)):
+            for obj in objects:
+                obj.delete()
+    except ProtectedError as error:
+        inline.message_user(
+            request,
+            _("Cannot delete: %(objects)s are referenced by protected objects.")
+            % {"objects": ", ".join(str(obj) for obj in error.protected_objects)},
+            messages.ERROR,
+        )
+        return None
+    parent_admin = parent and inline.admin_site._registry.get(type(parent))
+    if parent_admin is not None and objects:
+        parent_admin.log_change(
+            request,
+            parent,
+            [
+                {"deleted": {"name": str(opts.verbose_name), "object": str(obj)}}
+                for obj in objects
+            ],
+        )
+    inline.message_user(
+        request,
+        ngettext(
+            "Deleted %(count)d %(name)s.",
+            "Deleted %(count)d %(name)s.",
+            len(objects),
+        )
+        % {
+            "count": len(objects),
+            "name": opts.verbose_name
+            if len(objects) == 1
+            else opts.verbose_name_plural,
+        },
+        messages.SUCCESS,
+    )
+    return None
+
+
+#: Actions that can be referenced by name in ``inline_bulk_actions``.
+BUILTIN_BULK_ACTIONS: dict[str, InlineAction] = {"delete_selected": delete_selected}
+
+
+# Row actions as django-inline-actions' mixins ---------------------------------
+
+
+class ViewAction:
+    """A "View" link on each row, to its change view::
+
+    class BookInline(ViewAction, InlineControlsMixin, admin.TabularInline):
+        ...
+    """
+
+    inline_actions: list[str | InlineAction] | None = ["view_action"]
+
+    @inline_action(permissions=["view"], description=_("View"))
+    def view_action(
+        self, request: HttpRequest, obj: Any, parent_obj: Any = None
+    ) -> Any:
+        from django_admin_inline_controls.row_actions import view
+
+        return view(self, request, obj, parent_obj)
+
+    view_action.inline_actions_link = True
+
+
+class DeleteAction:
+    """A "Delete" button on each row (with the delete permission)::
+
+    class BookInline(DeleteAction, InlineControlsMixin, admin.TabularInline):
+        ...
+    """
+
+    def get_inline_actions(self, request: HttpRequest | None, obj: Any = None) -> Any:
+        actions = list(super().get_inline_actions(request, obj))  # type: ignore[misc]
+        if "delete_action" not in actions:
+            actions.append("delete_action")
+        return actions
+
+    @inline_action(
+        permissions=["delete"],
+        description=_("Delete"),
+        confirmation=_("Delete “%(object)s”? This cannot be undone."),
+    )
+    def delete_action(self, request: HttpRequest, queryset: QuerySet) -> None:
+        return delete_selected(self, request, queryset)
+
+
+class DefaultActionsMixin(ViewAction, DeleteAction):
+    """``ViewAction`` and ``DeleteAction``."""
+
+    inline_actions: list[str | InlineAction] | None = []
+
+
+__all__ = [
+    "BUILTIN_BULK_ACTIONS",
+    "DefaultActionsMixin",
+    "DeleteAction",
+    "ViewAction",
+    "delete_selected",
+    "inline_action",
+]

django_admin_inline_controls/apps.py

@@ -0,0 +1,7 @@
+from django.apps import AppConfig
+
+
+class DjangoAdminInlineControlsConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "django_admin_inline_controls"
+    label = "django_admin_inline_controls"

django_admin_inline_controls/checks.py

@@ -0,0 +1,212 @@
+"""System checks for ``InlineControlsMixin`` options."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Any
+
+from django.contrib.admin.utils import label_for_field
+from django.core import checks
+from django.core.exceptions import FieldDoesNotExist
+
+from django_admin_inline_controls.controls import (
+    DEFAULT_SELECTORS,
+    FOOTER_FILTERED,
+    FOOTER_PAGE,
+    INFINITE,
+    PAGES,
+)
+
+if TYPE_CHECKING:
+    from django_admin_inline_controls.mixins import InlineControlsMixin
+
+
+def check_inline_controls(inline: InlineControlsMixin) -> list[checks.CheckMessage]:
+    from django_admin_inline_controls.mixins import (
+        InlineControlsAdminMixin,
+        resolve_lookup,
+    )
+
+    errors: list[checks.CheckMessage] = []
+    name = type(inline).__qualname__
+
+    def error(msg: str, id: str) -> None:
+        errors.append(checks.Error(msg, obj=type(inline), id=id))
+
+    if inline.inline_pagination not in (PAGES, INFINITE):
+        error(
+            f"The value of '{name}.inline_pagination' must be '{PAGES}' or "
+            f"'{INFINITE}'.",
+            "admin_inline_controls.E001",
+        )
+
+    per_page: Any = inline.inline_per_page
+    if per_page is not None and (
+        not isinstance(per_page, int) or isinstance(per_page, bool) or per_page < 1
+    ):
+        error(
+            f"The value of '{name}.inline_per_page' must be a positive integer "
+            "or None.",
+            "admin_inline_controls.E002",
+        )
+
+    if inline.inline_pagination == INFINITE and per_page is None:
+        error(
+            f"'{name}.inline_pagination = \"{INFINITE}\"' requires 'inline_per_page'.",
+            "admin_inline_controls.E003",
+        )
+
+    if isinstance(inline.inline_filter_fields, str):
+        error(
+            f"The value of '{name}.inline_filter_fields' must be a list or tuple.",
+            "admin_inline_controls.E004",
+        )
+    else:
+        for lookup in inline.inline_filter_fields:
+            try:
+                resolve_lookup(inline.model, lookup)
+            except FieldDoesNotExist:
+                error(
+                    f"'{name}.inline_filter_fields' refers to '{lookup}', which "
+                    f"is not a field of '{inline.model._meta.label}'.",
+                    "admin_inline_controls.E005",
+                )
+
+    ordering_fields: Any = inline.inline_ordering_fields
+    if isinstance(ordering_fields, str) or not isinstance(
+        ordering_fields, list | tuple | Mapping
+    ):
+        error(
+            f"The value of '{name}.inline_ordering_fields' must be a list, tuple "
+            "or dict.",
+            "admin_inline_controls.E006",
+        )
+    else:
+        for column in ordering_fields:
+            if not isinstance(column, str) or column.startswith("-") or "," in column:
+                error(
+                    f"'{name}.inline_ordering_fields' contains {column!r}; column "
+                    "names must be strings without a leading '-' or commas.",
+                    "admin_inline_controls.E007",
+                )
+
+    footer_rows: Any = inline.inline_footer_rows
+    if isinstance(footer_rows, str) or not isinstance(footer_rows, list | tuple):
+        error(
+            f"The value of '{name}.inline_footer_rows' must be a list of "
+            "(label, {column: value}) pairs.",
+            "admin_inline_controls.E013",
+        )
+    else:
+        for index, row in enumerate(footer_rows):
+            if not (
+                isinstance(row, list | tuple)
+                and len(row) == 2
+                and isinstance(row[1], Mapping)
+            ):
+                error(
+                    f"'{name}.inline_footer_rows[{index}]' must be a "
+                    "(label, {column: value}) pair.",
+                    "admin_inline_controls.E013",
+                )
+                continue
+            for column in row[1]:
+                try:
+                    label_for_field(column, inline.model, inline)  # type: ignore[call-overload]
+                except AttributeError:
+                    error(
+                        f"'{name}.inline_footer_rows[{index}]' refers to "
+                        f"'{column}', which is not a field of "
+                        f"'{inline.model._meta.label}' or of the inline.",
+                        "admin_inline_controls.E014",
+                    )
+
+    if not isinstance(inline.inline_footer_tfoot, bool):
+        error(
+            f"The value of '{name}.inline_footer_tfoot' must be True or False.",
+            "admin_inline_controls.E017",
+        )
+
+    if inline.inline_footer_scope not in (FOOTER_FILTERED, FOOTER_PAGE):
+        error(
+            f"The value of '{name}.inline_footer_scope' must be "
+            f"'{FOOTER_FILTERED}' or '{FOOTER_PAGE}'.",
+            "admin_inline_controls.E015",
+        )
+    elif inline.inline_footer_scope == FOOTER_PAGE and (
+        inline.inline_pagination == INFINITE
+    ):
+        error(
+            f"'{name}.inline_footer_scope = \"{FOOTER_PAGE}\"' can't be used with "
+            "infinite scroll (the shown rows change as more are loaded).",
+            "admin_inline_controls.E016",
+        )
+
+    selectors: Any = inline.inline_controls_selectors
+    if not isinstance(selectors, Mapping):
+        error(
+            f"The value of '{name}.inline_controls_selectors' must be a dict.",
+            "admin_inline_controls.E011",
+        )
+    else:
+        for key, value in selectors.items():
+            values = [value] if isinstance(value, str) else value
+            if key not in DEFAULT_SELECTORS or not (
+                isinstance(values, list | tuple)
+                and values
+                and all(isinstance(v, str) and v for v in values)
+            ):
+                error(
+                    f"'{name}.inline_controls_selectors' has an invalid entry "
+                    f"{key!r}: keys must be one of {sorted(DEFAULT_SELECTORS)} "
+                    "and values a selector or a non-empty list of selectors.",
+                    "admin_inline_controls.E012",
+                )
+
+    parent_admin = inline.admin_site._registry.get(inline.parent_model)
+    missing_admin_mixin = parent_admin is not None and not isinstance(
+        parent_admin, InlineControlsAdminMixin
+    )
+    for option, enabled, error_id in (
+        ("inline_save_button", inline.inline_save_button, "admin_inline_controls.E008"),
+        (
+            "inline_bulk_actions",
+            inline.inline_bulk_actions,
+            "admin_inline_controls.E010",
+        ),
+        ("inline_actions", inline.has_inline_actions, "admin_inline_controls.E019"),
+    ):
+        if enabled and missing_admin_mixin:
+            error(
+                f"'{name}.{option}' requires "
+                f"'{type(parent_admin).__qualname__}' to inherit from "
+                "'InlineControlsAdminMixin'.",
+                error_id,
+            )
+
+    for action in inline.inline_bulk_actions:
+        try:
+            _, func = inline._resolve_inline_bulk_action(action)
+        except AttributeError:
+            func = None
+        if not callable(func):
+            error(
+                f"'{name}.inline_bulk_actions' contains {action!r}, which is not a "
+                f"method of '{name}', a callable, or a built-in action.",
+                "admin_inline_controls.E009",
+            )
+
+    for action in inline.inline_actions or ():
+        try:
+            _, func = inline._resolve_inline_action(action)
+        except AttributeError:
+            func = None
+        if not callable(func):
+            error(
+                f"'{name}.inline_actions' contains {action!r}, which is not "
+                f"a method of '{name}', a callable, or a built-in row action "
+                "('view', 'delete').",
+                "admin_inline_controls.E018",
+            )
+
+    return errors

django_admin_inline_controls/contrib/__init__.py

@@ -0,0 +1,4 @@
+"""Integrations with optional third-party packages.
+
+Each submodule requires its matching extra and is only imported on demand.
+"""

django_admin_inline_controls/contrib/filters.py

@@ -0,0 +1,69 @@
+"""django-filter integration. Requires the ``filters`` extra."""
+
+from __future__ import annotations
+
+from typing import Any
+
+try:
+    import django_filters
+except ImportError as e:
+    raise ImportError(
+        "django_admin_inline_controls.contrib.filters requires django-filter. "
+        "Install it with: pip install django-admin-inline-controls[filters]"
+    ) from e
+
+from django.db.models import QuerySet
+from django.http import HttpRequest, QueryDict
+
+from django_admin_inline_controls.mixins import InlineControlsMixin
+from django_admin_inline_controls.types import FilterResult
+
+
+class FilterSetInlineControlsMixin(InlineControlsMixin):
+    """Filter the inline with a django-filter ``FilterSet``::
+
+        class BookInline(FilterSetInlineControlsMixin, admin.TabularInline):
+            model = Book
+            inline_per_page = 20
+            inline_filterset_class = BookFilterSet
+
+    The filterset receives the request (``self.request`` inside it) and
+    whatever ``get_inline_filterset_kwargs()`` returns, e.g. the parent object.
+    """
+
+    inline_filterset_class: type[django_filters.FilterSet] | None = None
+
+    def get_inline_filterset_class(
+        self, request: HttpRequest, obj: Any
+    ) -> type[django_filters.FilterSet] | None:
+        return self.inline_filterset_class
+
+    def get_inline_filterset_kwargs(
+        self, request: HttpRequest, obj: Any
+    ) -> dict[str, Any]:
+        return {}
+
+    def get_inline_filtered_queryset(
+        self,
+        request: HttpRequest,
+        obj: Any,
+        queryset: QuerySet,
+        data: QueryDict,
+        prefix: str,
+    ) -> FilterResult:
+        filterset_class = self.get_inline_filterset_class(request, obj)
+        if filterset_class is None:
+            return super().get_inline_filtered_queryset(
+                request, obj, queryset, data, prefix
+            )
+        filterset = filterset_class(
+            data,
+            queryset=queryset,
+            prefix=prefix,
+            request=request,
+            **self.get_inline_filterset_kwargs(request, obj),
+        )
+        return filterset.form, filterset.qs
+
+
+__all__ = ["FilterSetInlineControlsMixin"]

django_admin_inline_controls/contrib/nested.py

@@ -0,0 +1,77 @@
+"""django-nested-admin integration. Requires the ``nested`` extra."""
+
+from __future__ import annotations
+
+from typing import Any
+
+try:
+    import nested_admin  # noqa: F401
+except ImportError as e:
+    raise ImportError(
+        "django_admin_inline_controls.contrib.nested requires django-nested-admin. "
+        "Install it with: pip install django-admin-inline-controls[nested]"
+    ) from e
+
+from django.core import checks
+
+from django_admin_inline_controls.controls import INFINITE
+from django_admin_inline_controls.mixins import InlineControlsMixin
+
+
+class NestedInlineControlsMixin(InlineControlsMixin):
+    """``InlineControlsMixin`` for ``nested_admin`` inlines::
+
+        class BookInline(NestedInlineControlsMixin, nested_admin.NestedTabularInline):
+            model = Book
+            inline_per_page = 20
+
+    nested_admin keeps its own client-side formset state, so filters,
+    sorting and page links reload the page instead of swapping the inline,
+    and infinite scroll, the save-inline button and inline actions are not
+    available.
+    """
+
+    inline_controls_ajax = False
+
+    def check(self, **kwargs: Any) -> list[Any]:
+        errors = super().check(**kwargs)
+        if self.inline_pagination == INFINITE:
+            errors.append(
+                checks.Error(
+                    f"'{type(self).__qualname__}.inline_pagination' cannot be "
+                    f"'{INFINITE}' on a nested_admin inline.",
+                    obj=type(self),
+                    id="admin_inline_controls.E101",
+                )
+            )
+        if self.inline_save_button:
+            errors.append(
+                checks.Error(
+                    f"'{type(self).__qualname__}.inline_save_button' is not "
+                    "supported on a nested_admin inline.",
+                    obj=type(self),
+                    id="admin_inline_controls.E102",
+                )
+            )
+        if self.inline_bulk_actions:
+            errors.append(
+                checks.Error(
+                    f"'{type(self).__qualname__}.inline_bulk_actions' is not "
+                    "supported on a nested_admin inline.",
+                    obj=type(self),
+                    id="admin_inline_controls.E103",
+                )
+            )
+        if self.has_inline_actions:
+            errors.append(
+                checks.Error(
+                    f"'{type(self).__qualname__}.inline_actions' is not "
+                    "supported on a nested_admin inline.",
+                    obj=type(self),
+                    id="admin_inline_controls.E105",
+                )
+            )
+        return errors
+
+
+__all__ = ["NestedInlineControlsMixin"]

django_admin_inline_controls/contrib/unfold.py

@@ -0,0 +1,85 @@
+"""django-unfold integration."""
+
+from __future__ import annotations
+
+from typing import Any
+
+try:
+    import unfold  # noqa: F401
+except ImportError as e:
+    raise ImportError(
+        "django_admin_inline_controls.contrib.unfold requires django-unfold. "
+        "Install it with: pip install django-admin-inline-controls[unfold]"
+    ) from e
+
+from django import forms
+from django.core import checks
+from django.http import HttpRequest
+
+from django_admin_inline_controls.mixins import InlineControlsMixin
+
+#: Where the controls go in Unfold's inline templates; applied under the
+#: inline's own ``inline_controls_selectors``.
+UNFOLD_SELECTORS: dict[str, list[str]] = {
+    "container": [
+        "[data-inline-type] > fieldset",
+        "[data-inline-type] > .inline-related > fieldset",
+    ],
+    "table_head": ["table thead"],
+    # Each form is a <tbody> (tabular) or a <div> (stacked), without an id.
+    "form_rows": ['[id="{prefix}-data"] > .form-group'],
+    "saved_row": [".original"],
+    "row_label": [
+        ':scope > tr > td > p[class~="group/title"]',
+        ":scope > .form-row > h3 > span",
+        ":scope > tr.form-row > td",
+    ],
+}
+
+
+class UnfoldInlineControlsMixin(InlineControlsMixin):
+    """``InlineControlsMixin`` for Unfold's inlines::
+
+        from unfold.admin import TabularInline
+
+        class BookInline(UnfoldInlineControlsMixin, TabularInline):
+            model = Book
+            inline_per_page = 20
+
+    Places the controls in Unfold's markup, styles them with its colors
+    (light and dark) and re-binds its "Add another" / delete buttons after an
+    inline is refreshed. Paginate with ``inline_per_page``, not Unfold's
+    ``per_page``.
+    """
+
+    def get_inline_controls_selectors(
+        self, request: HttpRequest, obj: Any
+    ) -> dict[str, list[str]]:
+        selectors = super().get_inline_controls_selectors(request, obj)
+        for key, value in UNFOLD_SELECTORS.items():
+            if key not in self.inline_controls_selectors:
+                selectors[key] = list(value)
+        return selectors
+
+    @property
+    def media(self) -> forms.Media:
+        return super().media + forms.Media(
+            js=["django_admin_inline_controls/js/contrib/unfold.js"],
+            css={"all": ["django_admin_inline_controls/css/contrib/unfold.css"]},
+        )
+
+    def check(self, **kwargs: Any) -> list[Any]:
+        errors = super().check(**kwargs)
+        if getattr(self, "per_page", None):
+            errors.append(
+                checks.Error(
+                    f"'{type(self).__qualname__}.per_page' paginates the inline "
+                    "a second time; use 'inline_per_page' instead.",
+                    obj=type(self),
+                    id="admin_inline_controls.E104",
+                )
+            )
+        return errors
+
+
+__all__ = ["UNFOLD_SELECTORS", "UnfoldInlineControlsMixin"]