adminsite

An admin panel for the SQLAlchemy 2.0 ORM that works with FastAPI, Starlette and Litestar.

Live demo · Documentation · Changelog · Discussions · For AI assistants

Installation

pip install adminsite

Add the driver your database needs, such as asyncpg or aiosqlite.

Usage

from adminsite import Admin, Link, ModelView


class OrderView(ModelView[Order]):
    fields = [Order.id, Order.customer, Order.status, Order.total]
    searchable_fields = [
        Link(Order.customer, Customer.name),
        Link(Order.customer, Customer.email),
    ]
    list_filters = [Order.status, Order.created_at]


app.mount("/admin", Admin(engine, views=[OrderView]))

The settings name your models' own attributes, so a type checker catches a misspelt one. The labels, filters, form controls and validation come from your models. Getting started builds a working admin in one file.

Features

• Pages from your models: a searchable, sortable list with filters and saved views, a page for each record, and forms with validation.
• Editing in the list for a value that changes often, such as an order's status.
• Lists that keep up to date on their own, for records that come in while people watch, such as new orders.
• Form layouts with panels, rows and tabs, which the record page follows too.
• Related records: pick a related record from a searchable list, and edit child rows, such as an order's lines, inside the parent's form.
• JSON columns edited with a form built from a Pydantic model or a TypedDict, instead of a code box.
• Built-in filters for choices, yes or no, number and date ranges, related records picked by name, and text.
• Custom filters for anything the built-in ones do not cover, such as "overdue" or "spent over €1,000".
• Actions that run your own code on the selected rows, on every row the filters match, on one record or on the whole table, with a dialog for any values they need.
• Permissions for each view, action, field and row.
• Hooks that run your code before and after a save or delete, in the same transaction, and can refuse it with a message.
• An audit log: who changed what and when, including actions, exports and sign ins, with a history on every record and an activity page you can filter.
• Import from CSV or Excel with a preview of every row, and export to CSV.
• File and image uploads, stored on disk or wherever you choose.
• A dashboard of stats, charts and the latest records.
• A command palette: Ctrl K jumps to any page or record.
• A JSON API that shares the same views and permissions.
• Signing in with a fixed list of users or your own user table.
• Pages and plugins of your own, such as reports or settings, in the same layout.
• Translations into eleven languages, among them Persian and Arabic laid out right to left, and every time shown in the reader's time zone.
• Light and dark themes, a layout for phones, and pages that work with a keyboard and a screen reader.
• Async or sync, on SQLite, Postgres and MySQL, with no N+1 queries.
• SQLModel models as they are.
• Large tables: rows never wait for their count, which can be estimated or skipped, and page 400 costs the same as page 1.
• No Node and no CDN: everything ships inside the package.

Motivation

Our business ran its back office on sqladmin, and then on starlette-admin. We needed features neither had, and in the end I had changed starlette-admin so much that turning it into pull requests would have taken more time than I had. So I built adminsite on what we learned from both, with everything our team needs.

It is not a side project. Our back office runs on it every day, and I keep developing it. An admin panel is not what sets our business apart, so it is open source, for anyone to use and improve.

adminsite is for SQLAlchemy only, and will stay that way. SQLModel models work too, since they are SQLAlchemy models, but I do not use SQLModel myself. If you do, reports and fixes are welcome.

How it works

adminsite is one ASGI app, mounted inside yours. Every page and the JSON API go through the ModelView you write for each model, so its rules hold everywhere.

Documentation

• Getting started builds a working admin in one file.
• Views covers everything a view can say about a model.
• Permissions is worth reading before you put the admin in front of anyone.
• The reference lists every class and option.

Contributing

Ask a question or share an idea in Discussions. Issues and pull requests are welcome. CONTRIBUTING.md says how to run the tests and rebuild the stylesheet.

License

MIT