polyadmin 0.1.0b1__py3-none-any.whl

polyadmin/__init__.py

@@ -0,0 +1,47 @@
+from polyadmin.core.admin import Admin
+from polyadmin.core.delete import (
+    DELETE_PREVIEW_SAMPLE,
+    DeleteGroup,
+    DeletePreview,
+    DeletePreviewer,
+)
+from polyadmin.core.field import (
+    BooleanField,
+    DateField,
+    DateTimeField,
+    DecimalField,
+    EmailField,
+    EnumField,
+    Field,
+    IntegerField,
+    JSONField,
+    PasswordField,
+    StringField,
+    TextField,
+    URLField,
+    UUIDField,
+)
+from polyadmin.core.model_admin import ModelAdmin
+
+__all__ = [
+    "DELETE_PREVIEW_SAMPLE",
+    "Admin",
+    "BooleanField",
+    "DateField",
+    "DateTimeField",
+    "DecimalField",
+    "DeleteGroup",
+    "DeletePreview",
+    "DeletePreviewer",
+    "EmailField",
+    "EnumField",
+    "Field",
+    "IntegerField",
+    "JSONField",
+    "ModelAdmin",
+    "PasswordField",
+    "StringField",
+    "TextField",
+    "URLField",
+    "UUIDField",
+]

polyadmin/core/_async.py

@@ -0,0 +1,21 @@
+"""Bridges a hook that may return a value or an awaitable.
+
+The CRUD lifecycle (`get_queryset`, `get_object`, `create`, `update`,
+`delete`, `list_page`) and `Authenticator.authenticate` may each be a plain
+function or an `async def` -- a ModelAdmin backed by an async HTTP client
+needs the latter. `maybe_await` lets one call site handle both without the
+author declaring which upfront.
+"""
+from __future__ import annotations
+
+import inspect
+from collections.abc import Awaitable
+from typing import TypeVar
+
+T = TypeVar("T")
+
+
+async def maybe_await(value: T | Awaitable[T]) -> T:
+    if inspect.isawaitable(value):
+        return await value
+    return value

polyadmin/core/action.py

