codex-fastapi-cabinet 0.1.0__py3-none-any.whl

fastapi_cabinet/contracts/navigation.py

@@ -0,0 +1,29 @@
+from pydantic import BaseModel, ConfigDict
+
+
+class SidebarItem(BaseModel):
+    """A navigation item shown inside the active admin module."""
+
+    model_config = ConfigDict(frozen=True)
+
+    key: str
+    label: str
+    path: str
+    icon: str = ""
+    badge_key: str | None = None
+    order: int = 100
+    permission: str | None = None
+
+
+class HeaderItem(BaseModel):
+    """A top-level registered admin module."""
+
+    model_config = ConfigDict(frozen=True)
+
+    key: str
+    label: str
+    path: str
+    icon: str = ""
+    group: str = "main"
+    group_label: str = ""
+    order: int = 100

fastapi_cabinet/contracts/pages.py

@@ -0,0 +1,164 @@
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from fastapi_cabinet.contracts.widgets import TableActionMap, TableColumnMap
+
+
+class CabinetPage(BaseModel):
+    """Declarative management page connected to an async provider."""
+
+    model_config = ConfigDict(frozen=True)
+
+    key: str
+    label: str
+    path: str
+    provider: str
+    kind: str
+    order: int = 100
+    permission: str | None = None
+    template: str | None = None
+
+
+class ListPage(CabinetPage):
+    kind: Literal["list"] = "list"
+
+
+class DetailPage(CabinetPage):
+    kind: Literal["detail"] = "detail"
+
+
+class FormPage(CabinetPage):
+    kind: Literal["form"] = "form"
+
+
+class OperationPage(CabinetPage):
+    kind: Literal["operation"] = "operation"
+
+
+class FilterChoiceMap(BaseModel):
+    value: str
+    label: str
+    selected: bool = False
+
+
+class FilterFieldMap(BaseModel):
+    name: str
+    label: str
+    value: str = ""
+    input_type: Literal["text", "search", "select", "checkbox"] = "text"
+    choices: list[FilterChoiceMap] = Field(default_factory=list)
+
+
+class PaginationMap(BaseModel):
+    page: int = Field(ge=1)
+    pages: int = Field(ge=1)
+    total: int = Field(ge=0)
+    previous_url: str | None = None
+    next_url: str | None = None
+
+
+class ListPageMap(BaseModel):
+    kind: Literal["list"] = "list"
+    title: str
+    subtitle: str | None = None
+    columns: list[TableColumnMap]
+    rows: list[dict[str, Any]]
+    filters: list[FilterFieldMap] = Field(default_factory=list)
+    pagination: PaginationMap | None = None
+    row_href_key: str | None = None
+    actions: list[TableActionMap] = Field(default_factory=list)
+    create_url: str | None = None
+    create_label: str = "Create"
+    empty_message: str = "No records found."
+
+
+class DetailFieldMap(BaseModel):
+    label: str
+    value: Any = None
+    key: str | None = None
+
+
+class DetailSectionMap(BaseModel):
+    title: str
+    fields: list[DetailFieldMap] = Field(default_factory=list)
+
+
+class PageLinkMap(BaseModel):
+    label: str
+    url: str
+    css_class: str = ""
+
+
+class DetailPageMap(BaseModel):
+    kind: Literal["detail"] = "detail"
+    title: str
+    subtitle: str | None = None
+    fields: list[DetailFieldMap] = Field(default_factory=list)
+    sections: list[DetailSectionMap] = Field(default_factory=list)
+    actions: list[PageLinkMap] = Field(default_factory=list)
+    back_url: str | None = None
+
+
+class FormChoiceMap(BaseModel):
+    value: str
+    label: str
+    selected: bool = False
+
+
+class FormFieldMap(BaseModel):
+    name: str
+    label: str
+    input_type: Literal[
+        "text",
+        "email",
+        "password",
+        "number",
+        "textarea",
+        "select",
+        "checkbox",
+        "hidden",
+        "url",
+    ] = "text"
+    value: Any = ""
+    placeholder: str = ""
+    help_text: str | None = None
+    required: bool = False
+    disabled: bool = False
+    choices: list[FormChoiceMap] = Field(default_factory=list)
+    errors: list[str] = Field(default_factory=list)
+
+
+class FormPageMap(BaseModel):
+    kind: Literal["form"] = "form"
+    title: str
+    action_url: str
+    fields: list[FormFieldMap]
+    method: Literal["POST", "PUT", "PATCH"] = "POST"
+    subtitle: str | None = None
+    submit_label: str = "Save"
+    cancel_url: str | None = None
+    cancel_label: str = "Cancel"
+    errors: list[str] = Field(default_factory=list)
+
+
+class OperationActionMap(BaseModel):
+    key: str
+    label: str
+    action_url: str
+    method: Literal["POST", "PUT", "PATCH", "DELETE"] = "POST"
+    description: str | None = None
+    confirmation: str | None = None
+    css_class: str = ""
+
+
+class OperationPageMap(BaseModel):
+    kind: Literal["operation"] = "operation"
+    title: str
+    subtitle: str | None = None
+    description: str | None = None
+    actions: list[OperationActionMap] = Field(default_factory=list)
+    notices: list[str] = Field(default_factory=list)
+
+
+type PageMap = ListPageMap | DetailPageMap | FormPageMap | OperationPageMap

