polyadmin 0.1.0b1__py3-none-any.whl

polyadmin/core/widget.py

@@ -0,0 +1,280 @@
+"""Widget: a single dashboard tile.
+
+Each type computes its own data via `get_data()` and names the template that
+renders it, so a custom widget is a subclass pointing `template` at its own
+file -- no framework change required. Every widget takes either a static value
+or a `get_*` callable, so an application can wire in live data without the
+widget caring where it came from.
+"""
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from typing import Any
+
+
+class Widget:
+    template = "admin/widgets/widget.html"
+
+    def __init__(self, title: str, *, size: str = "md", permission: str | None = None) -> None:
+        self.title = title
+        self.size = size
+        self.permission = permission
+
+    def get_data(self) -> Any:
+        raise NotImplementedError(f"{type(self).__name__} must implement get_data().")
+
+
+class Metric(Widget):
+    """A single headline number, e.g. "1,204 users"."""
+
+    template = "admin/widgets/metric.html"
+
+    def __init__(
+        self, title: str, *, value: Any = None, get_value: Callable[[], Any] | None = None, **kwargs: Any
+    ) -> None:
+        super().__init__(title, **kwargs)
+        self._value = value
+        self._get_value = get_value
+
+    def get_data(self) -> dict[str, Any]:
+        value = self._get_value() if self._get_value is not None else self._value
+        return {"value": value}
+
+
+class Stat(Widget):
+    """A headline number paired with its change against the previous period.
+    Metric answers "what is it now?"; Stat also answers "which way is it
+    moving?".
+
+    `delta` is the signed percentage change. Up is assumed good; for an
+    inverted metric such as an error rate, negate the delta and say so in the
+    title.
+    """
+
+    template = "admin/widgets/stat.html"
+
+    def __init__(
+        self,
+        title: str,
+        *,
+        value: Any = None,
+        delta: float = 0.0,
+        get_stat: Callable[[], tuple[Any, float]] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(title, **kwargs)
+        self._value = value
+        self._delta = delta
+        self._get_stat = get_stat
+
+    def get_data(self) -> dict[str, Any]:
+        value, delta = (
+            self._get_stat() if self._get_stat is not None else (self._value, self._delta)
+        )
+        # The template branches on `direction`, not the sign of `delta`,
+        # keeping the arrow and colour choice out of the markup. `delta`
+        # is reported unsigned, since the arrow carries the direction.
+        direction = "up" if delta > 0 else "down" if delta < 0 else "flat"
+        return {"value": value, "delta": round(abs(delta), 1), "direction": direction}
+
+
+class Progress(Widget):
+    """A value against a target, e.g. "42 / 100 tasks complete"."""
+
+    template = "admin/widgets/progress.html"
+
+    def __init__(
+        self,
+        title: str,
+        *,
+        value: float = 0,
+        target: float = 100,
+        get_data: Callable[[], tuple[float, float]] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(title, **kwargs)
+        self._value = value
+        self._target = target
+        self._get_data = get_data
+
+    def get_data(self) -> dict[str, Any]:
+        value, target = self._get_data() if self._get_data is not None else (self._value, self._target)
+        percent = 0 if target <= 0 else min(100, round(value / target * 100))
+        return {"value": value, "target": target, "percent": percent}
+
+
+class Table(Widget):
+    """Small tabular data: columns + rows (each row a dict keyed by column)."""
+
+    template = "admin/widgets/table.html"
+
+    def __init__(
+        self,
+        title: str,
+        *,
+        columns: Sequence[str] = (),
+        rows: Sequence[dict[str, Any]] = (),
+        get_rows: Callable[[], Sequence[dict[str, Any]]] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(title, **kwargs)
+        self.columns = list(columns)
+        self._rows = list(rows)
+        self._get_rows = get_rows
+
+    def get_data(self) -> dict[str, Any]:
+        rows = self._get_rows() if self._get_rows is not None else self._rows
+        return {"columns": self.columns, "rows": list(rows)}
+
+
+class Chart(Widget):
+    """Labeled values rendered as simple CSS bars -- no charting-library
+    dependency, since the framework ships with none."""
+
+    template = "admin/widgets/chart.html"
+
+    def __init__(
+        self,
+        title: str,
+        *,
+        series: Sequence[tuple[str, float]] = (),
+        get_series: Callable[[], Sequence[tuple[str, float]]] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(title, **kwargs)
+        self._series = list(series)
+        self._get_series = get_series
+
+    def get_data(self) -> dict[str, Any]:
+        series = list(self._get_series() if self._get_series is not None else self._series)
+        maximum = max((value for _, value in series), default=0) or 1
+        return {"series": [(label, value, round(value / maximum * 100)) for label, value in series]}
+
+
+# The qualitative palette for Donut slices, spaced around the wheel so six
+# categories stay distinguishable. They name theme.html's --chart-*
+# variables rather than literal shades, so a Donut follows the active
+# theme and is re-tuned for dark mode. No slice lands on the
+# success/warning/danger hues, so it cannot be mistaken for a status.
+_DONUT_COLORS = ("chart-1", "chart-2", "chart-3", "chart-4", "chart-5", "chart-6")
+
+
+class Donut(Widget):
+    """A share-of-total breakdown drawn as an SVG ring with a legend, built from
+    <circle> arcs -- the same no-charting-library stance as Chart.
+    """
+
+    template = "admin/widgets/donut.html"
+
+    def __init__(
+        self,
+        title: str,
+        *,
+        series: Sequence[tuple[str, float]] = (),
+        get_series: Callable[[], Sequence[tuple[str, float]]] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(title, **kwargs)
+        self._series = list(series)
+        self._get_series = get_series
+
+    def get_data(self) -> dict[str, Any]:
+        series = list(self._get_series() if self._get_series is not None else self._series)
+        total = sum(value for _, value in series)
+        slices = []
+        cumulative = 0.0
+        for i, (label, value) in enumerate(series):
+            percent = 0.0 if total <= 0 else value / total * 100
+            slices.append(
+                {
+                    "label": label,
+                    "value": value,
+                    "percent": round(percent, 1),
+                    # A circle of circumference 100 (r=15.9155) lets
+                    # stroke-dasharray take percentages directly. 25
+                    # rotates the first slice to 12 o'clock; each later
+                    # one is pushed by its predecessors' combined share.
+                    "dash_offset": round(25 - cumulative, 4),
+                    "color": _DONUT_COLORS[i % len(_DONUT_COLORS)],
+                }
+            )
+            cumulative += percent
+        return {"slices": slices, "total": total}
+
+
+class Activity(Widget):
+    """A recent-activity feed: a list of short text entries."""
+
+    template = "admin/widgets/activity.html"
+
+    def __init__(
+        self,
+        title: str,
+        *,
+        entries: Sequence[str] = (),
+        get_entries: Callable[[], Sequence[str]] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(title, **kwargs)
+        self._entries = list(entries)
+        self._get_entries = get_entries
+
+    def get_data(self) -> dict[str, Any]:
+        entries = self._get_entries() if self._get_entries is not None else self._entries
+        return {"entries": list(entries)}
+
+
+class Timeline(Widget):
+    """A vertical feed of dated events drawn as a rail of dots. Activity's flat
+    strings suit a short "who did what" list; Timeline is for entries needing a
+    timestamp and a body of their own.
+
+    Entries are `(time, title, description)` triples. `time` arrives already
+    formatted: the widget never parses or localizes it, so the application
+    controls how its timestamps read.
+    """
+
+    template = "admin/widgets/timeline.html"
+
+    def __init__(
+        self,
+        title: str,
+        *,
+        entries: Sequence[tuple[str, str, str]] = (),
+        get_entries: Callable[[], Sequence[tuple[str, str, str]]] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(title, **kwargs)
+        self._entries = list(entries)
+        self._get_entries = get_entries
+
+    def get_data(self) -> dict[str, Any]:
+        entries = self._get_entries() if self._get_entries is not None else self._entries
+        return {
+            "entries": [
+                {"time": time, "title": title, "description": description}
+                for time, title, description in entries
+            ]
+        }
+
+
+class Tabs(Widget):
+    """Several widgets stacked into one card, one visible at a time.
+
+    Panels are `(label, widget)` pairs. Tabs holds no data itself, and every
+    panel is computed on render rather than on first click, so a panel backed
+    by a slow query costs the same whether or not anyone opens it.
+    """
+
+    template = "admin/widgets/tabs.html"
+
+    def __init__(
+        self, title: str, *, panels: Sequence[tuple[str, Widget]] = (), **kwargs: Any
+    ) -> None:
+        super().__init__(title, **kwargs)
+        self.panels = list(panels)
+
+    def get_data(self) -> dict[str, Any]:
+        # Handed to the template, which renders each through the same `{%
+        # include widget.template %}` the dashboard uses.
+        return {"panels": [{"label": label, "widget": widget} for label, widget in self.panels]}

polyadmin/fastapi/__init__.py

@@ -0,0 +1,3 @@
+from polyadmin.fastapi.router import create_router
+
+__all__ = ["create_router"]

polyadmin/fastapi/audit.py

@@ -0,0 +1,52 @@
+"""Recording changes into the configured audit logger."""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timezone
+from typing import Any
+
+from polyadmin.core.audit import AuditEntry
+from polyadmin.core.model_admin import ModelAdmin
+
+logger = logging.getLogger("polyadmin")
+
+
+def object_label(model_admin: ModelAdmin, obj: Any) -> str:
+    """A short human label for an object, matching the breadcrumb rule:
+    the first search field, else the first list column, else the pk.
+    """
+    names = list(model_admin.search_fields) or list(model_admin.list_display)
+    for name in names:
+        try:
+            return str(model_admin.get_field(name).get_value(obj))
+        except KeyError:
+            continue
+    return str(model_admin.get_pk(obj))
+
+
+def record_audit(admin: Any, principal: Any, model_admin: ModelAdmin, action: str, obj: Any) -> None:
+    """Write one entry, if a logger is configured at all.
+
+    Called after the change has already succeeded, so a logger error is
+    reported and dropped rather than raised: failing the request here
+    would show the user an error beside a change that did happen, which
+    is worse than a missing log line. The label is captured now because
+    the record may be gone by the time anyone reads the entry.
+    """
+    if admin.audit_logger is None:
+        return
+    entry = AuditEntry(
+        at=datetime.now(timezone.utc),
+        principal=principal,
+        action=action,
+        resource=model_admin.get_slug(),
+        object_pk=model_admin.get_pk(obj) if obj is not None else None,
+        object_label=object_label(model_admin, obj) if obj is not None else "",
+    )
+    try:
+        admin.audit_logger.record(entry)
+    except Exception as exc:  # noqa: BLE001 -- see the docstring
+        logger.warning(
+            "audit log rejected a %s on %s: %s", action, model_admin.get_slug(), exc
+        )

polyadmin/fastapi/auth.py

@@ -0,0 +1,112 @@
+"""Authentication and authorization wiring for the FastAPI adapter. With no
+authenticator or authorizer configured, these are no-ops: every request is
+treated as authenticated and permitted.
+"""
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import quote
+
+from fastapi import Request
+from fastapi.responses import Response
+
+from polyadmin.core.admin import Admin
+from polyadmin.core.authorization import resource_permission
+from polyadmin.core.login import LOGIN_PATH, NEXT_QUERY_PARAM
+from polyadmin.core.model_admin import ModelAdmin
+from polyadmin.fastapi.errors import forbidden, unauthenticated
+from polyadmin.fastapi.locale import acached_principal
+from polyadmin.fastapi.responses import redirect
+
+
+async def authorize(
+    admin: Admin, request: Request, base_path: str, permission: str, resource: Any = None
+) -> tuple[Any, Response | None]:
+    """Returns (principal, None) if the request may proceed, or (None,
+    error_response) if it was rejected.
+
+    Which answer the unauthenticated case gets depends on whether there is a
+    login page to offer: with a login_backend the browser is redirected there
+    carrying where it was going, without one 401 is the whole story. Forbidden
+    never redirects -- the visitor is signed in and simply may not do this, so
+    a login form would invite them to re-authenticate as the same person to the
+    same refusal.
+    """
+    principal = None
+    if admin.authenticator is not None:
+        principal = await acached_principal(admin, request)
+        if principal is None:
+            if admin.login_backend is None:
+                return None, unauthenticated(request, admin, base_path)
+            # redirect(), not a bare 303: an expired session usually
+            # surfaces mid-page on an htmx request, where a 303 would be
+            # swapped in as content.
+            return None, redirect(request, login_url(base_path, _requested_url(request)))
+
+    if admin.authorizer is not None and not admin.authorizer.can(principal, permission, resource):
+        return None, forbidden(request, admin, base_path)
+
+    return principal, None
+
+
+def login_url(base_path: str, next_url: str = "") -> str:
+    """The path an unauthenticated visitor is sent to, carrying where
+    they were headed so signing in resumes it."""
+    target = f"{base_path}{LOGIN_PATH}"
+    if not next_url:
+        return target
+    return f"{target}?{NEXT_QUERY_PARAM}={quote(next_url, safe='')}"
+
+
+def _requested_url(request: Request) -> str:
+    """The path (with query) the current request was for -- what a
+    redirect to login should come back to."""
+    target = request.url.path
+    if request.url.query:
+        target += f"?{request.url.query}"
+    return target
+
+
+def authorize_object(admin: Admin, principal: Any, permission: str, obj: Any) -> bool:
+    """Re-run a permission check with the loaded record as the resource, so an
+    Authorizer can answer "may this principal touch this record" and not only
+    "this model at all".
+
+    The narrower of two gates: the coarse check already ran before the record
+    was fetched, so an unauthorized principal never costs a lookup.
+    """
+    if admin.authorizer is None:
+        return True
+    return admin.authorizer.can(principal, permission, obj)
+
+
+def compute_permissions(
+    admin: Admin, principal: Any, model_admin: ModelAdmin, obj: Any = None
+) -> dict[str, bool]:
+    """What the principal may do with this resource, combining the ModelAdmin's
+    static can_* toggles with the Authorizer's per-request decision. It decides
+    which controls the templates show; the routes enforce this independently,
+    so hiding a control is a UX nicety, not the security boundary.
+    """
+    slug = model_admin.get_slug()
+
+    def allowed(capability: bool, action: str) -> bool:
+        if not capability:
+            return False
+        if admin.authorizer is None:
+            return True
+        # obj is the record in view, or None on a list or create page.
+        # When present it is what the authorizer is asked about, so per-
+        # object rules decide which controls that record's pages show.
+        resource = model_admin if obj is None else obj
+        return admin.authorizer.can(principal, resource_permission(slug, action), resource)
+
+    # Keys are "can_view" etc -- see default_permissions in
+    # template_context.py for why "update" alone is unsafe here.
+    return {
+        "can_view": allowed(model_admin.can_view, "view"),
+        "can_create": allowed(model_admin.can_create, "create"),
+        "can_update": allowed(model_admin.can_update, "update"),
+        "can_delete": allowed(model_admin.can_delete, "delete"),
+        "can_export": allowed(model_admin.can_export, "export"),
+    }

polyadmin/fastapi/csrf.py

@@ -0,0 +1,93 @@
+"""Double-submit CSRF protection for the admin router.
+
+Implemented as a custom APIRoute rather than a dependency: every handler
+here returns an HTMLResponse or RedirectResponse *directly*, and FastAPI
+does not merge a dependency's response headers into a response the
+handler returned itself -- the cookie would be silently dropped. A route
+class wraps the endpoint and post-processes the real response, which is
+the idiomatic seam for this.
+
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from fastapi import Request, Response
+from fastapi.routing import APIRoute
+
+from polyadmin.core.csrf import (
+    CSRF_COOKIE_NAME,
+    CSRF_FIELD_NAME,
+    CSRF_HEADER_NAME,
+    csrf_tokens_match,
+    is_safe_method,
+    new_csrf_token,
+)
+from polyadmin.fastapi.errors import csrf_failure
+
+
+def make_csrf_route(admin, base_path: str) -> type[APIRoute]:
+    """Build the APIRoute subclass for one mounted admin."""
+
+    class CSRFRoute(APIRoute):
+        def get_route_handler(self) -> Callable:
+            original = super().get_route_handler()
+
+            async def handler(request: Request) -> Response:
+                cookie_token = request.cookies.get(CSRF_COOKIE_NAME)
+                token = cookie_token or new_csrf_token()
+                # Handlers and the renderer read the token from here.
+                request.state.csrf_token = token
+
+                if not admin.disable_csrf and not is_safe_method(request.method):
+                    submitted = request.headers.get(CSRF_HEADER_NAME)
+                    if not submitted:
+                        # Starlette caches the parsed form, so the handler
+                        # can still read it afterwards.
+                        form = await request.form()
+                        submitted = form.get(CSRF_FIELD_NAME)
+                    # Compared against the cookie, not against `token`:
+                    # `token` falls back to a freshly minted value, which
+                    # an attacker could never have echoed back but which a
+                    # confused client might. No cookie means no match.
+                    if not csrf_tokens_match(submitted, cookie_token):
+                        response = csrf_failure(request, admin, base_path)
+                        _decorate(response, token, cookie_token, request, base_path)
+                        return response
+
+                response = await original(request)
+                _decorate(response, token, cookie_token, request, base_path)
+                return response
+
+            return handler
+
+    return CSRFRoute
+
+
+def _decorate(
+    response: Response,
+    token: str,
+    cookie_token: str | None,
+    request: Request,
+    base_path: str,
+) -> None:
+    """Set the token cookie (when new) and the clickjacking headers.
+
+    The headers are unconditional: framing is a different attack from
+    forgery, so the CSRF opt-out does not disable them.
+    """
+    response.headers["X-Frame-Options"] = "DENY"
+    response.headers["Content-Security-Policy"] = "frame-ancestors 'none'"
+    if cookie_token is None:
+        response.set_cookie(
+            CSRF_COOKIE_NAME,
+            token,
+            path=base_path,
+            httponly=True,
+            samesite="lax",
+            # Secure only over TLS: a Secure cookie is not sent over plain
+            # HTTP, which would break running the example on a LAN
+            # address. Behind a proxy this needs X-Forwarded-Proto.
+            secure=request.url.scheme == "https",
+        )

polyadmin/fastapi/deletes.py

@@ -0,0 +1,76 @@
+"""delete_selected's confirmation step when the ModelAdmin previews deletes
+(docs/deletes.md)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import Request
+from fastapi.responses import HTMLResponse
+
+from polyadmin.core.delete import (
+    DELETE_PREVIEW_SAMPLE,
+    resolve_delete_preview,
+    selection_fingerprint,
+)
+from polyadmin.core.template_context import _object_label
+from polyadmin.fastapi.auth import compute_permissions
+
+CONFIRMED_FIELD = "_confirmed"
+FINGERPRINT_FIELD = "_fingerprint"
+RETURN_FIELD = "_return"
+
+
+def confirm_delete_selected(
+    request: Request,
+    form: Any,
+    admin: Any,
+    model_admin: Any,
+    renderer: Any,
+    principal: Any,
+    objects: list[Any],
+    select_all: bool,
+    return_to: str,
+    list_request: Any,
+    base_path: str,
+) -> HTMLResponse | None:
+    """Answer with the confirmation page (deleting nothing), or return None when
+    the confirmed, unchanged, unblocked selection may be deleted."""
+    fingerprint = selection_fingerprint(model_admin, objects)
+    confirmed = bool(form.get(CONFIRMED_FIELD))
+    changed = confirmed and select_all and form.get(FINGERPRINT_FIELD) != fingerprint
+    preview = resolve_delete_preview(admin, model_admin, principal, objects)
+    if confirmed and not changed and not preview.blocked:
+        return None
+    slug = model_admin.get_slug()
+    # Built here rather than in the context builder: the per-object view check
+    # lives in the adapter, and core must not import one.
+    items = [
+        {
+            "label": _object_label(model_admin, obj),
+            "url": f"{base_path}/{slug}/{model_admin.get_pk(obj)}"
+            if compute_permissions(admin, principal, model_admin, obj)["can_view"]
+            else None,
+        }
+        for obj in objects[:DELETE_PREVIEW_SAMPLE]
+    ]
+    selection = {
+        "objects": objects,
+        "select_all": select_all,
+        "pks": [] if select_all else [str(model_admin.get_pk(obj)) for obj in objects],
+        "list_request": list_request,
+        "fingerprint": fingerprint,
+        "return_to": return_to,
+        "changed": changed,
+        "items": items,
+    }
+    html = renderer.render_delete_selected(
+        admin,
+        model_admin,
+        selection,
+        preview,
+        base_path=base_path,
+        principal=principal,
+        csrf_token=request.state.csrf_token,
+    )
+    return HTMLResponse(html)