fastapi-lite-admin 0.1.2__tar.gz → 0.1.4__tar.gz

fastapi_lite_admin-0.1.4/PKG-INFO

@@ -0,0 +1,209 @@
+Metadata-Version: 2.4
+Name: fastapi-lite-admin
+Version: 0.1.4
+Summary: A lightweight, pluggable admin panel for FastAPI
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: sqlalchemy>=2.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: jinja2>=3.1.0
+Requires-Dist: python-multipart>=0.0.6
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: httpx; extra == "dev"
+Requires-Dist: uvicorn; extra == "dev"
+Dynamic: license-file
+
+# FastAPI Lite Admin
+
+A premium, lightweight, pluggable admin panel for FastAPI and SQLAlchemy.
+
+## Features
+
+- **Zero-config CRUD**: Automatically generate admin interfaces for your models.
+- **ORM Agnostic**: Initial support for SQLAlchemy, designed to support others.
+- **API First**: All admin actions are available via a clean, RESTful API.
+- **Lightweight UI**: Fast, responsive, Jinja2 templates with server-side pagination, sorting, and search.
+- **Attention Filters**: Highlight critical records (e.g. low stock, inactive users) requiring moderation attention.
+- **Live Activity Badges**: "24h Activity" badges in headers and footers for real-time monitoring.
+- **Custom System Logs**: Display a customizable activity feed on the main dashboard.
+
+---
+
+## Installation
+
+Install the package directly into your project:
+
+```bash
+pip install fastapi-lite-admin
+```
+
+For development/local setup, clone the repository and run:
+
+```bash
+pip install -e ".[dev]"
+```
+
+---
+
+## Quick Start & Usage
+
+Using `FastAPI Lite Admin` is designed to be highly explicit, simple, and require minimal boilerplate. Here is how you can set it up in your application.
+
+### 1. Initialize the Admin Panel
+
+Instantiate the `Admin` class and mount it to your `FastAPI` instance.
+
+```python
+from fastapi import FastAPI
+from fastapi_admin_lite import Admin
+
+app = FastAPI()
+
+admin = Admin(
+    title="Secure Control Panel",  # Dashboard title
+    base_url="/admin",             # URL prefix for the admin panel
+    enable_ui=True                 # Enable/disable Jinja-based UI
+)
+
+# Mount the admin router and views to your FastAPI app
+admin.mount(app)
+```
+
+This will automatically create and serve:
+- The UI dashboard at `http://localhost:8000/admin`
+
+---
+
+## Registering Models (Adding Tables)
+
+To add database tables to your admin panel, register your models using `admin.register()`.
+
+```python
+from database import get_db  # Your SQLAlchemy session dependency
+from models import User
+
+admin.register(
+    model=User,
+    get_db=get_db,
+    list_display=["id", "email", "is_active", "created_at"],
+    date_field="created_at",
+    attention_filter=(User.is_active == False),
+    readonly_fields=["created_at"],
+    config={"display_name": "System Users"}
+)
+```
+
+### Registration Configuration Parameters
+
+When calling `admin.register()`, you can configure how each model is represented:
+
+| Parameter | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **`model`** | `Type[Any]` | **Yes** | The SQLAlchemy Declarative model class to generate CRUD operations for. |
+| **`get_db`** | `Callable` | **Yes** | An async/sync generator yielding an active SQLAlchemy database session (`AsyncSession` or `Session`). |
+| **`list_display`** | `List[str]` | No | List of field/column names to display as columns in the UI model list view. Defaults to all fields. |
+| **`date_field`** | `str` | No | Name of the datetime field (e.g. `created_at`). Required to show the "24h Activity" count cards on the dashboard and lists. |
+| **`attention_filter`** | `SQLAlchemy Expression` | No | A SQLAlchemy binary filter expression (e.g., `User.is_active == False` or `Product.stock < 10`) used to calculate and flag rows that require moderator attention. |
+| **`readonly_fields`** | `List[str]` | No | List of columns that cannot be modified or set via creation or updates (e.g., auto-generated columns or timestamps like `id`, `created_at`). |
+| **`config`** | `Dict[str, Any]` | No | Dictionary containing extra settings. Supports `"display_name"` to override the sidebar label. |
+
+---
+
+## Initialization Configurations
+
+The `Admin` class constructor supports the following parameters for customization:
+
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| **`title`** | `str` | `"FastAPI Admin Lite"` | Customized title displayed in the UI header and dashboard. |
+| **`base_url`** | `str` | `"/admin"` | URL prefix where the admin UI is served. |
+| **`enable_ui`** | `bool` | `True` | Whether to serve the Jinja2 templates UI. If `False`, only the API routes are registered. |
+| **`dependencies`** | `List[Any]` | `[]` | General list of FastAPI dependencies to apply to all admin routes. |
+| **`auth_dependency`** | `Callable` | `None` | Dependency function for custom security gating (e.g., checking tokens or cookies). |
+| **`permission_checker`**| `Callable` | `allow all` | Custom callable to restrict user roles. |
+| **`dashboard_models`** | `List[str]` | `None` | List of registered model names to display on the dashboard (if you want to restrict which registered models show on the home dashboard). |
+| **`get_logs`** | `Callable` | `None` | An optional callable (async or sync) returning system logs to display on the dashboard activity log feed. |
+| **`logs_config`** | `Dict[str, Any]` | `{"title": "System Activity", "columns": ["level", "timestamp", "message"]}` | Config dictionary to customize dashboard log columns and activity title. |
+
+---
+
+## Gating Access & Security
+
+By default, the admin panel warns if no authentication is configured. You can gate the admin panel and its APIs using standard FastAPI dependencies:
+
+### 1. `auth_dependency`
+
+Pass a dependency to `Admin` constructor that handles authentication.
+
+```python
+from fastapi import Header, HTTPException
+
+async def verify_admin_token(x_admin_token: str = Header(None)):
+    if x_admin_token != "super-secret-admin-token":
+        raise HTTPException(status_code=401, detail="Unauthorized")
+    return x_admin_token
+
+admin = Admin(
+    title="Secure Admin",
+    auth_dependency=verify_admin_token
+)
+```
+
+### 2. `permission_checker`
+
+Restrict granular user roles with a custom callable:
+
+```python
+async def check_permissions(user: Any = Depends(get_current_user)) -> bool:
+    return user.is_superuser
+
+admin = Admin(
+    title="Staff Portal",
+    permission_checker=check_permissions
+)
+```
+
+---
+
+## Custom Dashboard Activity Logs
+
+Configure a live activity log feed on the dashboard homepage:
+
+```python
+async def fetch_system_logs():
+    # Fetch logs from a database table, file, or third-party service
+    return [
+        {"level": "info", "timestamp": "10:45 AM", "event": "User signup", "user": "alice@example.com"},
+        {"level": "error", "timestamp": "11:20 AM", "event": "Payment failed", "user": "bob@example.com"}
+    ]
+
+admin = Admin(
+    title="Command Center",
+    get_logs=fetch_system_logs,
+    logs_config={
+        "title": "Recent Activity Feed",
+        "columns": ["level", "timestamp", "event", "user"]
+    }
+)
+```
+
+---
+
+## Running the Example Application
+
+We package a complete working example inside the `/example` directory. To run it:
+
+```bash
+# 1. Install dependencies with dev options
+pip install -e ".[dev]"
+
+# 2. Run the example application
+python -m example.main
+```
+
+Then visit `http://localhost:8001/admin` in your web browser. You'll be able to view logs, add/update users, search database entries, and filter elements dynamically.
+