fastapi_cabinet/contracts/permissions.py

@@ -0,0 +1,16 @@
+from typing import Protocol
+
+from fastapi import Request
+
+
+class PermissionProvider(Protocol):
+    """Application-owned authorization port."""
+
+    async def can(self, request: Request, permission: str) -> bool: ...
+
+
+class AllowAllPermissionProvider:
+    """Convenient default for apps that secure the whole mount externally."""
+
+    async def can(self, request: Request, permission: str) -> bool:
+        return True

fastapi_cabinet/contracts/providers.py

@@ -0,0 +1,9 @@
+from collections.abc import Awaitable, Callable
+
+from fastapi import Request
+
+from fastapi_cabinet.contracts.pages import PageMap
+from fastapi_cabinet.contracts.widgets import WidgetMap
+
+type ProviderResult = WidgetMap | PageMap
+type CabinetProvider = Callable[[Request], Awaitable[ProviderResult]]

fastapi_cabinet/contracts/widgets.py

@@ -0,0 +1,102 @@
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class DashboardWidget(BaseModel):
+    """Declarative widget connected to an async provider."""
+
+    model_config = ConfigDict(frozen=True)
+
+    key: str
+    title: str
+    provider: str
+    kind: str
+    order: int = 100
+    permission: str | None = None
+    span: int = Field(default=1, ge=1, le=4)
+
+
+class MetricWidget(DashboardWidget):
+    kind: Literal["metric"] = "metric"
+    icon: str = ""
+
+
+class TableWidget(DashboardWidget):
+    kind: Literal["table"] = "table"
+
+
+class ListWidget(DashboardWidget):
+    kind: Literal["list"] = "list"
+
+
+class ChartWidget(DashboardWidget):
+    kind: Literal["chart"] = "chart"
+    chart_type: Literal["bar", "line", "pie", "doughnut"] = "bar"
+
+
+class MetricWidgetMap(BaseModel):
+    kind: Literal["metric"] = "metric"
+    key: str
+    title: str
+    value: str
+    subtitle: str | None = None
+    trend: str | None = None
+    icon: str = ""
+    span: int = Field(default=1, ge=1, le=4)
+
+
+class TableColumnMap(BaseModel):
+    key: str
+    label: str
+    align: Literal["left", "center", "right"] = "left"
+
+
+class TableActionMap(BaseModel):
+    key: str
+    label: str
+    action_url: str
+    method: Literal["POST", "PUT", "PATCH", "DELETE"] = "POST"
+    css_class: str = ""
+    permission: str | None = None
+
+
+class TableWidgetMap(BaseModel):
+    kind: Literal["table"] = "table"
+    key: str
+    title: str
+    columns: list[TableColumnMap]
+    rows: list[dict[str, Any]]
+    row_href_key: str | None = None
+    actions: list[TableActionMap] = Field(default_factory=list)
+    empty_message: str = "No data."
+    span: int = Field(default=1, ge=1, le=4)
+
+
+class ListWidgetMap(BaseModel):
+    kind: Literal["list"] = "list"
+    key: str
+    title: str
+    items: list[str] = Field(default_factory=list)
+    empty_message: str = "No data."
+    span: int = Field(default=1, ge=1, le=4)
+
+
+class ChartDatasetMap(BaseModel):
+    label: str
+    data: list[float]
+    color: str | None = None
+
+
+class ChartWidgetMap(BaseModel):
+    kind: Literal["chart"] = "chart"
+    key: str
+    title: str
+    chart_type: Literal["bar", "line", "pie", "doughnut"]
+    labels: list[str]
+    datasets: list[ChartDatasetMap]
+    height: int = Field(default=280, ge=120, le=1200)
+    span: int = Field(default=1, ge=1, le=4)
+
+
+type WidgetMap = MetricWidgetMap | TableWidgetMap | ListWidgetMap | ChartWidgetMap

