# 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

# adminsite

An admin panel for SQLAlchemy models. Mount it into Starlette, FastAPI or Litestar, and your team gets pages to search, filter, read and change your data.

```
from adminsite import Admin, ModelView


class OrderView(ModelView, model=Order):
    list_display = ("id", "customer.name", "status", "total", "created_at")
    search_fields = ("id", "customer.name", "customer.email")
    list_filter = ("status", "total", "created_at")
    ordering = ("-created_at",)


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

That is a working admin. The columns, labels, filters, form controls and validation all come from your models.

Try it

[The live demo](https://adminsite.duckdns.org) runs the example shop. Sign in as admin with the password admin and change anything you like. It goes back as it started every hour.

Alpha

adminsite is in alpha. It is tested and works, but names may still change before 0.1.0. Install it with the exact version: `pip install adminsite==0.1.0a6`.

## What you get

- **Pages worked out from your models.** Column types pick the right controls, `created_at` reads "Created at", an enum becomes a select, and a foreign key becomes a picker for the record it points at.
- **No N+1 queries.** Showing `customer.name` loads the customers with the page. Tests count the statements so it stays that way.
- **Fast on large tables.** Counting can be switched off per view, which makes a page one query.
- **Filters you can write yourself**, next to the built-in ones.
- **Bulk actions over everything that matches**, not only the rows on the page, and actions that ask for values first.
- **Permissions at four levels**: the view, the action, the field and the row.
- **Hooks inside the transaction** that can read other tables and refuse a save.
- **An audit log** with a history on every record.
- **Async or sync.** An `AsyncEngine` or a plain `Engine` both work. Tested on SQLite, Postgres and MySQL.
- **No Node and no CDN.** The CSS and JavaScript ship inside the package.

## Where to go next

- [Getting started](https://nimaxin.github.io/adminsite/getting-started/index.md) sets up a working admin in a few minutes.
- [Views](https://nimaxin.github.io/adminsite/views/index.md) covers everything a `ModelView` can say about a model.
- [Permissions](https://nimaxin.github.io/adminsite/permissions/index.md) is worth reading before you put the admin in front of anyone.

## For AI assistants

If an AI assistant helps you build with adminsite, point it at [llms.txt](https://nimaxin.github.io/adminsite/llms.txt), a short guide with links to every page, or [llms-full.txt](https://nimaxin.github.io/adminsite/llms-full.txt), the whole documentation in one file. Both are rebuilt with the docs, so they always match the current release.

# Getting started

## Install

```
pip install adminsite==0.1.0a6
```

adminsite does not pull in a database driver. Add the one you use, for example `asyncpg` or `psycopg` for Postgres, or `aiosqlite` for SQLite with an async engine.

## Your first admin

Say you have these models:

```
from sqlalchemy import ForeignKey, String
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship


class Base(DeclarativeBase):
    pass


class Customer(Base):
    __tablename__ = "customers"

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

    def __str__(self) -> str:
        return self.name


class Order(Base):
    __tablename__ = "orders"

    id: Mapped[int] = mapped_column(primary_key=True)
    customer_id: Mapped[int] = mapped_column(ForeignKey("customers.id"))
    note: Mapped[str | None] = mapped_column(String(500), default=None)

    customer: Mapped[Customer] = relationship()
```

Describe how each one should appear, and mount the admin:

```
from fastapi import FastAPI
from sqlalchemy.ext.asyncio import create_async_engine

from adminsite import Admin, ModelView

engine = create_async_engine("postgresql+asyncpg://localhost/shop")


class CustomerView(ModelView, model=Customer):
    list_display = ("name", "email")
    search_fields = ("name", "email")


class OrderView(ModelView, model=Order):
    list_display = ("id", "customer.name", "note")
    search_fields = ("id", "customer.name")


app = FastAPI()
admin = Admin(engine, title="Shop", views=[CustomerView, OrderView])
app.mount("/admin", admin)
```

Run the app and open `/admin`. You get a list for each model, with search, sorting and paging, and pages to add, change and delete records. The order form offers a customer picker rather than a number box, because `customer_id` is a foreign key.

A view with no settings at all still works: it shows every column. Settings only narrow and order what is shown.

## Mounting elsewhere

The admin is an ASGI app, so it mounts wherever ASGI apps do.

```
from starlette.applications import Starlette
from starlette.routing import Mount

app = Starlette(routes=[Mount("/admin", app=admin)])
```

```
app.mount("/admin", admin)
```

```
from litestar import Litestar, asgi


@asgi("/admin", is_mount=True)
async def admin_app(scope, receive, send) -> None:
    await admin(scope, receive, send)


app = Litestar(route_handlers=[admin_app])
```

Links inside the admin follow the path it is mounted on, so `/admin`, `/backoffice` or `/tools/admin` all work without configuration.

## Several admins in one app

Mount as many as you like, each with its own views, users and settings:

```
staff = Admin(
    engine,
    title="Staff",
    views=[OrderView, CustomerView, ProductView],
    auth=staff_auth,
    secret_key=settings.staff_secret,
)
support = Admin(
    engine,
    title="Support",
    views=[OrderView, CustomerView],
    auth=support_auth,
    secret_key=settings.support_secret,
)

app.mount("/staff", staff)
app.mount("/support", support)
```

Each admin keeps its own session, in a cookie named after its title (`adminsite_staff`, `adminsite_support`), so signing in to one never signs you in to the other. Give two admins with the same title different names with `session_cookie=`. The same view class can be used in both; each admin gets its own instance.

## Signing in

An admin reachable from the internet needs a login. The quickest one:

```
from adminsite.auth import PasswordAuth, hash_password

admin = Admin(
    engine,
    views=[CustomerView, OrderView],
    auth=PasswordAuth({"nima": "pbkdf2_sha256$600000$..."}),
    secret_key=settings.admin_secret_key,
)
```

Make the hash once with `hash_password("your password")` and keep the result in your settings. See [Signing in](https://nimaxin.github.io/adminsite/auth/index.md) for checking your own user table instead.

## Trying the example

The repository has a small shop with an admin already set up:

```
git clone https://github.com/nimaxin/adminsite
cd adminsite
uv run uvicorn examples.shop:app --reload
```

Open http://127.0.0.1:8000/admin and sign in as `nima` / `letmein`.
# Guide

# Views

A `ModelView` says how one model appears in the admin. Class attributes describe the list and the form. Methods whose names start with `get_` answer the same questions per request, for when the answer depends on who is asking.

```
from adminsite import CountMode, ModelView


class OrderView(ModelView, model=Order):
    group = "Sales"
    display_template = "Order #{id}"

    list_display = ("id", "customer.name", "status", "total", "created_at")
    search_fields = ("id", "customer.name", "customer.email")
    list_filter = ("status", "total", "created_at")
    ordering = ("-created_at",)
    page_size = 50

    form_fields = ("customer", "status", "note")
    readonly_fields = ("total",)
```

## Naming

| Setting            | Default                                                        | Used for                                                          |
| ------------------ | -------------------------------------------------------------- | ----------------------------------------------------------------- |
| `name`             | the model name, plural and snake case: `orders`, `order_items` | the URL                                                           |
| `label`            | `Order`, `Order item`                                          | headings and buttons                                              |
| `label_plural`     | `Orders`, `Order items`                                        | the sidebar and the list heading                                  |
| `group`            | none                                                           | the sidebar section the view sits under                           |
| `display_template` | `str(record)`                                                  | how a record is named elsewhere, for example `"{name} ({email})"` |

`display_template` is also used when another model links to this one, so a customer picker on the order form shows `Lena Fischer (lena@fischer.de)` instead of just the name.

## The list

| Setting           | What it does                                                                                               |
| ----------------- | ---------------------------------------------------------------------------------------------------------- |
| `list_display`    | The columns, in order. Dotted paths such as `customer.name` follow links.                                  |
| `search_fields`   | The paths the search box looks in. Text matches anywhere in the value, numbers match exactly.              |
| `list_filter`     | Paths, or filters you built yourself. See [Filters](https://nimaxin.github.io/adminsite/filters/index.md). |
| `ordering`        | The starting order. `-created_at` means newest first.                                                      |
| `page_size`       | Rows per page. 25 unless you say otherwise.                                                                |
| `page_sizes`      | The sizes people may switch between. Empty leaves the size fixed.                                          |
| `count_mode`      | `EXACT` counts every match, `ESTIMATED` guesses on big tables, `NONE` skips the count.                     |
| `deferred_fields` | Columns the list never shows, left out of its query.                                                       |
| `global_search`   | Whether the command palette searches this view. On by default.                                             |
| `list_columns`    | More columns people can add from the Columns menu.                                                         |
| `icon`            | The sidebar icon: inline SVG markup, or the address of a picture.                                          |
| `pagination`      | `Pagination.OFFSET` for page numbers, `Pagination.KEYSET` for big tables.                                  |

With no `list_display`, every column is shown, and a foreign key such as `customer_id` appears as its relationship, `customer`.

Anything the list shows is loaded with the page. `customer.name` joins the customer into the same query; a path through a collection such as `items.quantity` costs one more query for the whole page, not one per row.

### Choosing columns

The **Columns** menu above the list hides and shows columns. It offers the columns of `list_display`, plus any in `list_columns`:

```
class OrderView(ModelView, model=Order):
    list_display = ("id", "customer.name", "status", "total")
    list_columns = ("customer.email", "note", "created_at")
```

The choice goes in the URL as `?cols=id&cols=total`, so it can be bookmarked and shared, and it is remembered in the session, so the list keeps those columns next time. The CSV export follows it too. Only columns on offer can be picked: a column you hide from some users in `get_list_display` stays hidden, whatever the URL says. Override `get_column_choices(request)` to offer different extras per user.

### Rows per page

`page_size` sets how many rows a page holds. Offer a few sizes and a menu appears above the list:

```
class OrderView(ModelView, model=Order):
    page_size = 25
    page_sizes = (25, 100, 500)
```

The choice goes in the URL as `?size=100`, stays while paging, sorting, searching and filtering, and is remembered in the session. Only a size on offer counts, so nobody can ask for a million rows by editing the URL. "Select all matching" still means every matching row, whatever the page shows.

### Saved views

A saved view keeps a search, filters, a sort and columns under a name, such as "Unpaid this month", so nobody has to click them together again. Switch them on for the admin:

```
admin = Admin(engine, views=[OrderView], saved_views=True)
```

The list gets a **Saved views** menu with the views and a **Save this view** button. A view belongs to the person who saved it. Ticking **Everyone can use it** shares it with the rest of the team; only its owner can remove it. Without sign in, every view is everyone's.

Like the [audit log](https://nimaxin.github.io/adminsite/audit/index.md), the views go to a SQLite file of their own, `adminsite_views.db`. To keep them in your database instead:

```
from adminsite import SavedViews
from adminsite.saved_views import saved_view_metadata

admin = Admin(engine, saved_views=SavedViews(engine))

# In your Alembic env.py, so the table is part of your migrations:
target_metadata = [Base.metadata, saved_view_metadata]
```

### The command palette

Press `Ctrl`+`K`, or `Cmd`+`K` on a Mac, anywhere in the admin to jump to a page or a record. With nothing typed it lists the pages. From two letters on it also runs each view's own search and shows the first five matches per view, named by `display_template`. Arrow keys move, Enter opens.

It searches only views the user may open, through `scope_query`, and only views with `search_fields`. Leave a view out, for example a very large table, with `global_search = False`.

### Large tables

Two things get slow once a table holds millions of rows: counting every match, and reaching deep pages, since the database walks every row before the page it returns. Both have a setting.

```
from adminsite import CountMode, ModelView, Pagination


class EventView(ModelView, model=Event):
    ordering = ("-created_at",)
    count_mode = CountMode.ESTIMATED
    pagination = Pagination.KEYSET
```

**Counting.** `CountMode.ESTIMATED` reads the row count Postgres and MySQL already keep in their statistics, which costs nothing, and shows "about 2,500,000". It does so only when nothing narrows the list and the table holds more than 10,000 rows; below that an exact count is cheap. Once a search, a filter or `scope_query` narrows the list, the count stops at 10,001 rows and shows "more than 10,000". On SQLite, which keeps no estimate, it counts exactly.

`CountMode.NONE` skips the count altogether. The pager then shows no total and learns whether there is a next page by reading one extra row, so a page is a single query.

**Paging.** `Pagination.KEYSET` continues from the last row seen instead of skipping rows, so page 400 costs the same as page 1. The pager shows Previous and Next, without page numbers, and the URL carries a short cursor such as `?after=WyIyMDI2...`. The primary key is added to the order, so rows with the same value never repeat or go missing between pages.

**Wide rows.** A list that never shows a large column still loads it on every row. Name those columns and the list query leaves them out:

```
class EventView(ModelView, model=Event):
    list_display = ("id", "kind", "created_at")
    deferred_fields = ("payload",)
```

The record page, the form and the API load them as usual, so nothing disappears, and a column that the list does show is loaded whatever this says, as is the key and anything `display_template` reads. Those are the columns every row needs, and reading one afterwards would cost a query per row. Answer per request with `get_deferred_fields(request)`.

A keyset needs columns it can compare. When the list is sorted by a column that can be empty, or by a path through a relationship such as `customer.name`, that page falls back to page numbers. Put an index on the columns you sort by, primary key last, such as `(created_at, id)`.

## The form

| Setting                                | What it does                                                                                                                        |
| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `form_fields`                          | The fields, in order. A relationship name, such as `customer`, gives a picker.                                                      |
| `readonly_fields`                      | Shown, but never read back from what was submitted.                                                                                 |
| `exclude`                              | Left out of both the list and the form.                                                                                             |
| `fields`                               | Field objects that replace the ones worked out from the columns. See [Fields](https://nimaxin.github.io/adminsite/fields/index.md). |
| `can_create`, `can_edit`, `can_delete` | Switch those pages off. See [Permissions](https://nimaxin.github.io/adminsite/permissions/index.md).                                |
| `detail_fields`                        | What the record page shows, when that differs from the form.                                                                        |
| `can_detail`, `can_export`             | Switch off the record page and the CSV export.                                                                                      |

A readonly field is safe against a tampered form: its value is never taken from the request, even if someone adds the input back by hand.

### The record page

The record page shows the form's fields unless you name its own. That is how a page shows things nobody should post back, and how a form keeps fields the page has no reason to repeat:

```
class UserView(ModelView, model=User):
    form_fields = ("name", "email", "is_active")
    detail_fields = (
        "name",
        "email",
        "is_active",
        "signed_up_at",
        "invoices",
        "raw_payload",
    )
```

Anything the page names is loaded with the record, so a linked record costs no extra query. Use `get_detail_fields(request, record)` to answer per user, and remember that a field only on the page is never read back from a form, so it needs no `readonly_fields` entry.

### Related records in the same form

An order and its lines belong together, so edit them on one page. Name the relationship in `inlines`:

```
from adminsite import Inline


class OrderView(ModelView, model=Order):
    inlines = (Inline("items", fields=("product", "quantity", "unit_price")),)
```

The lines show as a table under the order's fields, with an **Add a row** button and a button to remove each line. A new order starts with one blank row to fill in; an order that has its lines gets no empty row under them. Everything is saved in one transaction with the order, so a line that fails to validate keeps the order unsaved too, and the page comes back with what was typed, the error next to the cell, and a list of every problem at the top of the form.

| Option             | What it does                                                                               |
| ------------------ | ------------------------------------------------------------------------------------------ |
| `fields`           | The child's columns, in order. Defaults to every field except the link back to the parent. |
| `readonly_fields`  | Shown, not editable.                                                                       |
| `label`            | The heading above the table. Defaults to the relationship's name.                          |
| `extra`            | How many blank rows a table starts with while it has no rows yet. Defaults to 1.           |
| `can_delete`       | Whether rows can be removed.                                                               |
| `display_template` | How a child is named, as on a view.                                                        |

The relationship has to hold a list. Blank rows that stay empty are ignored, and a required field only counts once something else in the row is filled in. The detail page lists the children too.

Removing a row deletes that child record. A key sent for a row that belongs to another parent is refused.

Pick a different set per request with `get_inlines(request, record)`.

### Pages a view does not need

Some views are complete on the list, and some hold data nobody should carry out of the admin:

```
class SessionView(ModelView, model=Session):
    can_detail = False
    can_export = False
