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

fastapi_admin_kit/__init__.py

@@ -0,0 +1,73 @@
+"""FastAPI Admin Kit — Drop-in admin panel for FastAPI + SQLAlchemy apps."""
+
+from fastapi_admin_kit.admin import Admin
+from fastapi_admin_kit.admin.decorators import column
+from fastapi_admin_kit.exceptions import ConfigError
+from fastapi_admin_kit.nav import (
+    BuiltNavGroup,
+    BuiltNavItem,
+    DefaultSidebarBuilder,
+    NavGroupConfig,
+    NavItemConfig,
+    SidebarBuilder,
+)
+from fastapi_admin_kit.registry import AdminRegistry, RegisteredModel
+from fastapi_admin_kit.types import (
+    ColumnMeta,
+    ExtraField,
+    FieldMeta,
+    FieldRenderContext,
+    FieldsetContext,
+    FieldsetSpec,
+    FormContext,
+    PermissionSet,
+    RelationMeta,
+    SeedRole,
+)
+from fastapi_admin_kit.views import (
+    AdminExtra,
+    BaseView,
+    BulkView,
+    CreateView,
+    DeleteView,
+    EditView,
+    ListView,
+    ModelAdmin,
+    SearchView,
+)
+
+__all__ = [
+    "Admin",
+    "AdminRegistry",
+    "ConfigError",
+    "RegisteredModel",
+    "ModelAdmin",
+    "column",
+    "BuiltNavGroup",
+    "BuiltNavItem",
+    "DefaultSidebarBuilder",
+    "NavGroupConfig",
+    "NavItemConfig",
+    "SidebarBuilder",
+    "ColumnMeta",
+    "RelationMeta",
+    "FieldMeta",
+    "PermissionSet",
+    "SeedRole",
+    "ExtraField",
+    "FieldRenderContext",
+    "FieldsetContext",
+    "FieldsetSpec",
+    "FormContext",
+    # View classes
+    "BaseView",
+    "ListView",
+    "CreateView",
+    "EditView",
+    "DeleteView",
+    "BulkView",
+    "SearchView",
+    # Per-model assets
+    "AdminExtra",
+]
+__version__ = "0.1.0"

fastapi_admin_kit/actions/__init__.py

