django-admin-tables 0.1.0__py3-none-any.whl

django_admin_tables/__init__.py

@@ -0,0 +1,22 @@
+"""Extras for the Django admin's tables: changelists and inlines."""
+
+from .columns import HideableColumnsMixin
+from .fk_links import ForeignKeyLinkMixin
+from .footer import FooterRowsMixin
+from .mixins import AdminTablesMixin
+from .radio_select import ExclusiveRadioFieldsMixin
+from .row_actions import RowActionsMixin, row_action
+from .unsaved import UnsavedChangesMixin
+
+__all__ = [
+    "AdminTablesMixin",
+    "ExclusiveRadioFieldsMixin",
+    "FooterRowsMixin",
+    "ForeignKeyLinkMixin",
+    "HideableColumnsMixin",
+    "RowActionsMixin",
+    "UnsavedChangesMixin",
+    "row_action",
+]
+
+__version__ = "0.1.0"

django_admin_tables/apps.py

@@ -0,0 +1,6 @@
+from django.apps import AppConfig
+
+
+class DjangoAdminTablesConfig(AppConfig):
+    name = "django_admin_tables"
+    verbose_name = "Django Admin Tables"

django_admin_tables/base.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, cast
+
+from django.contrib.admin.options import BaseModelAdmin
+from django.template.loader import select_template
+from django.template.response import TemplateResponse
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from django.contrib.admin.views.main import ChangeList
+    from django.db.models import Model
+    from django.forms.models import BaseInlineFormSet
+    from django.http import HttpRequest, HttpResponse
+
+
+class TableTemplatesMixin(BaseModelAdmin):
+    """The base of the mixins that add to the admin's tables: renders the
+    changelist with ``tables_change_list_template``, and a tabular inline
+    with ``tables_inline_template``, when one of them has something to add.
+
+    Each mixin adds its part through ``get_changelist_extras()`` and
+    ``get_inline_extras()``, calling ``super()``: their keys end up in the
+    template's context (``django_admin_tables_<key>``) for the changelist,
+    and in the inline's ``django_admin_tables_inline`` for an inline.
+
+    The changelist template extends the one the admin would use
+    (``change_list_template`` included); the inline one includes the
+    inline's own ``template``. The ``# type: ignore[misc]`` on ``super()``
+    calls is because only the concrete ``ModelAdmin``/``InlineModelAdmin``
+    declare them.
+    """
+
+    tables_change_list_template = "django_admin_tables/change_list.html"
+    tables_inline_template = "django_admin_tables/edit_inline.html"
+
+    def get_changelist_extras(
+        self, request: HttpRequest, cl: ChangeList
+    ) -> dict[str, Any]:
+        return {}
+
+    def get_inline_extras(
+        self, request: HttpRequest, obj: Model | None
+    ) -> dict[str, Any]:
+        return {}
+
+    def changelist_view(
+        self, request: HttpRequest, extra_context: dict[str, Any] | None = None
+    ) -> HttpResponse:
+        response = super().changelist_view(request, extra_context)  # type: ignore[misc]
+        if not isinstance(response, TemplateResponse) or response.is_rendered:
+            return response
+        context = response.context_data or {}
+        cl = context.get("cl")
+        if cl is None:
+            return response
+        extras = {
+            key: value
+            for key, value in self.get_changelist_extras(request, cl).items()
+            if value
+        }
+        if not extras:
+            return response
+        # The admin's changelist_view() renders a name or a list of names.
+        template_name = cast("str | Sequence[str]", response.template_name)
+        context["django_admin_tables_parent"] = select_template(
+            [template_name] if isinstance(template_name, str) else template_name
+        )
+        for key, value in extras.items():
+            context[f"django_admin_tables_{key}"] = value
+        response.template_name = self.tables_change_list_template
+        return response
+
+    def get_formset(
+        self, request: HttpRequest, obj: Model | None = None, **kwargs: Any
+    ) -> type[BaseInlineFormSet]:
+        formset_class = super().get_formset(request, obj, **kwargs)  # type: ignore[misc]
+        # django-admin-inline-controls renders the inline's own template
+        # inside its wrapper (and alone, when it refreshes the inline): wrap
+        # that one, so the extras are in both.
+        attribute = (
+            "inline_controls_inner_template"
+            if hasattr(self, "inline_controls_inner_template")
+            else "template"
+        )
+        template: str = getattr(self, attribute, "")
+        # The admin builds its inlines for each request: their template can
+        # change with the request. get_formset() may be called more than once.
+        if template != self.tables_inline_template:
+            extras = {
+                key: value
+                for key, value in self.get_inline_extras(request, obj).items()
+                if value
+            }
+            if extras:
+                self.django_admin_tables_inline = {
+                    "parent": select_template([template]),
+                    **extras,
+                }
+                setattr(self, attribute, self.tables_inline_template)
+        return formset_class

