Переход с Flask-Admin

starlette-admin начинался как перенос концепций Flask-Admin в экосистему ASGI, поэтому миграция происходит напрямую. Вы по-прежнему создаёте подкласс ModelView, настраиваете его через атрибуты класса и регистрируете его в экземпляре Admin. Основная работа сводится к переименованию атрибутов и переходу от неявного контекста запроса Flask к явному объекту request в Starlette.

Это руководство сопоставляет API Flask-Admin, атрибут за атрибутом, с его эквивалентом в starlette-admin.

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

Настройка

from flask import Flask
from flask_admin import Admin
from flask_admin.contrib.sqla import ModelView

app = Flask(__name__)
admin = Admin(app, name="My Admin", template_mode="bootstrap4")
admin.add_view(ModelView(Post, db.session))

from starlette.applications import Starlette
from starlette_admin.contrib.sqla import Admin, ModelView

app = Starlette()  # or FastAPI()
admin = Admin(engine, title="My Admin", secret_key="change-me")
admin.add_view(ModelView(Post))
admin.mount_to(app)

Переключателя template_mode здесь нет. Интерфейс использует Tabler (Bootstrap 5) и включает тёмную тему. Чтобы изменить внешний вид, напишите собственный BaseTheme или переопределите шаблоны.

Атрибуты страницы списка

Атрибуты форм

Экспорт и импорт

class PostView(ModelView):
    can_export = True
    export_types = ["csv", "xlsx"]
    export_max_rows = 10000

class PostView(ModelView):
    exporters = ["csv", "xlsx", "pdf"]
    importers = ["csv", "xlsx"]
    exclude_fields_from_export = ["internal_notes"]

Экспорт в CSV и JSON включён по умолчанию. Ограничения на количество строк применяются автоматически, а экранирование формул в электронных таблицах — это опциональная настройка exporter'а. Импорт, который Flask-Admin не предоставляет, включает этап предварительного просмотра с валидацией каждой строки и опциональным обновлением существующих записей по первичному ключу. См. раздел Экспорт и импорт.

Действия (Actions)

from flask_admin.actions import action


class PostView(ModelView):
    @action("publish", "Publish", "Publish selected posts?")
    def action_publish(self, ids):
        query = Post.query.filter(Post.id.in_(ids))
        for post in query.all():
            post.published = True

from starlette_admin import ActionSelection, action, flash


class PostView(ModelView):
    actions = ["publish", "delete"]

    @action(
        name="publish",
        text="Publish",
        confirmation="Publish selected posts?",
    )
    async def publish(self, request: Request, selection: ActionSelection) -> None:
        for post in await selection.rows():
            post.published = True
        flash(request, "Posts published")

Обработчик получает объект ActionSelection вместо «сырых» идентификаторов. Он лениво извлекает строки, предоставляет доступ к активным фильтрам и работает одинаково, когда пользователь выбирает все подходящие записи на всех страницах. Действия также могут отображать произвольную HTML-форму внутри диалога подтверждения. Для операций над отдельными строками @row_action и @link_row_action заменяют пользовательские column formatters.

Права доступа и контроль доступа

Флаги классов can_* во Flask-Admin превращаются в starlette-admin в методы, вызываемые для каждого запроса, благодаря чему решения об авторизации могут зависеть от текущего пользователя.

Во Flask-Admin вы интегрируете Flask-Login самостоятельно. starlette-admin поставляется с AuthProvider, включающим готовую страницу входа, а вам остаётся реализовать методы login, logout и authenticate поверх вашего хранилища пользователей. OAuthProvider покрывает сценарии перенаправления OIDC. Текущий пользователь доступен везде как request.state.admin_user.

Hook'и жизненного цикла модели

Помимо hook'ов отдельных view, система событий позволяет одному обработчику наблюдать за всеми view. Во Flask-Admin аналога нет.

from starlette_admin.events import AdminEvent, AfterCreateContext


async def audit(ctx: AfterCreateContext) -> None: ...


admin.events.on(AdminEvent.AFTER_CREATE, audit)

Пользовательские view и главная страница

Встроенные модели (Inline models)

class ArticleView(ModelView):
    inline_models = [Comment]

from starlette_admin.contrib.sqla import InlineModelView, ModelView


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


class ArticleView(ModelView):
    inlines = [CommentInline]

Явный класс даёт каждой встроенной модели полный набор возможностей конфигурации ModelView: выбор полей, валидацию и поддержку составных внешних ключей. См. раздел Встроенные формы.

Интернационализация

Flask-Admin зависит от Flask-Babel и окружения Flask. starlette-admin вместо этого использует объект конфигурации:

from starlette_admin import I18nConfig

admin = Admin(engine, i18n_config=I18nConfig(default_locale="fr"))

Отображение даты и времени с учётом часового пояса работает аналогичным образом — через TimezoneConfig. См. раздел Интернационализация и часовые пояса.

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

• Асинхронный стек. Нативно работает на FastAPI и Starlette с поддержкой async SQLAlchemy, Beanie и Tortoise ORM. Flask-Admin синхронен.
• Встроенные средства безопасности. Защита от CSRF, санитизация имён загружаемых файлов, проверка содержимого изображений и ограничения на количество строк при экспорте включаются сразу после создания экземпляра Admin; экранирование формул в электронных таблицах можно включить в exporter'ах. См. раздел Безопасность.
• Импорт данных. Этап предварительного просмотра валидирует каждую строку до того, как что-либо будет записано. Во Flask-Admin функции импорта нет.
• Система виджетов для дашбордов. Создавайте главные страницы и пользовательские view на Python вместо ручного написания шаблонов.
• Современный дизайн. Активно поддерживаемая кодовая база с аккуратным интерфейсом, встроенной тёмной темой и полноценными аннотациями типов.

Что придётся адаптировать

• Явные объекты запроса. Неявного контекста запроса нет. Каждый hook и метод проверки прав получает request в качестве параметра.
• Асинхронные обработчики. Hook'и и действия являются корутинами, поэтому избегайте блокирующих вызовов внутри них или выносите такую работу в отдельный поток.
• Нет FileAdmin. Если ваш рабочий процесс зависит от просмотра файловой системы сервера, starlette-admin этого не покрывает.
• Нет модальных окон создания и редактирования. Формы отображаются как полноценные страницы, а не всплывающие модальные окна.