Migrer depuis Flask-Admin

starlette-admin est né d'un portage des concepts de Flask-Admin vers l'écosystème ASGI ; la migration est donc directe. Vous continuez à hériter d'une ModelView, à la configurer avec des attributs de classe et à l'enregistrer sur une instance d'Admin. L'essentiel du travail consiste à renommer des attributs et à passer du contexte de requête implicite de Flask à l'objet request explicite de Starlette.

Ce guide met en correspondance l'API de Flask-Admin, attribut par attribut, avec son équivalent starlette-admin.

Modèle mental

Configuration

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)

Il n'existe pas d'interrupteur template_mode. L'interface utilise Tabler (Bootstrap 5) et inclut le mode sombre. Pour changer l'apparence, écrivez une BaseTheme personnalisée ou remplacez les templates.

Attributs de la page de liste

Attributs de formulaire

Export et import

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"]

L'export CSV et JSON est activé par défaut. Des limites de lignes s'appliquent automatiquement, et l'échappement des formules de tableur est une option d'exporter à activer explicitement. L'import, que Flask-Admin ne propose pas, inclut une étape d'aperçu avec validation ligne par ligne et mises à jour optionnelles des enregistrements existants par clé primaire. Voir Export et import.

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

Le gestionnaire reçoit un objet ActionSelection au lieu d'identifiants bruts. Il résout les lignes paresseusement, expose les filtres actifs et se comporte de la même manière lorsqu'un utilisateur sélectionne tous les enregistrements correspondants sur l'ensemble des pages. Les actions peuvent également afficher un formulaire HTML personnalisé dans la boîte de dialogue de confirmation. Pour les opérations par ligne, @row_action et @link_row_action remplacent les formatters de colonne personnalisés.

Permissions et contrôle d'accès

Les indicateurs de classe can_* de Flask-Admin deviennent des méthodes par requête dans starlette-admin, si bien que les décisions d'autorisation peuvent dépendre de l'utilisateur connecté.

Avec Flask-Admin, vous intégrez Flask-Login vous-même. starlette-admin fournit un AuthProvider accompagné d'une page de connexion prête à l'emploi, et vous implémentez les méthodes login, logout et authenticate auprès de votre magasin d'utilisateurs. Un OAuthProvider couvre les flux de redirection OIDC. L'utilisateur connecté est disponible partout via request.state.admin_user.

Hooks du cycle de vie du modèle

Au-delà des hooks par vue, le système d'événements permet à un seul gestionnaire d'observer toutes les vues. Flask-Admin n'a pas d'équivalent.

from starlette_admin.events import AdminEvent, AfterCreateContext


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


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

Vues personnalisées et page d'index

Modèles inline

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]

Une classe explicite offre à chaque modèle inline toute la surface de configuration d'une ModelView : sélection des champs, validation et prise en charge des clés étrangères composites. Voir Formulaires inline.

Internationalisation

Flask-Admin dépend de Flask-Babel et de l'environnement Flask qui l'entoure. starlette-admin utilise plutôt un objet de configuration :

from starlette_admin import I18nConfig

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

Le rendu des dates et heures tenant compte des fuseaux horaires fonctionne de la même manière, via TimezoneConfig. Voir Internationalisation et fuseaux horaires.

Ce que vous gagnez en migrant

• Une pile asynchrone. Fonctionne nativement sous FastAPI et Starlette, avec prise en charge de SQLAlchemy asynchrone, Beanie et Tortoise ORM. Flask-Admin est synchrone.
• Des fonctionnalités de sécurité intégrées. La protection CSRF, l'assainissement des noms de fichiers téléversés, la vérification du contenu des images et les limites de lignes d'export sont actives dès l'instanciation de Admin, et vous pouvez activer l'échappement des formules de tableur sur les exporters. Voir Sécurité.
• L'import de données. Une étape d'aperçu valide chaque ligne avant toute écriture. Flask-Admin ne propose aucune fonctionnalité d'import.
• Un système de widgets pour tableau de bord. Construisez les pages d'index et les vues personnalisées en Python plutôt qu'en écrivant des templates à la main.
• Un design moderne. Une base de code activement maintenue, dotée d'une interface soignée, d'un mode sombre intégré et d'annotations de types de premier ordre.

Ce à quoi vous devez vous adapter

• Des objets request explicites. Il n'existe pas de contexte de requête ambiant. Chaque hook et chaque méthode de permission reçoit la request en paramètre.
• Des gestionnaires asynchrones. Les hooks et les actions sont des coroutines ; évitez donc les appels bloquants ou déplacez ces traitements vers un thread.
• Pas de FileAdmin. Si votre flux de travail dépend de la navigation dans le système de fichiers du serveur, starlette-admin ne le couvre pas.
• Pas de fenêtres modales de création ni d'édition. Les formulaires s'affichent comme des pages complètes plutôt que comme des fenêtres contextuelles.