Démarrage rapide

Créez une interface d'administration CRUD entièrement fonctionnelle pour un blog en quelques minutes, avec des formulaires, des listes, une recherche, un import et un export générés automatiquement directement à partir de vos modèles de données.

Installation

Installez les paquets nécessaires à l'aide de votre gestionnaire de paquets préféré :

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

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

L'exemple complet

Créez un fichier nommé main.py et ajoutez-y le code suivant :

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)

Exécution de l'application

Démarrez le serveur de développement :

fastapi dev

uv run -- fastapi dev

Ouvrez un navigateur et rendez-vous sur http://127.0.0.1:8000/admin.

Dans la barre latérale, sélectionnez Posts, puis sélectionnez Create. Vous avez désormais accès aux pages de liste paginée, de détail, de création, de modification et de suppression. Le système génère automatiquement toutes ces interfaces à partir de la définition de votre modèle.

Fonctionnement

Les sections suivantes expliquent les composants essentiels de l'application.

Le modèle

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)
    )

Ce code utilise SQLAlchemy 2.0 standard. Le paquet starlette-admin lit les métadonnées de colonnes associées à ces attributs pour déterminer le champ HTML exact à générer. Par exemple, il crée un champ texte pour str, une case à cocher pour bool et un sélecteur de date et heure pour datetime.

La vue

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

PostView constitue l'objet central pour cette ressource. L'attribut fields détermine quelles colonnes apparaissent dans la liste et dans le formulaire, tandis que searchable_fields active la barre de recherche. Toutes les configurations relatives à l'apparence et au comportement de Post dans le tableau de bord d'administration résident dans cette unique classe.

L'administration

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

La classe Admin relie le moteur de base de données à l'interface utilisateur.

• add_view enregistre votre vue dans la barre latérale. Le paramètre facultatif icon accepte n'importe quelle classe Font Awesome valide.
• mount_to attache l'application d'administration à votre application FastAPI ou Starlette sous le chemin /admin.

Ajouter un second modèle

Vous pouvez enregistrer un nombre illimité de modèles. Par exemple, pour ajouter un modèle Tag ainsi que sa vue correspondante, définissez les classes puis appelez à nouveau 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"))

Actualisez la fenêtre du navigateur pour voir Posts et Tags apparaître dans la barre latérale. Chaque ressource dispose désormais de ses propres pages de liste, de création, de modification et de suppression entièrement fonctionnelles.

Prochaines étapes

• Concepts : Apprenez la terminologie des concepts présentés ici afin de mieux vous repérer dans le guide de l'utilisateur.
• Admin : Découvrez toutes les options de Admin(...), notamment le branding, les thèmes, l'authentification, la sécurité et l'internationalisation.
• Views : Explorez l'intégralité des options de configuration de ModelView disponibles pour personnaliser la présentation de vos données.