Быстрый старт

Создайте полнофункциональный CRUD-интерфейс администрирования для блога за считанные минуты — с автоматически генерируемыми формами, списками, поиском, импортом и экспортом на основе ваших моделей данных.

Установка

Установите необходимые пакеты с помощью предпочитаемого менеджера пакетов:

pip install starlette-admin sqlalchemy "fastapi[standard]"

uv add starlette-admin sqlalchemy "fastapi[standard]"

Полный пример

Создайте файл с именем main.py и добавьте в него следующий код:

from contextlib import asynccontextmanager
from datetime import datetime, timezone

from fastapi import FastAPI
from sqlalchemy import create_engine
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
from starlette_admin.contrib.sqla import Admin, ModelView

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


class Base(DeclarativeBase):
    pass


class Post(Base):
    __tablename__ = "posts"

    id: Mapped[int] = mapped_column(primary_key=True)
    title: Mapped[str]
    content: Mapped[str]
    published: Mapped[bool] = mapped_column(default=False)
    created_at: Mapped[datetime] = mapped_column(
        default=lambda: datetime.now(timezone.utc)
    )


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


@asynccontextmanager
async def lifespan(app: FastAPI):
    Base.metadata.create_all(engine)
    yield


# Note: This can also be replaced by Starlette(lifespan=lifespan)
app = FastAPI(lifespan=lifespan)

admin = Admin(engine, title="Blog Admin", secret_key="change-me")
admin.add_view(PostView(Post, icon="fa fa-newspaper"))
admin.mount_to(app)

Запуск приложения

Запустите сервер разработки:

fastapi dev

uv run -- fastapi dev

Откройте браузер и перейдите по адресу http://127.0.0.1:8000/admin.

В боковой панели выберите Posts, а затем Create. Теперь вам доступны страницы со списком с разбивкой на страницы, детальным просмотром, созданием, редактированием и удалением записей. Все эти интерфейсы система генерирует автоматически на основе определения вашей модели.

Как это работает

В следующих разделах описываются основные компоненты приложения.

Модель

class Post(Base):
    __tablename__ = "posts"

    id: Mapped[int] = mapped_column(primary_key=True)
    title: Mapped[str]
    content: Mapped[str]
    published: Mapped[bool] = mapped_column(default=False)
    created_at: Mapped[datetime] = mapped_column(
        default=lambda: datetime.now(timezone.utc)
    )

Этот код использует стандартный SQLAlchemy 2.0. Пакет starlette-admin считывает метаданные столбцов, сопоставленные с этими атрибутами, чтобы определить, какой именно HTML-элемент ввода следует сгенерировать. Например, для str создаётся текстовое поле, для bool — флажок, а для datetime — виджет выбора даты и времени.

Представление

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

PostView является центральным объектом для данного ресурса. Атрибут fields определяет, какие столбцы отображаются в списке и форме, а searchable_fields включает строку поиска. Все настройки внешнего вида и поведения Post в панели администрирования сосредоточены в этом единственном классе.

Административная панель

admin = Admin(engine, title="Blog Admin", secret_key="change-me")
admin.add_view(PostView(Post, icon="fa fa-newspaper"))
admin.mount_to(app)

Класс Admin связывает движок базы данных с пользовательским интерфейсом.

• add_view регистрирует ваше представление в боковой панели. Необязательный параметр icon принимает любой корректный класс Font Awesome.
• mount_to подключает административное приложение к вашему приложению FastAPI или Starlette по пути /admin.

Добавление второй модели

Вы можете зарегистрировать неограниченное количество моделей. Например, чтобы добавить модель Tag и соответствующее ей представление, определите классы и снова вызовите add_view:

class Tag(Base):
    __tablename__ = "tags"

    id: Mapped[int] = mapped_column(primary_key=True)
    name: Mapped[str]


class TagView(ModelView):
    fields = ["id", "name"]
    searchable_fields = ("name",)


admin.add_view(PostView(Post, icon="fa fa-newspaper"))
admin.add_view(TagView(Tag, icon="fa fa-tag"))

Обновите окно браузера, чтобы увидеть в боковой панели как Posts, так и Tags. Теперь каждый ресурс располагает собственными полнофункциональными страницами списка, создания, редактирования и удаления.

Следующие шаги

• Концепции: Ознакомьтесь с терминологией концепций, представленных здесь, чтобы увереннее ориентироваться в Руководстве пользователя.
• Admin: Изучите все параметры Admin(...), включая брендинг, темы оформления, аутентификацию, безопасность и интернационализацию.
• Views: Рассмотрите все доступные параметры конфигурации ModelView для настройки представления ваших данных.