hxadmin 0.1.0__py3-none-any.whl

hxadmin/__init__.py

@@ -0,0 +1,22 @@
+from importlib.metadata import version
+
+from hxadmin.actions import ActionResult, action
+from hxadmin.admin import HxAdmin
+from hxadmin.fields import Field, RelationField
+from hxadmin.forms import FormError
+from hxadmin.pages import Page
+from hxadmin.views import BadgeTone, ModelView
+
+__version__ = version("hxadmin")
+__all__ = [
+    "ActionResult",
+    "BadgeTone",
+    "Field",
+    "FormError",
+    "HxAdmin",
+    "ModelView",
+    "Page",
+    "RelationField",
+    "__version__",
+    "action",
+]

hxadmin/actions.py

@@ -0,0 +1,81 @@
+import inspect
+import re
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Any, Literal, Self
+
+from starlette.responses import Response
+
+from hxadmin.fields import label_for
+from hxadmin.toasts import Toast, ToastLevel
+
+type ActionMethod = Literal["GET", "POST"]
+type ActionHandler = Callable[..., Awaitable[Any]]
+
+ACTION_ATTR = "__hxadmin_action__"
+_NAME = re.compile(r"[A-Za-z0-9_-]+")
+
+
+@dataclass(frozen=True, slots=True)
+class Action:
+    """Metadata declared by one `@action` method."""
+
+    name: str
+    label: str
+    bulk: bool
+    confirm: str | None
+    method: ActionMethod
+
+
+@dataclass(frozen=True, slots=True)
+class ActionResult:
+    """Outcome of an action: a toast over the re-rendered view, a redirect, or a raw response."""
+
+    toast: Toast | None = None
+    url: str | None = None
+    raw: Response | None = None
+
+    @classmethod
+    def message(cls, text: str, level: ToastLevel = "success") -> Self:
+        return cls(toast=Toast(text, level))
+
+    @classmethod
+    def redirect(cls, url: str) -> Self:
+        return cls(url=url)
+
+    @classmethod
+    def response(cls, response: Response) -> Self:
+        return cls(raw=response)
+
+
+def _require_async(name: str, func: object) -> None:
+    if not inspect.iscoroutinefunction(func):
+        raise TypeError(f"Action {name!r} must be an async function")
+
+
+def action[F: ActionHandler](
+    name: str,
+    *,
+    label: str | None = None,
+    bulk: bool = False,
+    confirm: str | None = None,
+    method: ActionMethod = "POST",
+) -> Callable[[F], F]:
+    """Declare a `ModelView` coroutine method as a row action, or a bulk action with `bulk=True`.
+
+    Row handlers receive `(request, session, obj)`, bulk handlers `(request, session, objs)`.
+    POST actions run over htmx; `method="GET"` actions are plain links / form submits so a
+    returned download reaches the browser.
+    """
+    if not _NAME.fullmatch(name):
+        raise ValueError(f"Invalid action name {name!r}: use letters, digits, '_' and '-'")
+    if method not in ("GET", "POST"):
+        raise ValueError(f"Action {name!r}: method must be 'GET' or 'POST', not {method!r}")
+    spec = Action(name, label or label_for(name.replace("-", "_")), bulk, confirm, method)
+
+    def decorate(func: F) -> F:
+        _require_async(name, func)
+        setattr(func, ACTION_ATTR, spec)
+        return func
+
+    return decorate

hxadmin/admin.py

