pre-alpha

Reference

Admin API

Updated November 20, 2026 10 min read

hinoki.admin.Admin

Admin(
    *,
    access: Access | None = None,
    users: AdminAccounts | None = None,
    manage_users: bool = True,
    secret: str | bytes | None = None,
    prefix: str | None = None,
    theme: str | Theme = "studio",
    templates: str | None = None,
    site: str = "Admin",
    per_page: int = 20,
    show_count: bool = False,
    tagline: str = "",
    workspace: str = "Workspace",
    links: tuple[Link, ...] = (),
    logout_url: str = "",
    role: Callable[[Caller[Any]], str] | None = None,
    activity: Callable[
        [Caller[Any]], Awaitable[list[Event]]
    ]
    | None = None,
    dashboard: tuple[str, ...] = (),
    secure_cookies: bool | None = None,
)

The admin site: prefix, access policy, theme and registered models.

users instance-attribute

users = users

access instance-attribute

access: Access = access or Access(
    auth=AdminSessionAuth(self),
    permissions=[BASE_PERMISSION],
)

secure_cookies instance-attribute

secure_cookies = secure_cookies

per_page instance-attribute

per_page = per_page

show_count instance-attribute

show_count = show_count

mount instance-attribute

mount = ''

site instance-attribute

site = site

tagline instance-attribute

tagline = tagline

workspace instance-attribute

workspace = workspace
links = links

logout_url instance-attribute

logout_url = logout_url

role instance-attribute

role = role or default_role

activity instance-attribute

activity = activity

dashboard instance-attribute

dashboard = dashboard

timezone instance-attribute

timezone: tzinfo = UTC

templates instance-attribute

templates = Templates(templates, theme)

theme instance-attribute

theme = self.templates.theme

parts instance-attribute

parts = Components(self.templates)

models instance-attribute

models: dict[str, ModelAdmin[Any]] = {}

manage_users instance-attribute

manage_users = manage_users

digests instance-attribute

digests = {
    "admin.css": digest(self.templates.stylesheet()),
    "admin.js": digest(self.templates.script()),
}
session_cookie: str

csrf property

csrf: Csrf

accounts property

accounts: AdminAccounts

prefix property

prefix: str

Where the admin lives under its Mount: nothing when the admin is mounted and names no prefix, /admin when it is included as it is.

base property

base: str

The path the admin is reachable at: its own prefix under any Mount.

cookie_name

cookie_name(name: str) -> str

__Secure- before the name when the admin is told its cookies are always secure (secure_cookies=True): a browser then refuses to set it over plain HTTP, so a sibling site cannot plant it.

bind_settings

bind_settings(settings: AdminSettings | None) -> None

Use the app's admin settings: the secret (unless the admin was given its own) and the session and password rules of its own users.

bind_timezone

bind_timezone(timezone: tzinfo) -> None

Use the including app's timezone; reject conflicting app bindings.

register

register(target: A, /, *, slug: str | None = None) -> A
register(
    target: type[M],
    admin: type[ModelAdmin[M]] | None = None,
    *,
    slug: str | None = None,
) -> type[M]
register(
    target: Any,
    admin: Any = None,
    *,
    slug: str | None = None,
) -> Any

Add a model to the admin and return target, so it also decorates.

site = Admin(access=editors, secret=secret)

@site.register
class PostAdmin(ModelAdmin, model=Post): ...   # a customised admin

site.register(User)                            # the default admin

register(Post, PostAdmin, slug="posts") is the older two-argument form.

refuse_own_tables

refuse_own_tables(
    model: type[Model], admin: object
) -> None

The admin's own account tables are managed by the Users section only: a plain model admin would show the password hash and let a grant holder edit who is a superuser.

admin

admin(
    model: type[Model], *, slug: str | None = None
) -> Callable[[A], A]

Decorate a ModelAdmin class that does not name its model:

@site.admin(Post)
class PostAdmin(ModelAdmin):
    columns = ("title", "published")

The class may also say model=Post itself; naming two different models is a RegistrationError.

attach

attach(
    model: type[M],
    admin: type[ModelAdmin[M]] | None,
    slug: str | None,
) -> None

holds_no_connection

holds_no_connection(name: str) -> bool

Routes that may hash a password take no route-wide transaction, so no connection waits on Argon2; their writes open their own, short one.

api

api() -> type[API]

The API class to include in the application.

add_user_admin

add_user_admin() -> None

Register the Users section last, after the application's own models.

check_dashboard

check_dashboard() -> None

route_options

route_options(name: str, write: bool) -> Options

The options of one admin view: public views name no access policy, and the views that hash a password take the sign-in rate limit.

bind_mount

bind_mount(mount: str) -> None

Called by Hinoki.include with the prefix of the Mount around the admin, so generated links, assets and the CSRF cookie path match the routes.

hinoki.admin.ModelAdmin

ModelAdmin()

How one model appears in the admin. Subclass and override what you need.

  • queryset scopes every list, lookup, update and delete (it is part of the SQL statement); can gates view, add, change and delete for a model or a row. Row visibility belongs in queryset.
  • save and remove are the single places that write, so an application can run a domain command there instead of writing around its rules. assign columns are set by the server on creation and are not form fields; readonly columns are shown but never accepted; exclude columns are neither shown nor accepted.
  • After a default write the row must still be inside queryset; otherwise the write is rolled back.

model instance-attribute

model: type[M]

slug class-attribute

slug: str = ''

label class-attribute

label: str = ''

icon class-attribute

icon: str = 'file-text'

columns class-attribute

columns: tuple[str, ...] = ()

search class-attribute

search: tuple[str, ...] = ()

ordering class-attribute

ordering: tuple[str, ...] = ()

exclude class-attribute