fastapi_cabinet/exceptions.py

@@ -0,0 +1,18 @@
+class CabinetError(Exception):
+    """Base error for cabinet configuration and rendering failures."""
+
+
+class CabinetRegistrationError(CabinetError):
+    """Raised when an admin declaration cannot be registered."""
+
+
+class CabinetDuplicateKeyError(CabinetRegistrationError):
+    """Raised when two admin declarations use the same key."""
+
+
+class CabinetModuleLoadError(CabinetError):
+    """Raised when a configured cabinet module cannot be loaded."""
+
+
+class CabinetProviderError(CabinetError):
+    """Raised when a provider cannot be resolved or returns an invalid map."""

fastapi_cabinet/fastapi.py

@@ -0,0 +1,36 @@
+from collections.abc import Sequence
+from pathlib import Path
+
+from fastapi import FastAPI
+from fastapi.staticfiles import StaticFiles
+
+from fastapi_cabinet.loader import CabinetModuleRef, load_cabinet_modules
+from fastapi_cabinet.runtime import normalize_mount_path
+from fastapi_cabinet.site import CabinetSite
+
+
+def include_cabinet(
+    app: FastAPI,
+    *,
+    modules: Sequence[CabinetModuleRef] = (),
+    mount_path: str = "/cabinet",
+    static_mount_path: str | None = None,
+    site: CabinetSite | None = None,
+) -> CabinetSite:
+    """Load modules and attach one cabinet site to a FastAPI application."""
+
+    active_site = site or CabinetSite()
+    if modules:
+        load_cabinet_modules(modules, active_site.registry)
+    mount = normalize_mount_path(mount_path)
+    assets = static_mount_path or f"{mount.rstrip('/')}/static"
+    active_site.static_mount_path = assets
+    app.include_router(active_site.build_router(mount_path=mount, static_mount_path=assets))
+
+    static_dir = Path(__file__).parent / "static"
+    app.mount(
+        assets,
+        StaticFiles(directory=static_dir),
+        name=f"fastapi_cabinet_static_{id(active_site)}",
+    )
+    return active_site

fastapi_cabinet/loader.py

@@ -0,0 +1,68 @@
+from collections.abc import Sequence
+from importlib import import_module
+from inspect import signature
+from types import ModuleType
+
+from fastapi_cabinet.contracts.admin import CabinetAdmin
+from fastapi_cabinet.exceptions import CabinetModuleLoadError
+from fastapi_cabinet.registry import CabinetRegistry
+
+type CabinetModuleRef = str | ModuleType
+
+
+def load_cabinet_modules(
+    modules: Sequence[CabinetModuleRef],
+    registry: CabinetRegistry,
+) -> tuple[ModuleType, ...]:
+    """Load modules through an explicit hook or a CABINET_ADMINS declaration."""
+
+    loaded: list[ModuleType] = []
+    for ref in modules:
+        try:
+            module = import_module(ref) if isinstance(ref, str) else ref
+        except ImportError as exc:
+            raise CabinetModuleLoadError(f"Could not import cabinet module {ref!r}.") from exc
+
+        hook = getattr(module, "register_cabinet", None)
+        declarations = getattr(module, "CABINET_ADMINS", None)
+        if hook is not None:
+            _call_registration_hook(module, hook, registry)
+        elif declarations is not None:
+            _register_declarations(module, declarations, registry)
+        else:
+            raise CabinetModuleLoadError(
+                f"Cabinet module {module.__name__!r} must expose register_cabinet(registry) or CABINET_ADMINS."
+            )
+        loaded.append(module)
+    return tuple(loaded)
+
+
+def _call_registration_hook(module: ModuleType, hook: object, registry: CabinetRegistry) -> None:
+    if not callable(hook):
+        raise CabinetModuleLoadError(
+            f"Cabinet module {module.__name__!r} defines register_cabinet, but it is not callable."
+        )
+    try:
+        parameters = signature(hook).parameters
+    except (TypeError, ValueError) as exc:
+        raise CabinetModuleLoadError(
+            f"Cabinet module {module.__name__!r} has an invalid register_cabinet hook."
+        ) from exc
+    if len(parameters) != 1:
+        raise CabinetModuleLoadError(
+            f"Cabinet module {module.__name__!r} register_cabinet hook must accept exactly one registry."
+        )
+    hook(registry)
+
+
+def _register_declarations(module: ModuleType, declarations: object, registry: CabinetRegistry) -> None:
+    if not isinstance(declarations, (tuple, list)):
+        raise CabinetModuleLoadError(f"Cabinet module {module.__name__!r} CABINET_ADMINS must be a sequence.")
+    for declaration in declarations:
+        if not isinstance(declaration, CabinetAdmin) and not (
+            isinstance(declaration, type) and issubclass(declaration, CabinetAdmin)
+        ):
+            raise CabinetModuleLoadError(
+                f"Cabinet module {module.__name__!r} contains a non-CabinetAdmin declaration."
+            )
+        registry.register(declaration)

