fastapi-admin-kit 0.1.0__py3-none-any.whl

fastapi_admin_kit/modeladmin.py

@@ -0,0 +1,375 @@
+"""ModelAdmin base class — configuration + lifecycle hooks + validation."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from fastapi_admin_kit.admin.decorators import column
+from fastapi_admin_kit.types import ExtraField, FieldMeta
+
+if TYPE_CHECKING:
+    from sqlalchemy.orm import Session
+
+    from fastapi_admin_kit.nav import NavItemConfig
+
+
+class ModelAdmin:
+    """Base class for model admin configuration.
+
+    Subclass this to customise how a model is displayed, filtered, and edited.
+    All fields are optional — unset fields fall back to auto-detected values.
+    """
+
+    # List view config
+    list_display: list[str] | None = None
+    list_filter: list[str] | None = None
+    search_fields: list[str] | None = None
+    ordering: list[str] | None = None
+    per_page: int = 20
+    pagination: Any = None  # OffsetPagination | CursorPagination | DynamicPagination
+    list_filter_options: dict[str, dict[str, Any]] = {}
+    list_filter_horizontal: bool = False
+
+    # Actions config
+    actions_list: list[str] = []
+    actions_row: list[str] = []
+    actions_detail: list[str] = []
+    actions_submit_line: list[str] = []
+    actions_list_hide_default: bool = False
+
+    # Form config
+    fields: list[str] | None = None
+    exclude: list[str] | None = None
+    readonly_fields: list[str] | None = None
+    formfield_overrides: dict[str, Any] = {}
+    extra_fields: list[ExtraField] = []
+    fieldsets: list[
+        Any
+    ] = []  # FieldsetSpec accepted but not strictly enforced here
+    field_placeholders: dict[str, str] = {}  # {field_name: placeholder_text}
+
+    # Conditional fields
+    conditional_fields: dict[str, dict[str, Any]] = {}
+
+    # Form UX config
+    warn_unsaved_form: bool = True
+    compressed_fields: bool = True
+    change_form_show_cancel_button: bool = True
+
+    # Labels and display
+    verbose_name: str | None = None
+    verbose_name_plural: str | None = None
+    icon: str | None = None
+    tag: str | None = None
+    tags: list[str] | None = None
+    nav_order: int = 999
+    nav_children: list[NavItemConfig] | None = None
+
+    # Route generation
+    skip_auto_routes: bool = False
+
+    # Custom display functions (dict-based fallback)
+    display_functions: dict[str, Any] | None = None
+
+    # Decorator for custom column display
+    column = staticmethod(column)
+
+    # Badge hook — return str e.g. "12" or None
+    def get_nav_badge(self, request: Any = None) -> str | None:
+        return None
+
+    # Object display
+    def __str__(self, obj: Any) -> str:
+        """How to display an object in dropdowns/links."""
+        return str(
+            getattr(obj, "name", None)
+            or getattr(obj, "title", None)
+            or f"#{getattr(obj, 'id', '?')}"
+        )
+
+    def get_model(self) -> Any:
+        return self.model
+
+    # ── Query hooks ──────────────────────────────────────────────────
+
+    def get_queryset(self, session: Session, request: Any = None) -> Any:
+        """Override to filter records globally (e.g. soft-delete filter)."""
+        return session.query(self.model)  # type: ignore[attr-defined]
+
+    def get_object(self, session: Session, id: Any) -> Any:
+        """Override for custom PK lookup."""
+        return session.get(self.model, id)  # type: ignore[attr-defined]
+
+    # ── Lifecycle hooks (stubs) ─────────────────────────────────────
+
+    def prepare_create_data(self, data: dict[str, Any], request: Any = None) -> dict[str, Any]:
+        """Strip extra fields and return only model-column data for INSERT."""
+        extra_names = {f.name for f in self.extra_fields}
+        return {k: v for k, v in data.items() if k not in extra_names}
+
+    def prepare_update_data(self, data: dict[str, Any], request: Any = None) -> dict[str, Any]:
+        """Strip extra fields and return only model-column data for UPDATE."""
+        extra_names = {f.name for f in self.extra_fields}
+        return {k: v for k, v in data.items() if k not in extra_names}
+
+    def on_create(self, obj: Any, request: Any = None) -> None:
+        """Called before INSERT. Mutate *obj* as needed."""
+
+    def after_create(self, obj: Any, request: Any = None) -> None:
+        """Called after INSERT commit."""
+
+    def on_update(
+        self, obj: Any, data: dict[str, Any], request: Any = None
+    ) -> None:
+        """Called before UPDATE. *data* contains the incoming form values."""
+
+    def after_update(self, obj: Any, request: Any = None) -> None:
+        """Called after UPDATE commit."""
+
+    def on_delete(self, obj: Any, request: Any = None) -> None:
+        """Called before DELETE."""
+
+    def after_delete(self, obj: Any, request: Any = None) -> None:
+        """Called after DELETE commit."""
+
+    # ── Validation hooks (stubs) ────────────────────────────────────
+
+    def validate_create(
+        self, data: dict[str, Any], request: Any = None
+    ) -> dict[str, Any]:
+        """Validate and/or transform form data before create.
+
+        Return the (possibly modified) data dict.  Raise ``ValueError``
+        with a user-facing message to abort the operation.
+        """
+        return data
+
+    def validate_update(
+        self, obj: Any, data: dict[str, Any], request: Any = None
+    ) -> dict[str, Any]:
+        """Validate and/or transform form data before update.
+
+        Return the (possibly modified) data dict.  Raise ``ValueError``
+        with a user-facing message to abort the operation.
+        """
+        return data
+
+    # ── Form data processing hooks ──────────────────────────────────
+
+    def process_form_data(self, data: dict[str, Any], request: Any = None) -> dict[str, Any]:
+        """Process form data before save. Override for custom processing.
+
+        Called after form parsing and validation. Use this to transform
+        form data, extract special fields, or prepare data for saving.
+        """
+        return data
+
+    def save_model(
+        self, obj: Any, data: dict[str, Any], request: Any = None, is_create: bool = False
+    ) -> None:
+        """Custom save logic. Override for full control over save flow.
+
+        When overridden, this method is called instead of the default
+        save logic. The object is already added to the session but not
+        committed yet. Call session.commit() yourself if needed.
+        """
+        pass
+
+    # ── Form context hooks ──────────────────────────────────────────
+
+    def get_form_context(
+        self, context: dict[str, Any], obj: Any = None, request: Any = None
+    ) -> dict[str, Any]:
+        """Customize form template context. Return modified context.
+
+        Called when building the form context for create/edit views.
+        Override to add custom template variables.
+        """
+        return context
+
+    # ── Dynamic field hooks ─────────────────────────────────────────
+
+    def get_readonly_fields(self, obj: Any = None, request: Any = None) -> list[str]:
+        """Return list of readonly field names. Override for dynamic readonly.
+
+        Called during form field generation. Fields returned here are
+        in addition to the static readonly_fields list.
+        """
+        return self.readonly_fields or []
+
+    def get_hidden_fields(self, obj: Any = None, request: Any = None) -> list[str]:
+        """Return list of hidden field names. Override for dynamic hidden.
+
+        Called during form field generation. Hidden fields are excluded
+        from the form entirely.
+        """
+        return []
+
+    # ── Form field helper ───────────────────────────────────────────
+
+    def get_form_fields(
+        self,
+        obj: Any = None,
+        request: Any = None,
+        columns: list[Any] | None = None,
+        relationships: list[Any] | None = None,
+    ) -> list[FieldMeta]:
+        """Return ordered list of FieldMeta objects for the create/edit form."""
+        from fastapi_admin_kit.inspection import auto_label, is_required
+
+        columns = columns or []
+        relationships = relationships or []
+        form_fields: list[FieldMeta] = []
+
+        raw = []
+        if self.fields is not None:
+            names = set(self.fields)
+            raw = [
+                c for c in columns if c.name in names and not c.primary_key
+            ] + [
+                r
+                for r in relationships
+                if r.name in names
+                and r.direction in ("MANYTOONE", "MANYTOMANY")
+            ]
+        else:
+            raw = [c for c in columns if not c.primary_key] + [
+                r
+                for r in relationships
+                if r.direction in ("MANYTOONE", "MANYTOMANY")
+            ]
+            if self.exclude:
+                raw = [x for x in raw if x.name not in self.exclude]
+
+            # Exclude FK columns that have a corresponding relationship
+            # to avoid duplicate fields (e.g., user_id + user both showing)
+            from sqlalchemy import inspect as sa_inspect
+
+            rel_fk_cols: set[str] = set()
+            try:
+                mapper = sa_inspect(self.model)
+                for r in relationships:
+                    if r.direction in ("MANYTOONE", "MANYTOMANY"):
+                        rel_prop = mapper.relationships.get(r.name)
+                        if rel_prop is not None:
+                            for local_col in rel_prop.local_columns:
+                                rel_fk_cols.add(local_col.key)
+            except Exception:
+                pass
+            raw = [x for x in raw if not (hasattr(x, "foreign_keys") and x.name in rel_fk_cols)]
+
+        dynamic_readonly = set(self.get_readonly_fields())
+        dynamic_hidden = set(self.get_hidden_fields())
+
+        for item in raw:
+            name = item.name
+            if name in dynamic_hidden:
+                continue
+            readonly = name in (self.readonly_fields or []) or name in dynamic_readonly
+            required = is_required(item) if hasattr(item, "nullable") else False
+            label = auto_label(name)
+            placeholder = self.field_placeholders.get(
+                name, f"Enter {label.lower()}..."
+            )
+            form_fields.append(
+                FieldMeta(
+                    name=name,
+                    label=label,
+                    required=required,
+                    readonly=readonly,
+                    placeholder=placeholder,
+                )
+            )
+
+        for extra in self.extra_fields:
+            form_fields.append(
+                FieldMeta(
+                    name=extra.name,
+                    label=extra.label or auto_label(extra.name),
+                    required=extra.required,
+                    readonly=False,
+                    extra={
+                        "extra_field": True,
+                        "widget": extra.widget,
+                        "required_on_create": extra.required_on_create,
+                    },
+                )
+            )
+
+        # Respect fieldsets ordering if defined
+        if self.fieldsets:
+            ordered: list[FieldMeta] = []
+            seen: set[str] = set()
+            for fs in self.fieldsets:
+                for fname in fs.fields:
+                    for fm in form_fields:
+                        if fm.name == fname and fname not in seen:
+                            ordered.append(fm)
+                            seen.add(fname)
+                            break
+            for fm in form_fields:
+                if fm.name not in seen:
+                    ordered.append(fm)
+            return ordered
+
+        return form_fields
+
+    # ── Action helpers ─────────────────────────────────────────────
+
+    def get_actions_for_location(self, location: str) -> list[Any]:
+        """Get resolved Action instances for a given location (list/row/detail/submit_line)."""
+        from fastapi_admin_kit.actions.base import Action
+
+        action_names = getattr(self, f"actions_{location}", [])
+        resolved = []
+        for name in action_names:
+            action_fn = getattr(self, name, None)
+            if not action_fn:
+                continue
+            if hasattr(action_fn, "_admin_action"):
+                resolved.append(action_fn._admin_action())
+            elif callable(action_fn):
+                label = name.replace("_", " ").title()
+                _fn = action_fn
+                _admin = self
+
+                class _FallbackAction(Action):
+                    def __init__(self):
+                        super().__init__(name=name, label=label)
+
+                    async def execute(self, objects, request):
+                        import inspect
+
+                        if inspect.iscoroutinefunction(_fn):
+                            await _fn(_admin, objects, request)
+                        else:
+                            _fn(_admin, objects, request)
+
+                resolved.append(_FallbackAction())
+        return resolved
+
+    def get_list_actions(self) -> list[Any]:
+        return self.get_actions_for_location("list")
+
+    def get_row_actions(self) -> list[Any]:
+        return self.get_actions_for_location("row")
+
+    def get_detail_actions(self) -> list[Any]:
+        return self.get_actions_for_location("detail")
+
+    def get_submit_line_actions(self) -> list[Any]:
+        return self.get_actions_for_location("submit_line")
+
+    # ── Permission helpers ───────────────────────────────────────────
+
+    def has_view_permission(self, request: Any = None) -> bool:
+        return True
+
+    def has_create_permission(self, request: Any = None) -> bool:
+        return True
+
+    def has_edit_permission(self, request: Any = None) -> bool:
+        return True
+
+    def has_delete_permission(self, request: Any = None) -> bool:
+        return True

fastapi_admin_kit/models/__init__.py

@@ -0,0 +1,7 @@
+"""Admin database models — single import point for migrations and table creation."""
+
+from fastapi_admin_kit.models.base import Base
+
+__all__ = [
+    "Base",
+]

fastapi_admin_kit/models/base.py

@@ -0,0 +1,7 @@
+"""Shared SQLAlchemy DeclarativeBase for all admin tables."""
+
+from sqlalchemy.orm import DeclarativeBase
+
+
+class Base(DeclarativeBase):
+    """Base class for all fastapi_admin_kit SQLAlchemy models."""

fastapi_admin_kit/nav.py

@@ -0,0 +1,208 @@
+"""Navigation tag & group system for the admin sidebar.
+
+Implements the full tag system from TAG_SPEC.md:
+- NavGroupConfig / NavItemConfig — developer-provided config
+- BuiltNavGroup / BuiltNavItem — resolved output of SidebarBuilder
+- DefaultSidebarBuilder / SidebarBuilderProtocol
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from fastapi_admin_kit.registry import RegisteredModel
+
+
+# ---------------------------------------------------------------------------
+# Public config types (passed by the developer)
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class NavItemConfig:
+    """A custom nav item placed inside a tag group (independent of models)."""
+
+    label: str
+    url: str
+    icon: str | None = None
+    order: int = 999
+    permission: str | None = None
+
+
+@dataclass
+class NavGroupConfig:
+    """Developer-provided configuration for one sidebar tag group."""
+
+    tag: str
+    label: str | None = None
+    icon: str | None = None
+    order: int = 999
+    collapsed_by_default: bool = False
+    permission: str | None = None
+    extra_items: list[NavItemConfig] = field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------
+# Built types (produced by SidebarBuilder at startup — read-only in templates)
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class BuiltNavItem:
+    label: str
+    url: str
+    icon: str | None = None
+    order: int = 999
+    badge_fn: Callable | None = None
+    permission_table: str | None = None
+    children: list[BuiltNavItem] = field(default_factory=list)
+
+
+@dataclass
+class BuiltNavGroup:
+    tag: str
+    label: str
+    icon: str | None = None
+    order: int = 999
+    collapsed_by_default: bool = False
+    permission_table: str | None = None
+    items: list[BuiltNavItem] = field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------
+# SidebarBuilder protocol + default implementation
+# ---------------------------------------------------------------------------
+
+
+@runtime_checkable
+class SidebarBuilder(Protocol):
+    """Protocol that all sidebar builders must satisfy."""
+
+    def build(
+        self,
+        registry: list[RegisteredModel],
+        nav_group_configs: list[NavGroupConfig],
+        admin_path: str = "/admin",
+    ) -> list[BuiltNavGroup]: ...
+
+
+class DefaultSidebarBuilder:
+    """Default implementation: bucket registered models by tag, honour configs."""
+
+    def build(
+        self,
+        registry: list[RegisteredModel],
+        nav_group_configs: list[NavGroupConfig],
+        admin_path: str = "/admin",
+    ) -> list[BuiltNavGroup]:
+        buckets: dict[str, list[BuiltNavItem]] = {}
+        for registered in registry:
+            tags = self._get_tags(registered)
+            for tag in tags:
+                buckets.setdefault(tag, []).append(
+                    BuiltNavItem(
+                        label=registered.verbose_name_plural,
+                        url=f"{admin_path}/{registered.table_name}/",
+                        icon=getattr(registered.admin, "icon", None),
+                        order=getattr(registered.admin, "nav_order", 999),
+                        badge_fn=getattr(
+                            registered.admin, "get_nav_badge", None
+                        ),
+                        permission_table=registered.table_name,
+                        children=self._build_children(registered),
+                    )
+                )
+
+        groups: list[BuiltNavGroup] = []
+        seen: set[str] = set()
+
+        # Process configured tags in order first
+        configured_lower = {cfg.tag.lower(): cfg for cfg in nav_group_configs}
+        for cfg in sorted(nav_group_configs, key=lambda c: c.order):
+            tag = cfg.tag
+            if tag in seen:
+                continue
+            seen.add(tag)
+            items = sorted(
+                buckets.get(tag, []),
+                key=lambda i: (i.order, i.label),
+            )
+            extra_items = self._build_extra_items(cfg.extra_items)
+            all_items = sorted(items + extra_items, key=lambda i: i.order)
+            groups.append(
+                BuiltNavGroup(
+                    tag=tag,
+                    label=cfg.label or tag.title(),
+                    icon=cfg.icon,
+                    order=cfg.order,
+                    collapsed_by_default=cfg.collapsed_by_default,
+                    permission_table=cfg.permission,
+                    items=all_items,
+                )
+            )
+
+        # Process any remaining buckets (no explicit config)
+        for tag, items in buckets.items():
+            if tag in seen:
+                continue
+            seen.add(tag)
+            cfg = configured_lower.get(tag.lower())
+            groups.append(
+                BuiltNavGroup(
+                    tag=tag,
+                    label=cfg.label if cfg else tag.title(),
+                    icon=cfg.icon if cfg else None,
+                    order=cfg.order if cfg else 999,
+                    collapsed_by_default=cfg.collapsed_by_default
+                    if cfg
+                    else False,
+                    permission_table=cfg.permission if cfg else None,
+                    items=sorted(items, key=lambda i: (i.order, i.label)),
+                )
+            )
+
+        groups.sort(key=lambda g: (g.order, g.label))
+        return groups
+
+    def _get_tags(self, registered: RegisteredModel) -> list[str]:
+        admin = registered.admin
+        tags = getattr(admin, "tags", None)
+        if tags:
+            return list(tags)
+        tag = getattr(admin, "tag", None)
+        if tag:
+            return [tag]
+        return ["Other"]
+
+    def _build_children(
+        self, registered: RegisteredModel
+    ) -> list[BuiltNavItem]:
+        children_configs = getattr(registered.admin, "nav_children", None) or []
+        result: list[BuiltNavItem] = []
+        for child_cfg in children_configs:
+            result.append(
+                BuiltNavItem(
+                    label=child_cfg.label,
+                    url=child_cfg.url,
+                    icon=getattr(child_cfg, "icon", None),
+                    permission_table=getattr(child_cfg, "permission", None),
+                )
+            )
+        return result
+
+    def _build_extra_items(
+        self, extras: list[NavItemConfig]
+    ) -> list[BuiltNavItem]:
+        return [
+            BuiltNavItem(
+                label=e.label,
+                url=e.url,
+                icon=e.icon,
+                order=e.order,
+                permission_table=e.permission,
+            )
+            for e in extras
+        ]

