fastapi-admin-kit 0.1.0__tar.gz

fastapi_admin_kit-0.1.0/.gitignore

@@ -0,0 +1,74 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+*.whl
+*.tar.gz
+MANIFEST
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+.env
+.env.local
+.env.*.local
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+*.sublime-project
+*.sublime-workspace
+
+# Database
+*.db
+*.sqlite
+*.sqlite3
+alembic_version
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Build tools
+.ruff_cache/
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# uv
+uv.lock
+
+# MkDocs
+site/
+
+# OS
+.DS_Store
+Thumbs.db
+*.log

fastapi_admin_kit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Borhan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fastapi_admin_kit-0.1.0/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: fastapi-admin-kit
+Version: 0.1.0
+Summary: Drop-in admin panel for FastAPI + SQLAlchemy + SQLModel apps
+Project-URL: Homepage, https://github.com/borhanst/fastapi-admin-kit
+Project-URL: Documentation, https://borhanst.github.io/fastapi-admin-kit/
+Project-URL: Repository, https://github.com/borhanst/fastapi-admin-kit
+Project-URL: Changelog, https://github.com/borhanst/fastapi-admin-kit/releases
+Author-email: Borhan <mdborhan.st@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: admin,admin-panel,async,crud,dashboard,fastapi,rbac,sqlalchemy,sqlmodel
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: aiosqlite>=0.20.0
+Requires-Dist: bcrypt>=4.0.0
+Requires-Dist: fastapi>=0.136.3
+Requires-Dist: itsdangerous>=2.2.0
+Requires-Dist: jinja2>=3.1.0
+Requires-Dist: pyjwt>=2.13.0
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: sqlalchemy>=2.0.0
+Requires-Dist: uvicorn>=0.49.0
+Provides-Extra: dev
+Requires-Dist: hatch>=1.13.0; extra == 'dev'
+Requires-Dist: httpx>=0.27.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.5.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5.0; extra == 'docs'
+Requires-Dist: mkdocs>=1.6.0; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.25.0; extra == 'docs'
+Provides-Extra: mysql
+Requires-Dist: aiomysql>=0.2.0; extra == 'mysql'
+Provides-Extra: postgres
+Requires-Dist: asyncpg>=0.29.0; extra == 'postgres'
+Provides-Extra: sqlmodel
+Requires-Dist: sqlmodel>=0.0.39; extra == 'sqlmodel'
+Description-Content-Type: text/markdown
+
+# FastAPI Admin Kit
+
+[![PyPI version](https://img.shields.io/pypi/v/fastapi-admin-kit.svg)](https://pypi.org/project/fastapi-admin-kit/)
+[![Python versions](https://img.shields.io/pypi/pyversions/fastapi-admin-kit.svg)](https://pypi.org/project/fastapi-admin-kit/)
+[![License](https://img.shields.io/pypi/l/fastapi-admin-kit.svg)](https://github.com/borhanst/fastapi-admin-kit/blob/main/LICENSE)
+
+A drop-in admin panel for FastAPI + SQLAlchemy apps, inspired by Django Unfold.
+
+📖 **[Documentation](https://borhanst.github.io/fastapi-admin-kit/)** | 🚀 **[Quick Start](#quick-start)** | 📦 **[PyPI](https://pypi.org/project/fastapi-admin-kit/)**
+
+## Features
+
+- Zero-config auto-discovery of SQLAlchemy models
+- Built-in authentication, RBAC, and audit logging
+- Modern UI with Tailwind CSS, HTMX, and Alpine.js
+- Fully customizable widgets, themes, and templates
+- CLI for user management (`fastapi-admin-kit` / `fak` — create superusers, list users, change passwords)
+- Async-first with support for PostgreSQL, MySQL, and SQLite
+
+## Installation
+
+```bash
+pip install fastapi-admin-kit
+```
+
+For database-specific async drivers:
+
+```bash
+pip install fastapi-admin-kit[postgres]  # PostgreSQL via asyncpg
+pip install fastapi-admin-kit[mysql]     # MySQL via aiomysql
+```
+
+## Quick Start
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from sqlalchemy import Column, Float, Integer, String
+from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine
+from sqlalchemy.orm import DeclarativeBase, sessionmaker
+
+from fastapi_admin_kit import Admin
+from fastapi_admin_kit.auth.backend import BuiltinAuthBackend
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+class Product(Base):
+    __tablename__ = "products"
+    id = Column(Integer, primary_key=True)
+    name = Column(String(100), nullable=False)
+    price = Column(Float, nullable=False)
+
+
+DATABASE_URL = "sqlite+aiosqlite:///./app.db"
+SECRET_KEY = "change-me-to-a-random-secret-key-in-production"
+
+engine = create_async_engine(DATABASE_URL)
+async_session = sessionmaker(engine, class_=AsyncSession)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+    yield
+    await engine.dispose()
+
+
+app = FastAPI(lifespan=lifespan)
+admin = Admin(
+    app=app,
+    engine=engine,
+    base=Base,
+    secret_key=SECRET_KEY,
+    auth_backend=BuiltinAuthBackend(),
+)
+admin.register(Product)
+```
+
+## CLI Usage
+
+Both the full name and the short alias work interchangeably:
+
+```bash
+# Create a superuser
+fastapi-admin-kit create-superuser -e admin@example.com -p mypassword
+fak create-superuser -e admin@example.com -p mypassword       # short alias
+
+# List all admin users
+fastapi-admin-kit users
+fak users
+
+# Change a user's password
+fastapi-admin-kit changepassword -e admin@example.com -p newpassword
+fak changepassword -e admin@example.com -p newpassword
+```
+
+All commands accept `-d DATABASE_URL` or read the `DATABASE_URL` environment variable.
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Default |
+|---|---|---|
+| `DATABASE_URL` | Async database connection string | `sqlite+aiosqlite:///./app.db` |
+| `SECRET_KEY` | Signing key for sessions/CSRF/JWT (min 32 chars) | Required in production |
+
+### Admin Options
+
+```python
+admin = Admin(
+    app=app,
+    engine=engine,
+    base=Base,
+    secret_key=SECRET_KEY,
+    title="My Admin",           # Admin panel title
+    admin_path="/admin",        # URL prefix
+    dark_mode_default=False,    # Dark mode on by default
+    # Theme
+    theme=ThemeConfig(preset="modern", primary_color="#6366F1"),
+    # Auth
+    auth_backend=BuiltinAuthBackend(),
+    # Environment badge
+    environment_label="Production",
+    environment_color="danger",
+)
+```
+
+### Database Support
+
+- **SQLite** (default, built-in via `aiosqlite`)
+- **PostgreSQL**: `pip install fastapi-admin-kit[postgres]` + set `DATABASE_URL=postgresql+asyncpg://...`
+- **MySQL**: `pip install fastapi-admin-kit[mysql]` + set `DATABASE_URL=mysql+aiomysql://...`
+
+## Development
+
+```bash
+# Install with dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Lint
+ruff check fastapi_admin_kit/
+
+# Build distribution
+pip install hatch
+hatch build
+```
+
+## License
+
+MIT

fastapi_admin_kit-0.1.0/README.md

@@ -0,0 +1,158 @@
+# FastAPI Admin Kit
+
+[![PyPI version](https://img.shields.io/pypi/v/fastapi-admin-kit.svg)](https://pypi.org/project/fastapi-admin-kit/)
+[![Python versions](https://img.shields.io/pypi/pyversions/fastapi-admin-kit.svg)](https://pypi.org/project/fastapi-admin-kit/)
+[![License](https://img.shields.io/pypi/l/fastapi-admin-kit.svg)](https://github.com/borhanst/fastapi-admin-kit/blob/main/LICENSE)
+
+A drop-in admin panel for FastAPI + SQLAlchemy apps, inspired by Django Unfold.
+
+📖 **[Documentation](https://borhanst.github.io/fastapi-admin-kit/)** | 🚀 **[Quick Start](#quick-start)** | 📦 **[PyPI](https://pypi.org/project/fastapi-admin-kit/)**
+
+## Features
+
+- Zero-config auto-discovery of SQLAlchemy models
+- Built-in authentication, RBAC, and audit logging
+- Modern UI with Tailwind CSS, HTMX, and Alpine.js
+- Fully customizable widgets, themes, and templates
+- CLI for user management (`fastapi-admin-kit` / `fak` — create superusers, list users, change passwords)
+- Async-first with support for PostgreSQL, MySQL, and SQLite
+
+## Installation
+
+```bash
+pip install fastapi-admin-kit
+```
+
+For database-specific async drivers:
+
+```bash
+pip install fastapi-admin-kit[postgres]  # PostgreSQL via asyncpg
+pip install fastapi-admin-kit[mysql]     # MySQL via aiomysql
+```
+
+## Quick Start
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from sqlalchemy import Column, Float, Integer, String
+from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine
+from sqlalchemy.orm import DeclarativeBase, sessionmaker
+
+from fastapi_admin_kit import Admin
+from fastapi_admin_kit.auth.backend import BuiltinAuthBackend
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+class Product(Base):
+    __tablename__ = "products"
+    id = Column(Integer, primary_key=True)
+    name = Column(String(100), nullable=False)
+    price = Column(Float, nullable=False)
+
+
+DATABASE_URL = "sqlite+aiosqlite:///./app.db"
+SECRET_KEY = "change-me-to-a-random-secret-key-in-production"
+
+engine = create_async_engine(DATABASE_URL)
+async_session = sessionmaker(engine, class_=AsyncSession)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+    yield
+    await engine.dispose()
+
+
+app = FastAPI(lifespan=lifespan)
+admin = Admin(
+    app=app,
+    engine=engine,
+    base=Base,
+    secret_key=SECRET_KEY,
+    auth_backend=BuiltinAuthBackend(),
+)
+admin.register(Product)
+```
+
+## CLI Usage
+
+Both the full name and the short alias work interchangeably:
+
+```bash
+# Create a superuser
+fastapi-admin-kit create-superuser -e admin@example.com -p mypassword
+fak create-superuser -e admin@example.com -p mypassword       # short alias
+
+# List all admin users
+fastapi-admin-kit users
+fak users
+
+# Change a user's password
+fastapi-admin-kit changepassword -e admin@example.com -p newpassword
+fak changepassword -e admin@example.com -p newpassword
+```
+
+All commands accept `-d DATABASE_URL` or read the `DATABASE_URL` environment variable.
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Default |
+|---|---|---|
+| `DATABASE_URL` | Async database connection string | `sqlite+aiosqlite:///./app.db` |
+| `SECRET_KEY` | Signing key for sessions/CSRF/JWT (min 32 chars) | Required in production |
+
+### Admin Options
+
+```python
+admin = Admin(
+    app=app,
+    engine=engine,
+    base=Base,
+    secret_key=SECRET_KEY,
+    title="My Admin",           # Admin panel title
+    admin_path="/admin",        # URL prefix
+    dark_mode_default=False,    # Dark mode on by default
+    # Theme
+    theme=ThemeConfig(preset="modern", primary_color="#6366F1"),
+    # Auth
+    auth_backend=BuiltinAuthBackend(),
+    # Environment badge
+    environment_label="Production",
+    environment_color="danger",
+)
+```
+
+### Database Support
+
+- **SQLite** (default, built-in via `aiosqlite`)
+- **PostgreSQL**: `pip install fastapi-admin-kit[postgres]` + set `DATABASE_URL=postgresql+asyncpg://...`
+- **MySQL**: `pip install fastapi-admin-kit[mysql]` + set `DATABASE_URL=mysql+aiomysql://...`
+
+## Development
+
+```bash
+# Install with dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Lint
+ruff check fastapi_admin_kit/
+
+# Build distribution
+pip install hatch
+hatch build
+```
+
+## License
+
+MIT

fastapi_admin_kit-0.1.0/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-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-0.1.0/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)