@@ -0,0 +1,370 @@
+import inspect
+import json
+import logging
+from collections.abc import Awaitable, Callable, Mapping, Sequence
+from pathlib import Path
+from typing import Any, cast
+
+from fastapi import Depends, FastAPI
+from fastapi.staticfiles import StaticFiles
+from jinja2 import (
+    BaseLoader,
+    ChoiceLoader,
+    Environment,
+    FileSystemLoader,
+    PackageLoader,
+    select_autoescape,
+)
+from sqlalchemy import Select, select
+from sqlalchemy.ext.asyncio import AsyncSession
+from starlette.exceptions import HTTPException as StarletteHTTPException
+from starlette.requests import Request
+from starlette.responses import HTMLResponse, RedirectResponse, Response
+from starlette.routing import BaseRoute
+
+from hxadmin.components import date_format, html_attrs, pick
+from hxadmin.deps import AuthDependency, SessionDependency
+from hxadmin.fields import default_widget, field_widget, field_width
+from hxadmin.icons import check_icon, icon
+from hxadmin.nav import build_nav
+from hxadmin.origin import is_cross_origin, normalize_origin
+from hxadmin.pages import AdminPage, PageEndpoint, PageHandler
+from hxadmin.toasts import FLASH_COOKIE, Toast, encode_flash, hx_trigger, read_flash
+from hxadmin.users import user_initials, user_label
+from hxadmin.views import ModelView
+
+logger = logging.getLogger("hxadmin")
+
+
+def json_pretty(value: Any) -> str:
+    return json.dumps(value, indent=2, ensure_ascii=False)
+
+
+def _first_segment(path: str) -> str:
+    return path.strip("/").split("/", 1)[0]
+
+
+def _require_async_page(path: str, handler: object) -> None:
+    if not inspect.iscoroutinefunction(handler):
+        raise TypeError(f"Page handler for {path!r} must be an async function")
+
+
+_PAGE_METHODS = ("GET", "HEAD", "POST", "PUT", "PATCH", "DELETE")
+
+
+def _method_not_allowed(allowed: Sequence[str]) -> Callable[[], Awaitable[Response]]:
+    """Endpoint answering 405 for a page path, so `/{identity}/{pk}` cannot claim it as a 404."""
+    allow = ", ".join(m.upper() for m in allowed)
+
+    async def not_allowed() -> Response:
+        return Response(status_code=405, headers={"Allow": allow})
+
+    return not_allowed
+
+
+class HxAdmin:
+    current_user: Callable[..., Awaitable[Any]]
+    current_session: Callable[..., Awaitable[AsyncSession]]
+    _page_slot: int
+
+    def __init__(
+        self,
+        app: FastAPI,
+        *,
+        session: SessionDependency,
+        auth: AuthDependency,
+        title: str = "HxAdmin",
+        prefix: str = "/admin",
+        login_url: str | None = None,
+        logout_url: str | None = None,
+        logo_url: str | None = None,
+        templates_dir: str | Path | None = None,
+        trusted_origins: Sequence[str] = (),
+    ) -> None:
+        self.app = app
+        self.title = title
+        self.prefix = prefix.rstrip("/")
+        self.login_url = login_url
+        self.logout_url = logout_url
+        self.logo_url = logo_url
+        self.views: dict[str, ModelView[Any]] = {}
+        self.pages: list[AdminPage] = []
+        self._page_methods: dict[str, set[str]] = {}
+        self._method_fallbacks: dict[str, BaseRoute] = {}
+        self._session = session
+        self._auth = auth
+        self.trusted_origins = frozenset(normalize_origin(origin) for origin in trusted_origins)
+        self.templates = self._make_environment(templates_dir)
+        self.subapp = FastAPI(openapi_url=None, docs_url=None, redoc_url=None)
+        self.subapp.mount(
+            "/static",
+            StaticFiles(directory=str(Path(__file__).parent / "static")),
+            name="static",
+        )
+        self._build_dependencies()
+        self._install_routes()
+        self.subapp.add_exception_handler(StarletteHTTPException, self._handle_http_exception)
+        self.subapp.add_exception_handler(Exception, self._handle_server_error)
+        app.mount(self.prefix, self.subapp, name="hxadmin")
+
+    def _make_environment(self, templates_dir: str | Path | None) -> Environment:
+        loaders: list[BaseLoader] = [PackageLoader("hxadmin", "templates")]
+        if templates_dir is not None:
+            loaders.insert(0, FileSystemLoader(str(templates_dir)))
+        env = Environment(loader=ChoiceLoader(loaders), autoescape=select_autoescape(["html"]))
+        env.filters["json_pretty"] = json_pretty
+        env_globals = cast(dict[str, Any], env.globals)
+        env_globals["default_widget"] = default_widget
+        env_globals["field_widget"] = field_widget
+        env_globals["field_width"] = field_width
+        env_globals["lucide_icon"] = icon
+        env_globals["hx_attrs"] = html_attrs
+        env_globals["hx_pick"] = pick
+        env_globals["hx_date_format"] = date_format
+        env_globals["hx_user_label"] = user_label
+        env_globals["hx_user_initials"] = user_initials
+        return env
+
+    def _build_dependencies(self) -> None:
+        auth = self._auth
+        session = self._session
+        trusted = self.trusted_origins
+
+        async def current_user(request: Request, user: Any = Depends(auth)) -> Any:
+            request.state.hxadmin_user = user
+            if is_cross_origin(request, trusted):
+                logger.warning(
+                    "Blocked cross-origin %s %s (Origin: %s, Sec-Fetch-Site: %s)",
+                    request.method,
+                    request.url.path,
+                    request.headers.get("origin"),
+                    request.headers.get("sec-fetch-site"),
+                )
+                raise StarletteHTTPException(403, "Cross-origin request blocked.")
+            return user
+
+        async def current_session(
+            session_: AsyncSession = Depends(session),
+        ) -> AsyncSession:
+            return session_
+
+        self.current_user = current_user
+        self.current_session = current_session
+
+    def _install_routes(self) -> None:
+        from hxadmin.routes import build_router
+
+        self._page_slot = len(self.subapp.router.routes)
+        self.subapp.include_router(build_router(self))
+
+    async def _handle_http_exception(self, request: Request, exc: Exception) -> Response:
+        if not isinstance(exc, StarletteHTTPException):
+            raise exc
+        htmx = request.headers.get("HX-Request") == "true"
+        authenticated = hasattr(request.state, "hxadmin_user")
+        if exc.status_code in (401, 403) and self.login_url is not None and not authenticated:
+            if htmx:
+                return Response(status_code=200, headers={"HX-Redirect": self.login_url})
+            return RedirectResponse(self.login_url, status_code=303)
+        if htmx:
+            toast = Toast(str(exc.detail), "error")
+            response: Response = Response(
+                status_code=exc.status_code,
+                headers={"HX-Trigger": hx_trigger(toast), "HX-Reswap": "none"},
+            )
+        else:
+            response = self.render(
+                request,
+                "error.html",
+                {"status_code": exc.status_code, "detail": exc.detail},
+                status_code=exc.status_code,
+            )
+        response.headers.update(exc.headers or {})
+        return response
+
+    async def _handle_server_error(self, request: Request, exc: Exception) -> Response:
+        """An error toast for htmx, else the error page; Starlette still re-raises `exc`."""
+        detail = "Something went wrong."
+        if request.headers.get("HX-Request") == "true":
+            return Response(
+                status_code=500,
+                headers={"HX-Trigger": hx_trigger(Toast(detail, "error")), "HX-Reswap": "none"},
+            )
+        return self.render(
+            request, "error.html", {"status_code": 500, "detail": detail}, status_code=500
+        )
+
+    def register[V: ModelView[Any]](self, view_cls: type[V]) -> type[V]:
+        view = view_cls()
+        if view.identity in self.views:
+            raise ValueError(f"A view with identity {view.identity!r} is already registered")
+        if any(_first_segment(page.path) == view.identity for page in self.pages):
+            raise ValueError(f"A page path already uses {view.identity!r}")
+        check_icon(view.icon)
+        self.views[view.identity] = view
+        return view_cls
+
+    def page[F: PageHandler](
+        self,
+        path: str,
+        *,
+        title: str,
+        category: str | None = None,
+        icon: str | None = None,
+        methods: Sequence[str] = ("GET",),
+        name: str | None = None,
+    ) -> Callable[[F], F]:
+        """Register a custom page under the admin prefix, guarded by `auth`, in the sidebar."""
+        if "{" in path:
+            raise ValueError(f"Sidebar page {path!r} cannot take path parameters; use admin.route")
+        check_icon(icon)
+        return self._add_page(AdminPage(path, title, category, icon, in_nav=True), methods, name)
+
+    def route[F: PageHandler](
+        self,
+        path: str,
+        *,
+        title: str = "",
+        methods: Sequence[str] = ("GET",),
+        name: str | None = None,
+    ) -> Callable[[F], F]:
+        """Register a route under the admin prefix, guarded by `auth`, not in the sidebar."""
+        return self._add_page(AdminPage(path, title), methods, name)
+
+    def _add_page[F: PageHandler](
+        self, page: AdminPage, methods: Sequence[str], name: str | None
+    ) -> Callable[[F], F]:
+        self._check_page_path(page.path)
+        wanted = {m.upper() for m in methods}
+        if "GET" in wanted:
+            wanted.add("HEAD")
+        clash = wanted & self._page_methods.get(page.path, set())
+        if clash:
+            raise ValueError(
+                f"Page path {page.path!r} is already registered for {', '.join(sorted(clash))}"
+            )
+        if page.in_nav and any(p.in_nav and p.path == page.path for p in self.pages):
+            raise ValueError(f"Page path {page.path!r} is already in the sidebar")
+
+        def decorate(handler: F) -> F:
+            _require_async_page(page.path, handler)
+            routes = self.subapp.router.routes
+            start = len(routes)
+            self.subapp.add_api_route(
+                page.path,
+                PageEndpoint(self, page, handler),
+                methods=list(methods),
+                name=name or getattr(handler, "__name__", page.path),
+                dependencies=[Depends(self.current_user)],
+                response_model=None,
+                include_in_schema=False,
+            )
+            added = routes[start:]
+            del routes[start:]
+            routes[self._page_slot : self._page_slot] = added
+            self._page_slot += len(added)
+            allowed = self._page_methods.get(page.path, set()) | wanted
+            self._page_methods[page.path] = allowed
+            self._set_method_fallback(page.path, allowed)
+            self.pages.append(page)
+            return handler
+
+        return decorate
+
+    def _set_method_fallback(self, path: str, allowed: set[str]) -> None:
+        """One 405 route per page path, kept after every page handler and before model routes."""
+        routes = self.subapp.router.routes
+        old = self._method_fallbacks.pop(path, None)
+        if old is not None:
+            routes.remove(old)
+        other = [m for m in _PAGE_METHODS if m not in allowed]
+        if not other:
+            return
+        self.subapp.add_api_route(
+            path,
+            _method_not_allowed(sorted(allowed)),
+            methods=other,
+            dependencies=[Depends(self.current_user)],
+            include_in_schema=False,
+        )
+        route = routes.pop()
+        routes.insert(self._page_slot, route)
+        self._method_fallbacks[path] = route
+
+    def _check_page_path(self, path: str) -> None:
+        first = _first_segment(path)
+        if not path.startswith("/") or not first or first.startswith("{"):
+            raise ValueError(f"Page path must start with a fixed segment like '/reports': {path!r}")
+        if first == "static" or first in self.views:
+            raise ValueError(f"Page path {path!r} collides with the admin's {first!r} routes")
+
+    def view_for(self, model: type[Any]) -> ModelView[Any] | None:
+        return next((v for v in self.views.values() if v.model is model), None)
+
+    def can_reach(self, request: Request, model: type[Any]) -> bool:
+        """Whether rows of `model` may be offered: it has no view, or an accessible one."""
+        target = self.view_for(model)
+        return target is None or target.is_accessible(request)
+
+    def relation_scope(self, request: Request, model: type[Any]) -> Select[Any] | None:
+        """Rows of `model` a relation may offer or accept, or None if its view is locked."""
+        target = self.view_for(model)
+        if target is None:
+            return select(model)
+        if not target.is_accessible(request):
+            return None
+        return target.get_query(request)
+
+    def display(self, obj: Any) -> str:
+        view = self.view_for(type(obj))
+        return view.display(obj) if view is not None else str(obj)
+
+    def url(self, request: Request, path: str = "/") -> str:
+        return f"{request.scope.get('root_path', '')}{path}"
+
+    def redirect(self, request: Request, url: str, *, toast: Toast | None = None) -> Response:
+        """Redirect after a successful write: HX-Redirect on 200 for htmx, 303 otherwise.
+
+        A `toast` rides along in a short-lived cookie and is shown on the next full page.
+        """
+        if request.headers.get("HX-Request") == "true":
+            response: Response = Response(status_code=200, headers={"HX-Redirect": url})
+        else:
+            response = RedirectResponse(url, status_code=303)
+        if toast is not None:
+            response.set_cookie(
+                FLASH_COOKIE,
+                encode_flash(toast),
+                max_age=60,
+                path=self.url(request, "/"),
+                httponly=True,
+                samesite="lax",
+            )
+        return response
+
+    def render(
+        self,
+        request: Request,
+        template: str,
+        context: Mapping[str, Any] | None = None,
+        *,
+        status_code: int = 200,
+    ) -> HTMLResponse:
+        consume = request.headers.get("HX-Request") != "true" and FLASH_COOKIE in request.cookies
+        flash = read_flash(request) if consume else None
+        full_context: dict[str, Any] = {
+            "admin": self,
+            "request": request,
+            "user": getattr(request.state, "hxadmin_user", None),
+            "nav": build_nav(self, request),
+            "toasts": [flash.as_dict()] if flash is not None else [],
+        }
+        if context:
+            full_context.update(context)
+        html = self.templates.get_template(template).render(full_context)
+        response = HTMLResponse(html, status_code=status_code)
+        if consume:
+            response.delete_cookie(
+                FLASH_COOKIE, path=self.url(request, "/"), httponly=True, samesite="lax"
+            )
+        return response