@@ -0,0 +1,135 @@
+"""Actions: ModelAdmin methods applied to one or more records.
+
+An action is invoked with a list of objects either way -- a "record" action
+from the detail page passes a list of exactly one, a "bulk" action from the
+list view's row-selection passes as many as were checked. There is
+deliberately no separate record/bulk type: the same method serves both,
+since it never needs to know which UI entry point invoked it.
+
+Declare one by decorating a ModelAdmin method with `@action`. The decorator
+only records options on the function; ModelAdmin.get_actions() resolves them
+(see `collect_actions`).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Sequence
+from dataclasses import dataclass
+from typing import Any, Literal, TypeVar, overload
+
+from polyadmin.core.auth import Principal
+
+# Which pages offer an action: the list page's bulk bar, one record's detail
+# page, or both.
+ActionWhere = Literal["list", "detail", "both"]
+ACTION_WHERE: tuple[str, ...] = ("list", "detail", "both")
+
+# The bound method a ModelAdmin's action resolves to. It may be a coroutine
+# function; the adapter awaits it when it is one.
+ActionHandler = Callable[[Sequence[Any], Principal | None], Awaitable[str | None] | str | None]
+
+# The built-in bulk delete's action name. Reserved: overriding the
+# ModelAdmin.delete_selected method replaces the built-in, which is how you
+# customise the confirmation text or the deletion itself.
+DELETE_SELECTED_NAME = "delete_selected"
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+_OPTIONS_ATTR = "__polyadmin_action__"
+
+
+@dataclass(frozen=True)
+class ActionOptions:
+    """What `@action` records on a method."""
+
+    label: str | None = None
+    # A confirmation prompt shown before running (the dialog in
+    # components/action_confirm_modal.html) -- None means no confirmation.
+    confirm: str | None = None
+    # Extra permission suffix checked via resource_permission(slug,
+    # permission) alongside the resource's `.view` -- None means no extra
+    # check beyond being able to see the resource at all.
+    permission: str | None = None
+    # Placement only, not authorization: the action route serves every action
+    # whichever page offered it, and checks `permission` there.
+    where: ActionWhere = "both"
+
+
+@dataclass(frozen=True)
+class Action:
+    """One resolved action of one ModelAdmin instance. Built by
+    `collect_actions`; not something a host constructs."""
+
+    name: str
+    handler: ActionHandler
+    label: str
+    confirm: str | None = None
+    permission: str | None = None
+    where: ActionWhere = "both"
+
+
+@overload
+def action(func: F, /) -> F: ...
+
+
+@overload
+def action(
+    *,
+    label: str | None = None,
+    confirm: str | None = None,
+    permission: str | None = None,
+    where: ActionWhere = "both",
+) -> Callable[[F], F]: ...
+
+
+def action(
+    func: F | None = None,
+    /,
+    *,
+    label: str | None = None,
+    confirm: str | None = None,
+    permission: str | None = None,
+    where: ActionWhere = "both",
+) -> F | Callable[[F], F]:
+    """Mark a ModelAdmin method as an action: `(self, objects, principal) -> str | None`.
+
+    The method's name is the action's name. The decorator returns the function
+    unchanged, so type checkers keep seeing its own signature.
+    """
+    if where not in ACTION_WHERE:
+        raise ValueError(f"@action: where must be one of {ACTION_WHERE}, not {where!r}.")
+    options = ActionOptions(label=label, confirm=confirm, permission=permission, where=where)
+
+    def decorate(fn: F) -> F:
+        setattr(fn, _OPTIONS_ATTR, options)
+        return fn
+
+    return decorate(func) if func is not None else decorate
+
+
+def collect_actions(model_admin: Any) -> list[Action]:
+    """The actions `model_admin` declares, in definition order.
+
+    The class hierarchy is walked base-first, so a subclass's actions follow
+    its base's. A subclass that re-decorates a name replaces that name's
+    options but keeps its position; one that overrides the method without
+    decorating it keeps the base's options and runs its own body, because the
+    handler is looked up on the instance.
+    """
+    found: dict[str, ActionOptions] = {}
+    for klass in reversed(type(model_admin).__mro__):
+        for name, member in vars(klass).items():
+            options = getattr(member, _OPTIONS_ATTR, None)
+            if isinstance(options, ActionOptions):
+                found[name] = options
+    return [
+        Action(
+            name=name,
+            handler=getattr(model_admin, name),
+            label=options.label or name.replace("_", " ").title(),
+            confirm=options.confirm,
+            permission=options.permission,
+            where=options.where,
+        )
+        for name, options in found.items()
+    ]

polyadmin/core/admin.py

@@ -0,0 +1,129 @@
+"""Admin: the root object mounted by the host application.
+
+Owns the ModelAdmin registry, the AdminPage registry (custom routes
+registered via `route()`), and the authenticator/authorizer/dashboard
+wiring. CRUD/page route generation and template/static configuration
+live in the framework adapters (e.g. polyadmin.fastapi), not here.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Mapping, Sequence
+from pathlib import Path
+from typing import Any
+
+from polyadmin.core.model_admin import ModelAdmin
+from polyadmin.core.page import AdminPage, PageHandler
+
+
+class Admin:
+    """Root admin application: owns the ModelAdmin and AdminPage registries."""
+
+    def __init__(
+        self,
+        model_admins: Iterable[ModelAdmin] = (),
+        *,
+        dashboard: Any | None = None,
+        authenticator: Any | None = None,
+        authorizer: Any | None = None,
+        site_title: str = "PolyAdmin",
+        site_logo_url: str | None = None,
+        disable_csrf: bool = False,
+        audit_logger: Any | None = None,
+        login_backend: Any | None = None,
+        default_locale: str = "en",
+        locales: Sequence[str] = (),
+        locale_resolver: Callable[[Any, Any], str | None] | None = None,
+        catalogs: Sequence[tuple[str | Path, str]] = (),
+        translator: Any | None = None,
+        locale_names: Mapping[str, str] | None = None,
+        locale_switcher: bool = True,
+        pseudo_locale: bool = False,
+    ) -> None:
+        self.dashboard = dashboard
+        self.authenticator = authenticator
+        self.authorizer = authorizer
+        self.site_title = site_title
+        self.site_logo_url = site_logo_url
+        # Opt-out, never opt-in: a security control that defaults to off
+        # is one nobody turns on. The token cookie is still minted when
+        # this is set, so templates and custom pages behave identically.
+        self.disable_csrf = disable_csrf
+        # When set, receives an entry for every create, update, delete
+        # and action. None means nothing is recorded -- the framework
+        # does not store a log itself. See core/audit.py.
+        self.audit_logger = audit_logger
+        # When set, mounts the built-in login page and makes an
+        # unauthenticated request redirect there instead of returning
+        # 401. None leaves both behaviours off -- see core/login.py.
+        self.login_backend = login_backend
+        # Internationalisation -- see polyadmin/i18n and docs/i18n.md. The
+        # defaults serve English plus every framework catalog (fr, ru),
+        # resolved per request, with the language switcher shown.
+        # locale_resolver(request, principal) gets the request's
+        # authenticated principal on every page, login and error pages
+        # included -- None only without a session or an authenticator.
+        self.default_locale = default_locale
+        self.locales = list(locales)
+        self.locale_resolver = locale_resolver
+        self.catalogs = list(catalogs)
+        self.translator = translator
+        self.locale_names = dict(locale_names or {})
+        self.locale_switcher = locale_switcher
+        self.pseudo_locale = pseudo_locale
+        self._registry: dict[str, ModelAdmin] = {}
+        self._pages: dict[str, AdminPage] = {}
+        for model_admin in model_admins:
+            self.register(model_admin)
+
+    def register(self, model_admin: ModelAdmin) -> None:
+        slug = model_admin.get_slug()
+        if slug in self._registry:
+            raise ValueError(f"A ModelAdmin is already registered for slug {slug!r}.")
+        model_admin.validate_detail_actions()
+        self._registry[slug] = model_admin
+
+    def get_model_admin(self, slug: str) -> ModelAdmin:
+        try:
+            return self._registry[slug]
+        except KeyError:
+            raise KeyError(f"No ModelAdmin registered for slug {slug!r}.") from None
+
+    @property
+    def model_admins(self) -> list[ModelAdmin]:
+        return list(self._registry.values())
+
+    def route(
+        self,
+        path: str,
+        handler: PageHandler,
+        *,
+        label: str | None = None,
+        category: str | None = None,
+        icon: str = "collection",
+        permission: str | None = None,
+        methods: tuple[str, ...] = ("GET", "POST"),
+        show_in_nav: bool = True,
+    ) -> AdminPage:
+        """Register a custom admin page -- for functionality that isn't
+        resource CRUD (reports, wizards, internal tools). See
+        docs/routing.md.
+        """
+        page = AdminPage(
+            path,
+            handler,
+            label=label,
+            category=category,
+            icon=icon,
+            permission=permission,
+            methods=methods,
+            show_in_nav=show_in_nav,
+        )
+        if page.path in self._pages:
+            raise ValueError(f"A page is already registered for path {page.path!r}.")
+        self._pages[page.path] = page
+        return page
+
+    @property
+    def pages(self) -> list[AdminPage]:
+        return list(self._pages.values())

