Переход с Django Admin

Если вы знакомы с Django Admin, starlette-admin покажется вам привычным инструментом. Оба решения генерируют административный интерфейс на основе декларативной конфигурации для каждой модели, а также поддерживают инлайн-редактирование, пакетные действия и разрешения на уровне каждого запроса.

Различия носят структурный характер. starlette-admin работает поверх любого ASGI-приложения вместо обязательного использования Django, поддерживает несколько ORM и позволяет подключить собственную аутентификацию, не навязывая встроенную модель пользователя.

В этом руководстве каждая основная концепция ModelAdmin сопоставлена со своим эквивалентом в starlette-admin, с примерами кода рядом.

Концептуальная модель

Регистрация модели

from django.contrib import admin
from .models import Post


@admin.register(Post)
class PostAdmin(admin.ModelAdmin):
    list_display = ["title", "published", "created_at"]
    search_fields = ["title", "content"]

from starlette_admin.contrib.sqla import Admin, ModelView


class PostView(ModelView):
    fields = ["id", "title", "content", "published", "created_at"]
    exclude_fields_from_list = ["content"]
    searchable_fields = ["title", "content"]


admin = Admin(engine, title="Blog Admin", secret_key="change-me")
admin.add_view(PostView(Post, icon="fa fa-newspaper"))
admin.mount_to(app)  # app is your FastAPI or Starlette instance

Обратите внимание на два структурных отличия:

1. Один список полей управляет всеми страницами. Атрибут fields — единственный источник истины. Для вариаций по страницам используются exclude_fields_from_list, exclude_fields_from_detail, exclude_fields_from_create и exclude_fields_from_edit.
2. Экземпляр Admin владеет движком базы данных. Вам не нужно передавать сессию каждому представлению.

Настройки страницы списка

Формы

Пример fieldsets

class PostAdmin(admin.ModelAdmin):
    fieldsets = [
        ("Content", {"fields": ["title", "body"]}),
        ("Publication", {"fields": ["published", "created_at"]}),
    ]

from starlette_admin import FieldsetWidget


class PostView(ModelView):
    fields = ["id", "title", "body", "published", "created_at"]
    form_layout = [
        FieldsetWidget(legend="Content", children=["title", "body"]),
        FieldsetWidget(legend="Publication", children=["published", "created_at"]),
    ]

Возможности form_layout шире, чем у fieldsets: можно создавать вкладки, адаптивные сетки и вложенные макеты. См. Form Layout.

Инлайны

class CommentInline(admin.TabularInline):
    model = Comment
    extra = 1


class ArticleAdmin(admin.ModelAdmin):
    inlines = [CommentInline]

from starlette_admin.contrib.sqla import InlineModelView, ModelView


class CommentInline(InlineModelView):
    model = Comment
    fields = ["author", "body"]


class ArticleView(ModelView):
    inlines = [CommentInline]

starlette-admin определяет внешний ключ автоматически, если он однозначен, и поддерживает составные внешние ключи. Расширенные конфигурации описаны в разделе Inline Forms.

Действия

@admin.action(description="Mark selected articles as published")
def make_published(modeladmin, request, queryset):
    queryset.update(published=True)


class ArticleAdmin(admin.ModelAdmin):
    actions = [make_published]

from starlette_admin import ActionSelection, action, flash


class ArticleView(ModelView):
    actions = ["make_published", "delete"]

    @action(
        name="make_published",
        text="Mark selected articles as published",
        confirmation="Publish the selected articles?",
    )
    async def make_published(
        self, request: Request, selection: ActionSelection
    ) -> None:
        for article in await selection.rows():
            article.published = True
        flash(request, "Articles published")

Там, где Django Admin передаёт QuerySet, обработчик starlette-admin получает объект ActionSelection. Он лениво разрешает строки, первичные ключи и активные фильтры и ведёт себя одинаково, когда пользователь выбирает все совпадающие записи.

Действия также могут отрисовывать собственную HTML-форму внутри диалога подтверждения — в Django Admin для этого пришлось бы создавать промежуточную страницу. Для операций над отдельными строками используйте @row_action и @link_row_action; аналогов в Django Admin у них нет.

Разрешения и аутентификация

Django Admin делегирует эти задачи модулю django.contrib.auth. starlette-admin разделяет проблему на две части: AuthProvider отвечает на вопрос «кто этот пользователь», а методы представлений — на вопрос «что он может делать».

Следующее представление разрешает удаление только пользователям с ролью admin:

class ArticleView(ModelView):
    def can_delete(self, request: Request) -> bool:
        return "admin" in request.state.admin_user.roles

Каждый метод can_* получает запрос, поэтому ваши решения об авторизации могут опираться на текущего пользователя, HTTP-заголовки или любые другие данные запроса.

Hook'и сохранения и сигналы

Конфигурация уровня всего сайта

Что вы получаете при переходе

• Сквозная асинхронность: Обработчики, lifecycle hook'и и callback'и widget'ов могут быть корутинами, выполняющимися в вашем существующем event loop рядом с endpoint'ами FastAPI.
• Гибкость в выборе БД: Одна и та же конфигурация админ-панели работает независимо от того, используете ли вы SQLAlchemy, SQLModel, MongoDB через MongoEngine или Beanie либо Tortoise ORM.
• Встроенный экспорт и импорт: CSV, JSON и PDF, плюс Excel и другие форматы через tablib. Экспортируйте записи напрямую или импортируйте данные пакетно с помощью wizard'а, который сначала показывает предпросмотр, обеспечивает валидацию на уровне строк и поддерживает опциональный upsert по первичному ключу. См. Export and Import.
• Widget'ы для дашборда: Карточки статистики, ApexCharts и сетки макетов компонуются в index-страницы и custom view, поэтому для создания дашборда не нужен внешний пакет с темой. См. Custom Views and Widgets.
• Современный пользовательский интерфейс: Tabler (Bootstrap 5) даёт тёмную тему, переключатели видимости столбцов и подсветку результатов поиска по умолчанию.

Что нужно реализовать самостоятельно

• Аутентификация: Встроенной модели пользователя или базы разрешений нет. Реализуйте AuthProvider.authenticate(), опираясь на хранилище данных, которое уже используется вашим приложением.
• Журналирование аудита: starlette-admin не генерирует таблицу LogEntry. Подключите систему событий к собственной таблице аудита.
• Конфигурация UI на уровне модели: Удобства Django вроде модельных choices, verbose_name и валидаторов автоматически не переносятся. Задайте их на уровне поля starlette-admin с помощью EnumField, label= и validators=.