fastapi_admin_kit/pagination/__init__.py

@@ -0,0 +1,14 @@
+"""Pagination strategies for FastAPI Admin Kit."""
+
+from fastapi_admin_kit.pagination.base import BasePagination, PaginationResult
+from fastapi_admin_kit.pagination.cursor import CursorPagination
+from fastapi_admin_kit.pagination.dynamic import DynamicPagination
+from fastapi_admin_kit.pagination.offset import OffsetPagination
+
+__all__ = [
+    "BasePagination",
+    "PaginationResult",
+    "OffsetPagination",
+    "CursorPagination",
+    "DynamicPagination",
+]

fastapi_admin_kit/pagination/base.py

@@ -0,0 +1,40 @@
+"""Base pagination classes and result dataclass."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class PaginationResult:
+    """Unified result from any pagination strategy."""
+
+    items: list[Any]
+    total: int
+    per_page: int
+    page: int | None = None
+    total_pages: int | None = None
+    next_cursor: str | None = None
+    has_next: bool = False
+    mode: str = "offset"
+
+
+class BasePagination(ABC):
+    """Abstract base for all pagination strategies."""
+
+    @abstractmethod
+    async def paginate(
+        self,
+        stmt: Any,
+        session: Any,
+        per_page: int,
+        page: int = 1,
+        after: str | None = None,
+        before: str | None = None,
+        pk_col: Any = None,
+        model: Any = None,
+    ) -> PaginationResult:
+        """Execute paginated query and return results."""
+        ...