polyadmin/core/audit.py

@@ -0,0 +1,65 @@
+"""Audit logging: who changed what, and where the record of it lives."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any, Protocol, runtime_checkable
+
+AUDIT_CREATE = "create"
+AUDIT_UPDATE = "update"
+AUDIT_DELETE = "delete"
+
+
+@dataclass
+class AuditEntry:
+    """One recorded change: who did what to which record. Deliberately flat and
+    free of references into application state, since an entry outlives the
+    request that made it and a logger may serialise it.
+    """
+
+    # When the change happened. Set by the framework, not the logger, so
+    # entries from several processes agree on what "now" meant.
+    at: datetime
+    # One of AUDIT_CREATE/AUDIT_UPDATE/AUDIT_DELETE, or an Action's name
+    # when a bulk or record action ran.
+    action: str
+    # The label is captured at write time because the record may not exist
+    # by the time anyone reads the log.
+    resource: str
+    object_pk: Any = None
+    object_label: str = ""
+    # Who made the change. None when no authenticator is configured,
+    # which is also the case in which an audit log is least meaningful.
+    principal: Any = None
+
+
+@runtime_checkable
+class AuditLogger(Protocol):
+    """Receives an entry per change.
+
+    The framework never stores entries itself: it does not own persistence any
+    more than it owns identity, so where the log lives is the application's
+    decision.
+
+    `record` is called after the change has succeeded. An error is reported,
+    not swallowed, but never rolls the change back: the record is already
+    written, and failing the request would leave the user with an error next to
+    a change that did happen.
+    """
+
+    def record(self, entry: AuditEntry) -> None:
+        ...
+
+
+@runtime_checkable
+class AuditReader(Protocol):
+    """The optional read side. A logger implementing it too gets a History section
+    on the record's detail page; one that does not simply records without
+    surfacing anything. Same optional-capability shape as list_page.
+    """
+
+    def history(self, resource: str, pk: Any, limit: int) -> list[AuditEntry]:
+        """The most recent entries for one record, newest first, capped
+        at `limit`."""
+        ...

polyadmin/core/auth.py

@@ -0,0 +1,52 @@
+"""Authenticator: Request -> Principal.
+
+The admin doesn't care whether authentication comes from session
+cookies, JWT, OAuth, or an existing IAM service -- only that something
+can turn an inbound request into a Principal, or None if unauthenticated.
+`request` is intentionally untyped here: whatever object the adapter
+(e.g. a FastAPI Request) passes through is opaque to core.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Protocol
+
+from polyadmin.i18n import N_
+
+
+@dataclass
+class Principal:
+    id: Any
+    display_name: str = ""
+    is_superuser: bool = False
+    extra: dict[str, Any] = field(default_factory=dict)
+
+
+class Authenticator(Protocol):
+    def authenticate(self, request: Any) -> Principal | None:
+        """May also be `async def`, returning an Awaitable[Principal | None];
+        the FastAPI adapter awaits it via acached_principal when it is."""
+        ...
+
+
+class AllowAllAuthenticator:
+    """Authenticates every request as the same Principal.
+
+    For local development and tests only -- never wire this into a
+    real deployment.
+    """
+
+    def __init__(self, principal: Principal | None = None) -> None:
+        # N_: the sidebar translates this default name (and only this one
+        # -- a principal's own name is never translated).
+        self._principal = principal or Principal(id="anonymous", display_name=N_("Anonymous"), is_superuser=True)
+
+    def authenticate(self, request: Any) -> Principal | None:
+        return self._principal
+
+
+class DenyAllAuthenticator:
+    """Authenticates nobody. Useful for asserting a login gate works."""
+
+    def authenticate(self, request: Any) -> Principal | None:
+        return None