fastapi_lite_admin-0.1.4/README.md

@@ -0,0 +1,190 @@
+# FastAPI Lite Admin
+
+A premium, lightweight, pluggable admin panel for FastAPI and SQLAlchemy.
+
+## Features
+
+- **Zero-config CRUD**: Automatically generate admin interfaces for your models.
+- **ORM Agnostic**: Initial support for SQLAlchemy, designed to support others.
+- **API First**: All admin actions are available via a clean, RESTful API.
+- **Lightweight UI**: Fast, responsive, Jinja2 templates with server-side pagination, sorting, and search.
+- **Attention Filters**: Highlight critical records (e.g. low stock, inactive users) requiring moderation attention.
+- **Live Activity Badges**: "24h Activity" badges in headers and footers for real-time monitoring.
+- **Custom System Logs**: Display a customizable activity feed on the main dashboard.
+
+---
+
+## Installation
+
+Install the package directly into your project:
+
+```bash
+pip install fastapi-lite-admin
+```
+
+For development/local setup, clone the repository and run:
+
+```bash
+pip install -e ".[dev]"
+```
+
+---
+
+## Quick Start & Usage
+
+Using `FastAPI Lite Admin` is designed to be highly explicit, simple, and require minimal boilerplate. Here is how you can set it up in your application.
+
+### 1. Initialize the Admin Panel
+
+Instantiate the `Admin` class and mount it to your `FastAPI` instance.
+
+```python
+from fastapi import FastAPI
+from fastapi_admin_lite import Admin
+
+app = FastAPI()
+
+admin = Admin(
+    title="Secure Control Panel",  # Dashboard title
+    base_url="/admin",             # URL prefix for the admin panel
+    enable_ui=True                 # Enable/disable Jinja-based UI
+)
+
+# Mount the admin router and views to your FastAPI app
+admin.mount(app)
+```
+
+This will automatically create and serve:
+- The UI dashboard at `http://localhost:8000/admin`
+
+---
+
+## Registering Models (Adding Tables)
+
+To add database tables to your admin panel, register your models using `admin.register()`.
+
+```python
+from database import get_db  # Your SQLAlchemy session dependency
+from models import User
+
+admin.register(
+    model=User,
+    get_db=get_db,
+    list_display=["id", "email", "is_active", "created_at"],
+    date_field="created_at",
+    attention_filter=(User.is_active == False),
+    readonly_fields=["created_at"],
+    config={"display_name": "System Users"}
+)
+```
+
+### Registration Configuration Parameters
+
+When calling `admin.register()`, you can configure how each model is represented:
+
+| Parameter | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **`model`** | `Type[Any]` | **Yes** | The SQLAlchemy Declarative model class to generate CRUD operations for. |
+| **`get_db`** | `Callable` | **Yes** | An async/sync generator yielding an active SQLAlchemy database session (`AsyncSession` or `Session`). |
+| **`list_display`** | `List[str]` | No | List of field/column names to display as columns in the UI model list view. Defaults to all fields. |
+| **`date_field`** | `str` | No | Name of the datetime field (e.g. `created_at`). Required to show the "24h Activity" count cards on the dashboard and lists. |
+| **`attention_filter`** | `SQLAlchemy Expression` | No | A SQLAlchemy binary filter expression (e.g., `User.is_active == False` or `Product.stock < 10`) used to calculate and flag rows that require moderator attention. |
+| **`readonly_fields`** | `List[str]` | No | List of columns that cannot be modified or set via creation or updates (e.g., auto-generated columns or timestamps like `id`, `created_at`). |
+| **`config`** | `Dict[str, Any]` | No | Dictionary containing extra settings. Supports `"display_name"` to override the sidebar label. |
+
+---
+
+## Initialization Configurations
+
+The `Admin` class constructor supports the following parameters for customization:
+
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| **`title`** | `str` | `"FastAPI Admin Lite"` | Customized title displayed in the UI header and dashboard. |
+| **`base_url`** | `str` | `"/admin"` | URL prefix where the admin UI is served. |
+| **`enable_ui`** | `bool` | `True` | Whether to serve the Jinja2 templates UI. If `False`, only the API routes are registered. |
+| **`dependencies`** | `List[Any]` | `[]` | General list of FastAPI dependencies to apply to all admin routes. |
+| **`auth_dependency`** | `Callable` | `None` | Dependency function for custom security gating (e.g., checking tokens or cookies). |
+| **`permission_checker`**| `Callable` | `allow all` | Custom callable to restrict user roles. |
+| **`dashboard_models`** | `List[str]` | `None` | List of registered model names to display on the dashboard (if you want to restrict which registered models show on the home dashboard). |
+| **`get_logs`** | `Callable` | `None` | An optional callable (async or sync) returning system logs to display on the dashboard activity log feed. |
+| **`logs_config`** | `Dict[str, Any]` | `{"title": "System Activity", "columns": ["level", "timestamp", "message"]}` | Config dictionary to customize dashboard log columns and activity title. |
+
+---
+
+## Gating Access & Security
+
+By default, the admin panel warns if no authentication is configured. You can gate the admin panel and its APIs using standard FastAPI dependencies:
+
+### 1. `auth_dependency`
+
+Pass a dependency to `Admin` constructor that handles authentication.
+
+```python
+from fastapi import Header, HTTPException
+
+async def verify_admin_token(x_admin_token: str = Header(None)):
+    if x_admin_token != "super-secret-admin-token":
+        raise HTTPException(status_code=401, detail="Unauthorized")
+    return x_admin_token
+
+admin = Admin(
+    title="Secure Admin",
+    auth_dependency=verify_admin_token
+)
+```
+
+### 2. `permission_checker`
+
+Restrict granular user roles with a custom callable:
+
+```python
+async def check_permissions(user: Any = Depends(get_current_user)) -> bool:
+    return user.is_superuser
+
+admin = Admin(
+    title="Staff Portal",
+    permission_checker=check_permissions
+)
+```
+
+---
+
+## Custom Dashboard Activity Logs
+
+Configure a live activity log feed on the dashboard homepage:
+
+```python
+async def fetch_system_logs():
+    # Fetch logs from a database table, file, or third-party service
+    return [
+        {"level": "info", "timestamp": "10:45 AM", "event": "User signup", "user": "alice@example.com"},
+        {"level": "error", "timestamp": "11:20 AM", "event": "Payment failed", "user": "bob@example.com"}
+    ]
+
+admin = Admin(
+    title="Command Center",
+    get_logs=fetch_system_logs,
+    logs_config={
+        "title": "Recent Activity Feed",
+        "columns": ["level", "timestamp", "event", "user"]
+    }
+)
+```
+
+---
+
+## Running the Example Application
+
+We package a complete working example inside the `/example` directory. To run it:
+
+```bash
+# 1. Install dependencies with dev options
+pip install -e ".[dev]"
+
+# 2. Run the example application
+python -m example.main
+```
+
+Then visit `http://localhost:8001/admin` in your web browser. You'll be able to view logs, add/update users, search database entries, and filter elements dynamically.
+