@@ -0,0 +1,63 @@
+"""Bulk actions for list views."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from fastapi_admin_kit.actions.base import Action, ModelAction
+from fastapi_admin_kit.actions.registry import ActionRegistry
+
+__all__ = ["Action", "ModelAction", "ActionRegistry", "action"]
+
+
+def action(
+    name: str = "",
+    label: str = "",
+    confirmation_message: str = "",
+    icon: str | None = None,
+    variant: str = "default",
+    permissions: list[str] | None = None,
+    location: str = "list",
+    description: str = "",
+) -> Callable:
+    """Decorator to register an action on a ModelAdmin class.
+
+    Usage::
+
+        @admin.register(Product)
+        class ProductAdmin(ModelAdmin):
+            @action(
+                description="Export selected products",
+                icon="arrow-down-tray",
+                variant="primary",
+            )
+            async def export_products(self, objects, request):
+                ...
+    """
+
+    def decorator(fn: Callable) -> Callable:
+        action_name = name or fn.__name__
+        action_label = label or action_name.replace("_", " ").title()
+
+        class DecoratedAction(Action):
+            def __init__(self) -> None:
+                super().__init__(
+                    name=action_name,
+                    label=action_label,
+                    confirmation_message=confirmation_message,
+                    icon=icon,
+                    variant=variant,
+                    permissions=permissions or [],
+                    location=location,
+                    description=description,
+                )
+
+            async def execute(self, objects: list[Any], request: Any) -> None:
+                await fn(self, objects, request)
+
+        fn._admin_action = DecoratedAction
+        fn._admin_action_name = action_name
+        return fn
+
+    return decorator

fastapi_admin_kit/actions/base.py

@@ -0,0 +1,68 @@
+"""Action ABCs."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from fastapi import Request
+
+
+class Action(ABC):
+    """Abstract base class for admin actions.
+
+    Supports list-level, row-level, detail-level, and submit-line actions
+    with Unfold-style icon, variant, and permission configuration.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        label: str = "",
+        confirmation_message: str = "",
+        icon: str | None = None,
+        variant: str = "default",
+        permissions: list[str] | None = None,
+        location: str = "list",
+        description: str = "",
+    ) -> None:
+        self.name = name
+        self.label = label or name.replace("_", " ").title()
+        self.confirmation_message = confirmation_message
+        self.icon = icon
+        self.variant = variant  # default, primary, danger, success, warning
+        self.permissions = permissions or []
+        self.location = location  # list, row, detail, submit_line
+        self.description = description
+
+    @abstractmethod
+    async def execute(
+        self, objects: list[Any], request: Request | None
+    ) -> None:
+        """Run the action against the selected objects."""
+        ...
+
+    def get_confirmation_message(self) -> str:
+        return self.confirmation_message or f"Run {self.label}?"
+
+    def has_permission(self, user: Any) -> bool:
+        """Check if the user has permission to run this action."""
+        if not self.permissions:
+            return True
+        if getattr(user, "is_superuser", False):
+            return True
+        user_perms = getattr(user, "permissions", []) or []
+        return any(p in user_perms for p in self.permissions)
+
+
+class ModelAction(Action):
+    """Action that operates on a single model instance (row/detail actions)."""
+
+    async def execute_single(
+        self, obj: Any, request: Request | None
+    ) -> None:
+        """Run the action on a single object.
+
+        Override this instead of execute for single-object actions.
+        """
+        await self.execute([obj], request)

fastapi_admin_kit/actions/registry.py

@@ -0,0 +1,43 @@
+"""Action registry."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import Request
+
+from fastapi_admin_kit.actions.base import Action
+
+
+class DeleteSelectedAction(Action):
+    """Built-in bulk delete action."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            name="delete_selected",
+            label="Delete selected",
+            confirmation_message="Are you sure you want to delete the selected items?",
+        )
+
+    async def execute(
+        self, objects: list[Any], request: Request | None
+    ) -> None:
+        # Actual deletion is handled by the existing bulk handler in views/factory.py
+        pass
+
+
+class ActionRegistry:
+    """Registry for custom actions per model."""
+
+    def __init__(self) -> None:
+        self._actions: dict[str, list[Action]] = {}
+
+    def register(self, model_name: str, action: Action) -> None:
+        self._actions.setdefault(model_name, []).append(action)
+
+    def get_actions(self, model_name: str) -> list[Action]:
+        return self._actions.get(model_name, []).copy()
+
+    def auto_generate(self, model_name: str) -> list[Action]:
+        """Auto-generate default bulk actions for a model."""
+        return [DeleteSelectedAction()]

fastapi_admin_kit/admin/__init__.py

@@ -0,0 +1,17 @@
+"""Admin component classes for FastAPI Admin Kit."""
+
+from fastapi_admin_kit.admin.admin_config import AdminConfig
+from fastapi_admin_kit.admin.admin_database import AdminDatabase
+from fastapi_admin_kit.admin.admin_router import AdminRouter
+from fastapi_admin_kit.admin.admin_template import AdminTemplate
+from fastapi_admin_kit.admin.core import Admin
+from fastapi_admin_kit.admin.state import AdminState
+
+__all__ = [
+    "Admin",
+    "AdminConfig",
+    "AdminDatabase",
+    "AdminRouter",
+    "AdminState",
+    "AdminTemplate",
+]

fastapi_admin_kit/admin/admin_config.py

@@ -0,0 +1,95 @@
+"""Admin configuration orchestration."""
+
+from typing import TYPE_CHECKING
+
+from fastapi_admin_kit.config import (
+    AuditConfig,
+    AuthConfig,
+    BehaviorConfig,
+    NavConfig,
+    StorageConfig,
+    UIConfig,
+)
+
+if TYPE_CHECKING:
+    pass
+
+
+class AdminConfig:
+    """Orchestrates all configuration classes with validation."""
+
+    def __init__(
+        self,
+        ui: UIConfig | None = None,
+        auth: AuthConfig | None = None,
+        audit: AuditConfig | None = None,
+        behavior: BehaviorConfig | None = None,
+        storage: StorageConfig | None = None,
+        nav: NavConfig | None = None,
+    ):
+        self.ui = ui or UIConfig()
+        self.auth = auth or AuthConfig()
+        self.audit = audit or AuditConfig()
+        self.behavior = behavior or BehaviorConfig()
+        self.storage = storage or StorageConfig()
+        self.nav = nav or NavConfig()
+
+    def validate_all(self) -> None:
+        """Validate all configuration components."""
+        self.auth.validate_auth_model()
+        self.audit.validate_audit_config()
+        self.storage.validate_storage_config()
+        self.nav.validate_nav_config()
+
+    def get_ui_context(self) -> dict:
+        """Get UI configuration for template context."""
+        return self.ui.apply_to_template_context()
+
+    def get_branding_config(self) -> dict:
+        """Get branding configuration."""
+        return {
+            "title": self.ui.title,
+            "logo_url": self.ui.logo_url,
+            "favicon_url": self.ui.favicon_url,
+            "primary_color": self.ui.primary_color,
+            "primary_color_dark": self.ui.primary_color_dark,
+            "dark_mode_default": self.ui.dark_mode_default,
+        }
+
+    def get_session_config(self) -> dict:
+        """Get session configuration."""
+        return {
+            "session_ttl": self.auth.session_ttl,
+            "session_cookie_name": self.auth.session_cookie_name,
+            "session_secure": self.auth.session_secure,
+        }
+
+    def get_audit_config(self) -> dict:
+        """Get audit configuration."""
+        return {
+            "audit_retention_days": self.audit.audit_retention_days,
+        }
+
+    def get_storage_config(self) -> dict:
+        """Get storage configuration."""
+        return {
+            "uploads_url": self.storage.uploads_url,
+        }
+
+    def get_behavior_config(self) -> dict:
+        """Get behavior configuration."""
+        return {
+            "auto_discover": self.behavior.auto_discover,
+            "dashboard_stats": self.behavior.dashboard_stats,
+            "dashboard_charts": self.behavior.dashboard_charts,
+        }
+
+    def get_nav_config(self) -> dict:
+        """Get navigation configuration."""
+        return {
+            "nav_groups": self.nav.nav_groups,
+            "sidebar_builder": self.nav.sidebar_builder,
+            "require_tags": self.nav.require_tags,
+            "dashboard_permission": self.nav.dashboard_permission,
+            "settings_permission": self.nav.settings_permission,
+        }

fastapi_admin_kit/admin/admin_database.py

@@ -0,0 +1,138 @@
+"""Admin database setup and initialization."""
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    pass
+
+
+class AdminDatabase:
+    """Handles database setup, table creation, and role seeding."""
+
+    def __init__(
+        self,
+        engine: Any | None = None,
+        base: Any | None = None,
+    ):
+        self.engine = engine
+        self.base = base
+
+    async def _create_tables(self) -> None:
+        """Create all admin database tables (async-safe)."""
+        from sqlalchemy.ext.asyncio import AsyncEngine
+
+        from fastapi_admin_kit.audit import models as _audit_models  # noqa: F401
+
+        # Import models to register them with metadata
+        from fastapi_admin_kit.auth import models as _auth_models  # noqa: F401
+        from fastapi_admin_kit.models.base import Base as AdminBase
+
+        if isinstance(self.engine, AsyncEngine):
+            # Async engine - use run_sync
+            async with self.engine.begin() as conn:
+                # Create admin tables
+                await conn.run_sync(AdminBase.metadata.create_all)
+                # Create user tables if Base is provided
+                if self.base is not None:
+                    await conn.run_sync(self.base.metadata.create_all)
+        else:
+            # Sync engine - direct call
+            AdminBase.metadata.create_all(bind=self.engine)
+            if self.base is not None:
+                self.base.metadata.create_all(bind=self.engine)
+
+    async def _seed_roles(
+        self, seed_roles: list, seed_roles_overwrite: bool = False
+    ) -> None:
+        """Seed default roles if none exist (or if overwrite is enabled)."""
+        from sqlalchemy import select
+        from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession
+        from sqlalchemy.orm import Session, sessionmaker
+
+        from fastapi_admin_kit.auth.models import AdminPermission, AdminRole
+
+        is_async = isinstance(self.engine, AsyncEngine)
+
+        if is_async:
+            # Use AsyncSession for async engine
+            session_local = sessionmaker(
+                self.engine, class_=AsyncSession, expire_on_commit=False
+            )
+            async with session_local() as session:
+                # Check existing count
+                result = await session.execute(select(AdminRole))
+                existing_count = len(result.scalars().all())
+
+                if existing_count > 0 and not seed_roles_overwrite:
+                    return
+
+                if seed_roles_overwrite:
+                    await session.execute(select(AdminRole).delete())
+
+                for role_spec in seed_roles:
+                    role = AdminRole(
+                        name=role_spec.name, description=role_spec.description
+                    )
+                    session.add(role)
+                    await session.flush()  # get role.id
+
+                    if role_spec.permissions:
+                        for table_name, perms in role_spec.permissions.items():
+                            perm = AdminPermission(
+                                role_id=role.id,
+                                table_name=table_name,
+                                can_view=perms.get("view", False),
+                                can_create=perms.get("create", False),
+                                can_edit=perms.get("edit", False),
+                                can_delete=perms.get("delete", False),
+                            )
+                            session.add(perm)
+
+                await session.commit()
+        else:
+            # Use sync Session for sync engine
+            session = Session(bind=self.engine)
+            try:
+                existing_count = session.query(AdminRole).count()
+
+                if existing_count > 0 and not seed_roles_overwrite:
+                    return
+
+                if seed_roles_overwrite:
+                    session.query(AdminRole).delete()
+
+                for role_spec in seed_roles:
+                    role = AdminRole(
+                        name=role_spec.name, description=role_spec.description
+                    )
+                    session.add(role)
+                    session.flush()  # get role.id
+
+                    if role_spec.permissions:
+                        for table_name, perms in role_spec.permissions.items():
+                            perm = AdminPermission(
+                                role_id=role.id,
+                                table_name=table_name,
+                                can_view=perms.get("view", False),
+                                can_create=perms.get("create", False),
+                                can_edit=perms.get("edit", False),
+                                can_delete=perms.get("delete", False),
+                            )
+                            session.add(perm)
+
+                session.commit()
+            finally:
+                session.close()
+
+    def _init_session_backend(
+        self, secret_key: str, session_ttl: int, cookie_name: str, secure: bool
+    ) -> Any:
+        """Create and store the signed-cookie session backend."""
+        from fastapi_admin_kit.auth.session import SignedCookieSessionBackend
+
+        return SignedCookieSessionBackend(
+            secret_key=secret_key,
+            session_ttl=session_ttl,
+            cookie_name=cookie_name,
+            secure=secure,
+        )

fastapi_admin_kit/admin/admin_router.py

@@ -0,0 +1,74 @@
+"""Admin router building and static file mounting."""
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    pass
+
+
+class AdminRouter:
+    """Builds and mounts routers for all registered models and admin routes."""
+
+    def __init__(
+        self,
+        admin_path: str = "/admin",
+        secret_key: str = "",
+    ):
+        self.admin_path = admin_path.rstrip("/")
+        self.secret_key = secret_key or ""
+
+    def _build_router(self, app: Any) -> None:
+        """Build and mount routers for all registered models."""
+        from fastapi_admin_kit.api.search import router as search_api_router
+        from fastapi_admin_kit.auth.router import router as auth_router
+        from fastapi_admin_kit.registry import AdminRegistry
+        from fastapi_admin_kit.router import build_model_router
+        from fastapi_admin_kit.views.audit import router as audit_router
+        from fastapi_admin_kit.views.roles import router as roles_router
+
+        registry = AdminRegistry()
+
+        for registered in registry.all():
+            model_router = build_model_router(registered)
+            app.include_router(model_router, prefix=self.admin_path)
+
+        # Auth routes (login/logout)
+        app.include_router(auth_router, prefix=self.admin_path)
+
+        # Global search API
+        app.include_router(search_api_router, prefix=self.admin_path)
+
+        # Audit & role management routes
+        app.include_router(audit_router, prefix=self.admin_path)
+        app.include_router(roles_router, prefix=self.admin_path)
+
+    def _mount_static(self, app: Any) -> None:
+        """Mount the static files directory and uploads directory."""
+        from pathlib import Path
+
+        from fastapi.staticfiles import StaticFiles
+
+        static_dir = Path(__file__).parent.parent / "static"
+        if static_dir.is_dir():
+            # Primary mount — matches template references (/static/...)
+            app.mount(
+                "/static",
+                StaticFiles(directory=str(static_dir)),
+                name="admin_static",
+            )
+
+    def _init_jinja(self, app: Any) -> None:
+        """Initialise the Jinja2 template environment."""
+        import re
+        from pathlib import Path
+
+        from starlette.templating import Jinja2Templates
+
+        templates_dir = Path(__file__).parent / "templates"
+        jinja_env = Jinja2Templates(directory=str(templates_dir))
+
+        def slugify(s: str) -> str:
+            return re.sub(r"[^\w]", "-", s, flags=re.A).strip("-").lower()
+
+        jinja_env.env.filters["slugify"] = slugify
+        app.state.admin_jinja_env = jinja_env