```

Without a detail page, rows open the form instead, or read as plain text where there is no form either, and saving lands back on the list. Without export, the CSV button is gone and the route refuses. Both go through `allows`, so `Permission.DETAIL` and `Permission.EXPORT` can be decided per user like any other permission.

### An icon in the sidebar

`icon` takes inline SVG markup, or the address of a picture:

```
class OrderView(ModelView, model=Order):
    icon = '<svg viewBox="0 0 16 16"><path d="M2 4h12v9H2z" fill="currentColor"/></svg>'
```

Markup is written into the page as it is, so keep it to icons you control. A relative address is served from the admin, so a plugin's `add_static` folder works.

## Answering per request

Every `get_` method receives the request, so the answer can depend on the user:

```
class OrderView(ModelView, model=Order):
    list_display = ("id", "customer.name", "status", "total")

    def get_list_display(self, request=None):
        if request.user.is_support:
            return ("id", "status")
        return super().get_list_display(request)

    def get_readonly_fields(self, request=None, record=None):
        if record is not None and record.status == "shipped":
            return ("customer", "status", "total")
        return ()
```

The methods are `get_list_display`, `get_search_fields`, `get_filters`, `get_ordering`, `get_form_fields`, `get_readonly_fields` and `get_actions`.

## Several views of one model

A model can have as many views as you like, as long as each has its own name:

```
class ShippedOrders(ModelView, model=Order):
    name = "shipped_orders"
    label_plural = "Shipped orders"

    def scope_query(self, statement, *, request=None):
        return statement.where(Order.status == OrderStatus.SHIPPED)
```

`scope_query` narrows every read the view makes. It is covered in [Permissions](https://nimaxin.github.io/adminsite/permissions/index.md).

# Fields

A field turns a value into text for the list, puts it into a form input, and reads it back when the form is submitted. adminsite picks one for every column from its type, so you rarely write one yourself.

| Column                            | Field           | Shown as                 | Edited with                             |
| --------------------------------- | --------------- | ------------------------ | --------------------------------------- |
| `str` with a length up to 255     | `StringField`   | the text                 | a text input                            |
| `str` without a length, or longer | `TextField`     | the text                 | a text box                              |
| `int`                             | `IntegerField`  | `42`                     | a number input                          |
| `float`                           | `FloatField`    | `4.2`                    | a number input                          |
| `Decimal`                         | `DecimalField`  | `1,234.50`               | a number input                          |
| `bool`                            | `BooleanField`  | `Yes` or `No`            | a switch                                |
| `date`                            | `DateField`     | `Sep 8, 2026`            | a date picker                           |
| `datetime`                        | `DateTimeField` | `Sep 8, 2026 14:05`      | a date and time picker                  |
| `time`                            | `TimeField`     | `14:05`                  | a time picker                           |
| an enum                           | `ChoiceField`   | `Shipped`                | a select                                |
| a relationship                    | `RelationField` | the linked record's name | a picker, or a search box on big tables |

Labels come from the column name: `created_at` reads "Created at", and `customer_id` reads "Customer".

## When a value does not fit

A value that cannot be converted comes back on the form, with a message under the field and everything else still filled in:

| Field                           | Message                               |
| ------------------------------- | ------------------------------------- |
| a required field left empty     | This field is required.               |
| `IntegerField`                  | Enter a whole number.                 |
| `DecimalField`                  | Enter an amount, for example 12.50.   |
| a string longer than its column | Keep this to 120 characters or fewer. |
| `ChoiceField`                   | Choose one of the listed options.     |

## Replacing a field

Give the view a field object with the same name as the path, and it replaces the one adminsite would have built:

```
from adminsite.fields import EmailField, RelationField, TextField


class CustomerView(ModelView, model=Customer):
    fields = (
        EmailField("email", required=True),
        TextField("notes", label="Internal notes", help_text="Only staff see this."),
    )


class OrderView(ModelView, model=Order):
    fields = (
        RelationField(
            "customer",
            target=Customer,
            required=True,
            display_template="{name} ({email})",
        ),
    )
```

Every field takes `label`, `required`, `readonly`, `help_text`, `max_length`, `default`, `format` and `secret`. `default` is what a new record's form starts with, and what an action's dialog opens with. `secret` says whether the [audit log](https://nimaxin.github.io/adminsite/audit/#actions) keeps `***` instead of the value an action was run with; left out, a name such as `password` or `api_key` decides. `format` is how a value is written wherever it is shown, as `str.format` takes it, the same way a dashboard's `Stat` and `Chart` take it:

```
from adminsite import FieldOptions


class OrderView(ModelView, model=Order):
    fields = (FieldOptions("total", format="€{:,.2f}"),)
```

The list, the record page, the export and the overview's cards then read `€1,234.50`. The form's input keeps the plain number, since that is what it reads back.

## Changing one thing about a field

Most of the time the field adminsite worked out is the right one and only its label or a line of help is wrong. `FieldOptions` changes those without naming the type, the target or anything else again:

```
from adminsite import FieldOptions


class ProductView(ModelView, model=Product):
    fields = (
        FieldOptions("name", label="Product name"),
        FieldOptions("description", help_text="Shown on the shop page."),
    )


class OrderView(ModelView, model=Order):
    fields = (FieldOptions("customer", display_template="{name} ({email})"),)
```

It takes whatever the field takes, so `label`, `required`, `readonly`, `help_text` and `max_length` work on any field, and `display_template` works on a link. An option the field does not take is an error when the view first builds it, naming the path, rather than a setting that quietly does nothing.

`FieldOptions` sits in the same `fields` tuple as whole fields. Where both name the same path the whole field wins, since it already says everything.

A label given this way is used as it stands. Without one, a path through a link names the link as well, so `customer.name` reads Customer name.

## Links to many records

A relationship that holds many records, such as a customer's orders, shows the linked records' names in the list and a multiple select in the form.

Above 100 records the select is no good, so the picker becomes a search box. It searches the other model's text columns through a lookup, and the records already linked sit above it as chips, each with a button to take it off. Picking a record adds one more, picking the same one twice changes nothing, and the box says how many are held. A link that holds a single record works the same way, except that picking replaces what is there.

The search box is the only way the picker can work on a large table, so the records it offers are whatever the lookup finds, twenty at a time. Give the other model a `display_template` so those twenty read as something other than `<Order object at 0x...>`.

A picker reads through the other model's own view, so its `scope_query` and its permissions apply here as on any other page. A user who may see only their own region's customers sees only those in the picker, and a view nobody may open offers nothing at all. Where the other model has no view of its own, there is nothing to ask and its records are read directly.

The search looks in the target view's `search_fields`. Where it names none, it looks in the text columns the records are named by, which the picker is already showing. So a column a view keeps off its pages cannot be read a letter at a time through a picker, and a target with neither `search_fields` nor a `display_template` cannot be narrowed at all.

## JSON columns

A `JSON` or `JSONB` column gets a `JSONField` by itself. The list shows the document on one line, cut short where it is long, and the form edits it in a box, laid out over several lines. A document that does not parse comes back as an error on that field, with the text exactly as it was written, so nothing is lost and nothing malformed is stored.

The [JSON API](https://nimaxin.github.io/adminsite/api/index.md) reads and writes these columns as JSON, so `{"options": {"free_over": 10}}` is stored as an object, not as a string.

## A value the view works out

Not every column on a page is a column. `Computed` shows something the view works out from the record, in the list, on the record page and in the export:

```
from adminsite import Computed


class ProductView(ModelView, model=Product):
    list_display = ("name", "price", "capacity")
    fields = (
        Computed(
            "capacity",
            lambda product: f"{len(product.slots)}/{product.limit}",
            label="Capacity",
            needs=("slots",),
        ),
    )
```

`needs` names the paths the function reads, so they are loaded with the page. Without it a list of 25 records would ask the database 25 times.

A computed value is never written, sorted or filtered: its column has no sort link, the form leaves it out, and so do imports and the API's writes. The API still reads it.

## When a field needs the whole record

`display(value)` sees only the value, which is not always enough: an amount reads differently per currency, and a status reads differently when a second column says the check was switched off. Override `text_for` instead, which gets the record:

```
class Money(Field):
    widget = "number"

    def text_for(self, record, value):
        if value is None:
            return ""
        return f"{value:,.2f} {record.currency}"
```

Everything that shows a value goes through `text_for`: the list, the record page and the export. It falls back to `display`, so fields that do not need the record carry on as they are.

## A link or a badge in a cell

Cells are escaped text, so a name holding `<script>` shows as it was written and nothing else. Return `Html` where the cell is meant to be markup, such as a link to a file or to another system:

```
from adminsite import Computed, Html


class OrderView(ModelView, model=Order):
    list_display = ("id", "customer.name", "tracking")
    fields = (
        Computed(
            "tracking",
            lambda order: Html('<a class="link" href="{}">Track</a>').format(
                order.tracking_url
            ),
            needs=("tracking_url",),
        ),
    )
```

`Html` writes its own text into the page as markup. Everything put in with `format` or `%` is escaped first, so a value out of the database cannot carry markup of its own into the page. Write the markup yourself and the values through `format`, never the other way round.

The CSV export and the JSON API send the same cell without its tags, since markup belongs on a page and not in a spreadsheet. The first column is already a link to the record, so put markup in another one.

## Files and pictures

A file field keeps the upload in a storage and its key in a string column. Declare it among the view's `fields`:

```
from adminsite.fields import FileField, ImageField
from adminsite.files import LocalStorage

uploads = LocalStorage("uploads")


class ProductView(ModelView, model=Product):
    fields = (
        ImageField("photo", storage=uploads),
        FileField(
            "datasheet", storage=uploads, accept=".pdf", max_size=20 * 1024 * 1024
        ),
    )
