polyadmin 0.1.0b1__py3-none-any.whl

polyadmin/fastapi/inlines.py

@@ -0,0 +1,177 @@
+"""Inline-aware helpers for the FastAPI adapter -- builds the render
+context for a ModelAdmin's declared `inlines` (see core/inline.py) and
+validates those declarations at router-mount time.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from polyadmin.core.admin import Admin
+from polyadmin.core.authorization import resource_permission
+from polyadmin.core.inline import Inline, afilter_inline_children
+from polyadmin.core.model_admin import ModelAdmin
+from polyadmin.fastapi.auth import compute_permissions
+from polyadmin.fastapi.relations import compute_relation_options
+
+
+def inline_label(admin: Admin, inline: Inline) -> str:
+    child_admin = admin.get_model_admin(inline.child)
+    return inline.label or f"{child_admin.get_verbose_name()}s"
+
+
+def validate_inlines(admin: Admin, model_admin: ModelAdmin) -> None:
+    """The two startup invariants an `Inline` declaration must satisfy
+    -- run once per registered ModelAdmin at router-mount time (after
+    every ModelAdmin is registered, so cross-admin lookups resolve),
+    before any request is served. Mirrors Admin.register's
+    fail-fast-on-duplicate-slug precedent.
+    """
+    parent_slug = model_admin.get_slug()
+    seen: set[str] = set()
+    for inline in model_admin.inlines:
+        if inline.child in seen:
+            raise ValueError(f"{parent_slug!r} declares more than one inline for child {inline.child!r}.")
+        seen.add(inline.child)
+
+        try:
+            child_admin = admin.get_model_admin(inline.child)
+        except KeyError:
+            raise ValueError(f"{parent_slug!r}'s inline references unknown child {inline.child!r}.") from None
+
+        try:
+            field = child_admin.get_field(inline.fk_field)
+        except KeyError:
+            field = None
+        relation = getattr(field, "relation", None) if field is not None else None
+        if (
+            field is None
+            or relation is None
+            or field.field_type not in ("foreignkey", "onetoone")
+            or relation.target != parent_slug
+        ):
+            raise ValueError(
+                f"{parent_slug!r}'s inline fk_field {inline.fk_field!r} on child {inline.child!r} must be "
+                f"a ForeignKeyField/OneToOneField whose relation targets {parent_slug!r}."
+            )
+
+
+def _pk_column(child_admin: Any, field_names: list[str]) -> str | None:
+    """The field whose value is the record's primary key, or the first
+    field when none is shown. None when there are no columns at all.
+
+    get_pk() reads a value, not a field name -- a ModelAdmin may override
+    it -- so the column is found by asking a probe object which attribute
+    the two agree on.
+    """
+    if not field_names:
+        return None
+    probe = getattr(child_admin, "model", None)
+    for name in field_names:
+        # A ModelAdmin's get_pk defaults to `.id`; a name that resolves to
+        # the same attribute is the primary key's column.
+        if name == "id" or (probe is not None and getattr(probe, "pk_field", None) == name):
+            return name
+    return field_names[0]
+
+
+async def build_inline_context(
+    admin: Admin,
+    principal: Any,
+    model_admin: ModelAdmin,
+    obj: Any | None,
+    mode: str,
+    base_path: str,
+    *,
+    redisplay: dict[str, Any] | None = None,
+) -> list[dict[str, Any]]:
+    """One entry per `model_admin.inlines` the current principal may
+    view at all -- an entry is omitted entirely (the whole section
+    hidden, not just its controls) if the principal lacks the child's
+    own `.view` permission, same principle as relation-link hiding
+    elsewhere in the framework.
+
+    `mode` is "placeholder" (create page -- no parent pk yet, no rows
+    or add-form built), "edit" (rows + a persistent blank add-row, all
+    editable), or "readonly" (rows only, using the child's
+    detail_fields, no add/edit/remove controls).
+
+    `redisplay`, when given, is `{"pk": child_pk_or_None, "data":...,
+    "errors":...}` for the one row (or the add-row, if pk is None)
+    being redisplayed after a failed inline mutation.
+    """
+    sections: list[dict[str, Any]] = []
+    for inline in model_admin.inlines:
+        try:
+            child_admin = admin.get_model_admin(inline.child)
+        except KeyError:
+            continue
+        if not child_admin.can_view:
+            continue
+        if admin.authorizer is not None and not admin.authorizer.can(
+            principal, resource_permission(inline.child, "view"), child_admin
+        ):
+            continue
+
+        child_perms = compute_permissions(admin, principal, child_admin)
+        field_names = [name for name in child_admin.get_form_fields() if name != inline.fk_field]
+        detail_field_names = [name for name in child_admin.get_detail_fields() if name != inline.fk_field]
+        # Which readonly column opens the record. The primary key's own
+        # column when it is shown -- an id is the one cell that is never a
+        # link already and never wraps -- and the first column otherwise,
+        # so a row is always reachable. See the readonly table in
+        # components/inline.html.
+        link_field = _pk_column(child_admin, detail_field_names)
+
+        rows: list[dict[str, Any]] = []
+        add_row: dict[str, Any] | None = None
+        if mode != "placeholder":
+            parent_pk = model_admin.get_pk(obj)
+            children = await afilter_inline_children(child_admin, inline.fk_field, model_admin, parent_pk)
+            for child_obj in children:
+                child_pk = child_admin.get_pk(child_obj)
+                row_redisplay = (
+                    redisplay
+                    if redisplay is not None and redisplay.get("pk") is not None and str(redisplay["pk"]) == str(child_pk)
+                    else None
+                )
+                row_options = await compute_relation_options(admin, child_admin, obj=child_obj) if mode == "edit" else {}
+                rows.append(
+                    {
+                        "pk": child_pk,
+                        "obj": child_obj,
+                        "data": row_redisplay["data"] if row_redisplay else None,
+                        "errors": row_redisplay["errors"] if row_redisplay else {},
+                        "relation_options": row_options,
+                        "update_url": f"{base_path}/{model_admin.get_slug()}/{parent_pk}/inlines/{inline.child}/{child_pk}",
+                        "delete_url": f"{base_path}/{model_admin.get_slug()}/{parent_pk}/inlines/{inline.child}/{child_pk}",
+                        "detail_url": f"{base_path}/{inline.child}/{child_pk}",
+                    }
+                )
+            if mode == "edit" and child_perms["can_create"]:
+                add_redisplay = redisplay if redisplay is not None and redisplay.get("pk") is None else None
+                add_row = {
+                    "data": add_redisplay["data"] if add_redisplay else None,
+                    "errors": add_redisplay["errors"] if add_redisplay else {},
+                    "relation_options": await compute_relation_options(admin, child_admin),
+                    "create_url": f"{base_path}/{model_admin.get_slug()}/{parent_pk}/inlines/{inline.child}",
+                }
+
+        sections.append(
+            {
+                "slug": inline.child,
+                "label": inline_label(admin, inline),
+                # The child's own placeholder, not the parent's.
+                "empty_value": child_admin.get_empty_value(),
+                "layout": inline.layout,
+                "mode": mode,
+                "child_admin": child_admin,
+                "field_names": field_names,
+                "detail_field_names": detail_field_names,
+                "link_field": link_field,
+                "can_change": child_perms["can_update"],
+                "can_delete": child_perms["can_delete"],
+                "rows": rows,
+                "add_row": add_row,
+            }
+        )
+    return sections

polyadmin/fastapi/locale.py

@@ -0,0 +1,128 @@
+"""Per-request locale resolution and the language switcher's route."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from fastapi import Request, Response
+from fastapi.routing import APIRoute
+
+from polyadmin.core._async import maybe_await
+from polyadmin.core.csrf import safe_redirect_path
+from polyadmin.fastapi.csrf import make_csrf_route
+from polyadmin.fastapi.responses import redirect
+from polyadmin.i18n import I18n, use_locale
+
+LOCALE_COOKIE_NAME = "admin_locale"
+LOCALE_FORM_FIELD = "locale"
+LOCALE_COOKIE_MAX_AGE = 365 * 24 * 60 * 60
+
+_UNSET = object()
+
+
+def cached_principal(admin: Any, request: Request) -> Any:
+    """Authenticate at most once per request: resolving the locale may
+    already have, to hand a locale_resolver the principal."""
+    if admin.authenticator is None:
+        return None
+    cached = getattr(request.state, "principal_cache", _UNSET)
+    if cached is _UNSET:
+        cached = admin.authenticator.authenticate(request)
+        request.state.principal_cache = cached
+    return cached
+
+
+async def acached_principal(admin: Any, request: Request) -> Any:
+    """Async counterpart of cached_principal, for an Authenticator whose
+    authenticate() is a coroutine function.
+
+    Shares the same request.state.principal_cache slot as cached_principal,
+    so whichever one runs first for a given request caches the answer for
+    the other. cached_principal itself is untouched: it is still what the
+    locale_resolver path uses (see resolve_request_locale below), which
+    runs outside any event loop and cannot await -- combining an async
+    Authenticator with a configured locale_resolver is unsupported.
+    """
+    if admin.authenticator is None:
+        return None
+    cached = getattr(request.state, "principal_cache", _UNSET)
+    if cached is _UNSET:
+        cached = await maybe_await(admin.authenticator.authenticate(request))
+        request.state.principal_cache = cached
+    return cached
+
+
+def switcher_on(admin: Any, i18n: I18n) -> bool:
+    """Whether the language switcher (and its route) is on: enabled, and
+    more than one locale to choose from."""
+    return bool(admin.locale_switcher) and len(i18n.supported) > 1
+
+
+def resolve_request_locale(admin: Any, i18n: I18n, request: Request) -> str:
+    """The request's locale. The admin_locale cookie counts only while the
+    switcher is on: with it off nothing in the admin can change the
+    cookie, so a leftover one must not override the resolver or the
+    browser."""
+    resolver = None
+    if admin.locale_resolver is not None:
+
+        def resolver() -> str | None:
+            return admin.locale_resolver(request, cached_principal(admin, request))
+
+    cookie = request.cookies.get(LOCALE_COOKIE_NAME) if switcher_on(admin, i18n) else None
+    return i18n.resolve(cookie, resolver, request.headers.get("accept-language"))
+
+
+def make_admin_route(admin: Any, base_path: str, i18n: I18n, renderer: Any) -> type[APIRoute]:
+    """The route class for one mounted admin: the locale is resolved and
+    installed first, then CSRF runs, so even its failure page is localised.
+
+    A route class, like CSRF's, rather than a dependency: it wraps the
+    handler's whole execution, so the context variable is set for the
+    handler and everything it calls, and reset afterwards.
+    """
+    csrf_route = make_csrf_route(admin, base_path)
+
+    class AdminRoute(csrf_route):
+        def get_route_handler(self) -> Callable:
+            inner = super().get_route_handler()
+
+            async def handler(request: Request) -> Response:
+                locale = resolve_request_locale(admin, i18n, request)
+                request.state.locale = locale
+                request.state.renderer = renderer
+                with use_locale(locale, i18n.translator):
+                    return await inner(request)
+
+            return handler
+
+    return AdminRoute
+
+
+def build_locale_handler(i18n: I18n, base_path: str) -> Callable:
+    """POST {base}/locale: store the switcher's choice, go back.
+
+    An unsupported value is ignored rather than refused: the redirect is
+    the same either way, and there is nothing to explain."""
+
+    async def handler(request: Request) -> Response:
+        form = await request.form()
+        # The fallback is the admin root: "/" when mounted at the site root.
+        root = base_path or "/"
+        target = safe_redirect_path(request.headers.get("referer"), request.url.netloc, base_path, root)
+        response = redirect(request, target)
+        locale = i18n.match(form.get(LOCALE_FORM_FIELD))
+        if locale:
+            response.set_cookie(
+                LOCALE_COOKIE_NAME,
+                locale,
+                max_age=LOCALE_COOKIE_MAX_AGE,
+                path=base_path or "/",
+                httponly=True,
+                samesite="lax",
+                secure=request.url.scheme == "https",
+            )
+        return response
+
+    return handler

