Metadata-Version: 2.4
Name: fastapi-autoadmin
Version: 0.1.1
Summary: A dynamic visual admin dashboard and CRUD panel for FastAPI backend applications with auto model-schema discovery.
License: MIT
Classifier: Framework :: FastAPI
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.8
Requires-Dist: fastapi>=0.100.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-multipart>=0.0.6
Requires-Dist: sqlalchemy>=2.0.0
Description-Content-Type: text/markdown

# 🚀 FastAPI-AutoAdmin

A self-generating visual admin dashboard and CRUD panel for **FastAPI** applications. 

`FastAPI-AutoAdmin` dynamically discovers your SQLAlchemy / SQLModel database models, inspects their column structures and relations, generates secure JSON REST endpoints, and hosts a stunning client-side single-page dashboard featuring customizable analytics widgets, visual charts, and inline data management.

---

## ✨ Features

- 🔍 **Zero-Boilerplate Auto-Discovery**: Scans your application's memory space and dynamically registers SQLAlchemy & SQLModel schemas.
- 📊 **Dynamic Board Panels**: Add, drag, configure, and delete visual analytics charts (Bar, Line, Pie, Doughnut, KPI metric cards) grouped by columns and aggregated (Sum, Avg, Count, Min, Max).
- 🛠️ **Fully-Featured CRUD Views**: Auto-generated interfaces for managing database values, with built-in search, sorting, pagination, and data export (to CSV).
- 🧬 **Type-Aware Forms**: Automatically builds input form controls (such as toggles for booleans, selectors for Enums, date-pickers for Datetime) based on SQLAlchemy metadata.
- 🎨 **Premium Modern Design**: Built with a sleek dark/light theme engine, glassmorphic UI elements, vivid gradients, and smooth transition animations.
- 💾 **Local Widget Persistence**: Remembers your customized board widget layout directly in your browser (`localStorage`).

---

## 📦 Installation

To use `FastAPI-AutoAdmin` in your project, install it directly from the GitHub repository:

```bash
# Using pip
pip install git+https://github.com/Harshidpatel12/FastAPI-AutoAdmin.git

# Using UV package manager
uv pip install git+https://github.com/Harshidpatel12/FastAPI-AutoAdmin.git
```

---

## 🚀 Quick Start (2-Line Setup)

Integrating `FastAPI-AutoAdmin` into any existing FastAPI project takes only two lines of code.

```python
from fastapi import FastAPI
from sqlalchemy.orm import sessionmaker
from fastapi_autoadmin import FastAPIAutoAdmin

# 1. Your existing FastAPI application & DB setup
app = FastAPI()
SessionLocal = sessionmaker(...) 

# 2. Mount FastAPIAutoAdmin! (session_factory & models are automatically discovered)
FastAPIAutoAdmin(app)
```

---

## 💡 Complete Integration Example

Here is a full example illustrating how `FastAPI-AutoAdmin` automatically detects database models (`User` and `Order`) and your SQLAlchemy `sessionmaker`, mounting the admin panel on `/dashboard`:

```python
import datetime
from fastapi import FastAPI
from sqlalchemy import create_engine, Column, Integer, String, Float, DateTime
from sqlalchemy.orm import declarative_base, sessionmaker
from fastapi_autoadmin import FastAPIAutoAdmin

# Setup standard SQLAlchemy engine
DATABASE_URL = "sqlite:///./app.db"
engine = create_engine(DATABASE_URL)
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
Base = declarative_base()

# Declare your database models
class User(Base):
    __tablename__ = "users"
    id = Column(Integer, primary_key=True)
    username = Column(String, unique=True, nullable=False)
    email = Column(String, unique=True, nullable=False)

class Order(Base):
    __tablename__ = "orders"
    id = Column(Integer, primary_key=True)
    total_amount = Column(Float, nullable=False)
    order_date = Column(DateTime, default=datetime.datetime.utcnow)

# Run migrations (create tables)
Base.metadata.create_all(bind=engine)

# Initialize FastAPI
app = FastAPI()

# Mount FastAPIAutoAdmin (Auto-discovers sessionmaker and SQLAlchemy models)
FastAPIAutoAdmin(app)
```

Now, run your app with Uvicorn:
```bash
uvicorn main:app --reload
```
And navigate to:
👉 **[http://127.0.0.1:8000/dashboard](http://127.0.0.1:8000/dashboard)**

---

## 🛠️ Advanced Customization

### Explicit Model Selection
By default, `FastAPI-AutoAdmin` automatically scans `sys.modules` for any registered database model. If you want to restrict the dashboard to show only specific models, pass them explicitly:

```python
from my_models import Product, Category

FastAPIAutoAdmin(
    app, 
    session_factory=SessionLocal, 
    models=[Product, Category] # Only show these two models
)
```

### Automatic Sessionmaker Discovery
By default, `FastAPI-AutoAdmin` will scan all imported modules in `sys.modules` for a SQLAlchemy `sessionmaker` or `async_sessionmaker` instance (e.g., `SessionLocal`). If only one instance exists in your project, it will be automatically selected and bound. 

If you have multiple database setups, use multiple sessionmakers, or simply want to be explicit, you can pass the sessionmaker object directly to the `session_factory` parameter.

---

## 📂 Project Structure

```text
fastapi-autoadmin/
├── fastapi_autoadmin/          # Main Library Directory
│   ├── __init__.py             # Exposes FastAPIAutoAdmin class
│   ├── discovery.py            # Metadata / SQL introspection
│   ├── api.py                  # Dynamic CRUD & aggregate API builder
│   ├── ui.py                   # Frontend SPA server routes
│   └── templates/
│       └── dashboard.html      # Responsive HTML/CSS/JS template
│   ├── demo_app.py             # Self-contained runnable sandbox demo
├── pyproject.toml              # Build configurations (PEP 517)
└── README.md                   # Project documentation
```

---

## 🛡️ License

This project is licensed under the **MIT License**. Feel free to use, modify, and distribute it for personal and commercial projects.
