|
| 1 | +"""Surface a ``ModelAdmin``'s *custom* admin views to the SPA (Issue #439). |
| 2 | +
|
| 3 | +Many consumers add bespoke admin pages — report / import-export / |
| 4 | +dashboard pages and per-object tool views — by overriding |
| 5 | +``ModelAdmin.get_urls()`` (or ``AdminSite.get_urls()``). The SPA cannot |
| 6 | +render those Django-templated pages itself, but it can **link out** to |
| 7 | +them (Option A): a real ``<a target="_blank">`` to the legacy |
| 8 | +admin-rendered page. This module is the design-safe foundation — the |
| 9 | +same ``{name, label, url, level}`` payload also powers a future iframe |
| 10 | +or native approach. |
| 11 | +
|
| 12 | +How custom routes are distinguished from the standard CRUD set |
| 13 | +---------------------------------------------------------------- |
| 14 | +
|
| 15 | +Django's ``ModelAdmin.get_urls`` always emits five *named* routes for a |
| 16 | +model — ``<app>_<model>_{changelist,add,change,delete,history}`` — plus |
| 17 | +one unnamed catch-all (the legacy ``<pk>/`` redirect, ``name=None``). |
| 18 | +Anything a consumer adds on top has a different (or no) standard suffix. |
| 19 | +We compute the standard names from ``model._meta`` and treat every |
| 20 | +remaining *named* route as a custom view. Unnamed routes are skipped: |
| 21 | +without a name they can't be ``reverse()``-d through the admin |
| 22 | +namespace, so the SPA could never link to them anyway. |
| 23 | +
|
| 24 | +How URLs are reversed |
| 25 | +--------------------- |
| 26 | +
|
| 27 | +Custom admin routes live under the **admin site's** URL namespace |
| 28 | +(``admin_site.name``, e.g. ``"admin"``). We reverse each route as |
| 29 | +``reverse(f"{admin_site.name}:{name}", args=[...])`` — ``args=[obj.pk]`` |
| 30 | +for an object-level route, ``args=[]`` for a changelist-level one. Every |
| 31 | +reverse is guarded; an un-reversible route (legacy admin not mounted, |
| 32 | +extra capture groups we don't fill, a consumer ``reverse`` quirk) is |
| 33 | +silently skipped rather than raising. |
| 34 | +
|
| 35 | +Hardening (``SECURITY.md`` §3): this module introduces **no new |
| 36 | +permission surface**. It is only ever called from the detail / registry |
| 37 | +views, *after* their staff + ``has_view_permission`` gates have run, and |
| 38 | +it never reads object data beyond the ``pk`` it is handed. A misbehaving |
| 39 | +consumer ``get_urls`` must never 500 a response — every introspection |
| 40 | +step degrades to ``[]``. |
| 41 | +""" |
| 42 | + |
| 43 | +from __future__ import annotations |
| 44 | + |
| 45 | +from typing import Any |
| 46 | + |
| 47 | +from django.contrib.admin.options import ModelAdmin |
| 48 | +from django.db.models import Model |
| 49 | +from django.urls import reverse |
| 50 | +from django.utils.text import capfirst |
| 51 | + |
| 52 | +# Capture-group names Django uses for the per-object segment of a |
| 53 | +# ``ModelAdmin`` route. If a custom route's regex captures any of these |
| 54 | +# (or, defensively, a generic ``pk``), it is an *object-level* view that |
| 55 | +# needs an object id to reverse. |
| 56 | +_OBJECT_ID_GROUPS: frozenset[str] = frozenset({"object_id", "pk"}) |
| 57 | + |
| 58 | + |
| 59 | +def _standard_route_names(model: type[Model]) -> frozenset[str]: |
| 60 | + """The five route names Django's ``ModelAdmin.get_urls`` always emits. |
| 61 | +
|
| 62 | + Built from ``model._meta`` exactly the way Django builds them in |
| 63 | + ``ModelAdmin.get_urls`` (``info = app_label, model_name``), so this |
| 64 | + stays correct for any model without depending on Django internals. |
| 65 | + """ |
| 66 | + info = f"{model._meta.app_label}_{model._meta.model_name}" |
| 67 | + return frozenset( |
| 68 | + { |
| 69 | + f"{info}_changelist", |
| 70 | + f"{info}_add", |
| 71 | + f"{info}_change", |
| 72 | + f"{info}_delete", |
| 73 | + f"{info}_history", |
| 74 | + } |
| 75 | + ) |
| 76 | + |
| 77 | + |
| 78 | +def _is_object_level(pattern: Any) -> bool: |
| 79 | + """``True`` if the URL pattern captures an object id. |
| 80 | +
|
| 81 | + Inspects the compiled regex's named capture groups for an |
| 82 | + ``object_id`` / ``pk`` group — the marker that the route is a |
| 83 | + per-object tool view (e.g. ``<pk>/make-report/``) rather than a |
| 84 | + page that stands alone (e.g. ``import/``). Any introspection error |
| 85 | + is treated as "not object-level" (changelist-level) so we still |
| 86 | + attempt a no-args reverse. |
| 87 | + """ |
| 88 | + try: |
| 89 | + groups = pattern.regex.groupindex.keys() |
| 90 | + except Exception: |
| 91 | + return False |
| 92 | + return any(group in _OBJECT_ID_GROUPS for group in groups) |
| 93 | + |
| 94 | + |
| 95 | +def _label_for_route(entry: Any, name: str) -> str: |
| 96 | + """Human-readable label for a custom route. |
| 97 | +
|
| 98 | + Prefers a ``short_description`` on the view callable (Django's own |
| 99 | + convention for naming admin callables); falls back to humanising the |
| 100 | + route name — ``capfirst(name.replace("_", " "))``. The model/app |
| 101 | + prefix that ``get_urls`` bakes into the name (``<app>_<model>_``) is |
| 102 | + stripped first so the label reads as the *action* (e.g. |
| 103 | + ``"Send report"``) rather than the wiring. |
| 104 | + """ |
| 105 | + callback = getattr(entry, "callback", None) |
| 106 | + short = getattr(callback, "short_description", None) |
| 107 | + if short: |
| 108 | + return str(short) |
| 109 | + return str(capfirst(name.replace("_", " "))) |
| 110 | + |
| 111 | + |
| 112 | +def _reverse_or_none(admin_site: Any, name: str, args: list[Any]) -> str | None: |
| 113 | + """Reverse ``<admin_site.name>:<name>`` with ``args``, or ``None``. |
| 114 | +
|
| 115 | + Guards every reverse: an un-reversible route (legacy admin not |
| 116 | + mounted, a route needing more args than we supply, a custom |
| 117 | + namespace quirk) degrades to ``None`` and is dropped by the caller. |
| 118 | + """ |
| 119 | + site_name = getattr(admin_site, "name", None) |
| 120 | + if not site_name: |
| 121 | + return None |
| 122 | + try: |
| 123 | + return reverse(f"{site_name}:{name}", args=args) |
| 124 | + except Exception: |
| 125 | + return None |
| 126 | + |
| 127 | + |
| 128 | +def custom_views_for( |
| 129 | + model_admin: ModelAdmin, |
| 130 | + admin_site: Any, |
| 131 | + *, |
| 132 | + obj: Model | None = None, |
| 133 | +) -> list[dict[str, Any]]: |
| 134 | + """Custom (non-CRUD) admin views for a ``ModelAdmin`` (Issue #439). |
| 135 | +
|
| 136 | + Walks ``model_admin.get_urls()``, drops the five standard CRUD |
| 137 | + routes (and any unnamed route), and returns a descriptor per |
| 138 | + remaining custom route:: |
| 139 | +
|
| 140 | + {"name": str, "label": str, "url": str, "level": "object"|"changelist"} |
| 141 | +
|
| 142 | + Reversal rules: |
| 143 | +
|
| 144 | + - ``level == "object"`` routes need an object id. When ``obj`` is |
| 145 | + provided they are reversed with ``args=[obj.pk]``; when ``obj`` is |
| 146 | + ``None`` (the registry / changelist context) they are skipped — |
| 147 | + there is no object to point them at. |
| 148 | + - ``level == "changelist"`` routes are reversed with ``args=[]``. |
| 149 | +
|
| 150 | + Returns ``[]`` when the admin exposes no custom routes, or when none |
| 151 | + of them reverse. NEVER raises: a misbehaving consumer ``get_urls`` |
| 152 | + degrades to ``[]`` (so the caller's detail / registry response is |
| 153 | + unaffected). |
| 154 | + """ |
| 155 | + try: |
| 156 | + urls = model_admin.get_urls() |
| 157 | + except Exception: |
| 158 | + return [] |
| 159 | + |
| 160 | + try: |
| 161 | + standard = _standard_route_names(model_admin.model) |
| 162 | + except Exception: |
| 163 | + return [] |
| 164 | + |
| 165 | + out: list[dict[str, Any]] = [] |
| 166 | + for entry in urls: |
| 167 | + descriptor = _descriptor_for_route(entry, standard, admin_site, obj) |
| 168 | + if descriptor is not None: |
| 169 | + out.append(descriptor) |
| 170 | + return out |
| 171 | + |
| 172 | + |
| 173 | +def _descriptor_for_route( |
| 174 | + entry: Any, |
| 175 | + standard: frozenset[str], |
| 176 | + admin_site: Any, |
| 177 | + obj: Model | None, |
| 178 | +) -> dict[str, Any] | None: |
| 179 | + """Build one custom-view descriptor, or ``None`` to skip the route. |
| 180 | +
|
| 181 | + A route is skipped (``None``) when it is unnamed, is a standard CRUD |
| 182 | + route, is object-level but we have no object, fails to reverse, or |
| 183 | + raises during introspection. One bad route never sinks the rest: |
| 184 | + every failure degrades to ``None`` rather than propagating. |
| 185 | + """ |
| 186 | + try: |
| 187 | + name = getattr(entry, "name", None) |
| 188 | + # Unnamed routes (Django's legacy ``<pk>/`` catch-all) and the |
| 189 | + # five standard CRUD routes are not "custom views". |
| 190 | + if not name or name in standard: |
| 191 | + return None |
| 192 | + |
| 193 | + pattern = getattr(entry, "pattern", None) |
| 194 | + object_level = _is_object_level(pattern) if pattern is not None else False |
| 195 | + |
| 196 | + if object_level: |
| 197 | + if obj is None: |
| 198 | + # No object to anchor the route to in this context. |
| 199 | + return None |
| 200 | + url = _reverse_or_none(admin_site, name, [obj.pk]) |
| 201 | + level = "object" |
| 202 | + else: |
| 203 | + url = _reverse_or_none(admin_site, name, []) |
| 204 | + level = "changelist" |
| 205 | + |
| 206 | + if url is None: |
| 207 | + return None |
| 208 | + |
| 209 | + return { |
| 210 | + "name": str(name), |
| 211 | + "label": _label_for_route(entry, str(name)), |
| 212 | + "url": url, |
| 213 | + "level": level, |
| 214 | + } |
| 215 | + except Exception: |
| 216 | + return None |
0 commit comments