{fastapi_lite_admin-0.1.2 → fastapi_lite_admin-0.1.4}/fastapi_admin_lite/ui/templates/dashboard.html

@@ -90,26 +90,27 @@
     }
 
     .badge {
-        padding: 4px 8px;
-        border-radius: 4px;
+        padding: 4px 10px;
+        border-radius: 12px;
         font-size: 0.7rem;
         font-weight: 700;
         text-transform: uppercase;
+        letter-spacing: 0.025em;
     }
 
-    .badge-info { background-color: #e0f2fe; color: #0369a1; }
-    .badge-warn { background-color: #fef3c7; color: #b45309; }
-    .badge-error { background-color: #fee2e2; color: #b91c1c; }
-    .badge-success { background-color: #dcfce7; color: #15803d; }
+    .badge-info { background-color: var(--info-bg); color: var(--info-text); }
+    .badge-warn { background-color: var(--warning-bg); color: var(--warning-text); }
+    .badge-error { background-color: var(--error-bg); color: var(--error-text); }
+    .badge-success { background-color: var(--success-bg); color: var(--success-text); }
 
     .status-text {
         font-weight: 600;
         font-family: monospace;
     }
 
-    .status-200 { color: var(--success); }
-    .status-422 { color: var(--error); }
-    .status-latency { color: var(--warning); }
+    .status-200 { color: var(--success-text); }
+    .status-422 { color: var(--error-text); }
+    .status-latency { color: var(--warning-text); }
 
     /* Quick Actions */
     .quick-actions {
@@ -134,12 +135,12 @@
     .action-icon {
         width: 48px;
         height: 48px;
-        background-color: #f1f5f9;
+        background-color: var(--bg-surface);
         border-radius: 12px;
         display: flex;
         align-items: center;
         justify-content: center;
-        color: var(--text-muted);
+        color: var(--primary);
         font-size: 1.25rem;
     }
 

{fastapi_lite_admin-0.1.2 → fastapi_lite_admin-0.1.4}/fastapi_admin_lite/ui/templates/layout.html

@@ -8,28 +8,68 @@
     <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.0/css/all.min.css">
     <style>
         :root {
-            --primary: #0089a7;
-            --primary-hover: #00768f;
+            --primary: #6366f1;
+            --primary-hover: #4f46e5;
             --bg-main: #f8fafc;
-            --bg-sidebar: #ffffff;
+            --bg-card: #ffffff;
+            --bg-surface: #f1f5f9;
+            --bg-header: #f8fafc;
+            --bg-sidebar: #0f172a;
             --text-main: #1e293b;
             --text-muted: #64748b;
+            --sidebar-text: #94a3b8;
+            --sidebar-text-active: #ffffff;
             --border: #e2e8f0;
-            --surface: #ffffff;
-            --success: #10b981;
-            --warning: #f59e0b;
-            --error: #ef4444;
-            --sidebar-width: 260px;
+            --sidebar-hover: #1e293b;
+            --sidebar-active: #334155;
+            --shadow: 0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1);
+            --sidebar-width: 240px;
+            --topbar-height: 48px;
+
+            /* Status Colors */
+            --success-bg: #dcfce7;
+            --success-text: #166534;
+            --warning-bg: #fef9c3;
+            --warning-text: #854d0e;
+            --error-bg: #fee2e2;
+            --error-text: #991b1b;
+            --info-bg: #e0f2fe;
+            --info-text: #075985;
+        }
+
+        [data-theme="dark"] {
+            --bg-main: #020617;
+            --bg-card: #0f172a;
+            --bg-surface: #1e293b;
+            --bg-header: #1e293b;
+            --bg-sidebar: #020617;
+            --text-main: #f1f5f9;
+            --text-muted: #94a3b8;
+            --border: #1e293b;
+            --sidebar-hover: #0f172a;
+            --sidebar-active: #1e293b;
+            --shadow: 0 4px 6px -1px rgb(0 0 0 / 0.3);
+
+            /* Status Colors - Dark Mode */
+            --success-bg: rgba(22, 101, 52, 0.2);
+            --success-text: #4ade80;
+            --warning-bg: rgba(133, 77, 14, 0.2);
+            --warning-text: #facc15;
+            --error-bg: rgba(153, 27, 27, 0.2);
+            --error-text: #f87171;
+            --info-bg: rgba(7, 89, 133, 0.2);
+            --info-text: #38bdf8;
         }
 
         * {
             margin: 0;
             padding: 0;
             box-sizing: border-box;
+            font-family: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif;
+            transition: background-color 0.2s, border-color 0.2s, color 0.2s;
         }
 
         body {
-            font-family: 'Inter', sans-serif;
             background-color: var(--bg-main);
             color: var(--text-main);
             display: flex;
@@ -69,14 +109,14 @@
         .logo-text {
             font-weight: 700;
             font-size: 1.1rem;
-            color: var(--text-main);
+            color: var(--sidebar-text-active);
         }
 
         .logo-subtext {
             font-size: 0.7rem;
             text-transform: uppercase;
             letter-spacing: 0.05em;
-            color: var(--text-muted);
+            color: var(--sidebar-text);
             margin-top: -2px;
         }
 
@@ -91,7 +131,7 @@
             gap: 12px;
             padding: 12px 16px;
             text-decoration: none;
-            color: var(--text-muted);
+            color: var(--sidebar-text);
             border-radius: 8px;
             font-weight: 500;
             transition: all 0.2s;
@@ -99,13 +139,13 @@
         }
 
         .nav-item:hover {
-            background-color: #f1f5f9;
-            color: var(--text-main);
+            background-color: var(--sidebar-hover);
+            color: var(--sidebar-text-active);
         }
 
         .nav-item.active {
-            background-color: #ecfeff;
-            color: var(--primary);
+            background-color: var(--sidebar-active);
+            color: var(--sidebar-text-active);
         }
 
         .sidebar-footer {
@@ -134,11 +174,12 @@
         .user-info .name {
             font-size: 0.9rem;
             font-weight: 600;
+            color: var(--sidebar-text-active);
         }
 
         .user-info .email {
             font-size: 0.75rem;
-            color: var(--text-muted);
+            color: var(--sidebar-text);
         }
 
         /* Main Content */
@@ -151,8 +192,8 @@
 
         /* Topbar */
         .topbar {
-            height: 48px;
-            background-color: var(--surface);
+            height: var(--topbar-height);
+            background-color: var(--bg-card);
             border-bottom: 1px solid var(--border);
             display: flex;
             align-items: center;
@@ -167,13 +208,14 @@
 
         .search-box input {
             width: 100%;
-            padding: 6px 12px 6px 32px;
-            background-color: #f1f5f9;
-            border: 1px solid transparent;
-            border-radius: 6px;
+            padding: 8px 12px 8px 36px;
+            background-color: var(--bg-surface);
+            border: 1px solid var(--border);
+            border-radius: 8px;
             outline: none;
             font-size: 0.85rem;
             transition: all 0.2s;
+            color: var(--text-main);
         }
 
         .search-box i {
@@ -217,11 +259,11 @@
 
         /* Shared Components */
         .card {
-            background-color: var(--surface);
+            background-color: var(--bg-card);
             border: 1px solid var(--border);
             border-radius: 12px;
             padding: 24px;
-            box-shadow: 0 1px 3px rgba(0,0,0,0.05);
+            box-shadow: var(--shadow);
         }
 
         .btn {
@@ -244,16 +286,17 @@
 
         .btn-primary:hover {
             background-color: var(--primary-hover);
+            box-shadow: 0 4px 12px rgba(99, 102, 241, 0.2);
         }
 
         .btn-secondary {
-            background-color: white;
+            background-color: var(--bg-card);
             border-color: var(--border);
             color: var(--text-main);
         }
 
         .btn-secondary:hover {
-            background-color: #f8fafc;
+            background-color: var(--bg-surface);
         }
 
         /* Extra CSS from child templates */
@@ -311,6 +354,9 @@
                 <input type="text" placeholder="Search resources...">
             </div>
             <div class="topbar-actions">
+                <button id="theme-toggle" class="btn-icon" style="background: none; border: none; cursor: pointer; color: var(--text-muted);">
+                    <i class="fas fa-moon"></i>
+                </button>
                 <i class="far fa-bell"></i>
                 <i class="far fa-question-circle"></i>
                 <div class="avatar" style="width: 32px; height: 32px;">
@@ -324,6 +370,33 @@
         </div>
     </div>
 
+    <script>
+        // Theme Toggle Logic
+        const themeToggle = document.getElementById('theme-toggle');
+        const icon = themeToggle.querySelector('i');
+        
+        // Check for saved theme or default to light
+        const savedTheme = localStorage.getItem('theme') || 'light';
+        document.documentElement.setAttribute('data-theme', savedTheme);
+        updateIcon(savedTheme);
+
+        themeToggle.addEventListener('click', () => {
+            const currentTheme = document.documentElement.getAttribute('data-theme');
+            const newTheme = currentTheme === 'light' ? 'dark' : 'light';
+            
+            document.documentElement.setAttribute('data-theme', newTheme);
+            localStorage.setItem('theme', newTheme);
+            updateIcon(newTheme);
+        });
+
+        function updateIcon(theme) {
+            if (theme === 'dark') {
+                icon.className = 'fas fa-sun';
+            } else {
+                icon.className = 'fas fa-moon';
+            }
+        }
+    </script>
     {% block extra_js %}{% endblock %}
 </body>
 </html>