polyadmin/core/authorization.py

@@ -0,0 +1,48 @@
+"""Authorizer: can(principal, permission, resource).
+
+Standard permission names: `dashboard.view` and, per resource,
+`{slug}.list` / `.view` / `.create` / `.update` / `.delete` / `.export`,
+built by `resource_permission`. Applications add action-specific
+permission strings of their own alongside these.
+
+Authorization is always enforced server-side by the adapter --
+`resource_permission` results also flow into templates so they can
+hide controls the current principal can't use, but that's a UX
+nicety, never the security boundary itself.
+"""
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+DASHBOARD_VIEW = "dashboard.view"
+
+
+def resource_permission(slug: str, action: str) -> str:
+    return f"{slug}.{action}"
+
+
+class Authorizer(Protocol):
+    def can(self, principal: Any, permission: str, resource: Any = None) -> bool: ...
+
+
+class AllowAllAuthorizer:
+    """Grants every permission. For local development and tests only."""
+
+    def can(self, principal: Any, permission: str, resource: Any = None) -> bool:
+        return True
+
+
+class DenyAllAuthorizer:
+    """Denies every permission. Useful for asserting a gate works."""
+
+    def can(self, principal: Any, permission: str, resource: Any = None) -> bool:
+        return False
+
+
+class SuperuserAuthorizer:
+    """Grants every permission to superusers, denies everyone else -- a
+    reasonable default before an application builds out granular roles.
+    """
+
+    def can(self, principal: Any, permission: str, resource: Any = None) -> bool:
+        return bool(getattr(principal, "is_superuser", False))

