Venir de Django Admin

Si vous connaissez Django Admin, starlette-admin vous semblera familier. Les deux génèrent une interface d'administration à partir d'une configuration déclarative, modèle par modèle, et prennent tous deux en charge l'édition en ligne, les actions par lot et des permissions par requête.

Les différences sont structurelles : starlette-admin fonctionne sur n'importe quelle application ASGI au lieu d'exiger Django, prend en charge plusieurs ORM et vous permet de brancher votre propre authentification plutôt que d'imposer un modèle utilisateur intégré.

Ce guide fait correspondre chaque concept majeur de ModelAdmin à son équivalent starlette-admin, avec du code côte à côte.

Modèle mental

Enregistrer un modèle

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

Deux différences structurelles ressortent :

1. Une seule liste de champs pilote toutes les pages. fields constitue la source de vérité unique. Vous utilisez ensuite exclude_fields_from_list, exclude_fields_from_detail, exclude_fields_from_create et exclude_fields_from_edit pour des variations par page.
2. L'instance Admin détient le moteur de base de données. Vous ne passez pas une session à chaque vue.

Options de la page de liste

Formulaires

Exemple de 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 va plus loin que les fieldsets : vous pouvez créer des onglets, des grilles responsives et des mises en page imbriquées. Voir Form Layout.

Inlines

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 détecte la clé étrangère lorsqu'elle est non ambiguë et prend en charge les clés étrangères composites. Consultez Formulaires inline pour les configurations avancées.

Actions

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

Là où Django Admin passe un QuerySet, le handler starlette-admin reçoit un objet ActionSelection. Il résout paresseusement les lignes, les clés primaires et les filtres actifs, et se comporte de la même manière lorsqu'un utilisateur sélectionne tous les enregistrements correspondants.

Les actions peuvent également afficher un formulaire HTML personnalisé dans la boîte de dialogue de confirmation, ce qui, dans Django Admin, implique la construction d'une page intermédiaire. Pour les opérations par ligne, utilisez @row_action et @link_row_action, qui n'ont pas d'équivalent dans Django Admin.

Permissions et authentification

Django Admin délègue à django.contrib.auth. starlette-admin scinde le problème en deux : un AuthProvider répond « qui est cet utilisateur », et les méthodes par vue répondent « que peut-il faire ».

La vue suivante restreint la suppression aux utilisateurs ayant le rôle admin :

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

Chaque méthode can_* reçoit la requête : vos décisions d'autorisation peuvent donc lire l'utilisateur courant, les en-têtes HTTP ou tout autre élément de la requête.

Hooks d'enregistrement et signaux

Configuration globale du site

Ce que vous gagnez en migrant

• Asynchronisme de bout en bout : les handlers, les lifecycle hooks et les callbacks de widgets peuvent tous être des coroutines exécutées sur votre boucle d'événements existante, aux côtés de vos endpoints FastAPI.
• Flexibilité de la base de données : la même configuration d'administration s'applique que vous utilisiez SQLAlchemy, SQLModel, MongoDB via MongoEngine ou Beanie, ou Tortoise ORM.
• Export et import intégrés : CSV, JSON et PDF, plus Excel et d'autres formats via tablib. Exportez directement les enregistrements, ou importez des données en masse via un assistant axé sur la prévisualisation qui applique une validation au niveau de chaque ligne et prend en charge les upserts optionnels de clés primaires. Voir Export et Import.
• Widgets de tableau de bord : cartes statistiques, ApexCharts et grilles de mise en page se combinent pour former des index pages et des custom views, si bien que vous n'avez besoin d'aucun package de thème externe pour construire un dashboard. Voir Custom Views et Widgets.
• Interface utilisateur moderne : Tabler (Bootstrap 5) vous offre le mode sombre, les bascules de visibilité des colonnes et la surlignage des résultats de recherche par défaut.

Ce que vous devez apporter vous-même

• Authentification : il n'existe ni modèle utilisateur ni base de permissions intégrés. Implémentez AuthProvider.authenticate() sur le magasin de données qu'utilise déjà votre application.
• Journalisation d'audit : starlette-admin ne génère pas de table LogEntry. Branchez le système d'événements sur votre propre table d'audit.
• Configuration UI au niveau du modèle : les commodités de Django telles que les choices, verbose_name et validateurs au niveau du modèle ne se transfèrent pas. Déclarez-les plutôt sur le champ starlette-admin, avec EnumField, label= et validators=.