django_admin_tables/columns/__init__.py

@@ -0,0 +1,5 @@
+"""Changelist columns the user can hide, remembered in their browser."""
+
+from .mixins import HideableColumnsMixin
+
+__all__ = ["HideableColumnsMixin"]

django_admin_tables/columns/mixins.py

@@ -0,0 +1,206 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from django.apps import apps
+from django.contrib.admin.utils import label_for_field
+from django.core import checks
+from django.utils.text import capfirst
+
+from ..base import TableTemplatesMixin
+from .responsive import BREAKPOINTS, Breakpoint, max_width, media_rules
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+
+    from django.contrib.admin.views.main import ChangeList
+    from django.db.models import Model
+    from django.http import HttpRequest
+
+#: Attribute naming the field behind a generated ``list_display`` callable
+#: (``ForeignKeyLinkMixin``'s links), so it can be listed by that name.
+FIELD_NAME_ATTR = "_django_admin_tables_field"
+
+
+def column_name(item: Any) -> str:
+    """The name ``item`` (a ``list_display`` entry) is listed by."""
+    if isinstance(item, str):
+        return item
+    return str(getattr(item, FIELD_NAME_ATTR, None) or getattr(item, "__name__", ""))
+
+
+def column_class(item: Any, index: int) -> str:
+    """The suffix of the ``column-``/``field-`` classes the admin gives
+    ``item``'s cells (``_coerce_field_name()`` in ``admin_list``)."""
+    if isinstance(item, str):
+        return item
+    if item.__name__ == "<lambda>":
+        return f"lambda{index}"
+    return item.__name__
+
+
+def checkbox_classes() -> str:
+    if not apps.is_installed("unfold"):
+        return ""
+    from unfold.widgets import CHECKBOX_CLASSES
+
+    return " ".join(CHECKBOX_CLASSES)
+
+
+class HideableColumnsMixin(TableTemplatesMixin):
+    """Mixin hiding columns, for a ``ModelAdmin`` or a ``TabularInline``:
+
+    - ``list_display_hideable``: a "Columns" menu on the changelist, to
+      hide or show those columns. The choice is per user and per model,
+      kept in the browser's ``localStorage``.
+    - ``responsive_columns``: columns hidden below a viewport width, on the
+      changelist (``list_display`` names) or in a tabular inline (field
+      names), with CSS media queries.
+
+    Both hide on the ``column-<name>`` and ``field-<name>`` classes the
+    admin gives each column's cells, so sorting, actions, ``list_editable``
+    and the inline's form work as they do without it.
+
+    They're added by the changelist's and the inline's templates (see
+    ``TableTemplatesMixin``).
+    """
+
+    #: ``list_display`` entries the user can hide: field names, or the
+    #: name of a method or callable.
+    list_display_hideable: Sequence[str] = ()
+    #: Entries of ``list_display_hideable`` hidden until the user shows them.
+    list_display_hidden: Sequence[str] = ()
+    #: Columns hidden below a viewport width: ``{"album": "md"}``. Widths
+    #: are a name of ``BREAKPOINTS`` (``"sm"``, ``"md"``, ``"lg"``, ``"xl"``,
+    #: ``"2xl"``) or pixels.
+    responsive_columns: Mapping[str, Breakpoint] = {}
+
+    def get_list_display_hideable(self, request: HttpRequest) -> Sequence[str]:
+        return self.list_display_hideable
+
+    def get_list_display_hidden(self, request: HttpRequest) -> Sequence[str]:
+        return self.list_display_hidden
+
+    def get_responsive_columns(
+        self, request: HttpRequest, obj: Model | None = None
+    ) -> Mapping[str, Breakpoint]:
+        return self.responsive_columns
+
+    def get_hideable_columns(
+        self, request: HttpRequest, cl: ChangeList
+    ) -> list[dict[str, Any]]:
+        """The hideable columns of ``cl``, in ``list_display`` order."""
+        hideable = set(self.get_list_display_hideable(request))
+        if not hideable:
+            return []
+        hidden = set(self.get_list_display_hidden(request))
+        responsive = self.get_responsive_columns(request)
+        columns = []
+        for index, item in enumerate(cl.list_display):
+            name = column_name(item)
+            if name not in hideable:
+                continue
+            columns.append(
+                {
+                    "name": name,
+                    "class": column_class(item, index),
+                    "label": capfirst(
+                        str(label_for_field(item, cl.model, model_admin=self))
+                    ),
+                    "hidden": name in hidden,
+                    "max_width": (
+                        max_width(responsive[name]) if name in responsive else None
+                    ),
+                }
+            )
+        return columns
+
+    def get_changelist_extras(
+        self, request: HttpRequest, cl: ChangeList
+    ) -> dict[str, Any]:
+        extras = super().get_changelist_extras(request, cl)
+        columns = self.get_hideable_columns(request, cl)
+        if columns:
+            opts = cl.model._meta
+            extras["columns"] = {
+                "columns": columns,
+                "unfold": apps.is_installed("unfold"),
+                "checkbox_classes": checkbox_classes(),
+                "config": {
+                    "storageKey": (
+                        f"django-admin-tables:{self.admin_site.name}:"
+                        f"{opts.app_label}.{opts.model_name}:hidden-columns"
+                    ),
+                    "hidden": [c["class"] for c in columns if c["hidden"]],
+                    "columns": [c["class"] for c in columns],
+                },
+            }
+        extras["responsive"] = media_rules(
+            self.get_responsive_columns(request),
+            (
+                (column_name(item), column_class(item, index))
+                for index, item in enumerate(cl.list_display)
+            ),
+        )
+        return extras
+
+    def get_inline_extras(
+        self, request: HttpRequest, obj: Model | None
+    ) -> dict[str, Any]:
+        extras = super().get_inline_extras(request, obj)
+        responsive = self.get_responsive_columns(request, obj)
+        extras["responsive"] = media_rules(
+            responsive, ((name, name) for name in responsive)
+        )
+        return extras
+
+    def check(self, **kwargs: Any) -> list[checks.CheckMessage]:
+        return [*super().check(**kwargs), *self._check_hideable_columns()]
+
+    def _check_hideable_columns(self) -> list[checks.CheckMessage]:
+        errors: list[checks.CheckMessage] = []
+        for name, breakpoint in self.responsive_columns.items():
+            try:
+                max_width(breakpoint)
+            except ValueError:
+                errors.append(
+                    checks.Error(
+                        f"'{name}' in responsive_columns has an unknown "
+                        f"breakpoint, {breakpoint!r}: use one of "
+                        f"{', '.join(BREAKPOINTS)}, or pixels.",
+                        obj=self.__class__,
+                        id="django_admin_tables.E003",
+                    )
+                )
+        list_display = getattr(self, "list_display", None)
+        if list_display is None:  # An inline: there's no changelist.
+            return errors
+        listed = {column_name(item) for item in list_display}
+        errors += [
+            checks.Error(
+                f"'{name}' in responsive_columns isn't in list_display.",
+                obj=self.__class__,
+                id="django_admin_tables.E004",
+            )
+            for name in self.responsive_columns
+            if name not in listed
+        ]
+        errors += [
+            checks.Error(
+                f"'{name}' in list_display_hideable isn't in list_display.",
+                obj=self.__class__,
+                id="django_admin_tables.E001",
+            )
+            for name in self.list_display_hideable
+            if name not in listed
+        ]
+        errors += [
+            checks.Error(
+                f"'{name}' in list_display_hidden isn't in list_display_hideable.",
+                obj=self.__class__,
+                id="django_admin_tables.E002",
+            )
+            for name in self.list_display_hidden
+            if name not in self.list_display_hideable
+        ]
+        return errors