fastapi_cabinet/registry.py

@@ -0,0 +1,31 @@
+from collections.abc import Iterable
+
+from fastapi_cabinet.contracts.admin import CabinetAdmin
+from fastapi_cabinet.exceptions import CabinetDuplicateKeyError, CabinetRegistrationError
+
+
+class CabinetRegistry:
+    """Application-scoped registry of cabinet modules."""
+
+    def __init__(self) -> None:
+        self._admins: dict[str, CabinetAdmin] = {}
+
+    def register(self, admin: type[CabinetAdmin] | CabinetAdmin) -> CabinetAdmin:
+        admin_instance = admin() if isinstance(admin, type) else admin
+        key = getattr(admin_instance, "key", "").strip()
+        label = getattr(admin_instance, "label", "").strip()
+        if not key or not label:
+            raise CabinetRegistrationError("Cabinet admin must define non-empty key and label values.")
+        if key in self._admins:
+            raise CabinetDuplicateKeyError(f"Cabinet admin key {key!r} is already registered.")
+        self._admins[key] = admin_instance
+        return admin_instance
+
+    def get(self, key: str) -> CabinetAdmin:
+        return self._admins[key]
+
+    def all(self) -> tuple[CabinetAdmin, ...]:
+        return tuple(sorted(self._admins.values(), key=lambda admin: (admin.order, admin.key)))
+
+    def keys(self) -> Iterable[str]:
+        return self._admins.keys()

fastapi_cabinet/rendering/__init__.py

@@ -0,0 +1,5 @@
+from fastapi_cabinet.rendering.layout_mapper import build_layout_map
+from fastapi_cabinet.rendering.page_mapper import resolve_page
+from fastapi_cabinet.rendering.widget_mapper import resolve_widget, resolve_widgets
+
+__all__ = ["build_layout_map", "resolve_page", "resolve_widget", "resolve_widgets"]

fastapi_cabinet/rendering/layout_mapper.py

@@ -0,0 +1,88 @@
+from functools import lru_cache
+from pathlib import Path
+
+from fastapi_cabinet.contracts.admin import CabinetAdmin
+from fastapi_cabinet.contracts.layout import CabinetLayoutMap, HeaderGroup
+from fastapi_cabinet.contracts.navigation import HeaderItem, SidebarItem
+from fastapi_cabinet.runtime import admin_public_path
+
+_STATIC_DIR = Path(__file__).parents[1] / "static"
+
+
+def build_layout_map(
+    admins: tuple[CabinetAdmin, ...],
+    *,
+    mount_path: str,
+    static_mount_path: str,
+    brand_name: str,
+    active_admin: CabinetAdmin | None,
+    active_path: str,
+    sidebar: list[SidebarItem] | None = None,
+    sidebar_badges: dict[str, int | str] | None = None,
+    title: str | None = None,
+) -> CabinetLayoutMap:
+    header = [
+        HeaderItem(
+            key=admin.key,
+            label=admin.label,
+            path=admin_public_path(admin, mount_path),
+            icon=admin.icon,
+            group=admin.group,
+            group_label=admin.group_label,
+            order=admin.order,
+        )
+        for admin in admins
+    ]
+    return CabinetLayoutMap(
+        mount_path=mount_path,
+        static_mount_path=static_mount_path,
+        static_version=_static_version(),
+        brand_name=brand_name,
+        title=title or (active_admin.label if active_admin else brand_name),
+        active_module=active_admin.key if active_admin else None,
+        active_path=active_path,
+        header_groups=_build_header_groups(header),
+        sidebar=_build_sidebar(sidebar or [], active_admin, mount_path),
+        sidebar_badges=sidebar_badges or {},
+    )
+
+
+def _build_header_groups(header: list[HeaderItem]) -> list[HeaderGroup]:
+    groups: dict[str, HeaderGroup] = {}
+    for item in sorted(header, key=lambda value: (value.order, value.key)):
+        if item.group not in groups:
+            groups[item.group] = HeaderGroup(
+                key=item.group,
+                label=item.group_label or item.group,
+                items=[],
+            )
+        groups[item.group].items.append(item)
+    return list(groups.values())
+
+
+def _build_sidebar(
+    sidebar: list[SidebarItem],
+    active_admin: CabinetAdmin | None,
+    mount_path: str,
+) -> list[SidebarItem]:
+    items = sorted(sidebar, key=lambda item: (item.order, item.key))
+    if active_admin is None:
+        return items
+    base_path = admin_public_path(active_admin, mount_path).rstrip("/")
+    return [
+        item
+        if item.path.startswith("/")
+        else item.model_copy(update={"path": f"{base_path}/{item.path.strip('/')}"})
+        for item in items
+    ]
+
+
+@lru_cache(maxsize=1)
+def _static_version() -> str:
+    mtimes: list[int] = []
+    for relative in ("css/cabinet.css", "js/cabinet.js"):
+        try:
+            mtimes.append(int((_STATIC_DIR / relative).stat().st_mtime))
+        except OSError:
+            mtimes.append(0)
+    return str(max(mtimes))