```

The form gets a file input with the current file, a thumbnail for pictures and a box to remove it. The list shows a thumbnail or a link, and the detail page a larger picture.

| Option     | What it does                                                                                                                                      |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `storage`  | Where the files go.                                                                                                                               |
| `accept`   | The types taken, as in a browser's `accept`: extensions such as `.pdf`, types such as `application/pdf`, or `image/*`. Checked on the server too. |
| `max_size` | The largest file in bytes. 10 MB for files and 5 MB for pictures unless you say.                                                                  |

`ImageField` takes PNG, JPEG, GIF and WebP, and checks the file's first bytes, so a script renamed to `.png` is refused. SVG is left out because it can carry script.

**Keys.** A file is stored under a key such as `2026/09/k3j9x2-datasheet.pdf`: the month, a random part so names never clash, and the original name, cleaned of anything that could climb out of the folder. Make the column long enough for it, `String(255)` is plenty.

**Serving.** By default files are served through the admin at `/admin/-/files/...`, behind the sign in, to whoever may open the view. Pictures and PDFs open in the browser; anything else is sent as a download, so an uploaded HTML file can never run in the admin. If your application already serves the folder, say where, and links point there instead:

```
uploads = LocalStorage("uploads", url_prefix="https://cdn.example.com/uploads")
```

**Replacing and removing.** A new upload replaces the old file, which is deleted once the save has committed; a save that fails leaves the old file and throws the new one away. Deleting a record keeps its files, so nothing is lost by accident.

**Other storages.** Subclass `FileStorage` to keep files elsewhere, such as S3. `save` stores an upload and returns its key, `delete` removes one, and `url` or `response` say how it is fetched, for example with a redirect to a signed URL.

File fields are not available inside [inlines](https://nimaxin.github.io/adminsite/views/#related-records-in-the-same-form) yet.

## Your own field type

Subclass `Field` and say how to show and read the value:

```
from adminsite.exceptions import FieldValidationError
from adminsite.fields import Field


class PercentField(Field):
    widget = "number"
    python_type = float
    error_message = "Enter a percentage, for example 12.5."

    def display(self, value):
        return "" if value is None else f"{value:.1f}%"

    def to_python(self, text):
        number = super().to_python(text.rstrip("%"))
        if not 0 <= number <= 100:
            raise FieldValidationError(self.name, "Enter a value between 0 and 100.")
        return number
```

To use it for every column of a type, register it:

```
from adminsite.fields import default_registry

default_registry.register(Percentage, PercentField)
```

How the input looks is decided by its `widget` name; see [Customizing the look](https://nimaxin.github.io/adminsite/customizing/#one-widget) to draw your own.

# Filters

Filters sit in a panel above the list. The ones in use show as chips, and the whole state lives in the URL, so a filtered list can be bookmarked or sent to someone.

## Built in

Name a path in `list_filter` and adminsite picks the filter that fits the column:

```
class OrderView(ModelView, model=Order):
    list_filter = ("status", "total", "created_at", "customer", "customer.region")
```

| Column           | Filter                                       | In the URL                                                |
| ---------------- | -------------------------------------------- | --------------------------------------------------------- |
| enum             | `ChoiceFilter`, several values, with counts  | `?status=PAID&status=SHIPPED`                             |
| `bool`           | `BooleanFilter`                              | `?is_active=true`                                         |
| number           | `NumberRangeFilter`, either end optional     | `?total=10,50` or `?total=100,`                           |
| date or datetime | `DateRangeFilter`, a shortcut or two dates   | `?created_at=week` or `?created_at=2026-09-01,2026-09-30` |
| relationship     | `RelationFilter`, by the linked record's key | `?customer=3`                                             |
| text             | `TextFilter`, matching part of the value     | `?email=fischer`                                          |

A dotted path such as `customer.region` filters through the link without adding a join, so rows are never duplicated. Its name in the URL is `customer__region`.

## Counts

Choice and boolean filters show how many records each option matches. The counts follow the search but not the other filters, so they stay steady while you pick. On a big table, turn them off:

```
from adminsite.backends.sqlalchemy import ChoiceFilter


class OrderView(ModelView, model=Order):
    list_filter = (
        ChoiceFilter(
            "status",
            choices=(("PAID", "Paid"), ("SHIPPED", "Shipped")),
            show_counts=False,
        ),
    )
```

## Writing your own

A filter is a class that returns a condition. Here orders are grouped by whether they are late:

```
from datetime import timedelta

from sqlalchemy import func

from adminsite.backends.sqlalchemy import SQLFilter
from adminsite.filters import FilterOption


class DeliveryFilter(SQLFilter):
    """Orders past their delivery date, or due soon."""

    async def options(self, context):
        return [FilterOption("late", "Overdue"), FilterOption("soon", "Due in 2 days")]

    def condition(self, value, repository):
        if value.first == "late":
            return Order.due_at < func.now()
        return Order.due_at.between(func.now(), func.now() + timedelta(days=2))


class OrderView(ModelView, model=Order):
    list_filter = ("status", DeliveryFilter("delivery", label="Delivery"))
```

`value.first` is the chosen option, and `value.values` holds all of them when the filter allows several (set `multiple = True` on the class).

When the filter needs to change the statement itself, for example to add a join, override `apply` instead of `condition`:

```
from sqlalchemy import func, select


class BigSpenders(SQLFilter):
    def apply(self, statement, value, repository):
        spent = (
            select(Order.customer_id)
            .group_by(Order.customer_id)
            .having(func.sum(Order.total) > int(value.first))
        )
        return statement.where(Customer.id.in_(spent))
```

## One place for every read

The list, its count, a CSV export and a bulk action all go through the same filters. "Select all 12,408 matching" always means exactly the rows the list is showing.

# Actions

An action is a button that runs over the rows the user ticked. Mark a method with `@action`:

```
from adminsite.actions import Selection, action


class OrderView(ModelView, model=Order):
    @action("Mark as shipped", confirm="Mark the chosen orders as shipped?")
    async def ship(self, selection: Selection) -> str:
        changed = await selection.update(status=OrderStatus.SHIPPED)
        return f"{changed} orders marked as shipped."
```

Ticking rows shows a bar with the view's actions. What the method returns is shown to the user once it has run.

## Every row that matches

Ticking every row on the page offers "Select all 12,408 matching". The selection then covers every row the current search and filters match, not only the page.

A `Selection` is a query, not a list of records, so an action over twelve thousand rows is still one statement. It gives you:

| Method                             | What it does                                                          |
| ---------------------------------- | --------------------------------------------------------------------- |
| `await selection.update(**values)` | Changes every covered row in one `UPDATE`, and returns how many.      |
| `await selection.delete()`         | Deletes every covered row in one `DELETE`, and returns how many.      |
| `await selection.count()`          | How many rows it covers.                                              |
| `await selection.records()`        | Loads the records, for work that needs each one.                      |
| `selection.statement()`            | A `select()` of the covered primary keys, to use in your own queries. |

`update` and `delete` never load the records, so they skip the save hooks, and a delete relies on the database for cascades. Give a child table's foreign key `ondelete="CASCADE"` where children should go with their parent. Use `records()` when the hooks matter.

## Asking for values first

An action can ask for values before it runs. They appear in a dialog, are checked like form fields, and reach the method by name:

```
from adminsite.fields import ChoiceField, StringField

CARRIERS = (("dhl", "DHL Express"), ("ups", "UPS"), ("postnl", "PostNL"))


class OrderView(ModelView, model=Order):
    @action(
        "Mark as shipped",
        confirm="Mark the chosen orders as shipped?",
        inputs=[
            ChoiceField("carrier", choices=CARRIERS, required=True),
            StringField("tracking", label="Tracking number", max_length=40),
        ],
    )
    async def ship(
        self, selection: Selection, carrier: str, tracking: str | None
    ) -> str:
        changed = await selection.update(
            status=OrderStatus.SHIPPED, carrier=carrier, tracking=tracking
        )
        return f"{changed} orders sent with {carrier}."
```

A missing or invalid value stops the action and tells the user which field and why. The names `keys`, `everything` and `_csrf` are taken by the action form itself and cannot be used.

### Where the dialog starts

`default` says what an input holds when the dialog opens, so switches that are usually on open on and nobody has to set them every time. `multiple=True` on a `ChoiceField` lets one input hold several options, and the method receives a list:

```
class OrderView(ModelView, model=Order):
    @action(
        "Download",
        inputs=[
            ChoiceField("kinds", choices=KINDS, multiple=True, default=("paper",)),
            BooleanField("with_totals", label="With totals", default=True),
        ],
    )
    async def download(
        self, selection: Selection, kinds: list[str], with_totals: bool
    ) -> Response: ...
```

`default` works on any field, and a form for a new record starts from it too. A stored value always wins over it, so it never overwrites anything.

With the [audit log](https://nimaxin.github.io/adminsite/audit/#actions) on, the values an action was run with are written down with it. A secret is kept as `***`: an input named like `password` or `api_key`, or one given `secret=True`.

### Choices worked out per request

The inputs are read when the page is drawn, so `get_actions` can hand back an action carrying whatever this user may pick:

```
import dataclasses


class OrderView(ModelView, model=Order):
    @action("Move", inputs=[ChoiceField("warehouse", choices=())])
    async def move(self, selection: Selection, warehouse: str) -> str: ...

    def get_actions(self, request=None):
        choices = warehouses_for(request.user)
        return tuple(
            dataclasses.replace(
                item, inputs=(ChoiceField("warehouse", choices=choices),)
            )
            if item.name == "move"
            else item
            for item in super().get_actions(request)
        )
```

The run goes through `get_actions` as well, so a value that was never on offer is refused rather than accepted because the class said so.

## Options

| Option       | What it does                                                                   |
| ------------ | ------------------------------------------------------------------------------ |
| `label`      | The button text. Defaults to the method name, `mark_paid` reading "Mark paid". |
| `confirm`    | A question asked in a dialog before it runs.                                   |
| `inputs`     | Fields to ask for, each with an optional `default`. See above.                 |
| `dangerous`  | Draws the button in red.                                                       |
| `permission` | What the user needs to run it. `Permission.EDIT` unless you say otherwise.     |
| `name`       | The name in the URL, if the method name will not do.                           |

## Refusing

Raise `RefusedError` to stop an action with a message. Everything it did is rolled back:

```
from adminsite import RefusedError


@action("Refund")
async def refund(self, selection: Selection) -> str:
    if await selection.count() > 50:
        raise RefusedError("Refund at most 50 orders at a time.")
    ...
```

An action that breaks a database constraint, for example deleting customers that orders still point at, is rolled back and reported the same way.

## Exporting

Every list has an "Export CSV" button. It exports every row the search and filters match, not just the page, using the values the list shows, and streams them in batches, so a large export never has to fit in memory.

## What an action acts on

`on` says what an action is about, and what its method is given:

| `on`                       | Where it appears                      | The method gets     |
| -------------------------- | ------------------------------------- | ------------------- |
| `"selection"`, the default | above the list, once rows are ticked  | a `Selection`       |
| `"record"`                 | on each row, and on the record's page | `(record, session)` |
| `"view"`                   | above the list, with nothing ticked   | `(session)`         |

### On one record

```
class InvoiceView(ModelView, model=Invoice):
    @action("Confirm", on="record", confirm="Confirm this invoice?")
    async def confirm(self, record: Invoice, session: SessionAdapter) -> str:
        record.status = "confirmed"
        return f"Invoice {record.number} confirmed."
```

The button sits on the row and on the record's page, and the record's own permission decides whether it is offered: `allows(action, record=record)` refusing a paid invoice hides Confirm for that row and refuses the request if someone posts it anyway. A view with several record actions collects them into a menu on the row. Afterwards the person lands back on the record.

Everything a selection action has is here too: a confirmation, inputs asked in a dialog, a `dangerous` style, and an entry in the record's [history](https://nimaxin.github.io/adminsite/audit/index.md).

### On the whole view

Some work is about the table, not about any row: fetching from another system, importing from an API, sending a summary. Those need nothing ticked:

```
class OrderView(ModelView, model=Order):
    @action("Sync from the provider", on="view", permission=Permission.VIEW)
    async def sync(self, session: SessionAdapter) -> str:
        return f"{await fetch_new_orders(session)} orders fetched."
```

## Answering with a file

An action can return a response instead of a message, which is how a download works:

```
@action("Download as CSV", on="record", permission=Permission.EXPORT)
async def download(self, record: Order, session: SessionAdapter) -> Response:
    return Response(
        render_csv(record),
        media_type="text/csv",
        headers={
            "content-disposition": f'attachment; filename="order-{record.id}.csv"'
        },
    )
```

Anything Starlette can answer with works: a file, JSON, or a redirect to somewhere the result waits. The transaction is committed first, so the answer describes work that really happened.

# Importing

People can add and change records from a CSV or Excel file. Nothing is written until they have seen a preview of every row: what will be added, what will change, and what is wrong.

Importing is off until you switch it on for a view, since it writes many records at once:

```
class CustomerView(ModelView, model=Customer):
    form_fields = ("name", "email", "region", "is_active")
    can_import = True
```

The list gets an **Import** button. Excel files need openpyxl:

```
pip install "adminsite[excel]"
```

## The file

The first row names the columns. A header is a field's name or its label, in any case, so `email`, `Email` and `E-mail address` (if that is the label) all work. Columns that match nothing are listed and left out. The import page lists the columns and offers an empty file to fill in.

The columns are the primary key and the form's fields. Read only fields, file fields and links to many records are left out.

- **A row with a key** that exists changes that record. Only the columns in the file are touched.
- **A row without a key** adds a record. Every required field has to be in the file.
- **A row with a key that does not exist** is a problem, not a new record, so a typo never creates a stray record.

Values are checked by the same fields as the form, and a few spreadsheet habits are accepted: a choice may be written as its label ("Shipped"), numbers may group thousands ("1,250.50"), and yes or no columns take yes, no, true, false, 1 and 0. A link to another record takes that record's key.

CSV files may be separated by commas, semicolons or tabs, and saved as UTF-8 or in the Windows code page older Excel versions use.

## The preview

The preview shows the first fifty rows and every row with a problem, each problem next to its cell, with counts of what is new, what changes and what is wrong. **Import** saves the good rows and skips the rest.

Each row is saved through the view like a form, so permissions, hooks and the [audit log](https://nimaxin.github.io/adminsite/audit/index.md) all apply. A hook that refuses a row stops only that row, and the message after the import says which rows were refused and why.

Between the preview and the import the file waits in the server's temporary folder for up to an hour. It belongs to the person who uploaded it and can be imported once.

| Setting        | What it does                                                             |
| -------------- | ------------------------------------------------------------------------ |
| `can_import`   | Switches importing on. `Permission.IMPORT` in `allows` decides per user. |
| `import_limit` | The most rows one file may hold. 10,000 unless you say.                  |

# Permissions

Permissions work at four levels: the whole view, one action, one field, and one row. Each is a method on the view, so the answer can depend on the request and on the record.

## The view and its actions

The simplest switches are attributes:

```
class AuditedPayments(ModelView, model=Payment):
    can_create = False
    can_delete = False
```

For anything that depends on the user, override `allows`:

```
from adminsite import Permission


class OrderView(ModelView, model=Order):
    async def allows(self, action, *, request=None, record=None):
        user = request.state.user
        if action == Permission.DELETE:
            return user.is_manager
        if action == Permission.EDIT and record is not None:
            return record.status != "shipped"
        return await super().allows(action, request=request, record=record)
```

`action` is one of `Permission.VIEW`, `CREATE`, `EDIT`, `DELETE`, `DETAIL`, `EXPORT`, `IMPORT` and `HISTORY`, or the permission an [action](https://nimaxin.github.io/adminsite/actions/index.md) asks for. The check runs before a page is shown and again before anything is written, so a refused user gets an error even if they post the form by hand. Buttons for things the user may not do are left out.

A refused page shows "Not allowed" inside the admin with a 403, and views a user may not open are left out of the sidebar.

## History

`Permission.HISTORY` decides who reads the [audit log](https://nimaxin.github.io/adminsite/audit/index.md) of a view: the History tab on its records, and its entries on the Activity page. The log keeps every field's old and new value, so refuse it where the values are sensitive:

```
class PayrollView(ModelView, model=Salary):
    async def allows(self, action, *, request=None, record=None):
        if action == Permission.HISTORY:
            return request.state.user.is_hr
        return await super().allows(action, request=request, record=record)
```

The Activity page shows only entries from views where the user has both `VIEW` and `HISTORY`, and only from views registered on this admin, so two admins sharing one log never show each other's entries. A user with no such view does not see the Activity page at all.

## Rows

`scope_query` narrows every read the view makes:

```
class OrderView(ModelView, model=Order):
    def scope_query(self, statement, *, request=None):
        return statement.where(Order.region == request.state.user.region)
```

It is applied to the list, its count, opening one record, the CSV export and bulk actions. A row outside the scope cannot be seen, opened, changed or deleted, and guessing its key in the URL gives a "not found". There is no path through the admin that forgets to check.

That includes a picker on someone else's form. When an order links to a customer, the picker reads through `CustomerView`, so it offers only the customers this user may see, and offers none at all where they may not open the view. See [Fields](https://nimaxin.github.io/adminsite/fields/#links-to-many-records).

The same holds when the form comes back. A key sent for a link is resolved through the target's own view, so a customer outside the user's scope cannot be attached by editing the form, and the answer to a key the view will not give up is the same as to a key that does not exist: "Choose a record." A model with no view of its own is loaded by key, since there is no view to ask.

Sorting follows it too. `?sort=` in the URL is honoured only for a column the user can read somewhere on the view: one on offer in the list, on the record page or in the form. Sorting by anything else, such as a column left out with `exclude`, is ignored rather than putting the rows in the order of a value the user cannot see.

## Fields

Hide a column or lock a field for some users with the `get_` methods:

```
class CustomerView(ModelView, model=Customer):
    list_display = ("name", "email", "credit_limit")

    def get_list_display(self, request=None):
        if not request.state.user.can_see_money:
            return ("name", "email")
        return super().get_list_display(request)

    def get_readonly_fields(self, request=None, record=None):
        if not request.state.user.is_manager:
            return ("credit_limit",)
        return ()
```

A locked field is ignored when the form comes back, so adding the input back with the browser's developer tools changes nothing.

## Who is asking

When signing in is set up, the user is on `request.scope["user_record"]`, as your [auth provider](https://nimaxin.github.io/adminsite/auth/index.md) loaded it. If your application already puts the user on `request.state` with its own middleware, use that instead; adminsite passes the same request through.

# Hooks

Hooks run around a save or a delete, inside the same transaction. They receive the session, so a business rule can read or write other tables, and they can refuse the change.

```
from adminsite import RefusedError
from adminsite.views.writing import DeleteContext, SaveContext


class OrderView(ModelView, model=Order):
    async def before_save(self, context: SaveContext) -> None:
        if context.created:
            stock = await context.session.get(Stock, context.record.product_id)
            if stock is None or stock.quantity < 1:
                raise RefusedError("That product is out of stock.")

    async def after_save(self, context: SaveContext) -> None:
        await context.session.add(Notification(order_id=context.record.id))

    async def before_delete(self, context: DeleteContext) -> None:
        if context.record.status == "shipped":
            raise RefusedError("A shipped order cannot be deleted.")
```

| Hook            | When it runs                                                               |
| --------------- | -------------------------------------------------------------------------- |
| `before_save`   | Before the submitted values are written onto the record.                   |
| `after_save`    | After the flush, so the record has its primary key, and before the commit. |
| `before_delete` | Before the record is deleted.                                              |
| `after_delete`  | After the delete is flushed, before the commit.                            |

## What a hook receives

`SaveContext` has:

| Attribute | What it holds                                      |
| --------- | -------------------------------------------------- |
| `session` | The session, for reading and writing other tables. |
| `record`  | The record being saved. On create, a new instance. |
| `values`  | The values that were submitted, already converted. |
| `created` | Whether this is a new record.                      |
| `request` | The request, to see who is asking.                 |

`DeleteContext` has `session`, `record` and `request`.

## Refusing

Raise `RefusedError` with a message and the whole change is rolled back, including anything the hook already wrote. The message is shown on the form, or above the list for a delete.

Any other exception is treated as a fault: the change is rolled back, and the error is reported as one, so a bug in a hook is never mistaken for a business rule.

## The session in a hook

The session is adminsite's wrapper, the same for async and sync engines, so a hook is written once:

```
await context.session.add(record)
await context.session.get(Model, key)
await context.session.scalar(select(func.count()).select_from(Model))
```

For work that needs a plain SQLAlchemy `Session`, such as lazy loading, use `run`:

```
def count_lines(session):
    order = session.get(Order, key)
    return len(order.items)


total = await context.session.run(count_lines)
```

## Changing a value before it is stored

`before_save` runs before the submitted values are written onto the record, so that is where to change them. Change `context.values`, or use `context.set`:

```
class ProductView(ModelView, model=Product):
    async def before_save(self, context: SaveContext) -> None:
        name = context.values.get("name")
        if name:
            context.set("slug", slugify(name))
```

Whatever the hook leaves in `context.values` is what is stored, so the database never sees the untransformed value and a unique check fires against the value you meant. Setting an attribute on `context.record` here would be overwritten a moment later by the value from the form; set the attribute in `after_save` only for things the form does not send.

## Refusing one field

A refusal with a field name appears next to that input, like any other problem with what was typed, and everything else the person wrote stays in place:

```
async def before_save(self, context: SaveContext) -> None:
    delay = context.values.get("validation_delay")
    if delay is not None and delay < context.record.check_delay:
        raise RefusedError("Keep this above the check delay.", field="validation_delay")
```

Without a field the message sits above the form, as before. The [JSON API](https://nimaxin.github.io/adminsite/api/index.md) answers 422 with `{"errors": {"validation_delay": "..."}}` for a refusal about a field, and 409 for the rest.

# Audit log

Switch it on and adminsite writes down every create, change and delete: who did it, when, and what each field was before and after.

```
admin = Admin(engine, views=[OrderView, CustomerView], audit=True)
```

Every record's page gets a **History** tab, and the sidebar gets an **Activity** page listing everything across the admin.

Values are written the way the admin shows them, so a change reads "Customer: Lena Fischer → Marco Rossi" rather than "customer_id: 1 → 2".

## Where the entries go

`audit=True` keeps the log in a SQLite file of its own, `adminsite_audit.db` in the working directory. It needs no setup and no migration.

That suits a single server. Each worker process or container gets its own file, though, so with several of them, or with containers that are rebuilt, keep the log in your own database instead:

```
from adminsite.audit import AuditLog

admin = Admin(engine, views=[OrderView], audit=AuditLog(engine))
```

The table is `adminsite_audit_log`, defined on `audit_metadata`. adminsite never creates a table in your database uninvited, so add it to your migrations:

```
# alembic/env.py
from adminsite.audit import audit_metadata

target_metadata = [Base.metadata, audit_metadata]
```

Or let adminsite create it, for a quick start:

```
audit = AuditLog(engine, create_table=True)
```

A file of its own at another path works too: `AuditLog("sqlite:////var/lib/shop/audit.db")`.

New versions of adminsite add columns to this table. Every one of them may be empty, so a table adminsite created itself gets them added the first time the log is used. For a table in your own migrations, generate a migration after upgrading.

## Actions

Every action run is written down, whatever it acts on and whatever it answers with, a file included:

- An action on one record writes an entry for it, with the fields it changed, the way a save does.
- A bulk action writes one entry for each record it touched, and the entries share a batch id. Every record's history shows the action, and the batch can still be read as one event. This is how Laravel Nova and Django's bulk delete record them.
- An action on the whole model writes one entry for the model, with no record.

The records a bulk action covers are read before it runs. "Mark every pending order as shipped" would find no pending orders afterwards, so reading them first is the only way to know which ones it changed. For `selection.update`, the old values are read in the same single query. A download over three chosen orders says who took which three.

Each entry keeps the values the action was run with, in `entry.inputs`. A secret is kept as `***`: an input whose name is made of a word such as `password`, `secret`, `token`, `key` or `pin`, as in `api_key`, or one given `secret=True`. Give `secret=False` to keep a value whose name only looks secret. An uploaded file is kept by its name, type and size, never by what is in it.

An action that is refused, that the person may not run, or that fails is written down too, as failed, with the reason in `entry.error`. Its work is rolled back first, and the entry is written after, outside that transaction. A refusal keeps its message; any other error keeps only its kind, such as `ZeroDivisionError`, since its text may hold the data itself.

## Exports

Downloading a list as CSV writes an entry for the model with the list's search, filters, sort and columns in `entry.inputs`. An export can hold thousands of rows, so the entry names the list rather than each record in it.

## What is never recorded

- A save that was rolled back. Entries are written only after the commit succeeds, so a hook that refuses a save leaves no trace. Actions are different: a refused or failed one is written down as failed, as above.
- A save that changed nothing. Saving a form without edits writes no entry.

## Who did it, and from where

Each entry names the person twice. `entry.user` is the name the admin shows for them, and `entry.user_key` is what your [auth provider](https://nimaxin.github.io/adminsite/auth/index.md)'s `identity(user)` returns. The name reads well; the key still finds the same person after their name changes. For `PasswordAuth` both are the username. Without signing in, entries show "Someone".

Each entry also keeps the IP address and the browser's own description of itself, as `entry.ip` and `entry.user_agent`. The History tab shows the address, and the browser when you point at it. The address is the one your ASGI server worked out, so behind a proxy it is the visitor's only when the server trusts that proxy, for example with uvicorn's `--forwarded-allow-ips`.

## Signing in

With a [sign in](https://nimaxin.github.io/adminsite/auth/index.md) set up, the log also keeps every sign in, every failed attempt and every sign out, each with its address and browser. A failed attempt is filed under the account when there is one, and otherwise under the name that was typed. `PasswordAuth` says whether the username was unknown or the password wrong, and your own provider gives its reason by raising `SignInRefused` from `verify`. The reason stays in the log; the person signing in is never told it.

Signing in happens to no model, so these entries have an empty `view` and no view's permissions decide who reads them. By default the Activity page shows them to someone who may read the history of every model. Override `AuthProvider.may_read_sign_ins` to let others see them too.

## The Activity page

The Activity page lists the log newest first, fifty entries at a time, with a link to the older ones. Its tabs narrow it to one model, and its filters to:

- one kind of entry, such as changes, actions, exports or failed sign ins;
- one person, by the key their provider gives them or by the name shown;
- a range of days, the last one included;
- one record, by its key.

The filters are part of the address, so a result can be bookmarked or sent to someone who may read it too. A record's History tab shows its latest twenty entries, and a link to the rest on the Activity page, filtered to that record.

## Reading it yourself

```
from adminsite.audit import AuditEvent, AuditQuery

entries = await admin.audit.find(AuditQuery(view="orders", record_key="42"), limit=50)
deletes = await admin.audit.find(
    AuditQuery(user="nima", events=[AuditEvent.DELETED], since=last_monday), limit=100
)

for entry in entries:
    print(entry.occurred_at, entry.user, entry.event, entry.changes)
```

`entry.changes` maps each field name to a pair of values, before and after. Times are stored in UTC. Every field of `AuditQuery` narrows the result, and `older_than`, the time and id of the last entry you have, gives the page after it.

## Keeping the log somewhere else

The admin writes and reads the log through two methods, `record` and `find`, and anything that has them can take `AuditLog`'s place: a table your application already has, or a service you send logs to. The History tab and the Activity page read through `find`, so they show whatever your store returns, including rows written before the admin existed.

```
from collections.abc import Sequence

from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker

from adminsite.audit import AuditEntry, AuditEvent, AuditQuery


class ChangeLogStore:
    """The admin's log, in the application's own change_log table."""

    def __init__(self, sessions: async_sessionmaker[AsyncSession]) -> None:
        self.sessions = sessions

    async def record(self, entries: Sequence[AuditEntry]) -> None:
        async with self.sessions() as session:
            session.add_all(
                ChangeLog(
                    at=entry.occurred_at,
                    table_name=entry.view,
                    row_key=entry.record_key,
                    event=entry.event.value,
                    changes={name: list(pair) for name, pair in entry.changes.items()},
                    payload=dict(entry.inputs),
                    error=entry.error,
                    who=entry.user_key,
                    who_name=entry.user,
                    ip=entry.ip,
                    user_agent=entry.user_agent,
                )
                for entry in entries
            )
            await session.commit()

    async def find(self, query: AuditQuery, *, limit: int) -> list[AuditEntry]:
        statement = select(ChangeLog).order_by(ChangeLog.at.desc(), ChangeLog.id.desc())
        if query.view is not None:
            statement = statement.where(ChangeLog.table_name == query.view)
        if query.record_key is not None:
            statement = statement.where(ChangeLog.row_key == query.record_key)
        # ...and the other fields of the query, the same way.
        async with self.sessions() as session:
            rows = await session.scalars(statement.limit(limit))
            return [
                AuditEntry(
                    id=row.id,
                    occurred_at=row.at,
                    view=row.table_name,
                    record_key=row.row_key,
                    event=AuditEvent(row.event),
                    changes={name: tuple(pair) for name, pair in row.changes.items()},
                    inputs=row.payload or {},
                    error=row.error,
                    user_key=row.who,
                    user=row.who_name,
                    ip=row.ip,
                    user_agent=row.user_agent,
                )
                for row in rows
            ]


admin = Admin(engine, views=[OrderView], audit=ChangeLogStore(sessions))
```

A row whose kind has no `AuditEvent` of its own can come back as `AuditEvent.ACTION`, with its name in `action`. `diff` and `as_json`, which the admin uses to describe a change, are in `adminsite.audit` too, for code that writes entries of its own.

A store can also wrap another. This one keeps the log as usual, without the addresses:

```
from dataclasses import replace

from adminsite.audit import AuditLog, AuditStore


class WithoutAddresses:
    """The log as usual, but no IP address or browser is kept."""

    def __init__(self, store: AuditStore) -> None:
        self.store = store

    async def record(self, entries: Sequence[AuditEntry]) -> None:
        await self.store.record(
            [replace(entry, ip=None, user_agent=None) for entry in entries]
        )

    async def find(self, query: AuditQuery, *, limit: int) -> list[AuditEntry]:
        return await self.store.find(query, limit=limit)


admin = Admin(engine, views=[OrderView], audit=WithoutAddresses(AuditLog(engine)))
```

# Dashboard

The overview page is a grid of cards. Without any setup it shows how many records each view holds. Pass `dashboard` to choose the cards:

```
from sqlalchemy import func, select

from adminsite import Admin, Chart, RecentRecords, Stat

order_day = func.date(Order.created_at)

admin = Admin(
    engine,
    views=[OrderView, CustomerView],
    dashboard=[
        Stat("Revenue", select(func.sum(Order.total)), format="€{:,.2f}"),
        Stat(
            "Waiting to ship",
            select(func.count()).where(Order.status == "paid"),
            link="orders?status=PAID",
        ),
        Chart(
            "Revenue per day",
            select(order_day, func.sum(Order.total))
            .group_by(order_day)
            .order_by(order_day),
            format="€{:,.2f}",
        ),
        RecentRecords("Latest orders", "orders", sort="-created_at", detail="total"),
    ],
)
```

Cards sit four to a row on a wide screen and one to a row on a phone. Each has a `width` from 1 to 4; stats take one column, charts and lists two.

## Where the numbers come from

A card reads either a SQLAlchemy `select`, or an async function that receives the session and returns the value:

```
async def active_customers(session):
    return await session.scalar(select(func.count()).where(Customer.is_active))


Stat("Active customers", active_customers)
```

The function is the way to reach anything else: another database, an API, a cache.

## The cards

### Stat

A single number.

| Option     | What it does                                                                                                                 |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `format`   | How the value is written, such as `"{:,}"` or `"€{:,.2f}"`.                                                                  |
| `previous` | A second source for the period before. The card then shows the change, such as "+12% on the period before", in green or red. |
| `hint`     | A line of text under the number, when there is no change to show.                                                            |
| `link`     | Where clicking the card goes. A relative link starts at the admin, so `"orders?status=PAID"` opens the filtered list.        |

### Chart

Bars or a line over rows of a label and a value. `kind` is `"bar"` or `"line"`. The chart is drawn as plain SVG on the server, so no chart library is loaded. Hovering a bar shows its value, and screen readers get the same numbers as a table.

Dates as labels are written short, such as "Sep 14".

### RecentRecords

The latest records of a view, each linking to its page. It reads through the view, so the view's `scope_query` applies and the card is hidden from users who may not open the view.

| Option   | What it does                                                             |
| -------- | ------------------------------------------------------------------------ |
| `sort`   | The order, such as `"-created_at"`. The view's own ordering if left out. |
| `detail` | A path shown at the right of each record, such as `"total"`.             |
| `limit`  | How many records. Five unless you say.                                   |

### ModelCounts

The record counts of every view the user may open, within its scope. It is the whole overview when you set no dashboard, and you can put it among your own cards.

## Cards of your own

Subclass `Widget`, give it a template from your `template_dirs`, and return what it needs from `load`. The template gets `widget` and `data`:

```
from adminsite import Widget


class Weather(Widget):
    title = "Weather at the warehouse"
    template = "cards/weather.html"
    width = 2

    async def load(self, admin, request):
        return await fetch_weather("Rotterdam")
```

```
<div class="card h-full border border-base-300">
  <div class="card-body p-4">
    <h2 class="text-sm font-medium text-base-content/70">{{ widget.title }}</h2>
    <p class="text-2xl">{{ data.temperature }}°</p>
  </div>
</div>
```

## Who sees what

Every card has `allows(admin, request)`. Override it to show a card only to some users:

```
class Margin(Stat):
    async def allows(self, admin, request):
        return request.state.user.is_manager
```

A card whose query fails shows "This card could not be loaded" and the error goes to the `adminsite` logger. The rest of the overview still loads.

# Pages and plugins

Not everything in an admin is a table. A sales report, a settings form or a button that clears a cache are pages of your own. They live next to the model views, in the same layout, behind the same sign in.

## A page of your own

```
from adminsite import AdminPage
from sqlalchemy import func, select


class SalesReport(AdminPage):
    label = "Sales report"
    group = "Reports"
    template = "reports/sales.html"

    async def get_context(self, request):
        async with self.admin.database.session() as session:
            total = await session.scalar(select(func.sum(Order.total)))
        return {"total": total}


admin = Admin(
    engine, views=[OrderView], pages=[SalesReport], template_dirs=["templates"]
)
```

The page is served at `/admin/-/sales_report`, named after the class, and shows up in the sidebar under its group and in the [command palette](https://nimaxin.github.io/adminsite/views/#the-command-palette). The template sits in one of your `template_dirs` and extends the admin's layout:

```
{% extends "adminsite/base.html" %}

{% block header %}<h1 class="text-base font-semibold">{{ page.label }}</h1>{% endblock %}

{% block content %}
  <div class="p-6">
    <div class="stat">
      <div class="stat-title">Sold so far</div>
      <div class="stat-value">{{ total }}</div>
    </div>
  </div>
{% endblock %}
```

The admin's styles are [daisyUI](https://daisyui.com) components, so a page can use the same cards, stats and tables as the rest of the admin. `page` is the page object; `urls`, `user` and `csrf_input` are there as on every page.

| Setting    | What it does                                                                           |
| ---------- | -------------------------------------------------------------------------------------- |
| `name`     | The URL, `/-/` and the name. Defaults to the class name in snake case, without `Page`. |
| `label`    | The sidebar text. Defaults to the name, spaced out.                                    |
| `group`    | The sidebar section. Pages share groups with views.                                    |
| `template` | The template to render.                                                                |

### Who may open it

```
class SalesReport(AdminPage):
    async def allows(self, request):
        return request.state.user.is_manager
```

A refused page is left out of the sidebar and answers with a 403.

### Forms

A page that takes a form overrides `post`. The form's token is already checked, so a form from another site never reaches it:

```
from starlette.responses import RedirectResponse

from adminsite.http.templating import add_message


class Settings(AdminPage):
    template = "settings.html"

    async def post(self, request, form):
        await save_settings(form)
        add_message(request, "Settings saved.")
        return RedirectResponse(request.url, status_code=303)
```

Put `{{ csrf_input | safe }}` inside the `<form method="post">` in the template.

To answer with something other than a template, such as a file or JSON, override `get` and return any Starlette response.

## Plugins

A plugin packages views, pages, routes, templates and static files so several projects can share them. It gets the admin once and adds what it brings:

```
from pathlib import Path

from adminsite import Plugin

HERE = Path(__file__).parent


class Reports(Plugin):
    name = "reports"

    def setup(self, admin):
        admin.add_template_dir(HERE / "templates")
        admin.add_static("reports", HERE / "static")
        admin.add_stylesheet("-/static/reports/reports.css")
        admin.add_page(SalesReport)
        admin.add_view(ReportScheduleView)
        admin.add_route("/-/reports/export.csv", export_sales)


admin = Admin(engine, plugins=[Reports()])
```

| Method                                                      | What it adds                                                                                                                                                                                     |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `add_view(view)`                                            | A model view.                                                                                                                                                                                    |
| `add_page(page)`                                            | A page of your own.                                                                                                                                                                              |
| `add_route(path, endpoint, methods=("GET",), guarded=True)` | Any endpoint, called as `endpoint(admin, request)`. The path starts with `/-/`, so it never meets a model's URL. `guarded=False` leaves it outside the sign in, for a health check or a webhook. |
| `add_template_dir(path)`                                    | A folder of templates, searched before the admin's own, so a plugin can also replace one of them.                                                                                                |
| `add_static(name, path)`                                    | A folder served at `/-/static/` and the name.                                                                                                                                                    |
| `add_stylesheet(href)`, `add_script(src)`                   | A stylesheet or script on every page. A relative path starts at the admin, a full URL is used as it is.                                                                                          |

The same methods work on the admin directly, without a plugin. Routes and static files have to be added before the admin answers its first request, since the routes are fixed from then on.

# JSON API

The admin can answer in JSON as well, for scripts, other services or a front end of your own. It reads and writes through the same views, so permissions, `scope_query`, hooks and the audit log all apply, exactly as they do on the pages.

```
admin = Admin(engine, views=[OrderView, CustomerView], api=True)
```

Everything lives under `/admin/-/api`.

| Request                           | What it does                                                 |
| --------------------------------- | ------------------------------------------------------------ |
| `GET /-/api`                      | The views this user may open, with their fields and actions. |
| `GET /-/api/orders`               | A page of orders.                                            |
| `POST /-/api/orders`              | Add an order. Answers 201 with the new record.               |
| `GET /-/api/orders/12`            | One order.                                                   |
| `PATCH /-/api/orders/12`          | Change the fields sent, and only those.                      |
| `DELETE /-/api/orders/12`         | Delete the order. Answers 204.                               |
| `POST /-/api/orders/actions/ship` | Run a bulk action.                                           |

## Reading

A page takes the same query as the list page: `q` to search, `sort` such as `-created_at`, the filters by name such as `status=SHIPPED`, `page`, and `limit` up to 500.

```
{
  "items": [
    {"key": "12", "id": 12, "customer": "3", "customer.name": "Aisha Khan",
     "status": "shipped", "total": "107.00", "created_at": "2026-09-01T10:30:00"}
  ],
  "total": 24,
  "estimated": false,
  "page": 1,
  "has_next": true,
  "next": null,
  "previous": null
}
```

A record carries the paths of `list_display`, then those of the form. Links come as the key of the linked record, links to many as a list of keys, decimals as strings so no cents are lost, dates and times in ISO format, and files as their name and address. With [keyset pagination](https://nimaxin.github.io/adminsite/views/#large-tables), `page` is null and `next` and `previous` are cursors to pass back as `after` and `before`.

## Writing

`POST` and `PATCH` take a JSON object of paths and values, checked by the form's fields. A `PATCH` touches only the fields it sends; a `POST` needs every required field. Problems come back per field, with status 422:

```
{"error": "Some fields need another look.",
 "errors": {"total": "Enter an amount, for example 12.50.", "colour": "This field cannot be written."}}
```

Only the form's fields can be written, read only fields never. Files are uploaded through the form. A hook that refuses, or a delete other records depend on, answers 409 with the reason.

## Actions

```
POST /admin/-/api/orders/actions/ship?status=PAID
Content-Type: application/json

{"keys": ["12", "13"], "inputs": {"carrier": "dhl"}}
```

Send `"everything": true` instead of keys to run the action over every record the query matches, as the "select all matching" link does on the list page. The answer is the action's message: `{"message": "2 orders marked as shipped."}`.

## Signing in

Without `auth` the API is as open as the admin. With `auth`, a request needs one of two things:

- **The session** of someone signed in to the admin, as a front end running in the same browser has. A request that changes something then has to send the form token in an `X-CSRF-Token` header, so another site cannot make the browser do it. The token is in the `_csrf` field of any admin form.
- **A token** in `Authorization: Bearer <token>`, for scripts and services. Nobody gets in this way until your auth provider says who a token belongs to:

```
class StaffAuth(AuthProvider):
    async def authenticate_token(self, token):
        async with Session() as session:
            key = await session.scalar(select(ApiKey).where(ApiKey.token == token))
            return key.user if key and key.active else None
```

A request without either gets a 401. Anything refused by a permission gets a 403 in JSON, never a page.

# Signing in

Without an auth provider the admin is open to anyone who can reach it. That is fine behind a VPN or on your own machine, and nowhere else.

## A fixed list of users

```
from adminsite.auth import PasswordAuth

admin = Admin(
    engine,
    views=[OrderView],
    auth=PasswordAuth({"nima": settings.admin_password_hash}),
    secret_key=settings.admin_secret_key,
)
```

`PasswordAuth` takes password hashes, never passwords, and refuses a plain one at startup. Make a hash once and keep the result in your settings:

```
python -c "from adminsite.auth import hash_password; print(hash_password('your password'))"
```

Hashes use PBKDF2 with SHA-256 and 600,000 rounds, from the standard library.

`secret_key` signs the session cookie. Keep it secret, make it long and random, and read it from your settings. Passing `auth` without one is refused at startup.

## Your own user table

For anything more than a handful of people, subclass `AuthProvider` and check your own users:

```
from sqlalchemy import select

from adminsite.auth import AuthProvider, SignInRefused, verify_password


class StaffAuth(AuthProvider):
    async def verify(self, username: str, password: str):
        async with session_factory() as session:
            user = await session.scalar(select(User).where(User.email == username))
        if user is None or not verify_password(password, user.password_hash):
            return None
        if not user.is_staff:
            raise SignInRefused("Not a member of staff.", user=user)
        return user

    def identity(self, user) -> str:
        return str(user.id)

    async def load_user(self, key: str):
        async with session_factory() as session:
            return await session.get(User, int(key))
```

| Method                                             | What it does                                                              |
| -------------------------------------------------- | ------------------------------------------------------------------------- |
| `verify(username, password)`                       | Returns the user for these details, or `None`, or raises `SignInRefused`. |
| `identity(user)`                                   | The short string kept in the session cookie.                              |
| `load_user(key)`                                   | Turns that string back into a user on each request.                       |
| `sign_in_failed(request, username)`                | Runs when a sign in fails, and returns what to say.                       |
| `may_read_sign_ins(request, reads_everything=...)` | Whether this person sees sign ins on the Activity page.                   |

`SignInRefused(reason, user=...)` refuses a sign in and says why. The reason goes to the [audit log](https://nimaxin.github.io/adminsite/audit/index.md), filed under that user, and the person signing in is told only what `sign_in_failed` returns. `PasswordAuth` gives "There is no such username." or "The password was wrong."

The loaded user is on `request.scope["user_record"]`, for your [permission](https://nimaxin.github.io/adminsite/permissions/index.md) checks. Its `str()` is what the sidebar and the audit log show, and `identity(user)` is the key the audit log files it under.

## When a sign in fails

The login page says "That username and password do not match." Override `sign_in_failed` to say something else, and to do something about it. With the [audit log](https://nimaxin.github.io/adminsite/audit/index.md) on, every attempt is already written down; `sign_in_failed` is where an alert or a wait belongs:

```
class StaffAuth(AuthProvider):
    async def sign_in_failed(self, request, username: str) -> str:
        await note_attempt(username, request.client.host)
        if await too_many_lately(request.client.host):
            return "Too many tries. Wait a minute and try again."
        return await super().sign_in_failed(request, username)
```

Keep the message vague. One that says the username exists tells whoever is guessing the same thing.

## CSRF

Every form the admin draws carries a token tied to the session, and every post is checked against it, including deletes and actions. A post without the right token is refused with a 403. Scripts that post to the admin can send the token in an `X-CSRF-Token` header instead of a form field.

The [JSON API](https://nimaxin.github.io/adminsite/api/index.md) also takes a bearer token, once your provider's `authenticate_token` says who it belongs to.

Signing in starts a fresh session, so a token taken from the login page stops working once the person is signed in. A script that drives the admin through a session takes its token from a page drawn after signing in.

Without a `secret_key` there is no session, and so no token. That does not leave the admin open to a form posted from another site: browsers say where a post came from, in the `Sec-Fetch-Site` and `Origin` headers, and a post from elsewhere is refused. A request that carries neither, from a script or `curl`, goes through, as it did before. This matters for an admin left open on a private network, where the browser of anyone on that network could otherwise be made to post to it.

## The session cookie

The cookie is signed with `secret_key` and lasts two weeks. Serve the admin over HTTPS and say so, and the cookie is never sent over plain HTTP:

```
admin = Admin(
    engine, auth=auth, secret_key=..., session_https_only=True, session_max_age=8 * 3600
)
```

`session_max_age=None` keeps the cookie for the browser session only.

# Databases

## Async or sync

Give the admin whichever you already have:

```
Admin(create_async_engine("postgresql+asyncpg://localhost/shop"))
Admin(create_engine("postgresql+psycopg://localhost/shop"))
Admin(async_sessionmaker(engine))
Admin(sessionmaker(engine))
```

Everything above the session is written once, so both behave the same. A sync session runs on a single worker thread for its whole life, which keeps SQLAlchemy from ever being used by two threads at once.

## Tested on

- SQLite, with `aiosqlite` and with the standard library driver
- Postgres, with `asyncpg` and with `psycopg`
- MySQL 8, with `aiomysql` and with `pymysql`

The whole test suite runs against each of these in CI.

## MySQL

Two things behave differently on MySQL, and adminsite accounts for both:

- A native `ENUM` column sorts in the order its values were declared but compares as text. Keyset pagination would skip rows on such a column, so a list sorted by an enum uses page numbers instead.
- `CountMode.ESTIMATED` reads `information_schema.tables`, whose row count for InnoDB is itself an estimate and can be off by a lot on a table that changes often. Below 10,000 rows the count is exact anyway.

If you write a [filter](https://nimaxin.github.io/adminsite/filters/index.md) of your own, note that MySQL refuses a `LIMIT` straight inside `IN (...)`; wrap the limited select in a subquery first.

## SQLite with a sync engine

A sync session runs on a worker thread, and SQLite refuses a connection that moves between threads unless told otherwise:

```
engine = create_engine("sqlite:///shop.db", connect_args={"check_same_thread": False})
```

Only one thread uses the connection at a time, so this is safe.

## Foreign keys

Postgres always enforces foreign keys. SQLite does not, unless you switch it on for each connection:

```
from sqlalchemy import event


@event.listens_for(engine, "connect")
def enforce_foreign_keys(connection, record):
    connection.execute("PRAGMA foreign_keys=ON")
```

With them on, deleting a record that others still point at is refused, and the admin shows "This customer cannot be deleted, because other records still refer to it." A value that must be unique is reported the same way.

Bulk deletes from an [action](https://nimaxin.github.io/adminsite/actions/index.md) are single statements and never load the records, so they rely on the database for cascades. Give child tables `ondelete="CASCADE"` where children should go with their parent:

```
order_id: Mapped[int] = mapped_column(ForeignKey("orders.id", ondelete="CASCADE"))
```

## After a rollback

When a save is refused or fails, SQLAlchemy expires the objects in the session, so reading an attribute afterwards goes back to the database. With an async session, that raises `MissingGreenlet`. In your own code around a failed save, read what you need first, or load the record again.

# Translations

The admin speaks English unless you choose another language. Persian ships with it, and the layout mirrors for languages written right to left.

```
admin = Admin(engine, views=[OrderView], language="fa")
```

Every page then has `<html lang="fa" dir="rtl">`: the sidebar moves to the right, tables and toolbars read from right to left, and the pager's "previous" sits on the right. Buttons, messages, form errors, refusals, filter shortcuts and the history all come in Persian.

## Letting people choose

Offer more than one language and a menu appears at the foot of the sidebar:

```
admin = Admin(engine, language="en", languages=["fa"])
```

The first visit follows the browser's `Accept-Language`, so someone whose browser prefers Persian gets Persian. A choice made in the menu is kept in a cookie for a year. `language` stays the default for anyone whose browser asks for neither.

## Your own words

Your views' labels, groups and field labels are yours, so write them in the language you want:

```
class OrderView(ModelView, model=Order):
    label = "سفارش"
    label_plural = "سفارش‌ها"
    fields = (ChoiceField("status", label="وضعیت", choices=STATUSES),)
```

To change one of adminsite's own texts, or to add a language adminsite does not ship, pass `translations`. The keys are the English texts:

```
admin = Admin(
    engine,
    language="de",
    translations={
        "de": {
            "Save": "Speichern",
            "Cancel": "Abbrechen",
            "Search {things}": "{things} suchen",
        },
        "fa": {"Save": "ثبت"},
    },
)
```

Your translations win over the ones adminsite ships, and a text with no translation stays in English rather than disappearing. Keep the `{placeholders}` as they are; only their place in the sentence may move.

In your own code, such as a hook's refusal or an action's message, use the same function:

```
from adminsite.i18n import gettext as _

raise RefusedError(_("Shipped orders cannot be changed."))
```

and add the text to `translations`.

## Adding a language to adminsite

The catalogs live in `src/adminsite/locales`, one JSON file per language. To list every text a catalog is missing:

```
uv run python -m tests.messages de
```

It prints a JSON object of the missing texts, ready to fill in. The test suite checks that the shipped catalogs translate every text and keep every placeholder.

# Accessibility

An admin is somebody's workplace for hours a day, so it has to work with a keyboard, a screen reader and a zoomed in screen. This is what adminsite does for that, and what to keep in mind when you add templates of your own.

## What the pages do

- **Keyboard.** Everything is a link, a button or a form control, reached with Tab in reading order. The first Tab shows a "Skip to the content" link. `Ctrl`+`K` opens the command palette; arrows move through it, Enter opens, Escape closes. Dialogs are native `<dialog>` elements, so focus stays inside them and Escape closes them.
- **Landmarks.** The sidebar is a named navigation, the page content is `<main>`, and the pager is a navigation of its own. The open page is marked with `aria-current="page"`.
- **Tables.** Every list has a caption naming what it lists. A sorted column says which way with `aria-sort`, and each row's checkbox is named after its record, such as "Select Order #12", rather than "Select this row" fifty times.
- **Forms.** Every input is named by its field's label, and an error or a help text is tied to it with `aria-describedby`; an input with an error carries `aria-invalid`. Inputs inside [inlines](https://nimaxin.github.io/adminsite/views/#related-records-in-the-same-form) are named by their column.
- **Messages.** "Saved" and similar news is announced politely and fades after six seconds. A problem is announced at once and stays until it is closed, so nobody misses it for reading slowly. After a search or a filter updates the list, the new count is announced.
- **Language and direction.** Every page states its language and direction, so a screen reader pronounces Persian as Persian. See [Translations](https://nimaxin.github.io/adminsite/translations/index.md).
- **Contrast.** Secondary text is dimmed no further than 60 percent of the text colour, which keeps it readable in both themes.

The test suite checks that every input, select, textarea and button on the main pages has an accessible name, and that the pieces above stay in place.

## In your own templates

When you write a [page](https://nimaxin.github.io/adminsite/pages/index.md) or a [card](https://nimaxin.github.io/adminsite/dashboard/index.md) of your own:

- Give every input a `<label for="...">` or an `aria-label`. A placeholder is not a label.
- Use `<button>` for things that do something and `<a href>` for things that go somewhere.
- Give icon-only buttons an `aria-label`.
- If a chart or picture carries information, write the same information as text, as the built in charts do with a table only screen readers see.
- Use `sr-only` for text that only screen readers need, and the `ms-`, `me-`, `ps-`, `pe-`, `start-` and `end-` classes rather than left and right, so the page also mirrors for right to left languages.

# Customizing the look

The interface is built on [daisyUI](https://daisyui.com) and Tailwind, rendered on the server with Jinja, with HTMX for partial updates and Alpine for the few pieces that keep state. The built CSS and JavaScript ship inside the package, so nothing needs Node to install or run.

## Overriding a template

Point the admin at a folder of your own. Any template found there is used instead of the one that ships:

```
admin = Admin(engine, views=[OrderView], template_dirs=["templates/admin"])
```

Keep the same relative path. To replace the sign in page, create `templates/admin/adminsite/login.html`.

| Template                                              | What it draws                                        |
| ----------------------------------------------------- | ---------------------------------------------------- |
| `adminsite/base.html`                                 | The shell: sidebar, header, messages                 |
| `adminsite/index.html`                                | The front page                                       |
| `adminsite/list.html`, `_toolbar.html`, `_table.html` | The list, its search and filters, and the table      |
| `adminsite/_saved_tabs.html`, `_row_actions.html`     | The saved views above a list, and a row's menu       |
| `adminsite/detail.html`, `_history.html`              | One record, and its history                          |
| `adminsite/form.html`, `_field.html`, `_inlines.html` | The create and edit form, and its child rows         |
| `adminsite/dashboard/*.html`                          | The overview's cards                                 |
| `adminsite/_icons.html`, `_values.html`               | The icons, and how a status or a yes and no is drawn |
| `adminsite/widgets/*.html`                            | One form control each                                |
| `adminsite/activity.html`                             | The activity page                                    |
| `adminsite/login.html`                                | Signing in                                           |

## A line above every page

`banner` puts one line of text above every page, the sign in page included. Use it to say which copy of the admin people are looking at:

```
admin = Admin(engine, banner="Staging: changes here are not real.")
```

The text is escaped. Give it as `Html(...)` to include a link.

## One widget

Each form control is its own small template under `adminsite/widgets/`, named after the field's `widget`: `input.html`, `textarea.html`, `checkbox.html`, `select.html`, `relation.html` and `readonly.html`. A field whose widget has no template of its own uses `input.html`.

To draw a widget your way, add a file with that name. To add a new one, give your field a new widget name and add the template:

```
class ColourField(StringField):
    widget = "colour"
```

```
{# templates/admin/adminsite/widgets/colour.html #}
<input type="color" class="input w-24" id="field-{{ row.path }}"
       name="{{ row.path }}" value="{{ row.value or '#3ecf8e' }}">
```

A widget template receives `row`, which has `path`, `value`, `field`, `choices`, `error` and `required`.

## Colours and theme

The stylesheet has two themes, a light one and a dark one, and follows the browser unless the user picks one with the button in the sidebar. To change the colours, edit the theme in `frontend/input.css` and rebuild:

```
cd frontend
npm install
npm run build
```

Beside daisyUI's own colours the themes set a few more, as CSS variables on the page: `--subtle` for the surface behind cards, `--line` and `--line-strong` for the lines between rows, `--muted` for text that steps back, `--link`, `--selected` for ticked rows, and `--chart` and `--chart-strong` for bars. A project's own stylesheet can set any of them.

A choice such as a status is drawn as a badge in one of six tones, `tone-0` to `tone-5`, set by the choice's place in the list: the first option is amber, the second blue, then green, grey, violet and rose. Reorder the choices to change which colour a status gets.

The typeface is Geist, which ships inside the package in the two subsets European languages need. Any other script, Persian among them, is drawn in the system's own font.

The build writes `src/adminsite/static/adminsite.css`. If your own templates use Tailwind or daisyUI classes the shipped stylesheet does not have, build your own stylesheet from the same input with your template folder added as a `@source`, and serve it in your overridden `base.html`.
# Reference

# Reference

The classes you use most, with their signatures and docstrings.

## The admin

## adminsite.Admin

```
Admin(
    source: Database | SessionSource,
    *,
    title: str = "Admin",
    banner: str = "",
    views: Sequence[ModelView | type[ModelView]] = (),
    inspector: SQLAlchemyInspector | None = None,
    fields: FieldRegistry | None = None,
    template_dirs: Sequence[str | Path] = (),
    auth: AuthProvider | None = None,
    secret_key: str = "",
    audit: AuditStore | bool = False,
    saved_views: SavedViews | bool = False,
    session_cookie: str | None = None,
    pages: Sequence[AdminPage | type[AdminPage]] = (),
    plugins: Sequence[Plugin] = (),
    dashboard: Sequence[Widget] | None = None,
    api: bool = False,
    session_https_only: bool = False,
    session_max_age: int | None = 14 * 24 * 3600,
    language: str = "en",
    languages: Sequence[str] = (),
    translations: Mapping[str, Mapping[str, str]]
    | None = None,
)
```

The admin itself: a small ASGI app you mount into your own.

```
admin = Admin(engine, title="Acme")
admin.add_view(OrderView)
app.mount("/admin", admin)
```

### add_view

```
add_view(view: ModelView | type[ModelView]) -> ModelView
```

Register a model with the admin.

### add_page

```
add_page(page: AdminPage | type[AdminPage]) -> AdminPage
```

Add a page of your own, served at /-/ and its name.

### use

```
use(plugin: Plugin) -> Plugin
```

Let a plugin add what it brings.

### add_route

```
add_route(
    path: str,
    endpoint: Endpoint,
    *,
    methods: Sequence[str] = ("GET",),
    name: str | None = None,
    guarded: bool = True,
) -> None
```

Answer one more path, called as `endpoint(admin, request)`.

The path has to start with /-/, which no model name can take, and the route sits behind the admin's sign in unless `guarded` is off.

### add_static

```
add_static(name: str, directory: str | Path) -> None
```

Serve a folder of files at /-/static/ and the name.

### add_template_dir

```
add_template_dir(directory: str | Path) -> None
```

Look for templates in one more folder, before the built in ones.

### add_stylesheet

```
add_stylesheet(href: str) -> None
```

Load a stylesheet on every page. A relative path starts at the admin.

### add_script

```
add_script(src: str) -> None
```

Load a script on every page. A relative path starts at the admin.

### render_template

```
render_template(
    name: str,
    request: Request,
    context: dict[str, Any] | None = None,
    status_code: int = 200,
) -> Response
```

Render a template of your own, found in the admin's template dirs.

## Views

## adminsite.ModelView

```
ModelView(
    inspector: SQLAlchemyInspector | None = None,
    registry: FieldRegistry | None = None,
)
```

How one model appears in the admin.

Set the class attributes to describe the list and the form. Override the `get_` methods when the answer depends on who is asking.

### get_list_display

```
get_list_display(request: Any = None) -> tuple[str, ...]
```

The columns the list shows.

### get_search_fields

```
get_search_fields(request: Any = None) -> tuple[str, ...]
```

The paths the search box looks in.

### get_filters

```
get_filters(request: Any = None) -> tuple[SQLFilter, ...]
```

The filters offered beside the list.

### get_ordering

```
get_ordering(request: Any = None) -> tuple[Sort, ...]
```

The order the list starts in.

### get_form_fields

```
get_form_fields(
    request: Any = None, record: Any = None
) -> tuple[str, ...]
```

The fields the form shows, in order.

### get_readonly_fields

```
get_readonly_fields(
    request: Any = None, record: Any = None
) -> tuple[str, ...]
```

The fields shown but not editable, named here or by themselves.

A primary key is readonly by its nature, but a form that names one means to set it, so a key stays editable unless it is named here.

### get_actions

```
get_actions(request: Any = None) -> tuple[Action, ...]
```

The actions this view offers, in the order they appear.

### get_inlines

```
get_inlines(
    request: Any = None, record: Any = None
) -> tuple[Inline, ...]
```

The child records edited inside the form.

### get_column_choices

```
get_column_choices(request: Any = None) -> tuple[str, ...]
```

The columns the picker offers: the list's own, then the extras.

### allows

```
allows(
    action: Permission | str,
    *,
    request: Any = None,
    record: Any = None,
) -> bool
```

Whether the current user may do this, to this record.

### scope_query

```
scope_query(
    statement: Select[Any], *, request: Any = None
) -> Select[Any]
```

Narrow every read to the rows this user may see.

This runs on the list, the count, a single record, an export and a bulk action, so a row can never leak through a path that forgot to check.

### before_save

```
before_save(context: SaveContext) -> None
```

Runs before the values are written.

Change `context.values`, or `context.set("slug", ...)`, to store something other than what was submitted. Raise `RefusedError` to refuse the save, naming a field to put the message beside it.

### after_save

```
after_save(context: SaveContext) -> None
```

Runs after the flush, while the transaction is still open.

### before_delete

```
before_delete(context: DeleteContext) -> None
```

Runs before a record is deleted. Raise to refuse the delete.

### after_delete

```
after_delete(context: DeleteContext) -> None
```

Runs after the delete, while the transaction is still open.

### title_of

```
title_of(record: Any) -> str
```

Name a record, for a heading or a link to it.

## adminsite.Inline

```
Inline(
    name: str,
    fields: Sequence[str] = (),
    readonly_fields: Sequence[str] = (),
    label: str = "",
    extra: int = 1,
    can_delete: bool = True,
    display_template: str = "",
)
```

Child records edited inside their parent's form, such as order lines.

```
class OrderView(ModelView, model=Order):
    inlines = (Inline("items", fields=("product", "quantity", "unit_price")),)
```

The name is a relationship on the parent that holds many records. Each child shows as a row of inputs, with a box to delete it, and new rows can be added in the form.

### input_name

```
input_name(index: int | str, path: str) -> str
```

The name a child's input carries in the submitted form.

## adminsite.CountMode

Bases: `StrEnum`

How hard to work to report how many records match.

## adminsite.Pagination

Bases: `StrEnum`

How the list moves from one page to the next.

## adminsite.views.writing.SaveContext

```
SaveContext(
    session: SessionAdapter,
    record: Any,
    values: dict[str, Any],
    created: bool,
    request: Any = None,
)
```

What a save hook is given. Everything here is inside one transaction.

In `before_save` the values have not been written onto the record yet, so that is where to change them: `context.values` is the dictionary that is about to be applied, and `set` writes into it. Setting an attribute on `context.record` there would be overwritten a moment later by the value from the form.

### set

```
set(path: str, value: Any) -> None
```

Change a value before it is stored.

## adminsite.views.writing.DeleteContext

```
DeleteContext(
    session: SessionAdapter,
    record: Any,
    request: Any = None,
)
```

What a delete hook is given, inside the same transaction.

## Actions

## adminsite.actions.action.action

```
action(
    label: str = "",
    *,
    name: str = "",
    confirm: str = "",
    permission: str = Permission.EDIT,
    dangerous: bool = False,
    inputs: Sequence[Field] = (),
    on: str = ON_SELECTION,
) -> Callable[[Handler], Handler]
```

Mark a method as an action.

```
@action(
    "Mark as shipped",
    confirm="Mark the chosen orders as shipped?",
    inputs=[ChoiceField("carrier", choices=CARRIERS, required=True)],
)
async def ship(self, selection: Selection, carrier: str) -> str:
    changed = await selection.update(status="shipped", carrier=carrier)
    return f"{changed} orders sent with {carrier}."
```

Each input is asked for in a dialog before the action runs, checked like a form field, and passed to the method by name.

`on` says what it acts on, and what the method is given:

- `"selection"`, the default: the rows the user ticked, as a `Selection`.
- `"record"`: one record, from its row in the list or from its page, as `(record, session)`.
- `"view"`: nothing in particular, as `(session)`. For work about the whole table, such as fetching from another system.

A method returns the message to show, or a response to send instead, such as a file to download.

## adminsite.actions.Selection

```
Selection(
    view: ModelView,
    session: SessionAdapter,
    spec: QuerySpec,
    keys: Sequence[str] = (),
    everything: bool = False,
    request: Any = None,
    changes: dict[str, dict[str, Change]] = dict(),
)
```

The rows an action runs over.

Either the rows that were ticked, or every row the current search and filters match. The second kind is never loaded into memory, so an action over a large table stays one statement.

### update

```
update(**values: Any) -> int
```

Change every row this covers, in one statement.

This does not run the save hooks, because it never loads the records. Use `records` when the hooks matter.

### delete

```
delete() -> int
```

Delete every row this covers, in one statement.

### count

```
count() -> int
```

How many rows this covers.

### records

```
records() -> list[Any]
```

Load the records, for work that needs each one in turn.

### statement

```
statement() -> Select[Any]
```

A statement selecting the primary keys this covers.

### covered_keys

```
covered_keys() -> list[str]
```

The keys of the records this covers, written as the URLs write them.

## Filters

## adminsite.backends.sqlalchemy.SQLFilter

```
SQLFilter(
    name: str,
    *,
    path: str | None = None,
    label: str | None = None,
)
```

Bases: `Filter`

A filter that narrows a SQLAlchemy statement.

Write a custom filter by subclassing this and returning a condition. Override `apply` instead when the filter needs to change the statement itself, for example to add a join.

### condition

```
condition(
    value: FilterValue, repository: SQLAlchemyRepository
) -> ColumnElement[bool] | None
```

The condition this filter adds, or nothing to leave the list be.

### apply

```
apply(
    statement: Select[Any],
    value: FilterValue,
    repository: SQLAlchemyRepository,
) -> Select[Any]
```

Narrow the statement with this filter's condition.

## adminsite.filters.FilterOption

```
FilterOption(
    value: str, label: str, count: int | None = None
)
```

One choice a filter offers, with how many records it would match.

## adminsite.filters.FilterValue

```
FilterValue(name: str, values: tuple[str, ...])
```

What the user picked for one filter.

### first

```
first: str
```

The first value, which is all a single choice filter uses.

## Fields

## adminsite.FieldOptions

```
FieldOptions(name: str, **changes: Any)
```

Changes to the field adminsite worked out for a path.

Put it in a view's `fields` where only a label, a line of help or a length changes and the field itself is already right:

```
class ProductView(ModelView, model=Product):
    fields = (
        FieldOptions("name", label="Product name"),
        FieldOptions("description", help_text="Shown on the shop page."),
    )
```

It takes whatever the field takes, so a link can be given a `display_template` without naming its target again.

## adminsite.Computed

```
Computed(
    name: str,
    getter: Callable[[Any], Any],
    *,
    needs: Sequence[str] = (),
    **options: Any,
)
```

Bases: `Field`

A value the view works out from a record, rather than a column.

```
class ProductView(ModelView, model=Product):
    list_display = ("name", "capacity")
    fields = (
        Computed(
            "capacity",
            lambda product: f"{len(product.slots)}/{product.limit}",
            label="Capacity",
            needs=("slots",),
        ),
    )
```

It shows in the list, on the record page and in the export, and is never written, sorted or filtered. `needs` names the paths the function reads, so they are loaded with the page instead of one query per row.

### text_for

```
text_for(record: Any, value: Any = None) -> str
```

Work the value out from the record, as text.

### display

```
display(value: Any) -> str
```

An empty value shows as nothing, anything else as text.

## adminsite.Html

Bases: `Markup`

Text written into the page as markup instead of being escaped.

A field that returns it can put a link, a badge or an icon in a cell:

```
Computed(
    "tracking",
    lambda order: Html('<a href="{}">Track</a>').format(order.tracking_url),
    needs=("tracking_url",),
)
```

Everything interpolated with `format` or `%` is escaped, so a value from the database cannot carry markup of its own into the page. Anything written straight into the string is not, so keep that to markup you wrote.

The CSV export and the JSON API send the text without the tags, since markup belongs on the page and not in a spreadsheet.

## adminsite.fields.JSONField

```
JSONField(
    name: str,
    *,
    label: str | None = None,
    required: bool = False,
    readonly: bool = False,
    help_text: str = "",
    max_length: int | None = None,
    default: Any = None,
    format: str | None = None,
    secret: bool | None = None,
)
```

Bases: `Field`

A JSON column: an object, a list, or any other JSON document.

Chosen for JSON columns by itself. The form edits the document in a box, pretty printed, and a malformed one comes back as an error on the field with the text still there.

### display

```
display(value: Any) -> str
```

The document on one line, cut short where a cell needs it.

### serialize

```
serialize(value: Any) -> str
```

The document laid out over several lines, for the box.

Text goes back as it was typed, so a document that failed to parse comes back to its writer exactly as they left it.

### to_python

```
to_python(text: str) -> Any
```

Read the text as a JSON document.

## adminsite.fields.FileField

```
FileField(
    name: str,
    *,
    storage: FileStorage,
    accept: str = "",
    max_size: int = 10 * MEGABYTE,
    **options: Any,
)
```

Bases: `Field`

An uploaded file, kept in a storage, its key kept in a string column.

```
FileField("invoice", storage=LocalStorage("uploads"), accept=".pdf")
```

### display

```
display(value: Any) -> str
```

The file's original name.

### content_type

```
content_type(key: str) -> str
```

The type of a stored file, guessed from its name.

### parse_upload

```
parse_upload(
    raw: Any, *, remove: bool, has_file: bool
) -> Any
```

Read a file input: a new file, None to remove, or UNCHANGED.

`has_file` says whether the record already holds a file, since a required field is satisfied by the one already stored.

### check

```
check(upload: UploadFile) -> None
```

Refuse a file that is too big or not of an accepted type.

### accepts

```
accepts(upload: UploadFile) -> bool
```

Whether the upload matches `accept`, as a browser reads it.

## adminsite.fields.ImageField

```
ImageField(
    name: str,
    *,
    storage: FileStorage,
    accept: str = "image/png,image/jpeg,image/gif,image/webp",
    max_size: int = 5 * MEGABYTE,
    **options: Any,
)
```

Bases: `FileField`

An uploaded picture, shown as a thumbnail in the list and the form.

Takes PNG, JPEG, GIF and WebP, checked by the file's first bytes, not just its name. SVG is left out on purpose: it can carry script.

### check

```
check(upload: UploadFile) -> None
```

Refuse anything that is not really one of the image types.

## adminsite.files.FileStorage

Where uploaded files go.

Subclass it to keep files somewhere else, such as S3: `save` returns the key kept in the column, and `response` answers a request for the file, for example with a redirect to a signed URL.

### save

```
save(upload: UploadFile) -> str
```

Store an upload and return the key to keep in the column.

### delete

```
delete(key: str) -> None
```

Remove a stored file. A missing file is not an error.

### url

```
url(key: str) -> str
```

A public address for the file, or nothing to serve it through the admin.

### response

```
response(key: str, content_type: str = '') -> Response
```

Answer a request for the file, made through the admin.

## adminsite.files.LocalStorage

```
LocalStorage(
    directory: str | Path, *, url_prefix: str = ""
)
```

Bases: `FileStorage`

Keeps files in a folder on this machine.

```
uploads = LocalStorage("uploads")
```

Files are served through the admin, behind its sign in, unless you give `url_prefix` for a place your application already serves them from. Each file gets a key such as `2026/09/k3j9x2-invoice.pdf`: the month, a random part so names never clash, and the original name.

### url

```
url(key: str) -> str
```

The public address, when the files are served elsewhere.

### path_for

```
path_for(key: str) -> Path
```

Where a key lives on disk, refusing any key that leaves the folder.

## Pages, plugins and the dashboard

## adminsite.AdminPage

```
AdminPage()
```

A page of your own inside the admin, such as a report or a settings form.

```
class SalesReport(AdminPage):
    label = "Sales report"
    group = "Reports"
    template = "reports/sales.html"

    async def get_context(self, request):
        async with self.admin.database.session() as session:
            total = await session.scalar(select(func.sum(Order.total)))
        return {"total": total}
```

The template lives in one of the admin's `template_dirs` and usually extends `adminsite/base.html`, so the page keeps the sidebar and header. It is served at `/-/sales_report` and listed in the sidebar and the command palette.

### allows

```
allows(request: Request) -> bool
```

Whether this user may open the page. Everyone may, unless you say.

### get_context

```
get_context(request: Request) -> dict[str, Any]
```

The values the template needs, on top of what every page has.

### get

```
get(request: Request) -> Response
```

Show the page. Override it to answer with anything else.

### post

```
post(request: Request, form: dict[str, Any]) -> Response
```

Handle a form posted to the page, already checked for its token.

## adminsite.Plugin

Something that adds to an admin, packaged so it can be shared.

A plugin gets the admin once, in `setup`, and adds what it brings with the same methods a project uses:

```
class Reports(Plugin):
    name = "reports"

    def setup(self, admin):
        admin.add_template_dir(Path(__file__).parent / "templates")
        admin.add_static("reports", Path(__file__).parent / "static")
        admin.add_stylesheet("-/static/reports/reports.css")
        admin.add_page(SalesReport)
        admin.add_route("/-/reports/export", export_sales)


admin = Admin(engine, plugins=[Reports()])
```

### setup

```
setup(admin: Admin) -> None
```

Add the plugin's views, pages, routes, templates and assets.

## adminsite.Widget

One card on the overview page.

Subclass it for a card of your own: set `template` to a template in your `template_dirs` and return what it needs from `load`. The template gets `widget` and `data`.

### allows

```
allows(admin: Admin, request: Request) -> bool
```

Whether this user sees the card. Everyone does, unless you say.

### load

```
load(admin: Admin, request: Request) -> Any
```

Read what the card shows.

## adminsite.Stat

```
Stat(
    title: str,
    value: Source,
    *,
    previous: Source | None = None,
    format: str = "{:,}",
    hint: str = "",
    link: str = "",
    width: int = 1,
)
```

Bases: `Widget`

A single number, such as revenue this month, with an optional change.

```
Stat(
    "Revenue this month",
    select(func.sum(Order.total)).where(Order.created_at >= month_start),
    previous=select(func.sum(Order.total)).where(...last month...),
    format="€{:,.2f}",
)
```

### load

```
load(admin: Admin, request: Request) -> StatData
```

Read the number, and the one it is compared with.

## adminsite.Chart

```
Chart(
    title: str,
    rows: Source,
    *,
    kind: str = "bar",
    format: str = "{:,}",
    width: int = 2,
)
```

Bases: `Widget`

Bars or a line over labelled values, drawn as plain SVG.

The source gives rows of a label and a value, such as orders per day:

```
day = func.date(Order.created_at)
Chart(
    "Orders per day",
    select(day, func.count()).group_by(day).order_by(day),
    kind="line",
)
```

### load

```
load(admin: Admin, request: Request) -> ChartData
```

Read the rows and place them on the canvas.

### tick_label

```
tick_label(value: float) -> str
```

A value on the axis, without cents where it is a whole number.

## adminsite.RecentRecords

```
RecentRecords(
    title: str,
    view: str,
    *,
    sort: str = "",
    detail: str = "",
    limit: int = 5,
    width: int = 2,
)
```

Bases: `Widget`

The latest records of a view, linking to each.

```
RecentRecords("Latest orders", "orders", sort="-created_at", detail="total")
```

It reads through the view, so the view's permissions and scope apply.

### allows

```
allows(admin: Admin, request: Request) -> bool
```

Shown to whoever may open the view.

### load

```
load(admin: Admin, request: Request) -> list[RecentItem]
```

Read the latest records through the view.

## adminsite.ModelCounts

Bases: `Widget`

How many records each view holds: the overview when nothing else is set.

### load

```
load(admin: Admin, request: Request) -> list[CountItem]
```

Count the records of every view this user may open, within its scope.

## Saved views

## adminsite.SavedViews

```
SavedViews(
    source: Database | SessionSource | str = DEFAULT_URL,
    *,
    create_table: bool | None = None,
)
```

Bases: `Store`

Where people keep the lists they come back to.

Like the audit log, the views go to a SQLite file of their own by default. Pass your engine to keep them in your database; the table is then `adminsite_saved_views` on `saved_view_metadata`.

### visible_to

```
visible_to(view: str, owner: str | None) -> list[SavedView]
```

A person's own views of a list, and the ones others shared.

### save

```
save(saved: SavedView) -> SavedView
```

Keep a view, and return it with its id.

### delete

```
delete(key: int, owner: str | None) -> bool
```

Remove a view, if it belongs to this person.

## Translations

## adminsite.i18n.gettext

```
gettext(text: str, **values: Any) -> str
```

Translate a piece of English text into the current language.

A project's own translations win over the built in ones, and text with no translation stays in English rather than disappearing.

## Signing in

## adminsite.auth.AuthProvider

Decides who may use the admin.

Subclass it and write `verify`. The session handling here is enough for most projects, and `load_user` is where you turn the key kept in the session back into whatever your application calls a user.

### verify

```
verify(username: str, password: str) -> Any | None
```

Return the user for these details, or nothing.

To have the audit log say why an attempt failed, raise `SignInRefused("This account is switched off.", user=account)` instead of returning nothing.

### load_user

```
load_user(key: str) -> Any | None
```

Turn the key kept in the session back into a user.

### authenticate_token

```
authenticate_token(token: str) -> Any | None
```

Return the user an API token belongs to, or nothing.

The JSON API calls this for `Authorization: Bearer <token>`. Nobody gets in this way until you write it, for example by looking the token up in a table of API keys.

### identity

```
identity(user: Any) -> str
```

The key to keep in the session for this user.

### current_user

```
current_user(request: Request) -> Any | None
```

Who is signed in, if anyone.

### sign_in

```
sign_in(
    request: Request, username: str, password: str
) -> Any | None
```

Check the details and remember the user.

### sign_in_failed

```
sign_in_failed(request: Request, username: str) -> str
```

Called when a sign in fails. Returns what to tell the person.

Override it to record the attempt, to make the next one wait, or to say something other than the default. Whatever it returns is shown above the form, so keep it vague: a message that says the username exists tells an attacker so too.

### may_read_sign_ins

```
may_read_sign_ins(
    request: Request, *, reads_everything: bool
) -> bool
```

Whether this person sees who signed in, on the Activity page.

Signing in belongs to no model, so no view's permissions decide it. By default only someone who may read the history of every model sees it, which `reads_everything` says. Override it to let in, say, an auditor who reads less.

### sign_out

```
sign_out(request: Request) -> None
```

Forget the user.

## adminsite.auth.PasswordAuth

```
PasswordAuth(users: Mapping[str, str])
```

Bases: `AuthProvider`

Signs in against a fixed set of usernames and password hashes.

```
from adminsite.auth import PasswordAuth, hash_password

PasswordAuth({"nima": hash_password("letmein")})
```

Passwords have to be hashed with `hash_password`, so a plain one never ends up in your settings or your repository. This suits a small internal tool. Anything larger should subclass `AuthProvider` and check its own user table.

### verify

```
verify(username: str, password: str) -> Any | None
```

Check the password against the stored hash.

## adminsite.auth.hash_password

```
hash_password(
    password: str, *, iterations: int = ITERATIONS
) -> str
```

Hash a password for storing.

```
from adminsite.auth import hash_password

hash_password("letmein")
```

Keep the result, not the password. The format is `pbkdf2_sha256$iterations$salt$hash`.

## Audit log

## adminsite.audit.AuditLog

```
AuditLog(
    source: Database | SessionSource | str = DEFAULT_URL,
    *,
    create_table: bool | None = None,
)
```

Bases: `Store`

Where the admin writes down who changed what.

By default the entries go to a SQLite file of their own, which needs no setup. Pass your engine to keep them in your own database instead; the table is then `adminsite_audit_log` on `audit_metadata`, which you add to your migrations.

Entries are written after the change they describe has committed, so a change that was rolled back never shows up in the history.

### find

```
find(query: AuditQuery, *, limit: int) -> list[AuditEntry]
```

The entries that match, newest first, at most `limit` of them.

### history

```
history(
    view: str, record_key: str, *, limit: int = 100
) -> list[AuditEntry]
```

What happened to one record, newest first.

### recent

```
recent(
    *,
    view: str | None = None,
    views: Sequence[str] | None = None,
    limit: int = 100,
) -> list[AuditEntry]
```

The latest entries, across the admin, for some views or for one.

### record

```
record(entries: Sequence[AuditEntry]) -> None
```

Write entries down, a batch at a time.

## adminsite.audit.AuditStore

Bases: `Protocol`

Where the audit log is written and read back.

`AuditLog` is the one that ships. Write your own to keep the log in a table of your application, or to send it on elsewhere; the History tab and the Activity page read it through `find` either way.

### record

```
record(entries: Sequence[AuditEntry]) -> None
```

Keep these entries.

### find

```
find(query: AuditQuery, *, limit: int) -> list[AuditEntry]
```

The entries that match, newest first, at most `limit` of them.

Newest first means by `occurred_at`, then by `id`, both descending, which is also the order `older_than` pages through.

## adminsite.audit.AuditQuery

```
AuditQuery(
    views: Sequence[str] | None = None,
    view: str | None = None,
    record_key: str | None = None,
    user: str | None = None,
    events: Sequence[AuditEvent] = (),
    since: datetime | None = None,
    until: datetime | None = None,
    older_than: tuple[datetime, int] | None = None,
)
```

Which entries to find. Every field narrows the result; empty means all.

- `views`: only entries of these views, such as the ones a person may read. An empty string among them stands for entries of no view, such as signing in.
- `view` and `record_key`: one view, or one record of it.
- `user`: one person, matched against `user_key` and against `user`.
- `events`: only these kinds of entry.
- `since` and `until`: from `since`, up to but not including `until`.
- `older_than`: the `(occurred_at, id)` of the last entry already shown, to find the next page after it.

## adminsite.audit.AuditEntry

```
AuditEntry(
    view: str,
    record_key: str,
    event: AuditEvent,
    changes: Mapping[str, Change] = dict(),
    record_title: str | None = None,
    action: str | None = None,
    batch: str | None = None,
    user: str | None = None,
    message: str | None = None,
    occurred_at: datetime = (
        lambda: datetime.now(UTC).replace(tzinfo=None)
    )(),
    id: int | None = None,
    user_key: str | None = None,
    ip: str | None = None,
    user_agent: str | None = None,
    error: str | None = None,
    inputs: Mapping[str, Any] = dict(),
)
```

One thing that happened in the admin, who did it, and from where.

`user` is the name the admin shows for the person, and `user_key` what `AuthProvider.identity` returns for them, which does not change when the name does. `ip` and `user_agent` say where the request came from. `error` holds why something failed; it is empty when it worked. `inputs` holds the values an action was run with, secrets masked.

### succeeded

```
succeeded: bool
```

Whether what the entry describes worked.

### as_row

```
as_row() -> dict[str, Any]
```

The entry as a row for the audit table.

### from_row

```
from_row(row: Mapping[Any, Any]) -> AuditEntry
```

Read an entry back from a row of the audit table.

## Errors

## adminsite.RefusedError

```
RefusedError(message: str, *, field: str = '')
```

Bases: `AdminSiteError`

Raise this from a hook to refuse a save or a delete.

The message is shown to the user on the form or above the list, and the transaction is rolled back. Any other exception is a fault, and is reported as one.

Name a field and the message appears next to that input instead of above the form:

```
raise RefusedError("Keep this above the check delay.", field="delay")
```

## adminsite.PermissionDeniedError

```
PermissionDeniedError(action: str, subject: str = '')
```

Bases: `AdminSiteError`

Raised when the current user may not do this.

## adminsite.RecordNotFoundError

```
RecordNotFoundError(model: type[object], key: object)
```

Bases: `AdminSiteError`

Raised when a key does not match any record.

# Changelog

## 0.1.0a6

A new look, and an audit log that answers what gets asked of it afterwards. The admin is redesigned throughout and fits a phone. The audit log now records sign ins, every action and export, and what failed, names each person by a key that lasts and the address they came from, pages and filters, and can live in a table of your own.

Before upgrading:

- The audit table gains the columns `user_key`, `ip`, `user_agent`, `error` and `inputs`, all of which may be empty. A table adminsite created adds them by itself; for one in your own migrations, generate a migration.
- `PasswordAuth.verify` raises `SignInRefused` for an unknown username or a wrong password, where it returned `None`.
- A record's History tab shows its latest twenty entries, and the Activity page the rest.

What changed:

- A new look. The admin sits on a quiet ground with each page on a raised panel, set in Geist, which now ships inside the package with no request to any other site. The sidebar gets icons, search at the top, and an active page you can read in light mode as well as dark. Colours come from two daisyUI themes, so a project can still restyle the admin with its own.
- The list reads better. Saved views are tabs above it instead of a menu. Each filter is a chip that opens a small form of its own, and a range is typed into two fields, or picked from presets, instead of one box that wanted `from,to`. A choice such as a status is a coloured badge, in a tone that follows its place among the choices so it never changes between pages. A row's actions and its form sit in one menu at its end, ticked rows raise a bar of actions over the table, and the pager numbers its pages.
- A record's page has a title with its status beside it, its actions as buttons and delete in a menu, its details in two columns, and the records it links to one by one as cards beside them, opening the linked record's own page. The history's latest entries sit there too.
- The form lists every problem at the top, each a link to its field, as well as beside the field, so a mistake at the bottom of a long form is never missed. Fields sit two to a row where they are short, a value that cannot be changed reads as text instead of a greyed out box, and an inline row is removed with a bin button instead of a red box. `Inline.extra` blank rows now appear only while a table has no rows, so editing a record no longer shows an empty line under its children.
- The overview's cards share the new look. A chart gets lines across it at round numbers, an axis that says what they are, its tallest bar picked out, and each bar's value on hover. A day that SQLite hands back as text reads as "Sep 14" like any other date. The latest records card links to the whole list.
- On a phone the list becomes a column of cards, each with its first column and badge on top and the rest below, its amount at the end. A page's secondary actions fold into one menu so the header keeps to one line, the form's title gets the whole line, and the overview's cards sit two to a row.
- Every field takes `format`, such as `format="€{:,.2f}"`, for how its value is written in the list, on the record page, in the export and on the overview. The form keeps the plain number. The sign in page, error pages, the activity page, imports and action dialogs share the new look.
- A checkbox's tick appears at once. daisyUI drew it over 0.4 seconds, which dragged when ticking a column of rows.
- `Admin(banner=...)` shows one line above every page and on the sign in page, such as "Staging: changes here are not real."
- In a short window the overview and the forms no longer make the whole page scroll. The chart's numbers for screen readers were hidden from sight but kept their full height, and text kept for screen readers low in a long form was placed against the page instead of the panel.
- Every audit entry says who acted by the key `AuthProvider.identity` returns, as `user_key`, as well as by the name shown, which it had already. It also keeps the IP address and the browser, and the History tab shows the address. The audit table gains the columns `user_key`, `ip`, `user_agent`, `error` and `inputs`, all of which may be empty. A table adminsite created adds them by itself; for one in your own migrations, generate a migration after upgrading.
- The audit log can live anywhere. The admin writes and reads it through `AuditStore`, two methods: `record` and `find`, which takes an `AuditQuery` with filters and a place to page from. A store of your own can keep the log in a table your application already has, and the History tab and the Activity page show its rows. `AuditLog` gains `find`; `history` and `recent` stay.
- The audit log keeps every sign in, failed attempt and sign out, with the address and browser. `verify` can raise `SignInRefused(reason, user=...)` to say why an attempt failed; the reason goes to the log, never to the person. `PasswordAuth.verify` now raises it, saying whether the username was unknown or the password wrong, where it returned `None` before. The Activity page shows these entries to people who may read every model's history, and `AuthProvider.may_read_sign_ins` changes who.
- Every action is audited: on one record, with the fields it changed; on the whole model, which wrote nothing before; and one that answers with a file, which returned before it was written down. Each entry keeps the values the action was run with, with secrets as `***` and files by name, type and size. A field's new `secret` option decides what is a secret, where a name such as `password` or `api_key` does not. An action that is refused, not allowed or fails is written down as failed with its reason, after its work is rolled back. Downloading a list as CSV is written down with its search and filters.
- The Activity page pages through the whole log, fifty entries at a time, where it stopped at the latest 200. It filters by kind of entry, person, days and record as well as by model, and keeps the filters in its address. A record's History tab shows the latest twenty, where it showed a hundred, and links to the rest on the Activity page.

## 0.1.0a5

A security release. A review of every route found ways to read or link records outside a view's scope, to sort by columns the view hides, to post to an admin without a secret key from another site, and to tell usernames apart by how long a sign in took. All are closed. Anyone on 0.1.0a4 or earlier should upgrade.

- **Security.** A link could be set to a record its own view would not show. The form's picker offered only records within the target view's scope, but the key that came back was loaded by itself, so a user scoped to one region could attach an order to a customer of another, and learn from the answer whether a key existed. A key is now resolved through the target's own view, on the form, in inline rows and in the API, and a key it will not give up is refused like any other bad choice, with nothing said about whether the record exists.
- **Security.** `?sort=` took any column, including one left out with `exclude` and columns of a linked model, which put the rows in the order of a value the user could not see. A sort asked for in the URL now has to name a column the user can read somewhere on the view.
- **Security.** An admin without a `secret_key` has no session, and so had no form token, which left it open to a form posted from another site through the browser of anyone on the same network. Without a session, a post is now refused when the browser says it came from elsewhere, through `Sec-Fetch-Site` and `Origin`. A request that says nothing, from a script, goes through as before.
- `PasswordAuth` answered an unknown username at once and a known one after 600,000 rounds of hashing, so the time a sign in took said which usernames exist. An unknown name now costs the same as a wrong password, and the hashing runs on a thread instead of holding up every other request.
- Signing in starts a fresh session, so nothing planted in the browser before it, the form token included, is worth anything afterwards. Signing out ends the whole session. A script that takes the token from the login page has to take it from a page drawn after signing in instead.
- An action that `get_actions` leaves out for this user can no longer be run by name; asking for it is a 404, as is asking for an action that does not exist at all, which used to be a crash.
- The CSV export marks a cell that a spreadsheet would run as a formula, one starting with `=`, `+`, `@` or a tab, as text with a leading apostrophe. Numbers are left alone.
- The buttons of a record action were broken markup, since the record's key was written into a double quoted attribute in double quotes. They are drawn in single quotes now.
- A `before_save` that refused a change to an existing record crashed on an async engine, because the form was drawn again from a record the rollback had expired. The record is loaded again first.
- A bulk action on a table whose key is two columns acted on the wrong rows: the rows were matched by the first column of the key alone, so relabelling one line of an order relabelled every line of it, and deleting one deleted them all. Rows are matched by the whole key now, and the log names the whole key.
- A path in the URL that names no field, in the lookup or the file route, is a 404 instead of a crash. The JSON API writes a `ChoiceField(multiple=True)` from a list. A kept import file is readable by the server's own user alone.
- **Security.** A relation picker read the other model's table directly, so it ignored that model's view: it offered records outside `scope_query`, offered them to users whose permissions denied the view entirely, and searched every text column rather than the ones on show. A picker now reads through the target's own view, and its lookup needs the permission that opens a form. Anyone running 0.1.0a4 or earlier with a `scope_query` or a denied view should upgrade.
- A picker's search looks in the target view's `search_fields`, and where it names none, in the text columns its records are named by. A target with neither cannot be narrowed by typing.

## 0.1.0a4

The fourth alpha. It closes the gaps the first ports of real panels ran into: actions on one record and on the view, computed fields, JSON columns, markup in a cell, lighter field overrides, a relation picker that holds many records, and settings for the pages a view does not need. Tested on SQLite, Postgres and MySQL.

- `AuthProvider.sign_in_failed(request, username)` runs on every wrong password and returns what the login page says, so an attempt can be recorded, alerted on or slowed down, and the message is no longer fixed.
- Action inputs can start with a value, `default=True`, hold several options, `ChoiceField(multiple=True)`, and be worked out per request, since the run now goes through `get_actions` too. `default` works on any field, so a form for a new record starts from it.
- `deferred_fields` leaves heavy columns out of the list query, so a table carrying a large JSON payload no longer loads it on every row. The record page, the form and the API load them as usual, and a column the list shows is never left out.
- A cell can hold markup. A field that returns `Html` writes it into the page as it is, so a column can link to a related record, a file or another system. Values put in with `format` are escaped, and the CSV export and the JSON API send the text without the tags.
- The CSV export was missing computed columns. It wrote the columns the query loaded rather than the columns the list shows, and a computed column loads nothing of its own.
- `FieldOptions("name", label="Product name")` in a view's `fields` changes one thing about the field adminsite worked out, without naming its type or its target again. An option the field does not take is an error naming the path, not a setting that does nothing.
- A field that says `readonly=True` is now treated as readonly by the form, the API and the import, as `readonly_fields` already was. A primary key is the exception: a form that names one means to set it.
- A relationship holding many records can be edited on a large table. Above 100 records the picker became a search box that kept one key, which lost every other record the link held. It now keeps all of them, showing each as a chip with a button to take it off.
- `can_export = False` switches the CSV export off for a view, and the button now follows `Permission.EXPORT` instead of always showing. `can_detail = False` switches off the record page: rows open the form instead, and saving lands on the list.
- `page_sizes` offers a rows per page menu above the list. The choice is kept in the URL and the session, stays while paging, sorting, searching and filtering, and only a size the view offers counts.
- `before_save` can change what is stored: whatever it leaves in `context.values`, or writes with `context.set(path, value)`, is what is applied, so a slug or a derived value is stored instead of what was submitted. The caller's own values are left alone.
- `RefusedError("...", field="delay")` puts a refusal next to that input instead of above the form, keeping everything else that was typed. The API answers 422 with the field, and 409 for a refusal about no field in particular.
- JSON columns get a `JSONField`: readable on one line in the list, laid out in a box on the form, and a malformed document comes back as an error on the field instead of being stored as text.
- A value that fails to parse comes back into its input as it was written. Before, the field fell back to the stored value and quietly threw away what the person had typed.
- Actions can run on one record, `on="record"`, appearing on its row and on its page with the record's own permission deciding, or on the whole view, `on="view"`, with nothing ticked. Both keep the dialog, inputs, confirmation, messages and audit that selection actions have.
- An action can return a response instead of a message, so it can hand back a file or JSON.
- `Computed` shows a value the view works out from a record, in the list, on the record page and in the export. `needs` names what the function reads so it is loaded with the page, and the value is never written, sorted or filtered.
- `Field.text_for(record, value)` gives a field the record its value belongs to, so an amount can read with its currency or a status with the column beside it. Everything that shows a value goes through it, and it falls back to `display`.
- `detail_fields`, and `get_detail_fields(request, record)`, say what the record page shows when that differs from the form. The page follows the form unless you name them.
- A view's `icon` is drawn in the sidebar. It takes inline SVG markup or the address of a picture.
- A filter on a path through a relationship shows its options without counts instead of raising.
- `session_https_only` and `session_max_age` on `Admin` for the session cookie.

## 0.1.0a3

The third alpha. It adds everything the first projects asked for: inlines, big-table paging, saved views, a command palette, pages and plugins, a dashboard, file fields, CSV and Excel import, a JSON API, Persian and right to left layouts, and an accessibility pass. Tested on SQLite, Postgres and MySQL.

- Tested on MySQL 8 with aiomysql and pymysql, and CI runs the suite against MySQL. Keyset pagination falls back to page numbers when a list is sorted by an enum column, since MySQL sorts and compares native ENUMs differently and the next page would skip rows.
- Inlines: edit a record's children in its own form, such as an order's lines, with `inlines = (Inline("items"),)`. Rows can be added, changed and removed, all saved in one transaction with the parent, and the detail page lists them.
- Keyset pagination for big tables: `pagination = Pagination.KEYSET` moves by cursor, so deep pages cost the same as the first. Sorts it cannot use fall back to page numbers.
- `CountMode.ESTIMATED` shows the table estimate Postgres and MySQL keep, and stops a narrowed count at 10,000.
- The primary key breaks ties in every sort, so rows no longer repeat across pages when a sorted column has equal values.
- Changing the search, a filter or the sort goes back to the first page.
- Accessibility: a skip link, named landmarks and `aria-current` in the sidebar; captioned tables with `aria-sort`; row checkboxes named after their record; inputs named by their label and tied to their error or help; problems that stay until closed; the new count announced after the list updates; stronger contrast for dimmed text. A test checks every control has a name.
- Translations: `language="fa"` puts the whole admin in Persian with a mirrored right to left layout, and `languages=[...]` adds a menu, picking the browser's language on the first visit. Your own `translations` override or add to the shipped catalogs, and `adminsite.i18n.gettext` translates your own messages.
- JSON API: `api=True` serves every view at `/-/api` for listing, reading, adding, changing, deleting and running actions, through the same permissions, scopes, hooks and audit log as the pages. Scripts sign in with a bearer token checked by `AuthProvider.authenticate_token`; a browser session has to send the form token in `X-CSRF-Token` to change anything.
- Importing from CSV or Excel with a preview: switch it on with `can_import = True`. Rows with a known key change that record, rows without one add a record, and every row is checked by the form's fields before anything is written. The good rows are saved through the view, so hooks, permissions and the audit log apply. Excel needs `adminsite[excel]`.
- Two messages in a row are both shown. The second used to be lost, since the session was only saved when a key was set, not when its list grew.
- File and picture fields: `FileField` and `ImageField` store uploads through a `FileStorage`, `LocalStorage` built in. Files are served behind the sign in, with anything but pictures and PDFs sent as a download; pictures are checked by their bytes. Replaced files are deleted after the commit, and a failed save throws its new file away.
- Every endpoint closes the request's form when it is done, so uploads never leave temporary files open.
- Dashboard: the overview takes cards with `dashboard=[...]`: `Stat` with an optional change on the period before, `Chart` drawn as SVG on the server, `RecentRecords` through a view's permissions, `ModelCounts`, or a `Widget` of your own. A failing card is shown as failed and logged instead of breaking the page.
- Pages of your own: subclass `AdminPage` with a template and a context, and it gets the admin's layout, a place in the sidebar and the palette, its own permission check and form handling.
- Plugins: a `Plugin` adds views, pages, routes under `/-/`, template folders, static files, stylesheets and scripts. The same `add_*` methods work on the admin directly.
- Command palette: Ctrl+K or Cmd+K jumps to any page, or to a record found by each view's own search, within the user's permissions and scope. `global_search = False` leaves a view out.
- `Permission.HISTORY` controls the History tab and a view's entries on the Activity page. The Activity page shows only views this admin registers and the user may read, filtered in the query so the latest readable entries always show.
- A refused page is a 403 "Not allowed" page inside the admin instead of a server error, and missing pages get the same layout. The sidebar leaves out views the user may not open.
- Column picker: people hide and show columns from a Columns menu, offered from `list_display` and `list_columns`. The choice is kept in the URL and the session, and the export follows it.
- Saved views: `saved_views=True` lets people keep a search, filters, sort and columns under a name, for themselves or shared with everyone. Stored in `adminsite_views.db` by default, or in your database with `SavedViews(engine)`.
- Several admins in one app keep separate sessions by default: the session cookie is named after the admin's title unless you set `session_cookie`.
- Action and delete buttons are hidden from users that `allows()` refuses.

## 0.1.0a2

The second alpha. If you use Postgres, upgrade: 0.1.0a1 could not open records there.

- Audit log. `audit=True` records who created, changed or deleted what, with each field's value before and after, in a SQLite file of its own; pass an `AuditLog(engine)` to keep it in your own database. Records get a History tab and the admin gets an Activity page. Bulk actions write one entry per affected record, grouped by a batch id, the way Laravel Nova does. Entries are written only after the change commits.
- Actions can ask for values in a dialog before they run, checked like form fields and passed to the method by name. Confirmations and deleting a record use a dialog instead of the browser's confirm box.
- The UI is rebuilt on daisyUI, with light and dark themes, a drawer sidebar on phones, and one template per form widget.
- A foreign key column shows as its relationship in the default list and form.
- Tested on Postgres with asyncpg and psycopg, and CI runs the suite against Postgres.
- Keys read from URLs and filters are converted to the column type. Postgres refused to compare an integer key with text, which broke the detail, edit and delete pages there.
- Deleting a record that others still refer to, or saving a value that must be unique, now shows a message instead of an error page.

## 0.1.0a1

The first alpha. The shape of the API may still change before 0.1.0.

- Read a model and describe it without any ORM detail, so another ORM can be supported later.
- Fields that display, edit and convert values, chosen from the column types.
- One async interface over async and sync SQLAlchemy sessions.
- List pages with search across dotted paths, filters with counts, sorting and paging, and no N+1 queries.
- Filters you can write yourself.
- Create, edit, detail and delete pages, with links picked from a list or searched.
- Permissions at view, action, field and row level.
- Hooks that run inside the transaction and can refuse a save.
- Bulk actions over the chosen rows or over every row matching the filter.
- CSV export of the filtered list.
- Signing in, and a CSRF token on every form.

`PasswordAuth` takes hashed passwords. Use `adminsite.auth.hash_password` to make one.