polyadmin 0.1.0b1__py3-none-any.whl

polyadmin/fastapi/relations.py

@@ -0,0 +1,264 @@
+"""Relation-aware helpers for the FastAPI adapter."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Any
+
+from polyadmin.core._async import maybe_await
+from polyadmin.core.admin import Admin
+from polyadmin.core.authorization import resource_permission
+from polyadmin.core.field import Field
+from polyadmin.core.filter import FILTER_KIND_RELATION
+from polyadmin.core.model_admin import ModelAdmin
+from polyadmin.core.query import ListRequest, alist_objects
+from polyadmin.core.relation import Relation
+
+
+def _relation_fields(
+    model_admin: ModelAdmin, names: list[str]
+) -> Iterator[tuple[str, Field, Relation]]:
+    for name in names:
+        field = model_admin.get_field(name)
+        relation = getattr(field, "relation", None)
+        if relation is not None:
+            yield name, field, relation
+
+
+def compute_relation_permissions(
+    admin: Admin, principal: Any, model_admin: ModelAdmin, names: list[str]
+) -> dict[str, bool]:
+    """Whether the current principal may view each relation target
+    referenced by `names` -- the admin must not link to an
+    object the principal isn't authorized to see.
+    """
+    result: dict[str, bool] = {}
+    for _, _, relation in _relation_fields(model_admin, names):
+        if relation.target in result:
+            continue
+        try:
+            target_admin = admin.get_model_admin(relation.target)
+        except KeyError:
+            result[relation.target] = False
+            continue
+        if not target_admin.can_view:
+            result[relation.target] = False
+        elif admin.authorizer is None:
+            result[relation.target] = True
+        else:
+            result[relation.target] = admin.authorizer.can(
+                principal, resource_permission(relation.target, "view"), target_admin
+            )
+    return result
+
+
+async def compute_relation_options(
+    admin: Admin, model_admin: ModelAdmin, obj: Any = None
+) -> dict[str, dict[str, Any]]:
+    """Selectable options for each relation field in `model_admin.form_fields`.
+
+    For a field listed in `model_admin.autocomplete_fields`, this skips
+    loading the target's queryset entirely and only resolves the
+    current selection's own label -- the rest of the options are
+    fetched on demand from the /lookup route as the user
+    types, via components/ui/field.html's combobox. Every other relation
+    field keeps populating a same-page <select> from the target's full
+    unfiltered queryset, gated only by its static `can_view` -- coarser
+    than `compute_relation_permissions`, fine for a same-page selector.
+    """
+    autocomplete_names = set(model_admin.autocomplete_fields)
+    result: dict[str, dict[str, Any]] = {}
+    for name, field, relation in _relation_fields(
+        model_admin, model_admin.get_form_fields()
+    ):
+        try:
+            target_admin = admin.get_model_admin(relation.target)
+        except KeyError:
+            continue
+        if not target_admin.can_view:
+            continue
+        display_field = target_admin.get_field(relation.display_field)
+        current = field.get_value(obj) if obj is not None else None
+
+        if name in autocomplete_names and field.field_type in (
+            "foreignkey",
+            "onetoone",
+        ):
+            selected_pk = target_admin.get_pk(current) if current is not None else None
+            selected_label = (
+                display_field.get_value(current) if current is not None else None
+            )
+            result[name] = {
+                "options": [],
+                "selected_pk": selected_pk,
+                "selected_pks": [],
+                "autocomplete": True,
+                "selected_label": selected_label,
+                "lookup_target": relation.target,
+            }
+            continue
+
+        # unlimited: a non-autocomplete relation renders every choice
+        # inline, which is exactly what this widget is for. Going through
+        # alist_objects means a list_page target, or one with async hooks,
+        # answers this from its own data source like every other list query.
+        related_objects, _ = await alist_objects(target_admin, ListRequest(unlimited=True))
+        options = [
+            (target_admin.get_pk(related), display_field.get_value(related))
+            for related in related_objects
+        ]
+        if field.field_type == "manytomany":
+            selected_pks = [target_admin.get_pk(related) for related in (current or [])]
+            result[name] = {
+                "options": options,
+                "selected_pk": None,
+                "selected_pks": selected_pks,
+                "autocomplete": False,
+            }
+        else:
+            selected_pk = target_admin.get_pk(current) if current is not None else None
+            result[name] = {
+                "options": options,
+                "selected_pk": selected_pk,
+                "selected_pks": [],
+                "autocomplete": False,
+            }
+    return result
+
+
+async def relation_filter_choices(
+    admin: Admin, principal: Any, model_admin: ModelAdmin, field: Any
+) -> list[dict[str, str]] | None:
+    """A relation filter's choice list: every record of the target
+    ModelAdmin, as {"value", "label"} pairs.
+
+    None when the principal may not view the target. The caller drops the
+    filter entirely in that case -- an empty filter group reads as a
+    broken control, and a reader who may not see organizations should not
+    be told they exist. This is the principal-aware check, not
+    compute_relation_options' coarser can_view: a filter offers records by
+    name, so it has to answer to the same authorizer the target's own list
+    does.
+
+    The queryset is loaded whole and uncapped, exactly as
+    compute_relation_options already does for a non-autocomplete relation
+    <select>. autocomplete_fields is the answer to a large target, and it
+    is the same answer in both places; a cap here and not there would have
+    the panel and the form disagree about the same relation.
+    """
+    relation = getattr(field, "relation", None)
+    if relation is None:
+        return None
+    allowed = compute_relation_permissions(admin, principal, model_admin, [field.name])
+    if not allowed.get(relation.target, False):
+        return None
+    target_admin = admin.get_model_admin(relation.target)
+    if target_admin is None:
+        return None
+    related_objects, _ = await alist_objects(target_admin, ListRequest(unlimited=True))
+    try:
+        display_field = target_admin.get_field(relation.display_field)
+    except KeyError:
+        display_field = None
+    choices = []
+    for related in related_objects:
+        pk = str(target_admin.get_pk(related))
+        label = str(display_field.get_value(related)) if display_field is not None else pk
+        choices.append({"value": pk, "label": label})
+    return choices
+
+
+async def relation_filter_choices_for(
+    admin: Admin,
+    principal: Any,
+    model_admin: ModelAdmin,
+    filters: dict[str, str] | None = None,
+    base_path: str = "/admin",
+) -> dict[str, dict[str, Any] | None]:
+    """What each relation-kind filter needs but cannot supply itself,
+    keyed by filter name. A None value means "the principal may not view
+    this target, drop the filter".
+
+    Each entry is {"choices": [...], "combobox": {...} | None}: a relation
+    in `autocomplete_fields` gets the combobox and no choices, because the
+    point of that declaration is never loading the target's queryset into
+    the page; every other relation gets the link list.
+
+    Computed here and passed into `list_context` rather than resolved
+    inside it: core must not import the adapter (core/page.py), and this
+    needs the adapter's relation-permission check. That is the same
+    arrangement `delete_selected_context` already uses for its
+    permission-checked item list.
+    """
+    filters = filters or {}
+    sourced: dict[str, dict[str, Any] | None] = {}
+    for filt in model_admin.filters:
+        if filt.control_kind != FILTER_KIND_RELATION:
+            continue
+        try:
+            field = model_admin.get_field(filt.name)
+        except KeyError:
+            sourced[filt.name] = None
+            continue
+        if filt.name in model_admin.autocomplete_fields:
+            if not relation_filter_target_is_viewable(admin, principal, model_admin, field):
+                sourced[filt.name] = None
+                continue
+            sourced[filt.name] = {
+                "choices": [],
+                "combobox": await relation_filter_combobox(
+                    admin, principal, model_admin, field, filters.get(filt.name, ""), base_path
+                ),
+            }
+            continue
+        choices = await relation_filter_choices(admin, principal, model_admin, field)
+        sourced[filt.name] = None if choices is None else {"choices": choices, "combobox": None}
+    return sourced
+
+
+def relation_filter_target_is_viewable(
+    admin: Admin, principal: Any, model_admin: ModelAdmin, field: Any
+) -> bool:
+    """Whether the principal may view a relation filter's target, without
+    loading any of it. The combobox path needs the permission answer but
+    not the records.
+    """
+    relation = getattr(field, "relation", None)
+    if relation is None:
+        return False
+    allowed = compute_relation_permissions(admin, principal, model_admin, [field.name])
+    return allowed.get(relation.target, False)
+
+
+async def relation_filter_combobox(
+    admin: Admin, principal: Any, model_admin: ModelAdmin, field: Any, current: str, base_path: str
+) -> dict[str, str]:
+    """What the panel's combobox needs for a relation filter: the target's
+    lookup route, and the label of whatever is currently selected. It
+    loads no queryset -- that is the whole point of autocomplete_fields.
+
+    `current` is the filter's raw value, which is the target's primary key.
+    """
+    relation = field.relation
+    result = {
+        "lookup_url": f"{base_path}/{relation.target}/lookup",
+        "selected_pk": "",
+        "selected_label": "",
+    }
+    if not current:
+        return result
+    target_admin = admin.get_model_admin(relation.target)
+    if target_admin is None:
+        return result
+    # One object, not the queryset: the trigger has to show what is
+    # selected or the reader cannot tell what they are filtering by.
+    related = await maybe_await(target_admin.get_object(current))
+    if related is None:
+        return result
+    result["selected_pk"] = current
+    try:
+        display_field = target_admin.get_field(relation.display_field)
+        result["selected_label"] = str(display_field.get_value(related))
+    except KeyError:
+        result["selected_label"] = current
+    return result

polyadmin/fastapi/responses.py

@@ -0,0 +1,55 @@
+"""HTMX-aware response helpers."""
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from fastapi import Request, Response
+from fastapi.responses import HTMLResponse, RedirectResponse
+
+_FLASH_COOKIE = "admin_messages"
+
+
+def is_htmx_request(request: Request) -> bool:
+    return request.headers.get("HX-Request") == "true"
+
+
+def set_flash(response: Response, level: str, text: str) -> None:
+    response.set_cookie(
+        _FLASH_COOKIE,
+        json.dumps([{"level": level, "text": text}]),
+        max_age=10,
+        httponly=True,
+        samesite="lax",
+    )
+
+
+def pop_flash(request: Request) -> list[dict[str, Any]]:
+    """Read pending flash messages. Does not clear the cookie itself --
+    callers should call `clear_flash` on whichever response they end up
+    returning, once they know they've consumed the messages.
+    """
+    raw = request.cookies.get(_FLASH_COOKIE)
+    if not raw:
+        return []
+    try:
+        return json.loads(raw)
+    except (TypeError, ValueError):
+        return []
+
+
+def clear_flash(response: Response) -> None:
+    response.delete_cookie(_FLASH_COOKIE)
+
+
+def redirect(request: Request, url: str) -> Response:
+    """Redirect that works for both a normal browser navigation and an
+    HTMX request: a plain 303 in the former case, an `HX-Redirect`
+    response in the latter -- htmx otherwise treats a redirected AJAX
+    response as content to swap in, not a page navigation.
+    """
+    if is_htmx_request(request):
+        response = HTMLResponse("", status_code=200)
+        response.headers["HX-Redirect"] = url
+        return response
+    return RedirectResponse(url, status_code=303)

polyadmin/fastapi/router.py

@@ -0,0 +1,174 @@
+"""FastAPI adapter: mounts an Admin as an APIRouter.
+
+    app.include_router(create_router(admin, base_path="/admin"), prefix="/admin")
+
+`base_path` must match the `prefix` passed to `include_router` — it's
+used to build the links rendered inside templates (nav, pagination,
+redirects). The two aren't derived from each other because the router
+is built before FastAPI knows where it will be mounted.
+"""
+from __future__ import annotations
+
+from html import escape
+from pathlib import Path
+
+from fastapi import APIRouter, Request
+from fastapi.responses import HTMLResponse, RedirectResponse
+
+from polyadmin.core.admin import Admin
+from polyadmin.core.authorization import DASHBOARD_VIEW
+from polyadmin.core.exporter import CSVExporter, XLSXExporter
+from polyadmin.core.login import LOCALE_PATH, LOGIN_PATH, LOGOUT_PATH
+from polyadmin.fastapi.auth import authorize
+from polyadmin.fastapi.handlers import (
+    build_action_handler,
+    build_create_handlers,
+    build_delete_handlers,
+    build_detail_handler,
+    build_edit_handlers,
+    build_export_handler,
+    build_inline_handlers,
+    build_list_handler,
+    build_lookup_handler,
+)
+from polyadmin.fastapi.inlines import validate_inlines
+from polyadmin.fastapi.locale import build_locale_handler, make_admin_route, switcher_on
+from polyadmin.fastapi.login import build_login_handlers, build_logout_handler
+from polyadmin.fastapi.pages import build_page_handler
+from polyadmin.fastapi.responses import clear_flash, pop_flash
+from polyadmin.fastapi.static import mount_static
+from polyadmin.i18n import I18n, gettext
+from polyadmin.templating import Renderer
+
+DEFAULT_EXPORTERS = [CSVExporter(), XLSXExporter()]
+
+
+def create_router(
+    admin: Admin,
+    *,
+    base_path: str = "/admin",
+    template_dirs: tuple[str | Path, ...] = (),
+    static_dir: str | Path | None = None,
+    exporters: tuple = tuple(DEFAULT_EXPORTERS),
+) -> APIRouter:
+    i18n = I18n.from_admin(admin)
+    renderer = Renderer(template_dirs=template_dirs, i18n=i18n, switcher_enabled=admin.locale_switcher)
+    # route_class, not a dependency: see polyadmin/fastapi/locale.py.
+    router = APIRouter(route_class=make_admin_route(admin, base_path, i18n, renderer))
+
+    mount_static(router, static_dir=static_dir)
+
+    # The login routes go on before anything else, and only when the
+    # application supplied a backend to make them work. They are the
+    # routes that do not authenticate -- requiring a session to reach the
+    # page that creates one is a loop -- so they are also the ones that
+    # must not be shadowed by a ModelAdmin whose slug happens to be
+    # "login". Registering them first is what makes that collision
+    # visible rather than a silently unreachable login page.
+    if admin.login_backend is not None:
+        login_get, login_post = build_login_handlers(admin, renderer, base_path)
+        router.add_api_route(LOGIN_PATH, login_get, methods=["GET"], include_in_schema=False)
+        router.add_api_route(LOGIN_PATH, login_post, methods=["POST"], include_in_schema=False)
+        router.add_api_route(
+            LOGOUT_PATH,
+            build_logout_handler(admin, base_path),
+            methods=["POST"],
+            include_in_schema=False,
+        )
+
+    if switcher_on(admin, i18n):
+        router.add_api_route(
+            LOCALE_PATH, build_locale_handler(i18n, base_path), methods=["POST"], include_in_schema=False
+        )
+
+    @router.get("", include_in_schema=False)
+    async def index(request: Request) -> HTMLResponse:
+        principal, error = await authorize(admin, request, base_path, DASHBOARD_VIEW)
+        if error:
+            return error
+
+        if admin.dashboard is not None:
+            widgets = admin.dashboard.get_widgets(principal, admin.authorizer)
+            messages = pop_flash(request)
+            html = renderer.render_dashboard(
+                admin,
+                admin.dashboard,
+                widgets,
+                base_path=base_path,
+                messages=messages,
+                principal=principal,
+                csrf_token=request.state.csrf_token,
+            )
+            response = HTMLResponse(html)
+            clear_flash(response)
+            return response
+
+        # No Dashboard configured -- land on the first viewable resource.
+        for model_admin in admin.model_admins:
+            if model_admin.can_view:
+                return RedirectResponse(f"{base_path}/{model_admin.get_slug()}")
+        return HTMLResponse(f"<p>{escape(gettext('No resources registered.'))}</p>")
+
+    for model_admin in admin.model_admins:
+        prefix = f"/{model_admin.get_slug()}"
+
+        if model_admin.can_view:
+            router.add_api_route(
+                prefix, build_list_handler(admin, model_admin, renderer, base_path), methods=["GET"]
+            )
+
+        if model_admin.can_create:
+            create_get, create_post = build_create_handlers(admin, model_admin, renderer, base_path)
+            router.add_api_route(f"{prefix}/create", create_get, methods=["GET"])
+            router.add_api_route(f"{prefix}/create", create_post, methods=["POST"])
+
+        if model_admin.can_export:
+            for exporter in exporters:
+                router.add_api_route(
+                    f"{prefix}/export/{exporter.format}",
+                    build_export_handler(admin, model_admin, exporter, base_path),
+                    methods=["GET"],
+                )
+
+        if model_admin.can_view:
+            router.add_api_route(
+                f"{prefix}/lookup",
+                build_lookup_handler(admin, model_admin, renderer, base_path),
+                methods=["GET"],
+            )
+            if model_admin.get_actions():
+                router.add_api_route(
+                    f"{prefix}/actions/{{action_name}}",
+                    build_action_handler(admin, model_admin, renderer, base_path),
+                    methods=["POST"],
+                )
+            router.add_api_route(
+                f"{prefix}/{{pk}}",
+                build_detail_handler(admin, model_admin, renderer, base_path),
+                methods=["GET"],
+            )
+
+        if model_admin.can_update:
+            edit_get, edit_post = build_edit_handlers(admin, model_admin, renderer, base_path)
+            router.add_api_route(f"{prefix}/{{pk}}/edit", edit_get, methods=["GET"])
+            router.add_api_route(f"{prefix}/{{pk}}/edit", edit_post, methods=["POST"])
+
+        if model_admin.can_delete:
+            delete_get, delete_post, delete_htmx = build_delete_handlers(admin, model_admin, renderer, base_path)
+            router.add_api_route(f"{prefix}/{{pk}}/delete", delete_get, methods=["GET"])
+            router.add_api_route(f"{prefix}/{{pk}}/delete", delete_post, methods=["POST"])
+            router.add_api_route(f"{prefix}/{{pk}}/delete", delete_htmx, methods=["DELETE"])
+
+        if model_admin.inlines:
+            validate_inlines(admin, model_admin)
+            inline_create, inline_update, inline_delete = build_inline_handlers(admin, model_admin, renderer, base_path)
+            router.add_api_route(f"{prefix}/{{pk}}/inlines/{{child_slug}}", inline_create, methods=["POST"])
+            router.add_api_route(f"{prefix}/{{pk}}/inlines/{{child_slug}}/{{child_pk}}", inline_update, methods=["POST"])
+            router.add_api_route(f"{prefix}/{{pk}}/inlines/{{child_slug}}/{{child_pk}}", inline_delete, methods=["DELETE"])
+
+    for page in admin.pages:
+        router.add_api_route(
+            page.path, build_page_handler(admin, page, renderer, base_path), methods=list(page.methods)
+        )
+
+    return router

polyadmin/fastapi/static.py

@@ -0,0 +1,21 @@
+"""Static asset mounting for the FastAPI adapter."""
+from __future__ import annotations
+
+from pathlib import Path
+
+from fastapi import APIRouter
+from fastapi.staticfiles import StaticFiles
+
+FRAMEWORK_STATIC_DIR = Path(__file__).parent.parent / "static"
+
+
+def mount_static(router: APIRouter, *, static_dir: str | Path | None = None) -> None:
+    """Mount the admin's static assets at `<base_path>/static/*`.
+
+    Pass `static_dir` to serve an application's own directory (for
+    `custom.css`/`custom.js`) instead of the framework's.
+    """
+    directory = Path(static_dir) if static_dir else FRAMEWORK_STATIC_DIR
+    if not directory.exists():
+        return
+    router.mount("/static", StaticFiles(directory=str(directory)), name="admin-static")

polyadmin/i18n/__init__.py

@@ -0,0 +1,50 @@
+"""Internationalisation: the Translator, locale resolution, and the
+helpers host code uses to translate its own strings. See docs/i18n.md."""
+
+from polyadmin.i18n.context import (
+    N_,
+    LocaleContext,
+    get_locale,
+    gettext,
+    ngettext,
+    use_locale,
+)
+from polyadmin.i18n.negotiation import (
+    match_accept_language,
+    match_locale,
+    parse_accept_language,
+)
+from polyadmin.i18n.setup import BUILTIN_LOCALE_NAMES, I18n, LocaleOption
+from polyadmin.i18n.translator import (
+    DEFAULT_LOCALE,
+    DOMAIN,
+    FRAMEWORK_LOCALE_DIR,
+    PSEUDO_LOCALE,
+    GettextTranslator,
+    PseudoTranslator,
+    Translator,
+    pseudo,
+)
+
+__all__ = [
+    "BUILTIN_LOCALE_NAMES",
+    "DEFAULT_LOCALE",
+    "DOMAIN",
+    "FRAMEWORK_LOCALE_DIR",
+    "N_",
+    "PSEUDO_LOCALE",
+    "GettextTranslator",
+    "I18n",
+    "LocaleContext",
+    "LocaleOption",
+    "PseudoTranslator",
+    "Translator",
+    "get_locale",
+    "gettext",
+    "match_accept_language",
+    "match_locale",
+    "ngettext",
+    "parse_accept_language",
+    "pseudo",
+    "use_locale",
+]

polyadmin/i18n/context.py

@@ -0,0 +1,54 @@
+"""The request's locale, for code that has no request to hand.
+
+Set per request by the FastAPI adapter's route class; action handlers,
+validators and ModelAdmin methods read it through these helpers.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass
+
+from polyadmin.i18n.translator import DEFAULT_LOCALE, Translator
+
+
+@dataclass(frozen=True)
+class LocaleContext:
+    locale: str
+    translator: Translator
+
+
+_current: ContextVar[LocaleContext | None] = ContextVar("polyadmin_locale", default=None)
+
+
+def get_locale() -> str:
+    current = _current.get()
+    return current.locale if current else DEFAULT_LOCALE
+
+
+def gettext(message: str) -> str:
+    current = _current.get()
+    return current.translator.gettext(current.locale, message) if current else message
+
+
+def ngettext(singular: str, plural: str, n: int) -> str:
+    current = _current.get()
+    if current is None:
+        return singular if n == 1 else plural
+    return current.translator.ngettext(current.locale, singular, plural, n)
+
+
+def N_(message: str) -> str:
+    """Mark a string for extraction without translating it."""
+    return message
+
+
+@contextmanager
+def use_locale(locale: str, translator: Translator) -> Iterator[None]:
+    token = _current.set(LocaleContext(locale, translator))
+    try:
+        yield
+    finally:
+        _current.reset(token)