fastapi_cabinet/rendering/page_mapper.py

@@ -0,0 +1,44 @@
+from typing import cast
+
+from fastapi import Request
+from pydantic import BaseModel, ValidationError
+
+from fastapi_cabinet.contracts.admin import CabinetAdmin
+from fastapi_cabinet.contracts.pages import (
+    CabinetPage,
+    DetailPageMap,
+    FormPageMap,
+    ListPageMap,
+    OperationPageMap,
+    PageMap,
+)
+from fastapi_cabinet.exceptions import CabinetProviderError
+
+
+async def resolve_page(admin: CabinetAdmin, declaration: CabinetPage, request: Request) -> PageMap:
+    provider = admin.providers.get(declaration.provider)
+    if provider is None:
+        raise CabinetProviderError(
+            f"Provider {declaration.provider!r} is not registered for cabinet admin {admin.key!r}."
+        )
+    result = await provider(request)
+    model = _model_for_kind(declaration.kind)
+    try:
+        return cast("PageMap", model.model_validate(result))
+    except ValidationError as exc:
+        raise CabinetProviderError(
+            f"Provider {declaration.provider!r} returned an invalid {declaration.kind!r} page map."
+        ) from exc
+
+
+def _model_for_kind(kind: str) -> type[BaseModel]:
+    models: dict[str, type[BaseModel]] = {
+        "list": ListPageMap,
+        "detail": DetailPageMap,
+        "form": FormPageMap,
+        "operation": OperationPageMap,
+    }
+    try:
+        return models[kind]
+    except KeyError as exc:
+        raise CabinetProviderError(f"Unsupported cabinet page kind {kind!r}.") from exc

fastapi_cabinet/rendering/widget_mapper.py

@@ -0,0 +1,59 @@
+from typing import cast
+
+from fastapi import Request
+from pydantic import BaseModel, ValidationError
+
+from fastapi_cabinet.contracts.admin import CabinetAdmin
+from fastapi_cabinet.contracts.widgets import (
+    ChartWidgetMap,
+    DashboardWidget,
+    ListWidgetMap,
+    MetricWidgetMap,
+    TableWidgetMap,
+    WidgetMap,
+)
+from fastapi_cabinet.exceptions import CabinetProviderError
+
+
+async def resolve_widgets(
+    admin: CabinetAdmin,
+    declarations: tuple[DashboardWidget, ...],
+    request: Request,
+) -> list[WidgetMap]:
+    result: list[WidgetMap] = []
+    for declaration in sorted(declarations, key=lambda widget: (widget.order, widget.key)):
+        result.append(await resolve_widget(admin, declaration, request))
+    return result
+
+
+async def resolve_widget(
+    admin: CabinetAdmin,
+    declaration: DashboardWidget,
+    request: Request,
+) -> WidgetMap:
+    provider = admin.providers.get(declaration.provider)
+    if provider is None:
+        raise CabinetProviderError(
+            f"Provider {declaration.provider!r} is not registered for cabinet admin {admin.key!r}."
+        )
+    result = await provider(request)
+    model = _model_for_kind(declaration.kind)
+    try:
+        return cast("WidgetMap", model.model_validate(result))
+    except ValidationError as exc:
+        raise CabinetProviderError(
+            f"Provider {declaration.provider!r} returned an invalid {declaration.kind!r} widget map."
+        ) from exc
+
+
+def _model_for_kind(kind: str) -> type[BaseModel]:
+    models: dict[str, type[BaseModel]] = {
+        "metric": MetricWidgetMap,
+        "table": TableWidgetMap,
+        "list": ListWidgetMap,
+        "chart": ChartWidgetMap,
+    }
+    try:
+        return models[kind]
+    except KeyError as exc:
+        raise CabinetProviderError(f"Unsupported dashboard widget kind {kind!r}.") from exc