django_admin_tables/columns/responsive.py

@@ -0,0 +1,54 @@
+"""Columns hidden below a viewport width, with CSS media queries."""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Mapping
+
+#: Named breakpoints, in pixels: Tailwind's, which django-unfold uses.
+BREAKPOINTS = {"sm": 640, "md": 768, "lg": 1024, "xl": 1280, "2xl": 1536}
+
+Breakpoint = str | int
+
+
+def max_width(breakpoint: Breakpoint) -> float:
+    """The ``max-width`` of the media query hiding a column below
+    ``breakpoint`` (a name of ``BREAKPOINTS``, or pixels)."""
+    if isinstance(breakpoint, str) and breakpoint in BREAKPOINTS:
+        pixels = BREAKPOINTS[breakpoint]
+    elif isinstance(breakpoint, int) and not isinstance(breakpoint, bool):
+        pixels = breakpoint
+    else:
+        raise ValueError(f"Unknown breakpoint: {breakpoint!r}.")
+    if pixels <= 0:
+        raise ValueError(f"Unknown breakpoint: {breakpoint!r}.")
+    # Just under the breakpoint: at exactly its width, the column shows.
+    return pixels - 0.02
+
+
+def css_identifier(name: str) -> str:
+    """``name`` escaped for a class selector."""
+    return re.sub(r"[^\w-]", lambda match: f"\\{match.group()}", name)
+
+
+def media_rules(
+    breakpoints: Mapping[str, Breakpoint], classes: Iterable[tuple[str, str]]
+) -> list[dict[str, object]]:
+    """The media queries hiding each column below its breakpoint.
+
+    ``classes`` pairs each column's name (a key of ``breakpoints``) with
+    the suffix of its ``column-``/``field-`` classes. Returns one rule per
+    width, widest first: ``{"max_width": 767.98, "classes": [...]}``.
+    """
+    by_width: dict[float, list[str]] = {}
+    for name, css_class in classes:
+        if name in breakpoints:
+            width = max_width(breakpoints[name])
+            by_width.setdefault(width, []).append(css_identifier(css_class))
+    return [
+        {"max_width": width, "classes": by_width[width]}
+        for width in sorted(by_width, reverse=True)
+    ]

