Metadata-Version: 2.4
Name: litestar-admin
Version: 0.1.1
Summary: Modern admin panel framework for Litestar with Cloudflare-inspired UI
Keywords: litestar,admin,dashboard,crud,sqlalchemy,admin-panel
Author: Jacob Coffee
Author-email: Jacob Coffee <jacob@z7x.org>
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Dist: litestar>=2.0.0
Requires-Dist: advanced-alchemy>=0.10.0
Requires-Dist: sqlalchemy[asyncio]>=2.0.0
Requires-Dist: aiofiles>=25.1.0
Requires-Dist: litestar-admin[jwt,oauth,sqladmin,redis,structlog,auth,storage,excel,sanitize] ; extra == 'all'
Requires-Dist: passlib[argon2]>=1.7.4 ; extra == 'auth'
Requires-Dist: openpyxl>=3.1.0 ; extra == 'excel'
Requires-Dist: pyjwt>=2.8.0 ; extra == 'jwt'
Requires-Dist: litestar-oauth>=0.1.0 ; extra == 'oauth'
Requires-Dist: redis>=5.0.0 ; extra == 'redis'
Requires-Dist: nh3>=0.2.0 ; extra == 'sanitize'
Requires-Dist: sqladmin-litestar-plugin>=0.1.0 ; extra == 'sqladmin'
Requires-Dist: litestar-storages>=0.1.0 ; extra == 'storage'
Requires-Dist: pillow>=10.0.0 ; extra == 'storage'
Requires-Dist: structlog>=24.1.0 ; extra == 'structlog'
Requires-Python: >=3.10
Project-URL: Documentation, https://jacobcoffee.github.io/litestar-admin
Project-URL: Homepage, https://github.com/JacobCoffee/litestar-admin
Project-URL: Issues, https://github.com/JacobCoffee/litestar-admin/issues
Project-URL: Repository, https://github.com/JacobCoffee/litestar-admin
Provides-Extra: all
Provides-Extra: auth
Provides-Extra: excel
Provides-Extra: jwt
Provides-Extra: oauth
Provides-Extra: redis
Provides-Extra: sanitize
Provides-Extra: sqladmin
Provides-Extra: storage
Provides-Extra: structlog
Description-Content-Type: text/markdown

# litestar-admin

[![CI](https://github.com/JacobCoffee/litestar-admin/actions/workflows/ci.yml/badge.svg)](https://github.com/JacobCoffee/litestar-admin/actions/workflows/ci.yml)
[![PyPI version](https://badge.fury.io/py/litestar-admin.svg)](https://badge.fury.io/py/litestar-admin)
[![Python versions](https://img.shields.io/pypi/pyversions/litestar-admin.svg)](https://pypi.org/project/litestar-admin/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Modern admin panel framework for Litestar applications with a Cloudflare-inspired UI.**

litestar-admin provides a production-ready admin interface for managing SQLAlchemy models in Litestar applications, featuring:

- **Cloudflare Dashboard-inspired UI** - Modern dark theme with clean card layouts
- **Full CRUD Operations** - Create, read, update, delete with bulk actions
- **RBAC Authorization** - Role-based access control with granular permissions
- **Audit Logging** - Track all admin actions for compliance
- **SQLAlchemy Integration** - Works with SQLAlchemy 2.x and Advanced-Alchemy
- **Auto-discovery** - Automatically discovers and registers models
- **JWT & OAuth2 Authentication** - Flexible, pluggable auth backends
- **Static Export Frontend** - Next.js frontend with no runtime Node.js required

  ### Examples

<table>
    <tr>
      <td><img width="400" alt="image"
  src="https://github.com/user-attachments/assets/0b4852fb-b1e3-40a0-80c0-3d76ab29b5cb"
  /></td>
      <td><img width="400" alt="image"
  src="https://github.com/user-attachments/assets/085b380e-1f47-401c-8487-1e034e829490"
  /></td>
    </tr>
    <tr>
      <td><img width="400" alt="image"
  src="https://github.com/user-attachments/assets/c476f1ce-943f-4b56-9807-eb23061a9419"
  /></td>
      <td><img width="400" alt="image"
  src="https://github.com/user-attachments/assets/74e9610a-33a8-4eb9-8992-311b5d39718f"
  /></td>
    </tr>
</table>


## Installation

```bash
# Basic installation
pip install litestar-admin

# With JWT authentication
pip install litestar-admin[jwt]

# With OAuth support
pip install litestar-admin[oauth]

# With sqladmin bridge
pip install litestar-admin[sqladmin]

# All extras
pip install litestar-admin[all]
```

## Quick Start

Point the plugin at your app and it picks up your SQLAlchemy models automatically:

```python
from litestar import Litestar
from litestar_admin import AdminPlugin, AdminConfig
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column


class Base(DeclarativeBase):
    pass


class User(Base):
    __tablename__ = "users"

    id: Mapped[int] = mapped_column(primary_key=True)
    email: Mapped[str] = mapped_column(unique=True)
    name: Mapped[str]


app = Litestar(
    plugins=[AdminPlugin(config=AdminConfig(title="My Admin"))]
)
```

That's it. Auto-discovery finds your models, builds column lists from the table schema, makes string columns searchable, and gives you full CRUD. No boilerplate view classes required.

### Customizing a Model View

When you need more control over how a model looks or behaves in the admin, create a `ModelView` subclass. Auto-discovery skips any model that already has an explicit view registered.

```python
from litestar_admin import ModelView

class UserAdmin(ModelView, model=User):
    column_list = ["id", "email", "name", "created_at"]
    column_exclude_list = ["password_hash"]
    column_searchable_list = ["email", "name"]
    column_default_sort = ("created_at", "desc")

    can_create = True
    can_edit = True
    can_delete = False

    page_size = 25
```

Pass it in via `views=`:

```python
AdminConfig(
    title="My Admin",
    views=[UserAdmin],
)
```

Any models *without* an explicit view still get auto-discovered.

## RBAC Guards

```python
from litestar_admin.guards import require_permission, Permission

@get("/admin/users", guards=[require_permission(Permission.MODELS_READ)])
async def list_users() -> list[User]:
    ...

@post("/admin/users", guards=[require_permission(Permission.MODELS_WRITE)])
async def create_user(data: UserCreate) -> User:
    ...
```

## Development

```bash
# Clone the repository
git clone https://github.com/JacobCoffee/litestar-admin.git
cd litestar-admin

# Install development dependencies
make dev

# Run tests
make test

# Run linting
make lint

# Build frontend
make frontend

# Build documentation
make docs
```

## Documentation

Full documentation is available at [jacobcoffee.github.io/litestar-admin](https://jacobcoffee.github.io/litestar-admin).

## Related Projects

- [litestar](https://github.com/litestar-org/litestar) - The ASGI framework
- [advanced-alchemy](https://github.com/jolt-org/advanced-alchemy) - SQLAlchemy toolkit
- [sqladmin-litestar-plugin](https://github.com/peterschutt/sqladmin-litestar-plugin) - SQLAdmin bridge

## License

MIT License - see [LICENSE](LICENSE) for details.
