# adminsite

> An admin panel for SQLAlchemy models, mounted into Starlette, FastAPI or Litestar.

adminsite is an admin panel for SQLAlchemy 2.0 models. It is an ASGI app you mount into
Starlette, FastAPI or Litestar with `app.mount("/admin", admin)`. It works with an async
or a sync engine. Install with `pip install adminsite` (add `adminsite[excel]` for Excel
import) plus the database driver.

The core pieces:

- `Admin(engine, title=..., views=[...])` is the app. Options switch features on:
  `auth=` with `secret_key=` for signing in, `audit=True`, `saved_views=True`, `api=True`,
  `dashboard=[...]`, `pages=[...]`, `plugins=[...]`, `language="fa"`, `languages=[...]`.
- `class OrderView(ModelView, model=Order)` describes one model: `list_display`,
  `search_fields`, `list_filter`, `ordering`, `form_fields`, `readonly_fields`,
  `fields` (field objects that replace the defaults), `inlines`, `count_mode`,
  `pagination`, `can_create`/`can_edit`/`can_delete`/`can_import`.
- Anything that depends on the user is a method taking the request: `get_list_display`,
  `get_form_fields`, `scope_query` (row level), and `async def allows(action, *, request,
  record)` with `Permission.VIEW`, `CREATE`, `EDIT`, `DELETE`, `EXPORT`, `IMPORT`,
  `HISTORY`.
- Business rules go in `before_save`, `after_save`, `before_delete`, `after_delete`
  hooks. They run inside the transaction; raise `RefusedError("...")` to refuse.
- Bulk actions are methods decorated with `@action("Label")` that take a `Selection`.

Things agents often get wrong:

- Paths are dotted strings such as `"customer.name"`, not SQLAlchemy columns.
- `ModelView` is configured with class attributes and methods, never by passing options to
  its constructor. `views=[...]` takes the class; the admin builds it.
- Signing in needs `secret_key`. `PasswordAuth` takes password hashes made with
  `adminsite.auth.hash_password`, never plain passwords.
- Hooks and `allows` are async; `get_*` methods and `scope_query` are not.
- Extra routes added by plugins must start with `/-/`.


## Start here

- [Home](https://nimaxin.github.io/adminsite/index.md): What adminsite is and what it does
- [Getting started](https://nimaxin.github.io/adminsite/getting-started/index.md): Install, mount, sign in, and a first view

## Guide

- [Views](https://nimaxin.github.io/adminsite/views/index.md): Every ModelView setting, per request answers, inlines, big tables, saved views, the command palette
- [Fields](https://nimaxin.github.io/adminsite/fields/index.md): Field types, replacing a field, files and pictures, writing a field
- [Filters](https://nimaxin.github.io/adminsite/filters/index.md): Built in filters and writing your own
- [Actions](https://nimaxin.github.io/adminsite/actions/index.md): Bulk actions, confirmations and inputs
- [Importing](https://nimaxin.github.io/adminsite/import/index.md): Importing CSV and Excel files with a preview
- [Permissions](https://nimaxin.github.io/adminsite/permissions/index.md): View, action, field and row permissions
- [Hooks](https://nimaxin.github.io/adminsite/hooks/index.md): Hooks that run inside the save or delete transaction
- [Audit log](https://nimaxin.github.io/adminsite/audit/index.md): The audit log, history and activity
- [Dashboard](https://nimaxin.github.io/adminsite/dashboard/index.md): Stat, chart and recent records cards, and cards of your own
- [Pages and plugins](https://nimaxin.github.io/adminsite/pages/index.md): Pages of your own and the plugin API
- [JSON API](https://nimaxin.github.io/adminsite/api/index.md): The JSON API and token sign in
- [Signing in](https://nimaxin.github.io/adminsite/auth/index.md): Signing in and auth providers
- [Databases](https://nimaxin.github.io/adminsite/databases/index.md): Async and sync engines, SQLite, Postgres and MySQL
- [Translations](https://nimaxin.github.io/adminsite/translations/index.md): Languages, Persian, right to left layouts
- [Accessibility](https://nimaxin.github.io/adminsite/accessibility/index.md): What the pages do for accessibility
- [Customizing the look](https://nimaxin.github.io/adminsite/customizing/index.md): Templates, widgets and the look

## Reference

- [Reference](https://nimaxin.github.io/adminsite/reference/index.md): The public API
- [Changelog](https://nimaxin.github.io/adminsite/changelog/index.md): What changed in each release