polyadmin/fastapi/login.py

@@ -0,0 +1,110 @@
+"""The login page's handlers."""
+
+from __future__ import annotations
+
+import logging
+
+from fastapi import Request
+from fastapi.responses import HTMLResponse, RedirectResponse, Response
+
+from polyadmin.core._async import maybe_await
+from polyadmin.core.admin import Admin
+from polyadmin.core.login import NEXT_QUERY_PARAM, safe_next_url
+from polyadmin.fastapi.locale import acached_principal
+from polyadmin.fastapi.responses import redirect
+from polyadmin.i18n import N_, gettext
+from polyadmin.templating import Renderer
+
+logger = logging.getLogger("polyadmin")
+
+# The two messages the login page can show. INVALID_CREDENTIALS is
+# deliberately one message for both "no such user" and "wrong password":
+# telling them apart turns the form into an account enumerator.
+# core.login.LoginBackend asks implementations not to distinguish them
+# either, for the same reason.
+INVALID_CREDENTIALS = N_("That email and password don't match an account.")
+SIGNED_OUT = N_("You have been signed out.")
+SESSION_FAILED = N_("Sign-in could not be completed. Please try again.")
+
+
+def build_login_handlers(admin: Admin, renderer: Renderer, base_path: str):
+    """The GET and POST for the login page.
+
+    These are two of only three routes in a mounted admin that run
+    without authenticating (the third is logout), since requiring a
+    session to reach the page that creates one is a loop.
+    """
+
+    def _page(request: Request, *, identifier: str = "", error: str = "", notice: str = "", status: int = 200) -> HTMLResponse:
+        html = renderer.render_login(
+            admin,
+            csrf_token=request.state.csrf_token,
+            identifier=identifier,
+            error=error,
+            notice=notice,
+            base_path=base_path,
+        )
+        return HTMLResponse(html, status_code=status)
+
+    async def login_get(request: Request) -> Response:
+        # Already signed in: nothing here to do, so honour ?next= and
+        # send them on rather than showing a form they would have to
+        # pointlessly fill in.
+        if await acached_principal(admin, request) is not None:
+            return RedirectResponse(
+                safe_next_url(request.query_params.get(NEXT_QUERY_PARAM), base_path), status_code=303
+            )
+        notice = gettext(SIGNED_OUT) if request.query_params.get("signedout") == "1" else ""
+        return _page(request, notice=notice)
+
+    async def login_post(request: Request) -> Response:
+        # CSRF is already enforced -- the router's route_class covers
+        # every route, this one included, and the GET above is what mints
+        # the cookie the form echoes back.
+        form = await request.form()
+        identifier = str(form.get("identifier") or "")
+        password = str(form.get("password") or "")
+        next_url = safe_next_url(request.query_params.get(NEXT_QUERY_PARAM), base_path)
+
+        principal = await maybe_await(admin.login_backend.verify_credentials(request, identifier, password))
+        if principal is None:
+            # 401, not 200: a failed sign-in is a failed sign-in, and the
+            # status is what a log or a rate limiter in front of this
+            # reads. The body is still the form.
+            return _page(request, identifier=identifier, error=gettext(INVALID_CREDENTIALS), status=401)
+
+        response = RedirectResponse(next_url, status_code=303)
+        try:
+            # The response is handed over so the backend can set a cookie
+            # on it. This is the one place the two implementations'
+            # signatures differ: Fiber's ctx is both request and
+            # response, while Starlette has no "current response" to
+            # reach for -- see core/login.py.
+            await maybe_await(admin.login_backend.begin_session(request, principal, response))
+        except Exception as exc:  # noqa: BLE001 -- see below
+            # The credentials were right but the session could not be
+            # stored, so the visitor is not signed in and must not be
+            # told they are. Logged for the operator, generic on screen.
+            logger.warning("begin_session failed for %s: %s", principal.id, exc)
+            return _page(request, identifier=identifier, error=gettext(SESSION_FAILED), status=500)
+        return response
+
+    return login_get, login_post
+
+
+def build_logout_handler(admin: Admin, base_path: str):
+    """POST-only (see the route table): a logout reachable by GET is one
+    any <img src> on the internet can trigger."""
+
+    async def logout(request: Request) -> Response:
+        response = redirect(request, f"{base_path}/login?signedout=1")
+        try:
+            await maybe_await(admin.login_backend.end_session(request, response))
+        except Exception as exc:  # noqa: BLE001 -- see below
+            # Nothing useful to offer the visitor here: they asked to
+            # leave, and the most likely reason this failed is that there
+            # was nothing to clear.
+            logger.warning("end_session failed: %s", exc)
+        return response
+
+    return logout