polyadmin/i18n/negotiation.py

@@ -0,0 +1,56 @@
+"""Locale matching. Hand-written so Babel stays a dev-only dependency."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from polyadmin.i18n.translator import PSEUDO_LOCALE
+
+
+def parse_accept_language(header: str | None) -> list[str]:
+    """Language ranges ordered by q, highest first; q=0 and "*" dropped."""
+    ranked = []
+    for position, part in enumerate((header or "").split(",")):
+        tag, _, params = part.strip().partition(";")
+        tag = tag.strip()
+        q = 1.0
+        for param in params.split(";"):
+            key, _, value = param.strip().partition("=")
+            if key == "q":
+                try:
+                    q = float(value)
+                except ValueError:
+                    q = 0.0
+        if tag and tag != "*" and q > 0:
+            ranked.append((-q, position, tag))
+    return [tag for _, _, tag in sorted(ranked)]
+
+
+def match_locale(supported: Sequence[str], candidate: str | None) -> str | None:
+    """The supported locale a candidate names, or None.
+
+    Exact matches win (case-insensitively, "_" or "-"); otherwise a
+    regional variant maps onto its base language (fr-CA -> fr). The
+    pseudo-locale matches only exactly.
+    """
+    if not candidate:
+        return None
+    wanted = candidate.strip().replace("_", "-").lower()
+    by_lower = {locale.lower(): locale for locale in supported}
+    if wanted in by_lower:
+        return by_lower[wanted]
+    base = wanted.split("-")[0]
+    match = by_lower.get(base)
+    return match if match and match != PSEUDO_LOCALE else None
+
+
+def match_accept_language(supported: Sequence[str], header: str | None) -> str | None:
+    """The best supported locale for an Accept-Language header, or None.
+    Ranges are tried one at a time in q order."""
+    for tag in parse_accept_language(header):
+        if tag.lower() == PSEUDO_LOCALE.lower():
+            continue
+        match = match_locale(supported, tag)
+        if match:
+            return match
+    return None