exclude: tuple[str, ...] = ()

readonly class-attribute

readonly: tuple[str, ...] = ()

assign class-attribute

assign: Mapping[str, Callable[[Any], Any]] = {}

badges class-attribute

badges: Mapping[
    str, Mapping[Any, Badge | tuple[Any, ...]]
] = {}

tabs class-attribute

tabs: tuple[Tab | str, ...] = ()

fieldsets class-attribute

fieldsets: (
    tuple[Fieldset, ...] | Mapping[str, tuple[str, ...]]
) = ()

modified_field class-attribute

modified_field: str = ''

modified_label class-attribute

modified_label: str = 'Last modified'

per_page class-attribute

per_page: int | None = None

show_count class-attribute

show_count: bool | None = None

bulk_delete class-attribute

bulk_delete: bool = True

bulk_actions class-attribute

bulk_actions: tuple[BulkAction[Any], ...] = ()

extra_fields class-attribute

extra_fields: tuple[Extra, ...] = ()

site class-attribute instance-attribute

site: Any = None

tab_list instance-attribute

tab_list: tuple[Tab, ...] = ()

fieldset_list instance-attribute

fieldset_list: tuple[Fieldset, ...] = ()

extras

extras() -> tuple[Extra, ...]

The form fields that are not columns (extra_fields by default).

extra_initial async

extra_initial(row: M) -> dict[str, Any]

What the extra fields show for row on the edit form.

queryset

queryset(principal: Caller[Any]) -> QuerySet[M]

can

can(
    principal: Caller[Any],
    action: str,
    row: M | None = None,
) -> bool

title_of

title_of(row: M) -> str

A row's name: the first listed column that holds text.

display

display(row: M, column: str) -> Any

The value shown in a list column (return a Badge or Avatar for richer cells).

stats async

stats(principal: Caller[Any]) -> list[Stat]

check async

check(
    values: dict[str, Any],
    principal: Caller[Any],
    row: M | None,
) -> dict[str, str]

Cross-field validation hook: return {field: message} to refuse.

save async

save(
    values: dict[str, Any],
    principal: Caller[Any],
    row: M | None = None,
) -> M

remove async

remove(row: M, principal: Caller[Any]) -> None

ensure_visible async

ensure_visible(row: M, principal: Caller[Any]) -> None

plural

plural() -> str

shown_columns

shown_columns() -> tuple[str, ...]

The list columns: columns, else the first six that are not excluded (an excluded column is never displayed or sortable).

default_search() -> tuple[str, ...]

The first three shown text columns: what a search box is expected to look in, without ever reaching a column the list does not show.

skipped

skipped() -> frozenset[str]

normalize

normalize(slug: str) -> None

Fill the defaults the model implies and expand the short forms of badges, tabs and fieldsets.

validate_config

validate_config(slug: str) -> None

hinoki.admin.BulkAction dataclass

BulkAction(
    name: str,
    label: str,
    confirm: str,
    handler: Callable[
        [tuple[M, ...], Caller[Any]], Awaitable[None]
    ],
)

A confirmed action for selected rows in a model's admin list.

hinoki.admin.Theme dataclass

Theme(
    name: str,
    label: str,
    edit: str,
    light: Mapping[str, str],
    dark: Mapping[str, str],
    fixed: Mapping[str, str],
    default_mode: str = "light",
    extra_css: str = "",
    layout: str = "sidebar",
    list_style: str = "table",
)

check

check() -> None

Fail at configuration time, not on a half-styled page.

tokens_css

tokens_css() -> str

The token blocks for both schemes, honouring the system preference, an explicit data-mode and the theme's default mode.

hinoki.admin.Avatar dataclass

Avatar(name: str)

A person: initials in a circle plus the name.

hinoki.admin.Badge dataclass

Badge(
    label: str,
    tone: Tone | str = Tone.NEUTRAL,
    icon: str = "circle-check",
)

A status pill. icon is a Lucide icon name; tone one of TONES.

hinoki.admin.Tab dataclass

Tab(label: str, filters: Mapping[str, Any] = dict())

A saved filter shown as a tab: Tab("Drafts", {"published": False}).

hinoki.admin.Fieldset dataclass

Fieldset(
    title: str,
    fields: tuple[str, ...],
    collapsed: bool = False,
)

A titled group of form fields; collapsed renders it closed.

hinoki.admin.Extra dataclass

Extra(
    name: str,
    label: str,
    kind: str,
    note: str = "",
    choices: tuple[tuple[str, str], ...] = (),
)

A form field that is not a column of the model.

kind is "password" (a masked input that is never filled in again) or "choices" (a set of checkboxes: choices are (value, label) pairs and the submitted value is a frozenset of the checked ones). The values reach ModelAdmin.check and save next to the model's own columns.

hinoki.admin.Refusal

Bases: Exception

A write the admin refuses with a message meant for the person: raised from save or remove, it is shown on the form and rolls the write back.

hinoki.admin.Event dataclass

Event(
    text: str,
    when: str,
    icon: str = "pencil",
    tone: Tone | str = Tone.ACCENT,
)

One line of the recent-activity panel.

Link(label: str, href: str, icon: str = 'settings')

An extra sidebar link (settings, activity log, ...) supplied by the app.

hinoki.admin.Stat dataclass

Stat(
    label: str,
    value: int | str,
    icon: str = "file-text",
    tone: Tone | str = Tone.ACCENT,
    series: tuple[float, ...] = (),
)

A dashboard card. series (optional numbers, oldest first) draws a sparkline; without data there is no chart.

hinoki.admin.THEMES module-attribute

THEMES: dict[str, Theme] = {
    t.name: t for t in (STUDIO, CONSOLE, PAPER, BENTO)
}