polyadmin/fastapi/pages.py

@@ -0,0 +1,97 @@
+"""FastAPI wiring for AdminPage: a custom admin route with its own
+template and handler, for functionality that isn't resource CRUD
+(reports, wizards, internal tools). See docs/routing.md.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from fastapi import Request
+from fastapi.responses import HTMLResponse, Response
+
+from polyadmin.core.admin import Admin
+from polyadmin.core.page import AdminPage
+from polyadmin.core.template_context import base_context, category_breadcrumb
+from polyadmin.fastapi.auth import authorize
+from polyadmin.fastapi.responses import (
+    clear_flash,
+    is_htmx_request,
+    pop_flash,
+    redirect,
+    set_flash,
+)
+from polyadmin.i18n import gettext
+from polyadmin.templating import Renderer
+
+
+@dataclass
+class PageContext:
+    """What an AdminPage's handler receives -- the raw Request (for
+    form/query parsing, exactly like any other FastAPI handler) plus
+    render/redirect helpers reusing the framework's own layout, flash
+    cookie, and HTMX-aware redirect.
+    """
+
+    admin: Admin
+    page: AdminPage
+    request: Request
+    principal: Any
+    renderer: Renderer
+    base_path: str
+
+    @property
+    def is_htmx(self) -> bool:
+        return is_htmx_request(self.request)
+
+    async def form(self) -> Any:
+        return await self.request.form()
+
+    def render(self, template_name: str, *, status_code: int = 200, **extra: Any) -> HTMLResponse:
+        """Render template_name (an application-supplied template
+        extending "admin/base.html", resolved via the same
+        template_dirs search Jinja already uses for resource
+        overrides) inside the shared admin layout.
+        """
+        context = {
+            **base_context(
+                self.admin,
+                base_path=self.base_path,
+                messages=pop_flash(self.request),
+                breadcrumbs=[
+                    *category_breadcrumb(self.page.category),
+                    {"label": gettext(self.page.label), "url": None, "active": True},
+                ],
+                active_nav_key=f"page:{self.page.path}",
+                # getattr, not attribute access: mirrors the Fiber
+                # adapter's csrfToken(c), which yields "" rather than
+                # failing if a page is somehow rendered outside the
+                # mounted router that sets it.
+                csrf_token=getattr(self.request.state, "csrf_token", ""),
+            ),
+            "page": self.page,
+            **extra,
+        }
+        html = self.renderer.render(template_name, context)
+        response = HTMLResponse(html, status_code=status_code)
+        clear_flash(response)
+        return response
+
+    def redirect(self, url: str, *, flash: tuple[str, str] | None = None) -> Response:
+        response = redirect(self.request, url)
+        if flash:
+            set_flash(response, *flash)
+        return response
+
+
+def build_page_handler(admin: Admin, page: AdminPage, renderer: Renderer, base_path: str):
+    async def handler(request: Request):
+        principal, error = await authorize(admin, request, base_path, page.permission, page)
+        if error:
+            return error
+        ctx = PageContext(
+            admin=admin, page=page, request=request, principal=principal, renderer=renderer, base_path=base_path
+        )
+        return await page.handler(ctx)
+
+    return handler