hxadmin/components.py

@@ -0,0 +1,74 @@
+"""Helpers the component macros in `templates/components/` call as Jinja globals."""
+
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any
+
+from jinja2 import Undefined
+from markupsafe import escape
+
+_NAME = re.compile(r"[@:A-Za-z_][\w.:@-]*")
+
+
+@dataclass(frozen=True, slots=True)
+class Attributes:
+    """Extra HTML attributes that render themselves (Jinja treats them as safe markup).
+
+    Each pair is a name and an escaped value, or None for a bare boolean attribute.
+    """
+
+    pairs: tuple[tuple[str, str | None], ...]
+
+    def __html__(self) -> str:
+        return "".join(f" {k}" if v is None else f' {k}="{v}"' for k, v in self.pairs)
+
+    def __str__(self) -> str:
+        return self.__html__()
+
+
+def html_attrs(
+    attrs: Mapping[str, Any] | None = None, kwargs: Mapping[str, Any] | None = None
+) -> Attributes:
+    """Render `attrs` as-is and `kwargs` with `_` turned into `-`, later keys winning.
+
+    None, False and undefined values are dropped, True renders a bare attribute and anything
+    else is escaped. Names must look like HTML, Alpine or htmx attribute names, and `class`
+    is rejected because every component takes it as its own argument.
+    """
+    merged: dict[str, Any] = {}
+    for key, value in (attrs or {}).items():
+        merged[key] = value
+    for key, value in (kwargs or {}).items():
+        merged[key.replace("_", "-")] = value
+    pairs: list[tuple[str, str | None]] = []
+    for key, value in merged.items():
+        if not _NAME.fullmatch(key):
+            raise ValueError(f"Invalid attribute name {key!r}")
+        if key == "class":
+            raise ValueError("Pass class as the component's class argument, not as an attribute")
+        if value is None or value is False or isinstance(value, Undefined):
+            continue
+        pairs.append((key, None if value is True else str(escape(value))))
+    return Attributes(tuple(pairs))
+
+
+def pick(options: Mapping[str, str], key: str, what: str) -> str:
+    """`options[key]`, or a `ValueError` naming `what` and the allowed keys."""
+    try:
+        return options[key]
+    except KeyError:
+        allowed = ", ".join(options)
+        raise ValueError(f"Unknown {what} {key!r}: use one of {allowed}") from None
+
+
+DATE_FORMATS: Mapping[str, str] = {
+    "date": "MM/dd/yyyy",
+    "datetime": "MM/dd/yyyy HH:mm",
+    "time": "HH:mm",
+}
+
+
+def date_format(kind: str) -> str:
+    """Air Datepicker format for a date input of `kind`; lower-cased, its placeholder."""
+    return pick(DATE_FORMATS, kind, "date kind")

hxadmin/deps.py

@@ -0,0 +1,11 @@
+from collections.abc import AsyncIterator, Awaitable, Callable
+from typing import Any
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+type SessionDependency = (
+    Callable[..., AsyncSession]
+    | Callable[..., AsyncIterator[AsyncSession]]
+    | Callable[..., Awaitable[AsyncSession]]
+)
+type AuthDependency = Callable[..., Any]