django_admin_tables/fk_links/__init__.py

@@ -0,0 +1,5 @@
+"""Foreign keys in ``list_display`` shown as links to their change view."""
+
+from .mixins import UNFOLD_LINK_CLASS, ForeignKeyLinkMixin
+
+__all__ = ["UNFOLD_LINK_CLASS", "ForeignKeyLinkMixin"]

django_admin_tables/fk_links/mixins.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from django.apps import apps
+from django.contrib.admin.options import BaseModelAdmin
+from django.template.loader import render_to_string
+from django.urls import reverse
+from django.utils.html import format_html
+
+from ..columns.mixins import FIELD_NAME_ATTR
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Sequence
+    from typing import Any
+
+    from django.http import HttpRequest
+    from django.utils.safestring import SafeString
+
+
+#: django-unfold's link colors: its reset styles links like the text around.
+UNFOLD_LINK_CLASS = "text-primary-600 dark:text-primary-500"
+
+
+class ForeignKeyLinkMixin(BaseModelAdmin):
+    """ModelAdmin mixin rendering chosen FK fields in list_display as links
+    to their change view.
+
+    Meant to sit before ``admin.ModelAdmin`` in a subclass's bases, e.g.
+    ``class BookAdmin(ForeignKeyLinkMixin, admin.ModelAdmin)``. Inheriting
+    from ``BaseModelAdmin`` — the common base of ``ModelAdmin`` and
+    ``InlineModelAdmin`` — types ``self``/``super()`` while still letting
+    ``AdminTablesMixin`` combine it with ``ExclusiveRadioFieldsMixin`` on an
+    inline too, where there's no ``list_display`` and it does nothing. The
+    ``# type: ignore[misc]`` on ``super().get_list_display()`` is because
+    only the concrete ``ModelAdmin`` declares it.
+    """
+
+    list_display_foreign_key_links: Sequence[str] = ()
+    #: Template rendering each link, with ``obj``, ``related``, ``url``,
+    #: ``field_name`` and ``link_class`` in its context. ``None`` renders a
+    #: plain ``<a>`` tag.
+    foreign_key_link_template: str | None = None
+    #: CSS class of each link. ``None`` picks the admin theme's: django-unfold's
+    #: link colors when it's installed, else none.
+    foreign_key_link_class: str | None = None
+
+    def get_list_display_foreign_key_links(self, request: HttpRequest) -> Sequence[str]:
+        return self.list_display_foreign_key_links
+
+    def get_foreign_key_link_class(self) -> str:
+        if self.foreign_key_link_class is not None:
+            return self.foreign_key_link_class
+        return UNFOLD_LINK_CLASS if apps.is_installed("unfold") else ""
+
+    def get_foreign_key_link(
+        self, obj: Any, field_name: str, related: Any, url: str
+    ) -> str | SafeString:
+        """HTML of the link from ``obj`` to ``related``'s change view.
+
+        Override to change the markup (a class, a ``target``, an icon, the
+        text…), or set ``foreign_key_link_template`` to render it from a
+        template instead. Return safe HTML (``format_html()``): the admin
+        escapes plain strings.
+        """
+        link_class = self.get_foreign_key_link_class()
+        if self.foreign_key_link_template:
+            return render_to_string(
+                self.foreign_key_link_template,
+                {
+                    "obj": obj,
+                    "related": related,
+                    "url": url,
+                    "field_name": field_name,
+                    "link_class": link_class,
+                },
+            )
+        if link_class:
+            return format_html(
+                '<a href="{}" class="{}">{}</a>', url, link_class, related
+            )
+        return format_html('<a href="{}">{}</a>', url, related)
+
+    def get_list_display(self, request: HttpRequest) -> list[Any]:
+        base = list(super().get_list_display(request))  # type: ignore[misc]
+        list_editable = getattr(self, "list_editable", ())
+        result: list[Any] = []
+
+        for item in base:
+            if (
+                isinstance(item, str)
+                and item in self.get_list_display_foreign_key_links(request)
+                and item not in list_editable
+            ):
+                result.append(self._build_fk_link_callable(item))
+            else:
+                result.append(item)
+
+        return result
+
+    def _build_fk_link_callable(self, field_name: str) -> Callable[[Any], str]:
+        """Build the list_display callable that links to field_name's related object."""
+        try:
+            field = self.model._meta.get_field(field_name)
+            verbose = field.verbose_name
+            order_field: str | None = field_name
+        except Exception:
+            verbose = field_name.replace("_", " ")
+            order_field = None
+
+        def fk_link(obj: Any) -> str | SafeString:
+            """Return an <a> tag to obj's related change view, or '-' if unset."""
+            related = getattr(obj, field_name, None)
+            if not related:
+                return "-"
+
+            rel_meta = related._meta
+            url = reverse(
+                f"{self.admin_site.name}:{rel_meta.app_label}_{rel_meta.model_name}_change",
+                args=[related.pk],
+            )
+            return self.get_foreign_key_link(obj, field_name, related, url)
+
+        fk_link.__name__ = f"{field_name}_link"
+        # Listed by its field's name (list_display_hideable, say).
+        setattr(fk_link, FIELD_NAME_ATTR, field_name)
+        # short_description/admin_order_field are Django's own convention
+        # for annotating a list_display callable; there's no stub for
+        # attributes bolted onto a plain function like this.
+        fk_link.short_description = verbose  # type: ignore[attr-defined]
+        if order_field:
+            fk_link.admin_order_field = order_field  # type: ignore[attr-defined]
+
+        return fk_link

django_admin_tables/footer/__init__.py

@@ -0,0 +1,6 @@
+"""Totals, averages… below a table's columns: the changelist's, an inline's."""
+
+from .mixins import FooterRowsMixin
+from .rows import FOOTER_FILTERED, FOOTER_PAGE
+
+__all__ = ["FOOTER_FILTERED", "FOOTER_PAGE", "FooterRowsMixin"]