polyadmin/core/csrf.py

@@ -0,0 +1,70 @@
+"""CSRF token primitives.
+
+The wire names below are shared with both
+adapters' templates. Changing one side without the other silently breaks
+every form in the other language.
+"""
+
+from __future__ import annotations
+
+import hmac
+import secrets
+from urllib.parse import urlsplit
+
+CSRF_COOKIE_NAME = "admin_csrf"
+CSRF_HEADER_NAME = "X-CSRF-Token"
+CSRF_FIELD_NAME = "_csrf"
+
+_SAFE_METHODS = frozenset({"GET", "HEAD", "OPTIONS", "TRACE"})
+
+
+def new_csrf_token() -> str:
+    """32 crypto-random bytes as unpadded base64url (43 characters)."""
+    return secrets.token_urlsafe(32)
+
+
+def is_safe_method(method: str) -> bool:
+    """Whether a method is read-only per RFC 9110, and so needs no token."""
+    return method.upper() in _SAFE_METHODS
+
+
+def csrf_tokens_match(a: str | None, b: str | None) -> bool:
+    """Constant-time compare.
+
+    Empty on either side is always False: "no cookie" and "no submitted
+    token" must fail closed rather than match each other.
+    """
+    if not a or not b:
+        return False
+    return hmac.compare_digest(a, b)
+
+
+def safe_redirect_path(referer: str | None, host: str, base_path: str, fallback: str) -> str:
+    """Validate a client-supplied Referer before using it as a redirect
+    target, returning `fallback` when it cannot be trusted.
+
+    A raw Referer is attacker-controlled: without this, an action could be
+    made to bounce the signed-in admin to any site on the internet. The
+    return value is always a path, so the redirect can only ever land
+    inside this admin.
+    """
+    if not referer:
+        return fallback
+    try:
+        parsed = urlsplit(referer)
+    except ValueError:
+        return fallback
+    # A non-empty host must be ours. This also rejects protocol-relative
+    # "//evil.example.com/admin", which parses with no scheme but a
+    # foreign netloc.
+    if parsed.netloc and parsed.netloc != host:
+        return fallback
+    # A path a browser reads as protocol-relative: "//evil.example/x", or
+    # "/\\evil.example/x" (browsers treat "\\" like "/"). Under a root
+    # mount every path passes the base check below, so refuse these first.
+    if parsed.path.startswith(("//", "/\\")):
+        return fallback
+    # Exact match, or a child path -- "/adminX" must not pass for "/admin".
+    if parsed.path != base_path and not parsed.path.startswith(base_path + "/"):
+        return fallback
+    return f"{parsed.path}?{parsed.query}" if parsed.query else parsed.path

polyadmin/core/dashboard.py

@@ -0,0 +1,41 @@
+"""Dashboard: a separate first-class concept.
+
+The dashboard route is `GET /admin`. It's independent of any single
+ModelAdmin -- a Dashboard is just a collection of Widgets, each
+deciding its own data and, optionally, its own extra permission.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+
+from polyadmin.core.widget import Widget
+
+
+class Dashboard:
+    def __init__(
+        self, *, title: str = "Dashboard", widgets: Sequence[Widget] = ()
+    ) -> None:
+        self.title = title
+        self.widgets = list(widgets)
+
+    def get_widgets(
+        self, principal: Any = None, authorizer: Any = None
+    ) -> list[Widget]:
+        """Widgets visible to `principal`: a widget with no
+        `permission` is always shown; one that names a permission is
+        simply omitted -- not shown-disabled -- if the authorizer
+        denies it (or there's no authorizer to ask, in which case it's
+        shown, matching the rest of the framework's no-authorizer
+        default of permitting everything).
+        """
+        visible = []
+        for widget in self.widgets:
+            if (
+                widget.permission is None
+                or authorizer is None
+                or authorizer.can(principal, widget.permission, widget)
+            ):
+                visible.append(widget)
+        return visible